Struct piper::Writer

source ·

pub struct Writer { /* private fields */ }

Expand description

The writing side of a pipe.

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

Implementations§

source §

impl Writer

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 (_reader, mut writer) = piper::pipe(10);
let _ = writer.try_fill(&[0u8; 5]);
assert_eq!(writer.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 (_reader, mut writer) = piper::pipe(10);
assert!(writer.is_empty());
let _ = writer.try_fill(&[0u8; 5]);
assert!(!writer.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 (_, writer) = piper::pipe(10);
assert_eq!(writer.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!(!writer.is_full());
let _ = writer.try_fill(&[0u8; 10]);
assert!(writer.is_full());
let _ = reader.try_drain(&mut [0u8; 5]);
assert!(!writer.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 (reader, writer) = piper::pipe(10);
assert!(!writer.is_closed());
drop(reader);
assert!(writer.is_closed());

source

pub fn poll_fill( &mut self, cx: &mut Context<'_>, src: impl Read, ) -> Poll<Result<usize>>

Reads bytes from blocking src and writes into this writer.

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

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

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

§Examples

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

// Create a pipe.
let (mut reader, mut writer) = piper::pipe(1024);

// Fill the pipe with some bytes.
let data = b"hello world";
let n = future::poll_fn(|cx| writer.poll_fill(cx, &data[..])).await.unwrap();
assert_eq!(n, data.len());

// Read the bytes back.
let mut buf = [0; 1024];
reader.read_exact(&mut buf[..data.len()]).await.unwrap();
assert_eq!(&buf[..data.len()], data);

source

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

Writes bytes into this writer.

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

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

§Examples

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

// Create a pipe.
let (mut reader, mut writer) = piper::pipe(1024);

// Fill the pipe with some bytes.
let data = b"hello world";
let n = future::poll_fn(|cx| writer.poll_fill_bytes(cx, &data[..])).await;
assert_eq!(n, data.len());

// Read the bytes back.
let mut buf = [0; 1024];
reader.read_exact(&mut buf[..data.len()]).await.unwrap();
assert_eq!(&buf[..data.len()], data);

source

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

Tries to write bytes to this writer.

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

§Examples

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

let mut buf = [0; 10];
assert_eq!(w.try_fill(&[0, 1, 2, 3, 4]), 5);
assert_eq!(r.try_drain(&mut buf), 5);
assert_eq!(&buf[..5], &[0, 1, 2, 3, 4]);