Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.

Going async

Following Boost.Asio's convention, all network operations have asynchronous versions with the same name prefixed by async_. The last parameter to async operations is a CompletionToken, which dictates how the asynchronous operation will be managed and the function's return type. These async_ functions are called async initiating functions.

Every async initiating function has an associated handler type, which dictates how the asynchronous operation communicates its result back to the caller. This handler type always has one of the two following forms:

  1. void(error_code). Used in operations that do not have a proper result, e.g. connection::async_connect.
  2. void(error_code, T). Used in operations that have a result, e.g. connection::async_prepare_statement (in this case, T is statement).

All asynchronous functions are overloaded to accept an optional diagnostics output parameter. It is populated with any server-provided error information before calling the completion handler.

Single outstanding operation per connection

As mentioned in this section, only a single async operation per connection can be outstanding at a given point in time. If you need to perform queries in parallel, open more connections to the server.

Completion tokens

Any completion token you may use with Boost.Asio can also be used with this library. Here are some of the most common:

Cancellations and timeouts

All async operations in this library support per-operation cancellation. All operations support only the terminal boost::asio::cancellation_type. This means that, if an async operation is cancelled, the connection object is left in an unspecified state, after which you should close or destroy the connection. In particular, it is not safe to retry the cancelled operation.

Supporting cancellation allows you to implement timeouts without explicit support from the library. This example demonstrates how to implement this pattern.

Note that cancellation happens at the Boost.Asio level, and not at the MySQL operation level. This means that, when cancelling an operation, the current network read or write will be cancelled. The operation may have already reached the server and be executed. As stated above, after an operation is cancelled, the connection is left in an unspecified state, and you should close or destroy it.