Функция CreateIoCompletionPort
Создает порт завершения ввода-вывода и связывает его с указанным дескриптором файла или порт завершения ввода-вывода, который еще не связан с дескриптором файла, что позволяет связать его позже.
Связывание экземпляра открытого дескриптора файла с портом завершения ввода-вывода позволяет процессу получать уведомление о завершении асинхронных операций ввода-вывода с использованием этого дескриптора файла.
Примечание
Термин дескриптор файла , используемый здесь, относится к системной абстракции, представляющей перекрывающуюся конечную точку ввода-вывода, а не только файл на диске. В качестве дескрипторов файлов можно использовать любые системные объекты, поддерживающие перекрывающиеся операции ввода-вывода, такие как сетевые конечные точки, сокеты TCP, именованные каналы и почтовые слоты. Дополнительные сведения см. в разделе Примечания.
Синтаксис
HANDLE WINAPI CreateIoCompletionPort(
_In_ HANDLE FileHandle,
_In_opt_ HANDLE ExistingCompletionPort,
_In_ ULONG_PTR CompletionKey,
_In_ DWORD NumberOfConcurrentThreads
);
Параметры
-
FileHandle [in]
-
Открытый дескриптор файла или INVALID_HANDLE_VALUE.
Дескриптор должен быть объектом, поддерживающим перекрывающиеся операции ввода-вывода.
Если указан дескриптор, он должен быть открыт для перекрытия завершения ввода-вывода. Например, необходимо указать флаг FILE_FLAG_OVERLAPPED при использовании функции CreateFile для получения дескриптора.
Если указано INVALID_HANDLE_VALUE , функция создает порт завершения ввода-вывода, не связывая его с дескриптором файла. В этом случае параметр ExistingCompletionPort должен иметь значение NULL , а параметр CompletionKey игнорируется.
-
ExistingCompletionPort [в, необязательно]
-
Дескриптор существующего порта завершения ввода-вывода или null.
Если этот параметр указывает существующий порт завершения ввода-вывода, функция связывает его с дескриптором, указанным параметром FileHandle . Функция возвращает дескриптор существующего порта завершения ввода-вывода в случае успешного выполнения; Он не создает новый порт завершения ввода-вывода.
Если этот параметр имеет значение NULL, функция создает новый порт завершения ввода-вывода и, если параметр FileHandle является допустимым , связывает его с новым портом завершения ввода-вывода. В противном случае связь с дескриптором файла не возникает. Функция возвращает дескриптор в новый порт завершения ввода-вывода в случае успешного выполнения.
-
CompletionKey [in]
-
Определяемый пользователем ключ завершения для каждого дескриптора, который включается в каждый пакет завершения ввода-вывода для указанного дескриптора файла. Дополнительные сведения см. в разделе «Примечания».
-
NumberOfConcurrentThreads [in]
-
Максимальное количество потоков, которое операционная система может разрешить параллельно обрабатывать пакеты завершения ввода-вывода для порта завершения ввода-вывода. Этот параметр игнорируется, если параметр ExistingCompletionPort не равен NULL.
Если этот параметр равен нулю, система позволяет одновременно запускать столько потоков, сколько процессоров в системе.
Возвращаемое значение
При успешном выполнении функции возвращается значение дескриптора для порта завершения ввода-вывода:
Если параметр ExistingCompletionPort имеет значение NULL, возвращаемое значение представляет собой новый дескриптор.
Если параметр ExistingCompletionPort был допустимым дескриптором порта завершения ввода-вывода, возвращаемым значением будет тот же дескриптор.
Если параметр FileHandle был допустимым дескриптором, этот дескриптор файла теперь связывается с возвращенным портом завершения ввода-вывода.
Если функция завершается сбоем, возвращается значение NULL. Чтобы получить расширенные сведения об ошибке, вызовите функцию GetLastError .
Комментарии
Системе ввода-вывода можно указать отправлять пакеты уведомлений о завершении ввода-вывода на порты завершения ввода-вывода, где они находятся в очереди. Эту функцию предоставляет функция CreateIoCompletionPort .
Порт завершения ввода-вывода и его дескриптор связаны с процессом, который его создал, и не могут быть совместно используемыми между процессами. Однако один дескриптор можно совместно работать между потоками в одном процессе.
CreateIoCompletionPort можно использовать в трех различных режимах:
- Создайте только порт завершения ввода-вывода, не связывая его с дескриптором файла.
- Свяжите существующий порт завершения ввода-вывода с дескриптором файла.
- Создание и сопоставление выполняются в одном вызове.
Чтобы создать порт завершения ввода-вывода без его связывания, задайте для параметра FileHandleзначение INVALID_HANDLE_VALUE, для параметра ExistingCompletionPort — значение NULL, а для параметра CompletionKey — нулевое значение (что в данном случае игнорируется). Задайте для параметра NumberOfConcurrentThreads требуемое значение параллелизма для нового порта завершения ввода-вывода или ноль для значения по умолчанию (количество процессоров в системе).
Дескриптором, передаваемым в параметре 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 |
Да |
| SMB 3.0 Transparent Failover (TFO) |
Да |
| SMB 3.0 с масштабируемыми общими папками (SO) |
Да |
| Файловая система общего тома кластера (CSVFS) |
Да |
| Восстанавливаемая файловая система (ReFS) |
Да |
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента |
Windows XP [классические приложения | Приложения UWP] |
| Минимальная версия сервера |
Windows Server 2003 [классические приложения | Приложения UWP] |
| Заголовок |
|
| Библиотека |
|
| DLL |
|