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

Eviction on collision: When two keys hash to the same bucket, the older entry is evicted.
No iteration: Individual entries cannot be enumerated.

§Type Parameters

K: The key type. Must implement Hash + Eq.
V: The value type. Must implement Clone.
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.
isn’t at least 4.

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

See new.

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 remove<Q: ?Sized + Hash + Equivalent<K>>(&self, key: &Q) -> Option<V>

Remove an entry from the cache.

Returns the value if the key was present in 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.

Source

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

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

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

Source

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

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

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

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