Struct governor::Quota

source ·
pub struct Quota { /* private fields */ }
Expand description

A rate-limiting quota.

Quotas are expressed in a positive number of “cells” (the maximum number of positive decisions / allowed items until the rate limiter needs to replenish) and the amount of time for the rate limiter to replenish a single cell.

Neither the number of cells nor the replenishment unit of time may be zero.

§Burst sizes

There are multiple ways of expressing the same quota: a quota given as Quota::per_second(1) allows, on average, the same number of cells through as a quota given as Quota::per_minute(60). However, the quota of Quota::per_minute(60) has a burst size of 60 cells, meaning it is possible to accomodate 60 cells in one go, after which the equivalent of a minute of inactivity is required for the burst allowance to be fully restored.

Burst size gets really important when you construct a rate limiter that should allow multiple elements through at one time (using RateLimiter.check_n and its related functions): Only at most as many cells can be let through in one call as are given as the burst size.

In other words, the burst size is the maximum number of cells that the rate limiter will ever allow through without replenishing them.

§Examples

Construct a quota that allows 50 cells per second (replenishing at a rate of one cell per 20 milliseconds), with a burst size of 50 cells, allowing a full rate limiter to allow 50 cells through at a time:

let q = Quota::per_second(nonzero!(50u32));
assert_eq!(q, Quota::per_second(nonzero!(50u32)).allow_burst(nonzero!(50u32)));
assert_eq!(q.replenish_interval(), Duration::from_millis(20));
assert_eq!(q.burst_size().get(), 50);
// The Quota::new constructor is deprecated, but this constructs the equivalent quota:
#[allow(deprecated)]
assert_eq!(q, Quota::new(nonzero!(50u32), Duration::from_secs(1)).unwrap());

Construct a quota that allows 2 cells per hour through (replenishing at a rate of one cell per 30min), but allows bursting up to 90 cells at once:

let q = Quota::per_hour(nonzero!(2u32)).allow_burst(nonzero!(90u32));
assert_eq!(q.replenish_interval(), Duration::from_secs(30 * 60));
assert_eq!(q.burst_size().get(), 90);
// The entire maximum burst size will be restored if no cells are let through for 45 hours:
assert_eq!(q.burst_size_replenished_in(), Duration::from_secs(60 * 60 * (90 / 2)));

Implementations§

source§

impl Quota

Constructors for Quotas

source

pub const fn per_second(max_burst: NonZeroU32) -> Quota

Construct a quota for a number of cells per second. The given number of cells is also assumed to be the maximum burst size.

source

pub const fn per_minute(max_burst: NonZeroU32) -> Quota

Construct a quota for a number of cells per 60-second period. The given number of cells is also assumed to be the maximum burst size.

source

pub const fn per_hour(max_burst: NonZeroU32) -> Quota

Construct a quota for a number of cells per 60-minute (3600-second) period. The given number of cells is also assumed to be the maximum burst size.

source

pub fn with_period(replenish_1_per: Duration) -> Option<Quota>

Construct a quota that replenishes one cell in a given interval.

This constructor is meant to replace ::new, in cases where a longer refresh period than 1 cell/hour is necessary.

If the time interval is zero, returns None.

§Example
// Replenish one cell per day, with a burst capacity of 10 cells:
let _quota = Quota::with_period(Duration::from_secs(60 * 60 * 24))
    .unwrap()
    .allow_burst(nonzero!(10u32));
source

pub const fn allow_burst(self, max_burst: NonZeroU32) -> Quota

Adjusts the maximum burst size for a quota to construct a rate limiter with a capacity for at most the given number of cells.

source

pub fn new(max_burst: NonZeroU32, replenish_all_per: Duration) -> Option<Quota>

👎Deprecated since 0.2.0: This constructor is often confusing and non-intuitive. Use the per_(interval) / with_period and max_burst constructors instead.

Construct a quota for a given burst size, replenishing the entire burst size in that given unit of time.

Returns None if the duration is zero.

This constructor allows greater control over the resulting quota, but doesn’t make as much intuitive sense as other methods of constructing the same quotas. Unless your quotas are given as “max burst size, and time it takes to replenish that burst size”, you are better served by the Quota::per_second (and similar) constructors with the allow_burst modifier.

source§

impl Quota

Retrieving information about a quota

source

pub const fn replenish_interval(&self) -> Duration

The time it takes for a rate limiter with an exhausted burst budget to replenish a single element.

source

pub const fn burst_size(&self) -> NonZeroU32

The maximum number of cells that can be allowed in one burst.

source

pub const fn burst_size_replenished_in(&self) -> Duration

The time it takes to replenish the entire maximum burst size.

Trait Implementations§

source§

impl Clone for Quota

source§

fn clone(&self) -> Quota

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Quota

source§

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

Formats the value using the given formatter. Read more
source§

impl PartialEq for Quota

source§

fn eq(&self, other: &Quota) -> bool

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Copy for Quota

source§

impl Eq for Quota

source§

impl StructuralPartialEq for Quota

Auto Trait Implementations§

§

impl RefUnwindSafe for Quota

§

impl Send for Quota

§

impl Sync for Quota

§

impl Unpin for Quota

§

impl UnwindSafe for Quota

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V