Boost C++ Libraries

...one 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 a snapshot of the develop branch, built from commit 53a72f668d.
PrevUpHomeNext

Timeouts

This example demonstrates how to use Boost.Asio's cancellation features to add timeouts to your async operations, including the ones provided by Boost.MySQL. For that purpose, it employs C++20 coroutines. If you are not familiar with them, look at this example first.

This example assumes you have gone through the setup.

#include <boost/mysql/diagnostics.hpp>
#include <boost/mysql/error_code.hpp>
#include <boost/mysql/handshake_params.hpp>
#include <boost/mysql/row_view.hpp>
#include <boost/mysql/tcp_ssl.hpp>
#include <boost/mysql/throw_on_error.hpp>

#include <boost/asio/as_tuple.hpp>
#include <boost/asio/awaitable.hpp>
#include <boost/asio/co_spawn.hpp>
#include <boost/asio/io_context.hpp>
#include <boost/asio/ip/tcp.hpp>
#include <boost/asio/ssl/context.hpp>
#include <boost/asio/steady_timer.hpp>
#include <boost/asio/use_awaitable.hpp>

#include <chrono>
#include <exception>
#include <iostream>
#include <stdexcept>

#if defined(BOOST_ASIO_HAS_CO_AWAIT) && !defined(BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT)

#include <boost/asio/experimental/awaitable_operators.hpp>

using namespace boost::asio::experimental::awaitable_operators;
using boost::asio::use_awaitable;
using boost::mysql::error_code;

constexpr std::chrono::milliseconds TIMEOUT(8000);

void print_employee(boost::mysql::row_view employee)
{
    std::cout << "Employee '" << employee.at(0) << " "   // first_name (string)
              << employee.at(1) << "' earns "            // last_name  (string)
              << employee.at(2) << " dollars yearly\n";  // salary     (double)
}

/**
 * Helper functions to check whether an async operation, launched in parallel with
 * a timer, was successful, resulted in an error or timed out. The timer is always the first operation.
 * If the variant holds the first alternative, the timer fired before
 * the async operation completed, which means a timeout. We'll be using as_tuple with use_awaitable to be able
 * to use boost::mysql::throw_on_error and include server diagnostics in the thrown exceptions.
 */
template <class T>
T check_error(
    std::variant<std::monostate, std::tuple<error_code, T>>&& op_result,
    const boost::mysql::diagnostics& diag = {}
)
{
    if (op_result.index() == 0)
    {
        throw std::runtime_error("Operation timed out");
    }
    auto [ec, res] = std::get<1>(std::move(op_result));
    boost::mysql::throw_on_error(ec, diag);
    return res;
}

void check_error(
    const std::variant<std::monostate, std::tuple<error_code>>& op_result,
    const boost::mysql::diagnostics& diag
)
{
    if (op_result.index() == 0)
    {
        throw std::runtime_error("Operation timed out");
    }
    auto [ec] = std::get<1>(op_result);
    boost::mysql::throw_on_error(ec, diag);
}

// Using this completion token instead of plain use_awaitable prevents
// co_await from throwing exceptions. Instead, co_await will return a std::tuple<error_code>
// with a non-zero code on error. We will then use boost::mysql::throw_on_error
// to throw exceptions with embedded diagnostics, if available. If you
// employ plain use_awaitable, you will get boost::system::system_error exceptions
// instead of boost::mysql::error_with_diagnostics exceptions. This is a limitation of use_awaitable.
constexpr auto tuple_awaitable = boost::asio::as_tuple(boost::asio::use_awaitable);

/**
 * We use Boost.Asio's cancellation capabilities to implement timeouts for our
 * asynchronous operations. This is not something specific to Boost.MySQL, and
 * can be used with any other asynchronous operation that follows Asio's model.
 *
 * Each time we invoke an asynchronous operation, we also call timer_type::async_wait.
 * We then use Asio's overload for operator || to run the timer wait and the async operation
 * in parallel. Once the first of them finishes, the other operation is cancelled
 * (the behavior is similar to JavaScripts's Promise.race).
 * If we co_await the awaitable returned by operator ||, we get a std::variant<std::monostate, T>,
 * where T is the async operation's result type. If the timer wait finishes first (we have a
 * timeout), the variant will hold the std::monostate at index 0; otherwise, it will have the async
 * operation's result at index 1. The function check_error throws an exception in the case of
 * timeout and extracts the operation's result otherwise.
 *
 * If any of the MySQL specific operations result in a timeout, the connection is left
 * in an unspecified state. You should close it and re-open it to get it working again.
 */
