Struct Statistics

Source

pub struct Statistics { /* private fields */ }

Available on crate feature statistics only.

Expand description

Cache performance and usage statistics.

§Examples

use evictor::Lru;

let mut cache = Lru::new(std::num::NonZeroUsize::new(2).unwrap());
cache.insert("a".to_string(), 1);
cache.insert("b".to_string(), 2);

let stats = cache.statistics();
assert_eq!(stats.len(), 2);
assert_eq!(stats.insertions(), 2);
assert_eq!(stats.evictions(), 0);

Implementations§

Source §

impl Statistics

Source

pub fn is_empty(&self) -> bool

Returns true if the cache contains no entries.

§Examples

use evictor::Lru;

let mut cache = Lru::new(std::num::NonZeroUsize::new(2).unwrap());
assert!(cache.statistics().is_empty());

cache.insert("key".to_string(), "value".to_string());
assert!(!cache.statistics().is_empty());

Source

pub fn len(&self) -> usize

Returns the current number of entries stored in the cache.

This count represents the actual number of key-value pairs currently residing in the cache, which may be less than the cache’s capacity.

§Examples

use evictor::Lru;

let mut cache = Lru::new(std::num::NonZeroUsize::new(3).unwrap());
assert_eq!(cache.statistics().len(), 0);

cache.insert("a".to_string(), 1);
cache.insert("b".to_string(), 2);
assert_eq!(cache.statistics().len(), 2);

Source

pub fn residency(&self) -> f64

Returns the current cache residency as a percentage (0.0 to 100.0).

Residency represents how full the cache is, calculated as the current number of entries divided by the maximum capacity, expressed as a percentage. A residency of 100.0% indicates the cache is at full capacity.

§Examples

use evictor::Lru;

let mut cache = Lru::new(std::num::NonZeroUsize::new(4).unwrap());
assert_eq!(cache.statistics().residency(), 0.0);

cache.insert("a".to_string(), 1);
cache.insert("b".to_string(), 2);
assert_eq!(cache.statistics().residency(), 50.0);

cache.insert("c".to_string(), 3);
cache.insert("d".to_string(), 4);
assert_eq!(cache.statistics().residency(), 100.0);

Source

pub fn capacity(&self) -> usize

Returns the maximum capacity of the cache.

This is the maximum number of key-value pairs that the cache can store before eviction policies take effect to make room for new entries.

§Examples

use evictor::Lru;

let cache: Lru<String, i32> = Lru::new(std::num::NonZeroUsize::new(100).unwrap());
assert_eq!(cache.statistics().capacity(), 100);

Source

pub fn evictions(&self) -> u64

Returns the total number of evictions that have occurred.

An eviction happens when an entry is removed from the cache to make room for a new entry, according to the cache’s eviction policy (LRU, LFU, etc.). This counter tracks the lifetime total of such removals.

§Examples

use evictor::Lru;

let mut cache = Lru::new(std::num::NonZeroUsize::new(2).unwrap());
assert_eq!(cache.statistics().evictions(), 0);

cache.insert("a".to_string(), 1);
cache.insert("b".to_string(), 2);
assert_eq!(cache.statistics().evictions(), 0);

// This insertion will evict the least recently used entry
cache.insert("c".to_string(), 3);
assert_eq!(cache.statistics().evictions(), 1);

Source

pub fn insertions(&self) -> u64

Returns the total number of insertion operations that have occurred.

This counter increments every time a new key-value pair is inserted into the cache, regardless of whether it causes an eviction. Updates to existing keys do not count as insertions.

§Examples

use evictor::Lru;

let mut cache = Lru::new(std::num::NonZeroUsize::new(2).unwrap());
assert_eq!(cache.statistics().insertions(), 0);

cache.insert("a".to_string(), 1);
assert_eq!(cache.statistics().insertions(), 1);

cache.insert("a".to_string(), 2); // Update existing key
assert_eq!(cache.statistics().insertions(), 1);

Source

pub fn hits(&self) -> u64

Returns the total number of cache hits.

A cache hit occurs when a requested key is found in the cache. This metric is useful for measuring cache effectiveness.

§Examples

use evictor::Lru;

let mut cache = Lru::new(std::num::NonZeroUsize::new(2).unwrap());
cache.insert("a".to_string(), 1);

assert_eq!(cache.statistics().hits(), 0);

cache.get(&"a".to_string()); // Hit
assert_eq!(cache.statistics().hits(), 1);

cache.get(&"b".to_string()); // Miss
assert_eq!(cache.statistics().hits(), 1);

Source

pub fn misses(&self) -> u64

Returns the total number of cache misses.

A cache miss occurs when a requested key is not found in the cache. High miss rates may indicate the cache size is too small or the access pattern is not well-suited for caching.

§Examples

use evictor::Lru;

let mut cache = Lru::new(std::num::NonZeroUsize::new(2).unwrap());
cache.insert("a".to_string(), 1);

assert_eq!(cache.statistics().misses(), 0);

cache.get(&"a".to_string()); // Hit
assert_eq!(cache.statistics().misses(), 0);

cache.get(&"b".to_string()); // Miss
assert_eq!(cache.statistics().misses(), 1);

Source

pub fn hit_rate(&self) -> f64

Returns the cache hit rate as a percentage (0.0 to 100.0).

The hit rate is calculated as hits / (hits + misses) * 100. A higher hit rate indicates better cache performance. Returns 0.0 if no cache access operations have been performed yet.

§Examples

use evictor::Lru;

let mut cache = Lru::new(std::num::NonZeroUsize::new(2).unwrap());
cache.insert("a".to_string(), 1);
cache.insert("b".to_string(), 2);

// Initially no accesses, so hit rate is 0
assert_eq!(cache.statistics().hit_rate(), 0.0);

cache.get(&"a".to_string()); // Hit
cache.get(&"b".to_string()); // Hit
cache.get(&"c".to_string()); // Miss

// 2 hits out of 3 total accesses = 66.67%
assert!((cache.statistics().hit_rate() - 66.66666666666666).abs() < f64::EPSILON);

Source

pub fn miss_rate(&self) -> f64

Returns the cache miss rate as a percentage (0.0 to 100.0).

The miss rate is calculated as misses / (hits + misses) * 100. A lower miss rate indicates better cache performance. Returns 0.0 if no cache access operations have been performed yet.

Note: hit_rate() + miss_rate() always equals 100.0 (when there have been accesses).

§Examples

use evictor::Lru;

let mut cache = Lru::new(std::num::NonZeroUsize::new(2).unwrap());
cache.insert("a".to_string(), 1);

// Initially no accesses, so miss rate is 0
assert_eq!(cache.statistics().miss_rate(), 0.0);

cache.get(&"a".to_string()); // Hit
cache.get(&"b".to_string()); // Miss
cache.get(&"c".to_string()); // Miss

// 2 misses out of 3 total accesses = 66.67%
assert!((cache.statistics().miss_rate() - 66.66666666666666).abs() < f64::EPSILON);