Struct virtio_device::chain::WritableChain

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

Access the writable portion of a descriptor chain.

Provides access to the write-only portion of a descriptor chain. If no readable portion a WritableChain can be constructed directly from a DescChain, either [generating errors] (WritiableChain::new) if there are readable portions, or [ignoring them] (WritableChain::new_ignore_readable). Otherwise [Readable] chain can be [converted] (WritableChain::from_readable) into a WritableChain, with a similar option to ignore any remaining readable.

As the [Writable] takes ownership of the DescChain dropping the WritableChain will automatically return the DescChain to the Queue. To report how much was written the WritableChain has an internal counter of how much you have claimed to have written via add_written. Walking the chain via next or next_with_limit does not automatically increment the written counter as the WritableChain cannot assume how much of the returned range was written to.

Writing to the chain via the std::io::Write trait will automatically increment the written counter.

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

Implementations

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

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

Construct a WritableChain from a DescChain.

Requires a reference to a DriverMem in order to perform translation into DeviceRange. Generates an error if there are any readable portions.

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

Construct a WritableChain from a DescChain, ignoring some errors.

Same as new but ignores any readable descriptors. It may still generate an error as a corrupt chain may be noticed when it is walked to skip any readable descriptors.

pub fn from_readable( readable: ReadableChain<'a, 'b, N, M> ) -> Result<Self, ChainCompleteError>

Convert a ReadableChain to a WritableChain

Generates an error if there are still readable portions of the chain left.

pub fn from_incomplete_readable( readable: ReadableChain<'a, 'b, N, M> ) -> Result<Self, ChainError>

Convert a ReadableChain to a WritableChain

Skips any remaining readable descriptors to construct a WritableChain. May still generate an error if there was a problem walking the chain.

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

Immediately return a fully consumed chain.

Similar to ReadableChain::return_complete.

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.

Similar to ReadableChain::next_with_limit

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

Request the next range of readable bytes.

Similar to ReadableChain::next

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

Query writable bytes and descriptors remaining.

Similar to ReadableChain::remaining

pub fn add_written(&mut self, written: u32)

Increments the written bytes counter.

If descriptor ranges returned from next and next_with_limit are actually written to then the amount that is written needs to be added by calling this method, as the WritableChain itself does not know if, or how much, might have been returned to the returned ranges.

Note if using the std::io::Write trait implementation to write to the chain this method does not need to be called, as the trait implementation will call it for you. You only need to call this if actually directly calling next or [next_with_limit] (#next_with_limit).

add_written is cumulative and can be called multiple times. No checking of this value is performed and it is up to the caller to choose to honor the virtio specification.

Trait Implementations

impl<'a, 'b, N: DriverNotify, M: DriverMem> Drop for WritableChain<'a, 'b, N, M>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, 'b, N: DriverNotify, M: DriverMem> Write for WritableChain<'a, 'b, N, M>

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

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

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

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

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

Determines if this Writer has an efficient write_vectored implementation.

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

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

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

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

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

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.