Struct Cache

pub struct Cache<K, V, S = RandomState> { /* private fields */ }

Highly performant, thread-safe cache with a focus on simplicity.

It implements the S3-FIFO eviction algorithm as specified in FIFO Queues are All You Need for Cache Eviction. The cache is divided into multiple shards to reduce contention during concurrent access. This crate does not use any unsafe code.

Wrap the cache in a std::sync::Arc to share it between threads. Both reads and writes only require shared references to the cache.

Implementations

impl<K, V> Cache<K, V, RandomState>

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

pub fn with_capacity(capacity: usize) -> Cache<K, V, RandomState>

Creates a new cache with at least the specified capacity.

The actual capacity may be slightly higher due to sharding and rounding.

impl<K, V, S> Cache<K, V, S>

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

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

Inserts a key-value pair into the cache.

If the cache did not have this key present, None is returned.

If the cache did have this key present, the value is updated, and the old value is returned.

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

where K: Borrow<Q>, Q: ?Sized + Hash + Eq,

Returns the value corresponding to the key.

This method clones the value when returning the item. Consider wrapping your values in std::sync::Arc if cloning is too expensive for you use-case.

impl<K, V, S> Cache<K, V, S>

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

pub fn with_capacity_and_hasher( capacity: usize, hash_builder: S, ) -> Cache<K, V, S>

Creates a new cache with the at least the specified capacity, using hasher to hash the keys.

The actual capacity may be slightly higher due to sharding and rounding.

impl<K, V, S> Cache<K, V, S>

pub fn stats(&self) -> Stats

Returns cache performance statistics and resets the internal counters.

This method provides metrics about cache performance since the last call to stats(). After returning the statistics, all internal counters are reset to zero.

Examples

Basic usage:

use plain_cache::Cache;

let cache = Cache::with_capacity(100);
cache.insert("key1", "value1");
cache.get("key1"); // hit
cache.get("key2"); // miss

let stats = cache.stats();
println!("Hits: {}, Misses: {}", stats.hit_count, stats.miss_count);

Calculating hit rate:

use plain_cache::Cache;

let cache = Cache::with_capacity(100);
cache.insert("key1", "value1");
cache.get("key1"); // hit
cache.get("key2"); // miss

let stats = cache.stats();
let total_requests = stats.hit_count + stats.miss_count;
if total_requests > 0 {
    let hit_rate = stats.hit_count as f64 / total_requests as f64;
    println!("Hit rate: {:.2}%", hit_rate * 100.0);
}

Note

The counters are reset after each call to stats(), so each call returns statistics for the period since the previous call. This allows for periodic monitoring of cache performance.

Trait Implementations

impl<K: Debug, V: Debug, S: Debug> Debug for Cache<K, V, S>

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

Formats the value using the given formatter.