...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Retrieves a connection from the pool.
template<
class CompletionToken = with_diagnostics_t
<asio::deferred_t>>
auto
async_get_connection(
CompletionToken&& token = {});
Retrieves an idle connection from the pool to be used.
If this function completes successfully (empty error code), the return
pooled_connection
will have
valid()
== true
and will be usable. If it completes with a non-empty error code, it will
have valid()
== false
.
If a connection is idle when the operation is started, it will complete
immediately with that connection. Otherwise, it will wait for a connection
to become idle (possibly creating one in the process, if pool configuration
allows it), until the operation is cancelled (by emitting a cancellation
signal) or the pool is cancelled (by calling connection_pool::cancel
). If the pool is not
running, the operation fails immediately.
If the operation is cancelled, and the overload with diagnostics
was used, the output
diagnostics will contain the most recent error generated by the connections
attempting to connect (via any_connection::async_connect
), if any. In cases
where async_get_connection
doesn't
complete because connections are unable to connect, this feature can
help figuring out where the problem is.
this->valid() == true
While the operation is outstanding, the pool's internal data will be
kept alive. It is safe to destroy *this
while the operation is outstanding.
The handler signature for this operation is void(boost::mysql::error_code, boost::mysql::pooled_connection)
If the final handler has an associated immediate executor, and the operation
completes immediately, the final handler is dispatched to it. Otherwise,
the final handler is called as if it was submitted using asio::post
, and is never be called inline
from within this function. Immediate completions can only happen when
thread-safety is not enabled.
The final handler is executed using token
's
associated executor, or this->get_executor()
if the token doesn't have an associated
executor.
If the pool was constructed with thread-safety enabled, intermediate
completion handlers are executed using an internal strand that wraps
this->get_executor()
.
Otherwise, intermediate handlers are executed using token
's
associated executor if it has one, or this->get_executor()
if it hasn't.
This operation supports per-operation cancellation. Cancelling async_get_connection
has no observable
side effects. The following asio::cancellation_type_t
values are supported:
asio::cancellation_type_t::terminal
asio::cancellation_type_t::partial
asio::cancellation_type_t::total
client_errc::no_connection_available
,
if the async_get_connection
operation is cancelled before a connection becomes available.
client_errc::pool_not_running
, if the
async_get_connection
operation is cancelled before async_run is called.
client_errc::pool_cancelled
, if the pool
is cancelled before the operation completes, or async_get_connection
is called on a pool that has been cancelled.
Reads the internal state handle. Mutates the pool state. If the pool was built with thread-safety enabled, it can be called concurrently with other functions that don't modify the state handle.