Linux io_uring 怎样理解提交队列和完成队列

理解 Linux io_uring，可以先记住一句话：用户空间把待处理的 I/O 描述放进提交队列（SQ），内核处理后把结果放进完成队列（CQ）。提交端写入的是 SQE，完成端读取的是 CQE；两者通过 user_data 关联，而不是靠“第几个提交”猜结果。

官方地址：https://man7.org/linux/man-pages/man7/io_uring.7.html

下面的结构图是原创说明图，不是终端截图，也不是本机运行证据。示例使用 liburing 风格的 C 伪代码帮助理解对象关系，具体函数签名应以所用 liburing 版本文档为准。

先把 SQ 和 CQ 看成两条方向相反的环

io_uring 通过用户空间与内核共享的环形缓冲区传递请求和结果。提交队列的方向是“用户空间追加、内核取走”：应用把一个 io_uring_sqe 写入 SQ 的尾部，内核从 SQ 的头部取出它。完成队列正好相反：内核把 io_uring_cqe 追加到 CQ 尾部，应用从 CQ 头部取走它。

所以 SQ 不是“正在运行的任务列表”，CQ 也不是“按提交顺序排列的返回值列表”。它们更像两个交接缓冲区：SQ 负责把意图交给内核，CQ 负责把完成通知交还给应用。

一次请求中 SQE、CQE 分别负责什么

应用真正描述一次 I/O 时，先取得一个 SQE，填写操作类型、文件描述符、缓冲区和偏移等字段，再把自己的关联值写入 user_data。调用提交函数后，内核才会把已经准备好的 SQE 纳入处理范围；提交可以一次带上多个请求，减少频繁进入内核的次数。

// 取得一个空闲 SQE，并描述一次读取请求
struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
io_uring_prep_read(sqe, fd, buffer, buffer_size, offset);
// 用业务任务编号关联完成事件，不要依赖 CQE 的到达位置
sqe->user_data = task_id;

// 把已经准备好的 SQE 交给内核处理
int submitted = io_uring_submit(&ring);
// submitted 表示本次提交的数量；负值代表提交阶段出错
if (submitted 

完成后，应用从 CQ 取得 CQE。CQE 的 user_data 是之前放入 SQE 的关联值，res 是类似对应系统调用返回值的结果：成功时通常是读取字节数等非负值，失败时直接携带负的错误号，不能按普通阻塞系统调用那样等待 errno 被设置。

读取 CQE 时要先匹配任务，再解释结果

多个请求同时在途时，内核可以按实际资源情况完成它们，因此 CQE 的出现顺序不必等于 SQE 的提交顺序。正确做法是先用 user_data 找回任务上下文，再根据 res 判断成功、短读或错误。

// 从完成队列取出一个完成事件
struct io_uring_cqe *cqe = NULL;
int ret = io_uring_wait_cqe(&ring, &cqe);
if (ret user_data;
    int result = cqe->res;
    if (result 

队列边界和常见误区

• 提交不等于完成：提交函数返回的是已交给内核的请求数量，不代表这些 I/O 已经完成。
• 完成不保证顺序：需要严格顺序时，应在设计上控制同一资源的并发关系，或使用 io_uring 提供的链接能力；不要用 CQE 到达顺序代替业务序号。
• 结果要看 res：异步完成事件把结果放进 CQE，错误表现为负错误号；应用仍要处理短读、失败和取消等情况。
• 槽位要及时消费：CQ 不及时读取会占满完成空间，随后新的请求可能无法顺利推进；消费 CQE 后要调用对应的完成事件回收函数。

把问题简化成一条链就不容易混淆：SQE 描述“我要做什么”，SQ 负责交接，内核执行，CQ 负责交回，CQE 描述“结果是什么”。当并发请求超过一个时，唯一可靠的回溯键是自己写入的 user_data。

相关问题

提交队列和完成队列是同一个队列吗？

不是。SQ 面向待处理请求，应用写入、内核取出；CQ 面向完成事件，内核写入、应用取出。两者共享环形缓冲区的设计思路相近，但职责和读写方向不同。

为什么不能用 CQE 的顺序对应 SQE？

因为多个 I/O 可以同时在途，实际完成时间由文件、设备和内核调度共同决定。应使用 SQE 中的 user_data 保存业务关联值，再按 CQE 的 res 处理结果。

res 为负数时应该看哪里？

把它视为负的错误号并转成应用自己的错误处理路径；不要期待异步完成场景像普通系统调用那样通过 errno 传回同一错误。