IOCP不是线程池，正确使用需以FILE_FLAG_OVERLAPPED打开文件、堆分配绑定业务数据的OVERLAPPED结构体、设ol.hEvent为NULL，并通过CONTAINING_RECORD从完成包还原上下文。
IOCP 不是线程池，别直接 CreateIoCompletionPort 后就开线程等 GetQueuedCompletionStatus
很多人一上来就调用 CreateIoCompletionPort，然后在多个线程里死循环调用 GetQueuedCompletionStatus，以为这就是“异步 IO”。其实这只是完成了端口绑定和等待机制，真正让文件操作异步的关键，在于必须使用 FILE_FLAG_OVERLAPPED 标志打开文件，并且所有读写都必须传入有效的 LPOVERLAPPED 结构体。
常见错误现象：GetQueuedCompletionStatus 永远不返回、返回 FALSE 且 GetLastError() 是 ERROR_IO_PENDING 却没后续通知、或干脆同步完成（没走 IOCP 流程）。
- 打开文件时漏掉
FILE_FLAG_OVERLAPPED→ 所有ReadFile/WriteFile强制同步，IOCP 收不到通知 -
LPOVERLAPPED是栈变量且函数返回后就销毁 → 内存被复用，IO 完成时写入野地址，极大概率崩溃 - 调用
ReadFile返回TRUE（立即完成）但没检查lpNumberOfBytesRead→ 误以为异步，实际是同步读完，IOCP 根本不触发
如何正确封装一个可重用的异步文件句柄类
核心是把 OVERLAPPED 和业务上下文（比如缓冲区指针、回调函数、请求 ID）绑在一起，避免裸指针管理。Windows 要求 OVERLAPPED 在 IO 完成前必须有效，所以推荐堆分配 + RAII 管理。
示例关键结构：
struct AsyncFileOp {
OVERLAPPED ol;
HANDLE hFile;
std::vector<char> buffer;
std::function<void dword> callback; // (error, bytes)
AsyncFileOp(HANDLE h, size_t sz) : hFile(h), buffer(sz) {
ZeroMemory(&ol, sizeof(ol));
ol.hEvent = NULL; // 必须为 NULL，否则 IOCP 可能不投递
}
};</void></char>
-
ol.hEvent必须设为NULL，否则GetQueuedCompletionStatus可能跳过该完成包 - 不要用
std::shared_ptr——OVERLAPPED是 POD，不能继承或虚析构；用std::unique_ptr更安全 - 缓冲区（
buffer）必须在AsyncFileOp生命周期内有效，不能传入局部数组或临时std::string::data()
GetQueuedCompletionStatus 返回后，怎么区分是哪个操作完成了
Windows 不提供“完成包 ID”，只返回你当初传进去的 ULONG_PTR CompletionKey 和 LPOVERLAPPED 指针。所以 CompletionKey 应该是句柄级别标识（比如文件 ID 或对象指针），而具体操作上下文必须从 LPOVERLAPPED* 反推。
最稳妥做法：让 OVERLAPPED 成为结构体的第一个成员，这样通过指针偏移就能还原结构体首地址：
struct AsyncFileOp {
OVERLAPPED ol; // 必须第一项
HANDLE hFile;
...
};
// 在完成回调中：
AsyncFileOp* op = CONTAINING_RECORD(lpOverlapped, AsyncFileOp, ol);
- 别用
reinterpret_cast—— 如果(lpOverlapped) OVERLAPPED不是首成员，偏移错，UB -
CompletionKey建议设为reinterpret_cast（当前文件对象），用于快速过滤无效句柄(this) - 如果一个句柄对应多种操作（读/写/flush），靠
ol.Internal或自定义字段（如ol.Pointer）做类型标记更可靠
为什么 WriteFile 异步后，文件内容还是乱序或丢失
IOCP 本身不保证顺序 —— 它只保证每个 OVERLAPPED 对应的完成通知是原子的。但多个并发 WriteFile 请求若没有显式控制偏移，会相互覆盖。
- 必须手动指定
ol.Offset和ol.OffsetHigh，不能依赖文件指针（SetFilePointerEx在 overlapped 模式下无效） - 写同一区域前需加锁（如
SRWLock），或用单线程序列化写请求，否则数据竞争不可避免 - 关闭句柄前务必调用
FlushFileBuffers(hFile)，否则内核缓存可能未落盘，尤其在程序异常退出时 - 大文件写入建议分块（如 64KB），避免单次
WriteFile跨页或触发非分页池耗尽
IOCP 的复杂点不在 API 调用，而在状态管理和内存生命周期。最容易被忽略的是：OVERLAPPED 不是“参数”，它是异步操作的唯一身份证，它的生存期必须严格覆盖从发起 IO 到收到完成通知的全过程 —— 少一秒，就 crash 或静默失败。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
