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

using key_type = Key #

using entry_type = Entry #

using update_policy_type = UpdatePolicy #

using insert_policy_type = InsertPolicy #

using storage_type = CacheStorage #

using statistics_type = Statistics #

using value_type = typename entry_type::value_type#

using size_type = typename storage_type::size_type#

using storage_value_type = typename storage_type::value_type#

Public Functions

inline 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) = default#

inline constexpr size_type size() const noexcept#

Return current size of the cache.

Returns: The current size of this cache instance.

inline constexpr size_type capacity() const noexcept#

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.

Returns: 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.

inline bool reserve(size_type max_size)#

Change the maximum size this cache can grow to.

Parameters: max_size – [in] The new maximum size this cache will be allowed to grow to.
Returns: 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.

inline 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.

Parameters: k – [in] The key for the entry which should be looked up in the cache.
Returns: This function returns true if the cache holds the referenced entry, otherwise it returns false.

inline 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.

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.

Returns

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

inline 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.

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.

Returns

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

inline 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.

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.

Returns

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

inline 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.

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.

Returns

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

inline 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> inline 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.

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.

Returns

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

template<typename Value, std::enable_if_t<std::is_convertible_v<std::decay_t<Value>, value_type>, int> = 0> inline 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.

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.

Returns

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.

template<typename F, typename Value, typename = std::enable_if_t<std::is_convertible_v<std::decay_t<Value>, value_type>>> inline 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

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.

Returns

template<typename Entry_, std::enable_if_t<std::is_convertible_v<std::decay_t<Entry_>, entry_type>, int> = 0> inline 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.

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.

Returns

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

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

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.
Returns: 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).

inline 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.

Returns: 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).

inline void clear()#

Clear the cache.

Unconditionally removes all stored entries from the cache.

inline constexpr statistics_type const &get_statistics() const noexcept#