WinSock I/O 模型 -- IOCP 模型

前言

IOCP 全称 Input/Ouput Completion Ports，中文中翻译一般为“完成端口”，本文中我们使用 IOCP 简写.

IOCP 模型是迄今为止最为复杂的一种 I/O 模型，但是同时通过使用 IOCP 我们往往可以达到最佳的系统性能. 当你的网络应用程序需要管理大量的 Socket I/O 请求时，你或许没有其他的选择.

本篇文章，我们将通过一个官方的 IOCP demo 程序来介绍如何使用 IOCP. 因为其复杂性，这篇文章中我们主要介绍如何使用，不深入内部的实现，更多的详细信息，请参考官方文档.

官方程序的地址：

https://github.com/microsoft/Windows-classic-samples/tree/master/Samples/Win7Samples/netds/winsock/iocp/serverex

个人感觉官方的 demo 代码不太好看（包括格式，和一些额外琐碎的可省略的细节），因此，文末我会附上自己精简过的代码，以便读者阅读. 读者按需自取.

API 基础

关于我们将要使用的数据结构：

• OVERLAPPED 结构体
• WSAEvent
• CriticalSection
• CreateThread

等相关知识，在 WinSocket I/O 模型的相关文章 WinSock I/O 模型 – OVERLAPPED I/O 模型 中均已介绍过，这里不在赘述.

CreateIoCompletionPort

CreateIoCompletionPort 方法用于创建一个 IOCP handle 或者将现有的 Socket handle 与已经创建的 IOCP 关联起来.

HANDLE WINAPI CreateIoCompletionPort(
  _In_     HANDLE    FileHandle,
  _In_opt_ HANDLE    ExistingCompletionPort,
  _In_     ULONG_PTR CompletionKey,
  _In_     DWORD     NumberOfConcurrentThreads
);

1. FileHandle： 指定与 ExistingCompletionPort 关联的文件 handle（注意不仅仅是 socket handle）。 这个 fileHandle 必须支持 overlapped I/O。 对于 Socket handle 来说，该 socket 在创建时需要指定 WSA_FLAG_OVERLAPPED 标志. 当我们想要使用这个 API 来创建一个新的 IOCP handle 时， 将这个参数设置为 INVALID_HANDLE_VALUE.
2. ExistingCompletionPort: NULL 或者一个已经使用 CreateIoCompletionPort 创建出来的 IOCP 实例. 当我们想要使用这个 API 来创建一个新的 IOCP handle 时， 将这个参数设置为 NULL. 此时，该方法的返回值是新创建出来的 IOCP 实例。 当我们想要将一个 IOCP 实例与一个 FileHandle 关联以来的时候，将这个参数设置为当前已经存在的 IOCP 实例. 此时当此次方法调用成功的时候，该方法返回是 ExistingCompletionPort.
3. CompletionKey: 此参数用于指定一个与当前 FileHandle 关联的数据结构，这个结构将包含在每个 I/O completion packet (后面我们会解释该packet) 中.
4. NumberOfConcurrentThreads： 指定最大允许的线程数， 这些线程用于处理 I/O completion packet。 这个参数仅仅在创建新的 IOCP 实例时有用，其他情况下会被忽略. 当指定为 0， 系统将使用等同与当前系统 CPU 处理器数量的线程.

GetQueuedCompletionStatus

GetQueuedCompletionStatus 方法用于从指定的 IOCP 实例上获取 I/O completion packet.

I/O completion packet：通缩来讲，当我们创建一个 IOCP实例之后，系统内部会给对应的 IOCP 实例分配一个队列，这个队列用户保存所有与当前 IOCP 关联起来的 FileHandle 上已经完成的异步任务的信息。我们将这样的保存这个队列中的已完成的异步任务的信息称作 I/O completion packet.

使用这个 API 可以从该队列中取出这些 I/O completion packet. 注意这是一个队列， 意味着即使有多个线程同时从一个 IOCP 实例上获取 I/O completion packet 时，他们也不会获取到相同的 I/O completion packet，

还有一个更高级的方法： GetQueuedCompletionStatusEx，这里我们没有使用它，暂且不提.

BOOL GetQueuedCompletionStatus(
  HANDLE       CompletionPort,
  LPDWORD      lpNumberOfBytesTransferred,
  PULONG_PTR   lpCompletionKey,
  LPOVERLAPPED *lpOverlapped,
  DWORD        dwMilliseconds
);

