Following Boost.Asio's convetion,
all network operations have asynchronous versions with the same name prefixed
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
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:
All asynchronous functions are overloaded to accept an optional
output parameter. It is populated with any server-provided error information
before calling the completion handler.
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.
Any completion token you may use with Boost.Asio can also be used with this library. Here are some of the most common:
Callbacks. You can pass in a callable
(function pointer or function object) with the same signature as the
handler signature specified for the operation. The callable will be called
when the operation completes. The initiating function will return
This example demonstrates how to use async functions with callbacks.
Futures. In this case, you pass in the
as completion token. The initiating function will return one of the following:
std::future<void>, if the completion handler has the form given by 1).
std::future<T>, if the completion handler has the form given by 2).
You can wait for the future by calling
If an error occurs,
will throw an exception. Note that the exception is thrown by Asio itself,
and will always be of type
even if diagnostics were available.
This example demonstrates using futures.
void, if the completion handler has the form given by 1).
T, if the completion handler has the form given by 2).
If you use
the operation will set the given
when it fails. Otherwise, the function will throw a exception. Note that
this exception is thrown by Asio itself, and thus will always be of type
boost::system::system_error. To obtain an
we suggest using error codes and the
This example uses stackful coroutines.
C++20 coroutines. In this case, you
pass in the constant
as completion token. The initiating function will return:
You can then use
on this return value. If the operation fails,
will throw an exception. Note that this exception is thrown by Asio itself,
and thus will always be of type
To obtain an
we suggest using the
completion token, which will make
report failures using error codes, and the
This example demonstrates C++20 coroutines.
Boost.MySQL also supports default completion tokens. Recall that some stream types may have an associated Executor that has an associated default completion token type (see [asiorelink default_completion_token default_completion_token]). If this is the case, you don't need to specify the CompletionToken parameter in initiating functions, and the default will be used. This example demonstrates using default completion tokens with Boost.MySQL.
All async operations in this library support per-operation
cancellation. All operations support only the
This means that, if an async operation is cancelled, the
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.