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 BITCOIN_CUCKOOCACHE_H
6 : #define BITCOIN_CUCKOOCACHE_H
7 :
8 : #include <util/fastrange.h>
9 :
10 : #include <array>
11 : #include <algorithm> // std::find
12 : #include <atomic>
13 : #include <cmath>
14 : #include <cstring>
15 : #include <memory>
16 : #include <utility>
17 : #include <vector>
18 :
19 :
20 : /** High-performance cache primitives.
21 : *
22 : * Summary:
23 : *
24 : * 1. @ref bit_packed_atomic_flags is bit-packed atomic flags for garbage collection
25 : *
26 : * 2. @ref cache is a cache which is performant in memory usage and lookup speed. It
27 : * is lockfree for erase operations. Elements are lazily erased on the next insert.
28 : */
29 : namespace CuckooCache
30 : {
31 : /** @ref bit_packed_atomic_flags implements a container for garbage collection flags
32 : * that is only thread unsafe on calls to setup. This class bit-packs collection
33 : * flags for memory efficiency.
34 : *
35 : * All operations are `std::memory_order_relaxed` so external mechanisms must
36 : * ensure that writes and reads are properly synchronized.
37 : *
38 : * On setup(n), all bits up to `n` are marked as collected.
39 : *
40 : * Under the hood, because it is an 8-bit type, it makes sense to use a multiple
41 : * of 8 for setup, but it will be safe if that is not the case as well.
42 : */
43 : class bit_packed_atomic_flags
44 : {
45 : std::unique_ptr<std::atomic<uint8_t>[]> mem;
46 :
47 : public:
48 : /** No default constructor, as there must be some size. */
49 : bit_packed_atomic_flags() = delete;
50 :
51 : /**
52 : * bit_packed_atomic_flags constructor creates memory to sufficiently
53 : * keep track of garbage collection information for `size` entries.
54 : *
55 : * @param size the number of elements to allocate space for
56 : *
57 : * @post bit_set, bit_unset, and bit_is_set function properly forall x. x <
58 : * size
59 : * @post All calls to bit_is_set (without subsequent bit_unset) will return
60 : * true.
61 : */
62 3130 : explicit bit_packed_atomic_flags(uint32_t size)
63 1565 : {
64 : // pad out the size if needed
65 1565 : size = (size + 7) / 8;
66 1565 : mem.reset(new std::atomic<uint8_t>[size]);
67 82396701 : for (uint32_t i = 0; i < size; ++i)
68 82395136 : mem[i].store(0xFF);
69 3130 : };
70 :
71 : /** setup marks all entries and ensures that bit_packed_atomic_flags can store
72 : * at least `b` entries.
73 : *
74 : * @param b the number of elements to allocate space for
75 : * @post bit_set, bit_unset, and bit_is_set function properly forall x. x <
76 : * b
77 : * @post All calls to bit_is_set (without subsequent bit_unset) will return
78 : * true.
79 : */
80 1264 : inline void setup(uint32_t b)
81 : {
82 1264 : bit_packed_atomic_flags d(b);
83 1264 : std::swap(mem, d.mem);
84 1264 : }
85 :
86 : /** bit_set sets an entry as discardable.
87 : *
88 : * @param s the index of the entry to bit_set
89 : * @post immediately subsequent call (assuming proper external memory
90 : * ordering) to bit_is_set(s) == true.
91 : */
92 2196491 : inline void bit_set(uint32_t s)
93 : {
94 2196491 : mem[s >> 3].fetch_or(uint8_t(1 << (s & 7)), std::memory_order_relaxed);
95 2196491 : }
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 2090447 : inline void bit_unset(uint32_t s)
104 : {
105 2090447 : mem[s >> 3].fetch_and(uint8_t(~(1 << (s & 7))), std::memory_order_relaxed);
106 2090447 : }
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 true if the bit at index `s` was set, false otherwise
112 : * */
113 10856539 : inline bool bit_is_set(uint32_t s) const
114 : {
115 10856539 : return (1 << (s & 7)) & mem[s >> 3].load(std::memory_order_relaxed);
116 : }
117 : };
118 :
119 : /** @ref 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() for `erase=false`
125 : *
126 : * Read+Erase Operations:
127 : * - contains() for `erase=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 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 uint32_t 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 301 : uint32_t size{0};
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 an 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 301 : uint32_t epoch_heuristic_counter{0};
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 an 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 301 : uint32_t epoch_size{0};
195 :
196 : /** depth_limit determines how many elements insert should try to replace.
197 : * Should be set to log2(n).
198 : */
199 301 : uint8_t depth_limit{0};
200 :
201 : /** hash_function is a const instance of the hash function. It cannot be
202 : * static or initialized at call time as it may have internal state (such as
203 : * a nonce).
204 : */
205 : const Hash hash_function;
206 :
207 : /** compute_hashes is convenience for not having to write out this
208 : * expression everywhere we use the hash values of an Element.
209 : *
210 : * We need to map the 32-bit input hash onto a hash bucket in a range [0, size) in a
211 : * manner which preserves as much of the hash's uniformity as possible. Ideally
212 : * this would be done by bitmasking but the size is usually not a power of two.
213 : *
214 : * The naive approach would be to use a mod -- which isn't perfectly uniform but so
215 : * long as the hash is much larger than size it is not that bad. Unfortunately,
216 : * mod/division is fairly slow on ordinary microprocessors (e.g. 90-ish cycles on
217 : * haswell, ARM doesn't even have an instruction for it.); when the divisor is a
218 : * constant the compiler will do clever tricks to turn it into a multiply+add+shift,
219 : * but size is a run-time value so the compiler can't do that here.
220 : *
221 : * One option would be to implement the same trick the compiler uses and compute the
222 : * constants for exact division based on the size, as described in "{N}-bit Unsigned
223 : * Division via {N}-bit Multiply-Add" by Arch D. Robison in 2005. But that code is
224 : * somewhat complicated and the result is still slower than an even simpler option:
225 : * see the FastRange32 function in util/fastrange.h.
226 : *
227 : * The resulting non-uniformity is also more equally distributed which would be
228 : * advantageous for something like linear probing, though it shouldn't matter
229 : * one way or the other for a cuckoo table.
230 : *
231 : * The primary disadvantage of this approach is increased intermediate precision is
232 : * required but for a 32-bit random number we only need the high 32 bits of a
233 : * 32*32->64 multiply, which means the operation is reasonably fast even on a
234 : * typical 32-bit processor.
235 : *
236 : * @param e The element whose hashes will be returned
237 : * @returns Deterministic hashes derived from `e` uniformly mapped onto the range [0, size)
238 : */
239 3758739 : inline std::array<uint32_t, 8> compute_hashes(const Element& e) const
240 : {
241 30069912 : return {{FastRange32(hash_function.template operator()<0>(e), size),
242 3758739 : FastRange32(hash_function.template operator()<1>(e), size),
243 3758739 : FastRange32(hash_function.template operator()<2>(e), size),
244 3758739 : FastRange32(hash_function.template operator()<3>(e), size),
245 3758739 : FastRange32(hash_function.template operator()<4>(e), size),
246 3758739 : FastRange32(hash_function.template operator()<5>(e), size),
247 3758739 : FastRange32(hash_function.template operator()<6>(e), size),
248 3758739 : FastRange32(hash_function.template operator()<7>(e), size)}};
249 : }
250 :
251 : /** invalid returns a special index that can never be inserted to
252 : * @returns the special constexpr index that can never be inserted to */
253 2090447 : constexpr uint32_t invalid() const
254 : {
255 2090447 : return ~(uint32_t)0;
256 : }
257 :
258 : /** allow_erase marks the element at index `n` as discardable. Threadsafe
259 : * without any concurrent insert.
260 : * @param n the index to allow erasure of
261 : */
262 2196496 : inline void allow_erase(uint32_t n) const
263 : {
264 2196496 : collection_flags.bit_set(n);
265 2196496 : }
266 :
267 : /** please_keep marks the element at index `n` as an entry that should be kept.
268 : * Threadsafe without any concurrent insert.
269 : * @param n the index to prioritize keeping
270 : */
271 2090447 : inline void please_keep(uint32_t n) const
272 : {
273 2090447 : collection_flags.bit_unset(n);
274 2090447 : }
275 :
276 : /** epoch_check handles the changing of epochs for elements stored in the
277 : * cache. epoch_check should be run before every insert.
278 : *
279 : * First, epoch_check decrements and checks the cheap heuristic, and then does
280 : * a more expensive scan if the cheap heuristic runs out. If the expensive
281 : * scan succeeds, the epochs are aged and old elements are allow_erased. The
282 : * cheap heuristic is reset to retrigger after the worst case growth of the
283 : * current epoch's elements would exceed the epoch_size.
284 : */
285 2090447 : void epoch_check()
286 : {
287 2090447 : if (epoch_heuristic_counter != 0) {
288 2090363 : --epoch_heuristic_counter;
289 2090363 : return;
290 : }
291 : // count the number of elements from the latest epoch which
292 : // have not been erased.
293 84 : uint32_t epoch_unused_count = 0;
294 11010132 : for (uint32_t i = 0; i < size; ++i)
295 16511102 : epoch_unused_count += epoch_flags[i] &&
296 5501054 : !collection_flags.bit_is_set(i);
297 : // If there are more non-deleted entries in the current epoch than the
298 : // epoch size, then allow_erase on all elements in the old epoch (marked
299 : // false) and move all elements in the current epoch to the old epoch
300 : // but do not call allow_erase on their indices.
301 84 : if (epoch_unused_count >= epoch_size) {
302 3145752 : for (uint32_t i = 0; i < size; ++i)
303 6291456 : if (epoch_flags[i])
304 1622326 : epoch_flags[i] = false;
305 : else
306 1523402 : allow_erase(i);
307 24 : epoch_heuristic_counter = epoch_size;
308 24 : } else
309 : // reset the epoch_heuristic_counter to next do a scan when worst
310 : // case behavior (no intermittent erases) would exceed epoch size,
311 : // with a reasonable minimum scan size.
312 : // Ordinarily, we would have to sanity check std::min(epoch_size,
313 : // epoch_unused_count), but we already know that `epoch_unused_count
314 : // < epoch_size` in this branch
315 120 : epoch_heuristic_counter = std::max(1u, std::max(epoch_size / 16,
316 60 : epoch_size - epoch_unused_count));
317 2090447 : }
318 :
319 : public:
320 : /** You must always construct a cache with some elements via a subsequent
321 : * call to setup or setup_bytes, otherwise operations may segfault.
322 : */
323 903 : cache() : table(), collection_flags(0), epoch_flags(), hash_function()
324 301 : {
325 602 : }
326 :
327 : /** setup initializes the container to store no more than new_size
328 : * elements.
329 : *
330 : * setup should only be called once.
331 : *
332 : * @param new_size the desired number of elements to store
333 : * @returns the maximum number of elements storable
334 : */
335 1264 : uint32_t setup(uint32_t new_size)
336 : {
337 : // depth_limit must be at least one otherwise errors can occur.
338 1264 : depth_limit = static_cast<uint8_t>(std::log2(static_cast<float>(std::max((uint32_t)2, new_size))));
339 1264 : size = std::max<uint32_t>(2, new_size);
340 1264 : table.resize(size);
341 1264 : collection_flags.setup(size);
342 1264 : epoch_flags.resize(size);
343 : // Set to 45% as described above
344 1264 : epoch_size = std::max(uint32_t{1}, (45 * size) / 100);
345 : // Initially set to wait for a whole epoch
346 1264 : epoch_heuristic_counter = epoch_size;
347 1264 : return size;
348 : }
349 :
350 : /** setup_bytes is a convenience function which accounts for internal memory
351 : * usage when deciding how many elements to store. It isn't perfect because
352 : * it doesn't account for any overhead (struct size, MallocUsage, collection
353 : * and epoch flags). This was done to simplify selecting a power of two
354 : * size. In the expected use case, an extra two bits per entry should be
355 : * negligible compared to the size of the elements.
356 : *
357 : * @param bytes the approximate number of bytes to use for this data
358 : * structure
359 : * @returns the maximum number of elements storable (see setup()
360 : * documentation for more detail)
361 : */
362 1264 : uint32_t setup_bytes(size_t bytes)
363 : {
364 1264 : return setup(bytes/sizeof(Element));
365 : }
366 :
367 : /** insert loops at most depth_limit times trying to insert a hash
368 : * at various locations in the table via a variant of the Cuckoo Algorithm
369 : * with eight hash locations.
370 : *
371 : * It drops the last tried element if it runs out of depth before
372 : * encountering an open slot.
373 : *
374 : * Thus:
375 : *
376 : * ```
377 : * insert(x);
378 : * return contains(x, false);
379 : * ```
380 : *
381 : * is not guaranteed to return true.
382 : *
383 : * @param e the element to insert
384 : * @post one of the following: All previously inserted elements and e are
385 : * now in the table, one previously inserted element is evicted from the
386 : * table, the entry attempted to be inserted is evicted.
387 : */
388 2090447 : inline void insert(Element e)
389 : {
390 2090447 : epoch_check();
391 2090447 : uint32_t last_loc = invalid();
392 2090447 : bool last_epoch = true;
393 2090447 : std::array<uint32_t, 8> locs = compute_hashes(e);
394 : // Make sure we have not already inserted this element
395 : // If we have, make sure that it does not get deleted
396 18814023 : for (const uint32_t loc : locs)
397 16723576 : if (table[loc] == e) {
398 0 : please_keep(loc);
399 0 : epoch_flags[loc] = last_epoch;
400 0 : return;
401 : }
402 2176249 : for (uint8_t depth = 0; depth < depth_limit; ++depth) {
403 : // First try to insert to an empty slot, if one exists
404 5441287 : for (const uint32_t loc : locs) {
405 5355485 : if (!collection_flags.bit_is_set(loc))
406 3265038 : continue;
407 2090447 : table[loc] = std::move(e);
408 2090447 : please_keep(loc);
409 2090447 : epoch_flags[loc] = last_epoch;
410 2090447 : return;
411 : }
412 : /** Swap with the element at the location that was
413 : * not the last one looked at. Example:
414 : *
415 : * 1. On first iteration, last_loc == invalid(), find returns last, so
416 : * last_loc defaults to locs[0].
417 : * 2. On further iterations, where last_loc == locs[k], last_loc will
418 : * go to locs[k+1 % 8], i.e., next of the 8 indices wrapping around
419 : * to 0 if needed.
420 : *
421 : * This prevents moving the element we just put in.
422 : *
423 : * The swap is not a move -- we must switch onto the evicted element
424 : * for the next iteration.
425 : */
426 85802 : last_loc = locs[(1 + (std::find(locs.begin(), locs.end(), last_loc) - locs.begin())) & 7];
427 85802 : std::swap(table[last_loc], e);
428 : // Can't std::swap a std::vector<bool>::reference and a bool&.
429 85802 : bool epoch = last_epoch;
430 85802 : last_epoch = epoch_flags[last_loc];
431 85802 : epoch_flags[last_loc] = epoch;
432 :
433 : // Recompute the locs -- unfortunately happens one too many times!
434 85802 : locs = compute_hashes(e);
435 85802 : }
436 2090447 : }
437 :
438 : /** contains iterates through the hash locations for a given element
439 : * and checks to see if it is present.
440 : *
441 : * contains does not check garbage collected state (in other words,
442 : * garbage is only collected when the space is needed), so:
443 : *
444 : * ```
445 : * insert(x);
446 : * if (contains(x, true))
447 : * return contains(x, false);
448 : * else
449 : * return true;
450 : * ```
451 : *
452 : * executed on a single thread will always return true!
453 : *
454 : * This is a great property for re-org performance for example.
455 : *
456 : * contains returns a bool set true if the element was found.
457 : *
458 : * @param e the element to check
459 : * @param erase whether to attempt setting the garbage collect flag
460 : *
461 : * @post if erase is true and the element is found, then the garbage collect
462 : * flag is set
463 : * @returns true if the element is found, false otherwise
464 : */
465 1583097 : inline bool contains(const Element& e, const bool erase) const
466 : {
467 1583097 : std::array<uint32_t, 8> locs = compute_hashes(e);
468 5559498 : for (const uint32_t loc : locs)
469 5232367 : if (table[loc] == e) {
470 1255966 : if (erase)
471 674730 : allow_erase(loc);
472 1255966 : return true;
473 : }
474 327131 : return false;
475 1583097 : }
476 : };
477 : } // namespace CuckooCache
478 :
479 : #endif // BITCOIN_CUCKOOCACHE_H
|
