Struct iou::IoUring

pub struct IoUring { /* fields omitted */ }

The main interface to kernel IO using io_uring.

IoUring is a high-level wrapper around an io_uring object.

IoUrings are constructed with a requested number of ring buffer entries and possibly a set of SetupFlags. Allocations for IoUring are memlocked and will not be paged out.

// make a IoUring with 16 entries
let mut ring = IoUring::new(16)?;

// make a IoUring set to poll the IO context
let mut ring = IoUring::new_with_flags(32, SetupFlags::IOPOLL, SetupFeatures::empty())?;

IoUrings can either be used directly, or split into separate parts and operated on without synchronization.

// split an IoUring piecewise
let sq: SubmissionQueue = ring.sq();
let cq: CompletionQueue = ring.cq();
let reg: Registrar = ring.registrar();

// split an IoUring into its three parts all at once
let (sq, cq, reg) = ring.queues();

Implementations

impl IoUring

pub fn new(entries: u32) -> Result<IoUring>

Creates a new IoUring without any setup flags. IoUring's created using this method will use interrupt-driven IO.

The number of entries must be in the range of 1..4096 (inclusive) and it's recommended to be a power of two.

The underlying SubmissionQueue and CompletionQueue will each have this number of entries.

pub fn new_with_flags(
    entries: u32,
    flags: SetupFlags,
    features: SetupFeatures
) -> Result<IoUring>

Creates a new IoUring using a set of SetupFlags and SetupFeatures for advanced use cases.

pub fn sq(&mut self) -> SubmissionQueue<'_>

Returns the SubmissionQueue part of the IoUring.

pub fn cq(&mut self) -> CompletionQueue<'_>

Returns the CompletionQueue part of the IoUring.

pub fn registrar(&self) -> Registrar<'_>

Returns the Registrar part of the IoUring.

pub fn queues(
    &mut self
) -> (SubmissionQueue<'_>, CompletionQueue<'_>, Registrar<'_>)

Returns the three constituent parts of the IoUring.

pub fn probe(&mut self) -> Result<Probe>

pub fn prepare_sqe(&mut self) -> Option<SQE<'_>>

Returns the next SQE which can be prepared to submit.

pub fn prepare_sqes(&mut self, count: u32) -> Option<SQEs<'_>>

Returns the next count SQEs which can be prepared to submit as an iterator.

See the SQEs type for more information about how these multiple SQEs can be used.

pub fn submit_sqes(&mut self) -> Result<u32>

Submit all prepared SQEs to the kernel.

pub fn submit_sqes_and_wait(&mut self, wait_for: u32) -> Result<u32>

Submit all prepared SQEs to the kernel and wait until at least wait_for events have completed.

pub fn submit_sqes_and_wait_with_timeout(
    &mut self,
    wait_for: u32,
    duration: Duration
) -> Result<u32>

Submit all prepared SQEs to the kernel and wait until at least wait_for events have completed or duration has passed.

pub fn peek_for_cqe(&mut self) -> Option<CQE>

Peek for any CQE that is already completed, without blocking. This will consume that CQE.

pub fn wait_for_cqe(&mut self) -> Result<CQE>

Block until at least one CQE is completed. This will consume that CQE.

pub fn wait_for_cqe_with_timeout(&mut self, duration: Duration) -> Result<CQE>

Block until a CQE is ready or timeout.

pub fn cqes(&mut self) -> CQEs<'_>

Returns an iterator of CQEs which are ready from the kernel.

pub fn cqes_blocking(&mut self, count: u32) -> CQEsBlocking<'_>

Returns an iterator of CQEs which will block when there are no CQEs ready. It will block until at least count are ready, and then continue iterating.

This iterator will never be exhausted; every time it runs out of CQEs it will block the thread and wait for more to be ready.

pub fn wait_for_cqes(&mut self, count: u32) -> Result<()>

Wait until count CQEs are ready, without submitting any events.

pub fn raw(&self) -> &io_uring

pub unsafe fn raw_mut(&mut self) -> &mut io_uring

pub fn cq_ready(&mut self) -> u32

pub fn sq_ready(&mut self) -> u32

pub fn sq_space_left(&mut self) -> u32

pub fn cq_eventfd_enabled(&mut self) -> bool

pub fn cq_eventfd_toggle(&mut self, enabled: bool) -> Result<()>

pub fn raw_fd(&self) -> RawFd

Trait Implementations

impl Debug for IoUring

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

Formats the value using the given formatter.

impl Drop for IoUring

fn drop(&mut self)

Executes the destructor for this type.

impl Send for IoUring

impl Sync for IoUring