A library for working with phylogenetic data. v0.25.0
FunctionCache< R, A > Class Template Reference

#include <genesis/utils/containers/function_cache.hpp>

## Detailed Description

### template<typename R, typename... A> class genesis::utils::FunctionCache< R, A >

Simple cache, for example for function return values.

General usage: Provide the pure function that needs to be cached to the constructor, for example via a lambda. Then use operator() to request elements by their function parameters (which are combined into a key, see below). If the cache already contains the result for these parameters, it is returned; if not, it is first computed using the function that was provided in the constructor.

The template parameters of this class template are:

• R, the return type (value) of the function that is stored/cached.
• A, the list of arguments of the function that produces the return value. These arguments are combined into a key at which a return value is stored.

The cache of course assumes pure functions with no side effects, that is, the same arguments always produce the same output. This is for example useful to cache complicated mathematical functions that have few different, but re-used inputs.

The class is thread safe and blocks as needed when elements are requested from multiple threads. In order to facilitate concurrent fast access from mutliple threads, we are using the following strategy: The hash map that we use for storing key value pairs is split into "shards" that are accessible via an index computed from the keys. Each shard has its own mutex lock, and can hence be accessed without lock on the whole data structure. As long as the number of shards is sufficiently larger than the number of concurrent threads, it is likely that two threads request values from different shards, and hence can access them concurrently.

Definition at line 81 of file function_cache.hpp.

## Public Member Functions

FunctionCache (FunctionCache &&)=default

FunctionCache (FunctionCache const &)=delete

FunctionCache (std::function< R(A...)> load_function, size_t shards=256)
Constructor, takes the function that is needed to compute values for the cache. More...

~FunctionCache ()=default

void clear ()
Clear the cache. More...

void clear_counts ()
Clear the hit_count() and miss_count() counters. More...

bool contains (A const &... arguments) const
Return whether a certain key is already in the cache. More...

bool empty () const
Return whether the cache is currently empty. More...

bool enabled () const
Return whether the cache is currently enabled or not. More...

void enabled (bool value)
Enable or disable the caching. More...

size_t hit_count () const
Return how often in total there was a cache hit, that is, a key requested that was already present in the cache. More...

size_t miss_count () const
Return how often in total there was a cache miss, that is, a key requested that was not yet present in the cache and hence lead to a computation of the load function. More...

R const & operator() (A const &... arguments)
Access operator for retrieving a value given the key (arguments to the cached function). More...

FunctionCacheoperator= (FunctionCache &&)=default

FunctionCacheoperator= (FunctionCache const &)=delete

std::vector< size_t > shard_sizes () const
Get a tally of how many cached values are stored in each of the shards. More...

size_type size () const
Get the current count of elements in the cache. More...

## Public Types

using const_iterator = typename container_type::const_iterator

using container_type = std::unordered_map< key_type, value_type, genesis::utils::hash< key_type > >

using key_type = std::tuple< A... >

using size_type = size_t

using value_type = R

## ◆ FunctionCache() [1/3]

 FunctionCache ( std::function< R(A...)> load_function, size_t shards = 256 )
inline

Constructor, takes the function that is needed to compute values for the cache.

Additionaly, the number of shards can be set here, which should always be sufficiently larger than the number of concurrent threads that access this class, for best performance.

Definition at line 127 of file function_cache.hpp.

## ◆ ~FunctionCache()

 ~FunctionCache ( )
default

## ◆ FunctionCache() [2/3]

 FunctionCache ( FunctionCache< R, A > const & )
delete

## ◆ FunctionCache() [3/3]

 FunctionCache ( FunctionCache< R, A > && )
default

## ◆ clear()

 void clear ( )
inline

Clear the cache.

Clears all cached key-value-pairs. Does not clear the hit_count() and miss_count(). See clear_counts() for that.

Definition at line 195 of file function_cache.hpp.

## ◆ clear_counts()

 void clear_counts ( )
inline

Clear the hit_count() and miss_count() counters.

Definition at line 242 of file function_cache.hpp.

## ◆ contains()

 bool contains ( A const &... arguments ) const
inline

Return whether a certain key is already in the cache.

Definition at line 291 of file function_cache.hpp.

## ◆ empty()

 bool empty ( ) const
inline

Return whether the cache is currently empty.

Definition at line 183 of file function_cache.hpp.

## ◆ enabled() [1/2]

 bool enabled ( ) const
inline

Return whether the cache is currently enabled or not.

Definition at line 216 of file function_cache.hpp.

## ◆ enabled() [2/2]

 void enabled ( bool value )
inline

Enable or disable the caching.

This is useful for speed testing to see how much speedup the cache actually yields.

Definition at line 208 of file function_cache.hpp.

## ◆ hit_count()

 size_t hit_count ( ) const
inline

Return how often in total there was a cache hit, that is, a key requested that was already present in the cache.

Definition at line 225 of file function_cache.hpp.

## ◆ miss_count()

 size_t miss_count ( ) const
inline

Return how often in total there was a cache miss, that is, a key requested that was not yet present in the cache and hence lead to a computation of the load function.

Definition at line 234 of file function_cache.hpp.

## ◆ operator()()

 R const& operator() ( A const &... arguments )
inline

Access operator for retrieving a value given the key (arguments to the cached function).

This returns the cached value if present, or first computes and stores it if necessary.

Definition at line 257 of file function_cache.hpp.

## ◆ operator=() [1/2]

 FunctionCache& operator= ( FunctionCache< R, A > && )
default

## ◆ operator=() [2/2]

 FunctionCache& operator= ( FunctionCache< R, A > const & )
delete

## ◆ shard_sizes()

 std::vector shard_sizes ( ) const
inline

Get a tally of how many cached values are stored in each of the shards.

Useful for debugging to test that the shards have an equal distribution of values.

Definition at line 169 of file function_cache.hpp.

## ◆ size()

 size_type size ( ) const
inline

Get the current count of elements in the cache.

Definition at line 154 of file function_cache.hpp.

## ◆ const_iterator

 using const_iterator = typename container_type::const_iterator

Definition at line 97 of file function_cache.hpp.

## ◆ container_type

 using container_type = std::unordered_map >

Definition at line 95 of file function_cache.hpp.

## ◆ key_type

 using key_type = std::tuple

Definition at line 90 of file function_cache.hpp.

## ◆ size_type

 using size_type = size_t

Definition at line 89 of file function_cache.hpp.

## ◆ value_type

 using value_type = R

Definition at line 91 of file function_cache.hpp.

The documentation for this class was generated from the following file: