Struct runtime::net::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.

The Transmission Control Protocol is specified in IETF RFC 793.

Examples

use futures::prelude::*;
use runtime::net::TcpListener;

#[runtime::main]
async fn main() -> std::io::Result<()> {
    let mut listener = TcpListener::bind("127.0.0.1:8080")?;
    println!("Listening on {}", listener.local_addr()?);

    // accept connections and process them in parallel
    let mut incoming = listener.incoming();
    while let Some(stream) = incoming.next().await {
        runtime::spawn(async move {
            let stream = stream?;
            println!("Accepting from: {}", stream.peer_addr()?);

            let (reader, writer) = &mut stream.split();
            reader.copy_into(writer).await?;
            Ok::<(), std::io::Error>(())
        });
    }
    Ok(())
}

Methods

impl TcpListener

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

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:0:

use runtime::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:0")?;

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

Returns the local address that this listener is bound to.

This can be useful, for example, to identify when binding to port 0 which port was assigned by the OS.

Examples

use runtime::net::TcpListener;
use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4};

let listener = TcpListener::bind("127.0.0.1:8080")?;

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

pub fn incoming(&mut self) -> IncomingStream

Handle all incoming connections.

This method returns a stream of TcpStreams. This is useful when you want to open up a port that can handle multiple incoming requests.

If you intend to only handle single connections use .accept().

Examples

use futures::prelude::*;
use runtime::net::TcpListener;

let mut listener = TcpListener::bind("127.0.0.1:0")?;
let mut incoming = listener.incoming();
while let Some(stream) = incoming.next().await {
    match stream {
        Ok(stream) => println!("new client!"),
        Err(e) => { /* connection failed */ }
    }
}

Important traits for AcceptFuture<'stream>

impl<'stream> Future for AcceptFuture<'stream> type Output = Result<(TcpStream, SocketAddr)>;

pub fn accept(&mut self) -> AcceptFuture

Handle an incoming connection.

This is useful when you quickly want to receive an incoming TCP connection to quickly connect two points on a network.

If you intend to handle all incoming connections use .incoming().

Examples

use futures::prelude::*;
use runtime::net::TcpListener;

let mut listener = TcpListener::bind("127.0.0.1:0")?;
let (stream, addr) = listener.accept().await?;
println!("Connected to {}", addr);

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.