flowchart TB
    subgraph "Cache Module Architecture"
        subgraph "Cache Interface Layer"
            CacheAPI[Cache API]
            BlockCache[Block Cache Interface]
            RowCache[Row Cache Interface]
        end
        
        subgraph "Cache Implementation"
            subgraph "Primary Cache"
                LRUCache[LRU Cache]
                ClockCache[HyperClock Cache]
                ShardedCache[Sharded Cache Base]
            end
            
            subgraph "Secondary Cache"
                SecondaryCache[Secondary Cache Interface]
                CompressedCache[Compressed Secondary Cache]
                TieredCache[Tiered Secondary Cache]
                SecondaryAdapter[Secondary Cache Adapter]
            end
            
            subgraph "Cache Utilities"
                CacheKey[Cache Key]
                CacheHelpers[Cache Helpers]
                CacheReservation[Cache Reservation Manager]
                ChargedCache[Charged Cache]
            end
        end
        
        subgraph "Storage and Management"
            subgraph "Hash Table"
                LRUHandleTable[LRU Handle Table]
                ClockHandleTable[Clock Handle Table]
            end
            
            subgraph "Memory Management"
                MemoryAllocator[Memory Allocator]
                CacheEntryRoles[Cache Entry Roles]
                UsageTracker[Usage Tracker]
            end
            
            subgraph "Eviction Policies"
                LRUEviction[LRU Eviction]
                ClockEviction[Clock Eviction]
                PriorityQueues[Priority Queues]
            end
        end
        
        subgraph "Monitoring and Statistics"
            CacheStats[Cache Statistics]
            EvictionCallback[Eviction Callback]
            CacheEntryStats[Cache Entry Statistics]
        end
    end
    
    subgraph "External Dependencies"
        TableReader[Table Reader]
        FilterPolicy[Filter Policy]
        BlockBuilder[Block Builder]
        Compressor[Compressor]
    end
    
    %% API Connections
    CacheAPI --> LRUCache
    CacheAPI --> ClockCache
    BlockCache --> ShardedCache
    RowCache --> ShardedCache
    
    %% Implementation Connections
    LRUCache --> LRUHandleTable
    LRUCache --> LRUEviction
    ClockCache --> ClockHandleTable
    ClockCache --> ClockEviction
    ShardedCache --> MemoryAllocator
    
    %% Secondary Cache Connections
    LRUCache --> SecondaryAdapter
    ClockCache --> SecondaryAdapter
    SecondaryAdapter --> CompressedCache
    SecondaryAdapter --> TieredCache
    
    %% Utility Connections
    LRUCache --> CacheKey
    ClockCache --> CacheKey
    ShardedCache --> CacheHelpers
    ShardedCache --> CacheReservation
    
    %% Management Connections
    LRUEviction --> PriorityQueues
    ClockEviction --> UsageTracker
    MemoryAllocator --> CacheEntryRoles
    
    %% Statistics Connections
    LRUCache --> CacheStats
    ClockCache --> CacheStats
    ShardedCache --> EvictionCallback
    CacheStats --> CacheEntryStats
    
    %% External Dependencies
    TableReader --> CacheAPI
    FilterPolicy --> BlockCache
    BlockBuilder --> CacheAPI
    Compressor --> CompressedCache
    
    classDef interfaceClass fill:#e3f2fd
    classDef primaryClass fill:#f3e5f5
    classDef secondaryClass fill:#e8f5e8
    classDef utilityClass fill:#fff3e0
    classDef storageClass fill:#fce4ec
    classDef monitoringClass fill:#f1f8e9
    classDef externalClass fill:#ffebee
    
    class CacheAPI,BlockCache,RowCache interfaceClass
    class LRUCache,ClockCache,ShardedCache primaryClass
    class SecondaryCache,CompressedCache,TieredCache,SecondaryAdapter secondaryClass
    class CacheKey,CacheHelpers,CacheReservation,ChargedCache utilityClass
    class LRUHandleTable,ClockHandleTable,MemoryAllocator,CacheEntryRoles,UsageTracker,LRUEviction,ClockEviction,PriorityQueues storageClass
    class CacheStats,EvictionCallback,CacheEntryStats monitoringClass
    class TableReader,FilterPolicy,BlockBuilder,Compressor externalClass

// LRU缓存的核心数据结构
class LRUCacheShard {
private:
    // 双向链表节点
    struct LRUHandle {
        Cache::ObjectPtr value;              // 缓存值
        const Cache::CacheItemHelper* helper; // 缓存项辅助器
        LRUHandle* next_hash;               // 哈希链表指针
        LRUHandle* next;                    // LRU链表下一个节点
        LRUHandle* prev;                    // LRU链表上一个节点
        size_t total_charge;                // 总内存开销
        uint32_t hash;                      // 哈希值
        uint32_t refs;                      // 引用计数
        uint8_t m_flags;                    // 可变标志
        uint8_t im_flags;                   // 不可变标志
        char key_data[1];                   // 键数据（变长）
    };
    
    // 哈希表
    LRUHandleTable table_;
    
    // LRU链表头尾指针
    LRUHandle lru_;                         // 链表头（最近使用）
    LRUHandle* lru_low_pri_;               // 低优先级池头部
    LRUHandle* lru_bottom_pri_;            // 底部优先级池头部
    
    // 容量和使用量
    size_t capacity_;                       // 总容量
    size_t usage_;                         // 当前使用量
    size_t lru_usage_;                     // LRU链表使用量
    
    // 优先级池配置
    double high_pri_pool_ratio_;           // 高优先级池比例
    double low_pri_pool_ratio_;            // 低优先级池比例
    
