Struct Reader

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

Available on crate feature blocking 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.

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 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 block.

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 fill_buf<T>(&mut self) -> Region<'_, T>

where S: Storage<T>,

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

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 fill_buf may return the same contents. As such, consume must be called with the number of bytes 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 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 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 read, otherwise it will block until some are 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 writer has closed and all items have been read.
2. The buffer specified had a length of 0.

pub 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().

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> BufRead for Reader<S>

where S: Storage<u8>,

fn fill_buf(&mut self) -> Result<&[u8]>

Returns the contents of the internal buffer, filling it with more data, via Read methods, if empty.

fn consume(&mut self, amt: usize)

Marks the given amount of additional bytes from the internal buffer as having been read. Subsequent calls to read only return bytes that have not been marked as read.

fn has_data_left(&mut self) -> Result<bool, Error>

🔬This is a nightly-only experimental API. (buf_read_has_data_left)

Checks if there is any data left to be read.

fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes into buf until the delimiter byte or EOF is reached.

fn skip_until(&mut self, byte: u8) -> Result<usize, Error>

Skips all bytes until the delimiter byte or EOF is reached.

fn read_line(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until a newline (the 0xA byte) is reached, and append them to the provided String buffer.

fn split(self, byte: u8) -> Split<Self>

where Self: Sized,

Returns an iterator over the contents of this reader split on the byte byte.

fn lines(self) -> Lines<Self>

where Self: Sized,

Returns an iterator over the lines of this reader.

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)

Executes the destructor for this type.

impl<S> Read for Reader<S>

where S: Storage<u8>,

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.