C++

C++20 Coroutines + io_uring: A co_await File Read That Actually Runs

A hand-rolled C++20 coroutine reads a file through io_uring with no coroutine library: one pump, 36 bytes, content verified. liburing 2.16 built from source, GCC 13.3.0, and the two fixes the build needed.

Written November 9, 2026 · Tested with GCC 13.3.0 · 13 min read

By the end of this guide
  • The setup: liburing is not installed
  • The two fixes
  • What the nearest pages do not give you

What this guide is

C++20 added three keywords, co_await, co_yield, and co_return, and no type that uses them. The standard library in C++20 ships no task type for asynchronous work; the reference page states it plainly, that other coroutine types are provided by libraries or written by the program, with std::generator arriving in C++23 for sequences and std::execution::task arriving in C++26 for asynchronous operations. So a builder who wants a coroutine to drive an io_uring read today has two honest options: take a library, or write the awaitable by hand. This guide takes the second option and runs it.

The program below is a complete, minimal file read: a hand-rolled Task return type, a hand-rolled ReadAwaitable, and a small event loop in main. One coroutine awaits one read. The read goes through io_uring, submitted with liburing, and the completion queue entry resumes the coroutine. It compiles with the stock GCC 13.3.0 on Ubuntu 24.04, runs under WSL2 kernel 6.18.33.2, and prints PROBE_OK. No coroutine library, no thread pool, no framework.

The result is deliberately small. One pump, one completion, 36 bytes, content verified against the expected string. That is the whole claim: the wiring works, on this toolchain, with this liburing, and the two build fixes below are part of the record, not hidden. A guide that claims a production async file I/O design from a single 36 byte read would be lying, and this one does not.

The setup: liburing is not installed

The first check is whether liburing exists at all. It does not. There is no /usr/include/liburing.h, no pkg-config entry, and no liburing in the dynamic linker cache. The kernel header /usr/include/linux/io_uring.h is present, which means the kernel side is there, but the userspace helper library is not. Ubuntu 24.04 does not ship liburing in the default install, and this guide installs it from source rather than pretending the header alone is enough.

The install follows the liburing README, with one change: no sudo. The source is cloned from the axboe/liburing repository, configured with a user prefix, and built and installed into that prefix:

Command
git clone --depth 1 https://github.com/axboe/liburing.git
cd liburing
./configure --prefix=$HOME/.local
make && make install

That puts headers in ~/.local/include, the static archive in ~/.local/lib/liburing.a, and the shared library in ~/.local/lib/liburing.so.2. The installed version is liburing 2.16, confirmed by the program itself at run time. The README notes that liburing is not tied to a specific kernel release, so the newest library works on older kernels, with newer features available only on more recent kernels. Nothing here depends on a newer feature: the probe uses queue setup, one read submission, and one completion wait.

The compile line links the static archive directly, and the reason is one of the two fixes below:

Command
g++ -std=c++20 -Wall -Wextra -I$HOME/.local/include probe.cpp \
  $HOME/.local/lib/liburing.a -o probe

The program compiles with zero warnings under -Wall -Wextra on g++ 13.3.0.

The program

The full program:

C++
// Minimal C++20 coroutine co_await io_uring read probe.
// No coroutine library: hand-rolled Task + ReadAwaitable; the event loop
// resumes the awaiting coroutine from the CQE user_data pointer.
#include <liburing.h>
#include <coroutine>
#include <cstdio>
#include <cstring>
#include <exception>
#include <fcntl.h>
#include <unistd.h>

struct Task {
  struct promise_type {
    Task get_return_object() {
      return Task{std::coroutine_handle<promise_type>::from_promise(*this)};
    }
    std::suspend_never initial_suspend() noexcept { return {}; }
    std::suspend_always final_suspend() noexcept { return {}; }
    void return_void() {}
    void unhandled_exception() { std::terminate(); }
  };
  std::coroutine_handle<promise_type> h;
  explicit Task(std::coroutine_handle<promise_type> h_) : h(h_) {}
  ~Task() { if (h) h.destroy(); }
};

struct IoUringCtx {
  io_uring ring;
  bool init_ok = false;
  int init() { return io_uring_queue_init(8, &ring, 0); }
  ~IoUringCtx() { if (init_ok) io_uring_queue_exit(&ring); }
};

struct ReadAwaitable {
  IoUringCtx& ctx;
  int fd;
  void* buf;
  unsigned nbytes;
  off_t off;
  int res = -1;
  std::coroutine_handle<> waiter{};
  bool await_ready() const noexcept { return false; }
  void await_suspend(std::coroutine_handle<> h) {
    waiter = h;
    io_uring_sqe* sqe = io_uring_get_sqe(&ctx.ring);
    io_uring_prep_read(sqe, fd, buf, nbytes, off);
    io_uring_sqe_set_data(sqe, this);
    io_uring_submit(&ctx.ring);
  }
  int await_resume() noexcept { return res; }
};

