[−][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 |
CQEsBlocking | An iterator of |
CompletionQueue | The queue of completed IO events. |
IoUring | The main interface to kernel IO using |
Personality | |
Probe | A probe of the operations supported by this kernel version's io-uring interface. |
Registrar | A |
SQE | A pending IO event. |
SQEs | A sequence of |
SetupFeatures | Advanced features that can be enabled when setting up an |
SetupFlags |
|
SubmissionQueue | The queue of pending IO events. |