#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...

FunctionCache &	operator= (FunctionCache &&)=default

FunctionCache &	operator= (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 197 of file function_cache.hpp.

◆ clear_counts()

void clear_counts ( )

inline

Clear the hit_count() and miss_count() counters.

Definition at line 244 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 293 of file function_cache.hpp.

◆ empty()

bool empty ( ) const

inline

Return whether the cache is currently empty.

Definition at line 185 of file function_cache.hpp.

◆ enabled() [1/2]

bool enabled ( ) const

inline

Return whether the cache is currently enabled or not.

Definition at line 218 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 210 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 227 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 236 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 259 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 171 of file function_cache.hpp.

◆ size()

size_type size ( ) const

inline

Get the current count of elements in the cache.

Definition at line 156 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

using container_type = std::unordered_map<key_type, value_type, genesis::utils::hash<key_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:

function_cache.hpp

Detailed Description

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

Public Member Functions

Public Types

Constructor & Destructor Documentation

◆ FunctionCache() [1/3]

◆ ~FunctionCache()

◆ FunctionCache() [2/3]

◆ FunctionCache() [3/3]

Member Function Documentation

◆ clear()

◆ clear_counts()

◆ contains()

◆ empty()

◆ enabled() [1/2]

◆ enabled() [2/2]

◆ hit_count()

◆ miss_count()

◆ operator()()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ shard_sizes()

◆ size()

Member Typedef Documentation

◆ const_iterator

◆ container_type

◆ key_type

◆ size_type

◆ value_type

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