共用方式為


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 成員應該包含 WSACreateEventCreateEvent 函式所建立之事件的句柄。 若要接收 RIONotify 完成,應用程式應該使用 WSAWaitForMultipleEvents 或類似的等候例程等候指定的事件句柄。 此RIO_CQRIONotify 函式完成會發出事件訊號。 傳遞至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_CQRIONotify 函式完成會將專案排入 I/O 完成埠,您可以使用 GetQueuedCompletionStatusGetQueuedCompletionStatusEx 函式來擷取。 佇列專案會將傳回的 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.1Windows Server 2012 R2:Windows 市集應用程式支援 Windows 8.1、Windows Server 2012 R2 和更新版本。

規格需求

需求
標頭 mswsock.h