hpx/cache/local_cache.hpp

See Public API for a list of names and headers that are part of the public HPX API.

namespace hpx
namespace util
namespace cache
template<typename Key, typename Entry, typename UpdatePolicy = std::less<Entry>, typename InsertPolicy = policies::always<Entry>, typename CacheStorage = std::map<Key, Entry>, typename Statistics = statistics::no_statistics>
class local_cache
#include <hpx/cache/local_cache.hpp>

The local_cache implements the basic functionality needed for a local (non-distributed) cache.

Template Parameters

  • Key: The type of the keys to use to identify the entries stored in the cache

  • Entry: The type of the items to be held in the cache, must model the CacheEntry concept

  • UpdatePolicy: A (optional) type specifying a (binary) function object used to sort the cache entries based on their ‘age’. The ‘oldest’ entries (according to this sorting criteria) will be discarded first if the maximum capacity of the cache is reached. The default is std::less<Entry>. The function object will be invoked using 2 entry instances of the type Entry. This type must model the UpdatePolicy model.

  • InsertPolicy: A (optional) type specifying a (unary) function object used to allow global decisions whether a particular entry should be added to the cache or not. The default is policies::always, imposing no global insert related criteria on the cache. The function object will be invoked using the entry instance to be inserted into the cache. This type must model the InsertPolicy model.

  • CacheStorage: A (optional) container type used to store the cache items. The container must be an associative and STL compatible container.The default is a std::map<Key, Entry>.

  • Statistics: A (optional) type allowing to collect some basic statistics about the operation of the cache instance. The type must conform to the CacheStatistics concept. The default value is the type statistics::no_statistics which does not collect any numbers, but provides empty stubs allowing the code to compile.

Public Types

template<>
using key_type = Key
template<>
using entry_type = Entry
template<>
using update_policy_type = UpdatePolicy
template<>
using insert_policy_type = InsertPolicy
template<>
using storage_type = CacheStorage
template<>
using statistics_type = Statistics
template<>
using value_type = typename entry_type::value_type
template<>
using size_type = typename storage_type::size_type
template<>
using storage_value_type = typename storage_type::value_type

Public Functions

local_cache(size_type max_size = 0, update_policy_type const &up = update_policy_type(), insert_policy_type const &ip = insert_policy_type())

Construct an instance of a local_cache.

Parameters

  • max_size: [in] The maximal size this cache is allowed to reach any time. The default is zero (no size limitation). The unit of this value is usually determined by the unit of the values returned by the entry’s get_size function.

  • up: [in] An instance of the UpdatePolicy to use for this cache. The default is to use a default constructed instance of the type as defined by the UpdatePolicy template parameter.

  • ip: [in] An instance of the InsertPolicy to use for this cache. The default is to use a default constructed instance of the type as defined by the InsertPolicy template parameter.

local_cache(local_cache &&other)
constexpr size_type size() const

Return current size of the cache.

Return

The current size of this cache instance.

constexpr size_type capacity() const

Access the maximum size the cache is allowed to grow to.

Note

The unit of this value is usually determined by the unit of the return values of the entry’s function entry::get_size.

Return

The maximum size this cache instance is currently allowed to reach. If this number is zero the cache has no limitation with regard to a maximum size.

bool reserve(size_type max_size)

Change the maximum size this cache can grow to.

Return

This function returns true if successful. It returns false if the new max_size is smaller than the current limit and the cache could not be shrunk to the new maximum size.

Parameters

  • max_size: [in] The new maximum size this cache will be allowed to grow to.

bool holds_key(key_type const &k) const

Check whether the cache currently holds an entry identified by the given key.

Note

This function does not call the entry’s function entry::touch. It just checks if the cache contains an entry corresponding to the given key.

Return

This function returns true if the cache holds the referenced entry, otherwise it returns false.

Parameters

  • k: [in] The key for the entry which should be looked up in the cache.

bool get_entry(key_type const &k, key_type &realkey, entry_type &val)

Get a specific entry identified by the given key.

Note

The function will call the entry’s entry::touch function if the value corresponding to the provided key is found in the cache.

Return

This function returns true if the cache holds the referenced entry, otherwise it returns false.

Parameters

  • k: [in] The key for the entry which should be retrieved from the cache.

  • val: [out] If the entry indexed by the key is found in the cache this value on successful return will be a copy of the corresponding entry.

bool get_entry(key_type const &k, entry_type &val)

Get a specific entry identified by the given key.

Note

The function will call the entry’s entry::touch function if the value corresponding to the provided key is found in the cache.

Return

This function returns true if the cache holds the referenced entry, otherwise it returns false.

Parameters

  • k: [in] The key for the entry which should be retrieved from the cache.

  • val: [out] If the entry indexed by the key is found in the cache this value on successful return will be a copy of the corresponding entry.

bool get_entry(key_type const &k, value_type &val)

Get a specific entry identified by the given key.

Note

The function will call the entry’s entry::touch function if the value corresponding to the provided is found in the cache.

Return

This function returns true if the cache holds the referenced entry, otherwise it returns false.

Parameters

  • k: [in] The key for the entry which should be retrieved from the cache

  • val: [out] If the entry indexed by the key is found in the cache this value on successful return will be a copy of the corresponding value.

bool insert(key_type const &k, value_type const &val)

Insert a new element into this cache.

Note

This function invokes both, the insert policy as provided to the constructor and the function entry::insert of the newly constructed entry instance. If either of these functions returns false the key/value pair doesn’t get inserted into the cache and the insert function will return false. Other reasons for this function to fail (return false) are a) the key/value pair is already held in the cache or b) inserting the new value into the cache maxed out its capacity and it was not possible to free any of the existing entries.

