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

PrevUpHomeNext
connection_pool::async_get_connection (1 of 2 overloads)

Retrieves a connection from the pool.

Synopsis
template<
    class CompletionToken = with_diagnostics_t<asio::deferred_t>>
auto
async_get_connection(
    CompletionToken&& token = {});
Description

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.

Preconditions

this->valid() == true

Object lifetimes

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.

Handler signature

The handler signature for this operation is void(boost::mysql::error_code, boost::mysql::pooled_connection)

Executor

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.

Per-operation cancellation

This operation supports per-operation cancellation. Cancelling async_get_connection has no observable side effects. The following asio::cancellation_type_t values are supported:

Errors
Thread-safety

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.


PrevUpHomeNext