1

I do not fully understand what is the purpose of the OVERLAPPED structure, is it used for the advanced stuff? If I want to receive data for example, I just create an instance of WSABUF structure and pass it to WSARecv(), and when the read operation is completed I process the buffer. But where does the OVERLAPPED structure fits in all of this?

John
  • 1,049
  • 1
  • 14
  • 34

3 Answers3

2

From the documentation for WSARecv:

If the lpCompletionRoutine parameter is NULL, the hEvent parameter of lpOverlapped is signaled when the overlapped operation completes if it contains a valid event object handle. An application can use WSAWaitForMultipleEvents or WSAGetOverlappedResult to wait or poll on the event object.

If lpCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used by the application to pass context information to the completion routine. A caller that passes a non-NULL lpCompletionRoutine and later calls WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait parameter for that invocation of WSAGetOverlappedResult to TRUE. In this case the usage of the hEvent parameter is undefined, and attempting to wait on the hEvent parameter would produce unpredictable results.

So, either you are not using a completion routine, and can wait on the event to signal completion. Or you are using a completion routine and can use the event field to supply context to the completion routine.

David Heffernan
  • 601,492
  • 42
  • 1,072
  • 1,490
  • So in my case (I am not using a completion routine), I can wait on the event field in the `OVERLAPPED` instance to see when the IO operation is completed? – John Feb 24 '15 at 16:36
  • The quoted documentation has nothing to do with IOCP. It concerns overlapped I/O but the quoted mechanisms isn't how it would work. With IOCP, you wouldn't wait on hEvent or use the completion routine. The completion routine doesn't concern IOCP. You would create the socket with WSA_FLAG_OVERLAPPED and then add the socket to an IO completion port. When you call WSARecv, you would give it an empty OVERLAPPED structure with a NULL completion routine. – computerquip Dec 30 '22 at 10:59
1

I was a bit confused about this as well at first. I needed a refresher and ran across this which was a bit depressing. I've refreshed myself and I'll post my understanding here (mostly as a reference for myself). First some terms...

Overlapped I/O

Overlapped I/O means asynchronous. Normally, when you make a call to an I/O function, it blocks until completion. With overlapped I/O, you are either notified at a later time of the completion of I/O or you wait on that specific operation in a thread. IOCP deals with the former.

IOCP

IOCP is essentially an I/O completion queue of sorts. When an asynchronous I/O operation occurs, you need some way to handle the notification of completion of that operation. IOCP provides the primitives to be notified when that completion occurs along with information about the I/O operation performed.

The structure OVERLAPPED

OVERLAPPED is simply a structure that's often used with overlapped (asynchronous) I/O. It's important to make the distinction between overlapped I/O and the OVERLAPPED structure. For example, you can give WSARecv a completely empty OVERLAPPED structure and a routine and you can still be notified asynchronously of completion.

So...

What does IOCP have to do with the structure OVERLAPPED

In concept, almost nothing. IOCP is related to overlapped I/O, not the structure OVERLAPPED. However, the OVERLAPPED structure itself serves three practical purposes in regards to IOCP.

  1. Any function (such as WSARecv) that's capable of overlapped I/O requires an OVERLAPPED structure (even if empty) to indicate that you want overlapped I/O. You need overlapped I/O to make IOCP function or to even make sense.
  2. OVERLAPPED is used to hold contextual data in the completion packets given to IOCP. Raymond gives an example.
  3. The structure itself is used for miscellaneous information such as the ironically named Internal to hold status of the request, InternalHigh to hold bytes transferred, and hEvent, while not used directly, can be used to synchronize requests.
computerquip
  • 123
  • 7
0

As mentioned above, the OVERLAPPED structure provides context for your I/O operations. Whether using a completion routine, or polling/waiting via GetQueuedCompletionStatus.

Keep in mind that generally in IOCP you can have multiple operations pending on a single handle. It's also the only way to get status/error information in some cases (See GetQueuedCompletionStatusEx, for example).

Mark Nunberg
  • 3,551
  • 15
  • 18