| Home | Libraries | People | FAQ | More

###### connection::async_start_execution (1 of 2 overloads)

Starts a SQL execution as a multi-function operation.

###### Synopsis

    template<
        class ExecutionRequest,
        class ExecutionStateType,
        class CompletionToken>
    auto
    async_start_execution(
        ExecutionRequest&& req,
        ExecutionStateType& st,
        CompletionToken&& token);

###### Description

Writes the execution request and reads the initial server response and the column metadata, but not the generated rows or subsequent resultsets, if any. `st` may be either an `execution_state` or `static_execution_state` object.

After this operation completes, `st` will have `execution_state::meta` populated. Metadata will be populated according to `this->meta_mode()`.

If the operation generated any rows or more than one resultset, these must be read (by using `read_some_rows` and `read_resultset_head`) before engaging in any further network operation. Otherwise, the results are undefined.

req may be either a type convertible to `string_view` containing valid SQL or a bound prepared statement, obtained by calling `statement::bind`. If a string, it must be encoded using the connection's character set. Any string parameters provided to `statement::bind` should also be encoded using the connection's character set.

When using the static interface, this function will detect schema mismatches for the first resultset. Further errors may be detected by `read_resultset_head` and `read_some_rows`.

###### Object lifetimes

If `CompletionToken` is a deferred completion token (e.g. `use_awaitable`), the caller is responsible for managing `req`'s validity following these rules:

- If `req` is `string_view`, the string pointed to by `req` must be kept alive by the caller until the operation is initiated.
- If `req` is a `bound_statement_tuple`, and any of the parameters is a reference type (like `string_view`), the caller must keep the values pointed by these references alive until the operation is initiated.
- If `req` is a `bound_statement_iterator_range`, the caller must keep objects in the iterator range passed to `statement::bind` alive until the operation is initiated.

###### Handler signature

The handler signature for this operation is `void(boost::mysql::error_code)`.

###### Executor

Intermediate completion handlers, as well as the final handler, are executed using `token`'s associated executor, or `this->get_executor()` if the token doesn't have an associated 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.