    mutable DMutex mutex_;                 // 分布式互斥锁
    
public:
    // 查找操作
    Cache::Handle* Lookup(const Slice& key, uint32_t hash) {
        MutexLock l(&mutex_);
        LRUHandle* e = table_.Lookup(key, hash);
        if (e != nullptr) {
            // 命中：增加引用计数，从LRU链表中移除（如果在链表中）
            assert(e->InCache());
            if (!e->HasRefs()) {
                // 从LRU链表移到哈希表（仅引用状态）
                LRU_Remove(e);
            }
            e->Ref();
            e->SetHit();
        }
        return reinterpret_cast<Cache::Handle*>(e);
    }
    
    // 插入操作
    Status Insert(const Slice& key, uint32_t hash, Cache::ObjectPtr value,
                 const Cache::CacheItemHelper* helper, size_t charge,
                 Cache::Handle** handle, Cache::Priority priority) {
        
        MutexLock l(&mutex_);
        
        // 创建新的缓存项
        LRUHandle* e = reinterpret_cast<LRUHandle*>(
            malloc(sizeof(LRUHandle) - 1 + key.size()));
        e->value = value;
        e->helper = helper;
        e->total_charge = charge;
        e->key_length = key.size();
        e->hash = hash;
        e->refs = 0;  // 初始引用计数为0
        e->SetInCache(true);
        e->SetPriority(priority);
        memcpy(e->key_data, key.data(), key.size());
        
        // 检查容量限制
        if (usage_ + charge > capacity_ && strict_capacity_limit_) {
            // 严格容量限制：拒绝插入
            e->SetInCache(false);
            (*helper->del_cb)(e->key(), e->value);
            free(e);
            return Status::MemoryLimit("Insert failed due to capacity limit");
        }
        
        // 淘汰旧项以腾出空间
        while (usage_ + charge > capacity_ && lru_.next != &lru_) {
            LRUHandle* old = lru_.next;
            assert(!old->HasRefs());
            LRU_Remove(old);
            table_.Remove(old->key(), old->hash);
            old->SetInCache(false);
            usage_ -= old->total_charge;
            (*old->helper->del_cb)(old->key(), old->value);
            free(old);
        }
        
        // 插入到哈希表
        LRUHandle* old = table_.Insert(e);
        usage_ += charge;
        
        if (old != nullptr) {
            // 替换已存在的项
            old->SetInCache(false);
            if (!old->HasRefs()) {
                LRU_Remove(old);
            }
            (*old->helper->del_cb)(old->key(), old->value);
            free(old);
        }
        
        // 根据优先级插入到LRU链表
        if (handle == nullptr) {
            // 立即插入到LRU链表
            LRU_Insert(e);
        } else {
            // 返回句柄，延迟插入
            e->Ref();
            *handle = reinterpret_cast<Cache::Handle*>(e);
        }
        
        return Status::OK();
    }
    
private:
    // LRU链表操作
    void LRU_Remove(LRUHandle* e) {
        assert(e->next != nullptr);
        assert(e->prev != nullptr);
        e->next->prev = e->prev;
        e->prev->next = e->next;
        e->prev = e->next = nullptr;
        lru_usage_ -= e->total_charge;
    }
    
    void LRU_Insert(LRUHandle* e) {
        assert(e->next == nullptr);
        assert(e->prev == nullptr);
        
        // 根据优先级选择插入位置
        if (high_pri_pool_ratio_ > 0 && e->IsHighPri()) {
            // 高优先级：插入到高优先级池
            LRUHandle* head = &lru_;
            LRU_InsertAfter(head, e);
            e->SetInHighPriPool(true);
        } else if (low_pri_pool_ratio_ > 0 && e->IsLowPri()) {
            // 低优先级：插入到低优先级池
            LRU_InsertAfter(lru_low_pri_, e);
            e->SetInLowPriPool(true);
        } else {
            // 普通优先级：插入到普通区域
            LRU_InsertAfter(lru_low_pri_, e);
        }
        
        lru_usage_ += e->total_charge;
        
        // 维护优先级池边界
        MaintainPoolSize();
    }
    
    void LRU_InsertAfter(LRUHandle* pos, LRUHandle* e) {
        e->next = pos->next;
        e->prev = pos;
        pos->next->prev = e;
        pos->next = e;
    }
};

// HyperClock缓存的核心数据结构
template <class Table>
class HyperClockCacheShard {
private:
    // 缓存项状态编码
    static constexpr uint64_t kStateEmpty = 0;
    static constexpr uint64_t kStateConstruction = 1;
    static constexpr uint64_t kStateVisible = 2;
    static constexpr uint64_t kStateInvisible = 3;
    
    // 引用计数和时钟计数器的编码
    static constexpr int kAcquireIncrement = 1 << 2;
    static constexpr int kReleaseIncrement = 1 << (2 + kCountdownBits);
    static constexpr uint64_t kMaxCountdown = (1 << kCountdownBits) - 1;
    
    Table table_;                           // 哈希表
    std::atomic<uint64_t> clock_pointer_;   // 时钟指针
    
public:
    // 查找操作（无锁）
    Cache::Handle* Lookup(const Slice& key, uint32_t hash) {
        size_t slot = table_.GetSlot(key, hash);
        typename Table::HandleImpl* h = table_.HandlePtr(slot);
        
        // 原子地增加acquire计数
        uint64_t old_meta = h->meta.fetch_add(kAcquireIncrement,
                                             std::memory_order_acquire);
        
        // 检查状态和键匹配
        if ((old_meta & kStateMask) == kStateVisible &&
            table_.KeyMatch(h, key)) {
            // 命中：更新时钟计数（最多到3）
            uint64_t countdown = (old_meta >> kCountdownShift) & kMaxCountdown;
            if (countdown < kMaxCountdown) {
                // 时钟计数未达到最大值，可以增加
                // （acquire操作已经增加了计数）
            }
            return reinterpret_cast<Cache::Handle*>(h);
        } else {
            // 未命中：回退acquire计数
            h->meta.fetch_sub(kAcquireIncrement, std::memory_order_release);
            return nullptr;
        }
    }
    
