cache_rs/config/
lru.rs

1//! Configuration for the Least Recently Used (LRU) cache.
2//!
3//! This module provides configuration for LRU caches.
4//!
5//! # Sizing Guidelines
6//!
7//! ## Understanding `max_size` and `capacity`
8//!
9//! - **`max_size`**: The maximum total size in bytes for cached *values*. This should reflect
10//!   your memory budget for the cache data itself.
11//! - **`capacity`**: The maximum number of entries. Each entry has memory overhead beyond
12//!   the value size (approximately 64-128 bytes per entry for keys, pointers, and metadata).
13//!
14//! ## For In-Memory Caches
15//!
16//! Set `max_size` to the amount of memory you want to allocate for cached values:
17//!
18//! ```text
19//! Total Memory ≈ max_size + (capacity × overhead_per_entry)
20//! overhead_per_entry ≈ 64-128 bytes (keys, pointers, metadata)
21//! ```
22//!
23//! **Example**: For a 100MB cache with ~10KB average values:
24//! - `max_size = 100 * 1024 * 1024` (100MB for values)
25//! - `capacity = 10_000` entries
26//! - Overhead ≈ 10,000 × 100 bytes = ~1MB additional
27//!
28//! ## For Disk-Based or External Caches
29//!
30//! When caching references to external storage, size based on your target cache size:
31//!
32//! ```text
33//! capacity = target_cache_size / average_object_size
34//! ```
35//!
36//! **Example**: For a 1GB disk cache with 50KB average objects:
37//! - `max_size = 1024 * 1024 * 1024` (1GB)
38//! - `capacity = 1GB / 50KB ≈ 20,000` entries
39//!
40//! # Examples
41//!
42//! ```
43//! use cache_rs::config::LruCacheConfig;
44//! use cache_rs::LruCache;
45//! use core::num::NonZeroUsize;
46//!
47//! // In-memory cache: 50MB budget for values, ~5KB average size
48//! let config = LruCacheConfig {
49//!     capacity: NonZeroUsize::new(10_000).unwrap(),
50//!     max_size: 50 * 1024 * 1024,  // 50MB
51//! };
52//! let cache: LruCache<String, Vec<u8>> = LruCache::init(config, None);
53//!
54//! // Small fixed-size value cache (e.g., config values, counters)
55//! // When values are small, capacity is the primary constraint
56//! let config = LruCacheConfig {
57//!     capacity: NonZeroUsize::new(1000).unwrap(),
58//!     max_size: 1024 * 1024,  // 1MB is plenty for small values
59//! };
60//! let cache: LruCache<String, i32> = LruCache::init(config, None);
61//! ```
62
63use core::fmt;
64use core::num::NonZeroUsize;
65
66/// Configuration for an LRU (Least Recently Used) cache.
67///
68/// LRU evicts the least recently accessed items when the cache reaches capacity.
69///
70/// # Fields
71///
72/// - `capacity`: Maximum number of entries the cache can hold. Each entry has
73///   memory overhead (~64-128 bytes) for keys, pointers, and metadata.
74/// - `max_size`: Maximum total size in bytes for cached values. Set this based
75///   on your memory budget, not to `u64::MAX`. See module docs for sizing guidance.
76///
77/// # Sizing Recommendations
78///
79/// Always set meaningful values for both fields:
80///
81/// - **In-memory cache**: `max_size` = memory budget for values;
82///   `capacity` = `max_size` / average_value_size
83/// - **Disk-based cache**: `max_size` = disk space allocation;
84///   `capacity` = `max_size` / average_object_size
85///
86/// # Examples
87///
88/// ```
89/// use cache_rs::config::LruCacheConfig;
90/// use cache_rs::LruCache;
91/// use core::num::NonZeroUsize;
92///
93/// // 10MB cache for ~1KB average values → ~10,000 entries
94/// let config = LruCacheConfig {
95///     capacity: NonZeroUsize::new(10_000).unwrap(),
96///     max_size: 10 * 1024 * 1024,  // 10MB
97/// };
98/// let cache: LruCache<String, Vec<u8>> = LruCache::init(config, None);
99///
100/// // Small cache for tiny values (ints, bools) - capacity-limited
101/// let config = LruCacheConfig {
102///     capacity: NonZeroUsize::new(500).unwrap(),
103///     max_size: 64 * 1024,  // 64KB is ample for small values
104/// };
105/// let cache: LruCache<&str, i32> = LruCache::init(config, None);
106/// ```
107#[derive(Clone, Copy)]
108pub struct LruCacheConfig {
109    /// Maximum number of key-value pairs the cache can hold.
110    /// Account for ~64-128 bytes overhead per entry beyond value size.
111    pub capacity: NonZeroUsize,
112    /// Maximum total size in bytes for cached values.
113    /// Set based on your memory/disk budget. Avoid using `u64::MAX`.
114    pub max_size: u64,
115}
116
117impl fmt::Debug for LruCacheConfig {
118    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
119        f.debug_struct("LruCacheConfig")
120            .field("capacity", &self.capacity)
121            .field("max_size", &self.max_size)
122            .finish()
123    }
124}
125
126#[cfg(test)]
127mod tests {
128    use super::*;
129
130    #[test]
131    fn test_lru_config_creation() {
132        // 10MB cache with ~10KB average values
133        let config = LruCacheConfig {
134            capacity: NonZeroUsize::new(1000).unwrap(),
135            max_size: 10 * 1024 * 1024,
136        };
137        assert_eq!(config.capacity.get(), 1000);
138        assert_eq!(config.max_size, 10 * 1024 * 1024);
139    }
140
141    #[test]
142    fn test_lru_config_with_size_limit() {
143        // 1MB cache with ~1KB average values
144        let config = LruCacheConfig {
145            capacity: NonZeroUsize::new(1000).unwrap(),
146            max_size: 1024 * 1024,
147        };
148        assert_eq!(config.capacity.get(), 1000);
149        assert_eq!(config.max_size, 1024 * 1024);
150    }
151}
cache_rs/config/lru.rs

cache_rs/config/
lru.rs
