Struct Throttle 

pub struct Throttle<C: Clock = SystemClock> { /* private fields */ }

Token-bucket admission control gate.

The bucket is initialised full, so the first burst of up to capacity tokens is granted immediately. Tokens accrue at refill_per_sec per second up to capacity, computed lazily against the Clock on each Throttle::try_acquire call.

Throttle is generic over the clock so loom and unit tests can inject a ManualClock. Production code uses the SystemClock default.

Implementations

impl Throttle<SystemClock>

pub fn new(capacity: u64, refill_per_sec: u64) -> Self

Builds a throttle backed by the SystemClock.

The bucket starts full; the first acquire of up to capacity tokens succeeds without waiting.

impl<C: Clock> Throttle<C>

pub fn with_clock(capacity: u64, refill_per_sec: u64, clock: C) -> Self

Builds a throttle that consults clock for refill timing.

The bucket starts full and the last-refill timestamp is captured from clock at construction time. Subsequent clock.now() values must be monotonic relative to that initial reading.

pub fn capacity(&self) -> u64

Burst capacity (the maximum number of tokens that may be acquired in one go).

pub fn refill_per_sec(&self) -> u64

Sustained refill rate in tokens per second.

pub fn available(&self) -> u64

Best-effort snapshot of the currently available tokens.

Useful for tests and diagnostics; do not branch on this in admission code (use Throttle::try_acquire instead).

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

Tries to take n tokens.

Returns true on success and false if the bucket does not currently hold n tokens. The bucket is refilled from the clock-elapsed interval before the check.

Requesting n > capacity always returns false: the bucket can never hold that many tokens, so blocking would be pointless.

pub fn acquire_blocking(&self, n: u64) -> Result<(), ThrottleError>

Acquires n tokens, sleeping the calling thread if the bucket is empty.

This is the synchronous counterpart of dynomite’s async Throttle::acquire. The wait loop sleeps for the time required to refill the missing tokens at refill_per_sec, clamped to the range 1 ms .. 1 s so a fractional refill never spins tightly and a misconfigured throttle still polls regularly.

Errors

• ThrottleError::RequestExceedsCapacity if n is larger than the bucket’s capacity.
• ThrottleError::ZeroRefillExhausted if refill_per_sec == 0 and the initial bucket cannot satisfy the request.

Trait Implementations

impl<C: Clock> Debug for Throttle<C>

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

Formats the value using the given formatter.