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.

Async functions using stackful coroutines

This example demonstrates how use the asynchronous functions using stackful coroutines (using boost::asio::yield_context and boost::asio::spawn).

This example assumes you have gone through the setup.

// To use coroutines created by boost::asio::spawn, you need to link
// against Boost.Context.

#include <boost/mysql/diagnostics.hpp>
#include <boost/mysql/error_code.hpp>
#include <boost/mysql/error_with_diagnostics.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/io_context.hpp>
#include <boost/asio/ip/tcp.hpp>
#include <boost/asio/post.hpp>
#include <boost/asio/spawn.hpp>
#include <boost/asio/ssl/context.hpp>

#include <iostream>

using boost::mysql::error_code;

void print_employee(boost::mysql::row_view employee)
    std::cout << "Employee '" << << " "   // first_name (string)
              << << "' earns "            // last_name  (string)
              << << " dollars yearly\n";  // salary     (double)

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

    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);

    // Connection params
    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 spawn a stackful coroutine using boost::asio::spawn.
     * The coroutine will actually start running when we call io_context::run().
     * It will suspend every time we call one of the asynchronous functions, saving
     * all information it needs for resuming. When the asynchronous operation completes,
     * the coroutine will resume in the point it was left.
        [&conn, &resolver, params, hostname, company_id](boost::asio::yield_context yield) {
            // This error_code and diagnostics will be filled if an
            // operation fails. We will check them for every operation we perform.
            boost::mysql::error_code ec;
            boost::mysql::diagnostics diag;

            // Hostname resolution
            auto endpoints = resolver.async_resolve(hostname, boost::mysql::default_port_string, yield[ec]);

            // Connect to server
            conn.async_connect(*endpoints.begin(), params, diag, yield[ec]);
            boost::mysql::throw_on_error(ec, diag);

            // We will be using company_id, which is untrusted user input, so we will use a prepared
            // statement.
            boost::mysql::statement stmt = conn.async_prepare_statement(
                "SELECT first_name, last_name, salary FROM employee WHERE company_id = ?",
            boost::mysql::throw_on_error(ec, diag);

            // Execute the statement
            boost::mysql::results result;
            conn.async_execute(stmt.bind(company_id), result, diag, yield[ec]);
            boost::mysql::throw_on_error(ec, diag);

            // Print the employees
            for (boost::mysql::row_view employee : result.rows())

            // Notify the MySQL server we want to quit, then close the underlying connection.
            conn.async_close(diag, yield[ec]);
            boost::mysql::throw_on_error(ec, diag);
        // If any exception is thrown in the coroutine body, rethrow it.
        [](std::exception_ptr ptr) {
            if (ptr)

    // Don't forget to call run()! Otherwise, your program
    // will not spawn the coroutine and will do nothing.;

int main(int argc, char** argv)
        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 encoding
        // (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;