    // 插入操作
    Status Insert(const Slice& key, uint32_t hash, Cache::ObjectPtr value,
                 const Cache::CacheItemHelper* helper, size_t charge,
                 Cache::Handle** handle, Cache::Priority priority) {
        
        // 查找空闲槽或执行淘汰
        size_t slot = FindSlotForInsert(key, hash, charge);
        if (slot == kNoSlot) {
            return Status::MemoryLimit("Cache full");
        }
        
        typename Table::HandleImpl* h = table_.HandlePtr(slot);
        
        // 原子地切换到构造状态
        uint64_t old_meta = h->meta.exchange(kStateConstruction,
                                           std::memory_order_acquire);
        
        // 设置缓存项数据
        table_.SetKey(h, key);
        h->value = value;
        h->helper = helper;
        h->total_charge = charge;
        
        // 根据优先级设置初始时钟计数
        uint64_t initial_countdown;
        switch (priority) {
            case Cache::Priority::HIGH:
                initial_countdown = kMaxCountdown;
                break;
            case Cache::Priority::LOW:
                initial_countdown = 1;
                break;
            default:
                initial_countdown = kMaxCountdown / 2;
                break;
        }
        
        // 设置为可见状态
        uint64_t new_meta = kStateVisible | (initial_countdown << kCountdownShift);
        if (handle != nullptr) {
            // 返回句柄：增加引用计数
            new_meta += kAcquireIncrement;
            *handle = reinterpret_cast<Cache::Handle*>(h);
        }
        
        h->meta.store(new_meta, std::memory_order_release);
        
        // 更新使用量统计
        usage_.fetch_add(charge, std::memory_order_relaxed);
        
        return Status::OK();
    }
    
    // 释放操作（无锁）
    bool Release(Cache::Handle* handle, bool useful) {
        typename Table::HandleImpl* h =
            reinterpret_cast<typename Table::HandleImpl*>(handle);
            
        if (useful) {
            // 有用的释放：增加release计数
            h->meta.fetch_add(kReleaseIncrement, std::memory_order_release);
        } else {
            // 无用的释放：减少acquire计数（降低时钟计数）
            uint64_t old_meta = h->meta.fetch_sub(kAcquireIncrement,
                                                 std::memory_order_release);
            
            // 检查是否需要处理溢出
            if (UNLIKELY((old_meta >> kAcquireShift) == 0)) {
                // acquire计数下溢，需要特殊处理
                HandleAcquireUnderflow(h);
            }
        }
        
        return false;  // HyperClock不支持立即删除
    }
    
private:
    // 查找插入槽位（包含淘汰逻辑）
    size_t FindSlotForInsert(const Slice& key, uint32_t hash, size_t charge) {
        size_t start_slot = table_.GetSlot(key, hash);
        size_t slot = start_slot;
        
        // 线性探测查找空闲槽
        do {
            typename Table::HandleImpl* h = table_.HandlePtr(slot);
            uint64_t meta = h->meta.load(std::memory_order_acquire);
            
            if ((meta & kStateMask) == kStateEmpty) {
                // 找到空闲槽
                if (h->meta.compare_exchange_weak(meta, kStateConstruction,
                                                 std::memory_order_acquire)) {
                    return slot;
                }
                // CAS失败，继续查找
            }
            
            slot = table_.NextSlot(slot);
        } while (slot != start_slot);
        
        // 没有空闲槽，执行时钟淘汰
        return ClockEvict(charge);
    }
    
    // 时钟淘汰算法
    size_t ClockEvict(size_t needed_charge) {
        size_t start_clock = clock_pointer_.load(std::memory_order_relaxed);
        size_t clock_pos = start_clock;
        
        for (int effort = 0; effort < kMaxEvictionEffort; ++effort) {
            typename Table::HandleImpl* h = table_.HandlePtr(clock_pos);
            uint64_t meta = h->meta.load(std::memory_order_acquire);
            
            uint64_t state = meta & kStateMask;
            if (state == kStateVisible) {
                uint64_t acquire_count = (meta >> kAcquireShift) & kAcquireMask;
                uint64_t release_count = (meta >> kReleaseShift) & kReleaseMask;
                
                if (acquire_count == release_count) {
                    // 未被引用的项
                    uint64_t countdown = (meta >> kCountdownShift) & kMaxCountdown;
                    
                    if (countdown > 0) {
                        // 减少时钟计数
                        uint64_t new_meta = meta - (1ULL << kCountdownShift);
                        if (h->meta.compare_exchange_weak(meta, new_meta,
                                                         std::memory_order_release)) {
                            // 成功减少计数，继续查找
                        }
                    } else {
                        // 时钟计数为0，可以淘汰
                        if (h->meta.compare_exchange_weak(meta, kStateConstruction,
                                                         std::memory_order_acquire)) {
                            // 成功淘汰
                            FreeEntry(h);
                            clock_pointer_.store(table_.NextSlot(clock_pos),
                                               std::memory_order_relaxed);
                            return clock_pos;
                        }
                    }
                }
            }
            
            clock_pos = table_.NextSlot(clock_pos);
            if (clock_pos == start_clock) {
                // 完整遍历一轮
                break;
            }
        }
        
        // 淘汰失败
        return kNoSlot;
    }
};

