logo
pub struct TcpListener { /* private fields */ }
Expand description

A TCP socket server, listening for connections.

After creating a TcpListener by binding it to a socket address, it listens for incoming TCP connections. These can be accepted by awaiting elements from the async stream of incoming connections.

The socket will be closed when the value is dropped.

The Transmission Control Protocol is specified in IETF RFC 793.

This type is an async version of std::net::TcpListener.

Examples

use async_std::io;
use async_std::net::TcpListener;
use async_std::prelude::*;

let listener = TcpListener::bind("127.0.0.1:8080").await?;
let mut incoming = listener.incoming();

while let Some(stream) = incoming.next().await {
    let stream = stream?;
    let (reader, writer) = &mut (&stream, &stream);
    io::copy(reader, writer).await?;
}

Implementations

Creates a new TcpListener which will be bound to the specified address.

The returned listener is ready for accepting connections.

Binding with a port number of 0 will request that the OS assigns a port to this listener. The port allocated can be queried via the local_addr method.

Examples

Create a TCP listener bound to 127.0.0.1:0:

use async_std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:0").await?;

Accepts a new incoming connection to this listener.

When a connection is established, the corresponding stream and address will be returned.

Examples
use async_std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:0").await?;
let (stream, addr) = listener.accept().await?;

Returns a stream of incoming connections.

Iterating over this stream is equivalent to calling accept in a loop. The stream of connections is infinite, i.e awaiting the next connection will never result in None.

Examples
use async_std::net::TcpListener;
use async_std::prelude::*;

let listener = TcpListener::bind("127.0.0.1:0").await?;
let mut incoming = listener.incoming();

while let Some(stream) = incoming.next().await {
    let mut stream = stream?;
    stream.write_all(b"hello world").await?;
}

Turn this into a stream over the connections being received on this listener.

The returned stream is infinite and will also not yield the peer’s SocketAddr structure. Iterating over it is equivalent to calling TcpListener::accept in a loop.

Examples

Merge the incoming connections of multiple sockets into one Stream:

use async_std::net::TcpListener;

// Our server listens on multiple ports for some reason
let listeners = vec![
    TcpListener::bind("[::0]:8080").await?,
    TcpListener::bind("[::0]:12345").await?,
    TcpListener::bind("[::0]:5678").await?,
];
// Iterate over all incoming connections
let incoming = futures::stream::select_all(
    listeners.into_iter()
        .map(TcpListener::into_incoming)
        .map(Box::pin)
);

Returns the local address that this listener is bound to.

This can be useful, for example, to identify when binding to port 0 which port was assigned by the OS.

Examples
use async_std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:8080").await?;
let addr = listener.local_addr()?;

Trait Implementations

Extracts the raw file descriptor. Read more

Extracts the underlying raw socket from this object.

Formats the value using the given formatter. Read more

Converts a std::net::TcpListener into its asynchronous equivalent.

Constructs a new instance of Self from the given raw file descriptor. Read more

Creates a new I/O object from the given raw socket. Read more

Consumes this object, returning the raw underlying file descriptor. Read more

Consumes this object, returning the raw underlying socket. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.