[Boost-commit] svn:boost r61643 - in trunk: boost/asio libs/asio/doc libs/asio/doc/overview

Subject: [Boost-commit] svn:boost r61643 - in trunk: boost/asio libs/asio/doc libs/asio/doc/overview
From: chris_at_[hidden]
Date: 2010-04-28 08:39:08

Author: chris_kohlhoff
Date: 2010-04-28 08:39:06 EDT (Wed, 28 Apr 2010)
New Revision: 61643
URL: http://svn.boost.org/trac/boost/changeset/61643

Log:
Doc updates.

Text files modified: 
   trunk/boost/asio/io_service.hpp               |    16 ++++                                    
   trunk/boost/asio/read.hpp                     |    15 +++                                     
   trunk/boost/asio/read_until.hpp               |    93 +++++++++++++++++++++++++--             
   trunk/boost/asio/write.hpp                    |    20 ++++-                                   
   trunk/libs/asio/doc/history.qbk               |    35 ++++++++++                              
   trunk/libs/asio/doc/overview/serial_ports.qbk |     9 +-                                      
   trunk/libs/asio/doc/reference.qbk             |   134 ++++++++++++++++++++++++++++++++++++--- 
   7 files changed, 292 insertions(+), 30 deletions(-)

Modified: trunk/boost/asio/io_service.hpp
==============================================================================
--- trunk/boost/asio/io_service.hpp	(original)
+++ trunk/boost/asio/io_service.hpp	2010-04-28 08:39:06 EDT (Wed, 28 Apr 2010)
@@ -400,6 +400,14 @@
    * @param handler The handler to be called. The io_service will make
    * a copy of the handler object as required. The function signature of the
    * handler must be: @code void handler(); @endcode
+   *
+   * @note This function throws an exception only if:
+   *
+   * @li the handler's @c asio_handler_allocate function; or
+   *
+   * @li the handler's copy constructor
+   *
+   * throws an exception.
    */
   template <typename CompletionHandler>
   void dispatch(CompletionHandler handler);
@@ -417,6 +425,14 @@
    * @param handler The handler to be called. The io_service will make
    * a copy of the handler object as required. The function signature of the
    * handler must be: @code void handler(); @endcode
+   *
+   * @note This function throws an exception only if:
+   *
+   * @li the handler's @c asio_handler_allocate function; or
+   *
+   * @li the handler's copy constructor
+   *
+   * throws an exception.
    */
   template <typename CompletionHandler>
   void post(CompletionHandler handler);

Modified: trunk/boost/asio/read.hpp
==============================================================================
--- trunk/boost/asio/read.hpp	(original)
+++ trunk/boost/asio/read.hpp	2010-04-28 08:39:06 EDT (Wed, 28 Apr 2010)
@@ -301,7 +301,10 @@
  * @li An error occurred.
  *
  * This operation is implemented in terms of zero or more calls to the stream's
- * async_read_some function.
+ * async_read_some function, and is known as a <em>composed operation</em>. The
+ * program must ensure that the stream performs no other read operations (such
+ * as async_read, the stream's async_read_some function, or any other composed
+ * operations that perform reads) until this operation completes.
  *
  * @param s The stream from which the data is to be read. The type must support
  * the AsyncReadStream concept.
@@ -430,7 +433,10 @@
  * @li An error occurred.
  *
  * This operation is implemented in terms of zero or more calls to the stream's
- * async_read_some function.
+ * async_read_some function, and is known as a <em>composed operation</em>. The
+ * program must ensure that the stream performs no other read operations (such
+ * as async_read, the stream's async_read_some function, or any other composed
+ * operations that perform reads) until this operation completes.
  *
  * @param s The stream from which the data is to be read. The type must support
  * the AsyncReadStream concept.
@@ -477,7 +483,10 @@
  * @li The completion_condition function object returns 0.
  *
  * This operation is implemented in terms of zero or more calls to the stream's
- * async_read_some function.
+ * async_read_some function, and is known as a <em>composed operation</em>. The
+ * program must ensure that the stream performs no other read operations (such
+ * as async_read, the stream's async_read_some function, or any other composed
+ * operations that perform reads) until this operation completes.
  *
  * @param s The stream from which the data is to be read. The type must support
  * the AsyncReadStream concept.

