io_uring：提交与完成模型

io_uring 通过共享提交队列 SQ 和完成队列 CQ，把请求准备、提交、执行与结果收取解耦。它允许批量摊薄开销，并统一处理多类异步操作；实际是否更快取决于工作负载、设备、队列深度和实现方式。

Linux 5.1 引入基础框架，后续不断增加操作与特性。不能因为内核版本高于 5.1，就认为所有 opcode、标志组合和文件系统路径都支持。实际应用应探测能力，并处理创建或请求失败。

SQ 与 CQ 承载的是控制信息

应用准备 SQE，填入 opcode、fd、缓冲地址、长度、偏移和 user_data 等；内核消费后执行，并通过 CQE 返回 user_data、res、flags 等结果。环形队列共享能减少控制信息往返复制，不意味着数据 payload 自动成为零拷贝。

用户与内核分别推进生产、消费索引，需要正确的内存屏障。通常通过 liburing 管理，避免自己用普通整数操作 head/tail。多个应用线程同时操作同一个 ring 时，也必须遵守库和所用模式的并发契约。io_uring(7)

四个不能混淆的结果

io_uring_wait_cqe 返回 0 时，应再检查 cqe->res；如果 res 是 -ENOENT，错误来自那次操作，不能从当前线程 errno 推断。读操作 res 为 0 通常表示 EOF，正值是实际读取字节数。wait_cqe、prep_read

一个完整的单次读取程序

保存为 uring_read.c。程序只读取指定文件从 offset 0 开始的最多 4096 字节，输出实际字节数；它不是读取整个文件的循环。初始化或等待阶段的致命错误会终止这个演示进程，长期运行服务需实现独立的取消和回收路径。

#define _GNU_SOURCE
#include <errno.h>
#include <fcntl.h>
#include <liburing.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

static void fail_uring(const char *what, int result) {
    fprintf(stderr, "%s: %s\n", what, strerror(-result));
    exit(1);
}

int main(int argc, char **argv) {
    if (argc != 2) {
        fprintf(stderr, "usage: %s FILE\n", argv[0]);
        return 2;
    }
    int fd = open(argv[1], O_RDONLY);
    if (fd == -1) { perror("open"); return 1; }

    struct io_uring ring;
    int rc = io_uring_queue_init(8, &ring, 0);
    if (rc < 0) fail_uring("queue_init", rc);

    unsigned char buffer[4096];
    struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
    if (sqe == NULL) {
        fprintf(stderr, "no SQE available\n");
        exit(1);
    }
    io_uring_prep_read(sqe, fd, buffer, sizeof buffer, 0);
    sqe->user_data = 42;

    do { rc = io_uring_submit(&ring); } while (rc == -EINTR);
    if (rc < 0) fail_uring("submit", rc);
    if (rc != 1) {
        fprintf(stderr, "expected one submitted request, got %d\n", rc);
        exit(1);
    }

    struct io_uring_cqe *cqe;
    do { rc = io_uring_wait_cqe(&ring, &cqe); } while (rc == -EINTR);
    if (rc < 0) fail_uring("wait_cqe", rc);
    int result = cqe->res;
    unsigned long long tag = cqe->user_data;
    io_uring_cqe_seen(&ring, cqe);

    int failed = result < 0 || tag != 42;
    if (result < 0) fprintf(stderr, "read: %s\n", strerror(-result));
    else printf("read=%d, user_data=%llu\n", result, tag);
    io_uring_queue_exit(&ring);
    if (close(fd) == -1) failed = 1;
    return failed;
}

cc -Wall -Wextra uring_read.c -luring -o uring_read
./uring_read input.bin

buffer 在提交后仍存活，直到该单次请求 CQE 到来。cqe_seen 之后原 CQE 槽位可被复用，所以程序先保存 res 与 user_data。标签是应用的关联键，内核不会替标签指向的对象增加引用计数。

显式文件偏移避免多个并发请求争用隐式文件位置。要完整读取文件，应根据实际返回长度调整偏移和剩余长度，并处理 EOF、错误及取消，不能把一次短读一概当作失败。

SQ 空了，buffer 就能复用吗？

先准备两个请求并提交，SQ 会清空；再准备第三个请求，此时三个 buffer 都有明确拥有者。尝试先完成 R2 再完成 R1，CQ 按完成顺序排列，关联仍靠请求 ID。模型有意等到应用收取完成后才归还 buffer，避免把空 SQ 槽位当成业务资源空闲。

完成顺序与依赖

普通独立请求可能乱序完成，不能按提交队列下标直接匹配业务对象。user_data 通常编码请求 ID、类型或对象代次，防止旧完成落到已复用对象。

需要前后依赖时，按语义使用 link、drain 等机制，但它们不是数据库事务。前一个写入已经产生的副作用，不会因为后一个请求失败就自动回滚。对写入持久性还需提交适当同步操作并观察其结果。

SQPOLL 与 IOPOLL 是两个方向

SQPOLL 让内核线程轮询提交队列。应用仍需把已准备的 SQE 发布到队列；使用 liburing 时仍调用适当的 submit 路径，不能只 get_sqe/prep 后什么也不做。轮询线程休眠并设置 NEED_WAKEUP 时，库会按需进入内核唤醒它。io_uring_submit

IOPOLL 则针对受支持 I/O 的完成轮询，依设备、文件系统和访问模式等条件。二者可以分别讨论，不能把“轮询提交”和“轮询设备完成”当同一特性。

持续轮询可能显著占用 CPU，并非固定只用某一核心的 5%–10%。DEFER_TASKRUN 是把相应工作推迟到规定的进入内核收取事件路径，需要 SINGLE_ISSUER 等约束和正确的事件推进方式；不是简单的“关中断以变快”。高级标志应逐项核对匹配版本。liburing setup 文档

