Struct leaky_bucket::RateLimiter

pub struct RateLimiter { /* private fields */ }

A token-bucket rate limiter.

Implementations

impl RateLimiter

pub fn builder() -> Builder

Construct a new Builder for a RateLimiter.

Examples

use leaky_bucket::RateLimiter;
use std::time::Duration;

let limiter = RateLimiter::builder()
    .initial(100)
    .refill(100)
    .max(1000)
    .interval(Duration::from_millis(250))
    .fair(false)
    .build();

pub fn balance(&self) -> usize

Get the current token balance.

This indicates how many tokens can be requested without blocking.

Examples

use leaky_bucket::RateLimiter;

let limiter = RateLimiter::builder()
    .initial(100)
    .build();

assert_eq!(limiter.balance(), 100);
limiter.acquire(10).await;
assert_eq!(limiter.balance(), 90);

pub fn acquire_one(&self) -> Acquire<'_>

Acquire a single permit.

Examples

use leaky_bucket::RateLimiter;

let limiter = RateLimiter::builder()
    .initial(10)
    .build();

limiter.acquire_one().await;

pub fn acquire(&self, permits: usize) -> Acquire<'_>

Acquire the given number of permits, suspending the current task until they are available.

If zero permits are specified, this function never suspends the current task.

Examples

use leaky_bucket::RateLimiter;

let limiter = RateLimiter::builder()
    .initial(10)
    .build();

limiter.acquire(10).await;

pub fn acquire_owned(self: Arc<Self>, permits: usize) -> AcquireOwned

Acquire a permit using an owned future.

If zero permits are specified, this function never suspends the current task.

This required the RateLimiter to be wrapped inside of an std::sync::Arc but will in contrast permit the acquire operation to be owned by another struct making it more suitable for embedding.

Examples

use leaky_bucket::RateLimiter;
use std::sync::Arc;

let limiter = Arc::new(RateLimiter::builder().initial(10).build());

limiter.acquire_owned(10).await;

Example when embedded into another future. This wouldn’t be possible with RateLimiter::acquire since it would otherwise hold a reference to the corresponding RateLimiter instance.

use leaky_bucket::{AcquireOwned, RateLimiter};
use pin_project::pin_project;
use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
use std::task::{Context, Poll};
use std::time::Duration;

#[pin_project]
struct MyFuture {
    limiter: Arc<RateLimiter>,
    #[pin]
    acquire: Option<AcquireOwned>,
}

impl Future for MyFuture {
    type Output = ();

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        let mut this = self.project();

        loop {
            if let Some(acquire) = this.acquire.as_mut().as_pin_mut() {
                futures::ready!(acquire.poll(cx));
                return Poll::Ready(());
            }

            this.acquire.set(Some(this.limiter.clone().acquire_owned(100)));
        }
    }
}

let limiter = Arc::new(RateLimiter::builder().initial(100).build());

let future = MyFuture { limiter, acquire: None };
future.await;

Trait Implementations

impl Send for RateLimiter

impl Sync for RateLimiter