Linux io_uring 注册缓冲区的生命周期管理

Linux io_uring 的注册缓冲区适合由一个环级资源池统一持有：先分配稳定的数据内存，再注册索引表；请求使用期间保留内存和占用记录；停止新增请求、处理完关联完成事件并结束业务引用后，再注销和释放。提交成功、取消请求返回和缓冲区更新返回，都不应直接当作业务可以回收内存的统一信号。

本文只讨论普通 fixed-buffer 单次读写，不把 provided buffer ring、multishot 接收或零拷贝发送的通知语义混入同一套计数。下面是原创设计示例，未在本文环境执行，也不提供性能实测结论。

liburing 官方仓库：https://github.com/axboe/liburing

把注册缓冲区看作环级资源池

这里采用的模式是“环级固定池”：拥有 io_uring 的组件同时拥有注册表和数据内存，请求只借用池中的槽位。这样，注册开销属于池，单次操作只处理槽位占用。固定池适合反复使用同一批内存的负载；如果每次请求都注册、注销并重新分配，就很难体现预注册减少重复映射工作的意义。

需要分清两个对象。struct iovec 数组描述地址和长度，注册调用完成后，该描述数组可以离开作用域；iov_base 指向的数据内存则由应用继续管理，不能因为描述数组已无须保留，就提前 free 数据。liburing 注册手册明确允许描述数组放在栈上，并说明预注册的映射优化目的。注册接口说明

“注册”不等于取得某个槽位的独占写权限。内核保存注册资源，不会替应用判断解析线程是否仍在读取上一次结果。因此，资源池需要另外记录谁正在使用槽位。

确定地址、索引和占用权

fixed read 需要同时给出普通文件描述符、数据地址、请求字节数、文件偏移和注册索引。索引选中注册区间，地址与长度必须落在该区间内；可以读取区间的一部分，不必总从注册区间开头使用。缓冲区索引与 fixed-file 文件索引是两个概念，不要因使用固定缓冲区而自动添加 IOSQE_FIXED_FILE。

例如槽位 0 对应 4096 字节内存，读取该区域内的 1024 字节可以使用同一注册索引；地址换成另一块 malloc 内存后，沿用原索引并不会自动更新注册内容。fixed read 的 buf、nbytes 和 buf_index 必须共同描述合法区间。fixed read 参数说明

建议每个槽位同时维护“已交给 I/O 管理”和“仍被业务持有”两个事实。可以用不同计数实现，也可以让一个租约覆盖两段使用期。本文选择后者：只有 I/O 已完成且下游不再读取数据，租约才归还。这样计数为零的含义明确，不会把已读到数据但仍在解析的内存误判为空闲。

用一个所有者封装注册与释放

下面的 C 片段只封装单槽池的注册和关闭，供已有事件循环集成；它不是完整读文件程序。调用方必须持有一把覆盖注册、借用、归还和关闭的同一把锁，或把这些动作全部放到同一个事件循环线程。leases 是应用占用记录，不是从内核自动获得的请求数量。

#include 
#include 
#include 
#include 
#include 

struct fixed_pool {
    void *data;
    size_t capacity;
    unsigned leases;
    bool registered;
    bool closing;
};

