Crate rio

A steamy river of uring. Fast IO using io_uring.

io_uring is going to change everything. It will speed up your disk usage by like 300%. Go ahead, run the O_DIRECT example and compare that to using a threadpool or anything you want. It's not gonna come close!

Starting in linux 5.5, it also has support for tcp accept. This is gonna shred everything out there!!!

But there's a few snags. Mainly, it's a little misuse-prone. But Rust is pretty nice for specifying proofs about memory usage in the type system. And we don't even have to get too squirley. Check out the write_at implementation, for example. It just says that the Completion, the underlying uring, the file being used, the buffer being used, etc... will all be in scope at the same time while the Completion is in-use.

This library aims to be misuse-resistant. Most of the other io_uring libraries make it really easy to blow your legs off with use-after-frees. rio uses standard Rust lifetime specification to make use-after-frees fail to compile. Also, if a Completion that was pinned to the lifetime of a uring and backing buffer is dropped, it waits for its backing operation to complete before returning from Drop, to further prevent use-after-frees. use-after-frees are not expressible when using rio.

Examples

This won't compile:

let rio = rio::new().unwrap();
let file = std::fs::File::open("use_after_free").unwrap();
let out_buf = vec![42; 666];

let completion = rio.write_at(&file, &out_buf, 0).unwrap();

// At this very moment, the kernel has a pointer to that there slice.
// It also has the raw file descriptor of the file.
// It's fixin' to write the data from that memory into the file.
// But if we freed it, it would be a bug,
// and the kernel would write potentially scandalous data
// into the file instead.

// any of the next 3 lines would cause compilation to fail...
drop(out_io_slice);
drop(file);
drop(rio);

// this is both a Future and a normal blocking promise thing.
// If you're using async, just call `.await` on it instead
// of `.wait()`
completion.wait();

// now it's safe to drop those things in any order.

Really shines with O_DIRECT:

use std::{
    fs::OpenOptions,
    io::{IoSlice, Result},
    os::unix::fs::OpenOptionsExt,
};

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!
#[repr(align(4096))]
struct Aligned([u8; CHUNK_SIZE as usize]);

fn main() -> Result<()> {
    // start the ring
    let ring = rio::new().expect("create uring");

    // open output file, with `O_DIRECT` set
    let file = OpenOptions::new()
        .read(true)
        .write(true)
        .create(true)
        .truncate(true)
        .custom_flags(libc::O_DIRECT)
        .open("file")
        .expect("open file");

    // create output buffer
    let out_buf = Aligned([42; CHUNK_SIZE as usize]);
    let out_slice = out_buf.0.as_ref();

    let mut completions = vec![];

    for i in 0..(4 * 1024) {
        let at = i * CHUNK_SIZE;

        let completion = ring.write_at(
            &file,
            &out_slice,
            at,
        );
        completions.push(completion);
    }

    for completion in completions.into_iter() {
        completion.wait()?;
    }

    Ok(())
}

Structs

Completion	A Future value which may or may not be filled
Config	Configuration for the underlying io_uring system.
Rio	Nice bindings for the shiny new linux IO system
Uring	The top-level io_uring structure.

Enums

Ordering

Specify whether io_uring should run operations in a specific order. By default, it will run independent operations in any order it can to speed things up. This can be constrained by either submitting chains of Link events, which are executed one after the other, or by specifying the Drain ordering which causes all previously submitted operations to complete first.

Traits

AsIoVec	Encompasses various types of IO structures that can be operated on as if they were a libc::iovec
AsIoVecMut	We use this internally as a way of communicating that for certain operations, we cannot accept a reference into read-only memory, like for reads.
FromCqe	A trait for describing transformations from the io_uring_cqe type into an expected meaningful high-level result.

Functions

new	Create a new IO system.