Utils/docs/TokenBucket.md
TokenBucket is a pure utility class used for throttling actions, such as
components that want to throttle events.
It is similar to RateLimiter, but supports a different throttling behavior,
specifically time-based throughput throttling with burstiness. For instance,
TokenBucket allows a burst of 5 triggers, before throttling them to 1 trigger
per second after. Unused triggers are collected up to the burst maximum.
TokenBucket is a class that can be included and instantiated with the initial replenish interval and max tokens.
#include <Utils/TokenBucket.hpp>
...
U32 replenishIntervalMicroSecs = 1000000;
U32 maxTokens = 5;
TokenBucket bucket(replenishIntervalMicroSecs, maxTokens);
This instantiates TokenBucket with 5 initial tokens out of 5 maximum.
Updating and testing if an action should trigger is done in one method:
if (bucket.trigger(this->getTime())) {
// perform action, e.g. log EVR
}
Your component must provide it the current Fw::Time in the trigger. It will
then use that time to evaluate how many tokens to replenish between the last
trigger and now, and evaluate whether a token can be consumed.
With 5 initial tokens, the first five triggers are guaranteed to return true, no matter what the time given is. After that, trigger will return true only if time has elapsed enough for a token to be replenished (in this example, once per second).
Note that the max tokens is capped at 1000, currently defined as
MAX_TOKEN_BUCKET_TOKENS in TokenBucket.hpp.
TokenBucket can be constructed with 3 more parameters:
U32 replenishIntervalMicroSecs = 1000000;
U32 maxTokens = 5;
U32 replenishRate = 2;
U32 startTokens = 2;
Fw::Time startTime(5, 0);
TokenBucket bucket(replenishIntervalMicroSecs, maxTokens, replenishRate, startTokens, startTime);