GetMultipleCompletionStatus子程序

在线编辑

用途

将多个完成包从指定的 I/O 完成端口出队。

语法

#include <sys/iocp.h>
int GetMultipleCompletionStatus (CompletionPort, Nmin, Nmax, Timeout, Results[])
HANDLE CompletionPort;
DWORD Nmin, Nmax, Timeout;
struct gmcs {
    DWORD transfer_count, completion_key, errorno;
    LPOVERLAPPED overlapped;
} Results[];

描述

GetMultipleCompletionStatus子例程尝试从CompletionPort参数指定的完成端口重新排序若干完成数据包。 需要的出队完成信息包数从 Nmin 参数的值到 Nmax 参数的值不等。 在收集信息包时，此子例程可能会等待 Timeout 参数指定的预定最大时间量，以获取要到达的最小完成信息包数。 例如，如果第 X个完成数据包没有及时到达，子程序返回时只完成X-1数据包。

Timeout 参数或信号可能导致返回的补全小于 Nmin 参数的值。 换言之，除非 Timeout 参数值设置为 INFINITE ，并且信号不会中断等待，否则不保证返回 Nmin 完成。 返回零完成不视为错误。 但是， errno 值将指示具有 ETIMEDOUT 或 EINTR 错误代码的条件。 在极端低内存情况下，内核可能无法提供超时。 在这种情况下，系统调用将立即返回任何可用的完成，直至 Nmax 参数的值，并且 errno 值设置为 ENOMEM。 在调用GetMultipleCompletionStatus子程序之前，请务必将errno值设置为零，以便将子程序更改的errno值与现有值区分开来。

GetMultipleCompletionStatus子程序是 I/O 完成端口（IOCP）内核扩展的一部分。

注意：
  1. 此子例程仅使用套接字的文件描述符或用于异步 I/O 子系统的常规文件。 它不适用于其他类型的文件描述符。
  2. 此函数必须是完成端口上的互斥等待机制。 不支持通过GetMultipleCompletionStatus子程序、GetQueuedCompletionStatus子程序或两者同时进行多次等待。
  3. 当GetMultipleCompletionStatus子程序与lio_listio子程序一起使用时，可以将lio_listio子程序的cmd参数值设置为 LIO_NOWAIT_GMCS，以避免异步更新aiocb结构，从而减少开销。 在这种情况下，必须使用GetMultipleCompletionStatus子程序来等待 I/O 完成，并且只能从struct gmcs成员而不是aiocb结构中获取完成状态。 使用 LIO_NOWAIT_GMCS 值时，请勿在 gmcs 结构中使用 completion_key 值。 使用GetMultipleCompletionStatus子例程时，请勿在lio_listio子例程中使用LIO_NOWAIT_AIOWAIT值。 LIO_NOWAIT_GMCS 值可用于此目的。
  4. 取消异步 I/O 操作不会影响GetMultipleCompletionStatus子例程。 即使取消操作将活动异步 I/O 操作数减少到零，子例程也将继续等待。
  5. 在使用套接字的GetMultipleCompletionStatus子程序时，不要在超时为无限的情况下等待多次完成（Nmin> 1）。 请使用有限超时值，并准备在仍需要其他完成时重复调用。

参数

项 描述 属性描述
CompletionPort 指定此子例程将访问的完成端口的文件描述符。  
Nmin 指定最小完成次数。 如果超过 timeout 参数的值或接受信号，那么返回的值可能更少。 如果发生了其他补全，那么可能会返回更多值，最多为 Nmax 参数指定的数字。 将 Nmin 参数的值设置为零将轮询完成情况并立即返回，忽略 timeout 参数的值。  
最大值 指定要等待的最大完成数，最多为 GMCS_NMAX 宏的值。  
结果 这是用于接收完成数据的 gmcs 结构数组的地址。 数组必须包含 Nmax 参数指定的条目数的空间。  
  结果 [i]。 转账次数 指定传输的字节数。 此参数由子例程从 ith 完成包中接收的值设置。 此值限制为 2 G。
  结果 [i] .completion_key 指定与传输请求中使用的文件描述符相关联的完成键。 此参数由子例程从 ith 完成包中接收的值设置。 不要将此值与 lio_listio 子例程的 LIO_NOWAIT_GMCS 命令参数配合使用。
  结果 [i] .errorno 指定与 i 完成包关联的 errno 值。 当使用带有 LIO_NOWAIT_GMCS 命令参数的 lio_listio 子例程启动异步 I/O 请求时，必须使用此错误值，而不是使用 aiocb 结构中的 aio_errno 成员。 以检索与 I/O 请求关联的错误值。
  结果 [i]. 重叠 指定传输请求中使用的重叠结构。 此参数由子例程从 ith 完成包中接收的值设置。 对于常规文件，此参数包含指向已完成 AIO 请求的异步 I/O 控制块 (AIOCB) 的指针。 如果应用程序对常规文件的套接字和 AIO 使用相同的完成端口，那么它必须使用唯一的 completion_key 值来区分套接字和常规文件，以正确解释 重叠 参数。
超时 指定子例程等待完成包的时间量 (以毫秒计)。 此值可以设置为零。 如果此参数设置为 INFINITE ，那么子例程永远不会超时。  

返回值

项 描述
成功 子例程返回一个从零到 Nmax 参数值的整数范围，指示有多少完成信息包已取消排队。
失败 子程序返回值为-1。

错误代码

如果发生以下任何错误，那么子例程将失败:

项 描述
EINVAL CompletionPort 或其他参数的值无效。
EBUSY 另一个线程已在 I/O 完成端口上等待。
EBADF 当 CompletionPort 参数的值无效时，也可能返回此错误代码。

如果在处理某些完成后发生错误，那么将丢失错误通知。 复制结果时发生 Efault 错误可能会导致此情况。

示例

  1. 下面的程序片段说明了如何使用GetMultipleCompletionStatus子例程在 100 毫秒的窗口内排出多达 10 个完成数据包。
    struct gmcs results[10];
int n_results;
HANDLE iocpfd;
errno = 0;
n_results = GetMultipleCompletionStatus(iocpfd, 10, 10, 100, results);