Struct leaky_bucket::LeakyBucket

pub struct LeakyBucket { /* fields omitted */ }

The leaky bucket.

Implementations

impl LeakyBucket

pub fn builder() -> Builder<'static>

Construct a new leaky bucket through a builder.

pub fn tokens(&self) -> usize

Query how many tokens are available.

This is just a best-effort estimate, calling this to ensure that there are enough tokens available to avoid blocking does not guarantee that the acquire operation won't block.

Tokens is always reported as less than or equal to max.

Example

use leaky_bucket::LeakyBucket;
use std::{error::Error, time::Duration};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let rate_limiter = LeakyBucket::builder()
        .max(5)
        .tokens(0)
        .build()?;

    assert_eq!(0, rate_limiter.tokens());

    println!("Waiting for permit...");
    // should take about 5 seconds to acquire.
    rate_limiter.acquire_one().await?;
    println!("I made it!");

    assert!(rate_limiter.tokens() >= 0 && rate_limiter.tokens() <= rate_limiter.max());
    Ok(())
}

pub fn max(&self) -> usize

Get the max number of tokens this rate limiter is configured for.

pub async fn acquire_one(&self) -> Result<(), Error>

Acquire a single token.

This is identical to acquire with an argument of 1.

Example

use leaky_bucket::LeakyBucket;
use std::{error::Error, time::Duration};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let rate_limiter = LeakyBucket::builder()
        .max(5)
        .tokens(0)
        .build()?;

    assert_eq!(0, rate_limiter.tokens());

    println!("Waiting for permit...");
    // should take about 5 seconds to acquire.
    rate_limiter.acquire_one().await?;
    println!("I made it!");

    assert_eq!(0, rate_limiter.tokens());
    Ok(())
}

pub async fn acquire(&self, amount: usize) -> Result<(), Error>

Acquire the given amount of tokens.

Note that you are allowed to acquire more tokens than the current max, but the acquire will have to suspend the task until enough tokens has built up to satisfy the request.

Example

use leaky_bucket::LeakyBucket;
use std::{error::Error, time::Duration};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let rate_limiter = LeakyBucket::builder()
        .max(5)
        .tokens(5)
        .build()?;

    assert_eq!(5, rate_limiter.tokens());

    println!("Waiting for permit...");
    // should take about 5 seconds to acquire.
    rate_limiter.acquire(10).await?;
    println!("I made it!");

    assert_eq!(0, rate_limiter.tokens());
    Ok(())
}

Errors

The returned future will fail with an Error::TokenOverflow if the tracked number of tokens attempts to overflow the internal token counter, which is an usize.

For this reason you should prefer to use smaller values in the amount acquired.

Trait Implementations

impl Clone for LeakyBucket

pub fn clone(&self) -> LeakyBucket

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LeakyBucket

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

Formats the value using the given formatter.