Initial version of config API extension to support multiple memory tiers

* New class MemoryTierCacheConfig allows to configure a memory tier.
  Setting tier size and location of a file for file-backed memory are
  supported in this initial implementation;
* New member, vector of memory tiers, is added to class CacheAllocatorConfig.
* New test suite, chelib/allocator/tests/MemoryTiersTest.cpp,
  demonstrates the usage of and tests extended config API.

Integrate Memory Tier config API with CacheAllocator.

Enabled memory tier config API for cachebench.

Assumes NUMA bindings support - this commit was done before
tiering support enabled.

fix memBind call

replaces Add MemoryTierCacheConfig::fromShm()
(commit 1c7c15d)

Move validation code for memory tiers to validate() method and convert
ratios to sizes lazily

Do not compensate for rounding error when calculating tier sizes (pmem#43)

Compensation results in ratios being different than originially specified.

Fixed total cache size in CacheMemoryStats (pmem#38)

Return a sum of sizes of each tier instead of just 1st tier's size.

Issue75 rebased (pmem#88)

* pmem#75: Use actual tier sizes (rounded down to slab size and decreased by header size) when creating new memory pools

* Added getPoolSize method to calculate combined pool size for all tiers; added pool size validation to tests

* Explicitly specified type for totalCacheSize to avoid overflow

* Minor test change

* Reworked tests

* Minor change

* Deleted redundant tests

* Deleted unused constant

* First set of changes to cache configuration API to enable multi-tier caches (facebook#138)

Summary:
These changes introduce per-tier cache configuration required to implement features discussed here: facebook#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.

Pull Request resolved: facebook#138

Reviewed By: therealgymmy

Differential Revision: D36189766

Pulled By: jiayuebao

fbshipit-source-id: 947aa0cd800ea6accffc1b7b6b0c9693aa7fc0a5

Co-authored-by: Victoria McGrath <[email protected]>

Author: victoria-mcgrath

cachelib/allocator/CMakeLists.txt

@@ -117,6 +117,8 @@ if (BUILD_TESTS)
   add_test (tests/ChainedHashTest.cpp)
   add_test (tests/AllocatorResizeTypeTest.cpp)
   add_test (tests/AllocatorHitStatsTypeTest.cpp)
+  add_test (tests/AllocatorMemoryTiersTest.cpp)
+  add_test (tests/MemoryTiersTest.cpp)
   add_test (tests/MultiAllocatorTest.cpp)
   add_test (tests/NvmAdmissionPolicyTest.cpp)
   add_test (tests/CacheAllocatorConfigTest.cpp)

cachelib/allocator/CacheAllocator-inl.h

@@ -53,12 +53,13 @@ CacheAllocator<CacheTrait>::CacheAllocator(
     : isOnShm_{type != InitMemType::kNone ? true
                                           : config.memMonitoringEnabled()},
       config_(config.validate()),
+      memoryTierConfigs(config.getMemoryTierConfigs()),
       tempShm_(type == InitMemType::kNone && isOnShm_
-                   ? std::make_unique<TempShmMapping>(config_.size)
+                   ? std::make_unique<TempShmMapping>(config_.getCacheSize())
                    : nullptr),
       shmManager_(type != InitMemType::kNone
                       ? std::make_unique<ShmManager>(config_.cacheDir,
-                                                     config_.usePosixShm)
+                                                     config_.isUsingPosixShm())
                       : nullptr),
       deserializer_(type == InitMemType::kMemAttach ? createDeserializer()
                                                     : nullptr),
@@ -112,7 +113,9 @@ ShmSegmentOpts CacheAllocator<CacheTrait>::createShmCacheOpts() {
   // TODO: we support single tier so far
   XDCHECK_EQ(memoryTierConfigs.size(), 1ul);
   opts.memBindNumaNodes = memoryTierConfigs[0].getMemBind();
-
+  if (memoryTierConfigs.size() > 1) {
+    throw std::invalid_argument("CacheLib only supports a single memory tier");
+  }
   return opts;
 }
 
@@ -122,10 +125,10 @@ CacheAllocator<CacheTrait>::createNewMemoryAllocator() {
   return std::make_unique<MemoryAllocator>(
       getAllocatorConfig(config_),
       shmManager_
-          ->createShm(detail::kShmCacheName, config_.size,
+          ->createShm(detail::kShmCacheName, config_.getCacheSize(),
                       config_.slabMemoryBaseAddr, createShmCacheOpts())
           .addr,
-      config_.size);
+      config_.getCacheSize());
 }
 
 template <typename CacheTrait>
@@ -135,9 +138,8 @@ CacheAllocator<CacheTrait>::restoreMemoryAllocator() {
       deserializer_->deserialize<MemoryAllocator::SerializationType>(),
       shmManager_
           ->attachShm(detail::kShmCacheName, config_.slabMemoryBaseAddr,
-                      createShmCacheOpts())
-          .addr,
-      config_.size,
+          createShmCacheOpts()).addr,
+      config_.getCacheSize(),
       config_.disableFullCoredump);
 }
 
@@ -243,10 +245,10 @@ std::unique_ptr<MemoryAllocator> CacheAllocator<CacheTrait>::initAllocator(
   if (type == InitMemType::kNone) {
     if (isOnShm_ == true) {
       return std::make_unique<MemoryAllocator>(
-          getAllocatorConfig(config_), tempShm_->getAddr(), config_.size);
+          getAllocatorConfig(config_), tempShm_->getAddr(), config_.getCacheSize());
     } else {
       return std::make_unique<MemoryAllocator>(getAllocatorConfig(config_),
-                                               config_.size);
+                                               config_.getCacheSize());
     }
   } else if (type == InitMemType::kMemNew) {
     return createNewMemoryAllocator();
@@ -2177,6 +2179,13 @@ const std::string CacheAllocator<CacheTrait>::getCacheName() const {
   return config_.cacheName;
 }
 
+template <typename CacheTrait>
+size_t CacheAllocator<CacheTrait>::getPoolSize(PoolId poolId) const {
+  const auto& pool = allocator_->getPool(poolId);
+  size_t poolSize = pool.getPoolSize();
+  return poolSize;
+}
+
 template <typename CacheTrait>
 PoolStats CacheAllocator<CacheTrait>::getPoolStats(PoolId poolId) const {
   const auto& pool = allocator_->getPool(poolId);
@@ -2251,7 +2260,7 @@ PoolEvictionAgeStats CacheAllocator<CacheTrait>::getPoolEvictionAgeStats(
 template <typename CacheTrait>
 CacheMetadata CacheAllocator<CacheTrait>::getCacheMetadata() const noexcept {
   return CacheMetadata{kCachelibVersion, kCacheRamFormatVersion,
-                       kCacheNvmFormatVersion, config_.size};
+                       kCacheNvmFormatVersion, config_.getCacheSize()};
 }
 
 template <typename CacheTrait>

cachelib/allocator/CacheAllocator.h

@@ -1159,6 +1159,9 @@ class CacheAllocator : public CacheBase {
   // whether it is object-cache
   bool isObjectCache() const override final { return false; }
 
+  // combined pool size for all memory tiers
+  size_t getPoolSize(PoolId pid) const;
+
   // pool stats by pool id
   PoolStats getPoolStats(PoolId pid) const override final;
 
@@ -1986,6 +1989,8 @@ class CacheAllocator : public CacheBase {
 
   Config config_{};
 
+  const typename Config::MemoryTierConfigs memoryTierConfigs;
+
   // Manages the temporary shared memory segment for memory allocator that
   // is not persisted when cache process exits.
   std::unique_ptr<TempShmMapping> tempShm_;

cachelib/allocator/CacheAllocatorConfig.h

@@ -194,19 +194,24 @@ class CacheAllocatorConfig {
   // This allows cache to be persisted across restarts. One example use case is
   // to preserve the cache when releasing a new version of your service. Refer
   // to our user guide for how to set up cache persistence.
+  // TODO: get rid of baseAddr or if set make sure all mapping are adjacent?
+  // We can also make baseAddr a per-tier configuration
   CacheAllocatorConfig& enableCachePersistence(std::string directory,
                                                void* baseAddr = nullptr);
 
-  // uses posix shm segments instead of the default sys-v shm segments.
-  // @throw std::invalid_argument if called without enabling
-  // cachePersistence()
+  // Uses posix shm segments instead of the default sys-v shm
+  // segments. @throw std::invalid_argument if called without enabling
+  // cachePersistence().
   CacheAllocatorConfig& usePosixForShm();
 
   // Configures cache memory tiers. Each tier represents a cache region inside
   // byte-addressable memory such as DRAM, Pmem, CXLmem.
   // Accepts vector of MemoryTierCacheConfig. Each vector element describes
   // configuration for a single memory cache tier. Tier sizes are specified as
   // ratios, the number of parts of total cache size each tier would occupy.
+  // @throw std::invalid_argument if:
+  // - the size of configs is 0
+  // - the size of configs is greater than kMaxCacheMemoryTiers
   CacheAllocatorConfig& configureMemoryTiers(const MemoryTierConfigs& configs);
 
   // Return reference to MemoryTierCacheConfigs.
@@ -374,8 +379,7 @@ class CacheAllocatorConfig {
   std::map<std::string, std::string> serialize() const;
 
   // The max number of memory cache tiers
-  // TODO: increase this number when multi-tier configs are enabled
-  inline static const size_t kMaxCacheMemoryTiers = 1;
+  inline static const size_t kMaxCacheMemoryTiers = 2;
 
   // Cache name for users to indentify their own cache.
   std::string cacheName{""};
@@ -1085,7 +1089,7 @@ std::map<std::string, std::string> CacheAllocatorConfig<T>::serialize() const {
 
   configMap["size"] = std::to_string(size);
   configMap["cacheDir"] = cacheDir;
-  configMap["posixShm"] = usePosixShm ? "set" : "empty";
+  configMap["posixShm"] = isUsingPosixShm() ? "set" : "empty";
 
   configMap["defaultAllocSizes"] = "";
   // Stringify std::set

cachelib/allocator/MemoryTierCacheConfig.h

@@ -24,7 +24,6 @@ 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();
   }
 
@@ -51,7 +50,7 @@ class MemoryTierCacheConfig {
     return numaNodes;
   }
 
-  size_t calculateTierSize(size_t totalCacheSize, size_t partitionNum) {
+  size_t calculateTierSize(size_t totalCacheSize, size_t partitionNum) const {
     // TODO: Call this method when tiers are enabled in allocator
     // to calculate tier sizes in bytes.
     if (!partitionNum) {
@@ -66,7 +65,7 @@ class MemoryTierCacheConfig {
 
     return getRatio() * (totalCacheSize / partitionNum);
   }
-
+  
  private:
   // 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
@@ -80,6 +79,7 @@ class MemoryTierCacheConfig {
 
   // TODO: introduce a container for tier settings when adding support for
   // file-mapped memory
+
   MemoryTierCacheConfig() = default;
 };
 } // namespace cachelib

cachelib/allocator/memory/SlabAllocator.cpp

@@ -40,7 +40,7 @@
 using namespace facebook::cachelib;
 
 namespace {
-size_t roundDownToSlabSize(size_t size) { return size - (size % sizeof(Slab)); }
+static inline size_t roundDownToSlabSize(size_t size) { return size - (size % sizeof(Slab)); }
 } // namespace
 
 // definitions to avoid ODR violation.

cachelib/allocator/tests/AllocatorMemoryTiersTest.cpp

@@ -0,0 +1,30 @@
+/*
+ * 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.
+ */
+
+#include "cachelib/allocator/tests/AllocatorMemoryTiersTest.h"
+
+namespace facebook {
+namespace cachelib {
+namespace tests {
+
+using LruAllocatorMemoryTiersTest = AllocatorMemoryTiersTest<LruAllocator>;
+
+// TODO(MEMORY_TIER): add more tests with different eviction policies
+TEST_F(LruAllocatorMemoryTiersTest, MultiTiersValid1) { this->testMultiTiersValid1(); }
+
+} // end of namespace tests
+} // end of namespace cachelib
+} // end of namespace facebook

cachelib/allocator/tests/AllocatorMemoryTiersTest.h

@@ -0,0 +1,43 @@
+/*
+ * 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.
+ */
+
+#pragma once
+
+#include "cachelib/allocator/CacheAllocatorConfig.h"
+#include "cachelib/allocator/MemoryTierCacheConfig.h"
+#include "cachelib/allocator/tests/TestBase.h"
+
+namespace facebook {
+namespace cachelib {
+namespace tests {
+
+template <typename AllocatorT>
+class AllocatorMemoryTiersTest : public AllocatorTest<AllocatorT> {
+ public:
+  void testMultiTiersValid1() {
+    typename AllocatorT::Config config;
+    config.setCacheSize(100 * Slab::kSize);
+    ASSERT_NO_THROW(config.configureMemoryTiers({
+        MemoryTierCacheConfig::fromShm()
+            .setRatio(1).setMemBind(std::string("0")),
+        MemoryTierCacheConfig::fromShm()
+            .setRatio(1).setMemBind(std::string("0"))
+    }));
+  }
+};
+} // namespace tests
+} // namespace cachelib
+} // namespace facebook

cachelib/allocator/tests/AllocatorTypeTest.cpp

@@ -16,6 +16,7 @@
 
 #include "cachelib/allocator/tests/BaseAllocatorTest.h"
 #include "cachelib/allocator/tests/TestBase.h"
+#include "cachelib/allocator/MemoryTierCacheConfig.h"
 
 namespace facebook {
 namespace cachelib {
@@ -226,6 +227,12 @@ TYPED_TEST(BaseAllocatorTest, ReaperSkippingSlabTraversalWhileSlabReleasing) {
 }
 
 TYPED_TEST(BaseAllocatorTest, ReaperShutDown) { this->testReaperShutDown(); }
+TYPED_TEST(BaseAllocatorTest, ReaperShutDownFile) {
+  this->testReaperShutDown({
+    MemoryTierCacheConfig::fromShm()
+      .setRatio(1).setMemBind(std::string("0"))
+  });
+}
 
 TYPED_TEST(BaseAllocatorTest, ShutDownWithActiveHandles) {
   this->testShutDownWithActiveHandles();

cachelib/allocator/tests/BaseAllocatorTest.h

@@ -1259,7 +1259,7 @@ class BaseAllocatorTest : public AllocatorTest<AllocatorT> {
     this->testLruLength(alloc, poolId, sizes, keyLen, evictedKeys);
   }
 
-  void testReaperShutDown() {
+  void testReaperShutDown(typename AllocatorT::Config::MemoryTierConfigs cfgs = {}) {
     const size_t nSlabs = 20;
     const size_t size = nSlabs * Slab::kSize;
 
@@ -1269,6 +1269,8 @@ class BaseAllocatorTest : public AllocatorTest<AllocatorT> {
     config.setAccessConfig({8, 8});
     config.enableCachePersistence(this->cacheDir_);
     config.enableItemReaperInBackground(std::chrono::seconds(1), {});
+    if (cfgs.size())
+      config.configureMemoryTiers(cfgs);
     std::vector<typename AllocatorT::Key> keys;
     {
       AllocatorT alloc(AllocatorT::SharedMemNew, config);