[][src]Crate iou

Idiomatic Rust bindings to liburing.

This gives users an idiomatic Rust interface for interacting with the Linux kernel's io_uring interface for async IO. Despite being idiomatic Rust, this interface is still very low level and some fundamental operations remain unsafe.

The core entry point to the API is the IoUring type, which manages an io_uring object for interfacing with the kernel. Using this, users can submit IO events and wait for their completion.

It is also possible to "split" an IoUring instance into its constituent components - a SubmissionQueue, a CompletionQueue, and a Registrar - in order to operate on them separately without synchronization.

Submitting events

You can prepare new IO events using the SQE type. Once an event has been prepared, the next call to submit will submit that event. Eventually, those events will complete, and that a CQE will appear on the completion queue indicating that the event is complete.

Preparing IO events is inherently unsafe, as you must guarantee that the buffers and file descriptors used for that IO are alive long enough for the kernel to perform the IO operation with them.

Timeouts

Some APIs allow you to time out a call into the kernel. It's important to note how this works with io_uring.

A timeout is submitted as an additional IO event which completes after the specified time. Therefore when you create a timeout, all that happens is that a completion event will appear after that specified time. This also means that when processing completion events, you need to be prepared for the possibility that the completion represents a timeout and not a normal IO event (CQE has a method to check for this).

Modules

cqe

Types related to completion queue events.

registrar

Types related to registration and registered resources.

sqe

Types related to submission queue events.

Structs

CQE

A completed IO event.

CQEs

An iterator of CQEs from the CompletionQueue.

CQEsBlocking

An iterator of CQEs from the CompletionQueue.

CompletionQueue

The queue of completed IO events.

IoUring

The main interface to kernel IO using io_uring.

Personality
Probe

A probe of the operations supported by this kernel version's io-uring interface.

Registrar

A Registrar creates ahead-of-time kernel references to files and user buffers.

SQE

A pending IO event.

SQEs

A sequence of SQEs from the SubmissionQueue.

SetupFeatures

Advanced features that can be enabled when setting up an IoUring instance.

SetupFlags

IoUring initialization flags for advanced use cases.

SubmissionQueue

The queue of pending IO events.