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
 

Constructor & Destructor Documentation

◆ 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

Member Function Documentation

◆ 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<size_t> 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.

Member Typedef Documentation

◆ const_iterator

using const_iterator = typename container_type::const_iterator

Definition at line 97 of file function_cache.hpp.

◆ container_type

Definition at line 95 of file function_cache.hpp.

◆ key_type

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

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: