Struct tokio::net::TcpListener

pub struct TcpListener { /* fields omitted */ }

A TCP socket server, listening for connections.

You can accept a new connection by using the accept method. Alternatively TcpListener implements the Stream trait, which allows you to use the listener in places that want a stream. The stream will never return None and will also not yield the peer's SocketAddr structure. Iterating over it is equivalent to calling accept in a loop.

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 mut listener = TcpListener::bind("127.0.0.1:8080").await?;

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

Using impl Stream:

use tokio::{net::TcpListener, stream::StreamExt};

#[tokio::main]
async fn main() {
    let mut listener = TcpListener::bind("127.0.0.1:8080").await.unwrap();
    while let Some(stream) = listener.next().await {
        match stream {
            Ok(stream) => {
                println!("new client!");
            }
            Err(e) => { /* connection failed */ }
        }
    }
}

Implementations

impl TcpListener

pub async fn bind<A: ToSocketAddrs>(addr: 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.

The address type can be any implementor of the ToSocketAddrs trait. Note that strings only implement this trait when the dns feature is enabled, as strings may contain domain names that need to be resolved.

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.

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(())
}

Without the dns feature:

use tokio::net::TcpListener;
use std::net::Ipv4Addr;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind((Ipv4Addr::new(127, 0, 0, 1), 2345)).await?;

    // use the listener

    Ok(())
}

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

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.

Examples

use tokio::net::TcpListener;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let mut 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(
    &mut self,
    cx: &mut Context<'_>
) -> Poll<Result<(TcpStream, SocketAddr)>>

Attempts to poll SocketAddr and TcpStream bound to this address.

In case if I/O resource isn't ready yet, Poll::Pending is returned and current task will be notified by a waker.

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

Creates a new TCP listener from the standard library's TCP listener.

This method can be used when the Handle::tcp_listen method isn't sufficient because perhaps some more configuration is needed in terms of before the calls to bind and listen.

This API is typically paired with the net2 crate and the TcpBuilder 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.

The addr argument here is one of the addresses that listener is bound to and the listener will only be guaranteed to accept connections of the same address type currently.

The platform specific behavior of this function looks like:

• On Unix, the socket is placed into nonblocking mode and connections can be accepted as normal

• On Windows, the address is stored internally and all future accepts will only be for the same IP version as addr specified. That is, if addr is an IPv4 address then all sockets accepted will be IPv4 as well (same for IPv6).

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")?;
    let listener = TcpListener::from_std(std_listener)?;
    Ok(())
}

Panics

This function panics if thread-local runtime is not set.

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 Handle::enter function.

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

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 incoming(&mut self) -> Incoming<'_>

Returns a stream over the connections being received on this listener.

Note that TcpListener also directly implements Stream.

The returned stream will never return None and will also not yield the peer's SocketAddr structure. Iterating over it is equivalent to calling accept in a loop.

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

use tokio::{net::TcpListener, stream::StreamExt};

#[tokio::main]
async fn main() {
    let mut listener = TcpListener::bind("127.0.0.1:8080").await.unwrap();
    let mut incoming = listener.incoming();

    while let Some(stream) = incoming.next().await {
        match stream {
            Ok(stream) => {
                println!("new client!");
            }
            Err(e) => { /* connection failed */ }
        }
    }
}

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

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

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 AsRawFd for TcpListener

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for TcpListener

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

Formats the value using the given formatter.

impl Stream for TcpListener

type Item = Result<TcpStream>

Values yielded by the stream.

fn poll_next(
    self: Pin<&mut Self>,
    cx: &mut Context<'_>
) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.

impl TryFrom<TcpListener> for TcpListener

type Error = Error

The type returned in the event of a conversion error.

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

Consumes value, returning the mio I/O object.

See PollEvented::into_inner for more details about resource deregistration that happens during the call.

impl TryFrom<TcpListener> for TcpListener

type Error = Error

The type returned in the event of a conversion error.

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