connection_pool

(EXPERIMENTAL) 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. — 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.

Thread-safety

By default, connection pools are not thread-safe, but most functions can be made thread-safe by passing an adequate pool_executor_params objects to the constructor. See pool_executor_params::thread_safe and the discussion for details.

Distinct objects: safe.

Shared objects: unsafe, unless passing adequate values to the constructor.

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.

Experimental

This part of the API is experimental, and may change in successive releases without previous notice.

Convenience header <boost/mysql.hpp>