CreateIoCompletionPort-Funktion

Erstellt einen Eingabe-/Ausgabeport (E/A) und ordnet ihn einem angegebenen Dateihandle zu, oder erstellt einen E/A-Vervollständigungsport, der noch keinem Dateihandle zugeordnet ist, sodass die Zuordnung zu einem späteren Zeitpunkt möglich ist.

Das Zuordnen einer instance eines geöffneten Dateihandles zu einem E/A-Abschlussport ermöglicht es einem Prozess, eine Benachrichtigung über den Abschluss asynchroner E/A-Vorgänge zu erhalten, die dieses Dateihandle betreffen.

Syntax

HANDLE WINAPI CreateIoCompletionPort(
  _In_     HANDLE    FileHandle,
  _In_opt_ HANDLE    ExistingCompletionPort,
  _In_     ULONG_PTR CompletionKey,
  _In_     DWORD     NumberOfConcurrentThreads
);

Parameter

FileHandle [in]

Ein geöffnetes Dateihandle oder INVALID_HANDLE_VALUE.

Das Handle muss für ein Objekt sein, das überlappende E/A unterstützt.

Wenn ein Handle bereitgestellt wird, muss es für den überlappenden E/A-Abschluss geöffnet worden sein. Beispielsweise müssen Sie das flag FILE_FLAG_OVERLAPPED angeben, wenn Sie die CreateFile-Funktion verwenden, um das Handle abzurufen.

Wenn INVALID_HANDLE_VALUE angegeben ist, erstellt die Funktion einen E/A-Abschlussport, ohne ihn einem Dateihandle zuzuordnen. In diesem Fall muss der Parameter ExistingCompletionPortNULL sein, und der CompletionKey-Parameter wird ignoriert.

ExistingCompletionPort [in, optional]

Ein Handle für einen vorhandenen E/A-Abschlussport oder NULL.

Wenn dieser Parameter einen vorhandenen E/A-Abschlussport angibt, ordnet die Funktion ihn dem durch den FileHandle-Parameter angegebenen Handle zu. Die Funktion gibt bei erfolgreicher Ausführung das Handle des vorhandenen E/A-Abschlussports zurück. Es wird kein neuer E/A-Abschlussport erstellt.

Wenn dieser Parameter NULL ist, erstellt die Funktion einen neuen E/A-Vervollständigungsport und ordnet ihn, wenn der FileHandle-Parameter gültig ist, dem neuen E/A-Abschlussport zu. Andernfalls erfolgt keine Zuordnung des Dateihandles. Die Funktion gibt bei erfolgreicher Ausführung das Handle an den neuen E/A-Abschlussport zurück.

CompletionKey [in]

Der pro Handle benutzerdefinierte Vervollständigungsschlüssel, der in jedem E/A-Vervollständigungspaket für das angegebene Dateihandle enthalten ist. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

NumberOfConcurrentThreads [in]

Die maximale Anzahl von Threads, die das Betriebssystem zum gleichzeitigen Verarbeiten von E/A-Vervollständigungspaketen für den E/A-Abschlussport zulassen kann. Dieser Parameter wird ignoriert, wenn der Parameter ExistingCompletionPort nicht NULL ist.

Wenn dieser Parameter null ist, lässt das System so viele gleichzeitig ausgeführte Threads zu, wie prozessoren im System vorhanden sind.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert das Handle für einen E/A-Abschlussport:

• Wenn der ExistingCompletionPort-ParameterNULL ist, ist der Rückgabewert ein neues Handle.

• Wenn der ExistingCompletionPort-Parameter ein gültiges E/A-Vervollständigungsporthandle war, entspricht der Rückgabewert demselben Handle.

• Wenn der FileHandle-Parameter ein gültiges Handle war, ist dieses Dateihandle nun dem zurückgegebenen E/A-Vervollständigungsport zugeordnet.

Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL. Rufen Sie die GetLastError-Funktion auf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Das E/A-System kann angewiesen werden, E/A-Vervollständigungs-Benachrichtigungspakete an E/A-Abschlussports zu senden, wo sie sich in der Warteschlange befinden. Die CreateIoCompletionPort-Funktion stellt diese Funktionalität bereit.

Ein E/A-Vervollständigungsport und sein Handle sind dem Prozess zugeordnet, der ihn erstellt hat, und kann nicht zwischen Prozessen aufgeteilt werden. Ein einzelnes Handle kann jedoch zwischen Threads im selben Prozess aufgeteilt werden.

CreateIoCompletionPort kann in drei verschiedenen Modi verwendet werden:

• Erstellen Sie nur einen E/A-Vervollständigungsport, ohne ihn einem Dateihandle zuzuordnen.
• Ordnen Sie einem Dateihandle einen vorhandenen E/A-Vervollständigungsport zu.
• Führen Sie sowohl die Erstellung als auch die Zuordnung in einem einzigen Aufruf aus.

