doc/main/reference/concurrent_lru_cache_cls.rst
.. _concurrent_lru_cache:
.. note::
To enable this feature, define the TBB_PREVIEW_CONCURRENT_LRU_CACHE macro to 1.
A Class Template for Least Recently Used cache with concurrent operations.
.. contents:: :local: :depth: 1
Description
A concurrent_lru_cache container maps keys to values with the ability
to limit the number of stored unused values. For each key, there is at most one item
stored in the container.
The container permits multiple threads to concurrently retrieve items from it.
The container tracks which items are in use by returning a proxy
concurrent_lru_cache::handle object that refers to an item instead of its value.
Once there are no handle objects holding reference to an item, it is considered unused.
The container stores all the items that are currently in use plus a limited number of unused items. Excessive unused items are erased according to least recently used policy.
When no item is found for a given key, the container calls the user-specified
value_function_type object to construct a value for the key, and stores that value.
The value_function_type object must be thread-safe.
API
.. code:: cpp
#include "oneapi/tbb/concurrent_lru_cache.h"
.. code:: cpp
namespace oneapi {
namespace tbb {
template <typename Key, typename Value, typename ValueFunctionType = Value (*)(Key)>
class concurrent_lru_cache {
public:
using key_type = Key;
using value_type = Value;
using pointer = value_type*;
using const_pointer = const value_type*;
using reference = value_type&;
using const_reference = const value_type&;
using value_function_type = ValueFunctionType;
class handle {
public:
handle();
handle( handle&& other );
~handle();
handle& operator=( handle&& other );
operator bool() const;
value_type& value();
}; // class handle
concurrent_lru_cache( value_function_type f, std::size_t number_of_lru_history_items );
~concurrent_lru_cache();
handle operator[]( key_type key );
}; // class concurrent_lru_cache
} // namespace tbb
} // namespace oneapi
.. cpp:function:: concurrent_lru_cache( value_function_type f, std::size_t number_of_lru_history_items );
**Effects**: Constructs an empty cache that can keep up to ``number_of_lru_history_items``
unused values, with a function object ``f`` for constructing new values.
.. cpp:function:: ~concurrent_lru_cache();
**Effects**: Destroys the ``concurrent_lru_cache``. Calls the destructors of the stored elements and
deallocates the used storage.
The behavior is undefined in case of concurrent operations with *this.
.. cpp:function:: handle operator[]( key_type k );
**Effects**: Searches the container for an item that corresponds to the given key.
If such an item is not found, the user-specified function object is called to
construct a value that is inserted into the container.
**Returns**: a ``handle`` object holding reference to the matching value.
handle class
^^^^^^^^^^^^^^^^
Member Functions
.. cpp:function:: handle();
**Effects**: Constructs a ``handle`` object that does not refer to any value.
.. cpp:function:: handle( handle&& other );
**Effects**: Transfers the reference to the value stored in ``concurrent_lru_cache``
from ``other`` to the newly constructed object. Upon completion,
``other`` no longer refers to any value.
.. cpp:function:: ~handle();
**Effects**: Releases the reference (if it exists) to a value stored in ``concurrent_lru_cache``.
The behavior is undefined for concurrent operations with *this.
.. cpp:function:: handle& operator=( handle&& other );
**Effects**: Transfers the reference to a value stored in ``concurrent_lru_cache`` from ``other``
to ``*this``. If existed, the previous reference held by ``*this`` is released. Upon
completion ``other`` no longer refers to any value.
**Returns**: a reference to ``*this``.
.. cpp:function:: operator bool() const;
**Returns**: ``true`` if ``*this`` holds reference to a value, ``false`` otherwise.
.. cpp:function:: value_type& value();
**Returns**: a reference to a ``value_type`` object stored in ``concurrent_lru_cache``.
The behavior is undefined if *this does not refer to any value.