src/cuckoocache.h

   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 <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 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     bit_packed_atomic_flags(uint32_t size)
  62     {
  63         // pad out the size if needed
  64         size = (size + 7) / 8;
  65         mem.reset(new std::atomic<uint8_t>[size]);
  66         for (uint32_t i = 0; i < size; ++i)
  67             mem[i].store(0xFF);
  68     };
  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     inline void setup(uint32_t b)
  80     {
  81         bit_packed_atomic_flags d(b);
  82         std::swap(mem, d.mem);
  83     }
  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     inline void bit_set(uint32_t s)
  93     {
  94         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     inline void bit_unset(uint32_t s)
 104     {
 105         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     inline bool bit_is_set(uint32_t s) const
 114     {
 115         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     inline std::array<uint32_t, 8> compute_hashes(const Element& e) const
 219     {
 220         return {{hash_function.template operator()<0>(e) & hash_mask,
 221                  hash_function.template operator()<1>(e) & hash_mask,
 222                  hash_function.template operator()<2>(e) & hash_mask,
 223                  hash_function.template operator()<3>(e) & hash_mask,
 224                  hash_function.template operator()<4>(e) & hash_mask,
 225                  hash_function.template operator()<5>(e) & hash_mask,
 226                  hash_function.template operator()<6>(e) & hash_mask,
 227                  hash_function.template operator()<7>(e) & hash_mask}};
 228     }
 229
 230     /* end
 231      * @returns a constexpr index that can never be inserted to */
 232     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     inline void allow_erase(uint32_t n) const
 242     {
 243         collection_flags.bit_set(n);
 244     }
 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     inline void please_keep(uint32_t n) const
 251     {
 252         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     void epoch_check()
 265     {
 266         if (epoch_heuristic_counter != 0) {
 267             --epoch_heuristic_counter;
 268             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         for (uint32_t i = 0; i < size; ++i)
 274             epoch_unused_count += epoch_flags[i] &&
 275                                   !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         if (epoch_unused_count >= epoch_size) {
 281             for (uint32_t i = 0; i < size; ++i)
 282                 if (epoch_flags[i])
 283                     epoch_flags[i] = false;
 284                 else
 285                     allow_erase(i);
 286             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             epoch_heuristic_counter = std::max(1u, std::max(epoch_size / 16,
 295                         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     cache() : table(), size(), collection_flags(0), epoch_flags(),
 303     epoch_heuristic_counter(), epoch_size(), depth_limit(0), hash_function()
 304     {
 305     }
 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     uint32_t setup(uint32_t new_size)
 316     {
 317         // depth_limit must be at least one otherwise errors can occur.
 318         depth_limit = static_cast<uint8_t>(std::log2(static_cast<float>(std::max((uint32_t)2, new_size))));
 319         size = 1 << depth_limit;
 320         hash_mask = size-1;
 321         table.resize(size);
 322         collection_flags.setup(size);
 323         epoch_flags.resize(size);
 324         // Set to 45% as described above
 325         epoch_size = std::max((uint32_t)1, (45 * size) / 100);
 326         // Initially set to wait for a whole epoch
 327         epoch_heuristic_counter = epoch_size;
 328         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     uint32_t setup_bytes(size_t bytes)
 344     {
 345         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     inline void insert(Element e)
 369     {
 370         epoch_check();
 371         uint32_t last_loc = invalid();
 372         bool last_epoch = true;
 373         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         for (uint32_t loc : locs)
 377             if (table[loc] == e) {
 378                 please_keep(loc);
 379                 epoch_flags[loc] = last_epoch;
 380                 return;
 381             }
 382         for (uint8_t depth = 0; depth < depth_limit; ++depth) {
 383             // First try to insert to an empty slot, if one exists
 384             for (uint32_t loc : locs) {
 385                 if (!collection_flags.bit_is_set(loc))
 386                     continue;
 387                 table[loc] = std::move(e);
 388                 please_keep(loc);
 389                 epoch_flags[loc] = last_epoch;
 390                 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             last_loc = locs[(1 + (std::find(locs.begin(), locs.end(), last_loc) - locs.begin())) & 7];
 407             std::swap(table[last_loc], e);
 408             // Can't std::swap a std::vector<bool>::reference and a bool&.
 409             bool epoch = last_epoch;
 410             last_epoch = epoch_flags[last_loc];
 411             epoch_flags[last_loc] = epoch;
 412
 413             // Recompute the locs -- unfortunately happens one too many times!
 414             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     inline bool contains(const Element& e, const bool erase) const
 444     {
 445         std::array<uint32_t, 8> locs = compute_hashes(e);
 446         for (uint32_t loc : locs)
 447             if (table[loc] == e) {
 448                 if (erase)
 449                     allow_erase(loc);
 450                 return true;
 451             }
 452         return false;
 453     }
 454 };
 455 } // namespace CuckooCache
 456
 457 #endif