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#include <util/overflow.h>
10
11#include <algorithm>
12#include <array>
13#include <atomic>
14#include <cmath>
15#include <cstring>
16#include <limits>
17#include <memory>
18#include <utility>
19#include <vector>
20
21
22/** High-performance cache primitives.
23 *
24 * Summary:
25 *
26 * 1. @ref bit_packed_atomic_flags is bit-packed atomic flags for garbage collection
27 *
28 * 2. @ref cache is a cache which is performant in memory usage and lookup speed. It
29 * is lockfree for erase operations. Elements are lazily erased on the next insert.
30 */
31namespace CuckooCache
32{
33/** @ref bit_packed_atomic_flags implements a container for garbage collection flags
34 * that is only thread unsafe on calls to setup. This class bit-packs collection
35 * flags for memory efficiency.
36 *
37 * All operations are `std::memory_order_relaxed` so external mechanisms must
38 * ensure that writes and reads are properly synchronized.
39 *
40 * On setup(n), all bits up to `n` are marked as collected.
41 *
42 * Under the hood, because it is an 8-bit type, it makes sense to use a multiple
43 * of 8 for setup, but it will be safe if that is not the case as well.
44 */
45class bit_packed_atomic_flags
46{
47    std::unique_ptr<std::atomic<uint8_t>[]> mem;
48
49public:
50    /** No default constructor, as there must be some size. */
51    bit_packed_atomic_flags() = delete;
52
53    /**
54     * bit_packed_atomic_flags constructor creates memory to sufficiently
55     * keep track of garbage collection information for `size` entries.
56     *
57     * @param size the number of elements to allocate space for
58     *
59     * @post bit_set, bit_unset, and bit_is_set function properly forall x. x <
60     * size
61     * @post All calls to bit_is_set (without subsequent bit_unset) will return
62     * true.
63     */
64    explicit bit_packed_atomic_flags(uint32_t size)
65    {
66        // pad out the size if needed
67        size = CeilDiv(size, 8u);
68        mem.reset(new std::atomic<uint8_t>[size]);
69        for (uint32_t i = 0; i < size; ++i)
70            mem[i].store(0xFF);
71    };
72
73    /** setup marks all entries and ensures that bit_packed_atomic_flags can store
74     * at least `b` entries.
75     *
76     * @param b the number of elements to allocate space for
77     * @post bit_set, bit_unset, and bit_is_set function properly forall x. x <
78     * b
79     * @post All calls to bit_is_set (without subsequent bit_unset) will return
80     * true.
81     */
82    inline void setup(uint32_t b)
83    {
84        bit_packed_atomic_flags d(b);
85        std::swap(mem, d.mem);
86    }
87
88    /** bit_set sets an entry as discardable.
89     *
90     * @param s the index of the entry to bit_set
91     * @post immediately subsequent call (assuming proper external memory
92     * ordering) to bit_is_set(s) == true.
93     */
94    inline void bit_set(uint32_t s)
95    {
96        mem[s >> 3].fetch_or(uint8_t(1 << (s & 7)), std::memory_order_relaxed);
97    }
98
99    /** bit_unset marks an entry as something that should not be overwritten.
100     *
101     * @param s the index of the entry to bit_unset
102     * @post immediately subsequent call (assuming proper external memory
103     * ordering) to bit_is_set(s) == false.
104     */
105    inline void bit_unset(uint32_t s)
106    {
107        mem[s >> 3].fetch_and(uint8_t(~(1 << (s & 7))), std::memory_order_relaxed);
108    }
109
110    /** bit_is_set queries the table for discardability at `s`.
111     *
112     * @param s the index of the entry to read
113     * @returns true if the bit at index `s` was set, false otherwise
114     * */
115    inline bool bit_is_set(uint32_t s) const
116    {
117        return (1 << (s & 7)) & mem[s >> 3].load(std::memory_order_relaxed);
118    }
119};
120
121/** @ref cache implements a cache with properties similar to a cuckoo-set.
122 *
123 *  The cache is able to hold up to `(~(uint32_t)0) - 1` elements.
124 *
125 *  Read Operations:
126 *      - contains() for `erase=false`
127 *
128 *  Read+Erase Operations:
129 *      - contains() for `erase=true`
130 *
131 *  Erase Operations:
132 *      - allow_erase()
133 *
134 *  Write Operations:
135 *      - setup()
136 *      - setup_bytes()
137 *      - insert()
138 *      - please_keep()
139 *
140 *  Synchronization Free Operations:
141 *      - invalid()
142 *      - compute_hashes()
143 *
144 * User Must Guarantee:
145 *
146 * 1. Write requires synchronized access (e.g. a lock)
147 * 2. Read requires no concurrent Write, synchronized with last insert.
148 * 3. Erase requires no concurrent Write, synchronized with last insert.
149 * 4. An Erase caller must release all memory before allowing a new Writer.
150 *
151 *
152 * Note on function names:
153 *   - The name "allow_erase" is used because the real discard happens later.
154 *   - The name "please_keep" is used because elements may be erased anyways on insert.
155 *
156 * @tparam Element should be a movable and copyable type
157 * @tparam Hash should be a function/callable which takes a template parameter
158 * hash_select and an Element and extracts a hash from it. Should return
159 * high-entropy uint32_t hashes for `Hash h; h<0>(e) ... h<7>(e)`.
160 */
161template <typename Element, typename Hash>
162class cache
163{
164private:
165    /** table stores all the elements */
166    std::vector<Element> table;
167
168    /** size stores the total available slots in the hash table */
169    uint32_t size{0};
170
171    /** The bit_packed_atomic_flags array is marked mutable because we want
172     * garbage collection to be allowed to occur from const methods */
173    mutable bit_packed_atomic_flags collection_flags;
174
175    /** epoch_flags tracks how recently an element was inserted into
176     * the cache. true denotes recent, false denotes not-recent. See insert()
177     * method for full semantics.
178     */
179    mutable std::vector<bool> epoch_flags;
180
181    /** epoch_heuristic_counter is used to determine when an epoch might be aged
182     * & an expensive scan should be done. epoch_heuristic_counter is
183     * decremented on insert and reset to the new number of inserts which would
184     * cause the epoch to reach epoch_size when it reaches zero.
185     */
186    uint32_t epoch_heuristic_counter{0};
187
188    /** epoch_size is set to be the number of elements supposed to be in a
189     * epoch. When the number of non-erased elements in an epoch
190     * exceeds epoch_size, a new epoch should be started and all
191     * current entries demoted. epoch_size is set to be 45% of size because
192     * we want to keep load around 90%, and we support 3 epochs at once --
193     * one "dead" which has been erased, one "dying" which has been marked to be
194     * erased next, and one "living" which new inserts add to.
195     */
196    uint32_t epoch_size{0};
197
198    /** depth_limit determines how many elements insert should try to replace.
199     * Should be set to log2(n).
200     */
201    uint8_t depth_limit{0};
202
203    /** hash_function is a const instance of the hash function. It cannot be
204     * static or initialized at call time as it may have internal state (such as
205     * a nonce).
206     */
207    const Hash hash_function;
208
209    /** compute_hashes is convenience for not having to write out this
210     * expression everywhere we use the hash values of an Element.
211     *
212     * We need to map the 32-bit input hash onto a hash bucket in a range [0, size) in a
213     *  manner which preserves as much of the hash's uniformity as possible. Ideally
214     *  this would be done by bitmasking but the size is usually not a power of two.
215     *
216     * The naive approach would be to use a mod -- which isn't perfectly uniform but so
217     *  long as the hash is much larger than size it is not that bad. Unfortunately,
218     *  mod/division is fairly slow on ordinary microprocessors (e.g. 90-ish cycles on
219     *  haswell, ARM doesn't even have an instruction for it.); when the divisor is a
220     *  constant the compiler will do clever tricks to turn it into a multiply+add+shift,
221     *  but size is a run-time value so the compiler can't do that here.
222     *
223     * One option would be to implement the same trick the compiler uses and compute the
224     *  constants for exact division based on the size, as described in "{N}-bit Unsigned
225     *  Division via {N}-bit Multiply-Add" by Arch D. Robison in 2005. But that code is
226     *  somewhat complicated and the result is still slower than an even simpler option:
227     *  see the FastRange32 function in util/fastrange.h.
228     *
229     * The resulting non-uniformity is also more equally distributed which would be
230     *  advantageous for something like linear probing, though it shouldn't matter
231     *  one way or the other for a cuckoo table.
232     *
233     * The primary disadvantage of this approach is increased intermediate precision is
234     *  required but for a 32-bit random number we only need the high 32 bits of a
235     *  32*32->64 multiply, which means the operation is reasonably fast even on a
236     *  typical 32-bit processor.
237     *
238     * @param e The element whose hashes will be returned
239     * @returns Deterministic hashes derived from `e` uniformly mapped onto the range [0, size)
240     */
241    inline std::array<uint32_t, 8> compute_hashes(const Element& e) const
242    {
243        return {{FastRange32(hash_function.template operator()<0>(e), size),
244                 FastRange32(hash_function.template operator()<1>(e), size),
245                 FastRange32(hash_function.template operator()<2>(e), size),
246                 FastRange32(hash_function.template operator()<3>(e), size),
247                 FastRange32(hash_function.template operator()<4>(e), size),
248                 FastRange32(hash_function.template operator()<5>(e), size),
249                 FastRange32(hash_function.template operator()<6>(e), size),
250                 FastRange32(hash_function.template operator()<7>(e), size)}};