Struct MemoCache

Source

pub struct MemoCache<K, V, const SIZE: usize> { /* private fields */ }

Expand description

A small, fixed-size, heap-allocated key/value cache with retention management.

§Thread Safety

MemoCache is Send but not Sync. It can be moved between threads but cannot be shared across threads via shared references (&MemoCache).

This is because the cache uses interior mutability (via Cell) for tracking hit counts and random number generation, which is not thread-safe.

For concurrent access, wrap it in a synchronization primitive. E.g.:

use std::sync::Mutex;
use memo_cache::MemoCache;

let cache = Mutex::new(MemoCache::<u32, String, 8>::new());

// In thread 1:
cache.lock().unwrap().insert(42, "value".to_string());

// In thread 2:
let value = cache.lock().unwrap().get(&42);

Implementations§

Source §

impl<K, V, const SIZE: usize> MemoCache<K, V, SIZE>
where K: Eq,

Source

pub fn new() -> Self

Create a new cache.

§Examples

use memo_cache::MemoCache;

let c = MemoCache::<u32, String, 4>::new();

Source

pub const fn capacity(&self) -> usize

Get the (fixed) capacity of the cache in [number of elements].

§Examples

use memo_cache::MemoCache;

let c = MemoCache::<u32, String, 8>::new();

assert_eq!(c.capacity(), 8);

Source

pub fn insert(&mut self, k: K, v: V)

Insert a key/value pair.

§Examples

use memo_cache::MemoCache;

let mut c = MemoCache::<u32, &str, 4>::new();

assert_eq!(c.get(&42), None);

c.insert(42, "The Answer");

assert_eq!(c.get(&42), Some(&"The Answer"));

Source

pub fn contains_key<Q>(&self, k: &Q) -> bool
where K: Borrow<Q>, Q: Eq + ?Sized,

Returns true if the cache contains a value for the specified key.

§Examples

use memo_cache::MemoCache;

let mut c = MemoCache::<u32, &str, 4>::new();

assert_eq!(c.contains_key(&42), false);

c.insert(42, "The Answer");

assert_eq!(c.contains_key(&42), true);

Source

pub fn get<Q>(&self, k: &Q) -> Option<&V>
where K: Borrow<Q>, Q: Eq + ?Sized,

Lookup a cache entry by key.

§Examples

use memo_cache::MemoCache;

let mut c = MemoCache::<u32, &str, 4>::new();

assert_eq!(c.get(&42), None);

c.insert(42, "The Answer");

assert_eq!(c.get(&42), Some(&"The Answer"));

Source

pub fn get_mut<Q>(&mut self, k: &Q) -> Option<&mut V>
where K: Borrow<Q>, Q: Eq + ?Sized,

Lookup a cache entry by key (for mutation).

§Examples

use memo_cache::MemoCache;

let mut c = MemoCache::<u32, &str, 4>::new();

c.insert(42, "The Answer");

if let Some(v) = c.get_mut(&42) {
    *v = "Another Answer";
}

assert_eq!(c.get(&42), Some(&"Another Answer"));

Source

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

Get a value, or, if it does not exist in the cache, insert it using the value computed by f. Returns a reference to the found, or newly inserted value associated with the given key. If a value is inserted, the key is cloned.

§Examples

use memo_cache::MemoCache;

let mut c = MemoCache::<u32, &str, 4>::new();

assert_eq!(c.get(&42), None);

let v = c.get_or_insert_with(&42, |_| "The Answer");

assert_eq!(v, &"The Answer");
assert_eq!(c.get(&42), Some(&"The Answer"));

§Notes

Because this crate is no_std, we have no access to std::borrow::ToOwned, which means we cannot create a version of get_or_insert_with that can create an owned value from a borrowed key.

Source

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

Get a value, or, if it does not exist in the cache, insert it using the value computed by f. Returns a result with a reference to the found, or newly inserted value associated with the given key. If a value is inserted, the key is cloned.

§Examples

use memo_cache::MemoCache;

let mut c = MemoCache::<u32, &str, 4>::new();

assert_eq!(c.get(&42), None);

let answer : Result<_, &str> = Ok("The Answer");
let v = c.get_or_try_insert_with(&42, |_| answer);

assert_eq!(v, Ok(&"The Answer"));
assert_eq!(c.get(&42), Some(&"The Answer"));

let v = c.get_or_try_insert_with(&17, |_| Err("Dunno"));

assert_eq!(v, Err("Dunno"));
assert_eq!(c.get(&17), None);

§Errors

If the function f fails, the error of type E is returned.

§Notes

Because this crate is no_std, we have no access to std::borrow::ToOwned, which means we cannot create a version of get_or_try_insert_with that can create an owned value from a borrowed key.

Source

pub fn clear(&mut self)

Clear the cache.

§Examples

use memo_cache::MemoCache;

let mut c = MemoCache::<u32, &str, 4>::new();

assert_eq!(c.get(&42), None);

c.insert(42, "The Answer");

assert_eq!(c.get(&42), Some(&"The Answer"));

c.clear();

assert_eq!(c.get(&42), None);