Skip to main content

qualia_core_db/gpu_context/
reservation.rs

1//! Owned VRAM reservations for cold renderer resources.
2//!
3//! Telemetry snapshots (`record_render`, `record_tensor`, etc.) describe already
4//! resident subsystems. These guards account for additional allocations whose
5//! lifetime is explicit, and release their bytes on replacement or drop.
6
7use super::{ComputeUniverse, UniverseOrchestrator, VramLedger, VramLedgerSlot};
8use etalon_resources::reservation::{AdmissionLimits, Reservation, ReservationError};
9
10#[repr(u8)]
11#[derive(Clone, Copy, Debug, PartialEq, Eq)]
12pub enum VramResourceClass {
13    Geometry = 0,
14    TextureResidency = 1,
15    FrameTarget = 2,
16    UploadStaging = 3,
17    RecoveryCopy = 4,
18    /// Persistent tensor and scientific-field storage buffers owned by the viewport.
19    FieldResidency = 5,
20}
21
22impl VramResourceClass {
23    const fn index(self) -> usize {
24        self as usize
25    }
26}
27
28#[derive(Clone, Copy, Debug, PartialEq, Eq)]
29pub struct GraphicsReservationError {
30    pub requested_bytes: u64,
31    pub available_bytes: u64,
32}
33
34impl std::fmt::Display for GraphicsReservationError {
35    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
36        write!(
37            f,
38            "graphics reservation refused: requested {} bytes, {} available",
39            self.requested_bytes, self.available_bytes
40        )
41    }
42}
43
44impl std::error::Error for GraphicsReservationError {}
45
46/// RAII byte reservation against the process-wide adapter budget.
47#[derive(Debug)]
48pub struct VramReservation<'a> {
49    ledger: &'a VramLedger,
50    reservation: Option<Reservation<'a, 6>>,
51}
52
53impl VramLedger {
54    /// Atomically admit an additional graphics allocation against the existing
55    /// shared inference/render budget. Call only before the cold allocation.
56    pub fn try_reserve_graphics(
57        &self,
58        class: VramResourceClass,
59        bytes: u64,
60    ) -> Result<VramReservation<'_>, GraphicsReservationError> {
61        let budget = self.budget();
62        let recorded = self.recorded_used_bytes();
63        let viewport_recorded = self.used_in_slot(VramLedgerSlot::Viewport);
64        let viewport_budget = UniverseOrchestrator::from_total_budget(budget, self.mode())
65            .partition(ComputeUniverse::Viewport)
66            .vram_budget_bytes;
67        let reservation = self
68            .graphics_reservations
69            .try_reserve(
70                class.index(),
71                bytes,
72                AdmissionLimits {
73                    global_capacity: budget,
74                    global_recorded: recorded,
75                    partition_capacity: viewport_budget,
76                    partition_recorded: viewport_recorded,
77                },
78            )
79            .map_err(|error| match error {
80                ReservationError::BudgetExceeded {
81                    requested_bytes,
82                    available_bytes,
83                }
84                | ReservationError::ArithmeticOverflow {
85                    requested_bytes,
86                    available_bytes,
87                } => GraphicsReservationError {
88                    requested_bytes,
89                    available_bytes,
90                },
91                ReservationError::InvalidClass { .. } => GraphicsReservationError {
92                    requested_bytes: bytes,
93                    available_bytes: 0,
94                },
95            })?;
96        self.refresh_mode();
97        Ok(VramReservation {
98            ledger: self,
99            reservation: Some(reservation),
100        })
101    }
102
103    /// Live reservations in one resource class, for diagnostics and admission tests.
104    pub fn reserved_graphics_bytes(&self, class: VramResourceClass) -> u64 {
105        self.graphics_reservations
106            .class_bytes(class.index())
107            .unwrap_or(0)
108    }
109}
110
111impl Drop for VramReservation<'_> {
112    fn drop(&mut self) {
113        drop(self.reservation.take());
114        self.ledger.refresh_mode();
115    }
116}
117
118#[cfg(test)]
119mod tests {
120    use super::*;
121    use crate::gpu_context::VramLedgerSlot;
122
123    #[test]
124    fn reservations_compete_with_shared_recorded_usage_and_release_on_drop() {
125        let ledger = VramLedger::new(1_000);
126        ledger.record_slot(VramLedgerSlot::LlmKvCache, 200);
127        let field = ledger
128            .try_reserve_graphics(VramResourceClass::FieldResidency, 90)
129            .unwrap();
130        assert_eq!(ledger.used_bytes(), 290);
131        assert_eq!(ledger.universe_used_bytes(ComputeUniverse::Viewport), 90);
132        assert_eq!(
133            ledger.reserved_graphics_bytes(VramResourceClass::FieldResidency),
134            90
135        );
136        assert_eq!(
137            ledger
138                .try_reserve_graphics(VramResourceClass::FrameTarget, 61)
139                .unwrap_err(),
140            GraphicsReservationError {
141                requested_bytes: 61,
142                available_bytes: 60,
143            }
144        );
145        drop(field);
146        assert_eq!(ledger.used_bytes(), 200);
147        assert_eq!(ledger.universe_used_bytes(ComputeUniverse::Viewport), 0);
148        let _frame = ledger
149            .try_reserve_graphics(VramResourceClass::FrameTarget, 150)
150            .unwrap();
151    }
152
153    #[test]
154    fn reservation_refuses_over_budget_without_mutating_accounting() {
155        let ledger = VramLedger::new(u64::MAX);
156        assert!(ledger
157            .try_reserve_graphics(VramResourceClass::Geometry, u64::MAX)
158            .is_err());
159        let small = ledger
160            .try_reserve_graphics(VramResourceClass::RecoveryCopy, 1)
161            .expect("failed oversized reservation must leave capacity available");
162        drop(small);
163        assert_eq!(ledger.used_bytes(), 0);
164    }
165}