次の方法で共有

LPFN_RIOCREATECOMPLETIONQUEUE コールバック関数 (mswsock.h)

  • [アーティクル]

RIOCreateCompletionQueue 関数は、Winsock に登録された I/O 拡張機能で使用するために、特定のサイズの I/O 完了キューを作成します。

構文

LPFN_RIOCREATECOMPLETIONQUEUE LpfnRiocreatecompletionqueue;

RIO_CQ LpfnRiocreatecompletionqueue(
  DWORD QueueSize,
  PRIO_NOTIFICATION_COMPLETION NotificationCompletion
)
{...}

パラメーター

QueueSize

作成する完了キューのサイズ (エントリ数)。

NotificationCompletion

RIO_NOTIFICATION_COMPLETION構造体の Type メンバー (I/O 入力候補またはイベント通知) に基づいて使用する通知完了の種類。

Type メンバーが RIO_EVENT_COMPLETION に設定されている場合は、RIO_NOTIFICATION_COMPLETION構造体の Event メンバーを設定する必要があります。

Type メンバーが RIO_IOCP_COMPLETION に設定されている場合は、RIO_NOTIFICATION_COMPLETION 構造体の Iocp メンバーを設定する必要があり、RIO_NOTIFICATION_COMPLETION 構造体の Iocp.Overlapped メンバーを NULL にすることはできません。

NotificationCompletion パラメーターが NULL の場合、これは通知完了を使用せず、ポーリングを使用して完了を決定する必要があることを指定します。

戻り値

エラーが発生しない場合、 RIOCreateCompletionQueue 関数は、新しい完了キューを参照する記述子を返します。 それ以外の場合は、 RIO_INVALID_CQ の値が返され、 WSAGetLastError 関数を呼び出すことで特定のエラー コードを取得できます。

リターン コード 説明
WSAEFAULT
 呼び出しでポインター引数を使用しようとしたときに、システムにより、無効なポインター アドレスが検出されました。
WSAEINVAL
 無効なパラメーターが関数に渡されました。
QueueSize パラメーターが 1 より小さいか、Mswsockdef.h ヘッダー ファイルで定義RIO_MAX_CQ_SIZEより大きい場合、このエラーが返されます。
WSAENOBUFS
 十分なメモリを割り当てませんでした。 QueueSize パラメーターに基づいて要求された完了キューを割り当てるためのメモリが不足していた場合、このエラーが返されます。

注釈

RIOCreateCompletionQueue 関数は、特定のサイズの I/O 完了キューを作成します。 完了キューのサイズは、完了キューに関連付けることができる登録済み I/O ソケットのセットを制限します。 詳細については、 RIOCreateRequestQueue 関数に関するページを参照してください。

RIO_CQを作成する場合、NotificationCompletion パラメーターによって指されるRIO_NOTIFICATION_COMPLETION構造体によって、アプリケーションが完了キュー通知を受け取る方法が決まります。 完了キューの作成時に RIO_NOTIFICATION_COMPLETION 構造が指定されている場合、アプリケーションは RIONotify 関数を呼び出して完了キュー通知を要求できます。 通常、この通知は、完了キューが空でない場合に発生します。 これは、すぐに、または次の完了エントリが完了キューに挿入されたときに発生する可能性があります。 ただし、送信要求と受信要求には 、RIO_MSG_DONT_NOTIFYとしてフラグが設定されている場合があります。 完了キュー通知。このような要求の結果としてトリガーされることはありません。 完了キューに RIO_MSG_DONT_NOTIFY フラグが設定されたエントリのみが含まれている場合、完了キュー通知はトリガーされません。 また、新しいエントリが完了キューに入ると、完了キュー通知は、関連付けられた要求 でRIO_MSG_DONT_NOTIFY フラグが設定されていない場合にのみトリガーされます。 RIODequeueCompletion 関数を使用してポーリングすることで、完了した要求を引き続き取得できます。 完了キュー通知が発行されたら、アプリケーションは別の完了キュー通知を受信するために RIONotify 関数を呼び出す必要があります。 完了キュー通知が発生すると、通常、アプリケーションは RIODequeueCompletion 関数を呼び出して、完了した送信または受信要求をデキューします。

完了キュー通知には、2 つのオプションを使用できます。

  • イベント ハンドル。
  • I/O 完了ポート

