| Home | Libraries | People | FAQ | More

###### 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.

Caution: be careful when using thread-safety and `asio::cancel_after`, as it can result in inadvertent race conditions. Please refer to this page for more info.

###### 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:

- `asio::cancellation_type_t::terminal`
- `asio::cancellation_type_t::partial`
- `asio::cancellation_type_t::total`

###### Errors

- `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.

###### 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.