spawn.hpp 11 KB

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