Trait Algorithm

Source
pub trait Algorithm<P: Reference = <DefaultClock as Clock>::Instant>:
    Send
    + Sync
    + Sized
    + Debug {
    type BucketState: RateLimitState<Self, P>;
    type NegativeDecision: PartialEq + Display + Debug + Send + Sync;

    // Required methods
    fn construct(
        capacity: NonZeroU32,
        cell_weight: NonZeroU32,
        per_time_unit: Duration,
    ) -> Result<Self, InconsistentCapacity>;
    fn test_n_and_update(
        &self,
        state: &Self::BucketState,
        n: u32,
        at: P,
    ) -> Result<(), NegativeMultiDecision<Self::NegativeDecision>>;

    // Provided method
    fn test_and_update(
        &self,
        state: &Self::BucketState,
        at: P,
    ) -> Result<(), Self::NegativeDecision> { ... }
}
Expand description

The trait that implementations of metered rate-limiter algorithms have to implement.

Implementing structures are expected to represent the “parameters” (e.g., the allowed requests/s), and keep the information necessary to make a decision, e.g. concrete usage statistics for an in-memory rate limiter, in the associated structure BucketState.

Required Associated Types§

Source

type BucketState: RateLimitState<Self, P>

The state of a single rate limiting bucket.

Every new rate limiting state is initialized as Default. The states must be safe to share across threads (this crate uses a parking_lot Mutex to allow that).

Source

type NegativeDecision: PartialEq + Display + Debug + Send + Sync

The type returned when a rate limiting decision for a single cell is negative. Each rate limiting algorithm can decide to return the type that suits it best, but most algorithms’ decisions also implement NonConformance, to ease handling of how long to wait.

Required Methods§

Source

fn construct( capacity: NonZeroU32, cell_weight: NonZeroU32, per_time_unit: Duration, ) -> Result<Self, InconsistentCapacity>

Constructs a rate limiter with the given parameters: capacity is the number of cells to allow, weighing cell_weight, every per_time_unit.

Source

fn test_n_and_update( &self, state: &Self::BucketState, n: u32, at: P, ) -> Result<(), NegativeMultiDecision<Self::NegativeDecision>>

Tests if n cells can be accommodated in the rate limiter at the instant at and updates the rate-limiter state to account for the weight of the cells and updates the ratelimiter state.

The update is all or nothing: Unless all n cells can be accommodated, the state of the rate limiter will not be updated.

Provided Methods§

Source

fn test_and_update( &self, state: &Self::BucketState, at: P, ) -> Result<(), Self::NegativeDecision>

Tests if a single cell can be accommodated in the rate limiter at the instant at and updates the rate-limiter state to account for the weight of the cell.

This method is provided by default, using the n test&update method.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§