The CreateIoCompletionPort function can associate an instance of an opened file with a newly created or an existing input/output (I/O) completion port; or it can create an I/O completion port without associating it with a file.
Associating an instance of an opened file with an I/O completion port lets an application receive notification of the completion of asynchronous I/O operations involving that file.
HANDLE CreateIoCompletionPort (
HANDLE FileHandle, // file handle to associate with
// the I/O completion port
HANDLE ExistingCompletionPort, // handle to the I/O completion port
DWORD CompletionKey, // per-file completion key for I/O
// completion packets
DWORD NumberOfConcurrentThreads // number of threads allowed to
// execute concurrently
);
If FileHandle specifies INVALID_HANDLE_VALUE, CreateIoCompletionPort creates an I/O completion port without associating it with a file. In this case, the ExistingCompletionPort parameter must be NULL, and the CompletionKey parameter is ignored.
If this parameter specifies an existing completion port, the function associates it with the file specified by the FileHandle parameter. The function returns the handle of the existing completion port; it does not create a new I/O completion port.
If this parameter is NULL, the function creates a new I/O completion port and associates it with the file specified by the FileHandle parameter. The function returns the handle to the new I/O completion port.
If one thread 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 down.
A value of 0 for this parameter indicates that the system can allow as many threads as there are processors in the system.
If the function succeeds, the return value is the handle to the I/O completion port that is associated with the specified file.
If the function fails, the return value is NULL. To get extended error information, call GetLastError.
The I/O system can be instructed to send I/O completion notification packets to I/O completion ports, where they are queued. The CreateIoCompletionPort function provides this functionality.
After an instance of an open file is associated with an I/O completion port, it cannot be used in the ReadFileEx or WriteFileEx function. It is best not to share such an associated file through either handle inheritance or a call to the DuplicateHandle function. Operations performed with such duplicate handles will generate completion notifications.
When you perform an I/O operation with a file handle that has an associated I/O 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 I/O system.
Windows NT: Requires version 3.5 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winbase.h.
Import Library: Use kernel32.lib.
File I/O Overview, File Functions, GetQueuedCompletionStatus, PostQueuedCompletionStatus