persistent-cache-cpp
|
A cache of key-value pairs with persistent storage. More...
#include <core/persistent_string_cache.h>
Classes | |
struct | Data |
Simple pair of value and metadata. More... | |
Public Types | |
typedef std::unique_ptr< PersistentStringCache > | UPtr |
Public Member Functions | |
Copy and Assignment | |
Cache instances are not copyable, but can be moved.
| |
PersistentStringCache (PersistentStringCache const &)=delete | |
PersistentStringCache & | operator= (PersistentStringCache const &)=delete |
PersistentStringCache (PersistentStringCache &&) | |
PersistentStringCache & | operator= (PersistentStringCache &&) |
~PersistentStringCache () | |
Accessors | |
Optional< std::string > | get (std::string const &key) const |
Returns the value of an entry in the cache, provided the entry has not expired. | |
Optional< Data > | get_data (std::string const &key) const |
Returns the data for an entry in the cache, provided the entry has not expired. | |
Optional< std::string > | get_metadata (std::string const &key) const |
Returns the metadata for an entry in the cache, provided the entry has not expired. | |
bool | contains_key (std::string 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 PersistentStringCache. | |
static UPtr | open (std::string const &cache_path) |
Opens an existing PersistentStringCache. | |
Modifiers | |
typedef std::function< void(std::string const &key, PersistentStringCache &cache)> | Loader |
Function called by the cache to load an entry after a cache miss. | |
bool | put (std::string const &key, std::string const &value, std::chrono::time_point< std::chrono::system_clock > expiry_time=std::chrono::system_clock::time_point()) |
Adds or updates an entry. | |
bool | put (std::string const &key, char const *value, int64_t size, std::chrono::time_point< std::chrono::system_clock > expiry_time=std::chrono::system_clock::time_point()) |
Adds or updates an entry. | |
bool | put (std::string const &key, std::string const &value, std::string 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. | |
bool | put (std::string const &key, char const *value, int64_t value_size, char const *metadata, int64_t metadata_size, std::chrono::time_point< std::chrono::system_clock > expiry_time=std::chrono::system_clock::time_point()) |
Adds or updates an entry and its metadata. | |
Optional< std::string > | get_or_put (std::string const &key, Loader const &load_func) |
Atomically retrieves or stores a cache entry. | |
Optional< Data > | get_or_put_data (std::string const &key, Loader const &load_func) |
Atomically retrieves or stores a cache entry. | |
bool | put_metadata (std::string const &key, std::string const &metadata) |
Adds or replaces the metadata for an entry. | |
bool | put_metadata (std::string const &key, char const *metadata, int64_t size) |
Adds or replaces the metadata for an entry. | |
Optional< std::string > | take (std::string const &key) |
Removes an entry and returns its value. | |
Optional< Data > | take_data (std::string const &key) |
Removes an entry and returns its value and metadata. | |
bool | invalidate (std::string const &key) |
Removes an entry and its associated metadata (if any). | |
void | invalidate (std::vector< std::string > 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< std::string > const &keys) |
Atomically removes the specified entries from the cache. | |
void | invalidate () |
Deletes all entries from the cache. | |
bool | touch (std::string 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 | |
The cache allows you to register one or more callback functions that are called when the cache contents change.
| |
typedef std::function< void(std::string 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 cache of key-value pairs with persistent storage.
PersistentStringCache provides a cache of string
key-value pairs with a backing store. It is intended for caching arbitrary (possibly large) amounts of data, such as might be needed by a web browser cache.
See Overview for a more detailed description.
Typical use looks something like this:
typedef std::function<void(std::string const& key, CacheEvent ev, PersistentCacheStats const& stats)> core::PersistentStringCache::EventCallback |
The type of a handler function.
key | The key of the entry. |
ev | The event type. |
stats | The cache statistics. Note that the stats parameter reflects the state of the cache after the corresponding event. For example, for a Put event, stats.size_in_bytes() includes the size of the added entry. |
typedef std::function<void(std::string const& key, PersistentStringCache& cache)> core::PersistentStringCache::Loader |
Function called by the cache to load an entry after a cache miss.
typedef std::unique_ptr<PersistentStringCache> core::PersistentStringCache::UPtr |
Convenience typedef for the return type of open().
|
delete |
core::PersistentStringCache::PersistentStringCache | ( | PersistentStringCache && | ) |
core::PersistentStringCache::~PersistentStringCache | ( | ) |
Destroys the instance.
void core::PersistentStringCache::clear_stats | ( | ) |
Resets all statistics counters.
void core::PersistentStringCache::compact | ( | ) |
Compacts the database.
This operation compacts the database to consume as little disk space as possible. Note that this operation can be slow. (Compacting a 100 MB cache can take around ten seconds on a machine with a spinning-platter disk.)
bool core::PersistentStringCache::contains_key | ( | std::string const & | key | ) | const |
Tests if an (unexpired) entry is in the cache.
key | The key for the entry. |
true
if the entry is in the cache; false
otherwise. invalid_argument | key is the empty string. |
|
noexcept |
Returns the discard policy of the cache.
lru_only
or lru_ttl
). int64_t core::PersistentStringCache::disk_size_in_bytes | ( | ) | const |
Returns an estimate of the disk space consumed by the cache.
Optional< std::string > core::PersistentStringCache::get | ( | std::string const & | key | ) | const |
Returns the value of an entry in the cache, provided the entry has not expired.
key | The key for the entry. |
invalid_argument | key is the empty string. |
Returns the data for an entry in the cache, provided the entry has not expired.
key | The key for the entry. |
Data::metadata
is set to the empty string. invalid_argument | key is the empty string. |
Optional< std::string > core::PersistentStringCache::get_metadata | ( | std::string const & | key | ) | const |
Returns the metadata for an entry in the cache, provided the entry has not expired.
key | The key for the entry. |
invalid_argument | key is the empty string. |
Optional< std::string > core::PersistentStringCache::get_or_put | ( | std::string const & | key, |
Loader const & | load_func | ||
) |
Atomically retrieves or stores a cache entry.
get_or_put
attempts to retrieve the value of a (non-expired) entry. If the entry can be found, it returns its value. Otherwise, it calls load_func
, which is expected to add the entry to the cache. If the load function succeeds in adding the entry, the value added by the load function is returned. The load function is called by the application thread.
runtime_error | The load function threw an exception. |
put
methods to add a new entry for the provided key. Calling any other method on the cache from within the load function causes undefined behavior.Optional< Data > core::PersistentStringCache::get_or_put_data | ( | std::string const & | key, |
Loader const & | load_func | ||
) |
Atomically retrieves or stores a cache entry.
get_or_put
attempts to retrieve the value and metadata of a (non-expired) entry. If the entry can be found, it returns its data. Otherwise, it calls load_func
, which is expected to add the entry to the cache. If the load function succeeds in adding the entry, the data added by the load function is returned. The load function is called by the application thread.
runtime_error | The load function threw an exception. |
put
methods to add a new entry for the provided key. Calling any other method on the cache from within the load function causes undefined behavior.void core::PersistentStringCache::invalidate | ( | ) |
Deletes all entries from the cache.
This operation completely empties the cache.
|
inline |
Atomically removes the specified entries from the cache.
begin | Iterator to the first key for the entries to be removed. |
end | Iterator to the one-beyond-the-last key for the entries to be removed. |
If the iterator range is empty, this operation is a no-op. If one or more keys are empty or specify non-existent entries, they are ignored.
void core::PersistentStringCache::invalidate | ( | std::initializer_list< std::string > const & | keys | ) |
Atomically removes the specified entries from the cache.
keys | The keys for the entries to be removed. If keys is empty, this operation is a no-op. If one or more keys are empty or specify non-existent entries, they are ignored. |
bool core::PersistentStringCache::invalidate | ( | std::string const & | key | ) |
Removes an entry and its associated metadata (if any).
If a (non-expired) entry with the given key can be found, it is removed from the cache.
true
if the entry was removed; false
if the entry could not be found or was expired. invalid_argument | key is the empty string. |
void core::PersistentStringCache::invalidate | ( | std::vector< std::string > const & | keys | ) |
Atomically removes the specified entries from the cache.
keys | A vector of keys for the entries to be removed. If the vector is empty, this operation is a no-op. If one or more keys are empty or specify non-existent entries, they are ignored. |
|
noexcept |
Returns the maximum size of the cache in bytes.
|
static |
Opens an existing PersistentStringCache.
cache_path | The path to a directory containing the existing cache. |
unique_ptr
to the instance.
|
static |
Creates or opens a PersistentStringCache.
If no cache exists on disk, it will be created; otherwise, the pre-existing cache contents are used.
An existing cache can be opened only if max_size_in_bytes
and policy
have the same values they had when the cache was last closed.
cache_path | The path to a directory in which to store the cache. The contents of this directory are exlusively owned by the cache; do not create additional files or directories there. The directory need not exist when creating a new cache. |
max_size_in_bytes | The maximum size in bytes for the cache. |
policy | The discard policy for the cache (lru_only or lru_ttl ). The discard policy cannot be changed once a cache has been created. |
The size of an entry is the sum of the sizes of its key, value, and metadata. The maximum size of the cache is the sum of the sizes of all its entries.
unique_ptr
to the instance. invalid_argument | max_size_in_bytes is < 1. |
logic_error | max_size_in_bytes or policy do not match the settings of a pre-existing cache. |
PersistentStringCache & core::PersistentStringCache::operator= | ( | PersistentStringCache && | ) |
|
delete |
bool core::PersistentStringCache::put | ( | std::string const & | key, |
char const * | value, | ||
int64_t | size, | ||
std::chrono::time_point< std::chrono::system_clock > | expiry_time = std::chrono::system_clock::time_point() |
||
) |
Adds or updates an entry.
If an entry with the given key does not exist in the cache, it is added (possibly evicting a number of expired and/or older entries). If the entry still exists (whether expired or not), it is updated with the new value (and possibly expiry time).
This operation deletes any metadata associated with the entry.
true
if the entry was added or updated. false
if the policy is lru_ttl
and expiry_time
is in the past.key | The key of the entry. |
value | A pointer to the first byte of the value. |
size | The size of the value in bytes. |
expiry_time | The time at which the entry expires. |
invalid_argument | key is the empty string. |
invalid_argument | value is nullptr . |
invalid_argument | size is negative. |
logic_error | The size of the entry exceeds the maximum cache size. |
logic_error | The cache policy is lru_only and a non-infinite expiry time was provided. |
bool core::PersistentStringCache::put | ( | std::string const & | key, |
char const * | value, | ||
int64_t | value_size, | ||
char const * | metadata, | ||
int64_t | metadata_size, | ||
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 an entry with the given key does not exist in the cache, it is added (possibly evicting a number of expired and/or older entries). If the entry still exists (whether expired or not), it is updated with the new value and metadata (and possibly expiry time).
true
if the entry was added or updated. false
if the policy is lru_ttl
and expiry_time
is in the past.key | The key of the entry. |
value | A pointer to the first byte of the value. |
value_size | The size of the value in bytes. |
metadata | A pointer to the first byte of the metadata. |
metadata_size | The size of the metadata in bytes. |
expiry_time | The time at which the entry expires. |
invalid_argument | key is the empty string. |
logic_error | The sum of sizes of the entry and metadata exceeds the maximum cache size. |
logic_error | The cache policy is lru_only and a non-infinite expiry time was provided. |
bool core::PersistentStringCache::put | ( | std::string const & | key, |
std::string const & | value, | ||
std::chrono::time_point< std::chrono::system_clock > | expiry_time = std::chrono::system_clock::time_point() |
||
) |
Adds or updates an entry.
If an entry with the given key does not exist in the cache, it is added (possibly evicting a number of expired and/or older entries). If the entry still exists (whether expired or not), it is updated with the new value (and possibly expiry time).
This operation deletes any metadata associated with the entry.
true
if the entry was added or updated. false
if the policy is lru_ttl
and expiry_time
is in the past.invalid_argument | key is the empty string. |
logic_error | The size of the entry exceeds the maximum cache size. |
logic_error | The cache policy is lru_only and a non-infinite expiry time was provided. |
bool core::PersistentStringCache::put | ( | std::string const & | key, |
std::string const & | value, | ||
std::string 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 an entry with the given key does not exist in the cache, it is added (possibly evicting a number of expired and/or older entries). If the entry still exists (whether expired or not), it is updated with the new value and metadata (and possibly expiry time).
true
if the entry was added or updated. false
if the policy is lru_ttl
and expiry_time
is in the past.invalid_argument | key is the empty string. |
logic_error | The sum of sizes of the entry and metadata exceeds the maximum cache size. |
logic_error | The cache policy is lru_only and a non-infinite expiry time was provided. |
bool core::PersistentStringCache::put_metadata | ( | std::string const & | key, |
char const * | metadata, | ||
int64_t | size | ||
) |
Adds or replaces the metadata for an entry.
If a (non-expired) entry with the given key exists in the cache, its metadata is set to the provided value, replacing any previous metadata.
key | The key of the entry. |
metadata | A pointer to the first byte of the metadata. |
size | The size of the metadata in bytes. |
true
if the metadata was added or updated. false
if the entry could not be found or was expired.invalid_argument | key is the empty string. |
invalid_argument | metadata is nullptr . |
invalid_argument | size is negative. |
logic_error | The new size of the entry would exceed the maximum cache size. |
bool core::PersistentStringCache::put_metadata | ( | std::string const & | key, |
std::string const & | metadata | ||
) |
Adds or replaces the metadata for an entry.
If a (non-expired) entry with the given key exists in the cache, its metadata is set to the provided value, replacing any previous metadata.
true
if the metadata was added or updated. false
if the entry could not be found or was expired.invalid_argument | key is the empty string. |
logic_error | The new size of the entry would exceed the maximum cache size. |
void core::PersistentStringCache::resize | ( | int64_t | size_in_bytes | ) |
Changes the maximum size of the cache.
If size_in_bytes
is greater or equal to max_size_in_bytes(), the cache size is set to size_in_bytes
.
If size_in_bytes
is less than max_size_in_bytes(), the cache discards existing entries until the size falls to (or below) size_in_bytes
and sets the cache size to the new value.
invalid_argument | size_in_bytes is < 1 |
void core::PersistentStringCache::set_handler | ( | CacheEvent | events, |
EventCallback | cb | ||
) |
Installs a handler for one or more events.
events | A bitwise OR of the event types for which to install the handler. To install a handler for all events, you can use core::AllCacheEvents. |
cb | The handler to install. To cancel an existing handler, pass nullptr . |
For example, to install a handler for get
and put
events, you could use:
|
noexcept |
Returns the number of entries in the cache.
|
noexcept |
Returns the number of bytes consumed by entries in the cache.
PersistentCacheStats core::PersistentStringCache::stats | ( | ) | const |
Returns statistics for the cache.
The returned statistics are persistent and are restored the next time an existing cache is opened. Call clear_stats() to explicitly reset the statistics counters and time stamps to zero.
Optional< std::string > core::PersistentStringCache::take | ( | std::string const & | key | ) |
Removes an entry and returns its value.
If a (non-expired) entry with the given key can be found, it is removed from the cache and its value returned.
invalid_argument | key is the empty string. |
Removes an entry and returns its value and metadata.
If a (non-expired) entry with the given key can be found, it is removed from the cache and its data returned. If no metadata exists, Data::metadata
is set to the empty string.
invalid_argument | key is the empty string. |
bool core::PersistentStringCache::touch | ( | std::string 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.
If the entry specified by key
is still in the cache (whether expired or not), it is marked as the most-recently used entry. If the policy is lru_ttl
, the entry's expiry time is updated with the specified time (infinite expiry by default).
true
if the entry was updated; false
if the entry could not be found or expiry_time
is in the past. invalid_argument | key is the empty string. |
logic_error | key is the empty string. |
logic_error | The cache policy is lru_only and a non-infinite expiry time was provided. |
void core::PersistentStringCache::trim_to | ( | int64_t | used_size_in_bytes | ) |
Expires entries.
Expires entries using the cache's expiration policy until the cache size falls to or below used_size_in_bytes
. If used_size_in_bytes
is less than the current cache size, this operation is a no-op.
invalid_argument | used_size_in_bytes is < 0 |
logic_error | used_size_in_bytes is > max_size_in_bytes(). |