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) -> Self

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) -> Self

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

The configured Rate.

pub const fn burst(&self) -> u64

The configured burst capacity.

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

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)

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

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

Trait Implementations

impl Clone for TokenBucket

fn clone(&self) -> Self

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

Formats the value using the given formatter.