ExResilience.RateLimiter (ex_resilience v0.4.0)

Copy Markdown View Source

Token bucket rate limiter implemented as a GenServer.

Maintains a bucket of tokens that refill at a steady rate. Each call consumes one token. When the bucket is empty, calls are rejected with {:error, :rate_limited}.

Uses ETS for the hot-path token check and the GenServer for refill scheduling.

Options

  • :name -- required. Registered name for this rate limiter instance.
  • :rate -- tokens added per interval. Default 10.
  • :interval -- refill interval in ms. Default 1_000 (1 second).
  • :max_tokens -- bucket capacity. Default equals :rate.

Examples

iex> {:ok, _} = ExResilience.RateLimiter.start_link(name: :test_rl, rate: 5, interval: 1_000)
iex> ExResilience.RateLimiter.call(:test_rl, fn -> :ok end)
{:ok, :ok}

Summary

Types

option()
result()

Functions

available_tokens(name)

Returns the current number of available tokens.

call(name, fun)

Executes fun if a token is available.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

start_link(opts)

Starts a rate limiter process.

Types

option()

@type option() ::
  {:name, atom()}
  | {:rate, pos_integer()}
  | {:interval, pos_integer()}
  | {:max_tokens, pos_integer()}

result()

@type result() :: {:ok, term()} | {:error, :rate_limited} | {:error, term()}

Functions

available_tokens(name)

@spec available_tokens(atom()) :: non_neg_integer()

Returns the current number of available tokens.

call(name, fun)

@spec call(atom(), (-> term())) :: result()

Executes fun if a token is available.

Returns {:ok, result} on success or {:error, :rate_limited} if the bucket is empty.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

start_link(opts)

@spec start_link([option()]) :: GenServer.on_start()

Starts a rate limiter process.

See module docs for available options.