RIO_CQ
The RIO_CQ typedef specifies a completion queue descriptor used for I/O completion notification by send and receive requests with the Winsock registered I/O extensions.
typedef struct RIO_CQ_t* RIO_CQ, **PRIO_CQ;
-
RIO_CQ
-
A data type that specifies a completion queue descriptor used for I/O completion notification by send and receive requests.
Remarks
The RIO_CQ object is used for I/O completion notification of send and receive networking requests by the Winsock registered I/O extensions.
An application can use the RIONotify function to request notification when a RIO_CQ completion queue is not empty. An application can also poll the status at any time of a RIO_CQ completion queue in a non-blocking way using the RIODequeueCompletion function.
The RIO_CQ object is created using the RIOCreateCompletionQueue function. At creation time, the application must specify the size of the queue, which determines how many completion entries it can hold. When an application calls the RIOCreateRequestQueue function to obtain a RIO_RQ handle, the application must specify a RIO_CQ handle for send completions and a RIO_CQ handle for receive completions. These handles may be identical when the same queue should be used for send and receive completion. The RIOCreateRequestQueue function also requires a maximum number of outstanding send and receive operations, which are charged against the capacity of the associated completion queue or queues. If the queues do not have sufficient capacity remaining, the RIOCreateRequestQueue call will fail with WSAENOBUFS.
The notification behavior for a completion queue is set when the RIO_CQ is created.
For a completion queue that uses an event, the Type member of the RIO_NOTIFICATION_COMPLETION structure is set to RIO_EVENT_COMPLETION. The Event.EventHandle member should contain the handle for an event created by the WSACreateEvent or CreateEvent function. To receive the RIONotify completion, the application should wait on the specified event handle using WSAWaitForMultipleEvents or a similar wait routine. If the application plans to reset and reuse the event, the application can reduce overhead by setting the Event.NotifyReset member to a non-zero value. This causes the event to be automatically reset by the RIONotify function when the notification occurs. This mitigates the need to call the WSAResetEvent function to reset the event between calls to the RIONotify function.
For a completion queue that uses an I/O completion port, the Type member of the RIO_NOTIFICATION_COMPLETION structure is set to RIO_IOCP_COMPLETION. The Iocp.IocpHandle member should contain the handle for an I/O completion port created by the CreateIoCompletionPort function. To receive the RIONotify completion, the application should call the GetQueuedCompletionStatus or GetQueuedCompletionStatusEx function. The application should provide a dedicated OVERLAPPED object for the completion queue, and it may also use the Iocp.CompletionKey member to distinguish RIONotify requests on the completion queue from other I/O completions including RIONotify completions for other completion queues.
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.
If multiple threads attempt to access the same RIO_CQ using RIODequeueCompletion, 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.
When a completion queue is no longer needed, an application can close it using the RIOCloseCompletionQueue function.
The RIO_CQ typedef is defined in the Mswsockdef.h header file which is automatically included in the Mswsock.h header file. The Mswsockdef.h header file should never be used directly.
Thread Safety
If multiple threads attempt to access the same RIO_CQ using RIODequeueCompletion, 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
| Requirement | Value |
|---|---|
| Minimum supported client |
Windows 8 [desktop apps only] |
| Minimum supported server |
Windows Server 2012 [desktop apps only] |
| Header |
|
See also