Struct ExpiringLruCache 

pub struct ExpiringLruCache<K, V, S = DefaultHashBuilder> { /* 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.

cache_size / iter / evict contract: cache_size() returns the raw stored entry count and may include expired-but-not-yet-swept entries. iter() omits expired entries from the view but does not remove them. Call evict() (via CacheEvict) to physically remove expired entries and obtain an accurate live count.

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 new(max_size: usize) -> Self

Construct a ready-to-use ExpiringLruCache holding up to max_size entries.

For optional settings (on_evict) use builder.

Panics

Panics if max_size is 0, or if pre-allocating the backing store for max_size entries fails (e.g. usize::MAX). Use builder with build to handle those cases without panicking.

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

Return a builder for constructing an ExpiringLruCache.

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

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 set_max_size(&mut self, max_size: usize) -> Option<usize>

Change the maximum number of entries, returning the previous capacity; shrinking below the current entry count immediately evicts least-recently-used entries.

Eviction on shrink fires on_evict and counts evictions until the cache fits. Growing the capacity does not pre-allocate; the backing stores grow on demand as entries are inserted.

This is useful for sizing a #[cached(create = "{ ... }")] cache from a value loaded at startup (e.g. config), then adjusting it later as load changes.

Panics

Panics if max_size is 0. Use try_set_max_size to validate first and avoid the panic.

pub fn try_set_max_size( &mut self, max_size: usize, ) -> Result<Option<usize>, SetMaxSizeError>

Fallible counterpart of set_max_size: validates that max_size is non-zero and then delegates to set_max_size. Returns the previous capacity wrapped in Some on success.

Errors

Returns SetMaxSizeError::ZeroMaxSize if max_size is 0.

pub fn evict(&mut self) -> usize

Evict expired values from the cache.

pub fn retain<F: FnMut(&K, &V) -> bool>(&mut self, keep: F) -> usize

Retain only entries that are unexpired and satisfy keep.

Iterates the entries held in the underlying LRU store (most- to least-recently-used) and removes every entry that is already expired (per Expires::is_expired) or for which keep returns false — expired entries are removed without consulting keep. on_evict is called and the eviction counter incremented for each removed entry. The LRU recency order of the surviving entries is unchanged.

This matches LruTtlCache::retain; the plain LruCache::retain has no expiry dimension and removes solely on the predicate.

Returns the number of entries removed: the count folds together entries keep rejected and entries swept for having already expired, since expiry removal is unconditional regardless of what keep returns. retain is deliberately not #[must_use]: discarding the count is a legitimate and common use, matching existing bare cache.retain(...); call sites.

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. The eviction count does not depend on whether an on_evict callback is configured.

pub fn iter_order(&self) -> Vec<(K, CacheValue<V>)>

where K: Clone, V: Clone,

Return all live entries in current LRU order (most-recently-used first) as (K, CacheValue<V>) pairs. ExpiringLruCache carries no per-entry metadata beyond what V: Expires itself exposes, so the wrapper’s metadata type is (); the wrapper Derefs to V. Expired entries are excluded.

pub fn key_order(&self) -> Vec<K>

where K: Clone,

Return a Vec of keys in the current order from most to least recently used. Expired entries are excluded.

pub fn value_order(&self) -> Vec<CacheValue<V>>

where V: Clone,

Return a Vec of CacheValue-wrapped values in the current order from most to least recently used. Expired entries are excluded.

Trait Implementations

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

fn evict(&mut self) -> usize

Physically remove all expired entries from the cache and return the count removed.

impl<K: Hash + Eq + Clone, V: Expires, S: BuildHasher> CacheExpiry<K, V> for ExpiringLruCache<K, V, S>

fn cache_peek_expires_at<Q>(&self, k: &Q) -> (Option<V>, Option<Instant>)

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

Returns the stored value and its expiry instant, with no read side effects.

The instant is whatever Expires::expires_at reports for the value, and on this store that is advisory only: it is None unless the value type overrides expires_at (including for an entry that is expired), and it may be in the past for an entry Expires::is_expired reports as live. is_expired remains the authority on liveness here; use cache_peek_with_expiry_status for that. Uses the same lookup as that peek (the inner LruCache’s non-promoting cache_peek): no hit/miss counting, no LRU promotion, no removal of an expired entry.

fn cache_expires_at<Q>(&self, k: &Q) -> (bool, Option<Instant>)

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

Returns whether the key is present and its expiry instant, without the value.

The value-free counterpart of cache_peek_expires_at: same non-promoting lookup (the inner LruCache’s cache_peek), same advisory deadline, no clone and no V: Clone bound. (false, None) when the key is absent; (true, deadline) when it is present, where deadline is whatever Expires::expires_at reports for the stored value.

The presence flag is not advisory: the deadline is. On this store the deadline is None for any value type that does not override Expires::expires_at, including an entry that is expired – so (true, None) means “present, deadline unknown”, not “present and live”. is_expired, not this deadline, remains the authority on liveness; see the CacheExpiry trait docs’ Expires-store caveat. An expired entry is reported present and is not removed. No hit/miss counting, no LRU promotion.

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

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

Ergonomic alias for cache_peek_expires_at.

fn expires_at<Q>(&self, key: &Q) -> (bool, Option<Instant>)

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

Ergonomic alias for cache_expires_at.

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

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

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

Removes the entry and returns the value only if it is still live; an expired value is removed but reported as None. Use cache_remove_entry to receive the value regardless of expiry.

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

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

Removes the entry and returns it regardless of expiry (unlike cache_remove, which filters expired values).

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

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

Check whether the cache contains a live (non-expired) entry for k.

Delegates to CachedPeek::cache_peek, so it records no hit/miss metrics, performs no recency promotion, and reports absent/expired entries as false.

type Error = !

The error type returned by cache_try_set.

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_mut<F: FnOnce() -> V>(&mut self, k: K, f: F) -> &mut V

Get or insert a key-value pair, returning a mutable reference to the value.

fn cache_try_get_or_set_with_mut<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 and returning a mutable reference to the value.

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

Insert a key-value pair and return the previous value. On recency-ordered stores, overwriting an existing key promotes it to most-recently-used.

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>, Self::Error>

Fallible variant of Self::cache_set for custom stores whose insertion can fail. The default implementation is infallible and delegates to Self::cache_set; it always returns Ok. Every built-in in-memory store keeps that default (type Error = std::convert::Infallible).

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

Get or insert a key-value pair, returning a shared reference to the value.

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

Get or insert a key-value pair, propagating errors from the factory and returning a shared reference to the value.

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.

impl<K, V, S> CachedGetOrSetAsync<K, V> for ExpiringLruCache<K, V, S>

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

Available on crate feature async_core only.

fn async_cache_get_or_set_with_mut<'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,

The mutable counterpart of async_cache_get_or_set_with: returns &mut V. Stores implement this method; the shared-reference variant delegates to it.

fn async_cache_try_get_or_set_with_mut<'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,

The mutable counterpart of async_cache_try_get_or_set_with: returns Result<&mut V, E>.

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

where Self: Send, K: Send + '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_cache_try_get_or_set_with<'a, F, Fut, E>( &'a mut self, k: K, f: F, ) -> impl Future<Output = Result<&'a V, E>> + Send + 'a

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

Like async_cache_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.

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

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, S: BuildHasher> CachedPeek<K, V> for ExpiringLruCache<K, V, S>

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.

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

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

Ergonomic alias for cache_peek.

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

where K: Clone + Hash + Eq, V: Clone, S: 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, S: BuildHasher> CloneCached<K, V> for ExpiringLruCache<K, V, S>

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

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

Peek at the entry (including expired entries) without any read side effects.

Returns (Some(v), true) for an expired entry, (Some(v), false) for a live entry, and (None, false) when the key is absent. Does not update hit/miss counters and does not promote in LRU order.

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, V: Clone,

Ergonomic alias for cache_get_with_expiry_status.

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

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

Ergonomic alias for cache_peek_with_expiry_status.

impl<K, V, S> Debug for ExpiringLruCache<K, V, S>

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

Formats the value using the given formatter.

impl<K, V, S> Eq for ExpiringLruCache<K, V, S>

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

impl<K, V, S> PartialEq for ExpiringLruCache<K, V, S>

where K: Clone + Hash + Eq, V: PartialEq, S: BuildHasher,

Two ExpiringLruCache values are equal when their stored entries are equal (same keys, same values). Equality is membership-based: LRU recency order is not compared. Metrics (hits, misses, evictions) and the on_evict callback are not part of the comparison.

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.