boost/mysql/static_execution_state.hpp

0001 //
0002 // Copyright (c) 2019-2023 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
0003 //
0004 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0005 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0006 //
0007
0008 #ifndef BOOST_MYSQL_STATIC_EXECUTION_STATE_HPP
0009 #define BOOST_MYSQL_STATIC_EXECUTION_STATE_HPP
0010
0011 #include <boost/mysql/detail/config.hpp>
0012
0013 #ifdef BOOST_MYSQL_CXX14
0014
0015 #include <boost/mysql/metadata.hpp>
0016 #include <boost/mysql/metadata_collection_view.hpp>
0017 #include <boost/mysql/string_view.hpp>
0018
0019 #include <boost/mysql/detail/access.hpp>
0020 #include <boost/mysql/detail/execution_processor/static_execution_state_impl.hpp>
0021
0022 namespace boost {
0023 namespace mysql {
0024
0025 /**
0026  * \brief Holds state for multi-function SQL execution operations (static interface).
0027  * \details
0028  * This class behaves like a state machine. The current state can be accessed using
0029  * \ref should_start_op, \ref should_read_rows, \ref should_read_head
0030  * and \ref complete. They are mutually exclusive.
0031  * More states may be added in the future as more protocol features are implemented.
0032  * \n
0033  * Note that this class doesn't store rows anyhow. Row template parameters are
0034  * used to validate their compatibility with the data that will be returned by the server.
0035  *
0036  * \tparam StaticRow The row or row types that will be returned by the server.
0037  * There must be one for every resultset returned by the query, and always at least one.
0038  * All the passed types must fulfill the `StaticRow` concept.
0039  *
0040  * \par Thread safety
0041  * Distinct objects: safe. \n
0042  * Shared objects: unsafe.
0043  */
0044 template <class... StaticRow>
0045 class static_execution_state
0046 {
0047 public:
0048     /**
0049      * \brief Default constructor.
0050      * \details The constructed object is guaranteed to have
0051      * `should_start_op() == true`.
0052      *
0053      * \par Exception safety
0054      * No-throw guarantee.
0055      */
0056     static_execution_state() = default;
0057
0058     /**
0059      * \brief Copy constructor.
0060      * \par Exception safety
0061      * Strong guarantee. Internal allocations may throw.
0062      *
0063      * \par Object lifetimes
0064      * `*this` lifetime will be independent of `other`'s.
0065      */
0066     static_execution_state(const static_execution_state& other) = default;
0067
0068     /**
0069      * \brief Move constructor.
0070      * \par Exception safety
0071      * No-throw guarantee.
0072      *
0073      * \par Object lifetimes
0074      * Views obtained from `other` remain valid.
0075      */
0076     static_execution_state(static_execution_state&& other) = default;
0077
0078     /**
0079      * \brief Copy assignment.
0080      * \par Exception safety
0081      * Basic guarantee. Internal allocations may throw.
0082      *
0083      * \par Object lifetimes
0084      * `*this` lifetime will be independent of `other`'s. Views obtained from `*this`
0085      * are invalidated.
0086      */
0087     static_execution_state& operator=(const static_execution_state& other) = default;
0088
0089     /**
0090      * \brief Move assignment.
0091      * \par Exception safety
0092      * No-throw guarantee.
0093      *
0094      * \par Object lifetimes
0095      * Views obtained from `*this` are invalidated. Views obtained from `other` remain valid.
0096      */
0097     static_execution_state& operator=(static_execution_state&& other) = default;
0098
0099     /**
0100      * \brief Returns whether `*this` is in the initial state.
0101      * \details
0102      * Call \ref connection::start_execution or \ref connection::async_start_execution to move
0103      * forward. No data is available in this state.
0104      *
0105      * \par Exception safety
0106      * No-throw guarantee.
0107      */
0108     bool should_start_op() const noexcept { return impl_.get_interface().is_reading_first(); }
0109
0110     /**
0111      * \brief Returns whether the next operation should be read resultset head.
0112      * \details
0113      * Call \ref connection::read_resultset_head or its async counterpart to move forward.
0114      * Metadata and OK data for the previous resultset is available in this state.
0115      *
0116      * \par Exception safety
0117      * No-throw guarantee.
0118      */
0119     bool should_read_head() const noexcept { return impl_.get_interface().is_reading_first_subseq(); }
0120
0121     /**
0122      * \brief Returns whether the next operation should be read some rows.
0123      * \details
0124      * Call \ref connection::read_some_rows or its async counterpart to move forward.
0125      * Metadata for the current resultset is available in this state.
0126      *
0127      * \par Exception safety
0128      * No-throw guarantee.
0129      */
0130     bool should_read_rows() const noexcept { return impl_.get_interface().is_reading_rows(); }
0131
0132     /**
0133      * \brief Returns whether all the messages generated by this operation have been read.
0134      * \details
0135      * No further network calls are required to move forward. Metadata and OK data for the last
0136      * resultset are available in this state.
0137      *
0138      * \par Exception safety
0139      * No-throw guarantee.
0140      */
0141     bool complete() const noexcept { return impl_.get_interface().is_complete(); }
0142
0143     /**
0144      * \brief Returns metadata about the columns in the query.
0145      * \details
0146      * The returned collection will have as many \ref metadata objects as columns retrieved by
0147      * the SQL query, and in the same order. Note that this may not be the same order as in the `StaticRow`
0148      * type, since columns may be mapped by name or discarded. This function returns the representation that
0149      * was retrieved from the database.
0150      *
0151      * \par Exception safety
0152      * No-throw guarantee.
0153      *
0154      * \par Object lifetimes
0155      * This function returns a view object, with reference semantics. The returned view points into
0156      * memory owned by `*this`, and will be valid as long as `*this` or an object move-constructed
0157      * from `*this` are alive.
0158      */
0159     metadata_collection_view meta() const noexcept { return impl_.get_interface().meta(); }
0160
0161     /**
0162      * \brief Returns the number of rows affected by the SQL statement associated to this resultset.
0163      * \par Exception safety
0164      * No-throw guarantee.
0165      *
0166      * \par Preconditions
0167      * `this->complete() == true || this->should_read_head() == true`
0168      */
0169     std::uint64_t affected_rows() const noexcept { return impl_.get_interface().get_affected_rows(); }
0170
0171     /**
0172      * \brief Returns the last insert ID produced by the SQL statement associated to this resultset.
0173      * \par Exception safety
0174      * No-throw guarantee.
0175      *
0176      * \par Preconditions
0177      * `this->complete() == true || this->should_read_head() == true`
0178      */
0179     std::uint64_t last_insert_id() const noexcept { return impl_.get_interface().get_last_insert_id(); }
0180
0181     /**
0182      * \brief Returns the number of warnings produced by the SQL statement associated to this resultset.
0183      * \par Exception safety
0184      * No-throw guarantee.
0185      *
0186      * \par Preconditions
0187      * `this->complete() == true || this->should_read_head() == true`
0188      */
0189     unsigned warning_count() const noexcept { return impl_.get_interface().get_warning_count(); }
0190
0191     /**
0192      * \brief Returns additional text information about this resultset.
0193      * \details
0194      * The format of this information is documented by MySQL <a
0195      * href="https://dev.mysql.com/doc/c-api/8.0/en/mysql-info.html">here</a>.
0196      * \n
0197      * The returned string always uses ASCII encoding, regardless of the connection's character set.
0198      *
0199      * \par Exception safety
0200      * No-throw guarantee.
0201      *
0202      * \par Preconditions
0203      * `this->complete() == true || this->should_read_head() == true`
0204      *
0205      * \par Object lifetimes
0206      * This function returns a view object, with reference semantics. The returned view points into
0207      * memory owned by `*this`, and will be valid as long as `*this` or an object move-constructed
0208      * from `*this` are alive.
0209      */
0210     string_view info() const noexcept { return impl_.get_interface().get_info(); }
0211
0212     /**
0213      * \brief Returns whether the current resultset represents a procedure OUT params.
0214      * \par Preconditions
0215      * `this->complete() == true || this->should_read_head() == true`
0216      *
0217      * \par Exception safety
0218      * No-throw guarantee.
0219      */
0220     bool is_out_params() const noexcept { return impl_.get_interface().get_is_out_params(); }
0221
0222 private:
0223     detail::static_execution_state_impl<StaticRow...> impl_;
0224
0225     static_assert(sizeof...(StaticRow) > 0, "static_execution_state requires one row type, at least");
0226
0227 #ifndef BOOST_MYSQL_DOXYGEN
0228     friend struct detail::access;
0229 #endif
0230 };
0231
0232 }  // namespace mysql
0233 }  // namespace boost
0234
0235 #endif  // BOOST_MYSQL_CXX14
0236
0237 #endif