//
// Copyright (c) 2019-2024 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
//
#ifndef BOOST_MYSQL_PIPELINE_HPP
#define BOOST_MYSQL_PIPELINE_HPP
#include <boost/mysql/character_set.hpp>
#include <boost/mysql/diagnostics.hpp>
#include <boost/mysql/error_code.hpp>
#include <boost/mysql/field_view.hpp>
#include <boost/mysql/results.hpp>
#include <boost/mysql/statement.hpp>
#include <boost/mysql/string_view.hpp>
#include <boost/mysql/detail/access.hpp>
#include <boost/mysql/detail/config.hpp>
#include <boost/mysql/detail/execution_processor/execution_processor.hpp>
#include <boost/mysql/detail/pipeline.hpp>
#include <boost/mysql/detail/writable_field_traits.hpp>
#include <boost/assert.hpp>
#include <boost/core/span.hpp>
#include <boost/variant2/variant.hpp>
#include <array>
#include <cstdint>
#include <utility>
#include <vector>
namespace boost {
namespace mysql {
/**
* \brief (EXPERIMENTAL) A variant-like type holding the response of a single pipeline stage.
* \details
* This is a variant-like type, similar to `boost::system::result`. At any point in time,
* it can contain: \n
* \li A \ref statement. Will happen if the stage was a prepare statement that succeeded.
* \li A \ref results. Will happen if the stage was a query or statement execution that succeeded.
* \li An \ref error_code, \ref diagnostics pair. Will happen if the stage failed, or if it succeeded but
* it doesn't yield a value (as in close statement, reset connection and set character set).
*
* \par Experimental
* This part of the API is experimental, and may change in successive
* releases without previous notice.
*/
class stage_response
{
#ifndef BOOST_MYSQL_DOXYGEN
struct errcode_with_diagnostics
{
error_code ec;
diagnostics diag;
};
struct
{
variant2::variant<errcode_with_diagnostics, statement, results> value;
void emplace_results() { value.emplace<results>(); }
void emplace_error() { value.emplace<errcode_with_diagnostics>(); }
detail::execution_processor& get_processor()
{
return detail::access::get_impl(variant2::unsafe_get<2>(value));
}
void set_result(statement s) { value = s; }
void set_error(error_code ec, diagnostics&& diag)
{
value.emplace<0>(errcode_with_diagnostics{ec, std::move(diag)});
}
} impl_;
friend struct detail::access;
#endif
bool has_error() const { return impl_.value.index() == 0u; }
BOOST_MYSQL_DECL
void check_has_results() const;
public:
/**
* \brief Default constructor.
* \details
* Constructs an object containing an empty error code and diagnostics.
*
* \par Exception safety
* No-throw guarantee.
*/
stage_response() = default;
/**
* \brief Returns true if the object contains a statement.
*
* \par Exception safety
* No-throw guarantee.
*/
bool has_statement() const noexcept { return impl_.value.index() == 1u; }
/**
* \brief Returns true if the object contains a results.
*
* \par Exception safety
* No-throw guarantee.
*/
bool has_results() const noexcept { return impl_.value.index() == 2u; }
/**
* \brief Retrieves the contained error code.
* \details
* If `*this` contains an error, retrieves it.
* Otherwise (if `this->has_statement() || this->has_results()`),
* returns an empty (default-constructed) error code.
*
* \par Exception safety
* No-throw guarantee.
*/
error_code error() const noexcept
{
return has_error() ? variant2::unsafe_get<0>(impl_.value).ec : error_code();
}
/**
* \brief Retrieves the contained diagnostics (lvalue reference accessor).
* \details
* If `*this` contains an error, retrieves the associated diagnostic information
* by copying it.
* Otherwise (if `this->has_statement() || this->has_results()`),
* returns an empty diagnostics object.
*
* \par Exception safety
* Strong guarantee: memory allocations may throw.
*/
diagnostics diag() const&
{
return has_error() ? variant2::unsafe_get<0>(impl_.value).diag : diagnostics();
}
/**
* \brief Retrieves the contained diagnostics (rvalue reference accessor).
* \details
* If `*this` contains an error, retrieves the associated diagnostic information
* by moving it.
* Otherwise (if `this->has_statement() || this->has_results()`),
* returns an empty (default-constructed) error.
*
* \par Exception safety
* No-throw guarantee.
*/
diagnostics diag() && noexcept
{
return has_error() ? variant2::unsafe_get<0>(std::move(impl_.value)).diag : diagnostics();
}
/**
* \brief Retrieves the contained statement or throws an exception.
* \details
* If `*this` contains an statement (`this->has_statement() == true`),
* retrieves it. Otherwise, throws an exception.
*
* \par Exception safety
* Strong guarantee. Throws on invalid input.
* \throws std::invalid_argument If `*this` does not contain a statement.
*/
BOOST_MYSQL_DECL
statement as_statement() const;
/**
* \brief Retrieves the contained statement (unchecked accessor).
* \details
* If `*this` contains an statement,
* retrieves it. Otherwise, the behavior is undefined.
*
* \par Preconditions
* `this->has_statement() == true`
*
* \par Exception safety
* No-throw guarantee.
*/
statement get_statement() const noexcept
{
BOOST_ASSERT(has_statement());
return variant2::unsafe_get<1>(impl_.value);
}
/**
* \brief Retrieves the contained results or throws an exception.
* \details
* If `*this` contains a `results` object (`this->has_results() == true`),
* retrieves a reference to it. Otherwise, throws an exception.
*
* \par Exception safety
* Strong guarantee. Throws on invalid input.
* \throws std::invalid_argument If `this->has_results() == false`
*
* \par Object lifetimes
* The returned reference is valid as long as `*this` is alive
* and hasn't been assigned to.
*/
const results& as_results() const&
{
check_has_results();
return variant2::unsafe_get<2>(impl_.value);
}
/// \copydoc as_results
results&& as_results() &&
{
check_has_results();
return variant2::unsafe_get<2>(std::move(impl_.value));
}
/**
* \brief Retrieves the contained results (unchecked accessor).
* \details
* If `*this` contains a `results` object, retrieves a reference to it.
* Otherwise, the behavior is undefined.
*
* \par Preconditions
* `this->has_results() == true`
*
* \par Exception safety
* No-throw guarantee.
*
* \par Object lifetimes
* The returned reference is valid as long as `*this` is alive
* and hasn't been assigned to.
*/
const results& get_results() const& noexcept
{
BOOST_ASSERT(has_results());
return variant2::unsafe_get<2>(impl_.value);
}
/// \copydoc get_results
results&& get_results() && noexcept
{
BOOST_ASSERT(has_results());
return variant2::unsafe_get<2>(std::move(impl_.value));
}
};
/**
* \brief (EXPERIMENTAL) A pipeline request.
* \details
* Contains a collection of pipeline stages, fully describing the work to be performed
* by a pipeline operation.
* Call any of the `add_xxx` functions to append new stages to the request.
*
* \par Experimental
* This part of the API is experimental, and may change in successive
* releases without previous notice.
*/
class pipeline_request
{
#ifndef BOOST_MYSQL_DOXYGEN
struct impl_t
{
std::vector<std::uint8_t> buffer_;
std::vector<detail::pipeline_request_stage> stages_;
} impl_;
friend struct detail::access;
#endif
public:
/**
* \brief Default constructor.
* \details Constructs an empty pipeline request, with no stages.
*
* \par Exception safety
* No-throw guarantee.
*/
pipeline_request() = default;
/**
* \brief Adds a stage that executes a text query.
* \details
* Creates a stage that will run `query` as a SQL query,
* like \ref any_connection::execute.
*
* \par Exception safety
* Strong guarantee. Memory allocations may throw.
*
* \par Object lifetimes
* query is copied into the request and need not be kept alive after this function returns.
*/
BOOST_MYSQL_DECL
pipeline_request& add_execute(string_view query);
/**
* \brief Adds a stage that executes a prepared statement.
* \details
* Creates a stage that runs
* `stmt` bound to any parameters passed in `params`, like \ref any_connection::execute
* and \ref statement::bind. For example, `add_execute(stmt, 42, "John")` has
* effects equivalent to `conn.execute(stmt.bind(42, "John"))`.
*
* \par Exception safety
* Strong guarantee. Throws if the supplied number of parameters doesn't match the number
* of parameters expected by the statement. Additionally, memory allocations may throw.
* \throws std::invalid_argument If `sizeof...(params) != stmt.num_params()`
*
* \par Preconditions
* The passed statement should be valid (`stmt.valid() == true`).
*
* \par Object lifetimes
* Any objects pointed to by `params` are copied into the request and
* need not be kept alive after this function returns.
*
* \par Type requirements
* Any type satisfying `WritableField` can be used as a parameter.
* This includes all types that can be used with \ref statement::bind,
* including scalar types, strings, blobs and optionals.
*/
template <BOOST_MYSQL_WRITABLE_FIELD... WritableField>
pipeline_request& add_execute(statement stmt, const WritableField&... params)
{
std::array<field_view, sizeof...(WritableField)> params_arr{{detail::to_field(params)...}};
return add_execute_range(stmt, params_arr);
}
/**
* \brief Adds a stage that executes a prepared statement.
* \details
* Creates a stage that runs
* `stmt` bound to any parameters passed in `params`, like \ref any_connection::execute
* and \ref statement::bind. For example, `add_execute_range(stmt, params)` has
* effects equivalent to `conn.execute(stmt.bind(params.begin(), params.end()))`.
* \n
* This function can be used instead of \ref add_execute when the number of actual parameters
* of a statement is not known at compile time.
*
* \par Exception safety
* Strong guarantee. Throws if the supplied number of parameters doesn't match the number
* of parameters expected by the statement. Additionally, memory allocations may throw.
* \throws std::invalid_argument If `params.size() != stmt.num_params()`
*
* \par Preconditions
* The passed statement should be valid (`stmt.valid() == true`).
*
* \par Object lifetimes
* The `params` range is copied into the request and
* needs not be kept alive after this function returns.
*/
BOOST_MYSQL_DECL
pipeline_request& add_execute_range(statement stmt, span<const field_view> params);
/**
* \brief Adds a prepare statement stage.
* \details
* Creates a stage that prepares a statement server-side. The resulting
* stage has effects equivalent to `conn.prepare_statement(stmt_sql)`.
*
* \par Exception safety
* Strong guarantee. Memory allocations may throw.
*
* \par Object lifetimes
* stmt_sql is copied into the request and need not be kept alive after this function returns.
*/
BOOST_MYSQL_DECL
pipeline_request& add_prepare_statement(string_view stmt_sql);
/**
* \brief Adds a close statement stage.
* \details
* Creates a stage that closes a prepared statement. The resulting
* stage has effects equivalent to `conn.close_statement(stmt)`.
*
* \par Exception safety
* Strong guarantee. Memory allocations may throw.
*
* \par Preconditions
* The passed statement should be valid (`stmt.valid() == true`).
*/
BOOST_MYSQL_DECL pipeline_request& add_close_statement(statement stmt);
/**
* \brief Adds a reset connection stage.
* \details
* Creates a stage that resets server-side session state. The resulting
* stage has effects equivalent to `conn.reset_connection()`.
*
* \par Exception safety
* Strong guarantee. Memory allocations may throw.
*/
BOOST_MYSQL_DECL pipeline_request& add_reset_connection();
/**
* \brief Adds a set character set stage.
* \details
* Creates a stage that sets the connection's character set.
* The resulting stage has effects equivalent to `conn.set_character_set(charset)`.
*
* \par Exception safety
* Strong guarantee. Throws if the supplied character set name is not valid
* (i.e. `charset.name` contains non-ASCII characters).
* The check is performed as a hardening measure, and never happens with
* the character sets provided by this library.
*
* Additionally, memory allocations may throw.
* \throws std::invalid_argument If `charset.name` contains non-ASCII characters.
*
* \par Preconditions
* The passed character set should not be default-constructed
* (`charset.name != nullptr`).
*/
BOOST_MYSQL_DECL pipeline_request& add_set_character_set(character_set charset);
/**
* \brief Removes all stages in the pipeline request, making the object empty again.
* \details
* Can be used to re-use a single request object for multiple pipeline operations.
*
* \par Exception safety
* No-throw guarantee.
*/
void clear() noexcept
{
impl_.buffer_.clear();
impl_.stages_.clear();
}
};
} // namespace mysql
} // namespace boost
#ifdef BOOST_MYSQL_HEADER_ONLY
#include <boost/mysql/impl/pipeline.ipp>
#endif
#endif