Struct RateLimiter

pub struct RateLimiter { /* private fields */ }

Rate Limiter that works on both bandwidth and ops/s limiting.

Bandwidth (bytes/s) and ops/s limiting can be used at the same time or individually.

Implementation uses a single timer through TimerFd to refresh either or both token buckets.

Its internal buckets are ‘passively’ replenished as they’re being used (as part of consume() operations). A timer is enabled and used to ‘actively’ replenish the token buckets when limiting is in effect and consume() operations are disabled.

RateLimiters will generate events on the FDs provided by their AsRawFd trait implementation. These events are meant to be consumed by the user of this struct. On each such event, the user must call the event_handler() method.

Implementations

impl RateLimiter

pub fn make_bucket( total_capacity: u64, one_time_burst: u64, complete_refill_time_ms: u64, ) -> Option<TokenBucket>

This function creates a TokenBucket wrapped in an Option with a given total capacity, one time burst, and complete refill time (in miliseconds). If the total capacity or the complete refill time are zero, then None is returned.

pub fn new( bytes_total_capacity: u64, bytes_one_time_burst: u64, bytes_complete_refill_time_ms: u64, ops_total_capacity: u64, ops_one_time_burst: u64, ops_complete_refill_time_ms: u64, ) -> Result<Self>

Creates a new Rate Limiter that can limit on both bytes/s and ops/s.

Arguments

• bytes_total_capacity - the total capacity of the TokenType::Bytes token bucket.
• bytes_one_time_burst - initial extra credit on top of bytes_total_capacity, that does not replenish and which can be used for an initial burst of data.
• bytes_complete_refill_time_ms - number of milliseconds for the TokenType::Bytes token bucket to go from zero Bytes to bytes_total_capacity Bytes.
• ops_total_capacity - the total capacity of the TokenType::Ops token bucket.
• ops_one_time_burst - initial extra credit on top of ops_total_capacity, that does not replenish and which can be used for an initial burst of data.
• ops_complete_refill_time_ms - number of milliseconds for the TokenType::Ops token bucket to go from zero Ops to ops_total_capacity Ops.

If either bytes/ops size or refill_time are zero, the limiter is disabled for that respective token type.

Errors

If the timerfd creation fails, an error is returned.

pub fn consume(&mut self, tokens: u64, token_type: TokenType) -> bool

Attempts to consume tokens and returns whether that is possible.

If rate limiting is disabled on provided token_type, this function will always succeed.

pub fn manual_replenish(&mut self, tokens: u64, token_type: TokenType)

Adds tokens of token_type to their respective bucket.

Can be used to manually add tokens to a bucket. Useful for reverting a consume() if needed.

pub fn is_blocked(&self) -> bool

Returns whether this rate limiter is blocked.

The limiter ‘blocks’ when a consume() operation fails because there was not enough budget for it. An event will be generated on the exported FD when the limiter ‘unblocks’.

pub fn event_handler(&mut self) -> Result<(), Error>

This function needs to be called every time there is an event on the FD provided by this object’s AsRawFd trait implementation.

Errors

If the rate limiter is disabled or is not blocked, an error is returned.

pub fn update_buckets(&mut self, bytes: BucketUpdate, ops: BucketUpdate)

Updates the parameters of the token buckets associated with this RateLimiter.

pub fn bandwidth(&self) -> Option<&TokenBucket>

Returns an immutable view of the inner bandwidth token bucket.

pub fn ops(&self) -> Option<&TokenBucket>

Returns an immutable view of the inner ops token bucket.

Trait Implementations

impl AsRawFd for RateLimiter

fn as_raw_fd(&self) -> RawFd

Provides a FD which needs to be monitored for POLLIN events.

This object’s event_handler() method must be called on such events.

Will return a negative value if rate limiting is disabled on both token types.

impl Debug for RateLimiter

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

Formats the value using the given formatter.

impl Default for RateLimiter

fn default() -> Self

Default RateLimiter is a no-op limiter with infinite budget.

impl PartialEq for RateLimiter

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.