EIC code displayed by LXR master/​include/​boost/​mysql/​pipeline.hpp	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

Warning, file /include/boost/mysql/pipeline.hpp was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

 //
 // 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

This page was automatically generated by the 2.3.7 LXR engine. The LXR team