int main() {
  printf("liburing version %d.%d\n", io_uring_major_version(),
         io_uring_minor_version());
  IoUringCtx ctx;
  int rc = ctx.init();
  printf("io_uring_queue_init rc=%d\n", rc);
  if (rc != 0) {
    printf("SETUP_FAILED rc=%d\n", rc);
    return 2;
  }
  ctx.init_ok = true;
  const char* path = "/home/user/iouring-probe-2026-11-08/input.txt";
  int fd = open(path, O_RDONLY);
  if (fd < 0) {
    perror("open input.txt");
    return 3;
  }
  char buf[64];
  memset(buf, 0, sizeof(buf));
  bool done = false;
  int got = -1;
  auto run = [&]() -> Task {
    ReadAwaitable aw{ctx, fd, buf, sizeof(buf) - 1, 0};
    got = co_await aw;
    done = true;
  };
  Task t = run();
  int pumps = 0;
  while (!done) {
    io_uring_cqe* cqe = nullptr;
    int w = io_uring_wait_cqe(&ctx.ring, &cqe);
    if (w != 0) {
      printf("wait_cqe rc=%d\n", w);
      return 4;
    }
    auto* aw = static_cast<ReadAwaitable*>(io_uring_cqe_get_data(cqe));
    aw->res = cqe->res;
    std::coroutine_handle<> h = aw->waiter;
    io_uring_cqe_seen(&ctx.ring, cqe);
    ++pumps;
    h.resume();
  }
  printf("pumps=%d read res=%d buf=[%s]\n", pumps, got, buf);
  const char* expect = "io_uring coroutine probe 0123456789\n";
  printf("content_match=%d expected_len=%zu\n",
         strcmp(buf, expect) == 0, strlen(expect));
  printf("PROBE_OK\n");
  close(fd);
  return 0;
}

How the pieces fit

The Task type is the coroutine return type, and it is the minimum the C++20 framework requires. Its promise type starts eagerly, with initial_suspend returning std::suspend_never, so the coroutine body runs as soon as the lambda is called. Its final_suspend returns std::suspend_always, so the coroutine stays suspended at the end instead of destroying itself, and the Task destructor destroys the coroutine state through the handle. An uncaught exception calls std::terminate through unhandled_exception, which is the blunt option; a real program would carry the exception out through the promise instead.

The ReadAwaitable is where the coroutine meets io_uring. Its await_ready returns false unconditionally, so co_await always suspends. Its await_suspend takes the coroutine handle, stores it, prepares a read submission queue entry with io_uring_prep_read, attaches the awaitable itself as the entry's user data with io_uring_sqe_set_data, and submits. Its await_resume returns the result the event loop filled in, which is the completion queue entry's res field: the number of bytes read, or a negative error code.

The event loop in main is a plain blocking wait. It calls io_uring_wait_cqe, pulls the awaitable back out of the completion entry with io_uring_cqe_get_data, copies cqe->res into the awaitable, marks the entry seen, and resumes the stored coroutine handle. The coroutine then assigns the result, sets done, and returns. The loop runs exactly once for this program: one submission, one completion, one resume.

Two design points matter for anyone extending this. First, the awaitable outlives the suspension: it is a local inside the coroutine body, and the coroutine state keeps it alive across the suspend point, so storing this as the submission's user data is safe for the lifetime of the read. Second, the handle is resumed only after io_uring_cqe_seen, so the completion entry is released before the coroutine runs again; resuming first and marking seen second would leave the entry borrowed while the coroutine could submit more work.

The two fixes

The probe needed two fixes before it ran, and both are recorded here because a guide that hides its build failures teaches the wrong lesson.

The first fix is a missing include. The promise type calls std::terminate in unhandled_exception, and std::terminate lives in <exception>. Without that include the compile fails. The fix is one line: #include <exception>. The headers the program needs are <liburing.h>, <coroutine>, <cstdio>, <cstring>, <exception>, <fcntl.h>, and <unistd.h>.

The second fix is the link. The first attempt linked the shared library dynamically, and the program compiled but failed at load time: liburing.so.2: cannot open shared object file. The library lives in ~/.local/lib, which is not on the default loader search path, and no LD_LIBRARY_PATH was set. The fix used here is to link the static archive directly, $HOME/.local/lib/liburing.a, which removes the loader from the picture entirely. The alternative fix, adding ~/.local/lib to the loader path, would work too, but it is a machine setting the program then depends on silently, and the static link keeps the binary self contained.

