blankenshipz / tokenbucket

A Simple Token Bucket implementation in Elixir

TokenBucket

A Simple GenServer implementation of the TokenBucket Algorithm used primarily for rate limiting

Installation

If available in Hex, the package can be installed by adding tokenbucket to your list of dependencies in mix.exs:

def deps do
  [
    {:tokenbucket, "~> 0.1.0"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/tokenbucket.

Usage

A TokenBucket process can be started with any of the ways that you start a GenServer perhaps most commonly as part of your application supervision tree:

children = [
  { TokenBucket, name: SuperBucket, capacity: 20, cadence: 1000},
]

opts = [strategy: :one_for_one, name: TokenBucket.Supervisor]
Supervisor.start_link(children, opts)

Once the process is started the "bucket" will begin to fill at the rate set by cadence; until the capacity is reached.

Tokens can be removed from the bucket with take or await

TokenBucket.take returns immediately

case TokenBucket.take(SuperBucket) do
  :ok ->
    IO.puts "We got a token!"
  :empty ->
    IO.puts "Better luck next time!"
end

While TokenBucket.await blocks for its turn to get a token

TokenBucket.await(SuperBucket) // blocks