Dequeues multiple completion packets from a specified I/O completion port.
#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[];
The GetMultipleCompletionStatus subroutine attempts to dequeue a number of completion packets from the completion port that is specified by the CompletionPort parameter. The number of dequeued completion packets that are wanted ranges from the value of the Nmin parameter through the value of the Nmax parameter. As it collects the packets, this subroutine might wait a predetermined maximum amount of time that is specified by the Timeout parameter for the minimum number of completion packets to arrive. If, for example, the Xth completion packet does not arrive in time, the subroutine returns with only X-1 packets completed.
Either the Timeout parameter or a signal might cause a return with completions fewer than the value of the Nmin parameter. In other words, Nmin completions are not guaranteed to be returned unless the Timeout parameter value is set to INFINITE, and a signal does not interrupt the wait. The return of zero completions is not considered an error. The errno value will, however, indicate the condition with either the ETIMEDOUT or EINTR error code. In extreme low-memory situations, the kernel might not be able to provide a timeout. In this case, the system call returns immediately with any available completions, up to the value of the Nmax parameter, and the errno value is set to ENOMEM. Be sure to set the errno value to zero before calling the GetMultipleCompletionStatus subroutine so that the change of the errno value that the subroutine makes can be distinguished from the existing value.
The GetMultipleCompletionStatus subroutine is part of the I/O Completion Port (IOCP) kernel extension.
Item | Description | Attribute description |
---|---|---|
CompletionPort | Specifies the file descriptor for the completion port that this subroutine will access. | |
Nmin | Specifies the minimum number of completions. Fewer might be returned if the value of the timeout parameter is exceeded, or a signal accepted. More might be returned, up to the number that is specified by the Nmax parameter, if additional completions have occurred. Setting the value of the Nmin parameter to zero will poll for completions and return immediately, ignoring the value of the timeout parameter. | |
Nmax | Specifies the maximum number of completions to wait for, up to the value of the GMCS_NMAX macro. | |
Results | This is the address of an array of the gmcs structure to receive the completion data. The array must contain space for the number of entries specified by the Nmax parameter. | |
Results[i]. transfer_count | Specifies the number of bytes transferred. This parameter is set by the subroutine from the value received in the ith completion packet. This value is limited to 2 G. | |
Results[i].completion_key | Specifies the completion key associated with the file descriptor that is used in the transfer request. This parameter is set by the subroutine from the value received in the ith completion packet. Do not use this value with the LIO_NOWAIT_GMCS command parameter of the lio_listio subroutine. | |
Results[i].errorno | Specifies the errno value that is associated with the ith completion packet. When asynchronous I/O requests are started using the lio_listio subroutine with the LIO_NOWAIT_GMCS command parameter, you must use this error value, not the aio_errno member in the aiocb structure, to retrieve the error value that is associated with an I/O request. | |
Results[i].overlapped | Specifies the overlapped structure that is used in the transfer request. This parameter is set by the subroutine from the value received in the ith completion packet. For regular files, this parameter contains a pointer to the asynchronous I/O control block (AIOCB) for a completed AIO request. If an application uses the same completion port for both socket and AIO to regular files, it must use unique completion_key values to differentiate between sockets and regular files to properly interpret the overlapped parameter. | |
Timeout | Specifies the amount of time in milliseconds that the subroutine is to wait for completion packets. This value can be set to zero. If this parameter is set to INFINITE, the subroutine will never time out. |
Item | Description |
---|---|
Success | The subroutine returns an integer ranging from zero through the value of the Nmax parameter, indicating how many completion packets are dequeued. |
Failure | The subroutine returns a value of -1. |
The subroutine is unsuccessful if any of the following errors occur:
Item | Description |
---|---|
EINVAL | The value of the CompletionPort or other parameter is not valid. |
EBUSY | Another thread is already waiting on the I/O completion port. |
EBADF | This error code might also be returned when the value of the CompletionPort parameter is not valid. |
If an error occurs after some completions have been handled, the error notifications will be lost. An EFAULT error when copying out results can cause the situation.
struct gmcs results[10];
int n_results;
HANDLE iocpfd;
errno = 0;
n_results = GetMultipleCompletionStatus(iocpfd, 10, 10, 100, results);