Struct rl_core::Tracker

pub struct Tracker { /* fields omitted */ }

State for a single rate limit.

This tracks the state of a single rate limit. For example the rate limit for a particular IP.

This object is intentionally small and cheap so that it can be created for fine-grained tracking.

The std::default::Default implementation creates a “full” tracker. See Tracker::full().

Implementations

impl Tracker

pub fn empty() -> Self

Create a tracker that starts empty at the current time.

Equivalent to Tracker::new_at(std::time::SystemTime::now()).

pub fn full() -> Self

Create a tracker that is full.

This creates a tracker that has it’s full burst capacity available.

Equivalent to std::default::Default::default().

pub fn new_at(now: SystemTime) -> Self

Create a tracker that starts at the provided time.

This means that the bucket will be empty at the indicated time and will fill starting from there. Note that this is not what you want for an limit that hasn’t been used for a while and cleaned from the DB. For that case you want Tracker::default().

pub fn capacity(&self, config: &Config) -> u32

Returns the tokens currently available.

Equivalent to Tracker::capacity_at(std::time::SystemTime::now()).

pub fn capacity_at(&self, config: &Config, now: SystemTime) -> u32

Returns the tokens currently available at the specified time.

pub fn acquire(&mut self, config: &Config, count: u32) -> Result<(), Denied>

Attempt to acquire count tokens from the rate limiter at the current time

Equivalent to Tracker::acquire_at(config, count, std::time::SystemTime::now()).

pub fn acquire_at(
    &mut self,
    config: &Config,
    count: u32,
    now: SystemTime
) -> Result<(), Denied>

Attempt to acquire count tokens from the rate limiter.

If the requested number of tokens are available the state is updated and Ok(()) is returned. Otherwise an error describing the issue is returned.

Warning: To save memory a Tracker does not remember its Config. This means that you can switch the config argument between calls on the same Tracker. This is not recommended as it is not immediately obvious what the result will be but is completely supported. The only guarantee provided is that the new rate limit will take effect. If the Config is switched between calls the new rate limit will take effect immediately however the logical state of the Tracker may be surprising. For example a large “burst” config may be immediately filled or a new low “rate” may result in a previous “burst” capacity disappearing.

pub fn simplify(&mut self, config: &Config) -> bool

Attempts to minimize the state at the current time.

Equivalent to Tracker::simplify_at(config, std::time::SystemTime::now()).

pub fn simplify_at(&mut self, config: &Config, now: SystemTime) -> bool

Attempts to minimize the state.

If a rate limit hasn’t been used in a long time the bucket will be full and the state can be simplified.

Returns true if the state is “simple” and equivalent to Tracker::default(). If this occurs you don’t need to store the state and can use the default state if needed again.

Trait Implementations

impl Clone for Tracker

fn clone(&self) -> Tracker

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Tracker

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

Formats the value using the given formatter.

impl Default for Tracker

fn default() -> Tracker

Returns the “default value” for a type.