From 10a5d2a1d3cd2aeb30d6ecc1e3a31a678403a694 Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Wed, 19 Nov 2025 17:36:48 +0000
Subject: [PATCH 01/15] s3fifo skeleton

---
 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                 | 997 ++++++++++++++++++
 cachelib/allocator/serialize/objects.thrift   |  31 +
 7 files changed, 1069 insertions(+)
 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..093f0f09c4
--- /dev/null
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -0,0 +1,997 @@
+/*
+ * 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>
+#include <folly/Math.h>
+#pragma GCC diagnostic pop
+
+#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/CountMinSketch.h"
+#include "cachelib/common/Mutex.h"
+
+namespace facebook::cachelib {
+// Implements the S3-FIFO cache eviction policy as described in
+class MMS3FIFO {
+ public:
+  // unique identifier per MMType
+  static const int kId;
+
+  // forward declaration;
+  template <typename T>
+  using Hook = DListHook<T>;
+  using SerializationType = serialization::MMS3FIFOObject;
+  using SerializationConfigType = serialization::MMS3FIFOConfig;
+  using SerializationTypeContainer = serialization::MMS3FIFOCollection;
+
+  enum LruType { Main, Tiny, NumTypes };
+
+  // Config class for MMS3FIFO
+  struct Config {
+    // create from serialized config
+    explicit Config(SerializationConfigType configState)
+        : Config(*configState.lruRefreshTime(),
+                 *configState.lruRefreshRatio(),
+                 *configState.updateOnWrite(),
+                 *configState.updateOnRead(),
+                 *configState.tryLockUpdate(),
+                 *configState.windowToCacheSizeRatio(),
+                 *configState.tinySizePercent(),
+                 *configState.mmReconfigureIntervalSecs(),
+                 *configState.newcomerWinsOnTie()) {}
+
+    // @param time        the LRU refresh time in seconds.
+    //                    An item will be promoted only once in each lru refresh
+    //                    time depite the number of accesses it gets.
+    // @param udpateOnW   whether to promote the item on write
+    // @param updateOnR   whether to promote the item on read
+    Config(uint32_t time, bool updateOnW, bool updateOnR)
+        : Config(time,
+                 updateOnW,
+                 updateOnR,
+                 /* try lock update */ false,
+                 16,
+                 1) {}
+
+    // @param time              the LRU refresh time in seconds.
+    //                          An item will be promoted only once in each lru
+    //                          refresh time depite the number of accesses it
+    //                          gets.
+    // @param udpateOnW         whether to promote the item on write
+    // @param updateOnR         whether to promote the item on read
+    // @param windowToCacheSize multiplier of window size to cache size
+    // @param tinySizePct       percentage number of tiny size to overall size
+    Config(uint32_t time,
+           bool updateOnW,
+           bool updateOnR,
+           size_t windowToCacheSize,
+           size_t tinySizePct)
+        : Config(time,
+                 updateOnW,
+                 updateOnR,
+                 /* try lock update */ false,
+                 windowToCacheSize,
+                 tinySizePct) {}
+
+    // @param time              the LRU refresh time in seconds.
+    //                          An item will be promoted only once in each lru
+    //                          refresh time depite the number of accesses it
+    //                          gets.
+    // @param udpateOnW         whether to promote the item on write
+    // @param updateOnR         whether to promote the item on read
+    // @param tryLockU          whether to use a try lock when doing update.
+    // @param windowToCacheSize multiplier of window size to cache size
+    // @param tinySizePct       percentage number of tiny size to overall size
+    Config(uint32_t time,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t windowToCacheSize,
+           size_t tinySizePct)
+        : Config(time,
+                 0.,
+                 updateOnW,
+                 updateOnR,
+                 tryLockU,
+                 windowToCacheSize,
+                 tinySizePct) {}
+
+    // @param time                    the LRU refresh time in seconds.
+    //                                An item will be promoted only once in each
+    //                                lru refresh time depite the number of
+    //                                accesses it gets.
+    // @param ratio                   the lru refresh ratio. The ratio times the
+    //                                oldest element's lifetime in warm queue
+    //                                would be the minimum value of LRU refresh
+    //                                time.
+    // @param udpateOnW               whether to promote the item on write
+    // @param updateOnR               whether to promote the item on read
+    // @param tryLockU                whether to use a try lock when doing
+    //                                update.
+    // @param windowToCacheSize       multiplier of window size to cache size
+    // @param tinySizePct             percentage number of tiny size to overall
+    //                                size
+    Config(uint32_t time,
+           double ratio,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t windowToCacheSize,
+           size_t tinySizePct)
+        : Config(time,
+                 ratio,
+                 updateOnW,
+                 updateOnR,
+                 tryLockU,
+                 windowToCacheSize,
+                 tinySizePct,
+                 0) {}
+
+    // @param time                    the LRU refresh time in seconds.
+    //                                An item will be promoted only once in each
+    //                                lru refresh time depite the number of
+    //                                accesses it gets.
+    // @param ratio                   the lru refresh ratio. The ratio times the
+    //                                oldest element's lifetime in warm queue
+    //                                would be the minimum value of LRU refresh
+    //                                time.
+    // @param udpateOnW               whether to promote the item on write
+    // @param updateOnR               whether to promote the item on read
+    // @param tryLockU                whether to use a try lock when doing
+    //                                update.
+    // @param windowToCacheSize       multiplier of window size to cache size
+    // @param tinySizePct             percentage number of tiny size to overall
+    //                                size
+    // @param mmReconfigureInterval   Time interval for recalculating lru
+    //                                refresh time according to the ratio.
+    Config(uint32_t time,
+           double ratio,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t windowToCacheSize,
+           size_t tinySizePct,
+           uint32_t mmReconfigureInterval)
+        : defaultLruRefreshTime(time),
+          lruRefreshRatio(ratio),
+          updateOnWrite(updateOnW),
+          updateOnRead(updateOnR),
+          tryLockUpdate(tryLockU),
+          windowToCacheSizeRatio(windowToCacheSize),
+          tinySizePercent(tinySizePct),
+          mmReconfigureIntervalSecs(
+              std::chrono::seconds(mmReconfigureInterval)) {
+      checkConfig();
+    }
+
+    // @param time                    the LRU refresh time in seconds.
+    //                                An item will be promoted only once in each
+    //                                lru refresh time depite the number of
+    //                                accesses it gets.
+    // @param ratio                   the lru refresh ratio. The ratio times the
+    //                                oldest element's lifetime in warm queue
+    //                                would be the minimum value of LRU refresh
+    //                                time.
+    // @param udpateOnW               whether to promote the item on write
+    // @param updateOnR               whether to promote the item on read
+    // @param tryLockU                whether to use a try lock when doing
+    //                                update.
+    // @param windowToCacheSize       multiplier of window size to cache size
+    // @param tinySizePct             percentage number of tiny size to overall
+    //                                size
+    // @param mmReconfigureInterval   Time interval for recalculating lru
+    //                                refresh time according to the ratio.
+    // @param newcomerWinsOnTie       If true, new comer will replace existing
+    //                                item if their access frequencies tie.
+    Config(uint32_t time,
+           double ratio,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t windowToCacheSize,
+           size_t tinySizePct,
+           uint32_t mmReconfigureInterval,
+           bool _newcomerWinsOnTie)
+        : defaultLruRefreshTime(time),
+          lruRefreshRatio(ratio),
+          updateOnWrite(updateOnW),
+          updateOnRead(updateOnR),
+          tryLockUpdate(tryLockU),
+          windowToCacheSizeRatio(windowToCacheSize),
+          tinySizePercent(tinySizePct),
+          mmReconfigureIntervalSecs(
+              std::chrono::seconds(mmReconfigureInterval)),
+          newcomerWinsOnTie(_newcomerWinsOnTie) {
+      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 (tinySizePercent < 1 || tinySizePercent > 50) {
+        throw std::invalid_argument(
+            folly::sformat("Invalid tiny cache size {}. Tiny cache size "
+                           "must be between 1% and 50% of total cache size ",
+                           tinySizePercent));
+      }
+      if (windowToCacheSizeRatio < 2 || windowToCacheSizeRatio > 128) {
+        throw std::invalid_argument(
+            folly::sformat("Invalid window to cache size ratio {}. The ratio "
+                           "must be between 2 and 128",
+                           windowToCacheSizeRatio));
+      }
+    }
+
+    template <typename... Args>
+    void addExtraConfig(Args...) {}
+
+    // threshold value in seconds to compare with a node's update time to
+    // determine if we need to update the position of the node in the linked
+    // list. By default this is 60s to reduce the contention on the lru lock.
+    uint32_t defaultLruRefreshTime{60};
+    uint32_t lruRefreshTime{defaultLruRefreshTime};
+
+    // ratio of LRU refresh time to the tail age. If a refresh time computed
+    // according to this ratio is larger than lruRefreshtime, we will adopt
+    // this one instead of the lruRefreshTime set.
+    double lruRefreshRatio{0.};
+
+    // whether the lru needs to be updated on writes for recordAccess. If
+    // false, accessing the cache for writes does not promote the cached item
+    // to the head of the lru.
+    bool updateOnWrite{false};
+
+    // whether the lru needs to be updated on reads for recordAccess. If
+    // false, accessing the cache for reads does not promote the cached item
+    // to the head of the lru.
+    bool updateOnRead{true};
+
+    // whether to tryLock or lock the lru lock when attempting promotion on
+    // access. If set, and tryLock fails, access will not result in promotion.
+    bool tryLockUpdate{false};
+
+    // The multiplier for window size given the cache size.
+    size_t windowToCacheSizeRatio{32};
+
+    // The size of tiny cache, as a percentage of the total size.
+    size_t tinySizePercent{10};
+
+    // Minimum interval between reconfigurations. If 0, reconfigure is never
+    // called.
+    std::chrono::seconds mmReconfigureIntervalSecs{};
+
+    // If true, then if an item in the tail of the Tiny queue ties with the
+    // item in the tail of the main queue, the item from Tiny (newcomer) will
+    // replace the item from Main. This is fine for a default, but for
+    // strictly scan patterns (access a key exactly once and move on), this
+    // is not a desirable behavior (we'll always cache miss).
+    bool newcomerWinsOnTie{true};
+  };
+
+  // The container object which can be used to keep track of objects of type
+  // T. T must have a public member of type Hook. This object is wrapper
+  // around DList, is thread safe and can be accessed from multiple threads.
+  // The current implementation models an LRU using the above DList
+  // implementation.
+  template <typename T, Hook<T> T::* HookPtr>
+  struct Container {
+   private:
+    using LruList = MultiDList<T, HookPtr>;
+    using Mutex = folly::SpinLock;
+    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)) {
+      maybeGrowGhostLocked();
+      lruRefreshTime_ = config_.lruRefreshTime;
+      nextReconfigureTime_ =
+          config_.mmReconfigureIntervalSecs.count() == 0
+              ? std::numeric_limits<Time>::max()
+              : static_cast<Time>(util::getCurrentTimeSec()) +
+                    config_.mmReconfigureIntervalSecs.count();
+    }
+    Container(serialization::MMS3FIFOObject object, PtrCompressor compressor);
+
+    Container(const Container&) = delete;
+    Container& operator=(const Container&) = delete;
+
+    // records the information that the node was accessed. This could bump up
+    // the node to the head of the lru depending on the time when the node was
+    // last updated in lru and the kLruRefreshTime. If the node was moved to
+    // the head in the lru, the node's updateTime will be updated
+    // accordingly.
+    //
+    // @param node  node that we want to mark as relevant/accessed
+    // @param mode  the mode for the access operation.
+    //
+    // @return      True if the information is recorded and bumped the node
+    //              to the head of the lru, returns false otherwise
+    bool recordAccess(T& node, AccessMode mode) noexcept;
+
+    // adds the given node into the container and marks it as being present in
+    // the container. The node is added to the head of the lru.
+    //
+    // @param node  The node to be added to the container.
+    // @return  True if the node was successfully added to the container. False
+    //          if the node was already in the contianer. On error state of node
+    //          is unchanged.
+    bool add(T& node) noexcept;
+
+    // removes the node from the lru and sets it previous and next to nullptr.
+    //
+    // @param node  The node to be removed from the container.
+    // @return  True if the node was successfully removed from the container.
+    //          False if the node was not part of the container. On error, the
+    //          state of node is unchanged.
+    bool remove(T& node) noexcept;
+
+    class LockedIterator;
+    // same as the above but uses an iterator context. The iterator is updated
+    // on removal of the corresponding node to point to the next node. The
+    // iterator context holds the lock on the lru.
+    //
+    // iterator will be advanced to the next node after removing the node
+    //
+    // @param it    Iterator that will be removed
+    void remove(LockedIterator& it) noexcept;
+
+    // replaces one node with another, at the same position
+    //
+    // @param oldNode   node being replaced
+    // @param newNode   node to replace oldNode with
+    //
+    // @return true  If the replace was successful. Returns false if the
+    //               destination node did not exist in the container, or if the
+    //               source node already existed.
+    bool replace(T& oldNode, T& newNode) noexcept;
+
+    // context for iterating the MM container. At any given point of time,
+    // there can be only one iterator active since we need to lock the LRU for
+    // iteration. we can support multiple iterators at same time, by using a
+    // shared ptr in the context for the lock holder in the future.
+    class LockedIterator {
+     public:
+      using ListIterator = typename LruList::DListIterator;
+      // noncopyable but movable.
+      LockedIterator(const LockedIterator&) = delete;
+      LockedIterator& operator=(const LockedIterator&) = delete;
+      LockedIterator(LockedIterator&&) noexcept = default;
+
+      // Todo: Advance the iterator without calling getIter since getIter mutates
+      LockedIterator& operator++() noexcept {
+        ++getIter();
+        return *this;
+      }
+
+      LockedIterator& operator--() {
+        throw std::invalid_argument(
+            "Decrementing eviction iterator is not supported");
+      }
+
+      T* operator->() const noexcept { return getIter().operator->(); }
+      T& operator*() const noexcept { return getIter().operator*(); }
+
+      bool operator==(const LockedIterator& other) const noexcept {
+        return &c_ == &other.c_ && tIter_ == other.tIter_ &&
+               mIter_ == other.mIter_;
+      }
+
+      bool operator!=(const LockedIterator& other) const noexcept {
+        return !(*this == other);
+      }
+
+      explicit operator bool() const noexcept { return tIter_ || mIter_; }
+
+      T* get() const noexcept { return getIter().get(); }
+
+      // Invalidates this iterator
+      void reset() noexcept {
+        // Point iterator to first list's rend
+        tIter_.reset();
+        mIter_.reset();
+      }
+
+      // 1. Invalidate this iterator
+      // 2. Unlock
+      void destroy() {
+        reset();
+        if (l_.owns_lock()) {
+          l_.unlock();
+        }
+      }
+
+      // Reset this iterator to the beginning
+      void resetToBegin() {
+        if (!l_.owns_lock()) {
+          l_.lock();
+        }
+        tIter_.resetToBegin();
+        mIter_.resetToBegin();
+      }
+
+     private:
+      // private because it's easy to misuse and cause deadlock for MMS3FIFO
+      LockedIterator& operator=(LockedIterator&&) noexcept = default;
+
+      // create an lru iterator with the lock being held.
+      explicit LockedIterator(LockHolder l,
+                              const Container<T, HookPtr>& c) noexcept;
+
+      ListIterator& getIter() noexcept {
+        return const_cast<ListIterator&>(
+            static_cast<const LockedIterator*>(this)->getIter());
+      }
+
+      bool shouldEvictSmall() const noexcept {
+        int smallSize = static_cast<int>(c_.lru_.getList(LruType::Tiny).size());
+        int mainSize = static_cast<int>(c_.lru_.getList(LruType::Main).size());
+
+        if (smallSize == 0) {
+          return false;
+        }
+        if (mainSize == 0) {
+          return true;
+        }
+
+        const size_t total = smallSize + mainSize;
+        const size_t targetTiny =
+            static_cast<size_t>(c_.config_.tinySizePercent * c_.lru_.size() / 100);
+        // If tiny is at or above its target share, start evicting from tiny
+        return smallSize >= targetTiny;
+      }
+
+      // Todo: Now it may advance the iterators to skip items that need promotion.
+      // Is there a better way?
+      const ListIterator& getIter() const noexcept {
+        auto& tinyLru = c_.lru_.getList(LruType::Tiny);
+        auto& mainLru = c_.lru_.getList(LruType::Main);
+
+        while (true) {
+          bool tryTiny = shouldEvictSmall();
+          ListIterator activeIter = tryTiny ? tIter_ : mIter_;
+
+          if (!activeIter) {
+            // both exhausted, just return any
+            return activeIter;
+          }
+
+          if (tryTiny) {
+            // -------- evictS semantics ----------
+            // evictS:
+            //   while S not empty:
+            //     t = tail(S)
+            //     if t.freq accessed: move t to M, reset bit
+            //     else: eviction candidate
+            //
+            // Here we just choose the victim and do the promotion if needed.
+            // the actual removal from S or M is done in Container::remove(it).
+            // Remove() will insert into ghost
+
+            T& node = *activeIter;
+            if (Container<T, HookPtr>::isAccessed(node)) {
+              ++activeIter;
+              // promote to main cache
+              tinyLru.remove(node);
+              mainLru.linkAtHead(node);
+              Container<T, HookPtr>::unmarkTiny(node);
+              Container<T, HookPtr>::unmarkAccessed(node);
+              continue;
+            }
+            return activeIter;
+
+          } else {
+            // -------- evictM semantics ----------
+            // evictM:
+            //   while M not empty:
+            //     t = tail(M)
+            //     if t.freq > 0: move t to head(M), unset accessed bit.
+            //     else: evict
+            T& node = *activeIter;
+            if (Container<T, HookPtr>::isAccessed(node)) {
+              // Reinsert to head
+              ++activeIter;             // move iterator first
+              mainLru.moveToHead(node); // move t to head
+              Container<T, HookPtr>::unmarkAccessed(node);
+              continue;
+            }
+            return activeIter;
+          }
+        }
+      }
+
+      // only the container can create iterators
+      friend Container<T, HookPtr>;
+
+      const Container<T, HookPtr>& c_;
+      // Tiny and main cache iterators
+      ListIterator tIter_;
+      ListIterator mIter_;
+      // lock protecting the validity of the iterator
+      LockHolder l_;
+    };
+
+    Config getConfig() const;
+
+    void setConfig(const Config& newConfig);
+
+    bool isEmpty() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size() == 0;
+    }
+
+    size_t size() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size();
+    }
+
+    // TODO: Hash table for ghost queue
+    size_t counterSize() const noexcept {
+      LockHolder l(lruMutex_);
+      return accessFreq_.getByteSize();
+    }
+
+    // Returns the eviction age stats. See CacheStats.h for details
+    EvictionAgeStat getEvictionAgeStat(uint64_t projectedLength) const noexcept;
+
+    // Obtain an iterator that start from the tail and can be used
+    // to search for evictions. This iterator holds a lock to this
+    // container and only one such iterator can exist at a time
+    LockedIterator getEvictionIterator() const noexcept;
+
+    // Execute provided function under container lock. Function gets
+    // iterator passed as parameter.
+    template <typename F>
+    void withEvictionIterator(F&& f);
+
+    // Execute provided function under container lock.
+    template <typename F>
+    void withContainerLock(F&& f);
+
+    // for saving the state of the lru
+    //
+    // precondition:  serialization must happen without any reader or writer
+    // present. Any modification of this object afterwards will result in an
+    // invalid, inconsistent state for the serialized data.
+    //
+    serialization::MMS3FIFOObject saveState() const noexcept;
+
+    // return the stats for this container.
+    MMContainerStat getStats() const noexcept;
+
+    static LruType getLruType(const T& node) noexcept {
+      return isTiny(node) ? LruType::Tiny : 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);
+    }
+
+    // As the cache grows, the frequency counters may need to grow.
+    // Todo: Grow with hash table
+    void maybeGrowGhostLocked() noexcept;
+
+    // Returns the hash of node's key
+    static size_t hashNode(const T& node) noexcept {
+      return folly::hasher<folly::StringPiece>()(node.getKey());
+    }
+
+    // remove node from lru and adjust insertion points
+    //
+    // @param node          node to remove
+    void removeLocked(T& node) noexcept;
+
+    static bool isTiny(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag0>();
+    }
+
+    static bool isAccessed(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag1>();
+    }
+
+    // Bit MM_BIT_0 is used to record if the item is in tiny cache.
+    static void markTiny(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag0>();
+    }
+    static void unmarkTiny(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag0>();
+    }
+
+    // Bit MM_BIT_1 is used to record if the item has been accessed since being
+    // written in cache. Unaccessed items are ignored when determining projected
+    // update time.
+    static void markAccessed(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag1>();
+    }
+    static void unmarkAccessed(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag1>();
+    }
+
+    bool hashContains(const T& node) const noexcept {
+      // Mock implementation
+      // random return t or false
+      return (hashNode(node) % 2) == 0;
+    }
+
+    bool hashInsert(const T& node) noexcept {
+      // Mock implementation
+      return true;
+    }
+
+    // Initial cache capacity estimate for count-min-sketch
+    static constexpr size_t kDefaultCapacity = 100;
+
+    // Number of hashes
+    static constexpr size_t kHashCount = 4;
+
+    // The error threshold for frequency calculation
+    static constexpr size_t kErrorThreshold = 5;
+
+    // decay rate for frequency
+    static constexpr double kDecayFactor = 0.5;
+
+    // protects all operations on the lru. We never really just read the state
+    // of the LRU. Hence we dont really require a RW mutex at this point of
+    // time.
+    mutable Mutex lruMutex_;
+
+    // the lru
+    LruList lru_;
+
+    // the window size counter
+    size_t windowSize_{0};
+
+    // maximum value of window size which when hit the counters are halved
+    size_t maxWindowSize_{0};
+
+    // The capacity for which the counters are sized
+    size_t capacity_{0};
+
+    // The next time to reconfigure the container.
+    std::atomic<Time> nextReconfigureTime_{};
+
+    // How often to promote an item in the eviction queue.
+    std::atomic<uint32_t> lruRefreshTime_{};
+
+    // Max lruFreshTime.
+    static constexpr uint32_t kLruRefreshTimeCap{900};
+
+    // Config for this lru.
+    // Write access to the MMS3FIFO Config is serialized.
+    // Reads may be racy.
+    Config config_{};
+
+    // Approximate streaming frequency counters. The counts are halved every
+    // time the maxWindowSize is hit.
+    facebook::cachelib::util::CountMinSketch accessFreq_{};
+
+    // // Todo: Test?
+    // FRIEND_TEST(MMS3FIFOTest, SegmentStress);
+    // FRIEND_TEST(MMS3FIFOTest, TinyLFUBasic);
+    // FRIEND_TEST(MMS3FIFOTest, Reconfigure);
+  };
+};
+
+/* 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()) {
+  lruRefreshTime_ = config_.lruRefreshTime;
+  nextReconfigureTime_ = config_.mmReconfigureIntervalSecs.count() == 0
+                             ? std::numeric_limits<Time>::max()
+                             : static_cast<Time>(util::getCurrentTimeSec()) +
+                                   config_.mmReconfigureIntervalSecs.count();
+  maybeGrowGhostLocked();
+}
+
+// Todo: initialize hash table
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::maybeGrowGhostLocked() noexcept {
+  size_t capacity = lru_.size();
+  // If the new capacity ask is more than double the current size, recreate
+  // the approx frequency counters.
+  if (2 * capacity_ > capacity) {
+    return;
+  }
+  // Todo: ghost growing not implemented
+  printf("MMS3FIFO::Container::maybeGrowGhostLocked not implemented\n");
+}
+
+// We have no notion of "reconfiguring lock"
+// or refresh interval since we are not manipulating the list lru on access.
+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());
+  LockHolder l(lruMutex_);
+  // check if the node is still being memory managed
+  // No need refreshing since we are treating the list as a FIFO queue.
+  if (node.isInMMContainer() && !isAccessed(node)) {
+    if (!isAccessed(node)) {
+      markAccessed(node);
+    }
+    setUpdateTime(node, curr);
+    return true;
+  }
+  return false;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+cachelib::EvictionAgeStat MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStat(
+    uint64_t projectedLength) const noexcept {
+  LockHolder l(lruMutex_);
+  return getEvictionAgeStatLocked(projectedLength);
+}
+
+// We have 2 options:
+// 1. Use the tail to get eviction age -> Tail can be popular item
+// 2. Use the first unaccessed item from tail -> Tail is more accurate for age
+// estimation Currently we get the Nth unaccessed item from tail. This function
+// is used for:
+// - Filtering out slab candidates during slab release (projectedLength = 0),
+// actual age is used
+// - Estimating projected eviction age for lrutailage strategy, where
+// projectedLength > 0 We only implement up to 0 case for now. LRUTailAge should
+// not be used in MMS3FIFO.
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+cachelib::EvictionAgeStat
+MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStatLocked(
+    uint64_t projectedLength) const noexcept {
+  if (projectedLength != 0) {
+    throw std::invalid_argument(
+        "Projected eviction age estimation is not supported in MMS3FIFO");
+  }
+
+  EvictionAgeStat stat;
+  const auto curr = static_cast<Time>(util::getCurrentTimeSec());
+
+  auto& list = lru_.getList(LruType::Main);
+  auto it = list.rbegin();
+
+  // Check if accessed. If so, advance the iterator.
+  while (it != list.rend() && isAccessed(*it)) {
+    ++it;
+  }
+  stat.warmQueueStat.oldestElementAge =
+      it != list.rend() ? curr - getUpdateTime(*it) : 0;
+
+  stat.warmQueueStat.size = list.size();
+
+  return stat;
+}
+
+// Todo: Check whether item exist in ghost queue.
+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());
+  LockHolder l(lruMutex_);
+  if (node.isInMMContainer()) {
+    return false;
+  }
+
+  if (hashContains(node)) {
+    // Insert to main queue
+    auto& mainLru = lru_.getList(LruType::Main);
+    mainLru.linkAtHead(node);
+  } else {
+    // Insert to tiny queue
+    auto& tinyLru = lru_.getList(LruType::Tiny);
+    tinyLru.linkAtHead(node);
+    markTiny(node);
+  }
+
+  maybeGrowGhostLocked();
+
+  node.markInMMContainer();
+  setUpdateTime(node, currTime);
+  unmarkAccessed(node);
+
+  // Always link to probationary queue. Eviction logic will
+  // decide / promote as needed.
+
+  // const auto expectedSize = config_.tinySizePercent * lru_.size() / 100;
+  // if (lru_.getList(LruType::Tiny).size() > expectedSize) {
+  //   auto tailNode = tinyLru.getTail();
+  //   tinyLru.remove(*tailNode);
+
+  //   auto& mainLru = lru_.getList(LruType::Main);
+  //   mainLru.linkAtHead(*tailNode);
+  //   unmarkTiny(*tailNode);
+
+  // Maybe rehash here.
+  return true;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+typename MMS3FIFO::Container<T, HookPtr>::LockedIterator
+MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() const noexcept {
+  LockHolder l(lruMutex_);
+  return LockedIterator{std::move(l), *this};
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+template <typename F>
+void MMS3FIFO::Container<T, HookPtr>::withEvictionIterator(F&& fun) {
+  // Uses spinlock, can't use combined locking
+  fun(getEvictionIterator());
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+template <typename F>
+void MMS3FIFO::Container<T, HookPtr>::withContainerLock(F&& fun) {
+  LockHolder l(lruMutex_);
+  fun();
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::removeLocked(T& node) noexcept {
+  if (isTiny(node)) {
+    lru_.getList(LruType::Tiny).remove(node);
+    unmarkTiny(node);
+    // Insert to hash upon removal
+    hashInsert(node);
+  } else {
+    lru_.getList(LruType::Main).remove(node);
+  }
+
+  unmarkAccessed(node);
+  node.unmarkInMMContainer();
+  return;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+bool MMS3FIFO::Container<T, HookPtr>::remove(T& node) noexcept {
+  LockHolder l(lruMutex_);
+  if (!node.isInMMContainer()) {
+    return false;
+  }
+  removeLocked(node);
+  return true;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::remove(LockedIterator& 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 {
+  LockHolder l(lruMutex_);
+  if (!oldNode.isInMMContainer() || newNode.isInMMContainer()) {
+    return false;
+  }
+  const auto updateTime = getUpdateTime(oldNode);
+
+  if (isTiny(oldNode)) {
+    lru_.getList(LruType::Tiny).replace(oldNode, newNode);
+    unmarkTiny(oldNode);
+    markTiny(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;
+}
+
+// Todo: all the configs, states
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+typename MMS3FIFO::Config MMS3FIFO::Container<T, HookPtr>::getConfig() const {
+  LockHolder l(lruMutex_);
+  return config_;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::setConfig(const Config& c) {
+  LockHolder l(lruMutex_);
+  config_ = c;
+  lruRefreshTime_.store(config_.lruRefreshTime, std::memory_order_relaxed);
+  nextReconfigureTime_ = config_.mmReconfigureIntervalSecs.count() == 0
+                             ? std::numeric_limits<Time>::max()
+                             : static_cast<Time>(util::getCurrentTimeSec()) +
+                                   config_.mmReconfigureIntervalSecs.count();
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+serialization::MMS3FIFOObject MMS3FIFO::Container<T, HookPtr>::saveState()
+    const noexcept {
+  serialization::MMS3FIFOConfig configObject;
+  *configObject.lruRefreshTime() =
+      lruRefreshTime_.load(std::memory_order_relaxed);
+  *configObject.lruRefreshRatio() = config_.lruRefreshRatio;
+  *configObject.updateOnWrite() = config_.updateOnWrite;
+  *configObject.updateOnRead() = config_.updateOnRead;
+  *configObject.windowToCacheSizeRatio() = config_.windowToCacheSizeRatio;
+  *configObject.tinySizePercent() = config_.tinySizePercent;
+  *configObject.mmReconfigureIntervalSecs() =
+      config_.mmReconfigureIntervalSecs.count();
+  *configObject.newcomerWinsOnTie() = config_.newcomerWinsOnTie;
+  // TODO: Serialize with ghost queue too.
+  // Right now serialization / save state is incomplete.
+
+  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 {
+  LockHolder l(lruMutex_);
+
+  auto evictionAge = getEvictionAgeStatLocked(0).warmQueueStat.oldestElementAge;
+
+  return {
+      lru_.size(),
+      evictionAge, // Approximation of tail age from first unaccesessed items
+      0, // We have no notion of refresh time, accesses only toggle access bit
+      0,           0, 0, 0};
+}
+
+// Locked Iterator Context Implementation
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+MMS3FIFO::Container<T, HookPtr>::LockedIterator::LockedIterator(
+    LockHolder l, const Container<T, HookPtr>& c) noexcept
+    : c_(c),
+      tIter_(c.lru_.getList(LruType::Tiny).rbegin()),
+      mIter_(c.lru_.getList(LruType::Main).rbegin()),
+      l_(std::move(l)) {}
+} // namespace facebook::cachelib
diff --git a/cachelib/allocator/serialize/objects.thrift b/cachelib/allocator/serialize/objects.thrift
index 15d47bd2fc..0d4a4fc3b1 100644
--- a/cachelib/allocator/serialize/objects.thrift
+++ b/cachelib/allocator/serialize/objects.thrift
@@ -109,6 +109,37 @@ struct MM2QCollection {
   1: required map<i32, map<i32, MM2QObject>> pools;
 }
 
+
+
+struct MMS3FIFOConfig {
+  1: required i32 lruRefreshTime;
+  2: required bool updateOnWrite;
+  3: required i32 windowToCacheSizeRatio;
+  4: required i32 tinySizePercent;
+  5: bool updateOnRead = true;
+  6: bool tryLockUpdate = false;
+  7: double lruRefreshRatio = 0.0;
+  8: i32 mmReconfigureIntervalSecs = 0;
+  9: bool newcomerWinsOnTie = true;
+  10: i32 protectionFreq_ = 3;
+  11: i32 protectionSegmentSizePct = 80;
+}
+
+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;

From f4d553a125c718c853679458666089b4339bdc09 Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Thu, 20 Nov 2025 10:15:16 +0000
Subject: [PATCH 02/15] add ghostqueue

---
 cachelib/allocator/MMS3FIFO.h | 297 +++++++++++++++++++++-------------
 1 file changed, 181 insertions(+), 116 deletions(-)

diff --git a/cachelib/allocator/MMS3FIFO.h b/cachelib/allocator/MMS3FIFO.h
index 093f0f09c4..c472b1beaa 100644
--- a/cachelib/allocator/MMS3FIFO.h
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -35,6 +35,52 @@
 
 namespace facebook::cachelib {
 // Implements the S3-FIFO cache eviction policy as described in
+
+#pragma once
+#include <cstdint>
+#include <deque>
+#include <unordered_set>
+
+class GhostQueue {
+ public:
+  explicit GhostQueue(size_t capacity) : maxSize_(capacity) {}
+
+  bool contains(uint32_t key) const { return set_.find(key) != set_.end(); }
+
+  void insert(uint32_t key) {
+    if (set_.count(key) > 0) {
+      return;
+    }
+
+    fifo_.push_back(key);
+    set_.insert(key);
+
+    enforceCapacity();
+  }
+
+  void resize(size_t newSize) {
+    maxSize_ = newSize;
+    enforceCapacity();
+  }
+
+  size_t size() const { return set_.size(); }
+
+ private:
+  void enforceCapacity() {
+    while (fifo_.size() > maxSize_) {
+      uint32_t k = fifo_.front();
+      fifo_.pop_front();
+      set_.erase(k);
+    }
+  }
+
+ private:
+  size_t maxSize_;
+  std::deque<uint32_t> fifo_;
+  std::unordered_set<uint32_t> set_;
+};
+
+
 class MMS3FIFO {
  public:
   // unique identifier per MMType
@@ -74,7 +120,7 @@ class MMS3FIFO {
                  updateOnR,
                  /* try lock update */ false,
                  16,
