io_context.hpp 54 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536
  1. //
  2. // io_context.hpp
  3. // ~~~~~~~~~~~~~~
  4. //
  5. // Copyright (c) 2003-2023 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_HPP
  11. #define BOOST_ASIO_IO_CONTEXT_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 <cstddef>
  17. #include <stdexcept>
  18. #include <typeinfo>
  19. #include <boost/asio/async_result.hpp>
  20. #include <boost/asio/detail/concurrency_hint.hpp>
  21. #include <boost/asio/detail/cstdint.hpp>
  22. #include <boost/asio/detail/wrapped_handler.hpp>
  23. #include <boost/system/error_code.hpp>
  24. #include <boost/asio/execution.hpp>
  25. #include <boost/asio/execution_context.hpp>
  26. #if defined(BOOST_ASIO_HAS_CHRONO)
  27. # include <boost/asio/detail/chrono.hpp>
  28. #endif // defined(BOOST_ASIO_HAS_CHRONO)
  29. #if defined(BOOST_ASIO_WINDOWS) || defined(__CYGWIN__)
  30. # include <boost/asio/detail/winsock_init.hpp>
  31. #elif defined(__sun) || defined(__QNX__) || defined(__hpux) || defined(_AIX) \
  32. || defined(__osf__)
  33. # include <boost/asio/detail/signal_init.hpp>
  34. #endif
  35. #if defined(BOOST_ASIO_HAS_IOCP)
  36. # include <boost/asio/detail/win_iocp_io_context.hpp>
  37. #else
  38. # include <boost/asio/detail/scheduler.hpp>
  39. #endif
  40. #include <boost/asio/detail/push_options.hpp>
  41. namespace boost {
  42. namespace asio {
  43. namespace detail {
  44. #if defined(BOOST_ASIO_HAS_IOCP)
  45. typedef win_iocp_io_context io_context_impl;
  46. class win_iocp_overlapped_ptr;
  47. #else
  48. typedef scheduler io_context_impl;
  49. #endif
  50. struct io_context_bits
  51. {
  52. BOOST_ASIO_STATIC_CONSTEXPR(uintptr_t, blocking_never = 1);
  53. BOOST_ASIO_STATIC_CONSTEXPR(uintptr_t, relationship_continuation = 2);
  54. BOOST_ASIO_STATIC_CONSTEXPR(uintptr_t, outstanding_work_tracked = 4);
  55. BOOST_ASIO_STATIC_CONSTEXPR(uintptr_t, runtime_bits = 3);
  56. };
  57. } // namespace detail
  58. /// Provides core I/O functionality.
  59. /**
  60. * The io_context class provides the core I/O functionality for users of the
  61. * asynchronous I/O objects, including:
  62. *
  63. * @li boost::asio::ip::tcp::socket
  64. * @li boost::asio::ip::tcp::acceptor
  65. * @li boost::asio::ip::udp::socket
  66. * @li boost::asio::deadline_timer.
  67. *
  68. * The io_context class also includes facilities intended for developers of
  69. * custom asynchronous services.
  70. *
  71. * @par Thread Safety
  72. * @e Distinct @e objects: Safe.@n
  73. * @e Shared @e objects: Safe, with the specific exceptions of the restart()
  74. * and notify_fork() functions. Calling restart() while there are unfinished
  75. * run(), run_one(), run_for(), run_until(), poll() or poll_one() calls results
  76. * in undefined behaviour. The notify_fork() function should not be called
  77. * while any io_context function, or any function on an I/O object that is
  78. * associated with the io_context, is being called in another thread.
  79. *
  80. * @par Concepts:
  81. * Dispatcher.
  82. *
  83. * @par Synchronous and asynchronous operations
  84. *
  85. * Synchronous operations on I/O objects implicitly run the io_context object
  86. * for an individual operation. The io_context functions run(), run_one(),
  87. * run_for(), run_until(), poll() or poll_one() must be called for the
  88. * io_context to perform asynchronous operations on behalf of a C++ program.
  89. * Notification that an asynchronous operation has completed is delivered by
  90. * invocation of the associated handler. Handlers are invoked only by a thread
  91. * that is currently calling any overload of run(), run_one(), run_for(),
  92. * run_until(), poll() or poll_one() for the io_context.
  93. *
  94. * @par Effect of exceptions thrown from handlers
  95. *
  96. * If an exception is thrown from a handler, the exception is allowed to
  97. * propagate through the throwing thread's invocation of run(), run_one(),
  98. * run_for(), run_until(), poll() or poll_one(). No other threads that are
  99. * calling any of these functions are affected. It is then the responsibility
  100. * of the application to catch the exception.
  101. *
  102. * After the exception has been caught, the run(), run_one(), run_for(),
  103. * run_until(), poll() or poll_one() call may be restarted @em without the need
  104. * for an intervening call to restart(). This allows the thread to rejoin the
  105. * io_context object's thread pool without impacting any other threads in the
  106. * pool.
  107. *
  108. * For example:
  109. *
  110. * @code
  111. * boost::asio::io_context io_context;
  112. * ...
  113. * for (;;)
  114. * {
  115. * try
  116. * {
  117. * io_context.run();
  118. * break; // run() exited normally
  119. * }
  120. * catch (my_exception& e)
  121. * {
  122. * // Deal with exception as appropriate.
  123. * }
  124. * }
  125. * @endcode
  126. *
  127. * @par Submitting arbitrary tasks to the io_context
  128. *
  129. * To submit functions to the io_context, use the @ref boost::asio::dispatch,
  130. * @ref boost::asio::post or @ref boost::asio::defer free functions.
  131. *
  132. * For example:
  133. *
  134. * @code void my_task()
  135. * {
  136. * ...
  137. * }
  138. *
  139. * ...
  140. *
  141. * boost::asio::io_context io_context;
  142. *
  143. * // Submit a function to the io_context.
  144. * boost::asio::post(io_context, my_task);
  145. *
  146. * // Submit a lambda object to the io_context.
  147. * boost::asio::post(io_context,
  148. * []()
  149. * {
  150. * ...
  151. * });
  152. *
  153. * // Run the io_context until it runs out of work.
  154. * io_context.run(); @endcode
  155. *
  156. * @par Stopping the io_context from running out of work
  157. *
  158. * Some applications may need to prevent an io_context object's run() call from
  159. * returning when there is no more work to do. For example, the io_context may
  160. * be being run in a background thread that is launched prior to the
  161. * application's asynchronous operations. The run() call may be kept running by
  162. * using the @ref make_work_guard function to create an object of type
  163. * boost::asio::executor_work_guard<io_context::executor_type>:
  164. *
  165. * @code boost::asio::io_context io_context;
  166. * boost::asio::executor_work_guard<boost::asio::io_context::executor_type>
  167. * = boost::asio::make_work_guard(io_context);
  168. * ... @endcode
  169. *
  170. * To effect a shutdown, the application will then need to call the io_context
  171. * object's stop() member function. This will cause the io_context run() call
  172. * to return as soon as possible, abandoning unfinished operations and without
  173. * permitting ready handlers to be dispatched.
  174. *
  175. * Alternatively, if the application requires that all operations and handlers
  176. * be allowed to finish normally, the work object may be explicitly reset.
  177. *
  178. * @code boost::asio::io_context io_context;
  179. * boost::asio::executor_work_guard<boost::asio::io_context::executor_type>
  180. * = boost::asio::make_work_guard(io_context);
  181. * ...
  182. * work.reset(); // Allow run() to exit. @endcode
  183. */
  184. class io_context
  185. : public execution_context
  186. {
  187. private:
  188. typedef detail::io_context_impl impl_type;
  189. #if defined(BOOST_ASIO_HAS_IOCP)
  190. friend class detail::win_iocp_overlapped_ptr;
  191. #endif
  192. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  193. struct initiate_dispatch;
  194. struct initiate_post;
  195. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  196. public:
  197. template <typename Allocator, uintptr_t Bits>
  198. class basic_executor_type;
  199. template <typename Allocator, uintptr_t Bits>
  200. friend class basic_executor_type;
  201. /// Executor used to submit functions to an io_context.
  202. typedef basic_executor_type<std::allocator<void>, 0> executor_type;
  203. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  204. class work;
  205. friend class work;
  206. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  207. class service;
  208. #if !defined(BOOST_ASIO_NO_EXTENSIONS) \
  209. && !defined(BOOST_ASIO_NO_TS_EXECUTORS)
  210. class strand;
  211. #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
  212. // && !defined(BOOST_ASIO_NO_TS_EXECUTORS)
  213. /// The type used to count the number of handlers executed by the context.
  214. typedef std::size_t count_type;
  215. /// Constructor.
  216. BOOST_ASIO_DECL io_context();
  217. /// Constructor.
  218. /**
  219. * Construct with a hint about the required level of concurrency.
  220. *
  221. * @param concurrency_hint A suggestion to the implementation on how many
  222. * threads it should allow to run simultaneously.
  223. */
  224. BOOST_ASIO_DECL explicit io_context(int concurrency_hint);
  225. /// Destructor.
  226. /**
  227. * On destruction, the io_context performs the following sequence of
  228. * operations:
  229. *
  230. * @li For each service object @c svc in the io_context set, in reverse order
  231. * of the beginning of service object lifetime, performs
  232. * @c svc->shutdown().
  233. *
  234. * @li Uninvoked handler objects that were scheduled for deferred invocation
  235. * on the io_context, or any associated strand, are destroyed.
  236. *
  237. * @li For each service object @c svc in the io_context set, in reverse order
  238. * of the beginning of service object lifetime, performs
  239. * <tt>delete static_cast<io_context::service*>(svc)</tt>.
  240. *
  241. * @note The destruction sequence described above permits programs to
  242. * simplify their resource management by using @c shared_ptr<>. Where an
  243. * object's lifetime is tied to the lifetime of a connection (or some other
  244. * sequence of asynchronous operations), a @c shared_ptr to the object would
  245. * be bound into the handlers for all asynchronous operations associated with
  246. * it. This works as follows:
  247. *
  248. * @li When a single connection ends, all associated asynchronous operations
  249. * complete. The corresponding handler objects are destroyed, and all
  250. * @c shared_ptr references to the objects are destroyed.
  251. *
  252. * @li To shut down the whole program, the io_context function stop() is
  253. * called to terminate any run() calls as soon as possible. The io_context
  254. * destructor defined above destroys all handlers, causing all @c shared_ptr
  255. * references to all connection objects to be destroyed.
  256. */
  257. BOOST_ASIO_DECL ~io_context();
  258. /// Obtains the executor associated with the io_context.
  259. executor_type get_executor() BOOST_ASIO_NOEXCEPT;
  260. /// Run the io_context object's event processing loop.
  261. /**
  262. * The run() function blocks until all work has finished and there are no
  263. * more handlers to be dispatched, or until the io_context has been stopped.
  264. *
  265. * Multiple threads may call the run() function to set up a pool of threads
  266. * from which the io_context may execute handlers. All threads that are
  267. * waiting in the pool are equivalent and the io_context may choose any one
  268. * of them to invoke a handler.
  269. *
  270. * A normal exit from the run() function implies that the io_context object
  271. * is stopped (the stopped() function returns @c true). Subsequent calls to
  272. * run(), run_one(), poll() or poll_one() will return immediately unless there
  273. * is a prior call to restart().
  274. *
  275. * @return The number of handlers that were executed.
  276. *
  277. * @note Calling the run() function from a thread that is currently calling
  278. * one of run(), run_one(), run_for(), run_until(), poll() or poll_one() on
  279. * the same io_context object may introduce the potential for deadlock. It is
  280. * the caller's reponsibility to avoid this.
  281. *
  282. * The poll() function may also be used to dispatch ready handlers, but
  283. * without blocking.
  284. */
  285. BOOST_ASIO_DECL count_type run();
  286. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  287. /// (Deprecated: Use non-error_code overload.) Run the io_context object's
  288. /// event processing loop.
  289. /**
  290. * The run() function blocks until all work has finished and there are no
  291. * more handlers to be dispatched, or until the io_context has been stopped.
  292. *
  293. * Multiple threads may call the run() function to set up a pool of threads
  294. * from which the io_context may execute handlers. All threads that are
  295. * waiting in the pool are equivalent and the io_context may choose any one
  296. * of them to invoke a handler.
  297. *
  298. * A normal exit from the run() function implies that the io_context object
  299. * is stopped (the stopped() function returns @c true). Subsequent calls to
  300. * run(), run_one(), poll() or poll_one() will return immediately unless there
  301. * is a prior call to restart().
  302. *
  303. * @param ec Set to indicate what error occurred, if any.
  304. *
  305. * @return The number of handlers that were executed.
  306. *
  307. * @note Calling the run() function from a thread that is currently calling
  308. * one of run(), run_one(), run_for(), run_until(), poll() or poll_one() on
  309. * the same io_context object may introduce the potential for deadlock. It is
  310. * the caller's reponsibility to avoid this.
  311. *
  312. * The poll() function may also be used to dispatch ready handlers, but
  313. * without blocking.
  314. */
  315. BOOST_ASIO_DECL count_type run(boost::system::error_code& ec);
  316. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  317. #if defined(BOOST_ASIO_HAS_CHRONO) || defined(GENERATING_DOCUMENTATION)
  318. /// Run the io_context object's event processing loop for a specified
  319. /// duration.
  320. /**
  321. * The run_for() function blocks until all work has finished and there are no
  322. * more handlers to be dispatched, until the io_context has been stopped, or
  323. * until the specified duration has elapsed.
  324. *
  325. * @param rel_time The duration for which the call may block.
  326. *
  327. * @return The number of handlers that were executed.
  328. */
  329. template <typename Rep, typename Period>
  330. std::size_t run_for(const chrono::duration<Rep, Period>& rel_time);
  331. /// Run the io_context object's event processing loop until a specified time.
  332. /**
  333. * The run_until() function blocks until all work has finished and there are
  334. * no more handlers to be dispatched, until the io_context has been stopped,
  335. * or until the specified time has been reached.
  336. *
  337. * @param abs_time The time point until which the call may block.
  338. *
  339. * @return The number of handlers that were executed.
  340. */
  341. template <typename Clock, typename Duration>
  342. std::size_t run_until(const chrono::time_point<Clock, Duration>& abs_time);
  343. #endif // defined(BOOST_ASIO_HAS_CHRONO) || defined(GENERATING_DOCUMENTATION)
  344. /// Run the io_context object's event processing loop to execute at most one
  345. /// handler.
  346. /**
  347. * The run_one() function blocks until one handler has been dispatched, or
  348. * until the io_context has been stopped.
  349. *
  350. * @return The number of handlers that were executed. A zero return value
  351. * implies that the io_context object is stopped (the stopped() function
  352. * returns @c true). Subsequent calls to run(), run_one(), poll() or
  353. * poll_one() will return immediately unless there is a prior call to
  354. * restart().
  355. *
  356. * @note Calling the run_one() function from a thread that is currently
  357. * calling one of run(), run_one(), run_for(), run_until(), poll() or
  358. * poll_one() on the same io_context object may introduce the potential for
  359. * deadlock. It is the caller's reponsibility to avoid this.
  360. */
  361. BOOST_ASIO_DECL count_type run_one();
  362. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  363. /// (Deprecated: Use non-error_code overload.) Run the io_context object's
  364. /// event processing loop to execute at most one handler.
  365. /**
  366. * The run_one() function blocks until one handler has been dispatched, or
  367. * until the io_context has been stopped.
  368. *
  369. * @return The number of handlers that were executed. A zero return value
  370. * implies that the io_context object is stopped (the stopped() function
  371. * returns @c true). Subsequent calls to run(), run_one(), poll() or
  372. * poll_one() will return immediately unless there is a prior call to
  373. * restart().
  374. *
  375. * @return The number of handlers that were executed.
  376. *
  377. * @note Calling the run_one() function from a thread that is currently
  378. * calling one of run(), run_one(), run_for(), run_until(), poll() or
  379. * poll_one() on the same io_context object may introduce the potential for
  380. * deadlock. It is the caller's reponsibility to avoid this.
  381. */
  382. BOOST_ASIO_DECL count_type run_one(boost::system::error_code& ec);
  383. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  384. #if defined(BOOST_ASIO_HAS_CHRONO) || defined(GENERATING_DOCUMENTATION)
  385. /// Run the io_context object's event processing loop for a specified duration
  386. /// to execute at most one handler.
  387. /**
  388. * The run_one_for() function blocks until one handler has been dispatched,
  389. * until the io_context has been stopped, or until the specified duration has
  390. * elapsed.
  391. *
  392. * @param rel_time The duration for which the call may block.
  393. *
  394. * @return The number of handlers that were executed.
  395. */
  396. template <typename Rep, typename Period>
  397. std::size_t run_one_for(const chrono::duration<Rep, Period>& rel_time);
  398. /// Run the io_context object's event processing loop until a specified time
  399. /// to execute at most one handler.
  400. /**
  401. * The run_one_until() function blocks until one handler has been dispatched,
  402. * until the io_context has been stopped, or until the specified time has
  403. * been reached.
  404. *
  405. * @param abs_time The time point until which the call may block.
  406. *
  407. * @return The number of handlers that were executed.
  408. */
  409. template <typename Clock, typename Duration>
  410. std::size_t run_one_until(
  411. const chrono::time_point<Clock, Duration>& abs_time);
  412. #endif // defined(BOOST_ASIO_HAS_CHRONO) || defined(GENERATING_DOCUMENTATION)
  413. /// Run the io_context object's event processing loop to execute ready
  414. /// handlers.
  415. /**
  416. * The poll() function runs handlers that are ready to run, without blocking,
  417. * until the io_context has been stopped or there are no more ready handlers.
  418. *
  419. * @return The number of handlers that were executed.
  420. */
  421. BOOST_ASIO_DECL count_type poll();
  422. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  423. /// (Deprecated: Use non-error_code overload.) Run the io_context object's
  424. /// event processing loop to execute ready handlers.
  425. /**
  426. * The poll() function runs handlers that are ready to run, without blocking,
  427. * until the io_context has been stopped or there are no more ready handlers.
  428. *
  429. * @param ec Set to indicate what error occurred, if any.
  430. *
  431. * @return The number of handlers that were executed.
  432. */
  433. BOOST_ASIO_DECL count_type poll(boost::system::error_code& ec);
  434. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  435. /// Run the io_context object's event processing loop to execute one ready
  436. /// handler.
  437. /**
  438. * The poll_one() function runs at most one handler that is ready to run,
  439. * without blocking.
  440. *
  441. * @return The number of handlers that were executed.
  442. */
  443. BOOST_ASIO_DECL count_type poll_one();
  444. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  445. /// (Deprecated: Use non-error_code overload.) Run the io_context object's
  446. /// event processing loop to execute one ready handler.
  447. /**
  448. * The poll_one() function runs at most one handler that is ready to run,
  449. * without blocking.
  450. *
  451. * @param ec Set to indicate what error occurred, if any.
  452. *
  453. * @return The number of handlers that were executed.
  454. */
  455. BOOST_ASIO_DECL count_type poll_one(boost::system::error_code& ec);
  456. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  457. /// Stop the io_context object's event processing loop.
  458. /**
  459. * This function does not block, but instead simply signals the io_context to
  460. * stop. All invocations of its run() or run_one() member functions should
  461. * return as soon as possible. Subsequent calls to run(), run_one(), poll()
  462. * or poll_one() will return immediately until restart() is called.
  463. */
  464. BOOST_ASIO_DECL void stop();
  465. /// Determine whether the io_context object has been stopped.
  466. /**
  467. * This function is used to determine whether an io_context object has been
  468. * stopped, either through an explicit call to stop(), or due to running out
  469. * of work. When an io_context object is stopped, calls to run(), run_one(),
  470. * poll() or poll_one() will return immediately without invoking any
  471. * handlers.
  472. *
  473. * @return @c true if the io_context object is stopped, otherwise @c false.
  474. */
  475. BOOST_ASIO_DECL bool stopped() const;
  476. /// Restart the io_context in preparation for a subsequent run() invocation.
  477. /**
  478. * This function must be called prior to any second or later set of
  479. * invocations of the run(), run_one(), poll() or poll_one() functions when a
  480. * previous invocation of these functions returned due to the io_context
  481. * being stopped or running out of work. After a call to restart(), the
  482. * io_context object's stopped() function will return @c false.
  483. *
  484. * This function must not be called while there are any unfinished calls to
  485. * the run(), run_one(), poll() or poll_one() functions.
  486. */
  487. BOOST_ASIO_DECL void restart();
  488. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  489. /// (Deprecated: Use restart().) Reset the io_context in preparation for a
  490. /// subsequent run() invocation.
  491. /**
  492. * This function must be called prior to any second or later set of
  493. * invocations of the run(), run_one(), poll() or poll_one() functions when a
  494. * previous invocation of these functions returned due to the io_context
  495. * being stopped or running out of work. After a call to restart(), the
  496. * io_context object's stopped() function will return @c false.
  497. *
  498. * This function must not be called while there are any unfinished calls to
  499. * the run(), run_one(), poll() or poll_one() functions.
  500. */
  501. void reset();
  502. /// (Deprecated: Use boost::asio::dispatch().) Request the io_context to
  503. /// invoke the given handler.
  504. /**
  505. * This function is used to ask the io_context to execute the given handler.
  506. *
  507. * The io_context guarantees that the handler will only be called in a thread
  508. * in which the run(), run_one(), poll() or poll_one() member functions is
  509. * currently being invoked. The handler may be executed inside this function
  510. * if the guarantee can be met.
  511. *
  512. * @param handler The handler to be called. The io_context will make
  513. * a copy of the handler object as required. The function signature of the
  514. * handler must be: @code void handler(); @endcode
  515. *
  516. * @note This function throws an exception only if:
  517. *
  518. * @li the handler's @c asio_handler_allocate function; or
  519. *
  520. * @li the handler's copy constructor
  521. *
  522. * throws an exception.
  523. */
  524. template <typename LegacyCompletionHandler>
  525. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE_PREFIX(LegacyCompletionHandler, void ())
  526. dispatch(BOOST_ASIO_MOVE_ARG(LegacyCompletionHandler) handler)
  527. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE_SUFFIX((
  528. async_initiate<LegacyCompletionHandler, void ()>(
  529. declval<initiate_dispatch>(), handler, this)));
  530. /// (Deprecated: Use boost::asio::post().) Request the io_context to invoke
  531. /// the given handler and return immediately.
  532. /**
  533. * This function is used to ask the io_context to execute the given handler,
  534. * but without allowing the io_context to call the handler from inside this
  535. * function.
  536. *
  537. * The io_context guarantees that the handler will only be called in a thread
  538. * in which the run(), run_one(), poll() or poll_one() member functions is
  539. * currently being invoked.
  540. *
  541. * @param handler The handler to be called. The io_context will make
  542. * a copy of the handler object as required. The function signature of the
  543. * handler must be: @code void handler(); @endcode
  544. *
  545. * @note This function throws an exception only if:
  546. *
  547. * @li the handler's @c asio_handler_allocate function; or
  548. *
  549. * @li the handler's copy constructor
  550. *
  551. * throws an exception.
  552. */
  553. template <typename LegacyCompletionHandler>
  554. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE_PREFIX(LegacyCompletionHandler, void ())
  555. post(BOOST_ASIO_MOVE_ARG(LegacyCompletionHandler) handler)
  556. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE_SUFFIX((
  557. async_initiate<LegacyCompletionHandler, void ()>(
  558. declval<initiate_post>(), handler, this)));
  559. /// (Deprecated: Use boost::asio::bind_executor().) Create a new handler that
  560. /// automatically dispatches the wrapped handler on the io_context.
  561. /**
  562. * This function is used to create a new handler function object that, when
  563. * invoked, will automatically pass the wrapped handler to the io_context
  564. * object's dispatch function.
  565. *
  566. * @param handler The handler to be wrapped. The io_context will make a copy
  567. * of the handler object as required. The function signature of the handler
  568. * must be: @code void handler(A1 a1, ... An an); @endcode
  569. *
  570. * @return A function object that, when invoked, passes the wrapped handler to
  571. * the io_context object's dispatch function. Given a function object with the
  572. * signature:
  573. * @code R f(A1 a1, ... An an); @endcode
  574. * If this function object is passed to the wrap function like so:
  575. * @code io_context.wrap(f); @endcode
  576. * then the return value is a function object with the signature
  577. * @code void g(A1 a1, ... An an); @endcode
  578. * that, when invoked, executes code equivalent to:
  579. * @code io_context.dispatch(boost::bind(f, a1, ... an)); @endcode
  580. */
  581. template <typename Handler>
  582. #if defined(GENERATING_DOCUMENTATION)
  583. unspecified
  584. #else
  585. detail::wrapped_handler<io_context&, Handler>
  586. #endif
  587. wrap(Handler handler);
  588. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  589. private:
  590. io_context(const io_context&) BOOST_ASIO_DELETED;
  591. io_context& operator=(const io_context&) BOOST_ASIO_DELETED;
  592. // Helper function to add the implementation.
  593. BOOST_ASIO_DECL impl_type& add_impl(impl_type* impl);
  594. // Backwards compatible overload for use with services derived from
  595. // io_context::service.
  596. template <typename Service>
  597. friend Service& use_service(io_context& ioc);
  598. #if defined(BOOST_ASIO_WINDOWS) || defined(__CYGWIN__)
  599. detail::winsock_init<> init_;
  600. #elif defined(__sun) || defined(__QNX__) || defined(__hpux) || defined(_AIX) \
  601. || defined(__osf__)
  602. detail::signal_init<> init_;
  603. #endif
  604. // The implementation.
  605. impl_type& impl_;
  606. };
  607. namespace detail {
  608. } // namespace detail
  609. /// Executor implementation type used to submit functions to an io_context.
  610. template <typename Allocator, uintptr_t Bits>
  611. class io_context::basic_executor_type :
  612. detail::io_context_bits, Allocator
  613. {
  614. public:
  615. /// Copy constructor.
  616. basic_executor_type(
  617. const basic_executor_type& other) BOOST_ASIO_NOEXCEPT
  618. : Allocator(static_cast<const Allocator&>(other)),
  619. target_(other.target_)
  620. {
  621. if (Bits & outstanding_work_tracked)
  622. if (context_ptr())
  623. context_ptr()->impl_.work_started();
  624. }
  625. #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  626. /// Move constructor.
  627. basic_executor_type(basic_executor_type&& other) BOOST_ASIO_NOEXCEPT
  628. : Allocator(BOOST_ASIO_MOVE_CAST(Allocator)(other)),
  629. target_(other.target_)
  630. {
  631. if (Bits & outstanding_work_tracked)
  632. other.target_ = 0;
  633. }
  634. #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  635. /// Destructor.
  636. ~basic_executor_type() BOOST_ASIO_NOEXCEPT
  637. {
  638. if (Bits & outstanding_work_tracked)
  639. if (context_ptr())
  640. context_ptr()->impl_.work_finished();
  641. }
  642. /// Assignment operator.
  643. basic_executor_type& operator=(
  644. const basic_executor_type& other) BOOST_ASIO_NOEXCEPT;
  645. #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  646. /// Move assignment operator.
  647. basic_executor_type& operator=(
  648. basic_executor_type&& other) BOOST_ASIO_NOEXCEPT;
  649. #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  650. #if !defined(GENERATING_DOCUMENTATION)
  651. private:
  652. friend struct boost_asio_require_fn::impl;
  653. friend struct boost_asio_prefer_fn::impl;
  654. #endif // !defined(GENERATING_DOCUMENTATION)
  655. /// Obtain an executor with the @c blocking.possibly property.
  656. /**
  657. * Do not call this function directly. It is intended for use with the
  658. * boost::asio::require customisation point.
  659. *
  660. * For example:
  661. * @code auto ex1 = my_io_context.get_executor();
  662. * auto ex2 = boost::asio::require(ex1,
  663. * boost::asio::execution::blocking.possibly); @endcode
  664. */
  665. BOOST_ASIO_CONSTEXPR basic_executor_type require(
  666. execution::blocking_t::possibly_t) const
  667. {
  668. return basic_executor_type(context_ptr(),
  669. *this, bits() & ~blocking_never);
  670. }
  671. /// Obtain an executor with the @c blocking.never property.
  672. /**
  673. * Do not call this function directly. It is intended for use with the
  674. * boost::asio::require customisation point.
  675. *
  676. * For example:
  677. * @code auto ex1 = my_io_context.get_executor();
  678. * auto ex2 = boost::asio::require(ex1,
  679. * boost::asio::execution::blocking.never); @endcode
  680. */
  681. BOOST_ASIO_CONSTEXPR basic_executor_type require(
  682. execution::blocking_t::never_t) const
  683. {
  684. return basic_executor_type(context_ptr(),
  685. *this, bits() | blocking_never);
  686. }
  687. /// Obtain an executor with the @c relationship.fork property.
  688. /**
  689. * Do not call this function directly. It is intended for use with the
  690. * boost::asio::require customisation point.
  691. *
  692. * For example:
  693. * @code auto ex1 = my_io_context.get_executor();
  694. * auto ex2 = boost::asio::require(ex1,
  695. * boost::asio::execution::relationship.fork); @endcode
  696. */
  697. BOOST_ASIO_CONSTEXPR basic_executor_type require(
  698. execution::relationship_t::fork_t) const
  699. {
  700. return basic_executor_type(context_ptr(),
  701. *this, bits() & ~relationship_continuation);
  702. }
  703. /// Obtain an executor with the @c relationship.continuation property.
  704. /**
  705. * Do not call this function directly. It is intended for use with the
  706. * boost::asio::require customisation point.
  707. *
  708. * For example:
  709. * @code auto ex1 = my_io_context.get_executor();
  710. * auto ex2 = boost::asio::require(ex1,
  711. * boost::asio::execution::relationship.continuation); @endcode
  712. */
  713. BOOST_ASIO_CONSTEXPR basic_executor_type require(
  714. execution::relationship_t::continuation_t) const
  715. {
  716. return basic_executor_type(context_ptr(),
  717. *this, bits() | relationship_continuation);
  718. }
  719. /// Obtain an executor with the @c outstanding_work.tracked property.
  720. /**
  721. * Do not call this function directly. It is intended for use with the
  722. * boost::asio::require customisation point.
  723. *
  724. * For example:
  725. * @code auto ex1 = my_io_context.get_executor();
  726. * auto ex2 = boost::asio::require(ex1,
  727. * boost::asio::execution::outstanding_work.tracked); @endcode
  728. */
  729. BOOST_ASIO_CONSTEXPR basic_executor_type<Allocator,
  730. BOOST_ASIO_UNSPECIFIED(Bits | outstanding_work_tracked)>
  731. require(execution::outstanding_work_t::tracked_t) const
  732. {
  733. return basic_executor_type<Allocator, Bits | outstanding_work_tracked>(
  734. context_ptr(), *this, bits());
  735. }
  736. /// Obtain an executor with the @c outstanding_work.untracked property.
  737. /**
  738. * Do not call this function directly. It is intended for use with the
  739. * boost::asio::require customisation point.
  740. *
  741. * For example:
  742. * @code auto ex1 = my_io_context.get_executor();
  743. * auto ex2 = boost::asio::require(ex1,
  744. * boost::asio::execution::outstanding_work.untracked); @endcode
  745. */
  746. BOOST_ASIO_CONSTEXPR basic_executor_type<Allocator,
  747. BOOST_ASIO_UNSPECIFIED(Bits & ~outstanding_work_tracked)>
  748. require(execution::outstanding_work_t::untracked_t) const
  749. {
  750. return basic_executor_type<Allocator, Bits & ~outstanding_work_tracked>(
  751. context_ptr(), *this, bits());
  752. }
  753. /// Obtain an executor with the specified @c allocator property.
  754. /**
  755. * Do not call this function directly. It is intended for use with the
  756. * boost::asio::require customisation point.
  757. *
  758. * For example:
  759. * @code auto ex1 = my_io_context.get_executor();
  760. * auto ex2 = boost::asio::require(ex1,
  761. * boost::asio::execution::allocator(my_allocator)); @endcode
  762. */
  763. template <typename OtherAllocator>
  764. BOOST_ASIO_CONSTEXPR basic_executor_type<OtherAllocator, Bits>
  765. require(execution::allocator_t<OtherAllocator> a) const
  766. {
  767. return basic_executor_type<OtherAllocator, Bits>(
  768. context_ptr(), a.value(), bits());
  769. }
  770. /// Obtain an executor with the default @c allocator property.
  771. /**
  772. * Do not call this function directly. It is intended for use with the
  773. * boost::asio::require customisation point.
  774. *
  775. * For example:
  776. * @code auto ex1 = my_io_context.get_executor();
  777. * auto ex2 = boost::asio::require(ex1,
  778. * boost::asio::execution::allocator); @endcode
  779. */
  780. BOOST_ASIO_CONSTEXPR basic_executor_type<std::allocator<void>, Bits>
  781. require(execution::allocator_t<void>) const
  782. {
  783. return basic_executor_type<std::allocator<void>, Bits>(
  784. context_ptr(), std::allocator<void>(), bits());
  785. }
  786. #if !defined(GENERATING_DOCUMENTATION)
  787. private:
  788. friend struct boost_asio_query_fn::impl;
  789. friend struct boost::asio::execution::detail::mapping_t<0>;
  790. friend struct boost::asio::execution::detail::outstanding_work_t<0>;
  791. #endif // !defined(GENERATING_DOCUMENTATION)
  792. /// Query the current value of the @c mapping property.
  793. /**
  794. * Do not call this function directly. It is intended for use with the
  795. * boost::asio::query customisation point.
  796. *
  797. * For example:
  798. * @code auto ex = my_io_context.get_executor();
  799. * if (boost::asio::query(ex, boost::asio::execution::mapping)
  800. * == boost::asio::execution::mapping.thread)
  801. * ... @endcode
  802. */
  803. static BOOST_ASIO_CONSTEXPR execution::mapping_t query(
  804. execution::mapping_t) BOOST_ASIO_NOEXCEPT
  805. {
  806. return execution::mapping.thread;
  807. }
  808. /// Query the current value of the @c context property.
  809. /**
  810. * Do not call this function directly. It is intended for use with the
  811. * boost::asio::query customisation point.
  812. *
  813. * For example:
  814. * @code auto ex = my_io_context.get_executor();
  815. * boost::asio::io_context& ctx = boost::asio::query(
  816. * ex, boost::asio::execution::context); @endcode
  817. */
  818. io_context& query(execution::context_t) const BOOST_ASIO_NOEXCEPT
  819. {
  820. return *context_ptr();
  821. }
  822. /// Query the current value of the @c blocking property.
  823. /**
  824. * Do not call this function directly. It is intended for use with the
  825. * boost::asio::query customisation point.
  826. *
  827. * For example:
  828. * @code auto ex = my_io_context.get_executor();
  829. * if (boost::asio::query(ex, boost::asio::execution::blocking)
  830. * == boost::asio::execution::blocking.always)
  831. * ... @endcode
  832. */
  833. BOOST_ASIO_CONSTEXPR execution::blocking_t query(
  834. execution::blocking_t) const BOOST_ASIO_NOEXCEPT
  835. {
  836. return (bits() & blocking_never)
  837. ? execution::blocking_t(execution::blocking.never)
  838. : execution::blocking_t(execution::blocking.possibly);
  839. }
  840. /// Query the current value of the @c relationship property.
  841. /**
  842. * Do not call this function directly. It is intended for use with the
  843. * boost::asio::query customisation point.
  844. *
  845. * For example:
  846. * @code auto ex = my_io_context.get_executor();
  847. * if (boost::asio::query(ex, boost::asio::execution::relationship)
  848. * == boost::asio::execution::relationship.continuation)
  849. * ... @endcode
  850. */
  851. BOOST_ASIO_CONSTEXPR execution::relationship_t query(
  852. execution::relationship_t) const BOOST_ASIO_NOEXCEPT
  853. {
  854. return (bits() & relationship_continuation)
  855. ? execution::relationship_t(execution::relationship.continuation)
  856. : execution::relationship_t(execution::relationship.fork);
  857. }
  858. /// Query the current value of the @c outstanding_work property.
  859. /**
  860. * Do not call this function directly. It is intended for use with the
  861. * boost::asio::query customisation point.
  862. *
  863. * For example:
  864. * @code auto ex = my_io_context.get_executor();
  865. * if (boost::asio::query(ex, boost::asio::execution::outstanding_work)
  866. * == boost::asio::execution::outstanding_work.tracked)
  867. * ... @endcode
  868. */
  869. static BOOST_ASIO_CONSTEXPR execution::outstanding_work_t query(
  870. execution::outstanding_work_t) BOOST_ASIO_NOEXCEPT
  871. {
  872. return (Bits & outstanding_work_tracked)
  873. ? execution::outstanding_work_t(execution::outstanding_work.tracked)
  874. : execution::outstanding_work_t(execution::outstanding_work.untracked);
  875. }
  876. /// Query the current value of the @c allocator property.
  877. /**
  878. * Do not call this function directly. It is intended for use with the
  879. * boost::asio::query customisation point.
  880. *
  881. * For example:
  882. * @code auto ex = my_io_context.get_executor();
  883. * auto alloc = boost::asio::query(ex,
  884. * boost::asio::execution::allocator); @endcode
  885. */
  886. template <typename OtherAllocator>
  887. BOOST_ASIO_CONSTEXPR Allocator query(
  888. execution::allocator_t<OtherAllocator>) const BOOST_ASIO_NOEXCEPT
  889. {
  890. return static_cast<const Allocator&>(*this);
  891. }
  892. /// Query the current value of the @c allocator property.
  893. /**
  894. * Do not call this function directly. It is intended for use with the
  895. * boost::asio::query customisation point.
  896. *
  897. * For example:
  898. * @code auto ex = my_io_context.get_executor();
  899. * auto alloc = boost::asio::query(ex,
  900. * boost::asio::execution::allocator); @endcode
  901. */
  902. BOOST_ASIO_CONSTEXPR Allocator query(
  903. execution::allocator_t<void>) const BOOST_ASIO_NOEXCEPT
  904. {
  905. return static_cast<const Allocator&>(*this);
  906. }
  907. public:
  908. /// Determine whether the io_context is running in the current thread.
  909. /**
  910. * @return @c true if the current thread is running the io_context. Otherwise
  911. * returns @c false.
  912. */
  913. bool running_in_this_thread() const BOOST_ASIO_NOEXCEPT;
  914. /// Compare two executors for equality.
  915. /**
  916. * Two executors are equal if they refer to the same underlying io_context.
  917. */
  918. friend bool operator==(const basic_executor_type& a,
  919. const basic_executor_type& b) BOOST_ASIO_NOEXCEPT
  920. {
  921. return a.target_ == b.target_
  922. && static_cast<const Allocator&>(a) == static_cast<const Allocator&>(b);
  923. }
  924. /// Compare two executors for inequality.
  925. /**
  926. * Two executors are equal if they refer to the same underlying io_context.
  927. */
  928. friend bool operator!=(const basic_executor_type& a,
  929. const basic_executor_type& b) BOOST_ASIO_NOEXCEPT
  930. {
  931. return a.target_ != b.target_
  932. || static_cast<const Allocator&>(a) != static_cast<const Allocator&>(b);
  933. }
  934. /// Execution function.
  935. template <typename Function>
  936. void execute(BOOST_ASIO_MOVE_ARG(Function) f) const;
  937. #if !defined(BOOST_ASIO_NO_TS_EXECUTORS)
  938. public:
  939. /// Obtain the underlying execution context.
  940. io_context& context() const BOOST_ASIO_NOEXCEPT;
  941. /// Inform the io_context that it has some outstanding work to do.
  942. /**
  943. * This function is used to inform the io_context that some work has begun.
  944. * This ensures that the io_context's run() and run_one() functions do not
  945. * exit while the work is underway.
  946. */
  947. void on_work_started() const BOOST_ASIO_NOEXCEPT;
  948. /// Inform the io_context that some work is no longer outstanding.
  949. /**
  950. * This function is used to inform the io_context that some work has
  951. * finished. Once the count of unfinished work reaches zero, the io_context
  952. * is stopped and the run() and run_one() functions may exit.
  953. */
  954. void on_work_finished() const BOOST_ASIO_NOEXCEPT;
  955. /// Request the io_context to invoke the given function object.
  956. /**
  957. * This function is used to ask the io_context to execute the given function
  958. * object. If the current thread is running the io_context, @c dispatch()
  959. * executes the function before returning. Otherwise, the function will be
  960. * scheduled to run on the io_context.
  961. *
  962. * @param f The function object to be called. The executor will make a copy
  963. * of the handler object as required. The function signature of the function
  964. * object must be: @code void function(); @endcode
  965. *
  966. * @param a An allocator that may be used by the executor to allocate the
  967. * internal storage needed for function invocation.
  968. */
  969. template <typename Function, typename OtherAllocator>
  970. void dispatch(BOOST_ASIO_MOVE_ARG(Function) f,
  971. const OtherAllocator& a) const;
  972. /// Request the io_context to invoke the given function object.
  973. /**
  974. * This function is used to ask the io_context to execute the given function
  975. * object. The function object will never be executed inside @c post().
  976. * Instead, it will be scheduled to run on the io_context.
  977. *
  978. * @param f The function object to be called. The executor will make a copy
  979. * of the handler object as required. The function signature of the function
  980. * object must be: @code void function(); @endcode
  981. *
  982. * @param a An allocator that may be used by the executor to allocate the
  983. * internal storage needed for function invocation.
  984. */
  985. template <typename Function, typename OtherAllocator>
  986. void post(BOOST_ASIO_MOVE_ARG(Function) f,
  987. const OtherAllocator& a) const;
  988. /// Request the io_context to invoke the given function object.
  989. /**
  990. * This function is used to ask the io_context to execute the given function
  991. * object. The function object will never be executed inside @c defer().
  992. * Instead, it will be scheduled to run on the io_context.
  993. *
  994. * If the current thread belongs to the io_context, @c defer() will delay
  995. * scheduling the function object until the current thread returns control to
  996. * the pool.
  997. *
  998. * @param f The function object to be called. The executor will make a copy
  999. * of the handler object as required. The function signature of the function
  1000. * object must be: @code void function(); @endcode
  1001. *
  1002. * @param a An allocator that may be used by the executor to allocate the
  1003. * internal storage needed for function invocation.
  1004. */
  1005. template <typename Function, typename OtherAllocator>
  1006. void defer(BOOST_ASIO_MOVE_ARG(Function) f,
  1007. const OtherAllocator& a) const;
  1008. #endif // !defined(BOOST_ASIO_NO_TS_EXECUTORS)
  1009. private:
  1010. friend class io_context;
  1011. template <typename, uintptr_t> friend class basic_executor_type;
  1012. // Constructor used by io_context::get_executor().
  1013. explicit basic_executor_type(io_context& i) BOOST_ASIO_NOEXCEPT
  1014. : Allocator(),
  1015. target_(reinterpret_cast<uintptr_t>(&i))
  1016. {
  1017. if (Bits & outstanding_work_tracked)
  1018. context_ptr()->impl_.work_started();
  1019. }
  1020. // Constructor used by require().
  1021. basic_executor_type(io_context* i,
  1022. const Allocator& a, uintptr_t bits) BOOST_ASIO_NOEXCEPT
  1023. : Allocator(a),
  1024. target_(reinterpret_cast<uintptr_t>(i) | bits)
  1025. {
  1026. if (Bits & outstanding_work_tracked)
  1027. if (context_ptr())
  1028. context_ptr()->impl_.work_started();
  1029. }
  1030. io_context* context_ptr() const BOOST_ASIO_NOEXCEPT
  1031. {
  1032. return reinterpret_cast<io_context*>(target_ & ~runtime_bits);
  1033. }
  1034. uintptr_t bits() const BOOST_ASIO_NOEXCEPT
  1035. {
  1036. return target_ & runtime_bits;
  1037. }
  1038. // The underlying io_context and runtime bits.
  1039. uintptr_t target_;
  1040. };
  1041. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  1042. /// (Deprecated: Use executor_work_guard.) Class to inform the io_context when
  1043. /// it has work to do.
  1044. /**
  1045. * The work class is used to inform the io_context when work starts and
  1046. * finishes. This ensures that the io_context object's run() function will not
  1047. * exit while work is underway, and that it does exit when there is no
  1048. * unfinished work remaining.
  1049. *
  1050. * The work class is copy-constructible so that it may be used as a data member
  1051. * in a handler class. It is not assignable.
  1052. */
  1053. class io_context::work
  1054. {
  1055. public:
  1056. /// Constructor notifies the io_context that work is starting.
  1057. /**
  1058. * The constructor is used to inform the io_context that some work has begun.
  1059. * This ensures that the io_context object's run() function will not exit
  1060. * while the work is underway.
  1061. */
  1062. explicit work(boost::asio::io_context& io_context);
  1063. /// Copy constructor notifies the io_context that work is starting.
  1064. /**
  1065. * The constructor is used to inform the io_context that some work has begun.
  1066. * This ensures that the io_context object's run() function will not exit
  1067. * while the work is underway.
  1068. */
  1069. work(const work& other);
  1070. /// Destructor notifies the io_context that the work is complete.
  1071. /**
  1072. * The destructor is used to inform the io_context that some work has
  1073. * finished. Once the count of unfinished work reaches zero, the io_context
  1074. * object's run() function is permitted to exit.
  1075. */
  1076. ~work();
  1077. /// Get the io_context associated with the work.
  1078. boost::asio::io_context& get_io_context();
  1079. private:
  1080. // Prevent assignment.
  1081. void operator=(const work& other);
  1082. // The io_context implementation.
  1083. detail::io_context_impl& io_context_impl_;
  1084. };
  1085. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  1086. /// Base class for all io_context services.
  1087. class io_context::service
  1088. : public execution_context::service
  1089. {
  1090. public:
  1091. /// Get the io_context object that owns the service.
  1092. boost::asio::io_context& get_io_context();
  1093. private:
  1094. /// Destroy all user-defined handler objects owned by the service.
  1095. BOOST_ASIO_DECL virtual void shutdown();
  1096. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  1097. /// (Deprecated: Use shutdown().) Destroy all user-defined handler objects
  1098. /// owned by the service.
  1099. BOOST_ASIO_DECL virtual void shutdown_service();
  1100. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  1101. /// Handle notification of a fork-related event to perform any necessary
  1102. /// housekeeping.
  1103. /**
  1104. * This function is not a pure virtual so that services only have to
  1105. * implement it if necessary. The default implementation does nothing.
  1106. */
  1107. BOOST_ASIO_DECL virtual void notify_fork(
  1108. execution_context::fork_event event);
  1109. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  1110. /// (Deprecated: Use notify_fork().) Handle notification of a fork-related
  1111. /// event to perform any necessary housekeeping.
  1112. /**
  1113. * This function is not a pure virtual so that services only have to
  1114. * implement it if necessary. The default implementation does nothing.
  1115. */
  1116. BOOST_ASIO_DECL virtual void fork_service(
  1117. execution_context::fork_event event);
  1118. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  1119. protected:
  1120. /// Constructor.
  1121. /**
  1122. * @param owner The io_context object that owns the service.
  1123. */
  1124. BOOST_ASIO_DECL service(boost::asio::io_context& owner);
  1125. /// Destructor.
  1126. BOOST_ASIO_DECL virtual ~service();
  1127. };
  1128. namespace detail {
  1129. // Special service base class to keep classes header-file only.
  1130. template <typename Type>
  1131. class service_base
  1132. : public boost::asio::io_context::service
  1133. {
  1134. public:
  1135. static boost::asio::detail::service_id<Type> id;
  1136. // Constructor.
  1137. service_base(boost::asio::io_context& io_context)
  1138. : boost::asio::io_context::service(io_context)
  1139. {
  1140. }
  1141. };
  1142. template <typename Type>
  1143. boost::asio::detail::service_id<Type> service_base<Type>::id;
  1144. } // namespace detail
  1145. #if !defined(GENERATING_DOCUMENTATION)
  1146. namespace traits {
  1147. #if !defined(BOOST_ASIO_HAS_DEDUCED_EQUALITY_COMPARABLE_TRAIT)
  1148. template <typename Allocator, uintptr_t Bits>
  1149. struct equality_comparable<
  1150. boost::asio::io_context::basic_executor_type<Allocator, Bits>
  1151. >
  1152. {
  1153. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1154. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = true);
  1155. };
  1156. #endif // !defined(BOOST_ASIO_HAS_DEDUCED_EQUALITY_COMPARABLE_TRAIT)
  1157. #if !defined(BOOST_ASIO_HAS_DEDUCED_EXECUTE_MEMBER_TRAIT)
  1158. template <typename Allocator, uintptr_t Bits, typename Function>
  1159. struct execute_member<
  1160. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1161. Function
  1162. >
  1163. {
  1164. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1165. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = false);
  1166. typedef void result_type;
  1167. };
  1168. #endif // !defined(BOOST_ASIO_HAS_DEDUCED_EXECUTE_MEMBER_TRAIT)
  1169. #if !defined(BOOST_ASIO_HAS_DEDUCED_REQUIRE_MEMBER_TRAIT)
  1170. template <typename Allocator, uintptr_t Bits>
  1171. struct require_member<
  1172. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1173. boost::asio::execution::blocking_t::possibly_t
  1174. >
  1175. {
  1176. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1177. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = false);
  1178. typedef boost::asio::io_context::basic_executor_type<
  1179. Allocator, Bits> result_type;
  1180. };
  1181. template <typename Allocator, uintptr_t Bits>
  1182. struct require_member<
  1183. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1184. boost::asio::execution::blocking_t::never_t
  1185. >
  1186. {
  1187. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1188. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = false);
  1189. typedef boost::asio::io_context::basic_executor_type<
  1190. Allocator, Bits> result_type;
  1191. };
  1192. template <typename Allocator, uintptr_t Bits>
  1193. struct require_member<
  1194. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1195. boost::asio::execution::relationship_t::fork_t
  1196. >
  1197. {
  1198. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1199. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = false);
  1200. typedef boost::asio::io_context::basic_executor_type<
  1201. Allocator, Bits> result_type;
  1202. };
  1203. template <typename Allocator, uintptr_t Bits>
  1204. struct require_member<
  1205. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1206. boost::asio::execution::relationship_t::continuation_t
  1207. >
  1208. {
  1209. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1210. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = false);
  1211. typedef boost::asio::io_context::basic_executor_type<
  1212. Allocator, Bits> result_type;
  1213. };
  1214. template <typename Allocator, uintptr_t Bits>
  1215. struct require_member<
  1216. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1217. boost::asio::execution::outstanding_work_t::tracked_t
  1218. > : boost::asio::detail::io_context_bits
  1219. {
  1220. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1221. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = false);
  1222. typedef boost::asio::io_context::basic_executor_type<
  1223. Allocator, Bits | outstanding_work_tracked> result_type;
  1224. };
  1225. template <typename Allocator, uintptr_t Bits>
  1226. struct require_member<
  1227. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1228. boost::asio::execution::outstanding_work_t::untracked_t
  1229. > : boost::asio::detail::io_context_bits
  1230. {
  1231. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1232. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = false);
  1233. typedef boost::asio::io_context::basic_executor_type<
  1234. Allocator, Bits & ~outstanding_work_tracked> result_type;
  1235. };
  1236. template <typename Allocator, uintptr_t Bits>
  1237. struct require_member<
  1238. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1239. boost::asio::execution::allocator_t<void>
  1240. >
  1241. {
  1242. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1243. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = false);
  1244. typedef boost::asio::io_context::basic_executor_type<
  1245. std::allocator<void>, Bits> result_type;
  1246. };
  1247. template <uintptr_t Bits,
  1248. typename Allocator, typename OtherAllocator>
  1249. struct require_member<
  1250. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1251. boost::asio::execution::allocator_t<OtherAllocator>
  1252. >
  1253. {
  1254. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1255. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = false);
  1256. typedef boost::asio::io_context::basic_executor_type<
  1257. OtherAllocator, Bits> result_type;
  1258. };
  1259. #endif // !defined(BOOST_ASIO_HAS_DEDUCED_REQUIRE_MEMBER_TRAIT)
  1260. #if !defined(BOOST_ASIO_HAS_DEDUCED_QUERY_STATIC_CONSTEXPR_MEMBER_TRAIT)
  1261. template <typename Allocator, uintptr_t Bits, typename Property>
  1262. struct query_static_constexpr_member<
  1263. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1264. Property,
  1265. typename boost::asio::enable_if<
  1266. boost::asio::is_convertible<
  1267. Property,
  1268. boost::asio::execution::outstanding_work_t
  1269. >::value
  1270. >::type
  1271. > : boost::asio::detail::io_context_bits
  1272. {
  1273. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1274. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = true);
  1275. typedef boost::asio::execution::outstanding_work_t result_type;
  1276. static BOOST_ASIO_CONSTEXPR result_type value() BOOST_ASIO_NOEXCEPT
  1277. {
  1278. return (Bits & outstanding_work_tracked)
  1279. ? execution::outstanding_work_t(execution::outstanding_work.tracked)
  1280. : execution::outstanding_work_t(execution::outstanding_work.untracked);
  1281. }
  1282. };
  1283. template <typename Allocator, uintptr_t Bits, typename Property>
  1284. struct query_static_constexpr_member<
  1285. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1286. Property,
  1287. typename boost::asio::enable_if<
  1288. boost::asio::is_convertible<
  1289. Property,
  1290. boost::asio::execution::mapping_t
  1291. >::value
  1292. >::type
  1293. >
  1294. {
  1295. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1296. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = true);
  1297. typedef boost::asio::execution::mapping_t::thread_t result_type;
  1298. static BOOST_ASIO_CONSTEXPR result_type value() BOOST_ASIO_NOEXCEPT
  1299. {
  1300. return result_type();
  1301. }
  1302. };
  1303. #endif // !defined(BOOST_ASIO_HAS_DEDUCED_QUERY_STATIC_CONSTEXPR_MEMBER_TRAIT)
  1304. #if !defined(BOOST_ASIO_HAS_DEDUCED_QUERY_MEMBER_TRAIT)
  1305. template <typename Allocator, uintptr_t Bits, typename Property>
  1306. struct query_member<
  1307. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1308. Property,
  1309. typename boost::asio::enable_if<
  1310. boost::asio::is_convertible<
  1311. Property,
  1312. boost::asio::execution::blocking_t
  1313. >::value
  1314. >::type
  1315. >
  1316. {
  1317. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1318. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = true);
  1319. typedef boost::asio::execution::blocking_t result_type;
  1320. };
  1321. template <typename Allocator, uintptr_t Bits, typename Property>
  1322. struct query_member<
  1323. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1324. Property,
  1325. typename boost::asio::enable_if<
  1326. boost::asio::is_convertible<
  1327. Property,
  1328. boost::asio::execution::relationship_t
  1329. >::value
  1330. >::type
  1331. >
  1332. {
  1333. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1334. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = true);
  1335. typedef boost::asio::execution::relationship_t result_type;
  1336. };
  1337. template <typename Allocator, uintptr_t Bits>
  1338. struct query_member<
  1339. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1340. boost::asio::execution::context_t
  1341. >
  1342. {
  1343. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1344. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = true);
  1345. typedef boost::asio::io_context& result_type;
  1346. };
  1347. template <typename Allocator, uintptr_t Bits>
  1348. struct query_member<
  1349. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1350. boost::asio::execution::allocator_t<void>
  1351. >
  1352. {
  1353. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1354. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = true);
  1355. typedef Allocator result_type;
  1356. };
  1357. template <typename Allocator, uintptr_t Bits, typename OtherAllocator>
  1358. struct query_member<
  1359. boost::asio::io_context::basic_executor_type<Allocator, Bits>,
  1360. boost::asio::execution::allocator_t<OtherAllocator>
  1361. >
  1362. {
  1363. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_valid = true);
  1364. BOOST_ASIO_STATIC_CONSTEXPR(bool, is_noexcept = true);
  1365. typedef Allocator result_type;
  1366. };
  1367. #endif // !defined(BOOST_ASIO_HAS_DEDUCED_QUERY_MEMBER_TRAIT)
  1368. } // namespace traits
  1369. namespace execution {
  1370. template <>
  1371. struct is_executor<io_context> : false_type
  1372. {
  1373. };
  1374. } // namespace execution
  1375. #endif // !defined(GENERATING_DOCUMENTATION)
  1376. } // namespace asio
  1377. } // namespace boost
  1378. #include <boost/asio/detail/pop_options.hpp>
  1379. #include <boost/asio/impl/io_context.hpp>
  1380. #if defined(BOOST_ASIO_HEADER_ONLY)
  1381. # include <boost/asio/impl/io_context.ipp>
  1382. #endif // defined(BOOST_ASIO_HEADER_ONLY)
  1383. // If both io_context.hpp and strand.hpp have been included, automatically
  1384. // include the header file needed for the io_context::strand class.
  1385. #if !defined(BOOST_ASIO_NO_EXTENSIONS)
  1386. # if defined(BOOST_ASIO_STRAND_HPP)
  1387. # include <boost/asio/io_context_strand.hpp>
  1388. # endif // defined(BOOST_ASIO_STRAND_HPP)
  1389. #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
  1390. #endif // BOOST_ASIO_IO_CONTEXT_HPP