ferrum_interfaces/vnext/resource/
maintenance_boundary.rs

1use serde::Serialize;
2
3use super::{
4    BackingChunkIdentity, CapacityDomainId, CapacityVector, DynamicBackingPackingEnvelope,
5    DynamicBackingPoolId, DynamicPoolLiveOccupancyStatus, LogicalAdmissionCoordinatorId,
6};
7use crate::vnext::DeviceCapacityPressure;
8
9pub const DYNAMIC_POOL_MAINTENANCE_BOUNDARY_SCHEMA_VERSION: u32 = 1;
10
11/// One resident chunk as observed while every pool maintenance/state lock is
12/// held and before a pressure-driven rebalance mutates residency.
13#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
14pub struct DynamicPoolMaintenanceBoundaryChunk {
15    pub(in crate::vnext::resource) identity: BackingChunkIdentity,
16    pub(in crate::vnext::resource) bytes: u64,
17    pub(in crate::vnext::resource) live_segments: u64,
18    pub(in crate::vnext::resource) external_references: usize,
19    pub(in crate::vnext::resource) protected_packing: bool,
20    pub(in crate::vnext::resource) full_extent_available: bool,
21    pub(in crate::vnext::resource) resident_floor_allows_reclaim: bool,
22    pub(in crate::vnext::resource) reclaim_candidate: bool,
23}
24
25impl DynamicPoolMaintenanceBoundaryChunk {
26    pub fn identity(&self) -> &BackingChunkIdentity {
27        &self.identity
28    }
29
30    pub const fn bytes(&self) -> u64 {
31        self.bytes
32    }
33
34    pub const fn live_segments(&self) -> u64 {
35        self.live_segments
36    }
37
38    pub const fn external_references(&self) -> usize {
39        self.external_references
40    }
41
42    pub const fn protected_packing(&self) -> bool {
43        self.protected_packing
44    }
45
46    pub const fn full_extent_available(&self) -> bool {
47        self.full_extent_available
48    }
49
50    pub const fn resident_floor_allows_reclaim(&self) -> bool {
51        self.resident_floor_allows_reclaim
52    }
53
54    pub const fn reclaim_candidate(&self) -> bool {
55        self.reclaim_candidate
56    }
57}
58
59/// Event-bound physical and logical state for one pool at a failed device
60/// reservation. Consumers can recompute the complete reclaim frontier instead
61/// of inferring it from a later health snapshot.
62#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
63pub struct DynamicPoolMaintenanceBoundaryPool {
64    pub(in crate::vnext::resource) pool_id: DynamicBackingPoolId,
65    pub(in crate::vnext::resource) domain_id: CapacityDomainId,
66    pub(in crate::vnext::resource) excluded_from_reclaim: bool,
67    pub(in crate::vnext::resource) resident_bytes: u64,
68    pub(in crate::vnext::resource) pending_growth_bytes: u64,
69    pub(in crate::vnext::resource) free_bytes: u64,
70    pub(in crate::vnext::resource) largest_contiguous_bytes: u64,
71    pub(in crate::vnext::resource) free_extent_layout_fingerprint: String,
72    pub(in crate::vnext::resource) logical_used_bytes: u64,
73    pub(in crate::vnext::resource) live_occupancy: DynamicPoolLiveOccupancyStatus,
74    pub(in crate::vnext::resource) minimum_resident_bytes: u64,
75    pub(in crate::vnext::resource) maximum_resident_bytes: u64,
76    pub(in crate::vnext::resource) protected_immediate_bytes: u64,
77    pub(in crate::vnext::resource) protected_packing_satisfied: bool,
78    pub(in crate::vnext::resource) coherent_runnable_floor_bytes: u64,
79    pub(in crate::vnext::resource) resident_floor_bytes: u64,
80    pub(in crate::vnext::resource) reclaimable_bytes: u64,
81    pub(in crate::vnext::resource) chunks: Vec<DynamicPoolMaintenanceBoundaryChunk>,
82}
83
84impl DynamicPoolMaintenanceBoundaryPool {
85    pub fn pool_id(&self) -> &DynamicBackingPoolId {
86        &self.pool_id
87    }
88
89    pub const fn domain_id(&self) -> CapacityDomainId {
90        self.domain_id
91    }
92
93    pub const fn excluded_from_reclaim(&self) -> bool {
94        self.excluded_from_reclaim
95    }
96
97    pub const fn resident_bytes(&self) -> u64 {
98        self.resident_bytes
99    }
100
101    pub const fn pending_growth_bytes(&self) -> u64 {
102        self.pending_growth_bytes
103    }
104
105    pub const fn free_bytes(&self) -> u64 {
106        self.free_bytes
107    }
108
109    pub const fn largest_contiguous_bytes(&self) -> u64 {
110        self.largest_contiguous_bytes
111    }
112
113    pub fn free_extent_layout_fingerprint(&self) -> &str {
114        &self.free_extent_layout_fingerprint
115    }
116
117    pub const fn logical_used_bytes(&self) -> u64 {
118        self.logical_used_bytes
119    }
120
121    pub const fn live_occupancy(&self) -> &DynamicPoolLiveOccupancyStatus {
122        &self.live_occupancy
123    }
124
125    pub const fn minimum_resident_bytes(&self) -> u64 {
126        self.minimum_resident_bytes
127    }
128
129    pub const fn maximum_resident_bytes(&self) -> u64 {
130        self.maximum_resident_bytes
131    }
132
133    pub const fn protected_immediate_bytes(&self) -> u64 {
134        self.protected_immediate_bytes
135    }
136
137    pub const fn protected_packing_satisfied(&self) -> bool {
138        self.protected_packing_satisfied
139    }
140
141    pub const fn coherent_runnable_floor_bytes(&self) -> u64 {
142        self.coherent_runnable_floor_bytes
143    }
144
145    pub const fn resident_floor_bytes(&self) -> u64 {
146        self.resident_floor_bytes
147    }
148
149    pub const fn reclaimable_bytes(&self) -> u64 {
150        self.reclaimable_bytes
151    }
152
153    pub fn chunks(&self) -> &[DynamicPoolMaintenanceBoundaryChunk] {
154        &self.chunks
155    }
156}
157
158/// Atomic cold-path receipt for the exact capacity boundary that caused a
159/// rebalance attempt. Selected chunks describe the planner decision before
160/// mutation; `reclaim_sufficient=false` is the typed reason maintenance must
161/// wait for a release epoch instead of retrying allocation.
162#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
163pub struct DynamicPoolMaintenanceBoundaryReceipt {
164    pub(in crate::vnext::resource) schema_version: u32,
165    pub(in crate::vnext::resource) coordinator_id: LogicalAdmissionCoordinatorId,
166    pub(in crate::vnext::resource) logical_release_epoch: u64,
167    pub(in crate::vnext::resource) logical_capacity_epoch: u64,
168    pub(in crate::vnext::resource) plan_device_capacity_epoch: u64,
169    pub(in crate::vnext::resource) process_device_capacity_epoch: u64,
170    pub(in crate::vnext::resource) pressure: DeviceCapacityPressure,
171    pub(in crate::vnext::resource) planned_domains: Vec<CapacityDomainId>,
172    pub(in crate::vnext::resource) protected_immediate: CapacityVector,
173    pub(in crate::vnext::resource) protected_packing_envelopes: Vec<DynamicBackingPackingEnvelope>,
174    pub(in crate::vnext::resource) pools: Vec<DynamicPoolMaintenanceBoundaryPool>,
175    pub(in crate::vnext::resource) reclaim_candidate_chunks: usize,
176    pub(in crate::vnext::resource) reclaim_candidate_bytes: u64,
177    pub(in crate::vnext::resource) selected_chunks: Vec<BackingChunkIdentity>,
178    pub(in crate::vnext::resource) selected_bytes: u64,
179    pub(in crate::vnext::resource) reclaim_sufficient: bool,
180}
181
182impl DynamicPoolMaintenanceBoundaryReceipt {
183    pub const fn schema_version(&self) -> u32 {
184        self.schema_version
185    }
186
187    pub const fn coordinator_id(&self) -> LogicalAdmissionCoordinatorId {
188        self.coordinator_id
189    }
190
191    pub const fn logical_release_epoch(&self) -> u64 {
192        self.logical_release_epoch
193    }
194
195    pub const fn logical_capacity_epoch(&self) -> u64 {
196        self.logical_capacity_epoch
197    }
198
199    pub const fn plan_device_capacity_epoch(&self) -> u64 {
200        self.plan_device_capacity_epoch
201    }
202
203    pub const fn process_device_capacity_epoch(&self) -> u64 {
204        self.process_device_capacity_epoch
205    }
206
207    pub const fn pressure(&self) -> &DeviceCapacityPressure {
208        &self.pressure
209    }
210
211    pub fn planned_domains(&self) -> &[CapacityDomainId] {
212        &self.planned_domains
213    }
214
215    pub const fn protected_immediate(&self) -> &CapacityVector {
216        &self.protected_immediate
217    }
218
219    pub fn protected_packing_envelopes(&self) -> &[DynamicBackingPackingEnvelope] {
220        &self.protected_packing_envelopes
221    }
222
223    pub fn pools(&self) -> &[DynamicPoolMaintenanceBoundaryPool] {
224        &self.pools
225    }
226
227    pub const fn reclaim_candidate_chunks(&self) -> usize {
228        self.reclaim_candidate_chunks
229    }
230
231    pub const fn reclaim_candidate_bytes(&self) -> u64 {
232        self.reclaim_candidate_bytes
233    }
234
235    pub fn selected_chunks(&self) -> &[BackingChunkIdentity] {
236        &self.selected_chunks
237    }
238
239    pub const fn selected_bytes(&self) -> u64 {
240        self.selected_bytes
241    }
242
243    pub const fn reclaim_sufficient(&self) -> bool {
244        self.reclaim_sufficient
245    }
246}
ferrum_interfaces/vnext/resource/maintenance_boundary.rs

ferrum_interfaces/vnext/resource/
maintenance_boundary.rs
