Struct rl_core::Tracker

source · [−]

pub struct Tracker { /* private fields */ }

Expand description

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

source

impl Tracker

source

pub fn empty() -> Self

Create a tracker that starts empty at the current time.

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

source

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().

source

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().

source

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

Returns the tokens currently available.

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

source

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

Returns the tokens currently available at the specified time.

source

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()).

source

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.

source

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

Acquire up to count tokens from the rate limiter at the current time.

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

source

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

Acquire up to count tokens from the rate limiter.

Returns the number of tokens actually acquired. If greater than 0 tokens were requested and 0 tokens were available an error is returned instead. If acquiring 0 tokens is desired use .unwrap_or(0) to explicitly waive the error.

source

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()).

source

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.