Struct RateLimiter 

pub struct RateLimiter { /* private fields */ }

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

Available on crate features grpc and http and std only.

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

Available on crate features grpc and http and std only.

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

Available on crate features grpc and http and std only.

The configured Rate.

pub fn burst(&self) -> u64

Available on crate features grpc and http and std only.

The configured burst capacity.

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

Available on crate features grpc and http and std only.

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)

Available on crate features grpc and http and std only.

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)

Available on crate features grpc and http and std only.

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

pub fn notified_on_refund(&self) -> RefundWait

Available on crate features grpc and http and std only.

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

Available on crate features grpc and http and std only.

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

Trait Implementations

impl Clone for RateLimiter

fn clone(&self) -> RateLimiter

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<(), Error>

Formats the value using the given formatter.