annotate DEPENDENCIES/generic/include/boost/asio/io_service.hpp @ 133:4acb5d8d80b6 tip

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