Struct TinyLfuCache 

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

Available on crate feature std only.

A bounded, thread-safe cache with admission control.

TinyLfuCache tracks the access frequency of every key it observes — including keys that aren’t (yet) in the cache — using a Count-Min Sketch. On capacity overflow, an incoming key is admitted only if its estimated frequency exceeds the LRU victim’s. One-hit-wonders are rejected at the door instead of evicting hot entries.

A successful insert call does not guarantee the value is in the cache. The admission filter may reject it. Callers that need strict insertion guarantees should use LruCache or LfuCache.

Implementation

Sharded into up to 16 independent arenas keyed by hash of K. Each shard owns its own Count-Min Sketch — the frequency signal is per-shard, not global. This is a deliberate trade-off: a global sketch would force every access to lock a shared structure, defeating the point of sharding. Per-shard sketches still capture the local frequency signal accurately, which is what the local admission decision needs.

Eviction is approximate (per-shard LRU). Tiny caches (< 32 entries) use a single shard and retain strict global semantics.

Example

use cache_mod::{Cache, TinyLfuCache};

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

for _ in 0..16 {
    let _ = cache.get(&"hot");
    let _ = cache.insert("hot", 1);
}

assert_eq!(cache.get(&"hot"), Some(1));

Implementations

impl<K, V> TinyLfuCache<K, V>

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

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

Creates a cache with the given entry-count capacity.

Returns CacheError::InvalidCapacity if capacity == 0.

Example

use cache_mod::TinyLfuCache;

let cache: TinyLfuCache<String, u32> =
    TinyLfuCache::new(256).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::TinyLfuCache;

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

Trait Implementations

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