From f986604f852b86f5b002472f3605015b3b8b889d Mon Sep 17 00:00:00 2001 From: Thomas Korrison Date: Sun, 15 Feb 2026 15:36:09 +0000 Subject: [PATCH 1/2] Update policy documentation to reflect planned and implemented policies - Revised the list of upcoming cache policies in the README to include GDSF and TinyLFU/W-TinyLFU. - Added TinyLFU/W-TinyLFU to the implemented policy summaries in the roadmap documentation, ensuring clarity on current and future features. --- docs/policies/README.md | 4 +++ docs/policies/roadmap/README.md | 1 + docs/policies/roadmap/tinylfu.md | 45 ++++++++++++++++++++++++++++++++ 3 files changed, 50 insertions(+) create mode 100644 docs/policies/roadmap/tinylfu.md diff --git a/docs/policies/README.md b/docs/policies/README.md index 5b0f183..4bb3881 100644 --- a/docs/policies/README.md +++ b/docs/policies/README.md @@ -55,7 +55,11 @@ If you can only implement one “general purpose” policy for mixed workloads, ### Roadmap Policies (Planned) +<<<<<<< Updated upstream See [Policy roadmap](roadmap/README.md) for upcoming policies (ARC, CAR, LIRS, etc.). +======= +See [Policy roadmap](roadmap/README.md) for upcoming policies (LIRS, GDSF, TinyLFU/W-TinyLFU, etc.). +>>>>>>> Stashed changes ### Implemented Policy Summaries (Short) diff --git a/docs/policies/roadmap/README.md b/docs/policies/roadmap/README.md index 2d5fa09..414c918 100644 --- a/docs/policies/roadmap/README.md +++ b/docs/policies/roadmap/README.md @@ -14,4 +14,5 @@ If a policy moves into production code, its document should be moved back to - [LFU Aging](lfu-aging.md) - [LIRS](lirs.md) - [OPT](opt.md) +- [TinyLFU / W-TinyLFU](tinylfu.md) - [TTL](ttl.md) diff --git a/docs/policies/roadmap/tinylfu.md b/docs/policies/roadmap/tinylfu.md new file mode 100644 index 0000000..972c627 --- /dev/null +++ b/docs/policies/roadmap/tinylfu.md @@ -0,0 +1,45 @@ +# TinyLFU / W-TinyLFU (Admission + Eviction Design) + +## Goal +Improve hit rate under skewed and one-hit-wonder workloads by using +frequency-based admission instead of admitting every miss. + +## Core Idea +TinyLFU is primarily an **admission policy**: +- Keep an approximate recent frequency sketch (usually Count-Min Sketch). +- On a miss, compare candidate frequency against a sampled victim. +- Admit only if the candidate appears "hotter" than the victim. + +W-TinyLFU combines: +- **Window cache** (small recency-focused region, typically LRU) +- **Main cache** (segmented/protected region) +- **TinyLFU admission gate** between window and main + +This keeps recent bursts responsive while avoiding long-tail pollution. + +## Core Data Structures (Typical) +- Hash index `K -> Entry` +- Window segment (e.g., LRU list or ring) +- Main segment (e.g., SLRU-style probation/protected) +- Frequency sketch (Count-Min Sketch) +- Optional reset/aging counter for sketch decay + +## Complexity & Overhead +- Access/update in sketch: O(1) with small constant factors +- Admission decision: O(1) +- Extra memory for sketch and segmented metadata +- Approximate counts can produce false positives, but usually good tradeoff + +## Notes For CacheKit +- Fits best as **policy composition**: storage + segmented eviction + admission. +- Keep hot-path updates allocation-free (pre-sized sketch, fixed segments). +- Make admission optional/configurable for apples-to-apples benchmarks. +- Benchmark against `S3-FIFO`, `ARC/CAR`, and `Heap-LFU` on: + - Zipfian + - scan + point lookup mixes + - shifting hotspots + +## References +- Einziger et al. (2017): "TinyLFU: A Highly Efficient Cache Admission Policy". +- Caffeine design notes (W-TinyLFU implementation details). +- Wikipedia: https://en.wikipedia.org/wiki/Cache_replacement_policies From a253cd9f247221b99f5717b1ab7da7dfee9e98df Mon Sep 17 00:00:00 2001 From: Thomas Korrison Date: Sun, 15 Feb 2026 15:37:57 +0000 Subject: [PATCH 2/2] Update policy documentation to correct upcoming policies list - Removed outdated references to ARC and CAR from the planned policies section in the README. - Ensured the list accurately reflects the current focus on LIRS, GDSF, and TinyLFU/W-TinyLFU. --- docs/policies/README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/policies/README.md b/docs/policies/README.md index 4bb3881..6079395 100644 --- a/docs/policies/README.md +++ b/docs/policies/README.md @@ -55,11 +55,7 @@ If you can only implement one “general purpose” policy for mixed workloads, ### Roadmap Policies (Planned) -<<<<<<< Updated upstream -See [Policy roadmap](roadmap/README.md) for upcoming policies (ARC, CAR, LIRS, etc.). -======= See [Policy roadmap](roadmap/README.md) for upcoming policies (LIRS, GDSF, TinyLFU/W-TinyLFU, etc.). ->>>>>>> Stashed changes ### Implemented Policy Summaries (Short)