Asynchronous Reading
Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista
When messages are read synchronously, the reading function or method returns only when the I/O operation is completed. When messages are read asynchronously, the reading function or method returns immediately, but with notification that an asynchronous I/O operation is pending. This means that the time between initiation of the asynchronous read operation and its completion can be used to do something useful, which may be to initiate another read operation. There are four mechanisms that can be used to read messages asynchronously:
Callback functions
Windows events
Completion ports (Not available for dependent clients.)
Message Queuing COM components
When using a callback function, Message Queuing reads the message by calling the callback function that is currently registered. The function is called if a message is immediately available, when a message arrives, or when the time for reading a message expires. Only 63 callbacks can be registered at the same time.
When using an event mechanism, an Overlapped structure provides a valid handle (hEvent field) to an event object. When a suitable message arrives, or a time-out occurs, the event object is set to the signaled state.
When using a completion port, a queue handle can be associated with the port to receive messages asynchronously. For more information, see CreateIOCompletionPort.
When using the Message Queuing COM components, define an event handler that is notified when a message arrives or a time-out occurs. The user-defined event handler itself is invoked from an internally implemented callback function (limited to 64 callbacks, one of which is used by the runtime). Therefore, all callback features and restrictions apply when using the COM components.
COM components invoke an ArrivedError event handler with MQ_ERROR_IO_TIMEOUT when a time-out occurs.
Note
Cursors behave the same way in synchronous and asynchronous operations. However, when using a cursor to read messages asynchronously do not use the same cursor in overlapping read operations. For example, when moving a cursor you should not fire a second receive operation before the previous receive is completed. This type of action may lead to unexpected behavior.
When reading messages in a queue, Message Queuing can peek at the messages (leaving them in the queue) or retrieve them (removing the messages from the queue).
More Information
| For information on | See |
|---|---|
| Leaving a message when it is read | Peeking at Messages |
| Removing a message when it is read | Retrieving Messages |
| Reading past the first message in the queue | Navigating with Cursors |
| How transactions work and the different types of transactions | Transactions |
| Reading the first message in the queue synchronously | C/C++ Code Example: Reading Messages Synchronously C/C++ COM Code Example: Reading Messages Synchronously Visual Basic Code Example: Reading Messages Synchronously |
| Reading messages asynchronously | C/C++ Code Example: Reading Messages Asynchronously Using a Callback Function C/C++ Code Example: Reading Messages Asynchronously Using Completion Ports C/C++ COM Code Example: Reading Messages Asynchronously Visual Basic Code Example: Reading Messages Asynchronously |