WaitForSingleObject() on a completion port? - winapi

Question

Today I learned that I can call CreateIoCompletionPort() and then pass the returned HANDLE to WaitForSingleObject():
#include <Windows.h>
int main()
{
HANDLE h = CreateIoCompletionPort(INVALID_HANDLE_VALUE, nullptr, 0, 0);
auto bRes = PostQueuedCompletionStatus(h, 1, 2, 0);
if (!bRes) {
abort();
}
auto dwRes = WaitForSingleObject(h, INFINITE);
if (dwRes != WAIT_OBJECT_0){
abort();
}
LPOVERLAPPED pOvr;
DWORD cb;
ULONG_PTR key;
bRes = GetQueuedCompletionStatus(
h, &cb, &key, &pOvr, INFINITE); // <-- returns 1, 2, nullptr
if (!bRes) {
abort();
}
dwRes = WaitForSingleObject(h, INFINITE); // <-- blocks here
return 0;
}
It is working as expected on my Windows 10 box.
Is such behavior known or legal or documented? I was not able to find anything about it.

Answer 1

If you read the WaitForSingleObject() documentation, an I/O Completion Port is NOT an allowed handle type:
The WaitForSingleObject function can wait for the following objects:
Change notification
Console input
Event
Memory resource notification
Mutex
Process
Semaphore
Thread
Waitable timer
To wait for a completion event to arrive on the port, you must pass the handle to GetQueuedCompletionStatus() by itself and let it block until the event arrives or a timeout occurs.
#include <Windows.h>
int main()
{
HANDLE h = CreateIoCompletionPort(INVALID_HANDLE_VALUE, nullptr, 0, 0);
auto bRes = PostQueuedCompletionStatus(h, 1, 2, 0);
if (!bRes) {
abort();
}
LPOVERLAPPED pOvr;
DWORD cb;
ULONG_PTR key;
bRes = GetQueuedCompletionStatus(
h, &cb, &key, &pOvr, INFINITE); // <-- returns 1, 2, nullptr
if (!bRes) {
abort();
}
bRes = GetQueuedCompletionStatus(
h, &cb, &key, &pOvr, INFINITE); // <-- blocks here
return 0;
}

Answer 2

Summary:
don't do it. See Remy Lebeau's answer and MSDN on how to use completion ports correctly.
such abuse of completion ports is not only undocumented but also unreliable. Behavior varies between builds of Windows 10.
completion port is probably a legit object for a wait in kernel since KQUEUE that backs a completion port has a DISPATCHER_HEADER.