[][src]Crate ratelimit_futures

Rate-limiting for futures.

This crate hooks the ratelimit_meter crate up to futures v0.1 (the same version supported by Tokio right now).

Usage & mechanics of rate limiting with futures

To use this crate's Future type, use the provided Ratelimit::new function. It takes a direct rate limiter (an in-memory rate limiter implementation), and returns a Future that can be chained to the actual work that you mean to perform:

use futures::prelude::*;
use futures::future::{self, FutureResult};
use ratelimit_meter::{DirectRateLimiter, LeakyBucket};
use ratelimit_futures::Ratelimit;
use std::num::NonZeroU32;

let mut lim = DirectRateLimiter::<LeakyBucket>::per_second(NonZeroU32::new(1).unwrap());
{
    let mut lim = lim.clone();
    let ratelimit_future = Ratelimit::new(&mut lim);
    let future_of_3 = ratelimit_future.and_then(|_| {
        Ok(3)
    });
}
{
    let mut lim = lim.clone();
    let ratelimit_future = Ratelimit::new(&mut lim);
    let future_of_4 = ratelimit_future.and_then(|_| {
        Ok(4)
    });
}
// 1 second will pass before both futures resolve.

In this example, we're constructing futures that can each start work only once the (shared) rate limiter says that it's ok to start.

You can probably guess the mechanics of using these rate-limiting futures:

  • Chain your work to them using .and_then.
  • Construct and a single rate limiter for the work that needs to count against that rate limit. You can share them using their Clone trait.
  • Rate-limiting futures will wait as long as it takes to arrive at a point where code is allowed to proceed. If the shared rate limiter already allowed another piece of code to proceed, the wait time will be extended.

Structs

Ratelimit

The rate-limiter as a future.