ExDataSketch.Sketches (ExDataSketch v0.10.0)

A supervisor for starting ExDataSketch.Server processes per tenant or key at runtime, addressed by an arbitrary term rather than a compile-time atom.

Add one instance to your application's supervision tree:

children = [
  {ExDataSketch.Sketches, name: MyApp.Sketches}
]

Then start and address servers by any term (a tenant ID, a user ID, and so on):

{:ok, _pid} = ExDataSketch.Sketches.start_child(MyApp.Sketches, tenant_id, sketch: :hll, sketch_opts: [p: 14])
ExDataSketch.Server.update(ExDataSketch.Sketches.via(MyApp.Sketches, tenant_id), user_id)

:name is optional and defaults to ExDataSketch.Sketches itself, for applications that only need one instance and do not want to name it explicitly.

Implementation

Each Sketches instance is a plain Supervisor with two children: a Registry (keys: :unique) and a DynamicSupervisor. start_child/3 starts an ExDataSketch.Server under the DynamicSupervisor, registered in the Registry under key via a {:via, Registry, {registry, key}} name -- the standard OTP pattern for addressing dynamically-started, independently-addressable processes by term. No bespoke lookup or routing code is needed: ExDataSketch.Server's own client functions (update/2, estimate/1, and so on) already accept any GenServer.server(), including a :via tuple, so via/2's result can be passed to them directly.

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

start_child(name \\ __MODULE__, key, server_opts)

Starts an ExDataSketch.Server under name's DynamicSupervisor, addressable afterwards as via(name, key).

start_link(opts \\ [])

Starts a Sketches supervisor.

stop_child(name \\ __MODULE__, key)

Stops the ExDataSketch.Server started under key.

via(name \\ __MODULE__, key)

Returns the :via tuple for addressing the ExDataSketch.Server started under key, suitable as the server argument to any ExDataSketch.Server client function.

whereis(name \\ __MODULE__, key)

Looks up the pid of the ExDataSketch.Server started under key, or nil if none is registered.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

start_child(name \\ MODULE, key, server_opts)

@spec start_child(term(), term(), ExDataSketch.Server.start_opts()) ::
  DynamicSupervisor.on_start_child()

Starts an ExDataSketch.Server under name's DynamicSupervisor, addressable afterwards as via(name, key).

server_opts are the same options ExDataSketch.Server.start_link/1 accepts, except :name is set automatically and any given value for it is ignored.

Examples

iex> {:ok, _sketches} = ExDataSketch.Sketches.start_link(name: :sketches_doctest_start_child)
iex> {:ok, pid} = ExDataSketch.Sketches.start_child(:sketches_doctest_start_child, :tenant_a, sketch: :hll, sketch_opts: [p: 10])
iex> is_pid(pid)
true

start_link(opts \\ [])

@spec start_link(keyword()) :: Supervisor.on_start()

Starts a Sketches supervisor.

Options

:name -- optional (default: ExDataSketch.Sketches). Every other function in this module takes this same name (or its default) as its first argument, to address the matching instance.

Examples

iex> {:ok, pid} = ExDataSketch.Sketches.start_link(name: :sketches_doctest)
iex> is_pid(pid)
true

stop_child(name \\ MODULE, key)

@spec stop_child(term(), term()) :: :ok | {:error, :not_found}

Stops the ExDataSketch.Server started under key.

Returns {:error, :not_found} if no server is registered under key.

Examples

iex> {:ok, _sketches} = ExDataSketch.Sketches.start_link(name: :sketches_doctest_stop_child)
iex> {:ok, _pid} = ExDataSketch.Sketches.start_child(:sketches_doctest_stop_child, :tenant_a, sketch: :hll, sketch_opts: [p: 10])
iex> ExDataSketch.Sketches.stop_child(:sketches_doctest_stop_child, :tenant_a)
:ok
iex> ExDataSketch.Sketches.stop_child(:sketches_doctest_stop_child, :no_such_tenant)
{:error, :not_found}

via(name \\ MODULE, key)

@spec via(term(), term()) :: {:via, Registry, {module(), term()}}

Returns the :via tuple for addressing the ExDataSketch.Server started under key, suitable as the server argument to any ExDataSketch.Server client function.

Examples

iex> ExDataSketch.Sketches.via(:my_sketches, :tenant_a)
{:via, Registry, {:"Elixir.ExDataSketch.Sketches.Registry.my_sketches", :tenant_a}}

whereis(name \\ MODULE, key)

@spec whereis(term(), term()) :: pid() | nil

Looks up the pid of the ExDataSketch.Server started under key, or nil if none is registered.

Examples

iex> {:ok, _sketches} = ExDataSketch.Sketches.start_link(name: :sketches_doctest_whereis)
iex> ExDataSketch.Sketches.whereis(:sketches_doctest_whereis, :no_such_tenant)
nil