-                 1) {}
+                 10) {}
 
     // @param time              the LRU refresh time in seconds.
     //                          An item will be promoted only once in each lru
@@ -317,7 +363,6 @@ class MMS3FIFO {
     Container(Config c, PtrCompressor compressor)
         : lru_(LruType::NumTypes, std::move(compressor)),
           config_(std::move(c)) {
-      maybeGrowGhostLocked();
       lruRefreshTime_ = config_.lruRefreshTime;
       nextReconfigureTime_ =
           config_.mmReconfigureIntervalSecs.count() == 0
@@ -380,10 +425,7 @@ class MMS3FIFO {
     //               source node already existed.
     bool replace(T& oldNode, T& newNode) noexcept;
 
-    // context for iterating the MM container. At any given point of time,
-    // there can be only one iterator active since we need to lock the LRU for
-    // iteration. we can support multiple iterators at same time, by using a
-    // shared ptr in the context for the lock holder in the future.
+
     class LockedIterator {
      public:
       using ListIterator = typename LruList::DListIterator;
@@ -392,12 +434,25 @@ class MMS3FIFO {
       LockedIterator& operator=(const LockedIterator&) = delete;
       LockedIterator(LockedIterator&&) noexcept = default;
 
-      // Todo: Advance the iterator without calling getIter since getIter mutates
       LockedIterator& operator++() noexcept {
-        ++getIter();
+        // Advance the underlying iterator
+        ListIterator& it = ++getIter();
+        // Skip accessed items
+        skipAccessed(it);
         return *this;
       }
 
+      ListIterator& skipAccessed(ListIterator& it) noexcept {
+        while (it) {
+          T& node = *it;
+          if (!Container<T, HookPtr>::isAccessed(node)) {
+            break; // found a valid eviction victim
+          }
+          ++it; // skip this accessed item
+        }
+        return it;
+      }
+
       LockedIterator& operator--() {
         throw std::invalid_argument(
             "Decrementing eviction iterator is not supported");
@@ -445,93 +500,38 @@ class MMS3FIFO {
       }
 
      private:
-      // private because it's easy to misuse and cause deadlock for MMS3FIFO
+      // private because it's easy to misuse and cause deadlock for MMTinyLFU
       LockedIterator& operator=(LockedIterator&&) noexcept = default;
 
       // create an lru iterator with the lock being held.
-      explicit LockedIterator(LockHolder l,
-                              const Container<T, HookPtr>& c) noexcept;
+      explicit LockedIterator(LockHolder l, const Container<T, HookPtr>& c) noexcept;
+
+      const ListIterator& getIter() const noexcept {
+        auto shouldEvictTiny = evictTiny();
+
+        return shouldEvictTiny ? tIter_ : mIter_;
+      }
 
       ListIterator& getIter() noexcept {
         return const_cast<ListIterator&>(
             static_cast<const LockedIterator*>(this)->getIter());
       }
 
-      bool shouldEvictSmall() const noexcept {
-        int smallSize = static_cast<int>(c_.lru_.getList(LruType::Tiny).size());
-        int mainSize = static_cast<int>(c_.lru_.getList(LruType::Main).size());
-
-        if (smallSize == 0) {
-          return false;
-        }
-        if (mainSize == 0) {
+      // Todo: can probably cache the evicttiny call
+      // Will switch when iter is exhausted.
+      bool evictTiny() const noexcept {
+        if (!mIter_) {
           return true;
         }
+        if (!tIter_) {
+          return false;
+        }
 
-        const size_t total = smallSize + mainSize;
-        const size_t targetTiny =
-            static_cast<size_t>(c_.config_.tinySizePercent * c_.lru_.size() / 100);
-        // If tiny is at or above its target share, start evicting from tiny
-        return smallSize >= targetTiny;
-      }
-
-      // Todo: Now it may advance the iterators to skip items that need promotion.
-      // Is there a better way?
-      const ListIterator& getIter() const noexcept {
-        auto& tinyLru = c_.lru_.getList(LruType::Tiny);
-        auto& mainLru = c_.lru_.getList(LruType::Main);
-
-        while (true) {
-          bool tryTiny = shouldEvictSmall();
-          ListIterator activeIter = tryTiny ? tIter_ : mIter_;
-
-          if (!activeIter) {
-            // both exhausted, just return any
-            return activeIter;
-          }
+        int smallSize = static_cast<int>(c_.lru_.getList(LruType::Tiny).size());
 
-          if (tryTiny) {
-            // -------- evictS semantics ----------
-            // evictS:
-            //   while S not empty:
-            //     t = tail(S)
-            //     if t.freq accessed: move t to M, reset bit
-            //     else: eviction candidate
-            //
-            // Here we just choose the victim and do the promotion if needed.
-            // the actual removal from S or M is done in Container::remove(it).
-            // Remove() will insert into ghost
-
-            T& node = *activeIter;
-            if (Container<T, HookPtr>::isAccessed(node)) {
-              ++activeIter;
-              // promote to main cache
-              tinyLru.remove(node);
-              mainLru.linkAtHead(node);
-              Container<T, HookPtr>::unmarkTiny(node);
-              Container<T, HookPtr>::unmarkAccessed(node);
-              continue;
-            }
-            return activeIter;
-
-          } else {
-            // -------- evictM semantics ----------
-            // evictM:
-            //   while M not empty:
-            //     t = tail(M)
-            //     if t.freq > 0: move t to head(M), unset accessed bit.
-            //     else: evict
-            T& node = *activeIter;
-            if (Container<T, HookPtr>::isAccessed(node)) {
-              // Reinsert to head
-              ++activeIter;             // move iterator first
-              mainLru.moveToHead(node); // move t to head
-              Container<T, HookPtr>::unmarkAccessed(node);
-              continue;
-            }
-            return activeIter;
-          }
-        }
+        const size_t targetTiny = static_cast<size_t>(
+            c_.config_.tinySizePercent * c_.lru_.size()/100);
+        return smallSize >= targetTiny;
       }
 
       // only the container can create iterators
@@ -571,7 +571,9 @@ class MMS3FIFO {
     // Obtain an iterator that start from the tail and can be used
     // to search for evictions. This iterator holds a lock to this
     // container and only one such iterator can exist at a time
-    LockedIterator getEvictionIterator() const noexcept;
+    LockedIterator getEvictionIterator() noexcept;
+
+    void rebalanceForEviction();
 
     // Execute provided function under container lock. Function gets
     // iterator passed as parameter.
@@ -596,6 +598,7 @@ class MMS3FIFO {
     static LruType getLruType(const T& node) noexcept {
       return isTiny(node) ? LruType::Tiny : LruType::Main;
     }
+    
 
    private:
     EvictionAgeStat getEvictionAgeStatLocked(
@@ -623,6 +626,10 @@ class MMS3FIFO {
     // @param node          node to remove
     void removeLocked(T& node) noexcept;
 
+    size_t remove_tiny = 0;
+    size_t remove_main = 0;
+
+
     static bool isTiny(const T& node) noexcept {
       return node.template isFlagSet<RefFlags::kMMFlag0>();
     }
@@ -649,17 +656,6 @@ class MMS3FIFO {
       node.template unSetFlag<RefFlags::kMMFlag1>();
     }
 
-    bool hashContains(const T& node) const noexcept {
-      // Mock implementation
-      // random return t or false
-      return (hashNode(node) % 2) == 0;
-    }
-
-    bool hashInsert(const T& node) noexcept {
-      // Mock implementation
-      return true;
-    }
-
     // Initial cache capacity estimate for count-min-sketch
     static constexpr size_t kDefaultCapacity = 100;
 
@@ -680,6 +676,8 @@ class MMS3FIFO {
     // the lru
     LruList lru_;
 
+    GhostQueue ghostQueue_{0};
+
     // the window size counter
     size_t windowSize_{0};
 
@@ -736,8 +734,13 @@ void MMS3FIFO::Container<T, HookPtr>::maybeGrowGhostLocked() noexcept {
   if (2 * capacity_ > capacity) {
     return;
   }
-  // Todo: ghost growing not implemented
-  printf("MMS3FIFO::Container::maybeGrowGhostLocked not implemented\n");
+  
+  // Capacity should be proportion of main queue
+  // Todo config
+  // now size of main queue
+  size_t capacityMain = lru_.getList(LruType::Main).size();
+
+  ghostQueue_.resize(capacityMain);
 }
 
 // We have no notion of "reconfiguring lock"
@@ -785,6 +788,7 @@ template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 cachelib::EvictionAgeStat
 MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStatLocked(
     uint64_t projectedLength) const noexcept {
+  printf("MMS3FIFO::Container::getEvictionAgeStatLocked not implemented\n");
   if (projectedLength != 0) {
     throw std::invalid_argument(
         "Projected eviction age estimation is not supported in MMS3FIFO");
@@ -817,7 +821,7 @@ bool MMS3FIFO::Container<T, HookPtr>::add(T& node) noexcept {
     return false;
   }
 
-  if (hashContains(node)) {
+  if (ghostQueue_.contains(hashNode(node))) {
     // Insert to main queue
     auto& mainLru = lru_.getList(LruType::Main);
     mainLru.linkAtHead(node);
@@ -834,26 +838,85 @@ bool MMS3FIFO::Container<T, HookPtr>::add(T& node) noexcept {
   setUpdateTime(node, currTime);
   unmarkAccessed(node);
 
-  // Always link to probationary queue. Eviction logic will
-  // decide / promote as needed.
+  return true;
+}
 
-  // const auto expectedSize = config_.tinySizePercent * lru_.size() / 100;
-  // if (lru_.getList(LruType::Tiny).size() > expectedSize) {
-  //   auto tailNode = tinyLru.getTail();
-  //   tinyLru.remove(*tailNode);
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::rebalanceForEviction() {
+  auto& tinyLru = lru_.getList(LruType::Tiny);
+  auto& mainLru = lru_.getList(LruType::Main);
 
-  //   auto& mainLru = lru_.getList(LruType::Main);
-  //   mainLru.linkAtHead(*tailNode);
-  //   unmarkTiny(*tailNode);
+  if (tinyLru.size() == 0 && mainLru.size() == 0) {
+    return;
+  }
+  auto totalSize = tinyLru.size() + mainLru.size();
+  // Print the proportions of size
+  if (totalSize % 100 == 0) {
+    auto propTiny =
+        static_cast<double>(tinyLru.size()) / static_cast<double>(totalSize);
+    auto propMain =
+        static_cast<double>(mainLru.size()) / static_cast<double>(totalSize);
+    printf("Tiny size proportion: %.2f %d, Main size proportion: %.2f | %d\n",
+           propTiny,
+            tinyLru.size(),
+           propMain,
+           mainLru.size());
+  }
 
-  // Maybe rehash here.
-  return true;
+  // Run S3-FIFO rules until the current tail (of chosen list)
+  // is an unaccessed victim.
+
+  while (true) {
+    bool tryTiny = (lru_.size() * config_.tinySizePercent /100) < tinyLru.size();
+
+    if (tryTiny) {
+      // Tail of S
+      auto it = tinyLru.rbegin();
+      if (!it) {
+        return;
+      }
+
+      T& node = *it;
+      if (Container<T, HookPtr>::isAccessed(node)) {
+        // accessed tail in S → promote to M head
+        tinyLru.remove(node);
+        mainLru.linkAtHead(node);
+        Container<T, HookPtr>::unmarkTiny(node);
+        Container<T, HookPtr>::unmarkAccessed(node);
+        // sizes changed, loop again
+        continue;
+      } else {
+        // unaccessed tail in S → valid victim, stop rebalancing
+        return;
+      }
+
+    } else {
+      // Tail of M
+      auto it = mainLru.rbegin();
+      if (!it) {
+        return;
+      }
+
+      T& node = *it;
+      if (Container<T, HookPtr>::isAccessed(node)) {
+        // accessed tail in M → move to head(M), clear bit
+        mainLru.moveToHead(node);
+        Container<T, HookPtr>::unmarkAccessed(node);
+        // try again with new tail
+        continue;
+      } else {
+        // unaccessed tail in M → victim
+        return;
+      }
+    }
+  }
 }
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 typename MMS3FIFO::Container<T, HookPtr>::LockedIterator
-MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() const noexcept {
+MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() noexcept {
   LockHolder l(lruMutex_);
+  rebalanceForEviction();
   return LockedIterator{std::move(l), *this};
 }
 
@@ -877,7 +940,7 @@ void MMS3FIFO::Container<T, HookPtr>::removeLocked(T& node) noexcept {
     lru_.getList(LruType::Tiny).remove(node);
     unmarkTiny(node);
     // Insert to hash upon removal
-    hashInsert(node);
+    ghostQueue_.insert(hashNode(node));
   } else {
     lru_.getList(LruType::Main).remove(node);
   }
@@ -977,13 +1040,15 @@ template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 MMContainerStat MMS3FIFO::Container<T, HookPtr>::getStats() const noexcept {
   LockHolder l(lruMutex_);
 
-  auto evictionAge = getEvictionAgeStatLocked(0).warmQueueStat.oldestElementAge;
+  // auto evictionAge = getEvictionAgeStatLocked(0).warmQueueStat.oldestElementAge;
 
-  return {
-      lru_.size(),
-      evictionAge, // Approximation of tail age from first unaccesessed items
-      0, // We have no notion of refresh time, accesses only toggle access bit
-      0,           0, 0, 0};
+  return {lru_.size(),
+          0, // Approximation of tail age from first unaccesessed items
+          0, // We have no notion of refresh time, accesses only toggle access bit
+          0,           
+          0, 
+          0, 
+          0};
 }
 
 // Locked Iterator Context Implementation

From 1379ec06931239661911a2e4993b8d29be0fcfd8 Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Thu, 20 Nov 2025 10:55:53 +0000
Subject: [PATCH 03/15] seperate ghost queue

---
 cachelib/allocator/MMS3FIFO.h |  68 ++-------------------
 cachelib/common/FIFOHashSet.h | 110 ++++++++++++++++++++++++++++++++++
 2 files changed, 115 insertions(+), 63 deletions(-)
 create mode 100644 cachelib/common/FIFOHashSet.h

diff --git a/cachelib/allocator/MMS3FIFO.h b/cachelib/allocator/MMS3FIFO.h
index c472b1beaa..97d1d52e47 100644
--- a/cachelib/allocator/MMS3FIFO.h
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -30,57 +30,12 @@
 #include "cachelib/allocator/datastruct/MultiDList.h"
 #include "cachelib/allocator/memory/serialize/gen-cpp2/objects_types.h"
 #include "cachelib/common/CompilerUtils.h"
-#include "cachelib/common/CountMinSketch.h"
+#include "cachelib/common/FIFOHashSet.h"
 #include "cachelib/common/Mutex.h"
 
 namespace facebook::cachelib {
 // Implements the S3-FIFO cache eviction policy as described in
 
-#pragma once
-#include <cstdint>
-#include <deque>
-#include <unordered_set>
-
-class GhostQueue {
- public:
-  explicit GhostQueue(size_t capacity) : maxSize_(capacity) {}
-
-  bool contains(uint32_t key) const { return set_.find(key) != set_.end(); }
-
-  void insert(uint32_t key) {
-    if (set_.count(key) > 0) {
-      return;
-    }
-
-    fifo_.push_back(key);
-    set_.insert(key);
-
-    enforceCapacity();
-  }
-
-  void resize(size_t newSize) {
-    maxSize_ = newSize;
-    enforceCapacity();
-  }
-
-  size_t size() const { return set_.size(); }
-
- private:
-  void enforceCapacity() {
-    while (fifo_.size() > maxSize_) {
-      uint32_t k = fifo_.front();
-      fifo_.pop_front();
-      set_.erase(k);
-    }
-  }
-
- private:
-  size_t maxSize_;
-  std::deque<uint32_t> fifo_;
-  std::unordered_set<uint32_t> set_;
-};
-
-
 class MMS3FIFO {
  public:
   // unique identifier per MMType
@@ -559,12 +514,6 @@ class MMS3FIFO {
       return lru_.size();
     }
 
-    // TODO: Hash table for ghost queue
-    size_t counterSize() const noexcept {
-      LockHolder l(lruMutex_);
-      return accessFreq_.getByteSize();
-    }
-
     // Returns the eviction age stats. See CacheStats.h for details
     EvictionAgeStat getEvictionAgeStat(uint64_t projectedLength) const noexcept;
 
@@ -612,8 +561,7 @@ class MMS3FIFO {
       (node.*HookPtr).setUpdateTime(time);
     }
 
-    // As the cache grows, the frequency counters may need to grow.
-    // Todo: Grow with hash table
+    // As the cache grows, the ghost queue may need to be resized
     void maybeGrowGhostLocked() noexcept;
 
     // Returns the hash of node's key
@@ -676,7 +624,7 @@ class MMS3FIFO {
     // the lru
     LruList lru_;
 
-    GhostQueue ghostQueue_{0};
+    facebook::cachelib::util::FIFOHashSet ghostQueue_{};
 
     // the window size counter
     size_t windowSize_{0};
@@ -701,10 +649,6 @@ class MMS3FIFO {
     // Reads may be racy.
     Config config_{};
 
-    // Approximate streaming frequency counters. The counts are halved every
-    // time the maxWindowSize is hit.
-    facebook::cachelib::util::CountMinSketch accessFreq_{};
-
     // // Todo: Test?
     // FRIEND_TEST(MMS3FIFOTest, SegmentStress);
     // FRIEND_TEST(MMS3FIFOTest, TinyLFUBasic);
@@ -725,12 +669,11 @@ MMS3FIFO::Container<T, HookPtr>::Container(serialization::MMS3FIFOObject object,
   maybeGrowGhostLocked();
 }
 
-// Todo: initialize hash table
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 void MMS3FIFO::Container<T, HookPtr>::maybeGrowGhostLocked() noexcept {
   size_t capacity = lru_.size();
-  // If the new capacity ask is more than double the current size, recreate
-  // the approx frequency counters.
+  // If the new capacity ask is more than double the current size, 
+  // expand the ghost queue
   if (2 * capacity_ > capacity) {
     return;
   }
@@ -812,7 +755,6 @@ MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStatLocked(
   return stat;
 }
 
-// Todo: Check whether item exist in ghost queue.
 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());
diff --git a/cachelib/common/FIFOHashSet.h b/cachelib/common/FIFOHashSet.h
new file mode 100644
index 0000000000..afcd3f3b2d
--- /dev/null
+++ b/cachelib/common/FIFOHashSet.h
@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) Meta Platforms, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * ...
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <deque>
+#include <stdexcept>
+#include <unordered_set>
+
+namespace facebook::cachelib::util {
+
+namespace detail {
+
+// A bounded FIFO ghost list with O(1) membership check using a hash set.
+// Used by caching algorithms such as S3-FIFO, ARC, LIRS, CLOCK-Pro, etc.
+//
+// Semantics:
+//  - Tracks recently-evicted keys
+//  - Fixed capacity; evicts oldest entry (FIFO)
+//  - Membership test is O(1)
+//  - No TTL, no ranking, no frequency tracking
+//  - User must synchronize external concurrency
+//
+// Structure:
+//   deque<uint32_t>    : stores FIFO eviction order
+//   unordered_set<uint32_t> : stores O(1) membership
+//
+template <typename KeyT = uint32_t>
+class FIFOHashSetBase {
+ public:
+  // @param capacity   Maximum number of ghost entries to keep.
+  explicit FIFOHashSetBase(size_t capacity) : maxSize_{capacity} {
+    if (capacity == 0) {
+      throw std::invalid_argument{"GhostQueue capacity must be > 0"};
+    }
+  }
+
+  FIFOHashSetBase() = default;
+
+  FIFOHashSetBase(const FIFOHashSetBase&) = delete;
+  FIFOHashSetBase& operator=(const FIFOHashSetBase&) = delete;
+
+  FIFOHashSetBase(FIFOHashSetBase&& other) noexcept
+      : maxSize_{other.maxSize_},
+        fifo_{std::move(other.fifo_)},
+        set_{std::move(other.set_)} {
+    other.maxSize_ = 0;
+  }
+
+  FIFOHashSetBase& operator=(FIFOHashSetBase&& other) noexcept {
+    if (this != &other) {
+      this->~FIFOHashSetBase();
+      new (this) FIFOHashSetBase(std::move(other));
+    }
+    return *this;
+  }
+
+  // O(1) membership check.
+  bool contains(KeyT key) const { return set_.find(key) != set_.end(); }
+
+  // Insert a key into ghost queue. If already present, no-op.
+  void insert(KeyT key) {
+    if (set_.count(key) > 0) {
+      return;
+    }
+
+    fifo_.push_back(key);
+    set_.insert(key);
+
+    enforceCapacity();
+  }
+
+  // Resize queue capacity (evicts oldest entries if shrinking).
+  void resize(size_t newSize) {
+    if (newSize == 0) {
+      throw std::invalid_argument{"GhostQueue capacity must be > 0"};
+    }
+    maxSize_ = newSize;
+    enforceCapacity();
+  }
+
+  size_t size() const { return set_.size(); }
+
+  size_t capacity() const { return maxSize_; }
+
+ private:
+  // Remove oldest items until size <= capacity.
+  void enforceCapacity() {
+    while (fifo_.size() > maxSize_) {
+      KeyT k = fifo_.front();
+      fifo_.pop_front();
+      set_.erase(k);
+    }
+  }
+
+ private:
+  size_t maxSize_{0};
+  std::deque<KeyT> fifo_{};
+  std::unordered_set<KeyT> set_{};
+};
+
+} // namespace detail
+using FIFOHashSet = detail::FIFOHashSetBase<uint32_t>;
+
+} // namespace facebook::cachelib::util

From b3f75a8587ca6505bbf9d204ace809f0d2f15a30 Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Thu, 20 Nov 2025 12:21:20 +0000
Subject: [PATCH 04/15] s3fifo config

---
 cachelib/allocator/MMS3FIFO.h               | 325 +++-----------------
 cachelib/allocator/serialize/objects.thrift |  15 +-
 cachelib/cachebench/cache/Cache.h           |  17 +
 cachelib/cachebench/runner/Stressor.cpp     |  12 +
 cachelib/cachebench/util/CacheConfig.cpp    |   5 +-
 cachelib/cachebench/util/CacheConfig.h      |   6 +
 cachelib/common/FIFOHashSet.h               |   3 -
 7 files changed, 84 insertions(+), 299 deletions(-)

diff --git a/cachelib/allocator/MMS3FIFO.h b/cachelib/allocator/MMS3FIFO.h
index 97d1d52e47..ca95e58514 100644
--- a/cachelib/allocator/MMS3FIFO.h
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -54,180 +54,32 @@ class MMS3FIFO {
   struct Config {
     // create from serialized config
     explicit Config(SerializationConfigType configState)
-        : Config(*configState.lruRefreshTime(),
-                 *configState.lruRefreshRatio(),
+        : Config(
                  *configState.updateOnWrite(),
                  *configState.updateOnRead(),
-                 *configState.tryLockUpdate(),
-                 *configState.windowToCacheSizeRatio(),
                  *configState.tinySizePercent(),
-                 *configState.mmReconfigureIntervalSecs(),
-                 *configState.newcomerWinsOnTie()) {}
+                  *configState.ghostSizePercent()) {}
 
-    // @param time        the LRU refresh time in seconds.
-    //                    An item will be promoted only once in each lru refresh
-    //                    time depite the number of accesses it gets.
     // @param udpateOnW   whether to promote the item on write
     // @param updateOnR   whether to promote the item on read
-    Config(uint32_t time, bool updateOnW, bool updateOnR)
-        : Config(time,
-                 updateOnW,
+    Config(bool updateOnW, bool updateOnR)
+        : Config(updateOnW,
                  updateOnR,
-                 /* try lock update */ false,
-                 16,
-                 10) {}
-
-    // @param time              the LRU refresh time in seconds.
-    //                          An item will be promoted only once in each lru
-    //                          refresh time depite the number of accesses it
-    //                          gets.
-    // @param udpateOnW         whether to promote the item on write
-    // @param updateOnR         whether to promote the item on read
-    // @param windowToCacheSize multiplier of window size to cache size
-    // @param tinySizePct       percentage number of tiny size to overall size
-    Config(uint32_t time,
-           bool updateOnW,
-           bool updateOnR,
-           size_t windowToCacheSize,
-           size_t tinySizePct)
-        : Config(time,
-                 updateOnW,
-                 updateOnR,
-                 /* try lock update */ false,
-                 windowToCacheSize,
-                 tinySizePct) {}
-
-    // @param time              the LRU refresh time in seconds.
-    //                          An item will be promoted only once in each lru
-    //                          refresh time depite the number of accesses it
-    //                          gets.
+                 10,
+                 90) {}
+
     // @param udpateOnW         whether to promote the item on write
     // @param updateOnR         whether to promote the item on read
-    // @param tryLockU          whether to use a try lock when doing update.
     // @param windowToCacheSize multiplier of window size to cache size
     // @param tinySizePct       percentage number of tiny size to overall size
-    Config(uint32_t time,
-           bool updateOnW,
-           bool updateOnR,
-           bool tryLockU,
-           size_t windowToCacheSize,
-           size_t tinySizePct)
-        : Config(time,
-                 0.,
-                 updateOnW,
-                 updateOnR,
-                 tryLockU,
-                 windowToCacheSize,
-                 tinySizePct) {}
-
-    // @param time                    the LRU refresh time in seconds.
-    //                                An item will be promoted only once in each
-    //                                lru refresh time depite the number of
-    //                                accesses it gets.
-    // @param ratio                   the lru refresh ratio. The ratio times the
-    //                                oldest element's lifetime in warm queue
-    //                                would be the minimum value of LRU refresh
-    //                                time.
-    // @param udpateOnW               whether to promote the item on write
-    // @param updateOnR               whether to promote the item on read
-    // @param tryLockU                whether to use a try lock when doing
-    //                                update.
-    // @param windowToCacheSize       multiplier of window size to cache size
-    // @param tinySizePct             percentage number of tiny size to overall
-    //                                size
-    Config(uint32_t time,
-           double ratio,
-           bool updateOnW,
-           bool updateOnR,
-           bool tryLockU,
-           size_t windowToCacheSize,
-           size_t tinySizePct)
-        : Config(time,
-                 ratio,
-                 updateOnW,
-                 updateOnR,
-                 tryLockU,
-                 windowToCacheSize,
-                 tinySizePct,
-                 0) {}
-
-    // @param time                    the LRU refresh time in seconds.
-    //                                An item will be promoted only once in each
-    //                                lru refresh time depite the number of
-    //                                accesses it gets.
-    // @param ratio                   the lru refresh ratio. The ratio times the
-    //                                oldest element's lifetime in warm queue
-    //                                would be the minimum value of LRU refresh
-    //                                time.
-    // @param udpateOnW               whether to promote the item on write
-    // @param updateOnR               whether to promote the item on read
-    // @param tryLockU                whether to use a try lock when doing
-    //                                update.
-    // @param windowToCacheSize       multiplier of window size to cache size
-    // @param tinySizePct             percentage number of tiny size to overall
-    //                                size
-    // @param mmReconfigureInterval   Time interval for recalculating lru
-    //                                refresh time according to the ratio.
-    Config(uint32_t time,
-           double ratio,
-           bool updateOnW,
-           bool updateOnR,
-           bool tryLockU,
-           size_t windowToCacheSize,
-           size_t tinySizePct,
-           uint32_t mmReconfigureInterval)
-        : defaultLruRefreshTime(time),
-          lruRefreshRatio(ratio),
-          updateOnWrite(updateOnW),
-          updateOnRead(updateOnR),
-          tryLockUpdate(tryLockU),
-          windowToCacheSizeRatio(windowToCacheSize),
-          tinySizePercent(tinySizePct),
-          mmReconfigureIntervalSecs(
-              std::chrono::seconds(mmReconfigureInterval)) {
-      checkConfig();
-    }
-
-    // @param time                    the LRU refresh time in seconds.
-    //                                An item will be promoted only once in each
-    //                                lru refresh time depite the number of
-    //                                accesses it gets.
-    // @param ratio                   the lru refresh ratio. The ratio times the
-    //                                oldest element's lifetime in warm queue
-    //                                would be the minimum value of LRU refresh
-    //                                time.
-    // @param udpateOnW               whether to promote the item on write
-    // @param updateOnR               whether to promote the item on read
-    // @param tryLockU                whether to use a try lock when doing
-    //                                update.
-    // @param windowToCacheSize       multiplier of window size to cache size
-    // @param tinySizePct             percentage number of tiny size to overall
-    //                                size
-    // @param mmReconfigureInterval   Time interval for recalculating lru
-    //                                refresh time according to the ratio.
-    // @param newcomerWinsOnTie       If true, new comer will replace existing
-    //                                item if their access frequencies tie.
-    Config(uint32_t time,
-           double ratio,
-           bool updateOnW,
+    Config(bool updateOnW,
            bool updateOnR,
-           bool tryLockU,
-           size_t windowToCacheSize,
            size_t tinySizePct,
-           uint32_t mmReconfigureInterval,
-           bool _newcomerWinsOnTie)
-        : defaultLruRefreshTime(time),
-          lruRefreshRatio(ratio),
-          updateOnWrite(updateOnW),
+           size_t ghostSizePct)
+        : updateOnWrite(updateOnW),
           updateOnRead(updateOnR),
-          tryLockUpdate(tryLockU),
-          windowToCacheSizeRatio(windowToCacheSize),
           tinySizePercent(tinySizePct),
-          mmReconfigureIntervalSecs(
-              std::chrono::seconds(mmReconfigureInterval)),
-          newcomerWinsOnTie(_newcomerWinsOnTie) {
-      checkConfig();
-    }
+          ghostSizePercent(ghostSizePct) {}
 
     Config() = default;
     Config(const Config& rhs) = default;
@@ -236,65 +88,24 @@ class MMS3FIFO {
     Config& operator=(const Config& rhs) = default;
     Config& operator=(Config&& rhs) = default;
 
-    void checkConfig() {
-      if (tinySizePercent < 1 || tinySizePercent > 50) {
-        throw std::invalid_argument(
-            folly::sformat("Invalid tiny cache size {}. Tiny cache size "
-                           "must be between 1% and 50% of total cache size ",
-                           tinySizePercent));
-      }
-      if (windowToCacheSizeRatio < 2 || windowToCacheSizeRatio > 128) {
-        throw std::invalid_argument(
-            folly::sformat("Invalid window to cache size ratio {}. The ratio "
-                           "must be between 2 and 128",
-                           windowToCacheSizeRatio));
-      }
-    }
-
     template <typename... Args>
     void addExtraConfig(Args...) {}
 
-    // threshold value in seconds to compare with a node's update time to
-    // determine if we need to update the position of the node in the linked
-    // list. By default this is 60s to reduce the contention on the lru lock.
-    uint32_t defaultLruRefreshTime{60};
-    uint32_t lruRefreshTime{defaultLruRefreshTime};
-
-    // ratio of LRU refresh time to the tail age. If a refresh time computed
-    // according to this ratio is larger than lruRefreshtime, we will adopt
-    // this one instead of the lruRefreshTime set.
-    double lruRefreshRatio{0.};
-
-    // whether the lru needs to be updated on writes for recordAccess. If
+    // whether the cache needs to be updated on writes for recordAccess. If
     // false, accessing the cache for writes does not promote the cached item
     // to the head of the lru.
     bool updateOnWrite{false};
 
-    // whether the lru needs to be updated on reads for recordAccess. If
+    // whether the cache needs to be updated on reads for recordAccess. If
     // false, accessing the cache for reads does not promote the cached item
     // to the head of the lru.
     bool updateOnRead{true};
 
-    // whether to tryLock or lock the lru lock when attempting promotion on
-    // access. If set, and tryLock fails, access will not result in promotion.
-    bool tryLockUpdate{false};
-
-    // The multiplier for window size given the cache size.
-    size_t windowToCacheSizeRatio{32};
-
     // The size of tiny cache, as a percentage of the total size.
     size_t tinySizePercent{10};
 
-    // Minimum interval between reconfigurations. If 0, reconfigure is never
-    // called.
-    std::chrono::seconds mmReconfigureIntervalSecs{};
-
-    // If true, then if an item in the tail of the Tiny queue ties with the
-    // item in the tail of the main queue, the item from Tiny (newcomer) will
-    // replace the item from Main. This is fine for a default, but for
-    // strictly scan patterns (access a key exactly once and move on), this
-    // is not a desirable behavior (we'll always cache miss).
-    bool newcomerWinsOnTie{true};
+    // The size of ghost queue, as a percentage of main queue
+    size_t ghostSizePercent{100};
   };
 
   // The container object which can be used to keep track of objects of type
@@ -316,15 +127,7 @@ class MMS3FIFO {
    public:
     Container() = default;
     Container(Config c, PtrCompressor compressor)
-        : lru_(LruType::NumTypes, std::move(compressor)),
-          config_(std::move(c)) {
-      lruRefreshTime_ = config_.lruRefreshTime;
-      nextReconfigureTime_ =
-          config_.mmReconfigureIntervalSecs.count() == 0
-              ? std::numeric_limits<Time>::max()
-              : static_cast<Time>(util::getCurrentTimeSec()) +
-                    config_.mmReconfigureIntervalSecs.count();
-    }
+        : lru_(LruType::NumTypes, std::move(compressor)), config_(std::move(c)) {}
     Container(serialization::MMS3FIFOObject object, PtrCompressor compressor);
 
     Container(const Container&) = delete;
@@ -391,7 +194,12 @@ class MMS3FIFO {
 
       LockedIterator& operator++() noexcept {
         // Advance the underlying iterator
-        ListIterator& it = ++getIter();
+        ListIterator& it = getIter();
+
+        if (!it) {
+          return *this;
+        }
+        ++it;
         // Skip accessed items
         skipAccessed(it);
         return *this;
@@ -472,8 +280,8 @@ class MMS3FIFO {
             static_cast<const LockedIterator*>(this)->getIter());
       }
 
-      // Todo: can probably cache the evicttiny call
-      // Will switch when iter is exhausted.
+      // Decides to return iterator from tiny or main cache based on capacity.
+      // Will switch iterators when one of them is exhausted.
       bool evictTiny() const noexcept {
         if (!mIter_) {
           return true;
@@ -515,6 +323,7 @@ class MMS3FIFO {
     }
 
     // Returns the eviction age stats. See CacheStats.h for details
+    // Todo
     EvictionAgeStat getEvictionAgeStat(uint64_t projectedLength) const noexcept;
 
     // Obtain an iterator that start from the tail and can be used
@@ -548,7 +357,6 @@ class MMS3FIFO {
       return isTiny(node) ? LruType::Tiny : LruType::Main;
     }
     
-
    private:
     EvictionAgeStat getEvictionAgeStatLocked(
         uint64_t projectedLength) const noexcept;
@@ -574,10 +382,6 @@ class MMS3FIFO {
     // @param node          node to remove
     void removeLocked(T& node) noexcept;
 
-    size_t remove_tiny = 0;
-    size_t remove_main = 0;
-
-
     static bool isTiny(const T& node) noexcept {
       return node.template isFlagSet<RefFlags::kMMFlag0>();
     }
@@ -604,45 +408,18 @@ class MMS3FIFO {
       node.template unSetFlag<RefFlags::kMMFlag1>();
     }
 
-    // Initial cache capacity estimate for count-min-sketch
-    static constexpr size_t kDefaultCapacity = 100;
-
-    // Number of hashes
-    static constexpr size_t kHashCount = 4;
-
-    // The error threshold for frequency calculation
-    static constexpr size_t kErrorThreshold = 5;
-
-    // decay rate for frequency
-    static constexpr double kDecayFactor = 0.5;
-
     // protects all operations on the lru. We never really just read the state
     // of the LRU. Hence we dont really require a RW mutex at this point of
     // time.
     mutable Mutex lruMutex_;
+    
+    // Current ghost capacity
+    size_t capacity_{0};
 
     // the lru
     LruList lru_;
 
-    facebook::cachelib::util::FIFOHashSet ghostQueue_{};
-
-    // the window size counter
-    size_t windowSize_{0};
-
-    // maximum value of window size which when hit the counters are halved
-    size_t maxWindowSize_{0};
-
-    // The capacity for which the counters are sized
-    size_t capacity_{0};
-
-    // The next time to reconfigure the container.
-    std::atomic<Time> nextReconfigureTime_{};
-
-    // How often to promote an item in the eviction queue.
-    std::atomic<uint32_t> lruRefreshTime_{};
-
-    // Max lruFreshTime.
-    static constexpr uint32_t kLruRefreshTimeCap{900};
+    facebook::cachelib::util::FIFOHashSet ghostQueue_;
 
     // Config for this lru.
     // Write access to the MMS3FIFO Config is serialized.
@@ -661,17 +438,13 @@ 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()) {
-  lruRefreshTime_ = config_.lruRefreshTime;
-  nextReconfigureTime_ = config_.mmReconfigureIntervalSecs.count() == 0
-                             ? std::numeric_limits<Time>::max()
-                             : static_cast<Time>(util::getCurrentTimeSec()) +
-                                   config_.mmReconfigureIntervalSecs.count();
   maybeGrowGhostLocked();
 }
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 void MMS3FIFO::Container<T, HookPtr>::maybeGrowGhostLocked() noexcept {
   size_t capacity = lru_.size();
+
   // If the new capacity ask is more than double the current size, 
   // expand the ghost queue
   if (2 * capacity_ > capacity) {
@@ -679,11 +452,12 @@ void MMS3FIFO::Container<T, HookPtr>::maybeGrowGhostLocked() noexcept {
   }
   
   // Capacity should be proportion of main queue
-  // Todo config
-  // now size of main queue
   size_t capacityMain = lru_.getList(LruType::Main).size();
+  size_t expectedGhostSize =
+      static_cast<size_t>(capacityMain * config_.ghostSizePercent / 100);
 
-  ghostQueue_.resize(capacityMain);
+  ghostQueue_.resize(expectedGhostSize);
+  capacity_ = capacity;
 }
 
 // We have no notion of "reconfiguring lock"
@@ -793,7 +567,7 @@ void MMS3FIFO::Container<T, HookPtr>::rebalanceForEviction() {
   }
   auto totalSize = tinyLru.size() + mainLru.size();
   // Print the proportions of size
-  if (totalSize % 100 == 0) {
+  if (totalSize % 1000 == 0) {
     auto propTiny =
         static_cast<double>(tinyLru.size()) / static_cast<double>(totalSize);
     auto propMain =
@@ -805,9 +579,7 @@ void MMS3FIFO::Container<T, HookPtr>::rebalanceForEviction() {
            mainLru.size());
   }
 
-  // Run S3-FIFO rules until the current tail (of chosen list)
-  // is an unaccessed victim.
-
+  // Promote until we find a victim, so iterator won't have to mutate the lists
   while (true) {
     bool tryTiny = (lru_.size() * config_.tinySizePercent /100) < tinyLru.size();
 
@@ -825,10 +597,9 @@ void MMS3FIFO::Container<T, HookPtr>::rebalanceForEviction() {
         mainLru.linkAtHead(node);
         Container<T, HookPtr>::unmarkTiny(node);
         Container<T, HookPtr>::unmarkAccessed(node);
-        // sizes changed, loop again
         continue;
       } else {
-        // unaccessed tail in S → valid victim, stop rebalancing
+        // unaccessed tail in S → valid victim, we can pass to iterator.
         return;
       }
 
@@ -844,7 +615,6 @@ void MMS3FIFO::Container<T, HookPtr>::rebalanceForEviction() {
         // accessed tail in M → move to head(M), clear bit
         mainLru.moveToHead(node);
         Container<T, HookPtr>::unmarkAccessed(node);
-        // try again with new tail
         continue;
       } else {
         // unaccessed tail in M → victim
@@ -881,7 +651,7 @@ void MMS3FIFO::Container<T, HookPtr>::removeLocked(T& node) noexcept {
   if (isTiny(node)) {
     lru_.getList(LruType::Tiny).remove(node);
     unmarkTiny(node);
-    // Insert to hash upon removal
+    // Insert to ghost upon removal
     ghostQueue_.insert(hashNode(node));
   } else {
     lru_.getList(LruType::Main).remove(node);
@@ -947,31 +717,18 @@ typename MMS3FIFO::Config MMS3FIFO::Container<T, HookPtr>::getConfig() const {
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 void MMS3FIFO::Container<T, HookPtr>::setConfig(const Config& c) {
   LockHolder l(lruMutex_);
-  config_ = c;
-  lruRefreshTime_.store(config_.lruRefreshTime, std::memory_order_relaxed);
-  nextReconfigureTime_ = config_.mmReconfigureIntervalSecs.count() == 0
-                             ? std::numeric_limits<Time>::max()
-                             : static_cast<Time>(util::getCurrentTimeSec()) +
-                                   config_.mmReconfigureIntervalSecs.count();
+  config_ = c; 
 }
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 serialization::MMS3FIFOObject MMS3FIFO::Container<T, HookPtr>::saveState()
     const noexcept {
   serialization::MMS3FIFOConfig configObject;
-  *configObject.lruRefreshTime() =
-      lruRefreshTime_.load(std::memory_order_relaxed);
-  *configObject.lruRefreshRatio() = config_.lruRefreshRatio;
   *configObject.updateOnWrite() = config_.updateOnWrite;
   *configObject.updateOnRead() = config_.updateOnRead;
-  *configObject.windowToCacheSizeRatio() = config_.windowToCacheSizeRatio;
+  *configObject.ghostSizePercent() = config_.ghostSizePercent;
   *configObject.tinySizePercent() = config_.tinySizePercent;
-  *configObject.mmReconfigureIntervalSecs() =
-      config_.mmReconfigureIntervalSecs.count();
-  *configObject.newcomerWinsOnTie() = config_.newcomerWinsOnTie;
-  // TODO: Serialize with ghost queue too.
-  // Right now serialization / save state is incomplete.
-
+  // TODO: Serialize the ghost queue too.
   serialization::MMS3FIFOObject object;
   *object.config() = configObject;
   *object.lrus() = lru_.saveState();
diff --git a/cachelib/allocator/serialize/objects.thrift b/cachelib/allocator/serialize/objects.thrift
index 0d4a4fc3b1..c215a405cb 100644
--- a/cachelib/allocator/serialize/objects.thrift
+++ b/cachelib/allocator/serialize/objects.thrift
@@ -112,17 +112,10 @@ struct MM2QCollection {
 
 
 struct MMS3FIFOConfig {
-  1: required i32 lruRefreshTime;
-  2: required bool updateOnWrite;
-  3: required i32 windowToCacheSizeRatio;
-  4: required i32 tinySizePercent;
-  5: bool updateOnRead = true;
-  6: bool tryLockUpdate = false;
-  7: double lruRefreshRatio = 0.0;
-  8: i32 mmReconfigureIntervalSecs = 0;
-  9: bool newcomerWinsOnTie = true;
-  10: i32 protectionFreq_ = 3;
-  11: i32 protectionSegmentSizePct = 80;
+  1: required bool updateOnWrite;
+  2: bool updateOnRead = true;
+  3: i32 tinySizePercent;
+  4: i32 ghostSizePercent;
 }
 
 struct MMS3FIFOObject {
diff --git a/cachelib/cachebench/cache/Cache.h b/cachelib/cachebench/cache/Cache.h
index 6f1d35683d..65512e4a45 100644
--- a/cachelib/cachebench/cache/Cache.h
+++ b/cachelib/cachebench/cache/Cache.h
@@ -489,6 +489,23 @@ inline typename Lru2QAllocator::MMConfig makeMMConfig(
                                   config.useCombinedLockForIterators);
 }
 
+template <>
+inline typename S3FIFOAllocator::MMConfig makeMMConfig(
+    CacheConfig const& config) {
+       return S3FIFOAllocator::MMConfig(
+          config.lruUpdateOnWrite,
+          config.lruUpdateOnRead,
+          config.tinySizePercent,
+          config.ghostSizePercent);
+}
+
+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};
diff --git a/cachelib/common/FIFOHashSet.h b/cachelib/common/FIFOHashSet.h
index afcd3f3b2d..722a28a689 100644
--- a/cachelib/common/FIFOHashSet.h
+++ b/cachelib/common/FIFOHashSet.h
@@ -77,9 +77,6 @@ class FIFOHashSetBase {
 
   // Resize queue capacity (evicts oldest entries if shrinking).
   void resize(size_t newSize) {
-    if (newSize == 0) {
-      throw std::invalid_argument{"GhostQueue capacity must be > 0"};
-    }
     maxSize_ = newSize;
     enforceCapacity();
   }

From f4ace753e9ccfc6cc45055b52a7158cac746f482 Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Thu, 20 Nov 2025 13:30:22 +0000
Subject: [PATCH 05/15] add comments, cleanup

---
 cachelib/allocator/MMS3FIFO.h | 99 +++++++++++++++--------------------
 1 file changed, 41 insertions(+), 58 deletions(-)

diff --git a/cachelib/allocator/MMS3FIFO.h b/cachelib/allocator/MMS3FIFO.h
index ca95e58514..11abb24e7c 100644
--- a/cachelib/allocator/MMS3FIFO.h
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -35,6 +35,8 @@
 
 namespace facebook::cachelib {
 // Implements the S3-FIFO cache eviction policy as described in
+// https://dl.acm.org/doi/pdf/10.1145/3600006.3613147
+// 
 
 class MMS3FIFO {
  public:
@@ -70,16 +72,16 @@ class MMS3FIFO {
 
     // @param udpateOnW         whether to promote the item on write
     // @param updateOnR         whether to promote the item on read
-    // @param windowToCacheSize multiplier of window size to cache size
-    // @param tinySizePct       percentage number of tiny size to overall size
+    // @param tinySizePercent   percentage number of tiny size to overall size
+    // @param ghostSizePercent  percentage number of ghost size to main size
     Config(bool updateOnW,
            bool updateOnR,
-           size_t tinySizePct,
-           size_t ghostSizePct)
+           size_t tinySizePercent,
+           size_t ghostSizePercent)
         : updateOnWrite(updateOnW),
           updateOnRead(updateOnR),
-          tinySizePercent(tinySizePct),
-          ghostSizePercent(ghostSizePct) {}
+          tinySizePercent(tinySizePercent),
+          ghostSizePercent(ghostSizePercent) {}
 
     Config() = default;
     Config(const Config& rhs) = default;
@@ -91,14 +93,10 @@ class MMS3FIFO {
     template <typename... Args>
     void addExtraConfig(Args...) {}
 
-    // whether the cache needs to be updated on writes for recordAccess. If
-    // false, accessing the cache for writes does not promote the cached item
-    // to the head of the lru.
+    // whether the cache needs to be updated on writes for recordAccess.
     bool updateOnWrite{false};
 
-    // whether the cache needs to be updated on reads for recordAccess. If
-    // false, accessing the cache for reads does not promote the cached item
-    // to the head of the lru.
+    // whether the cache needs to be updated on reads for recordAccess. 
     bool updateOnRead{true};
 
     // The size of tiny cache, as a percentage of the total size.
@@ -133,21 +131,18 @@ class MMS3FIFO {
     Container(const Container&) = delete;
     Container& operator=(const Container&) = delete;
 
-    // records the information that the node was accessed. This could bump up
-    // the node to the head of the lru depending on the time when the node was
-    // last updated in lru and the kLruRefreshTime. If the node was moved to
-    // the head in the lru, the node's updateTime will be updated
-    // accordingly.
+    // records the information that the node was accessed. 
+    // This doesn't bump up nodes and only sets the access bit.
+    // It also updates the timestamp of last access.
     //
     // @param node  node that we want to mark as relevant/accessed
-    // @param mode  the mode for the access operation.
-    //
-    // @return      True if the information is recorded and bumped the node
-    //              to the head of the lru, returns false otherwise
+    // @param mode the mode for the access operation.
+    // @return      True if the information is recorded, returns false otherwise
     bool recordAccess(T& node, AccessMode mode) noexcept;
 
     // adds the given node into the container and marks it as being present in
-    // the container. The node is added to the head of the lru.
+    // the container. The node is added to tiny queue, unless it is present
+    // in ghost queue, in which case it is added to main queue.
     //
     // @param node  The node to be added to the container.
     // @return  True if the node was successfully added to the container. False
@@ -155,7 +150,8 @@ class MMS3FIFO {
     //          is unchanged.
     bool add(T& node) noexcept;
 
-    // removes the node from the lru and sets it previous and next to nullptr.
+    // removes the node from the container, adds it to ghost queue 
+    // if it was from tiny queue.
     //
     // @param node  The node to be removed from the container.
     // @return  True if the node was successfully removed from the container.
@@ -164,9 +160,10 @@ class MMS3FIFO {
     bool remove(T& node) noexcept;
 
     class LockedIterator;
+
     // same as the above but uses an iterator context. The iterator is updated
     // on removal of the corresponding node to point to the next node. The
-    // iterator context holds the lock on the lru.
+    // iterator context holds the lock.
     //
     // iterator will be advanced to the next node after removing the node
     //
@@ -192,6 +189,7 @@ class MMS3FIFO {
       LockedIterator& operator=(const LockedIterator&) = delete;
       LockedIterator(LockedIterator&&) noexcept = default;
 
+      // Iterator in S3FIFO only returns unaccessed items, so ++ skips accessed items.
       LockedIterator& operator++() noexcept {
         // Advance the underlying iterator
         ListIterator& it = getIter();
@@ -323,7 +321,8 @@ class MMS3FIFO {
     }
 
     // Returns the eviction age stats. See CacheStats.h for details
-    // Todo
+    // Is not really relevant for S3FIFO since we don't use age.
+    // Todo: deprecate or remove?
     EvictionAgeStat getEvictionAgeStat(uint64_t projectedLength) const noexcept;
 
     // Obtain an iterator that start from the tail and can be used
@@ -342,7 +341,7 @@ class MMS3FIFO {
     template <typename F>
     void withContainerLock(F&& f);
 
-    // for saving the state of the lru
+    // for saving the state of the s3fifo
     //
     // precondition:  serialization must happen without any reader or writer
     // present. Any modification of this object afterwards will result in an
@@ -377,9 +376,7 @@ class MMS3FIFO {
       return folly::hasher<folly::StringPiece>()(node.getKey());
     }
 
-    // remove node from lru and adjust insertion points
-    //
-    // @param node          node to remove
+
     void removeLocked(T& node) noexcept;
 
     static bool isTiny(const T& node) noexcept {
@@ -408,7 +405,7 @@ class MMS3FIFO {
       node.template unSetFlag<RefFlags::kMMFlag1>();
     }
 
-    // protects all operations on the lru. We never really just read the state
+    // protects all operations on the lrus. We never really just read the state
     // of the LRU. Hence we dont really require a RW mutex at this point of
     // time.
     mutable Mutex lruMutex_;
@@ -426,7 +423,7 @@ class MMS3FIFO {
     // Reads may be racy.
     Config config_{};
 
-    // // Todo: Test?
+    // // Todo: Test
     // FRIEND_TEST(MMS3FIFOTest, SegmentStress);
     // FRIEND_TEST(MMS3FIFOTest, TinyLFUBasic);
     // FRIEND_TEST(MMS3FIFOTest, Reconfigure);
@@ -474,10 +471,13 @@ bool MMS3FIFO::Container<T, HookPtr>::recordAccess(T& node,
   LockHolder l(lruMutex_);
   // check if the node is still being memory managed
   // No need refreshing since we are treating the list as a FIFO queue.
-  if (node.isInMMContainer() && !isAccessed(node)) {
+  if (node.isInMMContainer()) {
     if (!isAccessed(node)) {
       markAccessed(node);
     }
+    // Update time here is only used by eviction age stats, which
+    // arguably is not meaningful in FIFO reinsertion strategy.
+    // Todo: We can consider removing update time in future.
     setUpdateTime(node, curr);
     return true;
   }
@@ -491,21 +491,14 @@ cachelib::EvictionAgeStat MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStat(
   return getEvictionAgeStatLocked(projectedLength);
 }
 
-// We have 2 options:
-// 1. Use the tail to get eviction age -> Tail can be popular item
-// 2. Use the first unaccessed item from tail -> Tail is more accurate for age
-// estimation Currently we get the Nth unaccessed item from tail. This function
-// is used for:
-// - Filtering out slab candidates during slab release (projectedLength = 0),
-// actual age is used
-// - Estimating projected eviction age for lrutailage strategy, where
-// projectedLength > 0 We only implement up to 0 case for now. LRUTailAge should
-// not be used in MMS3FIFO.
+// LRU Eviction age is not defined in a FIFO reinsertion strategy, since items in tail
+// can be waiting for promotion.
+// Unaccessed items may have been in the cache for a long time too.
+// Right now it finds first unaccessed item from the tail and reports its age.
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 cachelib::EvictionAgeStat
 MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStatLocked(
     uint64_t projectedLength) const noexcept {
-  printf("MMS3FIFO::Container::getEvictionAgeStatLocked not implemented\n");
   if (projectedLength != 0) {
     throw std::invalid_argument(
         "Projected eviction age estimation is not supported in MMS3FIFO");
@@ -557,6 +550,11 @@ bool MMS3FIFO::Container<T, HookPtr>::add(T& node) noexcept {
   return true;
 }
 
+// This method is called before eviction iterator is called, so
+// Iterator doesn't have to mutate the lists while searching for victims.
+// 
+// It performs the necessary promotions and rebalancing to ensure
+// that items in the tail are evictable.
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 void MMS3FIFO::Container<T, HookPtr>::rebalanceForEviction() {
   auto& tinyLru = lru_.getList(LruType::Tiny);
@@ -566,18 +564,6 @@ void MMS3FIFO::Container<T, HookPtr>::rebalanceForEviction() {
     return;
   }
   auto totalSize = tinyLru.size() + mainLru.size();
-  // Print the proportions of size
-  if (totalSize % 1000 == 0) {
-    auto propTiny =
-        static_cast<double>(tinyLru.size()) / static_cast<double>(totalSize);
-    auto propMain =
-        static_cast<double>(mainLru.size()) / static_cast<double>(totalSize);
-    printf("Tiny size proportion: %.2f %d, Main size proportion: %.2f | %d\n",
-           propTiny,
-            tinyLru.size(),
-           propMain,
-           mainLru.size());
-  }
 
   // Promote until we find a victim, so iterator won't have to mutate the lists
   while (true) {
@@ -707,7 +693,6 @@ bool MMS3FIFO::Container<T, HookPtr>::replace(T& oldNode, T& newNode) noexcept {
   return true;
 }
 
-// Todo: all the configs, states
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 typename MMS3FIFO::Config MMS3FIFO::Container<T, HookPtr>::getConfig() const {
   LockHolder l(lruMutex_);
@@ -739,8 +724,6 @@ template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 MMContainerStat MMS3FIFO::Container<T, HookPtr>::getStats() const noexcept {
   LockHolder l(lruMutex_);
 
-  // auto evictionAge = getEvictionAgeStatLocked(0).warmQueueStat.oldestElementAge;
-
   return {lru_.size(),
           0, // Approximation of tail age from first unaccesessed items
           0, // We have no notion of refresh time, accesses only toggle access bit

From 71820d89af8337a6f7b322cd004991cfce8cf708 Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Thu, 20 Nov 2025 17:50:30 +0000
Subject: [PATCH 06/15] finishing touches

---
 cachelib/allocator/MMS3FIFO.h | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/cachelib/allocator/MMS3FIFO.h b/cachelib/allocator/MMS3FIFO.h
index 11abb24e7c..1a1bf5df86 100644
--- a/cachelib/allocator/MMS3FIFO.h
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -34,9 +34,17 @@
 #include "cachelib/common/Mutex.h"
 
 namespace facebook::cachelib {
+
 // Implements the S3-FIFO cache eviction policy as described in
 // https://dl.acm.org/doi/pdf/10.1145/3600006.3613147
+//
+// S3-FIFO is combines a "Tiny" queue, a larger "Main" queue, and a ghost history. 
+// New items enter the Tiny queue; recently accessed items are promoted to the Main queue.
+// Eviction always searches from the tails of these queues, skipping items
+// that have been accessed since insertion (using a single access bit).
 // 
+// A low overhead ghost queue (stores only 4 byte key hash/ item)tracks recently 
+// evicted keys from the small queue. Items found in ghost are directly into the Main queue. 
 
 class MMS3FIFO {
  public:
@@ -459,6 +467,7 @@ void MMS3FIFO::Container<T, HookPtr>::maybeGrowGhostLocked() noexcept {
 
 // We have no notion of "reconfiguring lock"
 // or refresh interval since we are not manipulating the list lru on access.
+// No need for locks, as we don't modify the list
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 bool MMS3FIFO::Container<T, HookPtr>::recordAccess(T& node,
                                                    AccessMode mode) noexcept {
@@ -468,16 +477,12 @@ bool MMS3FIFO::Container<T, HookPtr>::recordAccess(T& node,
   }
 
   const auto curr = static_cast<Time>(util::getCurrentTimeSec());
-  LockHolder l(lruMutex_);
-  // check if the node is still being memory managed
-  // No need refreshing since we are treating the list as a FIFO queue.
+
   if (node.isInMMContainer()) {
     if (!isAccessed(node)) {
       markAccessed(node);
     }
-    // Update time here is only used by eviction age stats, which
-    // arguably is not meaningful in FIFO reinsertion strategy.
-    // Todo: We can consider removing update time in future.
+    // Todo: can deprecate update time next
     setUpdateTime(node, curr);
     return true;
   }

From 3714df0cc3991684fbf08aed3acd00af588dfe7e Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Fri, 21 Nov 2025 20:29:23 +0000
Subject: [PATCH 07/15] Move growing ghost logic

---
 cachelib/allocator/MMS3FIFO.h          | 21 ++++++++-------------
 cachelib/cachebench/util/CacheConfig.h |  4 ++--
 2 files changed, 10 insertions(+), 15 deletions(-)

diff --git a/cachelib/allocator/MMS3FIFO.h b/cachelib/allocator/MMS3FIFO.h
index 1a1bf5df86..81b3d93ade 100644
--- a/cachelib/allocator/MMS3FIFO.h
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -110,8 +110,8 @@ class MMS3FIFO {
     // The size of tiny cache, as a percentage of the total size.
     size_t tinySizePercent{10};
 
-    // The size of ghost queue, as a percentage of main queue
-    size_t ghostSizePercent{100};
+    // The size of ghost queue, as a percentage of total size
+    size_t ghostSizePercent{90};
   };
 
   // The container object which can be used to keep track of objects of type
@@ -418,7 +418,7 @@ class MMS3FIFO {
     // time.
     mutable Mutex lruMutex_;
     
-    // Current ghost capacity
+    // Current capacity to track ghost size
     size_t capacity_{0};
 
     // the lru
@@ -450,17 +450,12 @@ template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 void MMS3FIFO::Container<T, HookPtr>::maybeGrowGhostLocked() noexcept {
   size_t capacity = lru_.size();
 
-  // If the new capacity ask is more than double the current size, 
-  // expand the ghost queue
-  if (2 * capacity_ > capacity) {
+  // Only consider growing ghost when lru size doubles.
+  if (2 * capacity_ > capacity || capacity == 0) {
     return;
   }
   
-  // Capacity should be proportion of main queue
-  size_t capacityMain = lru_.getList(LruType::Main).size();
-  size_t expectedGhostSize =
-      static_cast<size_t>(capacityMain * config_.ghostSizePercent / 100);
-
+  size_t expectedGhostSize = static_cast<size_t>(capacity * config_.ghostSizePercent / 100);
   ghostQueue_.resize(expectedGhostSize);
   capacity_ = capacity;
 }
@@ -546,8 +541,6 @@ bool MMS3FIFO::Container<T, HookPtr>::add(T& node) noexcept {
     markTiny(node);
   }
 
-  maybeGrowGhostLocked();
-
   node.markInMMContainer();
   setUpdateTime(node, currTime);
   unmarkAccessed(node);
@@ -620,6 +613,8 @@ typename MMS3FIFO::Container<T, HookPtr>::LockedIterator
 MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() noexcept {
   LockHolder l(lruMutex_);
   rebalanceForEviction();
+  // Cache is full now so we know it's max size
+  maybeGrowGhostLocked();
   return LockedIterator{std::move(l), *this};
 }
 
diff --git a/cachelib/cachebench/util/CacheConfig.h b/cachelib/cachebench/util/CacheConfig.h
index 7024aeab13..08446150fe 100644
--- a/cachelib/cachebench/util/CacheConfig.h
+++ b/cachelib/cachebench/util/CacheConfig.h
@@ -106,8 +106,8 @@ struct CacheConfig : public JSONConfig {
   size_t lru2qColdPct{20};
 
   // S3FIFO params
-  size_t ghostSizePercent{100};
-  size_t tinySizePercent{10};
+  size_t ghostSizePercent{90}; // Ghost size as percentage of whole cache
+  size_t tinySizePercent{10}; // Tiny size as percentage of whole cache
 
   double allocFactor{1.5};
   // maximum alloc size generated using the alloc factor above.

From 7f9f9c329ed0dd4c3e764e1e65ddfc117a9e117f Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Mon, 24 Nov 2025 22:34:13 +0000
Subject: [PATCH 08/15] shared lock, folly set

---
 cachelib/allocator/MMS3FIFO.h | 290 +++++++++++++++++-----------------
 cachelib/common/FIFOHashSet.h | 110 +++++++------
 2 files changed, 210 insertions(+), 190 deletions(-)

diff --git a/cachelib/allocator/MMS3FIFO.h b/cachelib/allocator/MMS3FIFO.h
index 81b3d93ade..9360185b7f 100644
--- a/cachelib/allocator/MMS3FIFO.h
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -22,6 +22,8 @@
 #pragma GCC diagnostic ignored "-Wconversion"
 #include <folly/Format.h>
 #include <folly/Math.h>
+#include <folly/synchronization/DistributedMutex.h>
+
 #pragma GCC diagnostic pop
 
 #include "cachelib/allocator/Cache.h"
@@ -31,20 +33,21 @@
 #include "cachelib/allocator/memory/serialize/gen-cpp2/objects_types.h"
 #include "cachelib/common/CompilerUtils.h"
 #include "cachelib/common/FIFOHashSet.h"
-#include "cachelib/common/Mutex.h"
 
 namespace facebook::cachelib {
 
 // Implements the S3-FIFO cache eviction policy as described in
 // https://dl.acm.org/doi/pdf/10.1145/3600006.3613147
 //
-// S3-FIFO is combines a "Tiny" queue, a larger "Main" queue, and a ghost history. 
-// New items enter the Tiny queue; recently accessed items are promoted to the Main queue.
-// Eviction always searches from the tails of these queues, skipping items
-// that have been accessed since insertion (using a single access bit).
-// 
-// A low overhead ghost queue (stores only 4 byte key hash/ item)tracks recently 
-// evicted keys from the small queue. Items found in ghost are directly into the Main queue. 
+// S3-FIFO is combines a "Tiny" queue, a larger "Main" queue, and a ghost
+// history. New items enter the Tiny queue; recently accessed items are promoted
+// to the Main queue. Eviction always searches from the tails of these queues,
+// skipping items that have been accessed since insertion (using a single access
+// bit).
+//
+// A low overhead ghost queue (stores only 4 byte key hash/ item)tracks recently
+// evicted keys from the small queue. Items found in ghost are directly into the
+// Main queue.
 
 class MMS3FIFO {
  public:
@@ -64,19 +67,15 @@ class MMS3FIFO {
   struct Config {
     // create from serialized config
     explicit Config(SerializationConfigType configState)
-        : Config(
-                 *configState.updateOnWrite(),
+        : Config(*configState.updateOnWrite(),
                  *configState.updateOnRead(),
                  *configState.tinySizePercent(),
-                  *configState.ghostSizePercent()) {}
+                 *configState.ghostSizePercent()) {}
 
     // @param udpateOnW   whether to promote the item on write
     // @param updateOnR   whether to promote the item on read
     Config(bool updateOnW, bool updateOnR)
-        : Config(updateOnW,
-                 updateOnR,
-                 10,
-                 90) {}
+        : Config(updateOnW, updateOnR, 10, 90) {}
 
     // @param udpateOnW         whether to promote the item on write
     // @param updateOnR         whether to promote the item on read
@@ -89,7 +88,8 @@ class MMS3FIFO {
         : updateOnWrite(updateOnW),
           updateOnRead(updateOnR),
           tinySizePercent(tinySizePercent),
-          ghostSizePercent(ghostSizePercent) {}
+          ghostSizePercent(ghostSizePercent) {
+    }
 
     Config() = default;
     Config(const Config& rhs) = default;
@@ -104,7 +104,7 @@ class MMS3FIFO {
     // whether the cache needs to be updated on writes for recordAccess.
     bool updateOnWrite{false};
 
-    // whether the cache needs to be updated on reads for recordAccess. 
+    // whether the cache needs to be updated on reads for recordAccess.
     bool updateOnRead{true};
 
     // The size of tiny cache, as a percentage of the total size.
@@ -112,6 +112,8 @@ class MMS3FIFO {
 
     // The size of ghost queue, as a percentage of total size
     size_t ghostSizePercent{90};
+
+    size_t reserveCapacity{0};
   };
 
   // The container object which can be used to keep track of objects of type
@@ -123,7 +125,7 @@ class MMS3FIFO {
   struct Container {
    private:
     using LruList = MultiDList<T, HookPtr>;
-    using Mutex = folly::SpinLock;
+    using Mutex = folly::DistributedMutex;
     using LockHolder = std::unique_lock<Mutex>;
     using PtrCompressor = typename T::PtrCompressor;
     using Time = typename Hook<T>::Time;
@@ -131,16 +133,22 @@ class MMS3FIFO {
     using RefFlags = typename T::Flags;
 
    public:
-    Container() = default;
+    Container() {};
+    // Reserve ghost queue here if needed
     Container(Config c, PtrCompressor compressor)
-        : lru_(LruType::NumTypes, std::move(compressor)), config_(std::move(c)) {}
+        : lru_(LruType::NumTypes, std::move(compressor)),
+          config_(std::move(c)) {
+            if (config_.reserveCapacity > 0) {
+              ghostQueue_.reserve(config_.reserveCapacity);
+            }
+          }
     Container(serialization::MMS3FIFOObject object, PtrCompressor compressor);
 
     Container(const Container&) = delete;
     Container& operator=(const Container&) = delete;
 
-    // records the information that the node was accessed. 
-    // This doesn't bump up nodes and only sets the access bit.
+    // records the information that the node was accessed.
+    // This doesn't move nodes and only sets the access bit.
     // It also updates the timestamp of last access.
     //
     // @param node  node that we want to mark as relevant/accessed
@@ -158,7 +166,7 @@ class MMS3FIFO {
     //          is unchanged.
     bool add(T& node) noexcept;
 
-    // removes the node from the container, adds it to ghost queue 
+    // removes the node from the container, adds it to ghost queue
     // if it was from tiny queue.
     //
     // @param node  The node to be removed from the container.
@@ -188,7 +196,6 @@ class MMS3FIFO {
     //               source node already existed.
     bool replace(T& oldNode, T& newNode) noexcept;
 
-
     class LockedIterator {
      public:
       using ListIterator = typename LruList::DListIterator;
@@ -197,7 +204,8 @@ class MMS3FIFO {
       LockedIterator& operator=(const LockedIterator&) = delete;
       LockedIterator(LockedIterator&&) noexcept = default;
 
-      // Iterator in S3FIFO only returns unaccessed items, so ++ skips accessed items.
+      // Iterator in S3FIFO only returns unaccessed items, so ++ skips accessed
+      // items.
       LockedIterator& operator++() noexcept {
         // Advance the underlying iterator
         ListIterator& it = getIter();
@@ -273,7 +281,8 @@ class MMS3FIFO {
       LockedIterator& operator=(LockedIterator&&) noexcept = default;
 
       // create an lru iterator with the lock being held.
-      explicit LockedIterator(LockHolder l, const Container<T, HookPtr>& c) noexcept;
+      explicit LockedIterator(LockHolder l,
+                              const Container<T, HookPtr>& c) noexcept;
 
       const ListIterator& getIter() const noexcept {
         auto shouldEvictTiny = evictTiny();
@@ -295,14 +304,24 @@ class MMS3FIFO {
         if (!tIter_) {
           return false;
         }
+        // List size will not change during iteration, return cached decision
+        if (evictTinyCache_ != -1) {
+          return evictTinyCache_ == 1;
+        }
 
         int smallSize = static_cast<int>(c_.lru_.getList(LruType::Tiny).size());
 
         const size_t targetTiny = static_cast<size_t>(
-            c_.config_.tinySizePercent * c_.lru_.size()/100);
-        return smallSize >= targetTiny;
+            c_.config_.tinySizePercent * c_.lru_.size() / 100);
+
+        this->evictTinyCache_ = smallSize >= targetTiny;
+
+        return evictTinyCache_;
       }
 
+      // Cache the value
+      mutable int evictTinyCache_{-1}; // -1 means not set, 0 false and 1 true
+
       // only the container can create iterators
       friend Container<T, HookPtr>;
 
@@ -318,16 +337,6 @@ class MMS3FIFO {
 
     void setConfig(const Config& newConfig);
 
-    bool isEmpty() const noexcept {
-      LockHolder l(lruMutex_);
-      return lru_.size() == 0;
-    }
-
-    size_t size() const noexcept {
-      LockHolder l(lruMutex_);
-      return lru_.size();
-    }
-
     // Returns the eviction age stats. See CacheStats.h for details
     // Is not really relevant for S3FIFO since we don't use age.
     // Todo: deprecate or remove?
@@ -363,7 +372,7 @@ class MMS3FIFO {
     static LruType getLruType(const T& node) noexcept {
       return isTiny(node) ? LruType::Tiny : LruType::Main;
     }
-    
+
    private:
     EvictionAgeStat getEvictionAgeStatLocked(
         uint64_t projectedLength) const noexcept;
@@ -384,7 +393,6 @@ class MMS3FIFO {
       return folly::hasher<folly::StringPiece>()(node.getKey());
     }
 
-
     void removeLocked(T& node) noexcept;
 
     static bool isTiny(const T& node) noexcept {
@@ -416,8 +424,8 @@ class MMS3FIFO {
     // protects all operations on the lrus. We never really just read the state
     // of the LRU. Hence we dont really require a RW mutex at this point of
     // time.
-    mutable Mutex lruMutex_;
-    
+    mutable folly::cacheline_aligned<Mutex> lruMutex_;
+
     // Current capacity to track ghost size
     size_t capacity_{0};
 
@@ -443,7 +451,6 @@ 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()) {
-  maybeGrowGhostLocked();
 }
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
@@ -451,11 +458,13 @@ void MMS3FIFO::Container<T, HookPtr>::maybeGrowGhostLocked() noexcept {
   size_t capacity = lru_.size();
 
   // Only consider growing ghost when lru size doubles.
+  // Right now we don't shrink ghost queue.
   if (2 * capacity_ > capacity || capacity == 0) {
     return;
   }
-  
-  size_t expectedGhostSize = static_cast<size_t>(capacity * config_.ghostSizePercent / 100);
+
+  size_t expectedGhostSize =
+      static_cast<size_t>(capacity * config_.ghostSizePercent / 100);
   ghostQueue_.resize(expectedGhostSize);
   capacity_ = capacity;
 }
@@ -470,15 +479,14 @@ bool MMS3FIFO::Container<T, HookPtr>::recordAccess(T& node,
       (mode == AccessMode::kRead && !config_.updateOnRead)) {
     return false;
   }
+  const auto currTime = static_cast<Time>(util::getCurrentTimeSec());
 
-  const auto curr = static_cast<Time>(util::getCurrentTimeSec());
-
+  // Remove lock from record access wince we only set bits
   if (node.isInMMContainer()) {
     if (!isAccessed(node)) {
       markAccessed(node);
     }
-    // Todo: can deprecate update time next
-    setUpdateTime(node, curr);
+    setUpdateTime(node, currTime);
     return true;
   }
   return false;
@@ -487,21 +495,22 @@ bool MMS3FIFO::Container<T, HookPtr>::recordAccess(T& node,
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 cachelib::EvictionAgeStat MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStat(
     uint64_t projectedLength) const noexcept {
-  LockHolder l(lruMutex_);
-  return getEvictionAgeStatLocked(projectedLength);
+  return lruMutex_->lock_combine([this, projectedLength]() {
+    return getEvictionAgeStatLocked(projectedLength);
+  });
 }
 
-// LRU Eviction age is not defined in a FIFO reinsertion strategy, since items in tail
-// can be waiting for promotion.
-// Unaccessed items may have been in the cache for a long time too.
-// Right now it finds first unaccessed item from the tail and reports its age.
+// LRU Eviction age is not defined in a FIFO reinsertion strategy, since items
+// in tail can be waiting for promotion. Unaccessed items may have been in the
+// cache for a long time too. Right now it finds first unaccessed item from the
+// tail and reports its age.
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 cachelib::EvictionAgeStat
 MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStatLocked(
     uint64_t projectedLength) const noexcept {
   if (projectedLength != 0) {
-    throw std::invalid_argument(
-        "Projected eviction age estimation is not supported in MMS3FIFO");
+    // Projected eviction age estimation is not supported in MMS3FIFO
+    return EvictionAgeStat{};
   }
 
   EvictionAgeStat stat;
@@ -525,32 +534,36 @@ MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStatLocked(
 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());
-  LockHolder l(lruMutex_);
-  if (node.isInMMContainer()) {
-    return false;
-  }
 
-  if (ghostQueue_.contains(hashNode(node))) {
-    // Insert to main queue
-    auto& mainLru = lru_.getList(LruType::Main);
-    mainLru.linkAtHead(node);
-  } else {
-    // Insert to tiny queue
-    auto& tinyLru = lru_.getList(LruType::Tiny);
-    tinyLru.linkAtHead(node);
-    markTiny(node);
-  }
+  const auto nodeHash = hashNode(node);
+  return lruMutex_->lock_combine([this, &node, currTime, nodeHash]() {
+    if (node.isInMMContainer()) {
+      return false;
+    }
 
-  node.markInMMContainer();
-  setUpdateTime(node, currTime);
-  unmarkAccessed(node);
+    const auto ghostContains = ghostQueue_.contains(nodeHash);
+    if (ghostContains) {
+      // Insert to main queue
+      auto& mainLru = lru_.getList(LruType::Main);
+      mainLru.linkAtHead(node);
+    } else {
+      // Insert to tiny queue
+      auto& tinyLru = lru_.getList(LruType::Tiny);
+      tinyLru.linkAtHead(node);
+      markTiny(node);
+    }
 
-  return true;
+    node.markInMMContainer();
+    setUpdateTime(node, currTime);
+    unmarkAccessed(node);
+
+    return true;
+  });
 }
 
 // This method is called before eviction iterator is called, so
 // Iterator doesn't have to mutate the lists while searching for victims.
-// 
+//
 // It performs the necessary promotions and rebalancing to ensure
 // that items in the tail are evictable.
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
@@ -558,51 +571,49 @@ void MMS3FIFO::Container<T, HookPtr>::rebalanceForEviction() {
   auto& tinyLru = lru_.getList(LruType::Tiny);
   auto& mainLru = lru_.getList(LruType::Main);
 
-  if (tinyLru.size() == 0 && mainLru.size() == 0) {
-    return;
-  }
   auto totalSize = tinyLru.size() + mainLru.size();
+  auto expectedTinySize =
+      static_cast<size_t>(config_.tinySizePercent * totalSize / 100);
 
   // Promote until we find a victim, so iterator won't have to mutate the lists
   while (true) {
-    bool tryTiny = (lru_.size() * config_.tinySizePercent /100) < tinyLru.size();
+    bool tryTiny = tinyLru.size() >= expectedTinySize;
 
     if (tryTiny) {
-      // Tail of S
-      auto it = tinyLru.rbegin();
-      if (!it) {
-        return;
+      // Tail of T
+      T* nodePtr = tinyLru.getTail();
+      if (!nodePtr) {
+        break;
       }
 
-      T& node = *it;
+      T& node = *nodePtr;
       if (Container<T, HookPtr>::isAccessed(node)) {
-        // accessed tail in S → promote to M head
+        // accessed tail in T → promote to M head
         tinyLru.remove(node);
         mainLru.linkAtHead(node);
         Container<T, HookPtr>::unmarkTiny(node);
         Container<T, HookPtr>::unmarkAccessed(node);
         continue;
       } else {
-        // unaccessed tail in S → valid victim, we can pass to iterator.
-        return;
+        // unaccessed tail in T → valid victim, we can stop here.
+        break;
       }
-
     } else {
       // Tail of M
-      auto it = mainLru.rbegin();
-      if (!it) {
-        return;
+      T* nodePtr = mainLru.getTail();
+      if (!nodePtr) {
+        break;
       }
 
-      T& node = *it;
+      T& node = *nodePtr;
       if (Container<T, HookPtr>::isAccessed(node)) {
         // accessed tail in M → move to head(M), clear bit
         mainLru.moveToHead(node);
         Container<T, HookPtr>::unmarkAccessed(node);
         continue;
       } else {
-        // unaccessed tail in M → victim
-        return;
+        // unaccessed tail in M → victim, we can stop here.
+        break;
       }
     }
   }
@@ -611,33 +622,31 @@ void MMS3FIFO::Container<T, HookPtr>::rebalanceForEviction() {
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 typename MMS3FIFO::Container<T, HookPtr>::LockedIterator
 MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() noexcept {
-  LockHolder l(lruMutex_);
+  LockHolder l(*lruMutex_);
+  maybeGrowGhostLocked();
   rebalanceForEviction();
   // Cache is full now so we know it's max size
-  maybeGrowGhostLocked();
   return LockedIterator{std::move(l), *this};
 }
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 template <typename F>
 void MMS3FIFO::Container<T, HookPtr>::withEvictionIterator(F&& fun) {
-  // Uses spinlock, can't use combined locking
   fun(getEvictionIterator());
 }
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 template <typename F>
 void MMS3FIFO::Container<T, HookPtr>::withContainerLock(F&& fun) {
-  LockHolder l(lruMutex_);
-  fun();
+  lruMutex_->lock_combine([&fun]() { fun(); });
 }
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 void MMS3FIFO::Container<T, HookPtr>::removeLocked(T& node) noexcept {
   if (isTiny(node)) {
-    lru_.getList(LruType::Tiny).remove(node);
+    lru_.getList(LruType::Tiny).remove(node); 
     unmarkTiny(node);
-    // Insert to ghost upon removal
+    // Insert into ghost queue upon eviction from tiny queue
     ghostQueue_.insert(hashNode(node));
   } else {
     lru_.getList(LruType::Main).remove(node);
@@ -650,59 +659,59 @@ void MMS3FIFO::Container<T, HookPtr>::removeLocked(T& node) noexcept {
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 bool MMS3FIFO::Container<T, HookPtr>::remove(T& node) noexcept {
-  LockHolder l(lruMutex_);
-  if (!node.isInMMContainer()) {
-    return false;
-  }
-  removeLocked(node);
-  return true;
+  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(LockedIterator& it) noexcept {
   T& node = *it;
   XDCHECK(node.isInMMContainer());
-  ++it;
+  ++it; 
   removeLocked(node);
 }
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 bool MMS3FIFO::Container<T, HookPtr>::replace(T& oldNode, T& newNode) noexcept {
-  LockHolder l(lruMutex_);
-  if (!oldNode.isInMMContainer() || newNode.isInMMContainer()) {
-    return false;
-  }
-  const auto updateTime = getUpdateTime(oldNode);
+  return lruMutex_->lock_combine([this, &oldNode, &newNode]() {
+    if (!oldNode.isInMMContainer() || newNode.isInMMContainer()) {
+      return false;
+    }
+    const auto updateTime = getUpdateTime(oldNode);
 
-  if (isTiny(oldNode)) {
-    lru_.getList(LruType::Tiny).replace(oldNode, newNode);
-    unmarkTiny(oldNode);
-    markTiny(newNode);
-  } else {
-    lru_.getList(LruType::Main).replace(oldNode, newNode);
-  }
+    if (isTiny(oldNode)) {
+      lru_.getList(LruType::Tiny).replace(oldNode, newNode);
+      unmarkTiny(oldNode);
+      markTiny(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;
+    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 {
-  LockHolder l(lruMutex_);
-  return config_;
+  return lruMutex_->lock_combine([this]() { return config_; });
 }
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 void MMS3FIFO::Container<T, HookPtr>::setConfig(const Config& c) {
-  LockHolder l(lruMutex_);
-  config_ = c; 
+  lruMutex_->lock_combine([this, c]() { config_ = c; });
 }
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
@@ -720,17 +729,16 @@ serialization::MMS3FIFOObject MMS3FIFO::Container<T, HookPtr>::saveState()
   return object;
 }
 
+// Unless we use age for slab rebalancing, these stats are not used.
+// E.g. Filter based on minTailAge, or using LRUTailAge strategy.
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 MMContainerStat MMS3FIFO::Container<T, HookPtr>::getStats() const noexcept {
-  LockHolder l(lruMutex_);
-
+  // LockHolder l(*lruMutex_);
   return {lru_.size(),
           0, // Approximation of tail age from first unaccesessed items
-          0, // We have no notion of refresh time, accesses only toggle access bit
-          0,           
-          0, 
-          0, 
-          0};
+          0, // We have no notion of refresh time, accesses only toggle access
+             // bit
+          0, 0, 0, 0};
 }
 
 // Locked Iterator Context Implementation
diff --git a/cachelib/common/FIFOHashSet.h b/cachelib/common/FIFOHashSet.h
index 722a28a689..de3387ca60 100644
--- a/cachelib/common/FIFOHashSet.h
+++ b/cachelib/common/FIFOHashSet.h
@@ -1,39 +1,20 @@
-/*
- * Copyright (c) Meta Platforms, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * ...
- */
-
 #pragma once
 
+#include <folly/Format.h>
+#include <folly/Math.h>
+#include <folly/container/F14Set.h>
+
 #include <cstdint>
 #include <deque>
 #include <stdexcept>
 #include <unordered_set>
 
 namespace facebook::cachelib::util {
-
 namespace detail {
 
-// A bounded FIFO ghost list with O(1) membership check using a hash set.
-// Used by caching algorithms such as S3-FIFO, ARC, LIRS, CLOCK-Pro, etc.
-//
-// Semantics:
-//  - Tracks recently-evicted keys
-//  - Fixed capacity; evicts oldest entry (FIFO)
-//  - Membership test is O(1)
-//  - No TTL, no ranking, no frequency tracking
-//  - User must synchronize external concurrency
-//
-// Structure:
-//   deque<uint32_t>    : stores FIFO eviction order
-//   unordered_set<uint32_t> : stores O(1) membership
-//
 template <typename KeyT = uint32_t>
 class FIFOHashSetBase {
  public:
-  // @param capacity   Maximum number of ghost entries to keep.
   explicit FIFOHashSetBase(size_t capacity) : maxSize_{capacity} {
     if (capacity == 0) {
       throw std::invalid_argument{"GhostQueue capacity must be > 0"};
@@ -45,63 +26,94 @@ class FIFOHashSetBase {
   FIFOHashSetBase(const FIFOHashSetBase&) = delete;
   FIFOHashSetBase& operator=(const FIFOHashSetBase&) = delete;
 
-  FIFOHashSetBase(FIFOHashSetBase&& other) noexcept
-      : maxSize_{other.maxSize_},
-        fifo_{std::move(other.fifo_)},
-        set_{std::move(other.set_)} {
+  FIFOHashSetBase(FIFOHashSetBase&& other) noexcept {
+    maxSize_ = other.maxSize_;
+    fifo_ = std::move(other.fifo_);
+    set_ = std::move(other.set_);
     other.maxSize_ = 0;
   }
 
   FIFOHashSetBase& operator=(FIFOHashSetBase&& other) noexcept {
     if (this != &other) {
-      this->~FIFOHashSetBase();
-      new (this) FIFOHashSetBase(std::move(other));
+      maxSize_ = other.maxSize_;
+      fifo_ = std::move(other.fifo_);
+      set_ = std::move(other.set_);
+      other.maxSize_ = 0;
     }
     return *this;
   }
 
-  // O(1) membership check.
-  bool contains(KeyT key) const { return set_.find(key) != set_.end(); }
+  bool contains(KeyT key) {
+    return set_.contains(key);
+  }
+
+  // Enforce size variant of contains
+  bool containsEnforce(KeyT key) {
+    enforceCapacityLocked();
+    return set_.contains(key);
+  }
+
+  size_t size() {
+    return set_.size();
+  }
+
+  size_t capacity() {
+    return maxSize_;
+  }
+
+  void reserve(size_t newCap) {
+    set_.reserve(newCap);
+  }
 
-  // Insert a key into ghost queue. If already present, no-op.
   void insert(KeyT key) {
-    if (set_.count(key) > 0) {
-      return;
+    auto [it, inserted] = set_.insert(key);
+    if (inserted) {
+      fifo_.push_back(key); 
     }
+    enforceCapacityLocked();
+  }
 
-    fifo_.push_back(key);
-    set_.insert(key);
-
-    enforceCapacity();
+  // No enforce variant of insert
+  void insertNoEnforce(KeyT key) {
+    auto [it, inserted] = set_.insert(key);
+    if (inserted) {
+      fifo_.push_back(key);
+    }
   }
 
-  // Resize queue capacity (evicts oldest entries if shrinking).
   void resize(size_t newSize) {
     maxSize_ = newSize;
-    enforceCapacity();
+    enforceCapacityLocked();
   }
 
-  size_t size() const { return set_.size(); }
-
-  size_t capacity() const { return maxSize_; }
+  // No enforce variant of resize
+  void resizeNoEnforce(size_t newSize) {
+    maxSize_ = newSize;
+  }
 
  private:
-  // Remove oldest items until size <= capacity.
-  void enforceCapacity() {
-    while (fifo_.size() > maxSize_) {
+  // To prevent tail latency, limits max elements removed per call.
+  void enforceCapacityLocked() {
+    constexpr int max_rem = 5;
+    int removed = 0;
+
+    while (fifo_.size() > maxSize_ && removed < max_rem) {
       KeyT k = fifo_.front();
       fifo_.pop_front();
       set_.erase(k);
+      removed++;
     }
   }
 
  private:
+  // mutable folly::SpinLock lock_;
   size_t maxSize_{0};
-  std::deque<KeyT> fifo_{};
-  std::unordered_set<KeyT> set_{};
+  std::deque<KeyT> fifo_;
+  folly::F14FastSet<KeyT> set_;
 };
 
 } // namespace detail
-using FIFOHashSet = detail::FIFOHashSetBase<uint32_t>;
+
+using FIFOHashSet = detail::FIFOHashSetBase<uint64_t>;
 
 } // namespace facebook::cachelib::util

From d0487506a8ed30387776a723b50e722f18f4546e Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Mon, 24 Nov 2025 23:15:37 +0000
Subject: [PATCH 09/15] allow ghost to shrink

---
 cachelib/allocator/MMS3FIFO.h | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/cachelib/allocator/MMS3FIFO.h b/cachelib/allocator/MMS3FIFO.h
index 9360185b7f..374afec8c7 100644
--- a/cachelib/allocator/MMS3FIFO.h
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -386,7 +386,7 @@ class MMS3FIFO {
     }
 
     // As the cache grows, the ghost queue may need to be resized
-    void maybeGrowGhostLocked() noexcept;
+    void maybeResizeGhostLocked() noexcept;
 
     // Returns the hash of node's key
     static size_t hashNode(const T& node) noexcept {
@@ -454,19 +454,21 @@ MMS3FIFO::Container<T, HookPtr>::Container(serialization::MMS3FIFOObject object,
 }
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
-void MMS3FIFO::Container<T, HookPtr>::maybeGrowGhostLocked() noexcept {
-  size_t capacity = lru_.size();
+void MMS3FIFO::Container<T, HookPtr>::maybeResizeGhostLocked() noexcept {
+  size_t lruSize = lru_.size();
 
-  // Only consider growing ghost when lru size doubles.
-  // Right now we don't shrink ghost queue.
-  if (2 * capacity_ > capacity || capacity == 0) {
+  // Grow when size doubled, shrink when halved
+  const bool shouldGrow = lruSize >= 2 * capacity_;
+  const bool shouldShrink = lruSize <= capacity_ / 2;
+
+  if (!shouldGrow && !shouldShrink) {
     return;
   }
 
   size_t expectedGhostSize =
-      static_cast<size_t>(capacity * config_.ghostSizePercent / 100);
+      static_cast<size_t>(lruSize * config_.ghostSizePercent / 100);
   ghostQueue_.resize(expectedGhostSize);
-  capacity_ = capacity;
+  capacity_ = lruSize;
 }
 
 // We have no notion of "reconfiguring lock"
@@ -623,7 +625,7 @@ template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 typename MMS3FIFO::Container<T, HookPtr>::LockedIterator
 MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() noexcept {
   LockHolder l(*lruMutex_);
-  maybeGrowGhostLocked();
+  maybeResizeGhostLocked();
   rebalanceForEviction();
   // Cache is full now so we know it's max size
   return LockedIterator{std::move(l), *this};

From 0566f6a1353a719396f85dc2a7d4a60a649f8f7a Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Tue, 2 Dec 2025 06:03:21 +0000
Subject: [PATCH 10/15] concurrent hash map for ghost

---
 cachelib/allocator/CMakeLists.txt             |  1 +
 cachelib/allocator/CacheAllocator.h           |  1 +
 .../allocator/CacheAllocatorS3FIFO5BCache.cpp | 21 ++++++
 cachelib/allocator/CacheTraits.h              |  7 ++
 cachelib/allocator/MMS3FIFO.h                 | 64 ++++++++++++----
 cachelib/common/FIFOConcurrentHashSet.h       | 70 +++++++++++++++++
 cachelib/common/FIFOHashSet.h                 | 75 ++++++-------------
 7 files changed, 170 insertions(+), 69 deletions(-)
 create mode 100644 cachelib/allocator/CacheAllocatorS3FIFO5BCache.cpp
 create mode 100644 cachelib/common/FIFOConcurrentHashSet.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..5defa7391e 100644
--- a/cachelib/allocator/CacheAllocator.h
+++ b/cachelib/allocator/CacheAllocator.h
@@ -6106,6 +6106,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..8bb8895f2e
--- /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>;
+}
diff --git a/cachelib/allocator/CacheTraits.h b/cachelib/allocator/CacheTraits.h
index 674d76e910..d8f03565a7 100644
--- a/cachelib/allocator/CacheTraits.h
+++ b/cachelib/allocator/CacheTraits.h
@@ -97,6 +97,13 @@ struct Lru5B2QCacheTrait {
   using CompressedPtrType = CompressedPtr5B;
 };
 
+struct S3FIFO5BCacheTrait {
+  using MMType = MMS3FIFO;
+  using AccessType = ChainedHashTable;
+  using AccessTypeLocks = SharedMutexBuckets;
+  using CompressedPtrType = CompressedPtr5B;
+};
+
 struct TinyLFU5BCacheTrait {
   using MMType = MMTinyLFU;
   using AccessType = ChainedHashTable;
diff --git a/cachelib/allocator/MMS3FIFO.h b/cachelib/allocator/MMS3FIFO.h
index 374afec8c7..35b967f700 100644
--- a/cachelib/allocator/MMS3FIFO.h
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -33,6 +33,7 @@
 #include "cachelib/allocator/memory/serialize/gen-cpp2/objects_types.h"
 #include "cachelib/common/CompilerUtils.h"
 #include "cachelib/common/FIFOHashSet.h"
+#include "cachelib/common/FIFOConcurrentHashSet.h"
 
 namespace facebook::cachelib {
 
@@ -112,8 +113,6 @@ class MMS3FIFO {
 
     // The size of ghost queue, as a percentage of total size
     size_t ghostSizePercent{90};
-
-    size_t reserveCapacity{0};
   };
 
   // The container object which can be used to keep track of objects of type
@@ -138,9 +137,6 @@ class MMS3FIFO {
     Container(Config c, PtrCompressor compressor)
         : lru_(LruType::NumTypes, std::move(compressor)),
           config_(std::move(c)) {
-            if (config_.reserveCapacity > 0) {
-              ghostQueue_.reserve(config_.reserveCapacity);
-            }
           }
     Container(serialization::MMS3FIFOObject object, PtrCompressor compressor);
 
@@ -216,7 +212,7 @@ class MMS3FIFO {
         ++it;
         // Skip accessed items
         skipAccessed(it);
-        return *this;
+        return *this; 
       }
 
       ListIterator& skipAccessed(ListIterator& it) noexcept {
@@ -389,10 +385,15 @@ class MMS3FIFO {
     void maybeResizeGhostLocked() noexcept;
 
     // Returns the hash of node's key
-    static size_t hashNode(const T& node) noexcept {
+    static size_t hashNode64(const T& node) noexcept {
       return folly::hasher<folly::StringPiece>()(node.getKey());
     }
 
+    static uint32_t hashNode(const T& node) noexcept {
+      return static_cast<uint32_t>(
+          folly::hasher<folly::StringPiece>()(node.getKey()));
+    }
+
     void removeLocked(T& node) noexcept;
 
     static bool isTiny(const T& node) noexcept {
@@ -432,7 +433,8 @@ class MMS3FIFO {
     // the lru
     LruList lru_;
 
-    facebook::cachelib::util::FIFOHashSet ghostQueue_;
+    facebook::cachelib::util::FIFOConcurrentHashSet32 ghostQueue_;
+    // facebook::cachelib::util::FIFOHashSet32 ghostQueue_;
 
     // Config for this lru.
     // Write access to the MMS3FIFO Config is serialized.
@@ -483,7 +485,7 @@ bool MMS3FIFO::Container<T, HookPtr>::recordAccess(T& node,
   }
   const auto currTime = static_cast<Time>(util::getCurrentTimeSec());
 
-  // Remove lock from record access wince we only set bits
+  // Remove lock from record access since we only set bits
   if (node.isInMMContainer()) {
     if (!isAccessed(node)) {
       markAccessed(node);
@@ -538,12 +540,12 @@ bool MMS3FIFO::Container<T, HookPtr>::add(T& node) noexcept {
   const auto currTime = static_cast<Time>(util::getCurrentTimeSec());
 
   const auto nodeHash = hashNode(node);
-  return lruMutex_->lock_combine([this, &node, currTime, nodeHash]() {
+  const auto ghostContains = ghostQueue_.contains(nodeHash);
+  return lruMutex_->lock_combine([this, &node, currTime, ghostContains]() {
     if (node.isInMMContainer()) {
       return false;
     }
 
-    const auto ghostContains = ghostQueue_.contains(nodeHash);
     if (ghostContains) {
       // Insert to main queue
       auto& mainLru = lru_.getList(LruType::Main);
@@ -625,6 +627,7 @@ template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 typename MMS3FIFO::Container<T, HookPtr>::LockedIterator
 MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() noexcept {
   LockHolder l(*lruMutex_);
+  // This is cheap
   maybeResizeGhostLocked();
   rebalanceForEviction();
   // Cache is full now so we know it's max size
@@ -643,13 +646,12 @@ void MMS3FIFO::Container<T, HookPtr>::withContainerLock(F&& fun) {
   lruMutex_->lock_combine([&fun]() { fun(); });
 }
 
+// Ghost queue insertion done on callee, outside lock
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 void MMS3FIFO::Container<T, HookPtr>::removeLocked(T& node) noexcept {
   if (isTiny(node)) {
     lru_.getList(LruType::Tiny).remove(node); 
     unmarkTiny(node);
-    // Insert into ghost queue upon eviction from tiny queue
-    ghostQueue_.insert(hashNode(node));
   } else {
     lru_.getList(LruType::Main).remove(node);
   }
@@ -661,21 +663,51 @@ void MMS3FIFO::Container<T, HookPtr>::removeLocked(T& node) noexcept {
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 bool MMS3FIFO::Container<T, HookPtr>::remove(T& node) noexcept {
-  return lruMutex_->lock_combine([this, &node]() {
+  bool isTiny_ = isTiny(node);
+  auto result = lruMutex_->lock_combine([this, &node]() {
     if (!node.isInMMContainer()) {
       return false;
     }
     removeLocked(node);
     return true;
   });
+  if (result && isTiny_) {
+    // Insert to ghost queue
+    ghostQueue_.insert(hashNode(node));
+  }
+  return result;
 }
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
 void MMS3FIFO::Container<T, HookPtr>::remove(LockedIterator& it) noexcept {
   T& node = *it;
   XDCHECK(node.isInMMContainer());
-  ++it; 
-  removeLocked(node);
+  ++it;
+
+  bool evictedFromTiny = false;
+  if (isTiny(node)) {
+    lru_.getList(LruType::Tiny).remove(node);
+    unmarkTiny(node);
+    evictedFromTiny = true;
+    // Insert into ghost queue upon eviction from tiny queue
+  } else {
+    lru_.getList(LruType::Main).remove(node);
+  }
+
+  unmarkAccessed(node);
+  node.unmarkInMMContainer();
+  
+  if (evictedFromTiny) {
+    // We need to insert to ghost queue. 
+    // Release lock early
+    // AFAIK every call to remove(locked itr) is followed by the iterator's destruction.
+    // If this is not the case, we may need to rethink this.
+    if (it.l_.owns_lock()) {
+      it.l_.unlock();
+    }
+    ghostQueue_.insert(hashNode(node));
+  }
+  return;
 }
 
 template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
diff --git a/cachelib/common/FIFOConcurrentHashSet.h b/cachelib/common/FIFOConcurrentHashSet.h
new file mode 100644
index 0000000000..8fa791517b
--- /dev/null
+++ b/cachelib/common/FIFOConcurrentHashSet.h
@@ -0,0 +1,70 @@
+
+#pragma once
+#include <folly/concurrency/ConcurrentHashMap.h>
+
+#include <atomic>
+#include <deque>
+#include <mutex>
+
+namespace facebook::cachelib::util {
+namespace detail {
+
+template <typename KeyT = uint32_t>
+class FIFOConcurrentHashSetBase {
+ public:
+  using Key = KeyT; // hashed object id
+  using TS = uint64_t;  // logical time / FIFO order
+
+  explicit FIFOConcurrentHashSetBase(size_t capacity)
+      : ghost_(capacity), seq_(0), queueSize_(0) {}
+
+  FIFOConcurrentHashSetBase() : seq_(0), queueSize_(0) {}
+
+  struct PendingEntry {
+    Key k;
+    TS ts;
+  };
+
+  inline void insert(Key k) {
+    TS ts = seq_.fetch_add(1, std::memory_order_relaxed);
+    ghost_.insert_or_assign(k, ts);
+    // If it overflows and wraps around, we reset the entire structure.
+    if (UNLIKELY(ts == std::numeric_limits<TS>::max())) {
+      ghost_.clear();
+    }
+  }
+
+  inline bool contains(Key k)  {
+    auto it = ghost_.find(k);
+    if (it == ghost_.end())
+      return false;
+    // Seq - current must be larger
+    auto currDiff = seq_.load(std::memory_order_relaxed) - it->second;
+    auto isValid = currDiff <= queueSize_.load(std::memory_order_relaxed);
+
+    if (!isValid) {
+      // remove stale entry
+      ghost_.erase(k);
+    }
+
+    return isValid;
+  }
+
+  inline void resize(TS limitTS) {
+    queueSize_.store(limitTS, std::memory_order_relaxed);
+  }
+
+ private:
+  folly::ConcurrentHashMap<Key, TS> ghost_;
+
+  // Logical TS counter
+  std::atomic<TS> seq_;
+  // Maximum size of the FIFO queue
+  std::atomic<TS> queueSize_;
+};
+
+} // namespace detail
+using FIFOConcurrentHashSet32 = detail::FIFOConcurrentHashSetBase<uint32_t>;
+using FIFOConcurrentHashSet64 = detail::FIFOConcurrentHashSetBase<uint64_t>;
+  
+} // namespace facebook::cachelib::util
\ No newline at end of file
diff --git a/cachelib/common/FIFOHashSet.h b/cachelib/common/FIFOHashSet.h
index de3387ca60..cadba8dc7a 100644
--- a/cachelib/common/FIFOHashSet.h
+++ b/cachelib/common/FIFOHashSet.h
@@ -3,11 +3,11 @@
 #include <folly/Format.h>
 #include <folly/Math.h>
 #include <folly/container/F14Set.h>
+#include <folly/synchronization/DistributedMutex.h>
 
 #include <cstdint>
 #include <deque>
 #include <stdexcept>
-#include <unordered_set>
 
 namespace facebook::cachelib::util {
 namespace detail {
@@ -26,87 +26,56 @@ class FIFOHashSetBase {
   FIFOHashSetBase(const FIFOHashSetBase&) = delete;
   FIFOHashSetBase& operator=(const FIFOHashSetBase&) = delete;
 
-  FIFOHashSetBase(FIFOHashSetBase&& other) noexcept {
-    maxSize_ = other.maxSize_;
-    fifo_ = std::move(other.fifo_);
-    set_ = std::move(other.set_);
-    other.maxSize_ = 0;
-  }
-
-  FIFOHashSetBase& operator=(FIFOHashSetBase&& other) noexcept {
-    if (this != &other) {
-      maxSize_ = other.maxSize_;
-      fifo_ = std::move(other.fifo_);
-      set_ = std::move(other.set_);
-      other.maxSize_ = 0;
-    }
-    return *this;
-  }
 
   bool contains(KeyT key) {
-    return set_.contains(key);
-  }
-
-  // Enforce size variant of contains
-  bool containsEnforce(KeyT key) {
-    enforceCapacityLocked();
-    return set_.contains(key);
+    return mutex_.lock_combine([&]() { return set_.contains(key); });
   }
 
   size_t size() {
-    return set_.size();
+    return mutex_.lock_combine([&]() { return set_.size(); });
   }
 
   size_t capacity() {
-    return maxSize_;
+    return mutex_.lock_combine([&]() { return maxSize_; });
   }
 
   void reserve(size_t newCap) {
-    set_.reserve(newCap);
+    mutex_.lock_combine([&]() { set_.reserve(newCap); });
   }
 
   void insert(KeyT key) {
-    auto [it, inserted] = set_.insert(key);
-    if (inserted) {
-      fifo_.push_back(key); 
-    }
-    enforceCapacityLocked();
-  }
-
-  // No enforce variant of insert
-  void insertNoEnforce(KeyT key) {
-    auto [it, inserted] = set_.insert(key);
-    if (inserted) {
-      fifo_.push_back(key);
-    }
+    mutex_.lock_combine([&]() {
+      auto [it, inserted] = set_.insert(key);
+      if (inserted) {
+        fifo_.push_back(key);
+      }
+      enforceCapacityLocked();
+    });
   }
 
   void resize(size_t newSize) {
-    maxSize_ = newSize;
-    enforceCapacityLocked();
-  }
-
-  // No enforce variant of resize
-  void resizeNoEnforce(size_t newSize) {
-    maxSize_ = newSize;
+    mutex_.lock_combine([&]() {
+      maxSize_ = newSize;
+    });
   }
 
  private:
-  // To prevent tail latency, limits max elements removed per call.
+  // Enforce max removal to control tail latency
   void enforceCapacityLocked() {
-    constexpr int max_rem = 5;
+    constexpr int max_rem = 2;
     int removed = 0;
 
     while (fifo_.size() > maxSize_ && removed < max_rem) {
       KeyT k = fifo_.front();
       fifo_.pop_front();
       set_.erase(k);
-      removed++;
+      ++removed;
     }
   }
 
  private:
-  // mutable folly::SpinLock lock_;
+  folly::DistributedMutex mutex_;
+
   size_t maxSize_{0};
   std::deque<KeyT> fifo_;
   folly::F14FastSet<KeyT> set_;
@@ -114,6 +83,6 @@ class FIFOHashSetBase {
 
 } // namespace detail
 
-using FIFOHashSet = detail::FIFOHashSetBase<uint64_t>;
+using FIFOHashSet32 = detail::FIFOHashSetBase<uint32_t>;
 
-} // namespace facebook::cachelib::util
+} // namespace facebook::cachelib::util
\ No newline at end of file

From c2265cd79ba2e265e1520383fb7a642c5e0bdcf7 Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Wed, 3 Dec 2025 01:13:42 +0000
Subject: [PATCH 11/15] No ghost, Cheap Evict

---
 cachelib/allocator/MMS3FIFO.h | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/cachelib/allocator/MMS3FIFO.h b/cachelib/allocator/MMS3FIFO.h
index 35b967f700..31998079b3 100644
--- a/cachelib/allocator/MMS3FIFO.h
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -210,12 +210,12 @@ class MMS3FIFO {
           return *this;
         }
         ++it;
-        // Skip accessed items
-        skipAccessed(it);
+        // // Skip accessed items
+        // skipAccessed(it);
         return *this; 
       }
 
-      ListIterator& skipAccessed(ListIterator& it) noexcept {
+      void skipAccessed(ListIterator& it) noexcept {
         while (it) {
           T& node = *it;
           if (!Container<T, HookPtr>::isAccessed(node)) {
@@ -223,7 +223,6 @@ class MMS3FIFO {
           }
           ++it; // skip this accessed item
         }
-        return it;
       }
 
       LockedIterator& operator--() {
@@ -469,7 +468,7 @@ void MMS3FIFO::Container<T, HookPtr>::maybeResizeGhostLocked() noexcept {
 
   size_t expectedGhostSize =
       static_cast<size_t>(lruSize * config_.ghostSizePercent / 100);
-  ghostQueue_.resize(expectedGhostSize);
+  // ghostQueue_.resize(expectedGhostSize);
   capacity_ = lruSize;
 }
 
@@ -540,7 +539,8 @@ bool MMS3FIFO::Container<T, HookPtr>::add(T& node) noexcept {
   const auto currTime = static_cast<Time>(util::getCurrentTimeSec());
 
   const auto nodeHash = hashNode(node);
-  const auto ghostContains = ghostQueue_.contains(nodeHash);
+  // auto ghostContains = ghostQueue_.contains(nodeHash);
+  auto ghostContains = false;
   return lruMutex_->lock_combine([this, &node, currTime, ghostContains]() {
     if (node.isInMMContainer()) {
       return false;
@@ -579,9 +579,16 @@ void MMS3FIFO::Container<T, HookPtr>::rebalanceForEviction() {
   auto expectedTinySize =
       static_cast<size_t>(config_.tinySizePercent * totalSize / 100);
 
+  auto rebalanceLimit = 5;
+  auto rebalanceCount = 0;
+
   // Promote until we find a victim, so iterator won't have to mutate the lists
   while (true) {
     bool tryTiny = tinyLru.size() >= expectedTinySize;
+    rebalanceCount++;
+    if (rebalanceCount > rebalanceLimit) {
+      break;
+    }
 
     if (tryTiny) {
       // Tail of T
@@ -672,8 +679,8 @@ bool MMS3FIFO::Container<T, HookPtr>::remove(T& node) noexcept {
     return true;
   });
   if (result && isTiny_) {
-    // Insert to ghost queue
-    ghostQueue_.insert(hashNode(node));
+    // // Insert to ghost queue
+    // ghostQueue_.insert(hashNode(node));
   }
   return result;
 }
@@ -705,7 +712,7 @@ void MMS3FIFO::Container<T, HookPtr>::remove(LockedIterator& it) noexcept {
     if (it.l_.owns_lock()) {
       it.l_.unlock();
     }
-    ghostQueue_.insert(hashNode(node));
+    // ghostQueue_.insert(hashNode(node));
   }
   return;
 }

From 492cf8b5c8c74fceb334ed6c34d96c27877f83b5 Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Wed, 3 Dec 2025 01:15:03 +0000
Subject: [PATCH 12/15] With Ghost, Cheap Evict

---
 cachelib/allocator/MMS3FIFO.h | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/cachelib/allocator/MMS3FIFO.h b/cachelib/allocator/MMS3FIFO.h
index 31998079b3..cffbe0b34a 100644
--- a/cachelib/allocator/MMS3FIFO.h
+++ b/cachelib/allocator/MMS3FIFO.h
@@ -468,7 +468,7 @@ void MMS3FIFO::Container<T, HookPtr>::maybeResizeGhostLocked() noexcept {
 
   size_t expectedGhostSize =
       static_cast<size_t>(lruSize * config_.ghostSizePercent / 100);
-  // ghostQueue_.resize(expectedGhostSize);
+  ghostQueue_.resize(expectedGhostSize);
   capacity_ = lruSize;
 }
 
@@ -539,8 +539,7 @@ bool MMS3FIFO::Container<T, HookPtr>::add(T& node) noexcept {
   const auto currTime = static_cast<Time>(util::getCurrentTimeSec());
 
   const auto nodeHash = hashNode(node);
-  // auto ghostContains = ghostQueue_.contains(nodeHash);
-  auto ghostContains = false;
+  auto ghostContains = ghostQueue_.contains(nodeHash);
   return lruMutex_->lock_combine([this, &node, currTime, ghostContains]() {
     if (node.isInMMContainer()) {
       return false;
@@ -680,7 +679,7 @@ bool MMS3FIFO::Container<T, HookPtr>::remove(T& node) noexcept {
   });
   if (result && isTiny_) {
     // // Insert to ghost queue
-    // ghostQueue_.insert(hashNode(node));
+    ghostQueue_.insert(hashNode(node));
   }
   return result;
 }
@@ -712,7 +711,7 @@ void MMS3FIFO::Container<T, HookPtr>::remove(LockedIterator& it) noexcept {
     if (it.l_.owns_lock()) {
       it.l_.unlock();
     }
-    // ghostQueue_.insert(hashNode(node));
+    ghostQueue_.insert(hashNode(node));
   }
   return;
 }

From cbeee43c7183fb1f5b11911d57baec3821336303 Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Fri, 5 Dec 2025 14:44:28 +0000
Subject: [PATCH 13/15] incremental feature files

---
 cachelib/allocator/MMS3FIFO_v0.h | 605 +++++++++++++++++++++++++++
 cachelib/allocator/MMS3FIFO_v1.h | 653 +++++++++++++++++++++++++++++
 cachelib/allocator/MMS3FIFO_v2.h | 688 +++++++++++++++++++++++++++++++
 3 files changed, 1946 insertions(+)
 create mode 100644 cachelib/allocator/MMS3FIFO_v0.h
 create mode 100644 cachelib/allocator/MMS3FIFO_v1.h
 create mode 100644 cachelib/allocator/MMS3FIFO_v2.h

diff --git a/cachelib/allocator/MMS3FIFO_v0.h b/cachelib/allocator/MMS3FIFO_v0.h
new file mode 100644
index 0000000000..a6a5c3925d
--- /dev/null
+++ b/cachelib/allocator/MMS3FIFO_v0.h
@@ -0,0 +1,605 @@
+/*
+ * 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>
+#include <folly/Math.h>
+#pragma GCC diagnostic pop
+
+#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 {
+// MMS3FIFOV0
+// This version is TinyLFU stripped down to basic FIFO functionality
+// Notes include:
+// 1. No lock in recordAccess
+class MMS3FIFO {
+ public:
+  // unique identifier per MMType
+  static const int kId;
+
+  // forward declaration;
+  template <typename T>
+  using Hook = DListHook<T>;
+  using SerializationType = serialization::MMS3FIFOObject;
+  using SerializationConfigType = serialization::MMS3FIFOConfig;
+  using SerializationTypeContainer = serialization::MMS3FIFOCollection;
+
+  enum LruType { Main, Tiny, NumTypes };
+
+  // Config class for MMS3FIFO
+  struct Config {
+    // create from serialized config
+    explicit Config(SerializationConfigType configState)
+        : Config(*configState.updateOnWrite(),
+                 *configState.updateOnRead(),
+                 *configState.tinySizePercent(),
+                 *configState.ghostSizePercent()) {}
+
+    // @param udpateOnW   whether to promote the item on write
+    // @param updateOnR   whether to promote the item on read
+    Config(bool updateOnW, bool updateOnR)
+        : Config(updateOnW, updateOnR, 10, 90) {}
+
+    // @param udpateOnW         whether to promote the item on write
+    // @param updateOnR         whether to promote the item on read
+    // @param tinySizePercent   percentage number of tiny size to overall size
+    // @param ghostSizePercent  percentage number of ghost size to main size
+    Config(bool updateOnW,
+           bool updateOnR,
+           size_t tinySizePercent,
+           size_t ghostSizePercent)
+        : updateOnWrite(updateOnW),
+          updateOnRead(updateOnR),
+          tinySizePercent(tinySizePercent),
+          ghostSizePercent(ghostSizePercent) {}
+
+    Config() = default;
+    Config(const Config& rhs) = default;
+    Config(Config&& rhs) = default;
+
+    Config& operator=(const Config& rhs) = default;
+    Config& operator=(Config&& rhs) = default;
+
+    template <typename... Args>
+    void addExtraConfig(Args...) {}
+
+    // whether the lru needs to be updated on writes for recordAccess. If
+    // false, accessing the cache for writes does not promote the cached item
+    // to the head of the lru.
+    bool updateOnWrite{false};
+
+    // whether the lru needs to be updated on reads for recordAccess. If
+    // false, accessing the cache for reads does not promote the cached item
+    // to the head of the lru.
+    bool updateOnRead{true};
+
+    // The size of tiny cache, as a percentage of the total size.
+    size_t tinySizePercent{10};
+
+    size_t ghostSizePercent{90};
+  };
+
+  // The container object which can be used to keep track of objects of type
+  // T. T must have a public member of type Hook. This object is wrapper
+  // around DList, is thread safe and can be accessed from multiple threads.
+  // The current implementation models an LRU using the above DList
+  // implementation.
+  template <typename T, Hook<T> T::* HookPtr>
+  struct Container {
+   private:
+    using LruList = MultiDList<T, HookPtr>;
+    using Mutex = folly::SpinLock;
+    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;
+
+    // records the information that the node was accessed. This could bump up
+    // the node to the head of the lru depending on the time when the node was
+    // last updated in lru and the kLruRefreshTime. If the node was moved to
+    // the head in the lru, the node's updateTime will be updated
+    // accordingly.
+    //
+    // @param node  node that we want to mark as relevant/accessed
+    // @param mode  the mode for the access operation.
+    //
+    // @return      True if the information is recorded and bumped the node
+    //              to the head of the lru, returns false otherwise
+    bool recordAccess(T& node, AccessMode mode) noexcept;
+
+    // adds the given node into the container and marks it as being present in
+    // the container. The node is added to the head of the lru.
+    //
+    // @param node  The node to be added to the container.
+    // @return  True if the node was successfully added to the container. False
+    //          if the node was already in the contianer. On error state of node
+    //          is unchanged.
+    bool add(T& node) noexcept;
+
+    // removes the node from the lru and sets it previous and next to nullptr.
+    //
+    // @param node  The node to be removed from the container.
+    // @return  True if the node was successfully removed from the container.
+    //          False if the node was not part of the container. On error, the
+    //          state of node is unchanged.
+    bool remove(T& node) noexcept;
+
+    class LockedIterator;
+    // same as the above but uses an iterator context. The iterator is updated
+    // on removal of the corresponding node to point to the next node. The
+    // iterator context holds the lock on the lru.
+    //
+    // iterator will be advanced to the next node after removing the node
+    //
+    // @param it    Iterator that will be removed
+    void remove(LockedIterator& it) noexcept;
+
+    // replaces one node with another, at the same position
+    //
+    // @param oldNode   node being replaced
+    // @param newNode   node to replace oldNode with
+    //
+    // @return true  If the replace was successful. Returns false if the
+    //               destination node did not exist in the container, or if the
+    //               source node already existed.
+    bool replace(T& oldNode, T& newNode) noexcept;
+
+    // context for iterating the MM container. At any given point of time,
+    // there can be only one iterator active since we need to lock the LRU for
+    // iteration. we can support multiple iterators at same time, by using a
+    // shared ptr in the context for the lock holder in the future.
+    class LockedIterator {
+     public:
+      using ListIterator = typename LruList::DListIterator;
+      // noncopyable but movable.
+      LockedIterator(const LockedIterator&) = delete;
+      LockedIterator& operator=(const LockedIterator&) = delete;
+      LockedIterator(LockedIterator&&) noexcept = default;
+
+      LockedIterator& operator++() noexcept {
+        ++getIter();
+        return *this;
+      }
+
+      LockedIterator& operator--() {
+        throw std::invalid_argument(
+            "Decrementing eviction iterator is not supported");
+      }
+
+      T* operator->() const noexcept { return getIter().operator->(); }
+      T& operator*() const noexcept { return getIter().operator*(); }
+
+      bool operator==(const LockedIterator& other) const noexcept {
+        return &c_ == &other.c_ && tIter_ == other.tIter_ &&
+               mIter_ == other.mIter_;
+      }
+
+      bool operator!=(const LockedIterator& other) const noexcept {
+        return !(*this == other);
+      }
+
+      explicit operator bool() const noexcept { return tIter_ || mIter_; }
+
+      T* get() const noexcept { return getIter().get(); }
+
+      // Invalidates this iterator
+      void reset() noexcept {
+        // Point iterator to first list's rend
+        tIter_.reset();
+        mIter_.reset();
+      }
+
+      // 1. Invalidate this iterator
+      // 2. Unlock
+      void destroy() {
+        reset();
+        if (l_.owns_lock()) {
+          l_.unlock();
+        }
+      }
+
+      // Reset this iterator to the beginning
+      void resetToBegin() {
+        if (!l_.owns_lock()) {
+          l_.lock();
+        }
+        tIter_.resetToBegin();
+        mIter_.resetToBegin();
+      }
+
+     private:
+      // private because it's easy to misuse and cause deadlock for MMS3FIFO
+      LockedIterator& operator=(LockedIterator&&) noexcept = default;
+
+      // create an lru iterator with the lock being held.
+      explicit LockedIterator(LockHolder l,
+                              const Container<T, HookPtr>& c) noexcept;
+
+      const ListIterator& getIter() const noexcept {
+        return evictTiny() ? tIter_ : mIter_;
+      }
+
+      ListIterator& getIter() noexcept {
+        return const_cast<ListIterator&>(
+            static_cast<const LockedIterator*>(this)->getIter());
+      }
+
+      bool evictTiny() const noexcept {
+        if (!mIter_) {
+          return true;
+        }
+        if (!tIter_) {
+          return false;
+        }
+
+        const auto expectedSize =
+            c_.config_.tinySizePercent * c_.lru_.size() / 100;
+        auto isTinyBig = c_.lru_.getList(LruType::Tiny).size() > expectedSize;
+        return isTinyBig;
+      }
+
+      // only the container can create iterators
+      friend Container<T, HookPtr>;
+
+      const Container<T, HookPtr>& c_;
+      // Tiny and main cache iterators
+      ListIterator tIter_;
+      ListIterator mIter_;
+      // lock protecting the validity of the iterator
+      LockHolder l_;
+    };
+
+    Config getConfig() const;
+
+    void setConfig(const Config& newConfig);
+
+    bool isEmpty() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size() == 0;
+    }
+
+    size_t size() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size();
+    }
+
+    // Returns the eviction age stats. See CacheStats.h for details
+    EvictionAgeStat getEvictionAgeStat(uint64_t projectedLength) const noexcept;
+
+    // Obtain an iterator that start from the tail and can be used
+    // to search for evictions. This iterator holds a lock to this
+    // container and only one such iterator can exist at a time
+    LockedIterator getEvictionIterator() const noexcept;
+
+    // Execute provided function under container lock. Function gets
+    // iterator passed as parameter.
+    template <typename F>
+    void withEvictionIterator(F&& f);
+
+    // Execute provided function under container lock.
+    template <typename F>
+    void withContainerLock(F&& f);
+
+    // for saving the state of the lru
+    //
+    // precondition:  serialization must happen without any reader or writer
+    // present. Any modification of this object afterwards will result in an
+    // invalid, inconsistent state for the serialized data.
+    //
+    serialization::MMS3FIFOObject saveState() const noexcept;
+
+    // return the stats for this container.
+    MMContainerStat getStats() const noexcept;
+
+    static LruType getLruType(const T& node) noexcept {
+      return isTiny(node) ? LruType::Tiny : 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);
+    }
+
+    // Returns the hash of node's key
+    static size_t hashNode(const T& node) noexcept {
+      return folly::hasher<folly::StringPiece>()(node.getKey());
+    }
+
+    // remove node from lru and adjust insertion points
+    //
+    // @param node          node to remove
+    void removeLocked(T& node) noexcept;
+
+    static bool isTiny(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag0>();
+    }
+
+    static bool isAccessed(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag1>();
+    }
+
+    // Bit MM_BIT_0 is used to record if the item is in tiny cache.
+    static void markTiny(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag0>();
+    }
+    static void unmarkTiny(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag0>();
+    }
+
+    // Bit MM_BIT_1 is used to record if the item has been accessed since being
+    // written in cache. Unaccessed items are ignored when determining projected
+    // update time.
+    static void markAccessed(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag1>();
+    }
+    static void unmarkAccessed(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag1>();
+    }
+
+    mutable Mutex lruMutex_;
+
+    // the lru
+    LruList lru_;
+
+    // Current capacity to track ghost size
+    size_t capacity_{0};
+
+    // Config for this lru.
+    // Write access to the MMS3FIFO Config is serialized.
+    // Reads may be racy.
+    Config config_{};
+
+    // FRIEND_TEST(MMTinyLFUTest, SegmentStress);
+    // FRIEND_TEST(MMTinyLFUTest, TinyLFUBasic);
+    // FRIEND_TEST(MMTinyLFUTest, Reconfigure);
+  };
+};
+
+/* 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());
+  // check if the node is still being memory managed
+  if (node.isInMMContainer() && !isAccessed(node)) {
+    markAccessed(node);
+    setUpdateTime(node, curr);
+    return true;
+  }
+  return false;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+cachelib::EvictionAgeStat MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStat(
+    uint64_t projectedLength) const noexcept {
+  LockHolder l(lruMutex_);
+  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 curr = static_cast<Time>(util::getCurrentTimeSec());
+
+  auto& list = lru_.getList(LruType::Main);
+  auto it = list.rbegin();
+  stat.warmQueueStat.oldestElementAge =
+      it != list.rend() ? curr - 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()
+                                        ? curr - getUpdateTime(*it)
+                                        : stat.warmQueueStat.oldestElementAge;
+  return stat;
+}
+
+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());
+  LockHolder l(lruMutex_);
+  if (node.isInMMContainer()) {
+    return false;
+  }
+
+  auto& tinyLru = lru_.getList(LruType::Tiny);
+  tinyLru.linkAtHead(node);
+  markTiny(node);
+
+  // If tiny cache is full, unconditionally promote tail to main cache.
+  const auto expectedSize = config_.tinySizePercent * lru_.size() / 100;
+  if (lru_.getList(LruType::Tiny).size() > expectedSize) {
+    auto tailNode = tinyLru.getTail();
+    tinyLru.remove(*tailNode);
+
+    auto& mainLru = lru_.getList(LruType::Main);
+    mainLru.linkAtHead(*tailNode);
+    unmarkTiny(*tailNode);
+  }
+
+  node.markInMMContainer();
+  setUpdateTime(node, currTime);
+  unmarkAccessed(node);
+  return true;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+typename MMS3FIFO::Container<T, HookPtr>::LockedIterator
+MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() const noexcept {
+  LockHolder l(lruMutex_);
+  return LockedIterator{std::move(l), *this};
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+template <typename F>
+void MMS3FIFO::Container<T, HookPtr>::withEvictionIterator(F&& fun) {
+  // uses spin lock which does not support combined locking
+  fun(getEvictionIterator());
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+template <typename F>
+void MMS3FIFO::Container<T, HookPtr>::withContainerLock(F&& fun) {
+  LockHolder l(lruMutex_);
+  fun();
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::removeLocked(T& node) noexcept {
+  if (isTiny(node)) {
+    lru_.getList(LruType::Tiny).remove(node);
+    unmarkTiny(node);
+  } else {
+    lru_.getList(LruType::Main).remove(node);
+  }
+
+  unmarkAccessed(node);
+  node.unmarkInMMContainer();
+  return;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+bool MMS3FIFO::Container<T, HookPtr>::remove(T& node) noexcept {
+  LockHolder l(lruMutex_);
+  if (!node.isInMMContainer()) {
+    return false;
+  }
+  removeLocked(node);
+  return true;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::remove(LockedIterator& 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 {
+  LockHolder l(lruMutex_);
+  if (!oldNode.isInMMContainer() || newNode.isInMMContainer()) {
+    return false;
+  }
+  const auto updateTime = getUpdateTime(oldNode);
+
+  if (isTiny(oldNode)) {
+    lru_.getList(LruType::Tiny).replace(oldNode, newNode);
+    unmarkTiny(oldNode);
+    markTiny(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 {
+  LockHolder l(lruMutex_);
+  return config_;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::setConfig(const Config& c) {
+  LockHolder l(lruMutex_);
+  config_ = c;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+serialization::MMS3FIFOObject MMS3FIFO::Container<T, HookPtr>::saveState()
+    const noexcept {
+  serialization::MMS3FIFOConfig configObject;
+  *configObject.updateOnWrite() = config_.updateOnWrite;
+  *configObject.updateOnRead() = config_.updateOnRead;
+  *configObject.ghostSizePercent() = config_.ghostSizePercent;
+  *configObject.tinySizePercent() = config_.tinySizePercent;
+  // TODO: Serialize the ghost queue too.
+  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 {
+  LockHolder l(lruMutex_);
+  auto* tail = lru_.size() == 0 ? nullptr : lru_.rbegin().get();
+  return {
+      lru_.size(), tail == nullptr ? 0 : getUpdateTime(*tail), 0, 0, 0, 0, 0};
+}
+
+// Locked Iterator Context Implementation
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+MMS3FIFO::Container<T, HookPtr>::LockedIterator::LockedIterator(
+    LockHolder l, const Container<T, HookPtr>& c) noexcept
+    : c_(c),
+      tIter_(c.lru_.getList(LruType::Tiny).rbegin()),
+      mIter_(c.lru_.getList(LruType::Main).rbegin()),
+      l_(std::move(l)) {}
+} // namespace facebook::cachelib
diff --git a/cachelib/allocator/MMS3FIFO_v1.h b/cachelib/allocator/MMS3FIFO_v1.h
new file mode 100644
index 0000000000..9550bb1869
--- /dev/null
+++ b/cachelib/allocator/MMS3FIFO_v1.h
@@ -0,0 +1,653 @@
+/*
+ * 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>
+#include <folly/Math.h>
+#pragma GCC diagnostic pop
+
+#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 {
+// MM S3FIFO V1
+// This version modifies v0 and introduces a promotion policy.
+// Only items that are unaccessed will be evicted
+// Iterator will skip accessed items during eviction search
+class MMS3FIFO {
+ public:
+  // unique identifier per MMType
+  static const int kId;
+
+  // forward declaration;
+  template <typename T>
+  using Hook = DListHook<T>;
+  using SerializationType = serialization::MMS3FIFOObject;
+  using SerializationConfigType = serialization::MMS3FIFOConfig;
+  using SerializationTypeContainer = serialization::MMS3FIFOCollection;
+
+  enum LruType { Main, Tiny, NumTypes };
+
+  // Config class for MMS3FIFO
+  struct Config {
+    // create from serialized config
+    explicit Config(SerializationConfigType configState)
+        : Config(*configState.updateOnWrite(),
+                 *configState.updateOnRead(),
+                 *configState.tinySizePercent(),
+                 *configState.ghostSizePercent()) {}
+
+    // @param udpateOnW   whether to promote the item on write
+    // @param updateOnR   whether to promote the item on read
+    Config(bool updateOnW, bool updateOnR)
+        : Config(updateOnW, updateOnR, 10, 90) {}
+
+    // @param udpateOnW         whether to promote the item on write
+    // @param updateOnR         whether to promote the item on read
+    // @param tinySizePercent   percentage number of tiny size to overall size
+    // @param ghostSizePercent  percentage number of ghost size to main size
+    Config(bool updateOnW,
+           bool updateOnR,
+           size_t tinySizePercent,
+           size_t ghostSizePercent)
+        : updateOnWrite(updateOnW),
+          updateOnRead(updateOnR),
+          tinySizePercent(tinySizePercent),
+          ghostSizePercent(ghostSizePercent) {}
+
+    Config() = default;
+    Config(const Config& rhs) = default;
+    Config(Config&& rhs) = default;
+
+    Config& operator=(const Config& rhs) = default;
+    Config& operator=(Config&& rhs) = default;
+
+    template <typename... Args>
+    void addExtraConfig(Args...) {}
+
+    // whether the lru needs to be updated on writes for recordAccess. If
+    // false, accessing the cache for writes does not promote the cached item
+    // to the head of the lru.
+    bool updateOnWrite{false};
+
+    // whether the lru needs to be updated on reads for recordAccess. If
+    // false, accessing the cache for reads does not promote the cached item
+    // to the head of the lru.
+    bool updateOnRead{true};
+
+    // The size of tiny cache, as a percentage of the total size.
+    size_t tinySizePercent{10};
+
+    size_t ghostSizePercent{90};
+  };
+
+  // The container object which can be used to keep track of objects of type
+  // T. T must have a public member of type Hook. This object is wrapper
+  // around DList, is thread safe and can be accessed from multiple threads.
+  // The current implementation models an LRU using the above DList
+  // implementation.
+  template <typename T, Hook<T> T::* HookPtr>
+  struct Container {
+   private:
+    using LruList = MultiDList<T, HookPtr>;
+    using Mutex = folly::SpinLock;
+    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;
+
+    // records the information that the node was accessed. This could bump up
+    // the node to the head of the lru depending on the time when the node was
+    // last updated in lru and the kLruRefreshTime. If the node was moved to
+    // the head in the lru, the node's updateTime will be updated
+    // accordingly.
+    //
+    // @param node  node that we want to mark as relevant/accessed
+    // @param mode  the mode for the access operation.
+    //
+    // @return      True if the information is recorded and bumped the node
+    //              to the head of the lru, returns false otherwise
+    bool recordAccess(T& node, AccessMode mode) noexcept;
+
+    // adds the given node into the container and marks it as being present in
+    // the container. The node is added to the head of the lru.
+    //
+    // @param node  The node to be added to the container.
+    // @return  True if the node was successfully added to the container. False
+    //          if the node was already in the contianer. On error state of node
+    //          is unchanged.
+    bool add(T& node) noexcept;
+
+    // removes the node from the lru and sets it previous and next to nullptr.
+    //
+    // @param node  The node to be removed from the container.
+    // @return  True if the node was successfully removed from the container.
+    //          False if the node was not part of the container. On error, the
+    //          state of node is unchanged.
+    bool remove(T& node) noexcept;
+
+    class LockedIterator;
+    // same as the above but uses an iterator context. The iterator is updated
+    // on removal of the corresponding node to point to the next node. The
+    // iterator context holds the lock on the lru.
+    //
+    // iterator will be advanced to the next node after removing the node
+    //
+    // @param it    Iterator that will be removed
+    void remove(LockedIterator& it) noexcept;
+
+    // replaces one node with another, at the same position
+    //
+    // @param oldNode   node being replaced
+    // @param newNode   node to replace oldNode with
+    //
+    // @return true  If the replace was successful. Returns false if the
+    //               destination node did not exist in the container, or if the
+    //               source node already existed.
+    bool replace(T& oldNode, T& newNode) noexcept;
+
+    // context for iterating the MM container. At any given point of time,
+    // there can be only one iterator active since we need to lock the LRU for
+    // iteration. we can support multiple iterators at same time, by using a
+    // shared ptr in the context for the lock holder in the future.
+    class LockedIterator {
+     public:
+      using ListIterator = typename LruList::DListIterator;
+      // noncopyable but movable.
+      LockedIterator(const LockedIterator&) = delete;
+      LockedIterator& operator=(const LockedIterator&) = delete;
+      LockedIterator(LockedIterator&&) noexcept = default;
+
+      LockedIterator& operator++() noexcept {
+        auto it = ++getIter();
+        skipAccessed(it);
+        return *this;
+      }
+
+      void skipAccessed(ListIterator& it) noexcept {
+        while (it) {
+          T& node = *it;
+          if (!Container<T, HookPtr>::isAccessed(node)) {
+            break; // found a valid eviction victim
+          }
+          ++it; // skip this accessed item
+        }
+      }
+
+      LockedIterator& operator--() {
+        throw std::invalid_argument(
+            "Decrementing eviction iterator is not supported");
+      }
+
+      T* operator->() const noexcept { return getIter().operator->(); }
+      T& operator*() const noexcept { return getIter().operator*(); }
+
+      bool operator==(const LockedIterator& other) const noexcept {
+        return &c_ == &other.c_ && tIter_ == other.tIter_ &&
+               mIter_ == other.mIter_;
+      }
+
+      bool operator!=(const LockedIterator& other) const noexcept {
+        return !(*this == other);
+      }
+
+      explicit operator bool() const noexcept { return tIter_ || mIter_; }
+
+      T* get() const noexcept { return getIter().get(); }
+
+      // Invalidates this iterator
+      void reset() noexcept {
+        // Point iterator to first list's rend
+        tIter_.reset();
+        mIter_.reset();
+      }
+
+      // 1. Invalidate this iterator
+      // 2. Unlock
+      void destroy() {
+        reset();
+        if (l_.owns_lock()) {
+          l_.unlock();
+        }
+      }
+
+      // Reset this iterator to the beginning
+      void resetToBegin() {
+        if (!l_.owns_lock()) {
+          l_.lock();
+        }
+        tIter_.resetToBegin();
+        mIter_.resetToBegin();
+      }
+
+     private:
+      // private because it's easy to misuse and cause deadlock for MMS3FIFO
+      LockedIterator& operator=(LockedIterator&&) noexcept = default;
+
+      // create an lru iterator with the lock being held.
+      explicit LockedIterator(LockHolder l,
+                              const Container<T, HookPtr>& c) noexcept;
+
+      const ListIterator& getIter() const noexcept {
+        return evictTiny() ? tIter_ : mIter_;
+      }
+
+      ListIterator& getIter() noexcept {
+        return const_cast<ListIterator&>(
+            static_cast<const LockedIterator*>(this)->getIter());
+      }
+
+      bool evictTiny() const noexcept {
+        if (!mIter_) {
+          return true;
+        }
+        if (!tIter_) {
+          return false;
+        }
+
+        const auto expectedSize =
+            c_.config_.tinySizePercent * c_.lru_.size() / 100;
+        auto isTinyBig = c_.lru_.getList(LruType::Tiny).size() > expectedSize;
+        return isTinyBig;
+      }
+
+      // only the container can create iterators
+      friend Container<T, HookPtr>;
+
+      const Container<T, HookPtr>& c_;
+      // Tiny and main cache iterators
+      ListIterator tIter_;
+      ListIterator mIter_;
+      // lock protecting the validity of the iterator
+      LockHolder l_;
+    };
+
+    Config getConfig() const;
+
+    void setConfig(const Config& newConfig);
+
+    bool isEmpty() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size() == 0;
+    }
+
+    size_t size() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size();
+    }
+
+    // Returns the eviction age stats. See CacheStats.h for details
+    EvictionAgeStat getEvictionAgeStat(uint64_t projectedLength) const noexcept;
+
+    // Obtain an iterator that start from the tail and can be used
+    // to search for evictions. This iterator holds a lock to this
+    // container and only one such iterator can exist at a time
+    LockedIterator getEvictionIterator() noexcept;
+
+    // Execute provided function under container lock. Function gets
+    // iterator passed as parameter.
+    template <typename F>
+    void withEvictionIterator(F&& f);
+
+    // Execute provided function under container lock.
+    template <typename F>
+    void withContainerLock(F&& f);
+
+    // for saving the state of the lru
+    //
+    // precondition:  serialization must happen without any reader or writer
+    // present. Any modification of this object afterwards will result in an
+    // invalid, inconsistent state for the serialized data.
+    //
+    serialization::MMS3FIFOObject saveState() const noexcept;
+
+    // return the stats for this container.
+    MMContainerStat getStats() const noexcept;
+
+    static LruType getLruType(const T& node) noexcept {
+      return isTiny(node) ? LruType::Tiny : 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);
+    }
+
+    // Returns the hash of node's key
+    static size_t hashNode(const T& node) noexcept {
+      return folly::hasher<folly::StringPiece>()(node.getKey());
+    }
+
+    // remove node from lru and adjust insertion points
+    //
+    // @param node          node to remove
+    void removeLocked(T& node) noexcept;
+
+    static bool isTiny(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag0>();
+    }
+
+    static bool isAccessed(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag1>();
+    }
+
+    // Bit MM_BIT_0 is used to record if the item is in tiny cache.
+    static void markTiny(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag0>();
+    }
+    static void unmarkTiny(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag0>();
+    }
+
+    // Bit MM_BIT_1 is used to record if the item has been accessed since being
+    // written in cache. Unaccessed items are ignored when determining projected
+    // update time.
+    static void markAccessed(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag1>();
+    }
+    static void unmarkAccessed(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag1>();
+    }
+
+    void rebalanceForEviction();
+
+    mutable Mutex lruMutex_;
+
+    // the lru
+    LruList lru_;
+
+    // Current capacity to track ghost size
+    size_t capacity_{0};
+
+    // Config for this lru.
+    // Write access to the MMS3FIFO Config is serialized.
+    // Reads may be racy.
+    Config config_{};
+
+    // FRIEND_TEST(MMTinyLFUTest, SegmentStress);
+    // FRIEND_TEST(MMTinyLFUTest, TinyLFUBasic);
+    // FRIEND_TEST(MMTinyLFUTest, Reconfigure);
+  };
+};
+
+/* 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());
+  // check if the node is still being memory managed
+  if (node.isInMMContainer() && !isAccessed(node)) {
+    markAccessed(node);
+    setUpdateTime(node, curr);
+    return true;
+  }
+  return false;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+cachelib::EvictionAgeStat MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStat(
+    uint64_t projectedLength) const noexcept {
+  LockHolder l(lruMutex_);
+  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 curr = static_cast<Time>(util::getCurrentTimeSec());
+
+  auto& list = lru_.getList(LruType::Main);
+  auto it = list.rbegin();
+  stat.warmQueueStat.oldestElementAge =
+      it != list.rend() ? curr - 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()
+                                        ? curr - getUpdateTime(*it)
+                                        : stat.warmQueueStat.oldestElementAge;
+  return stat;
+}
+
+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());
+  LockHolder l(lruMutex_);
+  if (node.isInMMContainer()) {
+    return false;
+  }
+
+  auto& tinyLru = lru_.getList(LruType::Tiny);
+  tinyLru.linkAtHead(node);
+
+  markTiny(node);
+  unmarkAccessed(node);
+  setUpdateTime(node, currTime);
+
+  node.markInMMContainer();
+  return true;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::rebalanceForEviction() {
+    // Bulk move accessed items from tiny to main cache
+    // Until tinycache's tail is unaccessed or tiny cache is within size limit
+    // Room for optimization:
+    // We can bulk move segments to main instead of one by one
+    auto& tinyLru = lru_.getList(LruType::Tiny);
+    auto& mainLru = lru_.getList(LruType::Main);
+
+    bool isTinyTailUnaccessed = false;
+    const auto expectedSize = config_.tinySizePercent * lru_.size() / 100;
+    while (!isTinyTailUnaccessed) {
+        if (tinyLru.size() <= expectedSize) {
+            break;
+        }
+        auto tailNode = tinyLru.getTail();
+        if (tailNode == nullptr || !isAccessed(*tailNode)) {
+            isTinyTailUnaccessed = true;
+            break;
+        }
+        tinyLru.remove(*tailNode);
+
+        mainLru.linkAtHead(*tailNode);
+        unmarkTiny(*tailNode);
+        unmarkAccessed(*tailNode);
+    }
+
+    // Reinsert items in main cache to head, until main cache's tail is unaccessed
+    // TODO: Room for optimization: 
+    // We can get the position of first unaccessed item from the tail
+    // And move the whole segment to head in one operation
+    bool isMainTailUnaccessed = false;
+    while (!isMainTailUnaccessed) {
+        auto tailNode = mainLru.getTail();
+        if (tailNode == nullptr || !isAccessed(*tailNode)) {
+            isMainTailUnaccessed = true;
+            break;
+        }
+        mainLru.remove(*tailNode);
+        mainLru.linkAtHead(*tailNode);
+        unmarkAccessed(*tailNode);
+    }
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+typename MMS3FIFO::Container<T, HookPtr>::LockedIterator
+MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() noexcept {
+  LockHolder l(lruMutex_);
+  rebalanceForEviction();
+  return LockedIterator{std::move(l), *this};
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+template <typename F>
+void MMS3FIFO::Container<T, HookPtr>::withEvictionIterator(F&& fun) {
+  // uses spin lock which does not support combined locking
+  fun(getEvictionIterator());
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+template <typename F>
+void MMS3FIFO::Container<T, HookPtr>::withContainerLock(F&& fun) {
+  LockHolder l(lruMutex_);
+  fun();
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::removeLocked(T& node) noexcept {
+  if (isTiny(node)) {
+    lru_.getList(LruType::Tiny).remove(node);
+    unmarkTiny(node);
+  } else {
+    lru_.getList(LruType::Main).remove(node);
+  }
+
+  unmarkAccessed(node);
+  node.unmarkInMMContainer();
+  return;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+bool MMS3FIFO::Container<T, HookPtr>::remove(T& node) noexcept {
+  LockHolder l(lruMutex_);
+  if (!node.isInMMContainer()) {
+    return false;
+  }
+  removeLocked(node);
+  return true;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::remove(LockedIterator& 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 {
+  LockHolder l(lruMutex_);
+  if (!oldNode.isInMMContainer() || newNode.isInMMContainer()) {
+    return false;
+  }
+  const auto updateTime = getUpdateTime(oldNode);
+
+  if (isTiny(oldNode)) {
+    lru_.getList(LruType::Tiny).replace(oldNode, newNode);
+    unmarkTiny(oldNode);
+    markTiny(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 {
+  LockHolder l(lruMutex_);
+  return config_;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::setConfig(const Config& c) {
+  LockHolder l(lruMutex_);
+  config_ = c;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+serialization::MMS3FIFOObject MMS3FIFO::Container<T, HookPtr>::saveState()
+    const noexcept {
+  serialization::MMS3FIFOConfig configObject;
+  *configObject.updateOnWrite() = config_.updateOnWrite;
+  *configObject.updateOnRead() = config_.updateOnRead;
+  *configObject.ghostSizePercent() = config_.ghostSizePercent;
+  *configObject.tinySizePercent() = config_.tinySizePercent;
+  // TODO: Serialize the ghost queue too.
+  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 {
+  LockHolder l(lruMutex_);
+  auto* tail = lru_.size() == 0 ? nullptr : lru_.rbegin().get();
+  return {
+      lru_.size(), tail == nullptr ? 0 : getUpdateTime(*tail), 0, 0, 0, 0, 0};
+}
+
+// Locked Iterator Context Implementation
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+MMS3FIFO::Container<T, HookPtr>::LockedIterator::LockedIterator(
+    LockHolder l, const Container<T, HookPtr>& c) noexcept
+    : c_(c),
+      tIter_(c.lru_.getList(LruType::Tiny).rbegin()),
+      mIter_(c.lru_.getList(LruType::Main).rbegin()),
+      l_(std::move(l)) {}
+} // namespace facebook::cachelib
diff --git a/cachelib/allocator/MMS3FIFO_v2.h b/cachelib/allocator/MMS3FIFO_v2.h
new file mode 100644
index 0000000000..cef610070e
--- /dev/null
+++ b/cachelib/allocator/MMS3FIFO_v2.h
@@ -0,0 +1,688 @@
+/*
+ * 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>
+#include <folly/Math.h>
+#pragma GCC diagnostic pop
+
+#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/FIFOConcurrentHashSet.h"
+#include "cachelib/common/Mutex.h"
+
+namespace facebook::cachelib {
+//  MMS3FIFOV2
+// This adds a ghost queue to v1
+class MMS3FIFO {
+ public:
+  // unique identifier per MMType
+  static const int kId;
+
+  // forward declaration;
+  template <typename T>
+  using Hook = DListHook<T>;
+  using SerializationType = serialization::MMS3FIFOObject;
+  using SerializationConfigType = serialization::MMS3FIFOConfig;
+  using SerializationTypeContainer = serialization::MMS3FIFOCollection;
+
+  enum LruType { Main, Tiny, NumTypes };
+
+  // Config class for MMS3FIFO
+  struct Config {
+    // create from serialized config
+    explicit Config(SerializationConfigType configState)
+        : Config(*configState.updateOnWrite(),
+                 *configState.updateOnRead(),
+                 *configState.tinySizePercent(),
+                 *configState.ghostSizePercent()) {}
+
+    // @param udpateOnW   whether to promote the item on write
+    // @param updateOnR   whether to promote the item on read
+    Config(bool updateOnW, bool updateOnR)
+        : Config(updateOnW, updateOnR, 10, 90) {}
+
+    // @param udpateOnW         whether to promote the item on write
+    // @param updateOnR         whether to promote the item on read
+    // @param tinySizePercent   percentage number of tiny size to overall size
+    // @param ghostSizePercent  percentage number of ghost size to main size
+    Config(bool updateOnW,
+           bool updateOnR,
+           size_t tinySizePercent,
+           size_t ghostSizePercent)
+        : updateOnWrite(updateOnW),
+          updateOnRead(updateOnR),
+          tinySizePercent(tinySizePercent),
+          ghostSizePercent(ghostSizePercent) {}
+
+    Config() = default;
+    Config(const Config& rhs) = default;
+    Config(Config&& rhs) = default;
+
+    Config& operator=(const Config& rhs) = default;
+    Config& operator=(Config&& rhs) = default;
+
+    template <typename... Args>
+    void addExtraConfig(Args...) {}
+
+    // whether the lru needs to be updated on writes for recordAccess. If
+    // false, accessing the cache for writes does not promote the cached item
+    // to the head of the lru.
+    bool updateOnWrite{false};
+
+    // whether the lru needs to be updated on reads for recordAccess. If
+    // false, accessing the cache for reads does not promote the cached item
+    // to the head of the lru.
+    bool updateOnRead{true};
+
+    // The size of tiny cache, as a percentage of the total size.
+    size_t tinySizePercent{10};
+
+    size_t ghostSizePercent{90};
+  };
+
+  // The container object which can be used to keep track of objects of type
+  // T. T must have a public member of type Hook. This object is wrapper
+  // around DList, is thread safe and can be accessed from multiple threads.
+  // The current implementation models an LRU using the above DList
+  // implementation.
+  template <typename T, Hook<T> T::* HookPtr>
+  struct Container {
+   private:
+    using LruList = MultiDList<T, HookPtr>;
+    using Mutex = folly::SpinLock;
+    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;
+
+    // records the information that the node was accessed. This could bump up
+    // the node to the head of the lru depending on the time when the node was
+    // last updated in lru and the kLruRefreshTime. If the node was moved to
+    // the head in the lru, the node's updateTime will be updated
+    // accordingly.
+    //
+    // @param node  node that we want to mark as relevant/accessed
+    // @param mode  the mode for the access operation.
+    //
+    // @return      True if the information is recorded and bumped the node
+    //              to the head of the lru, returns false otherwise
+    bool recordAccess(T& node, AccessMode mode) noexcept;
+
+    // adds the given node into the container and marks it as being present in
+    // the container. The node is added to the head of the lru.
+    //
+    // @param node  The node to be added to the container.
+    // @return  True if the node was successfully added to the container. False
+    //          if the node was already in the contianer. On error state of node
+    //          is unchanged.
+    bool add(T& node) noexcept;
+
+    // removes the node from the lru and sets it previous and next to nullptr.
+    //
+    // @param node  The node to be removed from the container.
+    // @return  True if the node was successfully removed from the container.
+    //          False if the node was not part of the container. On error, the
+    //          state of node is unchanged.
+    bool remove(T& node) noexcept;
+
+    class LockedIterator;
+    // same as the above but uses an iterator context. The iterator is updated
+    // on removal of the corresponding node to point to the next node. The
+    // iterator context holds the lock on the lru.
+    //
+    // iterator will be advanced to the next node after removing the node
+    //
+    // @param it    Iterator that will be removed
+    void remove(LockedIterator& it) noexcept;
+
+    // replaces one node with another, at the same position
+    //
+    // @param oldNode   node being replaced
+    // @param newNode   node to replace oldNode with
+    //
+    // @return true  If the replace was successful. Returns false if the
+    //               destination node did not exist in the container, or if the
+    //               source node already existed.
+    bool replace(T& oldNode, T& newNode) noexcept;
+
+    // context for iterating the MM container. At any given point of time,
+    // there can be only one iterator active since we need to lock the LRU for
+    // iteration. we can support multiple iterators at same time, by using a
+    // shared ptr in the context for the lock holder in the future.
+    class LockedIterator {
+     public:
+      using ListIterator = typename LruList::DListIterator;
+      // noncopyable but movable.
+      LockedIterator(const LockedIterator&) = delete;
+      LockedIterator& operator=(const LockedIterator&) = delete;
+      LockedIterator(LockedIterator&&) noexcept = default;
+
+      LockedIterator& operator++() noexcept {
+        auto it = ++getIter();
+        skipAccessed(it);
+        return *this;
+      }
+
+      void skipAccessed(ListIterator& it) noexcept {
+        while (it) {
+          T& node = *it;
+          if (!Container<T, HookPtr>::isAccessed(node)) {
+            break; // found a valid eviction victim
+          }
+          ++it; // skip this accessed item
+        }
+      }
+
+      LockedIterator& operator--() {
+        throw std::invalid_argument(
+            "Decrementing eviction iterator is not supported");
+      }
+
+      T* operator->() const noexcept { return getIter().operator->(); }
+      T& operator*() const noexcept { return getIter().operator*(); }
+
+      bool operator==(const LockedIterator& other) const noexcept {
+        return &c_ == &other.c_ && tIter_ == other.tIter_ &&
+               mIter_ == other.mIter_;
+      }
+
+      bool operator!=(const LockedIterator& other) const noexcept {
+        return !(*this == other);
+      }
+
+      explicit operator bool() const noexcept { return tIter_ || mIter_; }
+
+      T* get() const noexcept { return getIter().get(); }
+
+      // Invalidates this iterator
+      void reset() noexcept {
+        // Point iterator to first list's rend
+        tIter_.reset();
+        mIter_.reset();
+      }
+
+      // 1. Invalidate this iterator
+      // 2. Unlock
+      void destroy() {
+        reset();
+        if (l_.owns_lock()) {
+          l_.unlock();
+        }
+      }
+
+      // Reset this iterator to the beginning
+      void resetToBegin() {
+        if (!l_.owns_lock()) {
+          l_.lock();
+        }
+        tIter_.resetToBegin();
+        mIter_.resetToBegin();
+      }
+
+     private:
+      // private because it's easy to misuse and cause deadlock for MMS3FIFO
+      LockedIterator& operator=(LockedIterator&&) noexcept = default;
+
+      // create an lru iterator with the lock being held.
+      explicit LockedIterator(LockHolder l,
+                              const Container<T, HookPtr>& c) noexcept;
+
+      const ListIterator& getIter() const noexcept {
+        return evictTiny() ? tIter_ : mIter_;
+      }
+
+      ListIterator& getIter() noexcept {
+        return const_cast<ListIterator&>(
+            static_cast<const LockedIterator*>(this)->getIter());
+      }
+
+      bool evictTiny() const noexcept {
+        if (!mIter_) {
+          return true;
+        }
+        if (!tIter_) {
+          return false;
+        }
+
+        const auto expectedSize =
+            c_.config_.tinySizePercent * c_.lru_.size() / 100;
+        auto isTinyBig = c_.lru_.getList(LruType::Tiny).size() > expectedSize;
+        return isTinyBig;
+      }
+
+      // only the container can create iterators
+      friend Container<T, HookPtr>;
+
+      const Container<T, HookPtr>& c_;
+      // Tiny and main cache iterators
+      ListIterator tIter_;
+      ListIterator mIter_;
+      // lock protecting the validity of the iterator
+      LockHolder l_;
+    };
+
+    Config getConfig() const;
+
+    void setConfig(const Config& newConfig);
+
+    void maybeResizeGhostLocked() noexcept;
+
+    bool isEmpty() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size() == 0;
+    }
+
+    size_t size() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size();
+    }
+
+    // Returns the eviction age stats. See CacheStats.h for details
+    EvictionAgeStat getEvictionAgeStat(uint64_t projectedLength) const noexcept;
+
+    // Obtain an iterator that start from the tail and can be used
+    // to search for evictions. This iterator holds a lock to this
+    // container and only one such iterator can exist at a time
+    LockedIterator getEvictionIterator() noexcept;
+
+    // Execute provided function under container lock. Function gets
+    // iterator passed as parameter.
+    template <typename F>
+    void withEvictionIterator(F&& f);
+
+    // Execute provided function under container lock.
+    template <typename F>
+    void withContainerLock(F&& f);
+
+    // for saving the state of the lru
+    //
+    // precondition:  serialization must happen without any reader or writer
+    // present. Any modification of this object afterwards will result in an
+    // invalid, inconsistent state for the serialized data.
+    //
+    serialization::MMS3FIFOObject saveState() const noexcept;
+
+    // return the stats for this container.
+    MMContainerStat getStats() const noexcept;
+
+    static LruType getLruType(const T& node) noexcept {
+      return isTiny(node) ? LruType::Tiny : 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);
+    }
+
+    // Returns the hash of node's key
+    static size_t hashNode64(const T& node) noexcept {
+      return folly::hasher<folly::StringPiece>()(node.getKey());
+    }
+    static uint32_t hashNode(const T& node) noexcept {
+      return static_cast<uint32_t>(
+          folly::hasher<folly::StringPiece>()(node.getKey()));
+    }
+
+    // remove node from lru and adjust insertion points
+    //
+    // @param node          node to remove
+    void removeLocked(T& node) noexcept;
+
+    static bool isTiny(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag0>();
+    }
+
+    static bool isAccessed(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag1>();
+    }
+
+    // Bit MM_BIT_0 is used to record if the item is in tiny cache.
+    static void markTiny(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag0>();
+    }
+    static void unmarkTiny(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag0>();
+    }
+
+    // Bit MM_BIT_1 is used to record if the item has been accessed since being
+    // written in cache. Unaccessed items are ignored when determining projected
+    // update time.
+    static void markAccessed(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag1>();
+    }
+    static void unmarkAccessed(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag1>();
+    }
+
+    void rebalanceForEviction();
+
+    mutable Mutex lruMutex_;
+
+    // the lru
+    LruList lru_;
+
+    // Current capacity to track ghost size
+    size_t capacity_{0};
+
+    facebook::cachelib::util::FIFOConcurrentHashSet32 ghostQueue_;
+
+    // Config for this lru.
+    // Write access to the MMS3FIFO Config is serialized.
+    // Reads may be racy.
+    Config config_{};
+
+    // FRIEND_TEST(MMTinyLFUTest, SegmentStress);
+    // FRIEND_TEST(MMTinyLFUTest, TinyLFUBasic);
+    // FRIEND_TEST(MMTinyLFUTest, Reconfigure);
+  };
+};
+
+/* 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());
+  // check if the node is still being memory managed
+  if (node.isInMMContainer() && !isAccessed(node)) {
+    markAccessed(node);
+    setUpdateTime(node, curr);
+    return true;
+  }
+  return false;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+cachelib::EvictionAgeStat MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStat(
+    uint64_t projectedLength) const noexcept {
+  LockHolder l(lruMutex_);
+  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 curr = static_cast<Time>(util::getCurrentTimeSec());
+
+  auto& list = lru_.getList(LruType::Main);
+  auto it = list.rbegin();
+  stat.warmQueueStat.oldestElementAge =
+      it != list.rend() ? curr - 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()
+                                        ? curr - getUpdateTime(*it)
+                                        : stat.warmQueueStat.oldestElementAge;
+  return stat;
+}
+
+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());
+  auto ghostContains = ghostQueue_.contains(nodeHash);
+
+  LockHolder l(lruMutex_);
+  if (node.isInMMContainer()) {
+    return false;
+  }
+  unmarkAccessed(node);
+  setUpdateTime(node, currTime);
+
+  if (!ghostContains) {
+    auto& tinyLru = lru_.getList(LruType::Tiny);
+    tinyLru.linkAtHead(node);
+    markTiny(node);
+  } else {
+    // Insert to main queue
+    auto& mainLru = lru_.getList(LruType::Main);
+    mainLru.linkAtHead(node);
+  }
+
+
+  node.markInMMContainer();
+  return true;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::rebalanceForEviction() {
+  // Bulk move accessed items from tiny to main cache
+  // Until tinycache's tail is unaccessed or tiny cache is within size limit
+  // Room for optimization:
+  // We can bulk move segments to main instead of one by one
+  auto& tinyLru = lru_.getList(LruType::Tiny);
+  auto& mainLru = lru_.getList(LruType::Main);
+
+  bool isTinyTailUnaccessed = false;
+  const auto expectedSize = config_.tinySizePercent * lru_.size() / 100;
+  while (!isTinyTailUnaccessed) {
+    if (tinyLru.size() <= expectedSize) {
+      break;
+    }
+    auto tailNode = tinyLru.getTail();
+    if (tailNode == nullptr || !isAccessed(*tailNode)) {
+      isTinyTailUnaccessed = true;
+      break;
+    }
+    tinyLru.remove(*tailNode);
+
+    mainLru.linkAtHead(*tailNode);
+    unmarkTiny(*tailNode);
+    unmarkAccessed(*tailNode);
+  }
+
+  // Reinsert items in main cache to head, until main cache's tail is unaccessed
+  // TODO: Room for optimization:
+  // We can get the position of first unaccessed item from the tail
+  // And move the whole segment to head in one operation
+  bool isMainTailUnaccessed = false;
+  while (!isMainTailUnaccessed) {
+    auto tailNode = mainLru.getTail();
+    if (tailNode == nullptr || !isAccessed(*tailNode)) {
+      isMainTailUnaccessed = true;
+      break;
+    }
+    mainLru.remove(*tailNode);
+    mainLru.linkAtHead(*tailNode);
+    unmarkAccessed(*tailNode);
+  }
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::maybeResizeGhostLocked() noexcept {
+  size_t lruSize = lru_.size();
+
+  // Grow when size doubled, shrink when halved
+  const bool shouldGrow = lruSize >= 2 * capacity_;
+  const bool shouldShrink = lruSize <= capacity_ / 2;
+
+  if (!shouldGrow && !shouldShrink) {
+    return;
+  }
+
+  size_t expectedGhostSize =
+      static_cast<size_t>(lruSize * config_.ghostSizePercent / 100);
+  ghostQueue_.resize(expectedGhostSize);
+  capacity_ = lruSize;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+typename MMS3FIFO::Container<T, HookPtr>::LockedIterator
+MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() noexcept {
+  LockHolder l(lruMutex_);
+  maybeResizeGhostLocked();
+  rebalanceForEviction();
+  return LockedIterator{std::move(l), *this};
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+template <typename F>
+void MMS3FIFO::Container<T, HookPtr>::withEvictionIterator(F&& fun) {
+  // uses spin lock which does not support combined locking
+  fun(getEvictionIterator());
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+template <typename F>
+void MMS3FIFO::Container<T, HookPtr>::withContainerLock(F&& fun) {
+  LockHolder l(lruMutex_);
+  fun();
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::removeLocked(T& node) noexcept {
+  if (isTiny(node)) {
+    lru_.getList(LruType::Tiny).remove(node);
+    unmarkTiny(node);
+    ghostQueue_.insert(hashNode(node));
+  } else {
+    lru_.getList(LruType::Main).remove(node);
+  }
+
+  unmarkAccessed(node);
+  node.unmarkInMMContainer();
+  return;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+bool MMS3FIFO::Container<T, HookPtr>::remove(T& node) noexcept {
+  LockHolder l(lruMutex_);
+  if (!node.isInMMContainer()) {
+    return false;
+  }
+  removeLocked(node);
+  return true;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::remove(LockedIterator& 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 {
+  LockHolder l(lruMutex_);
+  if (!oldNode.isInMMContainer() || newNode.isInMMContainer()) {
+    return false;
+  }
+  const auto updateTime = getUpdateTime(oldNode);
+
+  if (isTiny(oldNode)) {
+    lru_.getList(LruType::Tiny).replace(oldNode, newNode);
+    unmarkTiny(oldNode);
+    markTiny(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 {
+  LockHolder l(lruMutex_);
+  return config_;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::setConfig(const Config& c) {
+  LockHolder l(lruMutex_);
+  config_ = c;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+serialization::MMS3FIFOObject MMS3FIFO::Container<T, HookPtr>::saveState()
+    const noexcept {
+  serialization::MMS3FIFOConfig configObject;
+  *configObject.updateOnWrite() = config_.updateOnWrite;
+  *configObject.updateOnRead() = config_.updateOnRead;
+  *configObject.ghostSizePercent() = config_.ghostSizePercent;
+  *configObject.tinySizePercent() = config_.tinySizePercent;
+  // TODO: Serialize the ghost queue too.
+  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 {
+  LockHolder l(lruMutex_);
+  auto* tail = lru_.size() == 0 ? nullptr : lru_.rbegin().get();
+  return {
+      lru_.size(), tail == nullptr ? 0 : getUpdateTime(*tail), 0, 0, 0, 0, 0};
+}
+
+// Locked Iterator Context Implementation
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+MMS3FIFO::Container<T, HookPtr>::LockedIterator::LockedIterator(
+    LockHolder l, const Container<T, HookPtr>& c) noexcept
+    : c_(c),
+      tIter_(c.lru_.getList(LruType::Tiny).rbegin()),
+      mIter_(c.lru_.getList(LruType::Main).rbegin()),
+      l_(std::move(l)) {}
+} // namespace facebook::cachelib

From 3a2af3256e62e78bb18863322d0a71910e4e83aa Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Sun, 7 Dec 2025 08:16:17 +0000
Subject: [PATCH 14/15] simpler than v0 version

---
 cachelib/allocator/MMS3FIFO_v-1.h | 620 ++++++++++++++++++++++++++++++
 1 file changed, 620 insertions(+)
 create mode 100644 cachelib/allocator/MMS3FIFO_v-1.h

diff --git a/cachelib/allocator/MMS3FIFO_v-1.h b/cachelib/allocator/MMS3FIFO_v-1.h
new file mode 100644
index 0000000000..33689859bd
--- /dev/null
+++ b/cachelib/allocator/MMS3FIFO_v-1.h
@@ -0,0 +1,620 @@
+/*
+ * 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>
+#include <folly/Math.h>
+#pragma GCC diagnostic pop
+
+#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 {
+// MMS3FIFOV0
+// This version:
+// straight up takes tinyLFU's recordaccess function
+// eviction iterator always evicts from main
+// returns eviction age stats
+class MMS3FIFO {
+ public:
+  // unique identifier per MMType
+  static const int kId;
+
+  // forward declaration;
+  template <typename T>
+  using Hook = DListHook<T>;
+  using SerializationType = serialization::MMS3FIFOObject;
+  using SerializationConfigType = serialization::MMS3FIFOConfig;
+  using SerializationTypeContainer = serialization::MMS3FIFOCollection;
+
+  enum LruType { Main, Tiny, NumTypes };
+
+  // Config class for MMS3FIFO
+  struct Config {
+    // create from serialized config
+    explicit Config(SerializationConfigType configState)
+        : Config(*configState.updateOnWrite(),
+                 *configState.updateOnRead(),
+                 *configState.tinySizePercent(),
+                 *configState.ghostSizePercent()) {}
+
+    // @param udpateOnW   whether to promote the item on write
+    // @param updateOnR   whether to promote the item on read
+    Config(bool updateOnW, bool updateOnR)
+        : Config(updateOnW, updateOnR, 10, 90) {}
+
+    // @param udpateOnW         whether to promote the item on write
+    // @param updateOnR         whether to promote the item on read
+    // @param tinySizePercent   percentage number of tiny size to overall size
+    // @param ghostSizePercent  percentage number of ghost size to main size
+    Config(bool updateOnW,
+           bool updateOnR,
+           size_t tinySizePercent,
+           size_t ghostSizePercent)
+        : updateOnWrite(updateOnW),
+          updateOnRead(updateOnR),
+          tinySizePercent(tinySizePercent),
+          ghostSizePercent(ghostSizePercent) {}
+
+    Config() = default;
+    Config(const Config& rhs) = default;
+    Config(Config&& rhs) = default;
+
+    Config& operator=(const Config& rhs) = default;
+    Config& operator=(Config&& rhs) = default;
+
+    template <typename... Args>
+    void addExtraConfig(Args...) {}
+
+    // whether the lru needs to be updated on writes for recordAccess. If
+    // false, accessing the cache for writes does not promote the cached item
+    // to the head of the lru.
+    bool updateOnWrite{false};
+
+    // whether the lru needs to be updated on reads for recordAccess. If
+    // false, accessing the cache for reads does not promote the cached item
+    // to the head of the lru.
+    bool updateOnRead{true};
+
+    // The size of tiny cache, as a percentage of the total size.
+    size_t tinySizePercent{10};
+
+    size_t ghostSizePercent{90};
+  };
+
+  // The container object which can be used to keep track of objects of type
+  // T. T must have a public member of type Hook. This object is wrapper
+  // around DList, is thread safe and can be accessed from multiple threads.
+  // The current implementation models an LRU using the above DList
+  // implementation.
+  template <typename T, Hook<T> T::* HookPtr>
+  struct Container {
+   private:
+    using LruList = MultiDList<T, HookPtr>;
+    using Mutex = folly::SpinLock;
+    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;
+
+    // records the information that the node was accessed. This could bump up
+    // the node to the head of the lru depending on the time when the node was
+    // last updated in lru and the kLruRefreshTime. If the node was moved to
+    // the head in the lru, the node's updateTime will be updated
+    // accordingly.
+    //
+    // @param node  node that we want to mark as relevant/accessed
+    // @param mode  the mode for the access operation.
+    //
+    // @return      True if the information is recorded and bumped the node
+    //              to the head of the lru, returns false otherwise
+    bool recordAccess(T& node, AccessMode mode) noexcept;
+
+    // adds the given node into the container and marks it as being present in
+    // the container. The node is added to the head of the lru.
+    //
+    // @param node  The node to be added to the container.
+    // @return  True if the node was successfully added to the container. False
+    //          if the node was already in the contianer. On error state of node
+    //          is unchanged.
+    bool add(T& node) noexcept;
+
+    // removes the node from the lru and sets it previous and next to nullptr.
+    //
+    // @param node  The node to be removed from the container.
+    // @return  True if the node was successfully removed from the container.
+    //          False if the node was not part of the container. On error, the
+    //          state of node is unchanged.
+    bool remove(T& node) noexcept;
+
+    class LockedIterator;
+    // same as the above but uses an iterator context. The iterator is updated
+    // on removal of the corresponding node to point to the next node. The
+    // iterator context holds the lock on the lru.
+    //
+    // iterator will be advanced to the next node after removing the node
+    //
+    // @param it    Iterator that will be removed
+    void remove(LockedIterator& it) noexcept;
+
+    // replaces one node with another, at the same position
+    //
+    // @param oldNode   node being replaced
+    // @param newNode   node to replace oldNode with
+    //
+    // @return true  If the replace was successful. Returns false if the
+    //               destination node did not exist in the container, or if the
+    //               source node already existed.
+    bool replace(T& oldNode, T& newNode) noexcept;
+
+    // context for iterating the MM container. At any given point of time,
+    // there can be only one iterator active since we need to lock the LRU for
+    // iteration. we can support multiple iterators at same time, by using a
+    // shared ptr in the context for the lock holder in the future.
+    class LockedIterator {
+     public:
+      using ListIterator = typename LruList::DListIterator;
+      // noncopyable but movable.
+      LockedIterator(const LockedIterator&) = delete;
+      LockedIterator& operator=(const LockedIterator&) = delete;
+      LockedIterator(LockedIterator&&) noexcept = default;
+
+      LockedIterator& operator++() noexcept {
+        ++getIter();
+        return *this;
+      }
+
+      LockedIterator& operator--() {
+        throw std::invalid_argument(
+            "Decrementing eviction iterator is not supported");
+      }
+
+      T* operator->() const noexcept { return getIter().operator->(); }
+      T& operator*() const noexcept { return getIter().operator*(); }
+
+      bool operator==(const LockedIterator& other) const noexcept {
+        return &c_ == &other.c_ && tIter_ == other.tIter_ &&
+               mIter_ == other.mIter_;
+      }
+
+      bool operator!=(const LockedIterator& other) const noexcept {
+        return !(*this == other);
+      }
+
+      explicit operator bool() const noexcept { return tIter_ || mIter_; }
+
+      T* get() const noexcept { return getIter().get(); }
+
+      // Invalidates this iterator
+      void reset() noexcept {
+        // Point iterator to first list's rend
+        tIter_.reset();
+        mIter_.reset();
+      }
+
+      // 1. Invalidate this iterator
+      // 2. Unlock
+      void destroy() {
+        reset();
+        if (l_.owns_lock()) {
+          l_.unlock();
+        }
+      }
+
+      // Reset this iterator to the beginning
+      void resetToBegin() {
+        if (!l_.owns_lock()) {
+          l_.lock();
+        }
+        tIter_.resetToBegin();
+        mIter_.resetToBegin();
+      }
+
+     private:
+      // private because it's easy to misuse and cause deadlock for MMS3FIFO
+      LockedIterator& operator=(LockedIterator&&) noexcept = default;
+
+      // create an lru iterator with the lock being held.
+      explicit LockedIterator(LockHolder l,
+                              const Container<T, HookPtr>& c) noexcept;
+
+      const ListIterator& getIter() const noexcept {
+        return evictTiny() ? tIter_ : mIter_;
+      }
+
+      ListIterator& getIter() noexcept {
+        return const_cast<ListIterator&>(
+            static_cast<const LockedIterator*>(this)->getIter());
+      }
+
+      bool evictTiny() const noexcept {
+        if (!mIter_) {
+          return true;
+        }
+        if (!tIter_) {
+          return false;
+        }
+        // Simplification, evict from main first
+        return false;
+      }
+
+      // only the container can create iterators
+      friend Container<T, HookPtr>;
+
+      const Container<T, HookPtr>& c_;
+      // Tiny and main cache iterators
+      ListIterator tIter_;
+      ListIterator mIter_;
+      // lock protecting the validity of the iterator
+      LockHolder l_;
+    };
+
+    Config getConfig() const;
+
+    void setConfig(const Config& newConfig);
+
+    bool isEmpty() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size() == 0;
+    }
+
+    size_t size() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size();
+    }
+
+    // Returns the eviction age stats. See CacheStats.h for details
+    EvictionAgeStat getEvictionAgeStat(uint64_t projectedLength) const noexcept;
+
+    // Obtain an iterator that start from the tail and can be used
+    // to search for evictions. This iterator holds a lock to this
+    // container and only one such iterator can exist at a time
+    LockedIterator getEvictionIterator() const noexcept;
+
+    // Execute provided function under container lock. Function gets
+    // iterator passed as parameter.
+    template <typename F>
+    void withEvictionIterator(F&& f);
+
+    // Execute provided function under container lock.
+    template <typename F>
+    void withContainerLock(F&& f);
+
+    // for saving the state of the lru
+    //
+    // precondition:  serialization must happen without any reader or writer
+    // present. Any modification of this object afterwards will result in an
+    // invalid, inconsistent state for the serialized data.
+    //
+    serialization::MMS3FIFOObject saveState() const noexcept;
+
+    // return the stats for this container.
+    MMContainerStat getStats() const noexcept;
+
+    static LruType getLruType(const T& node) noexcept {
+      return isTiny(node) ? LruType::Tiny : 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);
+    }
+
+    // Returns the hash of node's key
+    static size_t hashNode(const T& node) noexcept {
+      return folly::hasher<folly::StringPiece>()(node.getKey());
+    }
+
+    // remove node from lru and adjust insertion points
+    //
+    // @param node          node to remove
+    void removeLocked(T& node) noexcept;
+
+    static bool isTiny(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag0>();
+    }
+
+    static bool isAccessed(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag1>();
+    }
+
+    // Bit MM_BIT_0 is used to record if the item is in tiny cache.
+    static void markTiny(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag0>();
+    }
+    static void unmarkTiny(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag0>();
+    }
+
+    // Bit MM_BIT_1 is used to record if the item has been accessed since being
+    // written in cache. Unaccessed items are ignored when determining projected
+    // update time.
+    static void markAccessed(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag1>();
+    }
+    static void unmarkAccessed(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag1>();
+    }
+
+    mutable Mutex lruMutex_;
+
+    // the lru
+    LruList lru_;
+
+    // Current capacity to track ghost size
+    size_t capacity_{0};
+
+    // Config for this lru.
+    // Write access to the MMS3FIFO Config is serialized.
+    // Reads may be racy.
+    Config config_{};
+
+    // FRIEND_TEST(MMTinyLFUTest, SegmentStress);
+    // FRIEND_TEST(MMTinyLFUTest, TinyLFUBasic);
+    // FRIEND_TEST(MMTinyLFUTest, Reconfigure);
+  };
+};
+
+/* 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());
+  // check if the node is still being memory managed
+  if (node.isInMMContainer() && !isAccessed(node)) {
+    if (!isAccessed(node)) {
+      markAccessed(node);
+    }
+    LockHolder l(lruMutex_, std::defer_lock);
+    l.lock();
+    if (!l.owns_lock()) {
+      return false;
+    }
+    if (!node.isInMMContainer()) {
+      return false;
+    }
+    setUpdateTime(node, curr);
+    return true;
+  }
+  return false;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+cachelib::EvictionAgeStat MMS3FIFO::Container<T, HookPtr>::getEvictionAgeStat(
+    uint64_t projectedLength) const noexcept {
+  LockHolder l(lruMutex_);
+  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 curr = static_cast<Time>(util::getCurrentTimeSec());
+
+  auto& list = lru_.getList(LruType::Main);
+  auto it = list.rbegin();
+  stat.warmQueueStat.oldestElementAge =
+      it != list.rend() ? curr - 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()
+                                        ? curr - getUpdateTime(*it)
+                                        : stat.warmQueueStat.oldestElementAge;
+  return stat;
+}
+
+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());
+  LockHolder l(lruMutex_);
+  if (node.isInMMContainer()) {
+    return false;
+  }
+
+  auto& tinyLru = lru_.getList(LruType::Tiny);
+  tinyLru.linkAtHead(node);
+  markTiny(node);
+
+  // If tiny cache is full, unconditionally promote tail to main cache.
+  const auto expectedSize = config_.tinySizePercent * lru_.size() / 100;
+  if (lru_.getList(LruType::Tiny).size() > expectedSize) {
+    auto tailNode = tinyLru.getTail();
+    tinyLru.remove(*tailNode);
+
+    auto& mainLru = lru_.getList(LruType::Main);
+    mainLru.linkAtHead(*tailNode);
+    unmarkTiny(*tailNode);
+  }
+
+  node.markInMMContainer();
+  setUpdateTime(node, currTime);
+  unmarkAccessed(node);
+  return true;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+typename MMS3FIFO::Container<T, HookPtr>::LockedIterator
+MMS3FIFO::Container<T, HookPtr>::getEvictionIterator() const noexcept {
+  LockHolder l(lruMutex_);
+  return LockedIterator{std::move(l), *this};
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+template <typename F>
+void MMS3FIFO::Container<T, HookPtr>::withEvictionIterator(F&& fun) {
+  // uses spin lock which does not support combined locking
+  fun(getEvictionIterator());
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+template <typename F>
+void MMS3FIFO::Container<T, HookPtr>::withContainerLock(F&& fun) {
+  LockHolder l(lruMutex_);
+  fun();
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::removeLocked(T& node) noexcept {
+  if (isTiny(node)) {
+    lru_.getList(LruType::Tiny).remove(node);
+    unmarkTiny(node);
+  } else {
+    lru_.getList(LruType::Main).remove(node);
+  }
+
+  unmarkAccessed(node);
+  node.unmarkInMMContainer();
+  return;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+bool MMS3FIFO::Container<T, HookPtr>::remove(T& node) noexcept {
+  LockHolder l(lruMutex_);
+  if (!node.isInMMContainer()) {
+    return false;
+  }
+  removeLocked(node);
+  return true;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::remove(LockedIterator& 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 {
+  LockHolder l(lruMutex_);
+  if (!oldNode.isInMMContainer() || newNode.isInMMContainer()) {
+    return false;
+  }
+  const auto updateTime = getUpdateTime(oldNode);
+
+  if (isTiny(oldNode)) {
+    lru_.getList(LruType::Tiny).replace(oldNode, newNode);
+    unmarkTiny(oldNode);
+    markTiny(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 {
+  LockHolder l(lruMutex_);
+  return config_;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+void MMS3FIFO::Container<T, HookPtr>::setConfig(const Config& c) {
+  LockHolder l(lruMutex_);
+  config_ = c;
+}
+
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+serialization::MMS3FIFOObject MMS3FIFO::Container<T, HookPtr>::saveState()
+    const noexcept {
+  serialization::MMS3FIFOConfig configObject;
+  *configObject.updateOnWrite() = config_.updateOnWrite;
+  *configObject.updateOnRead() = config_.updateOnRead;
+  *configObject.ghostSizePercent() = config_.ghostSizePercent;
+  *configObject.tinySizePercent() = config_.tinySizePercent;
+  // TODO: Serialize the ghost queue too.
+  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 {
+  LockHolder l(lruMutex_);
+  auto* tail = lru_.size() == 0 ? nullptr : lru_.rbegin().get();
+
+  auto stat = getEvictionAgeStatLocked(0);
+  return {lru_.size(),
+          tail == nullptr ? 0 : getUpdateTime(*tail),
+          stat.warmQueueStat.oldestElementAge,
+          0,
+          0,
+          0,
+          0};
+}
+
+// Locked Iterator Context Implementation
+template <typename T, MMS3FIFO::Hook<T> T::* HookPtr>
+MMS3FIFO::Container<T, HookPtr>::LockedIterator::LockedIterator(
+    LockHolder l, const Container<T, HookPtr>& c) noexcept
+    : c_(c),
+      tIter_(c.lru_.getList(LruType::Tiny).rbegin()),
+      mIter_(c.lru_.getList(LruType::Main).rbegin()),
+      l_(std::move(l)) {}
+} // namespace facebook::cachelib

From 259e4606b0cc64ed5bfa16694da598f7eab98f81 Mon Sep 17 00:00:00 2001
From: Chameleon Cloud User <williamnixon20@gmail.com>
Date: Mon, 8 Dec 2025 15:42:29 +0000
Subject: [PATCH 15/15] tinylfu versions

---
 cachelib/allocator/MMTinyLFU-v0.h | 916 ++++++++++++++++++++++++++++++
 cachelib/allocator/MMTinyLFU-v1.h | 847 +++++++++++++++++++++++++++
 2 files changed, 1763 insertions(+)
 create mode 100644 cachelib/allocator/MMTinyLFU-v0.h
 create mode 100644 cachelib/allocator/MMTinyLFU-v1.h

diff --git a/cachelib/allocator/MMTinyLFU-v0.h b/cachelib/allocator/MMTinyLFU-v0.h
new file mode 100644
index 0000000000..e563330275
--- /dev/null
+++ b/cachelib/allocator/MMTinyLFU-v0.h
@@ -0,0 +1,916 @@
+/*
+ * 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>
+#include <folly/Math.h>
+#pragma GCC diagnostic pop
+
+#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/CountMinSketch.h"
+#include "cachelib/common/Mutex.h"
+
+namespace facebook::cachelib {
+// This version does deletions on mmtinylfu
+// to make it our template.
+class MMTinyLFU {
+ public:
+  // unique identifier per MMType
+  static const int kId;
+
+  // forward declaration;
+  template <typename T>
+  using Hook = DListHook<T>;
+  using SerializationType = serialization::MMTinyLFUObject;
+  using SerializationConfigType = serialization::MMTinyLFUConfig;
+  using SerializationTypeContainer = serialization::MMTinyLFUCollection;
+
+  enum LruType { Main, Tiny, NumTypes };
+
+  // Config class for MMTinfyLFU
+  struct Config {
+    // create from serialized config
+    explicit Config(SerializationConfigType configState)
+        : Config(*configState.lruRefreshTime(),
+                 *configState.lruRefreshRatio(),
+                 *configState.updateOnWrite(),
+                 *configState.updateOnRead(),
+                 *configState.tryLockUpdate(),
+                 *configState.windowToCacheSizeRatio(),
+                 *configState.tinySizePercent(),
+                 *configState.mmReconfigureIntervalSecs(),
+                 *configState.newcomerWinsOnTie()) {}
+
+    // @param time        the LRU refresh time in seconds.
+    //                    An item will be promoted only once in each lru refresh
+    //                    time depite the number of accesses it gets.
+    // @param udpateOnW   whether to promote the item on write
+    // @param updateOnR   whether to promote the item on read
+    Config(uint32_t time, bool updateOnW, bool updateOnR)
+        : Config(time,
+                 updateOnW,
+                 updateOnR,
+                 /* try lock update */ false,
+                 16,
+                 1) {}
+
+    // @param time              the LRU refresh time in seconds.
+    //                          An item will be promoted only once in each lru
+    //                          refresh time depite the number of accesses it
+    //                          gets.
+    // @param udpateOnW         whether to promote the item on write
+    // @param updateOnR         whether to promote the item on read
+    // @param windowToCacheSize multiplier of window size to cache size
+    // @param tinySizePct       percentage number of tiny size to overall size
+    Config(uint32_t time,
+           bool updateOnW,
+           bool updateOnR,
+           size_t windowToCacheSize,
+           size_t tinySizePct)
+        : Config(time,
+                 updateOnW,
+                 updateOnR,
+                 /* try lock update */ false,
+                 windowToCacheSize,
+                 tinySizePct) {}
+
+    // @param time              the LRU refresh time in seconds.
+    //                          An item will be promoted only once in each lru
+    //                          refresh time depite the number of accesses it
+    //                          gets.
+    // @param udpateOnW         whether to promote the item on write
+    // @param updateOnR         whether to promote the item on read
+    // @param tryLockU          whether to use a try lock when doing update.
+    // @param windowToCacheSize multiplier of window size to cache size
+    // @param tinySizePct       percentage number of tiny size to overall size
+    Config(uint32_t time,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t windowToCacheSize,
+           size_t tinySizePct)
+        : Config(time,
+                 0.,
+                 updateOnW,
+                 updateOnR,
+                 tryLockU,
+                 windowToCacheSize,
+                 tinySizePct) {}
+
+    // @param time                    the LRU refresh time in seconds.
+    //                                An item will be promoted only once in each
+    //                                lru refresh time depite the number of
+    //                                accesses it gets.
+    // @param ratio                   the lru refresh ratio. The ratio times the
+    //                                oldest element's lifetime in warm queue
+    //                                would be the minimum value of LRU refresh
+    //                                time.
+    // @param udpateOnW               whether to promote the item on write
+    // @param updateOnR               whether to promote the item on read
+    // @param tryLockU                whether to use a try lock when doing
+    //                                update.
+    // @param windowToCacheSize       multiplier of window size to cache size
+    // @param tinySizePct             percentage number of tiny size to overall
+    //                                size
+    Config(uint32_t time,
+           double ratio,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t windowToCacheSize,
+           size_t tinySizePct)
+        : Config(time,
+                 ratio,
+                 updateOnW,
+                 updateOnR,
+                 tryLockU,
+                 windowToCacheSize,
+                 tinySizePct,
+                 0) {}
+
+    // @param time                    the LRU refresh time in seconds.
+    //                                An item will be promoted only once in each
+    //                                lru refresh time depite the number of
+    //                                accesses it gets.
+    // @param ratio                   the lru refresh ratio. The ratio times the
+    //                                oldest element's lifetime in warm queue
+    //                                would be the minimum value of LRU refresh
+    //                                time.
+    // @param udpateOnW               whether to promote the item on write
+    // @param updateOnR               whether to promote the item on read
+    // @param tryLockU                whether to use a try lock when doing
+    //                                update.
+    // @param windowToCacheSize       multiplier of window size to cache size
+    // @param tinySizePct             percentage number of tiny size to overall
+    //                                size
+    // @param mmReconfigureInterval   Time interval for recalculating lru
+    //                                refresh time according to the ratio.
+    Config(uint32_t time,
+           double ratio,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t windowToCacheSize,
+           size_t tinySizePct,
+           uint32_t mmReconfigureInterval)
+        : defaultLruRefreshTime(time),
+          lruRefreshRatio(ratio),
+          updateOnWrite(updateOnW),
+          updateOnRead(updateOnR),
+          tryLockUpdate(tryLockU),
+          windowToCacheSizeRatio(windowToCacheSize),
+          tinySizePercent(tinySizePct),
+          mmReconfigureIntervalSecs(
+              std::chrono::seconds(mmReconfigureInterval)) {
+      checkConfig();
+    }
+
+    // @param time                    the LRU refresh time in seconds.
+    //                                An item will be promoted only once in each
+    //                                lru refresh time depite the number of
+    //                                accesses it gets.
+    // @param ratio                   the lru refresh ratio. The ratio times the
+    //                                oldest element's lifetime in warm queue
+    //                                would be the minimum value of LRU refresh
+    //                                time.
+    // @param udpateOnW               whether to promote the item on write
+    // @param updateOnR               whether to promote the item on read
+    // @param tryLockU                whether to use a try lock when doing
+    //                                update.
+    // @param windowToCacheSize       multiplier of window size to cache size
+    // @param tinySizePct             percentage number of tiny size to overall
+    //                                size
+    // @param mmReconfigureInterval   Time interval for recalculating lru
+    //                                refresh time according to the ratio.
+    // @param newcomerWinsOnTie       If true, new comer will replace existing
+    //                                item if their access frequencies tie.
+    Config(uint32_t time,
+           double ratio,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t windowToCacheSize,
+           size_t tinySizePct,
+           uint32_t mmReconfigureInterval,
+           bool _newcomerWinsOnTie)
+        : defaultLruRefreshTime(time),
+          lruRefreshRatio(ratio),
+          updateOnWrite(updateOnW),
+          updateOnRead(updateOnR),
+          tryLockUpdate(tryLockU),
+          windowToCacheSizeRatio(windowToCacheSize),
+          tinySizePercent(tinySizePct),
+          mmReconfigureIntervalSecs(
+              std::chrono::seconds(mmReconfigureInterval)),
+          newcomerWinsOnTie(_newcomerWinsOnTie) {
+      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 (tinySizePercent < 1 || tinySizePercent > 50) {
+        throw std::invalid_argument(
+            folly::sformat("Invalid tiny cache size {}. Tiny cache size "
+                           "must be between 1% and 50% of total cache size ",
+                           tinySizePercent));
+      }
+      if (windowToCacheSizeRatio < 2 || windowToCacheSizeRatio > 128) {
+        throw std::invalid_argument(
+            folly::sformat("Invalid window to cache size ratio {}. The ratio "
+                           "must be between 2 and 128",
+                           windowToCacheSizeRatio));
+      }
+    }
+
+    template <typename... Args>
+    void addExtraConfig(Args...) {}
+
+    // threshold value in seconds to compare with a node's update time to
+    // determine if we need to update the position of the node in the linked
+    // list. By default this is 60s to reduce the contention on the lru lock.
+    uint32_t defaultLruRefreshTime{60};
+    uint32_t lruRefreshTime{defaultLruRefreshTime};
+
+    // ratio of LRU refresh time to the tail age. If a refresh time computed
+    // according to this ratio is larger than lruRefreshtime, we will adopt
+    // this one instead of the lruRefreshTime set.
+    double lruRefreshRatio{0.};
+
+    // whether the lru needs to be updated on writes for recordAccess. If
+    // false, accessing the cache for writes does not promote the cached item
+    // to the head of the lru.
+    bool updateOnWrite{false};
+
+    // whether the lru needs to be updated on reads for recordAccess. If
+    // false, accessing the cache for reads does not promote the cached item
+    // to the head of the lru.
+    bool updateOnRead{true};
+
+    // whether to tryLock or lock the lru lock when attempting promotion on
+    // access. If set, and tryLock fails, access will not result in promotion.
+    bool tryLockUpdate{false};
+
+    // The multiplier for window size given the cache size.
+    size_t windowToCacheSizeRatio{32};
+
+    // The size of tiny cache, as a percentage of the total size.
+    size_t tinySizePercent{1};
+
+    // Minimum interval between reconfigurations. If 0, reconfigure is never
+    // called.
+    std::chrono::seconds mmReconfigureIntervalSecs{};
+
+    // If true, then if an item in the tail of the Tiny queue ties with the
+    // item in the tail of the main queue, the item from Tiny (newcomer) will
+    // replace the item from Main. This is fine for a default, but for
+    // strictly scan patterns (access a key exactly once and move on), this
+    // is not a desirable behavior (we'll always cache miss).
+    bool newcomerWinsOnTie{true};
+  };
+
+  // The container object which can be used to keep track of objects of type
+  // T. T must have a public member of type Hook. This object is wrapper
+  // around DList, is thread safe and can be accessed from multiple threads.
+  // The current implementation models an LRU using the above DList
+  // implementation.
+  template <typename T, Hook<T> T::* HookPtr>
+  struct Container {
+   private:
+    using LruList = MultiDList<T, HookPtr>;
+    using Mutex = folly::SpinLock;
+    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)) {
+      lruRefreshTime_ = config_.lruRefreshTime;
+      nextReconfigureTime_ =
+          config_.mmReconfigureIntervalSecs.count() == 0
+              ? std::numeric_limits<Time>::max()
+              : static_cast<Time>(util::getCurrentTimeSec()) +
+                    config_.mmReconfigureIntervalSecs.count();
+    }
+    Container(serialization::MMTinyLFUObject object, PtrCompressor compressor);
+
+    Container(const Container&) = delete;
+    Container& operator=(const Container&) = delete;
+
+    // records the information that the node was accessed. This could bump up
+    // the node to the head of the lru depending on the time when the node was
+    // last updated in lru and the kLruRefreshTime. If the node was moved to
+    // the head in the lru, the node's updateTime will be updated
+    // accordingly.
+    //
+    // @param node  node that we want to mark as relevant/accessed
+    // @param mode  the mode for the access operation.
+    //
+    // @return      True if the information is recorded and bumped the node
+    //              to the head of the lru, returns false otherwise
+    bool recordAccess(T& node, AccessMode mode) noexcept;
+
+    // adds the given node into the container and marks it as being present in
+    // the container. The node is added to the head of the lru.
+    //
+    // @param node  The node to be added to the container.
+    // @return  True if the node was successfully added to the container. False
+    //          if the node was already in the contianer. On error state of node
+    //          is unchanged.
+    bool add(T& node) noexcept;
+
+    // removes the node from the lru and sets it previous and next to nullptr.
+    //
+    // @param node  The node to be removed from the container.
+    // @return  True if the node was successfully removed from the container.
+    //          False if the node was not part of the container. On error, the
+    //          state of node is unchanged.
+    bool remove(T& node) noexcept;
+
+    class LockedIterator;
+    // same as the above but uses an iterator context. The iterator is updated
+    // on removal of the corresponding node to point to the next node. The
+    // iterator context holds the lock on the lru.
+    //
+    // iterator will be advanced to the next node after removing the node
+    //
+    // @param it    Iterator that will be removed
+    void remove(LockedIterator& it) noexcept;
+
+    // replaces one node with another, at the same position
+    //
+    // @param oldNode   node being replaced
+    // @param newNode   node to replace oldNode with
+    //
+    // @return true  If the replace was successful. Returns false if the
+    //               destination node did not exist in the container, or if the
+    //               source node already existed.
+    bool replace(T& oldNode, T& newNode) noexcept;
+
+    // context for iterating the MM container. At any given point of time,
+    // there can be only one iterator active since we need to lock the LRU for
+    // iteration. we can support multiple iterators at same time, by using a
+    // shared ptr in the context for the lock holder in the future.
+    class LockedIterator {
+     public:
+      using ListIterator = typename LruList::DListIterator;
+      // noncopyable but movable.
+      LockedIterator(const LockedIterator&) = delete;
+      LockedIterator& operator=(const LockedIterator&) = delete;
+      LockedIterator(LockedIterator&&) noexcept = default;
+
+      LockedIterator& operator++() noexcept {
+        ++getIter();
+        return *this;
+      }
+
+      LockedIterator& operator--() {
+        throw std::invalid_argument(
+            "Decrementing eviction iterator is not supported");
+      }
+
+      T* operator->() const noexcept { return getIter().operator->(); }
+      T& operator*() const noexcept { return getIter().operator*(); }
+
+      bool operator==(const LockedIterator& other) const noexcept {
+        return &c_ == &other.c_ && tIter_ == other.tIter_ &&
+               mIter_ == other.mIter_;
+      }
+
+      bool operator!=(const LockedIterator& other) const noexcept {
+        return !(*this == other);
+      }
+
+      explicit operator bool() const noexcept { return tIter_ || mIter_; }
+
+      T* get() const noexcept { return getIter().get(); }
+
+      // Invalidates this iterator
+      void reset() noexcept {
+        // Point iterator to first list's rend
+        tIter_.reset();
+        mIter_.reset();
+      }
+
+      // 1. Invalidate this iterator
+      // 2. Unlock
+      void destroy() {
+        reset();
+        if (l_.owns_lock()) {
+          l_.unlock();
+        }
+      }
+
+      // Reset this iterator to the beginning
+      void resetToBegin() {
+        if (!l_.owns_lock()) {
+          l_.lock();
+        }
+        tIter_.resetToBegin();
+        mIter_.resetToBegin();
+      }
+
+     private:
+      // private because it's easy to misuse and cause deadlock for MMTinyLFU
+      LockedIterator& operator=(LockedIterator&&) noexcept = default;
+
+      // create an lru iterator with the lock being held.
+      explicit LockedIterator(LockHolder l,
+                              const Container<T, HookPtr>& c) noexcept;
+
+      const ListIterator& getIter() const noexcept {
+        return evictTiny() ? tIter_ : mIter_;
+      }
+
+      ListIterator& getIter() noexcept {
+        return const_cast<ListIterator&>(
+            static_cast<const LockedIterator*>(this)->getIter());
+      }
+
+      bool evictTiny() const noexcept {
+        if (!mIter_) {
+          return true;
+        }
+        if (!tIter_) {
+          return false;
+        }
+        // Since iterators don't change the state of the container, we evict
+        // from tiny or main depending on whether the tiny node would be
+        // admitted to main cache. If it would be, we evict from main cache,
+        // otherwise tiny cache.
+        return !c_.admitToMain(*tIter_, *mIter_);
+      }
+
+      // only the container can create iterators
+      friend Container<T, HookPtr>;
+
+      const Container<T, HookPtr>& c_;
+      // Tiny and main cache iterators
+      ListIterator tIter_;
+      ListIterator mIter_;
+      // lock protecting the validity of the iterator
+      LockHolder l_;
+    };
+
+    Config getConfig() const;
+
+    void setConfig(const Config& newConfig);
+
+    bool isEmpty() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size() == 0;
+    }
+
+    size_t size() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size();
+    }
+
+    // reconfigure the MMContainer: update refresh time according to current
+    // tail age
+    void reconfigureLocked(const Time& currTime);
+
+    size_t counterSize() const noexcept {
+      LockHolder l(lruMutex_);
+      return accessFreq_.getByteSize();
+    }
+
+    // Returns the eviction age stats. See CacheStats.h for details
+    EvictionAgeStat getEvictionAgeStat(uint64_t projectedLength) const noexcept;
+
+    // Obtain an iterator that start from the tail and can be used
+    // to search for evictions. This iterator holds a lock to this
+    // container and only one such iterator can exist at a time
+    LockedIterator getEvictionIterator() const noexcept;
+
+    // Execute provided function under container lock. Function gets
+    // iterator passed as parameter.
+    template <typename F>
+    void withEvictionIterator(F&& f);
+
+    // Execute provided function under container lock.
+    template <typename F>
+    void withContainerLock(F&& f);
+
+    // for saving the state of the lru
+    //
+    // precondition:  serialization must happen without any reader or writer
+    // present. Any modification of this object afterwards will result in an
+    // invalid, inconsistent state for the serialized data.
+    //
+    serialization::MMTinyLFUObject saveState() const noexcept;
+
+    // return the stats for this container.
+    MMContainerStat getStats() const noexcept;
+
+    static LruType getLruType(const T& node) noexcept {
+      return isTiny(node) ? LruType::Tiny : 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);
+    }
+
+    // Returns the hash of node's key
+    static size_t hashNode(const T& node) noexcept {
+      return folly::hasher<folly::StringPiece>()(node.getKey());
+    }
+
+    // Returns true if tiny node must be admitted to main cache since its
+    // frequency is higher than that of the main node.
+    bool admitToMain(const T& tinyNode, const T& mainNode) const noexcept {
+      XDCHECK(isTiny(tinyNode));
+      XDCHECK(!isTiny(mainNode));
+      return true;
+    }
+
+    // remove node from lru and adjust insertion points
+    //
+    // @param node          node to remove
+    void removeLocked(T& node) noexcept;
+
+    static bool isTiny(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag0>();
+    }
+
+    static bool isAccessed(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag1>();
+    }
+
+    // Bit MM_BIT_0 is used to record if the item is in tiny cache.
+    static void markTiny(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag0>();
+    }
+    static void unmarkTiny(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag0>();
+    }
+
+    // Bit MM_BIT_1 is used to record if the item has been accessed since being
+    // written in cache. Unaccessed items are ignored when determining projected
+    // update time.
+    static void markAccessed(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag1>();
+    }
+    static void unmarkAccessed(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag1>();
+    }
+
+    // Initial cache capacity estimate for count-min-sketch
+    static constexpr size_t kDefaultCapacity = 100;
+
+    // Number of hashes
+    static constexpr size_t kHashCount = 4;
+
+    // The error threshold for frequency calculation
+    static constexpr size_t kErrorThreshold = 5;
+
+    // decay rate for frequency
+    static constexpr double kDecayFactor = 0.5;
+
+    // protects all operations on the lru. We never really just read the state
+    // of the LRU. Hence we dont really require a RW mutex at this point of
+    // time.
+    mutable Mutex lruMutex_;
+
+    // the lru
+    LruList lru_;
+
+    // the window size counter
+    size_t windowSize_{0};
+
+    // maximum value of window size which when hit the counters are halved
+    size_t maxWindowSize_{0};
+
+    // The capacity for which the counters are sized
+    size_t capacity_{0};
+
+    // The next time to reconfigure the container.
+    std::atomic<Time> nextReconfigureTime_{};
+
+    // How often to promote an item in the eviction queue.
+    std::atomic<uint32_t> lruRefreshTime_{};
+
+    // Max lruFreshTime.
+    static constexpr uint32_t kLruRefreshTimeCap{900};
+
+    // Config for this lru.
+    // Write access to the MMTinyLFU Config is serialized.
+    // Reads may be racy.
+    Config config_{};
+
+    // Approximate streaming frequency counters. The counts are halved every
+    // time the maxWindowSize is hit.
+    facebook::cachelib::util::CountMinSketch accessFreq_{};
+
+    FRIEND_TEST(MMTinyLFUTest, SegmentStress);
+    FRIEND_TEST(MMTinyLFUTest, TinyLFUBasic);
+    FRIEND_TEST(MMTinyLFUTest, Reconfigure);
+  };
+};
+
+/* Container Interface Implementation */
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+MMTinyLFU::Container<T, HookPtr>::Container(
+    serialization::MMTinyLFUObject object, PtrCompressor compressor)
+    : lru_(*object.lrus(), std::move(compressor)), config_(*object.config()) {
+  lruRefreshTime_ = config_.lruRefreshTime;
+  nextReconfigureTime_ = config_.mmReconfigureIntervalSecs.count() == 0
+                             ? std::numeric_limits<Time>::max()
+                             : static_cast<Time>(util::getCurrentTimeSec()) +
+                                   config_.mmReconfigureIntervalSecs.count();
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+bool MMTinyLFU::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());
+  // check if the node is still being memory managed
+  if (node.isInMMContainer() &&
+      ((curr >= getUpdateTime(node) +
+                    lruRefreshTime_.load(std::memory_order_relaxed)) ||
+       !isAccessed(node))) {
+    if (!isAccessed(node)) {
+      markAccessed(node);
+    }
+    LockHolder l(lruMutex_, std::defer_lock);
+    if (config_.tryLockUpdate) {
+      l.try_lock();
+    } else {
+      l.lock();
+    }
+    if (!l.owns_lock()) {
+      return false;
+    }
+    if (!node.isInMMContainer()) {
+      return false;
+    }
+
+    setUpdateTime(node, curr);
+    return true;
+  }
+  return false;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+cachelib::EvictionAgeStat MMTinyLFU::Container<T, HookPtr>::getEvictionAgeStat(
+    uint64_t projectedLength) const noexcept {
+  LockHolder l(lruMutex_);
+  return getEvictionAgeStatLocked(projectedLength);
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+cachelib::EvictionAgeStat
+MMTinyLFU::Container<T, HookPtr>::getEvictionAgeStatLocked(
+    uint64_t projectedLength) const noexcept {
+  EvictionAgeStat stat;
+  const auto curr = static_cast<Time>(util::getCurrentTimeSec());
+
+  auto& list = lru_.getList(LruType::Main);
+  auto it = list.rbegin();
+  stat.warmQueueStat.oldestElementAge =
+      it != list.rend() ? curr - 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()
+                                        ? curr - getUpdateTime(*it)
+                                        : stat.warmQueueStat.oldestElementAge;
+  return stat;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+bool MMTinyLFU::Container<T, HookPtr>::add(T& node) noexcept {
+  const auto currTime = static_cast<Time>(util::getCurrentTimeSec());
+  LockHolder l(lruMutex_);
+  if (node.isInMMContainer()) {
+    return false;
+  }
+
+  auto& tinyLru = lru_.getList(LruType::Tiny);
+  tinyLru.linkAtHead(node);
+  markTiny(node);
+
+  // If tiny cache is full, unconditionally promote tail to main cache.
+  const auto expectedSize = config_.tinySizePercent * lru_.size() / 100;
+  if (lru_.getList(LruType::Tiny).size() > expectedSize) {
+    auto tailNode = tinyLru.getTail();
+    tinyLru.remove(*tailNode);
+
+    auto& mainLru = lru_.getList(LruType::Main);
+    mainLru.linkAtHead(*tailNode);
+    unmarkTiny(*tailNode);
+  }
+
+  node.markInMMContainer();
+  setUpdateTime(node, currTime);
+  unmarkAccessed(node);
+  return true;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+typename MMTinyLFU::Container<T, HookPtr>::LockedIterator
+MMTinyLFU::Container<T, HookPtr>::getEvictionIterator() const noexcept {
+  LockHolder l(lruMutex_);
+  return LockedIterator{std::move(l), *this};
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+template <typename F>
+void MMTinyLFU::Container<T, HookPtr>::withEvictionIterator(F&& fun) {
+  // TinyLFU uses spin lock which does not support combined locking
+  fun(getEvictionIterator());
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+template <typename F>
+void MMTinyLFU::Container<T, HookPtr>::withContainerLock(F&& fun) {
+  LockHolder l(lruMutex_);
+  fun();
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+void MMTinyLFU::Container<T, HookPtr>::removeLocked(T& node) noexcept {
+  if (isTiny(node)) {
+    lru_.getList(LruType::Tiny).remove(node);
+    unmarkTiny(node);
+  } else {
+    lru_.getList(LruType::Main).remove(node);
+  }
+
+  unmarkAccessed(node);
+  node.unmarkInMMContainer();
+  return;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+bool MMTinyLFU::Container<T, HookPtr>::remove(T& node) noexcept {
+  LockHolder l(lruMutex_);
+  if (!node.isInMMContainer()) {
+    return false;
+  }
+  removeLocked(node);
+  return true;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+void MMTinyLFU::Container<T, HookPtr>::remove(LockedIterator& it) noexcept {
+  T& node = *it;
+  XDCHECK(node.isInMMContainer());
+  ++it;
+  removeLocked(node);
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+bool MMTinyLFU::Container<T, HookPtr>::replace(T& oldNode,
+                                               T& newNode) noexcept {
+  LockHolder l(lruMutex_);
+  if (!oldNode.isInMMContainer() || newNode.isInMMContainer()) {
+    return false;
+  }
+  const auto updateTime = getUpdateTime(oldNode);
+
+  if (isTiny(oldNode)) {
+    lru_.getList(LruType::Tiny).replace(oldNode, newNode);
+    unmarkTiny(oldNode);
+    markTiny(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, MMTinyLFU::Hook<T> T::* HookPtr>
+typename MMTinyLFU::Config MMTinyLFU::Container<T, HookPtr>::getConfig() const {
+  LockHolder l(lruMutex_);
+  return config_;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+void MMTinyLFU::Container<T, HookPtr>::setConfig(const Config& c) {
+  LockHolder l(lruMutex_);
+  config_ = c;
+  lruRefreshTime_.store(config_.lruRefreshTime, std::memory_order_relaxed);
+  nextReconfigureTime_ = config_.mmReconfigureIntervalSecs.count() == 0
+                             ? std::numeric_limits<Time>::max()
+                             : static_cast<Time>(util::getCurrentTimeSec()) +
+                                   config_.mmReconfigureIntervalSecs.count();
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+serialization::MMTinyLFUObject MMTinyLFU::Container<T, HookPtr>::saveState()
+    const noexcept {
+  serialization::MMTinyLFUConfig configObject;
+  *configObject.lruRefreshTime() =
+      lruRefreshTime_.load(std::memory_order_relaxed);
+  *configObject.lruRefreshRatio() = config_.lruRefreshRatio;
+  *configObject.updateOnWrite() = config_.updateOnWrite;
+  *configObject.updateOnRead() = config_.updateOnRead;
+  *configObject.windowToCacheSizeRatio() = config_.windowToCacheSizeRatio;
+  *configObject.tinySizePercent() = config_.tinySizePercent;
+  *configObject.mmReconfigureIntervalSecs() =
+      config_.mmReconfigureIntervalSecs.count();
+  *configObject.newcomerWinsOnTie() = config_.newcomerWinsOnTie;
+  // TODO: May be save/restore the counters.
+
+  serialization::MMTinyLFUObject object;
+  *object.config() = configObject;
+  *object.lrus() = lru_.saveState();
+  return object;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+MMContainerStat MMTinyLFU::Container<T, HookPtr>::getStats() const noexcept {
+  LockHolder l(lruMutex_);
+  auto* tail = lru_.size() == 0 ? nullptr : lru_.rbegin().get();
+  return {lru_.size(),
+          tail == nullptr ? 0 : getUpdateTime(*tail),
+          lruRefreshTime_.load(std::memory_order_relaxed),
+          0,
+          0,
+          0,
+          0};
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+void MMTinyLFU::Container<T, HookPtr>::reconfigureLocked(const Time& currTime) {
+  if (currTime < nextReconfigureTime_) {
+    return;
+  }
+  nextReconfigureTime_ = currTime + config_.mmReconfigureIntervalSecs.count();
+
+  // update LRU refresh time
+  auto stat = getEvictionAgeStatLocked(0);
+  auto lruRefreshTime = std::min(
+      std::max(config_.defaultLruRefreshTime,
+               static_cast<uint32_t>(stat.warmQueueStat.oldestElementAge *
+                                     config_.lruRefreshRatio)),
+      kLruRefreshTimeCap);
+
+  lruRefreshTime_.store(lruRefreshTime, std::memory_order_relaxed);
+}
+
+// Locked Iterator Context Implementation
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+MMTinyLFU::Container<T, HookPtr>::LockedIterator::LockedIterator(
+    LockHolder l, const Container<T, HookPtr>& c) noexcept
+    : c_(c),
+      tIter_(c.lru_.getList(LruType::Tiny).rbegin()),
+      mIter_(c.lru_.getList(LruType::Main).rbegin()),
+      l_(std::move(l)) {}
+} // namespace facebook::cachelib
diff --git a/cachelib/allocator/MMTinyLFU-v1.h b/cachelib/allocator/MMTinyLFU-v1.h
new file mode 100644
index 0000000000..f4c36f162a
--- /dev/null
+++ b/cachelib/allocator/MMTinyLFU-v1.h
@@ -0,0 +1,847 @@
+/*
+ * 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>
+#include <folly/Math.h>
+#pragma GCC diagnostic pop
+
+#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/CountMinSketch.h"
+#include "cachelib/common/Mutex.h"
+
+namespace facebook::cachelib {
+// This version moves s3fifo_v0 to mmtinylfu template
+class MMTinyLFU {
+ public:
+  // unique identifier per MMType
+  static const int kId;
+
+  // forward declaration;
+  template <typename T>
+  using Hook = DListHook<T>;
+  using SerializationType = serialization::MMTinyLFUObject;
+  using SerializationConfigType = serialization::MMTinyLFUConfig;
+  using SerializationTypeContainer = serialization::MMTinyLFUCollection;
+
+  enum LruType { Main, Tiny, NumTypes };
+
+  // Config class for MMTinfyLFU
+  struct Config {
+    // create from serialized config
+    explicit Config(SerializationConfigType configState)
+        : Config(*configState.lruRefreshTime(),
+                 *configState.lruRefreshRatio(),
+                 *configState.updateOnWrite(),
+                 *configState.updateOnRead(),
+                 *configState.tryLockUpdate(),
+                 *configState.windowToCacheSizeRatio(),
+                 *configState.tinySizePercent(),
+                 *configState.mmReconfigureIntervalSecs(),
+                 *configState.newcomerWinsOnTie()) {}
+
+    // @param time        the LRU refresh time in seconds.
+    //                    An item will be promoted only once in each lru refresh
+    //                    time depite the number of accesses it gets.
+    // @param udpateOnW   whether to promote the item on write
+    // @param updateOnR   whether to promote the item on read
+    Config(uint32_t time, bool updateOnW, bool updateOnR)
+        : Config(time,
+                 updateOnW,
+                 updateOnR,
+                 /* try lock update */ false,
+                 16,
+                 1) {}
+
+    // @param time              the LRU refresh time in seconds.
+    //                          An item will be promoted only once in each lru
+    //                          refresh time depite the number of accesses it
+    //                          gets.
+    // @param udpateOnW         whether to promote the item on write
+    // @param updateOnR         whether to promote the item on read
+    // @param windowToCacheSize multiplier of window size to cache size
+    // @param tinySizePct       percentage number of tiny size to overall size
+    Config(uint32_t time,
+           bool updateOnW,
+           bool updateOnR,
+           size_t windowToCacheSize,
+           size_t tinySizePct)
+        : Config(time,
+                 updateOnW,
+                 updateOnR,
+                 /* try lock update */ false,
+                 windowToCacheSize,
+                 tinySizePct) {}
+
+    // @param time              the LRU refresh time in seconds.
+    //                          An item will be promoted only once in each lru
+    //                          refresh time depite the number of accesses it
+    //                          gets.
+    // @param udpateOnW         whether to promote the item on write
+    // @param updateOnR         whether to promote the item on read
+    // @param tryLockU          whether to use a try lock when doing update.
+    // @param windowToCacheSize multiplier of window size to cache size
+    // @param tinySizePct       percentage number of tiny size to overall size
+    Config(uint32_t time,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t windowToCacheSize,
+           size_t tinySizePct)
+        : Config(time,
+                 0.,
+                 updateOnW,
+                 updateOnR,
+                 tryLockU,
+                 windowToCacheSize,
+                 tinySizePct) {}
+
+    // @param time                    the LRU refresh time in seconds.
+    //                                An item will be promoted only once in each
+    //                                lru refresh time depite the number of
+    //                                accesses it gets.
+    // @param ratio                   the lru refresh ratio. The ratio times the
+    //                                oldest element's lifetime in warm queue
+    //                                would be the minimum value of LRU refresh
+    //                                time.
+    // @param udpateOnW               whether to promote the item on write
+    // @param updateOnR               whether to promote the item on read
+    // @param tryLockU                whether to use a try lock when doing
+    //                                update.
+    // @param windowToCacheSize       multiplier of window size to cache size
+    // @param tinySizePct             percentage number of tiny size to overall
+    //                                size
+    Config(uint32_t time,
+           double ratio,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t windowToCacheSize,
+           size_t tinySizePct)
+        : Config(time,
+                 ratio,
+                 updateOnW,
+                 updateOnR,
+                 tryLockU,
+                 windowToCacheSize,
+                 tinySizePct,
+                 0) {}
+
+    // @param time                    the LRU refresh time in seconds.
+    //                                An item will be promoted only once in each
+    //                                lru refresh time depite the number of
+    //                                accesses it gets.
+    // @param ratio                   the lru refresh ratio. The ratio times the
+    //                                oldest element's lifetime in warm queue
+    //                                would be the minimum value of LRU refresh
+    //                                time.
+    // @param udpateOnW               whether to promote the item on write
+    // @param updateOnR               whether to promote the item on read
+    // @param tryLockU                whether to use a try lock when doing
+    //                                update.
+    // @param windowToCacheSize       multiplier of window size to cache size
+    // @param tinySizePct             percentage number of tiny size to overall
+    //                                size
+    // @param mmReconfigureInterval   Time interval for recalculating lru
+    //                                refresh time according to the ratio.
+    Config(uint32_t time,
+           double ratio,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t windowToCacheSize,
+           size_t tinySizePct,
+           uint32_t mmReconfigureInterval)
+        : defaultLruRefreshTime(time),
+          lruRefreshRatio(ratio),
+          updateOnWrite(updateOnW),
+          updateOnRead(updateOnR),
+          tryLockUpdate(tryLockU),
+          windowToCacheSizeRatio(windowToCacheSize),
+          tinySizePercent(tinySizePct),
+          mmReconfigureIntervalSecs(
+              std::chrono::seconds(mmReconfigureInterval)) {
+      checkConfig();
+    }
+
+    // @param time                    the LRU refresh time in seconds.
+    //                                An item will be promoted only once in each
+    //                                lru refresh time depite the number of
+    //                                accesses it gets.
+    // @param ratio                   the lru refresh ratio. The ratio times the
+    //                                oldest element's lifetime in warm queue
+    //                                would be the minimum value of LRU refresh
+    //                                time.
+    // @param udpateOnW               whether to promote the item on write
+    // @param updateOnR               whether to promote the item on read
+    // @param tryLockU                whether to use a try lock when doing
+    //                                update.
+    // @param windowToCacheSize       multiplier of window size to cache size
+    // @param tinySizePct             percentage number of tiny size to overall
+    //                                size
+    // @param mmReconfigureInterval   Time interval for recalculating lru
+    //                                refresh time according to the ratio.
+    // @param newcomerWinsOnTie       If true, new comer will replace existing
+    //                                item if their access frequencies tie.
+    Config(uint32_t time,
+           double ratio,
+           bool updateOnW,
+           bool updateOnR,
+           bool tryLockU,
+           size_t windowToCacheSize,
+           size_t tinySizePct,
+           uint32_t mmReconfigureInterval,
+           bool _newcomerWinsOnTie)
+        : defaultLruRefreshTime(time),
+          lruRefreshRatio(ratio),
+          updateOnWrite(updateOnW),
+          updateOnRead(updateOnR),
+          tryLockUpdate(tryLockU),
+          windowToCacheSizeRatio(windowToCacheSize),
+          tinySizePercent(tinySizePct),
+          mmReconfigureIntervalSecs(
+              std::chrono::seconds(mmReconfigureInterval)),
+          newcomerWinsOnTie(_newcomerWinsOnTie) {
+      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 (tinySizePercent < 1 || tinySizePercent > 50) {
+        throw std::invalid_argument(
+            folly::sformat("Invalid tiny cache size {}. Tiny cache size "
+                           "must be between 1% and 50% of total cache size ",
+                           tinySizePercent));
+      }
+      if (windowToCacheSizeRatio < 2 || windowToCacheSizeRatio > 128) {
+        throw std::invalid_argument(
+            folly::sformat("Invalid window to cache size ratio {}. The ratio "
+                           "must be between 2 and 128",
+                           windowToCacheSizeRatio));
+      }
+    }
+
+    template <typename... Args>
+    void addExtraConfig(Args...) {}
+
+    // threshold value in seconds to compare with a node's update time to
+    // determine if we need to update the position of the node in the linked
+    // list. By default this is 60s to reduce the contention on the lru lock.
+    uint32_t defaultLruRefreshTime{60};
+    uint32_t lruRefreshTime{defaultLruRefreshTime};
+
+    // ratio of LRU refresh time to the tail age. If a refresh time computed
+    // according to this ratio is larger than lruRefreshtime, we will adopt
+    // this one instead of the lruRefreshTime set.
+    double lruRefreshRatio{0.};
+
+    // whether the lru needs to be updated on writes for recordAccess. If
+    // false, accessing the cache for writes does not promote the cached item
+    // to the head of the lru.
+    bool updateOnWrite{false};
+
+    // whether the lru needs to be updated on reads for recordAccess. If
+    // false, accessing the cache for reads does not promote the cached item
+    // to the head of the lru.
+    bool updateOnRead{true};
+
+    // whether to tryLock or lock the lru lock when attempting promotion on
+    // access. If set, and tryLock fails, access will not result in promotion.
+    bool tryLockUpdate{false};
+
+    // The multiplier for window size given the cache size.
+    size_t windowToCacheSizeRatio{32};
+
+    // The size of tiny cache, as a percentage of the total size.
+    size_t tinySizePercent{1};
+
+    // Minimum interval between reconfigurations. If 0, reconfigure is never
+    // called.
+    std::chrono::seconds mmReconfigureIntervalSecs{};
+
+    // If true, then if an item in the tail of the Tiny queue ties with the
+    // item in the tail of the main queue, the item from Tiny (newcomer) will
+    // replace the item from Main. This is fine for a default, but for
+    // strictly scan patterns (access a key exactly once and move on), this
+    // is not a desirable behavior (we'll always cache miss).
+    bool newcomerWinsOnTie{true};
+  };
+
+  // The container object which can be used to keep track of objects of type
+  // T. T must have a public member of type Hook. This object is wrapper
+  // around DList, is thread safe and can be accessed from multiple threads.
+  // The current implementation models an LRU using the above DList
+  // implementation.
+  template <typename T, Hook<T> T::* HookPtr>
+  struct Container {
+   private:
+    using LruList = MultiDList<T, HookPtr>;
+    using Mutex = folly::SpinLock;
+    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)) {
+      lruRefreshTime_ = config_.lruRefreshTime;
+      nextReconfigureTime_ =
+          config_.mmReconfigureIntervalSecs.count() == 0
+              ? std::numeric_limits<Time>::max()
+              : static_cast<Time>(util::getCurrentTimeSec()) +
+                    config_.mmReconfigureIntervalSecs.count();
+    }
+    Container(serialization::MMTinyLFUObject object, PtrCompressor compressor);
+
+    Container(const Container&) = delete;
+    Container& operator=(const Container&) = delete;
+
+    // records the information that the node was accessed. This could bump up
+    // the node to the head of the lru depending on the time when the node was
+    // last updated in lru and the kLruRefreshTime. If the node was moved to
+    // the head in the lru, the node's updateTime will be updated
+    // accordingly.
+    //
+    // @param node  node that we want to mark as relevant/accessed
+    // @param mode  the mode for the access operation.
+    //
+    // @return      True if the information is recorded and bumped the node
+    //              to the head of the lru, returns false otherwise
+    bool recordAccess(T& node, AccessMode mode) noexcept;
+
+    // adds the given node into the container and marks it as being present in
+    // the container. The node is added to the head of the lru.
+    //
+    // @param node  The node to be added to the container.
+    // @return  True if the node was successfully added to the container. False
+    //          if the node was already in the contianer. On error state of node
+    //          is unchanged.
+    bool add(T& node) noexcept;
+
+    // removes the node from the lru and sets it previous and next to nullptr.
+    //
+    // @param node  The node to be removed from the container.
+    // @return  True if the node was successfully removed from the container.
+    //          False if the node was not part of the container. On error, the
+    //          state of node is unchanged.
+    bool remove(T& node) noexcept;
+
+    class LockedIterator;
+    // same as the above but uses an iterator context. The iterator is updated
+    // on removal of the corresponding node to point to the next node. The
+    // iterator context holds the lock on the lru.
+    //
+    // iterator will be advanced to the next node after removing the node
+    //
+    // @param it    Iterator that will be removed
+    void remove(LockedIterator& it) noexcept;
+
+    // replaces one node with another, at the same position
+    //
+    // @param oldNode   node being replaced
+    // @param newNode   node to replace oldNode with
+    //
+    // @return true  If the replace was successful. Returns false if the
+    //               destination node did not exist in the container, or if the
+    //               source node already existed.
+    bool replace(T& oldNode, T& newNode) noexcept;
+
+    // context for iterating the MM container. At any given point of time,
+    // there can be only one iterator active since we need to lock the LRU for
+    // iteration. we can support multiple iterators at same time, by using a
+    // shared ptr in the context for the lock holder in the future.
+    class LockedIterator {
+     public:
+      using ListIterator = typename LruList::DListIterator;
+      // noncopyable but movable.
+      LockedIterator(const LockedIterator&) = delete;
+      LockedIterator& operator=(const LockedIterator&) = delete;
+      LockedIterator(LockedIterator&&) noexcept = default;
+
+      LockedIterator& operator++() noexcept {
+        ++getIter();
+        return *this;
+      }
+
+      LockedIterator& operator--() {
+        throw std::invalid_argument(
+            "Decrementing eviction iterator is not supported");
+      }
+
+      T* operator->() const noexcept { return getIter().operator->(); }
+      T& operator*() const noexcept { return getIter().operator*(); }
+
+      bool operator==(const LockedIterator& other) const noexcept {
+        return &c_ == &other.c_ && tIter_ == other.tIter_ &&
+               mIter_ == other.mIter_;
+      }
+
+      bool operator!=(const LockedIterator& other) const noexcept {
+        return !(*this == other);
+      }
+
+      explicit operator bool() const noexcept { return tIter_ || mIter_; }
+
+      T* get() const noexcept { return getIter().get(); }
+
+      // Invalidates this iterator
+      void reset() noexcept {
+        // Point iterator to first list's rend
+        tIter_.reset();
+        mIter_.reset();
+      }
+
+      // 1. Invalidate this iterator
+      // 2. Unlock
+      void destroy() {
+        reset();
+        if (l_.owns_lock()) {
+          l_.unlock();
+        }
+      }
+
+      // Reset this iterator to the beginning
+      void resetToBegin() {
+        if (!l_.owns_lock()) {
+          l_.lock();
+        }
+        tIter_.resetToBegin();
+        mIter_.resetToBegin();
+      }
+
+     private:
+      // private because it's easy to misuse and cause deadlock for MMTinyLFU
+      LockedIterator& operator=(LockedIterator&&) noexcept = default;
+
+      // create an lru iterator with the lock being held.
+      explicit LockedIterator(LockHolder l,
+                              const Container<T, HookPtr>& c) noexcept;
+
+      const ListIterator& getIter() const noexcept {
+        return evictTiny() ? tIter_ : mIter_;
+      }
+
+      ListIterator& getIter() noexcept {
+        return const_cast<ListIterator&>(
+            static_cast<const LockedIterator*>(this)->getIter());
+      }
+
+      bool evictTiny() const noexcept {
+        if (!mIter_) {
+          return true;
+        }
+        if (!tIter_) {
+          return false;
+        }
+
+        const auto expectedSize =
+            c_.config_.tinySizePercent * c_.lru_.size() / 100;
+        auto isTinyBig = c_.lru_.getList(LruType::Tiny).size() > expectedSize;
+        return isTinyBig;
+      }
+
+      // only the container can create iterators
+      friend Container<T, HookPtr>;
+
+      const Container<T, HookPtr>& c_;
+      // Tiny and main cache iterators
+      ListIterator tIter_;
+      ListIterator mIter_;
+      // lock protecting the validity of the iterator
+      LockHolder l_;
+    };
+
+    Config getConfig() const;
+
+    void setConfig(const Config& newConfig);
+
+    bool isEmpty() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size() == 0;
+    }
+
+    size_t size() const noexcept {
+      LockHolder l(lruMutex_);
+      return lru_.size();
+    }
+
+    // reconfigure the MMContainer: update refresh time according to current
+    // tail age
+    void reconfigureLocked(const Time& currTime);
+
+    size_t counterSize() const noexcept {
+      LockHolder l(lruMutex_);
+      return accessFreq_.getByteSize();
+    }
+
+    // Returns the eviction age stats. See CacheStats.h for details
+    EvictionAgeStat getEvictionAgeStat(uint64_t projectedLength) const noexcept;
+
+    // Obtain an iterator that start from the tail and can be used
+    // to search for evictions. This iterator holds a lock to this
+    // container and only one such iterator can exist at a time
+    LockedIterator getEvictionIterator() const noexcept;
+
+    // Execute provided function under container lock. Function gets
+    // iterator passed as parameter.
+    template <typename F>
+    void withEvictionIterator(F&& f);
+
+    // Execute provided function under container lock.
+    template <typename F>
+    void withContainerLock(F&& f);
+
+    // for saving the state of the lru
+    //
+    // precondition:  serialization must happen without any reader or writer
+    // present. Any modification of this object afterwards will result in an
+    // invalid, inconsistent state for the serialized data.
+    //
+    serialization::MMTinyLFUObject saveState() const noexcept;
+
+    // return the stats for this container.
+    MMContainerStat getStats() const noexcept;
+
+    static LruType getLruType(const T& node) noexcept {
+      return isTiny(node) ? LruType::Tiny : LruType::Main;
+    }
+
+    // the lru
+    LruList lru_;
+
+   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);
+    }
+
+    // Returns the hash of node's key
+    static size_t hashNode(const T& node) noexcept {
+      return folly::hasher<folly::StringPiece>()(node.getKey());
+    }
+
+    // remove node from lru and adjust insertion points
+    //
+    // @param node          node to remove
+    void removeLocked(T& node) noexcept;
+
+    static bool isTiny(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag0>();
+    }
+
+    static bool isAccessed(const T& node) noexcept {
+      return node.template isFlagSet<RefFlags::kMMFlag1>();
+    }
+
+    // Bit MM_BIT_0 is used to record if the item is in tiny cache.
+    static void markTiny(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag0>();
+    }
+    static void unmarkTiny(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag0>();
+    }
+
+    // Bit MM_BIT_1 is used to record if the item has been accessed since being
+    // written in cache. Unaccessed items are ignored when determining projected
+    // update time.
+    static void markAccessed(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag1>();
+    }
+    static void unmarkAccessed(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag1>();
+    }
+
+    // Initial cache capacity estimate for count-min-sketch
+    static constexpr size_t kDefaultCapacity = 100;
+
+    // Number of hashes
+    static constexpr size_t kHashCount = 4;
+
+    // The error threshold for frequency calculation
+    static constexpr size_t kErrorThreshold = 5;
+
+    // decay rate for frequency
+    static constexpr double kDecayFactor = 0.5;
+
+    // protects all operations on the lru. We never really just read the state
+    // of the LRU. Hence we dont really require a RW mutex at this point of
+    // time.
+    mutable Mutex lruMutex_;
+
+    // the window size counter
+    size_t windowSize_{0};
+
+    // maximum value of window size which when hit the counters are halved
+    size_t maxWindowSize_{0};
+
+    // The capacity for which the counters are sized
+    size_t capacity_{0};
+
+    // The next time to reconfigure the container.
+    std::atomic<Time> nextReconfigureTime_{};
+
+    // How often to promote an item in the eviction queue.
+    std::atomic<uint32_t> lruRefreshTime_{};
+
+    // Max lruFreshTime.
+    static constexpr uint32_t kLruRefreshTimeCap{900};
+
+    // Config for this lru.
+    // Write access to the MMTinyLFU Config is serialized.
+    // Reads may be racy.
+    Config config_{};
+
+    // Approximate streaming frequency counters. The counts are halved every
+    // time the maxWindowSize is hit.
+    facebook::cachelib::util::CountMinSketch accessFreq_{};
+
+    FRIEND_TEST(MMTinyLFUTest, SegmentStress);
+    FRIEND_TEST(MMTinyLFUTest, TinyLFUBasic);
+    FRIEND_TEST(MMTinyLFUTest, Reconfigure);
+  };
+};
+
+/* Container Interface Implementation */
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+MMTinyLFU::Container<T, HookPtr>::Container(
+    serialization::MMTinyLFUObject object, PtrCompressor compressor)
+    : lru_(*object.lrus(), std::move(compressor)), config_(*object.config()) {}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+bool MMTinyLFU::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());
+  // check if the node is still being memory managed
+  if (node.isInMMContainer() && !isAccessed(node)) {
+    markAccessed(node);
+    setUpdateTime(node, curr);
+    return true;
+  }
+  return false;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+cachelib::EvictionAgeStat MMTinyLFU::Container<T, HookPtr>::getEvictionAgeStat(
+    uint64_t projectedLength) const noexcept {
+  LockHolder l(lruMutex_);
+  return getEvictionAgeStatLocked(projectedLength);
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+cachelib::EvictionAgeStat
+MMTinyLFU::Container<T, HookPtr>::getEvictionAgeStatLocked(
+    uint64_t projectedLength) const noexcept {
+  EvictionAgeStat stat;
+  const auto curr = static_cast<Time>(util::getCurrentTimeSec());
+
+  auto& list = lru_.getList(LruType::Main);
+  auto it = list.rbegin();
+  stat.warmQueueStat.oldestElementAge =
+      it != list.rend() ? curr - 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()
+                                        ? curr - getUpdateTime(*it)
+                                        : stat.warmQueueStat.oldestElementAge;
+  return stat;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+bool MMTinyLFU::Container<T, HookPtr>::add(T& node) noexcept {
+  const auto currTime = static_cast<Time>(util::getCurrentTimeSec());
+  LockHolder l(lruMutex_);
+  if (node.isInMMContainer()) {
+    return false;
+  }
+
+  auto& tinyLru = lru_.getList(LruType::Tiny);
+  tinyLru.linkAtHead(node);
+  markTiny(node);
+
+  // If tiny cache is full, unconditionally promote tail to main cache.
+  const auto expectedSize = config_.tinySizePercent * lru_.size() / 100;
+  if (lru_.getList(LruType::Tiny).size() > expectedSize) {
+    auto tailNode = tinyLru.getTail();
+    tinyLru.remove(*tailNode);
+
+    auto& mainLru = lru_.getList(LruType::Main);
+    mainLru.linkAtHead(*tailNode);
+    unmarkTiny(*tailNode);
+  }
+
+  node.markInMMContainer();
+  setUpdateTime(node, currTime);
+  unmarkAccessed(node);
+  return true;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+typename MMTinyLFU::Container<T, HookPtr>::LockedIterator
+MMTinyLFU::Container<T, HookPtr>::getEvictionIterator() const noexcept {
+  LockHolder l(lruMutex_);
+  return LockedIterator{std::move(l), *this};
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+template <typename F>
+void MMTinyLFU::Container<T, HookPtr>::withEvictionIterator(F&& fun) {
+  // uses spin lock which does not support combined locking
+  fun(getEvictionIterator());
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+template <typename F>
+void MMTinyLFU::Container<T, HookPtr>::withContainerLock(F&& fun) {
+  LockHolder l(lruMutex_);
+  fun();
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+void MMTinyLFU::Container<T, HookPtr>::removeLocked(T& node) noexcept {
+  if (isTiny(node)) {
+    lru_.getList(LruType::Tiny).remove(node);
+    unmarkTiny(node);
+  } else {
+    lru_.getList(LruType::Main).remove(node);
+  }
+
+  unmarkAccessed(node);
+  node.unmarkInMMContainer();
+  return;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+bool MMTinyLFU::Container<T, HookPtr>::remove(T& node) noexcept {
+  LockHolder l(lruMutex_);
+  if (!node.isInMMContainer()) {
+    return false;
+  }
+  removeLocked(node);
+  return true;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+void MMTinyLFU::Container<T, HookPtr>::remove(LockedIterator& it) noexcept {
+  T& node = *it;
+  XDCHECK(node.isInMMContainer());
+  ++it;
+  removeLocked(node);
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+bool MMTinyLFU::Container<T, HookPtr>::replace(T& oldNode,
+                                               T& newNode) noexcept {
+  LockHolder l(lruMutex_);
+  if (!oldNode.isInMMContainer() || newNode.isInMMContainer()) {
+    return false;
+  }
+  const auto updateTime = getUpdateTime(oldNode);
+
+  if (isTiny(oldNode)) {
+    lru_.getList(LruType::Tiny).replace(oldNode, newNode);
+    unmarkTiny(oldNode);
+    markTiny(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, MMTinyLFU::Hook<T> T::* HookPtr>
+typename MMTinyLFU::Config MMTinyLFU::Container<T, HookPtr>::getConfig() const {
+  LockHolder l(lruMutex_);
+  return config_;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+void MMTinyLFU::Container<T, HookPtr>::setConfig(const Config& c) {
+  LockHolder l(lruMutex_);
+  config_ = c;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+serialization::MMTinyLFUObject MMTinyLFU::Container<T, HookPtr>::saveState()
+    const noexcept {
+  serialization::MMTinyLFUConfig configObject;
+  *configObject.updateOnWrite() = config_.updateOnWrite;
+  *configObject.updateOnRead() = config_.updateOnRead;
+  *configObject.tinySizePercent() = config_.tinySizePercent;
+  // TODO: Serialize the ghost queue too.
+  serialization::MMTinyLFUObject object;
+  *object.config() = configObject;
+  *object.lrus() = lru_.saveState();
+  return object;
+}
+
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+MMContainerStat MMTinyLFU::Container<T, HookPtr>::getStats() const noexcept {
+  LockHolder l(lruMutex_);
+  auto* tail = lru_.size() == 0 ? nullptr : lru_.rbegin().get();
+  return {
+      lru_.size(), tail == nullptr ? 0 : getUpdateTime(*tail), 0, 0, 0, 0, 0};
+}
+
+// Locked Iterator Context Implementation
+template <typename T, MMTinyLFU::Hook<T> T::* HookPtr>
+MMTinyLFU::Container<T, HookPtr>::LockedIterator::LockedIterator(
+    LockHolder l, const Container<T, HookPtr>& c) noexcept
+    : c_(c),
+      tIter_(c.lru_.getList(LruType::Tiny).rbegin()),
+      mIter_(c.lru_.getList(LruType::Main).rbegin()),
+      l_(std::move(l)) {}
+} // namespace facebook::cachelib