/* 前提：ring 已初始化，p 为全零的新对象，调用方独占池。 */
static int pool_open(struct io_uring *ring, struct fixed_pool *p)
{
    void *data = malloc(4096);
    if (!data)
        return -ENOMEM;

    struct iovec description = {
        .iov_base = data,
        .iov_len = 4096
    };
    int ret = io_uring_register_buffers(ring, &description, 1);
    if (ret data = data;
    p->capacity = 4096;
    p->leases = 0;
    p->registered = true;
    p->closing = false;
    return 0;  /* 栈上的 description 可以结束，data 继续存活。 */
}

/* 调用方先借用，再准备 SQE；返回值是 liburing 风格的负错误码。 */
static int pool_borrow(struct fixed_pool *p)
{
    if (!p->registered || p->closing || p->leases != 0)
        return -EBUSY;
    p->leases = 1;  /* 示例单槽独占，不允许两个读请求写同一块内存。 */
    return 0;
}

/* 仅在目标 I/O 已结束、业务也结束读取后调用一次。 */
static int pool_return(struct fixed_pool *p)
{
    if (p->leases != 1)
        return -EINVAL;
    p->leases = 0;
    return 0;
}

/* 停止新增借用；忙时由事件循环继续处理完成事件，稍后再关闭。 */
static int pool_close(struct io_uring *ring, struct fixed_pool *p)
{
    p->closing = true;
    if (p->leases != 0)
        return -EBUSY;
    if (!p->registered)
        return 0;

    int ret = io_uring_unregister_buffers(ring);
    if (ret registered = false;
    free(p->data);
    p->data = NULL;
    p->capacity = 0;
    return 0;
}

这个封装故意把关闭请求设计成“禁止再借用，但允许继续排空”。如果第一次关闭返回 -EBUSY，不能紧接着销毁池对象或 ring；应由事件循环等已有租约归还后再次关闭。注销接口成功返回 0，失败返回负错误码，失败时保留对象便于上层恢复。注销接口返回约定

示例使用普通 malloc 和非直接 I/O 的内存模型；若改成 O_DIRECT，还要满足目标文件系统与设备对地址、长度、偏移的对齐要求。不要把本例 4096 解释为所有环境通用的对齐保证。

请求完成后还要交还业务占用

集成时，先成功借用槽位，再取得 SQE；取得失败时，本次尚未准备任何 SQE，可以立即归还租约。准备成功后，租约覆盖提交、等待目标 CQE 和业务消费。下面片段假设调用方已成功借用，且 sqe 是已取得的条目；fd 是普通文件描述符。

/* 这里使用注册索引 0，只读取槽位容量之内的数据。 */
io_uring_prep_read_fixed(sqe, fd, pool.data,
                        (unsigned)pool.capacity, 0, 0);
/* 请求标识由事件循环分配，用来关联目标 CQE 和槽位租约。 */
io_uring_sqe_set_data64(sqe, request_id);

io_uring_submit() 的结果说明提交层面的情况，不是这次读操作的字节数。真正读结果来自目标 CQE 的 res：正值为实际字节数，零表示本次读取到文件结尾，负值是操作错误。不要用 errno 覆盖负 res 表达的错误；也不要总按容量消费，因为读操作可能短读。

完成分发器应以请求标识找到租约，并保证每个目标请求只完成一次应用记账。若同步消费数据，消费结束后归还；若把数据交给另一个线程，租约跟随业务对象，最后一个消费者结束后再归还。io_uring_cqe_seen() 归还的是 CQ 条目，不能代替应用数据租约的释放。

提交出现部分成功或错误时，尤其不要把全部租约直接清零。事件循环必须区分尚未发布、已经交给提交路径、仍可能由内核处理的请求；不能确定状态时继续保留租约，按自己的 SQ/CQ 记账恢复。完整提交恢复依赖事件循环实现，不能靠一个无条件 free 兜底。

停机、取消和热更新分别处理

固定池关闭的前提有三个：已经禁止生产者取得新租约；所有可能引用该池的已准备或已提交请求都已妥善处理；业务消费者没有继续持有数据。这里的屏障是应用协议，需要与生产者同步，不能只读一次计数器后让另一线程继续借用。

取消请求有自己的完成结果，目标请求也有自己的完成事件。取消可能找不到目标，也可能已经来不及取消；事件循环仍应按目标请求的终结事件结清租约。不要看到取消 SQE 的 CQE 就重复归还目标租约，尤其不要把 -ENOENT 当作“已证明没有任何占用”。liburing 取消手册列出了完成竞态与 -EALREADY 时继续等待目标完成的要求。取消与目标完成语义

热更新比停机复杂。若不需要在线换池，优先采用暂停借用、排空、注销、重新注册的可解释实现。若选择带 tag 的注册与更新接口，应为旧资源保留退役记录，并把资源 tag 的释放通知与普通 I/O 请求标识分开。资源更新返回时，旧资源仍可能被在途请求保留；带非零 tag 的资源在注销且不再使用后，会发送相应 CQE。这个通知也不代替应用自己的业务引用记录。

注册资源跟随 ring 生命周期，但直接拆除 ring 的内核清理可能异步进行，不能承诺退出函数返回时所有页都已经立刻解除固定。常规注销、更新退役和 ring 整体拆除应作为三条不同的管理路径。上述资源 tag、更新与拆除语义来自 liburing 的系统调用手册。资源注册与退役说明

采用前的判断清单与常见问题

注册成功后可以 realloc 吗？ 不应对已登记的数据地址直接 realloc；它可能移动分配，注册表仍对应旧区间。容量变化应走明确的换池或更新协议。

可以让多个读请求共享同一注册槽位吗？ 注册索引本身不禁止共享，但重叠写入区间需要应用解决冲突。本文单槽示例采用独占租约；多槽池可以并发使用不同槽位，而不必牺牲地址稳定性。

注册缓冲区就是零拷贝吗？ 不能这样推断。固定注册减少的是相关资源准备工作，数据路径还取决于操作类型。是否值得使用，要结合固定内存成本、槽位等待、吞吐和尾延迟衡量，不能只根据注册成功就宣称更快。

申请注册失败怎么办？ 保留负错误码，并检查当前运行环境的资源限制、权限及接口支持；固定内存涉及资源预算。若业务允许退回普通读写路径，要使用独立且正确的生命周期协议，不能在注册失败后继续发 fixed-buffer 请求。

把代码落入项目时，先写清楚“谁能借用、什么事件归还、谁有权关闭”三个契约，再决定池大小与是否热更新。固定池是减少重复资源准备的一种取舍，额外的占用记录和停机同步也必须计入设计成本。