RIO_NOTIFICATION_COMPLETION構造体の Type メンバーが RIO_EVENT_COMPLETION に設定されている場合、イベント ハンドルを使用して完了キュー通知が通知されます。 イベント ハンドルは、RIOCreateCompletionQueue 関数に渡されるRIO_NOTIFICATION_COMPLETION構造体の EventNotify.EventHandle メンバーとして提供されます。 Event.EventHandle メンバーには、WSACreateEvent または CreateEvent 関数によって作成されたイベントのハンドルが含まれている必要があります。 RIONotify の完了を受け取る場合、アプリケーションは WSAWaitForMultipleEvents または同様の待機ルーチンを使用して、指定されたイベント ハンドルを待機する必要があります。 このRIO_CQの RIONotify 関数が完了すると、イベントが通知されます。 RIOCreateCompletionQueue 関数に渡されるRIO_NOTIFICATION_COMPLETION構造体の Event.NotifyReset メンバーは、RIONotify 関数の呼び出しの一部としてイベントをリセットするかどうかを示します。 アプリケーションがイベントのリセットと再利用を計画している場合、 Event.NotifyReset メンバーを 0 以外の値に設定することで、アプリケーションのオーバーヘッドを削減できます。 これにより、通知が発生したときに RIONotify 関数によってイベントが自動的にリセットされます。 これにより、 WSAResetEvent 関数を呼び出して 、RIONotify 関数の呼び出し間でイベントをリセットする必要が軽減されます。

RIO_NOTIFICATION_COMPLETION構造体の Type メンバーが RIO_IOCP_COMPLETION に設定されている場合は、I/O 完了ポートを使用して完了キュー通知を通知します。 I/O 完了ポート ハンドルは、RIOCreateCompletionQueue 関数に渡されるRIO_NOTIFICATION_COMPLETION構造体の Iocp.IocpHandle メンバーとして提供されます。 このRIO_CQの RIONotify 関数が完了すると、GetQueuedCompletionStatus または GetQueuedCompletionStatusEx 関数を使用して取得できる I/O 完了ポートへのエントリがキューに入れられます。 キューに登録されたエントリには、返された lpCompletionKey パラメーター値が、RIO_NOTIFICATION_COMPLETION構造体の Iocp.CompletionKey メンバーで指定された値に設定され、RIO_NOTIFICATION_COMPLETION構造体の Iocp.Overlapped メンバーは NULL 以外の値になります。

その使用法に関しては、完了キュー通知は、スレッドが完了キューを調べることができるように、待機中のアプリケーション スレッドをウェイクアップするように設計されています。 スレッドのウェイクとスケジュール設定はコストがかかるため、頻繁に発生しすぎると、アプリケーションのパフォーマンスに悪影響を及ぼします。 アプリケーションがこれらのイベントの頻度を制御し、パフォーマンスへの影響を制限できるように、 RIO_MSG_DONT_NOTIFY フラグが提供されます。

注意

効率のために、完了キュー (RIO_CQ 構造体) と要求キュー (RIO_RQ 構造体) へのアクセスは、同期プリミティブによって保護されません。 複数のスレッドから完了キューまたは要求キューにアクセスする必要がある場合は、クリティカル セクション、スリム リーダー書き込みロック、または同様のメカニズムによってアクセスを調整する必要があります。 このロックは、1 つのスレッドによるアクセスには必要ありません。 異なるスレッドは、ロックなしで個別の要求/完了キューにアクセスできます。 同期の必要性は、複数のスレッドが同じキューにアクセスしようとした場合にのみ発生します。 また、送信操作と受信操作でソケットの要求キューが使用されるため、複数のスレッドの問題が同じソケットで送受信される場合も、同期が必要です。

 

注意

RIOCreateCompletionQueue 関数への関数ポインターは、SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTERオペコードを指定して WSAIoctl 関数を呼び出すことによって、実行時に取得する必要があります。 WSAIoctl 関数に渡される入力バッファーには、Winsock に登録されている I/O 拡張関数を識別する値を持つグローバル一意識別子 (GUID) WSAID_MULTIPLE_RIOが含まれている必要があります。 成功すると、 WSAIoctl 関数によって返される出力には、Winsock に登録されている I/O 拡張関数へのポインターを含む RIO_EXTENSION_FUNCTION_TABLE 構造体へのポインターが含まれます。 SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL は、Ws2def.h ヘッダー ファイルで定義されています。 WSAID_MULTIPLE_RIO GUID は、Mswsock.h ヘッダー ファイルで定義されています。

 

Windows Phone 8: この関数は、Windows Phone 8 以降のWindows Phone ストア アプリでサポートされています。

Windows 8.1とWindows Server 2012 R2: この関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストア アプリでサポートされています。

要件

要件 値
Header mswsock.h