View Source speed_trap_token_bucket (speed_trap v1.1.1)

speed_trap_token_bucket implementation with atomics.

The current number of tokens is stored as a mutable atomic variable. When a token is taken from the bucket, the counter is decremented. It is allowed for the counter to become negative.

Adding tokens to the counter requires multiple operations. Since there is no operation to add with a threshold (contrary to ets:update_counter/3 for example), the value is first read and then incremented if necessary. It is possible that the value will be decremented between the two operations, but it cannot be incremented (given there's only one updater running at a time), so there's no risk of adding tokens above the bucket's capacity. On the other hand, the counter going below 0 is an issue that needs special handling: whenever the update operation finds a negative value, it sets the counter to 1. Incrementing it is not safe in this case, as concurrent processes may try to get tokens from the bucket, pushing its value to even lower between the read and the update.

It's worth mentioning that although counters can underflow, it is not a practical risk to call get_token/1 2^63 times in a single refill interval.

For simplicity, the actual updates are scheduled via timer:apply_interval/4, however an interval timer is linked to the process creating it. Therefore we need a simple server to own and manage these timers.

Summary

Types

state/0
token_bucket/0

Functions

active_buckets()
add_token(Bucket, BucketSize, RefillCount, DeleteWhenFull)
bucket(Id)
delete(Id, DeleteOverride)
Deletes a scheduled function by its id. The second parameter indicates whether to try deleting a store template based token bucket override by id or not.
delete_override(Id)
Deletes a possibly stored token bucket override from the store.
delete_overrides()
Cleans up the overrides store.
get_override(Id)
Gets an override from the overrides store.
get_token(Id)
handle_call(Request, From, Timers)
handle_cast(Request, Timers)
handle_info(Request, Timers)
init(_)
modify(Id, Options)
Modifies the scheduled function already registered under the given id.
new(Id, Options)
Add a new function to the scheduler. The provided MFA will be registered under the given id and applied every refill interval milliseconds.
options(Id)
return_token(Id)
start_link()
Start the scheduler server.

Types

Link to this type

state/0

View Source 
-type state() :: #{speed_trap:id() => timer:tref()}.
Link to this type

token_bucket/0

View Source 
-type token_bucket() :: atomics:atomics_ref().

Functions

Link to this function

active_buckets()

View Source 
-spec active_buckets() -> [{speed_trap:id(), speed_trap:stored_options()}].
Link to this function

add_token(Bucket, BucketSize, RefillCount, DeleteWhenFull)

View Source 
-spec add_token(token_bucket(), speed_trap:bucket_size(), speed_trap:refill_count(), boolean()) -> ok.
Link to this function

bucket(Id)

View Source 
-spec bucket(speed_trap:id()) ->
                {ok, {speed_trap:stored_options(), token_bucket()}} |
                {error, speed_trap:no_such_speed_trap()}.
Link to this function

delete(Id, DeleteOverride)

View Source 
-spec delete(speed_trap:id(), boolean()) -> ok | {error, speed_trap:no_such_speed_trap()}.
Deletes a scheduled function by its id. The second parameter indicates whether to try deleting a store template based token bucket override by id or not.
Link to this function

delete_override(Id)

View Source 
-spec delete_override(speed_trap:id()) -> ok.
Deletes a possibly stored token bucket override from the store.
Link to this function

delete_overrides()

View Source 
-spec delete_overrides() -> ok.
Cleans up the overrides store.
Link to this function

get_override(Id)

View Source 
-spec get_override(speed_trap:id()) -> {ok, speed_trap:modify_options()} | {error, not_found}.
Gets an override from the overrides store.
Link to this function

get_token(Id)

View Source 
-spec get_token(speed_trap:id()) ->
                   {ok, speed_trap:try_pass_success()} |
                   {error,
                    speed_trap:no_such_speed_trap() |
                    speed_trap:too_many_requests() |
                    speed_trap:blocked()}.
Link to this function

handle_call(Request, From, Timers)

View Source 
-spec handle_call(term(), {pid(), term()}, state()) -> {reply, ok | {error, term()}, state()}.
Link to this function

handle_cast(Request, Timers)

View Source 
-spec handle_cast(any(), state()) -> {noreply, state()}.
Link to this function

handle_info(Request, Timers)

View Source 
-spec handle_info(any(), state()) -> {noreply, state()}.
Link to this function

init(_)

View Source 
-spec init([]) -> {ok, state()}.
Link to this function

modify(Id, Options)

View Source 
-spec modify(speed_trap:id(), speed_trap:modify_options()) ->
                ok | {error, speed_trap_options:bad_options() | speed_trap:no_such_speed_trap()}.
Modifies the scheduled function already registered under the given id.
Link to this function

new(Id, Options)

View Source 
-spec new(speed_trap:id(), speed_trap:options()) -> ok | {error, speed_trap:already_exists()}.
Add a new function to the scheduler. The provided MFA will be registered under the given id and applied every refill interval milliseconds.
Link to this function

options(Id)

View Source 
-spec options(speed_trap:id()) ->
                 {ok, speed_trap:stored_options()} | {error, speed_trap:no_such_speed_trap()}.
Link to this function

return_token(Id)

View Source 
-spec return_token(speed_trap:id()) -> ok | {error, speed_trap:no_such_speed_trap()}.
Link to this function

start_link()

View Source 
-spec start_link() -> {ok, pid()} | {error, term()}.
Start the scheduler server.