Add policy feature flags (#15)

* Add eviction policy feature flags for modular builds

- Introduced feature flags for various eviction policies in `Cargo.toml`, allowing users to enable only the necessary policies for smaller builds.
- Updated documentation to reflect the new feature flags and their descriptions, enhancing clarity on usage and configuration.
- Modified `bench-support/Cargo.toml` to utilize the `policy-all` feature for comprehensive benchmarking.
- Ensured that the new feature flags are integrated into the cache builder and prelude for seamless access to different policies.

* Update default feature flags in Cargo.toml for eviction policies

- Changed the default feature flags to include specific eviction policies: `policy-s3-fifo`, `policy_lru`, `policy-fast-lru`, `policy_lru_k`, and `policy-clock`.
- This update allows for more targeted usage of eviction strategies, enhancing modularity and performance based on expected workload patterns.

* Fix typo in default feature flags in Cargo.toml

- Corrected the naming convention of the `policy_lru` feature flag to `policy-lru` for consistency with other feature flags.
- This change enhances clarity and maintains uniformity in the feature flag naming scheme.

* Enhance documentation for eviction policy feature flags

- Updated README and various documentation files to clarify that each eviction policy is gated behind a feature flag, improving modularity for builds.
- Added feature flag details for each policy in the documentation, ensuring users can easily identify and enable the necessary policies for their use cases.
- Included examples for minimal builds and emphasized the benefits of targeted feature usage for performance optimization.

Author: TKorr

Cargo.toml

@@ -33,10 +33,49 @@ doc = true
 crate-type = ["lib"]
 
 [features]
-default = []
+default = ["policy-s3-fifo", "policy-lru", "policy-fast-lru", "policy-lru-k", "policy-clock"]
 metrics = []
 concurrency = ["parking_lot"]
 
+# Eviction policy feature flags. Enable only the policies you need for smaller builds.
+# Use `default-features = false` and select specific policies, or use `policy-all` for every policy.
+policy-all = [
+    "policy-fifo",
+    "policy-lru",
+    "policy-fast-lru",
+    "policy-lru-k",
+    "policy-lfu",
+    "policy-heap-lfu",
+    "policy-two-q",
+    "policy-s3-fifo",
+    "policy-arc",
+    "policy-lifo",
+    "policy-mfu",
+    "policy-mru",
+    "policy-random",
+    "policy-slru",
+    "policy-clock",
+    "policy-clock-pro",
+    "policy-nru",
+]
+policy-fifo = []
+policy-lru = []
+policy-fast-lru = []
+policy-lru-k = []
+policy-lfu = []
+policy-heap-lfu = []
+policy-two-q = []
+policy-s3-fifo = []
+policy-arc = []
+policy-lifo = []
+policy-mfu = []
+policy-mru = []
+policy-random = []
+policy-slru = []
+policy-clock = []
+policy-clock-pro = []
+policy-nru = []
+
 [dependencies]
 parking_lot = { version = "0.12", optional = true }
 rustc-hash = "2.1"

README.md

@@ -33,11 +33,44 @@ cachekit = { git = "https://github.com/OxidizeLabs/cachekit" }
 
 ## Feature Flags
 
+### General
+
 | Feature | Enables |
 |---------|---------|
 | `metrics` | Hit/miss metrics and snapshots |
 | `concurrency` | Concurrent wrappers (requires `parking_lot`) |
 
+### Per-Policy (Eviction Policies)
+
+Each eviction policy is gated behind a feature flag. Use `default-features = false` and enable only the policies you need for smaller builds.
+
+| Feature | Policy | Description |
+|---------|--------|-------------|
+| `policy-fifo` | FIFO | First In, First Out |
+| `policy-lru` | LRU | Least Recently Used (Arc-wrapped, concurrent wrapper available) |
+| `policy-fast-lru` | Fast LRU | Optimized single-threaded LRU (~7–10× faster than LRU) |
+| `policy-lru-k` | LRU-K | Scan-resistant with K-th access |
+| `policy-lfu` | LFU | Least Frequently Used (bucket-based) |
+| `policy-heap-lfu` | Heap LFU | LFU with heap-based eviction |
+| `policy-two-q` | 2Q | Two-Queue |
+| `policy-s3-fifo` | S3-FIFO | Scan-resistant three-queue FIFO |
+| `policy-arc` | ARC | Adaptive Replacement Cache |
+| `policy-lifo` | LIFO | Last In, First Out |
+| `policy-mfu` | MFU | Most Frequently Used |
+| `policy-mru` | MRU | Most Recently Used |
+| `policy-random` | Random | Random eviction |
+| `policy-slru` | SLRU | Segmented LRU |
+| `policy-clock` | Clock | Second-chance clock |
+| `policy-clock-pro` | Clock-PRO | Scan-resistant clock |
+| `policy-nru` | NRU | Not Recently Used |
+
+**Convenience:** `policy-all` enables every policy above.
+
+```toml
+# Minimal build: only LRU and S3-FIFO
+cachekit = { version = "0.3", default-features = false, features = ["policy-lru", "policy-s3-fifo"] }
+```
+
 ## Overview
 
 CacheKit is a Rust library that provides:
@@ -85,7 +118,7 @@ fn main() {
 
 ### Available Policies
 
-All policies are available through the unified builder API:
+All policies are available through the unified builder API. Enable the corresponding feature flag for each policy (e.g. `policy-lru` for `CachePolicy::Lru`). See [Feature Flags](#per-policy-eviction-policies) above.
 
 ```rust
 use cachekit::builder::{CacheBuilder, CachePolicy};

bench-support/Cargo.toml

@@ -9,7 +9,7 @@ name = "render_docs"
 path = "src/bin/render_docs.rs"
 
 [dependencies]
-cachekit = { path = ".." }
+cachekit = { path = "..", features = ["policy-all"] }
 criterion = "0.8"
 rand = { version = "0.9", features = ["small_rng"] }
 rand_distr = "0.5"

docs/getting-started/integration.md

@@ -63,15 +63,18 @@ The `Cache<K, V>` wrapper requires:
 
 ### Policy Selection
 
-| Policy | Use Case | Trade-offs |
-|--------|----------|------------|
-| `Fifo` | Simple, predictable eviction | No recency/frequency tracking |
-| `Lru` | Temporal locality | Vulnerable to scans |
-| `LruK { k }` | Scan resistance | Extra memory for history |
-| `Lfu { bucket_hint }` | Stable hot spots | Slow to adapt to changes |
-| `HeapLfu` | Large caches, frequent evictions | O(log n) eviction |
-| `TwoQ { probation_frac }` | Mixed workloads | Two-queue overhead |
-| `S3Fifo { small_ratio, ghost_ratio }` | Scan-heavy workloads | Small + ghost queues |
+Each policy requires its feature flag (e.g. `policy-lru` for `CachePolicy::Lru`). See [Compatibility and Features](../guides/compatibility-and-features.md).
+
+| Policy | Feature | Use Case | Trade-offs |
+|--------|---------|----------|------------|
+| `Fifo` | `policy-fifo` | Simple, predictable eviction | No recency/frequency tracking |
+| `Lru` | `policy-lru` | Temporal locality | Vulnerable to scans |
+| `FastLru` | `policy-fast-lru` | Maximum single-threaded speed | No Arc wrapping, no concurrent wrapper |
+| `LruK { k }` | `policy-lru-k` | Scan resistance | Extra memory for history |
+| `Lfu { bucket_hint }` | `policy-lfu` | Stable hot spots | Slow to adapt to changes |
+| `HeapLfu` | `policy-heap-lfu` | Large caches, frequent evictions | O(log n) eviction |
+| `TwoQ { probation_frac }` | `policy-two-q` | Mixed workloads | Two-queue overhead |
+| `S3Fifo { small_ratio, ghost_ratio }` | `policy-s3-fifo` | Scan-heavy workloads | Small + ghost queues |
 
 ## Direct Policy Access
 

docs/getting-started/quickstart.md

@@ -8,9 +8,18 @@ Add CacheKit to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-cachekit = "0.2.0-alpha"
+cachekit = "0.3"
 ```
 
+Each eviction policy is gated behind a feature flag. The default features include `policy-s3-fifo`, `policy-lru`, `policy-fast-lru`, `policy-lru-k`, and `policy-clock`. For minimal builds, use `default-features = false` and enable only the policies you need:
+
+```toml
+[dependencies]
+cachekit = { version = "0.3", default-features = false, features = ["policy-lru"] }
+```
+
+See [Compatibility and Features](../guides/compatibility-and-features.md) for the full list of per-policy feature flags.
+
 ## Build Your First Cache
 
 Use `CacheBuilder` with an eviction policy:

docs/guides/api-surface.md

@@ -17,6 +17,10 @@ This page maps the major modules and how they fit together.
 3. Use the unified `Cache<K, V>` API for standard operations.
 4. Drop into `policy::*` or `ds::*` for advanced or policy-specific operations.
 
+## Feature Flags
+
+Policies are gated behind feature flags (e.g. `policy-lru`, `policy-s3-fifo`). Use `default-features = false` and enable only the policies you need. See [Compatibility and Features](compatibility-and-features.md).
+
 ## Where to Start
 
 - [Builder overview](../getting-started/integration.md)

docs/guides/choosing-a-policy.md

@@ -3,6 +3,8 @@
 This guide summarizes practical trade-offs and mirrors the benchmark-driven guidance
 in the [latest benchmark guide](../benchmarks/latest/index.md).
 
+**Feature flags:** Each policy is gated behind a feature flag (e.g. `policy-lru`, `policy-s3-fifo`). Enable only the policies you need for smaller builds. See [Compatibility and Features](compatibility-and-features.md).
+
 ## Quick Picks
 
 - **General purpose, skewed workloads**: `LRU` or `S3-FIFO`

docs/guides/compatibility-and-features.md

@@ -6,9 +6,46 @@ CacheKit targets the Rust MSRV listed in `Cargo.toml` and reflected in the READM
 
 ## Feature Flags
 
+### General
+
 - `metrics` — Enables hit/miss metrics and snapshots.
 - `concurrency` — Enables concurrent wrappers (requires `parking_lot`).
 
+### Eviction Policies (Per-Policy Feature Flags)
+
+Each eviction policy can be enabled or disabled via its own feature flag. This keeps builds smaller when you only need specific policies.
+
+| Feature | Policy | Description |
+|---------|--------|-------------|
+| `policy-fifo` | FIFO | First In, First Out |
+| `policy-lru` | LRU | Least Recently Used (Arc-wrapped, `ConcurrentLruCache` available) |
+| `policy-fast-lru` | Fast LRU | Optimized single-threaded LRU (~7–10× faster than LRU) |
+| `policy-lru-k` | LRU-K | Scan-resistant with K-th access |
+| `policy-lfu` | LFU | Least Frequently Used (bucket-based) |
+| `policy-heap-lfu` | Heap LFU | LFU with heap-based eviction |
+| `policy-two-q` | 2Q | Two-Queue |
+| `policy-s3-fifo` | S3-FIFO | Scan-resistant three-queue FIFO |
+| `policy-arc` | ARC | Adaptive Replacement Cache |
+| `policy-lifo` | LIFO | Last In, First Out |
+| `policy-mfu` | MFU | Most Frequently Used |
+| `policy-mru` | MRU | Most Recently Used |
+| `policy-random` | Random | Random eviction |
+| `policy-slru` | SLRU | Segmented LRU |
+| `policy-clock` | Clock | Second-chance clock |
+| `policy-clock-pro` | Clock-PRO | Scan-resistant clock |
+| `policy-nru` | NRU | Not Recently Used |
+
+**Default features** include `policy-s3-fifo`, `policy-lru`, `policy-fast-lru`, `policy-lru-k`, and `policy-clock`.
+
+**Convenience feature:** `policy-all` enables every policy above.
+
+**Minimal builds:** Use `default-features = false` and select only the policies you need:
+
+```toml
+[dependencies]
+cachekit = { version = "0.3", default-features = false, features = ["policy-lru", "policy-s3-fifo"] }
+```
+
 ## Optional Dependencies
 
 - `parking_lot` — Used for concurrent wrappers behind the `concurrency` feature.

docs/policies/2q.md

@@ -1,5 +1,7 @@
 # 2Q
 
+**Feature:** `policy-two-q`
+
 ## Goal
 Reduce scan pollution with a simple two-queue design that approximates "access twice before protection".
 

docs/policies/README.md

@@ -34,24 +34,27 @@ If you can only implement one “general purpose” policy for mixed workloads,
 
 ### Implemented Policies (CacheKit)
 
-| Policy | Summary | Doc |
-|--------|---------|-----|
-| LRU | Strong default for temporal locality | [LRU doc](lru.md) |
-| MRU | Evicts most recent (niche: cyclic patterns) | [MRU doc](mru.md) |
-| SLRU | Segmented LRU with probation/protected | [SLRU doc](slru.md) |
-| LFU | Frequency-driven, stable hot sets | [LFU doc](lfu.md) |
-| Heap-LFU | LFU with heap eviction | [Heap-LFU doc](heap-lfu.md) |
-| MFU | Evicts highest frequency (niche/baseline) | [MFU doc](mfu.md) |
-| LRU-K | Scan-resistant recency | [LRU-K doc](lru-k.md) |
-| 2Q | Probation + protected queues | [2Q doc](2q.md) |
-| ARC | Adaptive recency/frequency balance | [ARC doc](arc.md) |
-| FIFO | Simple insertion-order (oldest first) | [FIFO doc](fifo.md) |
-| LIFO | Stack-based (newest first) | [LIFO doc](lifo.md) |
-| Clock | Approximate LRU | [Clock doc](clock.md) |
-| Clock-PRO | Scan-resistant Clock variant | [Clock-PRO doc](clock-pro.md) |
-| NRU | Coarse recency tracking | [NRU doc](nru.md) |
-| S3-FIFO | Scan-resistant FIFO | [S3-FIFO doc](s3-fifo.md) |
-| Random | Baseline: uniform random eviction | [Random doc](random.md) |
+Enable the corresponding feature flag for each policy. See [Compatibility and Features](../guides/compatibility-and-features.md).
+
+| Policy | Feature | Summary | Doc |
+|--------|---------|---------|-----|
+| LRU | `policy-lru` | Strong default for temporal locality | [LRU doc](lru.md) |
+| Fast LRU | `policy-fast-lru` | Optimized single-threaded LRU | — |
+| MRU | `policy-mru` | Evicts most recent (niche: cyclic patterns) | [MRU doc](mru.md) |
+| SLRU | `policy-slru` | Segmented LRU with probation/protected | [SLRU doc](slru.md) |
+| LFU | `policy-lfu` | Frequency-driven, stable hot sets | [LFU doc](lfu.md) |
+| Heap-LFU | `policy-heap-lfu` | LFU with heap eviction | [Heap-LFU doc](heap-lfu.md) |
+| MFU | `policy-mfu` | Evicts highest frequency (niche/baseline) | [MFU doc](mfu.md) |
+| LRU-K | `policy-lru-k` | Scan-resistant recency | [LRU-K doc](lru-k.md) |
+| 2Q | `policy-two-q` | Probation + protected queues | [2Q doc](2q.md) |
+| ARC | `policy-arc` | Adaptive recency/frequency balance | [ARC doc](arc.md) |
+| FIFO | `policy-fifo` | Simple insertion-order (oldest first) | [FIFO doc](fifo.md) |
+| LIFO | `policy-lifo` | Stack-based (newest first) | [LIFO doc](lifo.md) |
+| Clock | `policy-clock` | Approximate LRU | [Clock doc](clock.md) |
+| Clock-PRO | `policy-clock-pro` | Scan-resistant Clock variant | [Clock-PRO doc](clock-pro.md) |
+| NRU | `policy-nru` | Coarse recency tracking | [NRU doc](nru.md) |
+| S3-FIFO | `policy-s3-fifo` | Scan-resistant FIFO | [S3-FIFO doc](s3-fifo.md) |
+| Random | `policy-random` | Baseline: uniform random eviction | [Random doc](random.md) |
 
 ### Roadmap Policies (Planned)