Struct Reader

Source

pub struct Reader { /* private fields */ }

Expand description

The reading side of a pipe.

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

Implementations§

Source §

impl Reader

Source

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.try_fill(&[0u8; 5]);
assert_eq!(reader.len(), 5);

Source

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.try_fill(&[0u8; 5]);
assert!(!reader.is_empty());

Source

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);

Source

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.try_fill(&[0u8; 10]);
assert!(reader.is_full());
let _ = reader.try_drain(&mut [0u8; 5]);
assert!(!reader.is_full());

Source

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());

Source

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");

Source

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");

Source

pub fn poll(&mut self, cx: &mut Context<'_>) -> Poll<bool>

Poll for data to become available in the pipe or the write side to be closed.

Returns Poll::Ready(true) when data is ready. Call peek_buf() to access the data, and consume() to advance the read position.

A return value of Poll::Ready(false) indicates that the pipe is closed.

If no data is available, this method will return Poll::Pending and register the waker to receive a notification when data is written to the pipe or the write end is closed.

Unlike AsyncBufRead::poll_fill_buf method, this method is infallible and does not require the std feature. It separates the polling, buffer access, and consume steps for compatibility with poll_fn’s lifetime requirements.

§Example

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();

future::poll_fn(|cx| r.poll(cx)).await;
let buf = r.peek_buf();
assert_eq!(buf, &b"hello world"[..buf.len()]);

// Consume one byte
r.consume(1);

future::poll_fn(|cx| r.poll(cx)).await;
let buf = r.peek_buf();
assert_eq!(buf, &b"ello world"[..buf.len()]);

r.consume(buf.len());

Source

pub fn peek_buf(&self) -> &[u8] ⓘ

Return the contents of the internal buffer that are available immediately.

Call Self::consume() to consume the bytes returned by this method. The buffer might not re-fill until another call to Self::poll() returns Poll::Ready.

Source

pub fn consume(&mut self, amt: usize)

Consume amt bytes from the pipe.

Panics if amt is greater than the length of the buffer returned by Self::peek_buf().

Source

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]);