View Source opuntia (opuntia v1.1.0)

opuntia, traffic shapers for Erlang and Elixir

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

The rate is given in tokens/0 per time_unit/0 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 time_unit/0.
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

Link to this type

bucket_size/0

View Source 
-type bucket_size() :: non_neg_integer().
Maximum capacity of the bucket regardless of how much time passes.
Link to this type

config/0

View Source 
-type config() ::
    0 |
    #{bucket_size := bucket_size(),
      rate := rate(),
      time_unit := time_unit(),
      start_full := boolean()}.
Link to this type

delay/0

View Source 
-type delay() :: non_neg_integer().
Number of milliseconds that is advise to wait after a shaping update.
Link to this type

rate/0

View Source 
-type rate() :: non_neg_integer().
Number of tokens accepted per time_unit/0.
Link to this type

shape/0

View Source 
-type shape() :: {bucket_size(), rate(), time_unit()}.
See new/1 for more details.
Link to this type

shaper/0

View Source 
-type shaper() :: none | #token_bucket_shaper{}.
Shaper type
Link to this type

time_unit/0

View Source 
-type time_unit() :: second | millisecond | microsecond | nanosecond | native.
Supported shaping time units.
Link to this type

tokens/0

View Source 
-type tokens() :: non_neg_integer().
Unit element the shaper consumes, for example bytes or requests.

Functions

Link to this function

new(Shape)

View Source 
-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 time_unit/0
  • 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.
Link to this function

peek(Shaper)

View Source 
-spec peek(shaper()) -> non_neg_integer() | infinity.
Peek currently available tokens.
Link to this function

update(Shaper, TokensNowUsed)

View Source 
-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.