liburing-rs

Rust bindings for liburing (Linux io_uring).

This provides Rust FFI bindings and idiomatic wrappers for https://github.com/axboe/liburing

Requirements

• Linux kernel 5.1+
• liburing 2.12 or newer (liburing.so)

Installing liburing

Debian/Ubuntu:

apt install liburing-dev

Fedora:

dnf install liburing-devel

Arch:

pacman -S liburing

From source:

git clone https://github.com/axboe/liburing.git
cd liburing
./configure
make
sudo make install

Build

cargo build --release

The build script:

1. Tries pkg-config to find system liburing
2. Falls back to cloning and building liburing-2.12 from source if not found
3. Uses bindgen to generate FFI bindings

Usage

Synchronous API:

use liburing_rs::{IoUring, ops::*};

let mut ring = IoUring::new(32)?;

// Submit operations
{
    let mut sq = ring.submission();
    let sqe = sq.get_sqe_or_err()?;
    Nop.prepare(sqe);
    sqe.set_user_data(1);
}

ring.submit()?;

// Get completions
let mut cq = ring.completion();
let cqe = cq.wait_cqe()?;
println!("Result: {}", cqe.result());

Async API (tokio):

use liburing_rs::async_io::AsyncIoUring;
use liburing_rs::ops::Nop;

let mut ring = AsyncIoUring::new(32)?;
let result = ring.submit_op(Nop).await?;
println!("Result: {}", result);

Enable with async-tokio feature:

liburing-rs = { version = "0.1", features = ["async-tokio"] }

Async API (async-std):

Enable with async-async-std feature:

liburing-rs = { version = "0.1", features = ["async-async-std"] }

Examples

Synchronous examples:

# Basic NOP operation
cargo run --example nop

# File copy
cargo run --release --example io_uring-cp source.txt dest.txt

# Linked operations
cargo run --release --example link-cp source.txt dest.txt

# Polling benchmark
cargo run --release --example poll-bench

Async examples:

# Async NOP with tokio
cargo run --example async_nop_tokio --features async-tokio

# Async NOP with async-std
cargo run --example async_nop_async_std --features async-async-std

# Async polling benchmark (tokio)
cargo run --release --example async_poll_bench --features async-tokio

# Async polling benchmark (async-std)
cargo run --release --example async_poll_bench_async_std --features async-async-std

Tests

cargo test --all

Coverage includes:

• Basic operations (NOP, fsync, close)
• File I/O (read, write, readv, writev)
• Network I/O (accept, connect, send, recv)
• Advanced features (timeout, poll, linking, cancellation)

Architecture

Four layers:

1. sys: Raw FFI bindings (unsafe)
2. Safe wrappers: RAII types (IoUring, SubmissionQueue, CompletionQueue)
3. Operations: Type-safe operation builders (Read, Write, etc.)
4. Async runtime integration: AsyncIoUring for tokio and async-std (optional)

Performance

poll-bench achieves ~12M ops/sec (93% of C liburing performance).

License

MIT

Author

Charalampos Mitrodimas <[email protected]>