From c43227abb2570db0bc7b0af52b440bd6c7b476a0 Mon Sep 17 00:00:00 2001
From: Helen <Helen@node0.r650.redundancy-pg0.clemson.cloudlab.us>
Date: Tue, 20 Aug 2024 14:59:15 -0400
Subject: [PATCH 1/3] added sieve implementation and relevant config changes

---
 cachelib/allocator/CacheAllocator.cpp         |   1 +
 cachelib/allocator/CacheAllocator.h           |   8 +
 cachelib/allocator/CacheTraits.h              |   6 +
 cachelib/allocator/MMSieve.h                  | 561 ++++++++++++++++++
 cachelib/allocator/datastruct/SieveList.h     | 448 ++++++++++++++
 .../datastruct/serialize/objects.thrift       |   7 +
 cachelib/allocator/serialize/objects.thrift   |  19 +
 7 files changed, 1050 insertions(+)
 create mode 100755 cachelib/allocator/MMSieve.h
 create mode 100755 cachelib/allocator/datastruct/SieveList.h

diff --git a/cachelib/allocator/CacheAllocator.cpp b/cachelib/allocator/CacheAllocator.cpp
index 010a1e9597..122ebe6c2e 100644
--- a/cachelib/allocator/CacheAllocator.cpp
+++ b/cachelib/allocator/CacheAllocator.cpp
@@ -21,4 +21,5 @@ template class CacheAllocator<LruCacheTrait>;
 template class CacheAllocator<LruCacheWithSpinBucketsTrait>;
 template class CacheAllocator<Lru2QCacheTrait>;
 template class CacheAllocator<TinyLFUCacheTrait>;
+template class CacheAllocator<SieveCacheTrait>;
 } // namespace facebook::cachelib
diff --git a/cachelib/allocator/CacheAllocator.h b/cachelib/allocator/CacheAllocator.h
index 94c2fdf9e8..2164d0af4e 100644
--- a/cachelib/allocator/CacheAllocator.h
+++ b/cachelib/allocator/CacheAllocator.h
@@ -5980,4 +5980,12 @@ using Lru2QAllocator = CacheAllocator<Lru2QCacheTrait>;
 // inserted items. And eventually it will onl admit items that are accessed
 // beyond a threshold into the warm cache.
 using TinyLFUAllocator = CacheAllocator<TinyLFUCacheTrait>;
+
+
+// CacheAllocator with Sieve eviction policy
+// It uses the access bit keep track of item's popularity
+// During eviction, the hand ptr sweeps backward to find itme with access bit turned off,
+// and turns off access bit as it goes. 
+using SieveAllocator = CacheAllocator<SieveCacheTrait>;
+
 } // namespace facebook::cachelib
diff --git a/cachelib/allocator/CacheTraits.h b/cachelib/allocator/CacheTraits.h
index 15e68b9dcc..9994a64436 100644
--- a/cachelib/allocator/CacheTraits.h
+++ b/cachelib/allocator/CacheTraits.h
@@ -55,5 +55,11 @@ struct TinyLFUCacheTrait {
   using AccessTypeLocks = SharedMutexBuckets;
 };
 
+struct SieveCacheTrait {
+  using MMType = MMTinyLFU;
+  using AccessType = ChainedHashTable;
+  using AccessTypeLocks = SharedMutexBuckets;
+};
+
 } // namespace cachelib
 } // namespace facebook
