Documentation.
diff --git a/asio/include/asio/basic_deadline_timer.hpp b/asio/include/asio/basic_deadline_timer.hpp index 75d33b9..62e49eb 100644 --- a/asio/include/asio/basic_deadline_timer.hpp +++ b/asio/include/asio/basic_deadline_timer.hpp
@@ -34,6 +34,10 @@ * The basic_deadline_timer class template provides the ability to perform a * blocking or asynchronous wait for a timer to expire. * + * A deadline timer is always in one of two states: "expired" or "not expired". + * If the wait() or async_wait() function is called on an expired timer, the + * wait operation will complete immediately. + * * Most applications will use the asio::deadline_timer typedef. * * @par Thread Safety @@ -192,6 +196,13 @@ * @return The number of asynchronous operations that were cancelled. * * @throws asio::system_error Thrown on failure. + * + * @note If the timer has already expired when cancel() is called, then the + * handlers for asynchronous wait operations will: + * @li have already been invoked; or + * @li have been queued for invocation in the near future. + * These handlers can no longer be cancelled, and therefore are passed an + * error code that indicates the successful completion of the wait operation. */ std::size_t cancel() { @@ -212,6 +223,13 @@ * @param ec Set to indicate what error occurred, if any. * * @return The number of asynchronous operations that were cancelled. + * + * @note If the timer has already expired when cancel() is called, then the + * handlers for asynchronous wait operations will: + * @li have already been invoked; or + * @li have been queued for invocation in the near future. + * These handlers can no longer be cancelled, and therefore are passed an + * error code that indicates the successful completion of the wait operation. */ std::size_t cancel(asio::error_code& ec) { @@ -239,6 +257,13 @@ * @return The number of asynchronous operations that were cancelled. * * @throws asio::system_error Thrown on failure. + * + * @note If the timer has already expired when expires_at() is called, then + * the handlers for asynchronous wait operations will: + * @li have already been invoked; or + * @li have been queued for invocation in the near future. + * These handlers can no longer be cancelled, and therefore are passed an + * error code that indicates the successful completion of the wait operation. */ std::size_t expires_at(const time_type& expiry_time) { @@ -260,6 +285,13 @@ * @param ec Set to indicate what error occurred, if any. * * @return The number of asynchronous operations that were cancelled. + * + * @note If the timer has already expired when expires_at() is called, then + * the handlers for asynchronous wait operations will: + * @li have already been invoked; or + * @li have been queued for invocation in the near future. + * These handlers can no longer be cancelled, and therefore are passed an + * error code that indicates the successful completion of the wait operation. */ std::size_t expires_at(const time_type& expiry_time, asio::error_code& ec) @@ -288,6 +320,13 @@ * @return The number of asynchronous operations that were cancelled. * * @throws asio::system_error Thrown on failure. + * + * @note If the timer has already expired when expires_from_now() is called, + * then the handlers for asynchronous wait operations will: + * @li have already been invoked; or + * @li have been queued for invocation in the near future. + * These handlers can no longer be cancelled, and therefore are passed an + * error code that indicates the successful completion of the wait operation. */ std::size_t expires_from_now(const duration_type& expiry_time) { @@ -309,6 +348,13 @@ * @param ec Set to indicate what error occurred, if any. * * @return The number of asynchronous operations that were cancelled. + * + * @note If the timer has already expired when expires_from_now() is called, + * then the handlers for asynchronous wait operations will: + * @li have already been invoked; or + * @li have been queued for invocation in the near future. + * These handlers can no longer be cancelled, and therefore are passed an + * error code that indicates the successful completion of the wait operation. */ std::size_t expires_from_now(const duration_type& expiry_time, asio::error_code& ec)
diff --git a/asio/include/asio/handler_invoke_hook.hpp b/asio/include/asio/handler_invoke_hook.hpp index 0c6587d..e75598f 100644 --- a/asio/include/asio/handler_invoke_hook.hpp +++ b/asio/include/asio/handler_invoke_hook.hpp
@@ -25,10 +25,9 @@ * io_service associated with the corresponding object (e.g. a socket or * deadline_timer). Certain guarantees are made on when the handler may be * invoked, in particular that a handler can only be invoked from a thread that - * is currently calling asio::io_service::run() on the corresponding - * io_service object. Handlers may subsequently be invoked through other - * objects (such as asio::strand objects) that provide additional - * guarantees. + * is currently calling @c run() on the corresponding io_service object. + * Handlers may subsequently be invoked through other objects (such as + * io_service::strand objects) that provide additional guarantees. * * When asynchronous operations are composed from other asynchronous * operations, all intermediate handlers should be invoked using the same
diff --git a/asio/include/asio/io_service.hpp b/asio/include/asio/io_service.hpp index ad37aee..40c89c6 100644 --- a/asio/include/asio/io_service.hpp +++ b/asio/include/asio/io_service.hpp
@@ -60,27 +60,36 @@ * * @par Thread Safety * @e Distinct @e objects: Safe.@n - * @e Shared @e objects: Safe, with the exception that calling reset() - * while there are unfinished run() calls results in undefined behaviour. + * @e Shared @e objects: Safe, with the exception that calling reset() while + * there are unfinished run(), run_one(), poll() or poll_one() calls results in + * undefined behaviour. * * @par Concepts: * Dispatcher. * + * @par Synchronous and asynchronous operations + * + * Synchronous operations on I/O objects implicitly run the io_service object + * for an individual operation. The io_service functions run(), run_one(), + * poll() or poll_one() must be called for the io_service to perform + * asynchronous operations on behalf of a C++ program. Notification that an + * asynchronous operation has completed is delivered by invocation of the + * associated handler. Handlers are invoked only by a thread that is currently + * calling any overload of run(), run_one(), poll() or poll_one() for the + * io_service. + * * @par Effect of exceptions thrown from handlers * * If an exception is thrown from a handler, the exception is allowed to - * propagate through the throwing thread's invocation of - * asio::io_service::run(), asio::io_service::run_one(), - * asio::io_service::poll() or asio::io_service::poll_one(). - * No other threads that are calling any of these functions are affected. It is - * then the responsibility of the application to catch the exception. + * propagate through the throwing thread's invocation of run(), run_one(), + * poll() or poll_one(). No other threads that are calling any of these + * functions are affected. It is then the responsibility of the application to + * catch the exception. * - * After the exception has been caught, the - * asio::io_service::run(), asio::io_service::run_one(), - * asio::io_service::poll() or asio::io_service::poll_one() - * call may be restarted @em without the need for an intervening call to - * asio::io_service::reset(). This allows the thread to rejoin the - * io_service's thread pool without impacting any other threads in the pool. + * After the exception has been caught, the run(), run_one(), poll() or + * poll_one() call may be restarted @em without the need for an intervening + * call to reset(). This allows the thread to rejoin the io_service object's + * thread pool without impacting any other threads in the pool. * * For example: * @@ -103,7 +112,7 @@ * * @par Stopping the io_service from running out of work * - * Some applications may need to prevent an io_service's run() call from + * Some applications may need to prevent an io_service object's run() call from * returning when there is no more work to do. For example, the io_service may * be being run in a background thread that is launched prior to the * application's asynchronous operations. The run() call may be kept running by @@ -113,10 +122,10 @@ * asio::io_service::work work(io_service); * ... @endcode * - * To effect a shutdown, the application will then need to call the io_service's - * stop() member function. This will cause the io_service run() call to return - * as soon as possible, abandoning unfinished operations and without permitting - * ready handlers to be dispatched. + * To effect a shutdown, the application will then need to call the io_service + * object's stop() member function. This will cause the io_service run() call + * to return as soon as possible, abandoning unfinished operations and without + * permitting ready handlers to be dispatched. * * Alternatively, if the application requires that all operations and handlers * be allowed to finish normally, the work object may be explicitly destroyed. @@ -126,6 +135,43 @@ * new asio::io_service::work(io_service)); * ... * work.reset(); // Allow run() to exit. @endcode + * + * @par The io_service class and I/O services + * + * Class io_service implements an extensible, type-safe, polymorphic set of I/O + * services, indexed by service type. An object of class io_service must be + * initialised before I/O objects such as sockets, resolvers and timers can be + * used. These I/O objects are distinguished by having constructors that accept + * an @c io_service& parameter. + * + * I/O services exist to manage the logical interface to the operating system on + * behalf of the I/O objects. In particular, there are resources that are shared + * across a class of I/O objects. For example, timers may be implemented in + * terms of a single timer queue. The I/O services manage these shared + * resources. + * + * Access to the services of an io_service is via three function templates, + * use_service(), add_service() and has_service(). + * + * In a call to @c use_service<Service>(), the type argument chooses a service, + * making available all members of the named type. If @c Service is not present + * in an io_service, an object of type @c Service is created and added to the + * io_service. A C++ program can check if an io_service implements a + * particular service with the function template @c has_service<Service>(). + * + * Service objects may be explicitly added to an io_service using the function + * template @c add_service<Service>(). If the @c Service is already present, the + * service_already_exists exception is thrown. If the owner of the service is + * not the same object as the io_service parameter, the invalid_service_owner + * exception is thrown. + * + * Once a service reference is obtained from an io_service object by calling + * use_service(), that reference remains usable as long as the owning io_service + * object exists. + * + * All I/O service implementations have io_service::service as a public base + * class. Custom I/O services may be implemented by deriving from this class and + * then added to an io_service using the facilities described above. */ class io_service : private noncopyable @@ -168,9 +214,40 @@ explicit io_service(std::size_t concurrency_hint); /// Destructor. + /** + * On destruction, the io_service performs the following sequence of + * operations: + * + * @li For each service object @c svc in the io_service set, in reverse order + * of the beginning of service object lifetime, performs + * @c svc->shutdown_service(). + * + * @li Uninvoked handler objects that were scheduled for deferred invocation + * on the io_service, or any associated strand, are destroyed. + * + * @li For each service object @c svc in the io_service set, in reverse order + * of the beginning of service object lifetime, performs + * <tt>delete static_cast<io_service::service*>(svc)</tt>. + * + * @note The destruction sequence described above permits programs to + * simplify their resource management by using @c shared_ptr<>. Where an + * object's lifetime is tied to the lifetime of a connection (or some other + * sequence of asynchronous operations), a @c shared_ptr to the object would + * be bound into the handlers for all asynchronous operations associated with + * it. This works as follows: + * + * @li When a single connection ends, all associated asynchronous operations + * complete. The corresponding handler objects are destroyed, and all + * @c shared_ptr references to the objects are destroyed. + * + * @li To shut down the whole program, the io_service function stop() is + * called to terminate any run() calls as soon as possible. The io_service + * destructor defined above destroys all handlers, causing all @c shared_ptr + * references to all connection objects to be destroyed. + */ ~io_service(); - /// Run the io_service's event processing loop. + /// Run the io_service object's event processing loop. /** * The run() function blocks until all work has finished and there are no * more handlers to be dispatched, or until the io_service has been stopped. @@ -187,12 +264,16 @@ * * @throws asio::system_error Thrown on failure. * - * @note The poll() function may also be used to dispatch ready handlers, - * but without blocking. + * @note The run() function must not be called from a thread that is currently + * calling one of run(), run_one(), poll() or poll_one() on the same + * io_service object. + * + * The poll() function may also be used to dispatch ready handlers, but + * without blocking. */ std::size_t run(); - /// Run the io_service's event processing loop. + /// Run the io_service object's event processing loop. /** * The run() function blocks until all work has finished and there are no * more handlers to be dispatched, or until the io_service has been stopped. @@ -209,12 +290,17 @@ * * @return The number of handlers that were executed. * - * @note The poll() function may also be used to dispatch ready handlers, - * but without blocking. + * @note The run() function must not be called from a thread that is currently + * calling one of run(), run_one(), poll() or poll_one() on the same + * io_service object. + * + * The poll() function may also be used to dispatch ready handlers, but + * without blocking. */ std::size_t run(asio::error_code& ec); - /// Run the io_service's event processing loop to execute at most one handler. + /// Run the io_service object's event processing loop to execute at most one + /// handler. /** * The run_one() function blocks until one handler has been dispatched, or * until the io_service has been stopped. @@ -225,7 +311,8 @@ */ std::size_t run_one(); - /// Run the io_service's event processing loop to execute at most one handler. + /// Run the io_service object's event processing loop to execute at most one + /// handler. /** * The run_one() function blocks until one handler has been dispatched, or * until the io_service has been stopped. @@ -236,7 +323,8 @@ */ std::size_t run_one(asio::error_code& ec); - /// Run the io_service's event processing loop to execute ready handlers. + /// Run the io_service object's event processing loop to execute ready + /// handlers. /** * The poll() function runs handlers that are ready to run, without blocking, * until the io_service has been stopped or there are no more ready handlers. @@ -247,7 +335,8 @@ */ std::size_t poll(); - /// Run the io_service's event processing loop to execute ready handlers. + /// Run the io_service object's event processing loop to execute ready + /// handlers. /** * The poll() function runs handlers that are ready to run, without blocking, * until the io_service has been stopped or there are no more ready handlers. @@ -258,7 +347,8 @@ */ std::size_t poll(asio::error_code& ec); - /// Run the io_service's event processing loop to execute one ready handler. + /// Run the io_service object's event processing loop to execute one ready + /// handler. /** * The poll_one() function runs at most one handler that is ready to run, * without blocking. @@ -269,7 +359,8 @@ */ std::size_t poll_one(); - /// Run the io_service's event processing loop to execute one ready handler. + /// Run the io_service object's event processing loop to execute one ready + /// handler. /** * The poll_one() function runs at most one handler that is ready to run, * without blocking. @@ -280,7 +371,7 @@ */ std::size_t poll_one(asio::error_code& ec); - /// Stop the io_service's event processing loop. + /// Stop the io_service object's event processing loop. /** * This function does not block, but instead simply signals the io_service to * stop. All invocations of its run() or run_one() member functions should @@ -339,15 +430,15 @@ /// on the io_service. /** * This function is used to create a new handler function object that, when - * invoked, will automatically pass the wrapped handler to the io_service's - * dispatch function. + * invoked, will automatically pass the wrapped handler to the io_service + * object's dispatch function. * * @param handler The handler to be wrapped. The io_service will make a copy * of the handler object as required. The function signature of the handler * must be: @code void handler(A1 a1, ... An an); @endcode * * @return A function object that, when invoked, passes the wrapped handler to - * the io_service's dispatch function. Given a function object with the + * the io_service object's dispatch function. Given a function object with the * signature: * @code R f(A1 a1, ... An an); @endcode * If this function object is passed to the wrap function like so: @@ -429,9 +520,9 @@ /// Class to inform the io_service when it has work to do. /** * The work class is used to inform the io_service when work starts and - * finishes. This ensures that the io_service's run() function will not exit - * while work is underway, and that it does exit when there is no unfinished - * work remaining. + * finishes. This ensures that the io_service object's run() function will not + * exit while work is underway, and that it does exit when there is no + * unfinished work remaining. * * The work class is copy-constructible so that it may be used as a data member * in a handler class. It is not assignable. @@ -442,24 +533,24 @@ /// Constructor notifies the io_service that work is starting. /** * The constructor is used to inform the io_service that some work has begun. - * This ensures that the io_service's run() function will not exit while the - * work is underway. + * This ensures that the io_service object's run() function will not exit + * while the work is underway. */ explicit work(asio::io_service& io_service); /// Copy constructor notifies the io_service that work is starting. /** * The constructor is used to inform the io_service that some work has begun. - * This ensures that the io_service's run() function will not exit while the - * work is underway. + * This ensures that the io_service object's run() function will not exit + * while the work is underway. */ work(const work& other); /// Destructor notifies the io_service that the work is complete. /** * The destructor is used to inform the io_service that some work has - * finished. Once the count of unfinished work reaches zero, the io_service's - * run() function is permitted to exit. + * finished. Once the count of unfinished work reaches zero, the io_service + * object's run() function is permitted to exit. */ ~work();