Return

This function returns true if the entry has been successfully added to the cache, otherwise it returns false.

Parameters

  • k: [in] The key for the entry which should be added to the cache.

  • value: [in] The value which should be added to the cache.

bool insert(key_type const &k, value_type &&val)
template<typename Entry_, std::enable_if_t<std::is_convertible_v<std::decay_t<Entry_>, entry_type>, int> = 0>
bool insert(key_type const &k, Entry_ &&e)

Insert a new entry into this cache.

Note

This function invokes both, the insert policy as provided to the constructor and the function entry::insert of the provided entry instance. If either of these functions returns false the key/value pair doesn’t get inserted into the cache and the insert function will return false. Other reasons for this function to fail (return false) are a) the key/value pair is already held in the cache or b) inserting the new value into the cache maxed out its capacity and it was not possible to free any of the existing entries.

Return

This function returns true if the entry has been successfully added to the cache, otherwise it returns false.

Parameters

  • k: [in] The key for the entry which should be added to the cache.

  • value: [in] The entry which should be added to the cache.

template<typename Value, std::enable_if_t<std::is_convertible_v<std::decay_t<Value>, value_type>, int> = 0>
bool update(key_type const &k, Value &&val)

Update an existing element in this cache.

Note

The function will call the entry’s entry::touch function if the indexed value is found in the cache.

Note

The difference to the other overload of the insert function is that this overload replaces the cached value only, while the other overload replaces the whole cache entry, updating the cache entry properties.

Return

This function returns true if the entry has been successfully updated, otherwise it returns false. If the entry currently is not held by the cache it is added and the return value reflects the outcome of the corresponding insert operation.

Parameters

  • k: [in] The key for the value which should be updated in the cache.

  • value: [in] The value which should be used as a replacement for the existing value in the cache. Any existing cache entry is not changed except for its value.

template<typename F, typename Value, typename = std::enable_if_t<std::is_convertible_v<std::decay_t<Value>, value_type>>>
bool update_if(key_type const &k, Value &&val, F &&f)

Update an existing element in this cache.

Note

The function will call the entry’s entry::touch function if the indexed value is found in the cache.

Note

The difference to the other overload of the insert function is that this overload replaces the cached value only, while the other overload replaces the whole cache entry, updating the cache entry properties.

Return

This function returns true if the entry has been successfully updated, otherwise it returns false. If the entry currently is not held by the cache it is added and the return value reflects the outcome of the corresponding insert operation.

Parameters

  • k: [in] The key for the value which should be updated in the cache.

  • value: [in] The value which should be used as a replacement for the existing value in the cache. Any existing cache entry is not changed except for its value.

  • f: [in] A callable taking two arguments, k and the key found in the cache (in that order). If f returns true, then the update will continue. If f returns false, then the update will not succeed.

template<typename Entry_, std::enable_if_t<std::is_convertible_v<std::decay_t<Entry_>, entry_type>, int> = 0>
bool update(key_type const &k, Entry_ &&e)

Update an existing entry in this cache.

Note

The function will call the entry’s entry::touch function if the indexed value is found in the cache.

Note

The difference to the other overload of the insert function is that this overload replaces the whole cache entry, while the other overload retplaces the cached value only, leaving the cache entry properties untouched.

Return

This function returns true if the entry has been successfully updated, otherwise it returns false. If the entry currently is not held by the cache it is added and the return value reflects the outcome of the corresponding insert operation.

Parameters

  • k: [in] The key for the entry which should be updated in the cache.

  • value: [in] The entry which should be used as a replacement for the existing entry in the cache. Any existing entry is first removed and then this entry is added.

template<typename Func = policies::always<storage_value_type>>
size_type erase(Func &&ep = Func())

Remove stored entries from the cache for which the supplied function object returns true.

Return

This function returns the overall size of the removed entries (which is the sum of the values returned by the entry::get_size functions of the removed entries).

Parameters

  • ep: [in] This parameter has to be a (unary) function object. It is invoked for each of the entries currently held in the cache. An entry is considered for removal from the cache whenever the value returned from this invocation is true. Even then the entry might not be removed from the cache as its entry::remove function might return false.

size_type erase()

Remove all stored entries from the cache.

Note

All entries are considered for removal, but in the end an entry might not be removed from the cache as its entry::remove function might return false. This function is very useful for instance in conjunction with an entry’s entry::remove function enforcing additional criteria like entry expiration, etc.

Return

This function returns the overall size of the removed entries (which is the sum of the values returned by the entry::get_size functions of the removed entries).

void clear()

Clear the cache.

Unconditionally removes all stored entries from the cache.

constexpr statistics_type const &get_statistics() const

Allow to access the embedded statistics instance.

Return

This function returns a reference to the statistics instance embedded inside this cache

statistics_type &get_statistics()

Protected Functions

bool free_space(long num_free)

Private Types

template<>
using iterator = typename storage_type::iterator
template<>
using const_iterator = typename storage_type::const_iterator
template<>
using heap_type = std::deque<iterator>
template<>
using heap_iterator = typename heap_type::iterator
template<>
using adapted_update_policy_type = adapt<UpdatePolicy, iterator>
template<>
using update_on_exit = typename statistics_type::update_on_exit

Private Members

size_type max_size_
size_type current_size_
storage_type store_
heap_type entry_heap_
adapted_update_policy_type update_policy_
insert_policy_type insert_policy_
statistics_type statistics_
template<typename Func, typename Iterator>
struct adapt

Public Functions

template<>
adapt(Func const &f)
template<>
adapt(Func &&f)
template<>
bool operator()(Iterator const &lhs, Iterator const &rhs) const

Public Members

template<>
Func f_