Cachemere
Modular Caching Library for C++
Public Types | Public Member Functions | Protected Member Functions | List of all members
cachemere::Cache< Key, Value, InsertionPolicy, EvictionPolicy, ConstraintPolicy, MeasureValue, MeasureKey, KeyHash, ThreadSafe > Class Template Reference

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
KeyThe type of the key used for retrieving items.
ValueThe type of the items stored in the cache.
InsertionPolicyA template parameterized by Key, KeyHash, and Value implementing the insertion policy interface.
EvictionPolicyA template parameterized by Key KeyHash, and Value implementing the eviction policy interface.
ConstraintPolicyA template parameterized by Key KeyHash, and Value implementing the constraint policy interface.
MeasureValueA functor returning the size of a cache value.
MeasureKeyA functor returning the size of a cache key.
KeyHashA default-constructible callable type returning a hash of a key. Defaults to absl::Hash<Key>.
ThreadSafeWhether 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
argsArguments 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
collectionThe collection to use to initialize the cache - must be a collection of pairs.
argsTuple 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
containerThe 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
KeyViewThe type of the key used for retrieving items.
Parameters
keyThe 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
KeyViewThe type of the key used for retrieving items.
Parameters
keyThe 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 ( unary_function)

Apply a function to all objects in cache.

Parameters
unary_functionThe 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
keyThe key to associate with the value.
valueThe 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
keyThe 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 ( predicate_fn)

Retain all objects matching a predicate.

Removes all items for which predicate_fn returns false.

Parameters
predicate_fnThe predicate function.
Template Parameters
PThe 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_sizeThe 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
otherThe 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
argsArguments to forward to the Constraint::update() .

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