diff --git a/cachelib/allocator/MMSieve.h b/cachelib/allocator/MMSieve.h
new file mode 100755
index 0000000000..2ed56573d3
--- /dev/null
+++ b/cachelib/allocator/MMSieve.h
@@ -0,0 +1,561 @@
+/*
+ * 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>
+#include <cstring>
+
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wconversion"
+#include <folly/Format.h>
+#pragma GCC diagnostic pop
+#include <folly/container/Array.h>
+#include <folly/lang/Aligned.h>
+#include <folly/synchronization/DistributedMutex.h>
+
+#include "cachelib/allocator/Cache.h"
+#include "cachelib/allocator/CacheStats.h"
+#include "cachelib/allocator/Util.h"
+#include "cachelib/allocator/datastruct/SieveList.h"
+#include "cachelib/allocator/memory/serialize/gen-cpp2/objects_types.h"
+#include "cachelib/common/CompilerUtils.h"
+#include "cachelib/common/Mutex.h"
+#include <thread>
+
+
+namespace facebook::cachelib {
+
+class MMSieve {
+ public:
+  // unique identifier per MMType
+  static const int kId;
+
+  // forward declaration;serialize/gen-cpp2/objects_types.h
+  template <typename T>
+  using Hook = SieveListHook<T>;
+  using SerializationType = serialization::MMSieveObject;
+  using SerializationConfigType = serialization::MMSieveConfig;
+  using SerializationTypeContainer = serialization::MMSieveCollection;
+
+  // This is not applicable for MMSieve, just for compile of cache allocator
+  enum LruType { NumTypes };
+
+  // Config class for MMSieve
+  struct Config {
+    // create from serialized config
+    explicit Config(SerializationConfigType configState)
+        : Config(
+                 *configState.updateOnWrite(),
+                 *configState.updateOnRead()
+		 ) {}
+   
+    // @param udpateOnW   whether to set visit bit for the item on write
+    // @param updateOnR   whether to set visit bit for the item on read
+    Config(bool updateOnW, bool updateOnR)
+        : updateOnWrite(updateOnW),
+          updateOnRead(updateOnR),
+	  useCombinedLockForIterators(false) {}
+    
+    // @param udpateOnW   whether to set visit bit for the item on write
+    // @param updateOnR   whether to set visit bit for the item on read
+    // useCombinedLockForIterators    Whether to use combined locking for
+    //                                withEvictionIterator
+    Config(bool updateOnW,
+           bool updateOnR, 
+           bool useCombinedLockForIterators)
+        : updateOnWrite(updateOnW),
+          updateOnRead(updateOnR),
+          useCombinedLockForIterators(useCombinedLockForIterators) {} 
+    
+    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...) {}
+    
+    
+    // Sieve will always set visit bit on write as we there's no locking involved.  
+    bool updateOnWrite{true};
+
+    // whether the sieve 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 sieve.
+    bool updateOnRead{true};
+   
+    // Minimum interval between reconfigurations. If 0, reconfigure is never
+    // called.
+    std::chrono::seconds mmReconfigureIntervalSecs{0};
+
+    // Whether to use combined locking for withEvictionIterator.
+    bool useCombinedLockForIterators{false};
+  };
+
+  // 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 SieveList, is thread safe and can be accessed from multiple threads.
+  // The current implementation models an SIEVE using the above SieveList
+  // implementation.
+  template <typename T, Hook<T> T::*HookPtr>
+  struct Container {
+   private:
+    using SIEVEList = SieveList<T, HookPtr>;
+    using Mutex = folly::DistributedMutex;
+    using LockHolder = std::unique_lock<Mutex>;
+    using PtrCompressor = typename T::PtrCompressor;
+    using Time = typename Hook<T>::Time;
+    using CompressedPtr = typename T::CompressedPtr;
+    using RefFlags = typename T::Flags;
+
+   public:
+    Container() = default;
+    Container(Config c, PtrCompressor compressor)
+        : compressor_(std::move(compressor)),
+          queue_(compressor_),
+          config_(std::move(c)) { 
+    }
+    Container(serialization::MMSieveObject object, PtrCompressor compressor);
+
+    Container(const Container&) = delete;
+    Container& operator=(const Container&) = delete;
+
+    using Iterator = typename SIEVEList::Iterator;
+
+    // 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 Iterator {
+     public:
+      // noncopyable but movable.
+      LockedIterator(const LockedIterator&) = delete;
+      LockedIterator& operator=(const LockedIterator&) = delete;
+
+      LockedIterator(LockedIterator&&) noexcept = default;
+
+     private:
+      // private because it's easy to misuse and cause deadlock for MMSieve
+      LockedIterator& operator=(LockedIterator&&) noexcept = default;
+
+      // create an sieve iterator with the lock being held.
+      LockedIterator(LockHolder l, const Iterator& iter) noexcept;
+
+      // only the container can create iterators
+      friend Container<T, HookPtr>;
+
+      // lock protecting the validity of the iterator
+      LockHolder l_;
+    };
+
+    // records the information that the node was accessed. 
+    // accessed node remains where they are, so no locking required.
+    // @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 sieve, 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 sieve.
+    //
+    // @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 sieve 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;
+
+    // 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 is responsible for locking.
+    //
+    // iterator will be advanced to the next node after removing the node
+    //
+    // @param it    Iterator that will be removed
+    void remove(Iterator& 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;
+
+    // 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);
+
+    // get copy of current config
+    Config getConfig() const;
+
+    // override the existing config with the new one.
+    void setConfig(const Config& newConfig);
+
+    bool isEmpty() const noexcept { return size() == 0; }
+
+    // reconfigure the MMContainer: update refresh time according to current
+    // tail age
+    void reconfigureLocked(const Time& currTime);
+
+    // returns the number of elements in the container
+    size_t size() const noexcept {
+      return sieveMutex_->lock_combine([this]() { return queue_.size(); });
+    }
+
+    // Returns the eviction age stats. See CacheStats.h for details
+    EvictionAgeStat getEvictionAgeStat(uint64_t projectedLength) const noexcept;
+
+    // for saving the state of the sieve
+    //
+    // 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::MMSieveObject saveState() const noexcept;
+
+    // return the stats for this container.
+    MMContainerStat getStats() const noexcept;
+
+    static LruType getLruType(const T& /* node */) noexcept {
+      return LruType{};
+    }
+
+    void inspectSieveList() noexcept;
+    
+    void inspectHand() noexcept;
+
+   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);
+    }
+
+    // remove node from sieve and adjust insertion points
+    // @param node          node to remove
+    void removeLocked(T& node);
+
+    // Bit MM_BIT_0 is used to record if the item is in tail. This
+    // is used to implement LRU insertion points
+    void markTail(T& node) noexcept {
+      node.template setFlag<RefFlags::kMMFlag0>();
+    }
+
+    void unmarkTail(T& node) noexcept {
+      node.template unSetFlag<RefFlags::kMMFlag0>();
+    }
+
+    bool isTail(T& node) const noexcept {
+      return node.template isFlagSet<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.
+    void markAccessed(T& node) noexcept {
+      queue_.setAsVisited(node);
+    }
+
+    void unmarkAccessed(T& node) noexcept {
+      queue_.setAsUnvisited(node);
+    }
+
+    bool isAccessed(const T& node) const noexcept {
+      return queue_.isVisited(node);
+    }
+
+    // protects all operations on the sieve. We never really just read the state
+    // of the Sieve. Hence we dont really require a RW mutex at this point of
+    // time.
+    mutable folly::cacheline_aligned<Mutex> sieveMutex_;
+
+    const PtrCompressor compressor_{};
+
+    // Sieve FIFO queue
+    SIEVEList queue_{}; 
+ 
+    // The next time to reconfigure the container.
+    std::atomic<Time> nextReconfigureTime_{};
+ 
+    // Config for this sieve.
+    // Write access to the MMSieve Config is serialized.
+    // Reads may be racy.
+    Config config_{}; 
+  };
+};
+
+/* Container Interface Implementation */
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+MMSieve::Container<T, HookPtr>::Container(serialization::MMSieveObject object,
+                                        PtrCompressor compressor)
+    : compressor_(std::move(compressor)),
+      queue_(*object.queue(), compressor_),
+      config_(*object.config()) { 
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+bool MMSieve::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);
+  }   
+  return true;
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+cachelib::EvictionAgeStat MMSieve::Container<T, HookPtr>::getEvictionAgeStat(
+    uint64_t projectedLength) const noexcept {
+  return sieveMutex_->lock_combine([this, projectedLength]() {
+    return getEvictionAgeStatLocked(projectedLength);
+  });
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+cachelib::EvictionAgeStat
+MMSieve::Container<T, HookPtr>::getEvictionAgeStatLocked(
+    uint64_t projectedLength) const noexcept {
+  EvictionAgeStat stat{};
+  const auto currTime = static_cast<Time>(util::getCurrentTimeSec());
+
+  const T* node = queue_.getTail();
+  stat.warmQueueStat.oldestElementAge =
+      node ? currTime - getUpdateTime(*node) : 0;
+  for (size_t numSeen = 0; numSeen < projectedLength && node != nullptr;
+       numSeen++, node = queue_.getPrev(*node)) {
+  }
+  stat.warmQueueStat.projectedAge = node ? currTime - getUpdateTime(*node)
+                                         : stat.warmQueueStat.oldestElementAge;
+  return stat;
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+void MMSieve::Container<T, HookPtr>::setConfig(const Config& newConfig) {
+    sieveMutex_->lock_combine([this, newConfig]() {
+    config_ = newConfig; 
+  });
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+typename MMSieve::Config MMSieve::Container<T, HookPtr>::getConfig() const {
+  return sieveMutex_->lock_combine([this]() { return config_; });
+}
+
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+bool MMSieve::Container<T, HookPtr>::add(T& node) noexcept {
+  const auto currTime = static_cast<Time>(util::getCurrentTimeSec());
+  // Lock and insert at head 
+  return sieveMutex_->lock_combine([this, &node, currTime]() {
+    if (node.isInMMContainer()) {
+      return false;
+    }
+    queue_.linkAtHead(node); 
+    node.markInMMContainer();
+    setUpdateTime(node, currTime);
+    unmarkAccessed(node);
+ 
+    return true;
+  });
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+void MMSieve::Container<T, HookPtr>::inspectSieveList() noexcept{
+  queue_.inspectSieveList();
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+void MMSieve::Container<T, HookPtr>::inspectHand() noexcept{
+  T* hand = queue_.getHand();
+  std::cout << "hand: ";
+  if (hand==nullptr)std::cout<<"null" << std::endl;
+  else {
+	  std::cout << hand->getKey().toString(); 
+ 	  std::cout<<", visited: "<< isAccessed(*hand)<< std::endl;
+  }
+}
+
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+typename MMSieve::Container<T, HookPtr>::LockedIterator
+MMSieve::Container<T, HookPtr>::getEvictionIterator() noexcept {
+  LockHolder l(*sieveMutex_);
+  return LockedIterator{std::move(l), queue_.iterBackFromHand()};
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+template <typename F>
+void MMSieve::Container<T, HookPtr>::withEvictionIterator(F&& fun) {
+  if (config_.useCombinedLockForIterators) {
+    sieveMutex_->lock_combine([this, &fun]() { fun(Iterator{queue_.iterBackFromHand()}); });
+  } else {
+    LockHolder l{*sieveMutex_};
+    auto iter = Iterator{queue_.iterBackFromHand()};
+    fun(iter);
+  }
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+template <typename F>
+void MMSieve::Container<T, HookPtr>::withContainerLock(F&& fun) {
+  sieveMutex_->lock_combine([&fun]() { fun(); });
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+void MMSieve::Container<T, HookPtr>::removeLocked(T& node) {
+  queue_.remove(node);
+  unmarkAccessed(node);
+  if (isTail(node)) {
+    unmarkTail(node);
+  }
+  node.unmarkInMMContainer();
+  return;
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+bool MMSieve::Container<T, HookPtr>::remove(T& node) noexcept {
+  return sieveMutex_->lock_combine([this, &node]() {
+    if (!node.isInMMContainer()) {
+      return false;
+    }
+    removeLocked(node);
+    return true;
+  });
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+void MMSieve::Container<T, HookPtr>::remove(Iterator& it) noexcept { 
+  T& node = *it;
+  XDCHECK(node.isInMMContainer());
+  removeLocked(node);
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+bool MMSieve::Container<T, HookPtr>::replace(T& oldNode, T& newNode) noexcept {
+  return sieveMutex_->lock_combine([this, &oldNode, &newNode]() {
+    if (!oldNode.isInMMContainer() || newNode.isInMMContainer()) {
+      return false;
+    }
+    const auto updateTime = getUpdateTime(oldNode);
+    queue_.replace(oldNode, newNode);
+    oldNode.unmarkInMMContainer();
+    newNode.markInMMContainer();
+    setUpdateTime(newNode, updateTime);
+    if (isAccessed(oldNode)) {
+      markAccessed(newNode);
+    } else {
+      unmarkAccessed(newNode);
+    }
+    XDCHECK(!isTail(newNode));
+    if (isTail(oldNode)) {
+      markTail(newNode);
+      unmarkTail(oldNode);
+    } else {
+      unmarkTail(newNode);
+    }
+    return true;
+  });
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+serialization::MMSieveObject MMSieve::Container<T, HookPtr>::saveState()
+    const noexcept {
+  serialization::MMSieveConfig configObject; 
+  *configObject.updateOnWrite() = config_.updateOnWrite;
+  *configObject.updateOnRead() = config_.updateOnRead;
+    
+  serialization::MMSieveObject object;
+  *object.config() = configObject;  
+  *object.queue() = queue_.saveState();
+  return object;
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+MMContainerStat MMSieve::Container<T, HookPtr>::getStats() const noexcept {
+  auto stat = sieveMutex_->lock_combine([this]() {
+    auto* tail = queue_.getTail();
+
+    // we return by array here because DistributedMutex is fastest when the
+    // output data fits within 48 bytes.  And the array is exactly 48 bytes, so
+    // it can get optimized by the implementation.
+    //
+    // the rest of the parameters are 0, so we don't need the critical section
+    // to return them
+    return folly::make_array(queue_.size(),
+                             tail == nullptr ? 0 : getUpdateTime(*tail)
+		    	    );
+                             
+  });
+  return {stat[0] /* sieve queue size */,
+          /*stat[1] tail time */
+          /*stat[2] refresh time */
+          0,
+          0,
+          0,
+          0};
+}
+
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+void MMSieve::Container<T, HookPtr>::reconfigureLocked(const Time& currTime) {
+  if (currTime < nextReconfigureTime_) {
+    return;
+  }
+  nextReconfigureTime_ = currTime + config_.mmReconfigureIntervalSecs.count();
+ 
+  auto stat = getEvictionAgeStatLocked(0); 
+}
+
+// Iterator Context Implementation
+template <typename T, MMSieve::Hook<T> T::*HookPtr>
+MMSieve::Container<T, HookPtr>::LockedIterator::LockedIterator(
+    LockHolder l, const Iterator& iter) noexcept
+    : Iterator(iter), l_(std::move(l)) {}
+} // namespace facebook::cachelib
diff --git a/cachelib/allocator/datastruct/SieveList.h b/cachelib/allocator/datastruct/SieveList.h
new file mode 100755
index 0000000000..840af37be9
--- /dev/null
+++ b/cachelib/allocator/datastruct/SieveList.h
@@ -0,0 +1,448 @@
+/*
+ * 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 <folly/logging/xlog.h>
+#include <map>
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wconversion"
+#include "cachelib/allocator/serialize/gen-cpp2/objects_types.h"
+#pragma GCC diagnostic pop
+
+#include "cachelib/common/CompilerUtils.h"
+#include <atomic>
+
+namespace facebook::cachelib {
+// node information for the double linked list modelling the queue. 
+// It has the previous, next, a visited bit information and 
+// the last time the item was updated in Sieve.
+template <typename T>
+struct CACHELIB_PACKED_ATTR SieveListHook {
+  using Time = uint32_t;
+  using CompressedPtr = typename T::CompressedPtr;
+  using PtrCompressor = typename T::PtrCompressor;
+
+  void setNext(T* const n, const PtrCompressor& compressor) noexcept {
+    next_ = compressor.compress(n);
+  }
+
+  void setNext(CompressedPtr next) noexcept { next_ = next; }
+
+  void setPrev(T* const p, const PtrCompressor& compressor) noexcept {
+    prev_ = compressor.compress(p);
+  }
+
+  void setPrev(CompressedPtr prev) noexcept { prev_ = prev; }
+
+  CompressedPtr getNext() const noexcept { return CompressedPtr(next_); }
+
+  T* getNext(const PtrCompressor& compressor) const noexcept {
+    return compressor.unCompress(next_);
+  }
+
+  CompressedPtr getPrev() const noexcept { return CompressedPtr(prev_); }
+
+  T* getPrev(const PtrCompressor& compressor) const noexcept {
+    return compressor.unCompress(prev_);
+  }
+
+  // set and get the time when the node was updated in the sieve.
+  void setUpdateTime(Time time) noexcept { updateTime_ = time; }
+
+  Time getUpdateTime() const noexcept {
+    // Suppress TSAN here because we don't care if an item is promoted twice by
+    // two get operations running concurrently. It should be very rarely and is
+    // just a minor inefficiency if it happens.
+    folly::annotate_ignore_thread_sanitizer_guard g(__FILE__, __LINE__);
+    return updateTime_;
+  }
+
+ 
+ private:
+  CompressedPtr next_{}; // next node in the linked list
+  CompressedPtr prev_{}; // previous node in the linked list
+  // timestamp when this was last updated to the head of the list
+  Time updateTime_{0};
+};
+
+// uses a double linked list to implement an LRU. T must be have a public
+// member of type Hook and HookPtr must point to that.
+template <typename T, SieveListHook<T> T::*HookPtr>
+class SieveList {
+ public:
+  using CompressedPtr = typename T::CompressedPtr;
+  using PtrCompressor = typename T::PtrCompressor;
+  using SieveListObject = serialization::SieveListObject;
+  using RefFlags = typename T::Flags;
+  using Mutex = folly::DistributedMutex;
+  using LockHolder = std::unique_lock<Mutex>;
+
+
+  SieveList() = default;
+  SieveList(const SieveList&) = delete;
+  SieveList& operator=(const SieveList&) = delete;
+
+  explicit SieveList(PtrCompressor compressor) noexcept
+      : compressor_(std::move(compressor)) {}
+
+  // Restore SieveList from saved state.
+  //
+  // @param object              Save SieveList object
+  // @param compressor          PtrCompressor object
+  SieveList(const SieveListObject& object, PtrCompressor compressor)
+      : compressor_(std::move(compressor)),
+        head_(compressor_.unCompress(CompressedPtr{*object.compressedHead()})),
+        tail_(compressor_.unCompress(CompressedPtr{*object.compressedTail()})),
+	hand_(compressor_.unCompress(CompressedPtr{*object.compressedHand()})),
+        size_(*object.size()) {}
+
+  /**
+   * Exports the current state as a thrift object for later restoration.
+   */
+  SieveListObject saveState() const {
+    SieveListObject state;
+    *state.compressedHead() = compressor_.compress(head_).saveState();
+    *state.compressedTail() = compressor_.compress(tail_).saveState();
+    *state.compressedHand() = compressor_.compress(hand_).saveState();
+    *state.size() = size_;
+    return state;
+  }
+
+  T* getNext(const T& node) const noexcept {
+    return (node.*HookPtr).getNext(compressor_);
+  }
+
+  T* getPrev(const T& node) const noexcept {
+    return (node.*HookPtr).getPrev(compressor_);
+  }
+
+  void setNext(T& node, T* next) noexcept {
+    (node.*HookPtr).setNext(next, compressor_);
+  }
+
+  void setNextFrom(T& node, const T& other) noexcept {
+    (node.*HookPtr).setNext((other.*HookPtr).getNext());
+  }
+
+  void setPrev(T& node, T* prev) noexcept {
+    (node.*HookPtr).setPrev(prev, compressor_);
+  }
+
+  void setPrevFrom(T& node, const T& other) noexcept {
+    (node.*HookPtr).setPrev((other.*HookPtr).getPrev());
+  }
+  
+  // set the access bit of node
+  void setAsVisited(T& node) noexcept;
+  
+  // unset the access bit of node
+  void setAsUnvisited (T& node) noexcept;
+
+  // return the access bit of node
+  bool isVisited (const T& node) const noexcept;
+
+  // return and update hand_ to point to the next item to be evicted  
+  T* operateHand() noexcept;
+
+  // Links the passed node to the head of the double linked list
+  // @param node node to be linked at the head
+  void linkAtHead(T& node) noexcept;
+
+  
+  // Links the passed node to the tail of the double linked list
+  // @param node node to be linked at the tail
+  void linkAtTail(T& node) noexcept; 
+ 
+  // removes the node completely from the linked list and cleans up the node
+  // appropriately by setting its next and prev as nullptr.
+  void remove(T& node) noexcept;
+  
+  
+  // Unlinks the destination node and replaces it with the source node
+  //
+  // @param oldNode   destination node
+  // @param newNode   source node
+  void replace(T& oldNode, T& newNode) noexcept;
+  
+  // moves a node that belongs to the linked list to the head of the linked
+  // list.
+  //void moveToHead(T& node) noexcept;
+  
+  T* getHead() const noexcept { return head_; }
+  T* getTail() const noexcept { return tail_; }
+  T* getHand() const noexcept {return hand_; }
+
+  size_t size() const noexcept { return size_; }
+
+
+  void inspectVisitMap() noexcept;
+
+  void inspectSieveList() noexcept;
+
+
+  // Iterator interface for the double linked list. Supports both iterating
+  // from the tail and head.
+  class Iterator {
+   public:
+    //enum class Direction { FROM_HEAD, FROM_TAIL };
+    Iterator(T* p, SieveList<T, HookPtr>& sievelist) noexcept 
+	    : curr_(p),sievelist_(&sievelist) {};
+
+    //Iterator(T* p, Direction d, SieveList<T, HookPtr>& sievelist) noexcept
+    //    : curr_(p), dir_(d), sievelist_(&sievelist) {}
+    virtual ~Iterator() = default;
+
+    // copyable and movable
+    Iterator(const Iterator&) = default;
+    Iterator& operator=(const Iterator&) = default;
+    Iterator(Iterator&&) noexcept = default;
+    Iterator& operator=(Iterator&&) noexcept = default;
+
+    // moves the iterator forward and backward. Calling ++ once the iterator
+    // has reached the end is undefined.
+    Iterator& operator++() noexcept;
+    Iterator& operator--() noexcept;
+
+    T* operator->() const noexcept { return curr_; }
+    T& operator*() const noexcept { return *curr_; }
+
+    bool operator==(const Iterator& other) const noexcept {
+      return sievelist_ == other.sievelist_ && curr_ == other.curr_ ;
+    }
+
+    bool operator!=(const Iterator& other) const noexcept {
+      return !(*this == other);
+    }
+
+    explicit operator bool() const noexcept {
+      return curr_ != nullptr && sievelist_ != nullptr;
+    }
+
+    T* get() const noexcept { 
+	return curr_; 
+    }
+	
+    // Invalidates this iterator
+    void reset() noexcept { curr_ = nullptr; }
+   
+    // Reset the iterator back to the beginning
+    void resetToBegin() noexcept { sievelist_->tail_;}
+
+   protected:
+    
+    // the current position of the iterator in the list
+    T* curr_{nullptr};
+    // sievelist 
+    SieveList<T, HookPtr>* sievelist_{nullptr};
+  }; 
+
+  // provides an iterator starting from a certain node to the head
+  Iterator iterBackFromHand()  noexcept;
+
+ private:
+  // unlinks the node from the linked list. Does not correct the next and
+  // previous.
+  void unlink(const T& node) noexcept;
+
+  const PtrCompressor compressor_{};
+
+  //mutable folly::cacheline_aligned<Mutex> sievelistMutex_;
+
+  // head of the linked list
+  T* head_{nullptr};
+
+  // tail of the linked list
+  T* tail_{nullptr};
+
+  // hand for eviction
+  T* hand_{nullptr};
+
+  // size of the list
+  size_t size_{0};
+};
+
+
+
+/* Linked list implemenation */
+
+template <typename T, SieveListHook<T> T::*HookPtr>
+void SieveList<T, HookPtr>::setAsVisited(T& node) noexcept{
+    node.template setFlag<RefFlags::kMMFlag1>();
+}
+
+template <typename T, SieveListHook<T> T::*HookPtr>
+void SieveList<T, HookPtr>::setAsUnvisited(T& node) noexcept{
+    node.template unSetFlag<RefFlags::kMMFlag1>();
+}
+
+
+template <typename T, SieveListHook<T> T::*HookPtr>
+bool SieveList<T, HookPtr>::isVisited(const T& node) const noexcept{
+   return node.template isFlagSet<RefFlags::kMMFlag1>();
+}
+
+
+template <typename T, SieveListHook<T> T::*HookPtr>
+void SieveList<T, HookPtr>::inspectSieveList() noexcept{
+  std::cout << "Inspecting sieve_cache..."<<std::endl;
+  T* curr = head_;
+  T* prev = nullptr;
+  T* next = nullptr;
+  while (curr){
+    prev = getPrev(*curr);
+    next = getNext(*curr);
+    /*
+    std::cout << curr->getKey().toString() <<"," << curr;
+    std::cout<<", visited: "<< isVisited(*curr);
+    
+    if (prev) std::cout<<". prev: "<< prev->getKey().toString() << ", " << prev;
+    else std::cout << ". prev: null";
+    if (next) std::cout<<", next: " << next->getKey().toString() << ", " << next;
+    else std::cout << ". next:null"; 
+    */
+    
+    std::cout << curr->getKey().toString() << ", visited: "<< isVisited(*curr);
+    
+    if (curr == hand_) std::cout << ". Hand" << std::endl;
+    else std::cout<< std::endl;
+    curr = getNext(*curr);
+  }
+  if (hand_ == nullptr) std::cout << "Hand is null" << std::endl;
+  std::cout << "done inspecting." << std::endl;
+}
+
+
+template <typename T, SieveListHook<T> T::*HookPtr>
+T* SieveList<T, HookPtr>::operateHand() noexcept{  
+  T* curr = hand_;
+  
+  if (curr == nullptr) curr = tail_;
+  if (curr == nullptr) return nullptr;
+  while (isVisited(*curr)){
+    setAsUnvisited(*curr);
+    curr = getPrev(*curr);
+    if (curr == nullptr) curr = tail_;
+  }
+
+  hand_ = getPrev(*curr); 
+  return curr;
+}
+
+
+template <typename T, SieveListHook<T> T::*HookPtr>
+void SieveList<T, HookPtr>::linkAtHead(T& node) noexcept {
+  XDCHECK_NE(reinterpret_cast<uintptr_t>(&node),
+             reinterpret_cast<uintptr_t>(head_));
+  
+  setPrev(node, nullptr);
+  setNext(node, head_); 
+  
+  // fix the prev ptr of head
+  if (head_ != nullptr) {
+    setPrev(*head_, &node);
+  }
+  head_ = &node;
+  if (tail_ == nullptr) {
+    tail_ = &node;
+  }
+  setAsUnvisited(node);
+  size_++; 
+}
+
+template <typename T, SieveListHook<T> T::*HookPtr>
+void SieveList<T, HookPtr>::unlink(const T& node) noexcept {
+   
+  XDCHECK_GT(size_, 0u);
+  // fix head_ and tail_ if the node is either of that.
+  auto* const prev = getPrev(node);
+  auto* const next = getNext(node); 
+
+  if (&node == head_) {
+    head_ = next;
+  }
+
+  if (&node == tail_) { 
+    tail_ = prev;
+  }
+
+  if (&node == hand_){
+    hand_ = prev;
+  }
+  // fix the next and prev ptrs of the node before and after us.
+  if (prev != nullptr) {
+    setNextFrom(*prev, node);
+  }
+  if (next != nullptr) {
+    setPrevFrom(*next, node);
+  }
+  size_--;
+}
+
+template <typename T, SieveListHook<T> T::*HookPtr>
+void SieveList<T, HookPtr>::remove(T& node) noexcept {
+  unlink(node);
+  setNext(node, nullptr);
+  setPrev(node, nullptr); 
+}
+
+template <typename T, SieveListHook<T> T::*HookPtr>
+void SieveList<T, HookPtr>::replace(T& oldNode, T& newNode) noexcept {
+  if (&oldNode == head_) {
+    head_ = &newNode;
+  }
+  if (&oldNode == tail_) {
+    tail_ = &newNode;
+  } 
+  if (&oldNode == hand_){
+    hand_ = getPrev(*hand_);
+  }
+  
+  setAsUnvisited(newNode);
+  // Make the previous and next nodes point to the new node
+  auto* const prev = getPrev(oldNode);
+  auto* const next = getNext(oldNode);
+  if (prev != nullptr) {
+    setNext(*prev, &newNode);
+  }
+  if (next != nullptr) {
+    setPrev(*next, &newNode);
+  }
+
+  // Make the new node point to the previous and next nodes
+  setPrev(newNode, prev);
+  setNext(newNode, next);
+
+  // Cleanup the old node
+  setPrev(oldNode, nullptr);
+  setNext(oldNode, nullptr);
+}
+
+
+template <typename T, SieveListHook<T> T::*HookPtr>
+typename SieveList<T, HookPtr>::Iterator&
+SieveList<T, HookPtr>::Iterator::operator++() noexcept { 
+  curr_ = sievelist_->operateHand(); 
+  return *this;
+}
+
+template <typename T, SieveListHook<T> T::*HookPtr>
+typename SieveList<T, HookPtr>::Iterator SieveList<T, HookPtr>::iterBackFromHand() noexcept{ 
+  auto firstNodeToBeEvicted = operateHand();
+  auto iterObj = SieveList<T, HookPtr>::Iterator(firstNodeToBeEvicted,*this);  
+  return iterObj;
+}
+} // namespace facebook::cachelib
diff --git a/cachelib/allocator/datastruct/serialize/objects.thrift b/cachelib/allocator/datastruct/serialize/objects.thrift
index 223b804e5b..94f9b6a4da 100644
--- a/cachelib/allocator/datastruct/serialize/objects.thrift
+++ b/cachelib/allocator/datastruct/serialize/objects.thrift
@@ -38,3 +38,10 @@ struct DListObject {
 struct MultiDListObject {
   1: required list<DListObject> lists;
 }
+
+struct SieveListObject{
+  1: required i64 compressedHead;
+  2: required i64 compressedTail;
+  3: required i64 compressedHand;
+  4: required i64 size;
+}
diff --git a/cachelib/allocator/serialize/objects.thrift b/cachelib/allocator/serialize/objects.thrift
index 7241ee88de..01df06b6fe 100644
--- a/cachelib/allocator/serialize/objects.thrift
+++ b/cachelib/allocator/serialize/objects.thrift
@@ -135,6 +135,25 @@ struct MMTinyLFUCollection {
   1: required map<i32, map<i32, MMTinyLFUObject>> pools;
 }
 
+struct MMSieveConfig { 
+  1: bool updateOnWrite = true;
+  2: bool updateOnRead = true; 
+}
+
+struct MMSieveObject {
+  1: required MMSieveConfig config;
+
+  // number of evictions for this MM object.
+  5: i64 evictions = 0;
+  
+  6: required SieveListObject queue;
+  7: required i64 compressedHand;
+}
+
+struct MMSieveCollection {
+  1: required map<i32, map<i32, MMSieveObject>> pools;
+}
+
 struct ChainedHashTableObject {
   // fields in ChainedHashTable::Config
   1: required i32 bucketsPower;

From 4f4fd8a3d5f3ea46332cf4800e308901047960f8 Mon Sep 17 00:00:00 2001
From: Helen <Helen@node0.r650.redundancy-pg0.clemson.cloudlab.us>
Date: Tue, 20 Aug 2024 16:25:57 -0400
Subject: [PATCH 2/3] integrate Sieve into cachebench

---
 cachelib/cachebench/cache/Cache.h       | 13 ++++++++++++-
 cachelib/cachebench/runner/Stressor.cpp |  6 ++++++
 cachelib/cachebench/util/CacheConfig.h  |  1 +
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/cachelib/cachebench/cache/Cache.h b/cachelib/cachebench/cache/Cache.h
index fc9a13d704..eabbfa8202 100644
--- a/cachelib/cachebench/cache/Cache.h
+++ b/cachelib/cachebench/cache/Cache.h
@@ -472,7 +472,7 @@ inline typename LruAllocator::MMConfig makeMMConfig(CacheConfig const& config) {
                                 config.useCombinedLockForIterators);
 }
 
-// LRU
+// LRU2Q
 template <>
 inline typename Lru2QAllocator::MMConfig makeMMConfig(
     CacheConfig const& config) {
@@ -488,6 +488,17 @@ inline typename Lru2QAllocator::MMConfig makeMMConfig(
                                   config.useCombinedLockForIterators);
 }
 
+// SIEVE
+template <>
+inline typename SieveAllocator::MMConfig makeMMConfig(
+    CacheConfig const& config) {
+  return SieveAllocator::MMConfig(config.sieveUpdateOnWrite,
+                                  config.sieveUpdateOnRead,
+                    		  config.useCombinedLockForIterators);
+}
+
+
+
 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 3852bee0c9..b3b22f9a97 100644
--- a/cachelib/cachebench/runner/Stressor.cpp
+++ b/cachelib/cachebench/runner/Stressor.cpp
@@ -191,6 +191,9 @@ std::unique_ptr<Stressor> Stressor::makeStressor(
     } else if (cacheConfig.allocator == "LRU2Q") {
       return std::make_unique<AsyncCacheStressor<Lru2QAllocator>>(
           cacheConfig, stressorConfig, std::move(generator));
+    } else if (cacheConfig.allocator == "SIEVE"){
+      return std::make_unique<AsyncCacheStressor<SieveAllocator>>(
+          cacheConfig, stressorConfig, std::move(generator));
     }
   } else {
     auto generator = makeGenerator(stressorConfig);
@@ -201,6 +204,9 @@ std::unique_ptr<Stressor> Stressor::makeStressor(
     } else if (cacheConfig.allocator == "LRU2Q") {
       return std::make_unique<CacheStressor<Lru2QAllocator>>(
           cacheConfig, stressorConfig, std::move(generator));
+    } else if (cacheConfig.allocator == "SIEVE"){ 
+      return std::make_unique<CacheStressor<SieveAllocator>>(
+          cacheConfig, stressorConfig, std::move(generator));
     }
   }
   throw std::invalid_argument("Invalid config");
diff --git a/cachelib/cachebench/util/CacheConfig.h b/cachelib/cachebench/util/CacheConfig.h
index 0a1569615d..5f00559b79 100644
--- a/cachelib/cachebench/util/CacheConfig.h
+++ b/cachelib/cachebench/util/CacheConfig.h
@@ -39,6 +39,7 @@ class CacheMonitorFactory {
   virtual ~CacheMonitorFactory() = default;
   virtual std::unique_ptr<CacheMonitor> create(LruAllocator& cache) = 0;
   virtual std::unique_ptr<CacheMonitor> create(Lru2QAllocator& cache) = 0;
+  virtual std::unique_prt<CacheMonitor> create(SieveAllocator& cache) = 0;
 };
 
 // Parse memory tiers configuration from JSON config

From f1e0512123720ded8e8aaa69f14115c744c19098 Mon Sep 17 00:00:00 2001
From: Helen <Helen@node0.r650.redundancy-pg0.clemson.cloudlab.us>
Date: Wed, 21 Aug 2024 09:20:34 -0400
Subject: [PATCH 3/3] Remove some debugging code

---
 cachelib/allocator/CacheTraits.h | 2 +-
 cachelib/allocator/MMSieve.h     | 8 +++++---
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/cachelib/allocator/CacheTraits.h b/cachelib/allocator/CacheTraits.h
index 9994a64436..1c3d41cec4 100644
--- a/cachelib/allocator/CacheTraits.h
+++ b/cachelib/allocator/CacheTraits.h
@@ -56,7 +56,7 @@ struct TinyLFUCacheTrait {
 };
 
 struct SieveCacheTrait {
-  using MMType = MMTinyLFU;
+  using MMType = MMSieve;
   using AccessType = ChainedHashTable;
   using AccessTypeLocks = SharedMutexBuckets;
 };
diff --git a/cachelib/allocator/MMSieve.h b/cachelib/allocator/MMSieve.h
index 2ed56573d3..f2acbebd83 100755
--- a/cachelib/allocator/MMSieve.h
+++ b/cachelib/allocator/MMSieve.h
@@ -343,7 +343,6 @@ bool MMSieve::Container<T, HookPtr>::recordAccess(T& node,
       (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);
@@ -364,6 +363,9 @@ cachelib::EvictionAgeStat
 MMSieve::Container<T, HookPtr>::getEvictionAgeStatLocked(
     uint64_t projectedLength) const noexcept {
   EvictionAgeStat stat{};
+  /*Eviction Age is used by LruTailAge Rebalance Strategy, 
+   * but Sieve doesn't have a defined tail age.*/
+
   const auto currTime = static_cast<Time>(util::getCurrentTimeSec());
 
   const T* node = queue_.getTail();
@@ -418,8 +420,8 @@ void MMSieve::Container<T, HookPtr>::inspectHand() noexcept{
   std::cout << "hand: ";
   if (hand==nullptr)std::cout<<"null" << std::endl;
   else {
-	  std::cout << hand->getKey().toString(); 
- 	  std::cout<<", visited: "<< isAccessed(*hand)<< std::endl;
+    std::cout << hand->getKey().toString(); 
+    std::cout<<", visited: "<< isAccessed(*hand)<< std::endl;
   }
 }