windows_overlapped_io_sys/lib.rs
1// Copyright (c) 2026 Mike Grier
2//! Owned overlapped I/O endpoints and pinned operations for Windows.
3//!
4//! This crate provides the ownership, association, completion, cancellation, and
5//! rundown model for overlapped I/O on top of `windows-sys`. It is the reusable
6//! foundation beneath `windows-threadpool-sys`: raw I/O completion ports and the
7//! object-based thread pool share endpoint and operation storage while remaining
8//! distinct completion backends.
9//!
10//! # Operation-family adapters
11//!
12//! Endpoints are created safely with [`UnassociatedEndpoint::open`], and each
13//! operation family has an adapter behind an opt-in feature. The `fs` and
14//! `socket` adapters are fully safe; the `device` adapter owns its buffers but
15//! its `ioctl` is `unsafe`, because an arbitrary control code may embed pointers
16//! to buffers the adapter cannot own:
17//!
18//! - `fs`: file read/write and scatter/gather, on the blocking and IOCP backends.
19//! Fully safe.
20//! - `socket`: socket send/receive, on the blocking and IOCP backends. Fully
21//! safe.
22//! - `device`: `DeviceIoControl` on both backends, through a buffer-owning but
23//! `unsafe` raw-control-code seam.
24//!
25//! The default feature set is empty, keeping the core completion machinery (the
26//! raw IOCP and blocking backends, owned endpoints, and pinned operations)
27//! minimal. A narrow unsafe submission seam ([`AssociatedEndpoint::submit`] and
28//! the [`Operation`] primitives) stays available for families without an adapter.
29//! Fully generic, fully safe overlapped submission remains intentionally
30//! unsolved; the per-family adapters are the sanctioned safe path.
31//!
32//! # Operation identity
33//!
34//! Submitting returns an [`OperationId`] that names that operation for the life
35//! of the process, not merely while its storage address stays put. Cancelling
36//! validates the identity against the backend's live operations first, so an
37//! identity kept past its operation's completion is rejected rather than applied
38//! to a later operation that reused the same storage. Holding an identity too
39//! long is therefore safe, and cancellation races safely against completion.
40
41#![warn(missing_docs)]
42
43#[cfg(windows)]
44mod blocking;
45
46#[cfg(windows)]
47mod config;
48
49#[cfg(windows)]
50mod buf;
51
52#[cfg(all(windows, feature = "device"))]
53mod device;
54
55#[cfg(windows)]
56mod endpoint;
57
58#[cfg(all(windows, feature = "fs"))]
59mod fs;
60
61#[cfg(windows)]
62mod identity;
63
64#[cfg(windows)]
65mod iocp;
66
67#[cfg(windows)]
68mod operation;
69
70#[cfg(all(windows, feature = "socket"))]
71mod socket;
72
73#[cfg(windows)]
74mod started;
75
76#[cfg(windows)]
77pub use blocking::{BlockingEndpoint, TryFromEndpointError};
78
79#[cfg(windows)]
80pub use buf::{IoBuf, IoBufMut};
81
82#[cfg(windows)]
83pub use config::{SourceTrackingAlreadySet, set_source_tracking, source_tracking_enabled};
84
85#[cfg(all(windows, feature = "device"))]
86pub use device::DeviceIoControlIo;
87
88#[cfg(windows)]
89pub use endpoint::{NotificationModes, UnassociatedEndpoint};
90
91#[cfg(all(windows, feature = "fs"))]
92pub use fs::{FILE_FLAG_NO_BUFFERING, FileIo, PAGE_SIZE, PageBuffers, ScatterGatherIo};
93
94#[cfg(windows)]
95pub use identity::{OperationId, OperationRegistry};
96
97#[cfg(windows)]
98pub use iocp::{AssociatedEndpoint, Completion, CompletionPort, Issued, Submitted};
99
100#[cfg(windows)]
101pub use operation::{Operation, OperationState, reclaim_overlapped};
102
103#[cfg(all(windows, feature = "socket"))]
104pub use socket::{AssociatedSocket, BlockingSocket, SocketIo};
105
106#[cfg(windows)]
107pub use started::Started;