These changes introduce per-tier cache configuration required to implement features discussed here: #102.

These specific changes enable single DRAM tier configs only which are compatible with the current version of cachelib.
Configuration API will be expanded as multi-tier changes in other parts of the library are introduced.

Author: victoria-mcgrath

cachelib/allocator/CMakeLists.txt

@@ -119,6 +119,7 @@ if (BUILD_TESTS)
   add_test (tests/AllocatorHitStatsTypeTest.cpp)
   add_test (tests/MultiAllocatorTest.cpp)
   add_test (tests/NvmAdmissionPolicyTest.cpp)
+  add_test (tests/CacheAllocatorConfigTest.cpp)
   add_test (nvmcache/tests/NvmItemTests.cpp)
   add_test (nvmcache/tests/InFlightPutsTest.cpp)
   add_test (nvmcache/tests/TombStoneTests.cpp)

cachelib/allocator/CacheAllocatorConfig.h

@@ -27,6 +27,7 @@
 #include "cachelib/allocator/Cache.h"
 #include "cachelib/allocator/MM2Q.h"
 #include "cachelib/allocator/MemoryMonitor.h"
+#include "cachelib/allocator/MemoryTierCacheConfig.h"
 #include "cachelib/allocator/NvmAdmissionPolicy.h"
 #include "cachelib/allocator/PoolOptimizeStrategy.h"
 #include "cachelib/allocator/RebalanceStrategy.h"
