dope_sys/io/reactor/complete/
mod.rs

1use o3::{alloc, base::num::bounded, depot};
2
3use crate::{Errno, engine::admit::Submitted, probe};
4
5pub mod flags;
6pub mod message;
7pub mod raw;
8pub mod resolve;
9
10pub mod packet;
11
12use crate::table::token::host;
13
14type Header<E> = Parts<<E as Entry>::Token, <E as Entry>::Outcome, <E as Entry>::Flags>;
15
16/// Owns one dequeued completion and its optional affine buffer.
17pub trait Packet: Sized {
18    type Parts: Copy;
19    type Buffer;
20
21    fn new(parts: Self::Parts, buffer: Option<Self::Buffer>) -> Self;
22    fn try_new<E>(
23        parts: Self::Parts,
24        buffer: Result<Option<Self::Buffer>, E>,
25    ) -> Result<Self, probe::Stopped<Self, packet::Invalid<E>>>;
26    fn parts(&self) -> Self::Parts;
27    fn buffer(&self) -> &Option<Self::Buffer>;
28    fn buffer_mut(&mut self) -> &mut Option<Self::Buffer>;
29    fn into_parts(self) -> (Self::Parts, Option<Self::Buffer>);
30    fn is_plain(&self) -> bool;
31    fn flow(&self) -> flags::Flow;
32    /// Retires the bound authority or borrows this exact refused packet.
33    fn try_retire(&self, echo: impl host::Echo) -> Result<(), &Self>;
34}
35
36/// Preserves the typed inputs of an emulated completion before rejection.
37pub trait Capture<E, S, F>: Sized {
38    fn operation(echo: E) -> Self;
39    fn creation(echo: E, queued: S, resolved: Option<S>) -> Self;
40    fn receive(echo: E, len: usize, flow: F) -> Self;
41}
42
43#[derive(Clone, Copy, Debug, Eq, PartialEq)]
44pub enum Decode<V, I> {
45    Value(V),
46    Error(Errno),
47    Invalid(I),
48}
49
50/// A completed owner routed to delivery or mandatory reclamation.
51pub enum Dequeued<E> {
52    Emit(E),
53    Reclaim(E),
54}
55
56impl<E> Dequeued<E> {
57    pub fn map<U>(self, map: impl FnOnce(E) -> U) -> Dequeued<U> {
58        match self {
59            Self::Emit(event) => Dequeued::Emit(map(event)),
60            Self::Reclaim(event) => Dequeued::Reclaim(map(event)),
61        }
62    }
63}
64
65impl<M: Map> Map for Dequeued<M> {
66    type Entry<T> = Dequeued<M::Entry<T>>;
67
68    fn map<T, U>(entry: Self::Entry<T>, map: impl FnOnce(T) -> U) -> Self::Entry<U> {
69        entry.map(|done| M::map(done, map))
70    }
71}
72
73/// A borrowed completion queue retaining its native publication order.
74pub trait Drain {
75    type Entry: Entry;
76
77    fn acquire(&mut self);
78    fn publish(&mut self);
79    fn refresh(&mut self);
80    fn len(&self) -> bounded::U32<0, { u32::MAX }>;
81    fn is_empty(&self) -> bool;
82    fn pop(&mut self) -> Option<Self::Entry>;
83}
84
85/// Inspects the next published completion without advancing either queue head.
86/// The returned borrow keeps the observed slot stable until an infallible commit.
87pub trait Inspect: Drain {
88    type Head<'a>: Head<Entry = Self::Entry>
89    where
90        Self: 'a;
91
92    fn front(&mut self) -> Option<Self::Head<'_>>;
93    fn available(&self) -> bounded::U32<0, { u32::MAX }>;
94}
95
96/// A published, unconsumed completion tied to the queue's exclusive borrow.
97pub trait Head: Sized {
98    type Entry: Entry;
99
100    fn parts(&self) -> Header<Self::Entry>
101    where
102        <Self::Entry as Entry>::Token: raw::Token;
103
104    /// Advances and publishes the head after every semantic check has succeeded.
105    fn commit(self);
106}
107
108pub trait Entry: Sized {
109    type Token;
110    type Outcome: Outcome;
111    type Flags: Flags;
112
113    fn into_parts(self) -> Parts<Self::Token, Self::Outcome, Self::Flags>
114    where
115        Self::Token: raw::Token;
116}
117
118pub trait Event {
119    type Key: Copy + Eq;
120
121    fn token(&self) -> Option<Self::Key>;
122    fn is_terminal(&self) -> bool;
123}
124
125pub trait Map {
126    type Entry<T>;
127
128    fn map<T, U>(entry: Self::Entry<T>, map: impl FnOnce(T) -> U) -> Self::Entry<U>;
129}
130
131/// Exact native completion evidence retained by a host decoder.
132pub trait Observe<T: Copy + Eq = (), S: Copy + Eq = (), F: Copy + Eq = ()> {
133    type Observation: Copy + Eq;
134}
135
136/// Separates successful values, native errors, and invalid kernel results.
137pub trait Outcome: Copy + Eq {
138    type Value: Value;
139    type Invalid: Copy + Eq;
140    type Returned: crate::kernel::Returned<Value = Self::Value, Invalid = Self::Invalid>;
141
142    fn decode(self) -> Decode<Self::Value, Self::Invalid>;
143    fn is_zero(self) -> bool;
144    /// Tests the native errno range without extracting its error payload.
145    fn is_error(self) -> bool;
146    fn canceled(self) -> Result<(), Self::Returned>;
147    fn bytes(self) -> Result<Result<Self::Value, crate::Errno>, Self::Returned>;
148    fn unit(self) -> Result<Result<(), crate::Errno>, Self::Returned>;
149    fn shutdown(self) -> Result<(), Self::Returned>;
150    fn stopped(self) -> Result<(), Self::Returned>;
151    fn aborted(self) -> Result<(), Self::Returned>;
152}
153
154/// Exact native completion fields retained before semantic interpretation.
155#[derive(Clone, Copy, Debug, Eq, PartialEq)]
156#[repr(C)]
157pub struct Parts<T, O, F> {
158    pub token: T,
159    pub outcome: O,
160    pub flags: F,
161}
162
163pub trait Queue: Sized {
164    type Event: Event;
165    type Capacity: depot::raw::Count;
166    type Vacancy<'a>: Vacancy<Event = Self::Event>
167    where
168        Self: 'a;
169
170    fn try_new(capacity: Self::Capacity) -> Result<Self, alloc::Error>;
171
172    fn vacant(&mut self) -> Option<Self::Vacancy<'_>>;
173
174    fn pop_front(&mut self) -> Option<Dequeued<Self::Event>>;
175
176    fn suppress(&mut self, key: <Self::Event as Event>::Key);
177
178    fn is_terminal(&self, key: <Self::Event as Event>::Key) -> bool;
179
180    fn is_empty(&self) -> bool;
181
182    fn available(&self) -> usize;
183}
184
185/// Preserves the exact native completion fields before semantic rejection.
186pub trait Record<T>: Sized {
187    type Outcome;
188    type Flags;
189
190    fn new(token: T, outcome: Self::Outcome, flags: Self::Flags) -> Self;
191}
192
193impl<T, O, F> Record<T> for Parts<T, O, F> {
194    type Outcome = O;
195    type Flags = F;
196
197    fn new(token: T, outcome: O, flags: F) -> Self {
198        Self {
199            token,
200            outcome,
201            flags,
202        }
203    }
204}
205
206pub trait Source {
207    type Queue<E: Event, C: depot::raw::Count>: Queue<Event = E, Capacity = C>;
208}
209
210pub trait Vacancy: Sized {
211    type Event: Event;
212
213    fn push(self, event: Self::Event);
214}
215
216/// Owns one registered operation and its validated native cancellation changes.
217pub trait Cancellation: Sized {
218    type Event: Event;
219
220    fn commit(self, vacant: impl Vacancy<Event = Self::Event>) -> Submitted;
221}
222
223/// A successful kernel result preserving its nonnegative signed range.
224pub trait Value: Copy + Eq + Into<bounded::U32<0, { i32::MAX as u32 }>> {
225    fn is_zero(self) -> bool;
226}
227
228impl Value for bounded::U32<0, { i32::MAX as u32 }> {
229    fn is_zero(self) -> bool {
230        self.get() == 0
231    }
232}
233
234/// Retains both decoded metadata and the exact rejected native flags.
235pub trait Flags: Copy + Eq + From<Self::Meta> {
236    type Meta: flags::Meta;
237    type Invalid: Copy + Eq + Into<Self>;
238
239    fn meta(self) -> Self::Meta;
240    fn decode(self) -> Result<Self::Meta, Self::Invalid>;
241    fn is_valid(self) -> bool;
242}
dope_sys/io/reactor/complete/mod.rs

dope_sys/io/reactor/complete/
mod.rs
