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>
impl<'a, 'b, N: DriverNotify, M: DriverMem> WritableChain<'a, 'b, N, M>
sourcepub fn new(
chain: DescChain<'a, 'b, N>,
mem: &'a M,
) -> Result<Self, ChainCompleteError>
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.
sourcepub fn new_ignore_readable(
chain: DescChain<'a, 'b, N>,
mem: &'a M,
) -> Result<Self, ChainError>
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.
sourcepub fn from_readable(
readable: ReadableChain<'a, 'b, N, M>,
) -> Result<Self, ChainCompleteError>
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.
sourcepub fn from_incomplete_readable(
readable: ReadableChain<'a, 'b, N, M>,
) -> Result<Self, ChainError>
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.
sourcepub fn return_complete(self) -> Result<(), ChainCompleteError>
pub fn return_complete(self) -> Result<(), ChainCompleteError>
Immediately return a fully consumed chain.
Similar to ReadableChain::return_complete
.
sourcepub fn next_with_limit(
&mut self,
limit: usize,
) -> Option<Result<DeviceRange<'a>, ChainError>>
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
sourcepub fn next(&mut self) -> Option<Result<DeviceRange<'a>, ChainError>>
pub fn next(&mut self) -> Option<Result<DeviceRange<'a>, ChainError>>
Request the next range of readable bytes.
Similar to ReadableChain::next
sourcepub fn remaining(&self) -> Result<Remaining, ChainError>
pub fn remaining(&self) -> Result<Remaining, ChainError>
Query writable bytes and descriptors remaining.
Similar to ReadableChain::remaining
sourcepub fn add_written(&mut self, written: u32)
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>
impl<'a, 'b, N: DriverNotify, M: DriverMem> Drop for WritableChain<'a, 'b, N, M>
source§impl<'a, 'b, N: DriverNotify, M: DriverMem> Write for WritableChain<'a, 'b, N, M>
impl<'a, 'b, N: DriverNotify, M: DriverMem> Write for WritableChain<'a, 'b, N, M>
source§fn write(&mut self, buf: &[u8]) -> Result<usize>
fn write(&mut self, buf: &[u8]) -> Result<usize>
source§fn flush(&mut self) -> Result<()>
fn flush(&mut self) -> Result<()>
source§fn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)1.0.0 · source§fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
source§fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)