Stage 1 of 5FREE PREVIEW~20 min read

Stage 1: io_uring Ring Initialization & SQE/CQE Mechanics

Set up the Linux io_uring instance, mmap the Submission Queue (SQ) and Completion Queue (CQ), and submit asynchronous reads.

Stage 1: The io_uring Architecture

In Stage 1, we replace traditional blocking POSIX read() and write() syscalls with asynchronous io_uring rings.

Submitting I/O is as simple as populating a Submission Queue Entry (SQE) in shared memory and notifying the kernel with io_uring_submit().

File purpose: Clean C++20 RAII abstraction over io_uring submission and completion queues.
cpp
#pragma once
#include <liburing.h>
#include <stdexcept>
#include <string>

class UringEngine {
public:
    explicit UringEngine(unsigned int queue_depth = 256) : depth_(queue_depth) {
        struct io_uring_params params{};
        int ret = io_uring_queue_init_params(depth_, &ring_, &params);
        if (ret < 0) {
            throw std::runtime_error("Failed to initialize io_uring: " + std::to_string(-ret));
        }
    }

    ~UringEngine() {
        io_uring_queue_exit(&ring_);
    }

    struct io_uring* raw_ring() noexcept { return &ring_; }

private:
    unsigned int depth_;
    struct io_uring ring_{};
};

Implementation Breakdown

io_uring Ring Initialization

  • Shared Memory Rings: io_uring_queue_init_params sets up two single-producer single-consumer circular buffers shared between the userspace process and kernel memory.
  • Submissions require no mutex locking: userspace writes SQEs, and the kernel consumes them concurrently.
Stage Verification & Test Benchmark
READY TO RUN
BASH
g++ -std=c++20 -O3 src/main.cpp -luring -o build/flux_test
./build/flux_test --file /tmp/test_nvme.dat --write-test
# ✓ 256 parallel SQEs submitted
# ✓ 256 CQEs reaped with 0 errors