// 二级缓存适配器
class SecondaryCache {
public:
    virtual ~SecondaryCache() = default;
    
    // 查找接口（异步）
    virtual std::unique_ptr<SecondaryCacheResultHandle> Lookup(
        const Slice& key, const Cache::CacheItemHelper* helper,
        Cache::CreateContext* create_context, bool wait, bool advise_erase,
        Statistics* stats, bool& kept_in_sec_cache) = 0;
    
    // 插入接口
    virtual Status Insert(const Slice& key, Cache::ObjectPtr obj,
                         const Cache::CacheItemHelper* helper,
                         bool force_insert) = 0;
    
    // 擦除接口
    virtual void Erase(const Slice& key) = 0;
    
    // 等待异步操作完成
    virtual void WaitAll(std::vector<SecondaryCacheResultHandle*> handles) = 0;
    
    // 获取缓存名称
    virtual const char* Name() const = 0;
};

// 压缩二级缓存实现
class CompressedSecondaryCache : public SecondaryCache {
private:
    struct CacheValue {
        CompressionType compression_type;    // 压缩类型
        uint32_t uncompressed_size;         // 未压缩大小
        uint32_t compressed_size;           // 压缩大小
        char data[1];                       // 压缩数据
    };
    
    std::shared_ptr<Cache> cache_;          // 底层缓存
    CompressionType compression_type_;      // 压缩算法
    uint32_t compress_format_version_;      // 压缩格式版本
    
public:
    std::unique_ptr<SecondaryCacheResultHandle> Lookup(
        const Slice& key, const Cache::CacheItemHelper* helper,
        Cache::CreateContext* create_context, bool wait, bool advise_erase,
        Statistics* stats, bool& kept_in_sec_cache) override {
        
        // 从底层缓存查找压缩数据
        Cache::Handle* handle = cache_->Lookup(key);
        if (handle == nullptr) {
            return nullptr;
        }
        
        // 获取压缩数据
        CacheValue* cache_value =
            reinterpret_cast<CacheValue*>(cache_->Value(handle));
        
        // 创建异步解压缩任务
        return std::make_unique<CompressedSecondaryCacheResultHandle>(
            cache_.get(), handle, cache_value, helper, create_context);
    }
    
    Status Insert(const Slice& key, Cache::ObjectPtr obj,
                 const Cache::CacheItemHelper* helper,
                 bool force_insert) override {
        
        // 序列化对象
        size_t size = (*helper->size_cb)(obj);
        std::string serialized;
        serialized.resize(size);
        Status s = (*helper->saveto_cb)(obj, 0, size, serialized.data());
        if (!s.ok()) {
            return s;
        }
        
        // 压缩数据
        std::string compressed;
        CompressionInfo compression_info(
            CompressionOptions(), create_context,
            CompressionDict::GetEmptyDict(), compression_type_,
            compress_format_version_);
        
        bool compression_success = CompressData(
            serialized, compression_info, compress_format_version_, &compressed);
        
        if (!compression_success || compressed.size() >= serialized.size()) {
            // 压缩失败或压缩效果不好，存储原始数据
            compressed = std::move(serialized);
            compression_type = kNoCompression;
        }
        
        // 创建缓存值
        size_t cache_value_size = sizeof(CacheValue) - 1 + compressed.size();
        CacheValue* cache_value =
            reinterpret_cast<CacheValue*>(malloc(cache_value_size));
        
        cache_value->compression_type = compression_type;
        cache_value->uncompressed_size = static_cast<uint32_t>(serialized.size());
        cache_value->compressed_size = static_cast<uint32_t>(compressed.size());
        memcpy(cache_value->data, compressed.data(), compressed.size());
        
        // 插入到底层缓存
        Cache::Handle* handle = nullptr;
        s = cache_->Insert(key, cache_value, cache_value_size,
                          &compressed_secondary_cache_helper, &handle);
        
        if (handle != nullptr) {
            cache_->Release(handle);
        }
        
        return s;
    }
};

// LRU缓存配置
struct LRUCacheOptions {
    size_t capacity = 0;                    // 缓存容量（字节）
    int num_shard_bits = -1;               // 分片位数（-1表示自动）
    bool strict_capacity_limit = false;     // 严格容量限制
    double high_pri_pool_ratio = 0.5;      // 高优先级池比例
    double low_pri_pool_ratio = 0.0;       // 低优先级池比例
    bool use_adaptive_mutex = kDefaultToAdaptiveMutex; // 自适应互斥锁
    CacheMetadataChargePolicy metadata_charge_policy =
        kDontChargeCacheMetadata;           // 元数据计费策略
    std::shared_ptr<MemoryAllocator> memory_allocator; // 内存分配器
    bool use_secondary_cache_insertion_policy = true; // 二级缓存插入策略
};

// HyperClock缓存配置
struct HyperClockCacheOptions {
    size_t capacity = 0;                    // 缓存容量
    size_t estimated_entry_charge = 0;      // 估计条目开销（0表示自动）
    int num_shard_bits = -1;               // 分片位数
    bool strict_capacity_limit = false;     // 严格容量限制
    CacheMetadataChargePolicy metadata_charge_policy =
        kDontChargeCacheMetadata;           // 元数据计费策略
    std::shared_ptr<MemoryAllocator> memory_allocator; // 内存分配器
    uint32_t hash_seed = 0;                // 哈希种子
    
    // HyperClock特有选项
    int eviction_effort_cap = 255;         // 淘汰努力上限
    
    std::shared_ptr<Cache> MakeSharedCache() const;
};

