Skip to main content

qualia_core_db/net/qdnf/cells/
scaling.rs

1//! In-process 1..=16 cell scaling under one host budget (E10.5).
2//!
3//! Admission is fair-share: a greedy request is capped so remaining cohort
4//! cells keep an equal floor of leftover bytes. RSS and NUMA live in
5//! [`super::hardware`]. Idle joules stay unmeasured.
6//!
7//! Tests charge KiB-scale [`CellProfile::NetworkSmall`] slots. The 42 MiB
8//! Sentinel figure stays in [`super::pass_budget`] as accounting.
9
10#[cfg(test)]
11use crate::net::peer::cells::admit::CellProfile;
12use crate::net::peer::cells::admit::{CellSlot, MAX_CELLS};
13use crate::net::peer::cells::host_owner::HostAdmission;
14use crate::net::qdnf::errors::QdnfError;
15
16/// Production occupancy. A 17th cell is [`QdnfError::Capacity`].
17pub const MAX_SCALE_CELLS: usize = MAX_CELLS;
18
19/// Hardware counters this slice does not collect. Never treat as zero.
20#[repr(u8)]
21#[derive(Clone, Copy, Debug, PartialEq, Eq)]
22pub enum HardwareObservation {
23    Unsupported = 0,
24    Unmeasured = 1,
25}
26
27/// Equal-share cap for one request among `remaining_cells` still to admit.
28///
29/// `remaining_cells` includes the caller. Others keep at least
30/// `floor(remaining_bytes / remaining_cells)` each. Remainder may go to this
31/// request. 0 or more than [`MAX_SCALE_CELLS`] is [`QdnfError::Capacity`].
32pub fn fair_grant(
33    remaining_bytes: u64,
34    remaining_cells: usize,
35    requested: u64,
36) -> Result<u64, QdnfError> {
37    if remaining_cells == 0 || remaining_cells > MAX_SCALE_CELLS {
38        return Err(QdnfError::Capacity);
39    }
40    if requested == 0 {
41        return Err(QdnfError::Capacity);
42    }
43    let n = remaining_cells as u64;
44    let floor = remaining_bytes / n;
45    if floor == 0 {
46        return Err(QdnfError::BudgetExhausted);
47    }
48    let others = n - 1;
49    let reserved = floor.checked_mul(others).ok_or(QdnfError::Capacity)?;
50    let max_this = remaining_bytes.saturating_sub(reserved);
51    Ok(requested.min(max_this))
52}
53
54/// One host owner plus fair cell admission (1..=16).
55pub struct ScaleHost {
56    host: HostAdmission,
57}
58
59impl ScaleHost {
60    /// Creates a default `ScaleHost`.
61    pub fn new(host_bytes: u64) -> Result<Self, QdnfError> {
62        Ok(Self {
63            host: HostAdmission::new(host_bytes)?,
64        })
65    }
66
67    #[inline]
68    /// Occupied count.
69    pub fn occupied(&self) -> usize {
70        self.host.occupied_cells()
71    }
72
73    #[inline]
74    /// `ScaleHost::remaining_bytes`.
75    pub fn remaining_bytes(&self) -> u64 {
76        self.host.remaining_host_bytes()
77    }
78
79    #[inline]
80    /// `ScaleHost::remaining_slots`.
81    pub fn remaining_slots(&self) -> usize {
82        MAX_SCALE_CELLS.saturating_sub(self.occupied())
83    }
84
85    /// Admit `requested` bytes, reserving equal floors for the rest of the
86    /// cohort (`cohort_remaining` includes this cell).
87    pub fn admit_fair(
88        &mut self,
89        requested: u64,
90        cohort_remaining: usize,
91    ) -> Result<CellSlot, QdnfError> {
92        if self.remaining_slots() == 0 {
93            return Err(QdnfError::Capacity);
94        }
95        if cohort_remaining > self.remaining_slots() {
96            return Err(QdnfError::Capacity);
97        }
98        let grant = fair_grant(self.remaining_bytes(), cohort_remaining, requested)?;
99        let profile = HostAdmission::profile_for_bytes(grant)?;
100        self.host.admit_cell(profile, grant)
101    }
102
103    /// Admit `n` equal cells (1..=16) of `per_cell` bytes.
104    pub fn admit_equal(
105        &mut self,
106        n: usize,
107        per_cell: u64,
108        out: &mut [Option<CellSlot>; MAX_SCALE_CELLS],
109    ) -> Result<usize, QdnfError> {
110        if n == 0 || n > MAX_SCALE_CELLS {
111            return Err(QdnfError::Capacity);
112        }
113        let mut i = 0usize;
114        while i < n {
115            out[i] = Some(self.admit_fair(per_cell, n - i)?);
116            i += 1;
117        }
118        Ok(n)
119    }
120
121    /// Releases the resource.
122    pub fn release(&mut self, slot: CellSlot) -> Result<(), QdnfError> {
123        self.host.release_cell(slot)
124    }
125}
126
127#[cfg(test)]
128mod tests {
129    use super::*;
130    use crate::net::qdnf::cells::pass_budget::SENTINEL_PASS_TOTAL;
131    use crate::net::qdnf::errors::QdnfError;
132
133    const CELL: u64 = 64;
134
135    #[test]
136    fn sixteen_cells_admitted_seventeenth_rejected() {
137        assert!(16 * CELL < SENTINEL_PASS_TOTAL);
138        let mut host = ScaleHost::new(MAX_SCALE_CELLS as u64 * CELL).unwrap();
139        let mut out = [None; MAX_SCALE_CELLS];
140        let n = host
141            .admit_equal(MAX_SCALE_CELLS, CELL, &mut out)
142            .expect("16 cells");
143        assert_eq!(n, MAX_SCALE_CELLS);
144        assert_eq!(host.occupied(), MAX_SCALE_CELLS);
145        assert_eq!(host.remaining_slots(), 0);
146        assert_eq!(host.admit_fair(CELL, 1), Err(QdnfError::Capacity));
147        assert_eq!(host.occupied(), MAX_SCALE_CELLS);
148        let mut i = 0usize;
149        while i < MAX_SCALE_CELLS {
150            assert_eq!(out[i].unwrap().bytes, CELL);
151            assert_eq!(out[i].unwrap().profile, CellProfile::NetworkSmall);
152            i += 1;
153        }
154    }
155
156    #[test]
157    fn greedy_cell_cannot_starve_remaining_budget() {
158        let budget = MAX_SCALE_CELLS as u64 * CELL;
159        let mut host = ScaleHost::new(budget).unwrap();
160        let greedy = host
161            .admit_fair(budget, MAX_SCALE_CELLS)
162            .expect("greedy is capped, not rejected");
163        assert_eq!(greedy.bytes, CELL);
164        assert!(greedy.bytes < budget);
165        assert_eq!(host.remaining_bytes(), 15 * CELL);
166        let mut i = 0usize;
167        while i < 15 {
168            let slot = host
169                .admit_fair(CELL, 15 - i)
170                .expect("remaining cohort keeps a floor share");
171            assert_eq!(slot.bytes, CELL);
172            i += 1;
173        }
174        assert_eq!(host.occupied(), MAX_SCALE_CELLS);
175        assert_eq!(host.remaining_bytes(), 0);
176    }
177
178    #[test]
179    fn scale_one_two_four_eight_sixteen() {
180        let counts = [1usize, 2, 4, 8, 16];
181        let mut c = 0usize;
182        while c < counts.len() {
183            let n = counts[c];
184            let mut host = ScaleHost::new(n as u64 * CELL).unwrap();
185            let mut out = [None; MAX_SCALE_CELLS];
186            assert_eq!(host.admit_equal(n, CELL, &mut out).unwrap(), n);
187            assert_eq!(host.occupied(), n);
188            c += 1;
189        }
190    }
191
192    #[test]
193    fn fair_grant_rejects_seventeenth_and_zero() {
194        assert_eq!(fair_grant(CELL, 0, CELL), Err(QdnfError::Capacity));
195        assert_eq!(
196            fair_grant(CELL, MAX_SCALE_CELLS + 1, CELL),
197            Err(QdnfError::Capacity)
198        );
199        assert_eq!(fair_grant(CELL, 1, 0), Err(QdnfError::Capacity));
200        assert_eq!(
201            fair_grant(MAX_SCALE_CELLS as u64 - 1, MAX_SCALE_CELLS, 1),
202            Err(QdnfError::BudgetExhausted)
203        );
204    }
205
206    #[test]
207    fn remainder_goes_to_current_without_starving_floor() {
208        let budget = 16 * CELL + 15;
209        assert_eq!(fair_grant(budget, 16, budget).unwrap(), CELL + 15);
210        let mut host = ScaleHost::new(budget).unwrap();
211        let greedy = host.admit_fair(budget, 16).unwrap();
212        assert_eq!(greedy.bytes, CELL + 15);
213        assert_eq!(host.remaining_bytes(), 15 * CELL);
214        let mut out = [None; MAX_SCALE_CELLS];
215        assert_eq!(host.admit_equal(15, CELL, &mut out).unwrap(), 15);
216        assert_eq!(host.occupied(), 16);
217    }
218}