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

persistent-cache-cpp

Classes | Public Types | List of all members
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. More...
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. More...
OptionalData | get_data (K const &key) const
| Returns the data for an entry in the cache, provided the entry has not expired. More...
OptionalMetadata | get_metadata (K const &key) const
| Returns the metadata for an entry in the cache, provided the entry has not expired. More...
bool | contains_key (K const &key) const
| Tests if an (unexpired) entry is in the cache. More...
int64_t | size () const noexcept
| Returns the number of entries in the cache. More...
int64_t | size_in_bytes () const noexcept
| Returns the number of bytes consumed by entries in the cache. More...
int64_t | max_size_in_bytes () const noexcept
| Returns the maximum size of the cache in bytes. More...
int64_t | disk_size_in_bytes () const
| Returns an estimate of the disk space consumed by the cache. More...
CacheDiscardPolicy | discard_policy () const noexcept
| Returns the discard policy of the cache. More...
PersistentCacheStats | stats () const
| Returns statistics for the cache. More...

## 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. More...
static UPtr | open (std::string const &cache_path)
| Opens an existing PersistentCache. More...

## 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. More...
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`. More...
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`. More...
OptionalValue | get_or_put (K const &key, Loader const &load_func)
| Atomically retrieves or stores a cache entry. More...
OptionalData | get_or_put_data (K const &key, Loader const &load_func)
| Atomically retrieves or stores a cache entry. More...
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. More...
OptionalValue | take (K const &key)
| Removes an entry and returns its value. More...
OptionalData | take_data (K const &key)
| Removes an entry and returns its value and metadata. More...
bool | invalidate (K const &key)
| Removes an entry and its associated metadata (if any). More...
void | invalidate (std::vector< K > const &keys)
| Atomically removes the specified entries from the cache. More...
template<typename It >
void | invalidate (It begin, It end)
| Atomically removes the specified entries from the cache. More...
void | invalidate (std::initializer_list< K > const &keys)
| Atomically removes the specified entries from the cache. More...
void | invalidate ()
| Deletes all entries from the cache. More...
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. More...
void | clear_stats ()
| Resets all statistics counters. More...
void | resize (int64_t size_in_bytes)
| Changes the maximum size of the cache. More...
void | trim_to (int64_t used_size_in_bytes)
| Expires entries. More...
void | compact ()
| Compacts the database. More...

## Monitoring cache activity
typedef std::function< void(K const &key, CacheEvent ev, PersistentCacheStats const &stats)> | EventCallback
| The type of a handler function. More...
void | set_handler (CacheEvent events, EventCallback cb)
| Installs a handler for one or more events. More...

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

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.
using PersonCache = core::PersistentCache<Person, string>;
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);

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:

- /build/persistent-cache-cpp-git/src/persistent-cache-cpp/include/core/persistent_cache.h

core::CacheCodec::encode
static std::string encode(T const &value)
Converts a value of custom type T into a string.
core::CacheCodec::decode
static T decode(std::string const &s)
Converts a string into a value of custom type T.
core
Top-level namespace for core functionality.
Definition: cache_codec.h:24
core::PersistentCache
A persistent cache of key-value pairs and metadata of user-defined type.
Definition: persistent_cache.h:119