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:

.. code:: bash

apt install liburing-dev

Fedora:

.. code:: bash

dnf install liburing-devel

Arch:

.. code:: bash

pacman -S liburing

From source:

.. code:: bash

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

Build

.. code:: bash

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:

.. code:: rust

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):

.. code:: rust

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:

.. code:: toml

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

Async API (async-std):

Enable with async-async-std feature:

.. code:: toml

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

Examples

Synchronous examples:

.. code:: bash

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:

.. code:: bash

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

.. code:: bash

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 charmitro@posteo.net