README.md

# TokenBucket

A Simple GenServer implementation of the [TokenBucket Algorithm](https://en.wikipedia.org/wiki/Token_bucket)
used primarily for rate limiting

## Installation

If [available in Hex](https://hex.pm/docs/publish), the package can be installed
by adding `tokenbucket` to your list of dependencies in `mix.exs`:

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

Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at [https://hexdocs.pm/tokenbucket](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:

```elixir
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 

```elixir
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

```elixir
TokenBucket.await(SuperBucket) // blocks
```