Struct ReadableChain

pub struct ReadableChain<'a, 'b, N: DriverNotify, M: DriverMem> { /* private fields */ }

Access the readable portion of a descriptor chain.

Provides access to the read-only portion of a descriptor chain. Can be [constructed directly] (ReadableChain::new) from a DescChain and once finished with can either be dropped or converted to a WritableChain if there are writable portions as well.

As the ReadableChain takes ownership of the DescChain dropping the ReadableChain will automatically return the DescChain to the Queue.

For devices and protocols where it is useful, the chain can also be explicitly returned via the return_complete method to validate full consumption of the chain.

Implementations

impl<'a, 'b, N: DriverNotify, M: DriverMem> ReadableChain<'a, 'b, N, M>

pub fn new(chain: DescChain<'a, 'b, N>, mem: &'a M) -> Self

Construct a ReadableChain from a DescChain.

Requires a reference to a DriverMem in order to perform translation into DeviceRange.

pub fn return_complete(self) -> Result<(), ChainCompleteError>

Immediately return a fully consumed chain.

This both drops the chain, thus returning the underlying DescChain to the [Queue] (crate::queue::Queue), and also checks if it was fully walked, generating an error if not. Fully walked here means that there are no readable or writable sections that had not been iterated over.

For virtio queues where the device is expected to fully consume what it is sent, and there is not expected to be anything to write, this provides a way to both check for correct device and driver functionality.

pub fn next_with_limit( &mut self, limit: usize, ) -> Option<Result<DeviceRange<'a>, ChainError>>

Request the next range of readable bytes, up to a limit.

As the DeviceRange returned here represents a contiguous range this may return a smaller range than requested by limit, even if there is more readable descriptor(s) remaining. In this way the caller is directly exposed to size of the underlying descriptors in the chain as queued by the driver.

A return value of None indicates there are no more readable descriptors, however there may still be readable descriptors.

Should this ever return a Some(Err(_)) it will always yield a None in future calls as the chain will be deemed corrupt. If walking and attempting to recover from corrupt chains is desirable, beyond just reporting an error, then you must use the DescChain directly and not this interface.

pub fn next(&mut self) -> Option<Result<DeviceRange<'a>, ChainError>>

Request the next range of readable bytes.

Similar to next_with_limit except limit is implicitly usize::MAX. This will therefore walk the descriptors in the structure as they were provided by the driver.

pub fn remaining(&self) -> Result<Remaining, ChainError>

Query readable bytes and descriptors remaining.

Returns the number of readable bytes and descriptors remaining in the chain. This does not imply that calling next_with_limit with the result will return that much, see next_with_limit for more details.

Trait Implementations

impl<'a, 'b, N: DriverNotify, M: DriverMem> Read for ReadableChain<'a, 'b, N, M>

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.