Struct TcpListener 

pub struct TcpListener { /* private fields */ }

Available on crate feature net only.

A TCP socket server, listening for connections.

You can accept a new connection by using the accept method.

A TcpListener can be turned into a Stream with TcpListenerStream.

The socket will be closed when the value is dropped.

Errors

Note that accepting a connection can lead to various errors and not all of them are necessarily fatal ‒ for example having too many open file descriptors or the other side closing the connection while it waits in an accept queue. These would terminate the stream if not handled in any way.

Examples

Using accept:

use tokio::net::TcpListener;

use std::io;

async fn process_socket<T>(socket: T) {
    // do work with socket here
}

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:8080").await?;

    loop {
        let (socket, _) = listener.accept().await?;
        process_socket(socket).await;
    }
}

Implementations

impl TcpListener

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

Available on non-loom and non-WASI only.

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.

The address type can be any implementor of the ToSocketAddrs trait. If addr yields multiple addresses, bind will be attempted with each of the addresses until one succeeds and returns the listener. If none of the addresses succeed in creating a listener, the error returned from the last attempt (the last address) is returned.

This function sets the SO_REUSEADDR option on the socket on Unix.

To configure the socket before binding, you can use the TcpSocket type.

Examples

use tokio::net::TcpListener;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:2345").await?;

    // use the listener

    Ok(())
}

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

Available on non-loom only.

Accepts a new incoming connection from this listener.

This function will yield once a new TCP connection is established. When established, the corresponding TcpStream and the remote peer’s address will be returned.

Cancel safety

This method is cancel safe. If the method is used as the event in a tokio::select! statement and some other branch completes first, then it is guaranteed that no new connections were accepted by this method.

Examples

use tokio::net::TcpListener;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:8080").await?;

    match listener.accept().await {
        Ok((_socket, addr)) => println!("new client: {:?}", addr),
        Err(e) => println!("couldn't get client: {:?}", e),
    }

    Ok(())
}

pub fn poll_accept( &self, cx: &mut Context<'_>, ) -> Poll<Result<(TcpStream, SocketAddr)>>

Available on non-loom only.

Polls to accept a new incoming connection to this listener.

If there is no connection to accept, Poll::Pending is returned and the current task will be notified by a waker. Note that on multiple calls to poll_accept, only the Waker from the Context passed to the most recent call is scheduled to receive a wakeup.

pub fn from_std(listener: TcpListener) -> Result<TcpListener>

Available on non-loom only.

Creates new TcpListener from a std::net::TcpListener.

This function is intended to be used to wrap a TCP listener from the standard library in the Tokio equivalent.

This API is typically paired with the socket2 crate and the Socket type to build up and customize a listener before it’s shipped off to the backing event loop. This allows configuration of options like SO_REUSEPORT, binding to multiple addresses, etc.

Notes

The caller is responsible for ensuring that the listener is in non-blocking mode. Otherwise all I/O operations on the listener will block the thread, which will cause unexpected behavior. Non-blocking mode can be set using set_nonblocking.

Passing a listener in blocking mode is always erroneous, and the behavior in that case may change in the future. For example, it could panic.

Examples

use std::error::Error;
use tokio::net::TcpListener;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let std_listener = std::net::TcpListener::bind("127.0.0.1:0")?;
    std_listener.set_nonblocking(true)?;
    let listener = TcpListener::from_std(std_listener)?;
    Ok(())
}

Panics

This function panics if it is not called from within a runtime with IO enabled.

The runtime is usually set implicitly when this function is called from a future driven by a tokio runtime, otherwise runtime can be set explicitly with Runtime::enter function.

pub fn into_std(self) -> Result<TcpListener>

Available on non-loom only.

Turns a tokio::net::TcpListener into a std::net::TcpListener.

The returned std::net::TcpListener will have nonblocking mode set as true. Use set_nonblocking to change the blocking mode if needed.

Examples

use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let tokio_listener = tokio::net::TcpListener::bind("127.0.0.1:0").await?;
    let std_listener = tokio_listener.into_std()?;
    std_listener.set_nonblocking(false)?;
    Ok(())
}

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

Available on non-loom only.

Returns the local address that this listener is bound to.

This can be useful, for example, when binding to port 0 to figure out which port was actually bound.

Examples

use tokio::net::TcpListener;

use std::io;
use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4};

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:8080").await?;

    assert_eq!(listener.local_addr()?,
               SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080)));

    Ok(())
}

pub fn ttl(&self) -> Result<u32>

Available on non-loom only.

Gets the value of the IP_TTL option for this socket.

For more information about this option, see set_ttl.

Examples

use tokio::net::TcpListener;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
   let listener = TcpListener::bind("127.0.0.1:0").await?;

   listener.set_ttl(100).expect("could not set TTL");
   assert_eq!(listener.ttl()?, 100);

   Ok(())
}

pub fn set_ttl(&self, ttl: u32) -> Result<()>

Available on non-loom only.

Sets the value for the IP_TTL option on this socket.

This value sets the time-to-live field that is used in every packet sent from this socket.

Examples

use tokio::net::TcpListener;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:0").await?;

    listener.set_ttl(100).expect("could not set TTL");

    Ok(())
}

Trait Implementations

impl AsFd for TcpListener

Available on non-loom only.

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor.

impl AsRawFd for TcpListener

Available on non-loom only.

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl AsRawSocket for TcpListener

Available on non-loom and Windows only.

fn as_raw_socket(&self) -> RawSocket

Available on docsrs and Unix and (crate features net or fs) only.

See std::os::windows::io::AsRawSocket::as_raw_socket

impl AsSocket for TcpListener

Available on non-loom and Windows only.

fn as_socket(&self) -> BorrowedSocket<'_>

Available on docsrs and Unix and (crate features net or fs) only.

See std::os::windows::io::AsSocket::as_socket

impl Debug for TcpListener

Available on non-loom only.

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

Formats the value using the given formatter.

impl TryFrom<TcpListener> for TcpListener

Available on non-loom only.

fn try_from(stream: TcpListener) -> Result<Self, Self::Error>

Consumes stream, returning the tokio I/O object.

This is equivalent to TcpListener::from_std(stream).

type Error = Error

The type returned in the event of a conversion error.