From 2b92189b65a90a269e0de288cbb0dbdb60969190 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Wed, 20 Feb 2019 18:55:01 -0800 Subject: [PATCH] Doc tidying --- doc/qbk/release_notes.qbk | 13 --- example/common/detect_ssl.hpp | 10 +- example/echo-op/echo_op.cpp | 4 +- .../beast/_experimental/http/icy_stream.hpp | 31 +++-- .../boost/beast/_experimental/test/stream.hpp | 46 +++++--- include/boost/beast/core/async_op_base.hpp | 10 +- include/boost/beast/core/basic_stream.hpp | 105 +++++++++-------- include/boost/beast/core/bind_handler.hpp | 2 + .../boost/beast/core/buffered_read_stream.hpp | 32 ++++-- .../beast/core/detail/bind_continuation.hpp | 2 + include/boost/beast/core/detail/read.hpp | 16 +-- include/boost/beast/core/flat_stream.hpp | 44 +++++--- include/boost/beast/core/handler_ptr.hpp | 4 +- include/boost/beast/core/saved_handler.hpp | 2 + include/boost/beast/http/read.hpp | 40 ++++--- include/boost/beast/http/write.hpp | 80 ++++++++----- include/boost/beast/websocket/ssl.hpp | 16 ++- include/boost/beast/websocket/stream.hpp | 106 +++++++++++------- include/boost/beast/websocket/teardown.hpp | 26 +++-- 19 files changed, 360 insertions(+), 229 deletions(-) diff --git a/doc/qbk/release_notes.qbk b/doc/qbk/release_notes.qbk index 451eedb5..159c4964 100644 --- a/doc/qbk/release_notes.qbk +++ b/doc/qbk/release_notes.qbk @@ -67,23 +67,10 @@ [heading Boost 1.70] -[/ - -Exposition: -Enlarged scope -- `net` is a namespace alias for `boost::asio` - async_op_base, stable_async_op_base -- New Networking refresher -- New websocket-chat-multi example -] - -[/-----------------------------------------------------------------------------] - [tip The namespace alias `net` is used throughout for `boost::asio`. ] - [/ includes up to version 209] diff --git a/example/common/detect_ssl.hpp b/example/common/detect_ssl.hpp index 46da82f8..a91c7988 100644 --- a/example/common/detect_ssl.hpp +++ b/example/common/detect_ssl.hpp @@ -211,9 +211,11 @@ detect_ssl( @param buffer The dynamic buffer to use. This type must meet the requirements of @b DynamicBuffer. - @param handler Invoked when the operation completes. - The handler may be moved or copied as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& error, // Set to the error, if any @@ -223,7 +225,7 @@ detect_ssl( 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_context::post`. + manner equivalent to using `net::post`. */ template< class AsyncReadStream, diff --git a/example/echo-op/echo_op.cpp b/example/echo-op/echo_op.cpp index 90035823..44b0d2d6 100644 --- a/example/echo-op/echo_op.cpp +++ b/example/echo-op/echo_op.cpp @@ -69,8 +69,8 @@ async_echo (AsyncStream& stream, DynamicBuffer& buffer, CompletionToken&& token) extended least until the completion handler is invoked. @param token The handler to be called when the operation completes. - The implementation will take ownership of the handler by move - construction. The handler must be invocable with this signature: + The implementation takes ownership of the handler by performing a decay-copy. + The handler must be invocable with this signature: @code void handler( beast::error_code error // Result of operation. diff --git a/include/boost/beast/_experimental/http/icy_stream.hpp b/include/boost/beast/_experimental/http/icy_stream.hpp index 6683dbbe..983a6a8b 100644 --- a/include/boost/beast/_experimental/http/icy_stream.hpp +++ b/include/boost/beast/_experimental/http/icy_stream.hpp @@ -208,16 +208,23 @@ public: buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called. - - @param handler The handler to be called when the read operation completes. - Copies will be made of the handler as required. The equivalent function - signature of the handler must be: + + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes read. ); @endcode - - @note The `read_some` operation may not read all of the requested number of + + 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 `net::post`. + + @note The `async_read_some` operation may not read all of the requested number of bytes. Consider using the function `net::async_read` if you need to ensure that the requested amount of data is read before the asynchronous operation completes. @@ -283,13 +290,19 @@ public: retained by the caller, which must guarantee that they remain valid until the handler is called. - @param handler The handler to be called when the write operation completes. - Copies will be made of the handler as required. The equivalent function - signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes written. ); @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 `net::post`. @note The `async_write_some` operation may not transmit all of the data to the peer. Consider using the function `net::async_write` if you need diff --git a/include/boost/beast/_experimental/test/stream.hpp b/include/boost/beast/_experimental/test/stream.hpp index 4a385f61..6c29ab76 100644 --- a/include/boost/beast/_experimental/test/stream.hpp +++ b/include/boost/beast/_experimental/test/stream.hpp @@ -378,15 +378,23 @@ public: buffers is retained by the caller, which must guarantee that they remain valid until the handler is called. - @param handler The handler to be called when the read operation completes. - Copies will be made of the handler as required. The equivalent function - signature of the handler must be: - @code void handler( - const boost::system::error_code& error, // Result of operation. - std::size_t bytes_transferred // Number of bytes read. - ); @endcode + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: - @note The `read_some` operation may not read all of the requested number of + @code + void handler( + error_code const& ec, // Result of operation. + std::size_t bytes_transferred // Number of bytes read. + ); + @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 `net::post`. + + @note The `async_read_some` operation may not read all of the requested number of bytes. Consider using the function `net::async_read` if you need to ensure that the requested amount of data is read before the asynchronous operation completes. @@ -448,13 +456,21 @@ public: retained by the caller, which must guarantee that they remain valid until the handler is called. - @param handler The handler to be called when the write operation completes. - Copies will be made of the handler as required. The equivalent function - signature of the handler must be: - @code void handler( - const boost::system::error_code& error, // Result of operation. - std::size_t bytes_transferred // Number of bytes written. - ); @endcode + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + + @code + void handler( + error_code const& ec, // Result of operation. + std::size_t bytes_transferred // Number of bytes written. + ); + @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 `net::post`. @note The `async_write_some` operation may not transmit all of the data to the peer. Consider using the function `net::async_write` if you need diff --git a/include/boost/beast/core/async_op_base.hpp b/include/boost/beast/core/async_op_base.hpp index 8af09e7d..d2748d18 100644 --- a/include/boost/beast/core/async_op_base.hpp +++ b/include/boost/beast/core/async_op_base.hpp @@ -197,8 +197,9 @@ class async_op_base public: /** Constructor - @param handler The final completion handler. The type of this - object must meet the requirements of CompletionHandler. + @param handler The final completion handler. + The type of this object must meet the requirements of CompletionHandler. + The implementation takes ownership of the handler by performing a decay-copy. @param ex1 The executor associated with the implied I/O object target of the operation. The implementation shall maintain an @@ -613,8 +614,9 @@ class stable_async_op_base public: /** Constructor - @param handler The final completion handler. The type of this - object must meet the requirements of CompletionHandler. + @param handler The final completion handler. + The type of this object must meet the requirements of CompletionHandler. + The implementation takes ownership of the handler by performing a decay-copy. @param ex1 The executor associated with the implied I/O object target of the operation. The implementation shall maintain an diff --git a/include/boost/beast/core/basic_stream.hpp b/include/boost/beast/core/basic_stream.hpp index 8c812f5e..41296285 100644 --- a/include/boost/beast/core/basic_stream.hpp +++ b/include/boost/beast/core/basic_stream.hpp @@ -883,9 +883,11 @@ public: @param ep The remote endpoint to which the underlying socket will be connected. Copies will be made of the endpoint object as required. - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code ec // Result of operation @@ -925,9 +927,11 @@ public: @param endpoints A sequence of endpoints. This this object must meet the requirements of EndpointSequence. - @param handler The handler to be called when the connect operation - completes. Ownership of the handler may be transferred. The function - signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( // Result of operation. if the sequence is empty, set to @@ -940,10 +944,10 @@ public: typename Protocol::endpoint const& endpoint ); @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 `net::post`. + 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 `net::post`. */ template< class EndpointSequence, @@ -993,9 +997,11 @@ public: The function object should return true if the next endpoint should be tried, and false if it should be skipped. - @param handler The handler to be called when the connect operation - completes. Ownership of the handler may be transferred. The function - signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( // Result of operation. if the sequence is empty, set to @@ -1008,10 +1014,10 @@ public: typename Protocol::endpoint const& endpoint ); @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 `net::post`. + 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 `net::post`. @par Example The following connect condition function object can be used to output @@ -1069,9 +1075,11 @@ public: @param end An iterator pointing to the end of a sequence of endpoints. - @param handler The handler to be called when the connect operation - completes. Ownership of the handler may be transferred. The function - signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( // Result of operation. if the sequence is empty, set to @@ -1084,10 +1092,10 @@ public: Iterator iterator ); @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 `net::post`. + 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 `net::post`. */ template< class Iterator, @@ -1122,9 +1130,12 @@ public: error_code const& ec, Iterator next); @endcode - @param handler The handler to be called when the connect operation - completes. Ownership of the handler may be transferred. The function - signature of the handler must be: + + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( // Result of operation. if the sequence is empty, set to @@ -1137,10 +1148,10 @@ public: Iterator iterator ); @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 `net::post`. + 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 `net::post`. */ template< class Iterator, @@ -1244,19 +1255,21 @@ public: underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called. - @param handler The handler to be called when the operation completes. - The implementation will take ownership of the handler by move construction. - The handler must be invocable with this signature: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code error, // Result of operation. std::size_t bytes_transferred // Number of bytes read. ); @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 - `net::post`. + 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 `net::post`. @note The `async_read_some` operation may not receive all of the requested number of bytes. Consider using the function `net::async_read` if you need @@ -1361,19 +1374,21 @@ public: underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called. - @param handler The handler to be called when the operation completes. - The implementation will take ownership of the handler by move construction. - The handler must be invocable with this signature: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code error, // Result of operation. std::size_t bytes_transferred // Number of bytes written. ); @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 - `net::post`. + 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 `net::post`. @note The `async_write_some` operation may not transmit all of the requested number of bytes. Consider using the function `net::async_write` if you need diff --git a/include/boost/beast/core/bind_handler.hpp b/include/boost/beast/core/bind_handler.hpp index a1cc8b2b..e0e31d7e 100644 --- a/include/boost/beast/core/bind_handler.hpp +++ b/include/boost/beast/core/bind_handler.hpp @@ -48,6 +48,7 @@ namespace beast { @endcode @param handler The handler to wrap. + The implementation takes ownership of the handler by performing a decay-copy. @param args A list of arguments to bind to the handler. The arguments are forwarded into the returned object. These @@ -100,6 +101,7 @@ bind_handler(Handler&& handler, Args&&... args) @endcode @param handler The handler to wrap. + The implementation takes ownership of the handler by performing a decay-copy. @param args A list of arguments to bind to the handler. The arguments are forwarded into the returned object. diff --git a/include/boost/beast/core/buffered_read_stream.hpp b/include/boost/beast/core/buffered_read_stream.hpp index b65c6f2e..fc7a47bb 100644 --- a/include/boost/beast/core/buffered_read_stream.hpp +++ b/include/boost/beast/core/buffered_read_stream.hpp @@ -247,17 +247,21 @@ public: is retained by the caller, which must guarantee that they remain valid until the handler is called. - @param handler Invoked when the operation completes. - The handler may be moved or copied as needed. - The equivalent function signature of the handler must be: - @code void handler( + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + + @code + void handler( error_code const& error, // result of operation std::size_t bytes_transferred // number of bytes transferred - ); @endcode + ); + @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 `net::io_context::post`. + manner equivalent to using `net::post`. */ template BOOST_ASIO_INITFN_RESULT_TYPE( @@ -319,17 +323,21 @@ public: retained by the caller, which must guarantee that they remain valid until the handler is called. - @param handler Invoked when the operation completes. - The handler may be moved or copied as needed. - The equivalent function signature of the handler must be: - @code void handler( + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + + @code + void handler( error_code const& error, // result of operation std::size_t bytes_transferred // number of bytes transferred - ); @endcode + ); + @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 `net::io_context::post`. + manner equivalent to using `net::post`. */ template BOOST_ASIO_INITFN_RESULT_TYPE( diff --git a/include/boost/beast/core/detail/bind_continuation.hpp b/include/boost/beast/core/detail/bind_continuation.hpp index def2b36d..7a5e06e9 100644 --- a/include/boost/beast/core/detail/bind_continuation.hpp +++ b/include/boost/beast/core/detail/bind_continuation.hpp @@ -32,6 +32,7 @@ namespace detail { flow of control. @param handler The handler to wrap. + The implementation takes ownership of the handler by performing a decay-copy. @see @@ -67,6 +68,7 @@ bind_continuation(CompletionHandler&& handler) @param ex The executor to use @param handler The handler to wrap + The implementation takes ownership of the handler by performing a decay-copy. @see diff --git a/include/boost/beast/core/detail/read.hpp b/include/boost/beast/core/detail/read.hpp index 437a500f..614988a6 100644 --- a/include/boost/beast/core/detail/read.hpp +++ b/include/boost/beast/core/detail/read.hpp @@ -194,9 +194,11 @@ read( in this case the optionally modifiable error passed to the completion condition will be delivered to the completion handler. - @param handler The handler to be called when the read operation completes. - The handler will be moved as needed. The handler must be invocable with - this function signature: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( @@ -209,10 +211,10 @@ read( // prior to the error. ); @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 - `net::io_context::post()`. + 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 `net::post`. */ template< class AsyncReadStream, diff --git a/include/boost/beast/core/flat_stream.hpp b/include/boost/beast/core/flat_stream.hpp index f0bc30db..d294ef16 100644 --- a/include/boost/beast/core/flat_stream.hpp +++ b/include/boost/beast/core/flat_stream.hpp @@ -231,13 +231,21 @@ public: buffers is retained by the caller, which must guarantee that they remain valid until the handler is called. - @param handler The handler to be called when the read operation completes. - Copies will be made of the handler as required. The equivalent function - signature of the handler must be: - @code void handler( - const boost::system::error_code& error, // Result of operation. - std::size_t bytes_transferred // Number of bytes read. - ); @endcode + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + + @code + void handler( + error_code const& error, // Result of operation. + std::size_t bytes_transferred // Number of bytes read. + ); + @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 `net::post`. @note The `read_some` operation may not read all of the requested number of bytes. Consider using the function `net::async_read` if you need @@ -305,13 +313,21 @@ public: retained by the caller, which must guarantee that they remain valid until the handler is called. - @param handler The handler to be called when the write operation completes. - Copies will be made of the handler as required. The equivalent function - signature of the handler must be: - @code void handler( - const boost::system::error_code& error, // Result of operation. - std::size_t bytes_transferred // Number of bytes written. - ); @endcode + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + + @code + void handler( + error_code const& ec, // Result of operation. + std::size_t bytes_transferred // Number of bytes written. + ); + @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 `net::post`. @note The `async_write_some` operation may not transmit all of the data to the peer. Consider using the function `net::async_write` if you need diff --git a/include/boost/beast/core/handler_ptr.hpp b/include/boost/beast/core/handler_ptr.hpp index 417501c0..3390a7da 100644 --- a/include/boost/beast/core/handler_ptr.hpp +++ b/include/boost/beast/core/handler_ptr.hpp @@ -106,8 +106,8 @@ public: @par Exception Safety Strong guarantee. - @param handler The handler to associate with the owned - object. The argument will be moved if it is an xvalue. + @param handler The handler to associate with the owned object. + The implementation takes ownership of the handler by performing a decay-copy. @param args Optional arguments forwarded to the owned object's constructor. diff --git a/include/boost/beast/core/saved_handler.hpp b/include/boost/beast/core/saved_handler.hpp index 7677bc19..069484f5 100644 --- a/include/boost/beast/core/saved_handler.hpp +++ b/include/boost/beast/core/saved_handler.hpp @@ -69,6 +69,7 @@ public: Requires `this->has_value() == false`. @param handler The completion handler to store. + The implementation takes ownership of the handler by performing a decay-copy. @param alloc The allocator to use. */ @@ -83,6 +84,7 @@ public: allocator to obtian storage. @param handler The completion handler to store. + The implementation takes ownership of the handler by performing a decay-copy. */ template void diff --git a/include/boost/beast/http/read.hpp b/include/boost/beast/http/read.hpp index 1aa01385..fafd8277 100644 --- a/include/boost/beast/http/read.hpp +++ b/include/boost/beast/http/read.hpp @@ -181,9 +181,11 @@ read_some( @param parser The parser to use. The object must remain valid at least until the handler is called; ownership is not transferred. - @param handler Invoked when the operation completes. The handler will - be moved as needed. The handler must be invocable with the following - signature: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& error, // result of operation @@ -193,7 +195,7 @@ read_some( 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 `net::io_context::post`. + 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 @@ -372,9 +374,11 @@ read_header( @param parser The parser to use. The object must remain valid at least until the handler is called; ownership is not transferred. - @param handler Invoked when the operation completes. The handler will - be moved as needed. The handler must be invocable with the following - signature: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& error, // result of operation @@ -384,7 +388,7 @@ read_header( 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 `net::io_context::post`. + 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 @@ -565,9 +569,11 @@ read( @param parser The parser to use. The object must remain valid at least until the handler is called; ownership is not transferred. - @param handler Invoked when the operation completes. The handler will - be moved as needed. The handler must be invocable with the following - signature: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& error, // result of operation @@ -577,7 +583,7 @@ read( 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 `net::io_context::post`. + 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 @@ -767,9 +773,11 @@ read( MoveConstructible requirements. The object must remain valid at least until the handler is called; ownership is not transferred. - @param handler Invoked when the operation completes. The handler will - be moved as needed. The handler must be invocable with the following - signature: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& error, // result of operation @@ -779,7 +787,7 @@ read( 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 `net::io_context::post`. + 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 diff --git a/include/boost/beast/http/write.hpp b/include/boost/beast/http/write.hpp index 95631a15..ccc09956 100644 --- a/include/boost/beast/http/write.hpp +++ b/include/boost/beast/http/write.hpp @@ -149,17 +149,21 @@ write_some( The object must remain valid at least until the handler is called; ownership is not transferred. - @param handler Invoked when the operation completes. - The handler may be moved or copied as needed. - The equivalent function signature of the handler must be: - @code void handler( + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + + @code + void handler( error_code const& error, // result of operation std::size_t bytes_transferred // the number of bytes written to the stream - ); @endcode + ); + @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 `net::io_context::post`. + manner equivalent to using `net::post`. @see @ref serializer */ @@ -270,17 +274,21 @@ write_header( The object must remain valid at least until the handler is called; ownership is not transferred. - @param handler Invoked when the operation completes. - The handler may be moved or copied as needed. - The equivalent function signature of the handler must be: - @code void handler( + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + + @code + void handler( error_code const& error, // result of operation std::size_t bytes_transferred // the number of bytes written to the stream - ); @endcode + ); + @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 `net::io_context::post`. + manner equivalent to using `net::post`. @note The implementation will call @ref serializer::split with the value `true` on the serializer passed in. @@ -388,17 +396,21 @@ write( The object must remain valid at least until the handler is called; ownership is not transferred. - @param handler Invoked when the operation completes. - The handler may be moved or copied as needed. - The equivalent function signature of the handler must be: - @code void handler( + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + + @code + void handler( error_code const& error, // result of operation std::size_t bytes_transferred // the number of bytes written to the stream - ); @endcode + ); + @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 `net::io_context::post`. + manner equivalent to using `net::post`. @see @ref serializer */ @@ -607,17 +619,21 @@ write( The object must remain valid at least until the handler is called; ownership is not transferred. - @param handler Invoked when the operation completes. - The handler may be moved or copied as needed. - The equivalent function signature of the handler must be: - @code void handler( + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + + @code + void handler( error_code const& error, // result of operation std::size_t bytes_transferred // the number of bytes written to the stream - ); @endcode + ); + @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 `net::io_context::post`. + manner equivalent to using `net::post`. @see @ref message */ @@ -665,17 +681,21 @@ async_write( The object must remain valid at least until the handler is called; ownership is not transferred. - @param handler Invoked when the operation completes. - The handler may be moved or copied as needed. - The equivalent function signature of the handler must be: - @code void handler( + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + + @code + void handler( error_code const& error, // result of operation std::size_t bytes_transferred // the number of bytes written to the stream - ); @endcode + ); + @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 `net::io_context::post`. + manner equivalent to using `net::post`. @see @ref message */ diff --git a/include/boost/beast/websocket/ssl.hpp b/include/boost/beast/websocket/ssl.hpp index 03226a16..79adcdf4 100644 --- a/include/boost/beast/websocket/ssl.hpp +++ b/include/boost/beast/websocket/ssl.hpp @@ -55,16 +55,20 @@ teardown( @param stream The stream to tear down. - @param handler Invoked when the operation completes. - The handler may be moved or copied as needed. - The equivalent function signature of the handler must be: - @code void handler( + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + + @code + void handler( error_code const& error // result of operation - ); @endcode + ); + @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 net::io_context::post(). + manner equivalent to using `net::post`. */ template diff --git a/include/boost/beast/websocket/stream.hpp b/include/boost/beast/websocket/stream.hpp index 87936683..76b08d5e 100644 --- a/include/boost/beast/websocket/stream.hpp +++ b/include/boost/beast/websocket/stream.hpp @@ -849,9 +849,11 @@ public: The implementation will not access the string data after the initiating function returns. - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& ec // Result of operation @@ -861,7 +863,7 @@ public: 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 `net::post`. - + @par Example @code ws.async_handshake("localhost", "/", @@ -926,9 +928,11 @@ public: The implementation will not access the string data after the initiating function returns. - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& ec // Result of operation @@ -1262,9 +1266,11 @@ public: pass the request to the appropriate overload of @ref accept or @ref async_accept - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& ec // Result of operation @@ -1323,9 +1329,11 @@ public: then to received WebSocket frames. The implementation will copy the caller provided data before the function returns. - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& ec // Result of operation @@ -1384,9 +1392,11 @@ public: Ownership is not transferred, the implementation will not access this object from other threads. - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& ec // Result of operation @@ -1516,9 +1526,11 @@ public: sent with the close code and optional reason string. Otherwise, the close frame is sent with no payload. - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& ec // Result of operation @@ -1614,9 +1626,11 @@ public: The implementation will not access the contents of this object after the initiating function returns. - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& ec // Result of operation @@ -1715,9 +1729,11 @@ public: The implementation will not access the contents of this object after the initiating function returns. - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& ec // Result of operation @@ -1868,9 +1884,11 @@ public: @param buffer A dynamic buffer to append message data to. - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& ec, // Result of operation @@ -2041,9 +2059,11 @@ public: will append into the buffer. If this value is zero, then a reasonable size will be chosen automatically. - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& ec, // Result of operation @@ -2210,9 +2230,11 @@ public: pointed to by the buffer sequence remain valid until the completion handler is called. - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& ec, // Result of operation @@ -2325,9 +2347,11 @@ public: the memory locations pointed to by buffers remains valid until the completion handler is called. - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& ec, // Result of operation @@ -2444,9 +2468,11 @@ public: the memory locations pointed to by buffers remains valid until the completion handler is called. - @param handler Invoked when the operation completes. Ownership - of the handler will be transferred by move-construction as needed. - The equivalent function signature of the handler must be: + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + @code void handler( error_code const& ec, // Result of operation diff --git a/include/boost/beast/websocket/teardown.hpp b/include/boost/beast/websocket/teardown.hpp index 3a19e466..e9fcf2f8 100644 --- a/include/boost/beast/websocket/teardown.hpp +++ b/include/boost/beast/websocket/teardown.hpp @@ -69,17 +69,20 @@ teardown( @param socket The socket to tear down. - @param handler Invoked when the operation completes. - The handler may be moved or copied as needed. - The equivalent function signature of the handler must be: - @code void handler( + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + + @code + void handler( error_code const& error // result of operation ); @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 net::io_context::post(). + manner equivalent to using `net::post`. */ template< @@ -147,17 +150,20 @@ teardown( @param socket The socket to tear down. - @param handler Invoked when the operation completes. - The handler may be moved or copied as needed. - The equivalent function signature of the handler must be: - @code void handler( + @param handler The completion handler to invoke when the operation + completes. The implementation takes ownership of the handler by + performing a decay-copy. The equivalent function signature of + the handler must be: + + @code + void handler( error_code const& error // result of operation ); @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 net::io_context::post(). + manner equivalent to using `net::post`. */ template<