format code + rework documentation

Author: byrnedj

MultiTierDataMovement.md

@@ -12,7 +12,7 @@ thread (green) is integrated to the CacheLib architecture.
 
 ## Synchronous Eviction and Promotion
 
-- `disableEvictionToMemory`: Disables eviction to memory (item is always evicted to NVMe or removed
+- `disableEviction`: Disables eviction to memory (item is always evicted to NVMe or removed
 on eviction)
 
 ## Background Evictors
@@ -23,7 +23,7 @@ strategies and general parameters.
 
 - `backgroundEvictorIntervalMilSec`: The interval that this thread runs for - by default
 the background evictor threads will wake up every 10 ms to scan the AllocationClasses. Also,
-the background evictor thead will be woken up everytime there is a failed allocation (from
+the background evictor thread will be woken up everytime there is a failed allocation (from
 a request handling thread) and the current percentage of free memory for the 
 AllocationClass is lower than `lowEvictionAcWatermark`. This may render the interval parameter
 not as important when there are many allocations occuring from request handling threads. 
@@ -59,7 +59,7 @@ don't set this above `10`.
 
 ## Background Promoters
 
-The background promotes scan each class to see if there are objects to move to a lower
+The background promoters scan each class to see if there are objects to move to a lower
 tier using a given strategy. Here we document the parameters for the different
 strategies and general parameters.
 
@@ -93,25 +93,3 @@ This value should correlate with `lowEvictionAcWatermark`, `highEvictionAcWaterm
 - `maxPromotionBatch`: The number of objects to promote in batch during BG promotion. Analogous to
 `maxEvictionBatch`. It's value should be lower to decrease contention on hot items.
 
-## Allocation policies
-
-- `maxAcAllocationWatermark`:  Item is always allocated in topmost tier if at least this 
-percentage of the AllocationClass is free.
-- `minAcAllocationWatermark`: Item is always allocated in bottom tier if only this percent
-of the AllocationClass is free. If percentage of free AllocationClasses is between `maxAcAllocationWatermark`
-and `minAcAllocationWatermark`: then extra checks (described below) are performed to decide where to put the element.
-
-By default, allocation will always be performed from the upper tier.
-
-- `acTopTierEvictionWatermark`: If there is less that this percent of free memory in topmost tier, cachelib will attempt to evict from top tier. This option takes precedence before allocationWatermarks.
-
-### Extra policies (used only when  percentage of free AllocationClasses is between `maxAcAllocationWatermark`
-and `minAcAllocationWatermark`)
-- `sizeThresholdPolicy`: If item is smaller than this value, always allocate it in upper tier.
-- `defaultTierChancePercentage`: Change (0-100%) of allocating item in top tier
-
-## MMContainer options
-
-- `lruInsertionPointSpec`: Can be set per tier when LRU2Q is used. Determines where new items are
-inserted. 0 = insert to hot queue, 1 = insert to warm queue, 2 = insert to cold queue
-- `markUsefulChance`: Per-tier, determines chance of moving item to the head of LRU on access

cachelib/allocator/BackgroundMover-inl.h

@@ -17,27 +17,24 @@
 namespace facebook {
 namespace cachelib {
 
-
 template <typename CacheT>
-BackgroundMover<CacheT>::BackgroundMover(Cache& cache,
-                               std::shared_ptr<BackgroundMoverStrategy> strategy, 
-                               MoverDir direction)
-    : cache_(cache),
-      strategy_(strategy),
-      direction_(direction)
-{
-    if (direction_ == MoverDir::Evict) {
-        moverFunc = 
-            BackgroundMoverAPIWrapper<CacheT>::traverseAndEvictItems;
-
-    } else if (direction_ == MoverDir::Promote) {
-        moverFunc = 
-            BackgroundMoverAPIWrapper<CacheT>::traverseAndPromoteItems;
-    }
+BackgroundMover<CacheT>::BackgroundMover(
+    Cache& cache,
+    std::shared_ptr<BackgroundMoverStrategy> strategy,
+    MoverDir direction)
+    : cache_(cache), strategy_(strategy), direction_(direction) {
+  if (direction_ == MoverDir::Evict) {
+    moverFunc = BackgroundMoverAPIWrapper<CacheT>::traverseAndEvictItems;
+
+  } else if (direction_ == MoverDir::Promote) {
+    moverFunc = BackgroundMoverAPIWrapper<CacheT>::traverseAndPromoteItems;
+  }
 }
 
 template <typename CacheT>
-BackgroundMover<CacheT>::~BackgroundMover() { stop(std::chrono::seconds(0)); }
+BackgroundMover<CacheT>::~BackgroundMover() {
+  stop(std::chrono::seconds(0));
+}
 
 template <typename CacheT>
 void BackgroundMover<CacheT>::work() {
@@ -49,14 +46,14 @@ void BackgroundMover<CacheT>::work() {
 }
 
 template <typename CacheT>
-void BackgroundMover<CacheT>::setAssignedMemory(std::vector<std::tuple<TierId, PoolId, ClassId>> &&assignedMemory)
-{
+void BackgroundMover<CacheT>::setAssignedMemory(
+    std::vector<std::tuple<TierId, PoolId, ClassId>>&& assignedMemory) {
   XLOG(INFO, "Class assigned to background worker:");
   for (auto [tid, pid, cid] : assignedMemory) {
     XLOGF(INFO, "Tid: {}, Pid: {}, Cid: {}", tid, pid, cid);
   }
 
-  mutex.lock_combine([this, &assignedMemory]{
+  mutex.lock_combine([this, &assignedMemory] {
     this->assignedMemory_ = std::move(assignedMemory);
   });
 }
@@ -65,31 +62,28 @@ void BackgroundMover<CacheT>::setAssignedMemory(std::vector<std::tuple<TierId, P
 // and return those for eviction
 template <typename CacheT>
 void BackgroundMover<CacheT>::checkAndRun() {
-  auto assignedMemory = mutex.lock_combine([this]{
-    return assignedMemory_;
-  });
+  auto assignedMemory = mutex.lock_combine([this] { return assignedMemory_; });
 
   unsigned int moves = 0;
   std::set<ClassId> classes{};
-  auto batches = strategy_->calculateBatchSizes(cache_,assignedMemory);
+  auto batches = strategy_->calculateBatchSizes(cache_, assignedMemory);
 
   for (size_t i = 0; i < batches.size(); i++) {
     const auto [tid, pid, cid] = assignedMemory[i];
     const auto batch = batches[i];
-  
+
     classes.insert(cid);
-    const auto& mpStats = cache_.getPoolByTid(pid,tid).getStats();
+    const auto& mpStats = cache_.getPoolByTid(pid, tid).getStats();
 
     if (!batch) {
       continue;
     }
 
-    totalBytesMoved.add(batch * mpStats.acStats.at(cid).allocSize);
-  
-    //try moving BATCH items from the class in order to reach free target
-    auto moved = moverFunc(cache_,tid,pid,cid,batch);
+    // try moving BATCH items from the class in order to reach free target
+    auto moved = moverFunc(cache_, tid, pid, cid, batch);
     moves += moved;
     moves_per_class_[tid][pid][cid] += moved;
+    totalBytesMoved.add(moved * mpStats.acStats.at(cid).allocSize);
   }
 
   numTraversals.inc();

cachelib/allocator/BackgroundMover.h

@@ -16,14 +16,13 @@
 
 #pragma once
 
-#include <gtest/gtest_prod.h>
 #include <folly/concurrency/UnboundedQueue.h>
+#include <gtest/gtest_prod.h>
 
-#include "cachelib/allocator/CacheStats.h"
-#include "cachelib/common/PeriodicWorker.h"
 #include "cachelib/allocator/BackgroundMoverStrategy.h"
+#include "cachelib/allocator/CacheStats.h"
 #include "cachelib/common/AtomicCounter.h"
-
+#include "cachelib/common/PeriodicWorker.h"
 
 namespace facebook {
 namespace cachelib {
@@ -32,23 +31,24 @@ namespace cachelib {
 // needed for the cache api
 template <typename C>
 struct BackgroundMoverAPIWrapper {
-
   static size_t traverseAndEvictItems(C& cache,
-          unsigned int tid, unsigned int pid, unsigned int cid, size_t batch) {
-    return cache.traverseAndEvictItems(tid,pid,cid,batch);
+                                      unsigned int tid,
+                                      unsigned int pid,
+                                      unsigned int cid,
+                                      size_t batch) {
+    return cache.traverseAndEvictItems(tid, pid, cid, batch);
   }
-  
+
   static size_t traverseAndPromoteItems(C& cache,
-          unsigned int tid, unsigned int pid, unsigned int cid, size_t batch) {
-    return cache.traverseAndPromoteItems(tid,pid,cid,batch);
+                                        unsigned int tid,
+                                        unsigned int pid,
+                                        unsigned int cid,
+                                        size_t batch) {
+    return cache.traverseAndPromoteItems(tid, pid, cid, batch);
   }
-  
 };
 
-enum class MoverDir {
-    Evict = 0,
-    Promote
-};
+enum class MoverDir { Evict = 0, Promote };
 
 // Periodic worker that evicts items from tiers in batches
 // The primary aim is to reduce insertion times for new items in the
@@ -58,35 +58,40 @@ class BackgroundMover : public PeriodicWorker {
  public:
   using Cache = CacheT;
   // @param cache               the cache interface
-  // @param strategy            the stragey class that defines how objects are moved,
+  // @param strategy            the stragey class that defines how objects are
+  // moved,
   //                            (promoted vs. evicted and how much)
   BackgroundMover(Cache& cache,
                   std::shared_ptr<BackgroundMoverStrategy> strategy,
                   MoverDir direction_);
 
   ~BackgroundMover() override;
-  
+
   BackgroundMoverStats getStats() const noexcept;
-  std::map<TierId, std::map<PoolId, std::map<ClassId, uint64_t>>> getClassStats() const noexcept;
+  std::map<TierId, std::map<PoolId, std::map<ClassId, uint64_t>>>
+  getClassStats() const noexcept;
 
-  void setAssignedMemory(std::vector<std::tuple<TierId, PoolId, ClassId>> &&assignedMemory);
+  void setAssignedMemory(
+      std::vector<std::tuple<TierId, PoolId, ClassId>>&& assignedMemory);
 
  private:
-   std::map<TierId, std::map<PoolId, std::map<ClassId, uint64_t>>> moves_per_class_;
+  std::map<TierId, std::map<PoolId, std::map<ClassId, uint64_t>>>
+      moves_per_class_;
   // cache allocator's interface for evicting
   using Item = typename Cache::Item;
-  
+
   Cache& cache_;
   std::shared_ptr<BackgroundMoverStrategy> strategy_;
   MoverDir direction_;
-  
-  std::function<size_t(Cache&, unsigned int, unsigned int, unsigned int, size_t)> moverFunc;
+
+  std::function<size_t(
+      Cache&, unsigned int, unsigned int, unsigned int, size_t)>
+      moverFunc;
 
   // implements the actual logic of running the background evictor
   void work() override final;
   void checkAndRun();
 
-  
   AtomicCounter numMovedItems{0};
   AtomicCounter numTraversals{0};
   AtomicCounter totalClasses{0};

cachelib/allocator/BackgroundMoverStrategy.h

@@ -23,10 +23,10 @@ namespace cachelib {
 
 // Base class for background eviction strategy.
 class BackgroundMoverStrategy {
-
-public:
-  virtual std::vector<size_t> calculateBatchSizes(const CacheBase& cache,
-                                       std::vector<std::tuple<TierId, PoolId, ClassId>> acVec) = 0;
+ public:
+  virtual std::vector<size_t> calculateBatchSizes(
+      const CacheBase& cache,
+      std::vector<std::tuple<TierId, PoolId, ClassId>> acVec) = 0;
 };
 
 } // namespace cachelib

cachelib/allocator/CacheAllocator-inl.h

@@ -427,7 +427,7 @@ CacheAllocator<CacheTrait>::allocateInternalTier(TierId tid,
   if (backgroundEvictor_.size() && !fromBgThread && (memory == nullptr || shouldWakeupBgEvictor(tid, pid, cid))) {
     backgroundEvictor_[backgroundWorkerId(tid, pid, cid, backgroundEvictor_.size())]->wakeUp();
   }
-  // TODO: Today disableEviction means do not evict from memory (DRAM).
+  // TODO: Today isEvictionDisabled means do not evict from memory (DRAM).
   //       Should we support eviction between memory tiers (e.g. from DRAM to PMEM)?
   if (memory == nullptr && !config_.isEvictionDisabled()) {
     memory = findEviction(tid, pid, cid);

cachelib/allocator/CacheAllocatorConfig.h

@@ -625,11 +625,8 @@ class CacheAllocatorConfig {
   // CacheAllocator::startCacheWorkers()
   bool delayCacheWorkersStart{false};
 
-  
-  double minAcAllocationWatermark{0.0};
-  double maxAcAllocationWatermark{0.0};
-
-  double promotionAcWatermark{4.0};
+  // see MultiTierDataMovement.md
+  double promotionAcWatermark{4.0}; 
   double lowEvictionAcWatermark{2.0};
   double highEvictionAcWatermark{5.0};
   double numDuplicateElements{0.0}; // inclusivness of the cache

cachelib/allocator/FreeThresholdStrategy.cpp

@@ -21,21 +21,27 @@
 namespace facebook {
 namespace cachelib {
 
-
-
-FreeThresholdStrategy::FreeThresholdStrategy(double lowEvictionAcWatermark, double highEvictionAcWatermark, uint64_t maxEvictionBatch, uint64_t minEvictionBatch)
-    : lowEvictionAcWatermark(lowEvictionAcWatermark), highEvictionAcWatermark(highEvictionAcWatermark), maxEvictionBatch(maxEvictionBatch), minEvictionBatch(minEvictionBatch) {}
+FreeThresholdStrategy::FreeThresholdStrategy(double lowEvictionAcWatermark,
+                                             double highEvictionAcWatermark,
+                                             uint64_t maxEvictionBatch,
+                                             uint64_t minEvictionBatch)
+    : lowEvictionAcWatermark(lowEvictionAcWatermark),
+      highEvictionAcWatermark(highEvictionAcWatermark),
+      maxEvictionBatch(maxEvictionBatch),
+      minEvictionBatch(minEvictionBatch) {}
 
 std::vector<size_t> FreeThresholdStrategy::calculateBatchSizes(
-  const CacheBase& cache, std::vector<std::tuple<TierId, PoolId, ClassId>> acVec) {
+    const CacheBase& cache,
+    std::vector<std::tuple<TierId, PoolId, ClassId>> acVec) {
   std::vector<size_t> batches{};
   for (auto [tid, pid, cid] : acVec) {
     auto stats = cache.getAllocationClassStats(tid, pid, cid);
     if (stats.approxFreePercent >= highEvictionAcWatermark) {
       batches.push_back(0);
     } else {
       auto toFreeMemPercent = highEvictionAcWatermark - stats.approxFreePercent;
-      auto toFreeItems = static_cast<size_t>(toFreeMemPercent * stats.memorySize / stats.allocSize);
+      auto toFreeItems = static_cast<size_t>(
+          toFreeMemPercent * stats.memorySize / stats.allocSize);
       batches.push_back(toFreeItems);
     }
   }
@@ -48,17 +54,18 @@ std::vector<size_t> FreeThresholdStrategy::calculateBatchSizes(
   if (maxBatch == 0)
     return batches;
 
-  std::transform(batches.begin(), batches.end(), batches.begin(), [&](auto numItems){
-    if (numItems == 0) {
-      return 0UL;
-    }
+  std::transform(
+      batches.begin(), batches.end(), batches.begin(), [&](auto numItems) {
+        if (numItems == 0) {
+          return 0UL;
+        }
 
-    auto cappedBatchSize = maxEvictionBatch * numItems / maxBatch;
-    if (cappedBatchSize < minEvictionBatch)
-      return minEvictionBatch;
-    else
-      return cappedBatchSize;
-  });
+        auto cappedBatchSize = maxEvictionBatch * numItems / maxBatch;
+        if (cappedBatchSize < minEvictionBatch)
+          return minEvictionBatch;
+        else
+          return cappedBatchSize;
+      });
 
   return batches;
 }

cachelib/allocator/FreeThresholdStrategy.h

@@ -16,24 +16,27 @@
 
 #pragma once
 
-#include "cachelib/allocator/Cache.h"
 #include "cachelib/allocator/BackgroundMoverStrategy.h"
+#include "cachelib/allocator/Cache.h"
 
 namespace facebook {
 namespace cachelib {
 
-
 // Base class for background mover strategy.
 class FreeThresholdStrategy : public BackgroundMoverStrategy {
-
-public:
-  FreeThresholdStrategy(double lowEvictionAcWatermark, double highEvictionAcWatermark, uint64_t maxEvictionBatch, uint64_t minEvictionBatch);
+ public:
+  FreeThresholdStrategy(double lowEvictionAcWatermark,
+                        double highEvictionAcWatermark,
+                        uint64_t maxEvictionBatch,
+                        uint64_t minEvictionBatch);
   ~FreeThresholdStrategy() {}
 
-  std::vector<size_t> calculateBatchSizes(const CacheBase& cache,
-                            std::vector<std::tuple<TierId, PoolId, ClassId>> acVecs);
-private:
-  double lowEvictionAcWatermark{2.0}; 
+  std::vector<size_t> calculateBatchSizes(
+      const CacheBase& cache,
+      std::vector<std::tuple<TierId, PoolId, ClassId>> acVecs);
+
+ private:
+  double lowEvictionAcWatermark{2.0};
   double highEvictionAcWatermark{5.0};
   uint64_t maxEvictionBatch{40};
   uint64_t minEvictionBatch{5};