Skip to main content

qualia_core_db/render/gpu/
residency_budget.rs

1//! Residency metadata is maintained by Etalon; Qualia owns resource policy and lifetime.
2
3pub use etalon_resources::residency::{
4    ResidencyError, ResidencyGovernor, ResidencyPoolCaps, ResidencySlot,
5};
6
7#[cfg(test)]
8mod tests {
9    use super::*;
10    #[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
11    use crate::specialized_libs::computational_geometry::allocation_counter::assert_zero_alloc;
12
13    #[test]
14    fn admit_within_caps_and_lru_eviction() {
15        let caps = ResidencyPoolCaps {
16            max_cpu_bytes: 1000,
17            max_gpu_vram_bytes: 2000,
18        };
19        let mut gov = ResidencyGovernor::<3>::new(caps);
20
21        // Admit slot 1 at tick 10 (400 CPU, 800 GPU)
22        gov.admit_or_evict_lru_zero_heap(0x101, 400, 800, false, 10)
23            .unwrap();
24        // Admit slot 2 at tick 20 (400 CPU, 800 GPU)
25        gov.admit_or_evict_lru_zero_heap(0x102, 400, 800, false, 20)
26            .unwrap();
27
28        assert_eq!(gov.occupied_slots(), 2);
29        assert_eq!(gov.current_cpu_bytes(), 800);
30        assert_eq!(gov.current_gpu_vram_bytes(), 1600);
31
32        // Touch slot 1 at tick 30 (making slot 2 the LRU candidate with tick 20)
33        assert!(gov.touch(0x101, 30));
34
35        // Admit slot 3 needing 400 CPU, 800 GPU: exceeds total CPU (800+400=1200 > 1000)
36        // Must evict slot 2 (tick 20), keeping slot 1 (tick 30)
37        gov.admit_or_evict_lru_zero_heap(0x103, 400, 800, false, 40)
38            .unwrap();
39
40        assert_eq!(gov.occupied_slots(), 2);
41        assert!(gov.contains(0x101));
42        assert!(!gov.contains(0x102));
43        assert!(gov.contains(0x103));
44    }
45
46    #[test]
47    fn mandatory_negative_request_exceeds_caps() {
48        let caps = ResidencyPoolCaps {
49            max_cpu_bytes: 500,
50            max_gpu_vram_bytes: 1000,
51        };
52        let mut gov = ResidencyGovernor::<4>::new(caps);
53
54        // CPU exceeds total cap
55        let err_cpu = gov
56            .admit_or_evict_lru_zero_heap(0x1, 501, 100, false, 1)
57            .unwrap_err();
58        match err_cpu {
59            ResidencyError::ResidencyBudgetExceeded { requested_cpu, .. } => {
60                assert_eq!(requested_cpu, 501)
61            }
62            other => panic!("unexpected: {other:?}"),
63        }
64
65        // GPU exceeds total cap
66        let err_gpu = gov
67            .admit_or_evict_lru_zero_heap(0x2, 100, 1001, false, 1)
68            .unwrap_err();
69        match err_gpu {
70            ResidencyError::ResidencyBudgetExceeded { requested_gpu, .. } => {
71                assert_eq!(requested_gpu, 1001)
72            }
73            other => panic!("unexpected: {other:?}"),
74        }
75    }
76
77    #[test]
78    fn mandatory_negative_pinned_headroom_fails_closed() {
79        let caps = ResidencyPoolCaps {
80            max_cpu_bytes: 1000,
81            max_gpu_vram_bytes: 2000,
82        };
83        let mut gov = ResidencyGovernor::<4>::new(caps);
84
85        // Pin resource 0xAAA with 800 CPU, 1500 GPU
86        gov.admit_or_evict_lru_zero_heap(0xAAA, 800, 1500, true, 10)
87            .unwrap();
88        // Unpinned resource 0xBBB with 100 CPU, 200 GPU
89        gov.admit_or_evict_lru_zero_heap(0xBBB, 100, 200, false, 20)
90            .unwrap();
91
92        // New request: 300 CPU. Even evicting 0xBBB leaves only 200 CPU available (1000 - 800)
93        let err = gov
94            .admit_or_evict_lru_zero_heap(0xCCC, 300, 100, false, 30)
95            .unwrap_err();
96        match err {
97            ResidencyError::ResidencyBudgetExceeded {
98                requested_cpu,
99                available_cpu,
100                ..
101            } => {
102                assert_eq!(requested_cpu, 300);
103                assert_eq!(available_cpu, 200);
104            }
105            other => panic!("unexpected: {other:?}"),
106        }
107
108        // Pinned resource 0xAAA must NOT be evicted or mutated
109        assert!(gov.contains(0xAAA));
110        assert!(gov.get_slot(0xAAA).unwrap().pinned);
111    }
112
113    #[test]
114    fn release_and_cancel_pending_hydration() {
115        let caps = ResidencyPoolCaps {
116            max_cpu_bytes: 1000,
117            max_gpu_vram_bytes: 1000,
118        };
119        let mut gov = ResidencyGovernor::<4>::new(caps);
120
121        gov.admit_or_evict_lru_zero_heap(0x123, 250, 250, false, 1)
122            .unwrap();
123        assert!(gov.contains(0x123));
124
125        gov.cancel_pending_hydration(0x123).unwrap();
126        assert!(!gov.contains(0x123));
127        assert_eq!(gov.current_cpu_bytes(), 0);
128        assert_eq!(gov.current_gpu_vram_bytes(), 0);
129
130        assert_eq!(
131            gov.release_resource(0x999),
132            Err(ResidencyError::ResourceNotFound(0x999))
133        );
134    }
135
136    #[test]
137    #[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
138    fn zero_alloc_residency_governor() {
139        let caps = ResidencyPoolCaps {
140            max_cpu_bytes: 2048,
141            max_gpu_vram_bytes: 4096,
142        };
143        let mut gov = ResidencyGovernor::<8>::new(caps);
144
145        assert_zero_alloc("residency_governor_admit_evict", || {
146            let _ = gov.admit_or_evict_lru_zero_heap(0x100, 256, 512, false, 1);
147            let _ = gov.admit_or_evict_lru_zero_heap(0x200, 512, 1024, true, 2);
148            let _ = gov.touch(0x100, 3);
149            let _ = gov.pin_resource(0x100, true);
150            let _ = gov.release_resource(0x100);
151        });
152    }
153}