// 缓存性能优化配置
class CachePerformanceTuner {
public:
    // 根据工作负载特征选择缓存类型
    static std::shared_ptr<Cache> SelectOptimalCache(
        size_t capacity, const WorkloadCharacteristics& workload) {
        
        if (workload.high_concurrency && workload.read_heavy) {
            // 高并发读密集：选择HyperClock缓存
            HyperClockCacheOptions opts(capacity);
            opts.num_shard_bits = GetOptimalShardBits(capacity, workload.thread_count);
            opts.estimated_entry_charge = workload.avg_entry_size;
            return opts.MakeSharedCache();
        } else if (workload.priority_sensitive) {
            // 优先级敏感：选择LRU缓存
            LRUCacheOptions opts(capacity);
            opts.high_pri_pool_ratio = 0.8;  // 大部分空间给高优先级
            opts.low_pri_pool_ratio = 0.1;   // 少量空间给低优先级
            opts.num_shard_bits = GetOptimalShardBits(capacity, workload.thread_count);
            return NewLRUCache(opts);
        } else {
            // 默认选择：平衡的LRU缓存
            LRUCacheOptions opts(capacity);
            opts.high_pri_pool_ratio = 0.5;
            return NewLRUCache(opts);
        }
    }
    
    // 计算最优分片数
    static int GetOptimalShardBits(size_t capacity, int thread_count) {
        // 基于容量和线程数的启发式算法
        int shard_bits = 0;
        size_t min_shard_size = 32 << 20;  // 32MB最小分片大小
        
        while ((capacity >> shard_bits) > min_shard_size &&
               (1 << shard_bits) < thread_count) {
            shard_bits++;
        }
        
        return std::min(shard_bits, 6);  // 最多64个分片
    }
    
    // 配置二级缓存
    static void ConfigureSecondaryCache(LRUCacheOptions& opts,
                                       size_t secondary_capacity) {
        if (secondary_capacity > 0) {
            // 创建压缩二级缓存
            CompressedSecondaryCacheOptions sec_opts;
            sec_opts.capacity = secondary_capacity;
            sec_opts.compression_type = kLZ4Compression;  // 快速压缩
            sec_opts.compress_format_version = 2;
            
            opts.secondary_cache = NewCompressedSecondaryCache(sec_opts);
        }
    }
    
    // 运行时性能监控
    static void MonitorCachePerformance(std::shared_ptr<Cache> cache,
                                       Statistics* stats) {
        // 关键指标监控
        uint64_t hit_count = stats->getTickerCount(BLOCK_CACHE_HIT);
        uint64_t miss_count = stats->getTickerCount(BLOCK_CACHE_MISS);
        double hit_rate = static_cast<double>(hit_count) / (hit_count + miss_count);
        
        uint64_t usage = cache->GetUsage();
        uint64_t capacity = cache->GetCapacity();
        double usage_ratio = static_cast<double>(usage) / capacity;
        
        // 性能告警
        if (hit_rate < 0.8) {
            LOG_WARN("Low cache hit rate: %.2f%%", hit_rate * 100);
        }
        
        if (usage_ratio > 0.95) {
            LOG_WARN("Cache usage high: %.2f%%", usage_ratio * 100);
        }
        
        // 自动调优建议
        if (hit_rate < 0.7 && usage_ratio > 0.9) {
            LOG_INFO("Consider increasing cache capacity");
        }
    }
};

std::shared_ptr<Cache> NewLRUCache(
    size_t capacity,
    int num_shard_bits = -1,
    bool strict_capacity_limit = false,
    double high_pri_pool_ratio = 0.5,
    std::shared_ptr<MemoryAllocator> memory_allocator = nullptr,
    bool use_adaptive_mutex = kDefaultToAdaptiveMutex,
    CacheMetadataChargePolicy metadata_charge_policy = kDefaultCacheMetadataChargePolicy,
    double low_pri_pool_ratio = 0.0
);

// cache/lru_cache.cc
std::shared_ptr<Cache> NewLRUCache(
    size_t capacity, int num_shard_bits, bool strict_capacity_limit,
    double high_pri_pool_ratio, std::shared_ptr<MemoryAllocator> allocator,
    bool use_adaptive_mutex, CacheMetadataChargePolicy metadata_charge_policy,
    double low_pri_pool_ratio) {
  
  // 验证参数合法性
  if (num_shard_bits < 0) {
    num_shard_bits = GetDefaultCacheShardBits(capacity);
  }
  if (num_shard_bits >= 20) {
    return nullptr;  // 分片数过多
  }
  if (high_pri_pool_ratio < 0.0 || high_pri_pool_ratio > 1.0) {
    return nullptr;
  }
  if (low_pri_pool_ratio < 0.0 || low_pri_pool_ratio > 1.0) {
    return nullptr;
  }
  if (high_pri_pool_ratio + low_pri_pool_ratio > 1.0) {
    return nullptr;
  }

  // 创建LRUCache实例
  return std::make_shared<LRUCache>(
      capacity, num_shard_bits, strict_capacity_limit, high_pri_pool_ratio,
      allocator, use_adaptive_mutex, metadata_charge_policy, low_pri_pool_ratio);
}

// db/db_impl/db_impl_open.cc - 数据库打开时初始化缓存
Status DBImpl::Open(const DBOptions& db_options,
                    const std::string& dbname,
                    const std::vector<ColumnFamilyDescriptor>& column_families,
                    std::vector<ColumnFamilyHandle*>* handles,
                    DB** dbptr) {
  // 如果用户未指定block_cache，创建默认缓存
  if (db_options.table_cache_numshardbits == -1 &&
      !db_options.block_cache) {
    size_t cache_size = 8 * 1024 * 1024;  // 默认8MB
    db_options.block_cache = NewLRUCache(cache_size);
  }
  
  // 将缓存传递给TableCache
  table_cache_ = new TableCache(immutable_db_options_,
                                 db_options.block_cache);
  return Status::OK();
}

