Struct Cache

Source

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

Expand description

A concurrent, fixed-size, set-associative cache.

This cache maps keys to values using a fixed number of buckets. Each key hashes to exactly one bucket, and collisions are resolved by eviction (the new value replaces the old one).

§Thread Safety

The cache is safe to share across threads (Send + Sync). All operations use atomic instructions and never block, making it suitable for high-contention scenarios.

§Limitations

No Drop support: Key and value types must not implement Drop. Use Copy types, primitives, or &'static references.
Eviction on collision: When two keys hash to the same bucket, the older entry is lost.
No iteration or removal: Individual entries cannot be enumerated or explicitly removed.

§Type Parameters

K: The key type. Must implement Hash + Eq and must not implement Drop.
V: The value type. Must implement Clone and must not implement Drop.
S: The hash builder type. Must implement BuildHasher. Defaults to RandomState or rapidhash if the rapidhash feature is enabled.

§Example

use fixed_cache::Cache;

let cache: Cache<u64, u64> = Cache::new(256, Default::default());

// Insert a value
cache.insert(42, 100);
assert_eq!(cache.get(&42), Some(100));

// Get or compute a value
let value = cache.get_or_insert_with(123, |&k| k * 2);
assert_eq!(value, 246);

Implementations§

Source §

impl<K, V, S> Cache<K, V, S>
where K: Hash + Eq, S: BuildHasher,

Source

pub fn new(num: usize, build_hasher: S) -> Self

Create a new cache with the specified number of entries and hasher.

Dynamically allocates memory for the cache entries.

§Panics

Panics if num is not a power of two.

Source

pub const fn new_static( entries: &'static [Bucket<(K, V)>], build_hasher: S, ) -> Self

Creates a new cache with the specified entries and hasher.

§Panics

Panics if entries.len() is not a power of two.

Source

pub const fn hasher(&self) -> &S

Returns the hash builder used by this cache.

Source

pub const fn capacity(&self) -> usize

Returns the number of entries in this cache.

Source §

impl<K, V, S> Cache<K, V, S>
where K: Hash + Eq, V: Clone, S: BuildHasher,

Source

pub fn get<Q: ?Sized + Hash + Equivalent<K>>(&self, key: &Q) -> Option<V>

Get an entry from the cache.

Source

pub fn insert(&self, key: K, value: V)

Insert an entry into the cache.

Source

pub fn get_or_insert_with<F>(&self, key: K, f: F) -> V
where F: FnOnce(&K) -> V,

Gets a value from the cache, or inserts one computed by f if not present.

If the key is found in the cache, returns a clone of the cached value. Otherwise, calls f to compute the value, attempts to insert it, and returns it.

Source

pub fn get_or_insert_with_ref<'a, Q, F, Cvt>( &self, key: &'a Q, f: F, cvt: Cvt, ) -> V
where Q: ?Sized + Hash + Equivalent<K>, F: FnOnce(&'a Q) -> V, Cvt: FnOnce(&'a Q) -> K,

Gets a value from the cache, or inserts one computed by f if not present.

If the key is found in the cache, returns a clone of the cached value. Otherwise, calls f to compute the value, attempts to insert it, and returns it.

This is the same as get_or_insert_with, but takes a reference to the key, and a function to get the key reference to an owned key.