Struct ExpiringLruCache 

pub struct ExpiringLruCache<K: Hash + Eq, V: Expires> { /* private fields */ }

LRU-bounded cache with per-value expiry.

Stores values that implement the Expires trait so that expiration is determined by the values themselves. This is useful for caching values which themselves contain an expiry timestamp.

For an unbounded variant (no size cap), see ExpiringCache. When using the #[cached] proc macro, expires = true selects this store when max_size is also specified; without max_size, it selects the unbounded ExpiringCache.

Note: This cache is in-memory only.

Note: once specialization is stable (#[feature(specialization)]), the expiry-checking behavior here could be folded into LruCache via a specialized Cached<K, V> impl for V: Expires, eliminating this separate type. Until then, the two must remain distinct because overlapping blanket impls are not allowed on stable Rust.

Implementations

impl<K: Clone + Hash + Eq, V: Expires> ExpiringLruCache<K, V>

pub fn builder() -> ExpiringLruCacheBuilder<K, V>

Return a builder for constructing an ExpiringLruCache.

pub fn capacity(&self) -> usize

Returns the maximum number of entries this cache will hold before evicting.

This is the bound set via ExpiringLruCacheBuilder::max_size, not the current number of entries — use cache_size for that.

pub fn store(&self) -> &LruCache<K, V>

Returns a reference to the inner LruCache.

pub fn evict(&mut self) -> usize

Evict expired values from the cache.

pub fn cache_clear_with_on_evict(&mut self)

Remove all entries and fire the on_evict callback for each one, incrementing the evictions counter.

Unlike cache_clear (which removes entries silently), this method invokes on_evict for every removed entry (whether or not they had expired) and increments evictions. If no on_evict callback was configured, it falls back to the plain cache_clear.

Trait Implementations

impl<K: Hash + Eq + Clone, V: Expires> CacheEvict for ExpiringLruCache<K, V>

fn evict(&mut self) -> usize

Remove all expired entries from the cache, returning the number removed.

impl<K: Hash + Eq + Clone, V: Expires> Cached<K, V> for ExpiringLruCache<K, V>

fn cache_get<Q>(&mut self, k: &Q) -> Option<&V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Attempt to retrieve a cached value.

fn cache_get_mut<Q>(&mut self, key: &Q) -> Option<&mut V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Attempt to retrieve a cached value with mutable access.

fn cache_get_or_set_with<F: FnOnce() -> V>(&mut self, k: K, f: F) -> &mut V

Get or insert a key-value pair.

fn cache_try_get_or_set_with<F: FnOnce() -> Result<V, E>, E>( &mut self, key: K, f: F, ) -> Result<&mut V, E>

Get or insert a key-value pair, propagating errors from the factory.

fn cache_set(&mut self, k: K, v: V) -> Option<V>

Insert a key-value pair and return the previous value.

fn cache_remove<Q>(&mut self, k: &Q) -> Option<V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Remove a cached value, returning it if it was both present and still live.

fn cache_remove_entry<Q>(&mut self, k: &Q) -> Option<(K, V)>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Remove a cached entry, returning the stored key and value whenever an entry was physically deleted — including entries that were present but already expired.

fn cache_clear(&mut self)

Remove all cached entries but preserve capacity allocation and metrics. To also reset metrics, call cache_reset_metrics afterward, or use cache_reset to do both at once.

fn cache_reset(&mut self)

Reset all entries and metrics (hits, misses, evictions) to zero. Store configuration — capacity, TTL, and on_evict callbacks — is preserved. To reset entries without resetting metrics, use cache_clear.

fn cache_size(&self) -> usize

Return the number of entries currently in the cache.

fn cache_capacity(&self) -> Option<usize>

Return the cache capacity, if bounded.

fn cache_hits(&self) -> Option<u64>

Return the number of times a cached value was successfully retrieved.

fn cache_misses(&self) -> Option<u64>

Return the number of times a cached value was not found.

fn cache_evictions(&self) -> Option<u64>

Return the number of times a value was evicted from the cache.

fn cache_reset_metrics(&mut self)

Reset hit/miss counters.

fn cache_try_set(&mut self, k: K, v: V) -> Result<Option<V>, Box<dyn Error>>

Fallible variant of Self::cache_set. Returns Err if the store cannot accept the entry (e.g. the TTL duration overflows Instant bounds). The default implementation is infallible and delegates to Self::cache_set.

fn get<Q>(&mut self, k: &Q) -> Option<&V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Retrieve a cached value. Delegates to cache_get.

fn get_mut<Q>(&mut self, k: &Q) -> Option<&mut V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Retrieve a cached value with mutable access. Delegates to cache_get_mut.

fn set(&mut self, k: K, v: V) -> Option<V>

Insert a key-value pair and return the previous value. Delegates to cache_set.

fn try_set(&mut self, k: K, v: V) -> Result<Option<V>, Box<dyn Error>>

Fallible insert. Delegates to cache_try_set.

fn get_or_set_with<F: FnOnce() -> V>(&mut self, key: K, f: F) -> &mut V

Get or insert a key-value pair. Delegates to cache_get_or_set_with.

fn try_get_or_set_with<F: FnOnce() -> Result<V, E>, E>( &mut self, k: K, f: F, ) -> Result<&mut V, E>

Get or insert a key-value pair with error handling. Delegates to cache_try_get_or_set_with.

fn remove<Q>(&mut self, k: &Q) -> Option<V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Remove a cached value. Delegates to cache_remove.

fn remove_entry<Q>(&mut self, k: &Q) -> Option<(K, V)>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Remove a cached entry, returning the stored key and value. Delegates to cache_remove_entry.

fn cache_delete<Q>(&mut self, k: &Q) -> bool

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Delete a cached entry without returning it. Returns true if an entry was physically deleted (including expired entries), false if the key was absent.

fn delete<Q>(&mut self, k: &Q) -> bool

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Delete a cached entry without returning it. Returns true if an entry was physically deleted (including expired entries). Delegates to cache_delete.

fn contains<Q>(&mut self, k: &Q) -> bool

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Return true if the cache contains a value for the given key.

fn clear(&mut self)

Remove all entries, keeping allocated memory for reuse. Delegates to cache_clear.

fn len(&self) -> usize

Return the number of entries currently in the cache. Delegates to cache_size.

fn is_empty(&self) -> bool

Return true if the cache contains no entries.

fn hits(&self) -> Option<u64>

Return the number of cache hits, if tracked.

fn misses(&self) -> Option<u64>

Return the number of cache misses, if tracked.

fn metrics(&self) -> CacheMetrics

Return a snapshot of cache metrics.

impl<K, V> CachedAsync<K, V> for ExpiringLruCache<K, V>

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

Available on crate feature async_core only.

fn async_get_or_set_with<'a, F, Fut>( &'a mut self, k: K, f: F, ) -> impl Future<Output = &'a mut V> + Send + 'a

