Crate windows_overlapped_io_sys

Expand description

Owned overlapped I/O endpoints and pinned operations for Windows.

This crate provides the ownership, association, completion, cancellation, and rundown model for overlapped I/O on top of windows-sys. It is the reusable foundation beneath windows-threadpool-sys: raw I/O completion ports and the object-based thread pool share endpoint and operation storage while remaining distinct completion backends.

§Operation-family adapters

Endpoints are created safely with UnassociatedEndpoint::open, and each operation family has an adapter behind an opt-in feature. The fs and socket adapters are fully safe; the device adapter owns its buffers but its ioctl is unsafe, because an arbitrary control code may embed pointers to buffers the adapter cannot own:

fs: file read/write and scatter/gather, on the blocking and IOCP backends. Fully safe.
socket: socket send/receive, on the blocking and IOCP backends. Fully safe.
device: DeviceIoControl on both backends, through a buffer-owning but unsafe raw-control-code seam.

The default feature set is empty, keeping the core completion machinery (the raw IOCP and blocking backends, owned endpoints, and pinned operations) minimal. A narrow unsafe submission seam (AssociatedEndpoint::submit and the Operation primitives) stays available for families without an adapter. Fully generic, fully safe overlapped submission remains intentionally unsolved; the per-family adapters are the sanctioned safe path.

§Operation identity

Submitting returns an OperationId that names that operation for the life of the process, not merely while its storage address stays put. Cancelling validates the identity against the backend’s live operations first, so an identity kept past its operation’s completion is rejected rather than applied to a later operation that reused the same storage. Holding an identity too long is therefore safe, and cancellation races safely against completion.

Structs§

AssociatedEndpoint: An overlapped endpoint bound to exactly one CompletionPort.
AssociatedSocket: An overlapped socket bound to exactly one CompletionPort.
BlockingEndpoint: An overlapped endpoint that completes operations synchronously, one at a time, via GetOverlappedResult.
BlockingSocket: A connected overlapped socket that completes operations synchronously, one at a time, via a Winsock completion event.
Completion: A completion packet dequeued from a CompletionPort.
CompletionPort: An owned I/O completion port.
DeviceIoControlIo: A pending device-control operation submitted through AssociatedEndpoint::ioctl.
FileIo: A pending file operation submitted through AssociatedEndpoint::read or AssociatedEndpoint::write.
NotificationModes: Which completion-notification shortcuts a handle should take.
Operation: Stable storage for one overlapped operation.
OperationId: An identity for an in-flight operation: the address of its OVERLAPPED together with the generation stamped on it at submission.
OperationRegistry: The set of identities a backend currently considers live.
PageBuffers: A page-aligned set of memory pages: the buffer form the scatter/gather adapters read into and write from.
ScatterGatherIo: A pending scatter/gather operation submitted through AssociatedEndpoint::read_scatter or AssociatedEndpoint::write_gather.
SocketIo: A pending socket operation submitted through AssociatedSocket::recv or AssociatedSocket::send.
SourceTrackingAlreadySet: Returned when source tracking is configured after it has already been set.
TryFromEndpointError: BlockingEndpoint::new’s rejection: endpoint has crate::NotificationModes::skip_set_event_on_handle set, which is incompatible with the blocking backend (see new’s docs). Carries the endpoint back so a caller that constructed it in error loses nothing.
UnassociatedEndpoint: An overlapped-capable endpoint that has not yet been associated with a completion backend.

Enums§

Issued: How the native call in AssociatedEndpoint::submit accepted an operation.
OperationState: The lifecycle state of an overlapped operation’s storage.
Started: What became of an adapter submission that did not fail immediately.
Submitted: The outcome of AssociatedEndpoint::submit.

Constants§

FILE_FLAG_NO_BUFFERING: The Win32 FILE_FLAG_NO_BUFFERING flag.
PAGE_SIZE: The memory page size assumed by the scatter/gather adapters.

Traits§

IoBuf: An owned buffer an operation reads bytes from (a write, a send).
IoBufMut: An owned buffer an operation writes bytes into (a read, a receive).

Functions§

reclaim_overlapped^⚠: Reclaim and drop an operation from its OVERLAPPED identity without knowing its payload type, using the thunk armed by Operation::into_overlapped.
set_source_tracking: Enable or disable per-operation source tracking for the whole process.
source_tracking_enabled: Whether per-operation source tracking is enabled for this process.