Trait QueueT

pub trait QueueT: for<'a> QueueGuard<'a> {
    // Required methods
    fn new(max_size: u16) -> Result<Self, Error>
       where Self: Sized;
    fn is_valid<M: GuestMemory>(&self, mem: &M) -> bool;
    fn reset(&mut self);
    fn lock(&mut self) -> <Self as QueueGuard<'_>>::G;
    fn max_size(&self) -> u16;
    fn size(&self) -> u16;
    fn set_size(&mut self, size: u16);
    fn ready(&self) -> bool;
    fn set_ready(&mut self, ready: bool);
    fn set_desc_table_address(&mut self, low: Option<u32>, high: Option<u32>);
    fn set_avail_ring_address(&mut self, low: Option<u32>, high: Option<u32>);
    fn set_used_ring_address(&mut self, low: Option<u32>, high: Option<u32>);
    fn set_event_idx(&mut self, enabled: bool);
    fn avail_idx<M>(
        &self,
        mem: &M,
        order: Ordering,
    ) -> Result<Wrapping<u16>, Error>
       where M: GuestMemory + ?Sized;
    fn used_idx<M: GuestMemory>(
        &self,
        mem: &M,
        order: Ordering,
    ) -> Result<Wrapping<u16>, Error>;
    fn add_used<M: GuestMemory>(
        &mut self,
        mem: &M,
        head_index: u16,
        len: u32,
    ) -> Result<(), Error>;
    fn enable_notification<M: GuestMemory>(
        &mut self,
        mem: &M,
    ) -> Result<bool, Error>;
    fn disable_notification<M: GuestMemory>(
        &mut self,
        mem: &M,
    ) -> Result<(), Error>;
    fn needs_notification<M: GuestMemory>(
        &mut self,
        mem: &M,
    ) -> Result<bool, Error>;
    fn next_avail(&self) -> u16;
    fn set_next_avail(&mut self, next_avail: u16);
    fn next_used(&self) -> u16;
    fn set_next_used(&mut self, next_used: u16);
    fn desc_table(&self) -> u64;
    fn avail_ring(&self) -> u64;
    fn used_ring(&self) -> u64;
    fn event_idx_enabled(&self) -> bool;
    fn pop_descriptor_chain<M>(&mut self, mem: M) -> Option<DescriptorChain<M>>
       where M: Clone + Deref,
             M::Target: GuestMemory;
}

Trait to access and manipulate a virtio queue.

To optimize for performance, different implementations of the QueueT trait may be provided for single-threaded context and multi-threaded context.

Using Higher-Rank Trait Bounds (HRTBs) to effectively define an associated type that has a lifetime parameter, without tagging the QueueT trait with a lifetime as well.

Required Methods

fn new(max_size: u16) -> Result<Self, Error>

where Self: Sized,

Construct an empty virtio queue state object with the given max_size.

Returns an error if max_size is invalid.

fn is_valid<M: GuestMemory>(&self, mem: &M) -> bool

Check whether the queue configuration is valid.

fn reset(&mut self)

Reset the queue to the initial state.

fn lock(&mut self) -> <Self as QueueGuard<'_>>::G

Get an exclusive reference to the underlying Queue object.

Logically this method will acquire the underlying lock protecting the Queue Object. The lock will be released when the returned object gets dropped.

fn max_size(&self) -> u16

Get the maximum size of the virtio queue.

fn size(&self) -> u16

Get the actual size configured by the guest.

fn set_size(&mut self, size: u16)

Configure the queue size for the virtio queue.

fn ready(&self) -> bool

Check whether the queue is ready to be processed.

fn set_ready(&mut self, ready: bool)

Configure the queue to ready for processing state.

fn set_desc_table_address(&mut self, low: Option<u32>, high: Option<u32>)

Set the descriptor table address for the queue.

The descriptor table address is 64-bit, the corresponding part will be updated if ‘low’ and/or high is Some and valid.

fn set_avail_ring_address(&mut self, low: Option<u32>, high: Option<u32>)

Set the available ring address for the queue.

The available ring address is 64-bit, the corresponding part will be updated if ‘low’ and/or high is Some and valid.

fn set_used_ring_address(&mut self, low: Option<u32>, high: Option<u32>)

Set the used ring address for the queue.

The used ring address is 64-bit, the corresponding part will be updated if ‘low’ and/or high is Some and valid.

fn set_event_idx(&mut self, enabled: bool)

Enable/disable the VIRTIO_F_RING_EVENT_IDX feature for interrupt coalescing.

fn avail_idx<M>(&self, mem: &M, order: Ordering) -> Result<Wrapping<u16>, Error>

where M: GuestMemory + ?Sized,

Read the idx field from the available ring.

Panics

Panics if order is Release or AcqRel.

fn used_idx<M: GuestMemory>( &self, mem: &M, order: Ordering, ) -> Result<Wrapping<u16>, Error>

Read the idx field from the used ring.

Panics

Panics if order is Release or AcqRel.

fn add_used<M: GuestMemory>( &mut self, mem: &M, head_index: u16, len: u32, ) -> Result<(), Error>

Put a used descriptor head into the used ring.

fn enable_notification<M: GuestMemory>( &mut self, mem: &M, ) -> Result<bool, Error>

Enable notification events from the guest driver.

Return true if one or more descriptors can be consumed from the available ring after notifications were enabled (and thus it’s possible there will be no corresponding notification).

fn disable_notification<M: GuestMemory>(&mut self, mem: &M) -> Result<(), Error>

Disable notification events from the guest driver.

fn needs_notification<M: GuestMemory>(&mut self, mem: &M) -> Result<bool, Error>

Check whether a notification to the guest is needed.

Please note this method has side effects: once it returns true, it considers the driver will actually be notified, remember the associated index in the used ring, and won’t return true again until the driver updates used_event and/or the notification conditions hold once more.

fn next_avail(&self) -> u16

Return the index of the next entry in the available ring.

fn set_next_avail(&mut self, next_avail: u16)

Set the index of the next entry in the available ring.

fn next_used(&self) -> u16

Return the index for the next descriptor in the used ring.

fn set_next_used(&mut self, next_used: u16)

Set the index for the next descriptor in the used ring.

fn desc_table(&self) -> u64

Return the address of the descriptor table.

fn avail_ring(&self) -> u64

Return the address of the available ring.

fn used_ring(&self) -> u64

Return the address of the used ring.

fn event_idx_enabled(&self) -> bool

Checks whether VIRTIO_F_RING_EVENT_IDX is negotiated.

This getter is only returning the correct value after the device passes the FEATURES_OK status.

fn pop_descriptor_chain<M>(&mut self, mem: M) -> Option<DescriptorChain<M>>

where M: Clone + Deref, M::Target: GuestMemory,

Pop and return the next available descriptor chain, or None when there are no more descriptor chains available.

This enables the consumption of available descriptor chains in a “one at a time” manner, without having to hold a borrow after the method returns.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl QueueT for Queue

impl QueueT for QueueSync