Struct async_std::net::TcpListener

pub struct TcpListener { /* private fields */ }

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

impl TcpListener

pub async fn bind<A: ToSocketAddrs>(addrs: A) -> Result<TcpListener>

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?;

pub async fn accept(&self) -> Result<(TcpStream, SocketAddr)>

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?;

pub fn incoming(&self) -> Incoming<'_>

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?;
}

pub fn into_incoming(self) -> impl Stream<Item = Result<TcpStream>> + Send

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)
);

pub fn local_addr(&self) -> Result<SocketAddr>

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

impl AsRawFd for TcpListener

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl AsRawSocket for TcpListener

fn as_raw_socket(&self) -> RawSocket

Extracts the underlying raw socket from this object.

impl Debug for TcpListener

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

Formats the value using the given formatter.

impl From<TcpListener> for TcpListener

fn from(listener: TcpListener) -> TcpListener

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

impl FromRawFd for TcpListener

unsafe fn from_raw_fd(fd: RawFd) -> TcpListener

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

impl FromRawSocket for TcpListener

unsafe fn from_raw_socket(handle: RawSocket) -> TcpListener

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

impl IntoRawFd for TcpListener

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.

impl IntoRawSocket for TcpListener

fn into_raw_socket(self) -> RawSocket

Consumes this object, returning the raw underlying socket.

impl TryFrom<TcpListener> for TcpListener

fn try_from(listener: TcpListener) -> Result<TcpListener>

Converts a TcpListener into its synchronous equivalent.

type Error = Error

The type returned in the event of a conversion error.