Struct devices::virtio::descriptor_utils::Writer

pub struct Writer {
    mem: GuestMemory,
    regions: DescriptorChainRegions,
}

Provides high-level interface over the sequence of memory regions defined by writable descriptors in the descriptor chain.

Note that virtio spec requires driver to place any device-writable descriptors after any device-readable descriptors (2.6.4.2 in Virtio Spec v1.1). Writer will start iterating the descriptors from the first writable one and will assume that all following descriptors are writable.

Fields

mem: GuestMemory

regions: DescriptorChainRegions

Implementations

impl Writer

pub fn new_from_regions( mem: &GuestMemory, writable_regions: SmallVec<[MemRegion; 2]> ) -> Writer

Construct a new Writer wrapper over writable_regions.

pub fn write_obj<T: AsBytes>(&mut self, val: T) -> Result<()>

Writes an object to the descriptor chain buffer.

pub fn write_iter<T: AsBytes, I: Iterator<Item = T>>( &mut self, iter: I ) -> Result<()>

Writes all objects produced by iter into the descriptor chain buffer. Unlike consume, this doesn’t require the values to be stored in an intermediate collection first. It also allows callers to choose which elements in a collection to write, for example by using the filter or take methods of the Iterator trait.

pub fn consume<T: AsBytes, C: IntoIterator<Item = T>>( &mut self, vals: C ) -> Result<()>

Writes a collection of objects into the descriptor chain buffer.

pub fn available_bytes(&self) -> usize

Returns number of bytes available for writing. May return an error if the combined lengths of all the buffers in the DescriptorChain would cause an overflow.

pub fn write_from_volatile_slice(&mut self, slice: VolatileSlice<'_>) -> usize

Reads data into a volatile slice up to the minimum of the slice’s length or the number of bytes remaining. Returns the number of bytes read.

pub fn write_from<F: FileReadWriteVolatile>( &mut self, src: F, count: usize ) -> Result<usize>

Writes data to the descriptor chain buffer from a readable object. Returns the number of bytes written to the descriptor chain buffer. The number of bytes written can be less than count if there isn’t enough data in the descriptor chain buffer.

pub fn write_from_at<F: FileReadWriteAtVolatile>( &mut self, src: &F, count: usize, off: u64 ) -> Result<usize>

Writes data to the descriptor chain buffer from a File at offset off. Returns the number of bytes written to the descriptor chain buffer. The number of bytes written can be less than count if there isn’t enough data in the descriptor chain buffer.

pub fn write_all_from<F: FileReadWriteVolatile>( &mut self, src: F, count: usize ) -> Result<()>

pub fn write_all_from_at<F: FileReadWriteAtVolatile>( &mut self, src: &F, count: usize, off: u64 ) -> Result<()>

pub async fn write_from_at_fut<F: AsyncDisk + ?Sized>( &mut self, src: &F, count: usize, off: u64 ) -> Result<usize>

Writes data to the descriptor chain buffer from an AsyncDisk at offset off. Returns the number of bytes written to the descriptor chain buffer. The number of bytes written can be less than count if there isn’t enough data in the descriptor chain buffer.

pub async fn write_all_from_at_fut<F: AsyncDisk + ?Sized>( &mut self, src: &F, count: usize, off: u64 ) -> Result<()>

pub fn bytes_written(&self) -> usize

Returns number of bytes already written to the descriptor chain buffer.

pub fn get_remaining_regions(&self) -> MemRegionIter<'_>

pub fn get_remaining(&self) -> SmallVec<[VolatileSlice<'_>; 16]>

Returns a &[VolatileSlice] that represents all the remaining data in this Writer. Calling this method does not actually advance the current position of the Writer in the buffer and callers should call consume_bytes to advance the Writer. Not calling consume_bytes with the amount of data copied into the returned VolatileSlices will result in that that data being overwritten the next time data is written into the Writer.

pub fn consume_bytes(&mut self, amt: usize)

Consumes amt bytes from the underlying descriptor chain. If amt is larger than the remaining data left in this Reader, then all remaining data will be consumed.

pub fn split_at(&mut self, offset: usize) -> Writer

Splits this Writer into two at the given offset in the DescriptorChain buffer. After the split, self will be able to write up to offset bytes while the returned Writer can write up to available_bytes() - offset bytes. If offset > self.available_bytes(), then the returned Writer will not be able to write any bytes.

Trait Implementations

impl Write for Writer

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.

impl Writer for Writer

type ClosureWriter = Writer

The type passed in to the closure in write_at. For most implementations, this should be Self.

fn write_at<F>(&mut self, offset: usize, f: F) -> Result<usize>

where F: Fn(&mut Self) -> Result<usize>,

Allows a closure to generate and write data at the current writer’s offset. The current writer is passed as a mutable reference to the closure. As an example, this provides an adapter for the read implementation of a filesystem to write directly to the final buffer without generating the FUSE header first.

fn has_sufficient_buffer(&self, size: u32) -> bool

Checks if the writer can still accept certain amount of data.

impl ZeroCopyWriter for Writer

fn write_from(&mut self, f: &mut File, count: usize, off: u64) -> Result<usize>

Copies at most count bytes from f at offset off directly into self without storing it in any intermediate buffers. If the return value is Ok(n) then it must be guaranteed that 0 <= n <= count. If n is 0, then it can indicate one of 3 possibilities:

fn write_all_from( &mut self, f: &mut File, count: usize, off: u64 ) -> Result<(), Error>

Copies exactly count bytes of data from f at offset off into self. off + count must be less than u64::MAX.

fn copy_to_end(&mut self, f: &mut File, off: u64) -> Result<usize, Error>

Copies all remaining bytes from f at offset off into self. Equivalent to repeatedly calling write_from until it returns either Ok(0) or a non-ErrorKind::Interrupted error.