Doc updates.
diff --git a/asio/include/asio/io_service.hpp b/asio/include/asio/io_service.hpp index 6552440..62d9e54 100644 --- a/asio/include/asio/io_service.hpp +++ b/asio/include/asio/io_service.hpp
@@ -399,6 +399,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); @@ -416,6 +424,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);
diff --git a/asio/include/asio/read.hpp b/asio/include/asio/read.hpp index bc732ad..859c05a 100644 --- a/asio/include/asio/read.hpp +++ b/asio/include/asio/read.hpp
@@ -300,7 +300,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. @@ -429,7 +432,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. @@ -476,7 +482,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.
diff --git a/asio/include/asio/read_until.hpp b/asio/include/asio/read_until.hpp index 4af7935..5df71ce 100644 --- a/asio/include/asio/read_until.hpp +++ b/asio/include/asio/read_until.hpp
@@ -128,6 +128,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, @@ -205,6 +215,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, @@ -284,6 +304,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, @@ -510,8 +540,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. @@ -560,6 +594,16 @@ * } * ... * 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, @@ -579,8 +623,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. @@ -629,6 +677,16 @@ * } * ... * 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, @@ -649,8 +707,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. @@ -701,6 +764,16 @@ * } * ... * 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, @@ -722,8 +795,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.
diff --git a/asio/include/asio/write.hpp b/asio/include/asio/write.hpp index 879cdeb..2b188cd 100644 --- a/asio/include/asio/write.hpp +++ b/asio/include/asio/write.hpp
@@ -305,7 +305,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. @@ -359,7 +362,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. @@ -429,7 +435,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. @@ -471,7 +480,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.
diff --git a/asio/src/doc/overview/serial_ports.qbk b/asio/src/doc/overview/serial_ports.qbk index 4fc4ae0..84af89f 100644 --- a/asio/src/doc/overview/serial_ports.qbk +++ b/asio/src/doc/overview/serial_ports.qbk
@@ -15,11 +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 asio.reference.read read()], [link -asio.reference.async_read async_read()], [link asio.reference.write write()], -[link asio.reference.async_write async_write()], [link -asio.reference.read_until read_until()] or [link +Once opened, the serial port may be used as a [link asio.overview.core.streams +stream]. This means the objects can be used with any of the [link +asio.reference.read read()], [link asio.reference.async_read async_read()], +[link asio.reference.write write()], [link asio.reference.async_write +async_write()], [link asio.reference.read_until read_until()] or [link asio.reference.async_read_until async_read_until()] free functions. The serial port implementation also includes option classes for configuring the
diff --git a/asio/src/doc/reference.qbk b/asio/src/doc/reference.qbk index 1aa9e91..e97fd89 100644 --- a/asio/src/doc/reference.qbk +++ b/asio/src/doc/reference.qbk
@@ -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 @@ 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 @@ 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 @@ 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] @@ -37991,6 +38036,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] @@ -38292,6 +38348,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] @@ -57813,7 +57880,22 @@ 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. @@ -57952,7 +58034,22 @@ 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. @@ -58091,7 +58188,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.