io-uring Rust Documentation

To perform asynchronous I/O operations, you must initialize an IoUring instance, build an opcode (such as Read), push it to the submission queue, and then wait for the completion queue entry (CQE).

Important Safety Note: The developer is responsible for ensuring that the entries pushed into the submission queue remain valid (e.g., the file descriptor and the buffer must not be dropped or moved) until the operation completes.

Kernel Requirement: The Read opcode requires Linux kernel 5.6 or higher. Using a kernel version lower than 5.6 will cause the operation to fail.

use io_uring::{opcode, types, IoUring};
use std::os::unix::io::AsRawFd;
use std::{fs, io};

fn main() -> io::Result<()> {
    let mut ring = IoUring::new(8)?;

    let fd = fs::File::open("README.md")?;
    let mut buf = vec![0; 1024];

    let read_e = opcode::Read::new(types::Fd(fd.as_raw_fd()), buf.as_mut_ptr(), buf.len() as _) 
        .build()
        .user_data(0x42);

    // Note that the developer needs to ensure
    // that the entry pushed into submission queue is valid (e.g. fd, buffer).
    unsafe {
        ring.submission()
            .push(&read_e)
            .expect("submission queue is full");
    }

    ring.submit_and_wait(1)?;

    let cqe = ring.completion().next().expect("completion queue is empty");

    assert_eq!(cqe.user_data(), 0x42);
    assert!(cqe.result() >= 0, "read error: {}", cqe.result());

    Ok()
}

To perform asynchronous I/O using the io-uring crate, you follow a pattern of creating an IoUring instance, building an opcode (such as Read), pushing that opcode to the submission queue, and then submitting the queue and waiting for completions.

Important Safety Note: The developer is responsible for ensuring that the resources used in the submission (such as file descriptors and memory buffers) remain valid until the operation completes. The io_uring crate uses unsafe blocks for submission because it cannot guarantee the lifetime of the underlying memory or file descriptors once they are handed off to the kernel.

use io_uring::{opcode, types, IoUring};
use std::os::unix::io::AsRawFd;
use std::{fs, io};

fn main() -> io::Result<()> {
    // Initialize a ring with a capacity of 8 entries
    let mut ring = IoUring::new(8)?;

    let fd = fs::File::open("README.md")?;
    let mut buf = vec![0; 1024];

    // 1. Build the opcode (e.g., Read)
    // We use types::Fd to wrap the raw file descriptor
    let read_e = opcode::Read::new(types::Fd(fd.as_raw_fd()), buf.as_mut_ptr(), buf.len() as _)
        .build()
        .user_data(0x42);

    // 2. Push the entry to the submission queue
    // This requires an unsafe block because the kernel will access the buffer/fd
    unsafe {
        ring.submission()
            .push(&read_e)
            .expect("submission queue is full");
    }

    // 3. Submit the entries and wait for at least 1 completion
    ring.submit_and_wait(1)?;

    // 4. Retrieve the completion queue entry (CQE)
    let cqe = ring.completion().next().expect("completion queue is empty");

    // Verify the user_data and the result (bytes read)
    assert_eq!(cqe.user_data(), 0x42);
    assert!(cqe.result() >= 0, "read error: {}", cqe.result());

    Ok()
}