Struct async_speed_limit::limiter::Limiter

pub struct Limiter<C: Clock = StandardClock> { /* fields omitted */ }

A type to control the maximum speed limit of multiple streams.

When a Limiter is cloned, the instances would share the same queue. Multiple tasks can cooperatively respect a global speed limit via clones. Cloning a Limiter is cheap (equals to cloning two Arcs).

The speed limit is imposed by awaiting consume(). The method returns a future which sleeps until rate falls below the limit.

Examples

Upload some small files atomically in parallel, while maintaining a global speed limit of 1 MiB/s.

use async_speed_limit::Limiter;
use futures_util::future::try_join_all;

let limiter = <Limiter>::new(1_048_576.0);
let processes = files
    .iter()
    .map(|file| {
        let limiter = limiter.clone();
        async move {
            limiter.consume(file.len()).await;
            upload(file).await?;
            Ok(())
        }
    });
try_join_all(processes).await?;

Implementations

impl<C: Clock> Limiter<C>

pub fn new(speed_limit: f64) -> Self

Creates a new speed limiter.

Use infinity to make the speed unlimited.

pub fn builder(speed_limit: f64) -> Builder<C>

Makes a Builder for further configurating this limiter.

Use infinity to make the speed unlimited.

pub fn clock(&self) -> &C

Returns the clock associated with this limiter.

pub fn set_speed_limit(&self, speed_limit: f64)

Dynamically changes the speed limit. The new limit applies to all clones of this instance.

Use infinity to make the speed unlimited.

This change will not affect any tasks scheduled before this call.

pub fn speed_limit(&self) -> f64

Returns the current speed limit.

This method returns infinity if the speed is unlimited.

pub fn total_bytes_consumed(&self) -> usize

Obtains the total number of bytes consumed by this limiter so far.

If more than usize::MAX bytes have been consumed, the count will wrap around.

pub fn reset_statistics(&self)

Resets the total number of bytes consumed to 0.

pub fn consume_duration(&self, byte_size: usize) -> Duration

Consumes several bytes from the speed limiter, returns the duration needed to sleep to maintain the speed limit.

pub fn unconsume(&self, byte_size: usize)

Reverts the consumption of the given bytes size.

pub fn consume(&self, byte_size: usize) -> Consume<C, ()>

Consumes several bytes from the speed limiter.

The consumption happens at the beginning, before the speed limit is applied. The returned future is fulfilled after the speed limit is satified.

pub fn limit<R>(self, resource: R) -> Resource<R, C>

Wraps a streaming resource with speed limiting. See documentation of Resource for details.

If you want to reuse the limiter after calling this function, clone() the limiter first.

impl<C: BlockingClock> Limiter<C>

pub fn blocking_consume(&self, byte_size: usize)

Consumes several bytes, and sleeps the current thread to maintain the speed limit.

The consumption happens at the beginning, before the speed limit is applied. This method blocks the current thread (e.g. using std::thread::sleep() given a StandardClock), and must not be used in async context.

Prefer using this method instead of futures_executor::block_on(limiter.consume(size)).

Trait Implementations

impl<C: Clone + Clock> Clone for Limiter<C> where
    C::Instant: Clone, 

fn clone(&self) -> Limiter<C>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<C: Debug + Clock> Debug for Limiter<C> where
    C::Instant: Debug, 

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

Formats the value using the given formatter.