Поделиться через


Функция 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 был допустимым дескриптором, этот дескриптор файла теперь связывается с возвращенным портом завершения ввода-вывода.
Если функция завершается сбоем, возвращается значение 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 Да
Прозрачная отработка отказа (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

См. также

AcceptEx

CreateFile

DuplicateHandle

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

Функции

GetQueuedCompletionStatus

GetQueuedCompletionStatusEx

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

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

PostQueuedCompletionStatus

ReadFileEx

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

Сокеты Windows 2

WriteFileEx