Struct TcpListener 

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

A TCP listener borrowed from a Stack, returned by Stack::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 a connection from the queue and constructs a full TcpSocket for it.

Connection attempts (SYN packets) are not answered (with a SYN|ACK packet) until you accept them.

Implementations

impl<'d> TcpListener<'_, 'd>

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

Start listening on the given endpoint.

Returns:

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

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_endpoint(&self) -> IpListenEndpoint

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

pub fn register_accept_waker(&mut self, waker: &Waker)

Register a waker for accept.

The waker is woken on state changes that might affect the return value of accept calls, such as a SYN being queued, or the listener closing.

Notes:

• Only one waker can be registered at a time. If another waker was previously registered, it is overwritten and will no longer be woken.
• The Waker is woken only once. Once woken, you must register it again before it may be woken again.
• “Spurious wakes” are allowed: a wake doesn’t guarantee the result of accept has changed.

pub fn can_accept(&self) -> bool

Whether a connection attempt is waiting to be accepted.

pub fn accept( &mut self, rx_capacity: usize, tx_capacity: usize, ) -> Option<TcpHandle>

Accept a queued connection attempt, allocating the socket for it with receive and transmit buffers of the given capacities.

The buffers are allocated on the heap, so this needs the alloc feature. Without it, use accept_with_bufs to lend your own buffers, or accept_with_socket to reuse a socket you already have.

The new socket starts in the SYN-RECEIVED state and is added to the stack.

Returns None if no connection attempt is queued, or if the stack has no room for another TCP socket. In the second case the attempt stays queued and accept can be retried after removing a socket.

pub fn accept_with_bufs( &mut self, rx_buffer: &'d mut [u8], tx_buffer: &'d mut [u8], ) -> Option<TcpHandle>

Accept a queued connection attempt, creating the socket for it with the given receive and transmit buffers.

The buffers are lent to the stack. It holds them until it is dropped or the socket is removed, so they must be declared before the stack, or be 'static. Removing the socket does not hand them back, so a program that serves many connections from a fixed set of buffers should accept into the same sockets over and over with accept_with_socket instead.

The new socket starts in the SYN-RECEIVED state and is added to the stack.

Returns None if no connection attempt is queued, or if the stack has no room for another TCP socket. In the second case the attempt stays queued and accept_with_bufs can be retried after removing a socket. The buffers are not handed back in either case, so check can_accept first.

pub fn accept_with_socket( &mut self, handle: TcpHandle, ) -> Result<(), AcceptError>

Accept a queued connection attempt into an existing socket, reusing its buffers.

The socket must be closed (see is_open), and is set up for the new connection exactly as connect sets it up for an outgoing one: its buffers are cleared and everything you configured on it (hop limit, timeout, keep-alive, Nagle, ACK delay) is kept. Its handle stays valid.

This is how to serve connections without a heap: create the sockets once, with the buffers they will use for the program’s whole life, and accept into them again as each connection ends. accept and accept_with_bufs create a new socket per connection, and buffers lent to the stack are never handed back.

The socket ends up in the SYN-RECEIVED state and sends the SYN|ACK on the next Stack::poll.

Errors:

• InvalidState if the socket is still open.
• Exhausted if no connection attempt is queued.

Panics

Panics if the handle does not belong to a socket of this stack.