Функция CreateIoCompletionPort


Функция CreateIoCompletionPort связывает порт завершения  ввода/вывода  (I/O) данных  с одним или несколькими дескрипторами файла, или она может создать порт завершение I/O, который не связан с дескриптором файла.

Соединение экземпляра открытого файла с портом завершения ввода - вывода   позволяет приложению получать уведомления о завершении асинхронных операций ввода-вывода (I/O), привлекающих к участию этот файл.

Синтаксис 

HANDLE CreateIoCompletionPort (
  HANDLE FileHandle,              // дескриптор файла
  HANDLE ExistingCompletionPort,  // дескриптор порта
                                  // завершения I/O  
  ULONG_PTR CompletionKey,        // код завершения
  DWORD NumberOfConcurrentThreads // число одновременно 
                                  // исполняемых потоков
);

Параметры

FileHandle

[in] Дескриптор файла открывается  для завершения асинхронной операции ввода-вывода. Вы должны установить флажок FILE_FLAG_OVERLAPPED при использовании функции CreateFile, чтобы получить этот дескриптор.

Если FileHandle установлен в INVALID_HANDLE_VALUE, функция CreateIoCompletionPort создает порт завершение ввода - вывода, не связывая его с файлом. В этом случае, параметр ExistingCompletionPort  должен быть ПУСТО (NULL), а параметр CompletionKey -  игнорироваться.

ExistingCompletionPort

[in] Дескриптор порта завершения ввода - вывода.

Если этот параметр определяет существующий порт завершения I/O, функция связывает его с файлом, указанным параметром FileHandle. Функция возвращает дескриптор существующего порта завершения I/O ; она не создает новый порт завершение  ввода - вывода.

Если этот параметр равен значению ПУСТО (NULL), функция создает новый порт завершение   ввода - вывода и связывает его с файлом, указанным в FileHandle. Функция возвращает дескриптор нового порта завершения I/O.

CompletionKey

[in]  Код завершения для каждого файла, который включается в каждый блок завершения ввода - вывода для указанного файла.

NumberOfConcurrentThreads

[in] Максимальное число потоков, которым операционная система дает возможность одновременно работать с блоками завершения ввода - вывода для порта завершения  ввода - вывода. Этот параметр игнорируется, если параметр ExistingCompletionPort - не ПУСТО (NULL). Если этот параметр равняется нулю, система дает возможность одновременно выполняться стольким  потокам, сколько есть процессоров в системе.

Возвращаемые значения

Если функция завершается успешно, возвращаемое значение - дескриптор порта завершения ввода-вывода (I/O), который связан с указанным файлом.

Если функция завершается ошибкой, возвращаемое значение - ПУСТО (NULL). Чтобы получить дополнительные данные об ошибке, вызовите GetLastError.

Замечания

Системе ввода - вывода может быть предписано, чтобы отправлять пакеты уведомления о завершении ввода - вывода портам завершающим I/O , где они поставлены в очередь. Функция CreateIoCompletionPort обеспечивает эти функциональные возможности.

Порт завершения освобождается тогда, когда нет больше ссылок на него. Дескриптор порта завершения и каждый дескриптор файла связаны ссылками на этот порт завершения. Все дескрипторы должны быть закрыты, чтобы освободить порт завершения. Чтобы закрыть дескриптор порта, вызовите функцию CloseHandle.

После того, как экземпляр открытого файла связывается с портом завершения ввода-вывода (I/O), он не может использоваться в функции ReadFileEx или WriteFileEx. Лучше всего такой связанный файл не использовать совместно  или через наследование дескриптора, или через вызов функции DuplicateHandle. Операции, выполненные с такими продублированными дескрипторами создают уведомления о завершении работы.

Когда Вы исполняете операцию ввода-вывода (I/O) с дескриптором файла, который имеет связь с портом завершения ввода-вывода (I/O) , система ввода - вывода отправляет пакет уведомления об окончании работы  порту завершения, когда операция ввода-вывода (I/O) заканчивает. Порт завершения ввода-вывода (I/O)  помещает пакет завершения в очередь по принципу "первым вошел - первым вышел". Используйте функцию GetQueuedCompletionStatus, чтобы извлекать эти синхронные пакеты завершения ввода - вывода.

Потоки в одном и том же процессе могут использовать функцию PostQueuedCompletionStatus, чтобы поместить пакеты уведомления о завершении ввода - вывода в очередь порта завершения. Делая так, в дополнение к получению пакетов уведомления о завершении ввода - вывода от системы I/O, Вы можете использовать этот порт, чтобы получить связь с другими потоками процесса.

Хотя любое число потоков может вызвать функцию GetQueuedCompletionStatus, чтобы ждать завершения I/O портом, каждый поток связан одновременно только с одним портом завершение I/O. Этот порт - порт, который был последний проверен потоком.

Когда пакет поставлен в очередь порта, система сначала проверяет, сколько выполняется потоков, связанных с портом . Если число запущенных потоков меньше, чем значение NumberOfConcurrentThreads, то одному из ждущих потоков дается возможность обработать пакет. Когда выполняющий поток заканчивает его обработку, он вызывает функцию GetQueuedCompletionStatus снова, чтобы в какой-то момент система могла дать возможность другому ждущему потоку обработать пакет.

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

Код примера

Пример смотри в статье Чтение асинхронно с портами завершения I/O

Смотри также 

Обзор Управление файламиФункции, используемые для файлового ввода-вывода (I/O), CreateFile, DuplicateHandle, GetQueuedCompletionStatus, PostQueuedCompletionStatus, ReadFileEx, WriteFileEx

Размещение и совместимость CreateIoCompletionPort

К

Windows XP

Да 

л

Windows 2000 Professional

Да

и

Windows NT Workstation

Да версии 3.5 и выше

е

Windows Me

Да

н

Windows 98

Да

т

Windows 95

Да

 
С

Windows Server 2003

Да

е Windows 2000 Server Да
р Windows NT Server Да версии 3.5 и выше
в    
е    
р    

Используемая библиотека

Kernel32.lib

Используемая DLL -
 Заголовочный файл  

- объявлено в

Winbase.h

 - включено в

Windows.h

 Unicode

Нет

 Замечания по платформе

Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки

Hosted by uCoz