Crate liburing_rs

Expand description

Rust bindings for io_uring via a transliteration of Jens Axboe’s liburing.

Building this crate successfully may require the following in your .cargo/config.toml:

[env]
CLANG_PATH = "/usr/bin/clang-20"
LIBCLANG_PATH = "/usr/lib/llvm-20/lib"

in order for bindgen to successfully generate the required struct definitions.

This crate implements an almost pure Rust version of Jens Axboe’s liburing. All the good names were taken so the package’s name is axboe-liburing but the imported crate is liburing_rs.

liburing has tremendous value in that it’s a low-level unopinionated set of helpers that form a complete vocabulary for using io_uring. Originally designed as a set of test helpers, liburing is used to setup and teardown rings, register buffer groups, and create and manage SQEs and CQEs. liburing’s API offers users a comprehensive way of using io_uring in a simple manner.

axboe-liburing implements the entire header liburing.h in native Rust so that everything is as equally inlined as if you were using the library from C or C++. This covers around 142 public functions.

Add the crate with:

cargo add axboe-liburing

axboe-liburing ships with the liburing source and builds liburing.a, statically linking it in via the build.rs. This means that axboe-liburing requires a C toolchain be present on the system in order to build. Typical conventions are followed, the environment variables CC, CXX are used to set the C and C++ compilers.

CC=clang-19 CXX=clang++-19 cargo build

§Building Tests

axboe-liburing includes a few Rust-specific tests to verify the basic flow works but the lion’s share of the testing is in recycling what already exists in liburing proper. To this end, we need objcopy in order to weaken the io_uring_get_sqe() symbol present in liburing.a. When cross-compiling, it can be important to specify the objcopy being used. The objcopy binary can be set via the OBJCOPY environment variable. objcopy ships with gcc toolchains.

Example building liburing tests with liburing-rs:

export CC=aarch64-linux-gnu-gcc
export CXX=aarch64-linux-gnu-g++
export OBJCOPY=aarch64-linux-gnu-objcopy
export CARGO_TOOLCHAIN=aarch64-unknown-linux-gnu
make -C test liburing_rs_tests -j$(nproc)

axboe-liburing is also tested using sanitizers as well. To build the tests with sanitization enabled, one needs to enable the sanitizers feature. This causes the crate to build liburing.a with sanitization enabled.

RUSTFLAGS='-Zsanitizer=address' cargo +nightly test --features sanitizers --target x86_64-unknown-linux-gnu -Zbuild-std

For building the liburing_rs_tests target in test/Makefile, one needs to first configure the project to use sanitization.

# for liburing_rs_test.a, needed for the C test files to link against
./configure --enable-sanitizer

# builds everything, including C the default tests which are relied upon to exist by other tests
make all -j$(nproc)

# build a static library that exports everything from the Rust crate and use a shim header in the
# test files so that they link against the Rust-derived staticlib
make -C test liburing_rs_tests -j$(nproc)

§Docs

For documentation, see the man pages for the liburing package itself. The Arch Linux pages have relatively up-to-date docs: https://man.archlinux.org/listing/extra/liburing/.

Examples can be found in the main repo: https://github.com/axboe/liburing/tree/master/examples

§Example

extern crate liburing_rs;

use std::{mem::zeroed, ptr, time::Duration};

use liburing_rs::*;

pub fn queue_init() {
    // Setup the ring.
    //
    // We create a stack-local instance of `struct io_uring` and use
    // the `io_uring_queue_init` function to initialize all of its
    // fields, using a submission queue size of 64. liburing sets
    // the size of the CQ to twice the SQ size by default.
    //
    let mut ring = unsafe { zeroed::<io_uring>() };
    let ring = &raw mut ring;
    let r = unsafe { io_uring_queue_init(64, ring, 0) };
    assert_eq!(r, 0);

    // Grab a pointer to an unused SQE from the SQ
    let sqe = unsafe { io_uring_get_sqe(ring) };
    assert!(!sqe.is_null());

    // We're going to create an SQE that completes after a specified
    // amount of time, in this case 250ms. We introduce a cast for `ts`
    // because liburing expects a pointer to `__kernel_timespec` which
    // is layout compatible.
    //
    let dur = Duration::from_millis(250);
    let mut ts: timespec = dur.into();
    let ts = (&raw mut ts).cast();

    unsafe { io_uring_prep_timeout(sqe, ts, 0, 0) };
    unsafe { io_uring_sqe_set_data64(sqe, 1234) };

    // Submit the SQ to the kernel for processing. `io_uring_submit` returns
    // the number of submitted entries that are going to be processed. In this case,
    // we only have 1 work item.
    //
    let n = unsafe { io_uring_submit(ring) };
    assert_eq!(n, 1);

    // Grab the first CQE off the queue and make sure it has the same `user_data`
    // field that we originally set.
    //
    let mut cqe = ptr::null_mut::<io_uring_cqe>();
    unsafe { io_uring_wait_cqe(ring, &raw mut cqe) };

    assert!(!cqe.is_null());
    assert_eq!(unsafe { (*cqe).user_data }, 1234);

    // Mark the CQE as seen so that its spot can be reused as more
    // completions arrive.
    //
    unsafe { io_uring_cqe_seen(ring, cqe) };

    // Teardown the ring.
    //
    unsafe { io_uring_queue_exit(ring) };
}

