Struct AssociatedSocket

Source

pub struct AssociatedSocket<'port> { /* private fields */ }

Expand description

An overlapped socket bound to exactly one CompletionPort.

The endpoint owns its socket (closed with closesocket on drop) and borrows the port it is associated with. It is intentionally not Clone.

Implementations§

Source §

impl<'port> AssociatedSocket<'port>

Source

pub fn socket(&self) -> BorrowedSocket<'_>

Borrow the underlying socket.

Source

pub fn key(&self) -> usize

The completion key packets from this socket are tagged with.

Source

pub fn port(&self) -> &'port CompletionPort

The completion port this socket is associated with.

Source

pub fn notification_modes(&self) -> NotificationModes

The completion-notification modes established on this socket.

Source

pub fn set_notification_modes(&mut self, modes: NotificationModes) -> Result<()>

Set this socket’s completion-notification modes, after checking that its provider actually supports them.

The handle side declares its modes before association, on UnassociatedEndpoint::set_notification_modes, because there the mode is part of an endpoint’s provenance. A socket has no unassociated stage to hang that on, so it declares here instead. Setting after association is still safe: the flag only takes effect at I/O time, and recv/send take &self, so a caller sets the mode once against &mut self and then submits freely.

Passing every field false is a no-op call, not a reset. A mode cannot be removed once set – a Win32 property of the handle, not a limitation of this wrapper – so a second call can only ever add modes.

§The capability probe

Win32 restricts NotificationModes::skip_completion_port_on_success on a socket to Layered Service Providers that return IFS handles, and a socket wrongly put in that mode reports Started::Pending for an operation whose packet was suppressed – leaving it outstanding forever and wedging CompletionPort::run_down. So this asks first, reading this socket’s own WSAPROTOCOL_INFOW via SO_PROTOCOL_INFOW and requiring XP1_IFS_HANDLES. That is narrower and more accurate than the WSAEnumProtocols sweep the flag’s documentation suggests: it asks about the provider that actually created this socket, not about every LSP installed on the machine.

skip_set_event_on_handle carries no such restriction and is not probed.

§Errors

Returns io::ErrorKind::Unsupported if skip-on-success was requested and this socket’s provider does not return IFS handles, or any error from getsockopt or SetFileCompletionNotificationModes.

Source

pub fn recv<B: IoBufMut>(&self, buffer: B) -> Result<Started<SocketIo, B>>

Submit an overlapped receive into buffer.

The buffer is any owned IoBufMut – handed over for the operation’s life and returned when it completes, with nothing copied and nothing allocated here.

Returns Started::Pending with a SocketIo token that recovers the buffer and byte count from the operation’s completion, or – only on a socket in a skip-on-success completion mode, where a synchronous success queues no packet – Started::Completed with the buffer already in hand.

§Errors

Returns io::ErrorKind::InvalidInput if the buffer is longer than u32::MAX, which WSABUF’s byte count cannot express, or any immediate failure from issuing the receive.

Source

pub fn send<B: IoBuf>(&self, buffer: B) -> Result<Started<SocketIo, B>>

Submit an overlapped send of buffer.

The buffer is any owned IoBuf – including a shared Arc<[u8]> or a &'static [u8] – handed over for the operation’s life and returned when it completes. Nothing is copied.

Returns Started::Pending with a SocketIo token, or Started::Completed with the buffer already in hand when the socket is in a skip-on-success completion mode and the send completed synchronously.

§Errors

Returns io::ErrorKind::InvalidInput if the buffer is longer than u32::MAX, which WSABUF’s byte count cannot express, or any immediate failure from issuing the send.

Source

pub fn cancel(&self, id: OperationId) -> Result<()>

Request cancellation of a single outstanding operation on this socket.

The identity is validated against the port’s live operations, and the native cancellation happens under the same guard, so an identity retained past its operation’s completion cannot reach a later operation that was given the same storage address.