io_uring 仅限 Linux 因其是内核 5.1+ 原生异步 I/O 接口，Windows/macOS 无对应机制，glibc/musl 不封装，调用 io_uring_setup 直接返回 ENOSYS。
io_uring 为什么在 Linux 上才能用
因为 io_uring 是 Linux 内核 5.1+ 引入的原生异步 I/O 接口，不依赖线程池或 syscall 模拟。Windows/macOS 没有对应机制，glibc、musl 也不封装它。你写 io_uring_setup 系统调用，其他系统直接返回 ENOSYS。
验证方式很简单：
grep -q io_uring /usr/include/asm/unistd_64.h && echo "ok" || echo "not available"
常见坑：
- 内核版本够但发行版默认禁用：Ubuntu 20.04 默认内核是 5.4，但某些云镜像会关掉
CONFIG_IO_URING；检查zcat /proc/config.gz | grep IO_URING或看/lib/modules/$(uname -r)/build/.config - 容器里没权限：Docker 默认 drop 了
sys_admin，得加--cap-add=SYS_ADMIN才能调io_uring_setup - Clang/GCC 编译时找不到
liburing头文件：不是装liburing-dev就完事——得确保 pkg-config 能查到，pkg-config --modversion liburing有输出才算真正就位
用 liburing 还是裸系统调用
直接 syscall（io_uring_setup、io_uring_register、io_uring_enter）理论上最轻，但几乎没人这么干。原因很实际：
立即学习“C++免费学习笔记（深入）”；
-
liburing不只是封装，它把 SQE（submission queue entry）填充、CQE（completion queue entry）轮询、buffer ring 注册这些重复逻辑全包了，且做了 ABI 兼容处理——比如内核 5.10 的IORING_OP_READV和 6.1 的字段偏移可能不同，liburing自动适配 - 你手写 mmap + barrier + cache line 对齐，稍有不慎就触发
EAGAIN或 CQE 乱序；liburing的io_uring_queue_init内部已做 full memory barrier 和 padding - 调试成本高：裸调用出问题，
strace -e trace=io_uring_setup,io_uring_enter只能看到数字 opcode，而liburing提供io_uring_sqe_set_data+ 自定义指针，方便 gdb 断点打在回调上下文上
结论：除非你在写 eBPF 辅助程序或嵌入式裁剪版，否则直接用 liburing。初始化就两行：
struct io_uring ring; int ret = io_uring_queue_init(1024, &ring, 0); // 1024 是 sq/cq size，不是并发数
读文件时 buffer 必须 pinned 吗
不是必须，但强烈建议。Linux 内核 5.19+ 支持 IORING_SETUP_IOPOLL 和用户态 buffer registration，但普通 read 类操作仍依赖 page pinning——也就是内核要确保你的 buffer 物理页不被 swap 或迁移。
如果你传的是 stack 变量地址或 malloc 分配的普通内存，io_uring 会在提交时隐式调 get_user_pages_fast，失败就回退到同步路径（性能暴跌）。所以：
- 用
posix_memalign(4096, size)分配对齐内存，比malloc更安全 - 高频小读（如数据库页读）考虑注册 buffer ring：
io_uring_register_buffers，之后所有 read/write 都复用这批 pinned page，避免反复 pin/unpin 开销 - 别用
std::vector<char></char>直接取.data()——它的内存可能被 move 析构，导致 CQE 完成时访问野地址
典型错误现象：read 返回 -EFAULT，dmesg 里出现 user buffer not pinned。
如何避免 submit/complete 死锁在多线程场景
io_uring 本身线程安全，但你的使用模式可能不安全。最常见问题是：一个线程反复 io_uring_submit，另一个线程只 io_uring_wait_cqe_nr，结果 submit 线程卡在 io_uring_enter 的 IORING_ENTER_GETEVENTS 标志上，而 wait 线程还没来得及 poll——本质是事件循环耦合太紧。
解法不是加锁，而是分层：
- 每个线程独占一个
io_uring实例（开销极小，每个 ring 约 16KB），避免跨线程竞争 SQ tail index - 若必须共享 ring，用
IORING_SETUP_SQPOLL让内核起专用 submit 线程，用户态只管填 SQ、收 CQE；但注意：SQPOLL 模式下io_uring_submit不触发 syscall，得显式io_uring_smp_store_release刷 SQ tail - 永远不要在 signal handler 或中断上下文里调
io_uring_submit——它内部有 futex 等待，会直接 panic
最容易被忽略的一点：io_uring_queue_exit 必须等所有 inflight 请求完成后再调，否则内核可能仍在访问你已 free 的 buffer，表现为随机 segfault 或 use-after-free dmesg 报告。
