boost/asio/use_awaitable.hpp

   1 //
   2 // use_awaitable.hpp
   3 // ~~~~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2019 Christopher M. Kohlhoff (chris at kohlhoff dot com)
   6 //
   7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
   8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   9 //
  10
  11 #ifndef BOOST_ASIO_USE_AWAITABLE_HPP
  12 #define BOOST_ASIO_USE_AWAITABLE_HPP
  13
  14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
  15 # pragma once
  16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
  17
  18 #include <boost/asio/detail/config.hpp>
  19
  20 #if defined(BOOST_ASIO_HAS_CO_AWAIT) || defined(GENERATING_DOCUMENTATION)
  21
  22 #include <boost/asio/awaitable.hpp>
  23
  24 #include <boost/asio/detail/push_options.hpp>
  25
  26 namespace boost {
  27 namespace asio {
  28
  29 /// A completion token that represents the currently executing coroutine.
  30 /**
  31  * The @c use_awaitable_t class, with its value @c use_awaitable, is used to
  32  * represent the currently executing coroutine. This completion token may be
  33  * passed as a handler to an asynchronous operation. For example:
  34  *
  35  * @code awaitable<void> my_coroutine()
  36  * {
  37  *   std::size_t n = co_await my_socket.async_read_some(buffer, use_awaitable);
  38  *   ...
  39  * } @endcode
  40  *
  41  * When used with co_await, the initiating function (@c async_read_some in the
  42  * above example) suspends the current coroutine. The coroutine is resumed when
  43  * the asynchronous operation completes, and the result of the operation is
  44  * returned.
  45  */
  46 template <typename Executor = executor>
  47 struct use_awaitable_t
  48 {
  49   /// Default constructor.
  50   BOOST_ASIO_CONSTEXPR use_awaitable_t()
  51   {
  52   }
  53
  54   /// Adapts an executor to add the @c use_awaitable_t completion token as the
  55   /// default.
  56   template <typename InnerExecutor>
  57   struct executor_with_default : InnerExecutor
  58   {
  59     /// Specify @c use_awaitable_t as the default completion token type.
  60     typedef use_awaitable_t default_completion_token_type;
  61
  62     /// Construct the adapted executor from the inner executor type.
  63     executor_with_default(const InnerExecutor& ex) BOOST_ASIO_NOEXCEPT
  64       : InnerExecutor(ex)
  65     {
  66     }
  67   };
  68
  69   /// Type alias to adapt an I/O object to use @c use_awaitable_t as its
  70   /// default completion token type.
  71 #if defined(BOOST_ASIO_HAS_ALIAS_TEMPLATES) \
  72   || defined(GENERATING_DOCUMENTATION)
  73   template <typename T>
  74   using as_default_on_t = typename T::template rebind_executor<
  75       executor_with_default<typename T::executor_type> >::other;
  76 #endif // defined(BOOST_ASIO_HAS_ALIAS_TEMPLATES)
  77        //   || defined(GENERATING_DOCUMENTATION)
  78
  79   /// Function helper to adapt an I/O object to use @c use_awaitable_t as its
  80   /// default completion token type.
  81   template <typename T>
  82   static typename T::template rebind_executor<
  83       executor_with_default<typename T::executor_type>
  84     >::other
  85   as_default_on(BOOST_ASIO_MOVE_ARG(T) object)
  86   {
  87     return typename as_default_on_t<typename decay<T>::type>::type(
  88         BOOST_ASIO_MOVE_CAST(T)(object));
  89   }
  90 };
  91
  92 /// A completion token object that represents the currently executing coroutine.
  93 /**
  94  * See the documentation for boost::asio::use_awaitable_t for a usage example.
  95  */
  96 #if defined(BOOST_ASIO_HAS_CONSTEXPR) || defined(GENERATING_DOCUMENTATION)
  97 constexpr use_awaitable_t<> use_awaitable;
  98 #elif defined(BOOST_ASIO_MSVC)
  99 __declspec(selectany) use_awaitable_t<> use_awaitable;
 100 #endif
 101
 102 } // namespace asio
 103 } // namespace boost
 104
 105 #include <boost/asio/detail/pop_options.hpp>
 106
 107 #include <boost/asio/impl/use_awaitable.hpp>
 108
 109 #endif // defined(BOOST_ASIO_HAS_CO_AWAIT) || defined(GENERATING_DOCUMENTATION)
 110
 111 #endif // BOOST_ASIO_USE_AWAITABLE_HPP