Returns a specification to start this module under a supervisor.

See Supervisor.

@spec estimate(GenServer.server(), estimate_opts()) :: number()

Returns the server's current headline estimate.

With no :window configured, this is ExDataSketch.estimate/1 on the underlying sketch. With :window configured, it defaults to the windowed reading (ExDataSketch.Window.estimate/1); pass window: :all to read the un-windowed, all-time accumulator instead, which requires the server to have been started with window: [..., track_all_time: true].

Raises ExDataSketch.Errors.UnsupportedOperationError for window: :all when track_all_time: true was not set, or for any estimate/1,2 call against a family with no single-value reading (see ExDataSketch.estimate/1).

Examples

iex> {:ok, pid} = ExDataSketch.Server.start_link(sketch: :hll, sketch_opts: [p: 10])
iex> :ok = ExDataSketch.Server.update_sync(pid, "user_1")
iex> ExDataSketch.Server.estimate(pid) > 0.0
true

iex> {:ok, pid} = ExDataSketch.Server.start_link(
...>   sketch: :hll, sketch_opts: [p: 10],
...>   window: [every: 60_000, keep: 5, track_all_time: true]
...> )
iex> :ok = ExDataSketch.Server.update_sync(pid, "user_1")
iex> ExDataSketch.Server.estimate(pid) > 0.0 and ExDataSketch.Server.estimate(pid, window: :all) > 0.0
true

@spec flush(GenServer.server()) :: struct()

Returns the server's current state and resets it to a fresh, empty one, on demand (independent of any configured :flush interval).

Unlike the automatic timer-driven flush (see the module documentation's "Flushing" section), a manual call here does not invoke the :flush callback -- only the timer does. Both emit [:ex_data_sketch, :server, :flush].

Examples

iex> {:ok, pid} = ExDataSketch.Server.start_link(sketch: :hll, sketch_opts: [p: 10])
iex> :ok = ExDataSketch.Server.update_sync(pid, "user_1")
iex> flushed = ExDataSketch.Server.flush(pid)
iex> ExDataSketch.HLL.estimate(flushed) > 0.0
true
iex> ExDataSketch.Server.estimate(pid)
0.0

@spec merge(
  GenServer.server(),
  struct()
) :: :ok

Merges an already-built partial sketch into the server's current state.

Raises ExDataSketch.Errors.UnsupportedOperationError if the server is windowed -- see the module documentation's "Windowing" section.

Examples

iex> {:ok, pid} = ExDataSketch.Server.start_link(sketch: :hll, sketch_opts: [p: 10])
iex> partial = ExDataSketch.HLL.new(p: 10) |> ExDataSketch.HLL.update("a")
iex> :ok = ExDataSketch.Server.merge(pid, partial)
iex> ExDataSketch.Server.estimate(pid) > 0.0
true

@spec reset(GenServer.server()) :: :ok

Resets the server to a fresh, empty state (the window and, if configured, the all-time accumulator, when windowed).

Examples

iex> {:ok, pid} = ExDataSketch.Server.start_link(sketch: :hll, sketch_opts: [p: 10])
iex> :ok = ExDataSketch.Server.update_sync(pid, "user_1")
iex> :ok = ExDataSketch.Server.reset(pid)
iex> ExDataSketch.Server.estimate(pid)
0.0

@spec sketch(GenServer.server()) :: struct()

Returns the server's current raw state: a %ExDataSketch.Window{} if :window was configured, otherwise the bare sketch struct.

Examples

iex> {:ok, pid} = ExDataSketch.Server.start_link(sketch: :hll, sketch_opts: [p: 10])
iex> match?(%ExDataSketch.HLL{}, ExDataSketch.Server.sketch(pid))
true

@spec start_link(start_opts()) :: GenServer.on_start()

Starts a server process.

Options

• :sketch -- required. A registry atom (:hll, looked up via ExDataSketch.sketches/0) or a sketch module directly. Must resolve to a mergeable family (see ExDataSketch.Window.new/3) when :window is also given.
• :sketch_opts -- options forwarded to the sketch module's new/1 (default: []).
• :name -- optional, forwarded to GenServer.start_link/3's :name (an atom, {:global, term}, or {:via, module, term}).
• :window -- optional. See the module documentation's "Windowing" section.
• :snapshot -- optional. See the module documentation's "Snapshotting" section.
• :flush -- optional. See the module documentation's "Flushing" section.
• :max_queue -- optional non-negative integer or :infinity (default: :infinity). See the module documentation's "Backpressure" section.

Examples

iex> {:ok, pid} = ExDataSketch.Server.start_link(sketch: :hll, sketch_opts: [p: 10])
iex> is_pid(pid)
true

@spec update(GenServer.server(), term()) :: :ok

Updates the server with a single item.

Asynchronous (GenServer.cast/2) -- returns immediately, does not wait for the update to be applied, and can be dropped under :max_queue pressure. See the module documentation's "Backpressure" section, and update_sync/2 for a guaranteed alternative.

Examples

iex> {:ok, pid} = ExDataSketch.Server.start_link(sketch: :hll, sketch_opts: [p: 10])
iex> ExDataSketch.Server.update(pid, "user_1")
:ok

@spec update_many(GenServer.server(), Enumerable.t()) :: :ok

Updates the server with every item in an enumerable.

Asynchronous, like update/2 -- see the module documentation's "Backpressure" section.

Examples

iex> {:ok, pid} = ExDataSketch.Server.start_link(sketch: :hll, sketch_opts: [p: 10])
iex> ExDataSketch.Server.update_many(pid, ["a", "b", "c"])
:ok

@spec update_sync(GenServer.server(), term()) :: :ok

Updates the server with a single item, blocking until it has been applied.

Never dropped by :max_queue -- callers that need a guarantee the update was applied use this instead of update/2.

Examples

iex> {:ok, pid} = ExDataSketch.Server.start_link(sketch: :hll, sketch_opts: [p: 10])
iex> :ok = ExDataSketch.Server.update_sync(pid, "user_1")
iex> ExDataSketch.Server.estimate(pid) > 0.0
true