Struct Writer

pub struct Writer<S> { /* private fields */ }

Available on crate feature asyncio only.

Adds items to the queue.

Values sent by the writer will be added to the end of the reader’s buffer, and capacity can be sent back to the writer from the start of the reader’s buffer to allow it to write more data.

A writer will automatically close itself when dropped.

Implementations

impl<S> Writer<S>

pub fn is_reader_open(&self) -> bool

Returns if the corresponding reader is still open.

If this is false, any attempt to write or flush the object will fail.

pub fn has_space(&self) -> bool

Returns if space is available in the writer’s buffer.

If this is true it is guaranteed that the next call to poll_empty_buf will return a non-empty slice, unless feed is called first.

Keep in mind that when using a reader and writer on separate threads, a writer that has no space can have more made available at any time - even between calls to has_space and other functions.

pub fn is_flushed(&self) -> bool

Returns if the buffer is flushed, i.e there are no items to read and any read operations will stall.

If this is true a writer can only resume the reader by calling feed to pass items to the reader.

Keep in mind that when using a reader and writer on separate threads, a writer that is not flushed can become flushed at any time - even between calls to is_flushed and other functions.

pub fn poll_empty_buf<T>( &mut self, cx: &mut Context<'_>, ) -> Poll<RegionMut<'_, T>>

where S: Storage<T>,

Attempt to get the writable buffer, waiting for more space if it is empty.

On success, returns Poll::Ready(Ok(buf)).

If no space is available for writing, the method returns Poll::Pending and arranges for the current task to receive a notification when the reader provides space or is closed.

This functions is a lower-level call. It needs to be paired with the feed method to function properly. When calling this method, none of the contents will be “written” in the sense that later calling poll_empty_buf may return the same contents. As such, feed must be called with the number of items that have been written to the buffer to ensure that the items are never returned twice.

An empty buffer returned indicates that the queue cannot be written to as the reader has closed.

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

Marks items at the start of the writer buffer as ready to be read, removing them from the slice returned by poll_empty_buf and making them available in the reader’s buffer.

Panics

This function will panic if amt is larger than the writer’s available space buffer.

pub async fn write<T>(&mut self, buf: &[T]) -> usize

where S: Storage<T>, T: Clone,

Writes some items from a buffer into this queue, returning how many items were written.

This function will attempt to write the entire contents of buf, but the entire write may not succeed if not enough space is available.

Return

It is guaranteed that the return value is <= buf.len().

A return value of 0 indicates one of these two scenarios:

1. The reader has closed.
2. The buffer specified had a length of 0.

Cancel safety

This method is cancel safe. If you use it in a select! statement and some other branch completes first, then it is guaranteed that no data was written.

pub async fn write_all<T>(&mut self, buf: &[T]) -> Result<usize, WriteError>

where S: Storage<T>, T: Clone,

Attempts to write all items in a buffer into this queue.

If the reader closes before all items are written, an error of the kind WriteError::ReaderClosed will be returned.

Return

If the return value is Ok(n), it is guaranteed that n == buf.len().

Cancel safety

This method is not cancellation safe. If it is used in a select! statement and some other branch completes first, then the provided buffer may have been partially written, but future calls to write_all will start over from the beginning of the buffer.

pub fn poll_flush( &mut self, cx: &mut Context<'_>, ) -> Poll<Result<(), WriteError>>

Attempt to flush the buffer, ensuring that any items waiting to be read are consumed by the reader.

On success, returns Poll::Ready(Ok(())). If the reader is closed, returns Poll::Ready(Err(FlushError::ReaderClosed)).

If flushing cannot immediately complete, this method returns Poll::Pending and arranges for the current task to receive a notification when the object can make progress towards flushing.

pub async fn flush(&mut self) -> Result<(), WriteError>

Flushes the buffer, ensuring that any items waiting to be read are consumed by the reader.

If the reader closes before the buffer is flushed, an error of the kind WriteError::ReaderClosed will be returned.

pub fn poll_close( &mut self, cx: &mut Context<'_>, ) -> Poll<Result<(), WriteError>>

Attempt to close the writer, flushing any remaining data and indicating to the reader that no more data will be written.

On success, returns Poll::Ready(Ok(())). Any future read operations will fail. Closing the writer multiple times has no effect.

pub async fn close(&mut self) -> Result<(), WriteError>

Closes the buffer, flushing any remaining data and indicating to the reader that no more data will be written.

If the reader closes before the buffer is flushed, an error of the kind WriteError::ReaderClosed will be returned.

Trait Implementations

impl<S> AsyncWrite for Writer<S>

where S: Storage<u8>,

Available on crate feature std-io only.

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Attempt to write bytes from bufs into the object using vectored IO operations.

impl<S: Debug> Debug for Writer<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S> Drop for Writer<S>

fn drop(&mut self)

Closes the writer without flushing.