sequenceDiagram
    participant Client as 客户端
    participant Factory as NewLRUCache工厂
    participant LRUCache as LRUCache对象
    participant Shards as LRUCacheShard数组
    participant Memory as MemoryAllocator

    Client->>Factory: NewLRUCache(capacity, options)
    activate Factory
    
    Factory->>Factory: 验证参数(num_shard_bits, ratios)
    Factory->>Factory: GetDefaultCacheShardBits(capacity)
    
    Factory->>LRUCache: new LRUCache(validated_params)
    activate LRUCache
    
    LRUCache->>LRUCache: 计算每个分片的容量
    
    loop 对每个分片
        LRUCache->>Shards: new LRUCacheShard(shard_capacity)
        activate Shards
        Shards->>Memory: Allocate(LRU_list + HashTable)
        Memory-->>Shards: 返回内存地址
        Shards-->>LRUCache: 分片初始化完成
        deactivate Shards
    end
    
    LRUCache-->>Factory: 返回LRUCache实例
    deactivate LRUCache
    
    Factory-->>Client: 返回shared_ptr<Cache>
    deactivate Factory

std::shared_ptr<Cache> HyperClockCacheOptions::MakeSharedCache() const;

// 配置结构体
struct HyperClockCacheOptions : public ShardedCacheOptions {
  size_t estimated_entry_charge = 0;
  bool use_secondary_cache_adapter_for_nvm_tier = true;
};

// cache/clock_cache.cc
std::shared_ptr<Cache> HyperClockCacheOptions::MakeSharedCache() const {
  // HyperClockCache要求固定大小的key（16字节）
  if (capacity == 0) {
    return nullptr;
  }

  // 计算分片数
  int actual_shard_bits = num_shard_bits;
  if (actual_shard_bits < 0) {
    actual_shard_bits = GetDefaultCacheShardBits(capacity);
  }

  // 计算每个分片的容量
  size_t per_shard_capacity = capacity >> actual_shard_bits;
  
  // 估算每个分片的槽位数
  size_t estimated_slots;
  if (estimated_entry_charge > 0) {
    estimated_slots = (per_shard_capacity + estimated_entry_charge - 1) /
                      estimated_entry_charge;
  } else {
    estimated_slots = per_shard_capacity / 256;  // 假设平均256字节
  }

  // 创建HyperClockCache实例
  return std::make_shared<HyperClockCache>(
      capacity, estimated_slots, actual_shard_bits,
      strict_capacity_limit, memory_allocator, secondary_cache);
}

// options/options_helper.cc - 从配置字符串创建缓存
Status GetCacheFromString(const ConfigOptions& config_options,
                          const std::string& value,
                          std::shared_ptr<Cache>* cache) {
  if (value.find("hyper_clock_cache") != std::string::npos) {
    HyperClockCacheOptions hc_options;
    ParseOptionsFromString(value, &hc_options);
    *cache = hc_options.MakeSharedCache();
    return Status::OK();
  }
  // ...其他缓存类型
}

sequenceDiagram
    participant Client as 客户端
    participant Options as HyperClockCacheOptions
    participant Factory as MakeSharedCache
    participant HCCache as HyperClockCache
    participant Shards as ClockCacheShard数组
    participant SlotArray as CLOCK槽位数组

    Client->>Options: 设置capacity, estimated_entry_charge
    Client->>Factory: options.MakeSharedCache()
    activate Factory
    
    Factory->>Factory: 计算actual_shard_bits
    Factory->>Factory: 计算per_shard_capacity
    Factory->>Factory: 估算每个分片的槽位数
    
    Factory->>HCCache: new HyperClockCache(params)
    activate HCCache
    
    loop 对每个分片
        HCCache->>Shards: new ClockCacheShard(estimated_slots)
        activate Shards
        Shards->>SlotArray: 分配固定大小的槽位数组
        SlotArray-->>Shards: 返回槽位数组
        Shards->>Shards: 初始化CLOCK指针为0
        Shards->>Shards: 初始化原子计数器
        Shards-->>HCCache: 分片初始化完成
        deactivate Shards
    end
    
    HCCache-->>Factory: 返回HyperClockCache实例
    deactivate HCCache
    
    Factory-->>Client: 返回shared_ptr<Cache>
    deactivate Factory

Status Cache::Insert(
    const Slice& key,
    ObjectPtr value,
    const CacheItemHelper* helper,
    size_t charge,
    Handle** handle = nullptr,
    Priority priority = Priority::LOW,
    const Slice& compressed_value = Slice(),
    CompressionType type = CompressionType::kNoCompression
);

