Struct EvictingCacheMap

pub struct EvictingCacheMap<K, V, const N: usize, F, S = DefaultHashBuilder>
where
    F: Fn(K, V),
{ /* private fields */ }

An evicting cache map.

Backed by a HashMap but maintains order and a maximum capacity. Upon inserting beyond capacity the cache map will remove the eldest elements to make room. Each removal or prune will call the provided prune hook with the values.

Being backed by a HashMap, this container has all the same requirements on its keys as HashMap. Specifically, Keys must implement Eq and Hash. You can typically derive these for types with #[derive(PartialEq, Eq, hash)]. If you implement these yourself you must ensure the following holds:

k1 == k2 -> hash(k1) == hash(k2)

You are also responsible to ensure Keys do not mutate such that their hash can change while in the map. For more information, check HashMap.

Implementations

impl<K, V, const N: usize> EvictingCacheMap<K, V, N, fn(K, V), DefaultHashBuilder>

pub fn new() -> Self

Creates a new map

Default prune hook simply drops K and V.

impl<K, V, const N: usize, F> EvictingCacheMap<K, V, N, F, DefaultHashBuilder>

where F: Fn(K, V),

pub fn with_prune_hook(func: F) -> Self

Create a new map with the provided prune hook

Examples found in repository

examples/channels.rs (line 17)

fn main() {
    let (tx, rx) = mpsc::channel();
    let mut cachemap: EvictingCacheMap<String, u8, 10, _> =
        EvictingCacheMap::with_prune_hook(move |k, v| tx.send((k, v)).unwrap());
    let send = thread::spawn(move || {
        for x in 0..20 {
            cachemap.insert(x.to_string(), x)
        }
    });

    let recv = thread::spawn(move || {
        while let Ok((k, v)) = rx.recv() {
            println!("{k}:{v}")
        }
    });

    let _ = send.join();
    let _ = recv.join();
}

impl<K, V, const N: usize, S> EvictingCacheMap<K, V, N, fn(K, V), S>

pub fn with_hasher(hash_builder: S) -> Self

Create a new map with provided hasher

impl<K, V, const N: usize, F, S> EvictingCacheMap<K, V, N, F, S>

where F: Fn(K, V),

pub fn with_hasher_and_prune_hook(hash_builer: S, func: F) -> Self

Create a new map with the provided hasher and prune hook

impl<K, V, const N: usize, F> EvictingCacheMap<K, V, N, F>

where K: Eq + Hash, F: Fn(K, V),

pub fn prune_by(&mut self, len: usize)

Remove elements and call prune hook

Removes len elements from the cache and calls the prune hook for each. If len is greater than the len() of the cache it will leave it empty.

pub fn prune_by_with(&mut self, len: usize, f: impl Fn(K, V))

Remove elements and calls provided prune hook

Removes len elements from the cache and calls the prune hook for each. If len is greater than the len() of th cache it will leave it empty.

pub fn prune_to(&mut self, len: usize)

Remove elements and call the prune hook

Removes elements until the cache is the provided size.

pub fn prune_to_with(&mut self, len: usize, f: impl Fn(K, V))

Removeelements and call the provided prune hook

Removes elements until the cache is the provided size.

pub fn promote<Q>(&mut self, key: &Q)

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

Promote the element if it exists

This moves an element to the top of the cache as-if removed and re-inserted but does not call the prune hook.

pub fn contains_key<Q>(&self, key: &Q) -> bool

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

Checks if cache contains this key

Does not promote the key.

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

Insert element to the top of the cache

If the container is full this will prune a single element, calling the prune hook.

Examples found in repository

examples/channels.rs (line 20)

fn main() {
    let (tx, rx) = mpsc::channel();
    let mut cachemap: EvictingCacheMap<String, u8, 10, _> =
        EvictingCacheMap::with_prune_hook(move |k, v| tx.send((k, v)).unwrap());
    let send = thread::spawn(move || {
        for x in 0..20 {
            cachemap.insert(x.to_string(), x)
        }
    });

    let recv = thread::spawn(move || {
        while let Ok((k, v)) = rx.recv() {
            println!("{k}:{v}")
        }
    });

    let _ = send.join();
    let _ = recv.join();
}

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

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

Get a reference to the corresponding element and promotes it to the top of the cache.

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

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

Get a reference to the corresponding element without promoting it.

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

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

Get a mutable reference to the corresponding element and promote it to the top of the cache.

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

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

Get a mutable reference to the corresponding element without promoting it.

pub fn get_key_value<Q>(&mut self, key: &Q) -> Option<(&K, &V)>

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

Get a reference to the key-value pair and promote it to the top of the cache.

pub fn get_key_value_no_promote<Q>(&mut self, key: &Q) -> Option<(&K, &V)>

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

Get a reference to the key-value pair without promoting it.

pub fn get_key_value_mut<Q>(&mut self, key: &Q) -> Option<(&K, &mut V)>

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

Get a mutable reference to the key-value pair and promote it to the top of the cache.

pub fn get_key_value_mut_no_promote<Q>( &mut self, key: &Q, ) -> Option<(&K, &mut V)>

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

Get a mutable reference to the key-value pair without promoting it.

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

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

Remove and return a value from the map.

Does not call the prune hook.

pub fn remove_entry<Q>(&mut self, key: &Q) -> Option<(K, V)>

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

Remove and return a key-value pair from the map.

Does not call the prune hook.

pub fn len(&self) -> usize

Retrieve the current number of elements in the cache.

pub fn is_empty(&self) -> bool

Check whether the cache is empty.

pub fn clear(&mut self)

Clear all elements from the map and call the prune hook for each element.

pub fn iter(&self) -> Iter<'_, K, V>

Iterator over the values in the map

pub fn iter_mut(&mut self) -> IterMut<'_, K, V>

Mutable Iterator for the values in the map

Note: mutating a value through this iterator does not promote keys.

Trait Implementations

impl<K, V, const N: usize, F, S> Debug for EvictingCacheMap<K, V, N, F, S>

where K: Debug, V: Debug, F: Fn(K, V),

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

Formats the value using the given formatter.

impl<K, V, const N: usize> Default for EvictingCacheMap<K, V, N, fn(K, V), DefaultHashBuilder>

fn default() -> Self

Returns the “default value” for a type.

impl<'a, K, V, const N: usize, F, S> IntoIterator for &'a EvictingCacheMap<K, V, N, F, S>

where F: Fn(K, V),

type Item = (&'a K, &'a V)

The type of the elements being iterated over.

type IntoIter = Iter<'a, K, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, K, V, const N: usize, F, S> IntoIterator for &'a mut EvictingCacheMap<K, V, N, F, S>

where F: Fn(K, V),

type Item = (&'a K, &'a mut V)

The type of the elements being iterated over.

type IntoIter = IterMut<'a, K, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.