There are a number of reasons to call CancelIo, but in my particular case I'm calling it in order to know that the system is no longer writing into a buffer. Once I know that, I can safely free the buffer.
But what if CancelIo fails? What I do now is explicitly leak the buffer and throw an exception. Are there better ways to deal with this?
P.S. Analogous calls for Europa, Ganymede, and Callisto seem to be missing. Should I file a bug?
The MSDN docs are not very clear on what errors could be returned. I imagine (since CancelIo is asynchronous anyway) that this means you used a bad handle, or something major like that. By asynchronous I mean that just because CancelIo returns OK, you cannot immediately release the buffer for any pending I/O.
It is stated in the docs that pending I/Os will be returned with ERROR_OPERATION_ABORTED. I would think you already track pending I/O state such that you could safely release the buffer if and only if all pending I/Os return this error. If a pending I/O is left hanging after CancelIo, releasing the buffer could cause a cascade of undesirable side effects.
You shouldn't immediately delete your buffers after issuing a cancel request.
Taken from the CancelIoEx documentation :
If there are any pending I/O operations in progress for the specified file handle, the CancelIoEx function marks them for cancellation. Most types of operations can be canceled immediately; other operations can continue toward completion before they are actually canceled and the caller is notified. The CancelIoEx function does not wait for all canceled operations to complete.
So CancelIo does not 'release' the io operation, but marks it only as 'cancelled'. You have to wait on the result of your async-Read/Write to finish (either successfully or with ERROR_OPERATION_ABORTED.