ceph/src/boost/boost/asio/spawn.hpp

   1 //
   2 // spawn.hpp
   3 // ~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2022 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_SPAWN_HPP
  12 #define BOOST_ASIO_SPAWN_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 #include <boost/coroutine/all.hpp>
  20 #include <boost/asio/any_io_executor.hpp>
  21 #include <boost/asio/bind_executor.hpp>
  22 #include <boost/asio/detail/memory.hpp>
  23 #include <boost/asio/detail/type_traits.hpp>
  24 #include <boost/asio/detail/wrapped_handler.hpp>
  25 #include <boost/asio/io_context.hpp>
  26 #include <boost/asio/is_executor.hpp>
  27 #include <boost/asio/strand.hpp>
  28
  29 #include <boost/asio/detail/push_options.hpp>
  30
  31 namespace boost {
  32 namespace asio {
  33
  34 /// A @ref completion_token that represents the currently executing coroutine.
  35 /**
  36  * The basic_yield_context class is a completion token type that is used to
  37  * represent the currently executing stackful coroutine. A basic_yield_context
  38  * object may be passed as a completion token to an asynchronous operation. For
  39  * example:
  40  *
  41  * @code template <typename Handler>
  42  * void my_coroutine(basic_yield_context<Handler> yield)
  43  * {
  44  *   ...
  45  *   std::size_t n = my_socket.async_read_some(buffer, yield);
  46  *   ...
  47  * } @endcode
  48  *
  49  * The initiating function (async_read_some in the above example) suspends the
  50  * current coroutine. The coroutine is resumed when the asynchronous operation
  51  * completes, and the result of the operation is returned.
  52  */
  53 template <typename Handler>
  54 class basic_yield_context
  55 {
  56 public:
  57   /// The coroutine callee type, used by the implementation.
  58   /**
  59    * When using Boost.Coroutine v1, this type is:
  60    * @code typename coroutine<void()> @endcode
  61    * When using Boost.Coroutine v2 (unidirectional coroutines), this type is:
  62    * @code push_coroutine<void> @endcode
  63    */
  64 #if defined(GENERATING_DOCUMENTATION)
  65   typedef implementation_defined callee_type;
  66 #elif defined(BOOST_COROUTINES_UNIDIRECT) || defined(BOOST_COROUTINES_V2)
  67   typedef boost::coroutines::push_coroutine<void> callee_type;
  68 #else
  69   typedef boost::coroutines::coroutine<void()> callee_type;
  70 #endif
  71
  72   /// The coroutine caller type, used by the implementation.
  73   /**
  74    * When using Boost.Coroutine v1, this type is:
  75    * @code typename coroutine<void()>::caller_type @endcode
  76    * When using Boost.Coroutine v2 (unidirectional coroutines), this type is:
  77    * @code pull_coroutine<void> @endcode
  78    */
  79 #if defined(GENERATING_DOCUMENTATION)
  80   typedef implementation_defined caller_type;
  81 #elif defined(BOOST_COROUTINES_UNIDIRECT) || defined(BOOST_COROUTINES_V2)
  82   typedef boost::coroutines::pull_coroutine<void> caller_type;
  83 #else
  84   typedef boost::coroutines::coroutine<void()>::caller_type caller_type;
  85 #endif
  86
  87   /// Construct a yield context to represent the specified coroutine.
  88   /**
  89    * Most applications do not need to use this constructor. Instead, the
  90    * spawn() function passes a yield context as an argument to the coroutine
  91    * function.
  92    */
  93   basic_yield_context(
  94       const detail::weak_ptr<callee_type>& coro,
  95       caller_type& ca, Handler& handler)
  96     : coro_(coro),
  97       ca_(ca),
  98       handler_(handler),
  99       ec_(0)
 100   {
 101   }
 102
 103   /// Construct a yield context from another yield context type.
 104   /**
 105    * Requires that OtherHandler be convertible to Handler.
 106    */
 107   template <typename OtherHandler>
 108   basic_yield_context(const basic_yield_context<OtherHandler>& other)
 109     : coro_(other.coro_),
 110       ca_(other.ca_),
 111       handler_(other.handler_),
 112       ec_(other.ec_)
 113   {
 114   }
 115
 116   /// Return a yield context that sets the specified error_code.
 117   /**
 118    * By default, when a yield context is used with an asynchronous operation, a
 119    * non-success error_code is converted to system_error and thrown. This
 120    * operator may be used to specify an error_code object that should instead be
 121    * set with the asynchronous operation's result. For example:
 122    *
 123    * @code template <typename Handler>
 124    * void my_coroutine(basic_yield_context<Handler> yield)
 125    * {
 126    *   ...
 127    *   std::size_t n = my_socket.async_read_some(buffer, yield[ec]);
 128    *   if (ec)
 129    *   {
 130    *     // An error occurred.
 131    *   }
 132    *   ...
 133    * } @endcode
 134    */
 135   basic_yield_context operator[](boost::system::error_code& ec) const
 136   {
 137     basic_yield_context tmp(*this);
 138     tmp.ec_ = &ec;
 139     return tmp;
 140   }
 141
 142 #if defined(GENERATING_DOCUMENTATION)
 143 private:
 144 #endif // defined(GENERATING_DOCUMENTATION)
 145   detail::weak_ptr<callee_type> coro_;
 146   caller_type& ca_;
 147   Handler handler_;
 148   boost::system::error_code* ec_;
 149 };
 150
 151 #if defined(GENERATING_DOCUMENTATION)
 152 /// A @ref completion_token object that represents the currently executing
 153 /// coroutine.
 154 typedef basic_yield_context<unspecified> yield_context;
 155 #else // defined(GENERATING_DOCUMENTATION)
 156 typedef basic_yield_context<
 157   executor_binder<void(*)(), any_io_executor> > yield_context;
 158 #endif // defined(GENERATING_DOCUMENTATION)
 159
 160 /**
 161  * @defgroup spawn boost::asio::spawn
 162  *
 163  * @brief Start a new stackful coroutine.
 164  *
 165  * The spawn() function is a high-level wrapper over the Boost.Coroutine
 166  * library. This function enables programs to implement asynchronous logic in a
 167  * synchronous manner, as illustrated by the following example:
 168  *
 169  * @code boost::asio::spawn(my_strand, do_echo);
 170  *
 171  * // ...
 172  *
 173  * void do_echo(boost::asio::yield_context yield)
 174  * {
 175  *   try
 176  *   {
 177  *     char data[128];
 178  *     for (;;)
 179  *     {
 180  *       std::size_t length =
 181  *         my_socket.async_read_some(
 182  *           boost::asio::buffer(data), yield);
 183  *
 184  *       boost::asio::async_write(my_socket,
 185  *           boost::asio::buffer(data, length), yield);
 186  *     }
 187  *   }
 188  *   catch (std::exception& e)
 189  *   {
 190  *     // ...
 191  *   }
 192  * } @endcode
 193  */
 194 /*@{*/
 195
 196 /// Start a new stackful coroutine, calling the specified handler when it
 197 /// completes.
 198 /**
 199  * This function is used to launch a new coroutine.
 200  *
 201  * @param function The coroutine function. The function must have the signature:
 202  * @code void function(basic_yield_context<Handler> yield); @endcode
 203  *
 204  * @param attributes Boost.Coroutine attributes used to customise the coroutine.
 205  */
 206 template <typename Function>
 207 void spawn(BOOST_ASIO_MOVE_ARG(Function) function,
 208     const boost::coroutines::attributes& attributes
 209       = boost::coroutines::attributes());
 210
 211 /// Start a new stackful coroutine, calling the specified handler when it
 212 /// completes.
 213 /**
 214  * This function is used to launch a new coroutine.
 215  *
 216  * @param handler A handler to be called when the coroutine exits. More
 217  * importantly, the handler provides an execution context (via the the handler
 218  * invocation hook) for the coroutine. The handler must have the signature:
 219  * @code void handler(); @endcode
 220  *
 221  * @param function The coroutine function. The function must have the signature:
 222  * @code void function(basic_yield_context<Handler> yield); @endcode
 223  *
 224  * @param attributes Boost.Coroutine attributes used to customise the coroutine.
 225  */
 226 template <typename Handler, typename Function>
 227 void spawn(BOOST_ASIO_MOVE_ARG(Handler) handler,
 228     BOOST_ASIO_MOVE_ARG(Function) function,
 229     const boost::coroutines::attributes& attributes
 230       = boost::coroutines::attributes(),
 231     typename constraint<
 232       !is_executor<typename decay<Handler>::type>::value &&
 233       !execution::is_executor<typename decay<Handler>::type>::value &&
 234       !is_convertible<Handler&, execution_context&>::value>::type = 0);
 235
 236 /// Start a new stackful coroutine, inheriting the execution context of another.
 237 /**
 238  * This function is used to launch a new coroutine.
 239  *
 240  * @param ctx Identifies the current coroutine as a parent of the new
 241  * coroutine. This specifies that the new coroutine should inherit the
 242  * execution context of the parent. For example, if the parent coroutine is
 243  * executing in a particular strand, then the new coroutine will execute in the
 244  * same strand.
 245  *
 246  * @param function The coroutine function. The function must have the signature:
 247  * @code void function(basic_yield_context<Handler> yield); @endcode
 248  *
 249  * @param attributes Boost.Coroutine attributes used to customise the coroutine.
 250  */
 251 template <typename Handler, typename Function>
 252 void spawn(basic_yield_context<Handler> ctx,
 253     BOOST_ASIO_MOVE_ARG(Function) function,
 254     const boost::coroutines::attributes& attributes
 255       = boost::coroutines::attributes());
 256
 257 /// Start a new stackful coroutine that executes on a given executor.
 258 /**
 259  * This function is used to launch a new coroutine.
 260  *
 261  * @param ex Identifies the executor that will run the coroutine. The new
 262  * coroutine is implicitly given its own strand within this executor.
 263  *
 264  * @param function The coroutine function. The function must have the signature:
 265  * @code void function(yield_context yield); @endcode
 266  *
 267  * @param attributes Boost.Coroutine attributes used to customise the coroutine.
 268  */
 269 template <typename Function, typename Executor>
 270 void spawn(const Executor& ex,
 271     BOOST_ASIO_MOVE_ARG(Function) function,
 272     const boost::coroutines::attributes& attributes
 273       = boost::coroutines::attributes(),
 274     typename constraint<
 275       is_executor<Executor>::value || execution::is_executor<Executor>::value
 276     >::type = 0);
 277
 278 /// Start a new stackful coroutine that executes on a given strand.
 279 /**
 280  * This function is used to launch a new coroutine.
 281  *
 282  * @param ex Identifies the strand that will run the coroutine.
 283  *
 284  * @param function The coroutine function. The function must have the signature:
 285  * @code void function(yield_context yield); @endcode
 286  *
 287  * @param attributes Boost.Coroutine attributes used to customise the coroutine.
 288  */
 289 template <typename Function, typename Executor>
 290 void spawn(const strand<Executor>& ex,
 291     BOOST_ASIO_MOVE_ARG(Function) function,
 292     const boost::coroutines::attributes& attributes
 293       = boost::coroutines::attributes());
 294
 295 #if !defined(BOOST_ASIO_NO_TS_EXECUTORS)
 296
 297 /// Start a new stackful coroutine that executes in the context of a strand.
 298 /**
 299  * This function is used to launch a new coroutine.
 300  *
 301  * @param s Identifies a strand. By starting multiple coroutines on the same
 302  * strand, the implementation ensures that none of those coroutines can execute
 303  * simultaneously.
 304  *
 305  * @param function The coroutine function. The function must have the signature:
 306  * @code void function(yield_context yield); @endcode
 307  *
 308  * @param attributes Boost.Coroutine attributes used to customise the coroutine.
 309  */
 310 template <typename Function>
 311 void spawn(const boost::asio::io_context::strand& s,
 312     BOOST_ASIO_MOVE_ARG(Function) function,
 313     const boost::coroutines::attributes& attributes
 314       = boost::coroutines::attributes());
 315
 316 #endif // !defined(BOOST_ASIO_NO_TS_EXECUTORS)
 317
 318 /// Start a new stackful coroutine that executes on a given execution context.
 319 /**
 320  * This function is used to launch a new coroutine.
 321  *
 322  * @param ctx Identifies the execution context that will run the coroutine. The
 323  * new coroutine is implicitly given its own strand within this execution
 324  * context.
 325  *
 326  * @param function The coroutine function. The function must have the signature:
 327  * @code void function(yield_context yield); @endcode
 328  *
 329  * @param attributes Boost.Coroutine attributes used to customise the coroutine.
 330  */
 331 template <typename Function, typename ExecutionContext>
 332 void spawn(ExecutionContext& ctx,
 333     BOOST_ASIO_MOVE_ARG(Function) function,
 334     const boost::coroutines::attributes& attributes
 335       = boost::coroutines::attributes(),
 336     typename constraint<is_convertible<
 337       ExecutionContext&, execution_context&>::value>::type = 0);
 338
 339 /*@}*/
 340
 341 } // namespace asio
 342 } // namespace boost
 343
 344 #include <boost/asio/detail/pop_options.hpp>
 345
 346 #include <boost/asio/impl/spawn.hpp>
 347
 348 #endif // BOOST_ASIO_SPAWN_HPP