Функция CreateIoCompletionPort (ioapiset.h)
Создает порт завершения ввода-вывода и связывает его с указанным дескриптором файла или создает порт завершения ввода-вывода, который еще не связан с дескриптором файла, что позволяет связаться позже.
Связывание экземпляра открытого дескриптора файла с портом завершения ввода-вывода позволяет процессу получать уведомления о завершении асинхронных операций ввода-вывода с использованием этого дескриптора файла.
Используемый здесь термин дескриптор файла относится к системной абстракции, представляющей перекрывающуюся конечную точку ввода-вывода, а не только файл на диске. Любые системные объекты, поддерживающие перекрывающиеся операции ввода-вывода, такие как сетевые конечные точки, сокеты TCP, именованные каналы и почтовые слоты, можно использовать в качестве дескрипторов файлов. Дополнительные сведения см. в разделе Примечания.
Синтаксис
HANDLE CreateIoCompletionPort(
[in] HANDLE FileHandle,
[in, optional] HANDLE ExistingCompletionPort,
[in] ULONG_PTR CompletionKey,
[in] DWORD NumberOfConcurrentThreads
);
Параметры
[in] FileHandle
Открытый дескриптор файла или INVALID_HANDLE_VALUE.
Дескриптор должен быть объектом, поддерживающим перекрывающиеся операции ввода-вывода.
Если указан дескриптор, он должен быть открыт для перекрывающихся операций ввода-вывода. Например, необходимо указать флаг FILE_FLAG_OVERLAPPED при использовании функции CreateFile для получения дескриптора.
Если указан INVALID_HANDLE_VALUE , функция создает порт завершения ввода-вывода, не связывая его с дескриптором файла. В этом случае параметр ExistingCompletionPort должен иметь значение NULL , а параметр CompletionKey игнорируется.
[in, optional] ExistingCompletionPort
Дескриптор существующего порта завершения ввода-вывода или null.
Если этот параметр указывает существующий порт завершения ввода-вывода, функция связывает его с дескриптором, заданным параметром FileHandle . Функция возвращает дескриптор существующего порта завершения ввода-вывода в случае успешного выполнения; он не создает новый порт завершения ввода-вывода.
Если этот параметр имеет значение NULL, функция создает новый порт завершения ввода-вывода и, если параметр FileHandle является допустимым , связывает его с новым портом завершения ввода-вывода. В противном случае связь дескрипторов файлов не возникает. Функция возвращает дескриптор в новый порт завершения ввода-вывода в случае успешного выполнения.
[in] CompletionKey
Определяемый пользователем ключ завершения для каждого дескриптора, включенный в каждый пакет завершения ввода-вывода для указанного дескриптора файла. Дополнительные сведения см. в разделе «Примечания».
[in] NumberOfConcurrentThreads
Максимальное количество потоков, которое может разрешить операционная система для параллельной обработки пакетов завершения ввода-вывода для порта завершения ввода-вывода. Этот параметр игнорируется, если параметр ExistingCompletionPort не имеет значения NULL.
Если этот параметр равен нулю, система допускает столько параллельно выполняющихся потоков, сколько процессоров в системе.
Возвращаемое значение
Если функция выполнена успешно, возвращается дескриптор порта завершения ввода-вывода:
- Если параметр ExistingCompletionPort имеет значение NULL, возвращаемое значение представляет собой новый дескриптор.
- Если параметр ExistingCompletionPort был допустимым дескриптором порта завершения ввода-вывода, возвращаемым значением будет тот же дескриптор.
- Если параметр FileHandle был допустимым дескриптором, этот дескриптор файла теперь связывается с возвращенным портом завершения ввода-вывода.
Комментарии
Системе ввода-вывода можно указать отправлять пакеты уведомлений о завершении ввода-вывода на порты завершения ввода-вывода, где они находятся в очереди. Эта функция предоставляется с помощью функции CreateIoCompletionPort .
Порт завершения ввода-вывода и его дескриптор связаны с процессом, который его создал, и не являются совместно используемыми между процессами. Однако один дескриптор можно совместно делиться между потоками в одном процессе.
CreateIoCompletionPort можно использовать в трех различных режимах:
- Создайте только порт завершения ввода-вывода, не связывая его с дескриптором файла.
- Свяжите существующий порт завершения ввода-вывода с дескриптором файла.
- Выполнение создания и связывания в одном вызове.
Дескриптором, передаваемым в параметре FileHandle , может быть любой дескриптор, поддерживающий перекрывающиеся операции ввода-вывода. Чаще всего это дескриптор, открытый функцией CreateFile с помощью флага FILE_FLAG_OVERLAPPED (например, файлы, почтовые слоты и каналы). Объекты, созданные другими функциями, такими как сокет , также могут быть связаны с портом завершения ввода-вывода. Пример использования сокетов см. в разделе AcceptEx. Дескриптор может быть связан только с одним портом завершения ввода-вывода, и после установления связи дескриптор остается связанным с этим портом завершения ввода-вывода, пока не будет закрыт.
Дополнительные сведения о теории портов завершения ввода-вывода, использовании и связанных функциях см. в разделе Порты завершения ввода-вывода.
Несколько дескрипторов файлов можно связать с одним портом завершения ввода-вывода, вызывая CreateIoCompletionPort несколько раз с одним дескриптором порта завершения ввода-вывода в параметре ExistingCompletionPort и другим дескриптором файла в параметре FileHandle каждый раз.
Используйте параметр CompletionKey , чтобы помочь приложению отслеживать, какие операции ввода-вывода завершены. Это значение не используется CreateIoCompletionPort для функционального управления; вместо этого он присоединяется к дескриптору файла, указанному в параметре FileHandle во время связи с портом завершения ввода-вывода. Этот ключ завершения должен быть уникальным для каждого дескриптора файла и сопровождать дескриптор файла на протяжении всего процесса внутренней очереди завершения. Он возвращается в вызове функции GetQueuedCompletionStatus при поступлении пакета завершения. Параметр CompletionKey также используется функцией PostQueuedCompletionStatus для постановки в очередь собственных пакетов завершения специального назначения.
После того как экземпляр открытого дескриптора связан с портом завершения ввода-вывода, его нельзя использовать в функции ReadFileEx или WriteFileEx , так как эти функции имеют собственные асинхронные механизмы ввода-вывода.
Лучше не предоставлять общий доступ к дескриптору файла, связанному с портом завершения ввода-вывода, с помощью наследования дескриптора или вызова функции DuplicateHandle . Операции, выполняемые с такими повторяющимися дескрипторами, создают уведомления о завершении. Рекомендуется тщательно рассмотреть этот вопрос.
Дескриптор порта завершения ввода-вывода и каждый дескриптор файла, связанный с этим портом завершения ввода-вывода, называются ссылками на порт завершения ввода-вывода. Порт завершения ввода-вывода освобождается, когда на него больше нет ссылок. Поэтому все эти дескрипторы должны быть должным образом закрыты, чтобы освободить порт завершения ввода-вывода и связанные с ним системные ресурсы. После выполнения этих условий закройте дескриптор порта завершения ввода-вывода, вызвав функцию CloseHandle .
В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.
| Технология | Поддерживается |
|---|---|
| Протокол SMB 3.0 | Да |
| Прозрачная отработка отказа (TFO) SMB 3.0 | Да |
| SMB 3.0 с масштабируемыми общими папками (SO) | Да |
| Файловая система общего тома кластера (CSVFS) | Да |
| Восстанавливаемая файловая система (ReFS) | Да |
Требования
| Минимальная версия клиента | Windows XP [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | ioapiset.h (включая Windows.h) |
| Библиотека | Kernel32.lib |
| DLL | Kernel32.dll |
См. также
Функции
Обзорные разделы