Struct SlidingWindowLog 

pub struct SlidingWindowLog<C = SystemClock>
where
    C: Clock,
{ /* private fields */ }

Available on crate feature std only.

An exact sliding-window-log rate limiter: at most limit units in any trailing window of window.

Construct with new (or per_second), then use the non-blocking try_acquire / peek or the waiting acquire. Time comes from an injectable Clock.

Examples

use std::time::Duration;
use throttle_net::SlidingWindowLog;

// At most 5 requests in any 1-second window.
let limiter = SlidingWindowLog::new(5, Duration::from_secs(1));
for _ in 0..5 {
    assert!(limiter.try_acquire());
}
assert!(!limiter.try_acquire()); // the 6th in this window is refused

Implementations

impl SlidingWindowLog<SystemClock>

pub fn new(limit: u32, window: Duration) -> Self

Creates a limiter admitting at most limit units per trailing window.

A limit of 0 admits nothing; a zero window makes every grant expire immediately (so it behaves as a per-instant limit of limit).

Examples

use std::time::Duration;
use throttle_net::SlidingWindowLog;

let limiter = SlidingWindowLog::new(100, Duration::from_secs(60)); // 100/min
assert_eq!(limiter.capacity(), 100);

pub fn per_second(rate: u32) -> Self

Creates a limiter admitting at most rate units in any one-second window.

Examples

use throttle_net::SlidingWindowLog;

let limiter = SlidingWindowLog::per_second(50);
assert!(limiter.try_acquire());

impl<C> SlidingWindowLog<C>

where C: Clock + Clone,

pub fn with_clock<C2>(self, clock: C2) -> SlidingWindowLog<C2>

where C2: Clock + Clone,

Replaces the time source, for deterministic tests with a ManualClock. The log is reset.

Examples

use std::sync::Arc;
use std::time::Duration;
use clock_lib::ManualClock;
use throttle_net::SlidingWindowLog;

let clock = Arc::new(ManualClock::new());
let limiter = SlidingWindowLog::new(2, Duration::from_secs(1)).with_clock(clock.clone());

assert!(limiter.try_acquire());
assert!(limiter.try_acquire());
assert!(!limiter.try_acquire());
clock.advance(Duration::from_secs(1)); // the window slides past both grants
assert!(limiter.try_acquire());

pub fn try_acquire(&self) -> bool

Attempts to take one unit without waiting.

pub fn try_acquire_with_cost(&self, cost: u32) -> bool

Attempts to take cost units without waiting (all-or-nothing).

pub fn peek(&self, cost: u32) -> Decision

Reports whether cost units would be admitted now, without recording.

pub fn available(&self) -> u32

Units still admissible in the current window.

pub fn capacity(&self) -> u32

The window limit (the most units admissible at once).

impl<C> SlidingWindowLog<C>

where C: Clock + Clone,

pub async fn acquire(&self) -> Result<(), ThrottleError>

Available on crate feature runtime only.

Takes one unit, waiting until the window has room.

Errors

Returns ThrottleError::CostExceedsCapacity when the limit is zero.

pub async fn acquire_with_cost(&self, cost: u32) -> Result<(), ThrottleError>

Available on crate feature runtime only.

Takes cost units, waiting until the window has room.

Errors

Returns ThrottleError::CostExceedsCapacity when cost exceeds the limit, so it can never be admitted.

Trait Implementations

impl<C> Limiter for SlidingWindowLog<C>

where C: Clock + Clone + Send + Sync,

fn peek(&self, cost: u32) -> Decision

Reports whether cost tokens would be granted now, without taking them.

fn acquire_cost(&self, cost: u32) -> Decision

Attempts to take cost tokens now, deducting them on success.

fn available(&self) -> u32

Returns the number of whole tokens available right now.

fn capacity(&self) -> u32

Returns the most tokens this limiter can ever hold at once (its burst ceiling). A request whose cost exceeds this can never be granted.