where K: 'a, V: Send + 'a, F: FnOnce() -> Fut + Send + 'a, Fut: Future<Output = V> + Send + 'a,

Get the value for k, or compute and insert it by awaiting f on a miss.

fn async_try_get_or_set_with<'a, F, Fut, E>( &'a mut self, k: K, f: F, ) -> impl Future<Output = Result<&'a mut V, E>> + Send + 'a

where K: 'a, V: Send + 'a, E: 'a, F: FnOnce() -> Fut + Send + 'a, Fut: Future<Output = Result<V, E>> + Send + 'a,

Like async_get_or_set_with, but f is fallible: on a miss the value is cached only if f resolves to Ok, and an Err is returned without caching.

fn get_async<'a, Q>( &'a mut self, k: &'a Q, ) -> impl Future<Output = Option<&'a V>> + Send + 'a

where Self: Cached<K, V> + Send, K: Borrow<Q> + 'a, Q: Hash + Eq + ?Sized + Sync, V: 'a,

Retrieve a cached value asynchronously.

fn set_async(&mut self, k: K, v: V) -> impl Future<Output = Option<V>> + Send

where Self: Cached<K, V> + Send, K: Send, V: Send,

Insert a key-value pair asynchronously.

fn remove_async<'a, Q>( &'a mut self, k: &'a Q, ) -> impl Future<Output = Option<V>> + Send + 'a

where Self: Cached<K, V> + Send, K: Borrow<Q> + 'a, Q: Hash + Eq + ?Sized + Sync, V: 'a,

Remove a cached value asynchronously.

fn clear_async(&mut self) -> impl Future<Output = ()> + Send

where Self: Cached<K, V> + Send,

Remove all entries asynchronously.

impl<K: Hash + Eq + Clone, V: Expires> CachedIter<K, V> for ExpiringLruCache<K, V>

fn iter<'a>(&'a self) -> impl Iterator<Item = (&'a K, &'a V)> + 'a

where K: 'a, V: 'a,

Return an iterator over the key-value pairs in the cache.

fn keys<'a>(&'a self) -> impl Iterator<Item = &'a K> + 'a

where Self: Sized, K: 'a, V: 'a,

Return an iterator over the keys in the cache.

fn values<'a>(&'a self) -> impl Iterator<Item = &'a V> + 'a

where Self: Sized, K: 'a, V: 'a,

Return an iterator over the values in the cache.

impl<K: Hash + Eq + Clone, V: Expires> CachedPeek<K, V> for ExpiringLruCache<K, V>

fn cache_peek<Q>(&self, key: &Q) -> Option<&V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Attempt to retrieve a cached value without mutating the cache.

impl<K, V> Clone for ExpiringLruCache<K, V>

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

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<K: Hash + Eq + Clone, V: Expires + Clone> CloneCached<K, V> for ExpiringLruCache<K, V>

fn cache_get_with_expiry_status<Q>(&mut self, k: &Q) -> (Option<V>, bool)

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Look up a cached value and report whether the found entry is expired.

fn get_with_expiry_status<Q>(&mut self, key: &Q) -> (Option<V>, bool)

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Ergonomic alias for cache_get_with_expiry_status.

impl<K: Hash + Eq, V: Expires> Debug for ExpiringLruCache<K, V>

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

Formats the value using the given formatter.