// cache/lru_cache.cc - LRUCacheShard::Insert
Status LRUCacheShard::Insert(const Slice& key, uint32_t hash,
                              ObjectPtr value, size_t charge,
                              Cache::DeleterFn deleter,
                              Cache::Handle** handle,
                              Cache::Priority priority) {
  // 创建新的LRU句柄
  LRUHandle* e = reinterpret_cast<LRUHandle*>(
      new char[sizeof(LRUHandle) - 1 + key.size()]);
  e->value = value;
  e->deleter = deleter;
  e->charge = charge;
  e->key_length = key.size();
  e->hash = hash;
  e->refs = 0;  // 引用计数
  e->next = e->prev = nullptr;
  e->SetInCache(true);
  e->SetPriority(priority);
  memcpy(e->key_data, key.data(), key.size());

  // 持有互斥锁进行插入
  autovector<LRUHandle*> last_reference_list;
  {
    DMutexLock l(&mutex_);
    
    // 如果缓存已满，进行淘汰
    while (usage_ + charge > capacity_ && lru_.next != &lru_) {
      LRUHandle* old = lru_.next;
      LRU_Remove(old);
      table_.Remove(old->key(), old->hash);
      old->SetInCache(false);
      usage_ -= old->charge;
      last_reference_list.push_back(old);
    }

    // 检查是否有足够空间
    if (strict_capacity_limit_ && usage_ + charge > capacity_) {
      e->SetInCache(false);
      delete[] reinterpret_cast<char*>(e);
      return Status::Incomplete("Cache capacity insufficient");
    }

    // 插入到哈希表和LRU链表
    LRUHandle* old = table_.Insert(e);
    usage_ += charge;
    if (old != nullptr) {
      // 已存在同key条目，移除旧条目
      LRU_Remove(old);
      old->SetInCache(false);
      usage_ -= old->charge;
      last_reference_list.push_back(old);
    }

    // 插入到LRU链表的适当位置
    if (priority == Cache::Priority::HIGH) {
      LRU_Insert(&lru_high_pri_, e);
    } else if (priority == Cache::Priority::LOW) {
      LRU_Insert(&lru_low_pri_, e);
    } else {
      LRU_Insert(&lru_, e);
    }

    // 如果调用方需要句柄，增加引用计数
    if (handle != nullptr) {
      e->refs++;
      *handle = reinterpret_cast<Cache::Handle*>(e);
    }
  }

  // 在锁外删除淘汰的条目（避免死锁）
  for (auto entry : last_reference_list) {
    entry->Free();
  }

  return Status::OK();
}

// table/block_based/block_based_table_reader.cc
Status BlockBasedTable::GetDataBlockFromCache(
    const ReadOptions& ro, const BlockHandle& handle,
    CachableEntry<Block>* block) {
  
  // 构造cache key
  char cache_key_buf[kMaxCacheKeyPrefixSize + kMaxVarint64Length];
  Slice cache_key = GetCacheKey(cache_key_buf, handle);

  // 尝试查找
  Cache::Handle* cache_handle = block_cache_->Lookup(cache_key);
  if (cache_handle == nullptr) {
    // 未命中，从SST文件读取
    BlockContents contents;
    Status s = ReadBlockFromFile(handle, &contents);
    
    // 解析Block
    Block* block = new Block(std::move(contents));
    
    // 插入缓存
    size_t charge = block->ApproximateMemoryUsage();
    Cache::Priority priority = Cache::Priority::LOW;
    s = block_cache_->Insert(cache_key, block, charge,
                              &DeleteCachedEntry<Block>,
                              &cache_handle, priority);
  }
  
  return Status::OK();
}

sequenceDiagram
    participant Client as BlockBasedTable
    participant Cache as Cache接口
    participant Shard as LRUCacheShard
    participant HashTable as HashTable
    participant LRUList as LRU链表
    participant Evictor as 淘汰器

    Client->>Cache: Insert(key, value, charge)
    activate Cache
    Cache->>Cache: 根据key hash计算分片ID
    Cache->>Shard: GetShard(shard_id)->Insert(...)
    activate Shard
    
    Shard->>Shard: 创建LRUHandle对象
    Shard->>Shard: mutex_.Lock()
    
    alt 缓存已满 (usage + charge > capacity)
        Shard->>Evictor: 启动淘汰
        activate Evictor
        loop 直到有足够空间
            Evictor->>LRUList: 从LRU尾部取出条目
            LRUList-->>Evictor: 返回victim条目
            Evictor->>HashTable: Remove(victim->key)
            Evictor->>Evictor: usage -= victim->charge
            Evictor->>Evictor: 加入last_reference_list
        end
        deactivate Evictor
    end
    
    alt strict_capacity_limit && 空间不足
        Shard->>Shard: mutex_.Unlock()
        Shard->>Client: 返回Status::Incomplete
    else 有足够空间
        Shard->>HashTable: Insert(new_handle)
        HashTable-->>Shard: 返回旧条目（如果存在）
        
        Shard->>LRUList: 根据priority插入到对应队列头部
        Shard->>Shard: usage += charge
        
        alt 调用方需要handle
            Shard->>Shard: new_handle->refs++
        end
        
        Shard->>Shard: mutex_.Unlock()
        
        Shard->>Shard: 在锁外释放淘汰的条目
        
        Shard-->>Cache: 返回Status::OK
    end
    
    deactivate Shard
    Cache-->>Client: 返回Status和handle
    deactivate Cache

Cache::Handle* Cache::Lookup(
    const Slice& key,
    const CacheItemHelper* helper = nullptr,
    CreateContext* create_context = nullptr,
    Priority priority = Priority::LOW,
    Statistics* stats = nullptr
);

// cache/lru_cache.cc - LRUCacheShard::Lookup
Cache::Handle* LRUCacheShard::Lookup(const Slice& key, uint32_t hash) {
  LRUHandle* e = nullptr;
  {
    DMutexLock l(&mutex_);
    e = table_.Lookup(key, hash);
    if (e != nullptr) {
      assert(e->InCache());
      // 增加引用计数
      e->refs++;
      // 更新LRU位置（移到队列头部）
      LRU_Remove(e);
      if (e->GetPriority() == Cache::Priority::HIGH) {
        LRU_Insert(&lru_high_pri_, e);
      } else if (e->GetPriority() == Cache::Priority::LOW) {
        LRU_Insert(&lru_low_pri_, e);
      } else {
        LRU_Insert(&lru_, e);
      }
    }
  }
  
  // 更新统计信息
  if (e != nullptr) {
    RecordTick(statistics_, BLOCK_CACHE_HIT);
  } else {
    RecordTick(statistics_, BLOCK_CACHE_MISS);
  }
  
  return reinterpret_cast<Cache::Handle*>(e);
}

