boost/mysql/any_address.hpp

0001 //
0002 // Copyright (c) 2019-2024 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_ANY_ADDRESS_HPP
0009 #define BOOST_MYSQL_ANY_ADDRESS_HPP
0010
0011 #include <boost/mysql/defaults.hpp>
0012 #include <boost/mysql/string_view.hpp>
0013
0014 #include <boost/mysql/detail/access.hpp>
0015
0016 #include <string>
0017
0018 namespace boost {
0019 namespace mysql {
0020
0021 /// (EXPERIMENTAL) The type of an address identifying a MySQL server.
0022 enum class address_type
0023 {
0024     /// An Internet hostname and a TCP port.
0025     host_and_port,
0026
0027     /// A UNIX domain socket path.
0028     unix_path
0029 };
0030
0031 /**
0032  * \brief (EXPERIMENTAL) A host and port identifying how to connect to a MySQL server.
0033  * \details
0034  * This is an owning type with value semantics.
0035  * \see any_address
0036  *
0037  * \par Experimental
0038  * This part of the API is experimental, and may change in successive
0039  * releases without previous notice.
0040  */
0041 struct host_and_port
0042 {
0043     /**
0044      * \brief The hostname where the MySQL server is expected to be listening.
0045      * \details
0046      * An empty string is equivalent to `localhost`. This is the default.
0047      * This is an owning field
0048      */
0049     std::string host;
0050
0051     /// The port where the MySQL server is expected to be listening.
0052     unsigned short port{default_port};
0053 };
0054
0055 /**
0056  * \brief (EXPERIMENTAL) Contains a UNIX-socket domain path.
0057  * \details
0058  * This type is defined in all systems, regardless of their UNIX socket support.
0059  * \n
0060  * This is an owning type with value semantics.
0061  * \see any_address
0062  */
0063 struct unix_path
0064 {
0065     /**
0066      * \brief The UNIX domain socket path where the MySQL server is listening.
0067      * \details Defaults to the empty string. This is an owning field.
0068      */
0069     std::string path;
0070 };
0071
0072 /**
0073  * \brief (EXPERIMENTAL) A server address, identifying how to physically connect to a MySQL server.
0074  * \details
0075  * A variant-like type that can represent the network address of a MySQL server,
0076  * regardless of the transport type being used. It can contain either a host
0077  * and port (to connect using TCP) or a UNIX path (to connect using UNIX domain sockets).
0078  * \n
0079  * This class may be extended in the future to accomodate Windows named pipes.
0080  * \n
0081  * This type has value semantics: it is owning and regular.
0082  */
0083 class any_address
0084 {
0085 #ifndef BOOST_MYSQL_DOXYGEN
0086     struct
0087     {
0088         address_type type;
0089         std::string address;
0090         unsigned short port;
0091     } impl_;
0092
0093     any_address(address_type t, std::string&& addr, unsigned short port) noexcept
0094         : impl_{t, std::move(addr), port}
0095     {
0096     }
0097     friend struct detail::access;
0098 #endif
0099
0100 public:
0101     /**
0102      * \brief Constructs an empty address.
0103      * \details Results in an address with `this->type() == address_type::host_and_port`,
0104      * `this->hostname() == ""` and `this->port() == default_port`, which identifies
0105      * a server running on `localhost` using the default port.
0106      * \par Exception safety
0107      * No-throw guarantee.
0108      */
0109     any_address() noexcept : any_address(address_type::host_and_port, std::string(), default_port) {}
0110
0111     /**
0112      * \brief Copy constructor.
0113      * \par Exception safety
0114      * Strong guarantee. Exceptions may be thrown by memory allocations.
0115      * \par Object lifetimes
0116      * `*this` and `other` will have independent lifetimes (regular value semantics).
0117      */
0118     any_address(const any_address& other) = default;
0119
0120     /**
0121      * \brief Move constructor.
0122      * \details Leaves `other` in a valid but unspecified state.
0123      * \par Exception safety
0124      * No-throw guarantee.
0125      */
0126     any_address(any_address&& other) = default;
0127
0128     /**
0129      * \brief Copy assignment.
0130      * \par Exception safety
0131      * Basic guarantee. Exceptions may be thrown by memory allocations.
0132      * \par Object lifetimes
0133      * `*this` and `other` will have independent lifetimes (regular value semantics).
0134      */
0135     any_address& operator=(const any_address& other) = default;
0136
0137     /**
0138      * \brief Move assignment.
0139      * \details Leaves `other` in a valid but unspecified state.
0140      * \par Exception safety
0141      * No-throw guarantee.
0142      */
0143     any_address& operator=(any_address&& other) = default;
0144
0145     /// Destructor.
0146     ~any_address() = default;
0147
0148     /**
0149      * \brief Constructs an address containing a host and a port.
0150      * \details Results in an address with `this->type() == address_type::host_and_port`,
0151      * `this->hostname() == value.hostname()` and `this->port() == value.port()`.
0152      *
0153      * \par Object lifetimes
0154      * `*this` and `value` will have independent lifetimes (regular value semantics).
0155      *
0156      * \par Exception safety
0157      * No-throw guarantee.
0158      */
0159     any_address(host_and_port value) noexcept
0160         : impl_{address_type::host_and_port, std::move(value.host), value.port}
0161     {
0162     }
0163
0164     /**
0165      * \brief Constructs an address containing a UNIX socket path.
0166      * \details Results in an address with `this->type() == address_type::unix_path`,
0167      * `this->unix_socket_path() == value.path()`.
0168      *
0169      * \par Object lifetimes
0170      * `*this` and `value` will have independent lifetimes (regular value semantics).
0171      *
0172      * \par Exception safety
0173      * No-throw guarantee.
0174      */
0175     any_address(unix_path value) noexcept : impl_{address_type::unix_path, std::move(value.path), 0} {}
0176
0177     /**
0178      * \brief Retrieves the type of address that this object contains.
0179      * \par Exception safety
0180      * No-throw guarantee.
0181      */
0182     address_type type() const noexcept { return impl_.type; }
0183
0184     /**
0185      * \brief Retrieves the hostname that this object contains.
0186      * \par Preconditions
0187      * `this->type() == address_type::host_and_port`
0188      *
0189      * \par Object lifetimes
0190      * The returned view points into `*this`, and is valid as long as `*this`
0191      * is alive and hasn't been assigned to or moved from.
0192      *
0193      * \par Exception safety
0194      * No-throw guarantee.
0195      */
0196     string_view hostname() const noexcept
0197     {
0198         BOOST_ASSERT(type() == address_type::host_and_port);
0199         return impl_.address;
0200     }
0201
0202     /**
0203      * \brief Retrieves the port that this object contains.
0204      * \par Preconditions
0205      * `this->type() == address_type::host_and_port`
0206      *
0207      * \par Exception safety
0208      * No-throw guarantee.
0209      */
0210     unsigned short port() const noexcept
0211     {
0212         BOOST_ASSERT(type() == address_type::host_and_port);
0213         return impl_.port;
0214     }
0215
0216     /**
0217      * \brief Retrieves the UNIX socket path that this object contains.
0218      * \par Preconditions
0219      * `this->type() == address_type::unix_path`
0220      *
0221      * \par Object lifetimes
0222      * The returned view points into `*this`, and is valid as long as `*this`
0223      * is alive and hasn't been assigned to or moved from.
0224      *
0225      * \par Exception safety
0226      * No-throw guarantee.
0227      */
0228     string_view unix_socket_path() const noexcept
0229     {
0230         BOOST_ASSERT(type() == address_type::unix_path);
0231         return impl_.address;
0232     }
0233
0234     /**
0235      * \brief Replaces the current object with a host and port.
0236      * \details
0237      * Destroys the current contained object and constructs a new
0238      * host and port from the passed components. This function can
0239      * change the underlying type of object held by `*this`.
0240      * \n
0241      * The constructed object has `this->type() == address_type::host_and_port`,
0242      * `this->hostname() == hostname` and `this->port() == port`.
0243      * \n
0244      * An empty hostname is equivalent to `localhost`.
0245      * \n
0246      * \par Exception safety
0247      * Basic guarantee. Memory allocations may throw.
0248      * \par Object lifetimes
0249      * Invalidates views pointing into `*this`.
0250      */
0251     void emplace_host_and_port(std::string hostname, unsigned short port = default_port)
0252     {
0253         impl_.type = address_type::host_and_port;
0254         impl_.address = std::move(hostname);
0255         impl_.port = port;
0256     }
0257
0258     /**
0259      * \brief Replaces the current object with a UNIX socket path.
0260      * \details
0261      * Destroys the current contained object and constructs a new
0262      * UNIX socket path from the passed value. This function can
0263      * change the underlying type of object held by `*this`.
0264      * \n
0265      * The constructed object has `this->type() == address_type::unix_path` and
0266      * `this->unix_socket_path() == path`.
0267      * \n
0268      * \par Exception safety
0269      * Basic guarantee. Memory allocations may throw.
0270      * \par Object lifetimes
0271      * Invalidates views pointing into `*this`.
0272      */
0273     void emplace_unix_path(std::string path)
0274     {
0275         impl_.type = address_type::unix_path;
0276         impl_.address = std::move(path);
0277         impl_.port = 0;
0278     }
0279
0280     /**
0281      * \brief Tests for equality.
0282      * \details Two addresses are equal if they have the same type and individual components.
0283      * \par Exception safety
0284      * No-throw guarantee.
0285      */
0286     bool operator==(const any_address& rhs) const noexcept
0287     {
0288         return impl_.type == rhs.impl_.type && impl_.address == rhs.impl_.address &&
0289                impl_.port == rhs.impl_.port;
0290     }
0291
0292     /**
0293      * \brief Tests for inequality.
0294      * \par Exception safety
0295      * No-throw guarantee.
0296      */
0297     bool operator!=(const any_address& rhs) const noexcept { return !(*this == rhs); }
0298 };
0299
0300 }  // namespace mysql
0301 }  // namespace boost
0302
0303 #endif