Struct CacheEntry

Source

pub struct CacheEntry<K, V, M = ()> {
    pub key: K,
    pub value: V,
    pub size: u64,
    pub metadata: Option<M>,
    /* private fields */
}

Expand description

Unified cache entry holding key, value, timestamps, and algorithm-specific metadata.

The M parameter allows each algorithm to store its own metadata without affecting the core entry structure. Use () for algorithms that don’t need extra per-entry metadata (e.g., LRU).

§Design Decisions

size: User-provided size of content this entry represents. Could be memory bytes, disk bytes, or any unit. Use 1 for count-based caches.
last_accessed: Atomic for lock-free monitoring and metrics. Can be updated during reads without requiring a write lock.
create_time: Atomic for consistency. Useful for TTL, debugging, metrics.
metadata: Optional algorithm-specific data. None for simple algorithms like LRU that don’t need extra per-entry state.

§Examples

use cache_rs::entry::CacheEntry;

// Create a simple entry for count-based caching
let entry: CacheEntry<&str, i32, ()> = CacheEntry::new("key", 42, 1);
assert_eq!(entry.key, "key");
assert_eq!(entry.value, 42);
assert_eq!(entry.size, 1);

Fields§

§key: K

The cached key

§value: V

The cached value (or reference/handle to external storage)

§size: u64

Size of content this entry represents (user-provided). For count-based caches, use 1. For size-aware caches, use actual bytes (memory, disk, etc.)

§metadata: Option<M>

Algorithm-specific metadata (frequency, priority, segment, etc.). None for algorithms that don’t need per-entry metadata (e.g., LRU).

Implementations§

Source §

impl<K, V, M> CacheEntry<K, V, M>

Source

pub fn new(key: K, value: V, size: u64) -> Self

Creates a new cache entry without algorithm-specific metadata.

Use this constructor for algorithms like LRU that don’t need per-entry metadata beyond the basic key, value, and timestamps.

§Arguments

key - The cache key
value - The cached value
size - Size of the content this entry represents (use 1 for count-based caches)

§Examples

use cache_rs::entry::CacheEntry;

// Count-based cache entry
let entry: CacheEntry<&str, String, ()> = CacheEntry::new("user:123", "Alice".to_string(), 1);

// Size-aware cache entry
let data = vec![0u8; 1024];
let entry: CacheEntry<&str, Vec<u8>, ()> = CacheEntry::new("file.bin", data, 1024);

Source

pub fn with_metadata(key: K, value: V, size: u64, metadata: M) -> Self

Creates a new cache entry with algorithm-specific metadata.

Use this constructor for algorithms like LFU, LFUDA, SLRU, or GDSF that need to track additional per-entry state.

§Arguments

key - The cache key
value - The cached value
size - Size of the content this entry represents (use 1 for count-based caches)
metadata - Algorithm-specific metadata

§Examples

use cache_rs::entry::CacheEntry;
use cache_rs::meta::LfuMeta;

let entry = CacheEntry::with_metadata(
    "key".to_string(),
    vec![1, 2, 3],
    3,
    LfuMeta { frequency: 0 },
);
assert!(entry.metadata.is_some());

Source

pub fn touch(&mut self)

Updates the last_accessed timestamp to the current time.

§Examples

use cache_rs::entry::CacheEntry;

let mut entry: CacheEntry<&str, i32, ()> = CacheEntry::new("key", 42, 1);
let old_access_time = entry.last_accessed();

// Simulate some time passing (in real code, time would actually pass)
entry.touch();

// On systems with std, the access time would be updated

Source

pub fn last_accessed(&self) -> u64

Gets the last_accessed timestamp in nanoseconds.

Returns nanoseconds since UNIX epoch when the std feature is enabled, or 0 in no_std environments.

Source

pub fn create_time(&self) -> u64

Gets the creation timestamp in nanoseconds.

Returns nanoseconds since UNIX epoch when the std feature is enabled, or 0 in no_std environments.

Source

pub fn age_nanos(&self) -> u64

Gets the age of this entry in nanoseconds.

Age is calculated as now - create_time. Returns 0 in no_std environments where time is not available.

§Examples

use cache_rs::entry::CacheEntry;

let entry: CacheEntry<&str, i32, ()> = CacheEntry::new("key", 42, 1);
let age = entry.age_nanos();
// Age should be very small since we just created the entry

Source

pub fn idle_nanos(&self) -> u64

Gets the time since last access in nanoseconds.

Idle time is calculated as now - last_accessed. Returns 0 in no_std environments where time is not available.

§Examples

use cache_rs::entry::CacheEntry;

let entry: CacheEntry<&str, i32, ()> = CacheEntry::new("key", 42, 1);
let idle = entry.idle_nanos();
// Idle time should be very small since we just created the entry

Source