tenferro_tensor/
cache.rs

1//! Cache accounting primitives shared by tensor backends and facade runtimes.
2
3/// Entry, retained-byte, and event accounting for one cache.
4///
5/// `retained_bytes` reports the cache-owned logical payload estimate. It does
6/// not include allocator arena slack, operating-system RSS, or memory retained
7/// by unrelated process allocators.
8///
9/// # Examples
10///
11/// ```
12/// use tenferro_tensor::CacheStats;
13///
14/// let stats = CacheStats {
15///     entries: 2,
16///     retained_bytes: 128,
17///     hits: 3,
18///     misses: 4,
19///     evictions: 0,
20///     clears: 0,
21/// };
22/// assert_eq!(stats.entries, 2);
23/// assert_eq!(stats.retained_bytes, 128);
24/// assert_eq!(stats.hits, 3);
25/// ```
26#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
27pub struct CacheStats {
28    /// Number of cache entries currently retained.
29    pub entries: usize,
30    /// Cache-owned retained payload estimate in bytes.
31    pub retained_bytes: usize,
32    /// Successful cache lookups.
33    pub hits: u64,
34    /// Failed cache lookups or typed lookup mismatches.
35    pub misses: u64,
36    /// Entries evicted by cache retention limits.
37    pub evictions: u64,
38    /// Explicit cache clear operations.
39    pub clears: u64,
40}
41
42impl CacheStats {
43    /// Return an empty stats snapshot.
44    ///
45    /// # Examples
46    ///
47    /// ```
48    /// use tenferro_tensor::CacheStats;
49    ///
50    /// let stats = CacheStats::empty();
51    /// assert_eq!(stats.entries, 0);
52    /// assert_eq!(stats.retained_bytes, 0);
53    /// ```
54    pub fn empty() -> Self {
55        Self::default()
56    }
57}
58
59/// Control surface required for backend runtime caches owned by higher-level runtimes.
60///
61/// Backend caches use this trait so higher-level runtimes and executors can
62/// clear and inspect the cache without knowing backend-specific entry types.
63///
64/// # Examples
65///
66/// ```
67/// use tenferro_tensor::{CacheStats, RuntimeCacheControl};
68///
69/// let mut cache = ();
70/// assert_eq!(cache.stats(), CacheStats::empty());
71/// cache.clear();
72/// assert_eq!(cache.stats().entries, 0);
73/// ```
74pub trait RuntimeCacheControl: Default {
75    /// Remove every retained cache entry.
76    fn clear(&mut self);
77
78    /// Snapshot retained entries and retained bytes.
79    fn stats(&self) -> CacheStats;
80}
81
82impl RuntimeCacheControl for () {
83    fn clear(&mut self) {}
84
85    fn stats(&self) -> CacheStats {
86        CacheStats::empty()
87    }
88}
89
90#[cfg(test)]
91mod tests;
tenferro_tensor/cache.rs

tenferro_tensor/
cache.rs