boost::asio::awaitable<void> coro_main(
    boost::mysql::tcp_ssl_connection& conn,
    boost::asio::ip::tcp::resolver& resolver,
    boost::asio::steady_timer& timer,
    const boost::mysql::handshake_params& params,
    const char* hostname,
    const char* company_id
)
{
    boost::mysql::diagnostics diag;

    // Resolve hostname
    timer.expires_after(TIMEOUT);
    auto endpoints = check_error(co_await (
        timer.async_wait(use_awaitable) ||
        resolver.async_resolve(hostname, boost::mysql::default_port_string, tuple_awaitable)
    ));

    // Connect to server. Note that we need to reset the timer before using it again.
    timer.expires_after(TIMEOUT);
    auto op_result = co_await (
        timer.async_wait(use_awaitable) ||
        conn.async_connect(*endpoints.begin(), params, diag, tuple_awaitable)
    );
    check_error(op_result, diag);

    // We will be using company_id, which is untrusted user input, so we will use a prepared
    // statement.
    auto stmt_op_result = co_await (
        timer.async_wait(use_awaitable) ||
        conn.async_prepare_statement(
            "SELECT first_name, last_name, salary FROM employee WHERE company_id = ?",
            diag,
            tuple_awaitable
        )
    );
    boost::mysql::statement stmt = check_error(std::move(stmt_op_result), diag);

    // Execute the statement
    boost::mysql::results result;
    timer.expires_after(TIMEOUT);
    op_result = co_await (
        timer.async_wait(use_awaitable) ||
        conn.async_execute(stmt.bind(company_id), result, diag, tuple_awaitable)
    );
    check_error(op_result, diag);

    // Print all the obtained rows
    for (boost::mysql::row_view employee : result.rows())
    {
        print_employee(employee);
    }

    // Notify the MySQL server we want to quit, then close the underlying connection.
    op_result = co_await (timer.async_wait(use_awaitable) || conn.async_close(diag, tuple_awaitable));
    check_error(op_result, diag);
}

void main_impl(int argc, char** argv)
{
    if (argc != 4 && argc != 5)
    {
        std::cerr << "Usage: " << argv[0] << " <username> <password> <server-hostname> [company-id]\n";
        exit(1);
    }

    const char* hostname = argv[3];

    // The company_id whose employees we will be listing. This
    // is user-supplied input, and should be treated as untrusted.
    const char* company_id = argc == 5 ? argv[4] : "HGS";

    // I/O context and connection. We use SSL because MySQL 8+ default settings require it.
    boost::asio::io_context ctx;
    boost::asio::ssl::context ssl_ctx(boost::asio::ssl::context::tls_client);
    boost::mysql::tcp_ssl_connection conn(ctx, ssl_ctx);
    boost::asio::steady_timer timer(ctx.get_executor());

    // Connection parameters
    boost::mysql::handshake_params params(
        argv[1],                // username
        argv[2],                // password
        "boost_mysql_examples"  // database to use; leave empty or omit for no database
    );

    // Resolver for hostname resolution
    boost::asio::ip::tcp::resolver resolver(ctx.get_executor());

    // The entry point. We pass in a function returning a boost::asio::awaitable<void>, as required.
    boost::asio::co_spawn(
        ctx.get_executor(),
        [&conn, &resolver, &timer, params, hostname, company_id] {
            return coro_main(conn, resolver, timer, params, hostname, company_id);
        },
        // If any exception is thrown in the coroutine body, rethrow it.
        [](std::exception_ptr ptr) {
            if (ptr)
            {
                std::rethrow_exception(ptr);
            }
        }
    );

    // Calling run will actually start the requested operations.
    ctx.run();
}

#else

void main_impl(int, char**)
{
    std::cout << "Sorry, your compiler does not support C++20 coroutines" << std::endl;
}

#endif

int main(int argc, char** argv)
{
    try
    {
        main_impl(argc, argv);
    }
    catch (const boost::mysql::error_with_diagnostics& err)
    {
        // You will only get this type of exceptions if you use throw_on_error.
        // Some errors include additional diagnostics, like server-provided error messages.
        // Security note: diagnostics::server_message may contain user-supplied values (e.g. the
        // field value that caused the error) and is encoded using to the connection's character set
        // (UTF-8 by default). Treat is as untrusted input.
        std::cerr << "Error: " << err.what() << '\n'
                  << "Server diagnostics: " << err.get_diagnostics().server_message() << std::endl;
        return 1;
    }
    catch (const std::exception& err)
    {
        std::cerr << "Error: " << err.what() << std::endl;
        return 1;
    }
}

PrevUpHomeNext