cache

#include <hpx/cache/local_cache.hpp>

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

typedef Key key_type
typedef Entry entry_type
typedef UpdatePolicy update_policy_type
typedef InsertPolicy insert_policy_type
typedef CacheStorage storage_type
typedef Statistics statistics_type
typedef entry_type::value_type value_type
typedef storage_type::size_type size_type
typedef storage_type::value_type storage_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)
size_type size() const

Return current size of the cache.

Return

The current size of this cache instance.

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, entry_type &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.

bool update(key_type const &k, value_type const &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>
bool update_if(key_type const &k, value_type const &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.

bool update(key_type const &k, entry_type &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>
size_type erase(Func const &ep = policies::always<storage_value_type>())

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.

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

typedef storage_type::iterator iterator
typedef storage_type::const_iterator const_iterator
typedef std::deque<iterator> heap_type
typedef heap_type::iterator heap_iterator
typedef adapt<UpdatePolicy, iterator> adapted_update_policy_type
typedef statistics_type::update_on_exit 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 f)
template<>
bool operator()(Iterator const &lhs, Iterator const &rhs) const

Public Members

template<>
Func f_

#include <hpx/cache/lru_cache.hpp>

namespace hpx
namespace util
namespace cache
template<typename Key, typename Entry, typename Statistics = statistics::no_statistics>
class lru_cache
#include <hpx/cache/lru_cache.hpp>

The lru_cache implements the basic functionality needed for a local (non-distributed) LRU 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.

  • 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

typedef Key key_type
typedef Entry entry_type
typedef Statistics statistics_type
typedef std::pair<key_type, entry_type> entry_pair
typedef std::list<entry_pair> storage_type
typedef std::map<Key, typename storage_type::iterator> map_type
typedef std::size_t size_type

Public Functions

lru_cache(size_type max_size = 0)

Construct an instance of a lru_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.

lru_cache(lru_cache &&other)
size_type size() const

Return current size of the cache.

Return

The current size of this cache instance.

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.

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

bool holds_key(key_type const &key)

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 &key, key_type &realkey, entry_type &entry)

Get a specific entry identified by the given key.

Note

The function will “touch” the entry and mark it as recently used if the key was found in the cache.

Return

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

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

  • entry: [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 &key, entry_type &entry)

Get a specific entry identified by the given key.

Note

The function will “touch” the entry and mark it as recently used if the key was found in the cache.

Return

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

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

  • entry: [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 insert(key_type const &key, entry_type const &entry)

Insert a new entry into this cache.

Note

This function assumes that the entry is not in the cache already. Inserting an already existing entry is considered undefined behavior

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

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

void insert_nonexist(key_type const &key, entry_type const &entry)
void update(key_type const &key, entry_type const &entry)

Update an existing element in this cache.

Note

The function will “touch” the entry and mark it as recently used if the key was 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
  • key: [in] The key for the value which should be updated in the cache.

  • entry: [in] The entry 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>
bool update_if(key_type const &key, entry_type const &entry, F &&f)

Update an existing element in this cache.

Note

The function will “touch” the entry and mark it as recently used if the key was 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
  • key: [in] The key for the value which should be updated in the cache.

  • entry: [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 Func>
size_type erase(Func const &ep)

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.

size_type erase()

Remove all stored entries from the cache.

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

size_type clear()

Clear the cache.

Unconditionally removes all stored entries from the cache.

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()

Private Types

typedef statistics_type::update_on_exit update_on_exit

Private Functions

void touch(typename storage_type::iterator it)
void evict()

Private Members

size_type max_size_
size_type current_size_
storage_type storage_
map_type map_
statistics_type statistics_

#include <hpx/cache/statistics/local_statistics.hpp>

namespace hpx
namespace util
namespace cache
namespace statistics
class local_statistics : public hpx::util::cache::statistics::no_statistics

Subclassed by hpx::util::cache::statistics::local_full_statistics

Public Functions

local_statistics()
std::size_t get_and_reset(std::size_t &value, bool reset)
std::size_t hits() const
std::size_t misses() const
std::size_t insertions() const
std::size_t evictions() const
std::size_t hits(bool reset)
std::size_t misses(bool reset)
std::size_t insertions(bool reset)
std::size_t evictions(bool reset)
void got_hit()

The function got_hit will be called by a cache instance whenever a entry got touched.

void got_miss()

The function got_miss will be called by a cache instance whenever a requested entry has not been found in the cache.

void got_insertion()

The function got_insertion will be called by a cache instance whenever a new entry has been inserted.

void got_eviction()

The function got_eviction will be called by a cache instance whenever an entry has been removed from the cache because a new inserted entry let the cache grow beyond its capacity.

void clear()

Reset all statistics.

Private Members

std::size_t hits_
std::size_t misses_
std::size_t insertions_
std::size_t evictions_

#include <hpx/cache/statistics/no_statistics.hpp>

namespace hpx
namespace util
namespace cache
namespace statistics

Enums

enum method

Values:

method_get_entry = 0
method_insert_entry = 1
method_update_entry = 2
method_erase_entry = 3
class no_statistics

Subclassed by hpx::util::cache::statistics::local_statistics

Public Functions

void got_hit()

The function got_hit will be called by a cache instance whenever a entry got touched.

void got_miss()

The function got_miss will be called by a cache instance whenever a requested entry has not been found in the cache.

void got_insertion()

The function got_insertion will be called by a cache instance whenever a new entry has been inserted.

void got_eviction()

The function got_eviction will be called by a cache instance whenever an entry has been removed from the cache because a new inserted entry let the cache grow beyond its capacity.

void clear()

Reset all statistics.

std::int64_t get_get_entry_count(bool)

The function get_get_entry_count returns the number of invocations of the get_entry() API function of the cache.

std::int64_t get_insert_entry_count(bool)

The function get_insert_entry_count returns the number of invocations of the insert_entry() API function of the cache.

std::int64_t get_update_entry_count(bool)

The function get_update_entry_count returns the number of invocations of the update_entry() API function of the cache.

std::int64_t get_erase_entry_count(bool)

The function get_erase_entry_count returns the number of invocations of the erase() API function of the cache.

std::int64_t get_get_entry_time(bool)

The function get_get_entry_time returns the overall time spent executing of the get_entry() API function of the cache.

std::int64_t get_insert_entry_time(bool)

The function get_insert_entry_time returns the overall time spent executing of the insert_entry() API function of the cache.

std::int64_t get_update_entry_time(bool)

The function get_update_entry_time returns the overall time spent executing of the update_entry() API function of the cache.

std::int64_t get_erase_entry_time(bool)

The function get_erase_entry_time returns the overall time spent executing of the erase() API function of the cache.

struct update_on_exit
#include <no_statistics.hpp>

Helper class to update timings and counts on function exit.

Public Functions

update_on_exit(no_statistics const&, method)

#include <hpx/cache/statistics/local_full_statistics.hpp>

namespace hpx
namespace util
namespace cache
namespace statistics
class local_full_statistics : public hpx::util::cache::statistics::local_statistics

Public Functions

std::int64_t get_get_entry_count(bool reset)

The function get_get_entry_count returns the number of invocations of the get_entry() API function of the cache.

std::int64_t get_insert_entry_count(bool reset)

The function get_insert_entry_count returns the number of invocations of the insert_entry() API function of the cache.

std::int64_t get_update_entry_count(bool reset)

The function get_update_entry_count returns the number of invocations of the update_entry() API function of the cache.

std::int64_t get_erase_entry_count(bool reset)

The function get_erase_entry_count returns the number of invocations of the erase() API function of the cache.

std::int64_t get_get_entry_time(bool reset)

The function get_get_entry_time returns the overall time spent executing of the get_entry() API function of the cache.

std::int64_t get_insert_entry_time(bool reset)

The function get_insert_entry_time returns the overall time spent executing of the insert_entry() API function of the cache.

std::int64_t get_update_entry_time(bool reset)

The function get_update_entry_time returns the overall time spent executing of the update_entry() API function of the cache.

std::int64_t get_erase_entry_time(bool reset)

The function get_erase_entry_time returns the overall time spent executing of the erase() API function of the cache.

Private Functions

std::int64_t get_and_reset_value(std::int64_t &value, bool reset)

Private Members

api_counter_data get_entry_
api_counter_data insert_entry_
api_counter_data update_entry_
api_counter_data erase_entry_

Friends

friend hpx::util::cache::statistics::update_on_exit
struct api_counter_data

Public Functions

api_counter_data()

Public Members

std::int64_t count_
std::int64_t time_
struct update_on_exit
#include <local_full_statistics.hpp>

Helper class to update timings and counts on function exit.

Public Functions

update_on_exit(local_full_statistics &stat, method m)
~update_on_exit()

Public Members

std::int64_t started_at_
api_counter_data &data_

Private Static Functions

static api_counter_data &get_api_counter_data(local_full_statistics &stat, method m)
static std::uint64_t now()

#include <hpx/cache/entries/lru_entry.hpp>

namespace hpx
namespace util
namespace cache
namespace entries
template<typename Value>
class lru_entry : public hpx::util::cache::entries::entry<Value, lru_entry<Value>>
#include <hpx/cache/entries/lru_entry.hpp>

The lru_entry type can be used to store arbitrary values in a cache. Using this type as the cache’s entry type makes sure that the least recently used entries are discarded from the cache first.

Note

The lru_entry conforms to the CacheEntry concept.

Note

This type can be used to model a ‘most recently used’ cache policy if it is used with a std::greater as the caches’ UpdatePolicy (instead of the default std::less).

Template Parameters
  • Value: The data type to be stored in a cache. It has to be default constructible, copy constructible and less_than_comparable.

Public Functions

lru_entry()

Any cache entry has to be default constructible.

lru_entry(Value const &val)

Construct a new instance of a cache entry holding the given value.

bool touch()

The function touch is called by a cache holding this instance whenever it has been requested (touched).

In the case of the LRU entry we store the time of the last access which will be used to compare the age of an entry during the invocation of the operator<().

Return

This function should return true if the cache needs to update it’s internal heap. Usually this is needed if the entry has been changed by touch() in a way influencing the sort order as mandated by the cache’s UpdatePolicy

std::chrono::steady_clock::time_point const &get_access_time() const

Returns the last access time of the entry.

Private Types

typedef entry<Value, lru_entry<Value>> base_type

Private Members

std::chrono::steady_clock::time_point access_time_

Friends

bool operator<(lru_entry const &lhs, lru_entry const &rhs)

Compare the ‘age’ of two entries. An entry is ‘older’ than another entry if it has been accessed less recently (LRU).

#include <hpx/cache/entries/fifo_entry.hpp>

namespace hpx
namespace util
namespace cache
namespace entries
template<typename Value>
class fifo_entry : public hpx::util::cache::entries::entry<Value, fifo_entry<Value>>
#include <hpx/cache/entries/fifo_entry.hpp>

The fifo_entry type can be used to store arbitrary values in a cache. Using this type as the cache’s entry type makes sure that the least recently inserted entries are discarded from the cache first.

Note

The fifo_entry conforms to the CacheEntry concept.

Note

This type can be used to model a ‘last in first out’ cache policy if it is used with a std::greater as the caches’ UpdatePolicy (instead of the default std::less).

Template Parameters
  • Value: The data type to be stored in a cache. It has to be default constructible, copy constructible and less_than_comparable.

Public Functions

fifo_entry()

Any cache entry has to be default constructible.

fifo_entry(Value const &val)

Construct a new instance of a cache entry holding the given value.

bool insert()

The function insert is called by a cache whenever it is about to be inserted into the cache.

Note

This function is part of the CacheEntry concept

Return

This function should return true if the entry should be added to the cache, otherwise it should return false.

std::chrono::steady_clock::time_point const &get_creation_time() const

Private Types

typedef entry<Value, fifo_entry<Value>> base_type

Private Members

std::chrono::steady_clock::time_point insertion_time_

Friends

bool operator<(fifo_entry const &lhs, fifo_entry const &rhs)

Compare the ‘age’ of two entries. An entry is ‘older’ than another entry if it has been created earlier (FIFO).

#include <hpx/cache/entries/entry.hpp>

namespace hpx
namespace util
namespace cache
namespace entries
template<typename Value, typename Derived>
class entry : private boost::less_than_comparable<detail::derived<Value, Derived>::type>
#include <hpx/cache/entries/entry.hpp>

Template Parameters
  • Value: The data type to be stored in a cache. It has to be default constructible, copy constructible and less_than_comparable.

  • Derived: The (optional) type for which this type is used as a base class.

Public Types

typedef Value value_type

Public Functions

entry()

Any cache entry has to be default constructible.

entry(value_type const &val)

Construct a new instance of a cache entry holding the given value.

bool touch()

The function touch is called by a cache holding this instance whenever it has been requested (touched).

Note

It is possible to change the entry in a way influencing the sort criteria mandated by the UpdatePolicy. In this case the function should return true to indicate this to the cache, forcing to reorder the cache entries.

Note

This function is part of the CacheEntry concept

Return

This function should return true if the cache needs to update it’s internal heap. Usually this is needed if the entry has been changed by touch() in a way influencing the sort order as mandated by the cache’s UpdatePolicy

bool insert()

The function insert is called by a cache whenever it is about to be inserted into the cache.

Note

This function is part of the CacheEntry concept

Return

This function should return true if the entry should be added to the cache, otherwise it should return false.

bool remove()

The function remove is called by a cache holding this instance whenever it is about to be removed from the cache.

Note

This function is part of the CacheEntry concept

Return

The return value can be used to avoid removing this instance from the cache. If the value is true it is ok to remove the entry, other wise it will stay in the cache.

std::size_t get_size() const

Return the ‘size’ of this entry. By default the size of each entry is just one (1), which is sensible if the cache has a limit (capacity) measured in number of entries.

value_type &get()

Get a reference to the stored data value.

Note

This function is part of the CacheEntry concept

value_type const &get() const

Private Members

value_type value_

Friends

bool operator<(entry const &lhs, entry const &rhs)

Forwarding operator< allowing to compare entries in stead of the values.

#include <hpx/cache/entries/lfu_entry.hpp>

namespace hpx
namespace util
namespace cache
namespace entries
template<typename Value>
class lfu_entry : public hpx::util::cache::entries::entry<Value, lfu_entry<Value>>
#include <hpx/cache/entries/lfu_entry.hpp>

The lfu_entry type can be used to store arbitrary values in a cache. Using this type as the cache’s entry type makes sure that the least frequently used entries are discarded from the cache first.

Note

The lfu_entry conforms to the CacheEntry concept.

Note

This type can be used to model a ‘most frequently used’ cache policy if it is used with a std::greater as the caches’ UpdatePolicy (instead of the default std::less).

Template Parameters
  • Value: The data type to be stored in a cache. It has to be default constructible, copy constructible and less_than_comparable.

Public Functions

lfu_entry()

Any cache entry has to be default constructible.

lfu_entry(Value const &val)

Construct a new instance of a cache entry holding the given value.

bool touch()

The function touch is called by a cache holding this instance whenever it has been requested (touched).

In the case of the LFU entry we store the reference count tracking the number of times this entry has been requested. This which will be used to compare the age of an entry during the invocation of the operator<().

Return

This function should return true if the cache needs to update it’s internal heap. Usually this is needed if the entry has been changed by touch() in a way influencing the sort order as mandated by the cache’s UpdatePolicy

unsigned long const &get_access_count() const

Private Types

typedef entry<Value, lfu_entry<Value>> base_type

Private Members

unsigned long ref_count_

Friends

bool operator<(lfu_entry const &lhs, lfu_entry const &rhs)

Compare the ‘age’ of two entries. An entry is ‘older’ than another entry if it has been accessed less frequently (LFU).

#include <hpx/cache/entries/size_entry.hpp>

namespace hpx
namespace util
namespace cache
namespace entries
template<typename Value, typename Derived>
class size_entry : public hpx::util::cache::entries::entry<Value, detail::size_derived<Value, Derived>::type>
#include <hpx/cache/entries/size_entry.hpp>

The size_entry type can be used to store values in a cache which have a size associated (such as files, etc.). Using this type as the cache’s entry type makes sure that the entries with the biggest size are discarded from the cache first.

Note

The size_entry conforms to the CacheEntry concept.

Note

This type can be used to model a ‘discard smallest first’ cache policy if it is used with a std::greater as the caches’ UpdatePolicy (instead of the default std::less).

Template Parameters
  • Value: The data type to be stored in a cache. It has to be default constructible, copy constructible and less_than_comparable.

  • Derived: The (optional) type for which this type is used as a base class.

Public Functions

size_entry()

Any cache entry has to be default constructible.

size_entry(Value const &val, std::size_t size)

Construct a new instance of a cache entry holding the given value.

std::size_t get_size() const

Return the ‘size’ of this entry.

Private Types

typedef detail::size_derived<Value, Derived>::type derived_type
typedef entry<Value, derived_type> base_type

Private Members

std::size_t size_

Friends

bool operator<(size_entry const &lhs, size_entry const &rhs)

Compare the ‘age’ of two entries. An entry is ‘older’ than another entry if it has a bigger size.

#include <hpx/cache/policies/always.hpp>

namespace hpx
namespace util
namespace cache
namespace policies
template<typename Entry>
struct always

Public Functions

bool operator()(Entry const&)

#include <compatibility/hpx/util/cache/local_cache.hpp>

#include <compatibility/hpx/util/cache/lru_cache.hpp>

#include <compatibility/hpx/util/cache/statistics/local_statistics.hpp>

#include <compatibility/hpx/util/cache/statistics/no_statistics.hpp>

#include <compatibility/hpx/util/cache/statistics/local_full_statistics.hpp>

#include <compatibility/hpx/util/cache/entries/lru_entry.hpp>

#include <compatibility/hpx/util/cache/entries/fifo_entry.hpp>

#include <compatibility/hpx/util/cache/entries/entry.hpp>

#include <compatibility/hpx/util/cache/entries/lfu_entry.hpp>

#include <compatibility/hpx/util/cache/entries/size_entry.hpp>

#include <compatibility/hpx/util/cache/policies/always.hpp>