@nxtedition/rocksdb 7.1.20 → 7.1.21

package/deps/rocksdb/rocksdb/cache/lru_cache.h

@@ -38,21 +38,14 @@ namespace lru_cache {
 //    (refs == 0 && in_cache == true)
 // 3. Referenced externally AND not in hash table.
 //    In that case the entry is not in the LRU list and not in hash table.
-//    The entry can be freed when refs becomes 0.
+//    The entry must be freed if refs becomes 0 in this state.
 //    (refs >= 1 && in_cache == false)
-// 4. The handle is never inserted into the LRUCache (both hash table and LRU
-//    list) and it doesn't experience the above three states.
-//    The entry can be freed when refs becomes 0.
-//    (refs >= 1 && in_cache == false && IS_STANDALONE == true)
-// All newly created LRUHandles are in state 1 or 4. If you call
-// LRUCacheShard::Release on entry in state 1, it will go into state 2.
-// To move from state 1 to state 3, either call LRUCacheShard::Erase or
-// LRUCacheShard::Insert with the same key (but possibly different value).
-// To move from state 2 to state 1, use LRUCacheShard::Lookup.
-// Before destruction, make sure that no handles are in state 1. This means
-// that any successful LRUCacheShard::Lookup/LRUCacheShard::Insert have a
-// matching LRUCache::Release (to move into state 2) or LRUCacheShard::Erase
-// (to move into state 3).
+// If you call LRUCacheShard::Release enough times on an entry in state 1, it
+// will go into state 2. To move from state 1 to state 3, either call
+// LRUCacheShard::Erase or LRUCacheShard::Insert with the same key (but
+// possibly different value). To move from state 2 to state 1, use
+// LRUCacheShard::Lookup.
+// While refs > 0, public properties like value and deleter must not change.
 
 struct LRUHandle {
   void* value;
@@ -60,7 +53,7 @@ struct LRUHandle {
     Info() {}
     ~Info() {}
     Cache::DeleterFn deleter;
-    const ShardedCache::CacheItemHelper* helper;
+    const Cache::CacheItemHelper* helper;
   } info_;
   // An entry is not added to the LRUHandleTable until the secondary cache
   // lookup is complete, so its safe to have this union.
@@ -77,45 +70,47 @@ struct LRUHandle {
   // The number of external refs to this entry. The cache itself is not counted.
   uint32_t refs;
 
-  enum Flags : uint16_t {
+  // Mutable flags - access controlled by mutex
+  // The m_ and M_ prefixes (and im_ and IM_ later) are to hopefully avoid
+  // checking an M_ flag on im_flags or an IM_ flag on m_flags.
+  uint8_t m_flags;
+  enum MFlags : uint8_t {
     // Whether this entry is referenced by the hash table.
-    IN_CACHE = (1 << 0),
-    // Whether this entry is high priority entry.
-    IS_HIGH_PRI = (1 << 1),
-    // Whether this entry is in high-pri pool.
-    IN_HIGH_PRI_POOL = (1 << 2),
+    M_IN_CACHE = (1 << 0),
     // Whether this entry has had any lookups (hits).
-    HAS_HIT = (1 << 3),
+    M_HAS_HIT = (1 << 1),
+    // Whether this entry is in high-pri pool.
+    M_IN_HIGH_PRI_POOL = (1 << 2),
+    // Whether this entry is in low-pri pool.
+    M_IN_LOW_PRI_POOL = (1 << 3),
+  };
+
+  // "Immutable" flags - only set in single-threaded context and then
+  // can be accessed without mutex
+  uint8_t im_flags;
+  enum ImFlags : uint8_t {
+    // Whether this entry is high priority entry.
+    IM_IS_HIGH_PRI = (1 << 0),
+    // Whether this entry is low priority entry.
+    IM_IS_LOW_PRI = (1 << 1),
     // Can this be inserted into the secondary cache.
-    IS_SECONDARY_CACHE_COMPATIBLE = (1 << 4),
+    IM_IS_SECONDARY_CACHE_COMPATIBLE = (1 << 2),
     // Is the handle still being read from a lower tier.
-    IS_PENDING = (1 << 5),
+    IM_IS_PENDING = (1 << 3),
     // Whether this handle is still in a lower tier
-    IS_IN_SECONDARY_CACHE = (1 << 6),
-    // Whether this entry is low priority entry.
-    IS_LOW_PRI = (1 << 7),
-    // Whether this entry is in low-pri pool.
-    IN_LOW_PRI_POOL = (1 << 8),
-    // Whether this entry is not inserted into the cache (both hash table and
-    // LRU list).
-    IS_STANDALONE = (1 << 9),
+    IM_IS_IN_SECONDARY_CACHE = (1 << 4),
+    // Marks result handles that should not be inserted into cache
+    IM_IS_STANDALONE = (1 << 5),
   };
 
-  uint16_t flags;
-
-#ifdef __SANITIZE_THREAD__
-  // TSAN can report a false data race on flags, where one thread is writing
-  // to one of the mutable bits and another thread is reading this immutable
-  // bit. So precisely suppress that TSAN warning, we separate out this bit
-  // during TSAN runs.
-  bool is_secondary_cache_compatible_for_tsan;
-#endif  // __SANITIZE_THREAD__
-
   // Beginning of the key (MUST BE THE LAST FIELD IN THIS STRUCT!)
   char key_data[1];
 
   Slice key() const { return Slice(key_data, key_length); }
 
+  // For HandleImpl concept
+  uint32_t GetHash() const { return hash; }
+
   // Increase the reference count by 1.
   void Ref() { refs++; }
 
@@ -129,104 +124,94 @@ struct LRUHandle {
   // Return true if there are external refs, false otherwise.
   bool HasRefs() const { return refs > 0; }
 
-  bool InCache() const { return flags & IN_CACHE; }
-  bool IsHighPri() const { return flags & IS_HIGH_PRI; }
-  bool InHighPriPool() const { return flags & IN_HIGH_PRI_POOL; }
-  bool IsLowPri() const { return flags & IS_LOW_PRI; }
-  bool InLowPriPool() const { return flags & IN_LOW_PRI_POOL; }
-  bool HasHit() const { return flags & HAS_HIT; }
+  bool InCache() const { return m_flags & M_IN_CACHE; }
+  bool IsHighPri() const { return im_flags & IM_IS_HIGH_PRI; }
+  bool InHighPriPool() const { return m_flags & M_IN_HIGH_PRI_POOL; }
+  bool IsLowPri() const { return im_flags & IM_IS_LOW_PRI; }
+  bool InLowPriPool() const { return m_flags & M_IN_LOW_PRI_POOL; }
+  bool HasHit() const { return m_flags & M_HAS_HIT; }
   bool IsSecondaryCacheCompatible() const {
-#ifdef __SANITIZE_THREAD__
-    return is_secondary_cache_compatible_for_tsan;
-#else
-    return flags & IS_SECONDARY_CACHE_COMPATIBLE;
-#endif  // __SANITIZE_THREAD__
+    return im_flags & IM_IS_SECONDARY_CACHE_COMPATIBLE;
+  }
+  bool IsPending() const { return im_flags & IM_IS_PENDING; }
+  bool IsInSecondaryCache() const {
+    return im_flags & IM_IS_IN_SECONDARY_CACHE;
   }
-  bool IsPending() const { return flags & IS_PENDING; }
-  bool IsInSecondaryCache() const { return flags & IS_IN_SECONDARY_CACHE; }
-  bool IsStandalone() const { return flags & IS_STANDALONE; }
+  bool IsStandalone() const { return im_flags & IM_IS_STANDALONE; }
 
   void SetInCache(bool in_cache) {
     if (in_cache) {
-      flags |= IN_CACHE;
+      m_flags |= M_IN_CACHE;
     } else {
-      flags &= ~IN_CACHE;
+      m_flags &= ~M_IN_CACHE;
     }
   }
 
   void SetPriority(Cache::Priority priority) {
     if (priority == Cache::Priority::HIGH) {
-      flags |= IS_HIGH_PRI;
-      flags &= ~IS_LOW_PRI;
+      im_flags |= IM_IS_HIGH_PRI;
+      im_flags &= ~IM_IS_LOW_PRI;
     } else if (priority == Cache::Priority::LOW) {
-      flags &= ~IS_HIGH_PRI;
-      flags |= IS_LOW_PRI;
+      im_flags &= ~IM_IS_HIGH_PRI;
+      im_flags |= IM_IS_LOW_PRI;
     } else {
-      flags &= ~IS_HIGH_PRI;
-      flags &= ~IS_LOW_PRI;
+      im_flags &= ~IM_IS_HIGH_PRI;
+      im_flags &= ~IM_IS_LOW_PRI;
     }
   }
 
   void SetInHighPriPool(bool in_high_pri_pool) {
     if (in_high_pri_pool) {
-      flags |= IN_HIGH_PRI_POOL;
+      m_flags |= M_IN_HIGH_PRI_POOL;
     } else {
-      flags &= ~IN_HIGH_PRI_POOL;
+      m_flags &= ~M_IN_HIGH_PRI_POOL;
     }
   }
 
   void SetInLowPriPool(bool in_low_pri_pool) {
     if (in_low_pri_pool) {
-      flags |= IN_LOW_PRI_POOL;
+      m_flags |= M_IN_LOW_PRI_POOL;
     } else {
-      flags &= ~IN_LOW_PRI_POOL;
+      m_flags &= ~M_IN_LOW_PRI_POOL;
     }
   }
 
-  void SetHit() { flags |= HAS_HIT; }
+  void SetHit() { m_flags |= M_HAS_HIT; }
 
   void SetSecondaryCacheCompatible(bool compat) {
     if (compat) {
-      flags |= IS_SECONDARY_CACHE_COMPATIBLE;
+      im_flags |= IM_IS_SECONDARY_CACHE_COMPATIBLE;
     } else {
-      flags &= ~IS_SECONDARY_CACHE_COMPATIBLE;
+      im_flags &= ~IM_IS_SECONDARY_CACHE_COMPATIBLE;
     }
-#ifdef __SANITIZE_THREAD__
-    is_secondary_cache_compatible_for_tsan = compat;
-#endif  // __SANITIZE_THREAD__
   }
 
-  void SetIncomplete(bool incomp) {
-    if (incomp) {
-      flags |= IS_PENDING;
+  void SetIsPending(bool pending) {
+    if (pending) {
+      im_flags |= IM_IS_PENDING;
     } else {
-      flags &= ~IS_PENDING;
+      im_flags &= ~IM_IS_PENDING;
     }
   }
 
   void SetIsInSecondaryCache(bool is_in_secondary_cache) {
     if (is_in_secondary_cache) {
-      flags |= IS_IN_SECONDARY_CACHE;
+      im_flags |= IM_IS_IN_SECONDARY_CACHE;
     } else {
-      flags &= ~IS_IN_SECONDARY_CACHE;
+      im_flags &= ~IM_IS_IN_SECONDARY_CACHE;
     }
   }
 
   void SetIsStandalone(bool is_standalone) {
     if (is_standalone) {
-      flags |= IS_STANDALONE;
+      im_flags |= IM_IS_STANDALONE;
     } else {
-      flags &= ~IS_STANDALONE;
+      im_flags &= ~IM_IS_STANDALONE;
     }
   }
 
   void Free() {
     assert(refs == 0);
-#ifdef __SANITIZE_THREAD__
-    // Here we can safely assert they are the same without a data race reported
-    assert(((flags & IS_SECONDARY_CACHE_COMPATIBLE) != 0) ==
-           is_secondary_cache_compatible_for_tsan);
-#endif  // __SANITIZE_THREAD__
     if (!IsSecondaryCacheCompatible() && info_.deleter) {
       (*info_.deleter)(key(), value);
     } else if (IsSecondaryCacheCompatible()) {
@@ -280,9 +265,6 @@ struct LRUHandle {
 // 4.4.3's builtin hashtable.
 class LRUHandleTable {
  public:
-  // If the table uses more hash bits than `max_upper_hash_bits`,
-  // it will eat into the bits used for sharding, which are constant
-  // for a given LRUHandleTable.
   explicit LRUHandleTable(int max_upper_hash_bits);
   ~LRUHandleTable();
 
@@ -291,8 +273,8 @@ class LRUHandleTable {
   LRUHandle* Remove(const Slice& key, uint32_t hash);
 
   template <typename T>
-  void ApplyToEntriesRange(T func, uint32_t index_begin, uint32_t index_end) {
-    for (uint32_t i = index_begin; i < index_end; i++) {
+  void ApplyToEntriesRange(T func, size_t index_begin, size_t index_end) {
+    for (size_t i = index_begin; i < index_end; i++) {
       LRUHandle* h = list_[i];
       while (h != nullptr) {
         auto n = h->next_hash;
@@ -331,23 +313,31 @@ class LRUHandleTable {
 };
 
 // A single shard of sharded cache.
-class ALIGN_AS(CACHE_LINE_SIZE) LRUCacheShard final : public CacheShard {
+class ALIGN_AS(CACHE_LINE_SIZE) LRUCacheShard final : public CacheShardBase {
  public:
   LRUCacheShard(size_t capacity, bool strict_capacity_limit,
                 double high_pri_pool_ratio, double low_pri_pool_ratio,
                 bool use_adaptive_mutex,
                 CacheMetadataChargePolicy metadata_charge_policy,
-                int max_upper_hash_bits,
-                const std::shared_ptr<SecondaryCache>& secondary_cache);
-  virtual ~LRUCacheShard() override = default;
+                int max_upper_hash_bits, SecondaryCache* secondary_cache);
+
+ public:  // Type definitions expected as parameter to ShardedCache
+  using HandleImpl = LRUHandle;
+  using HashVal = uint32_t;
+  using HashCref = uint32_t;
+
+ public:  // Function definitions expected as parameter to ShardedCache
+  static inline HashVal ComputeHash(const Slice& key) {
+    return Lower32of64(GetSliceNPHash64(key));
+  }
 
   // Separate from constructor so caller can easily make an array of LRUCache
   // if current usage is more than new capacity, the function will attempt to
   // free the needed space.
-  virtual void SetCapacity(size_t capacity) override;
+  void SetCapacity(size_t capacity);
 
   // Set the flag to reject insertion if cache if full.
-  virtual void SetStrictCapacityLimit(bool strict_capacity_limit) override;
+  void SetStrictCapacityLimit(bool strict_capacity_limit);
 
   // Set percentage of capacity reserved for high-pri cache entries.
   void SetHighPriorityPoolRatio(double high_pri_pool_ratio);
@@ -356,58 +346,49 @@ class ALIGN_AS(CACHE_LINE_SIZE) LRUCacheShard final : public CacheShard {
   void SetLowPriorityPoolRatio(double low_pri_pool_ratio);
 
   // Like Cache methods, but with an extra "hash" parameter.
-  virtual Status Insert(const Slice& key, uint32_t hash, void* value,
-                        size_t charge, Cache::DeleterFn deleter,
-                        Cache::Handle** handle,
-                        Cache::Priority priority) override {
+  inline Status Insert(const Slice& key, uint32_t hash, void* value,
+                       size_t charge, Cache::DeleterFn deleter,
+                       LRUHandle** handle, Cache::Priority priority) {
     return Insert(key, hash, value, charge, deleter, nullptr, handle, priority);
   }
-  virtual Status Insert(const Slice& key, uint32_t hash, void* value,
-                        const Cache::CacheItemHelper* helper, size_t charge,
-                        Cache::Handle** handle,
-                        Cache::Priority priority) override {
+  inline Status Insert(const Slice& key, uint32_t hash, void* value,
+                       const Cache::CacheItemHelper* helper, size_t charge,
+                       LRUHandle** handle, Cache::Priority priority) {
     assert(helper);
     return Insert(key, hash, value, charge, nullptr, helper, handle, priority);
   }
   // If helper_cb is null, the values of the following arguments don't matter.
-  virtual Cache::Handle* Lookup(const Slice& key, uint32_t hash,
-                                const ShardedCache::CacheItemHelper* helper,
-                                const ShardedCache::CreateCallback& create_cb,
-                                ShardedCache::Priority priority, bool wait,
-                                Statistics* stats) override;
-  virtual Cache::Handle* Lookup(const Slice& key, uint32_t hash) override {
+  LRUHandle* Lookup(const Slice& key, uint32_t hash,
+                    const Cache::CacheItemHelper* helper,
+                    const Cache::CreateCallback& create_cb,
+                    Cache::Priority priority, bool wait, Statistics* stats);
+  inline LRUHandle* Lookup(const Slice& key, uint32_t hash) {
     return Lookup(key, hash, nullptr, nullptr, Cache::Priority::LOW, true,
                   nullptr);
   }
-  virtual bool Release(Cache::Handle* handle, bool /*useful*/,
-                       bool erase_if_last_ref) override {
-    return Release(handle, erase_if_last_ref);
-  }
-  virtual bool IsReady(Cache::Handle* /*handle*/) override;
-  virtual void Wait(Cache::Handle* /*handle*/) override {}
-  virtual bool Ref(Cache::Handle* handle) override;
-  virtual bool Release(Cache::Handle* handle,
-                       bool erase_if_last_ref = false) override;
-  virtual void Erase(const Slice& key, uint32_t hash) override;
+  bool Release(LRUHandle* handle, bool useful, bool erase_if_last_ref);
+  bool IsReady(LRUHandle* /*handle*/);
+  void Wait(LRUHandle* /*handle*/) {}
+  bool Ref(LRUHandle* handle);
+  void Erase(const Slice& key, uint32_t hash);
 
   // Although in some platforms the update of size_t is atomic, to make sure
   // GetUsage() and GetPinnedUsage() work correctly under any platform, we'll
   // protect them with mutex_.
 
-  virtual size_t GetUsage() const override;
-  virtual size_t GetPinnedUsage() const override;
-  virtual size_t GetOccupancyCount() const override;
-  virtual size_t GetTableAddressCount() const override;
+  size_t GetUsage() const;
+  size_t GetPinnedUsage() const;
+  size_t GetOccupancyCount() const;
+  size_t GetTableAddressCount() const;
 
-  virtual void ApplyToSomeEntries(
+  void ApplyToSomeEntries(
       const std::function<void(const Slice& key, void* value, size_t charge,
                                DeleterFn deleter)>& callback,
-      uint32_t average_entries_per_lock, uint32_t* state) override;
-
-  virtual void EraseUnRefEntries() override;
+      size_t average_entries_per_lock, size_t* state);
 
-  virtual std::string GetPrintableOptions() const override;
+  void EraseUnRefEntries();
 
+ public:  // other function definitions
   void TEST_GetLRUList(LRUHandle** lru, LRUHandle** lru_low_pri,
                        LRUHandle** lru_bottom_pri);
 
@@ -421,17 +402,19 @@ class ALIGN_AS(CACHE_LINE_SIZE) LRUCacheShard final : public CacheShard {
   // Retrieves low pri pool ratio
   double GetLowPriPoolRatio();
 
+  void AppendPrintableOptions(std::string& /*str*/) const;
+
  private:
   friend class LRUCache;
   // Insert an item into the hash table and, if handle is null, insert into
   // the LRU list. Older items are evicted as necessary. If the cache is full
   // and free_handle_on_fail is true, the item is deleted and handle is set to
   // nullptr.
-  Status InsertItem(LRUHandle* item, Cache::Handle** handle,
+  Status InsertItem(LRUHandle* item, LRUHandle** handle,
                     bool free_handle_on_fail);
   Status Insert(const Slice& key, uint32_t hash, void* value, size_t charge,
                 DeleterFn deleter, const Cache::CacheItemHelper* helper,
-                Cache::Handle** handle, Cache::Priority priority);
+                LRUHandle** handle, Cache::Priority priority);
   // Promote an item looked up from the secondary cache to the LRU cache.
   // The item may be still in the secondary cache.
   // It is only inserted into the hash table and not the LRU list, and only
@@ -518,14 +501,15 @@ class ALIGN_AS(CACHE_LINE_SIZE) LRUCacheShard final : public CacheShard {
   // don't mind mutex_ invoking the non-const actions.
   mutable DMutex mutex_;
 
-  std::shared_ptr<SecondaryCache> secondary_cache_;
+  // Owned by LRUCache
+  SecondaryCache* secondary_cache_;
 };
 
 class LRUCache
 #ifdef NDEBUG
     final
 #endif
-    : public ShardedCache {
+    : public ShardedCache<LRUCacheShard> {
  public:
   LRUCache(size_t capacity, int num_shard_bits, bool strict_capacity_limit,
            double high_pri_pool_ratio, double low_pri_pool_ratio,
@@ -533,27 +517,21 @@ class LRUCache
            bool use_adaptive_mutex = kDefaultToAdaptiveMutex,
            CacheMetadataChargePolicy metadata_charge_policy =
                kDontChargeCacheMetadata,
-           const std::shared_ptr<SecondaryCache>& secondary_cache = nullptr);
-  virtual ~LRUCache();
-  virtual const char* Name() const override { return "LRUCache"; }
-  virtual CacheShard* GetShard(uint32_t shard) override;
-  virtual const CacheShard* GetShard(uint32_t shard) const override;
-  virtual void* Value(Handle* handle) override;
-  virtual size_t GetCharge(Handle* handle) const override;
-  virtual uint32_t GetHash(Handle* handle) const override;
-  virtual DeleterFn GetDeleter(Handle* handle) const override;
-  virtual void DisownData() override;
-  virtual void WaitAll(std::vector<Handle*>& handles) override;
-  std::string GetPrintableOptions() const override;
+           std::shared_ptr<SecondaryCache> secondary_cache = nullptr);
+  const char* Name() const override { return "LRUCache"; }
+  void* Value(Handle* handle) override;
+  size_t GetCharge(Handle* handle) const override;
+  DeleterFn GetDeleter(Handle* handle) const override;
+  void WaitAll(std::vector<Handle*>& handles) override;
 
   // Retrieves number of elements in LRU, for unit test purpose only.
   size_t TEST_GetLRUSize();
   // Retrieves high pri pool ratio.
   double GetHighPriPoolRatio();
 
+  void AppendPrintableOptions(std::string& str) const override;
+
  private:
-  LRUCacheShard* shards_ = nullptr;
-  int num_shards_ = 0;
   std::shared_ptr<SecondaryCache> secondary_cache_;
 };