GnuplotEx.Channel.RateLimiter (gnuplot_ex v0.5.1)

Token bucket rate limiter for plot streaming.

Provides backpressure for high-frequency plot updates to prevent overwhelming clients or consuming excessive resources.

Algorithm

Uses a token bucket algorithm:

  • Each plot_id has its own bucket
  • Tokens regenerate at rate per second
  • Bucket can hold up to burst tokens
  • Each update consumes one token

Configuration

config :gnuplot_ex,
  channel_rate: 10,    # updates per second
  channel_burst: 20    # max burst size

Example

# Check if allowed (returns remaining tokens or error)
case RateLimiter.check("sensor-1") do
  {:ok, remaining} -> push_update(...)
  {:error, :rate_limited, retry_after_ms} -> send_rate_limit_error(...)
end

# Always allow (for admin/bypass)
RateLimiter.allow("admin-plot")

Summary

Functions

allow(plot_id, opts \\ [])

Force allow an update, bypassing rate limits.

check(plot_id, opts \\ [])

Check if a plot update is allowed under rate limits.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

reset(plot_id, opts \\ [])

Reset rate limit state for a plot.

start_link(opts \\ [])

Start the rate limiter process.

stats(opts \\ [])

Get rate limiter stats.

tokens(plot_id, opts \\ [])

Get current token count for a plot.

Functions

allow(plot_id, opts \\ [])

@spec allow(
  String.t(),
  keyword()
) :: :ok

Force allow an update, bypassing rate limits.

Useful for admin actions or priority updates.

check(plot_id, opts \\ [])

@spec check(
  String.t(),
  keyword()
) :: {:ok, non_neg_integer()} | {:error, :rate_limited, pos_integer()}

Check if a plot update is allowed under rate limits.

Returns:

  • {:ok, remaining_tokens} - Update allowed
  • {:error, :rate_limited, retry_after_ms} - Rate limited, wait before retry

Example

case RateLimiter.check("my-plot") do
  {:ok, _} -> proceed_with_update()
  {:error, :rate_limited, ms} -> schedule_retry(ms)
end

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

reset(plot_id, opts \\ [])

@spec reset(
  String.t(),
  keyword()
) :: :ok

Reset rate limit state for a plot.

Restores tokens to full burst capacity.

start_link(opts \\ [])

Start the rate limiter process.

stats(opts \\ [])

@spec stats(keyword()) :: map()

Get rate limiter stats.

tokens(plot_id, opts \\ [])

@spec tokens(
  String.t(),
  keyword()
) :: non_neg_integer() | nil

Get current token count for a plot.

Returns nil if plot has no rate limit state.