kmx-aio

kmx-aio is a modern, high-performance C++26 asynchronous I/O library designed for building non-blocking network applications on Linux. It leverages C++ coroutines to provide a clean, synchronous-looking API for asynchronous operations across two execution models: readiness (epoll) and completion (io_uring).

Key Features

• Modern C++26: Built with the latest language standards.
• Coroutine-First Design: Uses co_await for intuitive, sequential async code flow without callback hell.
• Readiness + Completion Models: epoll-based readiness and io_uring-based completion APIs.
• Zero-Overhead Abstractions: Lightweight wrappers around system calls.
• Type-Safe Error Handling: Extensive use of std::expected and std::error_code for robust error management.
• TCP Networking: Built-in support for TCP listeners and streams.
• UDP Networking: Dual-layer API in both models — low-level socket wrapping recvmsg/sendmsg and high-level endpoint with span-based send/receive and automatic peer-address decoding, as readiness::udp::{socket,endpoint} and completion::udp::{socket,endpoint}.
• HTTP/2: Full codec, stream, frame, and HPACK serialization stack (no model affinity).
• TLS/ALPN: Encrypted streams (BoringSSL-backed, both models) with Application Layer Protocol Negotiation for seamless HTTP/2 handshakes.
• QUIC + HTTP/3: Full QUIC engine (both models) with lsquic backing; HTTP/3 server/client samples included.
• Async Timers: Readiness timer (timerfd + epoll) and completion timer (io_uring timeout op).
• V4L2 Async Capture (Readiness + Completion): Readiness mode uses epoll-driven frame capture; completion mode uses IORING_OP_POLL_ADD plus synchronous VIDIOC_DQBUF (hybrid model) in the same io_uring executor. Targets V4L2 streaming devices such as USB webcams, MIPI CSI-2 pipelines, and GMSL camera chains. Frames land in co_await-returned frame_view objects that auto-requeue mmap'd kernel buffers on destruction.
• Completion async_poll(fd, mask): First-class one-shot IORING_OP_POLL_ADD primitive to await arbitrary fd readiness (V4L2, eventfd, timerfd, signalfd, netlink) inside completion::executor; callers re-arm by invoking it again.
• Async Mutex: kmx::aio::async_mutex is acquired with co_await and can be held across a suspension — it parks the coroutine instead of blocking the worker thread, and hands ownership straight from the releasing holder to the first waiter in line.
• Coroutine-Frame Slab Allocator: kmx::aio::allocator::slab serves coroutine frames from a per-thread slab. Each frame carries its origin in a header, so one allocated on the executor thread and freed on another goes back to the right slab through a lock-free remote list rather than corrupting the heap.
• Thread-Pool Scheduler: kmx::aio::scheduler runs submitted callables on a fixed set of workers, with wait_until_idle() for owners that have to outlive their own queued work.
• Buffer Pool Primitives: kmx::aio::buffer::pool and kmx::aio::buffer::handle provide fixed-capacity RAII buffer leasing for deterministic zero-copy workflows.
• Channel Backpressure: kmx::aio::channel supports watermark-based producer throttling and credit reporting.
• OPC UA: Backend-neutral async client/server/subscription facade with open62541 backend support; this repository drives it through completion-executor progression, with a shim fallback for feature-off builds and tests.
• Modbus TCP and Modbus/TLS: Feature-gated readiness-model client/server facade with framing helpers, TLS/mTLS coverage, and deterministic unit/integration test harnesses.
• SOME/IP: Backend-neutral async client/server/subscription facade for AUTOSAR SOME/IP communication; vsomeip-backed when available, with an in-process stub for deterministic unit testing without a daemon.
• GPU Completion Model (CUDA): Lightweight thread-per-core gpu::executor allowing co_await on asynchronous CUDA event completions (gpu::event) submitted to CUDA streams (gpu::stream).
• AVB (Audio Video Bridging, IEEE 802.1): Shared generic raw Ethernet socket, gPTP clock synchronization, and SRP client with model-specific aliases for readiness and completion; sample-validated in both models.
• HFT Order Router Sample: Completion-sample demo using kmx::aio::channel between CPU-pinned threads to show producer throttling and synthetic order routing stats.
• AF_XDP Packet Socket: Kernel-bypass packet filtering with eBPF support and UMEM ring management.
• SPDK Block I/O: NVMe, generic bdev, and storage acceleration via DPDK.

Feature Domain Applicability Matrix

