C# 使用 IOCP 完成端口基礎入門（一）

前言

I/O 完成端口（IOCP）是 Windows 高效能非同步 I/O 模型的核心。本文為系列第一篇，介紹三大核心 API：CreateIoCompletionPort、PostQueuedCompletionStatus、GetQueuedCompletionStatus，並說明 SafeHandle 管理核心物件的最佳實務。

核心 API 總覽

CreateIoCompletionPort 參數詳解

[DllImport("kernel32.dll", CharSet = CharSet.Auto, SetLastError = true)]
public static extern SafeFileHandle CreateIoCompletionPort(
    IntPtr FileHandle,           // 要關聯的檔案/通訊端控制代碼，首次建立傳 -1
    IntPtr ExistingCompletionPort, // 現有完成端口，首次建立傳 IntPtr.Zero
    IntPtr CompletionKey,        // 單一控制代碼資料（如 Socket），首次建立傳 IntPtr.Zero
    uint NumberOfConcurrentThreads); // 允許並發執行緒數，0 表 CPU 核心數

為何使用 SafeFileHandle？

• 完成端口為核心物件，需顯式釋放，否則洩漏。
• SafeHandle 衍生自 CriticalFinalizerObject，CLR 保證其 Finalizer 最後執行，避免 ThreadAbortException 導致洩漏。
• 內建參考計數與 IDisposable，配合 using 區塊最安全。

PostQueuedCompletionStatus 參數詳解

[DllImport("Kernel32", CharSet = CharSet.Auto)]
private static extern bool PostQueuedCompletionStatus(
    SafeFileHandle CompletionPort,   // 目標完成端口
    uint dwNumberOfBytesTransferred, // 傳遞資料大小（指標通常 4/8 位元組）
    IntPtr dwCompletionKey,          // 單一控制代碼資料，本範例用 IntPtr.Zero
    IntPtr lpOverlapped);            // 自訂資料指標（透過 GCHandle 傳遞物件）

• 主執行緒可發送結束訊號、控制指令等自訂訊息給工作執行緒。
• dwNumberOfBytesTransferred 設為 sizeof(IntPtr) 或 4 即可。

完成端口建立與工作執行緒架構

1. 主執行緒呼叫 CreateIoCompletionPort(-1, 0, 0, 1) 建立獨立完成端口。
2. 啟動工作執行緒，傳入完成端口 SafeFileHandle。
3. 工作執行緒迴圈呼叫 GetQueuedCompletionStatus 等待訊息。
4. 主執行緒透過 PostQueuedCompletionStatus 發送資料或結束指令。
5. 工作執行緒收到結束指令後 Dispose() 完成端口並退出迴圈。

結語

理解三大 API 角色與 SafeHandle 資源管理，是掌握 IOCP 的第一步。後續文章將實作物件傳遞、Socket 整合與高效能伺服器模型。