CreateIoCompletionPort
The CreateIoCompletionPort
function can associate an instance of an opened file with a newly created or an
existing input/output completion port; or it can create an input/output
completion port without associating it with a file.
Associating
an instance of an opened file with an input/output completion port lets an
application receive notification of the completion of asynchronous input/output
operations involving that file.
HANDLE CreateIoCompletionPort (
|
HANDLE FileHandle, |
// file handle to
associate with I/O completion port |
|
HANDLE ExistingCompletionPort, |
// optional handle
to existing I/O completion port |
|
DWORD CompletionKey, |
// per-file
completion key for I/O completion packets |
|
DWORD NumberOfConcurrentThreads |
// number of
threads allowed to execute concurrently |
|
); |
|
Parameters
FileHandle
Handle to a
file opened for overlapped input/output completion. You must specify the
FILE_FLAG_OVERLAPPED flag when using the CreateFile function to obtain such a
handle.
Once an
instance of an open file is associated with an I/O completion port, it cannot
be used in ReadFileEx
or WriteFileEx
operations.
It is best
not to share such an associated file through either handle inheritance or a
call to the DuplicateHandle
function. Input/output operations done with such duplicate handles will
generate completion notifications.
If FileHandle
specifies INVALID_HANDLE_VALUE, CreateIoCompletionPort creates an
input/output completion port without associating it with a file. In this case,
the ExistingCompletionPort parameter must be NULL, and the CompletionKey
parameter is ignored.
ExistingCompletionPort
Handle to an
existing I/O completion port. This parameter can be NULL.
If this
parameter is not NULL, it specifies an existing completion port that the function
is to associate with the file specified by FileHandle.
If this
parameter is NULL, the function creates a new input/output completion port that
it associates with the specified file.
CompletionKey
Specifies a per-file
completion key that will be included in every input/output completion packet
for the specified file.
NumberOfConcurrentThreads
Specifies the
number of threads that are allowed to execute concurrently.
If one of the
threads enters a wait state, then another thread is allowed to proceed. There
may be brief periods when the number of active threads exceeds the specified
value, but the operating system quickly brings the number back down.
A value of 0
for this parameter tells the operating system to allow as many threads as there
are processors in the system.
Return Values
If the
function succeeds, the return value is the handle to the I/O completion port
that is associated with the specified file. This return value is not NULL.
If the
function fails, the return value is NULL. To get extended error information,
call GetLastError.
Remarks
The Win32 I/O
system can be instructed to send I/O completion notification packets to
input/output completion ports, where they are queued up. The CreateIoCompletionPort
function provides a mechanism for this.
When you
perform an input/output operation with a file handle that has an associated
input/output completion port, the I/O system sends a completion notification
packet to the completion port when the I/O operation completes. The I/O
completion port places the completion packet in a first-in-first-out queue. Use
the GetQueuedCompletionStatus function to retrieve these queued I/O
completion packets.
Threads in
the same process can use the PostQueuedCompletionStatus function to
place I/O completion notification packets in a completion port s queue. This
allows you to use the port to receive communications from other threads of the
process, in addition to receiving I/O completion notification packets from the
Win32 I/O system.
See Also