HttpClient.IoUring 1.0.0

HttpClient.IoUring

A high-performance io_uring transport for SocketsHttpHandler that replaces the default socket I/O with Linux's io_uring interface. Up to 69% faster throughput on Linux.

Performance

On a 2-core VM (AMD EPYC 9V74, Linux 6.17, .NET 10):

See BENCHMARKS.md for detailed methodology.

Features

• Drop-in replacement — one UseIoUring() call replaces the socket transport
• Batched syscalls — a single io_uring_enter submits CONNECT + SEND + RECV across all connections
• Zero-copy send (SEND_ZC) for payloads >4KB — avoids kernel buffer copy
• Registered file descriptors (IOSQE_FIXED_FILE) — kernel skips fd lookup per SQE
• Async connect via IORING_OP_CONNECT — fully non-blocking connection establishment
• Full SocketsHttpHandler features — HTTP/1.1, HTTP/2, HTTP/3, TLS, connection pooling, redirects, decompression — all work automatically
• Targets net8.0, net9.0, net10.0

Requirements

• Linux with kernel 5.1+ (for io_uring support)
• Kernel 6.0+ recommended (for zero-copy send, buffer rings)
• .NET 8 or later

Installation

dotnet add package HttpClient.IoUring

Quick Start

using HttpClient.IoUring.Extensions;

var handler = new SocketsHttpHandler();
using var transport = handler.UseIoUring(options =>
{
    options.RingSize = 256;
});

using var client = new HttpClient(handler);
var response = await client.GetAsync("https://api.example.com/data");

Factory Method

using var handler = IoUringTransport.CreateHandler(options =>
{
    options.RingSize = 256;
});
using var client = new HttpClient(handler);

Architecture

┌─────────────────────────────────────────────────────────────┐
│  HttpClient                                                  │
│   new HttpClient(handler)                                    │
│         │                                                    │
│   SocketsHttpHandler (HTTP/1.1+2+3, pooling, TLS, etc.)     │
│    └── ConnectCallback = IoUringTransport.ConnectAsync        │
│              │                                                │
│         IoUringTransport                                     │
│          ├── IoUringConnector (IORING_OP_CONNECT + DNS)      │
│          ├── IoUringStream (RECV/SEND via io_uring)           │
│          └── IoUringClientLoop (shared Ring, IO thread)       │
│               └── Ring → SQ/CQ → io_uring_enter              │
└─────────────────────────────────────────────────────────────┘

How it works

All IoUringStream instances share a single io_uring Ring. When multiple connections read/write concurrently, their SQEs are batched into a single io_uring_enter syscall:

Thread A: conn1.ReadAsync()  → enqueue RECV SQE
Thread B: conn2.WriteAsync() → enqueue SEND SQE
Thread C: conn3.Connect()    → enqueue CONNECT SQE
                                    │
IO Thread: io_uring_enter(3 SQEs) ←─┘  ← one syscall for 3 operations

Configuration

io_uring Features Used

Project Structure

├── src/HttpClient.IoUring/         ← NuGet library (net8.0/net9.0/net10.0)
├── tests/HttpClient.IoUring.Tests/ ← xunit tests
├── benchmarks/                      ← BenchmarkDotNet comparisons
└── samples/SampleApp/               ← Minimal usage example

License

MIT