| Home | Libraries | People | FAQ | More

###### connection_pool::async_get_connection (4 of 4 overloads)

Retrieves a connection from the pool.

###### Synopsis

    template<
        class CompletionToken>
    auto
    async_get_connection(
        std::chrono::steady_clock::duration timeout,
        diagnostics& diag,
        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), up to a duration of `timeout`. A zero timeout disables it.

If a timeout happens because connection establishment has failed, appropriate diagnostics will be returned.

###### Preconditions

`this->valid() == true`

Timeout values must be positive: `timeout.count() >= 0`.

###### 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)`

###### Errors

- Any error returned by `any_connection::async_connect`, if a timeout happens because connection establishment is failing.
- `client_errc::timeout`, if a timeout happens for any other reason (e.g. all connections are in use and limits forbid creating more).
- `client_errc::cancelled` if `cancel` was called before the operation is started or while it is outstanding, or if the pool is not running.

###### Executor

This function will run entirely in the pool's executor (as given by `this->get_executor()`). No internal data will be accessed or modified as part of the initiating function. This simplifies thread-safety.

###### Thead-safety

When the pool is constructed with adequate executor configuration, this function is safe to be called concurrently with `async_run`, `cancel`, `~pooled_connection` and `pooled_connection::return_without_reset`.