Struct TokenBucket 

pub struct TokenBucket { /* private fields */ }

A sans-IO token bucket: spend units at a bounded Rate with a configurable burst capacity.

The bucket never reads a clock: the caller provides now as monotonic nanoseconds from any epoch, as long as it is consistent across calls. This keeps the bucket no_std, deterministic to test and embeddable in other sans-IO state machines.

Internally the level is stored scaled by the period (in nanoseconds), so refills are exact integer arithmetic with zero drift.

Examples

use rama_utils::rate::{Acquire, Rate, TokenBucket};

let mut bucket = TokenBucket::from_rate(Rate::per_sec(2));
assert_eq!(bucket.try_acquire(0, 1), Acquire::Granted);
assert_eq!(bucket.try_acquire(0, 1), Acquire::Granted);
// bucket is empty: the next unit refills after half a period
assert_eq!(bucket.try_acquire(0, 1), Acquire::RetryAt(500_000_000));
assert_eq!(bucket.try_acquire(500_000_000, 1), Acquire::Granted);

Implementations

impl TokenBucket

pub fn new(rate: Rate, burst: u64) -> TokenBucket

Available on crate features grpc and http and std only.

Create a new TokenBucket with the given Rate and burst capacity (the maximum units spendable at once).

The bucket starts full.

Panics

Panics if burst is zero.

pub fn from_rate(rate: Rate) -> TokenBucket

Available on crate features grpc and http and std only.

Create a new TokenBucket with a burst capacity of one period worth of units (rate.units()): a plain smooth rate.

pub const fn rate(&self) -> Rate

Available on crate features grpc and http and std only.

The configured Rate.

pub const fn burst(&self) -> u64

Available on crate features grpc and http and std only.

The configured burst capacity.

pub fn try_acquire(&mut self, now: u64, n: u64) -> Acquire

Available on crate features grpc and http and std only.

Try to spend n units at monotonic instant now (nanoseconds, caller’s clock).

• Acquire::Granted: the units were spent.
• Acquire::RetryAt: nothing was spent; retrying with the returned instant (and an otherwise untouched bucket) is guaranteed to be granted.
• Acquire::Never: n exceeds the burst capacity and can never be granted as a single acquisition.

n == 0 is always granted. A now earlier than a previously provided instant is treated as no time having passed.

pub fn refund(&mut self, n: u64)

Available on crate features grpc and http and std only.

Give back up to n previously spent units, saturating at the burst capacity.

Intended for callers that reserve budget upfront and end up using less (e.g. a short write).

pub fn available(&mut self, now: u64) -> u64

Available on crate features grpc and http and std only.

The number of whole units available at monotonic instant now (nanoseconds, caller’s clock).

Trait Implementations

impl Clone for TokenBucket

fn clone(&self) -> TokenBucket

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TokenBucket

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

Formats the value using the given formatter.