Thread-safe memory-restricted cache. More...

#include <cache.h>

Public Types
using	MyInsertionPolicy = InsertionPolicy< Key, KeyHash, Value >

using	MyEvictionPolicy = EvictionPolicy< Key, KeyHash, Value >

using	MyConstraintPolicy = ConstraintPolicy< Key, KeyHash, Value >

using	CacheType = Cache< Key, Value, InsertionPolicy, EvictionPolicy, ConstraintPolicy, MeasureValue, MeasureKey, KeyHash, ThreadSafe >

using	LockGuard = std::unique_lock< std::recursive_mutex >

Public Member Functions
template<typename... Args>
	Cache (Args... args)
	Simple constructor. More...

template<typename C , typename... Args>
	Cache (C &collection, std::tuple< Args... > args)
	Constructor to initialize the cache with a set of items. More...

template<typename KeyView >
bool	contains (const KeyView &key) const
	Check whether a given key is stored in the cache. More...

template<typename KeyView >
std::optional< Value >	find (const KeyView &key) const
	Find a given key in cache returning the associated value when it exists. More...

template<typename C >
void	collect_into (C &container) const
	Copy the cache contents in the provided container. More...

bool	insert (Key key, Value value)
	Insert a key/value pair in the cache. More...

bool	remove (const Key &key)
	Remove a key and its value from the cache. More...

void	clear ()
	Clears the cache contents.

template<typename P >
void	retain (P predicate_fn)
	Retain all objects matching a predicate. More...

template<typename F >
void	for_each (F unary_function)
	Apply a function to all objects in cache. More...

void	swap (CacheType &other) noexcept
	Swaps the current cache with another cache of the same type. More...

size_t	number_of_items () const
	Get the number of items currently stored in the cache. More...

template<typename... Args>
void	update_constraint (Args... args)
	Update the cache constraint. More...

MyInsertionPolicy &	insertion_policy ()
	Get a reference to the insertion policy used by the cache.

const MyInsertionPolicy &	insertion_policy () const
	Get a const reference to the insertion policy used by the cache.

MyEvictionPolicy &	eviction_policy ()
	Get a reference to the eviction policy used by the cache.

const MyEvictionPolicy &	eviction_policy () const
	Get a const reference to the eviction policy used by the cache.

MyConstraintPolicy &	constraint_policy ()
	Get a reference to the constraint policy used by the cache.

const MyConstraintPolicy &	constraint_policy () const
	Get a const reference to the constraint policy used by the cache.

double	hit_rate () const
	Compute and return the running hit rate of the cache. More...

double	byte_hit_rate () const
	Compute and return the running byte hit rate of the cache, in bytes. More...

uint32_t	statistics_window_size () const
	Get the size of the sliding window used for computing statistics. More...

void	statistics_window_size (uint32_t window_size)
	Set the size of the sliding window used for computing statistics. More...

template<typename Coll , typename... Args>
	Cache (Coll &collection, std::tuple< Args... > args)

template<typename KeyView >
std::optional< V >	find (const KeyView &key) const

template<class Container >
void	collect_into (Container &container) const

template<class Coll >
void	import (Coll &collection)

Protected Member Functions
LockGuard	lock () const

LockGuard	lock (std::defer_lock_t defer_lock_tag) const

std::pair< LockGuard, LockGuard >	lock_pair (CacheType &other) const

template<typename C >
void	import (C &collection)

Detailed Description

template<typename Key, typename Value, template< class, class, class > class InsertionPolicy, template< class, class, class > class EvictionPolicy, template< class, class, class > class ConstraintPolicy, typename MeasureValue = measurement::Size<Value>, typename MeasureKey = measurement::Size<Key>, typename KeyHash = absl::Hash<Key>, bool ThreadSafe = true>
class cachemere::Cache< Key, Value, InsertionPolicy, EvictionPolicy, ConstraintPolicy, MeasureValue, MeasureKey, KeyHash, ThreadSafe >

Thread-safe memory-restricted cache.

This class keeps the inserted items alive, and it handles the bulk of the Insert/Evict logic while respecting the size constraints.

Some logic is delegated to the insertion and eviction policies. For details, see the Main Page.

Template Parameters

Key	The type of the key used for retrieving items.
Value	The type of the items stored in the cache.
InsertionPolicy	A template parameterized by `Key`, `KeyHash`, and `Value` implementing the insertion policy interface.
EvictionPolicy	A template parameterized by `Key` `KeyHash`, and `Value` implementing the eviction policy interface.
ConstraintPolicy	A template parameterized by `Key` `KeyHash`, and `Value` implementing the constraint policy interface.
MeasureValue	A functor returning the size of a cache value.
MeasureKey	A functor returning the size of a cache key.
KeyHash	A default-constructible callable type returning a hash of a key. Defaults to `absl::Hash<Key>`.
ThreadSafe	Whether to enable locking. When true, all cache operations will be protected by a lock. `true` by default.

Constructor & Destructor Documentation

◆ Cache() [1/2]

