Expand Minimize

RIODequeueCompletion function

The RIODequeueCompletion function removes entries from an I/O completion queue for use with the Winsock registered I/O extensions.

Syntax


ULONG  RIODequeueCompletion(
  _In_   RIO_CQ CQ,
  _Out_  PRIORESULT Array,
  _In_   ULONG ArraySize
);

Parameters

CQ [in]

A descriptor that identifies an I/O completion queue.

Array [out]

An array of RIORESULT structures to receive the description of the completions dequeued.

ArraySize [in]

The maximum number of entries in the Array to write.

Return value

If no error occurs, the RIODequeueCompletion function returns the number of completion entries removed from the specified completion queue. Otherwise, a value of RIO_CORRUPT_CQ is returned to indicate that the state of the RIO_CQ passed in the CQ parameter has become corrupt due to memory corruption or misuse of the RIO functions.

Remarks

The RIODequeueCompletion function removes entries from an I/O completion queue for send and receive requests with the Winsock registered I/O extensions.

The RIODequeueCompletion function is the mechanism by which an application can find out about completed send and receive requests. An application normally calls the RIODequeueCompletion function after receiving notification based on the method registered with the RIONotify function when the completion queue is not empty. The notification behavior for an I/O completion queue is set when the RIO_CQ is created. The RIO_NOTIFICATION_COMPLETION structure that determines the notification behavior is passed to the RIOCreateCompletionQueue function when a RIO_CQ is created.

When the RIODequeueCompletion function completes, the Array parameter contains an array of pointers to RIORESULT structures for the completed send and receive requests that were dequeued. The members of the returned RIORESULT structures provide information on the completion status of the completed request and the number of bytes that were transferred. Each returned RIORESULT structure also includes a socket context and an application context that can be used to identify the specific completed request.

If the I/O completion queue passed in the CQ parameter is not valid or damaged, the RIODequeueCompletion function returns a count of RIO_CORRUPT_CQ.

The RIODequeueCompletion function returns a value of zero is returned if there are no completed send or receive requests to be dequeued.

Only after a request’s completion has been dequeued does the system release the association to its buffer and buffer registration, along with its quota charge.

Note  For purposes of efficiency, access to the completion queues (RIO_CQ structs) and request queues (RIO_RQ structs) are not protected by synchronization primitives. If you need to access a completion or request queue from multiple threads, access should be coordinated by a critical section, slim reader write lock or similar mechanism. This locking is not needed for access by a single thread. Different threads can access separate requests/completion queues without locks. The need for synchronization occurs only when multiple threads try to access the same queue. Synchronization is also required if multiple threads issue sends and receives on the same socket because the send and receive operations use the socket’s request queue.

Note  The function pointer to the RIODequeueCompletion function must be obtained at run time by making a call to the WSAIoctl function with the SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode specified. The input buffer passed to the WSAIoctl function must contain WSAID_MULTIPLE_RIO, a globally unique identifier (GUID) whose value identifies the Winsock registered I/O extension functions. On success, the output returned by the WSAIoctl function contains a pointer to the RIO_EXTENSION_FUNCTION_TABLE structure that contains pointers to the Winsock registered I/O extension functions. The SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL is defined in the Ws2def.h header file. The WSAID_MULTIPLE_RIO GUID is defined in the Mswsock.h header file.

Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.

Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.

Thread Safety

If multiple threads attempt to access the same RIO_CQ using the RIODequeueCompletion function, access must be coordinated by a critical section, slim reader writer lock , or similar mutual exclusion mechanism. If the completion queues are not shared, mutual exclusion is not required.

Requirements

Minimum supported client

Windows 8.1, Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Minimum supported phone

Windows Phone 8

Header

Mswsock.h

Library

Mswsock.lib

DLL

Mswsock.dll

See also

RIO_CQ
RIO_EXTENSION_FUNCTION_TABLE
RIO_NOTIFICATION_COMPLETION
RIOCloseCompletionQueue
RIOCreateCompletionQueue
RIONotify
RIORESULT
WSAIoctl

 

 

Community Additions

ADD
Show:
© 2014 Microsoft