Struct LruCache 

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

Available on crate feature std only.

A bounded, thread-safe LRU cache.

On insert overflow the least-recently-accessed entry is evicted. Both get and insert count as accesses and promote the affected entry to most-recently-used.

Implementation

Sharded into up to 16 independent arenas keyed by hash of K. Each shard owns its own doubly-linked list, free-list, and HashMap, with its own Mutex<Inner>. Contention on the lock is bounded by the number of threads routing into the same shard, not by total cache traffic.

Eviction is approximate. Once the cache uses more than one shard, insert overflow evicts the local-to-shard least-recently-used entry, not the global one. Caches with fewer than 32 entries automatically use a single shard and retain strict global LRU ordering — this keeps small caches and test fixtures deterministic.

Example

use cache_mod::{Cache, LruCache};

let cache: LruCache<u32, &'static str> = LruCache::new(2).expect("capacity > 0");

cache.insert(1, "one");
cache.insert(2, "two");
assert_eq!(cache.get(&1), Some("one")); // 1 is now MRU, 2 is LRU

cache.insert(3, "three"); // evicts 2 (single shard at this size)
assert_eq!(cache.get(&2), None);
assert_eq!(cache.get(&1), Some("one"));
assert_eq!(cache.get(&3), Some("three"));

Implementations

impl<K, V> LruCache<K, V>

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

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

Creates a cache with the given capacity.

Returns CacheError::InvalidCapacity if capacity == 0.

Example

use cache_mod::LruCache;

let cache: LruCache<String, u32> = LruCache::new(128).expect("capacity > 0");

pub fn with_capacity(capacity: NonZeroUsize) -> Self

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

Example

use std::num::NonZeroUsize;
use cache_mod::LruCache;

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

Trait Implementations

impl<K, V> Cache<K, V> for LruCache<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.