LPFN_RIOCREATECOMPLETIONQUEUE Rückruffunktion (mswsock.h)

Die RIOCreateCompletionQueue-Funktion erstellt eine E/A-Vervollständigungswarteschlange einer bestimmten Größe für die Verwendung mit den registrierten Winsock-E/A-Erweiterungen.

Syntax

LPFN_RIOCREATECOMPLETIONQUEUE LpfnRiocreatecompletionqueue;

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

Parameter

QueueSize

Die Größe der zu erstellenden Vervollständigungswarteschlange in Der Anzahl der Einträge.

NotificationCompletion

Der Typ der zu verwendenden Benachrichtigungserfüllung basierend auf dem Typelement der RIO_NOTIFICATION_COMPLETION-Struktur (E/A-Vervollständigung oder Ereignisbenachrichtigung).

Wenn das Element Typ auf RIO_EVENT_COMPLETION festgelegt ist, muss das Ereigniselement der RIO_NOTIFICATION_COMPLETION-Struktur festgelegt werden.

Wenn das Element Typ auf RIO_IOCP_COMPLETION festgelegt ist, muss das Iocp-Element der RIO_NOTIFICATION_COMPLETION-Struktur festgelegt werden, und das Iocp.Overlapped-Element der RIO_NOTIFICATION_COMPLETION-Struktur darf nicht NULL sein.

Wenn der NotificationCompletion-Parameter NULL ist, gibt dies an, dass keine Benachrichtigungsvervollständigung verwendet wird und dass die Abfrage verwendet werden muss, um die Vervollständigung zu bestimmen.

Rückgabewert

Wenn kein Fehler auftritt, gibt die RIOCreateCompletionQueue-Funktion einen Deskriptor zurück, der auf eine neue Vervollständigungswarteschlange verweist. Andernfalls wird der Wert RIO_INVALID_CQ zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen der WSAGetLastError-Funktion abgerufen werden.

Rückgabecode	Beschreibung
WSAEFAULT	Das System hat beim Versuch, ein Zeigerargument in einem Aufruf zu verwenden, eine ungültige Zeigeradresse erkannt.
WSAEINVAL	Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn der QueueSize-Parameter kleiner als 1 oder größer als RIO_MAX_CQ_SIZE in der Headerdatei "Mswsockdef.h " definiert ist.
WSAENOBUFS	Es konnte nicht genügend Arbeitsspeicher zugewiesen werden. Dieser Fehler wird zurückgegeben, wenn nicht genügend Arbeitsspeicher vorhanden war, um die auf Grundlage des QueueSize-Parameters angeforderte Vervollständigungswarteschlange zuzuordnen.

Hinweise

Die RIOCreateCompletionQueue-Funktion erstellt eine E/A-Vervollständigungswarteschlange einer bestimmten Größe. Die Größe der Vervollständigungswarteschlange schränkt den Satz registrierter E/A-Sockets ein, die der Vervollständigungswarteschlange zugeordnet werden können. Weitere Informationen finden Sie in der RIOCreateRequestQueue-Funktion .

Beim Erstellen eines RIO_CQ bestimmt die RIO_NOTIFICATION_COMPLETION Struktur, auf die der NotificationCompletion-Parameter verweist, wie die Anwendung Benachrichtigungen zur Vervollständigungswarteschlange empfängt. Wenn beim Erstellen der Vervollständigungswarteschlange eine RIO_NOTIFICATION_COMPLETION Struktur bereitgestellt wird, kann die Anwendung die RIONotify-Funktion aufrufen, um eine Vervollständigungswarteschlangenbenachrichtigung anzufordern. Normalerweise tritt diese Benachrichtigung auf, wenn die Vervollständigungswarteschlange nicht leer ist. Dies kann sofort geschehen oder wenn der nächste Vervollständigungseintrag in die Vervollständigungswarteschlange eingefügt wird. Sende- und Empfangsanforderungen können jedoch als RIO_MSG_DONT_NOTIFY gekennzeichnet werden. Vervollständigungswarteschlangenbenachrichtigung und wird nie als Folge solcher Anforderungen ausgelöst. Wenn die Vervollständigungswarteschlange nur Einträge mit dem RIO_MSG_DONT_NOTIFY-Flag enthält, wird die Vervollständigungswarteschlangenbenachrichtigung nicht ausgelöst. Wenn ein neuer Eintrag in die Vervollständigungswarteschlange eintritt, wird die Vervollständigungswarteschlangenbenachrichtigung nur ausgelöst, wenn das RIO_MSG_DONT_NOTIFY Flag für die zugeordnete Anforderung nicht festgelegt wurde. Alle abgeschlossenen Anforderungen können weiterhin mithilfe der RIODequeueCompletion-Funktion abgerufen werden. Sobald eine Vervollständigungswarteschlangenbenachrichtigung ausgegeben wurde, muss die Anwendung die RIONotify-Funktion aufrufen, um eine weitere Vervollständigungswarteschlangenbenachrichtigung zu erhalten. Wenn eine Vervollständigungswarteschlangenbenachrichtigung auftritt, ruft die Anwendung in der Regel die RIODequeueCompletion-Funktion auf, um die abgeschlossenen Sende- oder Empfangsanforderungen zu entfernen.

Für die Benachrichtigung der Vervollständigungswarteschlange stehen zwei Optionen zur Verfügung.

• Ereignishandles.
• E/A-Vervollständigungsports

