Struct pipebuf::PipeBuf

pub struct PipeBuf<T: 'static = u8> { /* private fields */ }

Efficient byte-pipe buffer

This is the interface that is intended for use by the glue code. Use PipeBuf::wr to get a PBufWr reference to write to the buffer, and PipeBuf::rd get a PBufRd reference to read from the buffer. These are the references that should be passed to component code. See this crate’s top-level documentation for further discussion of how this works.

Implementations

impl<T: Copy + Default + 'static> PipeBuf<T>

pub fn new() -> Self

Available on crate features std and alloc only.

Create a new empty pipe buffer

pub fn with_capacity(cap: usize) -> Self

Available on crate features std and alloc only.

Create a new pipe buffer with the given initial capacity

pub fn with_fixed_capacity(cap: usize) -> Self

Available on crate features std and alloc only.

Create a new pipe buffer with the given fixed capacity. The buffer will never be reallocated. If a PBufWr::space call requests more space than is available, then the call will panic.

pub fn new_static(buffer: &'static mut [T]) -> Self

Available on crate feature static only.

Create a new pipe buffer backed by the given static memory. This is useful for no_std without an allocator. This is a safe call, but requires use of unsafe in caller code because the caller must guarantee that no other code is using this static memory.

static mut BUF: [u8; 1024] = [0; 1024];
let _ = PipeBuf::new_static(unsafe { &mut BUF });

pub fn reset(&mut self)

Reset the buffer to its initial state, i.e. in the Open state and empty. The buffer backing memory is not zeroed, so malicious code may observe old data in the slice returned by PBufWr::space. If sensitive data would be exposed in this case, use PipeBuf::reset_and_zero instead.

pub fn reset_and_zero(&mut self)

Zero the buffer, and reset it to its initial state. If a PipeBuf is going to be kept in a pool and reused, it may be best to zero it after use so that no sensitive data can leak between different parts of the codebase.

pub fn rd(&mut self) -> PBufRd<'_, T>

Get a consumer reference to the buffer

pub fn wr(&mut self) -> PBufWr<'_, T>

Get a producer reference to the buffer

pub fn tripwire(&self) -> PBufTrip

Obtain a tripwire value to detect buffer changes. See the PBufTrip type for further explanation.

pub fn is_tripped(&self, trip: PBufTrip) -> bool

Test whether there has been a change to the buffer since the tripwire value provided was obtained. See PBufTrip.

pub fn state(&self) -> PBufState

Get the current EOF/push state of the buffer

pub fn is_push(&self) -> bool

Test whether the “push” state is set on the buffer without changing the state.

pub fn set_push(&mut self, push: bool)

Change the “push” state. It may be necessary for the glue code to override the “push” status being set by a producer if the producer is flushing its output too frequently for optimal operation of a downstream component.

pub fn is_done(&self) -> bool

Test whether an EOF has been indicated and consumed, and for the case of a Closed EOF also that the buffer is empty. This means that processing on this PipeBuf is complete

Trait Implementations

impl<T: Copy + Default + 'static> Default for PipeBuf<T>

Available on crate features std and alloc only.

fn default() -> Self

Returns the “default value” for a type.

impl Read for PipeBuf<u8>

Available on crate feature std only.

fn read(&mut self, data: &mut [u8]) -> Result<usize, Error>

Read data from the pipe-buffer, as much as is available. The following returns are possible:

• Ok(len): Some data was read
• Ok(0): Successful end-of-file was reached
• Err(e) with e.kind() == ErrorKind::WouldBlock: No data available right now
• Err(e) with e.kind() == ErrorKind::ConnectionAborted: Aborted end-of-file was reached

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Read the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl Write for PipeBuf<u8>

Available on crate feature std only.

fn write(&mut self, data: &[u8]) -> Result<usize, Error>

Write data to the pipe-buffer. Never returns an error. For variable-capacity, always succeeds. For fixed-capacity may panic in case more data is written than there is space available.

fn flush(&mut self) -> Result<(), Error>

Flush sets the “push” state on the PipeBuf

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

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

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.