pub struct PBufWr<'a, T: 'static = u8> { /* private fields */ }
Expand description
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§
source§impl<'a, T: Copy + Default + 'static> PBufWr<'a, T>
impl<'a, T: Copy + Default + 'static> PBufWr<'a, T>
sourcepub fn reborrow<'b, 'r>(&'r mut self) -> PBufWr<'b, T>where
'a: 'b,
'r: 'b,
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.
sourcepub fn tripwire(&self) -> PBufTrip
pub fn tripwire(&self) -> PBufTrip
Obtain a tripwire value to detect buffer changes. See the
PBufTrip
type for further explanation.
sourcepub fn is_tripped(&self, trip: PBufTrip) -> bool
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
.
sourcepub fn space(&mut self, reserve: usize) -> &mut [T]
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.
sourcepub fn try_space(&mut self, reserve: usize) -> Option<&mut [T]>
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
.
sourcepub fn commit(&mut self, len: usize)
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.
sourcepub fn free_space(&self) -> Option<usize>
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.
sourcepub fn push(&mut self)
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.
sourcepub fn append(&mut self, data: &[T])
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
.
sourcepub fn is_eof(&self) -> bool
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.
sourcepub fn close(&mut self)
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.
If the stream is already closed or aborted then ignores this call. This makes certain component handling less error-prone.
sourcepub fn abort(&mut self)
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
.
If the stream is already closed or aborted then ignores this
call. This makes certain component handling less error-prone.
The reason for allowing a close followed by an abort to remain
as a close is because at the point that the close was
performed, the code considered that the stream was complete
and valid. Also, the Closing
status may already have been
observed.
sourcepub fn write_with<E>(
&mut self,
reserve: usize,
cb: impl FnMut(&mut [T]) -> Result<usize, E>,
) -> Result<usize, E>
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.
sourcepub fn write_with_noerr(
&mut self,
reserve: usize,
cb: impl FnMut(&mut [T]) -> usize,
) -> usize
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.
sourcepub fn exceeds_limit(&self, limit: usize) -> bool
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.
source§impl<'a> PBufWr<'a, u8>
impl<'a> PBufWr<'a, u8>
sourcepub fn input_from(&mut self, source: &mut impl Read, len: usize) -> Result<()>
Available on crate feature std
only.
pub fn input_from(&mut self, source: &mut impl Read, len: usize) -> Result<()>
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§
source§impl<'a> Write for PBufWr<'a, u8>
Available on crate feature std
only.
impl<'a> Write for PBufWr<'a, u8>
std
only.source§fn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)1.0.0 · source§fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
source§fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)