Struct VirtioQueue 

pub struct VirtioQueue { /* private fields */ }

Implementations

impl VirtioQueue

pub fn new( features: VirtioDeviceFeatures, params: QueueParams, mem: GuestMemory, notify: Interrupt, queue_event: PolledWait<Event>, initial_state: Option<QueueState>, ) -> Result<Self, QueueError>

pub fn queue_state(&self) -> QueueState

Returns the current queue progress state.

pub fn poll_kick(&mut self, cx: &mut Context<'_>) -> Poll<()>

Polls until the queue is kicked by the guest, indicating new work may be available.

Before sleeping, this arms kick notification and rechecks the queue. If new data arrived during arming, it returns immediately without sleeping. On wakeup, kicks are suppressed to avoid unnecessary doorbells while the caller drains the queue.

Returns Poll::Pending forever once the queue has failed, since no further work can ever be fetched. This keeps callers that loop on “kick, then retry” from spinning.

pub fn try_next(&mut self) -> Result<Option<VirtioQueueCallbackWork>, Error>

Try to get the next work item from the queue. Returns Ok(None) if no work is currently available, or an error if there was an issue accessing the queue.

This is a lightweight check that does not arm kick notification. When used in a poll loop with poll_kick, the kick will be armed automatically before sleeping.

pub fn try_peek(&mut self) -> Result<Option<PeekedWork<'_>>, Error>

Peek at the next available descriptor without advancing the available index. Returns a PeekedWork that holds the descriptor payload and a mutable reference to this queue.

The descriptor stays in the available ring. Call PeekedWork::consume to advance the index and get a normal VirtioQueueCallbackWork for completion.

Dropping the PeekedWork without consuming is a no-op — the descriptor remains available.

Calling try_peek again without consuming returns the same descriptor (the descriptor metadata is captured at peek time), but note that the guest may have modified the underlying buffer contents in the meantime.

pub async fn peek(&mut self) -> Result<PeekedWork<'_>, Error>

Waits until a descriptor is available for peeking, without advancing the available index. See try_peek.

Note that descriptor metadata is captured at peek time, but the guest may modify the underlying buffer contents between a peek and a subsequent consume or re-peek, so callers must not assume the buffer data is stable.

pub fn complete(&mut self, work: VirtioQueueCallbackWork, bytes_written: u32)

Complete a descriptor previously obtained from this queue.

Writes bytes_written to the used ring and delivers an interrupt to the guest (unless interrupt suppression is active).

Takes ownership of the work item, ensuring it can only be completed once.

pub fn complete_prepared( &mut self, completion: QueueCompletion, bytes_written: u32, )

Completes a descriptor from a lightweight QueueCompletion token previously obtained via VirtioQueueCallbackWork::into_completion.

Equivalent to complete but does not require holding the payload, so callers that buffer completions can store only the token.

Trait Implementations

impl Debug for VirtioQueue

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Inspect for VirtioQueue

fn inspect(&self, req: Request<'_>)

Inspects the object.

impl Stream for VirtioQueue

Yields each descriptor chain the guest makes available.

After yielding a QueueError the queue is retired, and the stream parks forever rather than ending: returning None would be ready synchronously on every poll, so a caller looping over the stream would spin on it. Parking makes it impossible for any caller to busy-loop, and the worker stays cancellable.

type Item = Result<VirtioQueueCallbackWork, Error>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.