1. CompletionPort: IOCP 实例
2. lpNumberOfBytesTransferred：当前已完成的异步任务成功传输的字节数. 如果当前异步任务是一个发送操作，这个这个参数返回成功发送的字节数。读操作同理.
3. lpCompletionKey: 我们在将一个 FileHandle 和 IOCP实例关联起来时指定了一个 lpCompletionKey，在这个 FileHandle 上有任务完成，我们通过GetQueuedCompletionStatus 获取到该任务完成的 I/O completion packet 时，这个参数便等于我们指定的那个 lpCompletionKey.
4. lpOverlapped: 提交异步任务给 IOCP 实例时所指定的 OVERLAPPED 结构体. 我们之前说过，OVERLAPPED 数据结构就像是一个异步任务的id，我们在开始一个异步任务的时候需要指定一个 OVERLAPPED结构体，当这个异步任务完成时，操作系统便可以通过返回这个 OVERLAPPED 结构体给我们，这样我们便能得知是我们提交的哪个异步任务完成了. 关于这个数据结构的使用，还有一些技巧，我们后边再解释.
5. dwMilliseconds: 指定一个超时时间，在指定时间内没有获取到任何 I/O completion packet，该方法将会返回, 此时该方法返回 FALSE. 实例中，我们将使用 INFINITE 来让这个方法一直阻塞，直到有至少一个任务完成.

返回值：
当该方法成功的获取到一个 I/O completion packet 时，该方法会返回 TRUE。 此时，lpNumberOfBytes，lpOverlapped， lpCompletionKey 会被填充上与当前 I/O completion packet 对应的数据结构.

当该方法调用失败时，该方法会返回 FALSE。此时 lpNumberOfBytes，lpOverlapped， lpCompletionKey 的可能返回值如下：

• lpOverlapped 返回参数是 NULL， 代表我们没有从 IOCP 实例上获取到任何异步任务的完成信息. lpNumberOfBytes， lpCompletionKey 也不包含任何有效信息.
• lpOverlapped 返回参数不为 NULL， 代表我们从 IOCP 实例上获取到了异步任务的信息. 这种情况下，该异步任务发生了错误， lpNumberOfBytes，lpOverlapped， lpCompletionKey 返回参数上保存这个失败的任务的信息。 详细的错误信息需要使用 GetLastError.来获取.

当该方法返回 FALSE，且 lpOverlapped 是 NULL， GetLastError 返回 ERROR_ABANDONED_WAIT_0， 代表当前 IOCP 实例被关闭.

HasOverlappedIoCompleted

HasOverlappedIoCompleted 是一个宏，这个宏用来查询在当前 IOCP 实例上是否有正在执行的异步任务.

void HasOverlappedIoCompleted(
   lpOverlapped
);

lpOverlapped 返回参数表示当前处于 Pending 状态的异步任务所关联的 OVERLAPPED 结构体.

如果你的异步任务不处于 ERROR_IO_PENDING， 在这种情况下，不要使用该宏

我们已经直到如何创建一个 IOCP 实例，以及如何得到异步任务完成的通知，我们接下来看看如何提交一个异步任务。

注意，我们将只关注这些 API 与 IOCP 搭配使用，不再提及他们支持的其他操作.

AcceptEx

AcceptEx 方法用来接收新连接.

BOOL AcceptEx(
  SOCKET       sListenSocket,
  SOCKET       sAcceptSocket,
  PVOID        lpOutputBuffer,
  DWORD        dwReceiveDataLength,
  DWORD        dwLocalAddressLength,
  DWORD        dwRemoteAddressLength,
  LPDWORD      lpdwBytesReceived,
  LPOVERLAPPED lpOverlapped
);

1. sAcceptSocket: 不同与 accept 方法，因为我们异步的接收新连接，因此，在调用此方法之前，我们需要创建一个 Socket Handle 来保存新接收到的 Socket 实例.
2. lpOutputBuffer: 该方法支持在接收连接的同时，解析该新socket的本地和远程地址，同时接收一块数据。接收到的数据会从该buffer 的开始位置，地址相关的数据紧跟这个接收到的数据.
3. dwReceiveDataLength： 用于指定我们用来期待接收到的第一块儿数据的长度. 当该参数为 0 时，意味着我们不接收数据，只接收新的连接. 此时， lpOutputBuffer 仅仅用来保存本地和远程地址。
4. dwLocalAddressLength， dwRemoteAddressLength： 指定需要为保存本地/远程地址应该在 lpOutputBuffer 中保留的地址。 该参数至少为 16，不能为 0.
5. lpdwBytesReceived： 返回我们接收到的第一块儿数据的长度. 这个参数仅仅在 AcceptEx 方法立马成功的情况下有效，如果当前接收操作返回 ERROR_IO_PENDING 错误，该返回值无效.
6. lpOverlapped：指定与当前异步接收操作关联的 OVERLAPPED 结构体.

