GetQueuedCompletionStatusEx function
Applies to: desktop apps only
Retrieves multiple completion port entries simultaneously. It waits for pending I/O operations that are associated with the specified completion port to complete.
To dequeue I/O completion packets one at a time, use the GetQueuedCompletionStatus function.
Syntax
BOOL WINAPI GetQueuedCompletionStatusEx( __in HANDLE CompletionPort, __out LPOVERLAPPED_ENTRY lpCompletionPortEntries, __in ULONG ulCount, __out PULONG ulNumEntriesRemoved, __in DWORD dwMilliseconds, __in BOOL fAlertable );
Parameters
- CompletionPort [in]
-
A handle to the completion port. To create a completion port, use the CreateIoCompletionPort function.
- lpCompletionPortEntries [out]
-
On input, points to a pre-allocated array of OVERLAPPED_ENTRY structures.
On output, receives an array of OVERLAPPED_ENTRY structures that hold the entries. The number of array elements is provided by ulNumEntriesRemoved.
The number of bytes transferred during each I/O, the completion key that indicates on which file each I/O occurred, and the overlapped structure address used in each original I/O are all returned in the lpCompletionPortEntries array.
- ulCount [in]
-
The maximum number of entries to remove.
- ulNumEntriesRemoved [out]
-
A pointer to a variable that receives the number of entries actually removed.
- dwMilliseconds [in]
-
The number of milliseconds that the caller is willing to wait for a completion packet to appear at the completion port. If a completion packet does not appear within the specified time, the function times out and returns FALSE.
If dwMilliseconds is INFINITE (0xFFFFFFFF), the function will never time out. If dwMilliseconds is zero and there is no I/O operation to dequeue, the function will time out immediately.
- fAlertable [in]
-
If this parameter is FALSE, the function does not return until the time-out period has elapsed or an entry is retrieved.
If the parameter is TRUE and there are no available entries, the function performs an alertable wait. The thread returns when the system queues an I/O completion routine or APC to the thread and the thread executes the function.
A completion routine is queued when the ReadFileEx or WriteFileEx function in which it was specified has completed, and the calling thread is the thread that initiated the operation. An APC is queued when you call QueueUserAPC.
Return value
Returns nonzero (TRUE) if successful or zero (FALSE) otherwise.
To get extended error information, call GetLastError.
Remarks
This function associates a thread with the specified completion port. A thread can be associated with at most one completion port.
This function returns TRUE when at least one pending I/O is completed, but it is possible that one or more I/O operations failed. Note that it is up to the user of this function to check the list of returned entries in the lpCompletionPortEntries parameter to determine which of them correspond to any possible failed I/O operations by looking at the status contained in the lpOverlapped member in each OVERLAPPED_ENTRY.
This function returns FALSE when no I/O operation was dequeued. This typically means that an error occurred while processing the parameters to this call, or that the CompletionPort handle was closed or is otherwise invalid. The GetLastError function provides extended error information.
If a call to GetQueuedCompletionStatusEx fails because the handle associated with it is closed, the function returns FALSE and GetLastError will return ERROR_ABANDONED_WAIT_0.
Server applications may have several threads calling the GetQueuedCompletionStatusEx function for the same completion port. As I/O operations complete, they are queued to this port in first-in-first-out order. If a thread is actively waiting on this call, one or more queued requests complete the call for that thread only.
For more information on I/O completion port theory, usage, and associated functions, see I/O Completion Ports.
Requirements
|
Minimum supported client | Windows Vista |
|---|---|
|
Minimum supported server | Windows Server 2008 |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
- Overview Topics
- File Management Functions
- I/O Completion Ports
- Using the Windows Headers
- Functions
- ConnectNamedPipe
- CreateIoCompletionPort
- DeviceIoControl
- GetQueuedCompletionStatusEx
- LockFileEx
- ReadFile
- PostQueuedCompletionStatus
- TransactNamedPipe
- WaitCommEvent
- WriteFile
Send comments about this topic to Microsoft
Build date: 4/17/2012
1) When the call enters an alertable wait state and a User APC is available to dispatch the return value of the GetQueuedCompletionStatusEx is TRUE, ulEntriesRemoved is non-zero and your 'pack' of OVERLAPPED_ENTRYs is untouched. So if you ensure that all your OVERLAPPED_ENTRYs have a known unique value set for their lpOverlapped members, before you call the API , you can more easily detect whether a removed entry is an APC or an I/O completion packet by checking lpOverlapped for that magic value.
2) The documentation states 'If [fAlertable] is TRUE and there are no available entries, the function performs an alertable wait'. And it is true ! ;-) User APCs will not get dispatched if there are any I/O completion packets in the queue. So QueueUserAPC might not be a good way to interrupt a worker thread that is calling GetQueuedCompletionStatusEx on a busy IoCompletionPort.
Platform : Windows Server 2008 x64 Standard Edition running on an Intel Core i7.
- 4/21/2010
- Darren Richards
- 4/21/2010
- Darren Richards
