Struct Eviction 

pub struct Eviction { /* private fields */ }

Available on crate feature std only.

How a PerKey limiter bounds the memory its per-key state can occupy.

A limiter that keeps state per key is a denial-of-service vector against itself if that state can grow without limit: a flood of unique keys would exhaust memory. Eviction is the defense, and two independent bounds compose:

• Capacity — a hard ceiling on live keys. Inserting a new key past the ceiling evicts the least-recently-seen one. This caps a unique-key flood.
• Idle TTL — keys not seen for longer than the TTL become evictable, so long-idle state is reclaimed rather than held forever.

Eviction is lazy and incremental: it runs while inserting a new key, touches only the one shard being written, and never sweeps the whole store or blocks the steady-state path. The capacity is enforced per shard, so the live-key count stays within a small factor of the cap.

The Default is safe: a DEFAULT_MAX_KEYS cap and no TTL — bounded out of the box. Opt into unbounded growth explicitly with unbounded, understanding the risk.

Examples

use std::time::Duration;
use throttle_net::Eviction;

// Cap at 100k keys and reclaim anything idle for five minutes.
let policy = Eviction::capacity(100_000).with_idle(Duration::from_secs(300));
assert_eq!(policy.max_keys(), Some(100_000));
assert_eq!(policy.idle_ttl(), Some(Duration::from_secs(300)));

Implementations

impl Eviction

pub const fn capacity(max_keys: usize) -> Self

A hard cap of max_keys live keys, with no idle expiry.

A max_keys of 0 is treated as 1 (the store always holds at least one key per shard).

Examples

use throttle_net::Eviction;

let policy = Eviction::capacity(50_000);
assert_eq!(policy.max_keys(), Some(50_000));
assert_eq!(policy.idle_ttl(), None);

pub const fn idle(ttl: Duration) -> Self

Reclaim keys idle for longer than ttl, keeping the default capacity cap.

Idle expiry alone does not bound a unique-key flood — flooded keys are not idle — so this keeps the DEFAULT_MAX_KEYS cap as the flood defense and layers the TTL on top. Use capacity plus with_idle to choose both bounds.

Examples

use std::time::Duration;
use throttle_net::{Eviction, DEFAULT_MAX_KEYS};

let policy = Eviction::idle(Duration::from_secs(300));
assert_eq!(policy.idle_ttl(), Some(Duration::from_secs(300)));
assert_eq!(policy.max_keys(), Some(DEFAULT_MAX_KEYS));

pub const fn new(max_keys: usize, ttl: Duration) -> Self

Both bounds at once: a max_keys cap and an idle ttl.

Examples

use std::time::Duration;
use throttle_net::Eviction;

let policy = Eviction::new(10_000, Duration::from_secs(60));
assert_eq!(policy.max_keys(), Some(10_000));
assert_eq!(policy.idle_ttl(), Some(Duration::from_secs(60)));

pub const fn unbounded() -> Self

No bounds at all — the store grows without limit.

Only safe when the key space is intrinsically bounded (a fixed set of tenants, say). Against untrusted keys this is a self-inflicted denial-of-service: prefer capacity.

Examples

use throttle_net::Eviction;

let policy = Eviction::unbounded();
assert_eq!(policy.max_keys(), None);

pub const fn with_capacity(self, max_keys: usize) -> Self

Returns a copy with the capacity cap set to max_keys.

Examples

use std::time::Duration;
use throttle_net::Eviction;

let policy = Eviction::idle(Duration::from_secs(30)).with_capacity(1_000);
assert_eq!(policy.max_keys(), Some(1_000));

pub const fn with_idle(self, ttl: Duration) -> Self

Returns a copy with idle expiry set to ttl.

Examples

use std::time::Duration;
use throttle_net::Eviction;

let policy = Eviction::capacity(1_000).with_idle(Duration::from_secs(30));
assert_eq!(policy.idle_ttl(), Some(Duration::from_secs(30)));

pub const fn without_capacity(self) -> Self

Returns a copy with the capacity cap removed (unbounded key count).

Examples

use throttle_net::Eviction;

let policy = Eviction::default().without_capacity();
assert_eq!(policy.max_keys(), None);

pub const fn max_keys(&self) -> Option<usize>

The configured capacity cap, if any.

pub const fn idle_ttl(&self) -> Option<Duration>

The configured idle TTL, if any.

Trait Implementations

impl Clone for Eviction

fn clone(&self) -> Eviction

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Eviction

impl Debug for Eviction

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

Formats the value using the given formatter.

impl Default for Eviction

fn default() -> Self

A DEFAULT_MAX_KEYS capacity cap and no idle TTL — bounded memory out of the box.

impl Eq for Eviction

impl PartialEq for Eviction

fn eq(&self, other: &Eviction) -> 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.

impl StructuralPartialEq for Eviction