oximedia_cache/lib.rs
1//! High-performance caching infrastructure for OxiMedia.
2//!
3//! `oximedia-cache` provides sixteen complementary caching primitives:
4//!
5//! - [`lru_cache`] — arena-backed O(1) LRU cache with TTL expiration,
6//! entry pinning, hit/miss/eviction stats, and capacity resize
7//! - [`tiered_cache`] — multi-tier (L1 memory → L2 memory → disk) cache with
8//! file-backed disk tier, adaptive promotion thresholds, entry compression
9//! for L2+ tiers, pluggable eviction (LRU/LFU/FIFO/Random/TinyLFU), and
10//! automatic promotion across tiers
11//! - [`cache_warming`] — predictive warming via access-pattern analysis,
12//! exponential inter-arrival EMA, auto-correlation periodicity detection, and
13//! score-ranked warmup plans
14//! - [`bloom_filter`] — probabilistic membership filter (standard, counting
15//! with deletion, and scalable auto-growing variant) using FNV-1a double
16//! hashing
17//! - [`distributed_cache`] — consistent-hash ring with configurable virtual
18//! nodes, per-node client, quorum replication factor, and cluster coordinator
19//! - [`eviction_policies`] — standalone LFU tracker, frequency counter with
20//! decay, TinyLFU admission gate (optimized hot path), and ARC ghost-list
21//! tracker
22//! - [`content_aware_cache`] — media-type-aware cache with configurable weight
23//! factors per media type; scores eviction candidates by recency × priority ×
24//! size
25//! - [`write_behind_cache`] — write-back cache with dirty tracking,
26//! flush-by-age, mark-clean, and backing-store abstraction
27//! - [`two_queue`] — 2Q scan-resistant eviction policy (A1in FIFO + Am LRU
28//! + A1out ghost list) as alternative to LRU
29//! - [`cache_metrics`] — atomic hit/miss/eviction counters with latency
30//! percentile tracking and `Arc`-shareable snapshots
31//! - [`prefetch`] — sequential media segment pre-loading based on access
32//! patterns with pluggable loader and pending queue
33//! - [`sharded_lru`] — concurrent LRU cache sharded across N independent
34//! `Mutex<LruCache>` instances to reduce lock contention
35//! - [`cache_partitioning`] — isolate cache space per tenant, stream, or
36//! workload with independent byte-level budgets and LRU eviction
37//! - [`cache_serialization`] — persist the cache state to disk on shutdown and
38//! restore on startup using a zero-copy binary format
39//! - [`slab_allocator`] — fixed-size slab allocator for cache entries to
40//! reduce heap fragmentation in long-running processes
41//!
42//! # Quick start
43//!
44//! ```rust
45//! use oximedia_cache::lru_cache::LruCache;
46//!
47//! let mut cache: LruCache<&str, Vec<u8>> = LruCache::new(128);
48//! cache.insert("frame-001", vec![0u8; 4096], 4096);
49//! assert!(cache.get(&"frame-001").is_some());
50//! ```
51
52#![warn(missing_docs)]
53#![allow(clippy::module_name_repetitions)]
54
55pub mod adaptive;
56pub mod admission_filter;
57pub mod bloom_filter;
58pub mod cache_metrics;
59pub mod cache_partitioning;
60pub mod cache_serialization;
61pub mod cache_warming;
62pub mod content_aware_cache;
63pub mod distributed_cache;
64pub mod eviction;
65pub mod eviction_policies;
66pub mod key_norm;
67pub mod lru_cache;
68pub mod negative;
69pub mod prefetch;
70pub mod segment_cache;
71pub mod sharded_lru;
72pub mod slab_allocator;
73pub mod stats;
74pub mod tier_compressor;
75pub mod tiered_cache;
76pub mod ttl_cache;
77pub mod two_queue;
78pub mod weighted_cache;
79pub mod write_behind_cache;
80pub mod write_through;