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

From: chris_at_[hidden]
Date: 2008-07-01 08:14:57

Author: chris_kohlhoff
Date: 2008-07-01 08:14:57 EDT (Tue, 01 Jul 2008)
New Revision: 46950
URL: http://svn.boost.org/trac/boost/changeset/46950

Log:
Clarify behaviour of read_until/async_read_until with respect to leftover
data in the streambuf. Use separate brief descriptions for function groups.
Add some extra notes to the io_service documentation.

Text files modified: 
   trunk/boost/asio/io_service.hpp |    32 ++++++++++                              
   trunk/boost/asio/read.hpp       |     6 +                                       
   trunk/boost/asio/read_at.hpp    |     6 +                                       
   trunk/boost/asio/read_until.hpp |   127 ++++++++++++++++++++++++++++++--------- 
   trunk/boost/asio/write.hpp      |     5 +                                       
   trunk/boost/asio/write_at.hpp   |     5 +                                       
   6 files changed, 150 insertions(+), 31 deletions(-)

Modified: trunk/boost/asio/io_service.hpp
==============================================================================
--- trunk/boost/asio/io_service.hpp	(original)
+++ trunk/boost/asio/io_service.hpp	2008-07-01 08:14:57 EDT (Tue, 01 Jul 2008)
@@ -101,6 +101,32 @@
  *   }
  * }
  * @endcode
+ *
+ * @par Stopping the io_service from running out of work
+ *
+ * Some applications may need to prevent an io_service'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
+ * creating an object of type boost::asio::io_service::work:
+ *
+ * @code boost::asio::io_service io_service;
+ * 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.
+ *
+ * Alternatively, if the application requires that all operations and handlers
+ * be allowed to finish normally, the work object may be explicitly destroyed.
+ *
+ * @code boost::asio::io_service io_service;
+ * auto_ptr<boost::asio::io_service::work> work(
+ *     new boost::asio::io_service::work(io_service));
+ * ...
+ * work.reset(); // Allow run() to exit. @endcode
  */
 class io_service
   : private noncopyable
@@ -160,6 +186,9 @@
    * @return The number of handlers that were executed.
    *
    * @throws boost::system::system_error Thrown on failure.
+   *
+   * @note The poll() function may also be used to dispatch ready handlers,
+   * but without blocking.
    */
   std::size_t run();
 
@@ -179,6 +208,9 @@
    * @param ec Set to indicate what error occurred, if any.
    *
    * @return The number of handlers that were executed.
+   *
+   * @note The poll() function may also be used to dispatch ready handlers,
+   * but without blocking.
    */
   std::size_t run(boost::system::error_code& ec);
 

Modified: trunk/boost/asio/read.hpp
==============================================================================
--- trunk/boost/asio/read.hpp	(original)
+++ trunk/boost/asio/read.hpp	2008-07-01 08:14:57 EDT (Tue, 01 Jul 2008)
@@ -30,6 +30,9 @@
 
 /**
  * @defgroup read boost::asio::read
+ *
+ * @brief Attempt to read a certain amount of data from a stream before
+ * returning.
  */
 /*@{*/
 
@@ -270,6 +273,9 @@
 /*@}*/
 /**
  * @defgroup async_read boost::asio::async_read
+ *
+ * @brief Start an asynchronous operation to read a certain amount of data from
+ * a stream.
  */
 /*@{*/
 

Modified: trunk/boost/asio/read_at.hpp
==============================================================================
--- trunk/boost/asio/read_at.hpp	(original)
+++ trunk/boost/asio/read_at.hpp	2008-07-01 08:14:57 EDT (Tue, 01 Jul 2008)
@@ -31,6 +31,9 @@
 
 /**
  * @defgroup read_at boost::asio::read_at
+ *
+ * @brief Attempt to read a certain amount of data at the specified offset
+ * before returning.
  */
 /*@{*/
 
@@ -305,6 +308,9 @@
 /*@}*/
 /**
  * @defgroup async_read_at boost::asio::async_read_at
+ *
+ * @brief Start an asynchronous operation to read a certain amount of data at
+ * the specified offset.
  */
 /*@{*/
 

Modified: trunk/boost/asio/read_until.hpp
==============================================================================
--- trunk/boost/asio/read_until.hpp	(original)
+++ trunk/boost/asio/read_until.hpp	2008-07-01 08:14:57 EDT (Tue, 01 Jul 2008)
@@ -65,10 +65,13 @@
 
 /**
  * @defgroup read_until boost::asio::read_until
+ *
+ * @brief Read data into a streambuf until it contains a delimiter, matches a
+ * regular expression, or a function object indicates a match.
  */
 /*@{*/
 
