Skip to main content

qualia_core_db/net/peer/runtime/
cancel.rs

1//! Operation identity, cancel epoch, and late-completion rules.
2//!
3//! A completion after cancel releases outstanding storage but cannot resurrect
4//! the operation. A stale generation is rejected. Cancellation alone does not
5//! make a live I/O lease reusable until `complete` (or an equivalent release)
6//! runs.
7
8use crate::net::qdnf::errors::QdnfError;
9use crate::net::qdnf::types::{Generation, OperationId};
10
11use super::handles::LeaseHandle;
12use super::leases::LeaseTable;
13
14const OPS: usize = 32;
15mod incarnation;
16mod inspect;
17
18/// Non-wrapping cancel epoch bound to an admitted operation.
19#[repr(transparent)]
20#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
21pub struct CancelEpoch(pub u64);
22
23impl CancelEpoch {
24    pub const ZERO: Self = Self(0);
25
26    #[inline]
27    /// Next item.
28    pub const fn next(self) -> Result<Self, QdnfError> {
29        match self.0.checked_add(1) {
30            Some(n) => Ok(Self(n)),
31            None => Err(QdnfError::StaleGeneration),
32        }
33    }
34}
35
36#[repr(C)]
37#[derive(Clone, Copy, Debug, PartialEq, Eq)]
38pub struct OperationHandle {
39    pub id: OperationId,
40    pub generation: Generation,
41    pub cancel_epoch: CancelEpoch,
42}
43
44#[derive(Clone, Copy)]
45struct OpSlot {
46    id: OperationId,
47    generation: Generation,
48    cancel_epoch: CancelEpoch,
49    lease: LeaseHandle,
50    occupied: bool,
51    cancelled: bool,
52    storage_held: bool,
53}
54
55pub struct OperationTable {
56    incarnation: super::incarnation::CanonicalIncarnation,
57    slots: [OpSlot; OPS],
58}
59
60impl OperationTable {
61    /// Creates a default `OperationTable`.
62    pub const fn new() -> Self {
63        Self {
64            incarnation: super::incarnation::CanonicalIncarnation::UNASSIGNED,
65            slots: [OpSlot {
66                id: OperationId::ZERO,
67                generation: Generation::ZERO,
68                cancel_epoch: CancelEpoch::ZERO,
69                lease: LeaseHandle::INVALID,
70                occupied: false,
71                cancelled: false,
72                storage_held: false,
73            }; OPS],
74        }
75    }
76
77    /// Admits an operation; error at capacity.
78    pub fn admit(
79        &mut self,
80        id: OperationId,
81        lease: LeaseHandle,
82    ) -> Result<OperationHandle, QdnfError> {
83        if id == OperationId::ZERO {
84            return Err(QdnfError::Malformed);
85        }
86        for slot in &self.slots {
87            if slot.occupied && slot.id == id {
88                return Err(QdnfError::Conflict);
89            }
90        }
91        for slot in &mut self.slots {
92            if slot.occupied {
93                continue;
94            }
95            let generation = slot.generation.next()?;
96            *slot = OpSlot {
97                id,
98                generation,
99                cancel_epoch: CancelEpoch::ZERO,
100                lease,
101                occupied: true,
102                cancelled: false,
103                storage_held: true,
104            };
105            return Ok(OperationHandle {
106                id,
107                generation,
108                cancel_epoch: CancelEpoch::ZERO,
109            });
110        }
111        Err(QdnfError::Capacity)
112    }
113
114    /// Cancels `id`, returning the epoch.
115    pub fn cancel(&mut self, id: OperationId) -> Result<CancelEpoch, QdnfError> {
116        let slot = self.find_mut(id).ok_or(QdnfError::Closed)?;
117        if slot.cancelled {
118            return Ok(slot.cancel_epoch);
119        }
120        slot.cancel_epoch = slot.cancel_epoch.next()?;
121        slot.cancelled = true;
122        Ok(slot.cancel_epoch)
123    }
124
125    /// `true` when `cancelled`.
126    pub fn is_cancelled(&self, id: OperationId) -> bool {
127        self.find(id).map(|s| s.cancelled).unwrap_or(false)
128    }
129
130    /// Finish an operation. After cancel this releases storage and returns
131    /// `Cancelled` so the caller cannot treat the result as a live success.
132    pub fn complete(
133        &mut self,
134        id: OperationId,
135        generation: Generation,
136        leases: &mut LeaseTable,
137    ) -> Result<(), QdnfError> {
138        let idx = self.find_index(id).ok_or(QdnfError::Closed)?;
139        if self.slots[idx].generation != generation {
140            return Err(QdnfError::StaleGeneration);
141        }
142        let cancelled = self.slots[idx].cancelled;
143        if self.slots[idx].storage_held {
144            leases.release(self.slots[idx].lease)?;
145            self.slots[idx].storage_held = false;
146        }
147        let keep_generation = self.slots[idx].generation;
148        self.slots[idx].occupied = false;
149        self.slots[idx].cancelled = false;
150        self.slots[idx].id = OperationId::ZERO;
151        self.slots[idx].lease = LeaseHandle::INVALID;
152        self.slots[idx].generation = keep_generation;
153        self.slots[idx].cancel_epoch = CancelEpoch::ZERO;
154        if cancelled {
155            Err(QdnfError::Cancelled)
156        } else {
157            Ok(())
158        }
159    }
160
161    fn find(&self, id: OperationId) -> Option<&OpSlot> {
162        self.slots.iter().find(|s| s.occupied && s.id == id)
163    }
164
165    fn find_mut(&mut self, id: OperationId) -> Option<&mut OpSlot> {
166        self.slots.iter_mut().find(|s| s.occupied && s.id == id)
167    }
168
169    fn find_index(&self, id: OperationId) -> Option<usize> {
170        self.slots.iter().position(|s| s.occupied && s.id == id)
171    }
172}
173
174impl Default for OperationTable {
175    fn default() -> Self {
176        Self::new()
177    }
178}
179
180#[cfg(test)]
181mod tests {
182    use super::*;
183    use crate::net::peer::runtime::events::{EffectKind, EffectQueue, KernelEffect};
184    use crate::net::peer::runtime::leases::LeaseTable;
185
186    fn op(n: u8) -> OperationId {
187        let mut id = [0u8; 16];
188        id[0] = n;
189        OperationId(id)
190    }
191
192    #[test]
193    fn cancel_then_late_complete_releases_storage() {
194        let mut leases = LeaseTable::new();
195        let mut ops = OperationTable::new();
196        let mut effects = EffectQueue::new();
197        let lease = leases.acquire(64, true).unwrap();
198        let id = op(1);
199        let handle = ops.admit(id, lease.handle).unwrap();
200        effects
201            .push(KernelEffect {
202                kind: EffectKind::SendFrame,
203                operation: id,
204                lease: lease.handle,
205            })
206            .unwrap();
207
208        let epoch = ops.cancel(id).unwrap();
209        assert_eq!(epoch, CancelEpoch(1));
210        assert!(ops.is_cancelled(id));
211        effects.cancel_in_flight(id).unwrap();
212
213        assert_eq!(effects.complete(), Err(QdnfError::Cancelled));
214        assert_eq!(
215            ops.complete(id, handle.generation, &mut leases),
216            Err(QdnfError::Cancelled)
217        );
218        assert_eq!(leases.release(lease.handle), Err(QdnfError::DoubleRelease));
219        assert_eq!(
220            ops.complete(id, handle.generation, &mut leases),
221            Err(QdnfError::Closed)
222        );
223    }
224
225    #[test]
226    fn stale_generation_is_rejected() {
227        let mut leases = LeaseTable::new();
228        let mut ops = OperationTable::new();
229        let lease = leases.acquire(8, true).unwrap();
230        let handle = ops.admit(op(2), lease.handle).unwrap();
231        assert_eq!(
232            ops.complete(op(2), Generation(handle.generation.0 + 1), &mut leases),
233            Err(QdnfError::StaleGeneration)
234        );
235        ops.complete(op(2), handle.generation, &mut leases).unwrap();
236    }
237
238    #[test]
239    fn cancel_epoch_does_not_wrap() {
240        assert_eq!(
241            CancelEpoch(u64::MAX).next(),
242            Err(QdnfError::StaleGeneration)
243        );
244    }
245}