Struct Cache 

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

A fixed-capacity key-value cache using Clock2Q+ replacement.

Keys must keep the same Hash and Eq identity throughout each cache operation, including value factories and other callbacks, and while resident or retained in Ghost history. Violating this requirement is a logic error and may cause incorrect lookups or admission decisions.

Implementations

impl<K: Hash + Eq, V> Cache<K, V>

pub fn new(capacity: NonZeroUsize) -> Self

Creates an empty cache with room for capacity residents.

pub const fn capacity(&self) -> usize

Returns the maximum number of entries the cache can hold.

pub fn len(&self) -> usize

Returns the number of entries currently in the cache.

pub fn is_empty(&self) -> bool

Returns true if the cache holds no entries.

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

Returns true if key is in the cache without recording use.

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

Returns a reference to the value for key without recording use.

Unlike Self::get, this does not affect replacement decisions.

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

Returns a reference to the value for key, recording use.

This takes &self so it can be called concurrently behind a shared lock. Hits update only relaxed atomic replacement metadata.

pub fn get_at(&self, slot: usize, key: &K) -> Option<&V>

Returns a reference to the value in slot if that slot currently holds key as a live entry, recording use.

This is the read half of an external slot index: callers that recorded a key’s slot (via Self::get_or_insert_mut) can resolve it with a key compare instead of a hash lookup. Any stale index entry reads as a miss rather than a wrong value: a slot reused for another key fails the key compare, a slot freed by Self::remove or Self::retain is not live, and an out-of-range slot does not exist. External indexes therefore need no maintenance beyond tolerating misses.

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

Returns a mutable reference to the value for key, recording use.

pub fn put(&mut self, key: K, value: V) -> Option<V>

Inserts value for key.

If key was already present, replaces and returns the previous value, recording use. Otherwise claims vacant capacity or selects a resident to evict.

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

Returns the value for key, computing and inserting it with f on a miss.

On a hit, f is not called. On a miss, f is called, its result is inserted (evicting a resident if necessary), and a reference to the stored value is returned.

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

Returns the value for key, computing and inserting it with a fallible f on a miss.

On a hit, f is not called. On a miss, f is called; if it returns an error the error is propagated and nothing is inserted, so failures are not cached.

pub fn get_or_insert_mut<F: FnOnce() -> V>( &mut self, key: K, make: F, ) -> (usize, &mut V)

Returns the slot index and a mutable reference to the slot for key, reusing an existing allocation where possible.

On a hit, records use and returns the current value. On a miss into a reused slot (a freed slot or an eviction victim), returns the reused slot’s stale value for the caller to overwrite. Only when the cache grows is make called to produce a fresh value. This lets callers whose values are buffers overwrite them in place without allocating on every insert.

The slot index identifies the entry until it is evicted or removed, so callers can record it in an external index and resolve later reads with Self::get_at instead of a hash lookup.

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

Removes key, returning whether it was present.

The slot and its allocation are retained for reuse, so the value is not returned.

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

Retains only the entries for which keep returns true.

Dropped entries’ slots and allocations are retained for reuse.

pub fn clear(&mut self)

Removes all entries, dropping their values and retaining the allocated capacity of the indexes and slot vectors.

impl<K: Hash + Eq + Default, V> Cache<K, V>

pub fn prefill<F: FnMut() -> V>(&mut self, make: F)

Pre-allocates all slots up to capacity, each holding a value from make, and leaves them free for reuse.

After this call, the first capacity inserts reuse a pre-allocated slot instead of growing, so make (and any allocation it performs) runs only here. Use this to front-load value allocation at construction so steady-state inserts never allocate values. Free slots are seeded with the default key as a throwaway placeholder that is overwritten when the slot is first filled.

Trait Implementations

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

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

Formats the value using the given formatter.