Struct glommio::net::UnixListener

pub struct UnixListener { /* fields omitted */ }

A Unix socket server, listening for connections.

After creating a UnixListener by binding it to a socket address, it listens for incoming Unix 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 so far only one approach to load balancing possible with the UnixListener:

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

The socket will be closed when the value is dropped.

Implementations

impl UnixListener

pub fn bind<A: AsRef<Path>>(addr: A) -> Result<UnixListener, ()>

Creates a Unix 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::UnixListener, LocalExecutor};

let ex = LocalExecutor::default();
ex.run(async move {
    let _listener = UnixListener::bind("/tmp/named").unwrap();
});

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

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

This is similar to accept, except it returns an AcceptedUnixStream instead of a UnixStream. AcceptedUnixStream 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::UnixListener, LocalExecutor};

let ex = LocalExecutor::default();
ex.run(async move {
    let listener = UnixListener::bind("/tmp/named").unwrap();
    let _stream = listener.shared_accept().await.unwrap();
});

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

Accepts a new incoming Unix 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::UnixListener, LocalExecutor};

let ex = LocalExecutor::default();
ex.run(async move {
    let listener = UnixListener::bind("/tmp/named").unwrap();
    let _stream = listener.accept().await.unwrap();
});

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

Creates a stream of incoming connections

Examples

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

let ex = LocalExecutor::default();
ex.run(async move {
    let listener = UnixListener::bind("/tmp/named").unwrap();
    let mut incoming = listener.incoming();
    while let Some(conn) = incoming.next().await {
        // handle
    }
});

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

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

Examples

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

let ex = LocalExecutor::default();
ex.run(async move {
    let listener = UnixListener::bind("/tmp/named").unwrap();
    println!("Listening on {:?}", listener.local_addr().unwrap());
});

Trait Implementations

impl Debug for UnixListener

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

Formats the value using the given formatter.