LPFN_RIOCREATECOMPLETIONQUEUE回呼函式 (mswsock.h)

  • 發行項

RIOCreateCompletionQueue 函式會建立特定大小的 I/O 完成佇列，以搭配 Winsock 已註冊的 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.重疊成員不得為 NULL。

如果 NotificationCompletion 參數為 NULL，這會指定不會使用任何通知完成，而且必須使用輪詢來判斷完成。

傳回值

如果沒有發生錯誤， RIOCreateCompletionQueue 函式會傳回參考新完成佇列的描述元。 否則，會傳回 RIO_INVALID_CQ 的值，而且可以藉由呼叫 WSAGetLastError 函式來擷取特定的錯誤碼。

傳回碼 Description
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 函式來取消佇列已完成的傳送或接收要求。

有兩個選項可供完成佇列通知使用。

  • 事件句柄。
  • 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 成員設定為非零值來降低額外負荷。 這會導致當通知發生時， 由RIONotify 函式 自動重設事件。 這可減輕呼叫 WSAResetEvent 函式的需求，以重設 對RIONotify 函式 呼叫之間的事件。

如果RIO_NOTIFICATION_COMPLETION結構的 Type 成員設定為RIO_IOCP_COMPLETION，則會使用 I/O 完成埠來發出完成佇列通知的訊號。 I/O 完成埠句柄是以傳遞至RIOCreateCompletionQueue 函式之RIO_NOTIFICATION_COMPLETION結構中的Iocp.IocpHandle成員的形式提供。 此RIO_CQ的RIONotify 函式完成會將專案排入 I/O 完成埠，您可以使用 GetQueuedCompletionStatus 或 GetQueuedCompletionStatusEx 函式來擷取。 佇列專案會將傳回的 lpCompletionKey 參數值設定為 RIO_NOTIFICATION_COMPLETION 結構的 Iocp.CompletionKey 成員中指定的值，而 RIO_NOTIFICATION_COMPLETION 結構中的 Iocp.Overlapped 成員將是非 NULL 值。

根據其使用方式，完成佇列通知的設計目的是要喚醒等候的應用程式線程，讓線程可以檢查完成佇列。 喚醒和排程線程會因成本而產生，因此如果發生太頻繁的情況，對應用程式效能會有負面影響。 提供 RIO_MSG_DONT_NOTIFY 旗標，讓應用程式可以控制這些事件的頻率，並限制其對效能的影響。

注意

為了有效率，存取完成佇列 (RIO_CQ 結構) ，並要求佇列 (RIO_RQ 結構) 不受同步處理基本類型保護。 如果您需要從多個線程存取完成或要求佇列，應該以重要區段、精簡讀取器寫入鎖定或類似的機制協調存取。 單一線程存取時不需要此鎖定。 不同的線程可以存取個別的要求/完成佇列，而不需要鎖定。 只有在多個線程嘗試存取相同的佇列時，才會發生同步處理的需求。 如果多個線程在相同的套接字上傳送和接收，因為傳送和接收作業使用套接字的要求佇列，則也需要同步處理。

 

注意

若要在運行時間取得 RIOCreateCompletionQueue 函式的函式指標，您必須呼叫 WSAIoctl 函式並指定 SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode。 傳遞至 WSAIoctl 函式的輸入緩衝區必須包含 WSAID_MULTIPLE_RIO，這是全域唯一標識碼 (GUID) ，其值可識別 Winsock 已註冊的 I/O 延伸模組函式。 成功時， WSAIoctl 函式所傳回的輸出包含 RIO_EXTENSION_FUNCTION_TABLE 結構的指標，其中包含 Winsock 已註冊 I/O 延伸模組函式的指標。 SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL 定義於 Ws2def.h 頭檔中。 WSAID_MULTIPLE_RIO GUID 定義於 Mswsock.h 頭檔中。

 

Windows Phone 8：Windows Phone 8 和更新版本上的 Windows Phone Store 應用程式支援此函式。

Windows 8.1和 Windows Server 2012 R2：Windows 市集應用程式支援 Windows 8.1、Windows Server 2012 R2 和更新版本。

規格需求

需求 值
標頭 mswsock.h