返回值：

• 当该方法调用立马成功时，该方法返回 TRUE.
• 当该方法没有立马成功时，该方法返回 FALSE。 此时应该使用 WSAGetLastError 获取具体的错误信息. 如果 WSAGetLastError 返回 ERROR_IO_PENDING，代表该接收任务已经提交成功，当前正在进行中.

值得一提的是： 官方文档中明确表明，该方法的性能远远高于 accept 方法。

WSARecv

WSARecv 用于从一个处于连接状态的 Socket 上接收数据.

int WSAAPI WSARecv(
  SOCKET                             s,
  LPWSABUF                           lpBuffers,
  DWORD                              dwBufferCount,
  LPDWORD                            lpNumberOfBytesRecvd,
  LPDWORD                            lpFlags,
  LPWSAOVERLAPPED                    lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

这里的 lpOverlapped 参数同 AcceptEx 方法中的 lpOverlapped 参数.

dwBuffers 用于指定一个用于保存接收到的数据的 buffer的数组。 dwBufferCount 指定 buffer 数组中的 buffer 数量。
lpNumberOfBytesRecvd：如果当前读操作立马完成，这个参数用于保存接收到的数据长度. 如果当前任务没有立即完成，而是处于 pending状态，那个这个参数的值无效.
lpCompletionRoutine： 本例中，我们不适用这个参数，因此指定为空。 我们使用 GetQueuedCompletionStatus 方法来异步的获取该接收任务完成的通知.

WSASend

WSASend 用于从一个处于连接状态的 Socket 上发送数据.

int WSAAPI WSASend(
  SOCKET                             s,
  LPWSABUF                           lpBuffers,
  DWORD                              dwBufferCount,
  LPDWORD                            lpNumberOfBytesSent,
  DWORD                              dwFlags,
  LPWSAOVERLAPPED                    lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

这个方法几乎和 WSARecv 相同，不再赘述。

实现思路

1. 创建一个 socket 作为监听 socket
2. 创建 IOCP 实例，并将 server socket 和 IOCP 实例关联起来
3. 使用 AcceptEx 提交异步 accept 任务。
4. 创建多个子线程， 在子线程中使用 GetQueuedCompletionStatus 阻塞的等待异步任务完成的通知（I/O completion packet）。并处理该通知。
5. 主线程一直阻塞，直到服务器退出, IOCP 实例关闭.

这个流程说起来是非常简单，但是简单的流程中隐藏了极多的细节，这里我们来详细描述一下我们这个 IOCP服务器的实现思路：

1. 首先，在我们创建了 server socket 之后，我们紧接着就需要创建对应的 IOCP实例（使用 CreateIoCompletePort）。同时将 server socket 与 IOCP 实例关联起来（使用 CreateIoCompletePort）。 在关联当前 server socket 实例的同时，我们需要指定一个 lpCompletionKey。我们需要在这个 lpCompletionKey 结构中存入足够多的信息，以便我们在收到该 server socket 上异步任务完成通知时，做出相应操作时有足够的信息.

这里，我们看看实例代码中作为 lpCompletionKey 的结构是什么样子的：

typedef struct _PER_SOCKET_CONTEXT {
   
	SOCKET                      Socket;

	LPFN_ACCEPTEX               fnAcceptEx;

	PPER_IO_CONTEXT             pIOContext;  
	struct _PER_SOCKET_CONTEXT  *pCtxtBack; 
	struct _PER_SOCKET_CONTEXT  *pCtxtForward;
} PER_SOCKET_CONTEXT, *PPER_SOCKET_CONTEXT;

Socket 字段： 当一个任务完成时，我们需要直到是哪个 socket 上的任务完成了，而 GetQueuedCompletionStatus 的返回值中并没有这个信息，因此我们需要自己保存。


fnAcceptEx： 这个字段的存在是因为 AcceptEx 方法的特殊性决定的。 我们无法直接调用 AcceptEx 方法，而是需要先通过 WSAIoctl 搭配 SIO_GET_EXTENSION_FUNCTION_POINTER 这个参数来动态的获取该方法的指针。 并且该方法指针是和对应的 Server socket 绑定的，也就是如果你有多个 server socket，那么这个函数指针也会有多个。 因此，这个字段不得不存储起来


pIOContext：这个字段用于保存在当前 socket 上执行异步任务需要使用的 Overlapped 结构体的数据。 (接下来，我们会更加详细来说这个结构)


pCtxBack 和 pCtxForward：这个真的不是必须的，如果你使用其他方式维护多个 _PER_SOCKET_CONTEXT 数据结构，那个两个字段完全不需要.

3. 在将 Server socket 和 IOCP 绑定之后，我们需要启用其他线程使用 GetQueuedCompletionStatus 来处理完成的异步任务。这里需要斟酌的点是？ 我们需要使用几个线程，这些线程是应该的阻塞的等待还是使用 timeout 来一轮询的方式等待，这需要读者自己好好斟酌。

4. 将 server socket 和 IOCP 实例关联起来之后， 处理任务完成通知的线程也有了，我们如何让 server socket 开始接收新的连接呢 ？使用 accept ？ 不，这里我们不是用它，它是阻塞的方式，这里我们用 AcceptEx 来异步的接收新连接。 那么我们如何做呢？

要使用 AcceptEx，非常重要的一点是，我们得先有个 Overlapped 结构体. 直接创建一个 Overlapped 结构体实例使用好不好？ 也不能说不好，但是就目前看到的 IOCP 实现中，没有人这样玩儿（本人看过两个 IOCP 的实现，不包括微软的官方demo，报错 libuv）。

目前，他们使用的方法都是将 Overlapped 数据结构包进另外一个结构体。 demo 中的结构体如下：

typedef struct _PER_IO_CONTEXT {
   
	WSAOVERLAPPED               Overlapped;
	char                        Buffer[MAX_BUFF_SIZE];
	WSABUF                      wsabuf;
	int                         nTotalBytes;
	int                         nSentBytes;
	IO_OPERATION                IOOperation;
	SOCKET                      SocketAccept; 

	struct _PER_IO_CONTEXT      *pIOContextForward;
} PER_IO_CONTEXT, *PPER_IO_CONTEXT;

注意，这个 _PER_IO_CONTEXT 包含在 _PER_SOCKET_CONTEXT（也就是我们 lpCompletionKey） 这个结构体中。
Overlapped: 这个字段自然是必须存在的.
IOOperation: 指明我们当前异步任务的类型，它的类型 IO_OPERATION： accept， send， read
SocketAccept： 如果我们当前异步任务是一个 accept 任务，那个这个字段用来存储我们新接收到的 socket 实例
wsaBuf: 这个字段是我们提交读或者写任务是需要传给 WSARecv 或 WSARead 的一个数据结构。
Buffer 是我们真正用来存储数据的地方。 WSABuf 这个结构中只包含一个 buffer 的指针，和这个buffer 的长度。这个 demo 中这样设计，那么毫无疑问， WSABuf 中的 buffer 指针必然指向 Buffer。 发送或接收到的数据都需要存在这儿
nTotalbytes， nSentBytes 用来存储要发送或者接收到的数据长度
pIOcontextForward: 这个字段存在的是因为： 我们将一个 Socket 与 _PER_SOCKET_CONTEXT 关联，而一个 _PER_SOCKET_CONTEXT 中仅仅包含一个 _PER_IO_CONTEXT（也就是 Overlapped 结构），那么如何应对在一个socket 上进行多个异步任务的场景呢？ 此时就需要多个 _PER_IO_CONTEXT 实例了，此时这个链表就发挥作用了。


这里唯一值得注意的是： Overlapped结构体放在 _PER_IO_CONTEXT 第一个字段，它的好处是，在我们使用 GetQueuedCompletionStatus 获取到当前完成的异步任务的 lpOverlapped 参数时，我们可以直接将该指针强转为 _PER_IO_CONTEXT， 这样我们便能直到当前具体的 I/O 操作是什么。 而 _PER_SOCKET_CONTEXT 这个结构会作为 lpCompletionKey 被GetQueuedCompletionStatus 返回，此时我们便有了当前 Socket 所有的上下文.


这种设计下， 一个 _PER_IO_CONTEXT 结构便 对应一个异步任务，如果一个 socket 有多个异步任务，那么便需要有多个 _PER_IO_CONTEXT 结构.
至于这个 demo 中，对于这个结构体的设计，在实际使用中，有很多需要斟酌的地方。

到了这里，我们使用 WSARecv 和 WSASend 也就不难了。

实例

代码较多，细细品味

// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (C) Microsoft Corporation.  All Rights Reserved.
//

#pragma warning (disable:4127)
#pragma comment(lib,"ws2_32.lib")

#include <winsock2.h>
#include <mswsock.h>
#include <Ws2tcpip.h>
#include <stdio.h>
#include <stdlib.h>
#include <strsafe.h>

#define DEFAULT_PORT        "5001"
#define MAX_BUFF_SIZE       8192
#define MAX_WORKER_THREAD   16

#define xmalloc(s) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, (s))
#define xfree(p)   HeapFree(GetProcessHeap(), 0, (p))

typedef enum _IO_OPERATION {
   
	ClientIoAccept,
	ClientIoRead,
	ClientIoWrite
} IO_OPERATION, *PIO_OPERATION;

typedef struct _PER_IO_CONTEXT {
   
	WSAOVERLAPPED               Overlapped;
	char                        Buffer[MAX_BUFF_SIZE];
	WSABUF                      wsabuf;
	int                         nTotalBytes;
	int                         nSentBytes;
	IO_OPERATION                IOOperation;
	SOCKET                      SocketAccept; 

	struct _PER_IO_CONTEXT      *pIOContextForward;
} PER_IO_CONTEXT, *PPER_IO_CONTEXT;

// 作为 lpCompletionKey 使用
// 每个 socket 对应一个 _PER_SOCKET_CONTEXT 结构
// 该 socket 上的异步任务信息存储在 pIoContext 中，该结构中是一个链表，因此 pIoContext 应当被当作一个动态数组来看待
typedef struct _PER_SOCKET_CONTEXT {
   
	SOCKET                      Socket;
    LPFN_ACCEPTEX               fnAcceptEx;
	PPER_IO_CONTEXT             pIOContext;  
	
	struct _PER_SOCKET_CONTEXT  *pCtxtBack; 
	struct _PER_SOCKET_CONTEXT  *pCtxtForward;
} PER_SOCKET_CONTEXT, *PPER_SOCKET_CONTEXT;

BOOL CreateListenSocket(void);
BOOL CreateAcceptSocket(BOOL fUpdateIOCP);
DWORD WINAPI WorkerThread(LPVOID WorkContext);

PPER_SOCKET_CONTEXT UpdateCompletionPort(SOCKET s, IO_OPERATION ClientIo, BOOL bAddToList);

PPER_SOCKET_CONTEXT CtxtAllocate(SOCKET s, IO_OPERATION ClientIO);
VOID CloseClient(PPER_SOCKET_CONTEXT lpPerSocketContext, BOOL bGraceful);
VOID CtxtListFree();
VOID CtxtListAddTo(PPER_SOCKET_CONTEXT lpPerSocketContext);
VOID CtxtListDeleteFrom(PPER_SOCKET_CONTEXT lpPerSocketContext);

BOOL                g_bEndServer                        = FALSE;
BOOL                g_bRestart                          = TRUE;
HANDLE              g_hIOCP                             = INVALID_HANDLE_VALUE;
SOCKET              g_sdListen                          = INVALID_SOCKET;
HANDLE              g_ThreadHandles[MAX_WORKER_THREAD];
WSAEVENT            g_hCleanupEvent[1];
PPER_SOCKET_CONTEXT g_pCtxtListenSocket                 = NULL;
PPER_SOCKET_CONTEXT g_pCtxtList                         = NULL;
CRITICAL_SECTION    g_CriticalSection;

int myprintf(const char *lpFormat, ...);

void main()	{
   

	SYSTEM_INFO systemInfo;
	WSADATA     wsaData;
	DWORD       dwThreadCount = 0;
	int         nRet = 0;
	HANDLE      hThread;
	DWORD       dwThreadId;

	g_ThreadHandles[0] = (HANDLE)WSA_INVALID_EVENT;

	for (int i = 0; i < MAX_WORKER_THREAD; i++) {
   
		g_ThreadHandles[i] = INVALID_HANDLE_VALUE;
	}

	GetSystemInfo(&systemInfo);
	dwThreadCount = systemInfo.dwNumberOfProcessors * 2;

	if (WSA_INVALID_EVENT == (g_hCleanupEvent[0] = WSACreateEvent())) {
   
		myprintf("WSACreateEvent() failed: %d\n", WSAGetLastError());
		return;
	}

	if ((nRet = WSAStartup(0x202, &wsaData)) != 0) {
   
		myprintf("WSAStartup() failed: %d\n",nRet