Quick reference that groups features by domain and highlights only their applicability scope.

Networking Core

Feature	Applicability domain
TCP	Client-server applications requiring reliable byte-stream transport and long-lived connections
UDP Endpoint	High-level datagram API with automatic peer address management
UDP Socket	Low-level datagram transport for custom protocols or best-effort traffic

Security and Web Protocols

Feature	Applicability domain
HTTP/2	Multiplexed application-layer services over persistent connections
HTTP/3	Modern web services over QUIC with reduced handshake/reconnect latency
QUIC Engine	Secure user-space transport with stream multiplexing and modern congestion control
TLS Stream	End-to-end encrypted channels for secure transport

Time, Device IO, and Polling

Feature	Applicability domain
Completion async_poll(fd, mask)	Unified readiness waiting for arbitrary file descriptors in completion execution
Timers	Time-based scheduling, deadlines, retry/backoff, and periodic work
V4L2 Capture	Asynchronous video capture for Linux camera devices and multimedia pipelines

Industrial and Automotive Integration

Feature	Applicability domain
AVB/IEEE 802.1	Deterministic, synchronized audio/video streaming over real-time Ethernet networks
Modbus	Industrial PLC and field-device telemetry/control over Modbus TCP and Modbus/TLS
OPC UA	Industrial interoperability for telemetry, control, and subscriptions in automation systems
SOME/IP	Service-oriented communication for AUTOSAR automotive systems

Performance and Hardware Acceleration

Feature	Applicability domain
AF_XDP Packets	Kernel-bypass packet processing for low-latency, high-throughput networking
GPU / CUDA	Asynchronous GPU offload for compute-bound and post-processing pipelines
OpenOnload	Accelerated user-space networking for latency-sensitive workloads
SPDK Block I/O	High-performance storage I/O for NVMe/bdev data-plane scenarios

Concurrency and Reference Workloads

Feature	Applicability domain
HFT Order Router	High-pressure producer-consumer flows with CPU pinning and controlled backpressure

Feature Availability Matrix

Quick reference showing which APIs are available in each execution model:

⚙ — Feature-gated (requires project.enable_*:true; off by default)

Feature	Readiness (epoll)	Completion (io_uring)	⚙	Notes
TCP	✅	✅		Listener, stream, accept, read, write
UDP Socket	✅	✅		Low-level recvmsg/sendmsg
UDP Endpoint	✅	✅		High-level span API over the socket layer; automatic peer IP/port decoding
TLS Stream	✅	✅		Generic template; BoringSSL Memory BIO
Timers	✅	✅		Readiness: timerfd + epoll; Completion: io_uring timeout ops
AF_XDP Packets	❌	✅	⚙	Kernel-bypass; eBPF filtering; UMEM ring management
AVB/IEEE 802.1	✅	✅	⚙	Shared generic stack; readiness/completion aliases; sample-validated
GPU / CUDA	❌	✅	⚙	Async CUDA event completion; thread-per-core pinning
HFT Order Router	❌	✅	⚙	Sample demo; kmx::aio::channel with CPU pinning
HTTP/2	✅	✅	⚙	Full codec + ALPN; no executor affinity
HTTP/3	✅	✅	⚙	HTTP/3 codec and message layer over QUIC
Modbus	✅	❌	⚙	Readiness-model Modbus TCP + Modbus/TLS client/server APIs
OPC UA	✅	✅	⚙	Backend-neutral facade; open62541 backend; completion-driven progression
OpenOnload	✅	❌	⚙	Zero-copy extensions; headers-only; gracefully disabled when absent
QUIC Engine	✅	✅	⚙	lsquic-backed; HTTP/3 server/client samples
SOME/IP	✅	✅	⚙	Backend-neutral facade; vsomeip or stub backend; echo server/client samples
SPDK Block I/O	❌	✅	⚙	NVMe, generic bdev; DPDK-backed
V4L2 Capture	✅	✅		No gate of its own; rides on whichever executor backend is enabled

This table says which model a feature works in. For how the two compare where both are available, kmx-aio-benchmark runs one scenario body on each executor and prints them side by side - see Benchmarking.

Documentation

• Architecture
• Core Primitives
• Readiness Model (epoll)
• Completion Model (io_uring)
• Known Limitations
• Setup and Dependencies
• Build and Feature Gates
• Testing Workflow
• Benchmarking
• Script Reference
• Static Analysis

License

Copyright © 2026 - present KMX Systems. All rights reserved.