Struct TtlCache 

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

Thread-safe TTL cache with stale-while-revalidate semantics.

This cache supports:

• Automatic expiration based on TTL
• Serving stale data when fresh data is unavailable
• Thread-safe access via RwLock

Example

use std::time::Duration;
use seer_core::cache::TtlCache;

let cache: TtlCache<String, String> = TtlCache::new(Duration::from_secs(3600));

// Insert a value
cache.insert("key".to_string(), "value".to_string());

// Get the value (returns None if expired)
if let Some(value) = cache.get(&"key".to_string()) {
    println!("Got: {}", value);
}

Implementations

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

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

pub fn new(default_ttl: Duration) -> Self

Creates a new cache with the specified default TTL and default max capacity (1024).

pub fn with_max_capacity(default_ttl: Duration, max_capacity: usize) -> Self

Creates a new cache with a specified TTL and max capacity.

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

Gets a value from the cache if it exists and is not expired.

Returns None if the key doesn’t exist, the entry has expired, or the lock is poisoned (with a warning logged).

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

Gets a value from the cache even if it’s expired.

This is useful for stale-while-revalidate patterns where you want to serve stale data while attempting to refresh.

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

Checks if a key exists and needs refresh (is stale but not expired).

Returns true if the entry exists and is past 75% of its TTL.

pub fn insert(&self, key: K, value: V)

Inserts a value into the cache with the default TTL.

pub fn insert_with_ttl(&self, key: K, value: V, ttl: Duration)

Inserts a value into the cache with a custom TTL.

If the cache exceeds max capacity, expired entries are purged first. If still over capacity, the oldest entry is evicted.

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

Removes a value from the cache.

pub fn cleanup(&self)

Removes all expired entries from the cache.

This is useful for periodic cleanup to prevent unbounded memory growth.

pub fn len(&self) -> usize

Returns the number of entries in the cache (including expired ones).

pub fn is_empty(&self) -> bool

Returns true if the cache is empty.

pub fn clear(&self)

Clears all entries from the cache.