Struct CompletionPort 

pub struct CompletionPort { /* private fields */ }

An owned I/O completion port.

Implementations

impl CompletionPort

pub fn new(concurrency: u32) -> Result<Self>

Create a new completion port.

concurrency is the maximum number of threads the system lets run completions for this port concurrently; zero means one per processor.

pub fn associate( &self, endpoint: UnassociatedEndpoint, key: usize, ) -> Result<AssociatedEndpoint<'_>>

Associate an overlapped endpoint with this port under key.

Completions for operations issued on the endpoint are delivered to this port and tagged with key. The association is permanent for the life of the handle, so the returned endpoint borrows the port.

Errors

Returns io::ErrorKind::InvalidInput if key is already associated with a live endpoint on this port (PR #20 review response): a completion key is a caller-defined tag, not a unique endpoint identity, and deregister_dequeued finds an endpoint’s outstanding-operation counter by looking it up under key alone. Associating a second endpoint under a key already in use would silently replace the first endpoint’s counter in endpoint_outstanding; completions for the first endpoint would then decrement the second’s counter (which can underflow) while the first’s own counter never reaches zero, blocking its Drop forever. Rejecting the duplicate before native association keeps every key’s counter unambiguous instead. Also returns the error from CreateIoCompletionPort.

pub fn post(&self, key: usize, bytes_transferred: u32) -> Result<()>

Post a user-defined wakeup packet to this port.

The packet carries key and bytes_transferred with a null OVERLAPPED, which keeps it distinguishable from operation completions; identify it by its key.

pub fn get(&self, timeout_ms: u32) -> Result<Option<Completion>>

Dequeue one completion packet, waiting up to timeout_ms milliseconds.

Returns Ok(None) when the wait times out with no packet. A packet is returned even when its operation failed; the failure is reported through Completion::error.

pub fn outstanding(&self) -> usize

The number of operations submitted through this port whose completion packet has not yet been dequeued.

A packet that has been dequeued is not counted, even if the Completion is still held and its storage not yet released. The count measures what the port is still waiting to deliver, which is what run_down blocks on.

pub fn run_down(&self) -> Result<()>

Block until a completion packet has been dequeued for every outstanding operation.

Every outstanding operation must already be cancelled or otherwise destined to complete – which closing or cancelling the endpoints guarantees – or this waits indefinitely. Each packet dequeued here is reclaimed immediately, since the Completion this creates is dropped within the loop.

A Completion held elsewhere does not keep this waiting: its packet has already been delivered, so it is not outstanding. It still owns the operation’s storage, and still frees it when dropped, which may be after this returns and after the port itself is gone.

The port is shareable, so another thread may be consuming completions at the same time. Each wait here is therefore bounded (RUN_DOWN_POLL_MS) and the live count is rechecked after it: a concurrent consumer can dequeue the last packet – and clear its registry entry – in the window between this loop observing a nonzero count and beginning its own wait, and an unbounded wait would then block forever on a packet no longer coming. Removing a registry entry does not wake a GetQueuedCompletionStatus already in progress, so the recheck, not a wakeup, is what ends the wait.

impl CompletionPort

pub fn associate_socket( &self, socket: OwnedSocket, key: usize, ) -> Result<AssociatedSocket<'_>>

Associate an overlapped socket with this port under key.

Completions for operations issued on the socket are delivered to this port and tagged with key. The socket must be overlapped-capable, which every std::net socket and any WSASocket created with WSA_FLAG_OVERLAPPED is; the association is permanent for the life of the socket.

Errors

Returns any error from CreateIoCompletionPort.

Trait Implementations

impl Debug for CompletionPort

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for CompletionPort

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.