Struct Reader

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

Available on crate feature asyncio only.

Receives items from 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 reader will automatically close itself when dropped.

Implementations

impl<S> Reader<S>

pub fn is_writer_open(&self) -> bool

Returns if the corresponding writer is still open.

If this is false, unread data will still be available to read but a well-behaved writer will not provide any new data.

pub fn has_data(&self) -> bool

Returns if data is available in the reader’s buffer.

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

Keep in mind that when using a reader and writer on separate threads, a reader that has no data can receive data at any time - even between calls to has_data and other functions.

pub fn is_full(&self) -> bool

Returns if the buffer is full, i.e all space is allocated to the reader and any write operations will stall.

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

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

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

where S: Storage<T>,

Attempt to read from the reader’s buffer, waiting for more data if it is empty.

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

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

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

An empty buffer returned indicates that all data has been read and the writer has closed.

pub fn consume(&mut self, amt: usize)

Marks items at the start of the reader buffer as consumed, removing them from the slice returned by poll_fill_buf and adding their capacity to the end of the writer’s buffer. Since queues have a fixed underlying length, calling this is required to allow the transfer of more data.

Panics

This function will panic if amt is larger than the reader’s available data buffer.

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

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

Pulls some items from this queue into the specified buffer, returning how many items were read.

This method will complete immediately if at least one item is available to be read.

Return

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

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

1. The writer has closed and all items have been read.
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 read.

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

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

Reads the exact number of items required to fill buf.

If the writer closes before the buffer is completely filled, an error of the kind ReadExactError::WriterClosed 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 the method is used in a select! statement and some other branch completes first, then some data may already have been read into buf.

pub fn close(&mut self)

Close the reader, indicating to the writer that no more data will be read.

Any in-progress writes or flushes on the writer will be interrupted, and any future operations will fail. Closing the reader multiple times has no effect.

Dropping the reader object will also close it.

Trait Implementations

impl<S> AsyncBufRead for Reader<S>

where S: Storage<u8>,

Available on crate feature std-io only.

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

Attempt to return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(self: Pin<&mut Self>, amt: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to poll_read.

impl<S> AsyncRead for Reader<S>

where S: Storage<u8>,

Available on crate feature std-io only.

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

Attempt to read from the AsyncRead into buf.

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

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl<S: Debug> Debug for Reader<S>

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

Formats the value using the given formatter.

impl<S> Drop for Reader<S>

fn drop(&mut self)

Closes the reader.