template<typename Key , typename Value , template< class, class, class > class InsertionPolicy, template< class, class, class > class EvictionPolicy, template< class, class, class > class ConstraintPolicy, typename MeasureValue , typename MeasureKey , typename KeyHash , bool ThreadSafe>

template<typename... Args>

cachemere::Cache< Key, Value, InsertionPolicy, EvictionPolicy, ConstraintPolicy, MeasureValue, MeasureKey, KeyHash, ThreadSafe >::Cache ( Args... args )

Simple constructor.

Parameters

args	Arguments to forward to the constraint policy constructor.

◆ Cache() [2/2]

template<typename Key , typename Value , template< class, class, class > class InsertionPolicy, template< class, class, class > class EvictionPolicy, template< class, class, class > class ConstraintPolicy, typename MeasureValue = measurement::Size<Value>, typename MeasureKey = measurement::Size<Key>, typename KeyHash = absl::Hash<Key>, bool ThreadSafe = true>

template<typename C , typename... Args>

cachemere::Cache< Key, Value, InsertionPolicy, EvictionPolicy, ConstraintPolicy, MeasureValue, MeasureKey, KeyHash, ThreadSafe >::Cache	(	C &	collection,
		std::tuple< Args... >	args
	)

Constructor to initialize the cache with a set of items.

Will insert items in order in the cache as long as the constraint is satisfied.

Parameters

collection	The collection to use to initialize the cache - must be a collection of pairs.
args	Tuple of arguments to forward to the constraint policy constructor.

Warning: Items that are imported from the collection are moved out of the container and left in an unspecified state. The container itself can be reused after clearing it.

Member Function Documentation

◆ byte_hit_rate()

template<class K , class V , template< class, class, class > class I, template< class, class, class > class E, template< class, class, class > class C, class SV , class SK , class KH , bool TS>

double cachemere::Cache< K, V, I, E, C, SV, SK, KH, TS >::byte_hit_rate

inline

Compute and return the running byte hit rate of the cache, in bytes.

The byte hit rate represents the average amount of data saved by cache accesses. This is a very useful metric in applications where item load times scale linearly with item size, for instance in a web server.

Returns: The byte hit rate, in bytes.

◆ collect_into()

template<typename Key , typename Value , template< class, class, class > class InsertionPolicy, template< class, class, class > class EvictionPolicy, template< class, class, class > class ConstraintPolicy, typename MeasureValue = measurement::Size<Value>, typename MeasureKey = measurement::Size<Key>, typename KeyHash = absl::Hash<Key>, bool ThreadSafe = true>

template<typename C >

void cachemere::Cache< Key, Value, InsertionPolicy, EvictionPolicy, ConstraintPolicy, MeasureValue, MeasureKey, KeyHash, ThreadSafe >::collect_into ( C & container ) const

Copy the cache contents in the provided container.

The container should conform to either of the STL's interfaces for associative containers or for sequence containers. Uses emplace_back for sequence containers, and emplace for associative containers. If the provided container has size() and reserve() methods, collect_into will reserve the appropriate amount of space in the container before inserting.

Parameters

container The container in which to insert the items.

◆ contains()

template<class K , class V , template< class, class, class > class I, template< class, class, class > class E, template< class, class, class > class C, class SV , class SK , class KH , bool TS>

template<typename KeyView >

bool cachemere::Cache< K, V, I, E, C, SV, SK, KH, TS >::contains ( const KeyView & key ) const

inline

Check whether a given key is stored in the cache.

Template Parameters

KeyView The type of the key used for retrieving items.

Parameters

key	The key whose presence to test.

Returns: Whether the key is in cache.

◆ find()

template<typename Key , typename Value , template< class, class, class > class InsertionPolicy, template< class, class, class > class EvictionPolicy, template< class, class, class > class ConstraintPolicy, typename MeasureValue = measurement::Size<Value>, typename MeasureKey = measurement::Size<Key>, typename KeyHash = absl::Hash<Key>, bool ThreadSafe = true>

template<typename KeyView >

std::optional<Value> cachemere::Cache< Key, Value, InsertionPolicy, EvictionPolicy, ConstraintPolicy, MeasureValue, MeasureKey, KeyHash, ThreadSafe >::find ( const KeyView & key ) const

Find a given key in cache returning the associated value when it exists.

Template Parameters

KeyView The type of the key used for retrieving items.

Parameters

key	The key to lookup.

Returns: The value if key is in cache, std::nullopt otherwise.

◆ for_each()

template<class K , class V , template< class, class, class > class I, template< class, class, class > class E, template< class, class, class > class C, class SV , class SK , class KH , bool TS>

template<class F >

void cachemere::Cache< K, V, I, E, C, SV, SK, KH, TS >::for_each ( F unary_function )

Apply a function to all objects in cache.

Parameters

unary_function The function to be applied to all items in cache. The function should have the signature void fn(const Key& key, const Value& value).

◆ hit_rate()

template<class K , class V , template< class, class, class > class I, template< class, class, class > class E, template< class, class, class > class C, class SV , class SK , class KH , bool TS>

double cachemere::Cache< K, V, I, E, C, SV, SK, KH, TS >::hit_rate

