io_uring is a Linux application programming interface for submitting operations to the kernel and receiving their results asynchronously. Introduced in Linux 5.1 in 2019, it uses queues shared between an application and the kernel to support efficient submission, batching, and completion handling. Originally developed around storage input/output, it also supports networking, timers, polling, and other operations. Its defining feature is a completion-oriented interface: applications submit requests and later retrieve results, rather than necessarily waiting for each operation to finish before continuing.
Background and purpose
Conventional synchronous I/O often requires a system call for each operation, with the calling thread potentially blocked until the operation completes. Applications can use nonblocking operations, readiness notification, or worker threads to overlap I/O with other work, but these approaches introduce their own coordination costs.
Linux already provided an asynchronous I/O interface, commonly called native AIO, before io_uring. That interface had restrictions that made it less suitable as a general-purpose asynchronous facility, particularly outside direct storage I/O. Readiness interfaces such as epoll serve a different purpose: they report that an operation may be possible without blocking, after which the application performs the operation itself.
io_uring was designed to provide a more general completion-based interface while reducing repeated transfers of control between user space and the kernel. Jens Axboe led its initial development. Its supported operations and execution modes have expanded substantially since the initial release.
“Asynchronous” describes the application-facing contract, not a guarantee that every underlying operation is executed by specialized asynchronous hardware. A request may finish immediately, proceed through an asynchronous kernel path, or be delegated to a kernel worker.
Shared-ring architecture
An io_uring instance provides a submission queue (SQ) and a completion queue (CQ), together with memory containing submission queue entries. The application maps these structures into its address space, allowing communication through shared memory rather than passing a separate request structure through a system call for every operation.
Submission
A submission queue entry (SQE) describes a request. Depending on the operation, it can contain:
- An operation code, such as a read, write, accept, or timeout.
- A file descriptor or registered-file reference.
- A buffer address and length.
- A file offset or operation-specific parameters.
- Flags controlling execution and dependencies.
- An application-defined
user_datavalue.
In the conventional layout, the submission ring contains indices identifying SQEs in a separate array. Newer configurations can alter aspects of this layout, so applications must follow the interface negotiated during setup rather than assume one universal representation.
The application prepares entries and publishes them by advancing the submission queue’s tail. The kernel consumes submitted entries and advances its head.
Completion
A completion queue entry (CQE) reports the outcome of an operation. Its standard fields include:
user_data, allowing the application to associate the completion with its request.res, an operation-specific result.- Flags supplying additional completion information.
For many I/O operations, a nonnegative res is a byte count or another successful result, while a negative value represents a negated error number. This differs from conventional library wrappers that return -1 and set errno.
The kernel publishes completions, and the application consumes them. Completion order need not match submission order. Applications therefore normally identify requests by user_data, not by their position in the completion stream.
Memory ordering
Shared queues require explicit synchronization. Request contents must become visible before the application publishes a new tail value, and completion contents must be read only after their publication has been observed. Correct use of atomic operations and memory-ordering rules prevents either side from seeing partially initialized entries.
Sharing a ring among application threads also requires coordination. The shared-memory design does not automatically make arbitrary concurrent access safe.
System calls and the userspace library
The original core interface consists of three system calls:
| System call | Main purpose |
|---|---|
io_uring_setup |
Creates an instance and returns information needed to configure its shared mappings. |
io_uring_enter |
Submits requests, waits for completions, or performs related coordination according to its flags. |
io_uring_register |
Registers resources or configures supported ring facilities. |
Applications commonly use liburing, a userspace library providing setup functions, queue-management helpers, and operation-preparation routines. It handles many low-level details without replacing the kernel’s execution mechanisms.
The interface is closely associated with the C programming language, but language libraries and asynchronous runtimes can expose it through other programming interfaces.
Execution and resource-management features
Batching and polling
Multiple SQEs can be submitted together, and multiple CQEs can be consumed together. This amortizes coordination costs over many operations.
With submission-queue polling, enabled through IORING_SETUP_SQPOLL, a kernel thread polls for newly published submissions. While that thread is active, applications can often submit work without a submission system call. If it goes to sleep, a system call may be required to wake it.
I/O polling, associated with IORING_SETUP_IOPOLL, is a separate mechanism for polling supported storage operations for completion. It has device, filesystem, and operation constraints and is not a general polling mode for every io_uring request.
Both mechanisms can exchange lower notification latency for additional CPU consumption.
Registered resources
Applications can register file references and memory buffers for reuse. This can reduce repeated file-reference handling or memory-management work on supported paths. Registered resources have explicit lifetimes and consume kernel resources; registration does not mean every operation becomes zero-copy.
Buffer selection facilities allow the kernel to choose a buffer from an application-provided group for supported operations. These facilities are useful when the size or arrival time of incoming data is not known in advance.
Linked requests and ordering
Requests can be linked to express execution dependencies. For example, a later operation can be made dependent on completion of an earlier one. Link flags determine how failures affect subsequent requests.
Links are not transactions: they do not provide general rollback or atomicity across a sequence. An operation that has already produced an external effect is not undone merely because a later linked operation fails.
Multishot operations and cancellation
Some operations support multishot mode, in which one submission can produce several completions. A multishot accept operation, for example, can report multiple incoming connections. Completion flags indicate whether further results may follow.
Cancellation is itself an operation with race-sensitive semantics. A request may complete before cancellation takes effect, and a cancellation result does not replace the need to account for the target request’s completion.
These features mean that “one submission produces exactly one completion” is not a universal rule. Multishot requests, notification completions, and optional suppression of successful completions require more careful bookkeeping.
Networking and asynchronous programming
io_uring supports operations involving sockets, including connection establishment, acceptance, sending, and receiving, subject to kernel-version support. This allows an event loop to handle storage and network operations through a common completion mechanism.
With readiness notification, an application typically waits until a socket is readable and then calls a receive function. With io_uring, it can submit a receive request directly and process the result when a completion arrives. Readiness polling operations are also available within io_uring, so the two approaches can coexist.
The interface can underpin asynchronous programming abstractions such as futures and coroutines. Runtime implementations still need to manage request ownership, cancellation, scheduling, and the lifetime of buffers.
Selected networking operations offer zero-copy send facilities. Such facilities have specific constraints and completion semantics: notification that data has been accepted for sending is not necessarily notification that the application may reuse the original memory. io_uring as a whole should not be described as inherently zero-copy.
Performance and limitations
io_uring is particularly relevant to applications with many outstanding operations, including storage services, network servers, and database management systems. Its potential benefits include fewer system calls, efficient batching, and unified completion handling.
Performance is workload-dependent. Important factors include queue depth, request size, batching policy, storage characteristics, worker scheduling, and whether polling is enabled. Shared queues can themselves introduce cache traffic and contention.
A low-concurrency application may gain little from the interface. An operation may still block internally and require a worker, and buffer registration may add overhead without providing a benefit for a particular workload. Higher throughput also does not necessarily imply lower tail latency.
Correctness imposes additional obligations:
- Buffers and request-associated state must remain valid for the period required by the operation.
- Reads and writes can complete partially.
- Queue capacity and completion overflow behavior must be handled.
- Submission success must not be confused with successful completion.
- Dependencies and cancellation must account for operations already in flight.
The kernel interface has evolved rapidly. Applications commonly probe supported operations and feature flags at runtime; a kernel version alone may not describe all capabilities because distributions can backport changes.
Security and deployment
io_uring exposes a substantial kernel interface and has had security vulnerabilities requiring fixes. Some deployments restrict or disable it to reduce the kernel attack surface, while others rely on its functionality and performance.
Its asynchronous execution also matters for sandboxing. Filtering the system calls used to create and operate a ring is not equivalent to inspecting each operation later submitted through shared memory. Security designs must account for the operations a ring can perform, the resources it can access, and any kernel-supported ring restrictions.
Kernel configuration, system policy, resource limits, and the surrounding runtime environment can affect availability. Software that must operate across varied Linux environments may therefore provide alternative I/O backends.