windows_ioring_sys/
token.rs

1// Copyright (c) 2026 Mike Grier
2//! [`OperationId`]: the name of one in-flight operation.
3//!
4//! The module is still called `token` because `Token<T>` lived here until
5//! `M28.4.1d` retired it; the file name is private (`mod token;`) and renaming
6//! it would churn history for no reader's benefit.
7
8use crate::ring::RingId;
9
10/// The name of one in-flight operation, carrying no claim on anything.
11///
12/// Returned by a push so a caller can *refer* to the operation it just
13/// queued -- to cancel it, to correlate it, or to feed
14/// [`crate::contract::RingContract`]. It is `Copy`, has no `Drop`, and losing
15/// one is harmless.
16///
17/// # A name, not a capability (D-71)
18///
19/// This deliberately carries **no power to retrieve a payload**. The ring
20/// hands a payload back only from the pop that observed its completion, which
21/// is what makes a use-after-free unrepresentable: there is no call that turns
22/// an identity into the memory an operation may still be using.
23///
24/// That is the same property `Token::claim_if` bought at runtime, and this
25/// buys it structurally. The retired `claim_if` took a
26/// [`crate::Completion`] rather than a `usize` precisely because a
27/// `Completion` has no public constructor, so the only proof the kernel has
28/// finished was one that had been popped; a caller-supplied integer would have
29/// let safe code free a buffer the kernel was still writing into. `M28.4.1d.3`
30/// removed the call rather than the argument: the payload now comes back *from*
31/// the pop, so there is no second entry point to guard.
32///
33/// Handing an `OperationId` to a cancel stays safe for the reason it was always
34/// safe to pass a token's id there: a cancel returns no memory.
35#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
36pub struct OperationId {
37    id: usize,
38    ring_id: RingId,
39}
40
41impl OperationId {
42    pub(crate) fn new(id: usize, ring_id: RingId) -> Self {
43        Self { id, ring_id }
44    }
45
46    /// The `UserData` value this operation carries.
47    ///
48    /// The integer the kernel echoes back in its `IORING_CQE`. Useful as a
49    /// cancel target and for a caller's own correlation; it is not a handle to
50    /// anything.
51    #[must_use]
52    pub fn user_data(&self) -> usize {
53        self.id
54    }
55
56    /// The ring that minted this identity.
57    ///
58    /// Every ring hands out `UserData` from its own counter starting at the
59    /// same value, so the same integer legitimately occurs on two rings. The
60    /// inventory is per-ring, which makes that collision structurally
61    /// harmless -- but a caller correlating across rings needs this to tell
62    /// them apart.
63    pub(crate) fn ring_id(&self) -> RingId {
64        self.ring_id
65    }
66}
67
68impl std::fmt::Display for OperationId {
69    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
70        write!(f, "{:#x}", self.id)
71    }
72}
73
74#[cfg(test)]
75mod tests;
windows_ioring_sys/token.rs

windows_ioring_sys/
token.rs
