Struct Throttle 

pub struct Throttle { /* private fields */ }

Token-bucket admission control gate.

The bucket is initialised full, so the first burst of up to capacity tokens is granted immediately.

Implementations

impl Throttle

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

Build a new throttle with the given burst capacity and sustained refill rate. The bucket starts full.

The queue metric label defaults to "default". Use Throttle::with_name to pick a meaningful label.

pub fn with_name(name: &'static str, capacity: u64, refill_per_sec: u64) -> Self

Build a new throttle with an explicit metric label.

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

Try to take n tokens. Returns true on success and false if the bucket does not currently hold n tokens. Refills the bucket from the elapsed wall-clock interval before checking.

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

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

Acquire n tokens, waiting if necessary for the bucket to refill. The time spent waiting is recorded on the throttle_wait_seconds histogram.

Panics

Panics if n > capacity. The bucket can never hold that many tokens, so an unconditional wait would be a deadlock. Panics if refill_per_sec is zero and the initial bucket cannot satisfy the request: the throttle has no way to ever recover, so a deadlock is the alternative.

Trait Implementations

impl Debug for Throttle

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

Formats the value using the given formatter.