Crate io_uring

This crate provides a wrapper around liburing-sys providing a safe and simple way for creating a io_uring instance, registering an eventfd file descriptor for receiving completion notifications, submitting read and write requests, and checking for completions.

Usage

Requirements

This crate requires a kernel with io_uring support. This means 5.1 or higher. Support for registering an eventfd for receiving completion notifications requires 5.2 or higher.

Unaligned buffers

Under certain circumstances, io_uring may require the buffer holding the data for a write operation, or used to store the data for a read request, to be page-aligned.

This crate checks the buffer alignment, and it either passes it directly to the kernel (if page aligned), or uses a temporary self-allocated buffer for the operation (if not page aligned), copying in/out the data between both buffers as required.

This behavior allows users of this crate to avoid worrying about buffer alignment themselves, but this comes with a cost (one additional copy plus the cost of allocating and freeing the temporary buffer). Users desiring to obtain the best possible performance need to make sure their buffers are aligned before using them to submit read/write requests to UringQueue.

Example

use io_uring::{Error, UringQueue};
use std::fs::File;
use std::io;
use std::os::unix::io::AsRawFd;

fn read_exact(file: File, buf: &mut [u8], offset: i64, wait: bool) -> Result<(), Error> {
    let mut queue = UringQueue::new(128)?;
    let cookie: u64 = 1234;

    queue.submit_read(file.as_raw_fd(), buf, offset, cookie)?;
    match queue.get_completion(wait)? {
        Some(c) => {
            assert!(c == cookie);
            println!("Successfully read from file: buf={:?}", buf);
            Ok(())
        }
        None => {
            assert!(!wait);
            Err(Error::IOError(io::Error::new(
                io::ErrorKind::WouldBlock,
                "completion queue was empty and wait == false",
            )))
        }
    }
}

Structs

UringQueue

UringQueue provides safe access to io_uring features.

Enums

Error

Errors from UringQueue operations.

Constants

IORING_REGISTER_EVENTFD	Register an eventfd in the uring for completion notifications.
IORING_UNREGISTER_EVENTFD	Unregister a previously registered eventfd.