bindings for io_uring, the hottest thing to happen to linux IO in a long time.
rio aims to leverage Rust's compile-time checks to be
misuse-resistant compared to io_uring interfaces in
other languages, but users should beware that
use-after-free bugs are still possible without
unsafe when using rio.
Completion borrows the
buffers involved in a request, and its destructor
blocks in order to delay the freeing of those buffers
until the corresponding request has completed; but it
is considered safe in Rust for an object's lifetime
and borrows to end without its destructor running,
and this can happen in various ways, including
std::mem::forget. Be careful not to let
completions leak in this way, and if Rust's soundness
guarantees are important to you, you may want to
avoid this crate.
- only relies on libc, no need for c/bindgen to complicate things, nobody wants that
- the completions work great with threads or an
async runtime (
- uses Rust marker traits to guarantee that a buffer will never be written into unless it is writable memory. (prevents you from trying to write data into static read-only memory)
- no need to mess with
libc::iovecdirectly. rio maintains these in the background for you.
- If left to its own devices, io_uring will allow you to submit more IO operations than would actually fit in the completion queue, allowing completions to be dropped and causing leaks of any userspace thing waiting for the completion. rio exerts backpressure on submitters when the number of in-flight requests reaches this threshold, to guarantee that no completions will be dropped due to completion queue overflow.
- rio will handle submission queue submissions
automatically. If you start waiting for a
Completion, rio will make sure that we have already submitted at least this request to the kernel. Other io_uring libraries force you to handle this manually, which is another possible source of misuse.
This is intended to be the core of sled's writepath. It is built with a specific high-level application in mind: a high performance storage engine and replication system.
io_uring is the biggest thing to happen to the
linux kernel in a very long time. It will change
everything. Anything that uses epoll right now
will be rewritten to use io_uring if it wants
to stay relevant. It started as a way to do real
async disk IO without needing to use O_DIRECT, but
its scope has expanded and it will continue to support
more and more kernel functionality over time due to
its ability to batch large numbers different syscalls.
In kernel 5.5 support is added for more networking
In 5.6 support is being added for
io_uring has been measured to dramatically outperform
epoll-based networking, with io_uring outperforming
epoll-based setups more and more under heavier load.
I started rio to gain an early deep understanding of this
amazing new interface, so that I could use it ASAP and
responsibly with sled.
io_uring unlocks the following kernel features:
- fully-async interface for a growing number of syscalls
- async disk IO without using O_DIRECT as you have to do with AIO
- batching hundreds of disk and network IO operations into a single syscall, which is especially wonderful in a post-meltdown/spectre world where our syscalls have dramatically slowed down
- 0-syscall IO operation submission, if configured in SQPOLL mode
- configurable completion polling for trading CPU for low latency
- Allows expression of sophisticated 0-copy broadcast semantics, similar to splice(2) or sendfile(2) but working with many file-like objects without ever needing to bounce memory and mappings into userspace en-route.
- Allows IO buffers and file descriptors to be registered for cheap reuse (remapping buffers and file descriptors for use in the kernel has a significant cost).
To read more about io_uring, check out:
- Ringing in a new asynchronous I/O API
- Efficient IO with io_uring
- What’s new with io_uring
- Follow Jens Axboe on Twitter to follow dev progress
For some slides with interesting io_uring performance results, check out slides 43-53 of this presentation deck by Jens.
why not use those other Rust io_uring libraries?
- they haven't copied
rio's features yet, which you pretty much have to use anyway to responsibly use
io_uringdue to the sharp edges of the API. All of the libraries I've seen as of January 13 2020 are totally easy to overflow the completion queue with, as well as easy to express use-after-frees with, don't seem to be async-friendly, etc...
examples that will be broken in the next day or two
async tcp echo server:
use ; async
let ring = new.expect; let file = open.expect; let data: &mut = &mut ; let completion = ring.read_at; // if using threads completion.wait?; // if using async completion.await?
let ring = new.expect; let file = create.expect; let to_write: & = &; let completion = ring.write_at; // if using threads completion.wait?; // if using async completion.await?
speedy O_DIRECT shi0t (try this at home / run the o_direct example)
use ; const CHUNK_SIZE: u64 = 4096 * 256; // `O_DIRECT` requires all reads and writes // to be aligned to the block device's block // size. 4096 might not be the best, or even // a valid one, for yours! ;