Skip to main content

qualia_core_db/solvers/calculus/
workspace.rs

1//! Caller-owned calculus workspace accounting.
2
3pub const SENTINEL_PASS_BYTES: usize = 42 * 1024 * 1024;
4
5#[derive(Debug, Clone, Copy, PartialEq, Eq)]
6pub enum WorkspaceError {
7    SizeOverflow,
8    SentinelExceeded { required: usize },
9    BufferTooSmall { required: usize, available: usize },
10}
11
12/// `?::checked_workspace_bytes`.
13pub const fn checked_workspace_bytes<T>(elements: usize) -> Result<usize, WorkspaceError> {
14    let Some(required) = elements.checked_mul(core::mem::size_of::<T>()) else {
15        return Err(WorkspaceError::SizeOverflow);
16    };
17    if required > SENTINEL_PASS_BYTES {
18        return Err(WorkspaceError::SentinelExceeded { required });
19    }
20    Ok(required)
21}
22
23pub struct Workspace<'a, T> {
24    storage: &'a mut [T],
25    used: usize,
26}
27
28impl<'a, T> Workspace<'a, T> {
29    /// Creates a default `Workspace`.
30    pub fn new(storage: &'a mut [T]) -> Result<Self, WorkspaceError> {
31        checked_workspace_bytes::<T>(storage.len())?;
32        Ok(Self { storage, used: 0 })
33    }
34
35    /// Maximum capacity.
36    pub const fn capacity(&self) -> usize {
37        self.storage.len()
38    }
39
40    /// `Workspace::used`.
41    pub const fn used(&self) -> usize {
42        self.used
43    }
44
45    /// Remaining amount.
46    pub const fn remaining(&self) -> usize {
47        self.storage.len() - self.used
48    }
49
50    /// Resets state.
51    pub fn reset(&mut self) {
52        self.used = 0;
53    }
54
55    /// `Workspace::take`.
56    pub fn take(&mut self, elements: usize) -> Result<&mut [T], WorkspaceError> {
57        let end = self
58            .used
59            .checked_add(elements)
60            .ok_or(WorkspaceError::SizeOverflow)?;
61        if end > self.storage.len() {
62            return Err(WorkspaceError::BufferTooSmall {
63                required: end,
64                available: self.storage.len(),
65            });
66        }
67        let start = self.used;
68        self.used = end;
69        Ok(&mut self.storage[start..end])
70    }
71}
72
73#[cfg(test)]
74mod tests {
75    use super::*;
76
77    #[test]
78    fn workspace_is_caller_owned_and_resettable() {
79        let mut storage = [0.0_f64; 16];
80        let mut workspace = Workspace::new(&mut storage).unwrap();
81        assert_eq!(workspace.take(5).unwrap().len(), 5);
82        assert_eq!(workspace.used(), 5);
83        assert_eq!(workspace.remaining(), 11);
84        workspace.reset();
85        assert_eq!(workspace.used(), 0);
86    }
87
88    #[test]
89    fn sentinel_and_capacity_fail_closed() {
90        assert!(matches!(
91            checked_workspace_bytes::<u64>(SENTINEL_PASS_BYTES / 8 + 1),
92            Err(WorkspaceError::SentinelExceeded { .. })
93        ));
94        let mut storage = [0_u32; 4];
95        let mut workspace = Workspace::new(&mut storage).unwrap();
96        assert_eq!(
97            workspace.take(5),
98            Err(WorkspaceError::BufferTooSmall {
99                required: 5,
100                available: 4
101            })
102        );
103    }
104}