Struct UdStreamListener

Source

pub struct UdStreamListener { /* private fields */ }

Available on Unix only.

Expand description

A Unix domain byte stream socket server, listening for connections.

All such sockets have the SOCK_STREAM socket type; in other words, this is the Unix domain version of a TCP server.

§Examples

Basic server:

use interprocess::os::unix::udsocket::{UdStream, UdStreamListener};
use std::{io::{self, prelude::*}, net::Shutdown};

fn handle_error(result: io::Result<UdStream>) -> Option<UdStream> {
    match result {
        Ok(val) => Some(val),
        Err(error) => {
            eprintln!("There was an error with an incoming connection: {}", error);
            None
        }
    }
}

let listener = UdStreamListener::bind("/tmp/example.sock")?;
// Outside the loop so that we could reuse the memory allocation for every client
let mut input_string = String::new();
for mut conn in listener.incoming()
    // Use filter_map to report all errors with connections and skip those connections in the loop,
    // making the actual server loop part much cleaner than if it contained error handling as well.
    .filter_map(handle_error) {
    conn.write_all(b"Hello from server!")?;
    conn.shutdown(Shutdown::Write)?;
    conn.read_to_string(&mut input_string)?;
    println!("Client answered: {}", input_string);
    input_string.clear();
}

Implementations§

Source §

impl UdStreamListener

Source

pub fn bind<'a>(path: impl ToUdSocketPath<'a>) -> Result<Self>

Creates a new listener socket at the specified address.

If the socket path exceeds the maximum socket path length (which includes the first 0 byte when using the socket namespace), an error is returned. Errors can also be produced for different reasons, i.e. errors should always be handled regardless of whether the path is known to be short enough or not.

After the socket is dropped, the socket file will be left over. Use bind_with_drop_guard() to mitigate this automatically, even during panics (if unwinding is enabled).

§Example

See ToUdSocketPath.

§System calls

socket
bind

Source

pub fn bind_with_drop_guard<'a>(path: impl ToUdSocketPath<'a>) -> Result<Self>

Creates a new listener socket at the specified address, remembers the address, and installs a drop guard that will delete the socket file once the socket is dropped.

See the documentation of bind().

Source

pub fn accept(&self) -> Result<UdStream>

Listens for incoming connections to the socket, blocking until a client is connected.

See incoming for a convenient way to create a main loop for a server.

§Example

use interprocess::os::unix::udsocket::UdStreamListener;

let listener = UdStreamListener::bind("/tmp/example.sock")?;
loop {
    match listener.accept() {
        Ok(connection) => {
            println!("New client!");
        },
        Err(error) => {
            println!("Incoming connection failed: {}", error);
        },
    }
}

§System calls

accept

Source

pub fn incoming(&self) -> Incoming<'_> ⓘ

Creates an infinite iterator which calls accept() with each iteration. Used together with for loops to conveniently create a main loop for a socket server.

§Example

use interprocess::os::unix::udsocket::UdStreamListener;

let listener = UdStreamListener::bind("/tmp/example.sock")?;
// Thanks to incoming(), you get a simple self-documenting infinite server loop
for connection in listener.incoming()
    .map(|conn| if let Err(error) = conn {
        eprintln!("Incoming connection failed: {}", error);
    }) {
    eprintln!("New client!");
}

Source

pub fn set_nonblocking(&self, nonblocking: bool) -> Result<()>

Enables or disables the nonblocking mode for the listener. By default, it is disabled.

In nonblocking mode, calls to accept, and, by extension, iteration through incoming will never wait for a client to become available to connect and will instead return a WouldBlock error immediately, allowing the thread to perform other useful operations while there are no new client connections to accept.

Source