io_context_strand.hpp 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386
  1. //
  2. // io_context_strand.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_IO_CONTEXT_STRAND_HPP
  11. #define BOOST_ASIO_IO_CONTEXT_STRAND_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. #if !defined(BOOST_ASIO_NO_EXTENSIONS)
  17. #include <boost/asio/async_result.hpp>
  18. #include <boost/asio/detail/handler_type_requirements.hpp>
  19. #include <boost/asio/detail/strand_service.hpp>
  20. #include <boost/asio/detail/wrapped_handler.hpp>
  21. #include <boost/asio/io_context.hpp>
  22. #include <boost/asio/detail/push_options.hpp>
  23. namespace boost {
  24. namespace asio {
  25. /// Provides serialised handler execution.
  26. /**
  27. * The io_context::strand class provides the ability to post and dispatch
  28. * handlers with the guarantee that none of those handlers will execute
  29. * concurrently.
  30. *
  31. * @par Order of handler invocation
  32. * Given:
  33. *
  34. * @li a strand object @c s
  35. *
  36. * @li an object @c a meeting completion handler requirements
  37. *
  38. * @li an object @c a1 which is an arbitrary copy of @c a made by the
  39. * implementation
  40. *
  41. * @li an object @c b meeting completion handler requirements
  42. *
  43. * @li an object @c b1 which is an arbitrary copy of @c b made by the
  44. * implementation
  45. *
  46. * if any of the following conditions are true:
  47. *
  48. * @li @c s.post(a) happens-before @c s.post(b)
  49. *
  50. * @li @c s.post(a) happens-before @c s.dispatch(b), where the latter is
  51. * performed outside the strand
  52. *
  53. * @li @c s.dispatch(a) happens-before @c s.post(b), where the former is
  54. * performed outside the strand
  55. *
  56. * @li @c s.dispatch(a) happens-before @c s.dispatch(b), where both are
  57. * performed outside the strand
  58. *
  59. * then @c asio_handler_invoke(a1, &a1) happens-before
  60. * @c asio_handler_invoke(b1, &b1).
  61. *
  62. * Note that in the following case:
  63. * @code async_op_1(..., s.wrap(a));
  64. * async_op_2(..., s.wrap(b)); @endcode
  65. * the completion of the first async operation will perform @c s.dispatch(a),
  66. * and the second will perform @c s.dispatch(b), but the order in which those
  67. * are performed is unspecified. That is, you cannot state whether one
  68. * happens-before the other. Therefore none of the above conditions are met and
  69. * no ordering guarantee is made.
  70. *
  71. * @note The implementation makes no guarantee that handlers posted or
  72. * dispatched through different @c strand objects will be invoked concurrently.
  73. *
  74. * @par Thread Safety
  75. * @e Distinct @e objects: Safe.@n
  76. * @e Shared @e objects: Safe.
  77. *
  78. * @par Concepts:
  79. * Dispatcher.
  80. */
  81. class io_context::strand
  82. {
  83. public:
  84. /// Constructor.
  85. /**
  86. * Constructs the strand.
  87. *
  88. * @param io_context The io_context object that the strand will use to
  89. * dispatch handlers that are ready to be run.
  90. */
  91. explicit strand(boost::asio::io_context& io_context)
  92. : service_(boost::asio::use_service<
  93. boost::asio::detail::strand_service>(io_context))
  94. {
  95. service_.construct(impl_);
  96. }
  97. /// Destructor.
  98. /**
  99. * Destroys a strand.
  100. *
  101. * Handlers posted through the strand that have not yet been invoked will
  102. * still be dispatched in a way that meets the guarantee of non-concurrency.
  103. */
  104. ~strand()
  105. {
  106. }
  107. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  108. /// (Deprecated: Use context().) Get the io_context associated with the
  109. /// strand.
  110. /**
  111. * This function may be used to obtain the io_context object that the strand
  112. * uses to dispatch handlers for asynchronous operations.
  113. *
  114. * @return A reference to the io_context object that the strand will use to
  115. * dispatch handlers. Ownership is not transferred to the caller.
  116. */
  117. boost::asio::io_context& get_io_context()
  118. {
  119. return service_.get_io_context();
  120. }
  121. /// (Deprecated: Use context().) Get the io_context associated with the
  122. /// strand.
  123. /**
  124. * This function may be used to obtain the io_context object that the strand
  125. * uses to dispatch handlers for asynchronous operations.
  126. *
  127. * @return A reference to the io_context object that the strand will use to
  128. * dispatch handlers. Ownership is not transferred to the caller.
  129. */
  130. boost::asio::io_context& get_io_service()
  131. {
  132. return service_.get_io_context();
  133. }
  134. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  135. /// Obtain the underlying execution context.
  136. boost::asio::io_context& context() const BOOST_ASIO_NOEXCEPT
  137. {
  138. return service_.get_io_context();
  139. }
  140. /// Inform the strand that it has some outstanding work to do.
  141. /**
  142. * The strand delegates this call to its underlying io_context.
  143. */
  144. void on_work_started() const BOOST_ASIO_NOEXCEPT
  145. {
  146. context().get_executor().on_work_started();
  147. }
  148. /// Inform the strand that some work is no longer outstanding.
  149. /**
  150. * The strand delegates this call to its underlying io_context.
  151. */
  152. void on_work_finished() const BOOST_ASIO_NOEXCEPT
  153. {
  154. context().get_executor().on_work_finished();
  155. }
  156. /// Request the strand to invoke the given function object.
  157. /**
  158. * This function is used to ask the strand to execute the given function
  159. * object on its underlying io_context. The function object will be executed
  160. * inside this function if the strand is not otherwise busy and if the
  161. * underlying io_context's executor's @c dispatch() function is also able to
  162. * execute the function before returning.
  163. *
  164. * @param f The function object to be called. The executor will make
  165. * a copy of the handler object as required. The function signature of the
  166. * function object must be: @code void function(); @endcode
  167. *
  168. * @param a An allocator that may be used by the executor to allocate the
  169. * internal storage needed for function invocation.
  170. */
  171. template <typename Function, typename Allocator>
  172. void dispatch(BOOST_ASIO_MOVE_ARG(Function) f, const Allocator& a) const
  173. {
  174. typename decay<Function>::type tmp(BOOST_ASIO_MOVE_CAST(Function)(f));
  175. service_.dispatch(impl_, tmp);
  176. (void)a;
  177. }
  178. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  179. /// (Deprecated: Use boost::asio::dispatch().) Request the strand to invoke
  180. /// the given handler.
  181. /**
  182. * This function is used to ask the strand to execute the given handler.
  183. *
  184. * The strand object guarantees that handlers posted or dispatched through
  185. * the strand will not be executed concurrently. The handler may be executed
  186. * inside this function if the guarantee can be met. If this function is
  187. * called from within a handler that was posted or dispatched through the same
  188. * strand, then the new handler will be executed immediately.
  189. *
  190. * The strand's guarantee is in addition to the guarantee provided by the
  191. * underlying io_context. The io_context guarantees that the handler will only
  192. * be called in a thread in which the io_context's run member function is
  193. * currently being invoked.
  194. *
  195. * @param handler The handler to be called. The strand will make a copy of the
  196. * handler object as required. The function signature of the handler must be:
  197. * @code void handler(); @endcode
  198. */
  199. template <typename LegacyCompletionHandler>
  200. BOOST_ASIO_INITFN_RESULT_TYPE(LegacyCompletionHandler, void ())
  201. dispatch(BOOST_ASIO_MOVE_ARG(LegacyCompletionHandler) handler)
  202. {
  203. // If you get an error on the following line it means that your handler does
  204. // not meet the documented type requirements for a LegacyCompletionHandler.
  205. BOOST_ASIO_LEGACY_COMPLETION_HANDLER_CHECK(
  206. LegacyCompletionHandler, handler) type_check;
  207. async_completion<LegacyCompletionHandler, void ()> init(handler);
  208. service_.dispatch(impl_, init.completion_handler);
  209. return init.result.get();
  210. }
  211. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  212. /// Request the strand to invoke the given function object.
  213. /**
  214. * This function is used to ask the executor to execute the given function
  215. * object. The function object will never be executed inside this function.
  216. * Instead, it will be scheduled to run by the underlying io_context.
  217. *
  218. * @param f The function object to be called. The executor will make
  219. * a copy of the handler object as required. The function signature of the
  220. * function object must be: @code void function(); @endcode
  221. *
  222. * @param a An allocator that may be used by the executor to allocate the
  223. * internal storage needed for function invocation.
  224. */
  225. template <typename Function, typename Allocator>
  226. void post(BOOST_ASIO_MOVE_ARG(Function) f, const Allocator& a) const
  227. {
  228. typename decay<Function>::type tmp(BOOST_ASIO_MOVE_CAST(Function)(f));
  229. service_.post(impl_, tmp);
  230. (void)a;
  231. }
  232. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  233. /// (Deprecated: Use boost::asio::post().) Request the strand to invoke the
  234. /// given handler and return immediately.
  235. /**
  236. * This function is used to ask the strand to execute the given handler, but
  237. * without allowing the strand to call the handler from inside this function.
  238. *
  239. * The strand object guarantees that handlers posted or dispatched through
  240. * the strand will not be executed concurrently. The strand's guarantee is in
  241. * addition to the guarantee provided by the underlying io_context. The
  242. * io_context guarantees that the handler will only be called in a thread in
  243. * which the io_context's run member function is currently being invoked.
  244. *
  245. * @param handler The handler to be called. The strand will make a copy of the
  246. * handler object as required. The function signature of the handler must be:
  247. * @code void handler(); @endcode
  248. */
  249. template <typename LegacyCompletionHandler>
  250. BOOST_ASIO_INITFN_RESULT_TYPE(LegacyCompletionHandler, void ())
  251. post(BOOST_ASIO_MOVE_ARG(LegacyCompletionHandler) handler)
  252. {
  253. // If you get an error on the following line it means that your handler does
  254. // not meet the documented type requirements for a LegacyCompletionHandler.
  255. BOOST_ASIO_LEGACY_COMPLETION_HANDLER_CHECK(
  256. LegacyCompletionHandler, handler) type_check;
  257. async_completion<LegacyCompletionHandler, void ()> init(handler);
  258. service_.post(impl_, init.completion_handler);
  259. return init.result.get();
  260. }
  261. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  262. /// Request the strand to invoke the given function object.
  263. /**
  264. * This function is used to ask the executor to execute the given function
  265. * object. The function object will never be executed inside this function.
  266. * Instead, it will be scheduled to run by the underlying io_context.
  267. *
  268. * @param f The function object to be called. The executor will make
  269. * a copy of the handler object as required. The function signature of the
  270. * function object must be: @code void function(); @endcode
  271. *
  272. * @param a An allocator that may be used by the executor to allocate the
  273. * internal storage needed for function invocation.
  274. */
  275. template <typename Function, typename Allocator>
  276. void defer(BOOST_ASIO_MOVE_ARG(Function) f, const Allocator& a) const
  277. {
  278. typename decay<Function>::type tmp(BOOST_ASIO_MOVE_CAST(Function)(f));
  279. service_.post(impl_, tmp);
  280. (void)a;
  281. }
  282. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  283. /// (Deprecated: Use boost::asio::bind_executor().) Create a new handler that
  284. /// automatically dispatches the wrapped handler on the strand.
  285. /**
  286. * This function is used to create a new handler function object that, when
  287. * invoked, will automatically pass the wrapped handler to the strand's
  288. * dispatch function.
  289. *
  290. * @param handler The handler to be wrapped. The strand will make a copy of
  291. * the handler object as required. The function signature of the handler must
  292. * be: @code void handler(A1 a1, ... An an); @endcode
  293. *
  294. * @return A function object that, when invoked, passes the wrapped handler to
  295. * the strand's dispatch function. Given a function object with the signature:
  296. * @code R f(A1 a1, ... An an); @endcode
  297. * If this function object is passed to the wrap function like so:
  298. * @code strand.wrap(f); @endcode
  299. * then the return value is a function object with the signature
  300. * @code void g(A1 a1, ... An an); @endcode
  301. * that, when invoked, executes code equivalent to:
  302. * @code strand.dispatch(boost::bind(f, a1, ... an)); @endcode
  303. */
  304. template <typename Handler>
  305. #if defined(GENERATING_DOCUMENTATION)
  306. unspecified
  307. #else
  308. detail::wrapped_handler<strand, Handler, detail::is_continuation_if_running>
  309. #endif
  310. wrap(Handler handler)
  311. {
  312. return detail::wrapped_handler<io_context::strand, Handler,
  313. detail::is_continuation_if_running>(*this, handler);
  314. }
  315. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  316. /// Determine whether the strand is running in the current thread.
  317. /**
  318. * @return @c true if the current thread is executing a handler that was
  319. * submitted to the strand using post(), dispatch() or wrap(). Otherwise
  320. * returns @c false.
  321. */
  322. bool running_in_this_thread() const BOOST_ASIO_NOEXCEPT
  323. {
  324. return service_.running_in_this_thread(impl_);
  325. }
  326. /// Compare two strands for equality.
  327. /**
  328. * Two strands are equal if they refer to the same ordered, non-concurrent
  329. * state.
  330. */
  331. friend bool operator==(const strand& a, const strand& b) BOOST_ASIO_NOEXCEPT
  332. {
  333. return a.impl_ == b.impl_;
  334. }
  335. /// Compare two strands for inequality.
  336. /**
  337. * Two strands are equal if they refer to the same ordered, non-concurrent
  338. * state.
  339. */
  340. friend bool operator!=(const strand& a, const strand& b) BOOST_ASIO_NOEXCEPT
  341. {
  342. return a.impl_ != b.impl_;
  343. }
  344. private:
  345. boost::asio::detail::strand_service& service_;
  346. mutable boost::asio::detail::strand_service::implementation_type impl_;
  347. };
  348. } // namespace asio
  349. } // namespace boost
  350. #include <boost/asio/detail/pop_options.hpp>
  351. #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
  352. #endif // BOOST_ASIO_IO_CONTEXT_STRAND_HPP