1.. _concurrent_lru_cache:
2
3concurrent_lru_cache
4====================
5
6.. note::
7   To enable this feature, define the ``TBB_PREVIEW_CONCURRENT_LRU_CACHE`` macro to 1.
8
9A Class Template for Least Recently Used cache with concurrent operations.
10
11.. contents::
12    :local:
13    :depth: 1
14
15Description
16***********
17
18A ``concurrent_lru_cache`` container maps keys to values with the ability
19to limit the number of stored unused values. For each key, there is at most one item
20stored in the container.
21
22The container permits multiple threads to concurrently retrieve items from it.
23
24The container tracks which items are in use by returning a proxy
25``concurrent_lru_cache::handle`` object that refers to an item instead of its value.
26Once there are no ``handle`` objects holding reference to an item, it is considered unused.
27
28The container stores all the items that are currently in use plus a limited
29number of unused items. Excessive unused items are erased according to
30least recently used policy.
31
32When no item is found for a given key, the container calls the user-specified
33``value_function_type`` object to construct a value for the key, and stores that value.
34The ``value_function_type`` object must be thread-safe.
35
36API
37***
38
39Header
40------
41
42.. code:: cpp
43
44    #include "oneapi/tbb/concurrent_lru_cache.h"
45
46Synopsis
47--------
48
49.. code:: cpp
50
51    namespace oneapi {
52        namespace tbb {
53            template <typename Key, typename Value, typename ValueFunctionType = Value (*)(Key)>
54            class concurrent_lru_cache {
55            public:
56                using key_type = Key;
57                using value_type = Value;
58                using pointer = value_type*;
59                using const_pointer = const value_type*;
60                using reference = value_type&;
61                using const_reference = const value_type&;
62
63                using value_function_type = ValueFunctionType;
64
65                class handle {
66                public:
67                    handle();
68                    handle( handle&& other );
69
70                    ~handle();
71
72                    handle& operator=( handle&& other );
73
74                    operator bool() const;
75                    value_type& value();
76                }; // class handle
77
78                concurrent_lru_cache( value_function_type f, std::size_t number_of_lru_history_items );
79                ~concurrent_lru_cache();
80
81                handle operator[]( key_type key );
82            }; // class concurrent_lru_cache
83        } // namespace tbb
84    } // namespace oneapi
85
86Member Functions
87----------------
88
89.. cpp:function:: concurrent_lru_cache( value_function_type f, std::size_t number_of_lru_history_items );
90
91    **Effects**: Constructs an empty cache that can keep up to ``number_of_lru_history_items``
92    unused values, with a function object ``f`` for constructing new values.
93
94-------------------------------------------------------
95
96.. cpp:function:: ~concurrent_lru_cache();
97
98    **Effects**: Destroys the ``concurrent_lru_cache``. Calls the destructors of the stored elements and
99    deallocates the used storage.
100
101The behavior is undefined in case of concurrent operations with ``*this``.
102
103-------------------------------------------------------
104
105.. cpp:function:: handle operator[]( key_type k );
106
107    **Effects**: Searches the container for an item that corresponds to the given key.
108    If such an item is not found, the user-specified function object is called to
109    construct a value that is inserted into the container.
110
111    **Returns**: a ``handle`` object holding reference to the matching value.
112
113Member Objects
114--------------
115
116``handle`` class
117^^^^^^^^^^^^^^^^
118
119**Member Functions**
120
121.. cpp:function:: handle();
122
123    **Effects**: Constructs a ``handle`` object that does not refer to any value.
124
125--------------------------------------------------
126
127.. cpp:function:: handle( handle&& other );
128
129    **Effects**: Transfers the reference to the value stored in ``concurrent_lru_cache``
130    from ``other`` to the newly constructed object. Upon completion,
131    ``other`` no longer refers to any value.
132
133---------------------------------------------------
134
135.. cpp:function:: ~handle();
136
137    **Effects**: Releases the reference (if it exists) to a value stored in ``concurrent_lru_cache``.
138
139The behavior is undefined for concurrent operations with ``*this``.
140
141---------------------------------------------------
142
143.. cpp:function:: handle& operator=( handle&& other );
144
145    **Effects**: Transfers the reference to a value stored in ``concurrent_lru_cache`` from ``other``
146    to ``*this``. If existed, the previous reference held by ``*this`` is released. Upon
147    completion ``other`` no longer refers to any value.
148
149    **Returns**: a reference to ``*this``.
150
151---------------------------------------------------
152
153.. cpp:function:: operator bool() const;
154
155    **Returns**: ``true`` if ``*this`` holds reference to a value, ``false`` otherwise.
156
157---------------------------------------------------
158
159.. cpp:function:: value_type& value();
160
161    **Returns**: a reference to a ``value_type`` object stored in ``concurrent_lru_cache``.
162
163The behavior is undefined if ``*this`` does not refer to any value.
164