Struct GenericCache

pub struct GenericCache<'f, C: SparseContainer> { /* private fields */ }

A generic cache for a function backed by anything that implements the SparseContainer trait.

Not all containers may support the precise access pattern, such as [VecCache] which implements FnCache directly, but most uses can simply implement SparseContainer for their container and immediately have everything working with GenericCache.

The cache takes ownership of all inputs, but only passes a reference to the function, allowing it to store the input in the cache without any copies or clones. Additionally, the function is shared using by using a RefCache when actually calling the function, preventing any reference counting or clones of the closure.

Implementations

impl<'f, C: SparseContainer> GenericCache<'f, C>

pub fn with_cache( cache: C, f: impl Fn(&C::Input) -> C::Output + Send + 'f, ) -> Self

Create a GenericCache out of a cache and a function.

Using this function you can pre-initialize some values into the cache if desired, change settings using specific constructors on the cache type, or any variation. If a default version of the cache is sufficient for your needs, Self::new may be less verbose.

let cache = GenericCache::with_cache(HashMap::<usize, usize>::new(), |x: &usize| *x);

pub fn recursive_with_cache( cache: C, f: impl Fn(&mut RefCache<'_, C>, &C::Input) -> C::Output + Send + 'f, ) -> Self

Create a GenericCache out of a cache and a recursive function.

Using this function you can pre-initialize some values into the cache if desired, change settings using specific constructors on the cache type, or any variation. If a default version of the cache is sufficient for your needs, Self::recursive may be less verbose.

let cache = GenericCache::recursive_with_cache(HashMap::<usize, usize>::new(), |cache, x| match x {
    0 => 1,
    1 => 1,
    _ => cache.get_many([x - 1, x - 2]).into_iter().sum()
});

pub fn cache(&self) -> &C

Get a reference to the underlying cache object, letting you use functions exclusive to the cache type (as long they only need &self of course).

impl<'f, C> GenericCache<'f, C>

where C: SparseContainer + Default,

pub fn new(f: impl Fn(&C::Input) -> C::Output + Send + 'f) -> Self

Create a GenericCache using the Default implementation of the [Cache] type.

If a specific instance of a cache is required, see Self::with_cache.

let cache: GenericCache<HashMap<_,_>> = GenericCache::new(|x: &usize| *x);

pub fn recursive( f: impl Fn(&mut RefCache<'_, C>, &C::Input) -> C::Output + Send + 'f, ) -> Self

Create a GenericCache using the Default implementation of the [Cache] type, using a recursive function.

If a specific instance of a cache is required, see Self::recursive_with_cache.

let cache: GenericCache<HashMap<usize, u64>> = GenericCache::recursive(|cache, x| match x {
    0 => 1,
    1 => 1,
    _ => cache.get_many([x - 1, x - 2]).into_iter().sum()
});

Issues

Currently it does not work if you pass in a recursive function generic over FnCache via a function pointer. Wrap the pointer in a closure.

fn increment(cache: &mut impl FnCache<usize, usize>, x: &usize) -> usize {
    match x {
        0 => 0,
        _ => cache.get(x - 1) + 1,
    }
}

// no good
//let cache: GenericCache<HashMap<_, _>> = GenericCache::recursive(increment);
//okay
let cache: GenericCache<HashMap<_, _>> = GenericCache::recursive(|c, i| increment(c, i));

impl<'f, C: SparseContainer + ContainerLen> GenericCache<'f, C>

pub fn len(&self) -> usize

Returns the number of elements in the cache.

impl<'f, C: SparseContainer + ContainerClear> GenericCache<'f, C>

pub fn clear(&mut self)

Clears the cache, removing all key-value pairs. Keeps the allocated memory for reuse.

impl<'f, C: SparseContainer + ContainerReserve> GenericCache<'f, C>

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements to be inserted in the cache. The collection may reserve more space to avoid frequent reallocations.

impl<'f, C: ContainerRemove> GenericCache<'f, C>

pub fn remove(&mut self, input: &C::Input) -> Option<C::Output>

Removes the input from the cache, returning any value if the input was previously in the cache.

Trait Implementations

impl<'f, C: SparseContainer> FnCache<<C as SparseContainer>::Input, <C as SparseContainer>::Output> for GenericCache<'f, C>

fn get(&mut self, input: C::Input) -> &C::Output

Retrieve a value stored in the cache. If the value does not yet exist in the cache, the function is called, and the result is added to the cache before returning it.

impl<'f, C> FnCacheMany<<C as SparseContainer>::Input, <C as SparseContainer>::Output> for GenericCache<'f, C>

where C: SparseContainer, C::Input: Clone,

fn get_many<const N: usize>(&mut self, inputs: [C::Input; N]) -> [&C::Output; N]

Retrieve multiple values stored in the cache. If any of the values do not yet exist, the function is called, and the result is added to the cache before returning them.

impl<'f, I, O, S> From<GenericCache<'f, HashMap<I, O, S>>> for HashCache<'f, I, O, S>

where I: Eq + Hash, S: BuildHasher,

fn from(value: GenericCache<'f, HashMap<I, O, S>>) -> Self

Converts to this type from the input type.