Struct romio::tcp::TcpListener

pub struct TcpListener { /* fields omitted */ }

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

The socket will be closed when the value is dropped.

Examples

use std::error::Error;

use romio::tcp::{TcpListener, TcpStream};
use futures::prelude::*;

async fn recite_shakespeare(mut stream: TcpStream) {
    stream.write_all(b"Shall I hear more, or shall I speak at this?").await;
}

async fn listen() -> Result<(), Box<dyn Error + 'static>> {
    let socket_addr = "127.0.0.1:80".parse()?;
    let mut listener = TcpListener::bind(&socket_addr)?;
    let mut incoming = listener.incoming();

    // accept connections and process them serially
    while let Some(stream) = incoming.next().await {
        recite_shakespeare(stream?).await;
    }
    Ok(())
}

Methods

impl TcpListener

pub fn bind(addr: &SocketAddr) -> 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:80:

use romio::tcp::TcpListener;

let socket_addr = "127.0.0.1:80".parse()?;
let listener = TcpListener::bind(&socket_addr)?;

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 romio::tcp::TcpListener;
use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4};

let socket_addr = "127.0.0.1:8080".parse()?;
let listener = TcpListener::bind(&socket_addr)?;

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

pub fn incoming(&mut self) -> Incoming

Consumes this listener, returning a stream of the sockets this listener accepts.

This method returns an implementation of the Stream trait which resolves to the sockets the are accepted on this listener.

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 futures::prelude::*;
use romio::tcp::TcpListener;

let socket_addr = "127.0.0.1:80".parse()?;
let mut listener = TcpListener::bind(&socket_addr)?;
let mut incoming = listener.incoming();

// accept connections and process them serially
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 futures::prelude::*;
use romio::tcp::TcpListener;

let socket_addr = "127.0.0.1:0".parse()?;
let listener = TcpListener::bind(&socket_addr)?;
listener.set_ttl(100)?;
assert_eq!(listener.ttl()?, 100);

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 futures::prelude::*;
use romio::tcp::TcpListener;

let socket_addr = "127.0.0.1:0".parse()?;
let listener = TcpListener::bind(&socket_addr)?;
listener.set_ttl(100)?;

Trait Implementations

impl Debug for TcpListener

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

Formats the value using the given formatter.

impl AsRawFd for TcpListener

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl AsyncReady for TcpListener

type Ok = (TcpStream, SocketAddr)

The type of successful values yielded by this trait.

type Err = Error

The type of failures yielded by this trait.

fn poll_ready(
    self: Pin<&mut Self>,
    cx: &mut Context
) -> Poll<Result<Self::Ok, Self::Err>>

Check if the stream can be read from.

fn poll_ready_unpin(
    &mut self,
    cx: &mut Context
) -> Poll<Result<Self::Ok, Self::Err>> where
    Self: Unpin, 

A convenience for calling AsyncReady::poll_ready on Unpin types.