Struct virtio_device::chain::WritableChain

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

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§

source§

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

source

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.

source

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.

source

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.

source

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.

source

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

Immediately return a fully consumed chain.

Similar to ReadableChain::return_complete.

source

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

source

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

Request the next range of readable bytes.

Similar to ReadableChain::next

source

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

Query writable bytes and descriptors remaining.

Similar to ReadableChain::remaining

source

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§

source§

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

source§

fn drop(&mut self)

Executes the destructor for this type. Read more
source§

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

source§

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

Write a buffer into this writer, returning how many bytes were written. Read more
source§

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

Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
1.36.0 · source§

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

Like write, except that it writes from a slice of buffers. Read more
source§

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. Read more
1.0.0 · source§

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

Attempts to write an entire buffer into this writer. Read more
source§

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. Read more
1.0.0 · source§

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

Writes a formatted string into this writer, returning any error encountered. Read more
1.0.0 · source§

fn by_ref(&mut self) -> &mut Self
where Self: Sized,

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

Auto Trait Implementations§

§

impl<'a, 'b, N, M> Freeze for WritableChain<'a, 'b, N, M>

§

impl<'a, 'b, N, M> !RefUnwindSafe for WritableChain<'a, 'b, N, M>

§

impl<'a, 'b, N, M> !Send for WritableChain<'a, 'b, N, M>

§

impl<'a, 'b, N, M> !Sync for WritableChain<'a, 'b, N, M>

§

impl<'a, 'b, N, M> Unpin for WritableChain<'a, 'b, N, M>

§

impl<'a, 'b, N, M> !UnwindSafe for WritableChain<'a, 'b, N, M>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.