CreateIoCompletionPort函数

创建输入/输出（I / O）完成端口并将其与指定的文件句柄相关联，或创建尚未与文件句柄相关联的I / O完成端口，从而允许以后进行关联。

将打开的文件句柄的实例与I / O完成端口相关联，可使进程接收有关该文件句柄的异步I / O操作完成的通知。

注意  

此处使用的术语文件句柄是指表示重叠的I / O端点的系统抽象，而不仅仅是磁盘上的文件。任何支持重叠I / O的系统对象（例如网络端点，TCP套接字，命名管道和邮件插槽）都可以用作文件句柄。有关更多信息，请参见“备注”部分。

 

句法

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

参数

FileHandle

打开的文件句柄或INVALID_HANDLE_VALUE。

该句柄必须指向支持重叠I / O的对象。

如果提供了句柄，则必须打开它才能完成I / O重叠。例如，在使用CreateFile函数获取句柄时，必须指定FILE_FLAG_OVERLAPPED标志 。

如果指定了INVALID_HANDLE_VALUE，该函数将创建一个I / O完成端口，而不将其与文件句柄关联。在这种情况下，ExistingCompletionPort参数必须为NULL，并且CompletionKey参数将被忽略。

ExistingCompletionPort

现有I / O完成端口或NULL的句柄。

如果此参数指定了现有的I / O完成端口，则该函数将其与FileHandle参数指定的句柄相关联。如果成功，该函数将返回现有I / O完成端口的句柄；它不会创建新的I / O完成端口。

如果此参数为NULL，则该函数将创建一个新的I / O完成端口，并且如果FileHandle参数有效，则将其与新的I / O完成端口关联。否则，不会发生文件句柄关联。如果成功，该函数将句柄返回到新的I / O完成端口。

CompletionKey

每个句柄用户定义的完成密钥，包含在指定文件句柄的每个I / O完成数据包中。有关更多信息，请参见“备注”部分。

NumberOfConcurrentThreads

操作系统可以允许同时处理I / O完成端口的I / O完成数据包的最大线程数。如果ExistingCompletionPort参数不为NULL，则忽略此参数。

如果此参数为零，则系统允许的并发运行线程数与系统中的处理器数量一样。

返回值

如果函数成功，则返回值是I / O完成端口的句柄：

• 如果ExistingCompletionPort参数为NULL，则返回值为新句柄。
• 如果ExistingCompletionPort参数是有效的I / O完成端口句柄，则返回值就是该句柄。
• 如果FileHandle参数是有效的句柄，则该文件句柄现在与返回的I / O完成端口关联。

如果函数失败，则返回值为NULL。若要获取扩展的错误信息，请调用GetLastError函数。

备注

可以指示I / O系统向排队的I / O完成端口发送I / O完成通知包。该 CreateIoCompletionPort函数提供了此功能。

I / O完成端口及其句柄与创建它的进程相关联，并且不能在进程之间共享。但是，在同一进程中的线程之间可以共享一个句柄。

CreateIoCompletionPort可以在三种不同的模式下使用：

• 仅创建一个I / O完成端口，而不将其与文件句柄关联。
• 将现有的I / O完成端口与文件句柄相关联。
• 在一个调用中执行创建和关联。

要创建不关联的I / O完成端口，请将FileHandle参数设置为INVALID_HANDLE_VALUE，将ExistingCompletionPort参数设置为NULL，并将CompletionKey参数设置为零（在这种情况下将被忽略）。对于新的I / O完成端口，将NumberOfConcurrentThreads参数设置为所需的并发值，对于默认值（系统中的处理器数量），请将其设置为零。

在FileHandle参数中传递的句柄可以是任何支持重叠I / O的句柄。最常见的是，这是由CreateFile函数使用FILE_FLAG_OVERLAPPED标志打开的句柄（例如，文件，邮件插槽和管道）。由其他功能（例如套接字）创建的对象也可以与I / O完成端口关联。有关使用套接字的示例，请参见AcceptEx。一个句柄只能与一个I / O完成端口相关联，并且在建立关联之后，该句柄将一直与该I / O完成端口相关联，直到关闭它为止。

有关I / O完成端口理论，用法和相关功能的更多信息，请参见I / O完成端口。

通过使用ExistingCompletionPort参数中的相同I / O完成端口句柄和FileHandle参数中的不同文件句柄多次调用CreateIoCompletionPort多次，可以将多个文件句柄与单个I / O完成端口关联。

使用CompletionKey参数可帮助您的应用程序跟踪已完成的I / O操作。CreateIoCompletionPort不会使用此值进行功能控制；而是在与I / O完成端口关联时将其附加到FileHandle参数中指定的文件句柄。对于每个文件句柄，此完成密钥应该是唯一的，并且在整个内部完成排队过程中，它会伴随文件句柄。当完成数据包到达时，它在GetQueuedCompletionStatus函数调用中返回。该CompletionKey参数也使用PostQueuedCompletionStatus功能排队自己的专用完成包。

将打开句柄的实例与I / O完成端口关联后，由于这些函数具有其自己的异步I / O机制，因此无法在ReadFileEx或 WriteFileEx函数中使用它 。

最好不要通过句柄继承或对DuplicateHandle函数的调用来共享与I / O完成端口关联的文件句柄 。使用此类重复句柄执行的操作将生成完成通知。建议仔细考虑。

I / O完成端口句柄以及与该特定I / O完成端口关联的每个文件句柄都称为对I / O完成端口的引用。没有更多引用时，将释放I / O完成端口。因此，必须正确关闭所有这些句柄才能释放I / O完成端口及其关联的系统资源。满足这些条件后，通过调用CloseHandle函数关闭I / O完成端口句柄 。

在Windows 8和Windows Server 2012中，以下技术支持此功能。