cachekit

High-performance cache policies and supporting data structures for Rust systems with optional metrics and benchmarks.

Why CacheKit

• Pluggable eviction policies with predictable performance characteristics.
• Unified builder API plus direct access for policy-specific operations.
• Optional metrics and benchmarks to validate trade-offs.

Installation

Add cachekit as a dependency in your Cargo.toml:

[dependencies]
cachekit = "0.2.0"

From git (bleeding edge):

[dependencies]
cachekit = { git = "https://github.com/OxidizeLabs/cachekit" }

Feature Flags

Feature	Enables
metrics	Hit/miss metrics and snapshots
concurrency	Concurrent wrappers (requires parking_lot)

Overview

CacheKit is a Rust library that provides:

• High-performance cache replacement policies (e.g., FIFO, LRU, LRU-K, Clock, NRU, S3-FIFO, SLRU, 2Q, and more).
• Supporting data structures and policy primitives for building caches.
• Optional metrics and benchmark harnesses.
• A modular API suitable for embedding in systems where control over caching behavior is critical.

This crate is designed for systems programming, microservices, and performance-critical applications.

Features

• Policy implementations optimized for performance and predictability.
• Optional integration with metrics collectors (e.g., Prometheus/metrics crates).
• Benchmarks to compare policy performance under real-world workloads.

Quick Start

Using the Builder (Recommended)

The CacheBuilder provides a unified API for creating caches with any eviction policy:

use cachekit::builder::{CacheBuilder, CachePolicy};

fn main() {
    // Create an LRU cache with a capacity of 100 entries
    let mut cache = CacheBuilder::new(100).build::<u64, String>(CachePolicy::Lru);

    // Insert items
    cache.insert(1, "value1".to_string());
    cache.insert(2, "value2".to_string());

    // Retrieve an item
    if let Some(value) = cache.get(&1) {
        println!("Got from cache: {}", value);
    }

    // Check existence and size
    assert!(cache.contains(&1));
    assert_eq!(cache.len(), 2);
}

Available Policies

All policies are available through the unified builder API:

use cachekit::builder::{CacheBuilder, CachePolicy};

// FIFO - First In, First Out
let fifo = CacheBuilder::new(100).build::<u64, String>(CachePolicy::Fifo);

// LRU - Least Recently Used
let lru = CacheBuilder::new(100).build::<u64, String>(CachePolicy::Lru);

// LRU-K - Scan-resistant LRU (K=2 is common)
let lru_k = CacheBuilder::new(100).build::<u64, String>(CachePolicy::LruK { k: 2 });

// LFU - Least Frequently Used (bucket-based, O(1))
let lfu = CacheBuilder::new(100).build::<u64, String>(
    CachePolicy::Lfu { bucket_hint: None }
);

// HeapLFU - Least Frequently Used (heap-based, O(log n))
let heap_lfu = CacheBuilder::new(100).build::<u64, String>(CachePolicy::HeapLfu);

// 2Q - Two-Queue with configurable probation fraction
let two_q = CacheBuilder::new(100).build::<u64, String>(
    CachePolicy::TwoQ { probation_frac: 0.25 }
);

// S3-FIFO - Scan-resistant FIFO with small + ghost ratios
let s3_fifo = CacheBuilder::new(100).build::<u64, String>(
    CachePolicy::S3Fifo { small_ratio: 0.1, ghost_ratio: 0.9 }
);

// LIFO - Last In, First Out (stack-like eviction)
let lifo = CacheBuilder::new(100).build::<u64, String>(CachePolicy::Lifo);

// MFU - Most Frequently Used (evicts hot items)
let mfu = CacheBuilder::new(100).build::<u64, String>(
    CachePolicy::Mfu { bucket_hint: None }
);

// MRU - Most Recently Used (evicts recently accessed)
let mru = CacheBuilder::new(100).build::<u64, String>(CachePolicy::Mru);

// Random - Uniform random eviction
let random = CacheBuilder::new(100).build::<u64, String>(CachePolicy::Random);

// SLRU - Segmented LRU with probationary/protected segments
let slru = CacheBuilder::new(100).build::<u64, String>(
    CachePolicy::Slru { probationary_frac: 0.25 }
);

// Clock - Approximate LRU with reference bits (lower overhead)
let clock = CacheBuilder::new(100).build::<u64, String>(CachePolicy::Clock);

// Clock-PRO - Scan-resistant Clock variant
let clock_pro = CacheBuilder::new(100).build::<u64, String>(CachePolicy::ClockPro);

// NRU - Not Recently Used (simple reference bit tracking)
let nru = CacheBuilder::new(100).build::<u64, String>(CachePolicy::Nru);

Policy Selection Guide

Policy	Best For	Eviction Basis
FIFO	Simple, predictable workloads	Insertion order
LRU	Temporal locality	Recency
LRU-K	Scan-resistant workloads	K-th access time
LFU	Stable access patterns	Frequency (O(1))
HeapLFU	Large caches, frequent evictions	Frequency (O(log n))
2Q	Mixed workloads	Two-queue promotion
S3-FIFO	Scan-heavy workloads	FIFO + ghost history
LIFO	Stack-like caching	Reverse insertion order
MFU	Inverse frequency patterns	Highest frequency
MRU	Anti-recency patterns	Most recent access
Random	Baseline/uniform distribution	Random selection
SLRU	Scan resistance	Segmented LRU
Clock	Low-overhead LRU approximation	Reference bits + hand
ClockPro	Scan-resistant Clock variant	Clock + ghost history
NRU	Simple coarse tracking	Reference bits (binary)

See Choosing a policy for benchmark-driven guidance.

Direct Policy Access

For advanced use cases requiring policy-specific operations, use the underlying implementations directly:

use std::sync::Arc;
use cachekit::policy::lru::LruCore;
use cachekit::traits::{CoreCache, LruCacheTrait};

fn main() {
    // LRU with policy-specific operations
    let mut lru_cache: LruCore<u64, &str> = LruCore::new(100);
    lru_cache.insert(1, Arc::new("value"));

    // Access LRU-specific methods
    if let Some((key, _)) = lru_cache.peek_lru() {
        println!("LRU key: {}", key);
    }
}

Next Steps

• Quickstart
• Integration guide
• Policy overview
• Benchmarks