When are IO completion port packets sent and when not?

Question

I'm currently working on an IPC mechanism based on named pipes using a IO completion port.

Unfortunately I have some troubles with the msdn documentation because it's quite unclear to me in which cases calls to ReadFile/WriteFile result in a completion packet.

The case when FALSE is returned with ERROR_IO_PENDING is clear, but what about the apparently possible case, when ERROR_MORE_DATA is returned? Will there be a completion packet in this case? Moreover, what if other errors are returned? In which cases do i have to handle the result and free resources directly and not in the completion handler?

Another case would be if ReadFile/WriteFile even succeed, which apparently is possible, too. MSDN is thankfully pretty clear about this here:

Further, the WriteFile function will sometimes return TRUE with a GetLastError value of ERROR_SUCCESS, even though it is using an asynchronous handle (which can also return FALSE with ERROR_IO_PENDING). ... In this example, the recommendation would be to allow the completion port routine to be solely responsible for all freeing operations for such resources.

Is this recommendation correct in all cases, and the result of an ReadFile/WriteFile operation for handles assigned to a completion port could (and should) in fact be ignored completely, because a packet is sent to the port anyways?

Answer 1

There will be an IO completion item queued for an IO operation whenever the IO operation is able to start. Regardless of whether an error is encountered or not after the IO operation starts, a completion item will be queued to the completion port.

There is a mapping problem between the NTSTATUS codes returned by the IO system and Win32 error codes that makes it hard to tell what statuses are errors and which are just informational. NTSTATUS, which is used by the kernel and the native API, has four levels of severity: success, information, warning and error. Anything but an error code would indicate that the IO operation was able to start. Win32 only has one severity (ERROR_*), so the success, information and warning codes had to be mapped alongside the error codes.

• ERROR_IO_PENDING - STATUS_PENDING is a success status
• ERROR_MORE_DATA - STATUS_BUFFER_OVERFLOW a warning or STATUS_MORE_ENTRIES a success status

You can ignore any non-error codes that ReadFile or WriteFile return and expect a queued completion item, but determining which is which can be a bit of a pain. It would be nice if the Win32 error codes were better organized, but Microsoft does provide a mapping from NTSTATUS to Win32 error codes: http://support.microsoft.com/kb/113996. See ntstatus.h in the platform SDK or your VS installation to determine what severity a NTSTATUS code is.

It is possible for the IO operation to be completed when the original API call returns, e.g. a read request that was just copied out of the cache (nothing to wait on asynchronously). A completion message will still be queued in such cases for consistency's sake.

Answer 2

• Yes, it is entirely possible that ERROR_MORE_DATA could come up in a completion packet. You should always be prepared to handle any potential errors. In the documentation for GetQueuedCompletionStatus it is clear that when it returns FALSE, you should check if the lpOverlapped parameter is NULL. If it isn't NULL, the I/O completion packet contains an error.

• The default behavior is for a completion packet to be queued up to the completion port even when ReadFile or WriteFile return TRUE. Starting with Windows Vista, this policy can be changed. See the documentation on SetFileCompletionNotificationModes.