Struct pipebuf::PBufWr

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

Producer reference to a PipeBuf

Obtain this reference using PipeBuf::wr. This is a mutable reference to a PipeBuf that exposes the calls that a producer is allowed to use. It acts just like a &mut PipeBuf, and has the same size and efficiency. However unlike a &mut reference, reborrowing doesn’t happen automatically, but it can still be done just as efficiently using PBufWr::reborrow.

Implementations

impl<'a, T: Copy + Default + 'static> PBufWr<'a, T>

pub fn reborrow<'b, 'r>(&'r mut self) -> PBufWr<'b, T>

where 'a: 'b, 'r: 'b,

Create a new reference from this one, reborrowing it. Thanks to the borrow checker, the original reference will be inaccessible until the returned reference’s lifetime ends. The cost is just a pointer copy, just as for automatic &mut reborrowing.

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 space(&mut self, reserve: usize) -> &mut [T]

Get a reference to a mutable slice of reserve bytes of free space where new data may be written. Once written, the data must be committed immediately using PBufWr::commit, before any other operation that might compact the buffer.

Note that for efficiency the free space will not be initialised to zeros. It will contain some jumble of bytes previously written to the pipe. You must not make any assumptions about this data.

Panics

For a fixed-capacity buffer (created with PipeBuf::with_fixed_capacity or PipeBuf::new_static), panics if there is not enough free space to reserve the given number of bytes.

pub fn try_space(&mut self, reserve: usize) -> Option<&mut [T]>

Get a reference to a mutable slice of reserve bytes of free space where new data may be written. Once written, the data must be committed immediately using PBufWr::commit, before any other operation that might compact the buffer.

Note that for efficiency the free space will not be initialised to zeros. It will contain some jumble of bytes previously written to the pipe. You must not make any assumptions about this data.

Returns None if there is not enough free space available in a fixed-capacity PipeBuf.

pub fn commit(&mut self, len: usize)

Commit the given number of bytes to the pipe buffer. This data should have been written to the start of the slice returned by the PBufWr::space or PBufWr::try_space method just before this call.

Panics

Panics if data is written to the stream after it has been marked as closed or aborted. May panic if more data is committed than the space that was reserved.

pub fn free_space(&self) -> Option<usize>

Return the amount of free space left in the underlying PipeBuf if the capacity is fixed, otherwise None.

Note that in the PipeBuf model backpressure is intended to be handled by the glue code, and in the case of fixed-sized buffers, they should be sized ahead of time adequately for the expected data flowing through the chain. So if only 1000 bytes of data will be consumed at a time, then by calculating the maximum amount of data that could result from processing that 1000 bytes of data you could size all the buffers accordingly in the glue code. So in that case components don’t need to worry about backpressure and PBufWr::space can be used directly without any checks. A panic from PBufWr::space would only indicate that the glue code author had made an error in the sizing calculations. Component code authors could give guidance about buffer sizing in the documentation. So this call would not be required in that case.

However in the case of something like decompression where a small amount of input data may result in a huge amount of data being output, the glue code will need some help. In that case the decompressor may output to a fixed-size pipe buffer and use this call to see how much space is available for output. The glue code may need to run the downstream chain repeatedly until the decompressor has caught up.

So this call can be used as part of a backpressure-aware processing step by only consuming sufficient data to create PBufWr::free_space elements of output.

pub fn push(&mut self)

Set the “push” state on the buffer, which the consumer may use to decide whether or not to flush data immediately.

pub fn append(&mut self, data: &[T])

Append a slice of data to the buffer

Panics

Panics if data is written to the pipe buffer after it has been marked as closed or aborted. For fixed-capacity panics, see PBufWr::space.

pub fn is_eof(&self) -> bool

Test whether end-of-file has already been indicated, either using PBufWr::close or PBufWr::abort. No more data should be written after EOF.

pub fn close(&mut self)

Indicate end-of-file with success. This is a normal EOF, where the data will be complete. The pipe buffer is given the state PBufState::Closing. There may still be unread data in the buffer, but that is the final data before the EOF.

Panics

Panics if end-of-file has already been indicated on this buffer

pub fn abort(&mut self)

Indicate end-of-file with abort. This is an EOF after some kind of failure, where the data may be incomplete. The pipe buffer is given the state PBufState::Aborting.

Panics

Panics if end-of-file has already been indicated on this buffer

pub fn write_with<E>( &mut self, reserve: usize, cb: impl FnMut(&mut [T]) -> Result<usize, E> ) -> Result<usize, E>

Write data to the buffer using a closure. A mutable slice of reserve bytes of free space is passed to the closure. If the closure successfully writes data to the slice, it should return the length written as Ok(len) to commit that data to the buffer. If it fails then it may return any type of its choosing as Err(e). The closure return value is directly returned. If no error-handling is required see PBufWr::write_with_noerr.

Note that for efficiency the free space will not be initialised to zeros. It will contain some jumble of bytes previously written to the pipe. You must not make any assumptions about this data.

Panics

Panics if data is written to the stream after it has been marked as closed or aborted. May panic if more data is committed than the space that was reserved. Also see PBufWr::space for handling of fixed-capacity buffers.

pub fn write_with_noerr( &mut self, reserve: usize, cb: impl FnMut(&mut [T]) -> usize ) -> usize

Write data to the buffer using a closure. A mutable slice of reserve bytes of free space is passed to the closure. If the closure successfully writes data to the slice, it should return the length written to commit that data to the buffer. The same length is returned from this method. To pass through errors see PBufWr::write_with.

Note that for efficiency the free space will not be initialised to zeros. It will contain some jumble of bytes previously written to the pipe. You must not make any assumptions about this data.

Panics

Panics if data is written to the stream after it has been marked as closed or aborted. May panic if more data is committed than the space that was reserved. Also see PBufWr::space for handling of fixed-capacity buffers.

pub fn exceeds_limit(&self, limit: usize) -> bool

Test whether the amount of data stored in the pipe-buffer exceeds the given limit in bytes. It is preferred to not expose any information about the consumer-side of the pipe-buffer to the producer to avoid the producer changing its behaviour depending on how the consumer behaves, which could lead to hard-to-find bugs. However it may be the producer that is enforcing limits to protect against denial-of-service, so this call is provided.

impl<'a> PBufWr<'a, u8>

pub fn input_from(&mut self, source: &mut impl Read, len: usize) -> Result<()>

Available on crate feature std only.

Input data from the given Read implementation, up to the given length. If EOF is indicated by the Read source through an Ok(0) return, then a normal PBufState::Closing EOF is set on the pipe buffer, and no more data will be read in future calls. The read call is retried in case of ErrorKind::Interrupted errors, but all other errors are returned directly. So if the Read implementation supports an error return that indicates that the stream has aborted, that needs handling by the caller.

Use a tripwire (see PBufWr::tripwire) if you need to determine whether or not new data was read. This is necessary because a call may both read data and return an error (for example WouldBlock).

Trait Implementations

impl<'a> Write for PBufWr<'a, u8>

Available on crate feature std only.

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

Write data to the pipe-buffer

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.