注册资源：提前支付部分管理成本

注册 buffer 可在符合条件的路径中减少重复固定用户页的工作，但占用资源并有注册、注销成本。使用时还需选对应 fixed-buffer 操作与索引，注册一次不代表所有普通 read 自动享有同样路径。register_buffers

注册 files 建立 ring 的文件表，使用 IOSQE_FIXED_FILE 时 SQE 中相应值是表内索引，不是普通进程 fd。更新、注销与在途请求的关系需按接口协议处理。register_files

buffer、描述符对象和请求状态都有生命周期。不能看到提交成功就 free(buffer)，也不能因为取消请求已提交就立即复用旧 request_id。

取消与超时：还要观察原请求终结

取消操作是另一个请求，也会有自己的完成结果。它可能成功、发现目标已完成，或无法立即取消；原操作的完成记录仍需按接口处理。应用应追踪“已请求取消”与“原请求已终结”两个状态。prep_cancel

link timeout 可以限制关联操作的等待，但不等于给整个 ring 自动建立超时隔离。一个独立慢请求通常也不会天然阻止所有其他独立请求完成；是否存在依赖链由提交方式决定。

普通一次性操作常对应一条 CQE，但 multishot 接受或接收可产生多条，应检查 IORING_CQE_F_MORE 判断请求是否还会继续。某些零拷贝发送还需额外通知来判断数据缓冲何时可复用，不能把所有 CQE 一概当作资源最终回收点。Multishot accept

取消竞态要分别记录两笔结果

以下表格限定按唯一 user_data 取消一个普通单次请求，不使用取消全部匹配项的标志。C 是取消请求，R 是原请求；取消本身并不回滚 R 已完成的外部副作用。取消结果

如果业务超时后只是不再需要结果，可以把 R 标为“结果丢弃”，但其 I/O 生命周期仍需完成。业务状态结束和内核访问 buffer 结束不是同一件事；这也是异步接口必须明确拥有关系的原因。

multishot 的一次结果与请求终结也要分开

下面是离线 CQE 模型，MORE 表示对应 IORING_CQE_F_MORE 的布尔值，不读取真实 ring。两次成功 accept 得到两个 fd，最后一条取消完成结束这次 multishot 请求。示例只记录数字，不创建或关闭真实套接字。

import errno
active = True
accepted = []
terminal = None
cqes = [(101, True), (102, True), (-errno.ECANCELED, False)]
for result, more in cqes:
    assert active
    if result >= 0:
        accepted.append(result)
    if not more:
        active = False
        terminal = result
assert accepted == [101, 102]
assert not active and terminal == -errno.ECANCELED
# 成功结果也可能是最后一条，不能用 result >= 0 判断仍然活跃。
last_success, more = 103, False
assert last_success >= 0 and not more

真实 accept 的成功结果是已经获得的连接资源，需要交给连接管理或关闭；请求终结不自动关闭之前接受的连接。判断是否继续等待这一请求的后续 CQE，应检查 MORE，而不是只看 res 的正负。Multishot accept

取消完成，不等于原请求完成

先只收取 C，buffer 仍保留；收取 R 才完成原请求的账目。切换到 read 先成功，R 的4字节结果不会因为稍后提交取消就被撤销。这里允许选择收取顺序，用于说明两笔账独立，不承诺任意内核版本都会产生同样的 CQE 排列。

批量与背压

SQE 取不到时，需要提交已准备项并根据在途数量继续推进；CQ 也要及时收取和推进消费位置。等待多条完成与实际批量遍历是不同动作，不能把 wait_cqes 的名字理解成已经替应用消费所有 CQE。

队列深度控制并发在途工作。过小可能无法填满设备，过大则可能增加排队延迟、内存和尾延迟；不存在通用“256–512 就够”。先用完成时间和目标吞吐估算并发需求，再测量饱和点与尾延迟。

用吞吐与延迟估算数量，再加上缓冲的账

假设目标吞吐为每秒 20000 次请求，平均在途时间为 2 ms，稳定状态下平均在途数量约为 40。这是吞吐乘平均时间的容量估算，不是尾延迟保证，也不是内核必须配置 SQ 深度为 40。

rate = 20_000
mean_seconds = 0.002
average_inflight = rate * mean_seconds
assert average_inflight == 40
buffer_size = 64 * 1024
limit = 64
buffer_budget = limit * buffer_size
assert buffer_budget == 4 * 1024 * 1024

若每个普通读请求独占 64 KiB 缓冲，在途上限 64 就对应至少 4 MiB payload 容量，还没算请求对象、ring、对齐和其他队列。SQ 空位只是提交容量：SQE 已被内核消费后，请求仍可能执行中，所以不能把“又拿到一个 SQE”当作“在途缓冲预算自动减少”。

应用应独立维护在途请求数与可用缓冲池，达到上限时先收取完成或暂停上游。对 multishot，再计入已经接受但尚未处理的连接/消息数量；单个活跃 SQE 可以持续产生业务资源，单靠 SQ 深度无法限制它们的累积。

与 libaio 或 POSIX AIO 比较时，固定 buffered/direct 模式、块大小、设备、线程和同步保证。Linux 原生 AIO 的异步性在某些 buffered 路径受限制，不等于语法上绝对不能提交缓冲文件 I/O；POSIX AIO 是接口规范，Linux libc 的线程实现只是具体实现之一。

请求 API 提供异步模型，不意味着每个操作都由设备硬件异步执行；部分工作可能即时完成或交给内核工作线程。优先验证行为、资源回收和背压，再讨论系统调用减少多少。

关键词：io_uring, SQE, CQE, liburing, completion, buffer lifetime, SQPOLL, IOPOLL, fixed buffers, cancellation, multishot, queue depth