Struct TcpListener 

pub struct TcpListener<'d> { /* private fields */ }

A TCP listener.

Use a TcpListener to accept incoming TCP connections.

A listener can be bound to a port and optionally an address. It receives all incoming connection attempts and queues them. Calling accept pops an attempt from the queue as an AcceptToken. Pass it to TcpSocket::accept to set up a socket for it, possibly in another task.

Connection attempts (SYN packets) are not answered (with a SYN|ACK packet) until a socket accepts them. The queue depth is set by the tcp-listener-backlog-N feature of xarxa.

Implementations

impl<'d> TcpListener<'d>

pub fn new(stack: Stack<'d>) -> Result<Self, Full>

Create a new TCP listener on the given stack.

The listener starts closed. Call listen to start listening.

Errors

• Full: if the stack has no room for another listener. Only possible without the alloc feature, where the limit is set by the tcp-listener-count-N feature of xarxa.

pub fn bind_to_iface( &mut self, iface: Option<IfaceHandle>, ) -> Result<(), ListenError>

Bind the listener to an interface, or unbind it with None.

A listener bound to an interface only accepts connection attempts that arrive on that interface.

When accepting a connection, the sockets inherit the binding.

The listener must be closed. The binding is kept across close.

Two listeners on the same address can coexist if they are bound to different interfaces, or if one is not bound. In the latter case, the bound listener “wins” for incoming connections coming from the bound interface.

Errors

• InvalidState: if the listener is open.

pub fn bound_iface(&self) -> Option<IfaceHandle>

Return the interface the listener is bound to, or None.

See bind_to_iface.

pub fn listen( &mut self, local: impl Into<ListenSocketAddr>, ) -> Result<(), ListenError>

Start listening on the given local address.

Errors

• Unaddressable: if the port is zero.
• InvalidState: if the listener is already listening (unless it is listening on this same address, which is a no-op).
• InUse: if another listener is bound to an identical address. Listeners on the same port with different specificity (one wildcard, one per-version, one per-address) may coexist, and so may listeners on identical addresses bound to different interfaces.

pub fn close(&mut self)

Stop listening, dropping all queued SYNs.

The dropped SYNs are not reset. The clients’ retransmissions are answered with an RST once the listener is gone.

pub fn is_open(&self) -> bool

Whether the listener is listening.

pub fn local_addr(&self) -> ListenSocketAddr

Return the listened address. The address is the filter the listen scoped the listener to. A zero port means the listener is closed.

pub fn can_accept(&self) -> bool

Whether a connection attempt is waiting to be accepted.

pub fn wait_accept_ready(&self) -> impl Future<Output = ()> + '_

Wait until a connection attempt is waiting to be accepted.

This is the equivalent of accept, without accepting the connection.

pub async fn accept(&mut self) -> Result<AcceptToken, AcceptError>

Accept a queued connection attempt, waiting if none is queued yet.

Returns an AcceptToken.

Pass it to TcpSocket::accept to set up a socket for the incoming connection, possibly in another task.

Dropping the token forgets the attempt. The client retransmits its SYN, which queues the attempt on the listener again.

Errors

• InvalidState: if the listener is not listening.

Trait Implementations

impl Drop for TcpListener<'_>

Available on crate feature tcp-listener only.

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.