inline

Compute and return the running hit rate of the cache.

The hit rate is computed using a sliding window determined by the sliding window size passed to the constructor.

Returns: The hit rate, as a fraction.

◆ insert()

template<typename Key , typename Value , template< class, class, class > class InsertionPolicy, template< class, class, class > class EvictionPolicy, template< class, class, class > class ConstraintPolicy, typename MeasureValue = measurement::Size<Value>, typename MeasureKey = measurement::Size<Key>, typename KeyHash = absl::Hash<Key>, bool ThreadSafe = true>

bool cachemere::Cache< K, V, I, E, C, SV, SK, KH, TS >::insert	(	Key	key,
		Value	value
	)

Insert a key/value pair in the cache.

If the key is new, the key/value pair will be inserted. If the key already exists, the provided value will overwrite the previous one.

Parameters

key	The key to associate with the value.
value	The value to store.

Returns: Whether the item was inserted in cache.

◆ number_of_items()

template<class K , class V , template< class, class, class > class I, template< class, class, class > class E, template< class, class, class > class C, class SV , class SK , class KH , bool TS>

size_t cachemere::Cache< K, V, I, E, C, SV, SK, KH, TS >::number_of_items

inline

Get the number of items currently stored in the cache.

Warning: This method acquires a mutual exclusion lock to secure the item count. Calling this excessively while the cache is under contention will be detrimental to performance.

Returns: How many items are in cache.

◆ remove()

template<typename Key , typename Value , template< class, class, class > class InsertionPolicy, template< class, class, class > class EvictionPolicy, template< class, class, class > class ConstraintPolicy, typename MeasureValue = measurement::Size<Value>, typename MeasureKey = measurement::Size<Key>, typename KeyHash = absl::Hash<Key>, bool ThreadSafe = true>

bool cachemere::Cache< Key, Value, InsertionPolicy, EvictionPolicy, ConstraintPolicy, MeasureValue, MeasureKey, KeyHash, ThreadSafe >::remove ( const Key & key )

Remove a key and its value from the cache.

If the key is not present in cache, no operation is taken.

Parameters

key	The key to remove from the cache.

Returns: Whether the key was present in cache.

◆ retain()

template<class K , class V , template< class, class, class > class I, template< class, class, class > class E, template< class, class, class > class C, class SV , class SK , class KH , bool TS>

template<class P >

void cachemere::Cache< K, V, I, E, C, SV, SK, KH, TS >::retain ( P predicate_fn )

Retain all objects matching a predicate.

Removes all items for which predicate_fn returns false.

Parameters

predicate_fn The predicate function.

Template Parameters

P	The type of the predicate function. The predicate should have the signature `bool fn(const Key& key, const Value& value)`.

◆ statistics_window_size() [1/2]

template<class K , class V , template< class, class, class > class I, template< class, class, class > class E, template< class, class, class > class C, class SV , class SK , class KH , bool TS>

uint32_t cachemere::Cache< K, V, I, E, C, SV, SK, KH, TS >::statistics_window_size

inline

Get the size of the sliding window used for computing statistics.

Returns: The size of the statistics sliding window.

◆ statistics_window_size() [2/2]

template<class K , class V , template< class, class, class > class I, template< class, class, class > class E, template< class, class, class > class C, class SV , class SK , class KH , bool TS>

void cachemere::Cache< K, V, I, E, C, SV, SK, KH, TS >::statistics_window_size ( uint32_t window_size )

inline

Set the size of the sliding window used for computing statistics.

Warning: This will reset the access log, so cache accesses made prior to calling this will not be counted in the statistics.

Parameters

window_size The desired statistics window size.

◆ swap()

template<class K , class V , template< class, class, class > class I, template< class, class, class > class E, template< class, class, class > class C, class SV , class SK , class KH , bool TS>

void cachemere::Cache< K, V, I, E, C, SV, SK, KH, TS >::swap ( CacheType & other )

noexcept

Swaps the current cache with another cache of the same type.

Calls std::terminate if the cache runs in thread-safe mode and an exception is thrown while locking its mutex.

Parameters

other The cache to swap this instance with.

◆ update_constraint()

template<class K , class V , template< class, class, class > class I, template< class, class, class > class E, template< class, class, class > class C, class SV , class SK , class KH , bool TS>

template<typename... Args>

void cachemere::Cache< K, V, I, E, C, SV, SK, KH, TS >::update_constraint ( Args... args )

Update the cache constraint.

Forwards the update to the constraint and evicts items from the cache until the constraint is satisfied.

Parameters

args	Arguments to forward to the `Constraint::update()` .

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

include/cachemere/cache.h
include/cachemere/cache.hpp

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Cache() [1/2]

◆ Cache() [2/2]

Member Function Documentation

◆ byte_hit_rate()

◆ collect_into()

◆ contains()

◆ find()

◆ for_each()

◆ hit_rate()

◆ insert()

◆ number_of_items()

◆ remove()

◆ retain()

◆ statistics_window_size() [1/2]

◆ statistics_window_size() [2/2]

◆ swap()

◆ update_constraint()