Struct Receiver

pub struct Receiver { /* private fields */ }

Available on Unix only.

Reading end of a Unix pipe.

It can be constructed from a FIFO file with OpenOptions::open_receiver.

Examples

Receiving messages from a named pipe in a loop:

use std::io;

use compio_buf::BufResult;
use compio_fs::pipe;
use compio_io::AsyncReadExt;

const FIFO_NAME: &str = "path/to/a/fifo";

let mut rx = pipe::OpenOptions::new().open_receiver(FIFO_NAME).await?;
loop {
    let mut msg = Vec::with_capacity(256);
    let BufResult(res, msg) = rx.read_exact(msg).await;
    match res {
        Ok(_) => { /* handle the message */ }
        Err(e) if e.kind() == io::ErrorKind::UnexpectedEof => {
            // Writing end has been closed, we should reopen the pipe.
            rx = pipe::OpenOptions::new().open_receiver(FIFO_NAME).await?;
        }
        Err(e) => return Err(e.into()),
    }
}

On Linux, you can use a Receiver in read-write access mode to implement resilient reading from a named pipe. Unlike Receiver opened in read-only mode, read from a pipe in read-write mode will not fail with UnexpectedEof when the writing end is closed. This way, a Receiver can asynchronously wait for the next writer to open the pipe.

You should not use functions waiting for EOF such as read_to_end with a Receiver in read-write access mode, since it may wait forever. Receiver in this mode also holds an open writing end, which prevents receiving EOF.

To set the read-write access mode you can use OpenOptions::read_write. Note that using read-write access mode with FIFO files is not defined by the POSIX standard and it is only guaranteed to work on Linux.

use compio_fs::pipe;
use compio_io::AsyncReadExt;

const FIFO_NAME: &str = "path/to/a/fifo";

let mut rx = pipe::OpenOptions::new()
    .read_write(true)
    .open_receiver(FIFO_NAME)
    .unwrap();
loop {
    let mut msg = Vec::with_capacity(256);
    rx.read_exact(msg).await.unwrap();
    // handle the message
}

Implementations

impl Receiver

pub fn close(self) -> impl Future<Output = Result<()>>

Close the pipe. If the returned future is dropped before polling, the pipe won’t be closed.

Trait Implementations

impl AsRawFd for Receiver

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl AsyncRead for &Receiver

async fn read<B: IoBufMut>(&mut self, buffer: B) -> BufResult<usize, B>

Read some bytes from this source into the IoBufMut buffer and return a BufResult, consisting of the buffer and a usize indicating how many bytes were read.

async fn read_vectored<V: IoVectoredBufMut>( &mut self, buffer: V, ) -> BufResult<usize, V>

Like read, except that it reads into a type implements IoVectoredBufMut.

impl AsyncRead for Receiver

async fn read<B: IoBufMut>(&mut self, buf: B) -> BufResult<usize, B>

Read some bytes from this source into the IoBufMut buffer and return a BufResult, consisting of the buffer and a usize indicating how many bytes were read.

async fn read_vectored<V: IoVectoredBufMut>( &mut self, buf: V, ) -> BufResult<usize, V>

Like read, except that it reads into a type implements IoVectoredBufMut.

impl Clone for Receiver

fn clone(&self) -> Receiver

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Receiver

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

Formats the value using the given formatter.

impl FromRawFd for Receiver

unsafe fn from_raw_fd(fd: RawFd) -> Self

Constructs a new instance of Self from the given raw file descriptor.

impl ToSharedFd<File> for Receiver

fn to_shared_fd(&self) -> SharedFd<File>

Return a cloned SharedFd.