cache-mod 0.5.0

High-performance in-process caching with multiple eviction policies (LRU, LFU, TinyLFU, TTL, size-bounded). Async-safe, lock-minimized internals. Typed key-value API. No dependency on any external store.
Documentation

Status

Active development. Foundation milestone (0.2.0) shipped. On the path to 1.0.

The public API is not yet frozen. Pin specific versions; expect additive (and occasionally breaking) changes pre-1.0.

What it does

High-performance in-process caching with multiple eviction policies (LRU, LFU, TinyLFU, TTL, size-bounded). Async-safe, lock-minimized internals. Typed key-value API. No dependency on any external store.

Quick start

[dependencies]
cache-mod = "0.5"

use std::time::Duration;
use cache_mod::{Cache, LfuCache, LruCache, SizedCache, TinyLfuCache, TtlCache};

// LRU — evicts the least-recently-accessed entry on overflow.
let lru: LruCache<&'static str, u32> = LruCache::new(64).expect("capacity > 0");
lru.insert("requests", 1);
assert_eq!(lru.get(&"requests"), Some(1));

// LFU — evicts the lowest-counter entry on overflow.
let lfu: LfuCache<&'static str, u32> = LfuCache::new(64).expect("capacity > 0");
lfu.insert("requests", 1);

// TTL — entries expire after their per-entry deadline; lazy expiry on access.
let ttl: TtlCache<&'static str, u32> =
    TtlCache::new(64, Duration::from_secs(300)).expect("capacity > 0");
ttl.insert_with_ttl("flash", 7, Duration::from_secs(5));

// TinyLFU — Count-Min Sketch admission filter rejects cold candidates.
let tinylfu: TinyLfuCache<&'static str, u32> = TinyLfuCache::new(64).expect("capacity > 0");
tinylfu.insert("hot", 1);

// SizedCache — capacity is total byte-weight, not entry count.
fn byte_weight(v: &Vec<u8>) -> usize { v.len() }
let sized: SizedCache<&'static str, Vec<u8>> =
    SizedCache::new(4 * 1024, byte_weight).expect("max_weight > 0");
sized.insert("payload", vec![0u8; 256]);

What's shipped

  • Cache<K, V> trait — the common read / write / evict contract.
  • LruCache<K, V> — bounded, thread-safe Least-Recently-Used cache.
  • LfuCache<K, V> — bounded, thread-safe Least-Frequently-Used cache.
  • TtlCache<K, V> — bounded, thread-safe Time-To-Live cache with lazy expiry.
  • TinyLfuCache<K, V> — Count-Min Sketch admission filter + LRU main cache.
  • SizedCache<K, V> — capacity bound is total byte-weight across entries.
  • CacheError — error type returned by constructors.

Lock-free, arena-backed rewrites of the existing reference implementations land in 0.6.0 — public surface unchanged.

Standards

  • REPS governs every decision. See REPS.md.
  • MSRV: Rust 1.75.
  • Edition: 2024.
  • Cross-platform: Linux, macOS, Windows.

License

Dual-licensed under either of:

at your option.