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.

Table of Contents

• Overview
• Main Features
• Feature Flags
• Installation
• Quick Start
• Available Policies
• Policy Selection Guide
• Direct Policy Access
• Documentation
• Next Steps

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.

Installation

Add cachekit as a dependency in your Cargo.toml:

[dependencies]
cachekit = "0.3.0"

From source:

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

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);
}

Feature Flags

General

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.

Convenience: policy-all enables every policy above.

# Minimal build: only LRU and S3-FIFO
cachekit = { version = "0.3", default-features = false, features = ["policy-lru", "policy-s3-fifo"] }

Available Policies

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 above.

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

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
• Roadmap
• Testing
• Benchmarks