Struct RateLimiter 

pub struct RateLimiter { /* private fields */ }

A token-bucket rate limiter.

Construct one with RateLimiter::new, then gate work with try_acquire / try_acquire_one. The bucket starts full (a burst of up to capacity is allowed immediately).

Time is a plain u64 in any monotonic unit you choose (commonly milliseconds); refill_interval uses that same unit. The limiter never reads the clock itself — pass now to each method.

RateLimiter is not internally synchronized. Share one across threads by wrapping it in your own Mutex/lock.

Implementations

impl RateLimiter

pub const fn new( capacity: u64, refill_amount: u64, refill_interval: u64, ) -> Self

Creates a limiter that holds up to capacity tokens and adds refill_amount tokens every refill_interval time units.

The bucket starts full. capacity, refill_amount, and refill_interval are each clamped to a minimum of 1 (a zero interval would never refill and would divide by zero).

Examples found in repository

examples/basic.rs (line 16)

fn main() {
    // Allow bursts of up to 5, refilling 1 token every 200ms.
    let mut limiter = RateLimiter::new(5, 1, 200);
    let start = Instant::now();

    for i in 0..15 {
        let now = start.elapsed().as_millis() as u64;

        if limiter.try_acquire_one(now) {
            println!(
                "[{now:>4}ms] request {i:>2}: allowed ({} left)",
                limiter.available(now)
            );
        } else {
            let wait = limiter.retry_after(now, 1).unwrap_or(0);
            println!("[{now:>4}ms] request {i:>2}: throttled, retry after {wait}ms");
        }

        std::thread::sleep(std::time::Duration::from_millis(80));
    }
}

pub const fn capacity(&self) -> u64

Returns the bucket capacity (the maximum burst).

pub const fn refill_amount(&self) -> u64

Returns how many tokens are added on each refill.

pub const fn refill_interval(&self) -> u64

Returns the refill interval, in the caller’s time unit.

pub fn available(&mut self, now: u64) -> u64

Returns the number of tokens available at now, after refilling.

Examples found in repository

examples/basic.rs (line 25)

fn main() {
    // Allow bursts of up to 5, refilling 1 token every 200ms.
    let mut limiter = RateLimiter::new(5, 1, 200);
    let start = Instant::now();

    for i in 0..15 {
        let now = start.elapsed().as_millis() as u64;

        if limiter.try_acquire_one(now) {
            println!(
                "[{now:>4}ms] request {i:>2}: allowed ({} left)",
                limiter.available(now)
            );
        } else {
            let wait = limiter.retry_after(now, 1).unwrap_or(0);
            println!("[{now:>4}ms] request {i:>2}: throttled, retry after {wait}ms");
        }

        std::thread::sleep(std::time::Duration::from_millis(80));
    }
}

pub fn try_acquire(&mut self, now: u64, tokens: u64) -> bool

Tries to take tokens tokens at now. Returns true and consumes them if enough are available, otherwise returns false and consumes nothing.

A request for more than capacity tokens can never succeed.

pub fn try_acquire_one(&mut self, now: u64) -> bool

Tries to take a single token at now.

Examples found in repository

examples/basic.rs (line 22)

fn main() {
    // Allow bursts of up to 5, refilling 1 token every 200ms.
    let mut limiter = RateLimiter::new(5, 1, 200);
    let start = Instant::now();

    for i in 0..15 {
        let now = start.elapsed().as_millis() as u64;

        if limiter.try_acquire_one(now) {
            println!(
                "[{now:>4}ms] request {i:>2}: allowed ({} left)",
                limiter.available(now)
            );
        } else {
            let wait = limiter.retry_after(now, 1).unwrap_or(0);
            println!("[{now:>4}ms] request {i:>2}: throttled, retry after {wait}ms");
        }

        std::thread::sleep(std::time::Duration::from_millis(80));
    }
}

pub fn retry_after(&mut self, now: u64, tokens: u64) -> Option<u64>

Returns how long to wait, from now, until tokens tokens are available.

Returns Some(0) if they are available now, and None if tokens exceeds capacity (the bucket can never hold that many). Useful for a Retry-After hint. This refills the bucket but does not consume anything.

Examples found in repository

examples/basic.rs (line 28)

fn main() {
    // Allow bursts of up to 5, refilling 1 token every 200ms.
    let mut limiter = RateLimiter::new(5, 1, 200);
    let start = Instant::now();

    for i in 0..15 {
        let now = start.elapsed().as_millis() as u64;

        if limiter.try_acquire_one(now) {
            println!(
                "[{now:>4}ms] request {i:>2}: allowed ({} left)",
                limiter.available(now)
            );
        } else {
            let wait = limiter.retry_after(now, 1).unwrap_or(0);
            println!("[{now:>4}ms] request {i:>2}: throttled, retry after {wait}ms");
        }

        std::thread::sleep(std::time::Duration::from_millis(80));
    }
}

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 Copy for RateLimiter

impl Debug for RateLimiter

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

Formats the value using the given formatter.

impl Eq for RateLimiter

impl PartialEq for RateLimiter

fn eq(&self, other: &RateLimiter) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for RateLimiter