iouringd

iouringd is a small Unix-socket daemon that exposes bounded async I/O over Linux io_uring. It is usable as a standalone runtime kit and as a constrained service inside a larger host-local job platform.

The daemon provides:

• feature probing for io_uring_setup, probed op support, queue sizing, registered files, and registered buffers
• a stable handshake plus submission/completion wire protocol
• bounded client admission and per-client credits
• registered file and registered buffer support where the kernel allows them
• trace and metrics output over the control socket, plus optional structured stderr logs with --trace-stderr
• clear startup failures when io_uring is unavailable or blocked by policy

Build

cmake -S . -B build
cmake --build build -j4
python3 ./tests/run_tests.py

The test runner expects binaries under build/tests/ and the daemon at build/bin/iouringd.

Run

./build/bin/iouringd /tmp/iouringd.sock

Supported daemon arguments:

iouringd [--ring-entries N] [--max-clients N] \
  [--registered-fds N] [--registered-buffers N] \
  [--per-client-credits N] [--io-bytes-max N] \
  [--job-id N] [--trace-stderr] SOCKET_PATH

Every numeric argument is bounded by a compile-time ceiling and the daemon refuses to start outside it, naming the flag and the accepted range:

Flag	Range
--ring-entries	2 - 64
--max-clients	1 - 64
--registered-fds	1 - 32
--registered-buffers	1 - 4
--per-client-credits	1 - 64
--io-bytes-max	1 - 4096

--io-bytes-max caps a single transfer, so 4096 is the largest read or write one request can carry.

--job-id is numeric. --job-id annotates stderr trace and metrics records for correlation with cgroupd or another orchestrator. --trace-stderr emits structured trace and metrics lines to stderr in addition to the socket protocol trace stream.

Documents

• Wire Protocol
• Platform Integration

Examples

• Minimal client
• Per-job launch recipe
• Sealed memfd to overlay workspace copy

Failure Modes

If io_uring startup fails, the daemon exits with code 1 and emits a clear stderr message:

• unsupported kernel: io_uring setup is unavailable on this kernel (ENOSYS)
• blocked by policy: io_uring setup blocked by kernel policy or sandbox
• probe yielded no supported operations: io_uring probe reported no supported operations

That behavior is covered by the integration tests.