Cachemere
Modular Caching Library for C++
|
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) |
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.
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. |
cachemere::Cache< Key, Value, InsertionPolicy, EvictionPolicy, ConstraintPolicy, MeasureValue, MeasureKey, KeyHash, ThreadSafe >::Cache | ( | Args... | args | ) |
Simple constructor.
args | Arguments to forward to the constraint policy constructor. |
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.
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. |
|
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.
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.
container | The container in which to insert the items. |
|
inline |
Check whether a given key is stored in the cache.
KeyView | The type of the key used for retrieving items. |
key | The key whose presence to test. |
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.
KeyView | The type of the key used for retrieving items. |
key | The key to lookup. |
key
is in cache, std::nullopt
otherwise. 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.
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) . |
|
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.
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.
key | The key to associate with the value. |
value | The value to store. |
|
inline |
Get the number of items currently stored in the cache.
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.
key | The key to remove from the cache. |
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.
predicate_fn | The predicate function. |
P | The type of the predicate function. The predicate should have the signature bool fn(const Key& key, const Value& value) . |
|
inline |
Get the size of the sliding window used for computing statistics.
|
inline |
Set the size of the sliding window used for computing statistics.
window_size | The desired statistics window size. |
|
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.
other | The cache to swap this instance with. |
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.
args | Arguments to forward to the Constraint::update() . |