Linux io_uring 怎么取消尚未完成的请求

在 Linux io_uring 中，取消尚未完成的请求不是“删除一条 SQE”，而是再提交一个 IORING_OP_ASYNC_CANCEL 请求。最稳妥的做法是给原请求设置唯一的 user_data，再用 io_uring_prep_cancel64() 按这个值匹配。取消请求本身也会产生 CQE，所以应用必须同时等待并区分“取消请求的 CQE”和“原请求的 CQE”。

取消成功只表示内核找到了目标并接受了取消；真正决定缓冲区何时可以释放的，仍是原请求自己的 CQE。不要假设两个 CQE 的到达顺序，也不要在只收到取消 CQE 后立刻释放原请求资源。

Linux 内核 io_uring 文档：https://docs.kernel.org/io_uring/

liburing 取消接口手册：https://man7.org/linux/man-pages/man3/io_uring_prep_cancel64.3.html

先把取消模型拆成两个请求

一个待取消的读请求和一个取消请求，是两条独立的提交项。读请求的 user_data 是被匹配的键；取消请求还要拥有另一个 user_data，这样处理 CQE 时才不会把“取消操作完成”误认成“原始 I/O 完成”。

这两个标识必须在当前 ring 的在途请求中保持可区分。实践中可以把 user_data 设计成请求对象指针，也可以使用 64 位 ID；若选择整数，io_uring_sqe_set_data64() 与 io_uring_prep_cancel64() 的组合最直观。

用一个阻塞读构造最小可取消请求

下面的小程序创建一个管道，但不向写端写入数据。读请求因此有机会保持未完成状态，然后程序提交取消请求。示例关注请求身份和 CQE 处理，不把它扩展成完整事件循环。

#include 
#include 
#include 
#include 
#include 

enum {
    TARGET_ID = 0x1001,
    CANCEL_ID = 0x2001,
};

int main(void) {
    struct io_uring ring;
    struct io_uring_sqe *sqe;
    struct io_uring_cqe *cqe;
    int pipefd[2];
    char buffer[32];

    /* 初始化一个小型 ring，并创建保持写端开放的管道。 */
    if (io_uring_queue_init(8, &ring, 0) user_data == CANCEL_ID) {
            printf("取消 CQE: res=%d\n", cqe->res);
        } else if (cqe->user_data == TARGET_ID) {
            printf("目标 CQE: res=%d\n", cqe->res);
        }

        /* 每个 CQE 处理完都要归还给完成队列。 */
        io_uring_cqe_seen(&ring, cqe);
    }

    close(pipefd[0]);
    close(pipefd[1]);
    io_uring_queue_exit(&ring);
    return 0;
}

可用下面的命令编译。程序通常会看到取消 CQE 的 res=0，目标 CQE 的 res=-ECANCELED；但生产代码不能把这个组合写成唯一分支，因为目标请求可能在取消到达前自然完成。

# 需要系统已安装 liburing 开发包。
cc -O2 -Wall cancel_demo.c -luring -o cancel_demo

# 运行后观察取消请求和目标请求各自的 res。
./cancel_demo

取消请求靠 user_data 找到目标

io_uring_prep_cancel64(sqe, TARGET_ID, 0) 会准备一个 IORING_OP_ASYNC_CANCEL。默认匹配键是原请求 SQE 中的 user_data。因此，真正关键的不是取消函数调用本身，而是提交原请求时就建立可靠的身份体系。

如果项目使用指针作为请求上下文，可调用 io_uring_prep_cancel(sqe, request_ptr, 0)；它与 64 位版本的取消语义相同，只是参数类型不同。无论选择指针还是整数，都应避免在请求仍在途时复用同一个标识。

两个 CQE 要分别判断

取消 CQE 的 res 描述“匹配和取消尝试”，原请求 CQE 的 res 描述“原操作最终怎样结束”。liburing 手册给出的常见结果如下：

取消存在天然竞态。发出取消 SQE 后，目标可能已经完成、正在完成，或进入底层无法撤回的阶段。取消 CQE 与目标 CQE 的顺序也没有保证。因此事件循环应该按 user_data 分派，而不是写成“先等取消 CQE，再假设下一条一定是目标 CQE”。

资源只能在目标 CQE 到达后释放

最容易出现的错误，是收到取消 CQE 的 res=0 后立刻释放读缓冲区、关闭请求对象或复用 user_data。取消请求只负责触发取消，原请求仍需要投递自己的完成事件。只要目标 CQE 尚未被消费，就应认为该请求上下文仍由 ring 的生命周期管理。

一个实用的请求对象可以保存两个状态：cancel_requested 表示业务已不再需要结果，target_completed 表示内核已经交付原请求 CQE。只有第二个状态成立，才允许释放原请求专属的缓冲区。若多个业务方共享 fd，还要避免把“取消某个请求”和“关闭整个 fd”混为一谈。

按 fd、批量或任意请求匹配

默认的 user_data 匹配最精确，也最适合单请求取消。较新的内核还提供其他匹配方式，但部署时必须同时确认运行内核和头文件支持情况。

例如，按普通 fd 取消全部匹配请求，可以使用 io_uring_prep_cancel_fd() 并组合 IORING_ASYNC_CANCEL_FD | IORING_ASYNC_CANCEL_ALL。这种做法会影响同一 fd 上的多条在途操作，应只在连接整体关闭、批量清理等明确场景使用。

/* 按同一个普通 fd 匹配所有请求，适合连接整体清理。 */
sqe = io_uring_get_sqe(&ring);
io_uring_prep_cancel_fd(
    sqe,
    fd,
    IORING_ASYNC_CANCEL_FD | IORING_ASYNC_CANCEL_ALL
);

/* 批量取消请求也需要自己的 user_data，便于识别取消 CQE。 */
io_uring_sqe_set_data64(sqe, CANCEL_ALL_ID);

什么时候不该手写 ASYNC_CANCEL

如果需求只是“某次 I/O 超过指定时间就自动取消”，可考虑把请求与 io_uring_prep_link_timeout() 链接。这样超时关系由内核维护，不必在用户态定时器触发后再查找目标。不过，连接断开、业务主动放弃结果、停止 multishot 请求或批量清理 fd 等场景，显式 ASYNC_CANCEL 仍然更直接。

关闭 ring 时，待处理请求会被取消；但如果应用需要处理每条请求的最终状态、归还缓冲区或统计结果，仍应在退出前排空相关 CQE，而不是把 io_uring_queue_exit() 当作普通请求生命周期管理的替代品。

常见错误清单

• 取消请求和目标请求使用同一个 user_data：事件循环无法可靠区分两个 CQE。
• 收到取消 CQE 就释放目标缓冲区：原请求 CQE 尚未到达，资源可能仍被引用。
• 把 -ENOENT 当成系统故障：它经常只是目标已经先完成，应结合目标 CQE 判断。
• 假设取消一定成功：部分操作已提交到底层后可能无法撤回，会得到 -EALREADY 或正常目标结果。
• 依赖两个 CQE 的顺序：应按 user_data 分派，并为每个请求单独维护状态。
• 无条件使用新 flags：先确认部署内核、liburing 与编译时头文件的支持范围。

总结

取消 io_uring 未完成请求的完整闭环只有三件事：原请求设置稳定且唯一的 user_data；用 io_uring_prep_cancel64() 或相关辅助函数提交独立取消请求；持续消费取消 CQE 和目标 CQE，直到确认原请求最终结束。把取消当作另一个异步请求，并让资源生命周期跟随目标 CQE，而不是跟随“取消已提交”，就能正确处理正常完成、取消成功、目标已完成和无法撤回等竞态。