Trait Cache

Source

pub trait Cache<K, V>where
    K: Eq + Hash,
    V: Clone,{
    // Required methods
    fn get(&self, key: &K) -> Option<V>;
    fn insert(&self, key: K, value: V) -> Option<V>;
    fn remove(&self, key: &K) -> Option<V>;
    fn contains_key(&self, key: &K) -> bool;
    fn len(&self) -> usize;
    fn clear(&self);
    fn capacity(&self) -> usize;

    // Provided method
    fn is_empty(&self) -> bool { ... }
}

Expand description

The common read / write / evict contract every cache type in this crate implements.

All methods take &self (not &mut self) so a cache instance can be shared across threads and across .await points without external locking. Implementations use interior mutability.

§Access semantics

get is an access: it may update the eviction order (e.g. promoting the entry to most-recently-used).
contains_key is a query only: it must not update the eviction order.
insert is an access on the inserted key.
remove is destructive and does not update order.

§Example

use cache_mod::{Cache, LruCache};

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

assert_eq!(cache.insert("a", 1), None);
assert_eq!(cache.get(&"a"), Some(1));
assert!(cache.contains_key(&"a"));
assert_eq!(cache.len(), 1);

assert_eq!(cache.remove(&"a"), Some(1));
assert!(cache.is_empty());

Required Methods§

Source

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.

Source

fn insert(&self, key: K, value: V) -> Option<V>

Inserts value under key. Returns the previously-stored value if key was already present.

May evict one or more existing entries to make room, according to the cache’s eviction policy. For TinyLfuCache the value may also be silently rejected by the admission filter — in that case the return value is None and the cache is unchanged.

The return value carries useful information (new-vs-replace, or admit-vs-reject for TinyLfuCache). If you genuinely don’t need it, bind to _ explicitly.

Source

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

Removes the entry for key and returns the value if present.

Source

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

Returns true if the cache currently holds an entry for key.

Unlike get, this method does not count as an access — eviction order is left unchanged. For TtlCache an expired-but-not-yet-cleaned entry is removed during the check and the method returns false.

Source

fn len(&self) -> usize

Number of entries currently stored.

For sharded caches (capacity ≥ 32), this is computed by summing each shard’s length while briefly locking each in turn — it is not an atomic snapshot of all shards simultaneously. In practice this matters only for code that races a len() against concurrent writers and expects a single instantaneous value.

Source

fn clear(&self)

Removes every entry. Capacity is preserved.

For caches with auxiliary state — LfuCache’s priority index, TinyLfuCache’s Count-Min Sketch, the monotonic clocks used by LfuCache and TinyLfuCache — that state is reset alongside the entries themselves. Configured capacity / max_weight is the only piece of state that survives.

Source

fn capacity(&self) -> usize

Configured capacity bound.

The unit depends on the implementation:

LruCache, LfuCache, TtlCache, TinyLfuCache — maximum number of entries.
SizedCache — maximum total byte-weight across entries.

Provided Methods§

Source

fn is_empty(&self) -> bool

Returns true when the cache holds no entries.