Struct TokenBucket 

pub struct TokenBucket { /* private fields */ }

Lock-free token bucket using atomic CAS operations.

All mutable state is stored in AtomicU64 — no Mutex is acquired on the hot path. Token refill is computed lazily on each acquire / try_acquire call based on elapsed time since the last refill.

Integer arithmetic is used throughout (no f64) for deterministic behaviour and to avoid floating-point CAS issues. Token counts are tracked in milli-tokens (tokens * 1000) to provide sub-token precision while staying in integer domain.

All public methods take &self (not &mut self), enabling concurrent access from multiple tasks via a shared reference.

Implementations

impl TokenBucket

pub fn new(rate_bytes_per_sec: u64, burst_bytes: Option<u64>) -> Self

Create a new token bucket with the given rate and optional burst.

rate_bytes_per_sec of 0 produces a bucket that never refills — callers should use TokenBucket::unlimited instead for “no limit” semantics.

pub fn unlimited() -> Self

Create an unlimited token bucket — acquire / try_acquire always succeed instantly without consuming any real tokens.

pub fn is_unlimited(&self) -> bool

Returns true if this bucket has no rate limit.

pub fn rate(&self) -> f64

Returns the configured rate in bytes per second (as f64 for API compat). Returns f64::MAX for unlimited buckets.

pub fn available_tokens(&self) -> f64

Returns the current available tokens (as f64 for API compat). Triggers a lazy refill before reading. Returns f64::MAX for unlimited buckets.

pub async fn acquire(&self, bytes: u64)

Acquire bytes tokens, blocking (async-sleeping) until enough tokens are available.

For requests larger than the burst capacity, this method waits for the deficit and then force-acquires (setting tokens to 0), matching the original implementation’s behaviour of allowing token “debt” clamped to zero. This prevents infinite loops when needed > capacity.

pub fn try_acquire(&self, bytes: u64) -> bool

Non-blocking attempt to acquire bytes tokens. Returns true if tokens were available and deducted, false otherwise.

pub fn set_rate(&self, rate_bytes_per_sec: u64)

Update the refill rate dynamically. Takes effect on the next refill cycle. rate_bytes_per_sec of 0 effectively pauses the bucket (no new tokens).

pub fn set_unlimited(&self, unlimited: bool)

Toggle the unlimited flag. When set to true, acquire/try_acquire always succeed instantly without consuming tokens.

Trait Implementations

impl Debug for TokenBucket

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

Formats the value using the given formatter.