Struct TtlCache 

pub struct TtlCache<K, V> { /* private fields */ }

Available on crate feature std only.

A bounded, thread-safe cache with per-entry time-to-live.

Each entry is stamped with a deadline at insert time. On every access (get, contains_key, len), expired entries are removed lazily. On overflow, the entry with the soonest expiration is evicted — already-expired entries are naturally preferred over live ones.

Both insert and insert_with_ttl reset the deadline on the affected entry — writes always re-arm the timer.

Implementation

Sharded into up to 16 independent stores keyed by hash of K. Each shard owns its own HashMap and applies expiry / overflow eviction locally. Tiny caches (< 32 entries) use a single shard.

Eviction is per-shard approximate — overflow inside one shard evicts the soonest-expiring entry within that shard, not necessarily the soonest-expiring entry globally. Lazy expiry remains exact within the operating shard.

Example

use std::time::Duration;
use cache_mod::{Cache, TtlCache};

let cache: TtlCache<&'static str, u32> =
    TtlCache::new(4, Duration::from_secs(60)).expect("capacity > 0");

cache.insert("session", 42);
assert_eq!(cache.get(&"session"), Some(42));

Implementations

impl<K, V> TtlCache<K, V>

where K: Eq + Hash + Clone, V: Clone,

pub fn new(capacity: usize, ttl: Duration) -> Result<Self, CacheError>

Creates a cache with the given capacity and default time-to-live.

ttl is applied to every insert that does not specify its own. Returns CacheError::InvalidCapacity if capacity == 0.

Example

use std::time::Duration;
use cache_mod::TtlCache;

let cache: TtlCache<String, u32> =
    TtlCache::new(128, Duration::from_secs(300)).expect("capacity > 0");

pub fn with_capacity(capacity: NonZeroUsize, ttl: Duration) -> Self

Creates a cache with the given non-zero capacity and default TTL. Infallible.

Example

use std::num::NonZeroUsize;
use std::time::Duration;
use cache_mod::TtlCache;

let cap = NonZeroUsize::new(64).expect("64 != 0");
let cache: TtlCache<String, u32> =
    TtlCache::with_capacity(cap, Duration::from_secs(60));

pub fn insert_with_ttl(&self, key: K, value: V, ttl: Duration) -> Option<V>

Inserts value under key with a per-call TTL that overrides the cache default. The deadline is now + ttl.

Returns the previously-stored live value if key was already present and not yet expired. An expired-but-not-yet-cleaned entry is treated as absent: the call returns None and replaces it.

Example

use std::time::Duration;
use cache_mod::{Cache, TtlCache};

let cache: TtlCache<u32, u32> =
    TtlCache::new(4, Duration::from_secs(60)).expect("capacity > 0");

cache.insert_with_ttl(1, 10, Duration::from_secs(5));
assert_eq!(cache.get(&1), Some(10));

Trait Implementations

impl<K, V> Cache<K, V> for TtlCache<K, V>

where K: Eq + Hash + Clone, V: Clone,

fn get(&self, key: &K) -> Option<V>

Returns the value associated with key, if any, and counts as an access for the purposes of the eviction policy.

fn insert(&self, key: K, value: V) -> Option<V>

Inserts value under key. Returns the previously-stored value if key was already present.

fn remove(&self, key: &K) -> Option<V>

Removes the entry for key and returns the value if present.

fn contains_key(&self, key: &K) -> bool

Returns true if the cache currently holds an entry for key.

fn len(&self) -> usize

Number of entries currently stored.

fn clear(&self)

Removes every entry. Capacity is preserved.

fn capacity(&self) -> usize

Configured capacity bound.

fn is_empty(&self) -> bool

Returns true when the cache holds no entries.