query_runtime/runtime/cache/
mod.rs

1//! GPU-resident cache ownership and lifecycle contracts.
2//!
3//! Cache implementations own their keys and GPU objects. This module owns the
4//! one state machine that makes their byte residency visible to the per-device
5//! ledger.
6
7use serde::Serialize;
8
9pub(crate) mod factory;
10#[doc(hidden)]
11pub mod local_parquet;
12pub(crate) mod residency;
13#[cfg(feature = "cugraph")]
14#[doc(hidden)]
15pub mod resident_graph;
16
17pub(crate) use factory::DeviceCacheAllocationFactory;
18pub(crate) use residency::{
19    CacheResidency, CacheResidencyChargeTransaction, CacheResidencyDestruction, CacheResidencyPin, CacheResidencyState,
20};
21
22/// Bounded, cache-owner event observation for one source-cache operation.
23///
24/// The source cache emits these from the same state machine that owns load
25/// claims and resident copies.  They are deliberately diagnostic facts and do
26/// not form a second residency ledger.  Byte authority remains with the paired
27/// device ledger.
28/// Both caller correlation and canonical source-key identity are one-way
29/// fingerprints so this public observation cannot disclose query identifiers
30/// or source locations.
31#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
32pub struct CacheSourceEventSnapshot {
33    /// Per-domain monotonically increasing event sequence.
34    pub(crate) sequence: u64,
35    pub(crate) device_ordinal: usize,
36    pub(crate) allocation_domain_id: u64,
37    /// Stable one-way fingerprint of the attempt's caller correlation, when
38    /// the execution context carried one.
39    pub(crate) correlation_fingerprint: Option<String>,
40    /// Stable one-way fingerprint of the exact canonical source-cache key.
41    pub(crate) cache_key_fingerprint: String,
42    /// Cache-state-machine action such as `load_leader`, `load_follower`,
43    /// `load_hit`, or `promotion_inserted`.
44    pub(crate) action: &'static str,
45    /// Bytes retained by an inserted source-cache promotion, if applicable.
46    pub(crate) retained_device_bytes: u64,
47}
48
49/// Produces the credential-free correlation token used by cache-owner event
50/// observations.  The same public function lets callers match an event to a
51/// correlation they supplied without exposing the original string.
52pub fn cache_observation_fingerprint(value: &str) -> String {
53    format!("b3:{}", blake3::hash(value.as_bytes()).to_hex())
54}
55
56/// Public, point-in-time observation of one device's resident-cache domain.
57///
58/// The physical fields are sampled directly from cuDF's one shared allocation
59/// domain.  The activity fields are cache-owned event counters and do not form
60/// a second byte ledger.  Resident-byte authority remains with the device ledger.
61#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
62pub struct DeviceCacheReport {
63    /// CUDA device whose cache domain was sampled.
64    pub device_ordinal: usize,
65    /// Shared native allocation domain used by this device's resident caches.
66    pub allocation_domain_id: u64,
67    /// Accounted cache-share limit in bytes.
68    pub cache_cap_bytes: u64,
69    /// The canonical ledger sequence sampled for this physical-domain report.
70    pub ledger_sequence: u64,
71    /// Cache-resident bytes eligible for eviction at the paired ledger sequence.
72    pub ledger_evictable_resident_bytes: u64,
73    /// Cache-resident bytes pinned by active use at the paired ledger sequence.
74    pub ledger_pinned_in_use_bytes: u64,
75    pub(crate) allocation_limit_bytes: u64,
76    /// Logical live allocation bytes sampled from the shared cache domain.
77    pub physical_current_bytes: u64,
78    pub(crate) physical_current_aligned_bytes: u64,
79    /// Highest logical live allocation bytes observed in the shared cache domain.
80    pub physical_peak_bytes: u64,
81    pub(crate) physical_total_bytes: u64,
82    pub(crate) physical_total_allocations: u64,
83    pub(crate) source: CacheSourceActivity,
84    /// Graph-cache activity counters for this device.
85    pub graph: CacheGraphActivity,
86}
87
88/// Cumulative source-cache activity and point-in-time key counts.
89#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
90pub struct CacheSourceActivity {
91    pub(crate) entry_count: usize,
92    pub(crate) promotions_in_progress: usize,
93    pub(crate) lookup_hits: u64,
94    pub(crate) lookup_misses: u64,
95    pub(crate) promotions_inserted: u64,
96    pub(crate) promotions_coalesced: u64,
97    pub(crate) promotions_capacity_skipped: u64,
98    pub(crate) promotions_allocation_failed: u64,
99    pub(crate) promoted_device_bytes: u64,
100    pub(crate) eviction_batches: u64,
101    pub(crate) evicted_device_bytes: u64,
102}
103
104/// Cumulative graph-cache activity and point-in-time key counts.
105#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
106pub struct CacheGraphActivity {
107    /// Graph entries currently available for checkout.
108    pub available_entries: usize,
109    /// Graph entries currently held by active callers.
110    pub checked_out_entries: usize,
111    /// Active pins that retain graph entries during preparation.
112    pub preparation_pins: usize,
113    /// Cumulative graph-cache lookups that found a matching entry.
114    pub lookup_hits: u64,
115    pub(crate) lookup_misses: u64,
116    /// Cumulative graph entries inserted into the cache.
117    pub insertions: u64,
118    pub(crate) duplicate_inserts: u64,
119}
query_runtime/runtime/cache/mod.rs

query_runtime/runtime/cache/
mod.rs
