From 8efb072b9f1e0d41db1049437d8886940be71efc Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Wed, 1 Apr 2026 18:31:37 +0000
Subject: [PATCH 1/2] base s3fifo without ghost

---
 cachelib/allocator/CMakeLists.txt             |   1 +
 cachelib/allocator/CacheAllocator.h           |   9 +
 .../allocator/CacheAllocatorS3FIFOCache.cpp   |  21 +
 cachelib/allocator/CacheTraits.h              |   8 +
 cachelib/allocator/ContainerTypes.cpp         |   2 +
 cachelib/allocator/MMS3FIFO.h                 | 611 ++++++++++++++++++
 cachelib/allocator/serialize/objects.thrift   |  27 +
 cachelib/cachebench/cache/Cache.h             |  21 +
 cachelib/cachebench/runner/Stressor.cpp       |  12 +
 cachelib/cachebench/util/CacheConfig.cpp      |   5 +-
 cachelib/cachebench/util/CacheConfig.h        |   6 +
 11 files changed, 722 insertions(+), 1 deletion(-)
 create mode 100644 cachelib/allocator/CacheAllocatorS3FIFOCache.cpp
 create mode 100644 cachelib/allocator/MMS3FIFO.h

diff --git a/cachelib/allocator/CMakeLists.txt b/cachelib/allocator/CMakeLists.txt
index aad79b0a52..ab8a4052d0 100644
--- a/cachelib/allocator/CMakeLists.txt
+++ b/cachelib/allocator/CMakeLists.txt
@@ -33,6 +33,7 @@ add_library (cachelib_allocator
     CacheAllocatorLru5BCacheWithSpinBuckets.cpp
     CacheAllocatorLruCache.cpp
     CacheAllocatorLruCacheWithSpinBuckets.cpp
+    CacheAllocatorS3FIFOCache.cpp
     CacheAllocatorTinyLFU5BCache.cpp
     CacheAllocatorTinyLFUCache.cpp
     CacheAllocatorWTinyLFU5BCache.cpp
diff --git a/cachelib/allocator/CacheAllocator.h b/cachelib/allocator/CacheAllocator.h
index 6082dee06d..807a23f511 100644
--- a/cachelib/allocator/CacheAllocator.h
+++ b/cachelib/allocator/CacheAllocator.h
@@ -6077,6 +6077,7 @@ namespace facebook::cachelib {
 extern template class CacheAllocator<LruCacheTrait>;
 extern template class CacheAllocator<LruCacheWithSpinBucketsTrait>;
 extern template class CacheAllocator<Lru2QCacheTrait>;
+extern template class CacheAllocator<S3FIFOCacheTrait>;
 extern template class CacheAllocator<TinyLFUCacheTrait>;
 extern template class CacheAllocator<WTinyLFUCacheTrait>;
 
@@ -6098,6 +6099,14 @@ using LruAllocatorSpinBuckets = CacheAllocator<LruCacheWithSpinBucketsTrait>;
 using Lru2QAllocator = CacheAllocator<Lru2QCacheTrait>;
 using Lru5B2QAllocator = CacheAllocator<Lru5B2QCacheTrait>;
 
+// CacheAllocator with S3 FIFO eviction policy
+// It maintains 2 queues, one for for probation and one for the main queue.
+// New items are added to the probation queue, and if not accessed
+// will be quickly removed from the cache to remove 1 hit wonders.
+// If accessed while in probation, it will eventually be promoted to the main queue.
+// Items in the tail of main queue will be reinserted if accessed.
+using S3FIFOAllocator = CacheAllocator<S3FIFOCacheTrait>;
+
 // CacheAllocator with Tiny LFU eviction policy
 // It has a window initially to gauage the frequency of accesses of newly
 // inserted items. And eventually it will onl admit items that are accessed
diff --git a/cachelib/allocator/CacheAllocatorS3FIFOCache.cpp b/cachelib/allocator/CacheAllocatorS3FIFOCache.cpp
new file mode 100644
index 0000000000..59e9431a99
--- /dev/null
+++ b/cachelib/allocator/CacheAllocatorS3FIFOCache.cpp
@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "cachelib/allocator/CacheAllocator.h"
+
+namespace facebook::cachelib {
+template class CacheAllocator<S3FIFOCacheTrait>;
+}
diff --git a/cachelib/allocator/CacheTraits.h b/cachelib/allocator/CacheTraits.h
index 26605ae989..674d76e910 100644
--- a/cachelib/allocator/CacheTraits.h
+++ b/cachelib/allocator/CacheTraits.h
@@ -18,6 +18,7 @@
 #include "cachelib/allocator/ChainedHashTable.h"
 #include "cachelib/allocator/MM2Q.h"
 #include "cachelib/allocator/MMLru.h"
+#include "cachelib/allocator/MMS3FIFO.h"
 #include "cachelib/allocator/MMTinyLFU.h"
 #include "cachelib/allocator/MMWTinyLFU.h"
 #include "cachelib/allocator/memory/CompressedPtr.h"
@@ -54,6 +55,13 @@ struct Lru2QCacheTrait {
   using CompressedPtrType = CompressedPtr4B;
 };
 
+struct S3FIFOCacheTrait {
+  using MMType = MMS3FIFO;
+  using AccessType = ChainedHashTable;
+  using AccessTypeLocks = SharedMutexBuckets;
+  using CompressedPtrType = CompressedPtr4B;
+};
+
 struct TinyLFUCacheTrait {
   using MMType = MMTinyLFU;
   using AccessType = ChainedHashTable;
diff --git a/cachelib/allocator/ContainerTypes.cpp b/cachelib/allocator/ContainerTypes.cpp
index e70f051b84..55b62a0dae 100644
--- a/cachelib/allocator/ContainerTypes.cpp
+++ b/cachelib/allocator/ContainerTypes.cpp
@@ -17,6 +17,7 @@
 #include "cachelib/allocator/ChainedHashTable.h"
 #include "cachelib/allocator/MM2Q.h"
 #include "cachelib/allocator/MMLru.h"
+#include "cachelib/allocator/MMS3FIFO.h"
 #include "cachelib/allocator/MMTinyLFU.h"
 #include "cachelib/allocator/MMWTinyLFU.h"
 namespace facebook::cachelib {
@@ -26,6 +27,7 @@ const int MMLru::kId = 1;
 const int MM2Q::kId = 2;
 const int MMTinyLFU::kId = 3;
 const int MMWTinyLFU::kId = 4;
+const int MMS3FIFO::kId = 5;
 
 // AccessType
 const int ChainedHashTable::kId = 1;
diff --git a/cachelib/allocator/MMS3FIFO.h b/cachelib/allocator/MMS3FIFO.h
new file mode 100644
index 0000000000..3772c6e3a1
--- /dev/null
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -0,0 +1,611 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <atomic>
+
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wconversion"
+#include <folly/Format.h>
+#pragma GCC diagnostic pop
+
+#include <folly/container/Array.h>
+#include <folly/lang/Align.h>
+#include <folly/synchronization/DistributedMutex.h>
+
+#include "cachelib/allocator/Cache.h"
+#include "cachelib/allocator/CacheStats.h"
+#include "cachelib/allocator/Util.h"
+#include "cachelib/allocator/datastruct/MultiDList.h"
+#include "cachelib/allocator/memory/serialize/gen-cpp2/objects_types.h"
+#include "cachelib/common/CompilerUtils.h"
+#include "cachelib/common/Mutex.h"
+
+namespace facebook::cachelib {
+
+// S3-FIFO eviction policy with two FIFO queues: Small and Main.
+//
+// New items enter the Small queue. On access (recordAccess), items that are accessed
+// are marked.
+//
+// Eviction follows the S3-FIFO paper: when Small exceeds `smallSizePercent`
+// of total size, the Small tail is processed — accessed items are promoted
+// to Main, unaccessed items become eviction victims. When Small is within
+// target, eviction comes from Main's tail, after item in main's tail are
+// reinserted to head of main if they are accessed.
+class MMS3FIFO {
+ public:
+  // unique identifier per MMType
+  static const int kId;
+
+  template <typename T>
+  using Hook = DListHook<T>;
+  using SerializationType = serialization::MMS3FIFOObject;
+  using SerializationConfigType = serialization::MMS3FIFOConfig;
+  using SerializationTypeContainer = serialization::MMS3FIFOCollection;
+
+  // Main=0, Small=1: MultiDList rbegin() starts at highest index (Small)
+  // tail first, then Main tail — giving correct S3-FIFO eviction order.
+  enum LruType { Main, Small, NumTypes };
+
+  struct Config {
+    explicit Config(SerializationConfigType configState)
+        : Config(*configState.lruRefreshTime(),
+                 *configState.lruRefreshRatio(),
+                 *configState.updateOnWrite(),
+                 *configState.updateOnRead(),
+                 *configState.tryLockUpdate(),
+                 *configState.smallSizePercent(),
+                 *configState.ghostSizePercent()) {}
+
+    Config(bool updateOnR, size_t smallSizePct, size_t ghostSizePct)
+        : Config(/* time */ 60,
+                 /* ratio */ 0.0,
+                 /* updateOnW */ false,
+                 updateOnR,
+                 /* tryLockU */ false,
+                 smallSizePct,
+                 ghostSizePct,
+                 /* mmReconfigureInterval */ 0,
+                 /* useCombinedLockForIterators */ false) {}
+
+    Config(uint32_t time,
+           double ratio,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t smallSizePct,
+           size_t ghostSizePct)
+        : Config(time,
+                 ratio,
+                 updateOnW,
+                 updateOnR,
+                 tryLockU,
+                 smallSizePct,
+                 ghostSizePct,
+                 /* mmReconfigureInterval */ 0,
+                 /* useCombinedLockForIterators */ false) {}
+
+    Config(uint32_t time,
+           double ratio,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t smallSizePct,
+           size_t ghostSizePct,
+           uint32_t mmReconfigureInterval,
+           bool useCombinedLockForIterators)
+        : defaultLruRefreshTime(time),
+          lruRefreshRatio(ratio),
+          updateOnWrite(updateOnW),
+          updateOnRead(updateOnR),
+          tryLockUpdate(tryLockU),
+          smallSizePercent(smallSizePct),
+          ghostSizePercent(ghostSizePct),
+          mmReconfigureIntervalSecs(
+              std::chrono::seconds(mmReconfigureInterval)),
+          useCombinedLockForIterators(useCombinedLockForIterators) {
+      checkConfig();
+    }
+
+    Config() = default;
+    Config(const Config& rhs) = default;
+    Config(Config&& rhs) = default;
+
+    Config& operator=(const Config& rhs) = default;
+    Config& operator=(Config&& rhs) = default;
+
+    void checkConfig() {
+      if (smallSizePercent < 1 || smallSizePercent > 50) {
+        throw std::invalid_argument(
+            folly::sformat("Invalid small queue size {}. Small queue size "
+                           "must be between 1% and 50% of total cache size.",
+                           smallSizePercent));
+      }
+    }
+
+    template <typename... Args>
+    void addExtraConfig(Args...) {}
+
+    uint32_t defaultLruRefreshTime{60};
+    uint32_t lruRefreshTime{defaultLruRefreshTime};
+
+    double lruRefreshRatio{0.};
+
+    bool updateOnWrite{false};
+
+    bool updateOnRead{true};
+
+    bool tryLockUpdate{false};
+
+    // The size of the Small queue as a percentage of the total size.
+    size_t smallSizePercent{10};
+
+    // Reserved for ghost queue sizing. Stored and serialized even though the
+    // ghost queue itself is not wired into eviction behavior yet.
+    size_t ghostSizePercent{100};
+
+    std::chrono::seconds mmReconfigureIntervalSecs{};
+
+    bool useCombinedLockForIterators{false};
+  };
+
+  template <typename T, Hook<T> T::* HookPtr>
+  struct Container {
+   private:
+    using LruList = MultiDList<T, HookPtr>;
+    using Mutex = folly::DistributedMutex;
+    using LockHolder = std::unique_lock<Mutex>;
+    using PtrCompressor = typename T::PtrCompressor;
+    using Time = typename Hook<T>::Time;
+    using CompressedPtrType = typename T::CompressedPtrType;
+    using RefFlags = typename T::Flags;
+
+   public:
+    Container() = default;
+    Container(Config c, PtrCompressor compressor)
+        : lru_(LruType::NumTypes, std::move(compressor)),
+          config_(std::move(c)) {}
+    Container(serialization::MMS3FIFOObject object, PtrCompressor compressor);
+
+    Container(const Container&) = delete;
+    Container& operator=(const Container&) = delete;
+
+    using Iterator = typename LruList::Iterator;
+
+    class LockedIterator : public Iterator {
+     public:
+      LockedIterator(const LockedIterator&) = delete;
+      LockedIterator& operator=(const LockedIterator&) = delete;
+
+      LockedIterator(LockedIterator&&) noexcept = default;
+
+      void destroy() {
+        Iterator::reset();
+        if (l_.owns_lock()) {
+          l_.unlock();
+        }
+      }
+
+      void resetToBegin() {
+        if (!l_.owns_lock()) {
+          l_.lock();
+        }
+        Iterator::resetToBegin();
+      }
+
+     private:
+      LockedIterator& operator=(LockedIterator&&) noexcept = default;
+
+      LockedIterator(LockHolder l, const Iterator& iter) noexcept;
+
+      friend Container<T, HookPtr>;
+
+      LockHolder l_;
+    };
+
+    // In S3-FIFO, recordAccess lazily marks Small items as accessed
+    // (no lock, no list ops). Promotion to Main is deferred to eviction
+    // time. Main is pure FIFO — recordAccess is a no-op.
+    bool recordAccess(T& node, AccessMode mode) noexcept;
+
+    // Adds the node to the Small queue head.
+    bool add(T& node) noexcept;
+
+    bool remove(T& node) noexcept;
+
+    void remove(Iterator& it) noexcept;
+
+    bool replace(T& oldNode, T& newNode) noexcept;
+
+    LockedIterator getEvictionIterator() const noexcept;
+
+    template <typename F>
+    void withEvictionIterator(F&& f);
+
+    template <typename F>
+    void withContainerLock(F&& f);
+
+    Config getConfig() const;
+
+    void setConfig(const Config& newConfig);
+
+    bool isEmpty() const noexcept { return size() == 0; }
+
+    size_t size() const noexcept {
+      return lruMutex_->lock_combine([this]() { return lru_.size(); });
+    }
+
+    EvictionAgeStat getEvictionAgeStat(uint64_t projectedLength) const noexcept;
+
+    serialization::MMS3FIFOObject saveState() const noexcept;
+
+    MMContainerStat getStats() const noexcept;
+
+    static LruType getLruType(const T& node) noexcept {
+      return isSmall(node) ? LruType::Small : LruType::Main;
+    }
+
+   private:
+    EvictionAgeStat getEvictionAgeStatLocked(
+        uint64_t projectedLength) const noexcept;
+
+    static Time getUpdateTime(const T& node) noexcept {
+      return (node.*HookPtr).getUpdateTime();
+    }
+
+    static void setUpdateTime(T& node, Time time) noexcept {
+      (node.*HookPtr).setUpdateTime(time);
+    }
+
+    void removeLocked(T& node) noexcept;
+
+    // Lazy promotion: when Small exceeds smallSizePercent, scan Small tail
+    // and promote accessed items to Main. Called under lock before yielding
+    // the eviction iterator. Const-safe because lru_ is mutable.
+    void lazyPromoteSmallTailLocked() const noexcept;
+
+    void reinsertMain() const noexcept;
+
+    // Flag helpers: kMMFlag0 = "in Small queue"
+    static bool isSmall(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag0>();
+    }
+    static void markSmall(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag0>();
+    }
+    static void unmarkSmall(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag0>();
+    }
+
+    // Flag helpers: kMMFlag1 = "accessed" (for stats)
+    static bool isAccessed(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag1>();
+    }
+    static void markAccessed(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag1>();
+    }
+    static void unmarkAccessed(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag1>();
+    }
+
+    mutable folly::cacheline_aligned<Mutex> lruMutex_;
+
+    mutable LruList lru_{};
+
+    Config config_{};
+
+    friend class MMTypeTest<MMS3FIFO>;
+  };
+};
+
+/* Container Interface Implementation */
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+MMS3FIFO::Container<T, HookPtr>::Container(serialization::MMS3FIFOObject object,
+                                           PtrCompressor compressor)
+    : lru_(*object.lrus(), std::move(compressor)), config_(*object.config()) {}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+bool MMS3FIFO::Container<T, HookPtr>::recordAccess(T& node,
+                                                   AccessMode mode) noexcept {
+  if ((mode == AccessMode::kWrite && !config_.updateOnWrite) ||
+      (mode == AccessMode::kRead && !config_.updateOnRead)) {
+    return false;
+  }
+
+  const auto curr = static_cast<Time>(util::getCurrentTimeSec());
+
+  if (!node.isInMMContainer()) {
+    return false;
+  }
+
+  // For Small items: lazily mark as accessed. Promotion to Main is
+  // deferred to eviction time (lazyPromoteSmallTailLocked).
+  // No lock needed — flag ops are atomic, time write is safe on x86.
+  if (!isAccessed(node)) {
+    markAccessed(node);
+    setUpdateTime(node, curr);
+  }
+  return true;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+bool MMS3FIFO::Container<T, HookPtr>::add(T& node) noexcept {
+  const auto currTime = static_cast<Time>(util::getCurrentTimeSec());
+
+  return lruMutex_->lock_combine([this, &node, currTime]() {
+    if (node.isInMMContainer()) {
+      return false;
+    }
+
+    lru_.getList(LruType::Small).linkAtHead(node);
+    markSmall(node);
+    node.markInMMContainer();
+    setUpdateTime(node, currTime);
+    unmarkAccessed(node);
+
+    return true;
+  });
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::lazyPromoteSmallTailLocked()
+    const noexcept {
+  const auto totalSize = lru_.size();
+  if (totalSize == 0) {
+    return;
+  }
+  const auto targetSmallSize = totalSize * config_.smallSizePercent / 100;
+  auto& smallList = lru_.getList(LruType::Small);
+
+  // Per S3-FIFO paper: only process Small when it exceeds target size.
+  while (smallList.size() > targetSmallSize) {
+    auto* tail = smallList.getTail();
+    if (!tail) {
+      break;
+    }
+    if (isAccessed(*tail)) {
+      // Accessed: promote to Main
+      smallList.remove(*tail);
+      lru_.getList(LruType::Main).linkAtHead(*tail);
+      unmarkSmall(*tail);
+      unmarkAccessed(*tail);
+    } else {
+      break; // Unaccessed: leave as eviction victim
+    }
+  }
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::reinsertMain() const noexcept {
+  auto& mainList = lru_.getList(LruType::Main);
+  auto tail = mainList.getTail();
+  while (tail && isAccessed(*tail)) {
+    // Accessed: reinsert to head
+    mainList.remove(*tail);
+    mainList.linkAtHead(*tail);
+    unmarkAccessed(*tail);
+    tail = mainList.getTail();
+  }
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+typename MMS3FIFO::Container<T, HookPtr>::LockedIterator
+MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() const noexcept {
+  LockHolder l(*lruMutex_);
+  lazyPromoteSmallTailLocked();
+
+  const auto totalSize = lru_.size();
+  const auto targetSmallSize =
+      totalSize == 0 ? 0 : totalSize * config_.smallSizePercent / 100;
+
+  if (lru_.getList(LruType::Small).size() > targetSmallSize) {
+    // Small exceeds target — evict from Small first
+    return LockedIterator{std::move(l), lru_.rbegin()};
+  }
+  // Reinsert to main
+  reinsertMain();
+  // Small within target — evict from Main (skip Small)
+  return LockedIterator{std::move(l), lru_.rbegin(LruType::Main)};
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+template <typename F>
+void MMS3FIFO::Container<T, HookPtr>::withEvictionIterator(F&& fun) {
+  auto makeItr = [this]() {
+    lazyPromoteSmallTailLocked();
+    const auto totalSize = lru_.size();
+    const auto targetSmallSize =
+        totalSize == 0 ? 0 : totalSize * config_.smallSizePercent / 100;
+    if (lru_.getList(LruType::Small).size() > targetSmallSize) {
+      return Iterator{lru_.rbegin()};
+    }
+    // Lazy promote the main
+    reinsertMain();
+    return Iterator{lru_.rbegin(LruType::Main)};
+  };
+
+  if (config_.useCombinedLockForIterators) {
+    lruMutex_->lock_combine([&fun, &makeItr]() { fun(makeItr()); });
+  } else {
+    LockHolder lck{*lruMutex_};
+    fun(makeItr());
+  }
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+template <typename F>
+void MMS3FIFO::Container<T, HookPtr>::withContainerLock(F&& fun) {
+  lruMutex_->lock_combine([&fun]() { fun(); });
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::removeLocked(T& node) noexcept {
+  if (isSmall(node)) {
+    lru_.getList(LruType::Small).remove(node);
+    unmarkSmall(node);
+  } else {
+    lru_.getList(LruType::Main).remove(node);
+  }
+  unmarkAccessed(node);
+  node.unmarkInMMContainer();
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+bool MMS3FIFO::Container<T, HookPtr>::remove(T& node) noexcept {
+  return lruMutex_->lock_combine([this, &node]() {
+    if (!node.isInMMContainer()) {
+      return false;
+    }
+    removeLocked(node);
+    return true;
+  });
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::remove(Iterator& it) noexcept {
+  T& node = *it;
+  XDCHECK(node.isInMMContainer());
+  ++it;
+  removeLocked(node);
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+bool MMS3FIFO::Container<T, HookPtr>::replace(T& oldNode, T& newNode) noexcept {
+  return lruMutex_->lock_combine([this, &oldNode, &newNode]() {
+    if (!oldNode.isInMMContainer() || newNode.isInMMContainer()) {
+      return false;
+    }
+    const auto updateTime = getUpdateTime(oldNode);
+
+    if (isSmall(oldNode)) {
+      lru_.getList(LruType::Small).replace(oldNode, newNode);
+      unmarkSmall(oldNode);
+      markSmall(newNode);
+    } else {
+      lru_.getList(LruType::Main).replace(oldNode, newNode);
+    }
+
+    oldNode.unmarkInMMContainer();
+    newNode.markInMMContainer();
+    setUpdateTime(newNode, updateTime);
+    if (isAccessed(oldNode)) {
+      markAccessed(newNode);
+    } else {
+      unmarkAccessed(newNode);
+    }
+    return true;
+  });
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+typename MMS3FIFO::Config MMS3FIFO::Container<T, HookPtr>::getConfig() const {
+  return lruMutex_->lock_combine([this]() { return config_; });
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::setConfig(const Config& c) {
+  lruMutex_->lock_combine([this, &c]() { config_ = c; });
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+cachelib::EvictionAgeStat MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStat(
+    uint64_t projectedLength) const noexcept {
+  return lruMutex_->lock_combine([this, projectedLength]() {
+    return getEvictionAgeStatLocked(projectedLength);
+  });
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+cachelib::EvictionAgeStat
+MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStatLocked(
+    uint64_t projectedLength) const noexcept {
+  EvictionAgeStat stat{};
+  const auto currTime = static_cast<Time>(util::getCurrentTimeSec());
+
+  // Report Main stats in warmQueueStat
+  {
+    auto& list = lru_.getList(LruType::Main);
+    auto it = list.rbegin();
+    stat.warmQueueStat.oldestElementAge =
+        it != list.rend() ? currTime - getUpdateTime(*it) : 0;
+    stat.warmQueueStat.size = list.size();
+    for (size_t numSeen = 0; numSeen < projectedLength && it != list.rend();
+         ++numSeen, ++it) {
+    }
+    stat.warmQueueStat.projectedAge = it != list.rend()
+                                          ? currTime - getUpdateTime(*it)
+                                          : stat.warmQueueStat.oldestElementAge;
+  }
+
+  // Report Small stats in coldQueueStat
+  {
+    auto& list = lru_.getList(LruType::Small);
+    auto it = list.rbegin();
+    stat.coldQueueStat.oldestElementAge =
+        it != list.rend() ? currTime - getUpdateTime(*it) : 0;
+    stat.coldQueueStat.size = list.size();
+    for (size_t numSeen = 0; numSeen < projectedLength && it != list.rend();
+         ++numSeen, ++it) {
+    }
+    stat.coldQueueStat.projectedAge = it != list.rend()
+                                          ? currTime - getUpdateTime(*it)
+                                          : stat.coldQueueStat.oldestElementAge;
+  }
+
+  return stat;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+serialization::MMS3FIFOObject MMS3FIFO::Container<T, HookPtr>::saveState()
+    const noexcept {
+  serialization::MMS3FIFOConfig configObject;
+  *configObject.lruRefreshTime() = config_.lruRefreshTime;
+  *configObject.lruRefreshRatio() = config_.lruRefreshRatio;
+  *configObject.updateOnWrite() = config_.updateOnWrite;
+  *configObject.updateOnRead() = config_.updateOnRead;
+  *configObject.tryLockUpdate() = config_.tryLockUpdate;
+  *configObject.smallSizePercent() = config_.smallSizePercent;
+  *configObject.ghostSizePercent() = config_.ghostSizePercent;
+
+  serialization::MMS3FIFOObject object;
+  *object.config() = configObject;
+  *object.lrus() = lru_.saveState();
+  return object;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+MMContainerStat MMS3FIFO::Container<T, HookPtr>::getStats() const noexcept {
+  auto stat = lruMutex_->lock_combine([this]() {
+    auto* tail =
+        lru_.size() == 0 ? nullptr : lru_.getList(LruType::Small).getTail();
+    if (!tail) {
+      tail = lru_.getList(LruType::Main).getTail();
+    }
+    return folly::make_array(lru_.size(),
+                             tail == nullptr ? 0 : getUpdateTime(*tail),
+                             static_cast<uint32_t>(0));
+  });
+  return {stat[0], stat[1], stat[2], 0, 0, 0, 0};
+}
+
+// LockedIterator constructor
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+MMS3FIFO::Container<T, HookPtr>::LockedIterator::LockedIterator(
+    LockHolder l, const Iterator& iter) noexcept
+    : Iterator(iter), l_(std::move(l)) {}
+} // namespace facebook::cachelib
diff --git a/cachelib/allocator/serialize/objects.thrift b/cachelib/allocator/serialize/objects.thrift
index 15d47bd2fc..d9def511ec 100644
--- a/cachelib/allocator/serialize/objects.thrift
+++ b/cachelib/allocator/serialize/objects.thrift
@@ -109,6 +109,33 @@ struct MM2QCollection {
   1: required map<i32, map<i32, MM2QObject>> pools;
 }
 
+
+
+struct MMS3FIFOConfig {
+  1: required bool updateOnWrite;
+  2: bool updateOnRead = true;
+  3: double smallSizePercent = 0.0;
+  4: double ghostSizePercent = 100.0;
+  5: bool tryLockUpdate = false;
+  6: double lruRefreshRatio = 0.0;
+  7: double lruRefreshTime = 0.0;
+}
+
+struct MMS3FIFOObject {
+  1: required MMS3FIFOConfig config;
+
+  // number of evictions for this MM object.
+  2: i64 evictions = 0;
+
+  // Warm, hot and cold lrus
+  3: required MultiDListObject lrus;
+}
+
+struct MMS3FIFOCollection {
+  1: required map<i32, map<i32, MMS3FIFOObject>> pools;
+}
+
+
 struct MMTinyLFUConfig {
   1: required i32 lruRefreshTime;
   2: required bool updateOnWrite;
diff --git a/cachelib/cachebench/cache/Cache.h b/cachelib/cachebench/cache/Cache.h
index 6f1d35683d..102052fe8a 100644
--- a/cachelib/cachebench/cache/Cache.h
+++ b/cachelib/cachebench/cache/Cache.h
@@ -489,6 +489,27 @@ inline typename Lru2QAllocator::MMConfig makeMMConfig(
                                   config.useCombinedLockForIterators);
 }
 
+template <>
+inline typename S3FIFOAllocator::MMConfig makeMMConfig(
+    CacheConfig const& config) {
+  return S3FIFOAllocator::MMConfig(config.lruRefreshSec,
+                                   config.lruRefreshRatio,
+                                   config.lruUpdateOnWrite,
+                                   config.lruUpdateOnRead,
+                                   config.tryLockUpdate,
+                                   config.tinySizePercent,
+                                   config.ghostSizePercent,
+                                   config.mmReconfigureIntervalSecs,
+                                   config.useCombinedLockForIterators);
+}
+
+template <>
+inline typename TinyLFUAllocator::MMConfig makeMMConfig(
+    CacheConfig const& config) {
+  return TinyLFUAllocator::MMConfig(
+      config.lruRefreshSec, config.lruUpdateOnWrite, config.lruUpdateOnRead);
+}
+
 template <typename Allocator>
 uint64_t Cache<Allocator>::fetchNandWrites() const {
   size_t total = 0;
diff --git a/cachelib/cachebench/runner/Stressor.cpp b/cachelib/cachebench/runner/Stressor.cpp
index 0bca4438bb..3b745a3a13 100644
--- a/cachelib/cachebench/runner/Stressor.cpp
+++ b/cachelib/cachebench/runner/Stressor.cpp
@@ -203,6 +203,12 @@ std::unique_ptr<Stressor> Stressor::makeStressor(
     } else if (cacheConfig.allocator == "LRU5B2Q") {
       return std::make_unique<AsyncCacheStressor<Lru5B2QAllocator>>(
           cacheConfig, stressorConfig, std::move(generator));
+    } else if (cacheConfig.allocator == "S3FIFO") {
+    return std::make_unique<CacheStressor<S3FIFOAllocator>>(
+        cacheConfig, stressorConfig, std::move(generator));
+    } else if (cacheConfig.allocator == "TinyLFU") {
+      return std::make_unique<CacheStressor<TinyLFUAllocator>>(
+          cacheConfig, stressorConfig, std::move(generator));
     }
   } else {
     auto generator = makeGenerator(stressorConfig);
@@ -219,6 +225,12 @@ std::unique_ptr<Stressor> Stressor::makeStressor(
     } else if (cacheConfig.allocator == "LRU5B2Q") {
       return std::make_unique<CacheStressor<Lru5B2QAllocator>>(
           cacheConfig, stressorConfig, std::move(generator));
+    } else if (cacheConfig.allocator == "S3FIFO") {
+      return std::make_unique<CacheStressor<S3FIFOAllocator>>(
+          cacheConfig, stressorConfig, std::move(generator));
+    }  else if (cacheConfig.allocator == "TinyLFU") {
+      return std::make_unique<CacheStressor<TinyLFUAllocator>>(
+          cacheConfig, stressorConfig, std::move(generator));
     }
   }
   throw std::invalid_argument("Invalid config");
diff --git a/cachelib/cachebench/util/CacheConfig.cpp b/cachelib/cachebench/util/CacheConfig.cpp
index 6d8f40874b..9358782859 100644
--- a/cachelib/cachebench/util/CacheConfig.cpp
+++ b/cachelib/cachebench/util/CacheConfig.cpp
@@ -48,6 +48,9 @@ CacheConfig::CacheConfig(const folly::dynamic& configJson) {
   JSONSetVal(configJson, lru2qHotPct);
   JSONSetVal(configJson, lru2qColdPct);
 
+  JSONSetVal(configJson, ghostSizePercent);
+  JSONSetVal(configJson, tinySizePercent);
+
   JSONSetVal(configJson, allocFactor);
   JSONSetVal(configJson, maxAllocSize);
   JSONSetVal(configJson, minAllocSize);
@@ -112,7 +115,7 @@ CacheConfig::CacheConfig(const folly::dynamic& configJson) {
   // if you added new fields to the configuration, update the JSONSetVal
   // to make them available for the json configs and increment the size
   // below
-  checkCorrectSize<CacheConfig, 760>();
+  checkCorrectSize<CacheConfig, 776>();
 
   if (numPools != poolSizes.size()) {
     throw std::invalid_argument(folly::sformat(
diff --git a/cachelib/cachebench/util/CacheConfig.h b/cachelib/cachebench/util/CacheConfig.h
index d1db6cbe14..7024aeab13 100644
--- a/cachelib/cachebench/util/CacheConfig.h
+++ b/cachelib/cachebench/util/CacheConfig.h
@@ -41,6 +41,8 @@ class CacheMonitorFactory {
   virtual std::unique_ptr<CacheMonitor> create(Lru2QAllocator& cache) = 0;
   virtual std::unique_ptr<CacheMonitor> create(Lru5BAllocator& cache) = 0;
   virtual std::unique_ptr<CacheMonitor> create(Lru5B2QAllocator& cache) = 0;
+  virtual std::unique_ptr<CacheMonitor> create(S3FIFOAllocator& cache) = 0;
+  virtual std::unique_ptr<CacheMonitor> create(TinyLFUAllocator& cache) = 0;
 };
 
 // Parse memory tiers configuration from JSON config
@@ -103,6 +105,10 @@ struct CacheConfig : public JSONConfig {
   size_t lru2qHotPct{20};
   size_t lru2qColdPct{20};
 
+  // S3FIFO params
+  size_t ghostSizePercent{100};
+  size_t tinySizePercent{10};
+
   double allocFactor{1.5};
   // maximum alloc size generated using the alloc factor above.
   size_t maxAllocSize{1024 * 1024};

From db04a6f5ffc985de3175f8c3b3c276cb86c4d5e3 Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Thu, 2 Apr 2026 00:36:21 +0000
Subject: [PATCH 2/2] add ghost

---
 cachelib/allocator/CMakeLists.txt             |   1 +
 cachelib/allocator/CacheAllocator.h           |   2 +
 .../allocator/CacheAllocatorS3FIFO5BCache.cpp |  21 ++
 cachelib/allocator/CacheTraits.h              |   7 +
 cachelib/allocator/MMS3FIFO.h                 |  64 ++++-
 cachelib/common/AtomicHashSet.h               | 246 ++++++++++++++++++
 6 files changed, 336 insertions(+), 5 deletions(-)
 create mode 100644 cachelib/allocator/CacheAllocatorS3FIFO5BCache.cpp
 create mode 100644 cachelib/common/AtomicHashSet.h

diff --git a/cachelib/allocator/CMakeLists.txt b/cachelib/allocator/CMakeLists.txt
index ab8a4052d0..41c59290b8 100644
--- a/cachelib/allocator/CMakeLists.txt
+++ b/cachelib/allocator/CMakeLists.txt
@@ -34,6 +34,7 @@ add_library (cachelib_allocator
     CacheAllocatorLruCache.cpp
     CacheAllocatorLruCacheWithSpinBuckets.cpp
     CacheAllocatorS3FIFOCache.cpp
+    CacheAllocatorS3FIFO5BCache.cpp
     CacheAllocatorTinyLFU5BCache.cpp
     CacheAllocatorTinyLFUCache.cpp
     CacheAllocatorWTinyLFU5BCache.cpp
diff --git a/cachelib/allocator/CacheAllocator.h b/cachelib/allocator/CacheAllocator.h
index 807a23f511..161a80ff2c 100644
--- a/cachelib/allocator/CacheAllocator.h
+++ b/cachelib/allocator/CacheAllocator.h
@@ -6078,6 +6078,7 @@ extern template class CacheAllocator<LruCacheTrait>;
 extern template class CacheAllocator<LruCacheWithSpinBucketsTrait>;
 extern template class CacheAllocator<Lru2QCacheTrait>;
 extern template class CacheAllocator<S3FIFOCacheTrait>;
+extern template class CacheAllocator<S3FIFO5BCacheTrait>;
 extern template class CacheAllocator<TinyLFUCacheTrait>;
 extern template class CacheAllocator<WTinyLFUCacheTrait>;
 
@@ -6106,6 +6107,7 @@ using Lru5B2QAllocator = CacheAllocator<Lru5B2QCacheTrait>;
 // If accessed while in probation, it will eventually be promoted to the main queue.
 // Items in the tail of main queue will be reinserted if accessed.
 using S3FIFOAllocator = CacheAllocator<S3FIFOCacheTrait>;
+using S3FIFO5BAllocator = CacheAllocator<S3FIFO5BCacheTrait>;
 
 // CacheAllocator with Tiny LFU eviction policy
 // It has a window initially to gauage the frequency of accesses of newly
diff --git a/cachelib/allocator/CacheAllocatorS3FIFO5BCache.cpp b/cachelib/allocator/CacheAllocatorS3FIFO5BCache.cpp
new file mode 100644
index 0000000000..c241ce84d7
--- /dev/null
+++ b/cachelib/allocator/CacheAllocatorS3FIFO5BCache.cpp
@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "cachelib/allocator/CacheAllocator.h"
+
+namespace facebook::cachelib {
+template class CacheAllocator<S3FIFO5BCacheTrait>;
+}
\ No newline at end of file
diff --git a/cachelib/allocator/CacheTraits.h b/cachelib/allocator/CacheTraits.h
index 674d76e910..9c49d43894 100644
--- a/cachelib/allocator/CacheTraits.h
+++ b/cachelib/allocator/CacheTraits.h
@@ -62,6 +62,13 @@ struct S3FIFOCacheTrait {
   using CompressedPtrType = CompressedPtr4B;
 };
 
+struct S3FIFO5BCacheTrait {
+  using MMType = MMS3FIFO;
+  using AccessType = ChainedHashTable;
+  using AccessTypeLocks = SharedMutexBuckets;
+  using CompressedPtrType = CompressedPtr5B;
+};
+
 struct TinyLFUCacheTrait {
   using MMType = MMTinyLFU;
   using AccessType = ChainedHashTable;
diff --git a/cachelib/allocator/MMS3FIFO.h b/cachelib/allocator/MMS3FIFO.h
index 3772c6e3a1..059dec1960 100644
--- a/cachelib/allocator/MMS3FIFO.h
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -16,6 +16,7 @@
 
 #pragma once
 
+#include <algorithm>
 #include <atomic>
 
 #pragma GCC diagnostic push
@@ -24,6 +25,7 @@
 #pragma GCC diagnostic pop
 
 #include <folly/container/Array.h>
+#include <folly/hash/Hash.h>
 #include <folly/lang/Align.h>
 #include <folly/synchronization/DistributedMutex.h>
 
@@ -34,6 +36,7 @@
 #include "cachelib/allocator/memory/serialize/gen-cpp2/objects_types.h"
 #include "cachelib/common/CompilerUtils.h"
 #include "cachelib/common/Mutex.h"
+#include "cachelib/common/AtomicHashSet.h"
 
 namespace facebook::cachelib {
 
@@ -272,8 +275,40 @@ class MMS3FIFO {
       (node.*HookPtr).setUpdateTime(time);
     }
 
+    static uint32_t hashNode(const T& node) noexcept {
+      return static_cast<uint32_t>(
+          folly::hasher<folly::StringPiece>()(node.getKey()));
+    }
+
     void removeLocked(T& node) noexcept;
 
+    // This function is not locked, thus the use of atomics.
+    void maybeGrowGhostCapacity() const noexcept {
+      // Approx size is lru.size(), but called under another function's lock.
+      const auto totalSize = approxSize_.load(std::memory_order_relaxed);
+      if (totalSize == 0 || config_.ghostSizePercent == 0) {
+        return;
+      }
+
+      const auto currCapacity = ghostCapacity_.load(std::memory_order_relaxed);
+      const auto capacity = totalSize * config_.ghostSizePercent / 100;
+
+      // Only grow if target capacity at least doubles.
+      if (capacity < 2 * currCapacity) {
+        return;
+      }
+
+      // Require stable size (cache is full), so ensure 2 consecutive calls didn't have a size change.
+      const auto lastRequestedSize =
+          lastSize_.exchange(totalSize, std::memory_order_relaxed);
+      if (lastRequestedSize != totalSize) {
+        return;
+      }
+
+      ghost_.resize(capacity);
+      ghostCapacity_.store(capacity, std::memory_order_relaxed);
+    }
+
     // Lazy promotion: when Small exceeds smallSizePercent, scan Small tail
     // and promote accessed items to Main. Called under lock before yielding
     // the eviction iterator. Const-safe because lru_ is mutable.
@@ -309,6 +344,12 @@ class MMS3FIFO {
 
     Config config_{};
 
+    // mutable util::FIFOHashSet32 ghost_{};
+    mutable util::AtomicFIFOHashSet32 ghost_{};
+    mutable std::atomic<size_t> ghostCapacity_{0};
+    mutable std::atomic<size_t> lastSize_{0};
+    mutable std::atomic<size_t> approxSize_{0};
+
     friend class MMTypeTest<MMS3FIFO>;
   };
 };
@@ -317,7 +358,8 @@ class MMS3FIFO {
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 MMS3FIFO::Container<T, HookPtr>::Container(serialization::MMS3FIFOObject object,
                                            PtrCompressor compressor)
-    : lru_(*object.lrus(), std::move(compressor)), config_(*object.config()) {}
+    : lru_(*object.lrus(), std::move(compressor)), config_(*object.config()) {
+}
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 bool MMS3FIFO::Container<T, HookPtr>::recordAccess(T& node,
@@ -347,13 +389,19 @@ template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 bool MMS3FIFO::Container<T, HookPtr>::add(T& node) noexcept {
   const auto currTime = static_cast<Time>(util::getCurrentTimeSec());
 
-  return lruMutex_->lock_combine([this, &node, currTime]() {
+  const auto insertIntoMain = ghost_.contains(hashNode(node));
+  return lruMutex_->lock_combine([this, &node, currTime, insertIntoMain]() {
     if (node.isInMMContainer()) {
       return false;
     }
 
-    lru_.getList(LruType::Small).linkAtHead(node);
-    markSmall(node);
+    auto listType = insertIntoMain ? LruType::Main : LruType::Small;
+    lru_.getList(listType).linkAtHead(node);
+    if (insertIntoMain) {
+      unmarkSmall(node);
+    } else {
+      markSmall(node);
+    }
     node.markInMMContainer();
     setUpdateTime(node, currTime);
     unmarkAccessed(node);
@@ -406,13 +454,14 @@ void MMS3FIFO::Container<T, HookPtr>::reinsertMain() const noexcept {
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 typename MMS3FIFO::Container<T, HookPtr>::LockedIterator
 MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() const noexcept {
+  maybeGrowGhostCapacity();
   LockHolder l(*lruMutex_);
   lazyPromoteSmallTailLocked();
 
   const auto totalSize = lru_.size();
   const auto targetSmallSize =
       totalSize == 0 ? 0 : totalSize * config_.smallSizePercent / 100;
-
+  approxSize_.store(lru_.size(), std::memory_order_relaxed);
   if (lru_.getList(LruType::Small).size() > targetSmallSize) {
     // Small exceeds target — evict from Small first
     return LockedIterator{std::move(l), lru_.rbegin()};
@@ -426,7 +475,9 @@ MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() const noexcept {
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 template <typename F>
 void MMS3FIFO::Container<T, HookPtr>::withEvictionIterator(F&& fun) {
+  maybeGrowGhostCapacity();
   auto makeItr = [this]() {
+    approxSize_.store(lru_.size(), std::memory_order_relaxed);
     lazyPromoteSmallTailLocked();
     const auto totalSize = lru_.size();
     const auto targetSmallSize =
@@ -481,6 +532,9 @@ void MMS3FIFO::Container<T, HookPtr>::remove(Iterator& it) noexcept {
   T& node = *it;
   XDCHECK(node.isInMMContainer());
   ++it;
+  if (isSmall(node)) {
+    ghost_.insert(hashNode(node));
+  }
   removeLocked(node);
 }
 
diff --git a/cachelib/common/AtomicHashSet.h b/cachelib/common/AtomicHashSet.h
new file mode 100644
index 0000000000..4900f478b7
--- /dev/null
+++ b/cachelib/common/AtomicHashSet.h
@@ -0,0 +1,246 @@
+#pragma once
+
+#include <algorithm>
+#include <atomic>
+#include <cstdint>
+#include <cstring>
+#include <limits>
+#include <memory>
+
+namespace facebook::cachelib::util {
+namespace detail {
+
+template <typename KeyT = uint32_t>
+class AtomicFIFOHashSetBase {
+ public:
+  using Key = KeyT;
+  using TS = uint32_t;
+
+  static_assert(
+      sizeof(KeyT) == sizeof(uint32_t),
+      "AtomicFIFOHashSetBase currently supports 32-bit keys only.");
+
+  AtomicFIFOHashSetBase() = default;
+
+  explicit AtomicFIFOHashSetBase(size_t capacity) noexcept {
+    resize(capacity);
+  }
+
+  AtomicFIFOHashSetBase(const AtomicFIFOHashSetBase&) = delete;
+  AtomicFIFOHashSetBase& operator=(const AtomicFIFOHashSetBase&) = delete;
+  AtomicFIFOHashSetBase(AtomicFIFOHashSetBase&&) = delete;
+  AtomicFIFOHashSetBase& operator=(AtomicFIFOHashSetBase&&) = delete;
+
+  bool initialized() const noexcept {
+    return table_.load(std::memory_order_acquire) != nullptr;
+  }
+
+  size_t capacity() const noexcept {
+    return fifoSize_.load(std::memory_order_relaxed);
+  }
+
+  void resize(size_t newSize) noexcept {
+    if (newSize == 0) {
+      fifoSize_.store(0, std::memory_order_relaxed);
+      return;
+    }
+
+    if (!initialized()) {
+      initStorage(newSize);
+    }
+
+    fifoSize_.store(static_cast<TS>(newSize), std::memory_order_relaxed);
+  }
+
+  bool contains(Key key) noexcept {
+    auto* tbl = table_.load(std::memory_order_acquire);
+    if (tbl == nullptr) {
+      return false;
+    }
+
+    const TS now = seq_.load(std::memory_order_relaxed);
+    const size_t bucketIdx = getBucketIdx(key, tbl->numElem);
+
+    for (size_t i = 0; i < kItemsPerBucket; ++i) {
+      auto* slot = &tbl->slots[bucketIdx + i];
+      uint64_t val = __atomic_load_n(slot, __ATOMIC_RELAXED);
+
+      if (val == 0) {
+        continue;
+      }
+
+      if (isExpired(val, now)) {
+        tryClear(slot, val);
+        continue;
+      }
+
+      if (matchKey(val, key)) {
+        tryClear(slot, val);
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  void insert(Key key) noexcept {
+    auto* tbl = table_.load(std::memory_order_acquire);
+    if (tbl == nullptr) {
+      return;
+    }
+
+    const TS ts = nextTimestamp();
+    const uint64_t newVal = pack(key, ts);
+    const size_t bucketIdx = getBucketIdx(key, tbl->numElem);
+
+    for (size_t i = 0; i < kItemsPerBucket; ++i) {
+      auto* slot = &tbl->slots[bucketIdx + i];
+      uint64_t val = __atomic_load_n(slot, __ATOMIC_RELAXED);
+
+      if (val == 0) {
+        uint64_t expected = 0;
+        if (__atomic_compare_exchange_n(slot,
+                                        &expected,
+                                        newVal,
+                                        false,
+                                        __ATOMIC_RELAXED,
+                                        __ATOMIC_RELAXED)) {
+          return;
+        }
+        continue;
+      }
+
+      if (isExpired(val, ts)) {
+        if (tryClear(slot, val)) {
+          uint64_t expected = 0;
+          if (__atomic_compare_exchange_n(slot,
+                                          &expected,
+                                          newVal,
+                                          false,
+                                          __ATOMIC_RELAXED,
+                                          __ATOMIC_RELAXED)) {
+            return;
+          }
+        }
+        continue;
+      }
+
+      if (matchKey(val, key)) {
+        return;
+      }
+    }
+
+    const size_t idx =
+        bucketIdx + (static_cast<uint32_t>(key) & (kItemsPerBucket - 1));
+    __atomic_store_n(&tbl->slots[idx], newVal, __ATOMIC_RELAXED);
+    numEvicts_.fetch_add(1, std::memory_order_relaxed);
+  }
+
+ private:
+  static constexpr size_t kLoadFactorInv = 2;
+  static constexpr size_t kItemsPerBucket = 8;
+  static constexpr uint64_t kKeyMask = 0x00000000FFFFFFFFULL;
+
+  struct Table {
+    explicit Table(size_t n) : numElem(n), slots(new uint64_t[n]) {
+      std::memset(slots.get(), 0, n * sizeof(uint64_t));
+    }
+
+    size_t numElem{0};
+    std::unique_ptr<uint64_t[]> slots;
+  };
+
+  static size_t roundUpToBucket(size_t n) noexcept {
+    return (n + (kItemsPerBucket - 1)) & ~(kItemsPerBucket - 1);
+  }
+
+  void initStorage(size_t logicalCap) noexcept {
+    if (logicalCap == 0 || initialized()) {
+      return;
+    }
+
+    const size_t numElem = roundUpToBucket(
+        std::max<size_t>(logicalCap * kLoadFactorInv, kItemsPerBucket));
+    auto newTable = std::make_unique<Table>(numElem);
+    auto* raw = newTable.get();
+    Table* expected = nullptr;
+
+    if (table_.compare_exchange_strong(expected,
+                                       raw,
+                                       std::memory_order_release,
+                                       std::memory_order_acquire)) {
+      owner_ = std::move(newTable);
+    }
+  }
+
+  static size_t getBucketIdx(Key key, size_t numElem) noexcept {
+    const size_t h = static_cast<uint32_t>(key) % numElem;
+    return h & ~(kItemsPerBucket - 1);
+  }
+
+  static bool matchKey(uint64_t val, Key key) noexcept {
+    return static_cast<uint32_t>(val & kKeyMask) ==
+           static_cast<uint32_t>(key);
+  }
+
+  static uint64_t pack(Key key, TS ts) noexcept {
+    const uint64_t uKey = static_cast<uint32_t>(key);
+    const uint64_t uTsStored = static_cast<uint64_t>(ts + 1);
+    return uKey | (uTsStored << 32);
+  }
+
+  static TS unpackTs(uint64_t val) noexcept {
+    return static_cast<TS>((val >> 32) - 1);
+  }
+
+  bool isExpired(uint64_t val, TS now) const noexcept {
+    const TS cap = fifoSize_.load(std::memory_order_relaxed);
+    if (cap == 0) {
+      return true;
+    }
+
+    const TS age = static_cast<TS>(now - unpackTs(val));
+    return age > cap;
+  }
+
+  static bool tryClear(uint64_t* slot, uint64_t expected) noexcept {
+    return __atomic_compare_exchange_n(slot,
+                                       &expected,
+                                       uint64_t{0},
+                                       false,
+                                       __ATOMIC_RELAXED,
+                                       __ATOMIC_RELAXED);
+  }
+
+  TS nextTimestamp() noexcept {
+    TS cur = seq_.load(std::memory_order_relaxed);
+    while (true) {
+      const TS next =
+          (cur >= std::numeric_limits<TS>::max() - 1) ? 0
+                                                      : static_cast<TS>(cur + 1);
+
+      if (seq_.compare_exchange_weak(cur,
+                                     next,
+                                     std::memory_order_relaxed,
+                                     std::memory_order_relaxed)) {
+        return cur;
+      }
+    }
+  }
+
+  std::unique_ptr<Table> owner_;
+  std::atomic<Table*> table_{nullptr};
+  std::atomic<TS> fifoSize_{0};
+  std::atomic<TS> seq_{0};
+  std::atomic<uint64_t> numEvicts_{0};
+};
+
+} // namespace detail
+
+using AtomicFIFOHashSet32 = detail::AtomicFIFOHashSetBase<uint32_t>;
+
+} // namespace facebook::cachelib::util
+
+namespace facebook::cachelib {
+using AtomicFIFOHashTable = util::AtomicFIFOHashSet32;
+}