/Src/Dependencies/Boost/boost/asio/io_service.hpp

http://hadesmem.googlecode.com/ · C++ Header · 772 lines · 177 code · 66 blank · 529 comment · 11 complexity · cc5e0598f626826a94b0015476cd9328 MD5 · raw file

  1. //
  2. // io_service.hpp
  3. // ~~~~~~~~~~~~~~
  4. //
  5. // Copyright (c) 2003-2011 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_SERVICE_HPP
  11. #define BOOST_ASIO_IO_SERVICE_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/detail/noncopyable.hpp>
  20. #include <boost/asio/detail/service_registry_fwd.hpp>
  21. #include <boost/asio/detail/wrapped_handler.hpp>
  22. #include <boost/system/error_code.hpp>
  23. #if defined(BOOST_ASIO_HAS_IOCP)
  24. # include <boost/asio/detail/win_iocp_io_service_fwd.hpp>
  25. #else
  26. # include <boost/asio/detail/task_io_service_fwd.hpp>
  27. #endif
  28. #if defined(BOOST_WINDOWS) || defined(__CYGWIN__)
  29. # include <boost/asio/detail/winsock_init.hpp>
  30. #elif defined(__sun) || defined(__QNX__) || defined(__hpux) || defined(_AIX) \
  31. || defined(__osf__)
  32. # include <boost/asio/detail/signal_init.hpp>
  33. #endif
  34. #include <boost/asio/detail/push_options.hpp>
  35. namespace boost {
  36. namespace asio {
  37. class io_service;
  38. template <typename Service> Service& use_service(io_service& ios);
  39. template <typename Service> void add_service(io_service& ios, Service* svc);
  40. template <typename Service> bool has_service(io_service& ios);
  41. #if defined(BOOST_ASIO_HAS_IOCP)
  42. namespace detail { typedef win_iocp_io_service io_service_impl; }
  43. #else
  44. namespace detail { typedef task_io_service io_service_impl; }
  45. #endif
  46. /// Provides core I/O functionality.
  47. /**
  48. * The io_service class provides the core I/O functionality for users of the
  49. * asynchronous I/O objects, including:
  50. *
  51. * @li boost::asio::ip::tcp::socket
  52. * @li boost::asio::ip::tcp::acceptor
  53. * @li boost::asio::ip::udp::socket
  54. * @li boost::asio::deadline_timer.
  55. *
  56. * The io_service class also includes facilities intended for developers of
  57. * custom asynchronous services.
  58. *
  59. * @par Thread Safety
  60. * @e Distinct @e objects: Safe.@n
  61. * @e Shared @e objects: Safe, with the specific exceptions of the reset() and
  62. * notify_fork() functions. Calling reset() while there are unfinished run(),
  63. * run_one(), poll() or poll_one() calls results in undefined behaviour. The
  64. * notify_fork() function should not be called while any io_service function,
  65. * or any function on an I/O object that is associated with the io_service, is
  66. * being called in another thread.
  67. *
  68. * @par Concepts:
  69. * Dispatcher.
  70. *
  71. * @par Synchronous and asynchronous operations
  72. *
  73. * Synchronous operations on I/O objects implicitly run the io_service object
  74. * for an individual operation. The io_service functions run(), run_one(),
  75. * poll() or poll_one() must be called for the io_service to perform
  76. * asynchronous operations on behalf of a C++ program. Notification that an
  77. * asynchronous operation has completed is delivered by invocation of the
  78. * associated handler. Handlers are invoked only by a thread that is currently
  79. * calling any overload of run(), run_one(), poll() or poll_one() for the
  80. * io_service.
  81. *
  82. * @par Effect of exceptions thrown from handlers
  83. *
  84. * If an exception is thrown from a handler, the exception is allowed to
  85. * propagate through the throwing thread's invocation of run(), run_one(),
  86. * poll() or poll_one(). No other threads that are calling any of these
  87. * functions are affected. It is then the responsibility of the application to
  88. * catch the exception.
  89. *
  90. * After the exception has been caught, the run(), run_one(), poll() or
  91. * poll_one() call may be restarted @em without the need for an intervening
  92. * call to reset(). This allows the thread to rejoin the io_service object's
  93. * thread pool without impacting any other threads in the pool.
  94. *
  95. * For example:
  96. *
  97. * @code
  98. * boost::asio::io_service io_service;
  99. * ...
  100. * for (;;)
  101. * {
  102. * try
  103. * {
  104. * io_service.run();
  105. * break; // run() exited normally
  106. * }
  107. * catch (my_exception& e)
  108. * {
  109. * // Deal with exception as appropriate.
  110. * }
  111. * }
  112. * @endcode
  113. *
  114. * @par Stopping the io_service from running out of work
  115. *
  116. * Some applications may need to prevent an io_service object's run() call from
  117. * returning when there is no more work to do. For example, the io_service may
  118. * be being run in a background thread that is launched prior to the
  119. * application's asynchronous operations. The run() call may be kept running by
  120. * creating an object of type boost::asio::io_service::work:
  121. *
  122. * @code boost::asio::io_service io_service;
  123. * boost::asio::io_service::work work(io_service);
  124. * ... @endcode
  125. *
  126. * To effect a shutdown, the application will then need to call the io_service
  127. * object's stop() member function. This will cause the io_service run() call
  128. * to return as soon as possible, abandoning unfinished operations and without
  129. * permitting ready handlers to be dispatched.
  130. *
  131. * Alternatively, if the application requires that all operations and handlers
  132. * be allowed to finish normally, the work object may be explicitly destroyed.
  133. *
  134. * @code boost::asio::io_service io_service;
  135. * auto_ptr<boost::asio::io_service::work> work(
  136. * new boost::asio::io_service::work(io_service));
  137. * ...
  138. * work.reset(); // Allow run() to exit. @endcode
  139. *
  140. * @par The io_service class and I/O services
  141. *
  142. * Class io_service implements an extensible, type-safe, polymorphic set of I/O
  143. * services, indexed by service type. An object of class io_service must be
  144. * initialised before I/O objects such as sockets, resolvers and timers can be
  145. * used. These I/O objects are distinguished by having constructors that accept
  146. * an @c io_service& parameter.
  147. *
  148. * I/O services exist to manage the logical interface to the operating system on
  149. * behalf of the I/O objects. In particular, there are resources that are shared
  150. * across a class of I/O objects. For example, timers may be implemented in
  151. * terms of a single timer queue. The I/O services manage these shared
  152. * resources.
  153. *
  154. * Access to the services of an io_service is via three function templates,
  155. * use_service(), add_service() and has_service().
  156. *
  157. * In a call to @c use_service<Service>(), the type argument chooses a service,
  158. * making available all members of the named type. If @c Service is not present
  159. * in an io_service, an object of type @c Service is created and added to the
  160. * io_service. A C++ program can check if an io_service implements a
  161. * particular service with the function template @c has_service<Service>().
  162. *
  163. * Service objects may be explicitly added to an io_service using the function
  164. * template @c add_service<Service>(). If the @c Service is already present, the
  165. * service_already_exists exception is thrown. If the owner of the service is
  166. * not the same object as the io_service parameter, the invalid_service_owner
  167. * exception is thrown.
  168. *
  169. * Once a service reference is obtained from an io_service object by calling
  170. * use_service(), that reference remains usable as long as the owning io_service
  171. * object exists.
  172. *
  173. * All I/O service implementations have io_service::service as a public base
  174. * class. Custom I/O services may be implemented by deriving from this class and
  175. * then added to an io_service using the facilities described above.
  176. */
  177. class io_service
  178. : private noncopyable
  179. {
  180. private:
  181. typedef detail::io_service_impl impl_type;
  182. #if defined(BOOST_ASIO_HAS_IOCP)
  183. friend class detail::win_iocp_overlapped_ptr;
  184. #endif
  185. public:
  186. class work;
  187. friend class work;
  188. class id;
  189. class service;
  190. class strand;
  191. /// Constructor.
  192. BOOST_ASIO_DECL io_service();
  193. /// Constructor.
  194. /**
  195. * Construct with a hint about the required level of concurrency.
  196. *
  197. * @param concurrency_hint A suggestion to the implementation on how many
  198. * threads it should allow to run simultaneously.
  199. */
  200. BOOST_ASIO_DECL explicit io_service(std::size_t concurrency_hint);
  201. /// Destructor.
  202. /**
  203. * On destruction, the io_service performs the following sequence of
  204. * operations:
  205. *
  206. * @li For each service object @c svc in the io_service set, in reverse order
  207. * of the beginning of service object lifetime, performs
  208. * @c svc->shutdown_service().
  209. *
  210. * @li Uninvoked handler objects that were scheduled for deferred invocation
  211. * on the io_service, or any associated strand, are destroyed.
  212. *
  213. * @li For each service object @c svc in the io_service set, in reverse order
  214. * of the beginning of service object lifetime, performs
  215. * <tt>delete static_cast<io_service::service*>(svc)</tt>.
  216. *
  217. * @note The destruction sequence described above permits programs to
  218. * simplify their resource management by using @c shared_ptr<>. Where an
  219. * object's lifetime is tied to the lifetime of a connection (or some other
  220. * sequence of asynchronous operations), a @c shared_ptr to the object would
  221. * be bound into the handlers for all asynchronous operations associated with
  222. * it. This works as follows:
  223. *
  224. * @li When a single connection ends, all associated asynchronous operations
  225. * complete. The corresponding handler objects are destroyed, and all
  226. * @c shared_ptr references to the objects are destroyed.
  227. *
  228. * @li To shut down the whole program, the io_service function stop() is
  229. * called to terminate any run() calls as soon as possible. The io_service
  230. * destructor defined above destroys all handlers, causing all @c shared_ptr
  231. * references to all connection objects to be destroyed.
  232. */
  233. BOOST_ASIO_DECL ~io_service();
  234. /// Run the io_service object's event processing loop.
  235. /**
  236. * The run() function blocks until all work has finished and there are no
  237. * more handlers to be dispatched, or until the io_service has been stopped.
  238. *
  239. * Multiple threads may call the run() function to set up a pool of threads
  240. * from which the io_service may execute handlers. All threads that are
  241. * waiting in the pool are equivalent and the io_service may choose any one
  242. * of them to invoke a handler.
  243. *
  244. * A normal exit from the run() function implies that the io_service object
  245. * is stopped (the stopped() function returns @c true). Subsequent calls to
  246. * run(), run_one(), poll() or poll_one() will return immediately unless there
  247. * is a prior call to reset().
  248. *
  249. * @return The number of handlers that were executed.
  250. *
  251. * @throws boost::system::system_error Thrown on failure.
  252. *
  253. * @note The run() function must not be called from a thread that is currently
  254. * calling one of run(), run_one(), poll() or poll_one() on the same
  255. * io_service object.
  256. *
  257. * The poll() function may also be used to dispatch ready handlers, but
  258. * without blocking.
  259. */
  260. BOOST_ASIO_DECL std::size_t run();
  261. /// Run the io_service object's event processing loop.
  262. /**
  263. * The run() function blocks until all work has finished and there are no
  264. * more handlers to be dispatched, or until the io_service has been stopped.
  265. *
  266. * Multiple threads may call the run() function to set up a pool of threads
  267. * from which the io_service may execute handlers. All threads that are
  268. * waiting in the pool are equivalent and the io_service may choose any one
  269. * of them to invoke a handler.
  270. *
  271. * A normal exit from the run() function implies that the io_service object
  272. * is stopped (the stopped() function returns @c true). Subsequent calls to
  273. * run(), run_one(), poll() or poll_one() will return immediately unless there
  274. * is a prior call to reset().
  275. *
  276. * @param ec Set to indicate what error occurred, if any.
  277. *
  278. * @return The number of handlers that were executed.
  279. *
  280. * @note The run() function must not be called from a thread that is currently
  281. * calling one of run(), run_one(), poll() or poll_one() on the same
  282. * io_service object.
  283. *
  284. * The poll() function may also be used to dispatch ready handlers, but
  285. * without blocking.
  286. */
  287. BOOST_ASIO_DECL std::size_t run(boost::system::error_code& ec);
  288. /// Run the io_service object's event processing loop to execute at most one
  289. /// handler.
  290. /**
  291. * The run_one() function blocks until one handler has been dispatched, or
  292. * until the io_service has been stopped.
  293. *
  294. * @return The number of handlers that were executed. A zero return value
  295. * implies that the io_service object is stopped (the stopped() function
  296. * returns @c true). Subsequent calls to run(), run_one(), poll() or
  297. * poll_one() will return immediately unless there is a prior call to
  298. * reset().
  299. *
  300. * @throws boost::system::system_error Thrown on failure.
  301. */
  302. BOOST_ASIO_DECL std::size_t run_one();
  303. /// Run the io_service object's event processing loop to execute at most one
  304. /// handler.
  305. /**
  306. * The run_one() function blocks until one handler has been dispatched, or
  307. * until the io_service has been stopped.
  308. *
  309. * @return The number of handlers that were executed. A zero return value
  310. * implies that the io_service object is stopped (the stopped() function
  311. * returns @c true). Subsequent calls to run(), run_one(), poll() or
  312. * poll_one() will return immediately unless there is a prior call to
  313. * reset().
  314. *
  315. * @return The number of handlers that were executed.
  316. */
  317. BOOST_ASIO_DECL std::size_t run_one(boost::system::error_code& ec);
  318. /// Run the io_service object's event processing loop to execute ready
  319. /// handlers.
  320. /**
  321. * The poll() function runs handlers that are ready to run, without blocking,
  322. * until the io_service has been stopped or there are no more ready handlers.
  323. *
  324. * @return The number of handlers that were executed.
  325. *
  326. * @throws boost::system::system_error Thrown on failure.
  327. */
  328. BOOST_ASIO_DECL std::size_t poll();
  329. /// Run the io_service object's event processing loop to execute ready
  330. /// handlers.
  331. /**
  332. * The poll() function runs handlers that are ready to run, without blocking,
  333. * until the io_service has been stopped or there are no more ready handlers.
  334. *
  335. * @param ec Set to indicate what error occurred, if any.
  336. *
  337. * @return The number of handlers that were executed.
  338. */
  339. BOOST_ASIO_DECL std::size_t poll(boost::system::error_code& ec);
  340. /// Run the io_service object's event processing loop to execute one ready
  341. /// handler.
  342. /**
  343. * The poll_one() function runs at most one handler that is ready to run,
  344. * without blocking.
  345. *
  346. * @return The number of handlers that were executed.
  347. *
  348. * @throws boost::system::system_error Thrown on failure.
  349. */
  350. BOOST_ASIO_DECL std::size_t poll_one();
  351. /// Run the io_service object's event processing loop to execute one ready
  352. /// handler.
  353. /**
  354. * The poll_one() function runs at most one handler that is ready to run,
  355. * without blocking.
  356. *
  357. * @param ec Set to indicate what error occurred, if any.
  358. *
  359. * @return The number of handlers that were executed.
  360. */
  361. BOOST_ASIO_DECL std::size_t poll_one(boost::system::error_code& ec);
  362. /// Stop the io_service object's event processing loop.
  363. /**
  364. * This function does not block, but instead simply signals the io_service to
  365. * stop. All invocations of its run() or run_one() member functions should
  366. * return as soon as possible. Subsequent calls to run(), run_one(), poll()
  367. * or poll_one() will return immediately until reset() is called.
  368. */
  369. BOOST_ASIO_DECL void stop();
  370. /// Determine whether the io_service object has been stopped.
  371. /**
  372. * This function is used to determine whether an io_service object has been
  373. * stopped, either through an explicit call to stop(), or due to running out
  374. * of work. When an io_service object is stopped, calls to run(), run_one(),
  375. * poll() or poll_one() will return immediately without invoking any
  376. * handlers.
  377. *
  378. * @return @c true if the io_service object is stopped, otherwise @c false.
  379. */
  380. BOOST_ASIO_DECL bool stopped() const;
  381. /// Reset the io_service in preparation for a subsequent run() invocation.
  382. /**
  383. * This function must be called prior to any second or later set of
  384. * invocations of the run(), run_one(), poll() or poll_one() functions when a
  385. * previous invocation of these functions returned due to the io_service
  386. * being stopped or running out of work. After a call to reset(), the
  387. * io_service object's stopped() function will return @c false.
  388. *
  389. * This function must not be called while there are any unfinished calls to
  390. * the run(), run_one(), poll() or poll_one() functions.
  391. */
  392. BOOST_ASIO_DECL void reset();
  393. /// Request the io_service to invoke the given handler.
  394. /**
  395. * This function is used to ask the io_service to execute the given handler.
  396. *
  397. * The io_service guarantees that the handler will only be called in a thread
  398. * in which the run(), run_one(), poll() or poll_one() member functions is
  399. * currently being invoked. The handler may be executed inside this function
  400. * if the guarantee can be met.
  401. *
  402. * @param handler The handler to be called. The io_service will make
  403. * a copy of the handler object as required. The function signature of the
  404. * handler must be: @code void handler(); @endcode
  405. *
  406. * @note This function throws an exception only if:
  407. *
  408. * @li the handler's @c asio_handler_allocate function; or
  409. *
  410. * @li the handler's copy constructor
  411. *
  412. * throws an exception.
  413. */
  414. template <typename CompletionHandler>
  415. void dispatch(BOOST_ASIO_MOVE_ARG(CompletionHandler) handler);
  416. /// Request the io_service to invoke the given handler and return immediately.
  417. /**
  418. * This function is used to ask the io_service to execute the given handler,
  419. * but without allowing the io_service to call the handler from inside this
  420. * function.
  421. *
  422. * The io_service guarantees that the handler will only be called in a thread
  423. * in which the run(), run_one(), poll() or poll_one() member functions is
  424. * currently being invoked.
  425. *
  426. * @param handler The handler to be called. The io_service will make
  427. * a copy of the handler object as required. The function signature of the
  428. * handler must be: @code void handler(); @endcode
  429. *
  430. * @note This function throws an exception only if:
  431. *
  432. * @li the handler's @c asio_handler_allocate function; or
  433. *
  434. * @li the handler's copy constructor
  435. *
  436. * throws an exception.
  437. */
  438. template <typename CompletionHandler>
  439. void post(BOOST_ASIO_MOVE_ARG(CompletionHandler) handler);
  440. /// Create a new handler that automatically dispatches the wrapped handler
  441. /// on the io_service.
  442. /**
  443. * This function is used to create a new handler function object that, when
  444. * invoked, will automatically pass the wrapped handler to the io_service
  445. * object's dispatch function.
  446. *
  447. * @param handler The handler to be wrapped. The io_service will make a copy
  448. * of the handler object as required. The function signature of the handler
  449. * must be: @code void handler(A1 a1, ... An an); @endcode
  450. *
  451. * @return A function object that, when invoked, passes the wrapped handler to
  452. * the io_service object's dispatch function. Given a function object with the
  453. * signature:
  454. * @code R f(A1 a1, ... An an); @endcode
  455. * If this function object is passed to the wrap function like so:
  456. * @code io_service.wrap(f); @endcode
  457. * then the return value is a function object with the signature
  458. * @code void g(A1 a1, ... An an); @endcode
  459. * that, when invoked, executes code equivalent to:
  460. * @code io_service.dispatch(boost::bind(f, a1, ... an)); @endcode
  461. */
  462. template <typename Handler>
  463. #if defined(GENERATING_DOCUMENTATION)
  464. unspecified
  465. #else
  466. detail::wrapped_handler<io_service&, Handler>
  467. #endif
  468. wrap(Handler handler);
  469. /// Fork-related event notifications.
  470. enum fork_event
  471. {
  472. /// Notify the io_service that the process is about to fork.
  473. fork_prepare,
  474. /// Notify the io_service that the process has forked and is the parent.
  475. fork_parent,
  476. /// Notify the io_service that the process has forked and is the child.
  477. fork_child
  478. };
  479. /// Notify the io_service of a fork-related event.
  480. /**
  481. * This function is used to inform the io_service that the process is about
  482. * to fork, or has just forked. This allows the io_service, and the services
  483. * it contains, to perform any necessary housekeeping to ensure correct
  484. * operation following a fork.
  485. *
  486. * This function must not be called while any other io_service function, or
  487. * any function on an I/O object associated with the io_service, is being
  488. * called in another thread. It is, however, safe to call this function from
  489. * within a completion handler, provided no other thread is accessing the
  490. * io_service.
  491. *
  492. * @param event A fork-related event.
  493. *
  494. * @throws boost::system::system_error Thrown on failure. If the notification
  495. * fails the io_service object should no longer be used and should be
  496. * destroyed.
  497. *
  498. * @par Example
  499. * The following code illustrates how to incorporate the notify_fork()
  500. * function:
  501. * @code my_io_service.notify_fork(boost::asio::io_service::fork_prepare);
  502. * if (fork() == 0)
  503. * {
  504. * // This is the child process.
  505. * my_io_service.notify_fork(boost::asio::io_service::fork_child);
  506. * }
  507. * else
  508. * {
  509. * // This is the parent process.
  510. * my_io_service.notify_fork(boost::asio::io_service::fork_parent);
  511. * } @endcode
  512. *
  513. * @note For each service object @c svc in the io_service set, performs
  514. * <tt>svc->fork_service();</tt>. When processing the fork_prepare event,
  515. * services are visited in reverse order of the beginning of service object
  516. * lifetime. Otherwise, services are visited in order of the beginning of
  517. * service object lifetime.
  518. */
  519. BOOST_ASIO_DECL void notify_fork(boost::asio::io_service::fork_event event);
  520. /// Obtain the service object corresponding to the given type.
  521. /**
  522. * This function is used to locate a service object that corresponds to
  523. * the given service type. If there is no existing implementation of the
  524. * service, then the io_service will create a new instance of the service.
  525. *
  526. * @param ios The io_service object that owns the service.
  527. *
  528. * @return The service interface implementing the specified service type.
  529. * Ownership of the service interface is not transferred to the caller.
  530. */
  531. template <typename Service>
  532. friend Service& use_service(io_service& ios);
  533. /// Add a service object to the io_service.
  534. /**
  535. * This function is used to add a service to the io_service.
  536. *
  537. * @param ios The io_service object that owns the service.
  538. *
  539. * @param svc The service object. On success, ownership of the service object
  540. * is transferred to the io_service. When the io_service object is destroyed,
  541. * it will destroy the service object by performing:
  542. * @code delete static_cast<io_service::service*>(svc) @endcode
  543. *
  544. * @throws boost::asio::service_already_exists Thrown if a service of the
  545. * given type is already present in the io_service.
  546. *
  547. * @throws boost::asio::invalid_service_owner Thrown if the service's owning
  548. * io_service is not the io_service object specified by the ios parameter.
  549. */
  550. template <typename Service>
  551. friend void add_service(io_service& ios, Service* svc);
  552. /// Determine if an io_service contains a specified service type.
  553. /**
  554. * This function is used to determine whether the io_service contains a
  555. * service object corresponding to the given service type.
  556. *
  557. * @param ios The io_service object that owns the service.
  558. *
  559. * @return A boolean indicating whether the io_service contains the service.
  560. */
  561. template <typename Service>
  562. friend bool has_service(io_service& ios);
  563. private:
  564. #if defined(BOOST_WINDOWS) || defined(__CYGWIN__)
  565. detail::winsock_init<> init_;
  566. #elif defined(__sun) || defined(__QNX__) || defined(__hpux) || defined(_AIX) \
  567. || defined(__osf__)
  568. detail::signal_init<> init_;
  569. #endif
  570. // The service registry.
  571. boost::asio::detail::service_registry* service_registry_;
  572. // The implementation.
  573. impl_type& impl_;
  574. };
  575. /// Class to inform the io_service when it has work to do.
  576. /**
  577. * The work class is used to inform the io_service when work starts and
  578. * finishes. This ensures that the io_service object's run() function will not
  579. * exit while work is underway, and that it does exit when there is no
  580. * unfinished work remaining.
  581. *
  582. * The work class is copy-constructible so that it may be used as a data member
  583. * in a handler class. It is not assignable.
  584. */
  585. class io_service::work
  586. {
  587. public:
  588. /// Constructor notifies the io_service that work is starting.
  589. /**
  590. * The constructor is used to inform the io_service that some work has begun.
  591. * This ensures that the io_service object's run() function will not exit
  592. * while the work is underway.
  593. */
  594. explicit work(boost::asio::io_service& io_service);
  595. /// Copy constructor notifies the io_service that work is starting.
  596. /**
  597. * The constructor is used to inform the io_service that some work has begun.
  598. * This ensures that the io_service object's run() function will not exit
  599. * while the work is underway.
  600. */
  601. work(const work& other);
  602. /// Destructor notifies the io_service that the work is complete.
  603. /**
  604. * The destructor is used to inform the io_service that some work has
  605. * finished. Once the count of unfinished work reaches zero, the io_service
  606. * object's run() function is permitted to exit.
  607. */
  608. ~work();
  609. /// Get the io_service associated with the work.
  610. boost::asio::io_service& get_io_service();
  611. private:
  612. // Prevent assignment.
  613. void operator=(const work& other);
  614. // The io_service.
  615. boost::asio::io_service& io_service_;
  616. };
  617. /// Class used to uniquely identify a service.
  618. class io_service::id
  619. : private noncopyable
  620. {
  621. public:
  622. /// Constructor.
  623. id() {}
  624. };
  625. /// Base class for all io_service services.
  626. class io_service::service
  627. : private noncopyable
  628. {
  629. public:
  630. /// Get the io_service object that owns the service.
  631. boost::asio::io_service& get_io_service();
  632. protected:
  633. /// Constructor.
  634. /**
  635. * @param owner The io_service object that owns the service.
  636. */
  637. BOOST_ASIO_DECL service(boost::asio::io_service& owner);
  638. /// Destructor.
  639. BOOST_ASIO_DECL virtual ~service();
  640. private:
  641. /// Destroy all user-defined handler objects owned by the service.
  642. virtual void shutdown_service() = 0;
  643. /// Handle notification of a fork-related event to perform any necessary
  644. /// housekeeping.
  645. /**
  646. * This function is not a pure virtual so that services only have to
  647. * implement it if necessary. The default implementation does nothing.
  648. */
  649. BOOST_ASIO_DECL virtual void fork_service(
  650. boost::asio::io_service::fork_event event);
  651. friend class boost::asio::detail::service_registry;
  652. struct key
  653. {
  654. key() : type_info_(0), id_(0) {}
  655. const std::type_info* type_info_;
  656. const boost::asio::io_service::id* id_;
  657. } key_;
  658. boost::asio::io_service& owner_;
  659. service* next_;
  660. };
  661. /// Exception thrown when trying to add a duplicate service to an io_service.
  662. class service_already_exists
  663. : public std::logic_error
  664. {
  665. public:
  666. BOOST_ASIO_DECL service_already_exists();
  667. };
  668. /// Exception thrown when trying to add a service object to an io_service where
  669. /// the service has a different owner.
  670. class invalid_service_owner
  671. : public std::logic_error
  672. {
  673. public:
  674. BOOST_ASIO_DECL invalid_service_owner();
  675. };
  676. namespace detail {
  677. // Special derived service id type to keep classes header-file only.
  678. template <typename Type>
  679. class service_id
  680. : public boost::asio::io_service::id
  681. {
  682. };
  683. // Special service base class to keep classes header-file only.
  684. template <typename Type>
  685. class service_base
  686. : public boost::asio::io_service::service
  687. {
  688. public:
  689. static boost::asio::detail::service_id<Type> id;
  690. // Constructor.
  691. service_base(boost::asio::io_service& io_service)
  692. : boost::asio::io_service::service(io_service)
  693. {
  694. }
  695. };
  696. template <typename Type>
  697. boost::asio::detail::service_id<Type> service_base<Type>::id;
  698. } // namespace detail
  699. } // namespace asio
  700. } // namespace boost
  701. #include <boost/asio/detail/pop_options.hpp>
  702. #include <boost/asio/impl/io_service.hpp>
  703. #if defined(BOOST_ASIO_HEADER_ONLY)
  704. # include <boost/asio/impl/io_service.ipp>
  705. #endif // defined(BOOST_ASIO_HEADER_ONLY)
  706. #endif // BOOST_ASIO_IO_SERVICE_HPP