boost/asio/use_awaitable.hpp

0001 //
0002 // use_awaitable.hpp
0003 // ~~~~~~~~~~~~~~~~~
0004 //
0005 // Copyright (c) 2003-2023 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_USE_AWAITABLE_HPP
0012 #define BOOST_ASIO_USE_AWAITABLE_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
0020 #if defined(BOOST_ASIO_HAS_CO_AWAIT) || defined(GENERATING_DOCUMENTATION)
0021
0022 #include <boost/asio/awaitable.hpp>
0023 #include <boost/asio/detail/handler_tracking.hpp>
0024
0025 #if defined(BOOST_ASIO_ENABLE_HANDLER_TRACKING)
0026 # if defined(BOOST_ASIO_HAS_SOURCE_LOCATION)
0027 #  include <boost/asio/detail/source_location.hpp>
0028 # endif // defined(BOOST_ASIO_HAS_SOURCE_LOCATION)
0029 #endif // defined(BOOST_ASIO_ENABLE_HANDLER_TRACKING)
0030
0031 #include <boost/asio/detail/push_options.hpp>
0032
0033 namespace boost {
0034 namespace asio {
0035
0036 /// A @ref completion_token that represents the currently executing coroutine.
0037 /**
0038  * The @c use_awaitable_t class, with its value @c use_awaitable, is used to
0039  * represent the currently executing coroutine. This completion token may be
0040  * passed as a handler to an asynchronous operation. For example:
0041  *
0042  * @code awaitable<void> my_coroutine()
0043  * {
0044  *   std::size_t n = co_await my_socket.async_read_some(buffer, use_awaitable);
0045  *   ...
0046  * } @endcode
0047  *
0048  * When used with co_await, the initiating function (@c async_read_some in the
0049  * above example) suspends the current coroutine. The coroutine is resumed when
0050  * the asynchronous operation completes, and the result of the operation is
0051  * returned.
0052  */
0053 template <typename Executor = any_io_executor>
0054 struct use_awaitable_t
0055 {
0056   /// Default constructor.
0057   constexpr use_awaitable_t(
0058 #if defined(BOOST_ASIO_ENABLE_HANDLER_TRACKING)
0059 # if defined(BOOST_ASIO_HAS_SOURCE_LOCATION)
0060       detail::source_location location = detail::source_location::current()
0061 # endif // defined(BOOST_ASIO_HAS_SOURCE_LOCATION)
0062 #endif // defined(BOOST_ASIO_ENABLE_HANDLER_TRACKING)
0063     )
0064 #if defined(BOOST_ASIO_ENABLE_HANDLER_TRACKING)
0065 # if defined(BOOST_ASIO_HAS_SOURCE_LOCATION)
0066     : file_name_(location.file_name()),
0067       line_(location.line()),
0068       function_name_(location.function_name())
0069 # else // defined(BOOST_ASIO_HAS_SOURCE_LOCATION)
0070     : file_name_(0),
0071       line_(0),
0072       function_name_(0)
0073 # endif // defined(BOOST_ASIO_HAS_SOURCE_LOCATION)
0074 #endif // defined(BOOST_ASIO_ENABLE_HANDLER_TRACKING)
0075   {
0076   }
0077
0078   /// Constructor used to specify file name, line, and function name.
0079   constexpr use_awaitable_t(const char* file_name,
0080       int line, const char* function_name)
0081 #if defined(BOOST_ASIO_ENABLE_HANDLER_TRACKING)
0082     : file_name_(file_name),
0083       line_(line),
0084       function_name_(function_name)
0085 #endif // defined(BOOST_ASIO_ENABLE_HANDLER_TRACKING)
0086   {
0087 #if !defined(BOOST_ASIO_ENABLE_HANDLER_TRACKING)
0088     (void)file_name;
0089     (void)line;
0090     (void)function_name;
0091 #endif // !defined(BOOST_ASIO_ENABLE_HANDLER_TRACKING)
0092   }
0093
0094   /// Adapts an executor to add the @c use_awaitable_t completion token as the
0095   /// default.
0096   template <typename InnerExecutor>
0097   struct executor_with_default : InnerExecutor
0098   {
0099     /// Specify @c use_awaitable_t as the default completion token type.
0100     typedef use_awaitable_t default_completion_token_type;
0101
0102     /// Construct the adapted executor from the inner executor type.
0103     template <typename InnerExecutor1>
0104     executor_with_default(const InnerExecutor1& ex,
0105         constraint_t<
0106           conditional_t<
0107             !is_same<InnerExecutor1, executor_with_default>::value,
0108             is_convertible<InnerExecutor1, InnerExecutor>,
0109             false_type
0110           >::value
0111         > = 0) noexcept
0112       : InnerExecutor(ex)
0113     {
0114     }
0115   };
0116
0117   /// Type alias to adapt an I/O object to use @c use_awaitable_t as its
0118   /// default completion token type.
0119   template <typename T>
0120   using as_default_on_t = typename T::template rebind_executor<
0121       executor_with_default<typename T::executor_type>>::other;
0122
0123   /// Function helper to adapt an I/O object to use @c use_awaitable_t as its
0124   /// default completion token type.
0125   template <typename T>
0126   static typename decay_t<T>::template rebind_executor<
0127       executor_with_default<typename decay_t<T>::executor_type>
0128     >::other
0129   as_default_on(T&& object)
0130   {
0131     return typename decay_t<T>::template rebind_executor<
0132         executor_with_default<typename decay_t<T>::executor_type>
0133       >::other(static_cast<T&&>(object));
0134   }
0135
0136 #if defined(BOOST_ASIO_ENABLE_HANDLER_TRACKING)
0137   const char* file_name_;
0138   int line_;
0139   const char* function_name_;
0140 #endif // defined(BOOST_ASIO_ENABLE_HANDLER_TRACKING)
0141 };
0142
0143 /// A @ref completion_token object that represents the currently executing
0144 /// coroutine.
0145 /**
0146  * See the documentation for boost::asio::use_awaitable_t for a usage example.
0147  */
0148 #if defined(GENERATING_DOCUMENTATION)
0149 constexpr use_awaitable_t<> use_awaitable;
0150 #else
0151 constexpr use_awaitable_t<> use_awaitable(0, 0, 0);
0152 #endif
0153
0154 } // namespace asio
0155 } // namespace boost
0156
0157 #include <boost/asio/detail/pop_options.hpp>
0158
0159 #include <boost/asio/impl/use_awaitable.hpp>
0160
0161 #endif // defined(BOOST_ASIO_HAS_CO_AWAIT) || defined(GENERATING_DOCUMENTATION)
0162
0163 #endif // BOOST_ASIO_USE_AWAITABLE_HPP