feat(cache): introduce three-tier LRU cache (active→inactive→idle) (alibaba#1209)

* refactor(cache): introduce three-tier cache (active→inactive→idle)

* add adaptive threshold

* fix build for gcc12

* use string-keyed unordered set

Author: xiaoyang-hhh

fs/cache/full_file_cache/cache_pool.cpp

@@ -20,6 +20,7 @@ limitations under the License.
 #include <sys/stat.h>
 
 #include <algorithm>
+#include <numeric>
 #include <sys/statvfs.h>
 
 #include "cache_store.h"
@@ -79,11 +80,7 @@ ICacheStore* FileCachePool::do_open(std::string_view pathname, int flags, mode_t
     return nullptr;
   }
 
-  // Check idle container first
-  auto idleIt = idleFileIndex_.find(pathname);
-  if (idleIt != idleFileIndex_.end()) {
-    promoteFromIdle(idleIt);
-  }
+  promoteToHot(pathname);
 
   auto find = fileIndex_.find(pathname);
   if (find == fileIndex_.end()) {
@@ -96,15 +93,7 @@ ICacheStore* FileCachePool::do_open(std::string_view pathname, int flags, mode_t
     find->second->openCount++;
   }
 
-  // If LRU exceeds the limit, demote the tail (only if not open) to idle
-  while (lru_.size() > demoteThreshold_) {
-    auto tailIt = lru_.back();
-    if (tailIt->second->openCount == 0) {
-      demoteToIdle(tailIt);
-    } else {
-      break;
-    }
-  }
+  demoteToCold();
 
   return new FileCacheStore(this, localFile, refillUnit_, find);
 }
@@ -139,10 +128,13 @@ int FileCachePool::stat(CacheStat* stat, std::string_view pathname) {
 }
 
 int FileCachePool::evict(std::string_view filename) {
-  // Check idle container first
-  auto idleIt = idleFileIndex_.find(filename);
-  if (idleIt != idleFileIndex_.end()) {
-    return evictIdleEntry(idleIt) >= 0 ? 0 : -1;
+  // Check cold tiers first
+  for (auto* tier : coldTiers_) {
+    if (tier->contains(filename)) {
+      auto freed = truncateAndUnlink(filename);
+      tier->remove(filename);
+      return freed >= 0 ? 0 : -1;
+    }
   }
 
   auto fileIter = fileIndex_.find(filename);
@@ -262,10 +254,18 @@ void FileCachePool::eviction() {
 
   isFull_ = true;
 
-  // Phase 1: evict from idle tier first.
-  actualEvict -= evictIdleWhenFull(actualEvict);
+  // Evict from cold tiers first in reverse order
+  for (int i = coldTiers_.size() - 1; i >= 0; i--) {
+    auto* tier = coldTiers_[i];
+    while (actualEvict > 0 && !tier->empty() && !exit_) {
+      auto name = tier->victim();
+      auto freed = truncateAndUnlink(name);
+      tier->remove(name);
+      if (freed >= 0) actualEvict -= freed;
+      photon::thread_yield();
+    }
+  }
 
-  // Phase 2: fall back to LRU eviction when idle tier is exhausted
   while (actualEvict > 0 && !lru_.empty() && !exit_) {
     auto fileIter = lru_.back();
     const auto& fileName = fileIter->first;
@@ -347,34 +347,72 @@ int FileCachePool::insertFile(std::string_view file) {
   }
   auto fileSize = st.st_blocks * kDiskBlockSize;
 
-  if (lru_.size() >= demoteThreshold_) {
-    auto idleLruIt = idleLru_.push_front(idleFileIndex_.end());
-    auto iter = idleFileIndex_.emplace(file, idleLruIt).first;
-    idleLru_.front() = iter;
-  } else {
-    auto lruIter = lru_.push_front(fileIndex_.end());
-    auto entry = std::unique_ptr<LruEntry>(new LruEntry{lruIter, 0, fileSize});
-    auto iter = fileIndex_.emplace(file, std::move(entry)).first;
-    lru_.front() = iter;
-  }
+  auto lruIter = lru_.push_front(fileIndex_.end());
+  auto entry = std::unique_ptr<LruEntry>(new LruEntry{lruIter, 0, fileSize});
+  auto iter = fileIndex_.emplace(file, std::move(entry)).first;
+  lru_.front() = iter;
   totalUsed_ += fileSize;
+
+  demoteToCold();
   return 0;
 }
 
-// Demote a LRU entry (openCount must be 0) to the idle container.
-void FileCachePool::demoteToIdle(FileNameMap::iterator iter) {
-  auto idleLruIt = idleLru_.push_front(idleFileIndex_.end());
-  auto idleIndexIt = idleFileIndex_.emplace(iter->first, idleLruIt).first;
-  idleLru_.front() = idleIndexIt;
+void FileCachePool::adaptThresholds() {
+  uint64_t count = std::accumulate(tierHits_.begin(), tierHits_.end(), 0ULL);
+  for (size_t i = 0; i + 1 < tierHits_.size(); i++) {
+    if (count > 0) {
+      double ratio = static_cast<double>(tierHits_[i]) / count;
+      // High ratio => this tier absorbs the bulk of hits, it has room to shrink.
+      // Low ratio => hits leak to colder tiers, grow it.
+      if (ratio > 0.90) thresholds_[i].adapt(0.80);
+      else if (ratio < 0.50) thresholds_[i].adapt(1.25);
+    }
+    count -= tierHits_[i];
+  }
 
-  lru_.remove(iter->second->lruIter);
-  fileIndex_.erase(iter);
+  promoteCount_ = 0;
+  tierHits_.fill(0);
 }
 
-// Promote an idle entry back to the front of LRU.
-void FileCachePool::promoteFromIdle(IdleFileNameMap::iterator idleIt) {
-  uint32_t idleLruIter = idleIt->second;
-  const auto& filename = idleIt->first;
+void FileCachePool::demoteToCold() {
+  while (lru_.size() > thresholds_[0].value) {
+    auto tailIt = lru_.back();
+    if (tailIt->second->openCount != 0) break;
+
+    coldTiers_[0]->insert(tailIt->first);
+    lru_.remove(tailIt->second->lruIter);
+    fileIndex_.erase(tailIt);
+
+    for (size_t i = 1; i < coldTiers_.size(); i++) {
+      if (coldTiers_[i-1]->size() > thresholds_[i].value) {
+        auto key = coldTiers_[i-1]->victim();
+        coldTiers_[i]->insert(key);
+        coldTiers_[i-1]->remove(key);
+      } else break;
+    }
+  }
+}
+
+void FileCachePool::promoteToHot(std::string_view filename) {
+  auto find = fileIndex_.find(filename);
+  if (find != fileIndex_.end()) {
+    tierHits_[0]++;
+    return;
+  }
+
+  bool found = false;
+  for (size_t i = 0; i < coldTiers_.size(); ++i) {
+    if (coldTiers_[i]->contains(filename)) {
+      tierHits_[i + 1]++;
+      found = true;
+      coldTiers_[i]->remove(filename);
+      break;
+    }
+  }
+  if (!found) return;
+
+  promoteCount_++;
+  if (promoteCount_ >= kPromotesPerAdapt) adaptThresholds();
 
   struct stat st = {};
   uint64_t fileSize = 0;
@@ -386,15 +424,9 @@ void FileCachePool::promoteFromIdle(IdleFileNameMap::iterator idleIt) {
   auto entry = std::unique_ptr<LruEntry>(new LruEntry{lruIter, 0, fileSize});
   auto iter = fileIndex_.emplace(filename, std::move(entry)).first;
   lru_.front() = iter;
-
-  idleLru_.remove(idleLruIter);
-  idleFileIndex_.erase(idleIt);
 }
 
-// Evict the idle entry pointed to by idleIt; return freed bytes or -1 on error.
-ssize_t FileCachePool::evictIdleEntry(IdleFileNameMap::iterator idleIt) {
-  const auto& filename = idleIt->first;
-
+ssize_t FileCachePool::truncateAndUnlink(std::string_view filename) {
   struct stat st = {};
   uint64_t fileSize = 0;
   if (mediaFs_->stat(filename.data(), &st) == 0) {
@@ -414,22 +446,49 @@ ssize_t FileCachePool::evictIdleEntry(IdleFileNameMap::iterator idleIt) {
     // we still evict fileSize bytes even if unlink fails
     LOG_ERRNO_RETURN(0, fileSize, "unlink failed, name : `", filename);
   }
-
-  uint32_t idleLruIter = idleIt->second;
-  idleLru_.remove(idleLruIter);
-  idleFileIndex_.erase(idleIt);
   return static_cast<ssize_t>(fileSize);
 }
 
-uint64_t FileCachePool::evictIdleWhenFull(uint64_t needEvict) {
-  uint64_t evictSize = 0;
-  while (evictSize < needEvict && !idleLru_.empty() && !exit_) {
-    auto r = evictIdleEntry(idleLru_.back());
-    if (r >= 0) evictSize += static_cast<uint64_t>(r);
-    photon::thread_yield();
-  }
-  return evictSize;
+// --- InactiveCacheTier ---
+bool InactiveCacheTier::contains(std::string_view name) {
+  return index_.find(name) != index_.end();
 }
 
+void InactiveCacheTier::remove(std::string_view name) {
+  auto it = index_.find(name);
+  if (it == index_.end()) return;
+  lru_.remove(it->second);
+  index_.erase(it);
+}
+
+void InactiveCacheTier::insert(std::string_view name) {
+  auto lruIt = lru_.push_front(index_.end());
+  auto it = index_.emplace(name, lruIt).first;
+  lru_.front() = it;
+}
+
+size_t InactiveCacheTier::size() { return index_.size(); }
+bool InactiveCacheTier::empty() { return lru_.empty(); }
+std::string_view InactiveCacheTier::victim() { return lru_.back()->first; }
+
+// --- IdleCacheTier ---
+bool IdleCacheTier::contains(std::string_view name) {
+  return index_.find(std::string(name)) != index_.end();
+}
+
+void IdleCacheTier::remove(std::string_view name) {
+  auto it = index_.find(std::string(name));
+  if (it == index_.end()) return;
+  index_.erase(it);
+}
+
+void IdleCacheTier::insert(std::string_view name) {
+  index_.emplace(name);
+}
+
+size_t IdleCacheTier::size() { return index_.size(); }
+bool IdleCacheTier::empty() { return index_.empty(); }
+std::string_view IdleCacheTier::victim() { return *index_.begin(); }
+
 }
 }

fs/cache/full_file_cache/cache_pool.h

@@ -16,10 +16,10 @@ limitations under the License.
 
 #pragma once
 
+#include <array>
 #include <map>
 #include <memory>
 #include <string>
-#include <unordered_map>
 #include <vector>
 #include <photon/thread/thread.h>
 #include <photon/thread/timer.h>
@@ -32,6 +32,49 @@ limitations under the License.
 namespace photon {
 namespace fs {
 
+// Abstract base for cold (non-hot) cache tiers.
+class ColdCacheTier {
+public:
+    virtual ~ColdCacheTier() = default;
+    virtual bool contains(std::string_view name) = 0;
+    virtual void remove(std::string_view name) = 0;
+    virtual void insert(std::string_view name) = 0;
+    virtual size_t size() = 0;
+    virtual bool empty() = 0;
+    // The returned view is valid until remove().
+    virtual std::string_view victim() = 0;
+};
+
+class InactiveCacheTier : public ColdCacheTier {
+public:
+    typedef map_string_key<uint32_t> IndexMap;
+    typedef photon::fs::LRU<IndexMap::iterator, uint32_t> LRUContainer;
+
+    bool contains(std::string_view name) override;
+    void remove(std::string_view name) override;
+    void insert(std::string_view name) override;
+    size_t size() override;
+    bool empty() override;
+    std::string_view victim() override;
+
+private:
+    LRUContainer lru_;
+    IndexMap index_;
+};
+
+class IdleCacheTier : public ColdCacheTier {
+public:
+    bool contains(std::string_view name) override;
+    void remove(std::string_view name) override;
+    void insert(std::string_view name) override;
+    size_t size() override;
+    bool empty() override;
+    std::string_view victim() override;
+
+private:
+    unordered_set_string_key<> index_;
+};
+
 class FileCachePool : public photon::fs::ICachePool {
 public:
     FileCachePool(photon::fs::IFileSystem *mediaFs, uint64_t capacityInGB, uint64_t periodInUs,
@@ -42,8 +85,6 @@ class FileCachePool : public photon::fs::ICachePool {
     static const uint64_t kDiskBlockSize = 512; // stat(2)
     static const uint64_t kDeleteDelayInUs = 1000;
     static const uint32_t kWaterMarkRatio = 90;
-    // max inuse-lru entries before demoting tail to idle-lru (default: 100w)
-    static const uint32_t kDemoteThreshold = 1'000'000;
 
     void Init();
 
@@ -112,19 +153,37 @@ class FileCachePool : public photon::fs::ICachePool {
     // filename -> lruEntry
     FileNameMap fileIndex_;
 
-    uint32_t demoteThreshold_ = kDemoteThreshold;
+    // Cold tiers: inactive (LRU-ordered) and idle (unordered).
+    // Eviction/promote cascades iterate coldTiers_ in order.
+    InactiveCacheTier inactiveTier_;
+    IdleCacheTier idleTier_;
+    std::array<ColdCacheTier*, 2> coldTiers_ = {&inactiveTier_, &idleTier_};
+
+    // Adaptive threshold tuning.
+    struct AdaptiveThreshold {
+        uint32_t min;
+        uint32_t max;
+        uint32_t value;
+
+        AdaptiveThreshold(int min, int max)
+            : min(min), max(max), value(min) {}
+        
+        void adapt(double ratio) {
+            value = std::max(min, std::min(max, static_cast<uint32_t>(value * ratio)));
+        }
+    };
+    std::array<AdaptiveThreshold, 2> thresholds_ = 
+        {AdaptiveThreshold(1'000, 100'000), AdaptiveThreshold(100'000, 100'000'000)};
+
+    static constexpr uint64_t kPromotesPerAdapt = 10'000;
+    uint64_t promoteCount_ = 0;
+    std::array<uint64_t, 3> tierHits_{};
 
-    // idleFileIndex_ stores filename -> lruContainer's iterator
-    // idleLru_ stores iterators into idleFileIndex_; std::map nodes are stable.
-    typedef map_string_key<uint32_t> IdleFileNameMap;
-    typedef photon::fs::LRU<IdleFileNameMap::iterator, uint32_t> IdleLRUContainer;
-    IdleLRUContainer idleLru_;
-    IdleFileNameMap idleFileIndex_;
+    void adaptThresholds();
+    void demoteToCold();
 
-    void demoteToIdle(FileNameMap::iterator iter);
-    void promoteFromIdle(IdleFileNameMap::iterator idleIter);
-    uint64_t evictIdleWhenFull(uint64_t needEvictSize);
-    ssize_t evictIdleEntry(IdleFileNameMap::iterator idleIter);
+    void promoteToHot(std::string_view filename);
+    ssize_t truncateAndUnlink(std::string_view filename);
 
     friend struct FileCachePoolTest;
 };