Struct UnixStream

pub struct UnixStream { /* private fields */ }

A structure representing a connected Unix socket with support for passing RawFd.

This is the implementation of EnqueueFd and DequeueFd that is based on tokio UnixStream. Conceptually the key interfaces on UnixStream interact as shown in the following diagram:

EnqueueFd => AsyncWrite => AsyncRead => DequeueFd

That is, you first enqueue a RawFd to the UnixStream and then AsyncWrite at least one byte. On the other side of the UnixStream you then AsyncRead at least one byte and then dequeue the RawFd.

This socket can be connected directly with UnixStream::connect or accepted from a listener with UnixListener::accept. Additionally, a pair of anonymous Unix sockets can be created with UnixStream::pair.

Examples

use tokio::io::{AsyncReadExt, AsyncWriteExt};
use std::fs::File;

let (mut sock1, mut sock2) = UnixStream::pair()?;

// sender side
// let file1: File = ...
sock1.enqueue(&file1).expect("Can't enqueue the file descriptor.");
sock1.write(b"a").await?;
sock1.flush().await?;

// receiver side
let mut buf = [0u8; 1];
sock2.read(&mut buf).await?;
let fd = sock2.dequeue().expect("Can't dequeue the file descriptor.");
let file2 = unsafe { File::from_raw_fd(fd) };

Implementations

impl UnixStream

pub async fn connect(path: impl AsRef<Path>) -> Result<UnixStream>

Connects to the socket named by path.

This function will create a new socket and connect the the path specified, associating the returned stream with the default event loop’s handle.

Examples

use fd_queue::tokio::UnixStream;
// let path: Path = ...

UnixStream::connect(path).await?;

pub fn pair() -> Result<(UnixStream, UnixStream)>

Creates an unnamed pair of connected sockets.

This function will create an unnamed pair of interconnected Unix sockets for communicating back and forth between one another. Each socket will be associated with the default event loop’s handle.

Examples

use fd_queue::tokio::UnixStream;

let (sock1, sock2) = UnixStream::pair()?;

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

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

Examples

use fd_queue::tokio::UnixStream;

// let path: Path = ...

let sock = UnixStream::connect(path).await?;

sock.local_addr()?;

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

Returns the socket address of the remote half of this connection.

Examples

use fd_queue::tokio::UnixStream;

// let path: Path = ...

let sock = UnixStream::connect(path).await?;

sock.peer_addr()?;

pub fn take_error(&self) -> Result<Option<Error>>

Returns the value of the SO_ERROR option.

Examples

use fd_queue::tokio::UnixStream;

// let path: Path = ...

let sock = UnixStream::connect(path).await?;

let err = match sock.take_error() {
    Ok(Some(err)) => err,
    Ok(None) => {
        println!("No error found.");
        return Ok(());
    }
    Err(e) => {
        println!("Couldn't take the SO_ERROR option: {}", e);
        return Ok(());
    }
};

pub fn shutdown(&self, how: Shutdown) -> Result<()>

Shuts down the read, write, or both halves of this connection.

This function will cause all pending and future I/O calls on the specified portions to immediately return with an appropriate value (see the documentation of Shutdown).

Examples

use std::net::Shutdown;
use tokio::io::AsyncReadExt;
use fd_queue::tokio::UnixStream;

let (mut sock, _) = UnixStream::pair()?;

sock.shutdown(Shutdown::Read)?;

let mut buf = [0u8; 256];
match sock.read(&mut buf).await {
    Ok(0) => {},
    _ => panic!("Read unexpectedly not shut down."),
}

Trait Implementations

impl AsRawFd for UnixStream

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl AsyncRead for UnixStream

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.

impl AsyncWrite for UnixStream

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl Debug for UnixStream

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

Formats the value using the given formatter.

impl DequeueFd for UnixStream

fn dequeue(&mut self) -> Option<RawFd>

Dequeue a previously transmitted RawFd.

impl EnqueueFd for UnixStream

fn enqueue(&mut self, fd: &impl AsRawFd) -> Result<(), QueueFullError>

Enqueue fd for later transmission to a different process.

impl From<UnixStream> for UnixStream

fn from(inner: TokioUnixStream) -> UnixStream

Converts to this type from the input type.

impl TryFrom<UnixStream> for UnixStream

type Error = Error

The type returned in the event of a conversion error.

fn try_from(inner: StdUnixStream) -> Result<Self, Self::Error>

Performs the conversion.

impl<'pin> Unpin for UnixStream

where __UnixStream<'pin>: Unpin,

impl UnsafeUnpin for UnixStream