Linux io_uring批量提交异步IO

我第一次把一批文件读取改成 io_uring 时，最先想到的是“把同步 read 换成异步 API”。真正影响吞吐的地方却是提交节奏：如果每个请求都单独进入内核，批量能力就被自己拆掉了。

更稳妥的做法是：先为一批请求准备多个 SQE，再调用一次 io_uring_submit()；随后从 CQ 中逐个取回 CQE，用 user_data 找回原请求，用 cqe->res 判断读取字节数或负数错误。这样既能减少提交次数，也不会把“提交顺序”和“完成顺序”混为一谈。

一句话结论：批量提交的核心不是把多个文件名塞进一个 SQE，而是一次准备多个 SQE、一次提交，再按 CQE 完成事件逐项收口。

先看懂一批请求在 ring 里怎么走

liburing 把 Linux 的共享环形队列封装成了比较易用的接口。应用先从 Submission Queue（SQ）取得空闲的 SQE，填入操作类型、文件描述符、缓冲区、偏移量和 user_data；调用 io_uring_submit() 后，内核从 SQ 取走这些请求并处理，结果写入 Completion Queue（CQ），每个结果对应一个 CQE。

这里有两个容易误解的点：

• 一个 SQE 描述一个 I/O 操作，批量是多个 SQE 一起提交，不是把多个操作压成一个 SQE。
• CQE 的到达顺序可能和 SQE 的准备顺序不同，业务必须依靠 user_data 或自己的索引关联请求。

官方的 liburing 项目地址是 https://github.com/axboe/liburing/，Linux 的底层提交入口可以参考 https://man7.org/linux/man-pages/man2/io_uring_enter.2.html。

问题现场：逐个提交为什么容易失去批量价值

假设程序要读取 32 个相互独立的文件块。如果循环中每准备一个 SQE 就立刻调用一次 io_uring_submit()，工作仍然能完成，但提交动作被拆成了 32 个小批次。它带来两个代价：

• 应用和内核之间的进入次数变多，批量提交能减少的固定成本没有被摊薄。
• 应用更早进入等待路径，内核看到的并发窗口更小，难以同时安排多个独立请求。

这不等于“批次越大越快”。SQ 有容量，缓冲区也要保持有效；批次过大可能增加内存占用和尾延迟。实践中应从一个小的固定批次开始，观察队列是否经常取空、CQ 是否积压，再调整。

动手准备：为每个读取请求绑定身份

下面的示例使用 liburing 批量读取同一个文件的多个区间。为了突出提交机制，缓冲区和请求数组都在整个批次完成前保持有效；示例没有把它当作基准测试，也不声称在本机执行过。

#include 
#include 
#include 
#include 
#include 
#include 

#define BATCH_SIZE 4
#define BLOCK_SIZE 4096

struct read_request {
    char *buffer;              // 每个请求独立持有读取缓冲区。
    unsigned long long offset; // 用偏移量帮助完成处理阶段定位请求。
};

int main(int argc, char **argv) {
    if (argc != 2) {
        fprintf(stderr, "用法：%s 文件路径\n", argv[0]);
        return EXIT_FAILURE; // 参数不足时不创建 ring，避免留下半初始化状态。
    }

    int fd = open(argv[1], O_RDONLY);
    if (fd user_data = i; // CQE 返回时用索引找回原请求。
    }

    ret = io_uring_submit(&ring); // 关键：多个 SQE 只提交一次。
    if (ret user_data;
        if (cqe->res res));
        } else {
            printf("请求 %u 完成，读取 %d 字节\n", index, cqe->res);
        }

        io_uring_cqe_seen(&ring, cqe); // 消费 CQE，否则 CQ 空间不会释放。
    }

    io_uring_queue_exit(&ring); // 释放 ring 关联的映射和资源。
    close(fd);
    return EXIT_SUCCESS;
}