-/// Read data into a streambuf until a delimiter is encountered.
+/// Read data into a streambuf until it contains a specified delimiter.
 /**
  * This function is used to read data into the specified streambuf until the
  * streambuf's get area contains the specified delimiter. The call will block
@@ -94,6 +97,10 @@
  *
  * @throws boost::system::system_error Thrown on failure.
  *
+ * @note After a successful read_until operation, the streambuf may contain
+ * additional data beyond the delimiter. An application will typically leave
+ * that data in the streambuf for a subsequent read_until operation to examine.
+ *
  * @par Example
  * To read data into a streambuf until a newline is encountered:
  * @code boost::asio::streambuf b;
@@ -106,7 +113,7 @@
 std::size_t read_until(SyncReadStream& s,
     boost::asio::basic_streambuf<Allocator>& b, char delim);
 
-/// Read data into a streambuf until a delimiter is encountered.
+/// Read data into a streambuf until it contains a specified delimiter.
 /**
  * This function is used to read data into the specified streambuf until the
  * streambuf's get area contains the specified delimiter. The call will block
@@ -131,13 +138,17 @@
  *
  * @returns The number of bytes in the streambuf's get area up to and including
  * the delimiter. Returns 0 if an error occurred.
+ *
+ * @note After a successful read_until operation, the streambuf may contain
+ * additional data beyond the delimiter. An application will typically leave
+ * that data in the streambuf for a subsequent read_until operation to examine.
  */
 template <typename SyncReadStream, typename Allocator>
 std::size_t read_until(SyncReadStream& s,
     boost::asio::basic_streambuf<Allocator>& b, char delim,
     boost::system::error_code& ec);
 
-/// Read data into a streambuf until a delimiter is encountered.
+/// Read data into a streambuf until it contains a specified delimiter.
 /**
  * This function is used to read data into the specified streambuf until the
  * streambuf's get area contains the specified delimiter. The call will block
@@ -163,6 +174,10 @@
  *
  * @throws boost::system::system_error Thrown on failure.
  *
+ * @note After a successful read_until operation, the streambuf may contain
+ * additional data beyond the delimiter. An application will typically leave
+ * that data in the streambuf for a subsequent read_until operation to examine.
+ *
  * @par Example
  * To read data into a streambuf until a newline is encountered:
  * @code boost::asio::streambuf b;
@@ -175,7 +190,7 @@
 std::size_t read_until(SyncReadStream& s,
     boost::asio::basic_streambuf<Allocator>& b, const std::string& delim);
 
-/// Read data into a streambuf until a delimiter is encountered.
+/// Read data into a streambuf until it contains a specified delimiter.
 /**
  * This function is used to read data into the specified streambuf until the
  * streambuf's get area contains the specified delimiter. The call will block
@@ -200,13 +215,18 @@
  *
  * @returns The number of bytes in the streambuf's get area up to and including
  * the delimiter. Returns 0 if an error occurred.
+ *
+ * @note After a successful read_until operation, the streambuf may contain
+ * additional data beyond the delimiter. An application will typically leave
+ * that data in the streambuf for a subsequent read_until operation to examine.
  */
 template <typename SyncReadStream, typename Allocator>
 std::size_t read_until(SyncReadStream& s,
     boost::asio::basic_streambuf<Allocator>& b, const std::string& delim,
     boost::system::error_code& ec);
 
