A collection of low-level C building blocks for event-driven, asynchronous programming on macOS and Linux (Windows is on the roadmap but not a near-term priority).
- Designed and reviewed by Leo X.
- Coded by Codebuddy VSCode plugin with claude-4.6-opus
| Module | Description |
|---|---|
| xbase | Core primitives — event loop, timers, tasks, async sockets, memory, lock-free data structures |
| xbuf | Buffer primitives — linear, ring, and block-chain I/O buffers |
| xnet | Networking primitives — URL parser, async DNS resolver, shared TLS configuration types |
| xhttp | Async HTTP client & server — libcurl multi-socket client with SSE streaming, HTTP/1.1 (llhttp) & HTTP/2 (nghttp2) async server with TLS (OpenSSL / MbedTLS) and parameterized routing, WebSocket server & client (RFC 6455) |
| xlog | Async logging — MPSC queue, timer/pipe flush, log rotation |
📖 See the full documentation for detailed design, architecture diagrams, API references, and usage examples.
| Dependency | Required | Notes |
|---|---|---|
| CMake ≥ 3.14 | ✅ | Build system |
| C99 compiler | ✅ | GCC or Clang |
| GoogleTest | For tests | libgtest-dev (apt) / googletest (brew) |
| libcurl | ✅ | Enables the xhttp client |
| llhttp | ✅ | HTTP/1.1 parsing for xhttp server — libllhttp-dev (apt) / llhttp (brew) |
| nghttp2 | ✅ | HTTP/2 support for xhttp server — libnghttp2-dev (apt) / nghttp2 (brew) |
| OpenSSL | ✅ pick one | TLS backend for xhttp — libssl-dev (apt) / openssl (brew) |
| MbedTLS | ✅ pick one | TLS backend for xhttp — libmbedtls-dev (apt) / mbedtls (brew) |
| libunwind | Optional | Better backtraces on Linux |
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallelTo skip tests:
cmake -S . -B build -DXK_BUILD_TESTS=OFFctest --test-dir build --output-on-failure --parallel 4The xhttp module supports two TLS backends. Use XK_TLS_BACKEND to choose one at configure time:
| Backend | Value | Extra dependency |
|---|---|---|
| OpenSSL | openssl |
libssl-dev (apt) / openssl (brew) |
| MbedTLS | mbedtls |
libmbedtls-dev (apt) / mbedtls (brew) |
OpenSSL (default when available):
cmake -S . -B build-openssl -DCMAKE_BUILD_TYPE=Debug -DXK_TLS_BACKEND=openssl
cmake --build build-openssl --parallel
ctest --test-dir build-openssl --output-on-failure --parallel 4MbedTLS:
cmake -S . -B build-mbedtls -DCMAKE_BUILD_TYPE=Debug -DXK_TLS_BACKEND=mbedtls
cmake --build build-mbedtls --parallel
ctest --test-dir build-mbedtls --output-on-failure --parallel 4Tip: To test both backends in one go, simply run the above commands sequentially with separate build directories.
The xhttp/https_test.cpp suite tests the client and server TLS integration end-to-end. It generates self-signed certificates at test time (requires openssl CLI) and covers:
- HTTPS GET / POST / Do with
skip_verify - Custom CA path verification
- Self-signed certificate rejection (verify enabled)
- Wrong CA path failure
- Mutual TLS (mTLS) with client certificates
- mTLS failure when client cert is missing
- Concurrent HTTPS requests
- Request timeout over HTTPS
- TLS config reset between requests
- Destroy client with in-flight HTTPS request
These tests run automatically with ctest when XK_TLS_BACKEND=openssl is set.
Requires macOS 26+ with Apple Containerization:
brew install container
container system start
./scripts/test-linux.sh # default: gcc:14, Debug, -j2
./scripts/test-linux.sh -j4 -m 4G # custom parallelism and memoryAll benchmarks run on Apple M3 Pro (12 cores, 36 GB), macOS 26.4, Clang 17, Release (-O2).
| Category | Highlight |
|---|---|
| MPSC Queue | 94.4 M ops/s single-producer; 68–70 M ops/s multi-producer |
| RingBuffer | 73.3 GiB/s write+read (4 KiB chunks) |
| IOBuffer | 44.8 GiB/s append (4 KiB), zero-copy cut at 26.1 GiB/s |
| HTTP/1.1 Server | 152 K req/s single-threaded, +15–60% faster than Go net/http |
| HTTP/2 Server | 576 K req/s single-threaded h2c, +15–405% faster than Go net/http + x/net/http2 |
| HTTPS Server | 512 K req/s HTTPS/2, TLS-bound parity on HTTPS/1.1, +209–278% on HTTPS/2 |
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DXK_BUILD_BENCHMARKS=ON
cmake --build build --parallel
./scripts/run_micro_bench.sh- Micro-benchmarks — detailed tables are in each module's documentation: mpsc.h · event.h · timer.h · heap.h · memory.h · buf.h · ring.h · io.h
- End-to-end — HTTP/1.1 Server Benchmark · HTTP/2 Server Benchmark · HTTPS Server Benchmark (xKit vs Go)
MIT © 2025-present Leo X. and xKit contributors