
Linux I/O performance is critical for high-scale network services. Traditional epoll-based asynchronous I/O, while efficient, still incurs significant overhead due to repeated syscalls and data copying between kernel and user space. io_uring, introduced in Linux kernel 5.1, fundamentally re-architects this by providing a powerful asynchronous I/O interface that minimizes syscalls and enables zero-copy operations. This guide details leveraging io_uring with Rust, specifically integrating it with tokio for high-throughput, zero-copy networking.
io_uring Paradigm Shiftio_uring operates on a shared ring buffer mechanism between user space and the kernel. Instead of issuing individual syscalls for each I/O operation, applications enqueue Submission Queue Entries (SQEs) into a Submission Queue (SQ). The kernel then processes these SQEs asynchronously, placing Completion Queue Entries (CQEs) into a Completion Queue (CQ) when operations complete. This batching significantly reduces context switches and syscall overhead.
Key io_uring features:
io_uring_enter syscall.io_uring_enter in some cases, further reducing latency.IORING_OP_SENDMSG and IORING_OP_RECVMSG can directly operate on user-space buffers, avoiding data copies.io_uring allows the kernel to optimize access and avoid repeated lookups.epoll vs. io_uring: Architectural Comparison| Feature | epoll (Standard Tokio) | io_uring (tokio-uring) |
|---|---|---|
| I/O Model | Edge-triggered, event-driven | Asynchronous, ring-buffer |
| Syscall Overhead | High (1 syscall per op + epoll_wait) | Low (batching, io_uring_enter for many ops) |
| Data Copy | User-kernel copy for read/write | Zero-copy possible (MSG_ZEROCOPY) |
| Buffer Management | User-managed, passed per-syscall | Kernel-registered fixed buffers |
| File Descriptors | Passed per-syscall | Kernel-registered fixed files |
| Latency | Higher due to syscalls/copies | Lower due to batching/zero-copy |
| Throughput | Good for many connections, limited by syscalls | Excellent for high-volume I/O |
| Kernel Version | Linux 2.5.44+ | Linux 5.1+ |
| Complexity | Simpler API | More complex API, higher learning curve |
tokio-uringWhile direct io_uring bindings exist (e.g., io-uring crate), integrating io_uring with an existing async runtime like tokio is often desirable. The tokio-uring crate provides a tokio-compatible runtime built on io_uring. It offers io_uring-backed equivalents for common tokio I/O primitives like TcpStream, UdpSocket, and file I/O.
tokio-uringAdd the following to your Cargo.toml:
[dependencies]
tokio-uring = { version = "0.6", features = ["net", "fs"] }
bytes = "1.4"
log = "0.4"
env_logger = "0.10"
The net feature enables TcpStream, UdpSocket, etc., while fs enables file I/O.
tokio-uring TCP Echo ServerThis example demonstrates a simple TCP echo server using tokio-uring. Note the tokio_uring::start() macro, which initializes the io_uring runtime.
use tokio_uring::net::{TcpListener, TcpStream};
use tokio_uring::buf::IoBuf;
use bytes::{BytesMut, BufMut};
use log::{info, error};
const BUFFER_SIZE: usize = 4096;
#[tokio_uring::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
env_logger::init();
let addr = "127.0.0.1:8080";
let listener = TcpListener::bind(addr).await?;
info!("Listening on {}", addr);
loop {
match listener.accept().await {
Ok((socket, peer_addr)) => {
info!("Accepted connection from {}", peer_addr);
tokio_uring::spawn(async move {
if let Err(e) = handle_connection(socket).await {
error!("Error handling connection from {}: {}", peer_addr, e);
}
});
}
Err(e) => {
error!("Error accepting connection: {}", e);
}
}
}
}
async fn handle_connection(mut socket: TcpStream) -> Result<(), Box<dyn std::error::Error>> {
let mut buf = BytesMut::with_capacity(BUFFER_SIZE);
loop {
// Prepare a buffer for receiving data.
// `bytes::BytesMut` implements `IoBuf`, making it suitable for `tokio-uring`.
let (res, filled_buf) = socket.recv(buf.split_off(0).limit(BUFFER_SIZE)).await;
let bytes_read = res?;
if bytes_read == 0 {
info!("Client disconnected.");
break; // Client disconnected
}
// Advance the buffer to reflect the bytes read.
// `filled_buf` is the original buffer, but its `IoBuf` trait implementation
// ensures it's correctly sliced for the `recv` operation.
// We need to manually advance the `BytesMut` to reflect the data.
buf.unsplit(filled_buf);
buf.advance_mut(bytes_read);
info!("Received {} bytes: {:?}", bytes_read, &buf[..bytes_read]);
// Send the received data back.
// `send` takes an `IoBuf` and returns the buffer back after completion.
let (res, _) = socket.send(buf.split_to(bytes_read)).await;
let bytes_written = res?;
info!("Sent {} bytes.", bytes_written);
if bytes_written == 0 {
info!("Failed to send data, client likely disconnected.");
break;
}
}
Ok(())
}
To test this, you can use netcat: nc 127.0.0.1 8080. Type some text and press enter; the server will echo it back.
MSG_ZEROCOPYThe true power of io_uring for networking lies in its ability to perform zero-copy operations. This is achieved using the IORING_OP_SENDMSG operation with the MSG_ZEROCOPY flag. When this flag is set, the kernel maps the user-space buffer directly into its own memory space for transmission, avoiding the traditional copy_from_user syscall. The application is notified via a CQE when the buffer is safe to reuse (i.e., the data has been transmitted or queued for transmission).
tokio-uring exposes this functionality through its send_zc method on TcpStream.
This example demonstrates a server that receives data and then sends a fixed response using zero-copy. The key is to manage the buffer lifecycle carefully.
use tokio_uring::net::{TcpListener, TcpStream};
use tokio_uring::buf::IoBuf;
use bytes::{BytesMut, BufMut};
use log::{info, error};
use std::sync::Arc;
const BUFFER_SIZE: usize = 4096;
const RESPONSE_DATA: &[u8] = b"HTTP/1.1 200 OK\r\nContent-Length: 12\r\n\r\nHello, World!";
#[tokio_uring::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
env_logger::init();
let addr = "127.0.0.1:8080";
let listener = TcpListener::bind(addr).await?;
info!("Listening on {}", addr);
loop {
match listener.accept().await {
Ok((socket, peer_addr)) => {
info!("Accepted connection from {}", peer_addr);
tokio_uring::spawn(async move {
if let Err(e) = handle_zero_copy_connection(socket).await {
error!("Error handling zero-copy connection from {}: {}", peer_addr, e);
}
});
}
Err(e) => {
error!("Error accepting connection: {}", e);
}
}
}
}
async fn handle_zero_copy_connection(mut socket: TcpStream) -> Result<(), Box<dyn std::error::Error>> {
let mut recv_buf = BytesMut::with_capacity(BUFFER_SIZE);
let send_buf = Arc::new(BytesMut::from(RESPONSE_DATA)); // Use Arc for shared buffer for zero-copy send
loop {
// Receive data (standard copy, as MSG_ZEROCOPY is for send)
let (res, filled_buf) = socket.recv(recv_buf.split_off(0).limit(BUFFER_SIZE)).await;
let bytes_read = res?;
if bytes_read == 0 {
info!("Client disconnected.");
break;
}
recv_buf.unsplit(filled_buf);
recv_buf.advance_mut(bytes_read);
info!("Received {} bytes from client.", bytes_read);
// Perform zero-copy send
// `send_zc` returns a future that completes when the kernel is done with the buffer.
// The buffer is returned, allowing reuse.
let (res, returned_buf) = socket.send_zc(send_buf.clone().slice(..)).await;
let bytes_written = res?;
info!("Zero-copy sent {} bytes.", bytes_written);
if bytes_written == 0 {
info!("Failed to zero-copy send data, client likely disconnected.");
break;
}
// Clear the receive buffer for the next read
recv_buf.clear();
}
Ok(())
}
To test this, you can use curl: curl http://127.0.0.1:8080. You should receive "Hello, World!".
send_zc must remain valid and unchanged until the send_zc future completes. tokio-uring handles this by returning the buffer, ensuring it's not dropped prematurely. For shared, static data, Arc<BytesMut> or Arc<[u8]> is suitable.MSG_ZEROCOPY requires Linux kernel 5.2 or newer.MSG_ZEROCOPY fails (e.g., due to insufficient kernel memory or older kernel), send_zc will return an error. A fallback to standard send might be necessary in production environments.io_uring using IORING_REGISTER_BUFFERS. tokio-uring provides tokio_uring::buf::BoundedBuf and tokio_uring::buf::FixedBuf for this.Benchmarking io_uring for 100k concurrent WebSocket connections requires a robust setup. We'll outline the approach and expected results rather than providing a full benchmark client/server, which would be extensive.
A tokio-uring based WebSocket server would involve:
tokio_uring::net::TcpListener: Accepting new connections.httparse or similar.tokio_uring::net::TcpStream::recv: For receiving WebSocket frames.tokio_uring::net::TcpStream::send_zc: For sending WebSocket frames, especially for broadcast messages or large data. This is where zero-copy shines.A benchmark client needs to:
ulimit -n).With io_uring and zero-copy, for a server sending frequent, identical messages (e.g., market data, game state updates) to many clients, we expect:
io_uring features.ulimit -n: Set to a value > 100,000 (e.g., ulimit -n 1048576).sysctl parameters like net.core.somaxconn, net.ipv4.tcp_max_syn_backlog, net.ipv4.tcp_tw_reuse, net.ipv4.tcp_fin_timeout.io_uring Not Available/Enabled:
io_uring operations fail with ENOSYS or similar errors.io_uring module not loaded/compiled.CONFIG_IO_URING=y in kernel config.ulimit -n Too Low:
Too many open files error when accepting connections or creating sockets.ulimit -n for the user running the application. For systemd services, set LimitNOFILE in the service unit file.MSG_ZEROCOPY Failures:
send_zc returns EOPNOTSUPP or other errors.TcpStream::send if send_zc fails.send_zc completes and returns it.tokio-uring's send_zc returns the buffer, indicating it's safe to reuse. For shared static data, use Arc and slice to ensure immutability during kernel processing.io_uring Polling:
io_uring worker threads consume 100% CPU even with low load.IORING_SETUP_SQPOLL (kernel polling) can be aggressive. If not configured correctly, it might spin-wait.io_uring is configured appropriately for your workload. tokio-uring generally manages this, but if you're using raw io-uring, be mindful of polling flags. For most server workloads, event-driven (non-polling) io_uring is sufficient, with polling reserved for ultra-low-latency scenarios.A high-performance network service is experiencing significant CPU overhead due to frequent context switches and data copying between user and kernel space during I/O operations. The service is deployed on a modern Linux environment (kernel 5.1+). Which of the following architectural changes would most effectively address these issues for high-throughput networking?
tokio-uring with existing tokio code?
Yes, tokio-uring provides a tokio-compatible runtime. You can use tokio_uring::spawn to run io_uring-backed futures alongside regular tokio::spawn futures, though it's generally recommended to keep io_uring specific I/O on the tokio-uring runtime for optimal performance.io_uring over epoll for networking?
The primary benefits are reduced syscall overhead through batching, and the ability to perform zero-copy data transfers between user space and the kernel. This leads to lower CPU utilization, higher throughput, and lower latency, especially for high-volume I/O operations.io_uring always faster than epoll?
Not always. For low-concurrency, low-throughput applications, the overhead of setting up io_uring might outweigh its benefits. io_uring shines in scenarios with high concurrency, high I/O volume, or when zero-copy is critical. It also requires a modern Linux kernel.tokio-uring handle buffer management for zero-copy?
tokio-uring's send_zc method takes an IoBuf (like BytesMut or Arc<[u8]>) and returns it once the kernel has finished with the buffer. This ensures the buffer's lifetime is correctly managed, preventing use-after-free issues. For static data, Arc is used to share ownership.io_uring and MSG_ZEROCOPY?
io_uring requires Linux kernel 5.1 or newer. MSG_ZEROCOPY specifically requires Linux kernel 5.2 or newer. For production, kernel 5.10 (LTS) or a recent 6.x kernel is recommended for stability and feature completeness.io_uring represents a significant advancement in Linux asynchronous I/O, offering unparalleled performance for high-throughput applications. Rust, with its strong type system and performance characteristics, is an ideal language to leverage io_uring's capabilities. The tokio-uring crate provides a robust and ergonomic way to integrate io_uring into tokio-based applications, enabling developers to build highly efficient network services with features like zero-copy data transfer. While the learning curve for io_uring can be steeper than traditional epoll, the performance gains for demanding workloads are substantial and warrant the investment.
Clean AI CLI logs, build cron expressions, decode JWTs, and calculate chmod permissions offline.

Setting up high-throughput WireGuard mesh VPNs on Linux kernel: MTU tuning, keepalive dynamics, asymmetric routing, and firewall rules.
Read more
Writing and verifying zero-knowledge proofs with Circom and Rust: arithmetic circuit compilation, Groth16 witness generation, and on-chain verification.
Read more
Building high-throughput REST microservices in Rust with Axum: Tower middleware, extractor patterns, connection pooling, and graceful shutdown.
Read more