Holy cow, I wrote a book!
A customer reported that their program was not respecting
the FILE_FLAG_OVERLAPPED flag consistently:
My program opens a file handle in
binds it to an I/O completion callback function with
issues a WriteFile against it.
I would expect that the WriteFile returns FALSE
and GetLastError() returns
indicating that the I/O operation is being performed asynchronously,
and that the completion function will be called when the
However, I find that some percentage of the time,
the call to WriteFile returns TRUE,
indicating that the operation was performed synchronously.
What am I doing wrong?
I don't want my thread to block on I/O;
that's why I'm issuing asynchronous I/O.
When you specify FILE_FLAG_OVERLAPPED,
you're promising that your program knows how to handle I/O
which completes asynchronously,
but it does not require the I/O stack to behave asynchronously.
A driver can choose to perform your I/O synchronously anyway.
For example, if the write operation can be performed by writing
to cache without blocking,
the driver will just copy the data to the cache and indicate
Don't worry, be happy:
Your I/O completed even faster than you expected!
Even though the I/O completed synchronously, all the asynchronous
completion notification machinery is still active.
It's just that they all accomplished their job before the
WriteFile call returned.
This means that the event handle will still be signaled,
the completion routine will still run (once you wait alertably),
and if the handle is bound to an I/O completion port,
the I/O completion port will receive a completion notification.
You can use the
function to change some aspects of this behavior,
giving some control of the behavior of the I/O subsystem when
a potentially-asynchronous I/O request completes synchronously.