@nxtedition/rocksdb 7.1.14 → 7.1.15

package/deps/rocksdb/rocksdb/cache/clock_cache.h

@@ -9,10 +9,9 @@
 
 #pragma once
 
-#include <sys/types.h>
-
 #include <array>
 #include <atomic>
+#include <cstddef>
 #include <cstdint>
 #include <memory>
 #include <string>
@@ -28,145 +27,267 @@
 
 namespace ROCKSDB_NAMESPACE {
 
-namespace clock_cache {
+namespace hyper_clock_cache {
 
 // Forward declaration of friend class.
 class ClockCacheTest;
 
-// An experimental alternative to LRUCache, using a lock-free, open-addressed
-// hash table and clock eviction.
-
-// ----------------------------------------------------------------------------
-// 1. INTRODUCTION
+// HyperClockCache is an experimental alternative to LRUCache.
+//
+// Benefits
+// --------
+// * Fully lock free (no waits or spins) for efficiency under high concurrency
+// * Optimized for hot path reads. For concurrency control, most Lookup() and
+// essentially all Release() are a single atomic add operation.
+// * Eviction on insertion is fully parallel and lock-free.
+// * Uses a generalized + aging variant of CLOCK eviction that might outperform
+// LRU in some cases. (For background, see
+// https://en.wikipedia.org/wiki/Page_replacement_algorithm)
+//
+// Costs
+// -----
+// * Hash table is not resizable (for lock-free efficiency) so capacity is not
+// dynamically changeable. Rely on an estimated average value (block) size for
+// space+time efficiency. (See estimated_entry_charge option details.)
+// * Insert usually does not (but might) overwrite a previous entry associated
+// with a cache key. This is OK for RocksDB uses of Cache.
+// * Only supports keys of exactly 16 bytes, which is what RocksDB uses for
+// block cache (not row cache or table cache).
+// * SecondaryCache is not supported.
+// * Cache priorities are less aggressively enforced. Unlike LRUCache, enough
+// transient LOW or BOTTOM priority items can evict HIGH priority entries that
+// are not referenced recently (or often) enough.
+// * If pinned entries leave little or nothing eligible for eviction,
+// performance can degrade substantially, because of clock eviction eating
+// CPU looking for evictable entries and because Release does not
+// pro-actively delete unreferenced entries when the cache is over-full.
+// Specifically, this makes this implementation more susceptible to the
+// following combination:
+//   * num_shard_bits is high (e.g. 6)
+//   * capacity small (e.g. some MBs)
+//   * some large individual entries (e.g. non-partitioned filters)
+// where individual entries occupy a large portion of their shard capacity.
+// This should be mostly mitigated by the implementation picking a lower
+// number of cache shards than LRUCache for a given capacity (when
+// num_shard_bits is not overridden; see calls to GetDefaultCacheShardBits()).
+// * With strict_capacity_limit=false, respecting the capacity limit is not as
+// aggressive as LRUCache. The limit might be transiently exceeded by a very
+// small number of entries even when not strictly necessary, and slower to
+// recover after pinning forces limit to be substantially exceeded. (Even with
+// strict_capacity_limit=true, RocksDB will nevertheless transiently allocate
+// memory before discovering it is over the block cache capacity, so this
+// should not be a detectable regression in respecting memory limits, except
+// on exceptionally small caches.)
+// * In some cases, erased or duplicated entries might not be freed
+// immediately. They will eventually be freed by eviction from further Inserts.
+// * Internal metadata can overflow if the number of simultaneous references
+// to a cache handle reaches many millions.
+//
+// High-level eviction algorithm
+// -----------------------------
+// A score (or "countdown") is maintained for each entry, initially determined
+// by priority. The score is incremented on each Lookup, up to a max of 3,
+// though is easily returned to previous state if useful=false with Release.
+// During CLOCK-style eviction iteration, entries with score > 0 are
+// decremented if currently unreferenced and entries with score == 0 are
+// evicted if currently unreferenced. Note that scoring might not be perfect
+// because entries can be referenced transiently within the cache even when
+// there are no outside references to the entry.
+//
+// Cache sharding like LRUCache is used to reduce contention on usage+eviction
+// state, though here the performance improvement from more shards is small,
+// and (as noted above) potentially detrimental if shard capacity is too close
+// to largest entry size. Here cache sharding mostly only affects cache update
+// (Insert / Erase) performance, not read performance.
+//
+// Read efficiency (hot path)
+// --------------------------
+// Mostly to minimize the cost of accessing metadata blocks with
+// cache_index_and_filter_blocks=true, we focus on optimizing Lookup and
+// Release. In terms of concurrency, at a minimum, these operations have
+// to do reference counting (and Lookup has to compare full keys in a safe
+// way). Can we fold in all the other metadata tracking *for free* with
+// Lookup and Release doing a simple atomic fetch_add/fetch_sub? (Assume
+// for the moment that Lookup succeeds on the first probe.)
+//
+// We have a clever way of encoding an entry's reference count and countdown
+// clock so that Lookup and Release are each usually a single atomic addition.
+// In a single metadata word we have both an "acquire" count, incremented by
+// Lookup, and a "release" count, incremented by Release. If useful=false,
+// Release can instead decrement the acquire count. Thus the current ref
+// count is (acquires - releases), and the countdown clock is min(3, acquires).
+// Note that only unreferenced entries (acquires == releases) are eligible
+// for CLOCK manipulation and eviction. We tolerate use of more expensive
+// compare_exchange operations for cache writes (insertions and erasures).
+//
+// In a cache receiving many reads and little or no writes, it is possible
+// for the acquire and release counters to overflow. Assuming the *current*
+// refcount never reaches to many millions, we only have to correct for
+// overflow in both counters in Release, not in Lookup. The overflow check
+// should be only 1-2 CPU cycles per Release because it is a predictable
+// branch on a simple condition on data already in registers.
+//
+// Slot states
+// -----------
+// We encode a state indicator into the same metadata word with the
+// acquire and release counters. This allows bigger state transitions to
+// be atomic. States:
 //
-// In RocksDB, a Cache is a concurrent unordered dictionary that supports
-// external references (a.k.a. user references). A ClockCache is a type of Cache
-// that uses the clock algorithm as its eviction policy. Internally, a
-// ClockCache is an open-addressed hash table that stores all KV pairs in a
-// large array. Every slot in the hash table is a ClockHandle, which holds a KV
-// pair plus some additional metadata that controls the different aspects of the
-// cache: external references, the hashing mechanism, concurrent access and the
-// clock algorithm.
+// * Empty - slot is not in use and unowned. All other metadata and data is
+// in an undefined state.
+// * Construction - slot is exclusively owned by one thread, the thread
+// successfully entering this state, for populating or freeing data.
+// * Shareable (group) - slot holds an entry with counted references for
+// pinning and reading, including
+//   * Visible - slot holds an entry that can be returned by Lookup
+//   * Invisible - slot holds an entry that is not visible to Lookup
+//     (erased by user) but can be read by existing references, and ref count
+//     changed by Ref and Release.
 //
+// A special case is "detached" entries, which are heap-allocated handles
+// not in the table. They are always Invisible and freed on zero refs.
 //
-// 2. EXTERNAL REFERENCES
+// State transitions:
+// Empty -> Construction (in Insert): The encoding of state enables Insert to
+// perform an optimistic atomic bitwise-or to take ownership if a slot is
+// empty, or otherwise make no state change.
 //
-// An externally referenced handle can't be deleted (either evicted by the clock
-// algorithm, or explicitly deleted) or replaced by a new version (via an insert
-// of the same key) until all external references to it have been released by
-// the users. ClockHandles have two members to support external references:
-// - EXTERNAL_REFS counter: The number of external refs. When EXTERNAL_REFS > 0,
-//    the handle is externally referenced. Updates that intend to modify the
-//    handle will refrain from doing so. Eventually, when all references are
-//    released, we have EXTERNAL_REFS == 0, and updates can operate normally on
-//    the handle.
-// - WILL_BE_DELETED flag: An handle is marked for deletion when an operation
-//    decides the handle should be deleted. This happens either when the last
-//    reference to a handle is released (and the release operation is instructed
-//    to delete on last reference) or on when a delete operation is called on
-//    the item. This flag is needed because an externally referenced handle
-//    can't be immediately deleted. In these cases, the flag will be later read
-//    and acted upon by the eviction algorithm. Importantly, WILL_BE_DELETED is
-//    used not only to defer deletions, but also as a barrier for external
-//    references: once WILL_BE_DELETED is set, lookups (which are the most
-//    common way to acquire new external references) will ignore the handle.
-//    For this reason, when WILL_BE_DELETED is set, we say the handle is
-//    invisible (and, otherwise, that it's visible).
+// Construction -> Visible (in Insert): This can be a simple assignment to the
+// metadata word because the current thread has exclusive ownership and other
+// metadata is meaningless.
 //
+// Visible -> Invisible (in Erase): This can be a bitwise-and while holding
+// a shared reference, which is safe because the change is idempotent (in case
+// of parallel Erase). By the way, we never go Invisible->Visible.
 //
-// 3. HASHING AND COLLISION RESOLUTION
+// Shareable -> Construction (in Evict part of Insert, in Erase, and in
+// Release if Invisible): This is for starting to freeing/deleting an
+// unreferenced entry. We have to use compare_exchange to ensure we only make
+// this transition when there are zero refs.
 //
-// ClockCache uses an open-addressed hash table to store the handles.
-// We use a variant of tombstones to manage collisions: every slot keeps a
-// count of how many KV pairs that are currently in the cache have probed the
-// slot in an attempt to insert. Probes are generated with double-hashing
-// (although the code can be easily modified to use other probing schemes, like
-// linear probing).
+// Construction -> Empty (in same places): This is for completing free/delete
+// of an entry. A "release" atomic store suffices, as we have exclusive
+// ownership of the slot but have to ensure none of the data member reads are
+// re-ordered after committing the state transition.
 //
-// A slot in the hash table can be in a few different states:
-// - Element: The slot contains an element. This is indicated with the
-//    IS_ELEMENT flag. Element can be sub-classified depending on the
-//    value of WILL_BE_DELETED:
-//    * Visible element.
-//    * Invisible element.
-// - Tombstone: The slot doesn't contain an element, but there is some other
-//    element that probed this slot during its insertion.
-// - Empty: The slot is unused---it's neither an element nor a tombstone.
+// Insert
+// ------
+// If Insert were to guarantee replacing an existing entry for a key, there
+// would be complications for concurrency and efficiency. First, consider how
+// many probes to get to an entry. To ensure Lookup never waits and
+// availability of a key is uninterrupted, we would need to use a different
+// slot for a new entry for the same key. This means it is most likely in a
+// later probing position than the old version, which should soon be removed.
+// (Also, an entry is too big to replace atomically, even if no current refs.)
 //
-// A slot cycles through the following sequence of states:
-// empty or tombstone --> visible element --> invisible element -->
-// empty or tombstone. Initially a slot is available---it's either
-// empty or a tombstone. As soon as a KV pair is written into the slot, it
-// becomes a visible element. At some point, the handle will be deleted
-// by an explicit delete operation, the eviction algorithm, or an overwriting
-// insert. In either case, the handle is marked for deletion. When the an
-// attempt to delete the element finally succeeds, the slot is freed up
-// and becomes available again.
+// However, overwrite capability is not really needed by RocksDB. Also, we
+// know from our "redundant" stats that overwrites are very rare for the block
+// cache, so we should not spend much to make them effective.
 //
+// So instead we Insert as soon as we find an empty slot in the probing
+// sequence without seeing an existing (visible) entry for the same key. This
+// way we only insert if we can improve the probing performance, and we don't
+// need to probe beyond our insert position, assuming we are willing to let
+// the previous entry for the same key die of old age (eventual eviction from
+// not being used). We can reach a similar state with concurrent insertions,
+// where one will pass over the other while it is "under construction."
+// This temporary duplication is acceptable for RocksDB block cache because
+// we know redundant insertion is rare.
 //
-// 4. CONCURRENCY
+// Another problem to solve is what to return to the caller when we find an
+// existing entry whose probing position we cannot improve on, or when the
+// table occupancy limit has been reached. If strict_capacity_limit=false,
+// we must never fail Insert, and if a Handle* is provided, we have to return
+// a usable Cache handle on success. The solution to this (typically rare)
+// problem is "detached" handles, which are usable by the caller but not
+// actually available for Lookup in the Cache. Detached handles are allocated
+// independently on the heap and specially marked so that they are freed on
+// the heap when their last reference is released.
 //
-// ClockCache is lock-free. At a high level, we synchronize the operations
-// using a read-prioritized, non-blocking variant of RW locks on every slot of
-// the hash table. To do this we generalize the concept of reference:
-// - Internal reference: Taken by a thread that is attempting to read a slot
-//    or do a very precise type of update.
-// - Exclusive reference: Taken by a thread that is attempting to write a
-//    a slot extensively.
+// Usage on capacity
+// -----------------
+// Insert takes different approaches to usage tracking depending on
+// strict_capacity_limit setting. If true, we enforce a kind of strong
+// consistency where compare-exchange is used to ensure the usage number never
+// exceeds its limit, and provide threads with an authoritative signal on how
+// much "usage" they have taken ownership of. With strict_capacity_limit=false,
+// we use a kind of "eventual consistency" where all threads Inserting to the
+// same cache shard might race on reserving the same space, but the
+// over-commitment will be worked out in later insertions. It is kind of a
+// dance because we don't want threads racing each other too much on paying
+// down the over-commitment (with eviction) either.
 //
-// We defer the precise definitions to the comments in the code below.
-// A crucial feature of our references is that attempting to take one never
-// blocks the thread. Another important feature is that readers are
-// prioritized, as they use extremely fast synchronization primitives---they
-// use atomic arithmetic/bit operations, but no compare-and-swaps (which are
-// much slower).
+// Eviction
+// --------
+// A key part of Insert is evicting some entries currently unreferenced to
+// make room for new entries. The high-level eviction algorithm is described
+// above, but the details are also interesting. A key part is parallelizing
+// eviction with a single CLOCK pointer. This works by each thread working on
+// eviction pre-emptively incrementing the CLOCK pointer, and then CLOCK-
+// updating or evicting the incremented-over slot(s). To reduce contention at
+// the cost of possibly evicting too much, each thread increments the clock
+// pointer by 4, so commits to updating at least 4 slots per batch. As
+// described above, a CLOCK update will decrement the "countdown" of
+// unreferenced entries, or evict unreferenced entries with zero countdown.
+// Referenced entries are not updated, because we (presumably) don't want
+// long-referenced entries to age while referenced. Note however that we
+// cannot distinguish transiently referenced entries from cache user
+// references, so some CLOCK updates might be somewhat arbitrarily skipped.
+// This is OK as long as it is rare enough that eviction order is still
+// pretty good.
 //
-// Internal references are used by threads to read slots during a probing
-// sequence, making them the most common references (probing is performed
-// in almost every operation, not just lookups). During a lookup, once
-// the target element is found, and just before the handle is handed over
-// to the user, an internal reference is converted into an external reference.
-// During an update operation, once the target slot is found, an internal
-// reference is converted into an exclusive reference. Interestingly, we
-// can't atomically upgrade from internal to exclusive, or we may run into a
-// deadlock. Releasing the internal reference and then taking an exclusive
-// reference avoids the deadlock, but then the handle may change inbetween.
-// One of the key observations we use in our implementation is that we can
-// make up for this lack of atomicity using IS_ELEMENT and WILL_BE_DELETED.
+// There is no synchronization on the completion of the CLOCK updates, so it
+// is theoretically possible for another thread to cycle back around and have
+// two threads racing on CLOCK updates to the same slot. Thus, we cannot rely
+// on any implied exclusivity to make the updates or eviction more efficient.
+// These updates use an opportunistic compare-exchange (no loop), where a
+// racing thread might cause the update to be skipped without retry, but in
+// such case the update is likely not needed because the most likely update
+// to an entry is that it has become referenced. (TODO: test efficiency of
+// avoiding compare-exchange loop)
 //
-// Distinguishing internal from external references is useful for two reasons:
-// - Internal references are short lived, but external references are typically
-//    not. This is helpful when acquiring an exclusive ref: if there are any
-//    external references to the item, it's probably not worth waiting until
-//    they go away.
-// - We can precisely determine when there are no more external references to a
-//    handle, and proceed to mark it for deletion. This is useful when users
-//    release external references.
+// Release
+// -------
+// In the common case, Release is a simple atomic increment of the release
+// counter. There is a simple overflow check that only does another atomic
+// update in extremely rare cases, so costs almost nothing.
 //
+// If the Release specifies "not useful", we can instead decrement the
+// acquire counter, which returns to the same CLOCK state as before Lookup
+// or Ref.
 //
-// 5. CLOCK ALGORITHM
+// Adding a check for over-full cache on every release to zero-refs would
+// likely be somewhat expensive, increasing read contention on cache shard
+// metadata. Instead we are less aggressive about deleting entries right
+// away in those cases.
 //
-// The clock algorithm circularly sweeps through the hash table to find the next
-// victim. Recall that handles that are referenced are not evictable; the clock
-// algorithm never picks those. We use different clock priorities: NONE, LOW,
-// MEDIUM and HIGH. Priorities LOW, MEDIUM and HIGH represent how close an
-// element is from being evicted, LOW being the closest to evicted. NONE means
-// the slot is not evictable. NONE priority is used in one of the following
-// cases:
-// (a) the slot doesn't contain an element, or
-// (b) the slot contains an externally referenced element, or
-// (c) the slot contains an element that used to be externally referenced,
-//      and the clock pointer has not swept through the slot since the element
-//      stopped being externally referenced.
-// ----------------------------------------------------------------------------
+// However Release tries to immediately delete entries reaching zero refs
+// if (a) erase_if_last_ref is set by the caller, or (b) the entry is already
+// marked invisible. Both of these are checks on values already in CPU
+// registers so do not increase cross-CPU contention when not applicable.
+// When applicable, they use a compare-exchange loop to take exclusive
+// ownership of the slot for freeing the entry. These are rare cases
+// that should not usually affect performance.
+//
+// Erase
+// -----
+// Searches for an entry like Lookup but moves it to Invisible state if found.
+// This state transition is with bit operations so is idempotent and safely
+// done while only holding a shared "read" reference. Like Release, it makes
+// a best effort to immediately release an Invisible entry that reaches zero
+// refs, but there are some corner cases where it will only be freed by the
+// clock eviction process.
+
+// ----------------------------------------------------------------------- //
 
 // The load factor p is a real number in (0, 1) such that at all
 // times at most a fraction p of all slots, without counting tombstones,
-// are occupied by elements. This means that the probability that a
-// random probe hits an empty slot is at most p, and thus at most 1/p probes
+// are occupied by elements. This means that the probability that a random
+// probe hits an occupied slot is at most p, and thus at most 1/p probes
 // are required on average. For example, p = 70% implies that between 1 and 2
 // probes are needed on average (bear in mind that this reasoning doesn't
-// consider the effects of clustering over time).
+// consider the effects of clustering over time, which should be negligible
+// with double hashing).
 // Because the size of the hash table is always rounded up to the next
 // power of 2, p is really an upper bound on the actual load factor---the
 // actual load factor is anywhere between p/2 and p. This is a bit wasteful,
@@ -174,440 +295,119 @@ class ClockCacheTest;
 // Since space cost is dominated by the values (the LSM blocks),
 // overprovisioning the table with metadata only increases the total cache space
 // usage by a tiny fraction.
-constexpr double kLoadFactor = 0.35;
+constexpr double kLoadFactor = 0.7;
 
 // The user can exceed kLoadFactor if the sizes of the inserted values don't
-// match estimated_value_size, or if strict_capacity_limit == false. To
-// avoid a performance drop, we set a strict upper bound on the load factor.
-constexpr double kStrictLoadFactor = 0.7;
-
-// Maximum number of spins when trying to acquire a ref.
-// TODO(Guido) This value was set arbitrarily. Is it appropriate?
-// What's the best way to bound the spinning?
-constexpr uint32_t kSpinsPerTry = 100000;
-
-// Arbitrary seeds.
-constexpr uint32_t kProbingSeed1 = 0xbc9f1d34;
-constexpr uint32_t kProbingSeed2 = 0x7a2bb9d5;
-
-struct ClockHandle {
-  void* value;
-  Cache::DeleterFn deleter;
-  uint32_t hash;
-  size_t total_charge;
-  std::array<char, kCacheKeySize> key_data;
-
-  static constexpr uint8_t kIsElementOffset = 0;
-  static constexpr uint8_t kClockPriorityOffset = 1;
-  static constexpr uint8_t kIsHitOffset = 3;
-  static constexpr uint8_t kCachePriorityOffset = 4;
-
-  enum Flags : uint8_t {
-    // Whether the slot is in use by an element.
-    IS_ELEMENT = 1 << kIsElementOffset,
-    // Clock priorities. Represents how close a handle is from being evictable.
-    CLOCK_PRIORITY = 3 << kClockPriorityOffset,
-    // Whether the handle has been looked up after its insertion.
-    HAS_HIT = 1 << kIsHitOffset,
-    // The value of Cache::Priority of the handle.
-    CACHE_PRIORITY = 1 << kCachePriorityOffset,
-  };
-
-  std::atomic<uint8_t> flags;
-
-  enum ClockPriority : uint8_t {
-    NONE = (0 << kClockPriorityOffset),
-    LOW = (1 << kClockPriorityOffset),
-    MEDIUM = (2 << kClockPriorityOffset),
-    HIGH = (3 << kClockPriorityOffset)
-  };
-
-  // The number of elements that hash to this slot or a lower one, but wind
-  // up in this slot or a higher one.
-  std::atomic<uint32_t> displacements;
-
-  static constexpr uint8_t kExternalRefsOffset = 0;
-  static constexpr uint8_t kSharedRefsOffset = 15;
-  static constexpr uint8_t kExclusiveRefOffset = 30;
-  static constexpr uint8_t kWillBeDeletedOffset = 31;
-
-  enum Refs : uint32_t {
-    // Synchronization model:
-    // - An external reference guarantees that hash, value, key_data
-    //    and the IS_ELEMENT flag are not modified. Doesn't allow
-    //    any writes.
-    // - An internal reference has the same guarantees as an
-    //    external reference, and additionally allows the following
-    //    idempotent updates on the handle:
-    //      * set CLOCK_PRIORITY to NONE;
-    //      * set the HAS_HIT bit;
-    //      * set the WILL_BE_DELETED bit.
-    // - A shared reference is either an external reference or an
-    //    internal reference.
-    // - An exclusive reference guarantees that no other thread has a shared
-    //    or exclusive reference to the handle, and allows writes
-    //    on the handle.
-
-    // Number of external references to the slot.
-    EXTERNAL_REFS = ((uint32_t{1} << 15) - 1)
-                    << kExternalRefsOffset,  // Bits 0, ..., 14
-    // Number of internal references plus external references to the slot.
-    SHARED_REFS = ((uint32_t{1} << 15) - 1)
-                  << kSharedRefsOffset,  // Bits 15, ..., 29
-    // Whether a thread has an exclusive reference to the slot.
-    EXCLUSIVE_REF = uint32_t{1} << kExclusiveRefOffset,  // Bit 30
-    // Whether the handle will be deleted soon. When this bit is set, new
-    // internal references to this handle stop being accepted.
-    // External references may still be granted---they can be created from
-    // existing external references, or converting from existing internal
-    // references.
-    WILL_BE_DELETED = uint32_t{1} << kWillBeDeletedOffset  // Bit 31
-
-    // Having these 4 fields in a single variable allows us to support the
-    // following operations efficiently:
-    // - Convert an internal reference into an external reference in a single
-    //    atomic arithmetic operation.
-    // - Attempt to take a shared reference using a single atomic arithmetic
-    //    operation. This is because we can increment the internal ref count
-    //    as well as checking whether the entry is marked for deletion using a
-    //    single atomic arithmetic operation (and one non-atomic comparison).
-  };
-
-  static constexpr uint32_t kOneInternalRef = 0x8000;
-  static constexpr uint32_t kOneExternalRef = 0x8001;
-
-  std::atomic<uint32_t> refs;
+// match estimated_value_size, or in some rare cases with
+// strict_capacity_limit == false. To avoid degenerate performance, we set a
+// strict upper bound on the load factor.
+constexpr double kStrictLoadFactor = 0.84;
 
-  // True iff the handle is allocated separately from hash table.
-  bool detached;
-
-  ClockHandle()
-      : value(nullptr),
-        deleter(nullptr),
-        hash(0),
-        total_charge(0),
-        flags(0),
-        displacements(0),
-        refs(0),
-        detached(false) {
-    SetWillBeDeleted(false);
-    SetIsElement(false);
-    SetClockPriority(ClockPriority::NONE);
-    SetCachePriority(Cache::Priority::LOW);
-    key_data.fill(0);
-  }
+using CacheKeyBytes = std::array<char, kCacheKeySize>;
 
-  // The copy ctor and assignment operator are only used to copy a handle
-  // for immediate deletion. (We need to copy because the slot may become
-  // re-used before the deletion is completed.) We only copy the necessary
-  // members to carry out the deletion. In particular, we don't need
-  // the atomic members.
-  ClockHandle(const ClockHandle& other) { *this = other; }
-
-  void operator=(const ClockHandle& other) {
-    value = other.value;
-    deleter = other.deleter;
-    key_data = other.key_data;
-    hash = other.hash;
-    total_charge = other.total_charge;
-  }
+struct ClockHandleBasicData {
+  void* value = nullptr;
+  Cache::DeleterFn deleter = nullptr;
+  CacheKeyBytes key = {};
+  size_t total_charge = 0;
 
-  Slice key() const { return Slice(key_data.data(), kCacheKeySize); }
+  Slice KeySlice() const { return Slice(key.data(), kCacheKeySize); }
 
-  void FreeData() {
+  void FreeData() const {
     if (deleter) {
-      (*deleter)(key(), value);
+      (*deleter)(KeySlice(), value);
     }
   }
+};
+
+struct ClockHandleMoreData : public ClockHandleBasicData {
+  uint32_t hash = 0;
+};
+
+// Target size to be exactly a common cache line size (see static_assert in
+// clock_cache.cc)
+struct ALIGN_AS(64U) ClockHandle : public ClockHandleMoreData {
+  // Constants for handling the atomic `meta` word, which tracks most of the
+  // state of the handle. The meta word looks like this:
+  // low bits                                                     high bits
+  // -----------------------------------------------------------------------
+  // | acquire counter          | release counter           | state marker |
+  // -----------------------------------------------------------------------
+
+  // For reading or updating counters in meta word.
+  static constexpr uint8_t kCounterNumBits = 30;
+  static constexpr uint64_t kCounterMask = (uint64_t{1} << kCounterNumBits) - 1;
+
+  static constexpr uint8_t kAcquireCounterShift = 0;
+  static constexpr uint64_t kAcquireIncrement = uint64_t{1}
+                                                << kAcquireCounterShift;
+  static constexpr uint8_t kReleaseCounterShift = kCounterNumBits;
+  static constexpr uint64_t kReleaseIncrement = uint64_t{1}
+                                                << kReleaseCounterShift;
+
+  // For reading or updating the state marker in meta word
+  static constexpr uint8_t kStateShift = 2U * kCounterNumBits;
+
+  // Bits contribution to state marker.
+  // Occupied means any state other than empty
+  static constexpr uint8_t kStateOccupiedBit = 0b100;
+  // Shareable means the entry is reference counted (visible or invisible)
+  // (only set if also occupied)
+  static constexpr uint8_t kStateShareableBit = 0b010;
+  // Visible is only set if also shareable
+  static constexpr uint8_t kStateVisibleBit = 0b001;
+
+  // Complete state markers (not shifted into full word)
+  static constexpr uint8_t kStateEmpty = 0b000;
+  static constexpr uint8_t kStateConstruction = kStateOccupiedBit;
+  static constexpr uint8_t kStateInvisible =
+      kStateOccupiedBit | kStateShareableBit;
+  static constexpr uint8_t kStateVisible =
+      kStateOccupiedBit | kStateShareableBit | kStateVisibleBit;
+
+  // Constants for initializing the countdown clock. (Countdown clock is only
+  // in effect with zero refs, acquire counter == release counter, and in that
+  // case the countdown clock == both of those counters.)
+  static constexpr uint8_t kHighCountdown = 3;
+  static constexpr uint8_t kLowCountdown = 2;
+  static constexpr uint8_t kBottomCountdown = 1;
+  // During clock update, treat any countdown clock value greater than this
+  // value the same as this value.
+  static constexpr uint8_t kMaxCountdown = kHighCountdown;
+  // TODO: make these coundown values tuning parameters for eviction?
+
+  // See above
+  std::atomic<uint64_t> meta{};
+  // The number of elements that hash to this slot or a lower one, but wind
+  // up in this slot or a higher one.
+  std::atomic<uint32_t> displacements{};
 
-  // Calculate the memory usage by metadata.
-  inline size_t CalcMetaCharge(
-      CacheMetadataChargePolicy metadata_charge_policy) const {
-    if (metadata_charge_policy != kFullChargeCacheMetadata) {
-      return 0;
-    } else {
-      // #ifdef ROCKSDB_MALLOC_USABLE_SIZE
-      //       return malloc_usable_size(
-      //           const_cast<void*>(static_cast<const void*>(this)));
-      // #else
-      // TODO(Guido) malloc_usable_size only works when we call it on
-      // a pointer allocated with malloc. Because our handles are all
-      // allocated in a single shot as an array, the user can't call
-      // CalcMetaCharge (or CalcTotalCharge or GetCharge) on a handle
-      // pointer returned by the cache. Moreover, malloc_usable_size
-      // expects a heap-allocated handle, but sometimes in our code we
-      // wish to pass a stack-allocated handle (this is only a performance
-      // concern).
-      // What is the right way to compute metadata charges with pre-allocated
-      // handles?
-      return sizeof(ClockHandle);
-      // #endif
-    }
-  }
-
-  inline void CalcTotalCharge(
-      size_t charge, CacheMetadataChargePolicy metadata_charge_policy) {
-    total_charge = charge + CalcMetaCharge(metadata_charge_policy);
-  }
-
-  inline size_t GetCharge(
-      CacheMetadataChargePolicy metadata_charge_policy) const {
-    size_t meta_charge = CalcMetaCharge(metadata_charge_policy);
-    assert(total_charge >= meta_charge);
-    return total_charge - meta_charge;
-  }
-
-  // flags functions.
-
-  bool IsElement() const { return flags & Flags::IS_ELEMENT; }
-
-  void SetIsElement(bool is_element) {
-    if (is_element) {
-      flags |= Flags::IS_ELEMENT;
-    } else {
-      flags &= static_cast<uint8_t>(~Flags::IS_ELEMENT);
-    }
-  }
-
-  bool HasHit() const { return flags & HAS_HIT; }
-
-  void SetHit() { flags |= HAS_HIT; }
-
-  Cache::Priority GetCachePriority() const {
-    return static_cast<Cache::Priority>(flags & CACHE_PRIORITY);
-  }
-
-  void SetCachePriority(Cache::Priority priority) {
-    if (priority == Cache::Priority::HIGH) {
-      flags |= Flags::CACHE_PRIORITY;
-    } else {
-      flags &= static_cast<uint8_t>(~Flags::CACHE_PRIORITY);
-    }
-  }
-
-  bool IsInClock() const {
-    return GetClockPriority() != ClockHandle::ClockPriority::NONE;
-  }
-
-  ClockPriority GetClockPriority() const {
-    return static_cast<ClockPriority>(flags & Flags::CLOCK_PRIORITY);
-  }
-
-  void SetClockPriority(ClockPriority priority) {
-    flags &= static_cast<uint8_t>(~Flags::CLOCK_PRIORITY);
-    flags |= priority;
-  }
-
-  void DecreaseClockPriority() {
-    uint8_t p = static_cast<uint8_t>(flags & Flags::CLOCK_PRIORITY) >>
-                kClockPriorityOffset;
-    assert(p > 0);
-    p--;
-    flags &= static_cast<uint8_t>(~Flags::CLOCK_PRIORITY);
-    ClockPriority new_priority =
-        static_cast<ClockPriority>(p << kClockPriorityOffset);
-    flags |= new_priority;
-  }
-
-  bool IsDetached() { return detached; }
-
-  void SetDetached() { detached = true; }
-
-  inline bool IsEmpty() const {
-    return !this->IsElement() && this->displacements == 0;
-  }
-
-  inline bool IsTombstone() const {
-    return !this->IsElement() && this->displacements > 0;
-  }
-
-  inline bool Matches(const Slice& some_key, uint32_t some_hash) const {
-    return this->hash == some_hash && this->key() == some_key;
-  }
-
-  // refs functions.
-
-  inline bool WillBeDeleted() const { return refs & WILL_BE_DELETED; }
-
-  void SetWillBeDeleted(bool will_be_deleted) {
-    if (will_be_deleted) {
-      refs |= WILL_BE_DELETED;
-    } else {
-      refs &= ~WILL_BE_DELETED;
-    }
-  }
-
-  uint32_t ExternalRefs() const {
-    return (refs & EXTERNAL_REFS) >> kExternalRefsOffset;
-  }
-
-  // Tries to take an internal ref. Returns true iff it succeeds.
-  inline bool TryInternalRef() {
-    if (!((refs += kOneInternalRef) & (EXCLUSIVE_REF | WILL_BE_DELETED))) {
-      return true;
-    }
-    refs -= kOneInternalRef;
-    return false;
-  }
-
-  // Tries to take an external ref. Returns true iff it succeeds.
-  inline bool TryExternalRef() {
-    if (!((refs += kOneExternalRef) & EXCLUSIVE_REF)) {
-      return true;
-    }
-    refs -= kOneExternalRef;
-    return false;
-  }
-
-  // Tries to take an exclusive ref. Returns true iff it succeeds.
-  // TODO(Guido) After every TryExclusiveRef call, we always call
-  // WillBeDeleted(). We could save an atomic read by having an output parameter
-  // with the last value of refs.
-  inline bool TryExclusiveRef() {
-    uint32_t will_be_deleted = refs & WILL_BE_DELETED;
-    uint32_t expected = will_be_deleted;
-    return refs.compare_exchange_strong(expected,
-                                        EXCLUSIVE_REF | will_be_deleted);
-  }
-
-  // Repeatedly tries to take an exclusive reference, but aborts as soon
-  // as an external or exclusive reference is detected (since the wait
-  // would presumably be too long).
-  inline bool SpinTryExclusiveRef() {
-    uint32_t expected = 0;
-    uint32_t will_be_deleted = 0;
-    uint32_t spins = kSpinsPerTry;
-    while (!refs.compare_exchange_strong(expected,
-                                         EXCLUSIVE_REF | will_be_deleted) &&
-           spins--) {
-      std::this_thread::yield();
-      if (expected & (EXTERNAL_REFS | EXCLUSIVE_REF)) {
-        return false;
-      }
-      will_be_deleted = expected & WILL_BE_DELETED;
-      expected = will_be_deleted;
-    }
-    return true;
-  }
-
-  // Take an external ref, assuming there is already one external ref
-  // to the handle.
-  void Ref() {
-    // TODO(Guido) Is it okay to assume that the existing external reference
-    // survives until this function returns?
-    refs += kOneExternalRef;
-  }
-
-  inline void ReleaseExternalRef() { refs -= kOneExternalRef; }
-
-  inline void ReleaseInternalRef() { refs -= kOneInternalRef; }
-
-  inline void ReleaseExclusiveRef() { refs.fetch_and(~EXCLUSIVE_REF); }
-
-  // Downgrade an exclusive ref to external.
-  inline void ExclusiveToExternalRef() {
-    refs += kOneExternalRef;
-    ReleaseExclusiveRef();
-  }
-
-  // Convert an internal ref into external.
-  inline void InternalToExternalRef() {
-    refs += kOneExternalRef - kOneInternalRef;
-  }
-
+  // True iff the handle is allocated separately from hash table.
+  bool detached = false;
 };  // struct ClockHandle
 
 class ClockHandleTable {
  public:
-  explicit ClockHandleTable(size_t capacity, int hash_bits);
+  explicit ClockHandleTable(int hash_bits, bool initial_charge_metadata);
   ~ClockHandleTable();
 
-  // Returns a pointer to a visible handle matching the key/hash, or
-  // nullptr if not present. When an actual handle is produced, an
-  // internal reference is handed over.
-  ClockHandle* Lookup(const Slice& key, uint32_t hash);
-
-  // Inserts a copy of h into the hash table. Returns a pointer to the
-  // inserted handle, or nullptr if no available slot was found. Every
-  // existing visible handle matching the key is already present in the
-  // hash table is marked as WILL_BE_DELETED. The deletion is also attempted,
-  // and, if the attempt is successful, the handle is inserted into the
-  // autovector deleted. When take_reference is true, the function hands
-  // over an external reference on the handle, and otherwise no reference is
-  // produced.
-  ClockHandle* Insert(ClockHandle* h, autovector<ClockHandle>* deleted,
-                      bool take_reference);
-
-  // Assigns h the appropriate clock priority, making it evictable.
-  void ClockOn(ClockHandle* h);
-
-  // Makes h non-evictable.
-  void ClockOff(ClockHandle* h);
-
-  // Runs the clock eviction algorithm until usage_ + charge is at most
-  // capacity_.
-  void ClockRun(size_t charge);
-
-  // Remove h from the hash table. Requires an exclusive ref to h.
-  void Remove(ClockHandle* h, autovector<ClockHandle>* deleted);
-
-  // Remove from the hash table all handles with matching key/hash along a
-  // probe sequence, starting from the given probe number. Doesn't
-  // require any references.
-  void RemoveAll(const Slice& key, uint32_t hash, uint32_t& probe,
-                 autovector<ClockHandle>* deleted);
-
-  void RemoveAll(const Slice& key, uint32_t hash,
-                 autovector<ClockHandle>* deleted) {
-    uint32_t probe = 0;
-    RemoveAll(key, hash, probe, deleted);
-  }
+  Status Insert(const ClockHandleMoreData& proto, ClockHandle** handle,
+                Cache::Priority priority, size_t capacity,
+                bool strict_capacity_limit);
 
-  // Tries to remove h from the hash table. If the attempt is successful,
-  // the function hands over an exclusive ref to h.
-  bool TryRemove(ClockHandle* h, autovector<ClockHandle>* deleted);
-
-  // Similar to TryRemove, except that it spins, increasing the chances of
-  // success. Requires that the caller thread has no shared ref to h.
-  bool SpinTryRemove(ClockHandle* h, autovector<ClockHandle>* deleted);
-
-  // Call this function after an Insert, Remove, RemoveAll, TryRemove
-  // or SpinTryRemove. It frees the deleted values and updates the hash table
-  // metadata.
-  void Free(autovector<ClockHandle>* deleted);
-
-  void ApplyToEntriesRange(std::function<void(ClockHandle*)> func,
-                           uint32_t index_begin, uint32_t index_end,
-                           bool apply_if_will_be_deleted) {
-    for (uint32_t i = index_begin; i < index_end; i++) {
-      ClockHandle* h = &array_[i];
-      if (h->TryExclusiveRef()) {
-        if (h->IsElement() &&
-            (apply_if_will_be_deleted || !h->WillBeDeleted())) {
-          func(h);
-        }
-        h->ReleaseExclusiveRef();
-      }
-    }
-  }
+  ClockHandle* Lookup(const CacheKeyBytes& key, uint32_t hash);
+
+  bool Release(ClockHandle* handle, bool useful, bool erase_if_last_ref);
 
-  void ConstApplyToEntriesRange(std::function<void(const ClockHandle*)> func,
+  void Ref(ClockHandle& handle);
+
+  void Erase(const CacheKeyBytes& key, uint32_t hash);
+
+  void ConstApplyToEntriesRange(std::function<void(const ClockHandle&)> func,
                                 uint32_t index_begin, uint32_t index_end,
-                                bool apply_if_will_be_deleted) const {
-    for (uint32_t i = index_begin; i < index_end; i++) {
-      ClockHandle* h = &array_[i];
-      // We take an external ref because we are handing over control
-      // to a user-defined function, and because the handle will not be
-      // modified.
-      if (h->TryExternalRef()) {
-        if (h->IsElement() &&
-            (apply_if_will_be_deleted || !h->WillBeDeleted())) {
-          func(h);
-        }
-        h->ReleaseExternalRef();
-      }
-    }
-  }
+                                bool apply_if_will_be_deleted) const;
+
+  void EraseUnRefEntries();
 
   uint32_t GetTableSize() const { return uint32_t{1} << length_bits_; }
 
@@ -615,22 +415,29 @@ class ClockHandleTable {
 
   uint32_t GetOccupancyLimit() const { return occupancy_limit_; }
 
-  uint32_t GetOccupancy() const { return occupancy_; }
+  uint32_t GetOccupancy() const {
+    return occupancy_.load(std::memory_order_relaxed);
+  }
 
-  size_t GetUsage() const { return usage_; }
+  size_t GetUsage() const { return usage_.load(std::memory_order_relaxed); }
 
-  size_t GetCapacity() const { return capacity_; }
+  size_t GetDetachedUsage() const {
+    return detached_usage_.load(std::memory_order_relaxed);
+  }
 
-  void SetCapacity(size_t capacity) { capacity_ = capacity; }
+  // Acquire/release N references
+  void TEST_RefN(ClockHandle& handle, size_t n);
+  void TEST_ReleaseN(ClockHandle* handle, size_t n);
 
+ private:  // functions
   // Returns x mod 2^{length_bits_}.
   uint32_t ModTableSize(uint32_t x) { return x & length_bits_mask_; }
 
- private:
-  // Extracts the element information from a handle (src), and assigns it
-  // to a hash table slot (dst). Doesn't touch displacements and refs,
-  // which are maintained by the hash table algorithm.
-  void Assign(ClockHandle* dst, ClockHandle* src);
+  // Runs the clock eviction algorithm trying to reclaim at least
+  // requested_charge. Returns how much is evicted, which could be less
+  // if it appears impossible to evict the requested amount without blocking.
+  void Evict(size_t requested_charge, size_t* freed_charge,
+             uint32_t* freed_count);
 
   // Returns the first slot in the probe sequence, starting from the given
   // probe number, with a handle e such that match(e) is true. At every
@@ -643,26 +450,17 @@ class ClockHandleTable {
   // value of probe is one more than the last non-aborting probe during the
   // call. This is so that that the variable can be used to keep track of
   // progress across consecutive calls to FindSlot.
-  inline ClockHandle* FindSlot(const Slice& key,
+  inline ClockHandle* FindSlot(uint32_t hash,
                                std::function<bool(ClockHandle*)> match,
                                std::function<bool(ClockHandle*)> stop,
                                std::function<void(ClockHandle*)> update,
                                uint32_t& probe);
 
-  // Returns an available slot for the given key. All copies of the
-  // key found along the probing sequence until an available slot is
-  // found are marked for deletion. On each of them, a deletion is
-  // attempted, and when the attempt succeeds the slot is assigned to
-  // the new copy of the element.
-  ClockHandle* FindAvailableSlot(const Slice& key, uint32_t hash,
-                                 uint32_t& probe,
-                                 autovector<ClockHandle>* deleted);
-
-  // After a failed FindSlot call (i.e., with answer -1) in
-  // FindAvailableSlot, this function fixes all displacements's
-  // starting from the 0-th probe, until the given probe.
-  void Rollback(const Slice& key, uint32_t probe);
+  // Re-decrement all displacements in probe path starting from beginning
+  // until (not including) the given handle
+  void Rollback(uint32_t hash, const ClockHandle* h);
 
+ private:  // data
   // Number of hash bits used for table index.
   // The size of the table is 1 << length_bits_.
   const int length_bits_;
@@ -673,27 +471,26 @@ class ClockHandleTable {
   // Maximum number of elements the user can store in the table.
   const uint32_t occupancy_limit_;
 
-  // Maximum total charge of all elements stored in the table.
-  size_t capacity_;
+  // Array of slots comprising the hash table.
+  const std::unique_ptr<ClockHandle[]> array_;
 
   // We partition the following members into different cache lines
   // to avoid false sharing among Lookup, Release, Erase and Insert
   // operations in ClockCacheShard.
 
-  ALIGN_AS(CACHE_LINE_SIZE)
-  // Array of slots comprising the hash table.
-  std::unique_ptr<ClockHandle[]> array_;
-
   ALIGN_AS(CACHE_LINE_SIZE)
   // Clock algorithm sweep pointer.
-  std::atomic<uint32_t> clock_pointer_;
+  std::atomic<uint64_t> clock_pointer_{};
 
   ALIGN_AS(CACHE_LINE_SIZE)
   // Number of elements in the table.
-  std::atomic<uint32_t> occupancy_;
+  std::atomic<uint32_t> occupancy_{};
+
+  // Memory usage by entries tracked by the cache (including detached)
+  std::atomic<size_t> usage_{};
 
-  // Memory size for entries residing in the cache.
-  std::atomic<size_t> usage_;
+  // Part of usage by detached entries (not in table)
+  std::atomic<size_t> detached_usage_{};
 };  // class ClockHandleTable
 
 // A single shard of sharded cache.
@@ -704,58 +501,34 @@ class ALIGN_AS(CACHE_LINE_SIZE) ClockCacheShard final : public CacheShard {
                   CacheMetadataChargePolicy metadata_charge_policy);
   ~ClockCacheShard() override = default;
 
-  // Separate from constructor so caller can easily make an array of ClockCache
-  // if current usage is more than new capacity, the function will attempt to
-  // free the needed space.
+  // TODO: document limitations
   void SetCapacity(size_t capacity) override;
 
-  // Set the flag to reject insertion if cache if full.
   void SetStrictCapacityLimit(bool strict_capacity_limit) override;
 
-  // Like Cache methods, but with an extra "hash" parameter.
-  // Insert an item into the hash table and, if handle is null, make it
-  // evictable by the clock algorithm. 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 Insert(const Slice& key, uint32_t hash, void* value, size_t charge,
                 Cache::DeleterFn deleter, Cache::Handle** handle,
                 Cache::Priority priority) override;
 
-  Status Insert(const Slice& key, uint32_t hash, void* value,
-                const Cache::CacheItemHelper* helper, size_t charge,
-                Cache::Handle** handle, Cache::Priority priority) override {
-    return Insert(key, hash, value, charge, helper->del_cb, handle, priority);
-  }
-
-  Cache::Handle* Lookup(const Slice& key, uint32_t hash,
-                        const Cache::CacheItemHelper* /*helper*/,
-                        const Cache::CreateCallback& /*create_cb*/,
-                        Cache::Priority /*priority*/, bool /*wait*/,
-                        Statistics* /*stats*/) override {
-    return Lookup(key, hash);
-  }
-
   Cache::Handle* Lookup(const Slice& key, uint32_t hash) override;
 
-  bool Release(Cache::Handle* handle, bool /*useful*/,
-               bool erase_if_last_ref) override {
-    return Release(handle, erase_if_last_ref);
-  }
-
-  bool IsReady(Cache::Handle* /*handle*/) override { return true; }
+  bool Release(Cache::Handle* handle, bool useful,
+               bool erase_if_last_ref) override;
 
-  void Wait(Cache::Handle* /*handle*/) override {}
+  bool Release(Cache::Handle* handle, bool erase_if_last_ref = false) override;
 
   bool Ref(Cache::Handle* handle) override;
 
-  bool Release(Cache::Handle* handle, bool erase_if_last_ref = false) override;
-
   void Erase(const Slice& key, uint32_t hash) override;
 
   size_t GetUsage() const override;
 
   size_t GetPinnedUsage() const override;
 
+  size_t GetOccupancyCount() const override;
+
+  size_t GetTableAddressCount() const override;
+
   void ApplyToSomeEntries(
       const std::function<void(const Slice& key, void* value, size_t charge,
                                DeleterFn deleter)>& callback,
@@ -765,45 +538,64 @@ class ALIGN_AS(CACHE_LINE_SIZE) ClockCacheShard final : public CacheShard {
 
   std::string GetPrintableOptions() const override { return std::string{}; }
 
- private:
+  // SecondaryCache not yet supported
+  Status Insert(const Slice& key, uint32_t hash, void* value,
+                const Cache::CacheItemHelper* helper, size_t charge,
+                Cache::Handle** handle, Cache::Priority priority) override {
+    return Insert(key, hash, value, charge, helper->del_cb, handle, priority);
+  }
+
+  Cache::Handle* Lookup(const Slice& key, uint32_t hash,
+                        const Cache::CacheItemHelper* /*helper*/,
+                        const Cache::CreateCallback& /*create_cb*/,
+                        Cache::Priority /*priority*/, bool /*wait*/,
+                        Statistics* /*stats*/) override {
+    return Lookup(key, hash);
+  }
+
+  bool IsReady(Cache::Handle* /*handle*/) override { return true; }
+
+  void Wait(Cache::Handle* /*handle*/) override {}
+
+  // Acquire/release N references
+  void TEST_RefN(Cache::Handle* handle, size_t n);
+  void TEST_ReleaseN(Cache::Handle* handle, size_t n);
+
+ private:  // functions
   friend class ClockCache;
   friend class ClockCacheTest;
 
-  ClockHandle* DetachedInsert(ClockHandle* h);
-
-  // Returns the charge of a single handle.
-  static size_t CalcEstimatedHandleCharge(
-      size_t estimated_value_size,
-      CacheMetadataChargePolicy metadata_charge_policy);
+  ClockHandle* DetachedInsert(const ClockHandleMoreData& h);
 
   // Returns the number of bits used to hash an element in the hash
   // table.
   static int CalcHashBits(size_t capacity, size_t estimated_value_size,
                           CacheMetadataChargePolicy metadata_charge_policy);
 
-  // Whether to reject insertion if cache reaches its full capacity.
-  std::atomic<bool> strict_capacity_limit_;
+ private:  // data
+  ClockHandleTable table_;
 
-  // Handles allocated separately from the table.
-  std::atomic<size_t> detached_usage_;
+  // Maximum total charge of all elements stored in the table.
+  std::atomic<size_t> capacity_;
 
-  ClockHandleTable table_;
+  // Whether to reject insertion if cache reaches its full capacity.
+  std::atomic<bool> strict_capacity_limit_;
 };  // class ClockCacheShard
 
-class ClockCache
+class HyperClockCache
 #ifdef NDEBUG
     final
 #endif
     : public ShardedCache {
  public:
-  ClockCache(size_t capacity, size_t estimated_value_size, int num_shard_bits,
-             bool strict_capacity_limit,
-             CacheMetadataChargePolicy metadata_charge_policy =
-                 kDontChargeCacheMetadata);
+  HyperClockCache(size_t capacity, size_t estimated_value_size,
+                  int num_shard_bits, bool strict_capacity_limit,
+                  CacheMetadataChargePolicy metadata_charge_policy =
+                      kDontChargeCacheMetadata);
 
-  ~ClockCache() override;
+  ~HyperClockCache() override;
 
-  const char* Name() const override { return "ClockCache"; }
+  const char* Name() const override { return "HyperClockCache"; }
 
   CacheShard* GetShard(uint32_t shard) override;
 
@@ -823,15 +615,8 @@ class ClockCache
   ClockCacheShard* shards_ = nullptr;
 
   int num_shards_;
-};  // class ClockCache
-
-}  // namespace clock_cache
+};  // class HyperClockCache
 
-// Only for internal testing, temporarily replacing NewClockCache.
-// TODO(Guido) Remove once NewClockCache constructs a ClockCache again.
-extern std::shared_ptr<Cache> ExperimentalNewClockCache(
-    size_t capacity, size_t estimated_value_size, int num_shard_bits,
-    bool strict_capacity_limit,
-    CacheMetadataChargePolicy metadata_charge_policy);
+}  // namespace hyper_clock_cache
 
 }  // namespace ROCKSDB_NAMESPACE