Crate hringas 

Pure Rust io_uring bindings that do not rely on libc, or the rust standard library. The api is designed to be simple and straight-forward.

Start with IoUring - this is the primary entry point.

This is a systems programming library at the same level of abstraction as liburing. while unsafe methods are kept to a minimum, submitting things to the linux kernel to be modified asynchronously is inherently outside rust’s concept of “safety”.

It is based on the iouring implementation in the zig standard library, though the design is beginning to diverge. The only dependency in rustix, which is roughly the equivalent of zig’s std.os.

Example

use hringas::{Cqe, IoUring};
use std::fs;
use std::os::fd::AsFd;

fn main() {
    let mut ring = IoUring::new(8).unwrap();

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

    let sqe = ring.get_sqe().expect("submission queue is full");
    sqe.prep_read(0x42, fd.as_fd(), &mut buf, 0);

    // Note that the developer needs to ensure
    // that the entry pushed into submission queue is valid (e.g. fd, buffer).
    let Cqe { user_data, res, .. } = unsafe {
        ring.submit_and_wait(1).unwrap();
        ring.copy_cqe().expect("completion queue is empty")
    };

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

Or, in no_std:

#![no_std]
use hringas::rustix::fd::AsFd;
use hringas::rustix::fs::{openat, Mode, OFlags, CWD};
use hringas::{Cqe, IoUring};

fn main() {
    let mut ring = IoUring::new(8).unwrap();

    let fd = openat(CWD, "README.md", OFlags::RDONLY, Mode::empty()).unwrap();
    let mut buf = [0; 1024];

    let sqe = ring.get_sqe().expect("submission queue is full");
    sqe.prep_read(0x42, fd.as_fd(), &mut buf, 0);

    // Note that the developer needs to ensure
    // that the entry pushed into submission queue is valid (e.g. fd, buffer).
    let Cqe { user_data, res, .. } = unsafe {
        ring.submit_and_wait(1).unwrap();
        ring.copy_cqe().expect("completion queue is empty")
    };

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

Re-exports

pub use rustix;

pub use crate::entry::*;

Modules

entry

err

Structs

BorrowedFd

A borrowed file descriptor.

Errno

errno—An error code.

IoUring

The main entry point to the library.

IoringEnterFlags

IORING_ENTER_* flags for use with io_uring_enter.

IoringSqeFlags

IOSQE_* flags for use with io_uring_sqe.

ReadWriteFlags

RWF_* constants for use with preadv2 and pwritev2.

io_uring_params

iovec

Enums

IoringOp

IORING_OP_* constants for use with io_uring_sqe.