Boost C++ Libraries

A completion token adapter used to include server diagnostics in exceptions.

Synopsis

Defined in header <boost/mysql/with_diagnostics.hpp>

template<
    class CompletionToken>
class with_diagnostics_t;

Member Functions

Description

When passed to an async initiating function, transforms its handler signature from void(error_code, T...) to void(std::exception_ptr, T...). Uses knowledge of Boost.MySQL internals to grab any diagnostics that the operation may produce to create a std::exception_ptr pointing to an error_with_diagnostics object. On success, the generated std::exception_ptr will be nullptr.

Using with_diagnostics to wrap tokens that throw exceptions (like deferred + co_await or yield_context) enhances the thrown exceptions with diagnostics information, matching the ones thrown by sync functions. If you don't use this token, Asio will use system_error exceptions, containing less info.

This token can only be used with operations involving Boost.MySQL, as it relies on its internals.

Like asio::as_tuple, this class wraps another completion token. For instance, with_diagnostics(asio::deferred) will generate a deferred operation with an adapted signature, which will throw error_with_diagnostics when co_await'ed.

If this token is applied to a function with a handler signature that does not match void(error_code, T...), the token acts as a pass-through: it does not modify the signature, and calls the underlying token's initiation directly. This has the following implications:

Convenience header <boost/mysql.hpp>