io_uring 注册缓冲区降低小文件 I/O 开销

在 Linux 上反复读取许多小文件时，io_uring 的普通读请求除了等待设备，还要反复处理用户缓冲区的检查、页面固定和内核映射。注册缓冲区的思路是把这部分准备工作提前做一次，后续使用 READ_FIXED 或 WRITE_FIXED 按索引复用已经登记的内存。它更适合“小、频繁、复用同一批缓冲区”的工作负载，并不是所有 I/O 都会因此变快。

官方资料：https://man7.org/linux/man-pages/man2/io_uring_register.2.html

最小路径可以概括为：分配匿名缓冲区，调用 io_uring_register_buffers 注册，再用 io_uring_prep_read_fixed 或 io_uring_prep_write_fixed 提交请求。完成队列中的 cqe->res 直接给出传输字节数或负的错误码。

先理解注册缓冲区减少了哪一段开销

普通读请求会把用户态地址和长度交给内核，内核需要确认这段内存可访问，并为 I/O 准备相应的页面引用与映射。注册缓冲区后，内核会长期持有这块内存的引用并建立映射，随后固定读写可以跳过每次 I/O 的重复准备工作。

这里的“固定”不是把文件固定在内存里，而是固定用户提供的缓冲区。文件描述符仍然要正常打开，读请求也仍然会受到文件偏移、权限和设备吞吐的影响。收益主要来自每次 I/O 的内存准备成本被摊平。

准备一块可以长期复用的匿名内存

IORING_REGISTER_BUFFERS 接受一组 struct iovec。常见实现使用 malloc 或匿名 mmap 得到内存；当前接口不接受文件映射内存。每个缓冲区还存在单块大小限制，实际项目应同时考虑进程的锁定内存额度和整个机器的资源余量。

// 这段代码只负责准备一块可复用的匿名缓冲区
void *buffer = NULL;
struct iovec iov;

// 4096 字节对齐便于兼容后续可能使用的直接 I/O 场景
int ret = posix_memalign(&buffer, 4096, 4096);
if (ret != 0) {
    // posix_memalign 返回的是错误号，不是负 errno
    fprintf(stderr, "分配缓冲区失败: %s\n", strerror(ret));
    return 1;
}

memset(buffer, 0, 4096);
iov.iov_base = buffer;
iov.iov_len = 4096;

// 注册后，iov 数组可以释放，但 buffer 必须保持有效并且内容可复用
ret = io_uring_register_buffers(&ring, &iov, 1);
if (ret 

iov 只是注册时的描述数组，注册完成后可以回收；真正的 buffer 不能提前释放，也不能在请求仍在使用时交给别的用途。多个缓冲区会按数组顺序获得从零开始的索引，后续 SQE 的 buf_index 就是这个索引。

用 READ_FIXED 读取小文件

注册完成后，不能继续使用普通的 io_uring_prep_read 来表达“使用注册缓冲区”。应改用固定版本，并保证传入的地址与长度完全落在注册项范围内。下面的最小示例读取一个文件的前 4096 字节，注册表中只有一个缓冲区，所以索引是 0。

// 假设 ring 已初始化，buffer 已按上节注册，fd 是已打开的小文件
struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
if (sqe == NULL) {
    // 没有可用 SQE 时，应先提交或等待，而不是继续写空指针
    fprintf(stderr, "获取 SQE 失败\n");
    goto cleanup;
}

// 只读取注册项中的前 4096 字节，最后一个参数 0 对应第一个注册缓冲区
io_uring_prep_read_fixed(sqe, fd, buffer, 4096, 0, 0);
sqe->user_data = 1;

int submitted = io_uring_submit(&ring);
if (submitted res res));
} else {
    // 正数表示实际读取的字节数，小文件可能出现短读
    printf("读取 %d 字节\n", cqe->res);
}
io_uring_cqe_seen(&ring, cqe);

cleanup:
// 先确保请求完成，再释放注册表和底层内存
io_uring_unregister_buffers(&ring);
free(buffer);

这个例子有两个容易忽略的点。第一，buffer 和 4096 必须落在索引为 0 的注册区域里，不能把另一个地址误传给固定读。第二，cqe->res 是实际 I/O 结果：负值是负错误码，非负值是读取字节数，短读不能被当作 API 失败。

处理注册失败和生命周期

注册缓冲区会锁定或长期引用用户内存，因此失败时先看资源限制，而不是反复调用同一注册接口。可以检查当前 shell 的锁定内存额度：

# 查看当前 shell 允许锁定的内存额度，单位通常是 KiB
ulimit -l

# 仅对当前 shell 临时放宽限制；生产环境应通过系统配置或服务资源声明管理
ulimit -l unlimited

返回 -ENOMEM 时，常见原因包括可用锁定内存不足或内核资源不足；返回 -EBUSY 可能表示 ring 已经有同类资源注册。注册缓冲区前还要检查数组数量是否为零、单个缓冲区是否过大，以及是否把文件映射内存当成普通匿名内存传入。

更新缓冲区时，旧请求还在飞行中就直接改写或释放内存会破坏生命周期。简单做法是等待相关 CQE 完成后再注销；需要动态更新时，再根据目标内核和 liburing 版本考虑 IORING_REGISTER_BUFFERS_UPDATE 等接口。关闭 ring 时系统会清理注册资源，但显式注销能让释放时机更清楚。

判断什么时候值得使用

可以先用下面的判断表做选型：

因此，注册缓冲区更像是 I/O 热路径的资源布局选择，而不是一个打开就必然有效的加速开关。先确认缓冲区是否能长期复用，再估算锁定内存预算，最后把普通读请求替换为固定版本，收益才有机会稳定出现。

常见问题

注册成功后为什么还要传 buffer 指针？

固定读写接口仍需要给出本次操作的地址和长度，但这段范围必须落在对应的注册项中；buf_index 用来选择注册项，不是替代地址参数。

注册缓冲区能直接用于文件映射内存吗？

当前通用注册接口要求匿名、非文件后备内存。使用 malloc 或匿名 mmap 更符合接口约束，不要把普通文件映射区域直接当作注册缓冲区。

为什么读小文件时没有明显收益？

如果请求数量很少、设备延迟占主要部分，或者缓冲区频繁变化，节省的内存准备成本可能被其他开销淹没。固定缓冲区的优势集中在高频、可复用的小 I/O。

固定缓冲区与 provided buffer ring 有什么区别？

固定缓冲区由应用预先注册一组长期可用内存，并通过索引做固定读写；provided buffer ring 更偏向把一组可供接收操作选择的缓冲区交给 ring 管理。两者是不同机制，接口和适用的请求类型也不同。