What the run prints

Output
g++ (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0
COMPILE_RC=0
liburing version 2.16
io_uring_queue_init rc=0
pumps=1 read res=36 buf=[io_uring coroutine probe 0123456789
]
content_match=1 expected_len=36
PROBE_OK
RUN_RC=0

Reading it line by line: the compiler is GCC 13.3.0, the compile succeeds with return code 0, liburing reports version 2.16, the ring initializes with return code 0, so io_uring works under WSL2 kernel 6.18.33.2 with no seccomp block. The event loop pumps exactly once, the read returns 36, which is the full length of the 36 byte input file, and the buffer content matches the expected string byte for byte. The program exits with return code 0.

What the output does not claim matters as much as what it does. There is no timing here, so there is no throughput claim, no latency claim, and no comparison against a synchronous read. One 36 byte read cannot support any of those, and this guide makes none of them. The claim is narrower and fully supported: a hand-rolled C++20 coroutine can submit an io_uring read through liburing and be resumed from the completion queue, on stock GCC 13, with the library built from source.

What the nearest pages do not give you

The C level of io_uring is well served. The unixism tutorial, Lord of the io_uring, teaches the ring, the submission and completion queues, and the C API in full, and it is the right first read for the mechanism itself. It does not touch C++ coroutines. The cppreference coroutines page teaches the framework, the promise type, and the suspension rules, and its example is a network echo server sketched with a library async type, not a hand-rolled awaitable driving io_uring.

The C++ coroutine plus io_uring combination exists in three forms, and none of them is this guide. A Hacker News thread points to the CM4all libcommon library, where a coroutine reads a file through io_uring with library types like CoReadTextFile; that is library code to read, not a guide to build from. A 2022 academic slide deck combines coroutines, io_uring, and eBPF into a high level interface, with evaluation on a 2014 era processor; that is a research prototype, not a minimal executed example. A deepwiki learning path walks a coroutine echo server over the network, step by step from raw syscalls; that is a server tutorial, not a minimal file read, and its file I/O examples use C, not coroutines.

What was missing, and what this guide supplies, is the minimal case with nothing else attached: one coroutine, one read, one resume, hand-rolled types, stock GCC 13, liburing built from source, executed twice on two nights with identical output.

What this guide does not cover

The scope is one read of 36 bytes. A program that reads large files, reads many files, or pipelines reads would need a different awaitable: one that handles short reads, tracks offsets, reuses buffers, and probably submits in batches. None of that is measured here, and none of it is claimed.

The event loop blocks in io_uring_wait_cqe. It waits for one completion at a time and resumes one coroutine. A loop that serves many coroutines would need a completion queue drain, a ready queue, and a way to schedule the resumed coroutines instead of resuming inline. That is a scheduler, and this guide does not build one.

The scope is WSL2 only: kernel 6.18.33.2-microsoft-standard, Ubuntu 24.04.4, GCC 13.3.0, liburing 2.16 built from source. A bare-metal kernel or a distribution that ships liburing as a package would change the install step and might change nothing else, but that is untested here.

The guide also does not re-teach the coroutine machinery itself. The companion guide builds a generator from scratch with a promise type, a Task, and a Generator, then replaces it with C++23 std::generator and pipes it through ranges views, with the real compiler results on GCC 13, GCC 14, and Clang 18. The companion pitfalls guide covers the failure modes of hand-rolled coroutines. This guide assumes that machinery and adds only the io_uring awaitable and the event loop.

Checklist

  • Before assuming liburing is installed, check for the header: this box had the kernel header but no /usr/include/liburing.h, no pkg-config entry, and no library in the linker cache, so the library had to be built from source.
  • Before linking dynamically against a library in ~/.local/lib, remember the loader: the dynamic link compiled and then failed at load time, and linking the static archive directly removed the loader from the picture.
  • Before calling std::terminate in a promise type, include <exception>: the first compile failed on the missing include, and the fix is one line.
  • Before claiming a coroutine read works, check the completion result: this read returned 36, the full file length, and the buffer matched the expected string byte for byte, which is the only verification that matters for one read.
  • Before presenting one read as a design, remember its size: one pump, one completion, 36 bytes, no timing, so no throughput claim, no latency claim, and no comparison against a synchronous read follows from it.
  • Before extending the awaitable, handle the short read: a real read can return fewer bytes than requested, and this awaitable returns whatever res holds with no retry, so a larger file needs offset tracking and a loop.
  • Before resuming a coroutine from a completion, mark the entry seen first: this loop calls io_uring_cqe_seen before resuming the handle, so the entry is released before the coroutine can submit more work.

Sources

Keep Exploring