Structs§

io_uring: Asynchronous I/O facility
io_uring_clone_buffers: Clones registered buffers between rings.

Constants§

IOSQE_ASYNC
IOSQE_BUFFER_SELECT
IOSQE_CQE_SKIP_SUCCESS
IOSQE_FIXED_FILE
IOSQE_IO_DRAIN
IOSQE_IO_HARDLINK
IOSQE_IO_LINK

Functions§

__io_uring_buf_ring_cq_advance^⚠: Advance index of provided buffer and CQ ring.
__io_uring_clone_buffers^⚠: Clones registered buffers between rings.
__io_uring_clone_buffers_offset^⚠: Clones registered buffers between rings.
io_uring_buf_ring_add^⚠: Add buffers to a shared buffer ring.
io_uring_buf_ring_advance^⚠: Advance index of provided buffer in buffer ring.
io_uring_buf_ring_available^⚠: Return number of unconsumed provided ring buffer entries.
io_uring_buf_ring_cq_advance^⚠: Advance index of provided buffer and CQ ring.
io_uring_buf_ring_init^⚠: Initialise a buffer ring.
io_uring_buf_ring_mask: Calculate buffer ring mask size.
io_uring_check_version^⚠: Functions and macros to check the liburing version.
io_uring_clone_buffers^⚠: Clones registered buffers between rings.
io_uring_clone_buffers_offset^⚠: Clones registered buffers between rings.
io_uring_close_ring_fd^⚠: Close a ring file descriptor and use it only via registered index.
io_uring_cq_advance^⚠: Mark one or more io_uring completion events as consumed.
io_uring_cq_eventfd_enabled^⚠: Check if eventfd notifications are enabled.
io_uring_cq_eventfd_toggle^⚠: Toggle eventfd notifications on or off.
io_uring_cq_has_overflow^⚠: Returns if there are overflow entries waiting to move to the CQ ring.
io_uring_cq_ready^⚠: Returns number of unconsumed ready entries in the CQ ring.
io_uring_cqe_get_data^⚠: Get user data for completion event.
io_uring_cqe_get_data64^⚠: Get user data for completion event.
io_uring_cqe_iter_init^⚠
io_uring_cqe_iter_next^⚠
io_uring_cqe_nr^⚠: Return the number of CQ ring slots consumed by a CQE.
io_uring_cqe_seen^⚠: Mark io_uring completion event as consumed.
io_uring_cqe_shift^⚠
io_uring_cqe_shift_from_flags
io_uring_enable_rings^⚠: Enable a disabled ring.
io_uring_enter^⚠: Initiate and/or complete asynchronous I/O.
io_uring_enter2^⚠: Initiate and/or complete asynchronous I/O.
io_uring_for_each_cqe^⚠: Iterate pending completion events.
io_uring_free_buf_ring^⚠: Register and free a buffer ring for provided buffers.
io_uring_free_probe^⚠: Free probe instance.
io_uring_get_events^⚠: Flush outstanding requests to CQE ring.
io_uring_get_probe^⚠: Get probe instance.
io_uring_get_probe_ring^⚠: Get probe information from an existing ring.
io_uring_get_sqe^⚠: Get the next available submission queue entry from the submission queue.
io_uring_get_sqe128^⚠: Get the next available 128-byte submission queue entry from the submission queue.
io_uring_initialize_sqe^⚠
io_uring_load_sq_head^⚠
io_uring_major_version^⚠: Functions and macros to check the liburing version.
io_uring_minor_version^⚠: Functions and macros to check the liburing version.
io_uring_opcode_supported^⚠: Is op code supported?.
io_uring_peek_batch_cqe^⚠: Check if an io_uring completion event is available.
io_uring_peek_cqe^⚠: Check if an io_uring completion event is available.
io_uring_prep_accept^⚠: Prepare an accept request.
io_uring_prep_accept_direct^⚠: Prepare an accept request.
io_uring_prep_bind^⚠: Prepare a bind request.
io_uring_prep_cancel^⚠: Prepare a cancelation request.
io_uring_prep_cancel64^⚠: Prepare a cancelation request.
io_uring_prep_cancel_fd^⚠: Prepare a cancelation request.
io_uring_prep_close^⚠: Prepare a file descriptor close request.
io_uring_prep_close_direct^⚠: Prepare a file descriptor close request.
io_uring_prep_cmd_discard^⚠: Prepare a discard command.
io_uring_prep_cmd_getsockname^⚠: Prepare a getsockname or getpeername. request
io_uring_prep_cmd_sock^⚠: Prepare a command request for a socket.
io_uring_prep_connect^⚠: Prepare a connect request.
io_uring_prep_epoll_ctl^⚠: Prepare an epoll_ctl request.
io_uring_prep_epoll_wait^⚠: Prepare an epoll wait request.
io_uring_prep_fadvise^⚠: Prepare a fadvise request.
io_uring_prep_fadvise64^⚠: Prepare a fadvise request.
io_uring_prep_fallocate^⚠: Prepare a fallocate request.
io_uring_prep_fgetxattr^⚠: Prepare a request to. get an extended attribute value
io_uring_prep_files_update^⚠: Prepare a registered file update request.
io_uring_prep_fixed_fd_install^⚠: Prepare fixed file fd installation. request
io_uring_prep_fsetxattr^⚠: Prepare a request to. set an extended attribute value
io_uring_prep_fsync^⚠: Prepare an fsync request.
io_uring_prep_ftruncate^⚠: Prepare an ftruncate request.
io_uring_prep_futex_wait^⚠: Prepare a futex wait request.
io_uring_prep_futex_waitv^⚠: Prepare a futex waitv request.
io_uring_prep_futex_wake^⚠: Prepare a futex wake request.
io_uring_prep_getxattr^⚠: Prepare a request to. get an extended attribute value
io_uring_prep_link^⚠: Prepare a linkat request.
io_uring_prep_link_timeout^⚠: A timeout request for linked sqes.
io_uring_prep_linkat^⚠: Prepare a linkat request.
io_uring_prep_listen^⚠: Prepare a listen request.
io_uring_prep_madvise^⚠: Prepare a madvise request.
io_uring_prep_madvise64^⚠: Prepare a madvise request.
io_uring_prep_mkdir^⚠: Prepare an mkdirat request.
io_uring_prep_mkdirat^⚠: Prepare an mkdirat request.
io_uring_prep_msg_ring^⚠: Send a message to another ring.
io_uring_prep_msg_ring_cqe_flags^⚠: Send a message to another ring.
io_uring_prep_msg_ring_fd^⚠: Send a direct descriptor to another ring.
io_uring_prep_msg_ring_fd_alloc^⚠: Send a direct descriptor to another ring.
io_uring_prep_multishot_accept^⚠: Prepare an accept request.
io_uring_prep_multishot_accept_direct^⚠: Prepare an accept request.
io_uring_prep_nop^⚠: Prepare a nop request.
io_uring_prep_nop128^⚠: Prepare a nop request.
io_uring_prep_open^⚠: Prepare an openat request.
io_uring_prep_open_direct^⚠: Prepare an openat request.
io_uring_prep_openat^⚠: Prepare an openat request.
io_uring_prep_openat2^⚠: Prepare an openat2 request.
io_uring_prep_openat2_direct^⚠: Prepare an openat2 request.
io_uring_prep_openat_direct^⚠: Prepare an openat request.
io_uring_prep_pipe^⚠: Prepare a pipe creation request.
io_uring_prep_pipe_direct^⚠: Prepare a pipe creation request.
io_uring_prep_poll_add^⚠: Prepare a poll request.
io_uring_prep_poll_multishot^⚠: Prepare a poll request.
io_uring_prep_poll_remove^⚠: Prepare a poll deletion request.
io_uring_prep_poll_update^⚠: Update an existing poll request.
io_uring_prep_provide_buffers^⚠: Prepare a provide buffers request.
io_uring_prep_read^⚠: Prepare I/O read request.
io_uring_prep_read_fixed^⚠: Prepare I/O read request with registered. buffer
io_uring_prep_read_multishot^⚠: Prepare I/O read multishot request.
io_uring_prep_readv^⚠: Prepare vector I/O read request.
io_uring_prep_readv2^⚠: Prepare vector I/O read request with flags.
io_uring_prep_readv_fixed^⚠: Prepare a vectored read using fixed buffers.
io_uring_prep_recv^⚠: Prepare a recv request.
io_uring_prep_recv_multishot^⚠: Prepare a recv request.
io_uring_prep_recvmsg^⚠: Prepare a recvmsg request.
io_uring_prep_recvmsg_multishot^⚠: Prepare a recvmsg request.
io_uring_prep_remove_buffers^⚠: Prepare a remove buffers request.
io_uring_prep_rename^⚠: Prepare a renameat request.
io_uring_prep_renameat^⚠: Prepare a renameat request.
io_uring_prep_rw^⚠
io_uring_prep_send^⚠: Prepare a send request.
io_uring_prep_send_bundle^⚠: Prepare a send request.
io_uring_prep_send_set_addr^⚠: Set address details for send requests.
io_uring_prep_send_zc^⚠: Prepare a zerocopy send request.
io_uring_prep_send_zc_fixed^⚠: Prepare a zerocopy send request.
io_uring_prep_sendmsg^⚠: Prepare a sendmsg request.
io_uring_prep_sendmsg_zc^⚠: Prepare a sendmsg request.
io_uring_prep_sendmsg_zc_fixed^⚠: Prepare a zero-copy sendmsg using fixed. buffers
io_uring_prep_sendto^⚠: Prepare a send request.
io_uring_prep_setxattr^⚠: Prepare a request to. set an extended attribute value
io_uring_prep_shutdown^⚠: Prepare a shutdown request.
io_uring_prep_socket^⚠: Prepare a socket creation request.
io_uring_prep_socket_direct^⚠: Prepare a socket creation request.
io_uring_prep_socket_direct_alloc^⚠: Prepare a socket creation request.
io_uring_prep_splice^⚠: Prepare an splice request.
io_uring_prep_statx^⚠: Prepare a statx request.
io_uring_prep_symlink^⚠: Prepare a symlinkat request.
io_uring_prep_symlinkat^⚠: Prepare a symlinkat request.
io_uring_prep_sync_file_range^⚠: Prepare a sync_file_range request.
io_uring_prep_tee^⚠: Prepare a tee request.
io_uring_prep_timeout^⚠: Prepare a timeout request.
io_uring_prep_timeout_remove^⚠: Prepare a request to update an existing. timeout
io_uring_prep_timeout_update^⚠: Prepare a request to update an existing. timeout
io_uring_prep_unlink^⚠: Prepare an unlinkat request.
io_uring_prep_unlinkat^⚠: Prepare an unlinkat request.
io_uring_prep_uring_cmd^⚠: Prepare a uring_cmd request.
io_uring_prep_uring_cmd128^⚠: Prepare a uring_cmd request.
io_uring_prep_waitid^⚠: Prepare a waitid request.
io_uring_prep_write^⚠: Prepare I/O write request.
io_uring_prep_write_fixed^⚠: Prepare I/O write request with registered. buffer
io_uring_prep_writev^⚠: Prepare vector I/O write request.
io_uring_prep_writev2^⚠: Prepare vector I/O write request with flags.
io_uring_prep_writev_fixed^⚠: Prepare a vectored write using fixed. buffers
io_uring_queue_exit^⚠: Tear down io_uring submission and completion. queues
io_uring_queue_init^⚠: Setup io_uring submission and completion queues.
io_uring_queue_init_mem^⚠: Setup io_uring submission and completion queues.
io_uring_queue_init_params^⚠: Setup io_uring submission and completion queues.
io_uring_queue_mmap^⚠: Mmap io_uring ring after setup.
io_uring_recvmsg_cmsg_firsthdr^⚠: Access data from multishot recvmsg.
io_uring_recvmsg_cmsg_nexthdr^⚠: Access data from multishot recvmsg.
io_uring_recvmsg_name^⚠: Access data from multishot recvmsg.
io_uring_recvmsg_payload^⚠: Access data from multishot recvmsg.
io_uring_recvmsg_payload_length^⚠: Access data from multishot recvmsg.
io_uring_recvmsg_validate^⚠: Access data from multishot recvmsg.
io_uring_register^⚠: Register files or user buffers for asynchronous I/O.
io_uring_register_bpf_filter^⚠: Register classic BPF filters for io_uring operations.
io_uring_register_bpf_filter_task^⚠: io_uring_register_bpf_filter, io_uring_register_bpf_filter_task - register classic BPF filters for io_uring operations
io_uring_register_buf_ring^⚠: Register buffer ring for provided buffers.
io_uring_register_buffers^⚠: Register buffers for fixed buffer operations.
io_uring_register_buffers_sparse^⚠: Register buffers for fixed buffer operations.
io_uring_register_buffers_tags^⚠: Register buffers for fixed buffer operations.
io_uring_register_buffers_update_tag^⚠: Register buffers for fixed buffer operations.
io_uring_register_clock^⚠: Set clock source for event waiting.
io_uring_register_eventfd^⚠: Register an eventfd with a ring.
io_uring_register_eventfd_async^⚠: Register an eventfd with a ring.
io_uring_register_file_alloc_range^⚠: Set range for fixed file. allocations
io_uring_register_files^⚠: Register file descriptors.
io_uring_register_files_sparse^⚠: Register file descriptors.
io_uring_register_files_tags^⚠: Register file descriptors.
io_uring_register_files_update^⚠: Register file descriptors.
io_uring_register_files_update_tag^⚠: Register file descriptors.
io_uring_register_ifq^⚠: Register a zero-copy receive interface queue.
io_uring_register_iowq_max_workers^⚠: Modify the maximum allowed async. workers
io_uring_register_napi^⚠: Register NAPI busy poll settings.
io_uring_register_personality^⚠: Register credentials with io_uring.
io_uring_register_probe^⚠: Register probe with io_uring.
io_uring_register_query^⚠: Query io_uring capabilities and feature. support
io_uring_register_region^⚠: Register a memory region.
io_uring_register_restrictions^⚠: Register restrictions with io_uring.
io_uring_register_ring_fd^⚠: Register a ring file descriptor.
io_uring_register_sync_cancel^⚠: Issue a synchronous cancelation request.
io_uring_register_sync_msg^⚠: Send a synchronous message to another ring.
io_uring_register_wait_reg^⚠: Register wait regions with io_uring.
io_uring_register_zcrx_ctrl^⚠: Perform control operations on a zero-copy. receive context
io_uring_resize_rings^⚠: Resize the SQ and CQ rings.
io_uring_ring_dontfork^⚠: Prevent ring memory from being shared after fork.
io_uring_setup^⚠: Setup a context for performing asynchronous I/O.
io_uring_setup_buf_ring^⚠: Setup and register buffer ring for provided. buffers
io_uring_sq_ready^⚠: Number of unconsumed or unsubmitted entries in the. SQ ring
io_uring_sq_space_left^⚠: Free space in the SQ ring.
io_uring_sqe_set_buf_group^⚠: Set buf group for submission queue event.
io_uring_sqe_set_data^⚠: Set user data for submission queue event.
io_uring_sqe_set_data64^⚠: Set user data for submission queue event.
io_uring_sqe_set_flags^⚠: Set flags for submission queue entry.
io_uring_sqe_shift^⚠
io_uring_sqe_shift_from_flags
io_uring_sqring_wait^⚠: Wait for free space in the SQ ring.
io_uring_submit^⚠: Submit requests to the submission queue.
io_uring_submit_and_get_events^⚠: Submit requests to the submission queue. and flush completions
io_uring_submit_and_wait^⚠: Submit requests to the submission queue and wait for completion.
io_uring_submit_and_wait_min_timeout^⚠: Submit requests to the submission. queue and wait for the completion with both batch and normal timeout
io_uring_submit_and_wait_reg^⚠: Sets up and registers fixed wait regions.
io_uring_submit_and_wait_timeout^⚠: Submit requests to the submission. queue and wait for the completion with timeout
io_uring_unregister_buf_ring^⚠: Unregister a previously registered buffer. ring
io_uring_unregister_buffers^⚠: Unregister buffers for fixed buffer. operations
io_uring_unregister_eventfd^⚠: Register an eventfd with a ring.
io_uring_unregister_files^⚠: Unregister file descriptors.
io_uring_unregister_iowq_aff^⚠: Register async worker CPU affinities.
io_uring_unregister_napi^⚠: Unregister NAPI busy poll settings.
io_uring_unregister_personality^⚠: Unregister a personality from io_uring.
io_uring_unregister_ring_fd^⚠: Unregister a ring file descriptor.
io_uring_wait_cqe^⚠: Wait for one io_uring completion event.
io_uring_wait_cqe_nr^⚠: Wait for one or more io_uring completion events.
io_uring_wait_cqe_timeout^⚠: Wait for one io_uring completion event with. timeout
io_uring_wait_cqes^⚠: Wait for one or more io_uring completion events.
io_uring_wait_cqes_min_timeout^⚠: Wait for completions with both batch. and normal timeout