Struct ratelimit_meter::algorithms::gcra::GCRA
[−]
[src]
pub struct GCRA { /* fields omitted */ }
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 = GCRA::for_capacity(20).unwrap().cell_weight(1).unwrap().build(); let now = Instant::now(); let ms = Duration::from_millis(1); assert_eq!(Decision::Yes, limiter.check_at(now).unwrap()); // the first cell is free for i in 0..20 { // Spam a lot: assert_eq!(Decision::Yes, limiter.check_at(now).unwrap(), "at {}", i); } // We have exceeded the bucket capacity: assert!(!limiter.check_at(now).unwrap().is_compliant()); // After a sufficient time period, cells are allowed again: assert_eq!(Decision::Yes, limiter.check_at(now + ms*50).unwrap());
Methods
impl GCRA
[src]
fn for_capacity(capacity: u32) -> Result<Builder>
[src]
Constructs a builder object for a GCRA rate-limiter with the
given capacity per second, at cell weight=1. See
Builder
for options.
fn with_parameters(t: Duration, tau: Duration, tat: Option<Instant>) -> GCRA
[src]
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 Decider for GCRA
[src]
fn check(&mut self) -> Result<Decision<Self::T>>
[src]
Tests if a single cell can be accommodated at Instant::now()
. See check_at
. Read more
fn check_at(&mut self, at: Instant) -> Result<Decision<Self::T>>
[src]
Tests is a single cell can be accommodated at the given time stamp. Read more
impl MultiDecider for GCRA
[src]
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<Decision<Self::T>>
[src]
Tests if n
cells can be accommodated at the given time stamp. An error ErrorKind::InsufficientCapacity
is returned if n
exceeds the bucket capacity. Read more
fn check_n(&mut self, n: u32) -> Result<Decision<Self::T>>
[src]
Tests if n
cells can be accommodated at the current time (Instant::now()
). An error ErrorKind::InsufficientCapacity
is returned if n
exceeds the bucket capacity. Read more
impl TypedDecider for GCRA
[src]
type T = Instant
In GCRA, negative decisions come with the time at which the next cell was expected to arrive; client code of GCRA can use this to decide what to do with the non-conforming cell.
impl Debug for GCRA
[src]
impl Clone for GCRA
[src]
fn clone(&self) -> GCRA
[src]
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0[src]
Performs copy-assignment from source
. Read more
impl From<Builder> for GCRA
[src]
Allows converting from a GCRA builder directly into a
GCRA decider. Same as
the borrowed implementation, except for
owned Builder
s.
Example:
use ratelimit_meter::{GCRA, Decider, Decision}; let mut gcra: GCRA = GCRA::for_capacity(50).unwrap().into(); assert_eq!(Decision::Yes, gcra.check().unwrap());
impl<'a> From<&'a mut Builder> for GCRA
[src]
Allows converting a GCRA builder directly into a GCRA decider.
Example:
use ratelimit_meter::{GCRA, Decider, Decision}; let mut gcra: GCRA = GCRA::for_capacity(50).unwrap().cell_weight(2).unwrap().into(); assert_eq!(Decision::Yes, gcra.check().unwrap());
impl<'a> Into<(Duration, Duration, Option<Instant>)> for &'a GCRA
[src]
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.
impl From<(Duration, Duration, Option<Instant>)> for GCRA
[src]
Allows converting the parameters returned from
Into<(Duration, Duration, Option<Instant>)>
back into a GCRA.