Wenn das Element Typ der RIO_NOTIFICATION_COMPLETION-Struktur auf RIO_EVENT_COMPLETION festgelegt ist, wird ein Ereignishandle verwendet, um Vervollständigungswarteschlangenbenachrichtigungen zu signalisieren. Ein Ereignishandle wird als EventNotify.EventHandle-Member in der RIO_NOTIFICATION_COMPLETION-Struktur bereitgestellt, die an die RIOCreateCompletionQueue-Funktion übergeben wird. Das Event.EventHandle-Element sollte das Handle für ein Ereignis enthalten, das von der WSACreateEvent - oder CreateEvent-Funktion erstellt wurde. Um die RIONotify-Vervollständigung zu erhalten, sollte die Anwendung mit WSAWaitForMultipleEvents oder einer ähnlichen Warteroutine auf das angegebene Ereignishandle warten. Die Vervollständigung der RIONotify-Funktion für diese RIO_CQ signalisiert das Ereignis. Das Event.NotifyReset-Element in der RIO_NOTIFICATION_COMPLETION-Struktur , das an die RIOCreateCompletionQueue-Funktion übergeben wurde, gibt an, ob das Ereignis im Rahmen eines Aufrufs der RIONotify-Funktion zurückgesetzt werden soll oder nicht. Wenn die Anwendung plant, das Ereignis zurückzusetzen und wiederzuverwenden, kann die Anwendung den Mehraufwand verringern, indem sie den Event.NotifyReset-Member auf einen Wert ungleich 0 festlegt. Dies führt dazu, dass das Ereignis automatisch von der RIONotify-Funktion zurückgesetzt wird, wenn die Benachrichtigung auftritt. Dies verringert die Notwendigkeit, die WSAResetEvent-Funktion aufzurufen, um das Ereignis zwischen Aufrufen der RIONotify-Funktion zurückzusetzen.

Wenn das Element Typ der RIO_NOTIFICATION_COMPLETION-Struktur auf RIO_IOCP_COMPLETION festgelegt ist, wird ein E/A-Vervollständigungsport verwendet, um Vervollständigungswarteschlangenbenachrichtigungen zu signalisieren. Ein E/A-Vervollständigungsporthandle wird als Iocp.IocpHandle-Member in der RIO_NOTIFICATION_COMPLETION-Struktur bereitgestellt, die an die RIOCreateCompletionQueue-Funktion übergeben wird. Durch die Vervollständigung der RIONotify-Funktion für diesen RIO_CQ wird ein Eintrag am E/A-Vervollständigungsport in die Warteschlange gestellt, der mithilfe der Funktion GetQueuedCompletionStatus oder GetQueuedCompletionStatusEx abgerufen werden kann. Bei einem Eintrag in der Warteschlange wird der zurückgegebene lpCompletionKey-Parameterwert auf den wert festgelegt, der im Iocp.CompletionKey-Member der RIO_NOTIFICATION_COMPLETION-Struktur angegeben ist, und der Iocp.Overlapped-Member in der RIO_NOTIFICATION_COMPLETION-Struktur ist ein Wert ohne NULL.

In Bezug auf ihre Verwendung ist die Vervollständigungswarteschlange so konzipiert, dass ein wartende Anwendungsthread aktiviert wird, damit der Thread die Vervollständigungswarteschlange untersuchen kann. Das Aufwachen und Planen eines Threads hat kostenaufwendig. Wenn dies zu häufig geschieht, wirkt sich dies negativ auf die Anwendungsleistung aus. Das RIO_MSG_DONT_NOTIFY-Flag wird bereitgestellt, damit die Anwendung die Häufigkeit dieser Ereignisse steuern und deren übermäßigen Auswirkungen auf die Leistung begrenzen kann.

Hinweis

Aus Gründen der Effizienz werden der Zugriff auf die Vervollständigungswarteschlangen (RIO_CQ-Strukturen ) und Anforderungswarteschlangen (RIO_RQ-Strukturen ) nicht durch Synchronisierungsgrundsätze geschützt. Wenn Sie über mehrere Threads auf eine Vervollständigungs- oder Anforderungswarteschlange zugreifen müssen, sollte der Zugriff durch einen kritischen Abschnitt, eine schlanke Lesesperre oder einen ähnlichen Mechanismus koordiniert werden. Diese Sperre ist für den Zugriff durch einen einzelnen Thread nicht erforderlich. Verschiedene Threads können ohne Sperren auf separate Anforderungen/Vervollständigungswarteschlangen zugreifen. Die Notwendigkeit einer Synchronisierung tritt nur auf, wenn mehrere Threads versuchen, auf dieselbe Warteschlange zuzugreifen. Eine Synchronisierung ist auch erforderlich, wenn mehrere Threads senden und empfangen, die auf demselben Socket gesendet und empfangen werden, da die Sende- und Empfangsvorgänge die Anforderungswarteschlange des Sockets verwenden.

 

Hinweis

Der Funktionszeiger auf die RIOCreateCompletionQueue-Funktion muss zur Laufzeit abgerufen werden, indem die WSAIoctl-Funktion mit dem angegebenen SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode aufgerufen wird. Der an die WSAIoctl-Funktion übergebene Eingabepuffer muss WSAID_MULTIPLE_RIO enthalten, einen global eindeutigen Bezeichner (GUID), dessen Wert die von Winsock registrierten E/A-Erweiterungsfunktionen identifiziert. Bei Erfolg enthält die von der WSAIoctl-Funktion zurückgegebene Ausgabe einen Zeiger auf die RIO_EXTENSION_FUNCTION_TABLE-Struktur , die Zeiger auf die von Winsock registrierten E/A-Erweiterungsfunktionen enthält. Die SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL ist in der Headerdatei Ws2def.h definiert. Die WSAID_MULTIPLE_RIO GUID ist in der Headerdatei "Mswsock.h " definiert.

 

Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps auf Windows Phone 8 und höher unterstützt.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anforderungen

Anforderung	Wert
Header	mswsock.h