arc-cache-project

一个用于探索与实现 ARC（Adaptive Replacement Cache，自适应替换缓存）思想的模块化缓存项目，当前实现包含：

• LRUList（T1）
• LFUList（T2）
• GhostLRU（B1）
• GhostLFU（B2）
• 线程安全 ARCCache

项目结构

arc-cache-project/
├─ src/
│  ├─ core/
│  │  └─ arc_cache.hpp
│  ├─ policies/
│  │  ├─ lru_list.hpp
│  │  └─ lfu_list.hpp
│  └─ ghost/
│     └─ ghost_lists.hpp
├─ tests/
│  ├─ unit_components_test.cpp
│  ├─ integration_arc_test.cpp
│  ├─ concurrency_stress_test.cpp
│  └─ visual_benchmark.py
├─ docs/
│  ├─ architecture.md
│  ├─ api.md
│  ├─ algorithm-flow.md
│  └─ performance-optimizations.md
├─ examples/
│  └─ arc_demo.cpp
├─ CMakeLists.txt
├─ run_visual_quick.bat
└─ README.md

架构图

flowchart LR
    C[Client] --> ARC[ARCCache]

    ARC --> T1[T1: LRUList]
    ARC --> T2[T2: LFUList]
    ARC --> B1[B1: GhostLRU]
    ARC --> B2[B2: GhostLFU]

    B1 --> P[Adjust p]
    B2 --> P

Loading

快速开始

1) 构建

cmake -S . -B build
cmake --build build

2) 运行示例

./build/example_arc_demo

Windows + MSVC 下可执行文件通常为 build\\Debug\\example_arc_demo.exe。

3) 运行测试

./build/test_unit_components
./build/test_integration_arc
./build/test_concurrency_stress

并发压测（可配置）

test_concurrency_stress 支持命令行参数：

• --capacity=<N>：缓存容量（默认 256）
• --key-space=<N>：key 空间大小（默认 4096）
• --threads=<N>：线程数（默认 8）
• --ops=<N>：每线程操作数（默认 60000）
• --read-ratio=<0~100>：读取占比（默认 70）
• --batch-size=<N>：批量大小（默认 1）

示例：

./build/test_concurrency_stress --threads=16 --ops=120000 --read-ratio=80 --batch-size=32

可视化测试（先做这个）

一键双击运行（无需终端输入）：

• run_visual_quick.bat

一键预设：

python tests/visual_benchmark.py --build-dir build --preset quick
python tests/visual_benchmark.py --build-dir build --preset full

自定义参数：

python tests/visual_benchmark.py --build-dir build --threads 8 --ops 60000 --read-ratio 70 --batch-sizes 1,2,4,8,16,32,64

默认输出目录：tests/benchmark_out/

• benchmark_results.csv
• throughput.svg
• hit_rate.svg
• benchmark_report.md

最近一次 Bug 迭代

• 修复 tests/integration_arc_test.cpp 中 assert(...) 与模板类型 ARCCache<int, int> 组合时的宏参数解析问题。
• 具体做法：对相关断言表达式使用双括号包裹，避免模板逗号被 assert 宏误判为多个参数。
• 修复 tests/visual_benchmark.py 对科学计数法吞吐输出的解析问题，例如 8.87e+06 ops/s。
• 优化 hit_rate.svg 的展示方式，改为局部坐标轴放大并提高标签精度，使小幅差异更易观察。

测试内容说明

单元测试（tests/unit_components_test.cpp）

• LRUList：add/remove/get/popVictim/淘汰顺序
• LFUList：频次提升、淘汰低频项、更新已有值
• GhostLRU/GhostLFU：仅 key 管理、容量限制、顺序更新

集成测试（tests/integration_arc_test.cpp）

• 自适应行为验证：
  • 构造 B1 命中，验证 p 增大
  • 构造 B2 命中，验证 p 减小
• 访问模式模拟：
  • 全随机访问
  • 热点访问（固定小热点）
  • 扫描式访问
• 校验：热点命中率高于全随机，扫描命中率低于热点

并发压力测试（tests/concurrency_stress_test.cpp）

• 多线程随机混合读写（Get/Put）
• 支持批量处理压测（batch-size）
• 输出吞吐（ops/s）与命中率
• 校验关键不变量：
  • size() <= capacity()
  • partition_p() <= capacity()

已实现优化（全部文档化）

• 批量接口：GetBatch/PutBatch
• 输出缓冲复用：GetBatch(..., out_buffer)
• 压测参数化：线程数、读写比、key 空间、批量大小
• 压测局部计数汇总：减少统计原子竞争
• 可视化基准：CSV + SVG + Markdown 自动报告
• 一键预设：quick/full

详情见：docs/performance-optimizations.md。

文档索引

• API 文档：docs/api.md
• 算法流程：docs/algorithm-flow.md
• 架构设计：docs/architecture.md
• 性能优化记录：docs/performance-optimizations.md