From 7d4da621ac76d9720b3067f07a5cc6975085b0f8 Mon Sep 17 00:00:00 2001 From: Mohammad Nejati Date: Mon, 12 Feb 2024 10:30:26 +0000 Subject: [PATCH] Update bytes_transferred documentation for http reads operations --- include/boost/beast/http/read.hpp | 93 ++++++++++--------------------- 1 file changed, 30 insertions(+), 63 deletions(-) diff --git a/include/boost/beast/http/read.hpp b/include/boost/beast/http/read.hpp index bbd85a5d..ec6ba06f 100644 --- a/include/boost/beast/http/read.hpp +++ b/include/boost/beast/http/read.hpp @@ -62,13 +62,9 @@ namespace http { @param parser The parser to use. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. @throws system_error Thrown on failure. - - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. */ template< class SyncReadStream, @@ -121,11 +117,7 @@ read_some( @param ec Set to the error, if any occurred. - @return The number of bytes transferred from the stream. - - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. + @return The number of bytes consumed by the parser. */ template< class SyncReadStream, @@ -189,7 +181,7 @@ read_some( @code void handler( error_code const& error, // result of operation - std::size_t bytes_transferred // the total number of bytes transferred from the stream + std::size_t bytes_transferred // the number of bytes consumed by the parser ); @endcode If the handler has an associated immediate executor, @@ -198,10 +190,6 @@ read_some( this function. Invocation of the handler will be performed in a manner equivalent to using `net::post`. - @note The completion handler will receive as a parameter the total number - of bytes transferred from the stream. This may be zero for the case where - there is sufficient pre-existing message data in the dynamic buffer. - @par Per-Operation Cancellation This asynchronous operation supports cancellation for the following @@ -270,14 +258,12 @@ async_read_some( @param parser The parser to use. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. @throws system_error Thrown on failure. - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. The implementation will call - @ref basic_parser::eager with the value `false` on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `false` on the parser passed in. */ template< class SyncReadStream, @@ -329,12 +315,10 @@ read_header( @param ec Set to the error, if any occurred. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. The implementation will call - @ref basic_parser::eager with the value `false` on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `false` on the parser passed in. */ template< class SyncReadStream, @@ -397,7 +381,7 @@ read_header( @code void handler( error_code const& error, // result of operation - std::size_t bytes_transferred // the total number of bytes transferred from the stream + std::size_t bytes_transferred // the number of bytes consumed by the parser ); @endcode If the handler has an associated immediate executor, @@ -406,11 +390,8 @@ read_header( this function. Invocation of the handler will be performed in a manner equivalent to using `net::post`. - @note The completion handler will receive as a parameter the total number - of bytes transferred from the stream. This may be zero for the case where - there is sufficient pre-existing message data in the dynamic buffer. The - implementation will call @ref basic_parser::eager with the value `false` - on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `false` on the parser passed in. @par Per-Operation Cancellation @@ -480,14 +461,12 @@ async_read_header( @param parser The parser to use. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. @throws system_error Thrown on failure. - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. The implementation will call - @ref basic_parser::eager with the value `true` on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `true` on the parser passed in. */ template< class SyncReadStream, @@ -539,12 +518,10 @@ read( @param ec Set to the error, if any occurred. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. The implementation will call - @ref basic_parser::eager with the value `true` on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `true` on the parser passed in. */ template< class SyncReadStream, @@ -607,7 +584,7 @@ read( @code void handler( error_code const& error, // result of operation - std::size_t bytes_transferred // the total number of bytes transferred from the stream + std::size_t bytes_transferred // the number of bytes consumed by the parser ); @endcode If the handler has an associated immediate executor, @@ -616,11 +593,8 @@ read( this function. Invocation of the handler will be performed in a manner equivalent to using `net::post`. - @note The completion handler will receive as a parameter the total number - of bytes transferred from the stream. This may be zero for the case where - there is sufficient pre-existing message data in the dynamic buffer. The - implementation will call @ref basic_parser::eager with the value `true` - on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `true` on the parser passed in. @par Per-Operation Cancellation @@ -693,14 +667,12 @@ async_read( is undefined. The type must be meet the MoveAssignable and MoveConstructible requirements. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. @throws system_error Thrown on failure. - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. The implementation will call - @ref basic_parser::eager with the value `true` on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `true` on the parser passed in. */ template< class SyncReadStream, @@ -755,12 +727,10 @@ read( @param ec Set to the error, if any occurred. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. The implementation will call - @ref basic_parser::eager with the value `true` on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `true` on the parser passed in. */ template< class SyncReadStream, @@ -826,7 +796,7 @@ read( @code void handler( error_code const& error, // result of operation - std::size_t bytes_transferred // the total number of bytes transferred from the stream + std::size_t bytes_transferred // the number of bytes consumed by the parser ); @endcode If the handler has an associated immediate executor, @@ -835,11 +805,8 @@ read( this function. Invocation of the handler will be performed in a manner equivalent to using `net::post`. - @note The completion handler will receive as a parameter the total number - of bytes transferred from the stream. This may be zero for the case where - there is sufficient pre-existing message data in the dynamic buffer. The - implementation will call @ref basic_parser::eager with the value `true` - on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `true` on the parser passed in. @par Per-Operation Cancellation