Winsock - CreateIoCompletionPort

Syntax

Copy

HANDLE WINAPI CreateIoCompletionPort(
  __in      HANDLE FileHandle,
  __in_opt  HANDLE ExistingCompletionPort,
  __in      ULONG_PTR CompletionKey,
  __in      DWORD NumberOfConcurrentThreads
);

Parameters

CompletionKey [in]

The per-handle user-defined completion key that is included in every I/O completion packet for the specified file handle. For more information, see the Remarks section.

用户自定义的单句柄完成键，包含在每个指定的HANDLE的I/O完成包中

NumberOfConcurrentThreads [in]

The maximum number of threads that the operating system can allow to concurrently process I/O completion packets for the I/O completion port. This parameter is ignored if the ExistingCompletionPort parameter is not NULL.

允许并发的最大线程数，也就是OS允许的在完成端口上并行的I/O完成包的最大值

If this parameter is zero, the system allows as many concurrently running threads as there are processors in the system.

设置为0的话，则系统允许的并行数和你电脑上CPU的数量一致

Return Value

If the function succeeds, the return value is the handle to an I/O completion port:

函数调用成功返回一个指向完成端口的HANDLE

• If the ExistingCompletionPort parameter was NULL, the return value is a new handle.

• If the ExistingCompletionPort parameter was a valid I/O completion port handle, the return value is that same handle.

• If the FileHandle parameter was a valid handle, that file handle is now associated with the returned I/O completion port.

If the function fails, the return value is NULL. To get extended error information, call the GetLastError function.

函数调用失败返回NULL，用GetLastError取得错误代码 WSAGetLastError()不知道行不行

Remarks

The I/O system can be instructed to send I/O completion notification packets to I/O completion ports, where they are queued. The CreateIoCompletionPortfunction provides this functionality.

CreateIoCompletionPort 提供这样一种功能，指示I/O系统给完成端口发送I/O完成通知包

An I/O completion port and its handle are associated with the process that created it and is not shareable between processes. However, a single handle is shareable between threads in the same process.

在进程中创建的完成端口以及与其相关联的HANDLE，尽在其线程中共享，而不与其他的进程共享

 

 

To create an I/O completion port without associating it, set the FileHandle parameter to INVALID_HANDLE_VALUE, the ExistingCompletionPort parameter to NULL, and the CompletionKey parameter to zero (which is ignored in this case). Set the NumberOfConcurrentThreads parameter to the desired concurrency value for the new I/O completion port, or zero for the default (the number of processors in the system).

The handle passed in the FileHandle parameter can be any handle that supports overlapped I/O. Most commonly, this is a handle opened by the CreateFile function using the FILE_FLAG_OVERLAPPED flag (for example, files, mail slots, and pipes). Objects created by other functions such as socket can also be associated with an I/O completion port. For an example using sockets, see AcceptEx. A handle can be associated with only one I/O completion port, and after the association is made, the handle remains associated with that I/O completion port until it is closed.

任何支持重叠I/O的HANDLE都能作为一个参数

大多数情况下，这个参数由CreateFile打开，在创建的时候需要指定FILE_FLAG_OVERLAPPED标志

(例如,文件,邮槽,管道)

由其他函数创建的对象,比如WSASocket 创建的 Socket (WSA_FLAG_OVERLAPPED标志)也能与完成端口关联

在HANDLE被关闭之前，它将一直与完成端口保持关联

For more information on I/O completion port theory, usage, and associated functions, see I/O Completion Ports.

有关更多完成端口原理，用法，和相关函数，查看 I/O Completion Ports.

Multiple file handles can be associated with a single I/O completion port by calling CreateIoCompletionPort multiple times with the same I/O completion port handle in the ExistingCompletionPort parameter and a different file handle in the FileHandle parameter each time.

多个HANDLE想要和同一个完成端口进行关联的话，只需要多次调用CreateIoCompletionPort 即可

Use the CompletionKey parameter to help your application track which I/O operations have completed. This value is not used by CreateIoCompletionPort for functional control; rather, it is attached to the file handle specified in the FileHandle parameter at the time of association with an I/O completion port. This completion key should be unique for each file handle, and it accompanies the file handle throughout the internal completion queuing process. It is returned in theGetQueuedCompletionStatus function call when a completion packet arrives. The CompletionKey parameter is also used by the PostQueuedCompletionStatusfunction to queue your own special-purpose completion packets.

CompletionKey 能帮助你追踪完成的是哪个I/O操作，这个参数不是用来给 CreateIoCompletionPort 函数提供控制

这个参数与之前绑定完成端口指定的HANDLE有关

与HANDLE相关的CompletionKey都应该独一无二，该参数在internal completion queuing过程中一直在伴随HANDLE

当一个完成包到达时，该参数在GetQueuedCompletionStatus的调用中返回

该参数同样用在PostQueuedCompletionStatus函数中用来插入你指定目的的完成包

After an instance of an open handle is associated with an I/O completion port, it cannot be used in the ReadFileEx or WriteFileEx function because these functions have their own asynchronous I/O mechanisms.

在关联一个已经实例化的HANDLE到完成端口以后，不能调用ReadFileEx or WriteFileEx 函数，因为这些函数有自己的异步I/O机制

 

The I/O completion port handle and every file handle associated with that particular I/O completion port are known as references to the I/O completion port. The I/O completion port is released when there are no more references to it. Therefore, all of these handles must be properly closed to release the I/O completion port and its associated system resources. After these conditions are satisfied, close the I/O completion port handle by calling the CloseHandle function.

在调用CloseHandle关闭完成端口对象之前，必须确保已经释放了所有与完成端口相关联的HANDLE以及其他相关的系统资源

It is best not to share a file handle associated with an I/O completion port by using either handle inheritance or a call to the DuplicateHandle function. Operations performed with such duplicate handles generate completion notifications. Careful consideration is advised.