persistent-cache-cpp
core::PersistentCache< K, V, M > Class Template Reference

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< DataOptionalData
 

Public Member Functions

Copy and Assignment
 PersistentCache (PersistentCache const &)=delete
 
PersistentCacheoperator= (PersistentCache const &)=delete
 
 PersistentCache (PersistentCache &&)=default
 
PersistentCacheoperator= (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.
 

Detailed Description

template<typename K, typename V, typename M = std::string>
class core::PersistentCache< K, V, M >

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.

Note
This template is a simple type adapter that forwards to core::PersistentStringCache. See the documentation there for details on cache operations and semantics.

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:

struct Person
{
string name;
int age;
};

In order to use the cache with the Person struct as the key, you must specialize the CacheCodec struct in namespace core:

namespace core // Specializations must be placed into namespace core.
{
template <>
string CacheCodec<Person>::encode(Person const& p)
{
ostringstream s;
s << p.age << ' ' << p.name;
return s.str();
}
template <>
Person CacheCodec<Person>::decode(string const& str)
{
istringstream s;
Person p;
s >> p.age >> p.name;
return p;
}
} // namespace core
Top-level namespace for core functionality.
Definition cache_codec.h:24
Definition cache_codec.h:39

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:

// Custom cache using Person as the key, and string as the value and metadata.
auto c = PersonCache::open("my_cache", 1024 * 1024 * 1024, CacheDiscardPolicy::LRU_only);
Person bjarne{"Bjarne Stroustrup", 65};
c->put(bjarne, "C++ inventor");
auto value = c->get(bjarne);
if (value)
{
cout << bjarne.name << ": " << *value << endl;
}
Person person{"no such person", 0};
value = c->get(person);
assert(!value);
A persistent cache of key-value pairs and metadata of user-defined type.
Definition persistent_cache.h:119

Running this code produces the output:

Bjarne Stroustrup: C++ inventor

You can use a custom type for the cache's value and metadata as well by simply providing CacheCodec specializations as needed.

See also
core::CacheCodec
core::PersistentStringCache

Member Typedef Documentation

◆ EventCallback

template<typename K , typename V , typename M = std::string>
typedef std::function<void(K const& key, CacheEvent ev, PersistentCacheStats const& stats)> core::PersistentCache< K, V, M >::EventCallback

The type of a handler function.

◆ Loader

template<typename K , typename V , typename M = std::string>
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.

◆ OptionalData

template<typename K , typename V , typename M = std::string>
typedef Optional<Data> core::PersistentCache< K, V, M >::OptionalData

◆ OptionalKey

template<typename K , typename V , typename M = std::string>
typedef Optional<K> core::PersistentCache< K, V, M >::OptionalKey

Convenience typedefs for returning nullable values.

Note
You should use OptionalKey, OptionalValue, and OptionalMetadata in your code in preference to boost::optional. This will ease an eventual transition to std::optional.

◆ OptionalMetadata

template<typename K , typename V , typename M = std::string>
typedef Optional<M> core::PersistentCache< K, V, M >::OptionalMetadata

◆ OptionalValue

template<typename K , typename V , typename M = std::string>
typedef Optional<V> core::PersistentCache< K, V, M >::OptionalValue

◆ UPtr

template<typename K , typename V , typename M = std::string>
typedef std::unique_ptr<PersistentCache<K, V, M> > core::PersistentCache< K, V, M >::UPtr

Convenience typedef for the return type of open().

Constructor & Destructor Documentation

◆ PersistentCache() [1/2]

template<typename K , typename V , typename M = std::string>
core::PersistentCache< K, V, M >::PersistentCache ( PersistentCache< K, V, M > const &  )
delete

◆ PersistentCache() [2/2]

template<typename K , typename V , typename M = std::string>
core::PersistentCache< K, V, M >::PersistentCache ( PersistentCache< K, V, M > &&  )
default

◆ ~PersistentCache()

template<typename K , typename V , typename M = std::string>
core::PersistentCache< K, V, M >::~PersistentCache ( )
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.

Member Function Documentation

◆ clear_stats()

template<typename K , typename V , typename M = std::string>
void core::PersistentCache< K, V, M >::clear_stats ( )

Resets all statistics counters.

◆ compact()

template<typename K , typename V , typename M = std::string>
void core::PersistentCache< K, V, M >::compact ( )

Compacts the database.

◆ contains_key()

template<typename K , typename V , typename M = std::string>
bool core::PersistentCache< K, V, M >::contains_key ( K const &  key) const

Tests if an (unexpired) entry is in the cache.

◆ discard_policy()

template<typename K , typename V , typename M = std::string>
CacheDiscardPolicy core::PersistentCache< K, V, M >::discard_policy ( ) const
noexcept

Returns the discard policy of the cache.

◆ disk_size_in_bytes()

template<typename K , typename V , typename M = std::string>
int64_t core::PersistentCache< K, V, M >::disk_size_in_bytes ( ) const

Returns an estimate of the disk space consumed by the cache.

◆ get()

template<typename K , typename V , typename M = std::string>
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.

◆ get_data()

template<typename K , typename V , typename M = std::string>
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.

◆ get_metadata()

template<typename K , typename V , typename M = std::string>
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.

◆ get_or_put()

template<typename K , typename V , typename M = std::string>
OptionalValue core::PersistentCache< K, V, M >::get_or_put ( K const &  key,
Loader const &  load_func 
)

Atomically retrieves or stores a cache entry.

◆ get_or_put_data()

template<typename K , typename V , typename M = std::string>
OptionalData core::PersistentCache< K, V, M >::get_or_put_data ( K const &  key,
Loader const &  load_func 
)

Atomically retrieves or stores a cache entry.

◆ invalidate() [1/5]

template<typename K , typename V , typename M = std::string>
void core::PersistentCache< K, V, M >::invalidate ( )

Deletes all entries from the cache.

◆ invalidate() [2/5]

template<typename K , typename V , typename M = std::string>
template<typename It >
void core::PersistentCache< K, V, M >::invalidate ( It  begin,
It  end 
)

Atomically removes the specified entries from the cache.

◆ invalidate() [3/5]

template<typename K , typename V , typename M = std::string>
bool core::PersistentCache< K, V, M >::invalidate ( K const &  key)

Removes an entry and its associated metadata (if any).

◆ invalidate() [4/5]

template<typename K , typename V , typename M = std::string>
void core::PersistentCache< K, V, M >::invalidate ( std::initializer_list< K > const &  keys)

Atomically removes the specified entries from the cache.

◆ invalidate() [5/5]

template<typename K , typename V , typename M = std::string>
void core::PersistentCache< K, V, M >::invalidate ( std::vector< K > const &  keys)

Atomically removes the specified entries from the cache.

◆ max_size_in_bytes()

template<typename K , typename V , typename M = std::string>
int64_t core::PersistentCache< K, V, M >::max_size_in_bytes ( ) const
noexcept

Returns the maximum size of the cache in bytes.

◆ open() [1/2]

template<typename K , typename V , typename M = std::string>
static UPtr core::PersistentCache< K, V, M >::open ( std::string const &  cache_path)
static

Opens an existing PersistentCache.

◆ open() [2/2]

template<typename K , typename V , typename M = std::string>
static UPtr core::PersistentCache< K, V, M >::open ( std::string const &  cache_path,
int64_t  max_size_in_bytes,
CacheDiscardPolicy  policy 
)
static

Creates or opens a PersistentCache.

◆ operator=() [1/2]

template<typename K , typename V , typename M = std::string>
PersistentCache & core::PersistentCache< K, V, M >::operator= ( PersistentCache< K, V, M > &&  )
default

◆ operator=() [2/2]

template<typename K , typename V , typename M = std::string>
PersistentCache & core::PersistentCache< K, V, M >::operator= ( PersistentCache< K, V, M > const &  )
delete

◆ put() [1/2]

template<typename K , typename V , typename M = std::string>
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.

◆ put() [2/2]

template<typename K , typename V , typename M = std::string>
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.

◆ put_metadata()

template<typename K , typename V , typename M = std::string>
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.

◆ resize()

template<typename K , typename V , typename M = std::string>
void core::PersistentCache< K, V, M >::resize ( int64_t  size_in_bytes)

Changes the maximum size of the cache.

◆ set_handler()

template<typename K , typename V , typename M = std::string>
void core::PersistentCache< K, V, M >::set_handler ( CacheEvent  events,
EventCallback  cb 
)

Installs a handler for one or more events.

◆ size()

template<typename K , typename V , typename M = std::string>
int64_t core::PersistentCache< K, V, M >::size ( ) const
noexcept

Returns the number of entries in the cache.

◆ size_in_bytes()

template<typename K , typename V , typename M = std::string>
int64_t core::PersistentCache< K, V, M >::size_in_bytes ( ) const
noexcept

Returns the number of bytes consumed by entries in the cache.

◆ stats()

template<typename K , typename V , typename M = std::string>
PersistentCacheStats core::PersistentCache< K, V, M >::stats ( ) const

Returns statistics for the cache.

◆ take()

template<typename K , typename V , typename M = std::string>
OptionalValue core::PersistentCache< K, V, M >::take ( K const &  key)

Removes an entry and returns its value.

◆ take_data()

template<typename K , typename V , typename M = std::string>
OptionalData core::PersistentCache< K, V, M >::take_data ( K const &  key)

Removes an entry and returns its value and metadata.

◆ touch()

template<typename K , typename V , typename M = std::string>
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.

◆ trim_to()

template<typename K , typename V , typename M = std::string>
void core::PersistentCache< K, V, M >::trim_to ( int64_t  used_size_in_bytes)

Expires entries.


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