Struct ratelimit_meter::GCRA

pub struct GCRA { /* private fields */ }

Implements the virtual scheduling description of the Generic Cell Rate Algorithm, attributed to ITU-T in recommendation I.371 Traffic control and congestion control in B-ISDN; from Wikipedia.

While algorithms like leaky-bucket rate limiters allow cells to be distributed across time in any way, GCRA is a rate-limiting and traffic-shaping algorithm. It mandates that a minimum amount of time passes between cells being measured. For example, if your API mandates that only 20 requests can be made per second, GCRA will ensure that each request is at least 50ms apart from the previous request. This makes GCRA suitable for shaping traffic in networking and telecom equipment (it was initially made for asynchronous transfer mode networks), or for outgoing workloads on consumers of attention, e.g. distributing outgoing emails across a day.

In a blatant side-stepping of the above traffic-shaping criteria, this implementation of GCRA comes with an extension that allows measuring multiple cells at once, assuming that if a pause of n*(the minimum time between cells) has passed, we can allow a single big batch of n cells through. This assumption may not be correct for your application, but if you depend on GCRA’s traffic-shaping properties, it’s better to not use the _n suffixed check functions.

Example

In this example, we construct a rate-limiter with the GCR algorithm that can accommodate 20 cells per second. This translates to the GCRA parameters τ=1s, T=50ms (that’s 1s / 20 cells).

let mut limiter = per_second::<GCRA>(NonZeroU32::new(20).unwrap());
let now = Instant::now();
let ms = Duration::from_millis(1);
assert_eq!(Ok(()), limiter.check_at(now)); // the first cell is free
for i in 0..20 {
    // Spam a lot:
    assert!(limiter.check_at(now).is_ok(), "at {}", i);
}
// We have exceeded the bucket capacity:
assert!(limiter.check_at(now).is_err());

// After a sufficient time period, cells are allowed again:
assert_eq!(Ok(()), limiter.check_at(now + ms*50));

Implementations

impl GCRA

pub fn with_parameters<T: Into<Option<Instant>>>(
    t: Duration,
    tau: Duration,
    tat: T
) -> GCRA

Constructs a GCRA rate-limiter with the parameters T (the minimum amount of time that single cells are spaced apart), tau (τ, the number of cells that fit into this buffer), and an optional t_at (the earliest instant that the rate-limiter would accept another cell).

Trait Implementations

impl Clone for GCRA

fn clone(&self) -> GCRA

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for GCRA

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

Formats the value using the given formatter.

impl Decider for GCRA

fn check(&mut self) -> Result<(), NonConformance>

Tests if a single cell can be accommodated at Instant::now(). If it can be, check updates the Decider to account for the conforming cell and returns Ok(()).

fn check_at(&mut self, at: Instant) -> Result<(), NonConformance>

Tests whether a single cell can be accommodated at the given time stamp. See check.

impl From<(Duration, Duration, Option<Instant>)> for GCRA

Allows converting the parameters returned from [Into<(Duration, Duration, Option<Instant>)>](#impl-Into<(Duration, Duration, Option)>) back into a GCRA.

fn from(params: (Duration, Duration, Option<Instant>)) -> GCRA

Converts to this type from the input type.

impl<'a> Into<(Duration, Duration, Option<Instant>)> for &'a GCRA

Allows converting a GCRA into a tuple containing its T (the minimum amount of time that single cells are spaced apart), tau (τ, the number of cells that fit into this buffer), and an optional t_at (the earliest instant that the rate-limiter would accept another cell).

These parameters can be used with .with_parameters to persist and construct a copy of the GCRA rate-limiter.

fn into(self) -> (Duration, Duration, Option<Instant>)

Converts this type into the (usually inferred) input type.

impl MultiDecider for GCRA

This crate’s GCRA implementation also allows checking multiple cells at once, assuming that (counter the traffic-shaping properties of GCRA) if a sufficiently long pause (n*t) has occurred between cells, the algorithm can accommodate n cells.

As this assumption does not necessarily hold in all circumstances, users of this trait on GCRA limiters should ensure that this is ok.

fn check_n_at(&mut self, n: u32, at: Instant) -> Result<(), NegativeMultiDecision>

Tests if n cells can be accommodated at the given time stamp. If (and only if) all cells in the batch can be accomodated, the MultiDecider updates the internal state to account for all cells and returns Ok(()).

fn check_n(&mut self, n: u32) -> Result<(), NegativeMultiDecision>

Tests if n cells can be accommodated at the current time (Instant::now()), using check_n_at