boost/asio/any_io_executor.hpp

0001 //
0002 // any_io_executor.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_ANY_IO_EXECUTOR_HPP
0012 #define BOOST_ASIO_ANY_IO_EXECUTOR_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 #if defined(BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT)
0020 # include <boost/asio/executor.hpp>
0021 #else // defined(BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT)
0022 # include <boost/asio/execution.hpp>
0023 # include <boost/asio/execution_context.hpp>
0024 #endif // defined(BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT)
0025
0026 #include <boost/asio/detail/push_options.hpp>
0027
0028 namespace boost {
0029 namespace asio {
0030
0031 #if defined(BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT)
0032
0033 typedef executor any_io_executor;
0034
0035 #else // defined(BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT)
0036
0037 /// Polymorphic executor type for use with I/O objects.
0038 /**
0039  * The @c any_io_executor type is a polymorphic executor that supports the set
0040  * of properties required by I/O objects. It is defined as the
0041  * execution::any_executor class template parameterised as follows:
0042  * @code execution::any_executor<
0043  *   execution::context_as_t<execution_context&>,
0044  *   execution::blocking_t::never_t,
0045  *   execution::prefer_only<execution::blocking_t::possibly_t>,
0046  *   execution::prefer_only<execution::outstanding_work_t::tracked_t>,
0047  *   execution::prefer_only<execution::outstanding_work_t::untracked_t>,
0048  *   execution::prefer_only<execution::relationship_t::fork_t>,
0049  *   execution::prefer_only<execution::relationship_t::continuation_t>
0050  * > @endcode
0051  */
0052 class any_io_executor :
0053 #if defined(GENERATING_DOCUMENTATION)
0054   public execution::any_executor<...>
0055 #else // defined(GENERATING_DOCUMENTATION)
0056   public execution::any_executor<
0057       execution::context_as_t<execution_context&>,
0058       execution::blocking_t::never_t,
0059       execution::prefer_only<execution::blocking_t::possibly_t>,
0060       execution::prefer_only<execution::outstanding_work_t::tracked_t>,
0061       execution::prefer_only<execution::outstanding_work_t::untracked_t>,
0062       execution::prefer_only<execution::relationship_t::fork_t>,
0063       execution::prefer_only<execution::relationship_t::continuation_t>
0064     >
0065 #endif // defined(GENERATING_DOCUMENTATION)
0066 {
0067 public:
0068 #if !defined(GENERATING_DOCUMENTATION)
0069   typedef execution::any_executor<
0070       execution::context_as_t<execution_context&>,
0071       execution::blocking_t::never_t,
0072       execution::prefer_only<execution::blocking_t::possibly_t>,
0073       execution::prefer_only<execution::outstanding_work_t::tracked_t>,
0074       execution::prefer_only<execution::outstanding_work_t::untracked_t>,
0075       execution::prefer_only<execution::relationship_t::fork_t>,
0076       execution::prefer_only<execution::relationship_t::continuation_t>
0077     > base_type;
0078
0079   typedef void supportable_properties_type(
0080       execution::context_as_t<execution_context&>,
0081       execution::blocking_t::never_t,
0082       execution::prefer_only<execution::blocking_t::possibly_t>,
0083       execution::prefer_only<execution::outstanding_work_t::tracked_t>,
0084       execution::prefer_only<execution::outstanding_work_t::untracked_t>,
0085       execution::prefer_only<execution::relationship_t::fork_t>,
0086       execution::prefer_only<execution::relationship_t::continuation_t>
0087     );
0088 #endif // !defined(GENERATING_DOCUMENTATION)
0089
0090   /// Default constructor.
0091   BOOST_ASIO_DECL any_io_executor() noexcept;
0092
0093   /// Construct in an empty state. Equivalent effects to default constructor.
0094   BOOST_ASIO_DECL any_io_executor(nullptr_t) noexcept;
0095
0096   /// Copy constructor.
0097   BOOST_ASIO_DECL any_io_executor(const any_io_executor& e) noexcept;
0098
0099   /// Move constructor.
0100   BOOST_ASIO_DECL any_io_executor(any_io_executor&& e) noexcept;
0101
0102   /// Construct to point to the same target as another any_executor.
0103 #if defined(GENERATING_DOCUMENTATION)
0104   template <class... OtherSupportableProperties>
0105     any_io_executor(execution::any_executor<OtherSupportableProperties...> e);
0106 #else // defined(GENERATING_DOCUMENTATION)
0107   template <typename OtherAnyExecutor>
0108   any_io_executor(OtherAnyExecutor e,
0109       constraint_t<
0110         conditional_t<
0111           !is_same<OtherAnyExecutor, any_io_executor>::value
0112             && is_base_of<execution::detail::any_executor_base,
0113               OtherAnyExecutor>::value,
0114           typename execution::detail::supportable_properties<
0115             0, supportable_properties_type>::template
0116               is_valid_target<OtherAnyExecutor>,
0117           false_type
0118         >::value
0119       > = 0)
0120     : base_type(static_cast<OtherAnyExecutor&&>(e))
0121   {
0122   }
0123 #endif // defined(GENERATING_DOCUMENTATION)
0124
0125   /// Construct to point to the same target as another any_executor.
0126 #if defined(GENERATING_DOCUMENTATION)
0127   template <class... OtherSupportableProperties>
0128     any_io_executor(std::nothrow_t,
0129       execution::any_executor<OtherSupportableProperties...> e);
0130 #else // defined(GENERATING_DOCUMENTATION)
0131   template <typename OtherAnyExecutor>
0132   any_io_executor(std::nothrow_t, OtherAnyExecutor e,
0133       constraint_t<
0134         conditional_t<
0135           !is_same<OtherAnyExecutor, any_io_executor>::value
0136             && is_base_of<execution::detail::any_executor_base,
0137               OtherAnyExecutor>::value,
0138           typename execution::detail::supportable_properties<
0139             0, supportable_properties_type>::template
0140               is_valid_target<OtherAnyExecutor>,
0141           false_type
0142         >::value
0143       > = 0) noexcept
0144     : base_type(std::nothrow, static_cast<OtherAnyExecutor&&>(e))
0145   {
0146   }
0147 #endif // defined(GENERATING_DOCUMENTATION)
0148
0149   /// Construct to point to the same target as another any_executor.
0150   BOOST_ASIO_DECL any_io_executor(std::nothrow_t,
0151       const any_io_executor& e) noexcept;
0152
0153   /// Construct to point to the same target as another any_executor.
0154   BOOST_ASIO_DECL any_io_executor(std::nothrow_t, any_io_executor&& e) noexcept;
0155
0156   /// Construct a polymorphic wrapper for the specified executor.
0157 #if defined(GENERATING_DOCUMENTATION)
0158   template <BOOST_ASIO_EXECUTION_EXECUTOR Executor>
0159   any_io_executor(Executor e);
0160 #else // defined(GENERATING_DOCUMENTATION)
0161   template <BOOST_ASIO_EXECUTION_EXECUTOR Executor>
0162   any_io_executor(Executor e,
0163       constraint_t<
0164         conditional_t<
0165           !is_same<Executor, any_io_executor>::value
0166             && !is_base_of<execution::detail::any_executor_base,
0167               Executor>::value,
0168           execution::detail::is_valid_target_executor<
0169             Executor, supportable_properties_type>,
0170           false_type
0171         >::value
0172       > = 0)
0173     : base_type(static_cast<Executor&&>(e))
0174   {
0175   }
0176 #endif // defined(GENERATING_DOCUMENTATION)
0177
0178   /// Construct a polymorphic wrapper for the specified executor.
0179 #if defined(GENERATING_DOCUMENTATION)
0180   template <BOOST_ASIO_EXECUTION_EXECUTOR Executor>
0181   any_io_executor(std::nothrow_t, Executor e);
0182 #else // defined(GENERATING_DOCUMENTATION)
0183   template <BOOST_ASIO_EXECUTION_EXECUTOR Executor>
0184   any_io_executor(std::nothrow_t, Executor e,
0185       constraint_t<
0186         conditional_t<
0187           !is_same<Executor, any_io_executor>::value
0188             && !is_base_of<execution::detail::any_executor_base,
0189               Executor>::value,
0190           execution::detail::is_valid_target_executor<
0191             Executor, supportable_properties_type>,
0192           false_type
0193         >::value
0194       > = 0) noexcept
0195     : base_type(std::nothrow, static_cast<Executor&&>(e))
0196   {
0197   }
0198 #endif // defined(GENERATING_DOCUMENTATION)
0199
0200   /// Assignment operator.
0201   BOOST_ASIO_DECL any_io_executor& operator=(
0202       const any_io_executor& e) noexcept;
0203
0204   /// Move assignment operator.
0205   BOOST_ASIO_DECL any_io_executor& operator=(any_io_executor&& e) noexcept;
0206
0207   /// Assignment operator that sets the polymorphic wrapper to the empty state.
0208   BOOST_ASIO_DECL any_io_executor& operator=(nullptr_t);
0209
0210   /// Destructor.
0211   BOOST_ASIO_DECL ~any_io_executor();
0212
0213   /// Swap targets with another polymorphic wrapper.
0214   BOOST_ASIO_DECL void swap(any_io_executor& other) noexcept;
0215
0216   /// Obtain a polymorphic wrapper with the specified property.
0217   /**
0218    * Do not call this function directly. It is intended for use with the
0219    * boost::asio::require and boost::asio::prefer customisation points.
0220    *
0221    * For example:
0222    * @code any_io_executor ex = ...;
0223    * auto ex2 = boost::asio::require(ex, execution::blocking.possibly); @endcode
0224    */
0225   template <typename Property>
0226   any_io_executor require(const Property& p,
0227       constraint_t<
0228         traits::require_member<const base_type&, const Property&>::is_valid
0229       > = 0) const
0230   {
0231     return static_cast<const base_type&>(*this).require(p);
0232   }
0233
0234   /// Obtain a polymorphic wrapper with the specified property.
0235   /**
0236    * Do not call this function directly. It is intended for use with the
0237    * boost::asio::prefer customisation point.
0238    *
0239    * For example:
0240    * @code any_io_executor ex = ...;
0241    * auto ex2 = boost::asio::prefer(ex, execution::blocking.possibly); @endcode
0242    */
0243   template <typename Property>
0244   any_io_executor prefer(const Property& p,
0245       constraint_t<
0246         traits::prefer_member<const base_type&, const Property&>::is_valid
0247       > = 0) const
0248   {
0249     return static_cast<const base_type&>(*this).prefer(p);
0250   }
0251 };
0252
0253 #if !defined(GENERATING_DOCUMENTATION)
0254
0255 template <>
0256 BOOST_ASIO_DECL any_io_executor any_io_executor::require(
0257     const execution::blocking_t::never_t&, int) const;
0258
0259 template <>
0260 BOOST_ASIO_DECL any_io_executor any_io_executor::prefer(
0261     const execution::blocking_t::possibly_t&, int) const;
0262
0263 template <>
0264 BOOST_ASIO_DECL any_io_executor any_io_executor::prefer(
0265     const execution::outstanding_work_t::tracked_t&, int) const;
0266
0267 template <>
0268 BOOST_ASIO_DECL any_io_executor any_io_executor::prefer(
0269     const execution::outstanding_work_t::untracked_t&, int) const;
0270
0271 template <>
0272 BOOST_ASIO_DECL any_io_executor any_io_executor::prefer(
0273     const execution::relationship_t::fork_t&, int) const;
0274
0275 template <>
0276 BOOST_ASIO_DECL any_io_executor any_io_executor::prefer(
0277     const execution::relationship_t::continuation_t&, int) const;
0278
0279 namespace traits {
0280
0281 #if !defined(BOOST_ASIO_HAS_DEDUCED_EQUALITY_COMPARABLE_TRAIT)
0282
0283 template <>
0284 struct equality_comparable<any_io_executor>
0285 {
0286   static const bool is_valid = true;
0287   static const bool is_noexcept = true;
0288 };
0289
0290 #endif // !defined(BOOST_ASIO_HAS_DEDUCED_EQUALITY_COMPARABLE_TRAIT)
0291
0292 #if !defined(BOOST_ASIO_HAS_DEDUCED_EXECUTE_MEMBER_TRAIT)
0293
0294 template <typename F>
0295 struct execute_member<any_io_executor, F>
0296 {
0297   static const bool is_valid = true;
0298   static const bool is_noexcept = false;
0299   typedef void result_type;
0300 };
0301
0302 #endif // !defined(BOOST_ASIO_HAS_DEDUCED_EXECUTE_MEMBER_TRAIT)
0303
0304 #if !defined(BOOST_ASIO_HAS_DEDUCED_QUERY_MEMBER_TRAIT)
0305
0306 template <typename Prop>
0307 struct query_member<any_io_executor, Prop> :
0308   query_member<any_io_executor::base_type, Prop>
0309 {
0310 };
0311
0312 #endif // !defined(BOOST_ASIO_HAS_DEDUCED_QUERY_MEMBER_TRAIT)
0313
0314 #if !defined(BOOST_ASIO_HAS_DEDUCED_REQUIRE_MEMBER_TRAIT)
0315
0316 template <typename Prop>
0317 struct require_member<any_io_executor, Prop> :
0318   require_member<any_io_executor::base_type, Prop>
0319 {
0320   typedef any_io_executor result_type;
0321 };
0322
0323 #endif // !defined(BOOST_ASIO_HAS_DEDUCED_REQUIRE_MEMBER_TRAIT)
0324
0325 #if !defined(BOOST_ASIO_HAS_DEDUCED_PREFER_MEMBER_TRAIT)
0326
0327 template <typename Prop>
0328 struct prefer_member<any_io_executor, Prop> :
0329   prefer_member<any_io_executor::base_type, Prop>
0330 {
0331   typedef any_io_executor result_type;
0332 };
0333
0334 #endif // !defined(BOOST_ASIO_HAS_DEDUCED_PREFER_MEMBER_TRAIT)
0335
0336 } // namespace traits
0337
0338 #endif // !defined(GENERATING_DOCUMENTATION)
0339
0340 #endif // defined(BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT)
0341
0342 } // namespace asio
0343 } // namespace boost
0344
0345 #include <boost/asio/detail/pop_options.hpp>
0346
0347 #if defined(BOOST_ASIO_HEADER_ONLY) \
0348   && !defined(BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT)
0349 # include <boost/asio/impl/any_io_executor.ipp>
0350 #endif // defined(BOOST_ASIO_HEADER_ONLY)
0351        //   && !defined(BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT)
0352
0353 #endif // BOOST_ASIO_ANY_IO_EXECUTOR_HPP