[Boost-commit] svn:boost r54916 - trunk/boost/asio

Subject: [Boost-commit] svn:boost r54916 - trunk/boost/asio
From: chris_at_[hidden]
Date: 2009-07-12 23:38:22

Author: chris_kohlhoff
Date: 2009-07-12 23:38:21 EDT (Sun, 12 Jul 2009)
New Revision: 54916
URL: http://svn.boost.org/trac/boost/changeset/54916

Log:
Documentation updates.

Text files modified: 
   trunk/boost/asio/basic_deadline_timer.hpp |    46 ++++++++++                              
   trunk/boost/asio/handler_invoke_hook.hpp  |     7                                         
   trunk/boost/asio/io_service.hpp           |   179 ++++++++++++++++++++++++++++++--------- 
   3 files changed, 184 insertions(+), 48 deletions(-)

Modified: trunk/boost/asio/basic_deadline_timer.hpp
==============================================================================
--- trunk/boost/asio/basic_deadline_timer.hpp	(original)
+++ trunk/boost/asio/basic_deadline_timer.hpp	2009-07-12 23:38:21 EDT (Sun, 12 Jul 2009)
@@ -35,6 +35,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 boost::asio::deadline_timer typedef.
  *
  * @par Thread Safety
@@ -193,6 +197,13 @@
    * @return The number of asynchronous operations that were cancelled.
    *
    * @throws boost::system::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()
   {
@@ -213,6 +224,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(boost::system::error_code& ec)
   {
@@ -240,6 +258,13 @@
    * @return The number of asynchronous operations that were cancelled.
    *
    * @throws boost::system::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)
   {
@@ -261,6 +286,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,
       boost::system::error_code& ec)
@@ -289,6 +321,13 @@
    * @return The number of asynchronous operations that were cancelled.
    *
    * @throws boost::system::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)
   {
@@ -310,6 +349,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,
       boost::system::error_code& ec)

Modified: trunk/boost/asio/handler_invoke_hook.hpp
==============================================================================
--- trunk/boost/asio/handler_invoke_hook.hpp	(original)
+++ trunk/boost/asio/handler_invoke_hook.hpp	2009-07-12 23:38:21 EDT (Sun, 12 Jul 2009)
@@ -26,10 +26,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 boost::asio::io_service::run() on the corresponding
- * io_service object. Handlers may subsequently be invoked through other
- * objects (such as boost::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

Modified: trunk/boost/asio/io_service.hpp
==============================================================================
--- trunk/boost/asio/io_service.hpp	(original)
+++ trunk/boost/asio/io_service.hpp	2009-07-12 23:38:21 EDT (Sun, 12 Jul 2009)
@@ -61,27 +61,36 @@
  *
  * @par Thread Safety
  * @e Distinct @e objects: Safe._at_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
- * boost::asio::io_service::run(), boost::asio::io_service::run_one(),
- * boost::asio::io_service::poll() or boost::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.
- *
- * After the exception has been caught, the
- * boost::asio::io_service::run(), boost::asio::io_service::run_one(),
- * boost::asio::io_service::poll() or boost::asio::io_service::poll_one()
- * call may be restarted @em without the need for an intervening call to
- * boost::asio::io_service::reset(). This allows the thread to rejoin the
- * io_service's thread pool without impacting any other threads in the pool.
+ * 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 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:
  *
@@ -104,7 +113,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
@@ -114,10 +123,10 @@
  * boost::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.
@@ -127,6 +136,43 @@
  *     new boost::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
@@ -169,9 +215,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.
@@ -188,12 +265,16 @@
    *
    * @throws boost::system::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.
@@ -210,12 +291,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(boost::system::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.
@@ -226,7 +312,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.
@@ -237,7 +324,8 @@
    */
   std::size_t run_one(boost::system::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.
@@ -248,7 +336,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.
@@ -259,7 +348,8 @@
    */
   std::size_t poll(boost::system::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.
@@ -270,7 +360,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.
@@ -281,7 +372,7 @@
    */
   std::size_t poll_one(boost::system::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
@@ -340,15 +431,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:
@@ -430,9 +521,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.
@@ -443,24 +534,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(boost::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();