-/// Read data into a streambuf until a regular expression is located.
+/// Read data into a streambuf until some part of the data it contains matches
+/// a regular expression.
 /**
  * This function is used to read data into the specified streambuf until the
  * streambuf's get area contains some data that matches a regular expression.
@@ -232,6 +252,11 @@
  *
  * @throws boost::system::system_error Thrown on failure.
  *
+ * @note After a successful read_until operation, the streambuf may contain
+ * additional data beyond that which matched the regular expression. An
+ * application will typically leave that data in the streambuf for a subsequent
+ * read_until operation to examine.
+ *
  * @par Example
  * To read data into a streambuf until a CR-LF sequence is encountered:
  * @code boost::asio::streambuf b;
@@ -244,7 +269,8 @@
 std::size_t read_until(SyncReadStream& s,
     boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr);
 
-/// Read data into a streambuf until a regular expression is located.
+/// Read data into a streambuf until some part of the data it contains matches
+/// a regular expression.
 /**
  * This function is used to read data into the specified streambuf until the
  * streambuf's get area contains some data that matches a regular expression.
@@ -270,6 +296,11 @@
  * @returns The number of bytes in the streambuf's get area up to and including
  * the substring that matches the regular expression. Returns 0 if an error
  * occurred.
+ *
+ * @note After a successful read_until operation, the streambuf may contain
+ * additional data beyond that which matched the regular expression. An
+ * application will typically leave that data in the streambuf for a subsequent
+ * read_until operation to examine.
  */
 template <typename SyncReadStream, typename Allocator>
 std::size_t read_until(SyncReadStream& s,
@@ -317,6 +348,10 @@
  *
  * @throws boost::system::system_error Thrown on failure.
  *
+ * @note After a successful read_until operation, the streambuf may contain
+ * additional data beyond that which matched the function object. An application
+ * will typically leave that data in the streambuf for a subsequent
+ *
  * @note The default implementation of the @c is_match_condition type trait
  * evaluates to true for function pointers and function objects with a
  * @c result_type typedef. It must be specialised for other user-defined
@@ -417,6 +452,10 @@
  * @returns The number of bytes in the streambuf's get area that have been fully
  * consumed by the match function. Returns 0 if an error occurred.
  *
+ * @note After a successful read_until operation, the streambuf may contain
+ * additional data beyond that which matched the function object. An application
+ * will typically leave that data in the streambuf for a subsequent
+ *
  * @note The default implementation of the @c is_match_condition type trait
  * evaluates to true for function pointers and function objects with a
  * @c result_type typedef. It must be specialised for other user-defined
@@ -430,12 +469,16 @@
 
 /*@}*/
 /**
-* @defgroup async_read_until boost::asio::async_read_until
-*/
+ * @defgroup async_read_until boost::asio::async_read_until
+ *
+ * @brief Start an asynchronous operation to read data into a streambuf until it
+ * contains a delimiter, matches a regular expression, or a function object
+ * indicates a match.
+ */
 /*@{*/
 
-/// Start an asynchronous operation to read data into a streambuf until a
-/// delimiter is encountered.
+/// Start an asynchronous operation to read data into a streambuf until it
+/// contains a specified delimiter.
 /**
  * This function is used to asynchronously read data into the specified
  * streambuf until the streambuf's get area contains the specified delimiter.
@@ -463,18 +506,24 @@
  * Copies will be made of the handler as required. The function signature of the
  * handler must be:
  * @code void handler(
- *   const boost::system::error_code& error,         // Result of operation.
+ *   // Result of operation.
+ *   const boost::system::error_code& error,
  *
- *   std::size_t bytes_transferred          // The number of bytes in the
- *                                          // streambuf's get area up to
- *                                          // and including the delimiter.
- *                                          // 0 if an error occurred.
+ *   // The number of bytes in the streambuf's get
+ *   // area up to and including the delimiter.
+ *   // 0 if an error occurred.
+ *   std::size_t bytes_transferred
  * ); @endcode
  * Regardless of whether the asynchronous operation completes immediately or
  * not, the handler will not be invoked from within this function. Invocation of
  * the handler will be performed in a manner equivalent to using
  * boost::asio::io_service::post().
  *
+ * @note After a successful async_read_until operation, the streambuf may
+ * contain additional data beyond the delimiter. An application will typically
+ * leave that data in the streambuf for a subsequent async_read_until operation
+ * to examine.
+ *
  * @par Example
  * To asynchronously read data into a streambuf until a newline is encountered:
  * @code boost::asio::streambuf b;
@@ -497,8 +546,8 @@
     boost::asio::basic_streambuf<Allocator>& b,
     char delim, ReadHandler handler);
 
-/// Start an asynchronous operation to read data into a streambuf until a
-/// delimiter is encountered.
+/// Start an asynchronous operation to read data into a streambuf until it
+/// contains a specified delimiter.
 /**
  * This function is used to asynchronously read data into the specified
  * streambuf until the streambuf's get area contains the specified delimiter.
@@ -526,18 +575,24 @@
  * Copies will be made of the handler as required. The function signature of the
  * handler must be:
  * @code void handler(
- *   const boost::system::error_code& error,         // Result of operation.
+ *   // Result of operation.
+ *   const boost::system::error_code& error,
  *
- *   std::size_t bytes_transferred          // The number of bytes in the
- *                                          // streambuf's get area up to
- *                                          // and including the delimiter.
- *                                          // 0 if an error occurred.
+ *   // The number of bytes in the streambuf's get
+ *   // area up to and including the delimiter.
+ *   // 0 if an error occurred.
+ *   std::size_t bytes_transferred
  * ); @endcode
  * Regardless of whether the asynchronous operation completes immediately or
  * not, the handler will not be invoked from within this function. Invocation of
  * the handler will be performed in a manner equivalent to using
  * boost::asio::io_service::post().
  *
+ * @note After a successful async_read_until operation, the streambuf may
+ * contain additional data beyond the delimiter. An application will typically
+ * leave that data in the streambuf for a subsequent async_read_until operation
+ * to examine.
+ *
  * @par Example
  * To asynchronously read data into a streambuf until a newline is encountered:
  * @code boost::asio::streambuf b;
@@ -560,8 +615,8 @@
     boost::asio::basic_streambuf<Allocator>& b, const std::string& delim,
     ReadHandler handler);
 
-/// Start an asynchronous operation to read data into a streambuf until a
-/// regular expression is located.
+/// Start an asynchronous operation to read data into a streambuf until some
+/// part of its data matches a regular expression.
 /**
  * This function is used to asynchronously read data into the specified
  * streambuf until the streambuf's get area contains some data that matches a
@@ -590,20 +645,25 @@
  * Copies will be made of the handler as required. The function signature of the
  * handler must be:
  * @code void handler(
- *   const boost::system::error_code& error,         // Result of operation.
+ *   // Result of operation.
+ *   const boost::system::error_code& error,
  *
- *   std::size_t bytes_transferred          // The number of bytes in the
- *                                          // streambuf's get area up to
- *                                          // and including the substring
- *                                          // that matches the regular.
- *                                          // expression. 0 if an error
- *                                          // occurred.
+ *   // The number of bytes in the streambuf's get
+ *   // area up to and including the substring
+ *   // that matches the regular. expression.
+ *   // 0 if an error occurred.
+ *   std::size_t bytes_transferred
  * ); @endcode
  * Regardless of whether the asynchronous operation completes immediately or
  * not, the handler will not be invoked from within this function. Invocation of
  * the handler will be performed in a manner equivalent to using
  * boost::asio::io_service::post().
  *
+ * @note After a successful async_read_until operation, the streambuf may
+ * contain additional data beyond that which matched the regular expression. An
+ * application will typically leave that data in the streambuf for a subsequent
+ * async_read_until operation to examine.
+ *
  * @par Example
  * To asynchronously read data into a streambuf until a CR-LF sequence is
  * encountered:
@@ -682,6 +742,11 @@
  * the handler will be performed in a manner equivalent to using
  * boost::asio::io_service::post().
  *
+ * @note After a successful async_read_until operation, the streambuf may
+ * contain additional data beyond that which matched the function object. An
+ * application will typically leave that data in the streambuf for a subsequent
+ * async_read_until operation to examine.
+ *
  * @note The default implementation of the @c is_match_condition type trait
  * evaluates to true for function pointers and function objects with a
  * @c result_type typedef. It must be specialised for other user-defined

Modified: trunk/boost/asio/write.hpp
==============================================================================
--- trunk/boost/asio/write.hpp	(original)
+++ trunk/boost/asio/write.hpp	2008-07-01 08:14:57 EDT (Tue, 01 Jul 2008)
@@ -30,6 +30,8 @@
 
 /**
  * @defgroup write boost::asio::write
+ *
+ * @brief Write a certain amount of data to a stream before returning.
  */
 /*@{*/
 
@@ -280,6 +282,9 @@
 /*@}*/
 /**
  * @defgroup async_write boost::asio::async_write
+ *
+ * @brief Start an asynchronous operation to write a certain amount of data to a
+ * stream.
  */
 /*@{*/
 

Modified: trunk/boost/asio/write_at.hpp
==============================================================================
--- trunk/boost/asio/write_at.hpp	(original)
+++ trunk/boost/asio/write_at.hpp	2008-07-01 08:14:57 EDT (Tue, 01 Jul 2008)
@@ -31,6 +31,8 @@
 
 /**
  * @defgroup write_at boost::asio::write_at
+ *
+ * @brief Write a certain amount of data at a specified offset before returning.
  */
 /*@{*/
 
@@ -304,6 +306,9 @@
 /*@}*/
 /**
  * @defgroup async_write_at boost::asio::async_write_at
+ *
+ * @brief Start an asynchronous operation to write a certain amount of data at
+ * the specified offset.
  */
 /*@{*/