persistent-cache-cpp
|
A persistent cache of key-value pairs and metadata of user-defined type. More...
#include <core/persistent_cache.h>
Classes | |
struct | Data |
Simple pair of value and metadata. More... | |
Public Types | |
typedef std::unique_ptr< PersistentCache< K, V, M > > | UPtr |
Typedefs for nullable keys, values, and metadata. | |
typedef Optional< K > | OptionalKey |
Convenience typedefs for returning nullable values. | |
typedef Optional< V > | OptionalValue |
typedef Optional< M > | OptionalMetadata |
typedef Optional< Data > | OptionalData |
Public Member Functions | |
Copy and Assignment | |
PersistentCache (PersistentCache const &)=delete | |
PersistentCache & | operator= (PersistentCache const &)=delete |
PersistentCache (PersistentCache &&)=default | |
PersistentCache & | operator= (PersistentCache &&)=default |
~PersistentCache ()=default | |
Accessors | |
OptionalValue | get (K const &key) const |
Returns the value of an entry in the cache, provided the entry has not expired. | |
OptionalData | get_data (K const &key) const |
Returns the data for an entry in the cache, provided the entry has not expired. | |
OptionalMetadata | get_metadata (K const &key) const |
Returns the metadata for an entry in the cache, provided the entry has not expired. | |
bool | contains_key (K const &key) const |
Tests if an (unexpired) entry is in the cache. | |
int64_t | size () const noexcept |
Returns the number of entries in the cache. | |
int64_t | size_in_bytes () const noexcept |
Returns the number of bytes consumed by entries in the cache. | |
int64_t | max_size_in_bytes () const noexcept |
Returns the maximum size of the cache in bytes. | |
int64_t | disk_size_in_bytes () const |
Returns an estimate of the disk space consumed by the cache. | |
CacheDiscardPolicy | discard_policy () const noexcept |
Returns the discard policy of the cache. | |
PersistentCacheStats | stats () const |
Returns statistics for the cache. | |
Static Public Member Functions | |
Creation Methods | |
static UPtr | open (std::string const &cache_path, int64_t max_size_in_bytes, CacheDiscardPolicy policy) |
Creates or opens a PersistentCache. | |
static UPtr | open (std::string const &cache_path) |
Opens an existing PersistentCache. | |
Modifiers | |
typedef std::function< void(K const &key, PersistentCache< K, V, M > &cache)> | Loader |
Function called by the cache to load an entry after a cache miss. | |
bool | put (K const &key, V const &value, std::chrono::time_point< std::chrono::system_clock > expiry_time=std::chrono::system_clock::time_point()) |
Adds or updates an entry. If V = std::string , the method is also overloaded to to accept char const* and size . | |
bool | put (K const &key, V const &value, M const &metadata, std::chrono::time_point< std::chrono::system_clock > expiry_time=std::chrono::system_clock::time_point()) |
Adds or updates an entry and its metadata. If 'V' or M = std::string , the method is also overloaded to accept char const* and size . | |
OptionalValue | get_or_put (K const &key, Loader const &load_func) |
Atomically retrieves or stores a cache entry. | |
OptionalData | get_or_put_data (K const &key, Loader const &load_func) |
Atomically retrieves or stores a cache entry. | |
bool | put_metadata (K const &key, M const &metadata) |
Adds or replaces the metadata for an entry. If M = std::string , an overload that accepts const char* and size is provided as well. | |
OptionalValue | take (K const &key) |
Removes an entry and returns its value. | |
OptionalData | take_data (K const &key) |
Removes an entry and returns its value and metadata. | |
bool | invalidate (K const &key) |
Removes an entry and its associated metadata (if any). | |
void | invalidate (std::vector< K > const &keys) |
Atomically removes the specified entries from the cache. | |
template<typename It > | |
void | invalidate (It begin, It end) |
Atomically removes the specified entries from the cache. | |
void | invalidate (std::initializer_list< K > const &keys) |
Atomically removes the specified entries from the cache. | |
void | invalidate () |
Deletes all entries from the cache. | |
bool | touch (K const &key, std::chrono::time_point< std::chrono::system_clock > expiry_time=std::chrono::system_clock::time_point()) |
Updates the access time of an entry. | |
void | clear_stats () |
Resets all statistics counters. | |
void | resize (int64_t size_in_bytes) |
Changes the maximum size of the cache. | |
void | trim_to (int64_t used_size_in_bytes) |
Expires entries. | |
void | compact () |
Compacts the database. | |
Monitoring cache activity | |
typedef std::function< void(K const &key, CacheEvent ev, PersistentCacheStats const &stats)> | EventCallback |
The type of a handler function. | |
void | set_handler (CacheEvent events, EventCallback cb) |
Installs a handler for one or more events. | |
A persistent cache of key-value pairs and metadata of user-defined type.
K
, V
, and M
are the key type, value type, and metadata type, respectively.
In order to use the cache with custom types (other than std::string
), you must provide methods to encode the type to string
, and decode from string
back to the type.
For example, suppose we have the following structure that we want to use as the key type of the cache:
In order to use the cache with the Person
struct as the key, you must specialize the CacheCodec struct in namespace core
:
For this example, it is convenient to stream the age first because this guarantees that decode()
will work correctly even if the name contains a space. The order in which you stream the fields does not matter, only that (for custom key types) the string representation of each value is unique.
With these two methods defined, we can now use the cache with Person
instances as the key. For example:
Running this code produces the output:
You can use a custom type for the cache's value and metadata as well by simply providing CacheCodec specializations as needed.
typedef std::function<void(K const& key, CacheEvent ev, PersistentCacheStats const& stats)> core::PersistentCache< K, V, M >::EventCallback |
The type of a handler function.
typedef std::function<void(K const& key, PersistentCache<K, V, M>& cache)> core::PersistentCache< K, V, M >::Loader |
Function called by the cache to load an entry after a cache miss.
typedef Optional<Data> core::PersistentCache< K, V, M >::OptionalData |
typedef Optional<K> core::PersistentCache< K, V, M >::OptionalKey |
Convenience typedefs for returning nullable values.
OptionalKey
, OptionalValue
, and OptionalMetadata
in your code in preference to boost::optional
. This will ease an eventual transition to std::optional
. typedef Optional<M> core::PersistentCache< K, V, M >::OptionalMetadata |
typedef Optional<V> core::PersistentCache< K, V, M >::OptionalValue |
typedef std::unique_ptr<PersistentCache<K, V, M> > core::PersistentCache< K, V, M >::UPtr |
Convenience typedef for the return type of open().
|
delete |
|
default |
|
default |
Destroys the instance.
The destructor compacts the database. This ensures that, while a cache is not in use, it comsumes as little disk space as possible.
void core::PersistentCache< K, V, M >::clear_stats | ( | ) |
Resets all statistics counters.
void core::PersistentCache< K, V, M >::compact | ( | ) |
Compacts the database.
bool core::PersistentCache< K, V, M >::contains_key | ( | K const & | key | ) | const |
Tests if an (unexpired) entry is in the cache.
|
noexcept |
Returns the discard policy of the cache.
int64_t core::PersistentCache< K, V, M >::disk_size_in_bytes | ( | ) | const |
Returns an estimate of the disk space consumed by the cache.
OptionalValue core::PersistentCache< K, V, M >::get | ( | K const & | key | ) | const |
Returns the value of an entry in the cache, provided the entry has not expired.
OptionalData core::PersistentCache< K, V, M >::get_data | ( | K const & | key | ) | const |
Returns the data for an entry in the cache, provided the entry has not expired.
OptionalMetadata core::PersistentCache< K, V, M >::get_metadata | ( | K const & | key | ) | const |
Returns the metadata for an entry in the cache, provided the entry has not expired.
OptionalValue core::PersistentCache< K, V, M >::get_or_put | ( | K const & | key, |
Loader const & | load_func | ||
) |
Atomically retrieves or stores a cache entry.
OptionalData core::PersistentCache< K, V, M >::get_or_put_data | ( | K const & | key, |
Loader const & | load_func | ||
) |
Atomically retrieves or stores a cache entry.
void core::PersistentCache< K, V, M >::invalidate | ( | ) |
Deletes all entries from the cache.
void core::PersistentCache< K, V, M >::invalidate | ( | It | begin, |
It | end | ||
) |
Atomically removes the specified entries from the cache.
bool core::PersistentCache< K, V, M >::invalidate | ( | K const & | key | ) |
Removes an entry and its associated metadata (if any).
void core::PersistentCache< K, V, M >::invalidate | ( | std::initializer_list< K > const & | keys | ) |
Atomically removes the specified entries from the cache.
void core::PersistentCache< K, V, M >::invalidate | ( | std::vector< K > const & | keys | ) |
Atomically removes the specified entries from the cache.
|
noexcept |
Returns the maximum size of the cache in bytes.
|
static |
Opens an existing PersistentCache.
|
static |
Creates or opens a PersistentCache.
|
default |
|
delete |
bool core::PersistentCache< K, V, M >::put | ( | K const & | key, |
V const & | value, | ||
M const & | metadata, | ||
std::chrono::time_point< std::chrono::system_clock > | expiry_time = std::chrono::system_clock::time_point() |
||
) |
Adds or updates an entry and its metadata. If 'V' or M
= std::string
, the method is also overloaded to accept char const*
and size
.
bool core::PersistentCache< K, V, M >::put | ( | K const & | key, |
V const & | value, | ||
std::chrono::time_point< std::chrono::system_clock > | expiry_time = std::chrono::system_clock::time_point() |
||
) |
Adds or updates an entry. If V
= std::string
, the method is also overloaded to to accept char const*
and size
.
bool core::PersistentCache< K, V, M >::put_metadata | ( | K const & | key, |
M const & | metadata | ||
) |
Adds or replaces the metadata for an entry. If M
= std::string
, an overload that accepts const char*
and size
is provided as well.
void core::PersistentCache< K, V, M >::resize | ( | int64_t | size_in_bytes | ) |
Changes the maximum size of the cache.
void core::PersistentCache< K, V, M >::set_handler | ( | CacheEvent | events, |
EventCallback | cb | ||
) |
Installs a handler for one or more events.
|
noexcept |
Returns the number of entries in the cache.
|
noexcept |
Returns the number of bytes consumed by entries in the cache.
PersistentCacheStats core::PersistentCache< K, V, M >::stats | ( | ) | const |
Returns statistics for the cache.
OptionalValue core::PersistentCache< K, V, M >::take | ( | K const & | key | ) |
Removes an entry and returns its value.
OptionalData core::PersistentCache< K, V, M >::take_data | ( | K const & | key | ) |
Removes an entry and returns its value and metadata.
bool core::PersistentCache< K, V, M >::touch | ( | K const & | key, |
std::chrono::time_point< std::chrono::system_clock > | expiry_time = std::chrono::system_clock::time_point() |
||
) |
Updates the access time of an entry.
void core::PersistentCache< K, V, M >::trim_to | ( | int64_t | used_size_in_bytes | ) |
Expires entries.