boost/asio/disposition.hpp

0001 //
0002 // disposition.hpp
0003 // ~~~~~~~~~~~~~~~
0004 //
0005 // Copyright (c) 2003-2025 Christopher M. Kohlhoff (chris at kohlhoff dot com)
0006 //
0007 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0008 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0009 //
0010
0011 #ifndef BOOST_ASIO_DISPOSITION_HPP
0012 #define BOOST_ASIO_DISPOSITION_HPP
0013
0014 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
0015 # pragma once
0016 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
0017
0018 #include <boost/asio/detail/config.hpp>
0019 #include <boost/asio/detail/throw_exception.hpp>
0020 #include <boost/asio/detail/type_traits.hpp>
0021 #include <boost/system/error_code.hpp>
0022 #include <boost/system/system_error.hpp>
0023 #include <exception>
0024
0025 #include <boost/asio/detail/push_options.hpp>
0026
0027 namespace boost {
0028 namespace asio {
0029
0030 /// Traits type to adapt arbitrary error types as dispositions.
0031 /**
0032  * This type may be specialised for user-defined types, to allow them to be
0033  * treated as a disposition by asio.
0034  *
0035  * The primary trait is not defined.
0036  */
0037 #if defined(GENERATING_DOCUMENTATION)
0038 template <typename T>
0039 struct disposition_traits
0040 {
0041   /// Determine whether a disposition represents no error.
0042   static bool not_an_error(const T& d) noexcept;
0043
0044   /// Throw an exception if the disposition represents an error.
0045   static void throw_exception(T d);
0046
0047   /// Convert a disposition into an @c exception_ptr.
0048   static std::exception_ptr to_exception_ptr(T d) noexcept;
0049 };
0050 #else // defined(GENERATING_DOCUMENTATION)
0051 template <typename T>
0052 struct disposition_traits;
0053 #endif // defined(GENERATING_DOCUMENTATION)
0054
0055 namespace detail {
0056
0057 template <typename T, typename = void, typename = void,
0058   typename = void, typename = void, typename = void, typename = void>
0059 struct is_disposition_impl : false_type
0060 {
0061 };
0062
0063 template <typename T>
0064 struct is_disposition_impl<T,
0065   enable_if_t<
0066     is_nothrow_default_constructible<T>::value
0067   >,
0068   enable_if_t<
0069     is_nothrow_move_constructible<T>::value
0070   >,
0071   enable_if_t<
0072     is_nothrow_move_assignable<T>::value
0073   >,
0074   enable_if_t<
0075     is_same<
0076       decltype(disposition_traits<T>::not_an_error(declval<const T&>())),
0077       bool
0078     >::value
0079   >,
0080   void_t<
0081     decltype(disposition_traits<T>::throw_exception(declval<T>()))
0082   >,
0083   enable_if_t<
0084     is_same<
0085       decltype(disposition_traits<T>::to_exception_ptr(declval<T>())),
0086       std::exception_ptr
0087     >::value
0088   >> : true_type
0089 {
0090 };
0091
0092 } // namespace detail
0093
0094 /// Trait used for testing whether a type satisfies the requirements of a
0095 /// disposition.
0096 /**
0097  * To be a valid disposition, a type must be nothrow default-constructible,
0098  * nothrow move-constructible, nothrow move-assignable, and there must be a
0099  * specialisation of the disposition_traits template for the type that provides
0100  * the following static member functions:
0101  * @li @c not_an_error: Takes an argument of type <tt>const T&</tt> and returns
0102  *     a @c bool.
0103  * @li @c throw_exception: Takes an argument of type <tt>T</tt>. The
0104  *     caller of this function must not pass a disposition value for which
0105  *     @c not_an_error returns true. This function must not return.
0106  * @li @c to_exception_ptr: Takes an argument of type <tt>T</tt> and returns a
0107  *     value of type @c std::exception_ptr.
0108  */
0109 template <typename T>
0110 struct is_disposition :
0111 #if defined(GENERATING_DOCUMENTATION)
0112   integral_constant<bool, automatically_determined>
0113 #else // defined(GENERATING_DOCUMENTATION)
0114   detail::is_disposition_impl<T>
0115 #endif // defined(GENERATING_DOCUMENTATION)
0116 {
0117 };
0118
0119 #if defined(BOOST_ASIO_HAS_VARIABLE_TEMPLATES)
0120
0121 template <typename T>
0122 constexpr const bool is_disposition_v = is_disposition<T>::value;
0123
0124 #endif // defined(BOOST_ASIO_HAS_VARIABLE_TEMPLATES)
0125
0126 #if defined(BOOST_ASIO_HAS_CONCEPTS)
0127
0128 template <typename T>
0129 BOOST_ASIO_CONCEPT disposition = is_disposition<T>::value;
0130
0131 #define BOOST_ASIO_DISPOSITION ::boost::asio::disposition
0132
0133 #else // defined(BOOST_ASIO_HAS_CONCEPTS)
0134
0135 #define BOOST_ASIO_DISPOSITION typename
0136
0137 #endif // defined(BOOST_ASIO_HAS_CONCEPTS)
0138
0139 /// Specialisation of @c disposition_traits for @c error_code.
0140 template <>
0141 struct disposition_traits<boost::system::error_code>
0142 {
0143   static bool not_an_error(const boost::system::error_code& ec) noexcept
0144   {
0145     return !ec;
0146   }
0147
0148   static void throw_exception(const boost::system::error_code& ec)
0149   {
0150     detail::throw_exception(boost::system::system_error(ec));
0151   }
0152
0153   static std::exception_ptr to_exception_ptr(
0154       const boost::system::error_code& ec) noexcept
0155   {
0156     return ec
0157       ? std::make_exception_ptr(boost::system::system_error(ec))
0158       : nullptr;
0159   }
0160 };
0161
0162 /// Specialisation of @c disposition_traits for @c std::exception_ptr.
0163 template <>
0164 struct disposition_traits<std::exception_ptr>
0165 {
0166   static bool not_an_error(const std::exception_ptr& e) noexcept
0167   {
0168     return !e;
0169   }
0170
0171   static void throw_exception(std::exception_ptr e)
0172   {
0173     std::rethrow_exception(static_cast<std::exception_ptr&&>(e));
0174   }
0175
0176   static std::exception_ptr to_exception_ptr(std::exception_ptr e) noexcept
0177   {
0178     return e;
0179   }
0180 };
0181
0182 /// A tag type used to indicate the absence of an error.
0183 struct no_error_t
0184 {
0185   /// Default constructor.
0186   constexpr no_error_t()
0187   {
0188   }
0189
0190   /// Equality operator.
0191   friend constexpr bool operator==(
0192       const no_error_t&, const no_error_t&) noexcept
0193   {
0194     return true;
0195   }
0196
0197   /// Inequality operator.
0198   friend constexpr bool operator!=(
0199       const no_error_t&, const no_error_t&) noexcept
0200   {
0201     return false;
0202   }
0203
0204   /// Equality operator, returns true if the disposition does not contain an
0205   /// error.
0206   template <BOOST_ASIO_DISPOSITION Disposition>
0207   friend constexpr constraint_t<is_disposition<Disposition>::value, bool>
0208   operator==(const no_error_t&, const Disposition& d) noexcept
0209   {
0210     return disposition_traits<Disposition>::not_an_error(d);
0211   }
0212
0213   /// Equality operator, returns true if the disposition does not contain an
0214   /// error.
0215   template <BOOST_ASIO_DISPOSITION Disposition>
0216   friend constexpr constraint_t<is_disposition<Disposition>::value, bool>
0217   operator==(const Disposition& d, const no_error_t&) noexcept
0218   {
0219     return disposition_traits<Disposition>::not_an_error(d);
0220   }
0221
0222   /// Inequality operator, returns true if the disposition contains an error.
0223   template <BOOST_ASIO_DISPOSITION Disposition>
0224   friend constexpr constraint_t<is_disposition<Disposition>::value, bool>
0225   operator!=(const no_error_t&, const Disposition& d) noexcept
0226   {
0227     return !disposition_traits<Disposition>::not_an_error(d);
0228   }
0229
0230   /// Inequality operator, returns true if the disposition contains an error.
0231   template <BOOST_ASIO_DISPOSITION Disposition>
0232   friend constexpr constraint_t<is_disposition<Disposition>::value, bool>
0233   operator!=(const Disposition& d, const no_error_t&) noexcept
0234   {
0235     return !disposition_traits<Disposition>::not_an_error(d);
0236   }
0237 };
0238
0239 /// A special value used to indicate the absence of an error.
0240 BOOST_ASIO_INLINE_VARIABLE constexpr no_error_t no_error;
0241
0242 /// Specialisation of @c disposition_traits for @c no_error_t.
0243 template <>
0244 struct disposition_traits<no_error_t>
0245 {
0246   static bool not_an_error(no_error_t) noexcept
0247   {
0248     return true;
0249   }
0250
0251   static void throw_exception(no_error_t)
0252   {
0253   }
0254
0255   static std::exception_ptr to_exception_ptr(no_error_t) noexcept
0256   {
0257     return std::exception_ptr();
0258   }
0259 };
0260
0261 /// Helper function to throw an exception arising from a disposition.
0262 template <typename Disposition>
0263 inline void throw_exception(Disposition&& d,
0264     constraint_t<is_disposition<decay_t<Disposition>>::value> = 0)
0265 {
0266   disposition_traits<decay_t<Disposition>>::throw_exception(
0267       static_cast<Disposition&&>(d));
0268 }
0269
0270 /// Helper function to convert a disposition to an @c exception_ptr.
0271 template <typename Disposition>
0272 inline std::exception_ptr to_exception_ptr(Disposition&& d,
0273     constraint_t<is_disposition<decay_t<Disposition>>::value> = 0) noexcept
0274 {
0275   return disposition_traits<decay_t<Disposition>>::to_exception_ptr(
0276       static_cast<Disposition&&>(d));
0277 }
0278
0279 } // namespace asio
0280 } // namespace boost
0281
0282 #include <boost/asio/detail/pop_options.hpp>
0283
0284 #endif // BOOST_ASIO_DISPOSITION_HPP