跳转到内容

std.os.linux.IoUring

标准库Zig 0.17.1官方原文
源码std/os/linux/IoUring.zig

第 1 行

字段

fd: linux.fd_t = -1
sq: SubmissionQueue
cq: CompletionQueue
flags: u32
features: u32

std.os.linux.IoUring.accept

函数

第 508 行

排入(但不提交)一个 SQE,以在套接字上执行 accept4(2)。 返回 SQE 指针。 自 5.5 起可用

pub fn accept( self: *IoUring, user_data: u64, fd: linux.fd_t, addr: ?*posix.sockaddr, addrlen: ?*posix.socklen_t, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
addr: ?*posix.sockaddr
addrlen: ?*posix.socklen_t
flags: u32

std.os.linux.IoUring.accept_direct

函数

第 555 行

将使用直接(已注册)文件描述符的 accept 操作加入队列。

要使用 accept 的 direct 变体,应用程序必须先通过 register_files 注册文件表。系统会动态选择未使用的表索引, 并通过 CQE 的 res 字段返回。

创建后,设置 SQE 的 flags 成员中的 IOSQE_FIXED_FILE, 并将 SQE 的 fd 字段设为直接描述符值 而非常规文件描述符,即可使用。

自 5.19 起可用。

pub fn accept_direct( self: *IoUring, user_data: u64, fd: linux.fd_t, addr: ?*posix.sockaddr, addrlen: ?*posix.socklen_t, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
addr: ?*posix.sockaddr
addrlen: ?*posix.socklen_t
flags: u32

std.os.linux.IoUring.accept_multishot

函数

第 530 行

将套接字的多次触发 accept 加入队列。

多次触发变体允许应用程序发出单个 accept 请求,在连接请求到达时反复触发 CQE。 只要 CQE 的 flags 中仍设置 IORING_CQE_F_MORE,accept 就会继续生成更多 CQE。

自 5.19 起可用。

pub fn accept_multishot( self: *IoUring, user_data: u64, fd: linux.fd_t, addr: ?*posix.sockaddr, addrlen: ?*posix.socklen_t, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
addr: ?*posix.sockaddr
addrlen: ?*posix.socklen_t
flags: u32

std.os.linux.IoUring.accept_multishot_direct

函数

第 571 行

使用直接(已注册)文件描述符将多次触发的 accept 操作加入队列。 自 5.19 起可用。

pub fn accept_multishot_direct( self: *IoUring, user_data: u64, fd: linux.fd_t, addr: ?*posix.sockaddr, addrlen: ?*posix.socklen_t, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
addr: ?*posix.sockaddr
addrlen: ?*posix.socklen_t
flags: u32

std.os.linux.IoUring.Allocator

别名

第 8 行

别名目标 std.mem.Allocator

std.os.linux.IoUring.assert

别名

第 9 行

别名目标 std.debug.assert

std.os.linux.IoUring.bind

函数

第 1412 行

排入(但不提交)一个 SQE,以在套接字上执行 bind(2)。 返回 SQE 指针。 自 6.11 起可用

pub fn bind( self: *IoUring, user_data: u64, fd: linux.fd_t, addr: *const posix.sockaddr, addrlen: posix.socklen_t, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
addr: *const posix.sockaddr
addrlen: posix.socklen_t
flags: u32

std.os.linux.IoUring.buf_ring_add

函数

第 1836 行

将 buffer 关联到 br 缓冲区环。 buffer_id 是将在 CQE 中返回的标识。 buffer_offset 是相对于当前尾部的插入偏移量。 若只提供一个缓冲区,再通过 advance 提交环尾,则偏移量应为 0。 若在循环中提供多个缓冲区后统一提交,则每增加一个缓冲区,偏移量必须加一。

pub fn buf_ring_add( br: *linux.io_uring_buf_ring, buffer: []u8, buffer_id: u16, mask: u16, buffer_offset: u16, ) void

参数

br: *linux.io_uring_buf_ring
buffer: []u8
buffer_id: u16
mask: u16
buffer_offset: u16

std.os.linux.IoUring.buf_ring_advance

函数

第 1853 行

使 count 个新缓冲区对内核可见。在调用 io_uring_buf_ring_add 共 count 次以填入新缓冲区后调用。

pub fn buf_ring_advance(br: *linux.io_uring_buf_ring, count: u16) void

参数

br: *linux.io_uring_buf_ring
count: u16

std.os.linux.IoUring.buf_ring_init

函数

第 1821 行

初始化 br,使其可供使用。

pub fn buf_ring_init(br: *linux.io_uring_buf_ring) void

参数

std.os.linux.IoUring.buf_ring_mask

函数

第 1827 行

计算缓冲区环的适当大小掩码。 entries 是 io_uring_register_buf_ring 中指定的环条目数。

pub fn buf_ring_mask(entries: u16) u16

参数

entries: u16

std.os.linux.IoUring.BufferGroup

容器

第 1626 行

应用程序提供的一组缓冲区。使用自内核 5.19 起支持的新类型,称为环映射缓冲区。缓冲区由缓冲区组标识和组内缓冲区标识确定。IO_Uring 可以有多个缓冲区组,每组的组标识必须唯一。

在 init 中,应用程序提供连续内存块 buffers,用于容纳 buffers_count 个大小为 buffers_size 的缓冲区。随后应用程序可以提交 recv 操作,无需预先指定缓冲区。当操作准备好接收数据时,会自动选择一个缓冲区,结果 CQE 的 cqe.buffer_id() 将包含其标识。使用 get 方法获取 CQE 中缓冲区标识所对应的缓冲区。应用程序处理完缓冲区后,可调用 put 将所有权交还内核,从而重复这一循环。

取决于数据到达速率,某个缓冲区组可能在 CQE 中的缓冲区交还内核之前耗尽缓冲区。若发生这种情况,cqe.err() 的错误值为 ENOBUFS。

字段

ring: *IoUring

此组注册到的父环。

br: *align(page_size_min) linux.io_uring_buf_ring

指向与内核共享的内存的指针。 与内核共享 buffers_count 个 io_uring_buf 结构体。 第一个 io_uring_buf 与 io_uring_buf_ring 结构体重叠存放。

buffers: []u8

大小为 (buffers_count * buffer_size) 的连续内存块。

buffer_size: u32

buffers 中每个缓冲区的大小。

buffers_count: u16

buffers 中的缓冲区数量,即 br 中的 io_uring_buf structures 数量。

heads: []u32

启用增量消费时,各缓冲区中未消费部分的起点。

group_id: u16

此组的标识符,必须在环内唯一。

std.os.linux.IoUring.BufferGroup.deinit

函数

第 1680 行

pub fn deinit(self: *BufferGroup, allocator: Allocator) void

参数

self: *BufferGroup
allocator: Allocator

std.os.linux.IoUring.BufferGroup.get

函数

第 1711 行

pub fn get(self: *BufferGroup, cqe: linux.io_uring_cqe) ![]u8

参数

std.os.linux.IoUring.BufferGroup.get_by_id

函数

第 1705 行

pub fn get_by_id(self: *BufferGroup, buffer_id: u16) []u8

参数

self: *BufferGroup
buffer_id: u16

std.os.linux.IoUring.BufferGroup.init

函数

第 1644 行

pub fn init( ring: *IoUring, allocator: Allocator, group_id: u16, buffer_size: u32, buffers_count: u16, ) !BufferGroup

参数

ring: *IoUring
allocator: Allocator
group_id: u16
buffer_size: u32
buffers_count: u16

std.os.linux.IoUring.BufferGroup.put

函数

第 1718 行

pub fn put(self: *BufferGroup, cqe: linux.io_uring_cqe) !void

参数

std.os.linux.IoUring.BufferGroup.recv

函数

第 1687 行

pub fn recv(self: *BufferGroup, user_data: u64, fd: linux.fd_t, flags: u32) !*linux.io_uring_sqe

参数

self: *BufferGroup
user_data: u64
fd: linux.fd_t
flags: u32

std.os.linux.IoUring.BufferGroup.recv_multishot

函数

第 1698 行

pub fn recv_multishot(self: *BufferGroup, user_data: u64, fd: linux.fd_t, flags: u32) !*linux.io_uring_sqe

参数

self: *BufferGroup
user_data: u64
fd: linux.fd_t
flags: u32

std.os.linux.IoUring.builtin

常量

第 3 行

std.os.linux.IoUring.cancel

函数

第 985 行

将移除现有操作的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。

通过 user_data 标识操作。

若找到操作并成功取消,完成事件结果为 0;若找到操作但已在执行,结果为 -EALREADY;若未找到操作,结果为 -ENOENT。

pub fn cancel( self: *IoUring, user_data: u64, cancel_user_data: u64, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
cancel_user_data: u64
flags: u32

std.os.linux.IoUring.close

函数

第 811 行

将用于执行 close(2) 的 SQE 加入队列(但不提交)。 返回指向该 SQE 的指针。 自 5.6 起可用。

pub fn close(self: *IoUring, user_data: u64, fd: linux.fd_t) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t

std.os.linux.IoUring.close_direct

函数

第 820 行

将关闭已注册文件描述符的操作加入队列。 自 5.15 起可用

pub fn close_direct(self: *IoUring, user_data: u64, file_index: u32) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
file_index: u32

std.os.linux.IoUring.cmd_sock

函数

第 1445 行

为套接字准备 cmd 请求。 参见:https://man7.org/linux/man-pages/man3/io_uring_prep_cmd.3.html 自 6.7 起可用。

pub fn cmd_sock( self: *IoUring, user_data: u64, cmd_op: linux.IO_URING_SOCKET_OP, fd: linux.fd_t, level: u32,optname: u32,optval: u64,optlen: u32,) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
cmd_op: linux.IO_URING_SOCKET_OP
fd: linux.fd_t
level: u32
optname: u32
optval: u64
optlen: u32

std.os.linux.IoUring.CompletionQueue

容器

第 1579 行

字段

head: *u32
tail: *u32
mask: u32
overflow: *u32
cqes: []linux.io_uring_cqe

std.os.linux.IoUring.CompletionQueue.deinit

函数

第 1601 行

pub fn deinit(self: *CompletionQueue) void

参数

std.os.linux.IoUring.CompletionQueue.init

函数

第 1586 行

pub fn init(fd: linux.fd_t, p: linux.io_uring_params, sq: SubmissionQueue) !CompletionQueue

参数

std.os.linux.IoUring.connect

函数

第 587 行

将对套接字执行 connect(2) 的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。

pub fn connect( self: *IoUring, user_data: u64, fd: linux.fd_t, addr: *const posix.sockaddr, addrlen: posix.socklen_t, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
addr: *const posix.sockaddr
addrlen: posix.socklen_t

std.os.linux.IoUring.copy_cqe

函数

第 310 行

返回 I/O 完成项的副本,必要时等待,并推进 CQ 环。 这是 copy_cqes() 的便利方法,适用于无需批处理或窥视的情况。

pub fn copy_cqe(ring: *IoUring) !linux.io_uring_cqe

参数

ring: *IoUring

std.os.linux.IoUring.copy_cqes

函数

第 279 行

复制尽可能多的已就绪 CQE,但不超过目标 cqes 切片容量。 如果没有可用 CQE,则进入内核,等待至少 wait_nr 个 CQE。 返回复制的 CQE 数量,并推进 CQ 环。 此方法以批处理形式,通过一个方法提供 liburing 的所有等待/探测功能。 复制 CQE 而不是复制指针的原因是:指针占 8 字节,而 CQE 仅占 16 字节,相差不大,且这样可以提供更安全、更快的接口。 更安全,是因为不再需要调用 cqe_seen(),从而避免幂等性错误。 更快,是因为可以将对 cq.head 的原子释放存储操作摊销到整个批次。 另见 https://github.com/axboe/liburing/issues/103#issuecomment-686665007. 与 liburing 中 io_uring_peek_batch_cqe() 的实现相同,但支持等待。

pub fn copy_cqes(self: *IoUring, cqes: []linux.io_uring_cqe, wait_nr: u32) !u32

参数

self: *IoUring
cqes: []linux.io_uring_cqe
wait_nr: u32

std.os.linux.IoUring.copy_cqes_ready

函数

第 289 行

fn copy_cqes_ready(self: *IoUring, cqes: []linux.io_uring_cqe) u32

参数

self: *IoUring
cqes: []linux.io_uring_cqe

std.os.linux.IoUring.cq_advance

函数

第 335 行

仅供实现自定义完成队列方法的高级场景使用。 与 liburing 中 cq_advance() 的实现一致。

pub fn cq_advance(self: *IoUring, count: u32) void

参数

self: *IoUring
count: u32

std.os.linux.IoUring.cq_ready

函数

第 265 行

返回完成队列中的 CQE 数量,即队列长度。 这些 CQE 尚未被应用程序消费。 与 liburing 中 io_uring_cq_ready 的实现一致。

pub fn cq_ready(self: *IoUring) u32

参数

self: *IoUring

std.os.linux.IoUring.cq_ring_needs_flush

函数

第 319 行

与 liburing 中 cq_ring_needs_flush() 的实现一致。

pub fn cq_ring_needs_flush(self: *IoUring) bool

参数

self: *IoUring

std.os.linux.IoUring.cqe_seen

函数

第 328 行

仅适用于实现自定义完成队列方法的高级用例。 若使用 copy_cqes() 或 copy_cqe(),不得调用 cqe_seen() 或 cq_advance()。 应用程序处理完零拷贝 CQE 后,必须且只能调用一次。 不是幂等操作;调用多次会导致其他 CQE 丢失。 与 liburing 中 cqe_seen() 的实现一致。

pub fn cqe_seen(self: *IoUring, cqe: *linux.io_uring_cqe) void

参数

self: *IoUring
cqe: *linux.io_uring_cqe

std.os.linux.IoUring.createSocketTestHarness

常量

第 14 行

std.os.linux.IoUring.deinit

函数

第 123 行

pub fn deinit(self: *IoUring) void

参数

self: *IoUring

std.os.linux.IoUring.enter

函数

第 178 行

通知内核已提交 SQE,和/或希望等待 CQE。 返回已提交的 SQE 数量。

pub fn enter(self: *IoUring, to_submit: u32, min_complete: u32, flags: u32) !u32

参数

self: *IoUring
to_submit: u32
min_complete: u32
flags: u32

std.os.linux.IoUring.epoll_ctl

函数

第 602 行

将用于执行 epoll_ctl(2) 的 SQE 加入队列(但不提交)。 返回指向该 SQE 的指针。

pub fn epoll_ctl( self: *IoUring, user_data: u64, epfd: linux.fd_t, fd: linux.fd_t, op: u32, ev: ?*linux.epoll_event, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
epfd: linux.fd_t
fd: linux.fd_t
op: u32
ev: ?*linux.epoll_event

std.os.linux.IoUring.fallocate

函数

第 946 行

将用于执行 fallocate(2) 的 SQE 加入队列(但不提交)。 返回指向该 SQE 的指针。

pub fn fallocate( self: *IoUring, user_data: u64, fd: linux.fd_t, mode: i32, offset: u64, len: u64, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
mode: i32
offset: u64
len: u64

std.os.linux.IoUring.flush_sq

函数

第 221 行

在 SQ 一侧将内部状态与内核环状态同步。 返回共享 SQ 环中所有待处理事件的数量。 与 liburing 相同,返回值包括此前已刷新的 SQE。 理由是应倾向于提示需要调用 io_uring_enter(),而非不需要。 与 liburing 中 __io_uring_flush_sq() 的实现一致。

pub fn flush_sq(self: *IoUring) u32

参数

self: *IoUring

std.os.linux.IoUring.free_buf_ring

函数

第 1812 行

pub fn free_buf_ring(fd: linux.fd_t, br: *align(page_size_min) linux.io_uring_buf_ring, entries: u32, group_id: u16) void

参数

fd: linux.fd_t
br: *align(page_size_min) linux.io_uring_buf_ring
entries: u32
group_id: u16

std.os.linux.IoUring.fsync

函数

第 351 行

将执行 fsync(2) 的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针,供高级用法进一步修改。 例如,为执行 fdatasync(),可将 IORING_FSYNC_DATASYNC 设置到 SQE 的 rw_flags 中。 注意:虽然 SQE 按提交队列中的顺序启动, 操作却会并行执行,且完成顺序不固定。因此,应用在 提交队列中先提交写入、再提交 fsync,并不能保证 fsync 作用于该次写入,因为 fsync 可能在写入下发磁盘之前完成。 最好对写入的 SQE 调用 link_with_next_sqe(),将其与 fsync 关联; 否则,应在将 fsync 加入队列时使用 drain_previous_sqes() 插入完整的写屏障。

pub fn fsync(self: *IoUring, user_data: u64, fd: linux.fd_t, flags: u32) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
flags: u32

std.os.linux.IoUring.get_probe

函数

第 1318 行

返回 io_uring_probe,用于探测当前运行内核的 io_uring 子系统能力。io_uring_probe 包含 受支持操作列表。

pub fn get_probe(self: *IoUring) !linux.io_uring_probe

参数

self: *IoUring

std.os.linux.IoUring.get_sqe

函数

第 139 行

返回指向空闲 SQE 的指针;提交队列满时返回错误。 严格遵循 liburing 的 io_uring_get_sqe() 实现,包括原子操作。 但此处返回错误而非空指针,以强制调用方安全处理。 提交队列满通常更像控制流错误; liburing 返回空指针主要是因为 C 语言习惯,缺乏 更好的替代方式。Zig 具备一等错误处理机制,因此应当使用。 与 liburing 中 io_uring_get_sqe() 的实现一致。

pub fn get_sqe(self: *IoUring) !*linux.io_uring_sqe

参数

self: *IoUring

std.os.linux.IoUring.getsockopt

函数

第 1486 行

准备获取套接字选项操作,以读取 fd 参数指定套接字中 option_name 参数指定选项的值。 自 6.7 起可用。

pub fn getsockopt( self: *IoUring, user_data: u64, fd: linux.fd_t, level: u32,optname: u32,opt: []u8, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
level: u32
optname: u32
opt: []u8

std.os.linux.IoUring.handle_register_buf_ring_result

函数

第 1803 行

fn handle_register_buf_ring_result(res: usize) !void

参数

res: usize

std.os.linux.IoUring.handle_registration_result

函数

第 1325 行

fn handle_registration_result(res: usize) !void

参数

res: usize

std.os.linux.IoUring.init

函数

第 27 行

使用默认 linux.io_uring_params 设置 io_uring 的便捷方法。 entries 必须是 1 到 32768 之间的 2 的幂,不过提交队列和完成队列 最终具有多少条目由内核决定, 参见 https://github.com/torvalds/linux/blob/v5.8/fs/io_uring.c#L8027-L8050。 接口与 liburing 中的 io_uring_queue_init() 一致。

pub fn init(entries: u16, flags: u32) !IoUring

参数

entries: u16
flags: u32

std.os.linux.IoUring.init_params

函数

第 39 行

功能更丰富的 io_uring 设置方法,可调整 linux.io_uring_params,例如提交 队列线程的 CPU 亲和性或线程空闲超时;内核和此实现默认均为 1 秒。 params 以引用传递,因为内核需要修改参数。 接口与 liburing 中的 io_uring_queue_init_params() 一致。

pub fn init_params(entries: u16, p: *linux.io_uring_params) !IoUring

参数

entries: u16
p: *linux.io_uring_params

std.os.linux.IoUring.Io

别名

第 7 行

别名目标 std.Io

std.os.linux.IoUring.IoUring

别名

第 1 行

别名目标 std.os.linux.IoUring

std.os.linux.IoUring.is_linux

常量

第 4 行

std.os.linux.IoUring.link_timeout

函数

第 889 行

排入(但不提交)一个 SQE,以添加链接超时操作。 返回该 SQE 的指针。

需要为目标操作的 flags 设置 linux.IOSQE_IO_LINK,随后紧接目标操作调用此方法。 详情见 https://lwn.net/Articles/803932/ 。

若依赖请求先于链接超时完成,则取消超时。若超时先于依赖请求完成,则取消依赖请求。

link_timeout 的完成事件结果在超时先于依赖请求完成时为 -ETIME(此时依赖请求的完成事件结果为 -ECANCELED);在依赖请求先于链接超时完成时为 -EALREADY。

pub fn link_timeout( self: *IoUring, user_data: u64, ts: *const linux.kernel_timespec, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
ts: *const linux.kernel_timespec
flags: u32

std.os.linux.IoUring.linkat

函数

第 1077 行

排入(但不提交)一个 SQE,以执行 linkat(2)。 返回 SQE 指针。

pub fn linkat( self: *IoUring, user_data: u64, old_dir_fd: linux.fd_t, old_path: [*:0]const u8, new_dir_fd: linux.fd_t, new_path: [*:0]const u8, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
old_dir_fd: linux.fd_t
old_path: [*:0]const u8
new_dir_fd: linux.fd_t
new_path: [*:0]const u8
flags: u32

std.os.linux.IoUring.linux

别名

第 11 行

别名目标 std.os.linux

std.os.linux.IoUring.listen

函数

第 1429 行

将用于对套接字执行 listen(2) 的 SQE 加入队列(但不提交)。 返回指向该 SQE 的指针。 自 6.11 起可用

pub fn listen( self: *IoUring, user_data: u64, fd: linux.fd_t, backlog: usize, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
backlog: usize
flags: u32

std.os.linux.IoUring.mkdirat

函数

第 1047 行

将用于执行 mkdirat(2) 的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。

pub fn mkdirat( self: *IoUring, user_data: u64, dir_fd: linux.fd_t, path: [*:0]const u8, mode: posix.mode_t, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
dir_fd: linux.fd_t
path: [*:0]const u8
mode: posix.mode_t

std.os.linux.IoUring.nop

函数

第 363 行

将执行空操作的 SQE 加入队列,但不提交。 返回指向 SQE 的指针,以便进一步修改 SQE 满足高级场景。 空操作比乍看之下更有用。 例如,可对返回的 SQE 调用 drain_previous_sqes(),利用空操作 在处理终止信号前确定环何时已空闲。

pub fn nop(self: *IoUring, user_data: u64) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64

std.os.linux.IoUring.openat

函数

第 768 行

将执行 openat(2) 的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。 自 5.6 起可用。

pub fn openat( self: *IoUring, user_data: u64, fd: linux.fd_t, path: [*:0]const u8, flags: linux.O, mode: posix.mode_t, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
path: [*:0]const u8
flags: linux.O
mode: posix.mode_t

std.os.linux.IoUring.openat_direct

函数

第 793 行

将使用直接文件描述符,即已注册描述符的 openat 加入队列。

使用 accept 的直接变体前,应用必须先通过 register_files 注册文件表。系统会动态选择一个未使用的 表索引,并在 CQE 的 res 字段返回。

创建后,可在 SQE 的 flags 成员中设置 IOSQE_FIXED_FILE, 并将 SQE 的 fd 字段设为直接描述符值, 而非常规文件描述符。

自 5.15 起可用。

pub fn openat_direct( self: *IoUring, user_data: u64, fd: linux.fd_t, path: [*:0]const u8, flags: linux.O, mode: posix.mode_t, file_index: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
path: [*:0]const u8
flags: linux.O
mode: posix.mode_t
file_index: u32

std.os.linux.IoUring.page_size_min

别名

第 13 行

别名目标 std.heap.page_size_min

std.os.linux.IoUring.poll_add

函数

第 903 行

将用于执行 poll(2) 的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。

pub fn poll_add( self: *IoUring, user_data: u64, fd: linux.fd_t, poll_mask: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
poll_mask: u32

std.os.linux.IoUring.poll_remove

函数

第 917 行

将用于移除现有轮询操作的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。

pub fn poll_remove( self: *IoUring, user_data: u64, target_user_data: u64, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
target_user_data: u64

std.os.linux.IoUring.poll_update

函数

第 930 行

排入(但不提交)一个 SQE,以更新现有 poll 操作的用户数据。返回 SQE 指针。

pub fn poll_update( self: *IoUring, user_data: u64, old_user_data: u64, new_user_data: u64, poll_mask: u32, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
old_user_data: u64
new_user_data: u64
poll_mask: u32
flags: u32

std.os.linux.IoUring.posix

别名

第 10 行

别名目标 std.posix

std.os.linux.IoUring.provide_buffers

函数

第 1098 行

将提供一组缓冲区的 SQE 加入队列,供读取或接收数据的命令使用,但不提交。 返回指向 SQE 的指针。

可在 read、recv 或 recvmsg 命令中通过 .buffer_selection 使用所提供的缓冲区。

内核要求一块大小为 buffers_count * buffer_size 的连续内存。

pub fn provide_buffers( self: *IoUring, user_data: u64, buffers: [*]u8, buffer_size: usize, buffers_count: usize, group_id: usize, buffer_id: usize, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
buffers: [*]u8
buffer_size: usize
buffers_count: usize
group_id: usize
buffer_id: usize

std.os.linux.IoUring.read

函数

第 393 行

按缓冲区类型,将执行 read(2) 或 preadv(2) 的 SQE 加入队列,但不提交。

返回指向该 SQE 的指针。

pub fn read( self: *IoUring, user_data: u64, fd: linux.fd_t, buffer: ReadBuffer, offset: u64, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
buffer: ReadBuffer
offset: u64

std.os.linux.IoUring.read_fixed

函数

第 455 行

将执行 IORING_OP_READ_FIXED 的 SQE 加入队列,但不提交。 提供的 buffer 必须先通过调用 register_buffers 向内核注册。 buffer_index 必须与其在传给 register_buffers 的数组中的索引一致。

返回指向 SQE 的指针,以便进一步修改 SQE 满足高级场景。

pub fn read_fixed( self: *IoUring, user_data: u64, fd: linux.fd_t, buffer: *posix.iovec, offset: u64, buffer_index: u16, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
buffer: *posix.iovec
offset: u64
buffer_index: u16

std.os.linux.IoUring.ReadBuffer

容器

第 371 行

用于选择如何处理读取。

字段

buffer: []u8

io_uring 将直接读取到此缓冲区中

iovecs: []const posix.iovec

io_uring 将使用 readv 直接读入这些缓冲区。

buffer_selection: struct {
    group_id: u16,
    len: usize,
}

io_uring 将选择之前通过 provide_buffers 提供的缓冲区。 通过 group_id 引用的缓冲区组必须至少包含一个缓冲区,读取才能正常执行。 len 控制要读入所选缓冲区的字节数。

std.os.linux.IoUring.recv

函数

第 633 行

将执行 recv(2) 的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。 自 5.6 起可用。

pub fn recv( self: *IoUring, user_data: u64, fd: linux.fd_t, buffer: RecvBuffer, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
buffer: RecvBuffer
flags: u32

std.os.linux.IoUring.RecvBuffer

容器

第 617 行

用于选择 recv 调用的处理方式。

字段

buffer: []u8

io_uring 将直接接收到此缓冲区

buffer_selection: struct {
    group_id: u16,
    len: usize,
}

io_uring 将选择一个先前通过 provide_buffers 提供的缓冲区。 group_id 引用的缓冲区组必须至少包含一个缓冲区,recv 调用才能工作。 len 控制要读入所选缓冲区的字节数。

std.os.linux.IoUring.recvmsg

函数

第 720 行

将用于执行 recvmsg(2) 的 SQE 加入队列(但不提交)。 返回指向该 SQE 的指针。 自 5.3 起可用

pub fn recvmsg( self: *IoUring, user_data: u64, fd: linux.fd_t, msg: *linux.msghdr, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
msg: *linux.msghdr
flags: u32

std.os.linux.IoUring.register_buf_ring

函数

第 1767 行

fn register_buf_ring( fd: linux.fd_t, addr: u64, entries: u32, group_id: u16, flags: linux.io_uring_buf_reg.Flags, ) !void

参数

fd: linux.fd_t
addr: u64
entries: u32
group_id: u16
flags: linux.io_uring_buf_reg.Flags

std.os.linux.IoUring.register_buffers

函数

第 1293 行

注册供 read_fixed 和 write_fixed 使用的缓冲区数组。

pub fn register_buffers(self: *IoUring, buffers: []const posix.iovec) !void

参数

self: *IoUring
buffers: []const posix.iovec

std.os.linux.IoUring.register_eventfd

函数

第 1242 行

注册 eventfd 的文件描述符,用于接收 io_uring 实例 完成事件的通知。 任一时刻只能注册一个 eventfd。

pub fn register_eventfd(self: *IoUring, fd: linux.fd_t) !void

参数

self: *IoUring
fd: linux.fd_t

std.os.linux.IoUring.register_eventfd_async

函数

第 1257 行

注册 eventfd 的文件描述符,以接收 io_uring 实例的完成事件通知。仅对异步完成的事件发送通知。 因此,提交过程中直接内联完成的事件不会触发通知。 任意时刻只能注册一个 eventfd。

pub fn register_eventfd_async(self: *IoUring, fd: linux.fd_t) !void

参数

self: *IoUring
fd: linux.fd_t

std.os.linux.IoUring.register_file_alloc_range

函数

第 1220 行

pub fn register_file_alloc_range(self: *IoUring, offset: u32, len: u32) !void

参数

self: *IoUring
offset: u32
len: u32

std.os.linux.IoUring.register_files

函数

第 1154 行

注册文件描述符数组。 每次将文件描述符放入 SQE 并提交给内核,内核都必须获取对应文件的引用,I/O 完成后再释放该引用。文件引用的原子操作可能拖慢高 IOPS 工作负载。预先注册文件描述符可以避免这一开销。 引用已注册的文件描述符时,必须在 SQE 的 flags 中设置 IOSQE_FIXED_FILE,并将 SQE 的 fd 设为该描述符在已注册数组中的索引。 注册文件描述符会等待环进入空闲状态。 销毁环时,内核会自动注销文件。 应用程序只有在需要注册新的文件描述符数组时,才需要主动注销。

pub fn register_files(self: *IoUring, fds: []const linux.fd_t) !void

参数

self: *IoUring
fds: []const linux.fd_t

std.os.linux.IoUring.register_files_sparse

函数

第 1197 行

注册一个包含 nr_files 个文件描述符的空(-1)文件表。

pub fn register_files_sparse(self: *IoUring, nr_files: u32) !void

参数

self: *IoUring
nr_files: u32

std.os.linux.IoUring.register_files_update

函数

第 1173 行

更新已注册的文件描述符。

从原文件描述符切片中给定偏移开始应用更新。 更新有三种:

  • 将稀疏条目,即 fd 为 -1 的条目,变为实际条目;
  • 移除已有条目,将 fd 设为 -1;
  • 用新 fd 替换已有条目。 添加新的文件描述符必须使用 register_files。
pub fn register_files_update(self: *IoUring, offset: u32, fds: []const linux.fd_t) !void

参数

self: *IoUring
offset: u32
fds: []const linux.fd_t

std.os.linux.IoUring.register_napi

函数

第 1280 行

pub fn register_napi(self: *IoUring, napi: *linux.io_uring_napi) !void

参数

self: *IoUring
napi: *linux.io_uring_napi

std.os.linux.IoUring.remove_buffers

函数

第 1115 行

将用于移除一组已提供缓冲区的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。

pub fn remove_buffers( self: *IoUring, user_data: u64, buffers_count: usize, group_id: usize, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
buffers_count: usize
group_id: usize

std.os.linux.IoUring.renameat

函数

第 1015 行

将执行 renameat2(2) 的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。

pub fn renameat( self: *IoUring, user_data: u64, old_dir_fd: linux.fd_t, old_path: [*:0]const u8, new_dir_fd: linux.fd_t, new_path: [*:0]const u8, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
old_dir_fd: linux.fd_t
old_path: [*:0]const u8
new_dir_fd: linux.fd_t
new_path: [*:0]const u8
flags: u32

std.os.linux.IoUring.send

函数

第 657 行

将执行 send(2) 的 SQE 加入队列,但不提交。 返回指向 SQE 的指针。 从 5.6 起可用。

pub fn send( self: *IoUring, user_data: u64, fd: linux.fd_t, buffer: []const u8, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
buffer: []const u8
flags: u32

std.os.linux.IoUring.send_zc

函数

第 685 行

将执行异步零拷贝 send(2) 的 SQE 加入队列,但不提交。

此操作极有可能产生两个 CQE。第一个 CQE 的 flags 字段可能包含 IORING_CQE_F_MORE,表示还会有第二个 CQE,且其 user_data 字段具有相同的值。通知发布之前,用户不得修改数据缓冲区。第一个 CQE 遵循通常规则,因此其 res 字段包含已发送的字节数或负错误码。通知的 res 字段设为零,flags 字段包含 IORING_CQE_F_NOTIF。之所以需要两阶段模型,是因为内核可能长时间持有缓冲区,例如等待 TCP ACK。通知负责控制缓冲区生命周期。即使请求出错,也可能产生通知。

自 6.0 起可用。

pub fn send_zc( self: *IoUring, user_data: u64, fd: linux.fd_t, buffer: []const u8, send_flags: u32, zc_flags: u16, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
buffer: []const u8
send_flags: u32
zc_flags: u16

std.os.linux.IoUring.send_zc_fixed

函数

第 702 行

将用于异步零复制 send(2) 的 SQE 加入队列,但不提交。 返回指向 SQE 的指针。 从 6.0 起可用。

pub fn send_zc_fixed( self: *IoUring, user_data: u64, fd: linux.fd_t, buffer: []const u8, send_flags: u32, zc_flags: u16, buf_index: u16, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
buffer: []const u8
send_flags: u32
zc_flags: u16
buf_index: u16

std.os.linux.IoUring.sendmsg

函数

第 736 行

将执行 sendmsg(2) 的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。 自 5.3 起可用。

pub fn sendmsg( self: *IoUring, user_data: u64, fd: linux.fd_t, msg: *const linux.msghdr_const, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
msg: *const linux.msghdr_const
flags: u32

std.os.linux.IoUring.sendmsg_zc

函数

第 752 行

排入(但不提交)一个 SQE,以执行异步零复制 sendmsg(2)。 返回 SQE 指针。 自 6.1 起可用

pub fn sendmsg_zc( self: *IoUring, user_data: u64, fd: linux.fd_t, msg: *const linux.msghdr_const, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
msg: *const linux.msghdr_const
flags: u32

std.os.linux.IoUring.setsockopt

函数

第 1464 行

在 level 参数指定的协议层,准备设置 optname 参数指定的套接字选项。 从 6.7.n 起可用。

pub fn setsockopt( self: *IoUring, user_data: u64, fd: linux.fd_t, level: u32,optname: u32,opt: []const u8, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
level: u32
optname: u32
opt: []const u8

std.os.linux.IoUring.setup_buf_ring

函数

第 1741 行

注册用于提供缓冲区的共享缓冲区环。 映射 entries 个 io_uring_buf 结构体,并与内核共享。 fd 为所注册缓冲区环对应的 IO_Uring.fd。 entries 为请求的缓冲区环条目数,必须是二的幂。 group_id 为选定的缓冲区组 ID,在 IO_Uring 中唯一。

pub fn setup_buf_ring( fd: linux.fd_t, entries: u16, group_id: u16, flags: linux.io_uring_buf_reg.Flags, ) !*align(page_size_min) linux.io_uring_buf_ring

参数

fd: linux.fd_t
entries: u16
group_id: u16
flags: linux.io_uring_buf_reg.Flags

std.os.linux.IoUring.shutdown

函数

第 1001 行

排入(但不提交)一个 SQE,以执行 shutdown(2)。 返回 SQE 指针。

该操作由其 user_data 标识。

pub fn shutdown( self: *IoUring, user_data: u64, sockfd: posix.socket_t, how: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
sockfd: posix.socket_t
how: u32

std.os.linux.IoUring.socket

函数

第 1361 行

准备创建套接字的请求。 新套接字的 fd 将在完成结果中返回。 自 5.19 起可用

pub fn socket( self: *IoUring, user_data: u64, domain: u32, socket_type: u32, protocol: u32, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
domain: u32
socket_type: u32
protocol: u32
flags: u32

std.os.linux.IoUring.socket_direct

函数

第 1377 行

为索引 file_index 处的已注册文件准备套接字创建请求。 自 5.19 起可用。

pub fn socket_direct( self: *IoUring, user_data: u64, domain: u32, socket_type: u32, protocol: u32, flags: u32, file_index: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
domain: u32
socket_type: u32
protocol: u32
flags: u32
file_index: u32

std.os.linux.IoUring.socket_direct_alloc

函数

第 1395 行

为注册文件准备套接字创建请求,由内核选择索引(文件索引分配)。 文件索引将在 CQE 的 res 字段返回。 自 5.19 起可用。

pub fn socket_direct_alloc( self: *IoUring, user_data: u64, domain: u32, socket_type: u32, protocol: u32, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
domain: u32
socket_type: u32
protocol: u32
flags: u32

std.os.linux.IoUring.splice

函数

第 443 行

排入(但不提交)一个 SQE,以执行 splice(2)。 fd_in 或 fd_out 必须有一个是管道。 若 fd_in 指向管道,则忽略 off_in,且必须将其设为 std.math.maxInt(u64)。 若 fd_in 不指向管道且 off_in 为 maxInt(u64),则从 fd_in 的文件偏移处读取 len 个字节;文件偏移会按读取的字节数递增。 若 fd_in 不指向管道且 off_in 不为 maxInt(u64),则 fd_in 的起始偏移为 off_in。 此 splice 操作可用于实现 sendfile:先 splice 到中间管道,再 splice 到最终目标。事实上,内核中的 sendfile 实现内部就使用 splice。

注意,即使 fd_in 或 fd_out 指向管道,如果其中一个 fd 未明确支持 splice 操作,该操作仍可能以 EINVAL 失败。例如,在内核 5.7 至 5.11 中,不支持从终端读取。 另见 https://github.com/axboe/liburing/issues/291

返回 SQE 指针,以便在高级用例中进一步修改该 SQE。

pub fn splice(self: *IoUring, user_data: u64, fd_in: linux.fd_t, off_in: u64, fd_out: linux.fd_t, off_out: u64, len: usize) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd_in: linux.fd_t
off_in: u64
fd_out: linux.fd_t
off_out: u64
len: usize

std.os.linux.IoUring.sq_ready

函数

第 256 行

返回提交队列中待处理的已刷出和未刷出的 SQE 总数。 换言之,这是提交队列中的 SQE 数量,即队列长度。 这些 SQE 尚未被内核消费。 与 liburing 中 io_uring_sq_ready 的实现一致。

pub fn sq_ready(self: *IoUring) u32

参数

self: *IoUring

std.os.linux.IoUring.sq_ring_needs_enter

函数

第 242 行

若未使用 SQ 线程,即只有当前调用方会提交,或者设置了 IORING_SQ_NEED_WAKEUP、必须显式唤醒 SQ 线程,则返回 true。 对于后一种情况,会设置 SQ 线程唤醒标志。 与 liburing 中 sq_ring_needs_enter() 的实现一致。

pub fn sq_ring_needs_enter(self: *IoUring, flags: *u32) bool

参数

self: *IoUring
flags: *u32

std.os.linux.IoUring.statx

函数

第 962 行

将用于执行 statx(2) 的 SQE 加入队列(但不提交)。 返回指向该 SQE 的指针。

pub fn statx( self: *IoUring, user_data: u64, fd: linux.fd_t, path: [:0]const u8, flags: u32, mask: linux.STATX, buf: *linux.Statx, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
path: [:0]const u8
flags: u32
mask: linux.STATX
buf: *linux.Statx

std.os.linux.IoUring.std

别名

第 6 行

别名目标 std

std.os.linux.IoUring.SubmissionQueue

容器

第 1505 行

字段

head: *u32
tail: *u32
mask: u32
flags: *u32
dropped: *u32
array: []u32
sqes: []linux.io_uring_sqe
mmap: []align(page_size_min) u8
mmap_sqes: []align(page_size_min) u8
sqe_head: u32 = 0
sqe_tail: u32 = 0

std.os.linux.IoUring.SubmissionQueue.deinit

函数

第 1573 行

pub fn deinit(self: *SubmissionQueue) void

参数

std.os.linux.IoUring.SubmissionQueue.init

函数

第 1523 行

pub fn init(fd: linux.fd_t, p: linux.io_uring_params) !SubmissionQueue

参数

std.os.linux.IoUring.submit

函数

第 157 行

将通过 get_sqe() 获取的 SQE 提交给内核。可多次调用 get_sqe() 设置多个 I/O 请求,再统一调用一次此函数。 未配合 IORING_SETUP_SQPOLL 使用时,返回提交的 SQE 数量。 若 io_uring 实例使用 IORING_SETUP_SQPOLL,成功时的返回值不保证等于此次调用实际提交的 SQE 数量,可能更大或更小,也可能为 0。 与 liburing 中 io_uring_submit() 的实现一致。

pub fn submit(self: *IoUring) !u32

参数

self: *IoUring

std.os.linux.IoUring.submit_and_wait

函数

第 164 行

类似 submit(),但也允许等待事件。 返回提交的 SQE 数量。 与 liburing 中 io_uring_submit_and_wait() 的实现一致。

pub fn submit_and_wait(self: *IoUring, wait_nr: u32) !u32

参数

self: *IoUring
wait_nr: u32

std.os.linux.IoUring.symlinkat

函数

第 1062 行

将用于执行 symlinkat(2) 的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。

pub fn symlinkat( self: *IoUring, user_data: u64, target: [*:0]const u8, new_dir_fd: linux.fd_t, link_path: [*:0]const u8, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
target: [*:0]const u8
new_dir_fd: linux.fd_t
link_path: [*:0]const u8

std.os.linux.IoUring.testing

别名

第 12 行

别名目标 std.testing

std.os.linux.IoUring.timeout

函数

第 840 行

将注册超时操作的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。

超时到期时完成;若 count 大于 0,也会在指定数量的 事件完成后完成。

flags 可以为 0 表示相对超时,或为 IORING_TIMEOUT_ABS 表示绝对超时。

若因到期而完成,完成事件结果为 -ETIME; 若在指定数量事件完成后完成,则为 0;若超时到期前 被移除,则为 -ECANCELED。

io_uring 超时使用 CLOCK.MONOTONIC 时钟源。

pub fn timeout( self: *IoUring, user_data: u64, ts: *const linux.kernel_timespec, count: u32, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
ts: *const linux.kernel_timespec
count: u32
flags: u32

std.os.linux.IoUring.timeout_remove

函数

第 861 行

将移除已有超时操作的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。

超时通过其 user_data 标识。

如果找到超时并成功取消,完成事件结果为 0; 如果找到超时但到期处理已开始,则为 -EBUSY; 如果找不到超时,则为 -ENOENT。

pub fn timeout_remove( self: *IoUring, user_data: u64, timeout_user_data: u64, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
timeout_user_data: u64
flags: u32

std.os.linux.IoUring.unlinkat

函数

第 1032 行

将用于执行 unlinkat(2) 的 SQE 加入队列(但不提交)。 返回指向该 SQE 的指针。

pub fn unlinkat( self: *IoUring, user_data: u64, dir_fd: linux.fd_t, path: [*:0]const u8, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
dir_fd: linux.fd_t
path: [*:0]const u8
flags: u32

std.os.linux.IoUring.unregister_buf_ring

函数

第 1790 行

fn unregister_buf_ring(fd: linux.fd_t, group_id: u16) !void

参数

fd: linux.fd_t
group_id: u16

std.os.linux.IoUring.unregister_buffers

函数

第 1305 行

注销已注册的缓冲区。

pub fn unregister_buffers(self: *IoUring) !void

参数

self: *IoUring

std.os.linux.IoUring.unregister_eventfd

函数

第 1269 行

注销已注册的 eventfd 文件描述符。

pub fn unregister_eventfd(self: *IoUring) !void

参数

self: *IoUring

std.os.linux.IoUring.unregister_files

函数

第 1348 行

注销先前与环关联的所有已注册文件描述符。

pub fn unregister_files(self: *IoUring) !void

参数

self: *IoUring

std.os.linux.IoUring.unregister_napi

函数

第 1286 行

pub fn unregister_napi(self: *IoUring, napi: *linux.io_uring_napi) !void

参数

self: *IoUring
napi: *linux.io_uring_napi

std.os.linux.IoUring.waitid

函数

第 1129 行

将用于执行 waitid(2) 的 SQE 加入队列,但不提交。 返回指向该 SQE 的指针。

pub fn waitid( self: *IoUring, user_data: u64, id_type: linux.P, id: i32, infop: *linux.siginfo_t, options: u32, flags: u32, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
id_type: linux.P
id: i32
infop: *linux.siginfo_t
options: u32
flags: u32

std.os.linux.IoUring.write

函数

第 416 行

排入(但不提交)一个 SQE,以执行 write(2)。 返回 SQE 指针。

pub fn write( self: *IoUring, user_data: u64, fd: linux.fd_t, buffer: []const u8, offset: u64, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
buffer: []const u8
offset: u64

std.os.linux.IoUring.write_fixed

函数

第 491 行

将执行 IORING_OP_WRITE_FIXED 的 SQE 加入队列,但不提交。 给定 buffer 必须预先通过调用 register_buffers 向内核注册。 buffer_index 必须与其在传给 register_buffers 的数组中的索引相同。

返回指向 SQE 的指针,以便在高级用例中继续修改它。

pub fn write_fixed( self: *IoUring, user_data: u64, fd: linux.fd_t, buffer: *posix.iovec, offset: u64, buffer_index: u16, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
buffer: *posix.iovec
offset: u64
buffer_index: u16

std.os.linux.IoUring.writev

函数

第 473 行

将执行 pwritev() 的 SQE 加入队列,但不提交。 返回指向 SQE 的指针,以便进一步修改 SQE 满足高级场景。 例如,要执行 pwritev2(),请设置返回 SQE 的 rw_flags。 参见 https://linux.die.net/man/2/pwritev。

pub fn writev( self: *IoUring, user_data: u64, fd: linux.fd_t, iovecs: []const posix.iovec_const, offset: u64, ) !*linux.io_uring_sqe

参数

self: *IoUring
user_data: u64
fd: linux.fd_t
iovecs: []const posix.iovec_const
offset: u64
源码

std/os/linux/IoUring.zig

const IoUring = @This();

const builtin = @import("builtin");
const is_linux = builtin.os.tag == .linux;

const std = @import("../../std.zig");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const assert = std.debug.assert;
const posix = std.posix;
const linux = std.os.linux;
const testing = std.testing;
const page_size_min = std.heap.page_size_min;
const createSocketTestHarness = @import("IoUring/test.zig").createSocketTestHarness;

fd: linux.fd_t = -1,
sq: SubmissionQueue,
cq: CompletionQueue,
flags: u32,
features: u32,

/// 使用默认 linux.io_uring_params 设置 io_uring 的便捷方法。
/// `entries` 必须是 1 到 32768 之间的 2 的幂,不过提交队列和完成队列
/// 最终具有多少条目由内核决定,
/// 参见 https://github.com/torvalds/linux/blob/v5.8/fs/io_uring.c#L8027-L8050。
/// 接口与 liburing 中的 io_uring_queue_init() 一致。
pub fn init(entries: u16, flags: u32) !IoUring {
    var params = std.mem.zeroInit(linux.io_uring_params, .{
        .flags = flags,
        .sq_thread_idle = 1000,
    });
    return try IoUring.init_params(entries, &params);
}

/// 功能更丰富的 io_uring 设置方法,可调整 linux.io_uring_params,例如提交
/// 队列线程的 CPU 亲和性或线程空闲超时;内核和此实现默认均为 1 秒。
/// `params` 以引用传递,因为内核需要修改参数。
/// 接口与 liburing 中的 io_uring_queue_init_params() 一致。
pub fn init_params(entries: u16, p: *linux.io_uring_params) !IoUring {
    if (entries == 0) return error.EntriesZero;
    if (!std.math.isPowerOfTwo(entries)) return error.EntriesNotPowerOfTwo;

    assert(p.sq_entries == 0);
    assert(p.cq_entries == 0 or p.flags & linux.IORING_SETUP_CQSIZE != 0);
    assert(p.features == 0);
    assert(p.wq_fd == 0 or p.flags & linux.IORING_SETUP_ATTACH_WQ != 0);
    assert(p.resv[0] == 0);
    assert(p.resv[1] == 0);
    assert(p.resv[2] == 0);

    const res = linux.io_uring_setup(entries, p);
    switch (linux.errno(res)) {
        .SUCCESS => {},
        .FAULT => return error.ParamsOutsideAccessibleAddressSpace,
        // resv 数组包含非零数据;p.flags 包含不受支持的标志;
        // entries 越界;指定 IORING_SETUP_SQ_AFF 却未指定 IORING_SETUP_SQPOLL;
        // 或指定 IORING_SETUP_CQSIZE,但 linux.io_uring_params.cq_entries 无效:
        .INVAL => return error.ArgumentsInvalid,
        .MFILE => return error.ProcessFdQuotaExceeded,
        .NFILE => return error.SystemFdQuotaExceeded,
        .NOMEM => return error.SystemResources,
        // 指定了 IORING_SETUP_SQPOLL,但有效用户 ID 权限不足,或容器 seccomp 策略禁止 io_uring 系统调用:
        //
        .PERM => return error.PermissionDenied,
        .NOSYS => return error.SystemOutdated,
        else => |errno| return posix.unexpectedErrno(errno),
    }
    const fd = @as(linux.fd_t, @intCast(res));
    assert(fd >= 0);
    errdefer _ = linux.close(fd);

    // 内核版本 5.4 及以上仅用一次 mmap() 映射提交队列和完成队列。
    // 这对我们并非可选特性:内核这样处理时,我们也必须如此。
    // 内核开发者的考虑是,提交队列和
    // 完成队列的环大小均略大于二的幂,但使用 u32 槽位的提交队列环
    // 明显更小。将两者打包到一次 mmap 中,内核
    // 便几乎无需额外空间就能容纳提交队列环。
    // 内核补丁见 https://patchwork.kernel.org/patch/11115257 。
    // 我们不支持 5.4 之前的双 mmap(),以保持
    // init/deinit 的 mmap 路径简单;此外,即使 5.4 之后 io_uring 也修复了许多错误。
    if ((p.features & linux.IORING_FEAT_SINGLE_MMAP) == 0) {
        return error.SystemOutdated;
    }

    // 检查内核是否确实设置了 params,确保看似“不可能”的情况没有发生。
    assert(p.sq_entries != 0);
    assert(p.cq_entries != 0);
    assert(p.cq_entries >= p.sq_entries);

    // 自此仅需读取 params,因此将 `p` 按值作为不可变值传递。
    // 完成队列与提交队列共享 mmap,因此也向其传递 `sq`。
    var sq = try SubmissionQueue.init(fd, p.*);
    errdefer sq.deinit();
    var cq = try CompletionQueue.init(fd, p.*, sq);
    errdefer cq.deinit();

    // 检查初始状态是否符合预期。
    assert(sq.head.* == 0);
    assert(sq.tail.* == 0);
    assert(sq.mask == p.sq_entries - 1);
    // 允许 flags.* 非零,因为内核随时可能设置 IORING_SQ_NEED_WAKEUP。
    assert(sq.dropped.* == 0);
    assert(sq.array.len == p.sq_entries);
    assert(sq.sqes.len == p.sq_entries);
    assert(sq.sqe_head == 0);
    assert(sq.sqe_tail == 0);

    assert(cq.head.* == 0);
    assert(cq.tail.* == 0);
    assert(cq.mask == p.cq_entries - 1);
    assert(cq.overflow.* == 0);
    assert(cq.cqes.len == p.cq_entries);

    return IoUring{
        .fd = fd,
        .sq = sq,
        .cq = cq,
        .flags = p.flags,
        .features = p.features,
    };
}

pub fn deinit(self: *IoUring) void {
    assert(self.fd >= 0);
    // mmap 依赖 fd,因此这些调用的顺序很重要:
    self.cq.deinit();
    self.sq.deinit();
    _ = linux.close(self.fd);
    self.fd = -1;
}

/// 返回指向空闲 SQE 的指针;提交队列满时返回错误。
/// 严格遵循 liburing 的 `io_uring_get_sqe()` 实现,包括原子操作。
/// 但此处返回错误而非空指针,以强制调用方安全处理。
/// 提交队列满通常更像控制流错误;
/// liburing 返回空指针主要是因为 C 语言习惯,缺乏
/// 更好的替代方式。Zig 具备一等错误处理机制,因此应当使用。
/// 与 liburing 中 io_uring_get_sqe() 的实现一致。
pub fn get_sqe(self: *IoUring) !*linux.io_uring_sqe {
    const head = @atomicLoad(u32, self.sq.head, .acquire);
    // 记住,这些头部和尾部偏移每四十亿次操作回绕一次。
    // 因此必须使用回绕加减法,避免运行时崩溃。
    const next = self.sq.sqe_tail +% 1;
    if (next -% head > self.sq.sqes.len) return error.SubmissionQueueFull;
    const sqe = &self.sq.sqes[self.sq.sqe_tail & self.sq.mask];
    self.sq.sqe_tail = next;
    return sqe;
}

/// 将通过 get_sqe() 获取的 SQE 提交给内核。可多次调用 get_sqe() 设置多个 I/O 请求,再统一调用一次此函数。
/// 未配合 IORING_SETUP_SQPOLL 使用时,返回提交的 SQE 数量。
/// 若 io_uring 实例使用 IORING_SETUP_SQPOLL,成功时的返回值不保证等于此次调用实际提交的 SQE 数量,可能更大或更小,也可能为 0。
/// 与 liburing 中 io_uring_submit() 的实现一致。
///
///
///
pub fn submit(self: *IoUring) !u32 {
    return self.submit_and_wait(0);
}

/// 类似 submit(),但也允许等待事件。
/// 返回提交的 SQE 数量。
/// 与 liburing 中 io_uring_submit_and_wait() 的实现一致。
pub fn submit_and_wait(self: *IoUring, wait_nr: u32) !u32 {
    const submitted = self.flush_sq();
    var flags: u32 = 0;
    if (self.sq_ring_needs_enter(&flags) or wait_nr > 0) {
        if (wait_nr > 0 or (self.flags & linux.IORING_SETUP_IOPOLL) != 0) {
            flags |= linux.IORING_ENTER_GETEVENTS;
        }
        return try self.enter(submitted, wait_nr, flags);
    }
    return submitted;
}

/// 通知内核已提交 SQE,和/或希望等待 CQE。
/// 返回已提交的 SQE 数量。
pub fn enter(self: *IoUring, to_submit: u32, min_complete: u32, flags: u32) !u32 {
    assert(self.fd >= 0);
    const res = linux.io_uring_enter(self.fd, to_submit, min_complete, flags, null);
    switch (linux.errno(res)) {
        .SUCCESS => {},
        // 内核无法为请求分配内存,或资源已耗尽。
        // 应用程序应等待部分请求完成后重试:
        .AGAIN => return error.SystemResources,
        // SQE `fd` 无效,或者已设置 IOSQE_FIXED_FILE 但未注册任何文件:
        .BADF => return error.FileDescriptorInvalid,
        // 文件描述符有效,但环的状态不正确。
        // 如何启用环,参见 io_uring_register(2)。
        .BADFD => return error.FileDescriptorInBadState,
        // 应用程序尝试提交的挂起请求数超过其可承载数量。
        // 应用程序应等待部分请求完成后重试:
        .BUSY => return error.CompletionQueueOvercommitted,
        // SQE 无效,或有效但环设置了 IORING_SETUP_IOPOLL:
        .INVAL => return error.SubmissionQueueEntryInvalid,
        // 缓冲区位于进程可访问地址空间之外;或指定了 IORING_OP_READ_FIXED
        // 或 IORING_OP_WRITE_FIXED,但未注册缓冲区;或 `addr`
        // 与 `len` 描述的范围不在 `buf_index` 处注册的缓冲区内:
        .FAULT => return error.BufferInvalid,
        .NXIO => return error.RingShuttingDown,
        // 内核认为 `self.fd` 未引用 io_uring 实例,
        // 或操作码有效但当前内核不支持,后者更有可能:
        .OPNOTSUPP => return error.OpcodeNotSupported,
        // 提交工作的线程无效。如果设置了 IORING_ENTER_GETEVENTS
        // 和 IORING_SETUP_DEFER_TASKRUN,但提交线程并非
        // 最初创建或启用与 fd 关联 io_uring 的线程,则可能发生此情况。
        .EXIST => return error.InvalidThread,
        // 操作在完成之前被递送的信号中断。
        // 使用 IORING_ENTER_GETEVENTS 等待事件时可能发生此情况:
        .INTR => return error.SignalInterrupt,
        else => |errno| return posix.unexpectedErrno(errno),
    }
    return @as(u32, @intCast(res));
}

/// 在 SQ 一侧将内部状态与内核环状态同步。
/// 返回共享 SQ 环中所有待处理事件的数量。
/// 与 liburing 相同,返回值包括此前已刷新的 SQE。
/// 理由是应倾向于提示需要调用 io_uring_enter(),而非不需要。
/// 与 liburing 中 __io_uring_flush_sq() 的实现一致。
pub fn flush_sq(self: *IoUring) u32 {
    if (self.sq.sqe_head != self.sq.sqe_tail) {
        // 填充已排队的 SQE,将它们添加到内核环中。
        const to_submit = self.sq.sqe_tail -% self.sq.sqe_head;
        var tail = self.sq.tail.*;
        var i: usize = 0;
        while (i < to_submit) : (i += 1) {
            self.sq.array[tail & self.sq.mask] = self.sq.sqe_head & self.sq.mask;
            tail +%= 1;
            self.sq.sqe_head +%= 1;
        }
        // 确保内核观察到尾部更新时,也确实能观察到 SQE 更新。
        @atomicStore(u32, self.sq.tail, tail, .release);
    }
    return self.sq_ready();
}

/// 若未使用 SQ 线程,即只有当前调用方会提交,或者设置了 IORING_SQ_NEED_WAKEUP、必须显式唤醒 SQ 线程,则返回 true。
/// 对于后一种情况,会设置 SQ 线程唤醒标志。
/// 与 liburing 中 sq_ring_needs_enter() 的实现一致。
///
pub fn sq_ring_needs_enter(self: *IoUring, flags: *u32) bool {
    assert(flags.* == 0);
    if ((self.flags & linux.IORING_SETUP_SQPOLL) == 0) return true;
    if ((@atomicLoad(u32, self.sq.flags, .unordered) & linux.IORING_SQ_NEED_WAKEUP) != 0) {
        flags.* |= linux.IORING_ENTER_SQ_WAKEUP;
        return true;
    }
    return false;
}

/// 返回提交队列中待处理的已刷出和未刷出的 SQE 总数。
/// 换言之,这是提交队列中的 SQE 数量,即队列长度。
/// 这些 SQE 尚未被内核消费。
/// 与 liburing 中 io_uring_sq_ready 的实现一致。
pub fn sq_ready(self: *IoUring) u32 {
    // 始终使用共享环状态(即 head 而非 sqe_head)以避免失步,
    // 参见 https://github.com/axboe/liburing/issues/92.
    return self.sq.sqe_tail -% @atomicLoad(u32, self.sq.head, .acquire);
}

/// 返回完成队列中的 CQE 数量,即队列长度。
/// 这些 CQE 尚未被应用程序消费。
/// 与 liburing 中 io_uring_cq_ready 的实现一致。
pub fn cq_ready(self: *IoUring) u32 {
    return @atomicLoad(u32, self.cq.tail, .acquire) -% self.cq.head.*;
}

/// 复制尽可能多的已就绪 CQE,但不超过目标 `cqes` 切片容量。
/// 如果没有可用 CQE,则进入内核,等待至少 `wait_nr` 个 CQE。
/// 返回复制的 CQE 数量,并推进 CQ 环。
/// 此方法以批处理形式,通过一个方法提供 liburing 的所有等待/探测功能。
/// 复制 CQE 而不是复制指针的原因是:指针占 8 字节,而 CQE 仅占 16 字节,相差不大,且这样可以提供更安全、更快的接口。
/// 更安全,是因为不再需要调用 cqe_seen(),从而避免幂等性错误。
/// 更快,是因为可以将对 `cq.head` 的原子释放存储操作摊销到整个批次。
/// 另见 https://github.com/axboe/liburing/issues/103#issuecomment-686665007.
/// 与 liburing 中 io_uring_peek_batch_cqe() 的实现相同,但支持等待。
///
pub fn copy_cqes(self: *IoUring, cqes: []linux.io_uring_cqe, wait_nr: u32) !u32 {
    const count = self.copy_cqes_ready(cqes);
    if (count > 0) return count;
    if (self.cq_ring_needs_flush() or wait_nr > 0) {
        _ = try self.enter(0, wait_nr, linux.IORING_ENTER_GETEVENTS);
        return self.copy_cqes_ready(cqes);
    }
    return 0;
}

fn copy_cqes_ready(self: *IoUring, cqes: []linux.io_uring_cqe) u32 {
    const ready = self.cq_ready();
    const count = @min(cqes.len, ready);
    const head = self.cq.head.* & self.cq.mask;

    // 回绕之前
    const n = @min(self.cq.cqes.len - head, count);
    @memcpy(cqes[0..n], self.cq.cqes[head..][0..n]);

    if (count > n) {
        // 环绕 self.cq.cqes
        const w = count - n;
        @memcpy(cqes[n..][0..w], self.cq.cqes[0..w]);
    }

    self.cq_advance(count);
    return count;
}

/// 返回 I/O 完成项的副本,必要时等待,并推进 CQ 环。
/// 这是 `copy_cqes()` 的便利方法,适用于无需批处理或窥视的情况。
pub fn copy_cqe(ring: *IoUring) !linux.io_uring_cqe {
    var cqes: [1]linux.io_uring_cqe = undefined;
    while (true) {
        const count = try ring.copy_cqes(&cqes, 1);
        if (count > 0) return cqes[0];
    }
}

/// 与 liburing 中 cq_ring_needs_flush() 的实现一致。
pub fn cq_ring_needs_flush(self: *IoUring) bool {
    return (@atomicLoad(u32, self.sq.flags, .unordered) & linux.IORING_SQ_CQ_OVERFLOW) != 0;
}

/// 仅适用于实现自定义完成队列方法的高级用例。
/// 若使用 copy_cqes() 或 copy_cqe(),不得调用 cqe_seen() 或 cq_advance()。
/// 应用程序处理完零拷贝 CQE 后,必须且只能调用一次。
/// 不是幂等操作;调用多次会导致其他 CQE 丢失。
/// 与 liburing 中 cqe_seen() 的实现一致。
pub fn cqe_seen(self: *IoUring, cqe: *linux.io_uring_cqe) void {
    _ = cqe;
    self.cq_advance(1);
}

/// 仅供实现自定义完成队列方法的高级场景使用。
/// 与 liburing 中 cq_advance() 的实现一致。
pub fn cq_advance(self: *IoUring, count: u32) void {
    if (count > 0) {
        // 确保内核仅在读取 CQE 后看到新的 head 值。
        @atomicStore(u32, self.cq.head, self.cq.head.* +% count, .release);
    }
}

/// 将执行 `fsync(2)` 的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针,供高级用法进一步修改。
/// 例如,为执行 `fdatasync()`,可将 `IORING_FSYNC_DATASYNC` 设置到 SQE 的 `rw_flags` 中。
/// 注意:虽然 SQE 按提交队列中的顺序启动,
/// 操作却会并行执行,且完成顺序不固定。因此,应用在
/// 提交队列中先提交写入、再提交 fsync,并不能保证 fsync
/// 作用于该次写入,因为 fsync 可能在写入下发磁盘之前完成。
/// 最好对写入的 SQE 调用 `link_with_next_sqe()`,将其与 fsync 关联;
/// 否则,应在将 fsync 加入队列时使用 `drain_previous_sqes()` 插入完整的写屏障。
pub fn fsync(self: *IoUring, user_data: u64, fd: linux.fd_t, flags: u32) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_fsync(fd, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将执行空操作的 SQE 加入队列,但不提交。
/// 返回指向 SQE 的指针,以便进一步修改 SQE 满足高级场景。
/// 空操作比乍看之下更有用。
/// 例如,可对返回的 SQE 调用 `drain_previous_sqes()`,利用空操作
/// 在处理终止信号前确定环何时已空闲。
pub fn nop(self: *IoUring, user_data: u64) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_nop();
    sqe.user_data = user_data;
    return sqe;
}

/// 用于选择如何处理读取。
pub const ReadBuffer = union(enum) {
    /// io_uring 将直接读取到此缓冲区中
    buffer: []u8,

    /// io_uring 将使用 readv 直接读入这些缓冲区。
    iovecs: []const posix.iovec,

    /// io_uring 将选择之前通过 `provide_buffers` 提供的缓冲区。
    /// 通过 `group_id` 引用的缓冲区组必须至少包含一个缓冲区,读取才能正常执行。
    /// `len` 控制要读入所选缓冲区的字节数。
    buffer_selection: struct {
        group_id: u16,
        len: usize,
    },
};

/// 按缓冲区类型,将执行 `read(2)` 或 `preadv(2)` 的 SQE 加入队列,但不提交。
/// * 读取到 `ReadBuffer.buffer` 使用 `read(2)`
/// * 读取到 `ReadBuffer.iovecs` 使用 `preadv(2)`
///   若要执行 `preadv2(2)`,请设置返回 SQE 的 `rw_flags`。参见 https://man7.org/linux/man-pages/man2/preadv2.2.html
///
/// 返回指向该 SQE 的指针。
pub fn read(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    buffer: ReadBuffer,
    offset: u64,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    switch (buffer) {
        .buffer => |slice| sqe.prep_read(fd, slice, offset),
        .iovecs => |vecs| sqe.prep_readv(fd, vecs, offset),
        .buffer_selection => |selection| {
            sqe.prep_rw(.READ, fd, 0, selection.len, offset);
            sqe.flags |= linux.IOSQE_BUFFER_SELECT;
            sqe.buf_index = selection.group_id;
        },
    }
    sqe.user_data = user_data;
    return sqe;
}

/// 排入(但不提交)一个 SQE,以执行 `write(2)`。
/// 返回 SQE 指针。
pub fn write(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    buffer: []const u8,
    offset: u64,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_write(fd, buffer, offset);
    sqe.user_data = user_data;
    return sqe;
}

/// 排入(但不提交)一个 SQE,以执行 `splice(2)`。
/// `fd_in` 或 `fd_out` 必须有一个是管道。
/// 若 `fd_in` 指向管道,则忽略 `off_in`,且必须将其设为 std.math.maxInt(u64)。
/// 若 `fd_in` 不指向管道且 `off_in` 为 maxInt(u64),则从 `fd_in` 的文件偏移处读取 `len` 个字节;文件偏移会按读取的字节数递增。
/// 若 `fd_in` 不指向管道且 `off_in` 不为 maxInt(u64),则 `fd_in` 的起始偏移为 `off_in`。
/// 此 splice 操作可用于实现 sendfile:先 splice 到中间管道,再 splice 到最终目标。事实上,内核中的 sendfile 实现内部就使用 splice。
///
/// 注意,即使 fd_in 或 fd_out 指向管道,如果其中一个 fd 未明确支持 splice 操作,该操作仍可能以 EINVAL 失败。例如,在内核 5.7 至 5.11 中,不支持从终端读取。
/// 另见 https://github.com/axboe/liburing/issues/291
///
/// 返回 SQE 指针,以便在高级用例中进一步修改该 SQE。
///
///
///
pub fn splice(self: *IoUring, user_data: u64, fd_in: linux.fd_t, off_in: u64, fd_out: linux.fd_t, off_out: u64, len: usize) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_splice(fd_in, off_in, fd_out, off_out, len);
    sqe.user_data = user_data;
    return sqe;
}

/// 将执行 IORING_OP_READ_FIXED 的 SQE 加入队列,但不提交。
/// 提供的 `buffer` 必须先通过调用 `register_buffers` 向内核注册。
/// `buffer_index` 必须与其在传给 `register_buffers` 的数组中的索引一致。
///
/// 返回指向 SQE 的指针,以便进一步修改 SQE 满足高级场景。
pub fn read_fixed(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    buffer: *posix.iovec,
    offset: u64,
    buffer_index: u16,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_read_fixed(fd, buffer, offset, buffer_index);
    sqe.user_data = user_data;
    return sqe;
}

/// 将执行 `pwritev()` 的 SQE 加入队列,但不提交。
/// 返回指向 SQE 的指针,以便进一步修改 SQE 满足高级场景。
/// 例如,要执行 `pwritev2()`,请设置返回 SQE 的 `rw_flags`。
/// 参见 https://linux.die.net/man/2/pwritev。
pub fn writev(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    iovecs: []const posix.iovec_const,
    offset: u64,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_writev(fd, iovecs, offset);
    sqe.user_data = user_data;
    return sqe;
}

/// 将执行 IORING_OP_WRITE_FIXED 的 SQE 加入队列,但不提交。
/// 给定 `buffer` 必须预先通过调用 `register_buffers` 向内核注册。
/// `buffer_index` 必须与其在传给 `register_buffers` 的数组中的索引相同。
///
/// 返回指向 SQE 的指针,以便在高级用例中继续修改它。
pub fn write_fixed(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    buffer: *posix.iovec,
    offset: u64,
    buffer_index: u16,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_write_fixed(fd, buffer, offset, buffer_index);
    sqe.user_data = user_data;
    return sqe;
}

/// 排入(但不提交)一个 SQE,以在套接字上执行 `accept4(2)`。
/// 返回 SQE 指针。
/// 自 5.5 起可用
pub fn accept(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    addr: ?*posix.sockaddr,
    addrlen: ?*posix.socklen_t,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_accept(fd, addr, addrlen, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将套接字的多次触发 accept 加入队列。
///
/// 多次触发变体允许应用程序发出单个 accept 请求,在连接请求到达时反复触发 CQE。
/// 只要 CQE 的 flags 中仍设置 IORING_CQE_F_MORE,accept 就会继续生成更多 CQE。
///
/// 自 5.19 起可用。
///
///
pub fn accept_multishot(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    addr: ?*posix.sockaddr,
    addrlen: ?*posix.socklen_t,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_multishot_accept(fd, addr, addrlen, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将使用直接(已注册)文件描述符的 accept 操作加入队列。
///
/// 要使用 accept 的 direct 变体,应用程序必须先通过
/// register_files 注册文件表。系统会动态选择未使用的表索引,
/// 并通过 CQE 的 res 字段返回。
///
/// 创建后,设置 SQE 的 flags 成员中的 IOSQE_FIXED_FILE,
/// 并将 SQE 的 fd 字段设为直接描述符值
/// 而非常规文件描述符,即可使用。
///
/// 自 5.19 起可用。
pub fn accept_direct(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    addr: ?*posix.sockaddr,
    addrlen: ?*posix.socklen_t,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_accept_direct(fd, addr, addrlen, flags, linux.IORING_FILE_INDEX_ALLOC);
    sqe.user_data = user_data;
    return sqe;
}

/// 使用直接(已注册)文件描述符将多次触发的 accept 操作加入队列。
/// 自 5.19 起可用。
pub fn accept_multishot_direct(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    addr: ?*posix.sockaddr,
    addrlen: ?*posix.socklen_t,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_multishot_accept_direct(fd, addr, addrlen, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将对套接字执行 `connect(2)` 的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
pub fn connect(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    addr: *const posix.sockaddr,
    addrlen: posix.socklen_t,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_connect(fd, addr, addrlen);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于执行 `epoll_ctl(2)` 的 SQE 加入队列(但不提交)。
/// 返回指向该 SQE 的指针。
pub fn epoll_ctl(
    self: *IoUring,
    user_data: u64,
    epfd: linux.fd_t,
    fd: linux.fd_t,
    op: u32,
    ev: ?*linux.epoll_event,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_epoll_ctl(epfd, fd, op, ev);
    sqe.user_data = user_data;
    return sqe;
}

/// 用于选择 recv 调用的处理方式。
pub const RecvBuffer = union(enum) {
    /// io_uring 将直接接收到此缓冲区
    buffer: []u8,

    /// io_uring 将选择一个先前通过 `provide_buffers` 提供的缓冲区。
    /// `group_id` 引用的缓冲区组必须至少包含一个缓冲区,recv 调用才能工作。
    /// `len` 控制要读入所选缓冲区的字节数。
    buffer_selection: struct {
        group_id: u16,
        len: usize,
    },
};

/// 将执行 `recv(2)` 的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
/// 自 5.6 起可用。
pub fn recv(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    buffer: RecvBuffer,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    switch (buffer) {
        .buffer => |slice| sqe.prep_recv(fd, slice, flags),
        .buffer_selection => |selection| {
            sqe.prep_rw(.RECV, fd, 0, selection.len, 0);
            sqe.rw_flags = flags;
            sqe.flags |= linux.IOSQE_BUFFER_SELECT;
            sqe.buf_index = selection.group_id;
        },
    }
    sqe.user_data = user_data;
    return sqe;
}

/// 将执行 `send(2)` 的 SQE 加入队列,但不提交。
/// 返回指向 SQE 的指针。
/// 从 5.6 起可用。
pub fn send(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    buffer: []const u8,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_send(fd, buffer, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将执行异步零拷贝 `send(2)` 的 SQE 加入队列,但不提交。
///
/// 此操作极有可能产生两个 CQE。第一个 CQE 的 flags 字段可能包含 IORING_CQE_F_MORE,表示还会有第二个 CQE,且其 user_data 字段具有相同的值。通知发布之前,用户不得修改数据缓冲区。第一个 CQE 遵循通常规则,因此其 res 字段包含已发送的字节数或负错误码。通知的 res 字段设为零,flags 字段包含 IORING_CQE_F_NOTIF。之所以需要两阶段模型,是因为内核可能长时间持有缓冲区,例如等待 TCP ACK。通知负责控制缓冲区生命周期。即使请求出错,也可能产生通知。
///
/// 自 6.0 起可用。
///
///
///
///
///
///
///
///
///
///
pub fn send_zc(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    buffer: []const u8,
    send_flags: u32,
    zc_flags: u16,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_send_zc(fd, buffer, send_flags, zc_flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于异步零复制 `send(2)` 的 SQE 加入队列,但不提交。
/// 返回指向 SQE 的指针。
/// 从 6.0 起可用。
pub fn send_zc_fixed(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    buffer: []const u8,
    send_flags: u32,
    zc_flags: u16,
    buf_index: u16,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_send_zc_fixed(fd, buffer, send_flags, zc_flags, buf_index);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于执行 `recvmsg(2)` 的 SQE 加入队列(但不提交)。
/// 返回指向该 SQE 的指针。
/// 自 5.3 起可用
pub fn recvmsg(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    msg: *linux.msghdr,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_recvmsg(fd, msg, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将执行 `sendmsg(2)` 的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
/// 自 5.3 起可用。
pub fn sendmsg(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    msg: *const linux.msghdr_const,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_sendmsg(fd, msg, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 排入(但不提交)一个 SQE,以执行异步零复制 `sendmsg(2)`。
/// 返回 SQE 指针。
/// 自 6.1 起可用
pub fn sendmsg_zc(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    msg: *const linux.msghdr_const,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_sendmsg_zc(fd, msg, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将执行 `openat(2)` 的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
/// 自 5.6 起可用。
pub fn openat(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    path: [*:0]const u8,
    flags: linux.O,
    mode: posix.mode_t,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_openat(fd, path, flags, mode);
    sqe.user_data = user_data;
    return sqe;
}

/// 将使用直接文件描述符,即已注册描述符的 openat 加入队列。
///
/// 使用 accept 的直接变体前,应用必须先通过 register_files
/// 注册文件表。系统会动态选择一个未使用的
/// 表索引,并在 CQE 的 res 字段返回。
///
/// 创建后,可在 SQE 的 flags 成员中设置 IOSQE_FIXED_FILE,
/// 并将 SQE 的 fd 字段设为直接描述符值,
/// 而非常规文件描述符。
///
/// 自 5.15 起可用。
pub fn openat_direct(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    path: [*:0]const u8,
    flags: linux.O,
    mode: posix.mode_t,
    file_index: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_openat_direct(fd, path, flags, mode, file_index);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于执行 `close(2)` 的 SQE 加入队列(但不提交)。
/// 返回指向该 SQE 的指针。
/// 自 5.6 起可用。
pub fn close(self: *IoUring, user_data: u64, fd: linux.fd_t) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_close(fd);
    sqe.user_data = user_data;
    return sqe;
}

/// 将关闭已注册文件描述符的操作加入队列。
/// 自 5.15 起可用
pub fn close_direct(self: *IoUring, user_data: u64, file_index: u32) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_close_direct(file_index);
    sqe.user_data = user_data;
    return sqe;
}

/// 将注册超时操作的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
///
/// 超时到期时完成;若 `count` 大于 `0`,也会在指定数量的
/// 事件完成后完成。
///
/// `flags` 可以为 `0` 表示相对超时,或为 `IORING_TIMEOUT_ABS` 表示绝对超时。
///
/// 若因到期而完成,完成事件结果为 `-ETIME`;
/// 若在指定数量事件完成后完成,则为 `0`;若超时到期前
/// 被移除,则为 `-ECANCELED`。
///
/// io_uring 超时使用 `CLOCK.MONOTONIC` 时钟源。
pub fn timeout(
    self: *IoUring,
    user_data: u64,
    ts: *const linux.kernel_timespec,
    count: u32,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_timeout(ts, count, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将移除已有超时操作的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
///
/// 超时通过其 `user_data` 标识。
///
/// 如果找到超时并成功取消,完成事件结果为 `0`;
/// 如果找到超时但到期处理已开始,则为 `-EBUSY`;
/// 如果找不到超时,则为 `-ENOENT`。
pub fn timeout_remove(
    self: *IoUring,
    user_data: u64,
    timeout_user_data: u64,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_timeout_remove(timeout_user_data, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 排入(但不提交)一个 SQE,以添加链接超时操作。
/// 返回该 SQE 的指针。
///
/// 需要为目标操作的 flags 设置 linux.IOSQE_IO_LINK,随后紧接目标操作调用此方法。
/// 详情见 https://lwn.net/Articles/803932/ 。
///
/// 若依赖请求先于链接超时完成,则取消超时。若超时先于依赖请求完成,则取消依赖请求。
///
/// link_timeout 的完成事件结果在超时先于依赖请求完成时为 `-ETIME`(此时依赖请求的完成事件结果为 `-ECANCELED`);在依赖请求先于链接超时完成时为 `-EALREADY`。
///
///
///
///
///
///
///
pub fn link_timeout(
    self: *IoUring,
    user_data: u64,
    ts: *const linux.kernel_timespec,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_link_timeout(ts, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于执行 `poll(2)` 的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
pub fn poll_add(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    poll_mask: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_poll_add(fd, poll_mask);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于移除现有轮询操作的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
pub fn poll_remove(
    self: *IoUring,
    user_data: u64,
    target_user_data: u64,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_poll_remove(target_user_data);
    sqe.user_data = user_data;
    return sqe;
}

/// 排入(但不提交)一个 SQE,以更新现有 poll 操作的用户数据。返回 SQE 指针。
///
pub fn poll_update(
    self: *IoUring,
    user_data: u64,
    old_user_data: u64,
    new_user_data: u64,
    poll_mask: u32,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_poll_update(old_user_data, new_user_data, poll_mask, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于执行 `fallocate(2)` 的 SQE 加入队列(但不提交)。
/// 返回指向该 SQE 的指针。
pub fn fallocate(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    mode: i32,
    offset: u64,
    len: u64,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_fallocate(fd, mode, offset, len);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于执行 `statx(2)` 的 SQE 加入队列(但不提交)。
/// 返回指向该 SQE 的指针。
pub fn statx(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    path: [:0]const u8,
    flags: u32,
    mask: linux.STATX,
    buf: *linux.Statx,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_statx(fd, path, flags, mask, buf);
    sqe.user_data = user_data;
    return sqe;
}

/// 将移除现有操作的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
///
/// 通过 `user_data` 标识操作。
///
/// 若找到操作并成功取消,完成事件结果为 `0`;若找到操作但已在执行,结果为 `-EALREADY`;若未找到操作,结果为 `-ENOENT`。
///
///
pub fn cancel(
    self: *IoUring,
    user_data: u64,
    cancel_user_data: u64,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_cancel(cancel_user_data, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 排入(但不提交)一个 SQE,以执行 `shutdown(2)`。
/// 返回 SQE 指针。
///
/// 该操作由其 `user_data` 标识。
pub fn shutdown(
    self: *IoUring,
    user_data: u64,
    sockfd: posix.socket_t,
    how: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_shutdown(sockfd, how);
    sqe.user_data = user_data;
    return sqe;
}

/// 将执行 `renameat2(2)` 的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
pub fn renameat(
    self: *IoUring,
    user_data: u64,
    old_dir_fd: linux.fd_t,
    old_path: [*:0]const u8,
    new_dir_fd: linux.fd_t,
    new_path: [*:0]const u8,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_renameat(old_dir_fd, old_path, new_dir_fd, new_path, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于执行 `unlinkat(2)` 的 SQE 加入队列(但不提交)。
/// 返回指向该 SQE 的指针。
pub fn unlinkat(
    self: *IoUring,
    user_data: u64,
    dir_fd: linux.fd_t,
    path: [*:0]const u8,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_unlinkat(dir_fd, path, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于执行 `mkdirat(2)` 的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
pub fn mkdirat(
    self: *IoUring,
    user_data: u64,
    dir_fd: linux.fd_t,
    path: [*:0]const u8,
    mode: posix.mode_t,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_mkdirat(dir_fd, path, mode);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于执行 `symlinkat(2)` 的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
pub fn symlinkat(
    self: *IoUring,
    user_data: u64,
    target: [*:0]const u8,
    new_dir_fd: linux.fd_t,
    link_path: [*:0]const u8,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_symlinkat(target, new_dir_fd, link_path);
    sqe.user_data = user_data;
    return sqe;
}

/// 排入(但不提交)一个 SQE,以执行 `linkat(2)`。
/// 返回 SQE 指针。
pub fn linkat(
    self: *IoUring,
    user_data: u64,
    old_dir_fd: linux.fd_t,
    old_path: [*:0]const u8,
    new_dir_fd: linux.fd_t,
    new_path: [*:0]const u8,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_linkat(old_dir_fd, old_path, new_dir_fd, new_path, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将提供一组缓冲区的 SQE 加入队列,供读取或接收数据的命令使用,但不提交。
/// 返回指向 SQE 的指针。
///
/// 可在 `read`、`recv` 或 `recvmsg` 命令中通过 .buffer_selection 使用所提供的缓冲区。
///
/// 内核要求一块大小为 buffers_count * buffer_size 的连续内存。
pub fn provide_buffers(
    self: *IoUring,
    user_data: u64,
    buffers: [*]u8,
    buffer_size: usize,
    buffers_count: usize,
    group_id: usize,
    buffer_id: usize,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_provide_buffers(buffers, buffer_size, buffers_count, group_id, buffer_id);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于移除一组已提供缓冲区的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
pub fn remove_buffers(
    self: *IoUring,
    user_data: u64,
    buffers_count: usize,
    group_id: usize,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_remove_buffers(buffers_count, group_id);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于执行 `waitid(2)` 的 SQE 加入队列,但不提交。
/// 返回指向该 SQE 的指针。
pub fn waitid(
    self: *IoUring,
    user_data: u64,
    id_type: linux.P,
    id: i32,
    infop: *linux.siginfo_t,
    options: u32,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_waitid(id_type, id, infop, options, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 注册文件描述符数组。
/// 每次将文件描述符放入 SQE 并提交给内核,内核都必须获取对应文件的引用,I/O 完成后再释放该引用。文件引用的原子操作可能拖慢高 IOPS 工作负载。预先注册文件描述符可以避免这一开销。
/// 引用已注册的文件描述符时,必须在 SQE 的 flags 中设置 IOSQE_FIXED_FILE,并将 SQE 的 fd 设为该描述符在已注册数组中的索引。
/// 注册文件描述符会等待环进入空闲状态。
/// 销毁环时,内核会自动注销文件。
/// 应用程序只有在需要注册新的文件描述符数组时,才需要主动注销。
///
///
///
///
pub fn register_files(self: *IoUring, fds: []const linux.fd_t) !void {
    assert(self.fd >= 0);
    const res = linux.io_uring_register(
        self.fd,
        .REGISTER_FILES,
        @as(*const anyopaque, @ptrCast(fds.ptr)),
        @as(u32, @intCast(fds.len)),
    );
    try handle_registration_result(res);
}

/// 更新已注册的文件描述符。
///
/// 从原文件描述符切片中给定偏移开始应用更新。
/// 更新有三种:
/// * 将稀疏条目,即 fd 为 -1 的条目,变为实际条目;
/// * 移除已有条目,将 fd 设为 -1;
/// * 用新 fd 替换已有条目。
/// 添加新的文件描述符必须使用 `register_files`。
pub fn register_files_update(self: *IoUring, offset: u32, fds: []const linux.fd_t) !void {
    assert(self.fd >= 0);

    const FilesUpdate = extern struct {
        offset: u32,
        resv: u32,
        fds: u64 align(8),
    };
    var update = FilesUpdate{
        .offset = offset,
        .resv = @as(u32, 0),
        .fds = @as(u64, @intFromPtr(fds.ptr)),
    };

    const res = linux.io_uring_register(
        self.fd,
        .REGISTER_FILES_UPDATE,
        @as(*const anyopaque, @ptrCast(&update)),
        @as(u32, @intCast(fds.len)),
    );
    try handle_registration_result(res);
}

/// 注册一个包含 `nr_files` 个文件描述符的空(-1)文件表。
pub fn register_files_sparse(self: *IoUring, nr_files: u32) !void {
    assert(self.fd >= 0);

    const reg = &linux.io_uring_rsrc_register{
        .nr = nr_files,
        .flags = linux.IORING_RSRC_REGISTER_SPARSE,
        .resv2 = 0,
        .data = 0,
        .tags = 0,
    };

    const res = linux.io_uring_register(
        self.fd,
        .REGISTER_FILES2,
        @ptrCast(reg),
        @as(u32, @sizeOf(linux.io_uring_rsrc_register)),
    );

    return handle_registration_result(res);
}

// 注册用于固定文件分配的范围。
// 自 6.0 起可用
pub fn register_file_alloc_range(self: *IoUring, offset: u32, len: u32) !void {
    assert(self.fd >= 0);

    const range = &linux.io_uring_file_index_range{
        .off = offset,
        .len = len,
        .resv = 0,
    };

    const res = linux.io_uring_register(
        self.fd,
        .REGISTER_FILE_ALLOC_RANGE,
        @ptrCast(range),
        0,
    );

    return handle_registration_result(res);
}

/// 注册 eventfd 的文件描述符,用于接收 io_uring 实例
/// 完成事件的通知。
/// 任一时刻只能注册一个 eventfd。
pub fn register_eventfd(self: *IoUring, fd: linux.fd_t) !void {
    assert(self.fd >= 0);
    const res = linux.io_uring_register(
        self.fd,
        .REGISTER_EVENTFD,
        @as(*const anyopaque, @ptrCast(&fd)),
        1,
    );
    try handle_registration_result(res);
}

/// 注册 eventfd 的文件描述符,以接收 io_uring 实例的完成事件通知。仅对异步完成的事件发送通知。
/// 因此,提交过程中直接内联完成的事件不会触发通知。
/// 任意时刻只能注册一个 eventfd。
///
pub fn register_eventfd_async(self: *IoUring, fd: linux.fd_t) !void {
    assert(self.fd >= 0);
    const res = linux.io_uring_register(
        self.fd,
        .REGISTER_EVENTFD_ASYNC,
        @as(*const anyopaque, @ptrCast(&fd)),
        1,
    );
    try handle_registration_result(res);
}

/// 注销已注册的 eventfd 文件描述符。
pub fn unregister_eventfd(self: *IoUring) !void {
    assert(self.fd >= 0);
    const res = linux.io_uring_register(
        self.fd,
        .UNREGISTER_EVENTFD,
        null,
        0,
    );
    try handle_registration_result(res);
}

pub fn register_napi(self: *IoUring, napi: *linux.io_uring_napi) !void {
    assert(self.fd >= 0);
    const res = linux.io_uring_register(self.fd, .REGISTER_NAPI, napi, 1);
    try handle_registration_result(res);
}

pub fn unregister_napi(self: *IoUring, napi: *linux.io_uring_napi) !void {
    assert(self.fd >= 0);
    const res = linux.io_uring_register(self.fd, .UNREGISTER_NAPI, napi, 1);
    try handle_registration_result(res);
}

/// 注册供 `read_fixed` 和 `write_fixed` 使用的缓冲区数组。
pub fn register_buffers(self: *IoUring, buffers: []const posix.iovec) !void {
    assert(self.fd >= 0);
    const res = linux.io_uring_register(
        self.fd,
        .REGISTER_BUFFERS,
        buffers.ptr,
        @as(u32, @intCast(buffers.len)),
    );
    try handle_registration_result(res);
}

/// 注销已注册的缓冲区。
pub fn unregister_buffers(self: *IoUring) !void {
    assert(self.fd >= 0);
    const res = linux.io_uring_register(self.fd, .UNREGISTER_BUFFERS, null, 0);
    switch (linux.errno(res)) {
        .SUCCESS => {},
        .NXIO => return error.BuffersNotRegistered,
        else => |errno| return posix.unexpectedErrno(errno),
    }
}

/// 返回 io_uring_probe,用于探测当前运行内核的
/// io_uring 子系统能力。io_uring_probe 包含
/// 受支持操作列表。
pub fn get_probe(self: *IoUring) !linux.io_uring_probe {
    var probe = std.mem.zeroInit(linux.io_uring_probe, .{});
    const res = linux.io_uring_register(self.fd, .REGISTER_PROBE, &probe, probe.ops.len);
    try handle_register_buf_ring_result(res);
    return probe;
}

fn handle_registration_result(res: usize) !void {
    switch (linux.errno(res)) {
        .SUCCESS => {},
        // 数组中的一个或多个 fd 无效,或内核不支持稀疏集合:
        .BADF => return error.FileDescriptorInvalid,
        .BUSY => return error.FilesAlreadyRegistered,
        .INVAL => return error.FilesEmpty,
        // 添加 `nr_args` 个文件引用会超过每用户 RLIMIT_NOFILE
        // 资源限制所允许的最大文件数量,且未设置
        // CAP_SYS_RESOURCE 能力;或者 `nr_args` 超过固定文件集的
        // 最大允许数量(旧内核限制为 1024 个文件,而非 64K 个):
        .MFILE => return error.UserFdQuotaExceeded,
        // 内核资源不足;或者调用者的 RLIMIT_MEMLOCK 软资源限制非零,
        // 却试图锁定超过该限制的内存。若进程具有 CAP_IPC_LOCK 特权,
        // 则不施加此限制:
        .NOMEM => return error.SystemResources,
        // 尝试向正在注册文件或正在销毁的环注册文件:
        .NXIO => return error.RingShuttingDownOrAlreadyRegisteringFiles,
        else => |errno| return posix.unexpectedErrno(errno),
    }
}

/// 注销先前与环关联的所有已注册文件描述符。
pub fn unregister_files(self: *IoUring) !void {
    assert(self.fd >= 0);
    const res = linux.io_uring_register(self.fd, .UNREGISTER_FILES, null, 0);
    switch (linux.errno(res)) {
        .SUCCESS => {},
        .NXIO => return error.FilesNotRegistered,
        else => |errno| return posix.unexpectedErrno(errno),
    }
}

/// 准备创建套接字的请求。
/// 新套接字的 fd 将在完成结果中返回。
/// 自 5.19 起可用
pub fn socket(
    self: *IoUring,
    user_data: u64,
    domain: u32,
    socket_type: u32,
    protocol: u32,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_socket(domain, socket_type, protocol, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 为索引 `file_index` 处的已注册文件准备套接字创建请求。
/// 自 5.19 起可用。
pub fn socket_direct(
    self: *IoUring,
    user_data: u64,
    domain: u32,
    socket_type: u32,
    protocol: u32,
    flags: u32,
    file_index: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_socket_direct(domain, socket_type, protocol, flags, file_index);
    sqe.user_data = user_data;
    return sqe;
}

/// 为注册文件准备套接字创建请求,由内核选择索引(文件索引分配)。
/// 文件索引将在 CQE 的 res 字段返回。
/// 自 5.19 起可用。
pub fn socket_direct_alloc(
    self: *IoUring,
    user_data: u64,
    domain: u32,
    socket_type: u32,
    protocol: u32,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_socket_direct_alloc(domain, socket_type, protocol, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 排入(但不提交)一个 SQE,以在套接字上执行 `bind(2)`。
/// 返回 SQE 指针。
/// 自 6.11 起可用
pub fn bind(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    addr: *const posix.sockaddr,
    addrlen: posix.socklen_t,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_bind(fd, addr, addrlen, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 将用于对套接字执行 `listen(2)` 的 SQE 加入队列(但不提交)。
/// 返回指向该 SQE 的指针。
/// 自 6.11 起可用
pub fn listen(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    backlog: usize,
    flags: u32,
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_listen(fd, backlog, flags);
    sqe.user_data = user_data;
    return sqe;
}

/// 为套接字准备 cmd 请求。
/// 参见:https://man7.org/linux/man-pages/man3/io_uring_prep_cmd.3.html
/// 自 6.7 起可用。
pub fn cmd_sock(
    self: *IoUring,
    user_data: u64,
    cmd_op: linux.IO_URING_SOCKET_OP,
    fd: linux.fd_t,
    level: u32, // linux.SOL
    optname: u32, // linux.SO
    optval: u64, // 指向选项值的指针
    optlen: u32, // 选项值的大小
) !*linux.io_uring_sqe {
    const sqe = try self.get_sqe();
    sqe.prep_cmd_sock(cmd_op, fd, level, optname, optval, optlen);
    sqe.user_data = user_data;
    return sqe;
}

/// 在 level 参数指定的协议层,准备设置
/// optname 参数指定的套接字选项。
/// 从 6.7.n 起可用。
pub fn setsockopt(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    level: u32, // linux.SOL
    optname: u32, // linux.SO
    opt: []const u8,
) !*linux.io_uring_sqe {
    return try self.cmd_sock(
        user_data,
        .SETSOCKOPT,
        fd,
        level,
        optname,
        @intFromPtr(opt.ptr),
        @intCast(opt.len),
    );
}

/// 准备获取套接字选项操作,以读取 fd 参数指定套接字中
/// option_name 参数指定选项的值。
/// 自 6.7 起可用。
pub fn getsockopt(
    self: *IoUring,
    user_data: u64,
    fd: linux.fd_t,
    level: u32, // linux.SOL
    optname: u32, // linux.SO
    opt: []u8,
) !*linux.io_uring_sqe {
    return try self.cmd_sock(
        user_data,
        .GETSOCKOPT,
        fd,
        level,
        optname,
        @intFromPtr(opt.ptr),
        @intCast(opt.len),
    );
}

pub const SubmissionQueue = struct {
    head: *u32,
    tail: *u32,
    mask: u32,
    flags: *u32,
    dropped: *u32,
    array: []u32,
    sqes: []linux.io_uring_sqe,
    mmap: []align(page_size_min) u8,
    mmap_sqes: []align(page_size_min) u8,

    // `sqe_head` 和 `sqe_tail` 的使用方式与 liburing 相同:
    // 递增 `sqe_tail`,但不递增 `tail`,对应每次调用 `get_sqe()`。
    // 只有实际提交这些事件时,才统一将 `tail` 设为 `sqe_tail`。
    // 这样可以将对 `tail` 执行 @atomicStore 的成本分摊到多个 SQE。
    sqe_head: u32 = 0,
    sqe_tail: u32 = 0,

    pub fn init(fd: linux.fd_t, p: linux.io_uring_params) !SubmissionQueue {
        assert(fd >= 0);
        assert((p.features & linux.IORING_FEAT_SINGLE_MMAP) != 0);
        const size = @max(
            p.sq_off.array + p.sq_entries * @sizeOf(u32),
            p.cq_off.cqes + p.cq_entries * @sizeOf(linux.io_uring_cqe),
        );
        const mmap = try posix.mmap(
            null,
            size,
            .{ .READ = true, .WRITE = true },
            .{ .TYPE = .SHARED, .POPULATE = true },
            fd,
            linux.IORING_OFF_SQ_RING,
        );
        errdefer posix.munmap(mmap);
        assert(mmap.len == size);

        // `sqes` 和 `array` 间接层的目的是允许
        // 应用程序预先分配静态 linux.io_uring_sqe 条目,并在需要时重放。
        const size_sqes = p.sq_entries * @sizeOf(linux.io_uring_sqe);
        const mmap_sqes = try posix.mmap(
            null,
            size_sqes,
            .{ .READ = true, .WRITE = true },
            .{ .TYPE = .SHARED, .POPULATE = true },
            fd,
            linux.IORING_OFF_SQES,
        );
        errdefer posix.munmap(mmap_sqes);
        assert(mmap_sqes.len == size_sqes);

        const array: [*]u32 = @ptrCast(@alignCast(&mmap[p.sq_off.array]));
        const sqes: [*]linux.io_uring_sqe = @ptrCast(@alignCast(&mmap_sqes[0]));
        // 我们预期内核会将 p.sq_entries 复制到 p.sq_off.ring_entries 所指的 u32,
        // 见 https://github.com/torvalds/linux/blob/v5.8/fs/io_uring.c#L7843-L7844。
        assert(p.sq_entries == @as(*u32, @ptrCast(@alignCast(&mmap[p.sq_off.ring_entries]))).*);
        return SubmissionQueue{
            .head = @ptrCast(@alignCast(&mmap[p.sq_off.head])),
            .tail = @ptrCast(@alignCast(&mmap[p.sq_off.tail])),
            .mask = @as(*u32, @ptrCast(@alignCast(&mmap[p.sq_off.ring_mask]))).*,
            .flags = @ptrCast(@alignCast(&mmap[p.sq_off.flags])),
            .dropped = @ptrCast(@alignCast(&mmap[p.sq_off.dropped])),
            .array = array[0..p.sq_entries],
            .sqes = sqes[0..p.sq_entries],
            .mmap = mmap,
            .mmap_sqes = mmap_sqes,
        };
    }

    pub fn deinit(self: *SubmissionQueue) void {
        posix.munmap(self.mmap_sqes);
        posix.munmap(self.mmap);
    }
};

pub const CompletionQueue = struct {
    head: *u32,
    tail: *u32,
    mask: u32,
    overflow: *u32,
    cqes: []linux.io_uring_cqe,

    pub fn init(fd: linux.fd_t, p: linux.io_uring_params, sq: SubmissionQueue) !CompletionQueue {
        assert(fd >= 0);
        assert((p.features & linux.IORING_FEAT_SINGLE_MMAP) != 0);
        const mmap = sq.mmap;
        const cqes: [*]linux.io_uring_cqe = @ptrCast(@alignCast(&mmap[p.cq_off.cqes]));
        assert(p.cq_entries == @as(*u32, @ptrCast(@alignCast(&mmap[p.cq_off.ring_entries]))).*);
        return CompletionQueue{
            .head = @ptrCast(@alignCast(&mmap[p.cq_off.head])),
            .tail = @ptrCast(@alignCast(&mmap[p.cq_off.tail])),
            .mask = @as(*u32, @ptrCast(@alignCast(&mmap[p.cq_off.ring_mask]))).*,
            .overflow = @ptrCast(@alignCast(&mmap[p.cq_off.overflow])),
            .cqes = cqes[0..p.cq_entries],
        };
    }

    pub fn deinit(self: *CompletionQueue) void {
        _ = self;
        // 由于现在与提交队列共享 mmap,因此是空操作。
        // 保留此处是为与提交队列对称,并支持将来的功能。
    }
};

/// 应用程序提供的一组缓冲区。使用自内核 5.19 起支持的新类型,称为环映射缓冲区。缓冲区由缓冲区组标识和组内缓冲区标识确定。IO_Uring 可以有多个缓冲区组,每组的组标识必须唯一。
///
/// 在 `init` 中,应用程序提供连续内存块 `buffers`,用于容纳 `buffers_count` 个大小为 `buffers_size` 的缓冲区。随后应用程序可以提交 `recv` 操作,无需预先指定缓冲区。当操作准备好接收数据时,会自动选择一个缓冲区,结果 CQE 的 `cqe.buffer_id()` 将包含其标识。使用 `get` 方法获取 CQE 中缓冲区标识所对应的缓冲区。应用程序处理完缓冲区后,可调用 `put` 将所有权交还内核,从而重复这一循环。
///
/// 取决于数据到达速率,某个缓冲区组可能在 CQE 中的缓冲区交还内核之前耗尽缓冲区。若发生这种情况,`cqe.err()` 的错误值为 ENOBUFS。
///
///
///
///
///
///
///
///
///
///
///
///
///
pub const BufferGroup = struct {
    /// 此组注册到的父环。
    ring: *IoUring,
    /// 指向与内核共享的内存的指针。
    /// 与内核共享 `buffers_count` 个 `io_uring_buf` 结构体。
    /// 第一个 `io_uring_buf` 与 `io_uring_buf_ring` 结构体重叠存放。
    br: *align(page_size_min) linux.io_uring_buf_ring,
    /// 大小为 (buffers_count * buffer_size) 的连续内存块。
    buffers: []u8,
    /// buffers 中每个缓冲区的大小。
    buffer_size: u32,
    /// `buffers` 中的缓冲区数量,即 br 中的 `io_uring_buf structures` 数量。
    buffers_count: u16,
    /// 启用增量消费时,各缓冲区中未消费部分的起点。
    heads: []u32,
    /// 此组的标识符,必须在环内唯一。
    group_id: u16,

    pub fn init(
        ring: *IoUring,
        allocator: Allocator,
        group_id: u16,
        buffer_size: u32,
        buffers_count: u16,
    ) !BufferGroup {
        const buffers = try allocator.alloc(u8, buffer_size * buffers_count);
        errdefer allocator.free(buffers);
        const heads = try allocator.alloc(u32, buffers_count);
        errdefer allocator.free(heads);

        const br = try setup_buf_ring(ring.fd, buffers_count, group_id, .{ .inc = true });
        buf_ring_init(br);

        const mask = buf_ring_mask(buffers_count);
        var i: u16 = 0;
        while (i < buffers_count) : (i += 1) {
            const pos = buffer_size * i;
            const buf = buffers[pos .. pos + buffer_size];
            heads[i] = 0;
            buf_ring_add(br, buf, i, mask, i);
        }
        buf_ring_advance(br, buffers_count);

        return BufferGroup{
            .ring = ring,
            .group_id = group_id,
            .br = br,
            .buffers = buffers,
            .heads = heads,
            .buffer_size = buffer_size,
            .buffers_count = buffers_count,
        };
    }

    pub fn deinit(self: *BufferGroup, allocator: Allocator) void {
        free_buf_ring(self.ring.fd, self.br, self.buffers_count, self.group_id);
        allocator.free(self.buffers);
        allocator.free(self.heads);
    }

    // 准备 recv 操作,从此组中选择缓冲区。
    pub fn recv(self: *BufferGroup, user_data: u64, fd: linux.fd_t, flags: u32) !*linux.io_uring_sqe {
        var sqe = try self.ring.get_sqe();
        sqe.prep_rw(.RECV, fd, 0, 0, 0);
        sqe.rw_flags = flags;
        sqe.flags |= linux.IOSQE_BUFFER_SELECT;
        sqe.buf_index = self.group_id;
        sqe.user_data = user_data;
        return sqe;
    }

    // 准备多次触发的 recv 操作,从此组中选择缓冲区。
    pub fn recv_multishot(self: *BufferGroup, user_data: u64, fd: linux.fd_t, flags: u32) !*linux.io_uring_sqe {
        var sqe = try self.recv(user_data, fd, flags);
        sqe.ioprio |= linux.IORING_RECV_MULTISHOT;
        return sqe;
    }

    // 通过 id 获取缓冲区。
    pub fn get_by_id(self: *BufferGroup, buffer_id: u16) []u8 {
        const pos = self.buffer_size * buffer_id;
        return self.buffers[pos .. pos + self.buffer_size][self.heads[buffer_id]..];
    }

    // 通过 CQE 获取缓冲区。
    pub fn get(self: *BufferGroup, cqe: linux.io_uring_cqe) ![]u8 {
        const buffer_id = try cqe.buffer_id();
        const used_len = @as(usize, @intCast(cqe.res));
        return self.get_by_id(buffer_id)[0..used_len];
    }

    // 将 CQE 的缓冲区释放回内核。
    pub fn put(self: *BufferGroup, cqe: linux.io_uring_cqe) !void {
        const buffer_id = try cqe.buffer_id();
        if (cqe.flags & linux.IORING_CQE_F_BUF_MORE == linux.IORING_CQE_F_BUF_MORE) {
            // 增量消费已启用,内核将再次写入此缓冲区。
            const used_len = @as(u32, @intCast(cqe.res));
            // 跟踪缓冲区中哪些部分正在使用
            self.heads[buffer_id] += used_len;
            return;
        }
        self.heads[buffer_id] = 0;

        // 将缓冲区释放给内核。    const mask = buf_ring_mask(self.buffers_count);
        const mask = buf_ring_mask(self.buffers_count);
        buf_ring_add(self.br, self.get_by_id(buffer_id), buffer_id, mask, 0);
        buf_ring_advance(self.br, 1);
    }
};

/// 注册用于提供缓冲区的共享缓冲区环。
/// 映射 `entries` 个 `io_uring_buf` 结构体,并与内核共享。
/// `fd` 为所注册缓冲区环对应的 IO_Uring.fd。
/// `entries` 为请求的缓冲区环条目数,必须是二的幂。
/// `group_id` 为选定的缓冲区组 ID,在 IO_Uring 中唯一。
pub fn setup_buf_ring(
    fd: linux.fd_t,
    entries: u16,
    group_id: u16,
    flags: linux.io_uring_buf_reg.Flags,
) !*align(page_size_min) linux.io_uring_buf_ring {
    if (entries == 0 or entries > 1 << 15) return error.EntriesNotInRange;
    if (!std.math.isPowerOfTwo(entries)) return error.EntriesNotPowerOfTwo;

    const mmap_size = @as(usize, entries) * @sizeOf(linux.io_uring_buf);
    const mmap = try posix.mmap(
        null,
        mmap_size,
        .{ .READ = true, .WRITE = true },
        .{ .TYPE = .PRIVATE, .ANONYMOUS = true },
        -1,
        0,
    );
    errdefer posix.munmap(mmap);
    assert(mmap.len == mmap_size);

    const br: *align(page_size_min) linux.io_uring_buf_ring = @ptrCast(mmap.ptr);
    try register_buf_ring(fd, @intFromPtr(br), entries, group_id, flags);
    return br;
}

fn register_buf_ring(
    fd: linux.fd_t,
    addr: u64,
    entries: u32,
    group_id: u16,
    flags: linux.io_uring_buf_reg.Flags,
) !void {
    var reg = std.mem.zeroInit(linux.io_uring_buf_reg, .{
        .ring_addr = addr,
        .ring_entries = entries,
        .bgid = group_id,
        .flags = flags,
    });
    var res = linux.io_uring_register(fd, .REGISTER_PBUF_RING, @as(*const anyopaque, @ptrCast(&reg)), 1);
    if (linux.errno(res) == .INVAL and reg.flags.inc) {
        // 不使用增量缓冲区消费方式重试。
        // 此功能自内核 6.12 起可用,旧版返回 INVAL。
        reg.flags.inc = false;
        res = linux.io_uring_register(fd, .REGISTER_PBUF_RING, @as(*const anyopaque, @ptrCast(&reg)), 1);
    }
    try handle_register_buf_ring_result(res);
}

fn unregister_buf_ring(fd: linux.fd_t, group_id: u16) !void {
    var reg = std.mem.zeroInit(linux.io_uring_buf_reg, .{
        .bgid = group_id,
    });
    const res = linux.io_uring_register(
        fd,
        .UNREGISTER_PBUF_RING,
        @as(*const anyopaque, @ptrCast(&reg)),
        1,
    );
    try handle_register_buf_ring_result(res);
}

fn handle_register_buf_ring_result(res: usize) !void {
    switch (linux.errno(res)) {
        .SUCCESS => {},
        .INVAL => return error.ArgumentsInvalid,
        else => |errno| return posix.unexpectedErrno(errno),
    }
}

// 注销先前注册的共享缓冲区环,该环由 io_uring_setup_buf_ring 返回。
pub fn free_buf_ring(fd: linux.fd_t, br: *align(page_size_min) linux.io_uring_buf_ring, entries: u32, group_id: u16) void {
    unregister_buf_ring(fd, group_id) catch {};
    var mmap: []align(page_size_min) u8 = undefined;
    mmap.ptr = @ptrCast(br);
    mmap.len = entries * @sizeOf(linux.io_uring_buf);
    posix.munmap(mmap);
}

/// 初始化 `br`,使其可供使用。
pub fn buf_ring_init(br: *linux.io_uring_buf_ring) void {
    br.tail = 0;
}

/// 计算缓冲区环的适当大小掩码。
/// `entries` 是 io_uring_register_buf_ring 中指定的环条目数。
pub fn buf_ring_mask(entries: u16) u16 {
    return entries - 1;
}

/// 将 `buffer` 关联到 `br` 缓冲区环。
/// `buffer_id` 是将在 CQE 中返回的标识。
/// `buffer_offset` 是相对于当前尾部的插入偏移量。
/// 若只提供一个缓冲区,再通过 advance 提交环尾,则偏移量应为 0。
/// 若在循环中提供多个缓冲区后统一提交,则每增加一个缓冲区,偏移量必须加一。
pub fn buf_ring_add(
    br: *linux.io_uring_buf_ring,
    buffer: []u8,
    buffer_id: u16,
    mask: u16,
    buffer_offset: u16,
) void {
    const bufs: [*]linux.io_uring_buf = @ptrCast(br);
    const buf: *linux.io_uring_buf = &bufs[(br.tail +% buffer_offset) & mask];

    buf.addr = @intFromPtr(buffer.ptr);
    buf.len = @intCast(buffer.len);
    buf.bid = buffer_id;
}

/// 使 `count` 个新缓冲区对内核可见。在调用
/// `io_uring_buf_ring_add` 共 `count` 次以填入新缓冲区后调用。
pub fn buf_ring_advance(br: *linux.io_uring_buf_ring, count: u16) void {
    const tail: u16 = br.tail +% count;
    @atomicStore(u16, &br.tail, tail, .release);
}

test BufferGroup {
    if (builtin.target.cpu.arch.isPowerPC()) return; // https://codeberg.org/ziglang/zig/issues/31562
    if (!is_linux) return error.SkipZigTest;

    const io = testing.io;
    _ = io;

    // 初始化 IoUring
    var ring = IoUring.init(16, 0) catch |err| switch (err) {
        error.SystemOutdated => return error.SkipZigTest,
        error.PermissionDenied => return error.SkipZigTest,
        else => return err,
    };
    defer ring.deinit();

    // 为环初始化缓冲组
    const group_id: u16 = 1; // 缓冲区组标识
    const buffers_count: u16 = 1; // 缓冲区组中的缓冲区数量
    const buffer_size: usize = 128; // 组中每个缓冲区的大小
    var buf_grp = BufferGroup.init(
        &ring,
        testing.allocator,
        group_id,
        buffer_size,
        buffers_count,
    ) catch |err| switch (err) {
        // 早于 5.19 的内核
        error.ArgumentsInvalid => return error.SkipZigTest,
        else => return err,
    };
    defer buf_grp.deinit(testing.allocator);

    // 创建客户端/服务器 fd
    const fds = try createSocketTestHarness(&ring);
    defer fds.close();
    const data = [_]u8{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0xa, 0xb, 0xc, 0xd, 0xe };

    // 客户端发送数据
    {
        _ = try ring.send(1, fds.client, data[0..], 0);
        const submitted = try ring.submit();
        try testing.expectEqual(1, submitted);
        const cqe_send = try ring.copy_cqe();
        if (cqe_send.err() == .INVAL) return error.SkipZigTest;
        try testing.expectEqual(linux.io_uring_cqe{ .user_data = 1, .res = data.len, .flags = 0 }, cqe_send);
    }

    // 服务器使用缓冲区组接收
    {
        // 提交 recv 操作,将从缓冲区组中选择缓冲区
        _ = try buf_grp.recv(2, fds.server, 0);
        const submitted = try ring.submit();
        try testing.expectEqual(1, submitted);

        // ……当 recv 操作完成时
        const cqe = try ring.copy_cqe();
        try testing.expectEqual(2, cqe.user_data); // 与提交的 user_data 匹配
        try testing.expect(cqe.res >= 0); // 成功
        try testing.expectEqual(posix.E.SUCCESS, cqe.err());
        try testing.expectEqual(data.len, @as(usize, @intCast(cqe.res))); // cqe.res 保存接收的数据长度

        // 从池中获取缓冲区
        const buf = try buf_grp.get(cqe);
        try testing.expectEqualSlices(u8, &data, buf);
        // 应用程序使用完毕后,将缓冲区释放回内核
        try buf_grp.put(cqe);
    }
}

test {
    if (builtin.target.cpu.arch.isPowerPC()) return; // https://codeberg.org/ziglang/zig/issues/31562
    if (is_linux) _ = @import("IoUring/test.zig");
}