@@ -50,6 +51,7 @@ class CacheAllocatorConfig {
   using NvmCacheDeviceEncryptor = typename CacheT::NvmCacheT::DeviceEncryptor;
   using MoveCb = typename CacheT::MoveCb;
   using NvmCacheConfig = typename CacheT::NvmCacheT::Config;
+  using MemoryTierConfigs = std::vector<MemoryTierCacheConfig>;
   using Key = typename CacheT::Key;
   using EventTrackerSharedPtr = std::shared_ptr<typename CacheT::EventTracker>;
   using Item = typename CacheT::Item;
@@ -199,6 +201,25 @@ class CacheAllocatorConfig {
   // cachePersistence()
   CacheAllocatorConfig& usePosixForShm();
 
+  // Configures cache memory tiers. Accepts vector of MemoryTierCacheConfig.
+  // Each vector element describes configuration for a single memory cache tier.
+  // Tiers can be set up as ratios of total cache size or have their sizes
+  // explicitly specified. If ratios are used, then total cache size must be set
+  // before this method is called; if sizes are explicitly specified, then
+  // their sum sizes must match the total cache size if it's previously set; if
+  // the total size has not been set then this method will set it as a sum of
+  // all tier sizes
+  CacheAllocatorConfig& configureMemoryTiers(const MemoryTierConfigs& configs);
+
+  // Sets total cache size and configures cache memory tiers. This method
+  // can be used when configuring cache memory tears whose sizes are specified
+  // via ratios of total cache size.
+  CacheAllocatorConfig& configureMemoryTiers(size_t totalCacheSize,
+                                             const MemoryTierConfigs& configs);
+
+  // Return reference to MemoryTierCacheConfigs.
+  const MemoryTierConfigs& getMemoryTierConfigs();
+
   // This turns on a background worker that periodically scans through the
   // access container and look for expired items and remove them.
   CacheAllocatorConfig& enableItemReaperInBackground(
@@ -575,6 +596,12 @@ class CacheAllocatorConfig {
   friend CacheT;
 
  private:
+  CacheAllocatorConfig& setCacheSizeImpl(size_t _size);
+
+  // Configuration for memory tiers.
+  MemoryTierConfigs memoryTierConfigs{
+      {MemoryTierCacheConfig::fromShm().setRatio(1)}};
+
   void mergeWithPrefix(
       std::map<std::string, std::string>& configMap,
       const std::map<std::string, std::string>& configMapToMerge,
@@ -597,7 +624,8 @@ CacheAllocatorConfig<T>& CacheAllocatorConfig<T>::setCacheName(
 }
 
 template <typename T>
-CacheAllocatorConfig<T>& CacheAllocatorConfig<T>::setCacheSize(size_t _size) {
+CacheAllocatorConfig<T>& CacheAllocatorConfig<T>::setCacheSizeImpl(
+    size_t _size) {
   size = _size;
   constexpr size_t maxCacheSizeWithCoredump = 64'424'509'440; // 60GB
   if (size <= maxCacheSizeWithCoredump) {
@@ -606,6 +634,18 @@ CacheAllocatorConfig<T>& CacheAllocatorConfig<T>::setCacheSize(size_t _size) {
   return *this;
 }
 
+template <typename T>
+CacheAllocatorConfig<T>& CacheAllocatorConfig<T>::setCacheSize(size_t _size) {
+  if (memoryTierConfigs.size() == 1) {
+    memoryTierConfigs[0].setSize(size);
+  } else {
+    throw std::invalid_argument(
+        "Cannot set cache size after configuring memory tiers.");
+  }
+
+  return setCacheSizeImpl(_size);
+}
+
 template <typename T>
 CacheAllocatorConfig<T>& CacheAllocatorConfig<T>::setDefaultAllocSizes(
     std::set<uint32_t> allocSizes) {
@@ -844,6 +884,95 @@ CacheAllocatorConfig<T>& CacheAllocatorConfig<T>::enableItemReaperInBackground(
   return *this;
 }
 
+template <typename T>
+CacheAllocatorConfig<T>& CacheAllocatorConfig<T>::configureMemoryTiers(
+    size_t totalCacheSize, const MemoryTierConfigs& config) {
+  setCacheSizeImpl(totalCacheSize);
+  if (!getCacheSize()) {
+    throw std::invalid_argument("Total cache size must be greater than 0.");
+  }
+
+  return configureMemoryTiers(config);
+}
+
+template <typename T>
+CacheAllocatorConfig<T>& CacheAllocatorConfig<T>::configureMemoryTiers(
+    const MemoryTierConfigs& config) {
+  if (config.size() != 1) {
+    throw std::invalid_argument(
+        "Only single memory tier is currently supported.");
+  }
+  memoryTierConfigs = config;
+  size_t sumRatios = 0;
+  size_t sumSizes = 0;
+
+  for (const auto& tierConfig : memoryTierConfigs) {
+    auto tierSize = tierConfig.getSize();
+    auto tierRatio = tierConfig.getRatio();
+    if ((sumRatios && tierSize) || (sumSizes && tierRatio)) {
+      throw std::invalid_argument(
+          "For each memory tier either size or ratio must be set.");
+    }
+    sumRatios += tierRatio;
+    sumSizes += tierSize;
+  }
+
+  if (!getCacheSize()) {
+    if (sumRatios) {
+      throw std::invalid_argument(
+          "Total cache size must be specified when size ratios are "
+          "used to specify memory tier sizes.");
+    } else if (sumSizes) {
+      setCacheSizeImpl(sumSizes);
+    }
+  }
+
+  if (sumRatios) {
+    if (!getCacheSize()) {
+      throw std::invalid_argument(
+          "Total cache size must be specified when size ratios are "
+          "used to specify memory tier sizes.");
+    } else {
+      if (getCacheSize() < sumRatios) {
+        throw std::invalid_argument(
+            "Sum of all tier size ratios is greater than total cache size.");
+      }
+      // Convert ratios to sizes
+      sumSizes = 0;
+      size_t partitionSize = getCacheSize() / sumRatios;
+      for (auto& tierConfig : memoryTierConfigs) {
+        tierConfig.setSize(partitionSize * tierConfig.getRatio());
+        sumSizes += tierConfig.getSize();
+      }
+      if (getCacheSize() != sumSizes) {
+        // Adjust capacity of the last tier to account for rounding error
+        memoryTierConfigs.back().setSize(memoryTierConfigs.back().getSize() +
+                                         (getCacheSize() - sumSizes));
+        sumSizes = getCacheSize();
+      }
+    }
+  } else if (sumSizes) {
+    if (sumSizes != getCacheSize()) {
+      throw std::invalid_argument(
+          "Sum of tier sizes doesn't match total cache size. "
+          "Setting of cache total size is not required when per-tier "
+          "sizes are specified - it is calculated as sum of tier sizes.");
+    }
+  } else {
+    throw std::invalid_argument(
+        "Either sum of all memory tiers sizes or sum of all ratios "
+        "must be greater than 0.");
+  }
+
+  return *this;
+}
+
+template <typename T>
+const typename CacheAllocatorConfig<T>::MemoryTierConfigs&
+CacheAllocatorConfig<T>::getMemoryTierConfigs() {
+  return memoryTierConfigs;
+}
+
 template <typename T>
 CacheAllocatorConfig<T>& CacheAllocatorConfig<T>::disableCacheEviction() {
   disableEviction = true;

cachelib/allocator/MemoryTierCacheConfig.h

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) Intel Corporation
+ *
+ * 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 <string>
+
+#include "cachelib/shm/ShmCommon.h"
+
+namespace facebook {
+namespace cachelib {
+class MemoryTierCacheConfig {
+ public:
+  // Creates instance of MemoryTierCacheConfig for Posix/SysV Shared memory.
+  static MemoryTierCacheConfig fromShm() {
+    // TODO: expand this method when adding support for file-mapped memory
+    return MemoryTierCacheConfig();
+  }
+
+  // Specifies size of this memory tier. Sizes of tiers  must be specified by
+  // either setting size explicitly or using ratio, mixing of the two is not
+  // supported.
+  MemoryTierCacheConfig& setSize(size_t _size) {
+    size = _size;
+    return *this;
+  }
+
+  // Specifies ratio of this memory tier to other tiers. Absolute size
+  // of each tier can be calculated as:
+  // cacheSize * tierRatio / Sum of ratios for all tiers; the difference
+  // between total cache size and sum of all tier sizes resulted from
+  // round off error is accounted for when calculating the last tier's
+  // size to make the totals equal.
+  MemoryTierCacheConfig& setRatio(double _ratio) {
+    ratio = _ratio;
+    return *this;
+  }
+
+  size_t getRatio() const noexcept { return ratio; }
+
+  size_t getSize() const noexcept { return size; }
+
+  // Size of this memory tiers
+  size_t size{0};
+
+  // Ratio is a number of parts of the total cache size to be allocated for this
+  // tier. E.g. if X is a total cache size, Yi are ratios specified for memory
+  // tiers, and Y is the sum of all Yi, then size of the i-th tier
+  // Xi = (X / Y) * Yi. For examle, to configure 2-tier cache where each
+  // tier is a half of the total cache size, set both tiers' ratios to 1.
+  size_t ratio{0};
+
+ private:
+  // TODO: introduce a container for tier settings when adding support for
+  // file-mapped memory
+  MemoryTierCacheConfig() = default;
+};
+} // namespace cachelib
+} // namespace facebook

cachelib/allocator/tests/CacheAllocatorConfigTest.cpp

@@ -0,0 +1,135 @@
+/*
+ * Copyright (c) Facebook, Inc. and its 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/CacheAllocatorConfig.h"
+#include "cachelib/allocator/MemoryTierCacheConfig.h"
+#include "cachelib/allocator/tests/TestBase.h"
+
+namespace facebook {
+namespace cachelib {
+
+namespace tests {
+
+using AllocatorT = LruAllocator;
+using MemoryTierConfigs = CacheAllocatorConfig<AllocatorT>::MemoryTierConfigs;
+
+// TODO: Increase this constant when multi-tier configs are fully enabled
+size_t maxNumTiers = 1;
+size_t defaultTotalSize = 2 * Slab::kSize * maxNumTiers;
+
+class CacheAllocatorConfigTest : public testing::Test {};
+
+MemoryTierConfigs generateTierConfigs(size_t numTiers,
+                                      MemoryTierCacheConfig& config) {
+  return MemoryTierConfigs(numTiers, config);
+}
+
+size_t sumTierSizes(const MemoryTierConfigs& configs) {
+  size_t sumSizes = 0;
+  for (const auto& config : configs) {
+    sumSizes += config.getSize();
+  }
+  return sumSizes;
+}
+
+TEST_F(CacheAllocatorConfigTest, MultipleTier0Config) {
+  AllocatorT::Config config1, config2;
+  // Throws if vector of tier configs is emptry
+  EXPECT_THROW(config1.configureMemoryTiers(MemoryTierConfigs()),
+               std::invalid_argument);
+  EXPECT_THROW(
+      config2.configureMemoryTiers(defaultTotalSize, MemoryTierConfigs()),
+      std::invalid_argument);
+}
+
+TEST_F(CacheAllocatorConfigTest, MultipleTier1Config) {
+  AllocatorT::Config config1, config2, config3;
+  // Accepts single-tier configuration
+  config1.setCacheSize(defaultTotalSize)
+      .configureMemoryTiers(
+          {MemoryTierCacheConfig::fromShm().setSize(defaultTotalSize)});
+  config2.setCacheSize(0).configureMemoryTiers(
+      {MemoryTierCacheConfig::fromShm().setSize(defaultTotalSize)});
+  config3.configureMemoryTiers(defaultTotalSize,
+                               {MemoryTierCacheConfig::fromShm().setRatio(1)});
+}
+
+TEST_F(CacheAllocatorConfigTest, MultipleTier2Config) {
+  AllocatorT::Config config1, config2;
+  // Throws if vector of tier configs > 1
+  EXPECT_THROW(config1.configureMemoryTiers(generateTierConfigs(
+                   maxNumTiers + 1,
+                   MemoryTierCacheConfig::fromShm().setSize(defaultTotalSize))),
+               std::invalid_argument);
+  EXPECT_THROW(
+      config2.configureMemoryTiers(
+          defaultTotalSize,
+          generateTierConfigs(maxNumTiers + 1,
+                              MemoryTierCacheConfig::fromShm().setRatio(1))),
+      std::invalid_argument);
+}
+
+TEST_F(CacheAllocatorConfigTest, TotalCacheSizeSet0) {
+  AllocatorT::Config config1, config2;
+  // If total cache size is set to zero and each individual tier specifies its
+  // size then total cache size is set to the sum of tier sizes
+  MemoryTierConfigs tierConfigs = {
+      MemoryTierCacheConfig::fromShm().setSize(defaultTotalSize)};
+  config1.setCacheSize(0).configureMemoryTiers(tierConfigs);
+  ASSERT_EQ(config1.getCacheSize(),
+            sumTierSizes(config1.getMemoryTierConfigs()));
+
+  // Throws if total cache size is set to 0 and ratios are used to specify sizes
+  EXPECT_THROW(config2.configureMemoryTiers(
+                   0, {MemoryTierCacheConfig::fromShm().setRatio(1)}),
+               std::invalid_argument);
+}
+
+TEST_F(CacheAllocatorConfigTest, TotalCacheSizeLessThanRatios) {
+  AllocatorT::Config config1, config2;
+  // Throws if total cache size is set to 0
+  EXPECT_THROW(
+      config1.setCacheSize(defaultTotalSize)
+          .configureMemoryTiers({MemoryTierCacheConfig::fromShm().setRatio(
+              defaultTotalSize + 1)}),
+      std::invalid_argument);
+  EXPECT_THROW(
+      config2.configureMemoryTiers(
+          defaultTotalSize,
+          {MemoryTierCacheConfig::fromShm().setRatio(defaultTotalSize + 1)}),
+      std::invalid_argument);
+}
+
+TEST_F(CacheAllocatorConfigTest, SumTierSizes) {
+  AllocatorT::Config config1, config2;
+  MemoryTierConfigs sizeConfigs = generateTierConfigs(
+      maxNumTiers,
+      MemoryTierCacheConfig::fromShm().setSize(defaultTotalSize / maxNumTiers));
+  MemoryTierConfigs ratioConfigs = generateTierConfigs(
+      maxNumTiers, MemoryTierCacheConfig::fromShm().setRatio(1));
+
+  config1.setCacheSize(defaultTotalSize).configureMemoryTiers(sizeConfigs);
+  ASSERT_EQ(config1.getCacheSize(),
+            sumTierSizes(config1.getMemoryTierConfigs()));
+
+  config2.setCacheSize(defaultTotalSize).configureMemoryTiers(ratioConfigs);
+  ASSERT_EQ(config2.getCacheSize(),
+            sumTierSizes(config2.getMemoryTierConfigs()));
+}
+
+} // namespace tests
+} // namespace cachelib
+} // namespace facebook