Line data Source code
1 : // Copyright (c) 2016 Jeremy Rubin
2 : // Distributed under the MIT software license, see the accompanying
3 : // file COPYING or http://www.opensource.org/licenses/mit-license.php.
4 :
5 : #ifndef PIVX_CUCKOOCACHE_H
6 : #define PIVX_CUCKOOCACHE_H
7 :
8 : #include <array>
9 : #include <algorithm>
10 : #include <atomic>
11 : #include <cstring>
12 : #include <cmath>
13 : #include <memory>
14 : #include <vector>
15 :
16 :
17 : /** namespace CuckooCache provides high performance cache primitives
18 : *
19 : * Summary:
20 : *
21 : * 1) bit_packed_atomic_flags is bit-packed atomic flags for garbage collection
22 : *
23 : * 2) cache is a cache which is performant in memory usage and lookup speed. It
24 : * is lockfree for erase operations. Elements are lazily erased on the next
25 : * insert.
26 : */
27 : namespace CuckooCache
28 : {
29 : /** bit_packed_atomic_flags implements a container for garbage collection flags
30 : * that is only thread unsafe on calls to setup. This class bit-packs collection
31 : * flags for memory efficiency.
32 : *
33 : * All operations are std::memory_order_relaxed so external mechanisms must
34 : * ensure that writes and reads are properly synchronized.
35 : *
36 : * On setup(n), all bits up to n are marked as collected.
37 : *
38 : * Under the hood, because it is an 8-bit type, it makes sense to use a multiple
39 : * of 8 for setup, but it will be safe if that is not the case as well.
40 : *
41 : */
42 800 : class bit_packed_atomic_flags
43 : {
44 : std::unique_ptr<std::atomic<uint8_t>[]> mem;
45 :
46 : public:
47 : /** No default constructor as there must be some size */
48 : bit_packed_atomic_flags() = delete;
49 :
50 : /**
51 : * bit_packed_atomic_flags constructor creates memory to sufficiently
52 : * keep track of garbage collection information for size entries.
53 : *
54 : * @param size the number of elements to allocate space for
55 : *
56 : * @post bit_set, bit_unset, and bit_is_set function properly forall x. x <
57 : * size
58 : * @post All calls to bit_is_set (without subsequent bit_unset) will return
59 : * true.
60 : */
61 1288 : bit_packed_atomic_flags(uint32_t size)
62 1288 : {
63 : // pad out the size if needed
64 1288 : size = (size + 7) / 8;
65 103826674 : mem.reset(new std::atomic<uint8_t>[size]);
66 103826674 : for (uint32_t i = 0; i < size; ++i)
67 103825456 : mem[i].store(0xFF);
68 1288 : };
69 :
70 : /** setup marks all entries and ensures that bit_packed_atomic_flags can store
71 : * at least size entries
72 : *
73 : * @param b the number of elements to allocate space for
74 : * @post bit_set, bit_unset, and bit_is_set function properly forall x. x <
75 : * b
76 : * @post All calls to bit_is_set (without subsequent bit_unset) will return
77 : * true.
78 : */
79 800 : inline void setup(uint32_t b)
80 : {
81 800 : bit_packed_atomic_flags d(b);
82 800 : std::swap(mem, d.mem);
83 800 : }
84 :
85 : /** bit_set sets an entry as discardable.
86 : *
87 : * @param s the index of the entry to bit_set.
88 : * @post immediately subsequent call (assuming proper external memory
89 : * ordering) to bit_is_set(s) == true.
90 : *
91 : */
92 2511517 : inline void bit_set(uint32_t s)
93 : {
94 2511517 : mem[s >> 3].fetch_or(1 << (s & 7), std::memory_order_relaxed);
95 : }
96 :
97 : /** bit_unset marks an entry as something that should not be overwritten
98 : *
99 : * @param s the index of the entry to bit_unset.
100 : * @post immediately subsequent call (assuming proper external memory
101 : * ordering) to bit_is_set(s) == false.
102 : */
103 2289791 : inline void bit_unset(uint32_t s)
104 : {
105 2289791 : mem[s >> 3].fetch_and(~(1 << (s & 7)), std::memory_order_relaxed);
106 : }
107 :
108 : /** bit_is_set queries the table for discardability at s
109 : *
110 : * @param s the index of the entry to read.
111 : * @returns if the bit at index s was set.
112 : * */
113 11058807 : inline bool bit_is_set(uint32_t s) const
114 : {
115 11058807 : return (1 << (s & 7)) & mem[s >> 3].load(std::memory_order_relaxed);
116 : }
117 : };
118 :
119 : /** cache implements a cache with properties similar to a cuckoo-set
120 : *
121 : * The cache is able to hold up to (~(uint32_t)0) - 1 elements.
122 : *
123 : * Read Operations:
124 : * - contains(*, false)
125 : *
126 : * Read+Erase Operations:
127 : * - contains(*, true)
128 : *
129 : * Erase Operations:
130 : * - allow_erase()
131 : *
132 : * Write Operations:
133 : * - setup()
134 : * - setup_bytes()
135 : * - insert()
136 : * - please_keep()
137 : *
138 : * Synchronization Free Operations:
139 : * - invalid()
140 : * - compute_hashes()
141 : *
142 : * User Must Guarantee:
143 : *
144 : * 1) Write Requires synchronized access (e.g., a lock)
145 : * 2) Read Requires no concurrent Write, synchronized with the last insert.
146 : * 3) Erase requires no concurrent Write, synchronized with last insert.
147 : * 4) An Erase caller must release all memory before allowing a new Writer.
148 : *
149 : *
150 : * Note on function names:
151 : * - The name "allow_erase" is used because the real discard happens later.
152 : * - The name "please_keep" is used because elements may be erased anyways on insert.
153 : *
154 : * @tparam Element should be a movable and copyable type
155 : * @tparam Hash should be a function/callable which takes a template parameter
156 : * hash_select and an Element and extracts a hash from it. Should return
157 : * high-entropy hashes for `Hash h; h<0>(e) ... h<7>(e)`.
158 : */
159 : template <typename Element, typename Hash>
160 : class cache
161 : {
162 : private:
163 : /** table stores all the elements */
164 : std::vector<Element> table;
165 :
166 : /** size stores the total available slots in the hash table */
167 : uint32_t size;
168 :
169 : /** The bit_packed_atomic_flags array is marked mutable because we want
170 : * garbage collection to be allowed to occur from const methods */
171 : mutable bit_packed_atomic_flags collection_flags;
172 :
173 : /** epoch_flags tracks how recently an element was inserted into
174 : * the cache. true denotes recent, false denotes not-recent. See insert()
175 : * method for full semantics.
176 : */
177 : mutable std::vector<bool> epoch_flags;
178 :
179 : /** epoch_heuristic_counter is used to determine when a epoch might be aged
180 : * & an expensive scan should be done. epoch_heuristic_counter is
181 : * decremented on insert and reset to the new number of inserts which would
182 : * cause the epoch to reach epoch_size when it reaches zero.
183 : */
184 : uint32_t epoch_heuristic_counter;
185 :
186 : /** epoch_size is set to be the number of elements supposed to be in a
187 : * epoch. When the number of non-erased elements in a epoch
188 : * exceeds epoch_size, a new epoch should be started and all
189 : * current entries demoted. epoch_size is set to be 45% of size because
190 : * we want to keep load around 90%, and we support 3 epochs at once --
191 : * one "dead" which has been erased, one "dying" which has been marked to be
192 : * erased next, and one "living" which new inserts add to.
193 : */
194 : uint32_t epoch_size;
195 :
196 : /** hash_mask should be set to appropriately mask out a hash such that every
197 : * masked hash is [0,size), eg, if floor(log2(size)) == 20, then hash_mask
198 : * should be (1<<20)-1
199 : */
200 : uint32_t hash_mask;
201 :
202 : /** depth_limit determines how many elements insert should try to replace.
203 : * Should be set to log2(n)*/
204 : uint8_t depth_limit;
205 :
206 : /** hash_function is a const instance of the hash function. It cannot be
207 : * static or initialized at call time as it may have internal state (such as
208 : * a nonce).
209 : * */
210 : const Hash hash_function;
211 :
212 : /** compute_hashes is convenience for not having to write out this
213 : * expression everywhere we use the hash values of an Element.
214 : *
215 : * @param e the element whose hashes will be returned
216 : * @returns std::array<uint32_t, 8> of deterministic hashes derived from e
217 : */
218 5243948 : inline std::array<uint32_t, 8> compute_hashes(const Element& e) const
219 : {
220 5243948 : return {{hash_function.template operator()<0>(e) & hash_mask,
221 5243948 : hash_function.template operator()<1>(e) & hash_mask,
222 5243948 : hash_function.template operator()<2>(e) & hash_mask,
223 5243948 : hash_function.template operator()<3>(e) & hash_mask,
224 5243948 : hash_function.template operator()<4>(e) & hash_mask,
225 5243948 : hash_function.template operator()<5>(e) & hash_mask,
226 5243948 : hash_function.template operator()<6>(e) & hash_mask,
227 5243948 : hash_function.template operator()<7>(e) & hash_mask}};
228 : }
229 :
230 : /* end
231 : * @returns a constexpr index that can never be inserted to */
232 2289791 : constexpr uint32_t invalid() const
233 : {
234 : return ~(uint32_t)0;
235 : }
236 :
237 : /** allow_erase marks the element at index n as discardable. Threadsafe
238 : * without any concurrent insert.
239 : * @param n the index to allow erasure of
240 : */
241 2511517 : inline void allow_erase(uint32_t n) const
242 : {
243 2511517 : collection_flags.bit_set(n);
244 2511517 : }
245 :
246 : /** please_keep marks the element at index n as an entry that should be kept.
247 : * Threadsafe without any concurrent insert.
248 : * @param n the index to prioritize keeping
249 : */
250 2289791 : inline void please_keep(uint32_t n) const
251 : {
252 2289791 : collection_flags.bit_unset(n);
253 : }
254 :
255 : /** epoch_check handles the changing of epochs for elements stored in the
256 : * cache. epoch_check should be run before every insert.
257 : *
258 : * First, epoch_check decrements and checks the cheap heuristic, and then does
259 : * a more expensive scan if the cheap heuristic runs out. If the expensive
260 : * scan succeeds, the epochs are aged and old elements are allow_erased. The
261 : * cheap heuristic is reset to retrigger after the worst case growth of the
262 : * current epoch's elements would exceed the epoch_size.
263 : */
264 2289791 : void epoch_check()
265 : {
266 2289791 : if (epoch_heuristic_counter != 0) {
267 2289711 : --epoch_heuristic_counter;
268 2289711 : return;
269 : }
270 : // count the number of elements from the latest epoch which
271 : // have not been erased.
272 : uint32_t epoch_unused_count = 0;
273 11010100 : for (uint32_t i = 0; i < size; ++i)
274 11930300 : epoch_unused_count += epoch_flags[i] &&
275 5500900 : !collection_flags.bit_is_set(i);
276 : // If there are more non-deleted entries in the current epoch than the
277 : // epoch size, then allow_erase on all elements in the old epoch (marked
278 : // false) and move all elements in the current epoch to the old epoch
279 : // but do not call allow_erase on their indices.
280 84 : if (epoch_unused_count >= epoch_size) {
281 3145750 : for (uint32_t i = 0; i < size; ++i)
282 3145730 : if (epoch_flags[i])
283 1622180 : epoch_flags[i] = false;
284 : else
285 3145730 : allow_erase(i);
286 24 : epoch_heuristic_counter = epoch_size;
287 : } else
288 : // reset the epoch_heuristic_counter to next do a scan when worst
289 : // case behavior (no intermittent erases) would exceed epoch size,
290 : // with a reasonable minimum scan size.
291 : // Ordinarily, we would have to sanity check std::min(epoch_size,
292 : // epoch_unused_count), but we already know that `epoch_unused_count
293 : // < epoch_size` in this branch
294 180 : epoch_heuristic_counter = std::max(1u, std::max(epoch_size / 16,
295 150 : epoch_size - epoch_unused_count));
296 : }
297 :
298 : public:
299 : /** You must always construct a cache with some elements via a subsequent
300 : * call to setup or setup_bytes, otherwise operations may segfault.
301 : */
302 488 : cache() : table(), size(), collection_flags(0), epoch_flags(),
303 488 : epoch_heuristic_counter(), epoch_size(), depth_limit(0), hash_function()
304 : {
305 488 : }
306 :
307 : /** setup initializes the container to store no more than new_size
308 : * elements. setup rounds down to a power of two size.
309 : *
310 : * setup should only be called once.
311 : *
312 : * @param new_size the desired number of elements to store
313 : * @returns the maximum number of elements storable
314 : **/
315 800 : uint32_t setup(uint32_t new_size)
316 : {
317 : // depth_limit must be at least one otherwise errors can occur.
318 1600 : depth_limit = static_cast<uint8_t>(std::log2(static_cast<float>(std::max((uint32_t)2, new_size))));
319 800 : size = 1 << depth_limit;
320 800 : hash_mask = size-1;
321 800 : table.resize(size);
322 800 : collection_flags.setup(size);
323 800 : epoch_flags.resize(size);
324 : // Set to 45% as described above
325 800 : epoch_size = std::max((uint32_t)1, (45 * size) / 100);
326 : // Initially set to wait for a whole epoch
327 800 : epoch_heuristic_counter = epoch_size;
328 800 : return size;
329 : }
330 :
331 : /** setup_bytes is a convenience function which accounts for internal memory
332 : * usage when deciding how many elements to store. It isn't perfect because
333 : * it doesn't account for any overhead (struct size, MallocUsage, collection
334 : * and epoch flags). This was done to simplify selecting a power of two
335 : * size. In the expected use case, an extra two bits per entry should be
336 : * negligible compared to the size of the elements.
337 : *
338 : * @param bytes the approximate number of bytes to use for this data
339 : * structure.
340 : * @returns the maximum number of elements storable (see setup()
341 : * documentation for more detail)
342 : */
343 800 : uint32_t setup_bytes(size_t bytes)
344 : {
345 800 : return setup(bytes/sizeof(Element));
346 : }
347 :
348 : /** insert loops at most depth_limit times trying to insert a hash
349 : * at various locations in the table via a variant of the Cuckoo Algorithm
350 : * with eight hash locations.
351 : *
352 : * It drops the last tried element if it runs out of depth before
353 : * encountering an open slot.
354 : *
355 : * Thus
356 : *
357 : * insert(x);
358 : * return contains(x, false);
359 : *
360 : * is not guaranteed to return true.
361 : *
362 : * @param e the element to insert
363 : * @post one of the following: All previously inserted elements and e are
364 : * now in the table, one previously inserted element is evicted from the
365 : * table, the entry attempted to be inserted is evicted.
366 : *
367 : */
368 2289791 : inline void insert(Element e)
369 : {
370 2289791 : epoch_check();
371 2289791 : uint32_t last_loc = invalid();
372 2289791 : bool last_epoch = true;
373 2289791 : std::array<uint32_t, 8> locs = compute_hashes(e);
374 : // Make sure we have not already inserted this element
375 : // If we have, make sure that it does not get deleted
376 20608100 : for (uint32_t loc : locs)
377 18318290 : if (table[loc] == e) {
378 0 : please_keep(loc);
379 0 : epoch_flags[loc] = last_epoch;
380 2289791 : return;
381 : }
382 2375961 : for (uint8_t depth = 0; depth < depth_limit; ++depth) {
383 : // First try to insert to an empty slot, if one exists
384 5644127 : for (uint32_t loc : locs) {
385 5557947 : if (!collection_flags.bit_is_set(loc))
386 : continue;
387 2289791 : table[loc] = std::move(e);
388 2289791 : please_keep(loc);
389 2289791 : epoch_flags[loc] = last_epoch;
390 2289791 : return;
391 : }
392 : /** Swap with the element at the location that was
393 : * not the last one looked at. Example:
394 : *
395 : * 1) On first iteration, last_loc == invalid(), find returns last, so
396 : * last_loc defaults to locs[0].
397 : * 2) On further iterations, where last_loc == locs[k], last_loc will
398 : * go to locs[k+1 % 8], i.e., next of the 8 indices wrapping around
399 : * to 0 if needed.
400 : *
401 : * This prevents moving the element we just put in.
402 : *
403 : * The swap is not a move -- we must switch onto the evicted element
404 : * for the next iteration.
405 : */
406 86173 : last_loc = locs[(1 + (std::find(locs.begin(), locs.end(), last_loc) - locs.begin())) & 7];
407 86173 : std::swap(table[last_loc], e);
408 : // Can't std::swap a std::vector<bool>::reference and a bool&.
409 86173 : bool epoch = last_epoch;
410 86173 : last_epoch = epoch_flags[last_loc];
411 172346 : epoch_flags[last_loc] = epoch;
412 :
413 : // Recompute the locs -- unfortunately happens one too many times!
414 86173 : locs = compute_hashes(e);
415 : }
416 : }
417 :
418 : /* contains iterates through the hash locations for a given element
419 : * and checks to see if it is present.
420 : *
421 : * contains does not check garbage collected state (in other words,
422 : * garbage is only collected when the space is needed), so:
423 : *
424 : * insert(x);
425 : * if (contains(x, true))
426 : * return contains(x, false);
427 : * else
428 : * return true;
429 : *
430 : * executed on a single thread will always return true!
431 : *
432 : * This is a great property for re-org performance for example.
433 : *
434 : * contains returns a bool set true if the element was found.
435 : *
436 : * @param e the element to check
437 : * @param erase
438 : *
439 : * @post if erase is true and the element is found, then the garbage collect
440 : * flag is set
441 : * @returns true if the element is found, false otherwise
442 : */
443 2867988 : inline bool contains(const Element& e, const bool erase) const
444 : {
445 2867988 : std::array<uint32_t, 8> locs = compute_hashes(e);
446 9255246 : for (uint32_t loc : locs)
447 8627415 : if (table[loc] == e) {
448 2240157 : if (erase)
449 2240157 : allow_erase(loc);
450 2240157 : return true;
451 : }
452 : return false;
453 : }
454 : };
455 : } // namespace CuckooCache
456 :
457 : #endif // PIVX_CUCKOOCACHE_H
|
