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 fixed-size 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.

This is a deliberate semantic deviation from LruCache / LfuCache / TtlCache: a successful insert call does not guarantee that the value is in the cache. The admission filter may have rejected it. Callers that need strict insertion guarantees should use LruCache or LfuCache instead.

Reference implementation details:

• depth-4 Count-Min Sketch with u8 saturating counters
• width = max(MIN_SKETCH_WIDTH, 2 × capacity), rounded to the next power of two
• periodic frequency decay: every 10 × capacity increments, every counter is right-shifted by 1 (this is the “aging” step from the W-TinyLFU paper, which keeps the sketch responsive to shifting workloads)
• main cache uses LRU ordering; eviction victim = least-recently-accessed
• lock-minimized via &self + Mutex<Inner>; a true sharded / lock-free variant lands in a later minor without changing this public surface

Example

use cache_mod::{Cache, TinyLfuCache};

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

// Build up the frequency signal for "hot".
for _ in 0..16 {
    let _ = cache.get(&"hot");
    let _ = cache.insert("hot", 1);
}

// A subsequent insert will see "hot" as warm in the sketch.
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.