Trait TcpListener

pub trait TcpListener: Sized {
    type Stream: TcpStream;

    // Required methods
    fn bind(addr: SocketAddr) -> Bind<Self> ;
    fn local_addr(&self) -> Result<SocketAddr>;
    fn poll_accept(
        &self,
        ctx: &mut Context<'_>,
    ) -> Poll<Result<(Self::Stream, SocketAddr)>>;
    fn ttl(&self) -> Result<u32>;
    fn set_ttl(&self, ttl: u32) -> Result<()>;

    // Provided methods
    fn accept(&self) -> Accept<'_, Self>  { ... }
    fn incoming(&self) -> Incoming<'_, Self> { ... }
}

A TCP socket server, listening for connections.

After creating a TcpListener by binding it to a socket address, it listens for incoming TCP connections. Thse can be accepted by calling accept() or by awaiting items from the stream of incoming connections.

The socket will be closed when all handles to it are dropped.

The Transmission Control Protocol is specified in IETF RFC 793.

Required Associated Types

type Stream: TcpStream

The type of a TCP connection created by accepting an incoming connection.

Required Methods

fn bind(addr: SocketAddr) -> Bind<Self>

Creates a new TcpListener bound to the given address.

Binding with a port number of 0 will request that the operating system assigns an available port to this listener. The assigned port can be queried via local_addr().

Examples

use async_tcp::TcpListener;
use std::net::SocketAddr;
use std::str::FromStr;

let addr = SocketAddr::from_str("127.0.0.1:0").unwrap();
let listener = async_net::TcpListener::bind(addr).await?;

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

Returns the local socket address of this listener.

Examples

use async_tcp::TcpListener;
use std::net::SocketAddr;
use std::str::FromStr;

let addr = SocketAddr::from_str("127.0.0.1:1105").unwrap();
let listener = async_net::TcpListener::bind(addr).await?;

assert_eq!(addr, listener.local_addr()?);

fn poll_accept( &self, ctx: &mut Context<'_>, ) -> Poll<Result<(Self::Stream, SocketAddr)>>

Attempts to accept a new incoming connection from this listener.

On success, returns a TcpStream and the address it is connected to.

If no new incoming connection is ready to be accepted, the current task is registered to be notified when one becomes ready to be accepted or the socket closed, and Poll::Pending is returned.

This method exists to be used by accept() and incoming(), we recommend you use of these methods instead.

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

Gets the value of the IP_TTL option on this socket.

For more information about this option, see set_ttl().

Examples

use async_tcp::TcpListener;
use std::net::SocketAddr;
use std::str::FromStr;

let addr = SocketAddr::from_str("127.0.0.1:0").unwrap();
let listener = async_net::TcpListener::bind(addr).await.unwrap();

listener.set_ttl(100)?;
assert_eq!(listener.ttl()?, 100);

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.

Example

use async_tcp::TcpListener;
use std::net::SocketAddr;
use std::str::FromStr;

let addr = SocketAddr::from_str("127.0.0.1:0").unwrap();
let listener = async_net::TcpListener::bind(addr).await.unwrap();

listener.set_ttl(100)?;
assert_eq!(listener.ttl()?, 100);

Provided Methods

fn accept(&self) -> Accept<'_, Self>

Accepts a new incoming connection.

Returns a TcpStream and the address it is connected to.

Examples

use async_tcp::{TcpListener, TcpStream};
use std::net::SocketAddr;
use std::str::FromStr;

let addr = SocketAddr::from_str("127.0.0.1:0").unwrap();
let listener = async_net::TcpListener::bind(addr).await?;

let (stream, addr) = listener.accept().await?;
assert_eq!(stream.peer_addr()?, addr);

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

Returns a stream of incoming connections.

Iterating over this stream is equivalent to calling accept() in a loop. The stream of connections is infinite, ie. it will never return None.

Examples

use async_tcp::{TcpListener, TcpStream};
use futures_lite::StreamExt;
use std::net::SocketAddr;
use std::str::FromStr;

let addr = SocketAddr::from_str("127.0.0.1:0").unwrap();
let listener = async_net::TcpListener::bind(addr).await?;
let mut incoming = listener.incoming();

while let Some(stream) = incoming.next().await {
    let mut stream = stream?;
    assert_eq!(stream.local_addr()?, listener.local_addr()?);
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors