Struct TokenBucket 

pub struct TokenBucket<I> { /* private fields */ }

A token bucket.

Calculations are performed at microsecond resolution. You likely want to call refill() each time you want to access or perform an operation on the token bucket.

This is partially inspired by tor’s token_bucket_ctr_t, but the implementation is quite a bit different. We use larger values here (for example u64), and we aim to avoid drift when refills occur at times that aren’t exactly in period with the refill rate.

It’s possible that we could relax these requirements to reduce memory usage and computation complexity, but that optimization should probably only be made if/when needed since it would make the code more difficult to reason about, and possibly more complex.

Implementations

impl<I: TokenBucketInstant> TokenBucket<I>

pub fn new(config: &TokenBucketConfig, now: I) -> Self

A new TokenBucket with a given rate in tokens/second and a max token limit.

The bucket will initially be full. The value max is commonly referred to as the “burst”.

pub fn is_empty(&self) -> bool

Are there no tokens in the bucket?

pub fn max(&self) -> u64

The maximum number of tokens that this bucket can hold.

pub fn drain( &mut self, count: u64, ) -> Result<BecameEmpty, InsufficientTokensError>

Remove count tokens from the bucket.

pub fn claim( &mut self, count: u64, ) -> Result<ClaimedTokens<'_, I>, InsufficientTokensError>

Claim a number of tokens.

The claim will be held by the returned ClaimedTokens, and committed when dropped.

Note: You probably want to call refill() before this.

pub fn adjust(&mut self, now: I, config: &TokenBucketConfig)

Adjust the refill rate and max tokens of the bucket.

The token bucket is refilled up to now before changing the rate.

If the new max is smaller than the existing number of tokens, the number of tokens will be reduced to the new max.

A rate and/or max of 0 is allowed.

pub fn tokens_available_at( &self, tokens: u64, ) -> Result<I, NeverEnoughTokensError>

An estimated time at which the bucket will have tokens available.

It is not guaranteed that tokens will be available at the returned time.

If there are already enough tokens available, a time in the past may be returned.

A value of None implies “never”, for example if the refill rate is 0, the bucket max is too small, or the time is too large to be represented as an I.

pub fn refill(&mut self, now: I) -> BecameNonEmpty

Refill the bucket.

Trait Implementations

impl<I: Debug> Debug for TokenBucket<I>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.