pub struct AsyncBufferedOutput<O>{ /* private fields */ }Expand description
Buffered asynchronous item output.
Accepted items remain owned by this wrapper until the inner output accepts
them. Partial writes are committed before another Poll::Pending, making
flushing cancellation-safe. Dropping this type cannot perform asynchronous
I/O; callers that need delivery guarantees must poll flush to completion
or recover the pending buffer through Self::into_parts.
§Type Parameters
O: Asynchronous item output type.
Implementations§
Source§impl<O> AsyncBufferedOutput<O>
impl<O> AsyncBufferedOutput<O>
Sourcepub fn new(inner: O) -> Self
pub fn new(inner: O) -> Self
Creates a buffered output with the default item capacity.
§Parameters
inner: Asynchronous item output to buffer.
§Returns
Returns a buffered output with DEFAULT_BUFFER_CAPACITY items.
§Panics
Panics if O::Item::default() or O::Item::clone() panics, or the
default backing length exceeds Vec’s supported capacity.
Sourcepub fn with_capacity(inner: O, capacity: usize) -> Self
pub fn with_capacity(inner: O, capacity: usize) -> Self
Creates a buffered output with a requested item capacity.
§Parameters
inner: Asynchronous item output to buffer.capacity: Requested number of buffered items.
§Returns
Returns a buffered output whose actual capacity is at least one.
§Panics
Panics if O::Item::default() or O::Item::clone() panics, or the
requested backing length exceeds Vec’s supported capacity.
Sourcepub fn try_with_capacity(
inner: O,
capacity: usize,
) -> Result<Self, TryReserveError>
pub fn try_with_capacity( inner: O, capacity: usize, ) -> Result<Self, TryReserveError>
Tries to create a buffered output with a requested item capacity.
§Parameters
inner: Asynchronous item output to buffer.capacity: Requested number of buffered items.
§Returns
Returns a buffered output whose actual capacity is at least one.
§Errors
Returns the allocation error when the backing buffer cannot be allocated.
§Panics
Panics if initializing the backing buffer requires
O::Item::default() or O::Item::clone() and either operation panics.
Sourcepub const fn inner(&self) -> &O
pub const fn inner(&self) -> &O
Returns a shared reference to the wrapped output.
§Returns
Returns the wrapped output. Items may still be pending in this wrapper.
Sourcepub fn inner_mut(&mut self) -> &mut O
pub fn inner_mut(&mut self) -> &mut O
Returns a mutable reference to the wrapped output.
Direct output calls can be ordered before items retained in the buffer.
§Returns
Returns the wrapped output.
Sourcepub fn into_parts(self) -> (O, Buffer<O::Item>)
pub fn into_parts(self) -> (O, Buffer<O::Item>)
Consumes this wrapper without flushing the wrapped output.
This method does not call AsyncOutput::flush_async and performs no
asynchronous I/O. Call AsyncOutput::flush_async before this method
for normal completion. Otherwise, the returned buffer contains the
pending items that the caller must write before continuing the logical
stream.
§Returns
Returns the wrapped output and pending item buffer.
Sourcepub fn capacity(&self) -> usize
pub fn capacity(&self) -> usize
Returns the internal item capacity.
§Returns
Returns the total number of items in the backing buffer.
Sourcepub const fn pending_len(&self) -> usize
pub const fn pending_len(&self) -> usize
Returns the number of pending buffered items.
§Returns
Returns the readable-window length awaiting delivery.
Sourcepub fn pending(&self) -> &[O::Item]
pub fn pending(&self) -> &[O::Item]
Returns the pending buffered item window.
§Returns
Returns items accepted by this wrapper but not yet accepted by the inner output.
Sourcepub fn try_reserve_capacity(
&mut self,
capacity: usize,
) -> Result<(), TryReserveError>
pub fn try_reserve_capacity( &mut self, capacity: usize, ) -> Result<(), TryReserveError>
Tries to ensure that the internal item capacity is at least capacity.
Pending items are retained and this method performs no I/O.
§Parameters
capacity: Minimum total item capacity to reserve.
§Returns
Returns Ok(()) after the backing buffer has at least capacity
item slots.
§Errors
Returns the allocation error when the backing buffer cannot grow.
§Panics
Panics if growing the backing buffer requires O::Item::default() or
O::Item::clone() and either operation panics.
Sourcepub fn spare_capacity(&self) -> usize
pub fn spare_capacity(&self) -> usize
Returns the unused capacity in the internal buffer.
§Returns
Returns the number of items that can be buffered without draining.
Sourcepub fn spare_raw_parts_mut(&mut self) -> (&mut [O::Item], usize, usize)
pub fn spare_raw_parts_mut(&mut self) -> (&mut [O::Item], usize, usize)
Returns the full backing storage and its spare-tail range.
Call Self::advance after writing initialized items into the returned
spare range.
§Returns
Returns the backing storage together with the first and past-the-end indexes of its spare range.
Sourcepub fn poll_ensure_spare_capacity(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
count: usize,
) -> Poll<Result<()>>
pub fn poll_ensure_spare_capacity( self: Pin<&mut Self>, cx: &mut Context<'_>, count: usize, ) -> Poll<Result<()>>
Polls delivery of pending items when count spare items are needed.
§Parameters
cx: Task context used to register a wake-up.count: Minimum number of spare item slots to make available.
§Returns
Returns a ready success when the requested spare capacity is available,
or Poll::Pending while the wrapped output is not ready.
§Errors
Returns ErrorKind::InvalidInput when count exceeds the buffer
capacity, ErrorKind::WriteZero when draining makes no progress, or
an error reported by the wrapped output.
Source§impl<O> AsyncBufferedOutput<O>
impl<O> AsyncBufferedOutput<O>
Sourcepub async fn ensure_spare_capacity_async(&mut self, count: usize) -> Result<()>
pub async fn ensure_spare_capacity_async(&mut self, count: usize) -> Result<()>
Asynchronously ensures that the pending buffer has room for at least
count more items.
Pending items are written to the wrapped output when necessary; this does not flush the wrapped output itself.
§Parameters
count: Minimum number of spare item slots to make available.
§Returns
Returns Ok(()) when the requested spare capacity is available.
§Errors
Returns ErrorKind::InvalidInput when count exceeds the buffer
capacity, ErrorKind::WriteZero when the wrapped output makes no
progress, or an error from the wrapped output.
Trait Implementations§
Source§impl<O> AsyncClose for AsyncBufferedOutput<O>
impl<O> AsyncClose for AsyncBufferedOutput<O>
Source§fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>
fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>
Polls delivery of pending items followed by closing the inner output.
§Parameters
cx: Task context used to register a wake-up.
§Returns
Returns Poll::Pending while delivery or closing is incomplete,
otherwise a ready success result.
§Errors
Returns io::ErrorKind::WriteZero if draining makes no progress, or
an error reported by the wrapped output. Invalid asynchronous error
kinds from the close operation are normalized to
io::ErrorKind::InvalidData.
Source§fn close_async(&mut self) -> CloseFuture<'_, Self> ⓘ
fn close_async(&mut self) -> CloseFuture<'_, Self> ⓘ
Source§impl<O> AsyncOutput for AsyncBufferedOutput<O>
impl<O> AsyncOutput for AsyncBufferedOutput<O>
Source§type Item = <O as AsyncOutput>::Item
type Item = <O as AsyncOutput>::Item
Item type accepted by the wrapped output.
Source§fn is_buffered(&self) -> bool
fn is_buffered(&self) -> bool
Source§unsafe fn poll_write_unchecked(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
input: &[Self::Item],
index: usize,
count: usize,
) -> Poll<Result<usize>>
unsafe fn poll_write_unchecked( self: Pin<&mut Self>, cx: &mut Context<'_>, input: &[Self::Item], index: usize, count: usize, ) -> Poll<Result<usize>>
Polls one write through the retained item buffer.
A zero-length request completes immediately. The method first uses spare buffer capacity, then drains pending items when necessary.
§Parameters
cx: Task context used to register a wake-up.input: Source item slice.index: Starting source index.count: Maximum number of items to accept.
§Returns
Returns Poll::Pending when pending items cannot yet be delivered. A
ready success contains the number of newly accepted items.
§Errors
Returns io::ErrorKind::WriteZero if draining makes no progress.
Other errors are propagated from the wrapped output.
§Panics
May panic if a nonzero requested input range does not fit. Debug builds validate buffered-copy ranges before copying.
§Safety
The range index..index + count must be valid for input.
Source§fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>
fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>
Polls delivery of pending items followed by the inner flush operation.
§Parameters
cx: Task context used to register a wake-up.
§Returns
Returns Poll::Pending while delivery or flushing is incomplete,
otherwise a ready success result.
§Errors
Returns io::ErrorKind::WriteZero if draining makes no progress, or
an error reported by the wrapped output. Invalid asynchronous error
kinds from the flush operation are normalized to
io::ErrorKind::InvalidData.