Um einen E/A-Vervollständigungsport zu erstellen, ohne ihn zuzuordnen, legen Sie den FileHandle-Parameter auf INVALID_HANDLE_VALUE, den Parameter ExistingCompletionPort auf NULL und den CompletionKey-Parameter auf 0 (in diesem Fall ignoriert) fest. Legen Sie den Parameter NumberOfConcurrentThreads auf den gewünschten Parallelitätswert für den neuen E/A-Abschlussport oder null für den Standardwert (die Anzahl der Prozessoren im System) fest.

Das im FileHandle-Parameter übergebene Handle kann ein beliebiges Handle sein, das überlappende E/A unterstützt. In der Regel handelt es sich um ein Handle, das von der CreateFile-Funktion mit dem flag FILE_FLAG_OVERLAPPED geöffnet wird (z. B. Dateien, E-Mail-Slots und Pipes). Objekte, die von anderen Funktionen wie socket erstellt werden, können auch einem E/A-Abschlussport zugeordnet werden. Ein Beispiel für die Verwendung von Sockets finden Sie unter AcceptEx. Ein Handle kann nur einem E/A-Abschlussport zugeordnet werden, und nachdem die Zuordnung vorgenommen wurde, bleibt das Handle diesem E/A-Abschlussport zugeordnet, bis es geschlossen wird.

Weitere Informationen zur E/A-Vervollständigung von Ports, zur Verwendung und zu den zugehörigen Funktionen finden Sie unter E/A-Abschlussports.

Mehrere Dateihandles können einem einzelnen E/A-Vervollständigungsport zugeordnet werden, indem CreateIoCompletionPort mehrmals mit demselben E/A-Abschlussporthandle im Parameter ExistingCompletionPort und jedes Mal ein anderes Dateihandle im FileHandle-Parameter aufgerufen wird.

Verwenden Sie den CompletionKey-Parameter , um Ihrer Anwendung zu helfen, nachzuverfolgen, welche E/A-Vorgänge abgeschlossen wurden. Dieser Wert wird von CreateIoCompletionPort nicht für die Funktionssteuerung verwendet. Stattdessen wird sie an das Dateihandle angefügt, das im FileHandle-Parameter zum Zeitpunkt der Zuordnung zu einem E/A-Abschlussport angegeben ist. Dieser Vervollständigungsschlüssel sollte für jedes Dateihandle eindeutig sein und begleitet das Dateihandle während des internen Vervollständigungswarteschlangenprozesses. Es wird im Funktionsaufruf GetQueuedCompletionStatus zurückgegeben, wenn ein Abschlusspaket eingeht. Der CompletionKey-Parameter wird auch von der PostQueuedCompletionStatus-Funktion verwendet, um Ihre eigenen speziellen Vervollständigungspakete in die Warteschlange zu stellen.

Nachdem ein instance eines geöffneten Handles einem E/A-Abschlussport zugeordnet ist, kann es nicht in der ReadFileEx- oder WriteFileEx-Funktion verwendet werden, da diese Funktionen über eigene asynchrone E/A-Mechanismen verfügen.

Es empfiehlt sich, ein Dateihandle, das einem E/A-Vervollständigungsport zugeordnet ist, nicht gemeinsam zu verwenden, indem Sie die Handlevererbung oder einen Aufruf der DuplicateHandle-Funktion verwenden. Vorgänge, die mit solchen doppelten Handles ausgeführt werden, generieren Vervollständigungsbenachrichtigungen. Es wird sorgfältig abgewogen.

Das E/A-Vervollständigungsporthandle und jedes Dateihandle, das diesem bestimmten E/A-Abschlussport zugeordnet ist, werden als Verweise auf den E/A-Abschlussport bezeichnet. Der E/A-Abschlussport wird freigegeben, wenn keine Verweise mehr darauf vorhanden sind. Daher müssen alle diese Handles ordnungsgemäß geschlossen werden, um den E/A-Abschlussport und die zugehörigen Systemressourcen freizugeben. Nachdem diese Bedingungen erfüllt sind, schließen Sie das E/A-Abschlussporthandle, indem Sie die CloseHandle-Funktion aufrufen.

In Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Anforderungen

Siehe auch

Übersichtsthemen

Dateiverwaltungsfunktionen

E/A-Vervollständigungsports

Verwenden der Windows-Header

Windows Sockets 2

Funktionen

AcceptEx

CreateFile

DuplicateHandle

GetQueuedCompletionStatus

GetQueuedCompletionStatusEx

PostQueuedCompletionStatus

ReadFileEx

WriteFileEx