Struct governor::DirectRateLimiter

pub struct DirectRateLimiter<C: Clock = DefaultClock> { /* fields omitted */ }

An in-memory rate limiter that makes direct (un-keyed) rate-limiting decisions. Direct rate limiters can be used to e.g. regulate the transmission of packets on a single connection, or to ensure that an API client stays within a service's rate limit.

Methods

impl DirectRateLimiter<MonotonicClock>

Methods that allow asynchronously waiting for the rate limit to clear.

pub async fn until_ready<'_>(&'_ self)

Asynchronously resolves as soon as the rate limiter allows it.

When polled, the returned future either resolves immediately (in the case where the rate limiter allows it), or else triggers an asynchronous delay, after which the rate limiter is polled again. This means that the future might resolve at some later time (depending on what other measurements are made on the rate limiter).

If multiple futures are dispatched against the rate limiter, it is advisable to use until_ready_with_jitter, to avoid thundering herds.

pub async fn until_ready_with_jitter<'_>(&'_ self, jitter: Jitter)

Asynchronously resolves as soon as the rate limiter allows it, with a randomized wait period.

When polled, the returned future either resolves immediately (in the case where the rate limiter allows it), or else triggers an asynchronous delay, after which the rate limiter is polled again. This means that the future might resolve at some later time (depending on what other measurements are made on the rate limiter).

This method allows for a randomized additional delay between polls of the rate limiter, which can help reduce the likelihood of thundering herd effects if multiple tasks try to wait on the same rate limiter.

impl DirectRateLimiter<DefaultClock>

The default constructor in std mode.

pub fn new(quota: Quota) -> Self

Construct a new direct rate limiter for a quota with the default clock.

impl<C: Clock> DirectRateLimiter<C>

Manually checking cells against a rate limit.

pub fn check(&self) -> Result<(), NotUntil<C::Instant>>

Allow a single cell through the rate limiter.

If the rate limit is reached, check returns information about the earliest time that a cell might be allowed through again.

pub fn check_all(
    &self,
    n: NonZeroU32
) -> Result<(), NegativeMultiDecision<NotUntil<C::Instant>>>

Allow only all n cells through the rate limiter.

This method can succeed in only one way and fail in two ways:

• Success: If all n cells can be accommodated, it returns Ok(()).
• Failure (but ok): Not all cells can make it through at the current time. The result is Err(NegativeMultiDecision::BatchNonConforming(NotUntil)), which can be interrogated about when the batch might next conform.
• Failure (the batch can never go through): The rate limit is too low for the given number of cells.

Performance

This method diverges a little from the GCRA algorithm, using multiplication to determine the next theoretical arrival time, and so is not as fast as checking a single cell.

impl<C: Clock> DirectRateLimiter<C>

pub fn new_with_clock(quota: Quota, clock: &C) -> DirectRateLimiter<C>

Construct a new direct rate limiter with a custom clock.

Important traits for &'_ mut W

impl<'_, W> Write for &'_ mut W where
    W: Write + ?Sized, impl<'_, R> Read for &'_ mut R where
    R: Read + ?Sized, impl<'_, F> Future for &'_ mut F where
    F: Unpin + Future + ?Sized,  type Output = <F as Future>::Output;impl<'_, I> Iterator for &'_ mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn get_clock(&self) -> &C

Returns a reference to the rate limiter's clock.

Trait Implementations

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

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

Formats the value using the given formatter.