opuntia (opuntia v1.1.2)

opuntia, traffic shapers for Erlang and Elixir

This module implements the token-bucket traffic-shaping algorithm.

The rate is given in t:tokens() per t:time_unit() and a bucket size. Resolution is in native unit times as described by erlang:monotonic_time/0.

The delay is always returned in milliseconds unit, as this is the unit receives and timers use in the BEAM.

Summary

Types

bucket_size/0

Maximum capacity of the bucket regardless of how much time passes.

config/0

delay/0

Number of milliseconds that is advise to wait after a shaping update.

rate/0

Number of tokens accepted per t:time_unit().

shape/0

See new/1 for more details.

shaper/0

Shaper type

time_unit/0

Supported shaping time units.

tokens/0

Unit element the shaper consumes, for example bytes or requests.

Functions

new(Shape)

Creates a new shaper according to the configuration.

peek(Shaper)

Peek currently available tokens.

update(Shaper, TokensNowUsed)

Update shaper and return possible waiting time.

Types

bucket_size/0

-type bucket_size() :: non_neg_integer().

Maximum capacity of the bucket regardless of how much time passes.

config/0

-type config() ::
          0 |
          #{bucket_size := bucket_size(),
            rate := rate(),
            time_unit := time_unit(),
            start_full := boolean()}.

delay/0

-type delay() :: non_neg_integer().

Number of milliseconds that is advise to wait after a shaping update.

rate/0

-type rate() :: non_neg_integer().

Number of tokens accepted per t:time_unit().

shape/0

-type shape() :: {bucket_size(), rate(), time_unit()}.

See new/1 for more details.

shaper/0

-type shaper() ::
          none |
          #token_bucket_shaper{shape :: opuntia:shape(),
                               available_tokens :: opuntia:tokens(),
                               last_update :: integer(),
                               debt :: float()}.

Shaper type

time_unit/0

-type time_unit() :: second | millisecond | microsecond | nanosecond | native.

Supported shaping time units.

tokens/0

-type tokens() :: non_neg_integer().

Unit element the shaper consumes, for example bytes or requests.

Functions

new(Shape)

-spec new(config()) -> shaper().

Creates a new shaper according to the configuration.

If zero is given, no shaper in created and any update action will always return zero delay; to configure a shaper it will need a config like

  #{bucket_size => MaximumTokens, rate => Rate, time_unit => TimeUnit, start_full => Boolean}

where

TimeUnit is the time unit of measurement as defined by t:time_unit()
Rate is the number of tokens per TimeUnit the bucket will grow with.
MaximumTokens is the maximum number of tokens the bucket can grow.
StartFull indicates if the shaper starts with the bucket full, or empty if not.

So, for example, if we configure a shaper with the following:

  #{bucket_size => 60000, rate => 10, time_unit => millisecond, start_full => true}

it means that the bucket will allow 10 tokens per millisecond, up to 60000 tokens, regardless of how long it is left unused to charge: it will never charge further than 60000 tokens.

peek(Shaper)

-spec peek(shaper()) -> non_neg_integer() | infinity.

Peek currently available tokens.

update(Shaper, TokensNowUsed)

-spec update(shaper(), tokens()) -> {shaper(), delay()}.

Update shaper and return possible waiting time.

This function takes the current shaper state, and the number of tokens that have been consumed, and returns a tuple containing the new shaper state, and a possibly non-zero number of unit times to wait if more tokens that the shaper allows were consumed.