Struct Clock 

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

A fixed-capacity key-value cache that evicts entries using the CLOCK (second-chance) replacement policy.

See the module documentation for the policy, allocation reuse, and concurrency details.

Implementations

impl<K: Hash + Eq + Clone, V> Clock<K, V>

pub fn new(capacity: NonZeroUsize) -> Self

Creates a cache that holds at most capacity entries.

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 set the entry’s reference bit, so it does not protect the entry from the next eviction sweep.

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

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

Recording use sets the entry’s reference bit so the next eviction sweep grants it a second chance. This takes &self so it can be called concurrently behind a shared lock.

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. If inserting a new entry exceeds the capacity, the CLOCK evictor reclaims a slot first.

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 an entry if the cache is full), 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), the returned reference is the reused slot’s stale value, which the caller is expected to overwrite. Only when the cache grows is make called to produce a fresh value. This lets callers holding pooled buffers overwrite in place rather than 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 index and slot vector.

impl<K: Hash + Eq + Clone + Default, V> Clock<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 allocation at construction so steady-state inserts never allocate. 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 Clock<K, V>

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

Formats the value using the given formatter.