Struct glommio::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 calling accept or shared_accept, or by iterating over the Incoming iterator returned by incoming.

A good networking architecture within a thread-per-core model needs to take into account parallelism and spawn work into multiple executors. If everything happens inside the same Executor, then at most one thread is used. Sometimes this is what you want: you may want to dedicate a CPU entirely for networking, or even use specialized ports for each CPU of the application, but most likely it isn’t.

There are two approaches to load balancing possible with the TcpListener:

• By default, the ReusePort flag is set in the socket automatically. The OS already provides some load balancing capabilities with that so you can simply bind to the same address from many executors.

• If that is insufficient or otherwise not desirable, it is possible to use shared_accept instead of accept: that returns an object that implements Send. You can then use a shared_channel to send the accepted connection into multiple executors. The object returned by shared_accept can then be bound to its executor with bind_to_executor, at which point it becomes a standard TcpStream.

Relying on the OS is definitely simpler, but which approach is better depends on the specific needs of your application.

The socket will be closed when the value is dropped.

Implementations

impl TcpListener

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

Creates a TCP listener bound to the specified address.

Binding with port number 0 will request an available port from the OS.

This method sets the ReusePort option in the bound socket, so it is designed to be called from multiple executors to achieve parallelism.

Examples

use glommio::{net::TcpListener, LocalExecutor};

let ex = LocalExecutor::default();
ex.run(async move {
    let listener = TcpListener::bind("127.0.0.1:8000").unwrap();
    println!("Listening on {}", listener.local_addr().unwrap());
});

pub async fn shared_accept(&self) -> Result<AcceptedTcpStream, ()>

Accepts a new incoming TCP connection and allows the result to be sent to a foreign executor

This is similar to accept, except it returns an AcceptedTcpStream instead of a TcpStream. AcceptedTcpStream implements Send, so it can be safely sent for processing over a shared channel to a different executor.

This is useful when the user wants to do her own load balancing across multiple executors instead of relying on the load balancing the OS would do with the ReusePort property of the bound socket.

Examples

use glommio::{net::TcpListener, LocalExecutor};

let ex = LocalExecutor::default();
ex.run(async move {
    let listener = TcpListener::bind("127.0.0.1:8000").unwrap();
    let stream = listener.shared_accept().await.unwrap();
});

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

Accepts a new incoming TCP connection in this executor

This is similar to calling shared_accept and bind_to_executor in a single operation.

If this connection once accepted is to be handled by the same executor in which it was accepted, this version is preferred.

Examples

use futures_lite::stream::StreamExt;
use glommio::{net::TcpListener, LocalExecutor};

let ex = LocalExecutor::default();
ex.run(async move {
    let listener = TcpListener::bind("127.0.0.1:8000").unwrap();
    let stream = listener.accept().await.unwrap();
    println!("Accepted client: {:?}", stream.local_addr());
});

pub fn incoming(&self) -> impl Stream<Item = Result<TcpStream, ()>> + Unpin + '_

Creates a stream of incoming connections

Examples

use futures_lite::stream::StreamExt;
use glommio::{net::TcpListener, LocalExecutor};

let ex = LocalExecutor::default();
ex.run(async move {
    let listener = TcpListener::bind("127.0.0.1:8000").unwrap();
    let mut incoming = listener.incoming();
    while let Some(conn) = incoming.next().await {
        println!("Accepted client: {:?}", conn);
    }
});

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

Returns the socket address of the local half of this TCP connection.

Examples

use glommio::{net::TcpListener, LocalExecutor};

let ex = LocalExecutor::default();
ex.run(async move {
    let listener = TcpListener::bind("127.0.0.1:8000").unwrap();
    println!("Listening on {}", listener.local_addr().unwrap());
});

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

Gets the value of the IP_TTL option for this socket.

This option configures the time-to-live field that is used in every packet sent from this socket.

Examples

use glommio::{net::TcpListener, LocalExecutor};

let ex = LocalExecutor::default();
ex.run(async move {
    let listener = TcpListener::bind("127.0.0.1:8000").unwrap();

    listener.set_ttl(100).expect("could not set TTL");
    assert_eq!(listener.ttl().unwrap(), 100);
});

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

Sets the value of the IP_TTL option for this socket.

This option configures the time-to-live field that is used in every packet sent from this socket.

Examples

use glommio::{net::TcpListener, LocalExecutor};

let ex = LocalExecutor::default();
ex.run(async move {
    let listener = TcpListener::bind("127.0.0.1:8000").unwrap();

    listener.set_ttl(100).expect("could not set TTL");
    assert_eq!(listener.ttl().unwrap(), 100);
});

Trait Implementations

impl Debug for TcpListener

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

Formats the value using the given formatter.