// table/block_based/block_based_table_reader.cc
Status BlockBasedTable::GetDataBlockFromCache(
    const ReadOptions& ro, const BlockHandle& handle,
    CachableEntry<Block>* block) {
  
  // 构造cache key
  char cache_key_buf[kMaxCacheKeyPrefixSize + kMaxVarint64Length];
  Slice cache_key = GetCacheKey(cache_key_buf, handle);

  // 查找缓存
  Cache::Handle* cache_handle = block_cache_->Lookup(cache_key, statistics_);
  
  if (cache_handle != nullptr) {
    // 命中：从句柄获取Block指针
    Block* cached_block = reinterpret_cast<Block*>(
        block_cache_->Value(cache_handle));
    block->SetCachedValue(cached_block, block_cache_, cache_handle);
    return Status::OK();
  } else {
    // 未命中：从文件读取
    BlockContents contents;
    Status s = ReadBlockFromFile(handle, &contents);
    // ... 插入缓存 ...
    return s;
  }
}

sequenceDiagram
    participant Client as BlockBasedTable
    participant Cache as Cache接口
    participant Shard as LRUCacheShard
    participant HashTable as HashTable
    participant LRUList as LRU链表
    participant Stats as Statistics

    Client->>Cache: Lookup(key, stats)
    activate Cache
    Cache->>Cache: 计算key hash和分片ID
    Cache->>Shard: GetShard(shard_id)->Lookup(key, hash)
    activate Shard
    
    Shard->>Shard: mutex_.Lock()
    Shard->>HashTable: Lookup(key, hash)
    activate HashTable
    HashTable->>HashTable: 根据hash找到bucket
    HashTable->>HashTable: 遍历链表查找key
    
    alt 找到条目
        HashTable-->>Shard: 返回LRUHandle*
        deactivate HashTable
        
        Shard->>Shard: e->refs++ (增加引用计数)
        Shard->>LRUList: LRU_Remove(e) (从当前位置移除)
        Shard->>LRUList: LRU_Insert(head, e) (插入到队列头部)
        Shard->>Stats: RecordTick(BLOCK_CACHE_HIT)
        
        Shard->>Shard: mutex_.Unlock()
        Shard-->>Cache: 返回Handle*
        Cache-->>Client: 返回Handle*
        
        Note over Client: 使用Value(handle)获取数据
        Note over Client: 使用完后必须调用Release(handle)
        
    else 未找到
        HashTable-->>Shard: 返回nullptr
        deactivate HashTable
        
        Shard->>Stats: RecordTick(BLOCK_CACHE_MISS)
        Shard->>Shard: mutex_.Unlock()
        Shard-->>Cache: 返回nullptr
        Cache-->>Client: 返回nullptr
        
        Note over Client: 从SST文件读取数据
        Note over Client: 调用Insert插入缓存
    end
    
    deactivate Shard
    deactivate Cache

bool Cache::Release(
    Handle* handle,
    bool useful = true,
    bool erase_if_last_ref = false
);

// cache/lru_cache.cc - LRUCacheShard::Release
bool LRUCacheShard::Release(Handle* handle, bool useful,
                            bool erase_if_last_ref) {
  if (handle == nullptr) {
    return false;
  }
  
  LRUHandle* e = reinterpret_cast<LRUHandle*>(handle);
  bool last_reference = false;
  bool erased = false;
  
  {
    DMutexLock l(&mutex_);
    // 减少引用计数
    e->refs--;
    assert(e->refs >= 0);
    
    // 如果useful=false，降低优先级
    if (!useful && e->GetPriority() == Cache::Priority::HIGH) {
      e->SetPriority(Cache::Priority::LOW);
      LRU_Remove(e);
      LRU_Insert(&lru_low_pri_, e);
    }
    
    // 检查是否是最后一个引用
    if (e->refs == 0) {
      last_reference = true;
      if (!e->InCache() || erase_if_last_ref) {
        // 条目已不在缓存中或需要立即删除
        usage_ -= e->charge;
        if (e->InCache()) {
          LRU_Remove(e);
          table_.Remove(e->key(), e->hash);
          e->SetInCache(false);
        }
        erased = true;
      }
    }
  }
  
  // 在锁外释放内存
  if (last_reference && erased) {
    e->Free();
  }
  
  return erased;
}

// table/block_based/block_based_table_reader.cc
// CachableEntry的RAII封装自动管理Release
template <typename T>
class CachableEntry {
 public:
  ~CachableEntry() {
    if (cache_handle_ != nullptr && cache_ != nullptr) {
      cache_->Release(cache_handle_);
    }
  }
  
  void SetCachedValue(T* value, Cache* cache, Cache::Handle* handle) {
    value_ = value;
    cache_ = cache;
    cache_handle_ = handle;
  }
  
 private:
  T* value_ = nullptr;
  Cache* cache_ = nullptr;
  Cache::Handle* cache_handle_ = nullptr;
};

// 使用示例
Status BlockBasedTable::Get(const ReadOptions& ro, const Slice& key,
                             GetContext* get_context) {
  CachableEntry<Block> block;
  // Lookup会设置cache_handle_
  Status s = GetDataBlockFromCache(ro, handle, &block);
  
  if (s.ok()) {
    // 使用block.GetValue()访问数据
    s = block.GetValue()->Get(key, get_context);
  }
  
  // 析构函数自动调用Release
  return s;
}