Modified: trunk/boost/asio/read_until.hpp
==============================================================================
--- trunk/boost/asio/read_until.hpp	(original)
+++ trunk/boost/asio/read_until.hpp	2010-04-28 08:39:06 EDT (Wed, 28 Apr 2010)
@@ -129,6 +129,16 @@
  * std::istream is(&b);
  * std::string line;
  * std::getline(is, line); @endcode
+ * After the @c read_until operation completes successfully, the buffer @c b
+ * contains the delimiter:
+ * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
+ * The call to @c std::getline then extracts the data up to and including the
+ * delimiter, so that the string @c line contains:
+ * @code { 'a', 'b', ..., 'c', '\n' } @endcode
+ * The remaining data is left in the buffer @c b as follows:
+ * @code { 'd', 'e', ... } @endcode
+ * This data may be the start of a new line, to be extracted by a subsequent
+ * @c read_until operation.
  */
 template <typename SyncReadStream, typename Allocator>
 std::size_t read_until(SyncReadStream& s,
@@ -206,6 +216,16 @@
  * std::istream is(&b);
  * std::string line;
  * std::getline(is, line); @endcode
+ * After the @c read_until operation completes successfully, the buffer @c b
+ * contains the delimiter:
+ * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
+ * The call to @c std::getline then extracts the data up to and including the
+ * delimiter, so that the string @c line contains:
+ * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
+ * The remaining data is left in the buffer @c b as follows:
+ * @code { 'd', 'e', ... } @endcode
+ * This data may be the start of a new line, to be extracted by a subsequent
+ * @c read_until operation.
  */
 template <typename SyncReadStream, typename Allocator>
 std::size_t read_until(SyncReadStream& s,
@@ -285,6 +305,16 @@
  * std::istream is(&b);
  * std::string line;
  * std::getline(is, line); @endcode
+ * After the @c read_until operation completes successfully, the buffer @c b
+ * contains the data which matched the regular expression:
+ * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
+ * The call to @c std::getline then extracts the data up to and including the
+ * match, so that the string @c line contains:
+ * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
+ * The remaining data is left in the buffer @c b as follows:
+ * @code { 'd', 'e', ... } @endcode
+ * This data may be the start of a new line, to be extracted by a subsequent
+ * @c read_until operation.
  */
 template <typename SyncReadStream, typename Allocator>
 std::size_t read_until(SyncReadStream& s,
@@ -511,8 +541,12 @@
  * @li An error occurred.
  *
  * This operation is implemented in terms of zero or more calls to the stream's
- * async_read_some function. If the streambuf's get area already contains the
- * delimiter, the asynchronous operation completes immediately.
+ * async_read_some function, and is known as a <em>composed operation</em>. If
+ * the streambuf's get area already contains the delimiter, this asynchronous
+ * operation completes immediately. The program must ensure that the stream
+ * performs no other read operations (such as async_read, async_read_until, the
+ * stream's async_read_some function, or any other composed operations that
+ * perform reads) until this operation completes.
  *
  * @param s The stream from which the data is to be read. The type must support
  * the AsyncReadStream concept.
@@ -561,6 +595,16 @@
  * }
  * ...
  * boost::asio::async_read_until(s, b, '\n', handler); @endcode
+ * After the @c async_read_until operation completes successfully, the buffer
+ * @c b contains the delimiter:
+ * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
+ * The call to @c std::getline then extracts the data up to and including the
+ * delimiter, so that the string @c line contains:
+ * @code { 'a', 'b', ..., 'c', '\n' } @endcode
+ * The remaining data is left in the buffer @c b as follows:
+ * @code { 'd', 'e', ... } @endcode
+ * This data may be the start of a new line, to be extracted by a subsequent
+ * @c async_read_until operation.
  */
 template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
 void async_read_until(AsyncReadStream& s,
@@ -580,8 +624,12 @@
  * @li An error occurred.
  *
  * This operation is implemented in terms of zero or more calls to the stream's
- * async_read_some function. If the streambuf's get area already contains the
- * delimiter, the asynchronous operation completes immediately.
+ * async_read_some function, and is known as a <em>composed operation</em>. If
+ * the streambuf's get area already contains the delimiter, this asynchronous
+ * operation completes immediately. The program must ensure that the stream
+ * performs no other read operations (such as async_read, async_read_until, the
+ * stream's async_read_some function, or any other composed operations that
+ * perform reads) until this operation completes.
  *
  * @param s The stream from which the data is to be read. The type must support
  * the AsyncReadStream concept.
@@ -630,6 +678,16 @@
  * }
  * ...
  * boost::asio::async_read_until(s, b, "\r\n", handler); @endcode
+ * After the @c async_read_until operation completes successfully, the buffer
+ * @c b contains the delimiter:
+ * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
+ * The call to @c std::getline then extracts the data up to and including the
+ * delimiter, so that the string @c line contains:
+ * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
+ * The remaining data is left in the buffer @c b as follows:
+ * @code { 'd', 'e', ... } @endcode
+ * This data may be the start of a new line, to be extracted by a subsequent
+ * @c async_read_until operation.
  */
 template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
 void async_read_until(AsyncReadStream& s,
@@ -650,8 +708,13 @@
  * @li An error occurred.
  *
  * This operation is implemented in terms of zero or more calls to the stream's
- * async_read_some function. If the streambuf's get area already contains data
- * that matches the regular expression, the function returns immediately.
+ * async_read_some function, and is known as a <em>composed operation</em>. If
+ * the streambuf's get area already contains data that matches the regular
+ * expression, this asynchronous operation completes immediately. The program
+ * must ensure that the stream performs no other read operations (such as
+ * async_read, async_read_until, the stream's async_read_some function, or any
+ * other composed operations that perform reads) until this operation
+ * completes.
  *
  * @param s The stream from which the data is to be read. The type must support
  * the AsyncReadStream concept.
@@ -702,6 +765,16 @@
  * }
  * ...
  * boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler); @endcode
+ * After the @c async_read_until operation completes successfully, the buffer
+ * @c b contains the data which matched the regular expression:
+ * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
+ * The call to @c std::getline then extracts the data up to and including the
+ * match, so that the string @c line contains:
+ * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
+ * The remaining data is left in the buffer @c b as follows:
+ * @code { 'd', 'e', ... } @endcode
+ * This data may be the start of a new line, to be extracted by a subsequent
+ * @c async_read_until operation.
  */
 template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
 void async_read_until(AsyncReadStream& s,
@@ -723,8 +796,12 @@
  * @li An error occurred.
  *
  * This operation is implemented in terms of zero or more calls to the stream's
- * async_read_some function. If the match condition function object already
- * indicates a match, the operation completes immediately.
+ * async_read_some function, and is known as a <em>composed operation</em>. If
+ * the match condition function object already indicates a match, this
+ * asynchronous operation completes immediately. The program must ensure that
+ * the stream performs no other read operations (such as async_read,
+ * async_read_until, the stream's async_read_some function, or any other
+ * composed operations that perform reads) until this operation completes.
  *
  * @param s The stream from which the data is to be read. The type must support
  * the AsyncReadStream concept.

Modified: trunk/boost/asio/write.hpp
==============================================================================
--- trunk/boost/asio/write.hpp	(original)
+++ trunk/boost/asio/write.hpp	2010-04-28 08:39:06 EDT (Wed, 28 Apr 2010)
@@ -306,7 +306,10 @@
  * @li An error occurred.
  *
  * This operation is implemented in terms of zero or more calls to the stream's
- * async_write_some function.
+ * async_write_some function, and is known as a <em>composed operation</em>. The
+ * program must ensure that the stream performs no other write operations (such
+ * as async_write, the stream's async_write_some function, or any other composed
+ * operations that perform writes) until this operation completes.
  *
  * @param s The stream to which the data is to be written. The type must support
  * the AsyncWriteStream concept.
@@ -360,7 +363,10 @@
  * @li The completion_condition function object returns 0.
  *
  * This operation is implemented in terms of zero or more calls to the stream's
- * async_write_some function.
+ * async_write_some function, and is known as a <em>composed operation</em>. The
+ * program must ensure that the stream performs no other write operations (such
+ * as async_write, the stream's async_write_some function, or any other composed
+ * operations that perform writes) until this operation completes.
  *
  * @param s The stream to which the data is to be written. The type must support
  * the AsyncWriteStream concept.
@@ -430,7 +436,10 @@
  * @li An error occurred.
  *
  * This operation is implemented in terms of zero or more calls to the stream's
- * async_write_some function.
+ * async_write_some function, and is known as a <em>composed operation</em>. The
+ * program must ensure that the stream performs no other write operations (such
+ * as async_write, the stream's async_write_some function, or any other composed
+ * operations that perform writes) until this operation completes.
  *
  * @param s The stream to which the data is to be written. The type must support
  * the AsyncWriteStream concept.
@@ -472,7 +481,10 @@
  * @li The completion_condition function object returns 0.
  *
  * This operation is implemented in terms of zero or more calls to the stream's
- * async_write_some function.
+ * async_write_some function, and is known as a <em>composed operation</em>. The
+ * program must ensure that the stream performs no other write operations (such
+ * as async_write, the stream's async_write_some function, or any other composed
+ * operations that perform writes) until this operation completes.
  *
  * @param s The stream to which the data is to be written. The type must support
  * the AsyncWriteStream concept.

Modified: trunk/libs/asio/doc/history.qbk
==============================================================================
--- trunk/libs/asio/doc/history.qbk	(original)
+++ trunk/libs/asio/doc/history.qbk	2010-04-28 08:39:06 EDT (Wed, 28 Apr 2010)
@@ -7,6 +7,41 @@
 
 [section:history Revision History]
 
+[heading Asio 1.4.5 / Boost 1.43]
+
+* Improved performance.
+* Reduced compile times.
+* Reduced the size of generated code.
+* Extended the guarantee that background threads don't call user code to all
+  asynchronous operations
+  ([@https://svn.boost.org/trac/boost/ticket/3923 #3923]).
+* Changed to use edge-triggered epoll on Linux.
+* Changed to use `timerfd` for dispatching timers on Linux, when available.
+* Changed to use one-shot notifications with kqueue on Mac OS X and BSD
+  platforms.
+* Added a bitmask type `ip::resolver_query_base::flags` as per the TR2 proposal.
+  This type prevents implicit conversion from `int` to `flags`, allowing the
+  compiler to catch cases where users incorrectly pass a numeric port number as
+  the service name.
+* Added `#define NOMINMAX` for all Windows compilers. Users can define
+  `BOOST_ASIO_NO_NOMINMAX` to suppress this definition
+  ([@https://svn.boost.org/trac/boost/ticket/3901 #3901]).
+* Fixed a bug where 0-byte asynchronous reads were incorrectly passing an
+  `error::eof` result to the completion handler
+  ([@https://svn.boost.org/trac/boost/ticket/4023 #4023]).
+* Changed the `io_control()` member functions to always call `ioctl` on the
+  underlying descriptor when modifying blocking mode
+  ([@https://svn.boost.org/trac/boost/ticket/3307 #3307]).
+* Changed the resolver implementation to longer require the typedefs
+  `InternetProtocol::resolver_query` and `InternetProtocol::resolver_iterator`,
+  as neither typedef is part of the documented `InternetProtocol` requirements.
+  The corresponding typedefs in the `ip::tcp`, `ip::udp` and `ip::icmp` classes
+  have been deprecated.
+* Fixed out-of-band handling for reactors not based on `select()`.
+* Added new `BOOST_ASIO_DISABLE_THREADS` macro that allows Asio's threading
+  support to be independently disabled.
+* Minor documentation improvements.
+
 [heading Asio 1.4.4 / Boost 1.42]
 
 * Added a new HTTP Server 4 example illustrating the use of stackless coroutines

Modified: trunk/libs/asio/doc/overview/serial_ports.qbk
==============================================================================
--- trunk/libs/asio/doc/overview/serial_ports.qbk	(original)
+++ trunk/libs/asio/doc/overview/serial_ports.qbk	2010-04-28 08:39:06 EDT (Wed, 28 Apr 2010)
@@ -15,10 +15,11 @@
 where name is something like `"COM1"` on Windows, and `"/dev/ttyS0"` on POSIX
 platforms.
 
-Once opened the serial port may be used as a stream. This means the objects can
-be used with any of the [link boost_asio.reference.read read()], [link
-boost_asio.reference.async_read async_read()], [link boost_asio.reference.write write()],
-[link boost_asio.reference.async_write async_write()], [link
+Once opened, the serial port may be used as a [link
+boost_asio.overview.core.streams stream]. This means the objects can be used
+with any of the [link boost_asio.reference.read read()], [link
+boost_asio.reference.async_read async_read()], [link boost_asio.reference.write
+write()], [link boost_asio.reference.async_write async_write()], [link
 boost_asio.reference.read_until read_until()] or [link
 boost_asio.reference.async_read_until async_read_until()] free functions.
 

Modified: trunk/libs/asio/doc/reference.qbk
==============================================================================
--- trunk/libs/asio/doc/reference.qbk	(original)
+++ trunk/libs/asio/doc/reference.qbk	2010-04-28 08:39:06 EDT (Wed, 28 Apr 2010)
@@ -342,7 +342,7 @@
 
 * An error occurred.
 
-This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function.
+This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a [*composed operation]. The program must ensure that the stream performs no other read operations (such as async\_read, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes.
 
 
 [heading Parameters]
@@ -505,7 +505,7 @@
 
 * An error occurred.
 
-This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function.
+This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a [*composed operation]. The program must ensure that the stream performs no other read operations (such as async\_read, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes.
 
 
 [heading Parameters]
@@ -576,7 +576,7 @@
 
 * The completion_condition function object returns 0.
 
-This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function.
+This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a [*composed operation]. The program must ensure that the stream performs no other read operations (such as async\_read, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes.
 
 
 [heading Parameters]
@@ -1087,7 +1087,7 @@
 
 * An error occurred.
 
-This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function. If the streambuf's get area already contains the delimiter, the asynchronous operation completes immediately.
+This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a [*composed operation]. If the streambuf's get area already contains the delimiter, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes.
 
 
 [heading Parameters]
@@ -1143,7 +1143,22 @@
    boost::asio::async_read_until(s, b, '\n', handler); 
 
 
+After the `async_read_until` operation completes successfully, the buffer `b` contains the delimiter: 
 
+   { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } 
+
+
+The call to `std::getline` then extracts the data up to and including the delimiter, so that the string `line` contains: 
+
+   { 'a', 'b', ..., 'c', '\n' } 
+
+
+The remaining data is left in the buffer `b` as follows: 
+
+   { 'd', 'e', ... } 
+
+
+This data may be the start of a new line, to be extracted by a subsequent `async_read_until` operation. 
 
 
 
@@ -1177,7 +1192,7 @@
 
 * An error occurred.
 
-This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function. If the streambuf's get area already contains the delimiter, the asynchronous operation completes immediately.
+This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a [*composed operation]. If the streambuf's get area already contains the delimiter, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes.
 
 
 [heading Parameters]
@@ -1233,7 +1248,22 @@
    boost::asio::async_read_until(s, b, "\r\n", handler); 
 
 
+After the `async_read_until` operation completes successfully, the buffer `b` contains the delimiter: 
+
+   { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } 
+
+
+The call to `std::getline` then extracts the data up to and including the delimiter, so that the string `line` contains: 
+
+   { 'a', 'b', ..., 'c', '\r', '\n' } 
+
+
+The remaining data is left in the buffer `b` as follows: 
+
+   { 'd', 'e', ... } 
+
 
+This data may be the start of a new line, to be extracted by a subsequent `async_read_until` operation. 
 
 
 
@@ -1267,7 +1297,7 @@
 
 * An error occurred.
 
-This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function. If the streambuf's get area already contains data that matches the regular expression, the function returns immediately.
+This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a [*composed operation]. If the streambuf's get area already contains data that matches the regular expression, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes.
 
 
 [heading Parameters]
@@ -1324,7 +1354,22 @@
    boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler); 
 
 
+After the `async_read_until` operation completes successfully, the buffer `b` contains the data which matched the regular expression: 
 
+   { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } 
+
+
+The call to `std::getline` then extracts the data up to and including the match, so that the string `line` contains: 
+
+   { 'a', 'b', ..., 'c', '\r', '\n' } 
+
+
+The remaining data is left in the buffer `b` as follows: 
+
+   { 'd', 'e', ... } 
+
+
+This data may be the start of a new line, to be extracted by a subsequent `async_read_until` operation. 
 
 
 
@@ -1360,7 +1405,7 @@
 
 * An error occurred.
 
-This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function. If the match condition function object already indicates a match, the operation completes immediately.
+This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a [*composed operation]. If the match condition function object already indicates a match, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes.
 
 
 [heading Parameters]
@@ -1553,7 +1598,7 @@
 
 * An error occurred.
 
-This operation is implemented in terms of zero or more calls to the stream's async\_write\_some function.
+This operation is implemented in terms of zero or more calls to the stream's async\_write\_some function, and is known as a [*composed operation]. The program must ensure that the stream performs no other write operations (such as async\_write, the stream's async\_write\_some function, or any other composed operations that perform writes) until this operation completes.
 
 
 [heading Parameters]
@@ -1623,7 +1668,7 @@
 
 * The completion_condition function object returns 0.
 
-This operation is implemented in terms of zero or more calls to the stream's async\_write\_some function.
+This operation is implemented in terms of zero or more calls to the stream's async\_write\_some function, and is known as a [*composed operation]. The program must ensure that the stream performs no other write operations (such as async\_write, the stream's async\_write\_some function, or any other composed operations that perform writes) until this operation completes.
 
 
 [heading Parameters]
@@ -1706,7 +1751,7 @@
 
 * An error occurred.
 
-This operation is implemented in terms of zero or more calls to the stream's async\_write\_some function.
+This operation is implemented in terms of zero or more calls to the stream's async\_write\_some function, and is known as a [*composed operation]. The program must ensure that the stream performs no other write operations (such as async\_write, the stream's async\_write\_some function, or any other composed operations that perform writes) until this operation completes.
 
 
 [heading Parameters]
@@ -1766,7 +1811,7 @@
 
 * The completion_condition function object returns 0.
 
-This operation is implemented in terms of zero or more calls to the stream's async\_write\_some function.
+This operation is implemented in terms of zero or more calls to the stream's async\_write\_some function, and is known as a [*composed operation]. The program must ensure that the stream performs no other write operations (such as async\_write, the stream's async\_write\_some function, or any other composed operations that perform writes) until this operation completes.
 
 
 [heading Parameters]
@@ -37638,6 +37683,17 @@
 ]
 
 
+[heading Remarks]
+      
+This function throws an exception only if:
+
+
+* the handler's asio_handler_allocate function; or
+
+
+* the handler's copy constructor
+
+throws an exception. 
 
 
 [endsect]
@@ -37939,6 +37995,17 @@
 ]
 
 
+[heading Remarks]
+      
+This function throws an exception only if:
+
+
+* the handler's asio_handler_allocate function; or
+
+
+* the handler's copy constructor
+
+throws an exception. 
 
 
 [endsect]
@@ -57460,8 +57527,23 @@
    std::getline(is, line); 
 
 
+After the `read_until` operation completes successfully, the buffer `b` contains the delimiter: 
+
+   { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } 
 
 
+The call to `std::getline` then extracts the data up to and including the delimiter, so that the string `line` contains: 
+
+   { 'a', 'b', ..., 'c', '\n' } 
+
+
+The remaining data is left in the buffer `b` as follows: 
+
+   { 'd', 'e', ... } 
+
+
+This data may be the start of a new line, to be extracted by a subsequent `read_until` operation. 
+
 
 
 
@@ -57599,8 +57681,23 @@
    std::getline(is, line); 
 
 
+After the `read_until` operation completes successfully, the buffer `b` contains the delimiter: 
+
+   { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } 
 
 
+The call to `std::getline` then extracts the data up to and including the delimiter, so that the string `line` contains: 
+
+   { 'a', 'b', ..., 'c', '\r', '\n' } 
+
+
+The remaining data is left in the buffer `b` as follows: 
+
+   { 'd', 'e', ... } 
+
+
+This data may be the start of a new line, to be extracted by a subsequent `read_until` operation. 
+
 
 
 
@@ -57738,7 +57835,22 @@
    std::getline(is, line); 
 
 
+After the `read_until` operation completes successfully, the buffer `b` contains the data which matched the regular expression: 
+
+   { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } 
+
+
+The call to `std::getline` then extracts the data up to and including the match, so that the string `line` contains: 
+
+   { 'a', 'b', ..., 'c', '\r', '\n' } 
+
+
+The remaining data is left in the buffer `b` as follows: 
+
+   { 'd', 'e', ... } 
+
 
+This data may be the start of a new line, to be extracted by a subsequent `read_until` operation.