connection_pool

A pool of connections of variable size.

Synopsis

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

class connection_pool;

Types

Name	Description
executor_type	The executor type associated to this object.

Member Functions

Name	Description
async_get_connection	Retrieves a connection from the pool.
async_run	Runs the pool task in charge of managing connections.
cancel	Stops any current outstanding operation and marks the pool as cancelled.
connection_pool [constructor]	Constructs a connection pool. — Move-constructor.
get_executor	Retrieves the executor associated to this object.
operator=	Move assignment.
valid	Returns whether the object is in a moved-from state.
~connection_pool [destructor]	Destructor.

A connection pool creates and manages any_connection objects. Using a pool allows to reuse sessions, avoiding part of the overhead associated to session establishment. It also features built-in error handling and reconnection. See the discussion and examples for more details on when to use this class.

Connections are retrieved by async_get_connection, which yields a pooled_connection object. They are returned to the pool when the pooled_connection is destroyed, or by calling pooled_connection::return_without_reset.

A pool needs to be run before it can return any connection. Use async_run for this. Pools can only be run once.

Connections are created, connected and managed internally by the pool, following a well-defined state model. Please refer to the discussion for details.

Due to oddities in Boost.Asio's universal async model, this class only exposes async functions. You can use asio::use_future to transform them into sync functions (please read the discussion for details).

This is a move-only type.

Default completion tokens

The default completion token for all async operations in this class is with_diagnostics(asio::deferred), which allows you to use co_await and have the expected exceptions thrown on error.

Thread-safety

Pools are composed of an internal state object, plus a handle to such state. Each component has different thread-safety rules.

Regarding internal state, connection pools are not thread-safe by default, but can be made safe by constructing them with pool_params::thread_safe set to true. Internal state is also mutated by some functions outside connection_pool, like returning connections.

The following actions imply a pool state mutation, and are protected by a strand when thread-safety is enabled:

Calling connection_pool::async_run.
Calling connection_pool::async_get_connection.
Cancelling async_get_connection by emitting a cancellation signal.
Returning a connection by destroying a pooled_connection or calling pooled_connection::return_without_reset.
Cancelling the pool by calling connection_pool::cancel, emitting a cancellation signal for async_run, or destroying the connection_pool object.

The handle to the pool state is never thread-safe, even for pools with thread-safety enabled. Functions like assignments modify the handle, and cause race conditions if called concurrently with other functions. Other objects, like pooled_connection, have their own state handle, and thus interact only with the pool state.

In summary:

Distinct objects: safe.
Shared objects: unsafe. Setting pool_params::thread_safe to true makes some functions safe.

Object lifetimes

Connection pool objects create an internal state object that is referenced by other objects and operations (like pooled_connection). This object will be kept alive using shared ownership semantics even after the connection_pool object is destroyed. This results in intuitive lifetime rules.

Convenience header <boost/mysql.hpp>