# Checklist: windows-ioring-sys
Design decisions are in [DESIGN-NOTES.md](DESIGN-NOTES.md); the session that produced them is
[DESIGN-SESSION-2026-08-22-ioring-architecture.md](design-sessions/DESIGN-SESSION-2026-08-22-ioring-architecture.md).
M1 through M7 (ring lifecycle through the `ring-copy` sample) are archived in
[COMPLETED-CHECKLIST.md](COMPLETED-CHECKLIST.md#moved-2026-08-22----m1-through-m6-ring-lifecycle-through-consumer-documentation)
and
[COMPLETED-CHECKLIST.md](COMPLETED-CHECKLIST.md#moved-2026-08-23----m7-ring-copy-a-topology-aligned-sample).
## M6+ -- Model B: explicit-thread delivery and affinity
Parked, not pending. Deferred by the engineer's explicit direction during the 2026-08-22 design session,
with the plan scoped now so the shape is not lost. This is **not** a fallback for a missing capability
(D-3) -- it is the high-performance architecture, and M4's thread-pool path is the convenient one.
- [ ] **M6+.1** -- `DeliveryMode::{ThreadpoolWait, PinnedThread}` as an explicit consumer choice, never an
automatic degradation.
- [ ] **M6+.2** -- Resolve the contention between a thread parked in `SubmitIoRing(ring, n, INFINITE, ..)`
and callers wanting to build SQEs. This is the hard part and the reason this is its own milestone: it
directly contradicts M3.1's `&mut`-enforced serialization, and needs either a submit-ownership handoff
or an internal lock. Neither is obviously right.
- [ ] **M6+.3** -- Shutdown: waking a thread parked on `INFINITE`. `IORING_OP_NOP` is supported and is the
wake mechanism.
- [ ] **M6+.4** -- Affinity: binding a ring's thread with `SetThreadGroupAffinity`, and documenting the
execution-domain pattern (one pinned thread, its ring, its node-local registered pool, its shard).
- [ ] **M6+.5** -- A test seam forcing the pinned-thread path even where the completion event is available,
so it stays testable on every machine rather than only on hardware that lacks the feature.
- [ ] **M6+.6** -- Decide `IoBuf`: extract to a shared crate, re-export from
`windows-overlapped-io-sys`, or leave duplicated (D-1). The merge-or-delete decision that duplicate-then-decide
defers to the point where the new path is proven -- which is here, not earlier.
## M8 -- `FileRef::Raw(HANDLE)` lifetime safety (PR #20 review finding)
A caller can close or reuse the raw `HANDLE` passed to `Batch::read`/`write`/`flush`/`cancel`/
`register_files` before the kernel finishes with it: unlike a buffer (owned by a `Token` until claimed),
`FileRef::Raw` carries no lifetime and nothing in this crate borrow-checks a handle across the async gap
between push and completion.
- [x] **M8.1** -- Ownership model decided: `Batch::read`/`write`/`flush`/`cancel`/`register_files` become
`unsafe fn` when addressing a raw `HANDLE` (their existing `SAFETY` comments already state the
caller-keeps-it-alive obligation informally; this makes it a real, compiler-checked boundary), paired
with a safe `SharedFile` wrapper (`Arc<OwnedHandle>`) for the common case: each push clones the `Arc` into
the same `Token` that already tracks the operation's buffer (or, for `flush`/`cancel`, a standalone
`Token<Arc<OwnedHandle>>`), so the underlying handle survives until every operation referencing it is
claimed or leaked, regardless of what the caller does with its own `SharedFile` clone. Rejected:
borrowing `FileRef::Raw` for the `Batch`'s own lifetime (does not solve the completion-outlives-the-push-
call problem) and forcing every raw handle through an owning wrapper the way
`windows-overlapped-io-sys`'s endpoints do (defeats `FileRef::Raw`'s zero-setup reason to exist).
`FileRef::Registered` needs none of this and stays unaffected.
- [x] **M8.2** -- Added `SharedFile` (`pub struct SharedFile(Arc<OwnedHandle>)`) with a constructor from
`OwnedHandle`, `Clone`, and a raw-handle accessor for building an `IORING_HANDLE_REF`.
- [x] **M8.3** -- Marked `Batch::read`/`write`/`flush`/`cancel`/`register_files`'s raw-`HANDLE`-taking
forms `unsafe fn` with a `# Safety` section stating the real obligation (valid handle, correct access
rights, remains valid until the pushed operation's completion is observed or the ring runs down).
**Scope correction found during execution:** `read_registered`/`write_registered` take the identical
`impl Into<FileRef>` shape for their own `file` argument and carry the same hazard, so they were marked
`unsafe fn` too, with no separate checklist item -- the original enumeration omitted them by oversight,
not by decision. Committed as `feat(ioring)!`.
- [x] **M8.4** -- Added safe overloads `read_shared`/`write_shared`/`flush_shared`/`cancel_shared` (plus
`read_registered_shared`/`write_registered_shared`, for the same reason as M8.3's correction) taking
`&SharedFile`, cloning the `Arc` into the same `Token` (a tuple with the buffer for `read`/`write`-shaped
pushes, or `Token<SharedFile>` alone for `flush`/`cancel`, which have no buffer of their own) so a caller
never needs `unsafe` for the common case. `register_files` gets no `_shared` counterpart: a registration's
handles must stay valid for the ring's remaining life, a lifetime no single push's `Token` can express.
- [x] **M8.5** -- Integration test
(`dropping_the_callers_own_sharedfile_clone_does_not_close_a_still_outstanding_handle`,
`tests/submission_lifecycle.rs`): drop the caller's own `SharedFile` clone (its only external reference)
while a push against it is still outstanding; the read still completes correctly against a live handle,
proving the `Arc` clone inside the token -- not the caller's copy -- is what kept it open.
- [x] **M8.6** -- Renamed the API so the safe path gets the plain names: the raw/`unsafe` entry points
became `read_raw`/`write_raw`/`flush_raw`/`cancel_raw`/`read_registered_raw`/`write_registered_raw`, and
the safe `SharedFile`-taking overloads (previously `*_shared`) took over the plain names
`read`/`write`/`flush`/`cancel`/`read_registered`/`write_registered` -- since the safe path is the one
this crate wants to steer callers toward. `register_files` keeps its plain name unsafe, since it has no
safe counterpart to make way for.
## M9 -- Cross-ring identity and registration-drop safety (PR #20 review findings)
`UserData`, `RegisteredFile`, and `RegisteredBuffers` indices are each meaningful only against the
specific ring that minted them, but nothing enforced that when more than one `IoRing` exists in the same
process.
- [x] **M9.1** -- Added `RingId` (`ring.rs`): a monotonic, process-lifetime-unique `AtomicU64` counter,
never the ring's own `HANDLE` (which Windows can reuse for the next object after a ring closes). Every
`IoRing` gets one at construction; every popped `Completion` now carries the id of the ring that
produced it (D-17).
- [x] **M9.2** -- `Token::claim_if` now requires both the `UserData` identity and the `RingId` to match,
closing the gap where two different rings' own zero-based `UserData` counters could coincide. Added
`claim_if_rejects_a_matching_user_data_from_a_different_ring` (`src/token/tests.rs`).
- [x] **M9.3** -- `RegisteredFile`/`RegisteredFiles`/`PendingFileRegistration` and
`RegisteredBuffers`/`PendingBufferRegistration` now carry the minting ring's `RingId`; `handle_ref`
(fallible now) and a new `Batch::check_registration_ring` reject a `FileRef::Registered`/
`RegisteredBuffers` argument from a different ring with `io::ErrorKind::InvalidInput`, checked before any
`Build*` call runs. Added `a_registered_file_from_a_different_ring_is_rejected` and
`a_registered_buffers_from_a_different_ring_is_rejected` (`tests/registration.rs`).
- [x] **M9.4** -- `PendingBufferRegistration` now leaks its buffers (via `ManuallyDrop` plus a
deliberately empty `Drop`) if dropped without a matching `claim_if`, mirroring `Token`/
`RegisteredBuffers` (D-18) -- previously it dropped `Vec<B>` normally, freeing memory the kernel might
still reference from an already-queued `BuildIoRingRegisterBuffers` call. Added
`dropping_an_unclaimed_pending_buffer_registration_leaks_rather_than_frees` (`tests/registration.rs`).
- [x] **M9.5** -- `Batch::do_submit` now marks itself attempted (`self.submitted = true`) *before*
propagating `SubmitIoRing`'s `HRESULT`, not after: `submit_and_wait` takes `self` by value, so a failed
call still runs `Drop` once its caller's `self` goes out of scope, and the old ordering left `Drop` free
to silently retry an already-attempted submit -- which could succeed on the retry without the original
caller's `Err` ever saying so.
- [x] **M9.6** -- Output-abstraction cleanup in the two examples the review flagged
(`examples/model_a_delivery.rs`, `examples/l3_domains.rs`): routed through a single writer seam per the
repository's architectural pre-step, matching `src/bin/run_scenario.rs` (in `windows-file-watcher`) and
`examples/ring_copy/main.rs`'s existing pattern. `PLANS.md`'s bare `COMPLETED-PLANS.md`/
`COMPLETED-CHECKLIST.md` references were also made clickable relative links.