Struct TcpListener

Source

pub struct TcpListener { /* private fields */ }

Available on crate feature tcp only.

Expand description

A TCP socket server, listening for connections.

§Examples

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

Implementations§

Source §

impl TcpListener

Source

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

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

    // use the listener

    Ok(())
}

Source

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

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

Source

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

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

Source

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

Source

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

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

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 */ }
        }
    }
}

Source

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

Source

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