Struct piper::Reader

pub struct Reader { /* private fields */ }

The reading side of a pipe.

This type is created by the pipe function. See its documentation for more details.

Implementations

impl Reader

pub fn len(&self) -> usize

Gets the total length of the data in the pipe.

This method returns the number of bytes that have been written into the pipe but haven’t been read yet.

Examples

let (mut reader, mut writer) = piper::pipe(10);
let _ = writer.poll_fill_bytes(cx, &[0u8; 5]);
assert_eq!(reader.len(), 5);

pub fn is_empty(&self) -> bool

Tell whether or not the pipe is empty.

This method returns true if the pipe is empty, and false otherwise.

Examples

let (mut reader, mut writer) = piper::pipe(10);
assert!(reader.is_empty());
let _ = writer.poll_fill_bytes(cx, &[0u8; 5]);
assert!(!reader.is_empty());

pub fn capacity(&self) -> usize

Gets the total capacity of the pipe.

This method returns the number of bytes that the pipe can hold at a time.

Examples

let (reader, _) = piper::pipe(10);
assert_eq!(reader.capacity(), 10);

pub fn is_full(&self) -> bool

Tell whether or not the pipe is full.

The pipe is full if the number of bytes written into it is equal to its capacity. At this point, writes will block until some data is read from the pipe.

This method returns true if the pipe is full, and false otherwise.

Examples

let (mut reader, mut writer) = piper::pipe(10);
assert!(!reader.is_full());
let _ = writer.poll_fill_bytes(cx, &[0u8; 10]);
assert!(reader.is_full());
let _ = reader.poll_drain_bytes(cx, &mut [0u8; 5]);
assert!(!reader.is_full());

pub fn is_closed(&self) -> bool

Tell whether or not the pipe is closed.

The pipe is closed if either the reader or the writer has been dropped. At this point, attempting to write into the pipe will return Poll::Ready(Ok(0)) and attempting to read from the pipe after any previously written bytes are read will return Poll::Ready(Ok(0)).

Examples

let (mut reader, mut writer) = piper::pipe(10);
assert!(!reader.is_closed());
drop(writer);
assert!(reader.is_closed());

pub fn poll_drain( &mut self, cx: &mut Context<'_>, dest: impl Write ) -> Poll<Result<usize>>

Reads bytes from this reader and writes into blocking dest.

This method reads directly from the pipe’s internal buffer into dest. This avoids an extra copy, but it may block the thread if dest blocks.

If the pipe is empty, this method returns Poll::Pending. If the pipe is closed, this method returns Poll::Ready(Ok(0)). Errors in dest are bubbled up through Poll::Ready(Err(e)). Otherwise, this method returns Poll::Ready(Ok(n)) where n is the number of bytes written.

This method is only available when the std feature is enabled. For no_std environments, consider using poll_drain_bytes instead.

Examples

use futures_lite::{future, prelude::*};

let (mut r, mut w) = piper::pipe(1024);

// Write some data to the pipe.
w.write_all(b"hello world").await.unwrap();

// Try reading from the pipe.
let mut buf = [0; 1024];
let n = future::poll_fn(|cx| r.poll_drain(cx, &mut buf[..])).await.unwrap();

// The data was written to the buffer.
assert_eq!(&buf[..n], b"hello world");

pub fn poll_drain_bytes( &mut self, cx: &mut Context<'_>, dest: &mut [u8] ) -> Poll<usize>

Reads bytes from this reader.

Rather than taking a Write trait object, this method takes a slice of bytes to write into. Because of this, it is infallible and can be used in no_std environments.

The same conditions that apply to poll_drain apply to this method.

Examples

use futures_lite::{future, prelude::*};
let (mut r, mut w) = piper::pipe(1024);

// Write some data to the pipe.
w.write_all(b"hello world").await.unwrap();

// Try reading from the pipe.
let mut buf = [0; 1024];
let n = future::poll_fn(|cx| r.poll_drain_bytes(cx, &mut buf[..])).await;

// The data was written to the buffer.
assert_eq!(&buf[..n], b"hello world");

pub fn try_drain(&mut self, dest: &mut [u8]) -> usize

Tries to read bytes from this reader.

Returns the total number of bytes that were read from this reader.

Examples

let (mut r, mut w) = piper::pipe(1024);

// `try_drain()` returns 0 off the bat.
let mut buf = [0; 10];
assert_eq!(r.try_drain(&mut buf), 0);

// After a write it returns the data.
w.try_fill(&[0, 1, 2, 3, 4]);
assert_eq!(r.try_drain(&mut buf), 5);
assert_eq!(&buf[..5], &[0, 1, 2, 3, 4]);

Trait Implementations

impl AsyncRead for Reader

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

Attempt to read from the AsyncRead into buf.

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

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl Drop for Reader

fn drop(&mut self)

Executes the destructor for this type.