Edit

RIO_NOTIFICATION_COMPLETION structure (mswsock.h)

  • Article

The RIO_NOTIFICATION_COMPLETION structure specifies the method for I/O completion to be used with a RIONotify function for sending or receiving network data with the Winsock registered I/O extensions.

Syntax

typedef struct _RIO_NOTIFICATION_COMPLETION {
  RIO_NOTIFICATION_COMPLETION_TYPE Type;
  union {
    struct {
      HANDLE EventHandle;
      BOOL   NotifyReset;
    } Event;
    struct {
      HANDLE IocpHandle;
      PVOID  CompletionKey;
      PVOID  Overlapped;
    } Iocp;
  };
} RIO_NOTIFICATION_COMPLETION, *PRIO_NOTIFICATION_COMPLETION;

Members

Type

The type of completion to use with the RIONotify function when sending or receiving data.

Event

Event.EventHandle

The handle for the event to set following a completed RIONotify request.

This value is valid when the Type member is set to RIO_EVENT_COMPLETION.

Event.NotifyReset

The boolean value that causes the associated event to be reset when the RIONotify function is called. A non-zero value cause the associated event to be reset.

This value is valid when the Type member is set to RIO_EVENT_COMPLETION.

Iocp

Iocp.IocpHandle

The handle for the I/O completion port to use for queuing a RIONotify request completion.

This value is valid when the Type member is set to RIO_IOCP_COMPLETION.

Iocp.CompletionKey

The value to use for lpCompletionKey parameter returned by the GetQueuedCompletionStatus or GetQueuedCompletionStatusEx function when queuing a RIONotify request.

This value is valid when the Type member is set to RIO_IOCP_COMPLETION.

Iocp.Overlapped

A pointer to the OVERLAPPED structure to use when queuing a RIONotify request completion. This member must point to a valid OVERLAPPED structure.

This value is valid when the Type member is set to RIO_IOCP_COMPLETION.

Remarks

The RIO_NOTIFICATION_COMPLETION structure is used to specify the behavior of the RIONotify function used with the Winsock registered I/O extensions.

The RIO_NOTIFICATION_COMPLETION structure is passed to the RIOCreateCompletionQueue function when a RIO_CQ is created. If an application does not call the RIONotify function for a completion queue, the completion queue can be created without a RIO_NOTIFICATION_COMPLETION object.

For completion queues using an event, the Type member of the RIO_NOTIFICATION_COMPLETION structure is set to RIO_EVENT_COMPLETION. The Event.EventHandle member of the RIO_NOTIFICATION_COMPLETION structure 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 of the RIO_NOTIFICATION_COMPLETION structure to a non-zero value. This causes the event to be reset by the RIONotify function when notification occurs. This mitigates the need to call the WSAResetEvent function to reset the event between calls to the RIONotify function.

For completion queues using an I/O completion port, the Type member of the RIO_NOTIFICATION_COMPLETION structure is set to RIO_IOCP_COMPLETION. The Iocp.IocpHandle member of the RIO_NOTIFICATION_COMPLETION structure 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.

An application using thread pools can use thread pool wait objects to get RIONotify completions via its thread pool. In that case, the call to the SetThreadpoolWait function should immediately follow the call to RIONotify. If the SetThreadpoolWait function is called before RIONotify and the application relies on RIONotify to clear the event object, this may result in spurious executions of the wait object callback.

Requirements

Requirement Value
Minimum supported client Windows 8 [desktop apps only]
Minimum supported server Windows Server 2012 [desktop apps only]
Header mswsock.h

See also

CreateEvent

CreateIoCompletionPort

GetQueuedCompletionStatus

GetQueuedCompletionStatusEx

OVERLAPPED

RIOCreateCompletionQueue

RIONotify

RIO_CQ

RIO_NOTIFICATION_COMPLETION_TYPE

SetThreadpoolWait

WSACreateEvent

WSAResetEvent

WSAWaitForMultipleEvents