io-uring

io_uring

Purpose

Guide agents through Linux io_uring: the submission/completion queue model (SQE/CQE), liburing API, multi-shot accept/recv, provided buffer rings, fixed files and registered buffers, zero-copy send, Rust integration with tokio-uring, performance comparison with epoll, and security considerations.

When to Use

• Building a high-throughput network or disk server on Linux 5.1+
• Replacing epoll + thread pool with fewer syscalls
• Implementing multi-shot accept/recv for connection-heavy services
• Using zero-copy networking with IORING_OP_SEND_ZC
• Integrating async I/O in Rust via tokio-uring
• Evaluating io_uring vs epoll for your workload

Workflow

1. SQ/CQ model

Application                    Kernel
    │                            │
    ├── mmap SQ ring ───────────►│ submission queue (SQE)
    ├── mmap CQ ring ◄──────────│ completion queue (CQE)
    ├── io_uring_submit() ──────►│ processes SQEs
    └── io_uring_wait_cqe() ◄──│ posts CQEs

Each SQE describes one operation; each CQE reports result and user_data cookie.

2. Minimal liburing example

#include <liburing.h>
#include <fcntl.h>
#include <unistd.h>
#include <stdio.h>

int main(void) {
    struct io_uring ring;
    io_uring_queue_init(32, &ring, 0);

    int fd = open("test.txt", O_RDONLY);
    char buf[4096];

    struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
    io_uring_prep_read(sqe, fd, buf, sizeof(buf), 0);
    io_uring_sqe_set_data(sqe, (void *)1);

    io_uring_submit(&ring);

    struct io_uring_cqe *cqe;
    io_uring_wait_cqe(&ring, &cqe);
    if (cqe->res >= 0)
        printf("read %d bytes\n", cqe->res);
    else
        perror("read");

    io_uring_cqe_seen(&ring, cqe);
    io_uring_queue_exit(&ring);
    close(fd);
    return 0;
}

gcc -o uring_read uring_read.c -luring
./uring_read

3. Common prep operations

Function	Operation
io_uring_prep_read	File read
io_uring_prep_write	File write
io_uring_prep_recv	Socket recv
io_uring_prep_send	Socket send
io_uring_prep_accept	Accept connection
io_uring_prep_connect	Outbound connect
io_uring_prep_poll_add	Poll fd
io_uring_prep_timeout	Timeout/link timeout