Функция CreateIoCompletionPort

Создает порт завершения ввода-вывода и связывает его с указанным дескриптором файла или порт завершения ввода-вывода, который еще не связан с дескриптором файла, что позволяет связать его позже.

Связывание экземпляра открытого дескриптора файла с портом завершения ввода-вывода позволяет процессу получать уведомление о завершении асинхронных операций ввода-вывода с использованием этого дескриптора файла.

Синтаксис

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 эта функция поддерживается следующими технологиями.

Требования

См. также

Обзорные разделы

Функции управления файлами

Порты завершения ввода-вывода

Использование заголовков Windows

Сокеты Windows 2

Функции

AcceptEx

CreateFile

DuplicateHandle

GetQueuedCompletionStatus

GetQueuedCompletionStatusEx

PostQueuedCompletionStatus

ReadFileEx

WriteFileEx