Channels ▼


Multithreaded Asynchronous I/O & I/O Completion Ports

Source Code Accompanies This Article. Download It Now.

Retrieving Completed I/O Events from the Port

Now that we know how to create a completion port, associate descriptors to it, and initiate asynchronous I/O operations on the descriptors, it's on to retrieving completion events from the port. A thread removes an event from the port's queue by calling the GetQueuedCompletionStatus function:

BOOL GetQueuedCompletionStatus(
  HANDLE   CompletionPort,
  LPDWORD   pNumberOfBytes,
  PULONG_PTR   pCompletionKey,
  LPOVERLAPPED*   ppOverlapped,
  DWORD   Timeout

Obviously, the first parameter to this function is the handle to the port object, followed by several pointers and a Timeout value. Once an operation has completed successfully, the variable pointed to by pNumberOfBytes contains the number of bytes written or read during the I/O completion, the pCompletionKey value contains the value of the completion key passed when associating the file descriptor to the port, and the ppOverlapped variable points to the OVERLAPPED pointer passed as the parameter to the asynchronous I/O function. The timeout value, which is specified in milliseconds, works just like other Windows functions in that the special value INFINITE may be passed to specify "wait forever."

Sending Your Own Events: PostQueuedCompletionStatus

Before we move on to a practical example, there's one more function to discuss:

BOOL PostQueuedCompletionStatus(
  HANDLE       CompletionPort,
  DWORD   NumberOfBytesTransferred,
  ULONG_PTR    CompletionKey,
  LPOVERLAPPED pOverlapped

This function lets you post completion events to the port. Typically, this function is used to send implementation-specific messages to the port. When you post a completion event to a port, one of the threads blocking on the port successfully returns from its call to GetQueuedCompletionStatus with copies of the parameters as they were posted.

This function is often used to notify worker threads of some global or application-wide event. Along those lines, the sample program presented in this article posts completion events with a special completion key value of COMPLETION_KEY_SHUTDOWN in order to tell the worker threads that the server is shutting down.

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.