@spec ask(name :: term()) :: {:ok, token()} | :dropped

Ask for access to a protected service. Instead of executing a callback this function returns a dropped atom or a context. It is the callers responsibility to check the context map back in to the regulator using one of the corresponding functions. Care must be taken to avoid leaking these contexts. Otherwise the regulator will not be able to adjust the inflight count which will eventually deadlock the regulator.

@spec ask(term(), (() -> result())) :: term()

Ask for access to a protected service. If we've reached the concurrency limit then ask will return a :dropped atom without executing the callback. Otherwise the callback will be applied. The callback must return tuple with the result as the first element and the desired return value as the second. The available result atoms are:

• :ok - The call succeeded.
• :error - The call failed or timed out. This is used as a signal to backoff or otherwise adjust the limit.
• :ignore - The call should not be counted in the concurrency limit. This is typically used to filter out status checks and other low latency RPCs.

@spec error(token()) :: :ok

Checks in a context and marks it as an error.

@spec ignore(token()) :: :ok

Checks in a context and ignores the result.

@spec install(
  name :: term(),
  {module(), Keyword.t()}
) :: DynamicSupervisor.on_start_child()

Creates a new regulator.

@spec ok(token()) :: :ok

Checks in a context and marks it as "ok".

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

Removes a regulator.