Struct RateLimiter 

pub struct RateLimiter { /* private fields */ }

Available on crate feature std only.

A cheap-to-clone async handle around a shared TokenBucket: clones share the same budget.

Two ways to consume it:

• RateLimiter::acquire waits until the budget allows (pacing);
• RateLimiter::try_acquire never waits and reports when to retry (rejecting, e.g. a 429 path).

Time is tracked against a per-limiter epoch taken at construction, using tokio’s clock (so paused-time tests work as expected).

There is no FIFO fairness guarantee between concurrent waiters. Under a sustained stream of smaller acquisitions, a larger acquisition can be repeatedly beaten to newly refilled tokens and starve; callers that need strict waiter fairness must serialize acquisitions above this primitive.

Implementations

impl RateLimiter

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

Create a new RateLimiter with the given Rate and burst capacity, starting full.

Panics

Panics if burst is zero.

pub fn from_rate(rate: Rate) -> Self

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

pub fn rate(&self) -> Rate

The configured Rate.

pub fn burst(&self) -> u64

The configured burst capacity.

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

Try to spend n units without waiting.

See TokenBucket::try_acquire; the Acquire::RetryAt instant is in this limiter’s clock and can be turned into a deadline with RateLimiter::deadline.

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

Spend n units, waiting until the budget allows it.

Requests larger than the burst capacity are acquired in burst-sized chunks, so this never fails: it paces. Concurrent acquisitions are not queued fairly; see the type docs.

Dropping the future while it waits for a chunk spends nothing for that chunk. For a request larger than the burst, chunks already acquired before cancellation stay spent. Refunding them could mint capacity when concurrent users spent refill produced while those chunks were held.

pub fn refund(&self, n: u64)

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

pub fn notified_on_refund(&self) -> RefundWait

Wait until this limiter is next refunded.

Poll-based users should create this listener before calling try_acquire, so a concurrent refund cannot land between observing a deficit and registering for notification.

pub fn deadline(&self, retry_at_nanos: u64) -> Instant

Turn an Acquire::RetryAt instant into a timer deadline, for poll-based callers.

Trait Implementations

impl Clone for RateLimiter

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 RateLimiter

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

Formats the value using the given formatter.