代码里的 user_data 只是一个无符号整数索引，生产代码也可以放入请求对象指针，但必须保证指针指向的对象在 CQE 被消费前一直有效。批量提交后，ret 表示实际提交的 SQE 数量；它不是“函数调用成功”这么简单，数量不对时应停止继续等待完整批次。

动手验证：先看提交数量，再看 CQE 的 res

提交成功后不要假设“返回了 4 个 CQE 就代表都读满 4096 字节”。对于读取操作，cqe->res 是实际读取的字节数，也可能是负的错误码。文件到达 EOF 时，结果可能小于请求长度；这和系统级错误是两回事。

收取 CQE 时，我会按下面的顺序处理：

1. 检查 io_uring_wait_cqe() 的返回值，区分等待 API 自身失败。
2. 读取 cqe->user_data，定位请求上下文，不按完成顺序猜请求。
3. 判断 cqe->res ；负数按 -cqe->res 转成错误号。
4. 无论成功还是失败，都调用 io_uring_cqe_seen() 释放这个 CQE 槽位。

完成顺序不同是正常现象。比如请求 1 先完成并返回错误，请求 0 随后读取成功，程序仍然要把两个 CQE 都标记为已消费。若业务要求按文件顺序合并结果，可以先写入以 user_data 为索引的结果数组，等整个批次收齐后再按索引整理。

定位原因：批量没有生效时看这几个边界

如果观察不到预期效果，通常不是 io_uring “没有异步”，而是批次边界或资源生命周期不正确。

• SQE 不够：io_uring_get_sqe() 返回空指针时，先提交或消费已有请求，再继续填充，不能无视返回值。
• 缓冲区过早释放：异步请求完成前不能释放、复用或移动读写缓冲区。
• 只看提交返回值：io_uring_submit() 的正数只说明提交了多少个 SQE，最终结果仍要逐个看 CQE。
• 忘记 seen：不调用 io_uring_cqe_seen() 会让 CQ 的已消费空间无法回收，后续批次可能越来越难取得 CQE。
• 把批次当成顺序保证：批量准备的顺序不等于完成顺序；有依赖关系时应研究链式 SQE 或在应用层建立状态机。

另外，io_uring 的具体行为还取决于内核、文件系统、存储设备和 liburing 版本。不要仅凭一个小文件读写示例推断生产负载收益；应在接近真实的文件大小、并发度和错误比例下测量提交次数、完成延迟、队列占用与内存。

按负载选择批次大小

我的经验是先用 8、16 或 32 这类容易观察的批次验证生命周期，再结合 CQ 消费速度和后端存储特性调大。批次只是调度窗口，不是越大越能代表并行度；如果消费者处理不过来，过大的 CQ 积压反而会放大内存和延迟。

常见疑问

一次 io_uring_submit() 能提交多少个请求？受 SQ 容量和当前可用 SQE 数量限制。应用应根据 io_uring_get_sqe() 是否返回有效指针以及 submit 返回数量处理，而不是写死“调用成功就等于整批成功”。

CQE 一定按 SQE 的顺序返回吗？不一定。独立请求的完成顺序可能不同；用 user_data 关联请求，不能用 CQE 的到达顺序当业务序号。

cqe->res 为什么是负数？liburing 的 CQE 结果通常直接携带负的 errno 值。判断小于 0 后，用 -cqe->res 交给 strerror，不要把它当作普通字节数打印成成功结果。

io_uring 能不能替代所有文件 I/O？不能简单这样理解。支持的操作、内核版本、文件系统和存储设备都会影响实际行为；对强顺序依赖、极小负载或缺少部署兼容性的场景，传统接口可能更简单。

小结

Linux io_uring 的批量异步 I/O 可以归纳成四个动作：准备多个 SQE、一次提交、逐个消费 CQE、最后标记已见。真正需要防的是三件事：没有检查实际提交数量、没有保持缓冲区和请求上下文的生命周期、把完成顺序误当成提交顺序。把这三处处理好，再用真实负载调批次大小，才有资格讨论吞吐与延迟收益。