diff --git a/doc/history.qbk b/doc/history.qbk index 1eec7fbeff..9af32d0219 100644 --- a/doc/history.qbk +++ b/doc/history.qbk @@ -740,15 +740,14 @@ operation is launched with location information, it outputs lines using the [*] [^n^m], prior to the [^n*m] line that signifies the beginning of the asynchronous operation. For example: - `` + [pre @asio|1589423304.861944|>7|ec=system:0,bytes_transferred=5 @asio|1589423304.861952|7^8|in 'async_write' (./../../../include/asio/impl/write.hpp:330) @asio|1589423304.861952|7^8|called from 'do_write' (handler_tracking/async_tcp_echo_server.cpp:62) @asio|1589423304.861952|7^8|called from 'operator()' (handler_tracking/async_tcp_echo_server.cpp:51) @asio|1589423304.861952|7*8|socket@0x7ff61c008230.async_send @asio|1589423304.861975|.8|non_blocking_send,ec=system:0,bytes_transferred=5 - @asio|1589423304.861980|<7| - ``[br] + @asio|1589423304.861980|<7|][br] If `std::source_location` or `std::experimental::source_location` are available, the `use_awaitable_t` token (when default-constructed or used as a default completion token) will also cause handler tracking to output a source @@ -777,21 +776,18 @@ include only those events in the tree that produced the nominated handlers. For example, to filter the output to include only the events associated with handlers `123`, `456`, and their predecessors: - `` - cat output.txt | perl handlertree.pl 123 456 - `` + [pre + cat output.txt | perl handlertree.pl 123 456] or: - `` - perl handlertree.pl 123 456 < output.txt - ``[br] + [pre + perl handlertree.pl 123 456 < output.txt][br] This script may be combined with handerlive.pl and handlerviz.pl to produce a graph of the "live" asynchronous operation chains. For example: - `` + [pre cat output.txt | \ perl handlertree.pl `perl handlerlive.pl output.txt` | \ perl handlerviz.pl | \ - dot -Tsvg > output.svg - ``[br] + dot -Tsvg > output.svg][br] * Added changes for clang-based Embarcadero C++ compilers. * Fixed a deadlock that can occur when multiple threads concurrently initialise the Windows I/O completion port backend. diff --git a/doc/model_dox.txt b/doc/model_dox.txt new file mode 100644 index 0000000000..bf28d6bde8 --- /dev/null +++ b/doc/model_dox.txt @@ -0,0 +1,14 @@ +// +// Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// +// Distributed under the Boost Software License, Version 1.0. (See accompanying +// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +// + +/** +\page asynchronous_operation asynchronous operation +*/ + +/** +\page completion_token completion token +*/ diff --git a/doc/quickref.xml b/doc/quickref.xml index 3af3dad904..a871b88775 100644 --- a/doc/quickref.xml +++ b/doc/quickref.xml @@ -439,11 +439,13 @@ DynamicBuffer_v2 MutableBufferSequence ReadHandler + ReadToken SyncRandomAccessReadDevice SyncRandomAccessWriteDevice SyncReadStream SyncWriteStream WriteHandler + WriteToken @@ -575,18 +577,24 @@ Asynchronous socket operations AcceptableProtocol AcceptHandler + AcceptToken ConnectCondition ConnectHandler + ConnectToken Endpoint EndpointSequence GettableSocketOption InternetProtocol IoControlCommand IteratorConnectHandler + IteratorConnectToken MoveAcceptHandler + MoveAcceptToken Protocol RangeConnectHandler + RangeConnectToken ResolveHandler + ResolveToken SettableSocketOption @@ -635,6 +643,7 @@ TimeTraits WaitHandler + WaitToken WaitTraits @@ -659,8 +668,11 @@ Type Requirements BufferedHandshakeHandler + BufferedHandshakeToken HandshakeHandler + HandshakeToken ShutdownHandler + ShutdownToken @@ -699,6 +711,7 @@ Type Requirements SignalHandler + SignalToken diff --git a/doc/reference.dox b/doc/reference.dox index 7f5d5d7a9e..25054fbe9f 100644 --- a/doc/reference.dox +++ b/doc/reference.dox @@ -83,6 +83,7 @@ INPUT = ./../../../boost/asio.hpp \ ./../../../boost/asio/windows \ ./../../../boost/asio/execution \ ./../../../boost/asio/experimental \ + ./model_dox.txt \ ./noncopyable_dox.txt \ ./std_exception_dox.txt FILE_PATTERNS = diff --git a/doc/reference.xsl b/doc/reference.xsl index 4e893661de..7105f3b879 100644 --- a/doc/reference.xsl +++ b/doc/reference.xsl @@ -46,17 +46,20 @@ [include requirements/asynchronous_socket_operations.qbk] [include requirements/AcceptableProtocol.qbk] [include requirements/AcceptHandler.qbk] +[include requirements/AcceptToken.qbk] [include requirements/AsyncRandomAccessReadDevice.qbk] [include requirements/AsyncRandomAccessWriteDevice.qbk] [include requirements/AsyncReadStream.qbk] [include requirements/AsyncWriteStream.qbk] [include requirements/BufferedHandshakeHandler.qbk] +[include requirements/BufferedHandshakeToken.qbk] [include requirements/CancellationHandler.qbk] [include requirements/CancellationSlot.qbk] [include requirements/CompletionCondition.qbk] [include requirements/CompletionHandler.qbk] [include requirements/ConnectCondition.qbk] [include requirements/ConnectHandler.qbk] +[include requirements/ConnectToken.qbk] [include requirements/ConstBufferSequence.qbk] [include requirements/DynamicBuffer.qbk] [include requirements/DynamicBuffer_v1.qbk] @@ -69,35 +72,45 @@ [include requirements/GettableSocketOption.qbk] [include requirements/Handler.qbk] [include requirements/HandshakeHandler.qbk] +[include requirements/HandshakeToken.qbk] [include requirements/InternetProtocol.qbk] [include requirements/IoControlCommand.qbk] [include requirements/IoObjectService.qbk] [include requirements/IteratorConnectHandler.qbk] +[include requirements/IteratorConnectToken.qbk] [include requirements/LegacyCompletionHandler.qbk] [include requirements/MoveAcceptHandler.qbk] +[include requirements/MoveAcceptToken.qbk] [include requirements/MutableBufferSequence.qbk] [include requirements/OperationState.qbk] [include requirements/ProtoAllocator.qbk] [include requirements/Protocol.qbk] [include requirements/RangeConnectHandler.qbk] +[include requirements/RangeConnectToken.qbk] [include requirements/ReadHandler.qbk] +[include requirements/ReadToken.qbk] [include requirements/Receiver.qbk] [include requirements/ResolveHandler.qbk] +[include requirements/ResolveToken.qbk] [include requirements/Scheduler.qbk] [include requirements/Sender.qbk] [include requirements/Service.qbk] [include requirements/SettableSerialPortOption.qbk] [include requirements/SettableSocketOption.qbk] [include requirements/ShutdownHandler.qbk] +[include requirements/ShutdownToken.qbk] [include requirements/SignalHandler.qbk] +[include requirements/SignalToken.qbk] [include requirements/SyncRandomAccessReadDevice.qbk] [include requirements/SyncRandomAccessWriteDevice.qbk] [include requirements/SyncReadStream.qbk] [include requirements/SyncWriteStream.qbk] [include requirements/TimeTraits.qbk] [include requirements/WaitHandler.qbk] +[include requirements/WaitToken.qbk] [include requirements/WaitTraits.qbk] [include requirements/WriteHandler.qbk] +[include requirements/WriteToken.qbk] @@ -694,6 +707,16 @@ `] + + [link boost_asio.overview.model.async_ops + + ] + + + [link boost_asio.overview.model.completion_tokens + + ] + ` @@ -727,6 +750,16 @@ `] + + [link boost_asio.overview.model.async_ops + + ] + + + [link boost_asio.overview.model.completion_tokens + + ] + ` diff --git a/doc/requirements/AcceptHandler.qbk b/doc/requirements/AcceptHandler.qbk index 9d5bbddff7..7c2e3709aa 100644 --- a/doc/requirements/AcceptHandler.qbk +++ b/doc/requirements/AcceptHandler.qbk @@ -12,61 +12,4 @@ boost_asio.reference.Handler handler]. A value `h` of an accept handler class should work correctly in the expression `h(ec)`, where `ec` is an lvalue of type `const error_code`. -[heading Examples] - -A free function as an accept handler: - - void accept_handler( - const boost::system::error_code& ec) - { - ... - } - -An accept handler function object: - - struct accept_handler - { - ... - void operator()( - const boost::system::error_code& ec) - { - ... - } - ... - }; - -A lambda as an accept handler: - - acceptor.async_accept(..., - [](const boost::system::error_code& ec) - { - ... - }); - -A non-static class member function adapted to an accept handler using -`std::bind()`: - - void my_class::accept_handler( - const boost::system::error_code& ec) - { - ... - } - ... - acceptor.async_accept(..., - std::bind(&my_class::accept_handler, - this, std::placeholders::_1)); - -A non-static class member function adapted to an accept handler using -`boost::bind()`: - - void my_class::accept_handler( - const boost::system::error_code& ec) - { - ... - } - ... - acceptor.async_accept(..., - boost::bind(&my_class::accept_handler, - this, boost::asio::placeholders::error)); - [endsect] diff --git a/doc/requirements/AcceptToken.qbk b/doc/requirements/AcceptToken.qbk new file mode 100644 index 0000000000..db8449efa2 --- /dev/null +++ b/doc/requirements/AcceptToken.qbk @@ -0,0 +1,99 @@ +[/ + / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:AcceptToken Accept token requirements] + +A accept token is a [link boost_asio.overview.model.completion_tokens completion +token] for completion signature `void(error_code)`. + +[heading Examples] + +A free function as a accept token: + + void accept_handler( + const boost::system::error_code& ec) + { + ... + } + +A accept token function object: + + struct accept_handler + { + ... + void operator()( + const boost::system::error_code& ec) + { + ... + } + ... + }; + +A lambda as a accept token: + + acceptor.async_accept(..., + [](const boost::system::error_code& ec) + { + ... + }); + +A non-static class member function adapted to a accept token using +`std::bind()`: + + void my_class::accept_handler( + const boost::system::error_code& ec) + { + ... + } + ... + acceptor.async_accept(..., + std::bind(&my_class::accept_handler, + this, std::placeholders::_1)); + +A non-static class member function adapted to a accept token using +`boost::bind()`: + + void my_class::accept_handler( + const boost::system::error_code& ec) + { + ... + } + ... + acceptor.async_accept(..., + boost::bind(&my_class::accept_handler, + this, boost::asio::placeholders::error)); + +Using [link boost_asio.reference.use_future use_future] as a accept token: + + std::future f = acceptor.async_accept(..., boost::asio::use_future); + ... + try + { + f.get(); + } + catch (const system_error& e) + { + ... + } + +Using [link boost_asio.reference.use_awaitable use_awaitable] as a accept token: + + boost::asio::awaitable my_coroutine() + { + try + { + ... + co_await acceptor.async_accept(..., boost::asio::use_awaitable); + ... + } + catch (const system_error& e) + { + ... + } + } + +[endsect] diff --git a/doc/requirements/BufferedHandshakeHandler.qbk b/doc/requirements/BufferedHandshakeHandler.qbk index 1e451c1c68..207f00c7e7 100644 --- a/doc/requirements/BufferedHandshakeHandler.qbk +++ b/doc/requirements/BufferedHandshakeHandler.qbk @@ -12,44 +12,4 @@ boost_asio.reference.Handler handler]. A value `h` of a buffered handshake handl class should work correctly in the expression `h(ec, s)`, where `ec` is an lvalue of type `const error_code` and `s` is an lvalue of type `const size_t`. -[heading Examples] - -A free function as a buffered handshake handler: - - void handshake_handler( - const boost::system::error_code& ec, - std::size_t bytes_transferred) - { - ... - } - -A buffered handshake handler function object: - - struct handshake_handler - { - ... - void operator()( - const boost::system::error_code& ec, - std::size_t bytes_transferred) - { - ... - } - ... - }; - -A non-static class member function adapted to a buffered handshake handler -using `boost::bind()`: - - void my_class::handshake_handler( - const boost::system::error_code& ec, - std::size_t bytes_transferred) - { - ... - } - ... - socket.async_handshake(..., - boost::bind(&my_class::handshake_handler, - this, boost::asio::placeholders::error, - boost::asio::placeholders::bytes_transferred)); - [endsect] diff --git a/doc/requirements/BufferedHandshakeToken.qbk b/doc/requirements/BufferedHandshakeToken.qbk new file mode 100644 index 0000000000..9c0269f237 --- /dev/null +++ b/doc/requirements/BufferedHandshakeToken.qbk @@ -0,0 +1,111 @@ +[/ + / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:BufferedHandshakeToken SSL buffered handshake token requirements] + +A buffered_handshake token is a [link boost_asio.overview.model.completion_tokens +completion token] for completion signature `void(error_code, size_t)`. + +[heading Examples] + +A free function as a buffered_handshake token: + + void buffered_handshake_handler( + const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + } + +A buffered_handshake token function object: + + struct buffered_handshake_handler + { + ... + void operator()( + const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + } + ... + }; + +A lambda as a buffered_handshake token: + + ssl_stream.async_handshake(..., + [](const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + }); + +A non-static class member function adapted to a buffered_handshake token using +`std::bind()`: + + void my_class::buffered_handshake_handler( + const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + } + ... + ssl_stream.async_handshake(..., + std::bind(&my_class::buffered_handshake_handler, + this, std::placeholders::_1, + std::placeholders::_2)); + +A non-static class member function adapted to a buffered_handshake token using +`boost::bind()`: + + void my_class::buffered_handshake_handler( + const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + } + ... + ssl_stream.async_handshake(..., + boost::bind(&my_class::buffered_handshake_handler, + this, boost::asio::placeholders::error, + boost::asio::placeholders::bytes_transferred)); + +Using [link boost_asio.reference.use_future use_future] as a buffered handshake token: + + std::future f = + ssl_stream.async_handshake(..., boost::asio::use_future); + ... + try + { + std::size_t n = f.get(); + ... + } + catch (const system_error& e) + { + ... + } + +Using [link boost_asio.reference.use_awaitable use_awaitable] as a buffered handshake +token: + + boost::asio::awaitable my_coroutine() + { + try + { + ... + std::size_t n = + co_await ssl_stream.async_handshake( + ..., boost::asio::use_awaitable); + ... + } + catch (const system_error& e) + { + ... + } + } + +[endsect] diff --git a/doc/requirements/ConnectHandler.qbk b/doc/requirements/ConnectHandler.qbk index ac5696e544..85b23958c0 100644 --- a/doc/requirements/ConnectHandler.qbk +++ b/doc/requirements/ConnectHandler.qbk @@ -12,61 +12,4 @@ boost_asio.reference.Handler handler]. A value `h` of a connect handler class should work correctly in the expression `h(ec)`, where `ec` is an lvalue of type `const error_code`. -[heading Examples] - -A free function as a connect handler: - - void connect_handler( - const boost::system::error_code& ec) - { - ... - } - -A connect handler function object: - - struct connect_handler - { - ... - void operator()( - const boost::system::error_code& ec) - { - ... - } - ... - }; - -A lambda as a connect handler: - - socket.async_connect(..., - [](const boost::system::error_code& ec) - { - ... - }); - -A non-static class member function adapted to a connect handler using -`std::bind()`: - - void my_class::connect_handler( - const boost::system::error_code& ec) - { - ... - } - ... - socket.async_connect(..., - std::bind(&my_class::connect_handler, - this, std::placeholders::_1)); - -A non-static class member function adapted to a connect handler using -`boost::bind()`: - - void my_class::connect_handler( - const boost::system::error_code& ec) - { - ... - } - ... - socket.async_connect(..., - boost::bind(&my_class::connect_handler, - this, boost::asio::placeholders::error)); - [endsect] diff --git a/doc/requirements/ConnectToken.qbk b/doc/requirements/ConnectToken.qbk new file mode 100644 index 0000000000..683dd087bd --- /dev/null +++ b/doc/requirements/ConnectToken.qbk @@ -0,0 +1,99 @@ +[/ + / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:ConnectToken Connect token requirements] + +A connect token is a [link boost_asio.overview.model.completion_tokens completion token] +for completion signature `void(error_code)`. + +[heading Examples] + +A free function as a connect token: + + void connect_handler( + const boost::system::error_code& ec) + { + ... + } + +A connect token function object: + + struct connect_handler + { + ... + void operator()( + const boost::system::error_code& ec) + { + ... + } + ... + }; + +A lambda as a connect token: + + socket.async_connect(..., + [](const boost::system::error_code& ec) + { + ... + }); + +A non-static class member function adapted to a connect token using +`std::bind()`: + + void my_class::connect_handler( + const boost::system::error_code& ec) + { + ... + } + ... + socket.async_connect(..., + std::bind(&my_class::connect_handler, + this, std::placeholders::_1)); + +A non-static class member function adapted to a connect token using +`boost::bind()`: + + void my_class::connect_handler( + const boost::system::error_code& ec) + { + ... + } + ... + socket.async_connect(..., + boost::bind(&my_class::connect_handler, + this, boost::asio::placeholders::error)); + +Using [link boost_asio.reference.use_future use_future] as a connect token: + + std::future f = socket.async_connect(..., boost::asio::use_future); + ... + try + { + f.get(); + } + catch (const system_error& e) + { + ... + } + +Using [link boost_asio.reference.use_awaitable use_awaitable] as a connect token: + + boost::asio::awaitable my_coroutine() + { + try + { + ... + co_await socket.async_connect(..., boost::asio::use_awaitable); + ... + } + catch (const system_error& e) + { + ... + } + } + +[endsect] diff --git a/doc/requirements/HandshakeHandler.qbk b/doc/requirements/HandshakeHandler.qbk index 98218f4607..cd3196797a 100644 --- a/doc/requirements/HandshakeHandler.qbk +++ b/doc/requirements/HandshakeHandler.qbk @@ -12,61 +12,4 @@ boost_asio.reference.Handler handler]. A value `h` of a handshake handler class should work correctly in the expression `h(ec)`, where `ec` is an lvalue of type `const error_code`. -[heading Examples] - -A free function as a handshake handler: - - void handshake_handler( - const boost::system::error_code& ec) - { - ... - } - -A handshake handler function object: - - struct handshake_handler - { - ... - void operator()( - const boost::system::error_code& ec) - { - ... - } - ... - }; - -A lambda as a handshake handler: - - ssl_stream.async_handshake(..., - [](const boost::system::error_code& ec) - { - ... - }); - -A non-static class member function adapted to a handshake handler using -`std::bind()`: - - void my_class::handshake_handler( - const boost::system::error_code& ec) - { - ... - } - ... - ssl_stream.async_handshake(..., - std::bind(&my_class::handshake_handler, - this, std::placeholders::_1)); - -A non-static class member function adapted to a handshake handler using -`boost::bind()`: - - void my_class::handshake_handler( - const boost::system::error_code& ec) - { - ... - } - ... - ssl_stream.async_handshake(..., - boost::bind(&my_class::handshake_handler, - this, boost::asio::placeholders::error)); - [endsect] diff --git a/doc/requirements/HandshakeToken.qbk b/doc/requirements/HandshakeToken.qbk new file mode 100644 index 0000000000..ef1aa4ae7f --- /dev/null +++ b/doc/requirements/HandshakeToken.qbk @@ -0,0 +1,99 @@ +[/ + / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:HandshakeToken SSL handshake token requirements] + +A handshake token is a [link boost_asio.overview.model.completion_tokens completion +token] for completion signature `void(error_code)`. + +[heading Examples] + +A free function as a handshake token: + + void handshake_handler( + const boost::system::error_code& ec) + { + ... + } + +A handshake token function object: + + struct handshake_handler + { + ... + void operator()( + const boost::system::error_code& ec) + { + ... + } + ... + }; + +A lambda as a handshake token: + + ssl_stream.async_handshake(..., + [](const boost::system::error_code& ec) + { + ... + }); + +A non-static class member function adapted to a handshake token using +`std::bind()`: + + void my_class::handshake_handler( + const boost::system::error_code& ec) + { + ... + } + ... + ssl_stream.async_handshake(..., + std::bind(&my_class::handshake_handler, + this, std::placeholders::_1)); + +A non-static class member function adapted to a handshake token using +`boost::bind()`: + + void my_class::handshake_handler( + const boost::system::error_code& ec) + { + ... + } + ... + ssl_stream.async_handshake(..., + boost::bind(&my_class::handshake_handler, + this, boost::asio::placeholders::error)); + +Using [link boost_asio.reference.use_future use_future] as a handshake token: + + std::future f = ssl_stream.async_handshake(..., boost::asio::use_future); + ... + try + { + f.get(); + } + catch (const system_error& e) + { + ... + } + +Using [link boost_asio.reference.use_awaitable use_awaitable] as a handshake token: + + boost::asio::awaitable my_coroutine() + { + try + { + ... + co_await ssl_stream.async_handshake(..., boost::asio::use_awaitable); + ... + } + catch (const system_error& e) + { + ... + } + } + +[endsect] diff --git a/doc/requirements/IteratorConnectHandler.qbk b/doc/requirements/IteratorConnectHandler.qbk index 6fe97a515f..8e10e98639 100644 --- a/doc/requirements/IteratorConnectHandler.qbk +++ b/doc/requirements/IteratorConnectHandler.qbk @@ -11,71 +11,6 @@ An iterator connect handler must meet the requirements for a [link boost_asio.reference.Handler handler]. A value `h` of an iterator connect handler class should work correctly in the expression `h(ec, i)`, where `ec` is an lvalue of type `const error_code` and `i` is an lvalue of the type `Iterator` -used in the corresponding `connect()` or async_connect()` function. - -[heading Examples] - -A free function as an iterator connect handler: - - void connect_handler( - const boost::system::error_code& ec, - boost::asio::ip::tcp::resolver::iterator iterator) - { - ... - } - -An iterator connect handler function object: - - struct connect_handler - { - ... - template - void operator()( - const boost::system::error_code& ec, - Iterator iterator) - { - ... - } - ... - }; - -A lambda as an iterator connect handler: - - boost::asio::async_connect(..., - [](const boost::system::error_code& ec, - boost::asio::ip::tcp::resolver::iterator iterator) - { - ... - }); - -A non-static class member function adapted to an iterator connect handler using -`std::bind()`: - - void my_class::connect_handler( - const boost::system::error_code& ec, - boost::asio::ip::tcp::resolver::iterator iterator) - { - ... - } - ... - boost::asio::async_connect(..., - std::bind(&my_class::connect_handler, - this, std::placeholders::_1, - std::placeholders::_2)); - -A non-static class member function adapted to an iterator connect handler using -`boost::bind()`: - - void my_class::connect_handler( - const boost::system::error_code& ec, - boost::asio::ip::tcp::resolver::iterator iterator) - { - ... - } - ... - boost::asio::async_connect(..., - boost::bind(&my_class::connect_handler, - this, boost::asio::placeholders::error, - boost::asio::placeholders::iterator)); +used in the corresponding `async_connect()` function. [endsect] diff --git a/doc/requirements/IteratorConnectToken.qbk b/doc/requirements/IteratorConnectToken.qbk new file mode 100644 index 0000000000..3a788df3cb --- /dev/null +++ b/doc/requirements/IteratorConnectToken.qbk @@ -0,0 +1,113 @@ +[/ + / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:IteratorConnectToken Iterator connect token requirements] + +An iterator connect token is a [link boost_asio.overview.model.completion_tokens +completion token] for completion signature `void(error_code, Iterator)`, where +the type `Iterator` is used in the corresponding `async_connect()` function. + +[heading Examples] + +A free function as an iterator connect token: + + void connect_handler( + const boost::system::error_code& ec, + boost::asio::ip::tcp::resolver::iterator iterator) + { + ... + } + +An iterator connect token function object: + + struct connect_handler + { + ... + template + void operator()( + const boost::system::error_code& ec, + Iterator iterator) + { + ... + } + ... + }; + +A lambda as an iterator connect token: + + boost::asio::async_connect(..., + [](const boost::system::error_code& ec, + boost::asio::ip::tcp::resolver::iterator iterator) + { + ... + }); + +A non-static class member function adapted to an iterator connect token using +`std::bind()`: + + void my_class::connect_handler( + const boost::system::error_code& ec, + boost::asio::ip::tcp::resolver::iterator iterator) + { + ... + } + ... + boost::asio::async_connect(..., + std::bind(&my_class::connect_handler, + this, std::placeholders::_1, + std::placeholders::_2)); + +A non-static class member function adapted to an iterator connect token using +`boost::bind()`: + + void my_class::connect_handler( + const boost::system::error_code& ec, + boost::asio::ip::tcp::resolver::iterator iterator) + { + ... + } + ... + boost::asio::async_connect(..., + boost::bind(&my_class::connect_handler, + this, boost::asio::placeholders::error, + boost::asio::placeholders::iterator)); + +Using [link boost_asio.reference.use_future use_future] as an iterator connect token: + + std::future f = + boost::asio::async_connect(..., boost::asio::use_future); + ... + try + { + boost::asio::ip::tcp::resolver::iterator i = f.get(); + ... + } + catch (const system_error& e) + { + ... + } + +Using [link boost_asio.reference.use_awaitable use_awaitable] as an iterator connect +token: + + boost::asio::awaitable my_coroutine() + { + try + { + ... + boost::asio::ip::tcp::resolver::iterator i = + co_await boost::asio::async_connect( + ..., boost::asio::use_awaitable); + ... + } + catch (const system_error& e) + { + ... + } + } + +[endsect] diff --git a/doc/requirements/MoveAcceptHandler.qbk b/doc/requirements/MoveAcceptHandler.qbk index 21fcaa18f2..10dacaa302 100644 --- a/doc/requirements/MoveAcceptHandler.qbk +++ b/doc/requirements/MoveAcceptHandler.qbk @@ -13,49 +13,4 @@ should work correctly in the expression `h(ec, s)`, where `ec` is an lvalue of type `const error_code` and `s` is an lvalue of the nested type `Protocol::socket` for the type `Protocol` of the socket class template. -[heading Examples] - -A free function as a move accept handler: - - void accept_handler( - const boost::system::error_code& ec, boost::asio::ip::tcp::socket s) - { - ... - } - -A move accept handler function object: - - struct accept_handler - { - ... - void operator()( - const boost::system::error_code& ec, boost::asio::ip::tcp::socket s) - { - ... - } - ... - }; - -A lambda as a move accept handler: - - acceptor.async_accept(..., - [](const boost::system::error_code& ec, boost::asio::ip::tcp::socket s) - { - ... - }); - -A non-static class member function adapted to a move accept handler using -`std::bind()`: - - void my_class::accept_handler( - const boost::system::error_code& ec, boost::asio::ip::tcp::socket socket) - { - ... - } - ... - boost::asio::async_accept(..., - std::bind(&my_class::accept_handler, - this, std::placeholders::_1, - std::placeholders::_2)); - [endsect] diff --git a/doc/requirements/MoveAcceptToken.qbk b/doc/requirements/MoveAcceptToken.qbk new file mode 100644 index 0000000000..de9ef56340 --- /dev/null +++ b/doc/requirements/MoveAcceptToken.qbk @@ -0,0 +1,94 @@ +[/ + / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:MoveAcceptToken Move accept token requirements] + +A move accept token is a [link boost_asio.overview.model.completion_tokens completion +token] for completion signature `void(error_code, typename Protocol::socket)` +or completion signature `void(error_code, typename Protocol::socket::template +rebind_executor::other)`, for the type `Protocol` of the acceptor +class template. + +[heading Examples] + +A free function as a move accept token: + + void accept_handler( + const boost::system::error_code& ec, boost::asio::ip::tcp::socket s) + { + ... + } + +A move accept token function object: + + struct accept_handler + { + ... + void operator()( + const boost::system::error_code& ec, boost::asio::ip::tcp::socket s) + { + ... + } + ... + }; + +A lambda as a move accept token: + + acceptor.async_accept(..., + [](const boost::system::error_code& ec, boost::asio::ip::tcp::socket s) + { + ... + }); + +A non-static class member function adapted to a move accept token using +`std::bind()`: + + void my_class::accept_handler( + const boost::system::error_code& ec, boost::asio::ip::tcp::socket socket) + { + ... + } + ... + boost::asio::async_accept(..., + std::bind(&my_class::accept_handler, + this, std::placeholders::_1, + std::placeholders::_2)); + +Using [link boost_asio.reference.use_future use_future] as a move accept token: + + std::future f = + acceptor.async_accept(..., boost::asio::use_future); + ... + try + { + boost::asio::ip::tcp::socket s = f.get(); + ... + } + catch (const system_error& e) + { + ... + } + +Using [link boost_asio.reference.use_awaitable use_awaitable] as a move accept token: + + boost::asio::awaitable my_coroutine() + { + try + { + ... + boost::asio::ip::tcp::socket s = + co_await acceptor.async_accept( + ..., boost::asio::use_awaitable); + ... + } + catch (const system_error& e) + { + ... + } + } + +[endsect] diff --git a/doc/requirements/RangeConnectHandler.qbk b/doc/requirements/RangeConnectHandler.qbk index 64815e3da0..ce9dc169ed 100644 --- a/doc/requirements/RangeConnectHandler.qbk +++ b/doc/requirements/RangeConnectHandler.qbk @@ -11,72 +11,6 @@ A range connect handler must meet the requirements for a [link boost_asio.reference.Handler handler]. A value `h` of a range connect handler class should work correctly in the expression `h(ec, ep)`, where `ec` is an lvalue of type `const error_code` and `ep` is an lvalue of the type `Protocol::endpoint` -for the `Protocol` type in the corresponding `connect()` or async_connect()` -function. - -[heading Examples] - -A free function as a range connect handler: - - void connect_handler( - const boost::system::error_code& ec, - const boost::asio::ip::tcp::endpoint& endpoint) - { - ... - } - -A range connect handler function object: - - struct connect_handler - { - ... - template - void operator()( - const boost::system::error_code& ec, - const boost::asio::ip::tcp::endpoint& endpoint) - { - ... - } - ... - }; - -A lambda as a range connect handler: - - boost::asio::async_connect(..., - [](const boost::system::error_code& ec, - const boost::asio::ip::tcp::endpoint& endpoint) - { - ... - }); - -A non-static class member function adapted to a range connect handler using -`std::bind()`: - - void my_class::connect_handler( - const boost::system::error_code& ec, - const boost::asio::ip::tcp::endpoint& endpoint) - { - ... - } - ... - boost::asio::async_connect(..., - std::bind(&my_class::connect_handler, - this, std::placeholders::_1, - std::placeholders::_2)); - -A non-static class member function adapted to a range connect handler using -`boost::bind()`: - - void my_class::connect_handler( - const boost::system::error_code& ec, - const boost::asio::ip::tcp::endpoint& endpoint) - { - ... - } - ... - boost::asio::async_connect(..., - boost::bind(&my_class::connect_handler, - this, boost::asio::placeholders::error, - boost::asio::placeholders::endpoint)); +for the `Protocol` type in the corresponding `async_connect()` function. [endsect] diff --git a/doc/requirements/RangeConnectToken.qbk b/doc/requirements/RangeConnectToken.qbk new file mode 100644 index 0000000000..53fcb2ff94 --- /dev/null +++ b/doc/requirements/RangeConnectToken.qbk @@ -0,0 +1,114 @@ +[/ + / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:RangeConnectToken Range connect token requirements] + +A range connect token is a [link boost_asio.overview.model.completion_tokens +completion token] for completion signature `void(error_code, typename +Protocol::endpoint)`, where the type `Protocol` is used in the corresponding +`async_connect()` function. + +[heading Examples] + +A free function as a range connect token: + + void connect_handler( + const boost::system::error_code& ec, + const boost::asio::ip::tcp::endpoint& endpoint) + { + ... + } + +A range connect token function object: + + struct connect_handler + { + ... + template + void operator()( + const boost::system::error_code& ec, + const boost::asio::ip::tcp::endpoint& endpoint) + { + ... + } + ... + }; + +A lambda as a range connect token: + + boost::asio::async_connect(..., + [](const boost::system::error_code& ec, + const boost::asio::ip::tcp::endpoint& endpoint) + { + ... + }); + +A non-static class member function adapted to a range connect token using +`std::bind()`: + + void my_class::connect_handler( + const boost::system::error_code& ec, + const boost::asio::ip::tcp::endpoint& endpoint) + { + ... + } + ... + boost::asio::async_connect(..., + std::bind(&my_class::connect_handler, + this, std::placeholders::_1, + std::placeholders::_2)); + +A non-static class member function adapted to a range connect token using +`boost::bind()`: + + void my_class::connect_handler( + const boost::system::error_code& ec, + const boost::asio::ip::tcp::endpoint& endpoint) + { + ... + } + ... + boost::asio::async_connect(..., + boost::bind(&my_class::connect_handler, + this, boost::asio::placeholders::error, + boost::asio::placeholders::endpoint)); + +Using [link boost_asio.reference.use_future use_future] as a range connect token: + + std::future f = + boost::asio::async_connect(..., boost::asio::use_future); + ... + try + { + boost::asio::ip::tcp::endpoint e = f.get(); + ... + } + catch (const system_error& e) + { + ... + } + +Using [link boost_asio.reference.use_awaitable use_awaitable] as a range connect +token: + + boost::asio::awaitable my_coroutine() + { + try + { + ... + boost::asio::ip::tcp::endpoint e = + co_await boost::asio::async_connect( + ..., boost::asio::use_awaitable); + ... + } + catch (const system_error& e) + { + ... + } + } + +[endsect] diff --git a/doc/requirements/ReadHandler.qbk b/doc/requirements/ReadHandler.qbk index 3c278e5b0b..8023a987de 100644 --- a/doc/requirements/ReadHandler.qbk +++ b/doc/requirements/ReadHandler.qbk @@ -12,68 +12,4 @@ boost_asio.reference.Handler handler]. A value `h` of a read handler class should work correctly in the expression `h(ec, s)`, where `ec` is an lvalue of type `const error_code` and `s` is an lvalue of type `const size_t`. -[heading Examples] - -A free function as a read handler: - - void read_handler( - const boost::system::error_code& ec, - std::size_t bytes_transferred) - { - ... - } - -A read handler function object: - - struct read_handler - { - ... - void operator()( - const boost::system::error_code& ec, - std::size_t bytes_transferred) - { - ... - } - ... - }; - -A lambda as a read handler: - - socket.async_read(... - [](const boost::system::error_code& ec, - std::size_t bytes_transferred) - { - ... - }); - -A non-static class member function adapted to a read handler using -`std::bind()`: - - void my_class::read_handler( - const boost::system::error_code& ec, - std::size_t bytes_transferred) - { - ... - } - ... - socket.async_read(..., - std::bind(&my_class::read_handler, - this, std::placeholders::_1, - std::placeholders::_2)); - -A non-static class member function adapted to a read handler using -`boost::bind()`: - - void my_class::read_handler( - const boost::system::error_code& ec, - std::size_t bytes_transferred) - { - ... - } - ... - socket.async_read(..., - boost::bind(&my_class::read_handler, - this, boost::asio::placeholders::error, - boost::asio::placeholders::bytes_transferred)); - [endsect] diff --git a/doc/requirements/ReadToken.qbk b/doc/requirements/ReadToken.qbk new file mode 100644 index 0000000000..fc3ab74362 --- /dev/null +++ b/doc/requirements/ReadToken.qbk @@ -0,0 +1,110 @@ +[/ + / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:ReadToken Read token requirements] + +A read token is a [link boost_asio.overview.model.completion_tokens completion token] +for completion signature `void(error_code, size_t)`. + +[heading Examples] + +A free function as a read token: + + void read_handler( + const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + } + +A read token function object: + + struct read_handler + { + ... + void operator()( + const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + } + ... + }; + +A lambda as a read token: + + socket.async_read_some(..., + [](const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + }); + +A non-static class member function adapted to a read token using +`std::bind()`: + + void my_class::read_handler( + const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + } + ... + socket.async_read_some(..., + std::bind(&my_class::read_handler, + this, std::placeholders::_1, + std::placeholders::_2)); + +A non-static class member function adapted to a read token using +`boost::bind()`: + + void my_class::read_handler( + const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + } + ... + socket.async_read_some(..., + boost::bind(&my_class::read_handler, + this, boost::asio::placeholders::error, + boost::asio::placeholders::bytes_transferred)); + +Using [link boost_asio.reference.use_future use_future] as a read token: + + std::future f = + socket.async_read_some(..., boost::asio::use_future); + ... + try + { + std::size_t n = f.get(); + ... + } + catch (const system_error& e) + { + ... + } + +Using [link boost_asio.reference.use_awaitable use_awaitable] as a read token: + + boost::asio::awaitable my_coroutine() + { + try + { + ... + std::size_t n = + co_await socket.async_read_some( + ..., boost::asio::use_awaitable); + ... + } + catch (const system_error& e) + { + ... + } + } + +[endsect] diff --git a/doc/requirements/ResolveHandler.qbk b/doc/requirements/ResolveHandler.qbk index 8ff661b833..425426c5af 100644 --- a/doc/requirements/ResolveHandler.qbk +++ b/doc/requirements/ResolveHandler.qbk @@ -15,68 +15,4 @@ expression `h(ec, r)`, where `ec` is an lvalue of type `const error_code` and boost_asio.reference.ip__basic_resolver `ip::basic_resolver<>`] which is used to initiate the asynchronous operation. -[heading Examples] - -A free function as a resolve handler: - - void resolve_handler( - const boost::system::error_code& ec, - boost::asio::ip::tcp::resolver::results_type results) - { - ... - } - -A resolve handler function object: - - struct resolve_handler - { - ... - void operator()( - const boost::system::error_code& ec, - boost::asio::ip::tcp::resolver::results_type results) - { - ... - } - ... - }; - -A lambda as a resolve handler: - - resolver.async_resolve(..., - [](const boost::system::error_code& ec, - boost::asio::ip::tcp::resolver::results_type results) - { - ... - }); - -A non-static class member function adapted to a resolve handler using -`std::bind()`: - - void my_class::resolve_handler( - const boost::system::error_code& ec, - boost::asio::ip::tcp::resolver::results_type results) - { - ... - } - ... - resolver.async_resolve(..., - std::bind(&my_class::resolve_handler, - this, std::placeholders::_1, - std::placeholders::_2)); - -A non-static class member function adapted to a resolve handler using -`boost::bind()`: - - void my_class::resolve_handler( - const boost::system::error_code& ec, - boost::asio::ip::tcp::resolver::results_type results) - { - ... - } - ... - resolver.async_resolve(..., - boost::bind(&my_class::resolve_handler, - this, boost::asio::placeholders::error, - boost::asio::placeholders::results)); - [endsect] diff --git a/doc/requirements/ResolveToken.qbk b/doc/requirements/ResolveToken.qbk new file mode 100644 index 0000000000..e10d92941d --- /dev/null +++ b/doc/requirements/ResolveToken.qbk @@ -0,0 +1,112 @@ +[/ + / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:ResolveToken Resolve token requirements] + +A resolve token is a [link boost_asio.overview.model.completion_tokens completion +token] for completion signature `void(error_code, +ip::basic_resolver_results)`, for a specified +`InternetProtocol`. + +[heading Examples] + +A free function as a resolve token: + + void resolve_handler( + const boost::system::error_code& ec, + boost::asio::ip::tcp::resolver::results_type results) + { + ... + } + +A resolve token function object: + + struct resolve_handler + { + ... + void operator()( + const boost::system::error_code& ec, + boost::asio::ip::tcp::resolver::results_type results) + { + ... + } + ... + }; + +A lambda as a resolve token: + + resolver.async_resolve(..., + [](const boost::system::error_code& ec, + boost::asio::ip::tcp::resolver::results_type results) + { + ... + }); + +A non-static class member function adapted to a resolve token using +`std::bind()`: + + void my_class::resolve_handler( + const boost::system::error_code& ec, + boost::asio::ip::tcp::resolver::results_type results) + { + ... + } + ... + resolver.async_resolve(..., + std::bind(&my_class::resolve_handler, + this, std::placeholders::_1, + std::placeholders::_2)); + +A non-static class member function adapted to a resolve token using +`boost::bind()`: + + void my_class::resolve_handler( + const boost::system::error_code& ec, + boost::asio::ip::tcp::resolver::results_type results) + { + ... + } + ... + resolver.async_resolve(..., + boost::bind(&my_class::resolve_handler, + this, boost::asio::placeholders::error, + boost::asio::placeholders::results)); + +Using [link boost_asio.reference.use_future use_future] as a resolve token: + + std::future f = + resolver.async_resolve(..., boost::asio::use_future); + ... + try + { + boost::asio::ip::tcp::resolver::results_type r = f.get(); + ... + } + catch (const system_error& e) + { + ... + } + +Using [link boost_asio.reference.use_awaitable use_awaitable] as a resolve token: + + boost::asio::awaitable my_coroutine() + { + try + { + ... + boost::asio::ip::tcp::resolver::results_type r = + co_await resolver.async_resolve( + ..., boost::asio::use_awaitable); + ... + } + catch (const system_error& e) + { + ... + } + } + +[endsect] diff --git a/doc/requirements/ShutdownHandler.qbk b/doc/requirements/ShutdownHandler.qbk index cf5c828727..bc1db2ab32 100644 --- a/doc/requirements/ShutdownHandler.qbk +++ b/doc/requirements/ShutdownHandler.qbk @@ -12,61 +12,4 @@ boost_asio.reference.Handler handler]. A value `h` of a shutdown handler class should work correctly in the expression `h(ec)`, where `ec` is an lvalue of type `const error_code`. -[heading Examples] - -A free function as a shutdown handler: - - void shutdown_handler( - const boost::system::error_code& ec) - { - ... - } - -A shutdown handler function object: - - struct shutdown_handler - { - ... - void operator()( - const boost::system::error_code& ec) - { - ... - } - ... - }; - -A lambda as a shutdown handler: - - ssl_stream.async_shutdown(..., - [](const boost::system::error_code& ec) - { - ... - }); - -A non-static class member function adapted to a shutdown handler using -`std::bind()`: - - void my_class::shutdown_handler( - const boost::system::error_code& ec) - { - ... - } - ... - ssl_stream.async_shutdown( - std::bind(&my_class::shutdown_handler, - this, std::placeholders::_1)); - -A non-static class member function adapted to a shutdown handler using -`boost::bind()`: - - void my_class::shutdown_handler( - const boost::system::error_code& ec) - { - ... - } - ... - ssl_stream.async_shutdown( - boost::bind(&my_class::shutdown_handler, - this, boost::asio::placeholders::error)); - [endsect] diff --git a/doc/requirements/ShutdownToken.qbk b/doc/requirements/ShutdownToken.qbk new file mode 100644 index 0000000000..334bd79a1d --- /dev/null +++ b/doc/requirements/ShutdownToken.qbk @@ -0,0 +1,99 @@ +[/ + / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:ShutdownToken SSL shutdown token requirements] + +A shutdown token is a [link boost_asio.overview.model.completion_tokens completion +token] for completion signature `void(error_code)`. + +[heading Examples] + +A free function as a shutdown token: + + void shutdown_handler( + const boost::system::error_code& ec) + { + ... + } + +A shutdown token function object: + + struct shutdown_handler + { + ... + void operator()( + const boost::system::error_code& ec) + { + ... + } + ... + }; + +A lambda as a shutdown token: + + ssl_stream.async_shutdown(..., + [](const boost::system::error_code& ec) + { + ... + }); + +A non-static class member function adapted to a shutdown token using +`std::bind()`: + + void my_class::shutdown_handler( + const boost::system::error_code& ec) + { + ... + } + ... + ssl_stream.async_shutdown(..., + std::bind(&my_class::shutdown_handler, + this, std::placeholders::_1)); + +A non-static class member function adapted to a shutdown token using +`boost::bind()`: + + void my_class::shutdown_handler( + const boost::system::error_code& ec) + { + ... + } + ... + ssl_stream.async_shutdown(..., + boost::bind(&my_class::shutdown_handler, + this, boost::asio::placeholders::error)); + +Using [link boost_asio.reference.use_future use_future] as a shutdown token: + + std::future f = ssl_stream.async_shutdown(..., boost::asio::use_future); + ... + try + { + f.get(); + } + catch (const system_error& e) + { + ... + } + +Using [link boost_asio.reference.use_awaitable use_awaitable] as a shutdown token: + + boost::asio::awaitable my_coroutine() + { + try + { + ... + co_await ssl_stream.async_shutdown(..., boost::asio::use_awaitable); + ... + } + catch (const system_error& e) + { + ... + } + } + +[endsect] diff --git a/doc/requirements/SignalHandler.qbk b/doc/requirements/SignalHandler.qbk index 11fe2570b7..93c1964b18 100644 --- a/doc/requirements/SignalHandler.qbk +++ b/doc/requirements/SignalHandler.qbk @@ -12,68 +12,4 @@ boost_asio.reference.Handler handler]. A value `h` of a signal handler class should work correctly in the expression `h(ec, n)`, where `ec` is an lvalue of type `const error_code` and `n` is an lvalue of type `const int`. -[heading Examples] - -A free function as a signal handler: - - void signal_handler( - const boost::system::error_code& ec, - int signal_number) - { - ... - } - -A signal handler function object: - - struct signal_handler - { - ... - void operator()( - const boost::system::error_code& ec, - int signal_number) - { - ... - } - ... - }; - -A lambda as a signal handler: - - my_signal_set.async_wait( - [](const boost::system::error_code& ec, - int signal_number) - { - ... - }); - -A non-static class member function adapted to a signal handler using -`std::bind()`: - - void my_class::signal_handler( - const boost::system::error_code& ec, - int signal_number) - { - ... - } - ... - my_signal_set.async_wait( - std::bind(&my_class::signal_handler, - this, std::placeholders::_1, - std::placeholders::_2)); - -A non-static class member function adapted to a signal handler using -`boost::bind()`: - - void my_class::signal_handler( - const boost::system::error_code& ec, - int signal_number) - { - ... - } - ... - my_signal_set.async_wait( - boost::bind(&my_class::signal_handler, - this, boost::asio::placeholders::error, - boost::asio::placeholders::signal_number)); - [endsect] diff --git a/doc/requirements/SignalToken.qbk b/doc/requirements/SignalToken.qbk new file mode 100644 index 0000000000..52950cb36e --- /dev/null +++ b/doc/requirements/SignalToken.qbk @@ -0,0 +1,109 @@ +[/ + / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:SignalToken Signal token requirements] + +A signal token is a [link boost_asio.overview.model.completion_tokens completion +token] for completion signature `void(error_code, int)`. + +[heading Examples] + +A free function as a signal token: + + void signal_handler( + const boost::system::error_code& ec, + int signal_number) + { + ... + } + +A signal token function object: + + struct signal_handler + { + ... + void operator()( + const boost::system::error_code& ec, + int signal_number) + { + ... + } + ... + }; + +A lambda as a signal token: + + signal_set.async_wait(..., + [](const boost::system::error_code& ec, + int signal_number) + { + ... + }); + +A non-static class member function adapted to a signal token using +`std::bind()`: + + void my_class::signal_handler( + const boost::system::error_code& ec, + int signal_number) + { + ... + } + ... + signal_set.async_wait(..., + std::bind(&my_class::signal_handler, + this, std::placeholders::_1, + std::placeholders::_2)); + +A non-static class member function adapted to a signal token using +`boost::bind()`: + + void my_class::signal_handler( + const boost::system::error_code& ec, + int signal_number) + { + ... + } + ... + signal_set.async_wait(..., + boost::bind(&my_class::signal_handler, + this, boost::asio::placeholders::error, + boost::asio::placeholders::signal_number)); + +Using [link boost_asio.reference.use_future use_future] as a signal token: + + std::future f = signal_set.async_wait(..., boost::asio::use_future); + ... + try + { + int signo = f.get(); + ... + } + catch (const system_error& e) + { + ... + } + +Using [link boost_asio.reference.use_awaitable use_awaitable] as a signal token: + + boost::asio::awaitable my_coroutine() + { + try + { + ... + int signo = + co_await signal_set.async_wait( + ..., boost::asio::use_awaitable); + ... + } + catch (const system_error& e) + { + ... + } + } + +[endsect] diff --git a/doc/requirements/WaitHandler.qbk b/doc/requirements/WaitHandler.qbk index b7d3a3894d..8a76294f22 100644 --- a/doc/requirements/WaitHandler.qbk +++ b/doc/requirements/WaitHandler.qbk @@ -12,61 +12,4 @@ boost_asio.reference.Handler handler]. A value `h` of a wait handler class should work correctly in the expression `h(ec)`, where `ec` is an lvalue of type `const error_code`. -[heading Examples] - -A free function as a wait handler: - - void wait_handler( - const boost::system::error_code& ec) - { - ... - } - -A wait handler function object: - - struct wait_handler - { - ... - void operator()( - const boost::system::error_code& ec) - { - ... - } - ... - }; - -A lambda as a wait handler: - - socket.async_wait(..., - [](const boost::system::error_code& ec) - { - ... - }); - -A non-static class member function adapted to a wait handler using -`std::bind()`: - - void my_class::wait_handler( - const boost::system::error_code& ec) - { - ... - } - ... - socket.async_wait(..., - std::bind(&my_class::wait_handler, - this, std::placeholders::_1)); - -A non-static class member function adapted to a wait handler using -`boost::bind()`: - - void my_class::wait_handler( - const boost::system::error_code& ec) - { - ... - } - ... - socket.async_wait(..., - boost::bind(&my_class::wait_handler, - this, boost::asio::placeholders::error)); - [endsect] diff --git a/doc/requirements/WaitToken.qbk b/doc/requirements/WaitToken.qbk new file mode 100644 index 0000000000..44bb50a643 --- /dev/null +++ b/doc/requirements/WaitToken.qbk @@ -0,0 +1,99 @@ +[/ + / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:WaitToken Wait token requirements] + +A wait token is a [link boost_asio.overview.model.completion_tokens completion token] +for completion signature `void(error_code)`. + +[heading Examples] + +A free function as a wait token: + + void wait_handler( + const boost::system::error_code& ec) + { + ... + } + +A wait token function object: + + struct wait_handler + { + ... + void operator()( + const boost::system::error_code& ec) + { + ... + } + ... + }; + +A lambda as a wait token: + + socket.async_wait(..., + [](const boost::system::error_code& ec) + { + ... + }); + +A non-static class member function adapted to a wait token using +`std::bind()`: + + void my_class::wait_handler( + const boost::system::error_code& ec) + { + ... + } + ... + socket.async_wait(..., + std::bind(&my_class::wait_handler, + this, std::placeholders::_1)); + +A non-static class member function adapted to a wait token using +`boost::bind()`: + + void my_class::wait_handler( + const boost::system::error_code& ec) + { + ... + } + ... + socket.async_wait(..., + boost::bind(&my_class::wait_handler, + this, boost::asio::placeholders::error)); + +Using [link boost_asio.reference.use_future use_future] as a wait token: + + std::future f = socket.async_wait(..., boost::asio::use_future); + ... + try + { + f.get(); + } + catch (const system_error& e) + { + ... + } + +Using [link boost_asio.reference.use_awaitable use_awaitable] as a wait token: + + boost::asio::awaitable my_coroutine() + { + try + { + ... + co_await socket.async_wait(..., boost::asio::use_awaitable); + ... + } + catch (const system_error& e) + { + ... + } + } + +[endsect] diff --git a/doc/requirements/WriteHandler.qbk b/doc/requirements/WriteHandler.qbk index d820530fb0..e2adb3c1f9 100644 --- a/doc/requirements/WriteHandler.qbk +++ b/doc/requirements/WriteHandler.qbk @@ -12,68 +12,4 @@ boost_asio.reference.Handler handler]. A value `h` of a write handler class should work correctly in the expression `h(ec, s)`, where `ec` is an lvalue of type `const error_code` and `s` is an lvalue of type `const size_t`. -[heading Examples] - -A free function as a write handler: - - void write_handler( - const boost::system::error_code& ec, - std::size_t bytes_transferred) - { - ... - } - -A write handler function object: - - struct write_handler - { - ... - void operator()( - const boost::system::error_code& ec, - std::size_t bytes_transferred) - { - ... - } - ... - }; - -A lambda as a write handler: - - socket.async_write(... - [](const boost::system::error_code& ec, - std::size_t bytes_transferred) - { - ... - }); - -A non-static class member function adapted to a write handler using -`std::bind()`: - - void my_class::write_handler( - const boost::system::error_code& ec, - std::size_t bytes_transferred) - { - ... - } - ... - socket.async_write(..., - std::bind(&my_class::write_handler, - this, std::placeholders::_1, - std::placeholders::_2)); - -A non-static class member function adapted to a write handler using -`boost::bind()`: - - void my_class::write_handler( - const boost::system::error_code& ec, - std::size_t bytes_transferred) - { - ... - } - ... - socket.async_write(..., - boost::bind(&my_class::write_handler, - this, boost::asio::placeholders::error, - boost::asio::placeholders::bytes_transferred)); - [endsect] diff --git a/doc/requirements/WriteToken.qbk b/doc/requirements/WriteToken.qbk new file mode 100644 index 0000000000..eb27a62803 --- /dev/null +++ b/doc/requirements/WriteToken.qbk @@ -0,0 +1,110 @@ +[/ + / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:WriteToken Write token requirements] + +A write token is a [link boost_asio.overview.model.completion_tokens completion token] +for completion signature `void(error_code, size_t)`. + +[heading Examples] + +A free function as a write token: + + void write_handler( + const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + } + +A write token function object: + + struct write_handler + { + ... + void operator()( + const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + } + ... + }; + +A lambda as a write token: + + socket.async_write_some(..., + [](const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + }); + +A non-static class member function adapted to a write token using +`std::bind()`: + + void my_class::write_handler( + const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + } + ... + socket.async_write_some(..., + std::bind(&my_class::write_handler, + this, std::placeholders::_1, + std::placeholders::_2)); + +A non-static class member function adapted to a write token using +`boost::bind()`: + + void my_class::write_handler( + const boost::system::error_code& ec, + std::size_t bytes_transferred) + { + ... + } + ... + socket.async_write_some(..., + boost::bind(&my_class::write_handler, + this, boost::asio::placeholders::error, + boost::asio::placeholders::bytes_transferred)); + +Using [link boost_asio.reference.use_future use_future] as a write token: + + std::future f = + socket.async_write_some(..., boost::asio::use_future); + ... + try + { + std::size_t n = f.get(); + ... + } + catch (const system_error& e) + { + ... + } + +Using [link boost_asio.reference.use_awaitable use_awaitable] as a write token: + + boost::asio::awaitable my_coroutine() + { + try + { + ... + std::size_t n = + co_await socket.async_write_some( + ..., boost::asio::use_awaitable); + ... + } + catch (const system_error& e) + { + ... + } + } + +[endsect] diff --git a/include/boost/asio/basic_datagram_socket.hpp b/include/boost/asio/basic_datagram_socket.hpp index 6d05648da8..bd4b952a3d 100644 --- a/include/boost/asio/basic_datagram_socket.hpp +++ b/include/boost/asio/basic_datagram_socket.hpp @@ -424,23 +424,26 @@ class basic_datagram_socket /// Start an asynchronous send on a connected socket. /** * This function is used to asynchronously send data on the datagram socket. - * The function call always returns immediately. + * It is an initiating function for an @ref asynchronous_operation, and always + * returns immediately. * * @param buffers One or more data buffers to be sent on the socket. Although * the buffers object may be copied as necessary, ownership of the underlying * memory blocks is retained by the caller, which must guarantee that they - * remain valid until the handler is called. + * remain valid until the completion handler is called. * - * @param handler The handler to be called when the send operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the send completes. Potential + * completion tokens include @ref use_future, @ref use_awaitable, @ref + * yield_context, or a function object with the correct completion signature. + * The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes sent. + * std::size_t bytes_transferred // Number of bytes sent. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -471,42 +474,45 @@ class basic_datagram_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_send(const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_send(this), handler, + initiate_async_send(this), token, buffers, socket_base::message_flags(0)); } /// Start an asynchronous send on a connected socket. /** * This function is used to asynchronously send data on the datagram socket. - * The function call always returns immediately. + * It is an initiating function for an @ref asynchronous_operation, and always + * returns immediately. * * @param buffers One or more data buffers to be sent on the socket. Although * the buffers object may be copied as necessary, ownership of the underlying * memory blocks is retained by the caller, which must guarantee that they - * remain valid until the handler is called. + * remain valid until the completion handler is called. * * @param flags Flags specifying how the send call is to be made. * - * @param handler The handler to be called when the send operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the send completes. Potential + * completion tokens include @ref use_future, @ref use_awaitable, @ref + * yield_context, or a function object with the correct completion signature. + * The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes sent. + * std::size_t bytes_transferred // Number of bytes sent. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -528,18 +534,18 @@ class basic_datagram_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_send(const ConstBufferSequence& buffers, socket_base::message_flags flags, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_send(this), handler, buffers, flags); + initiate_async_send(this), token, buffers, flags); } /// Send a datagram to the specified endpoint. @@ -633,26 +639,29 @@ class basic_datagram_socket /// Start an asynchronous send. /** * This function is used to asynchronously send a datagram to the specified - * remote endpoint. The function call always returns immediately. + * remote endpoint. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param buffers One or more data buffers to be sent to the remote endpoint. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param destination The remote endpoint to which the data will be sent. * Copies will be made of the endpoint as required. * - * @param handler The handler to be called when the send operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the send completes. Potential + * completion tokens include @ref use_future, @ref use_awaitable, @ref + * yield_context, or a function object with the correct completion signature. + * The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes sent. + * std::size_t bytes_transferred // Number of bytes sent. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -682,46 +691,49 @@ class basic_datagram_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_send_to(const ConstBufferSequence& buffers, const endpoint_type& destination, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_send_to(this), handler, buffers, + initiate_async_send_to(this), token, buffers, destination, socket_base::message_flags(0)); } /// Start an asynchronous send. /** * This function is used to asynchronously send a datagram to the specified - * remote endpoint. The function call always returns immediately. + * remote endpoint. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param buffers One or more data buffers to be sent to the remote endpoint. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param flags Flags specifying how the send call is to be made. * * @param destination The remote endpoint to which the data will be sent. * Copies will be made of the endpoint as required. * - * @param handler The handler to be called when the send operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the send completes. Potential + * completion tokens include @ref use_future, @ref use_awaitable, @ref + * yield_context, or a function object with the correct completion signature. + * The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes sent. + * std::size_t bytes_transferred // Number of bytes sent. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -739,18 +751,18 @@ class basic_datagram_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_send_to(const ConstBufferSequence& buffers, const endpoint_type& destination, socket_base::message_flags flags, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_send_to(this), handler, buffers, destination, flags); + initiate_async_send_to(this), token, buffers, destination, flags); } /// Receive some data on a connected socket. @@ -845,23 +857,26 @@ class basic_datagram_socket /// Start an asynchronous receive on a connected socket. /** * This function is used to asynchronously receive data from the datagram - * socket. The function call always returns immediately. + * socket. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param buffers One or more buffers into which the data will be received. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * - * @param handler The handler to be called when the receive operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the receive completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes received. + * std::size_t bytes_transferred // Number of bytes received. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -893,42 +908,45 @@ class basic_datagram_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_receive(const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_receive(this), handler, + initiate_async_receive(this), token, buffers, socket_base::message_flags(0)); } /// Start an asynchronous receive on a connected socket. /** * This function is used to asynchronously receive data from the datagram - * socket. The function call always returns immediately. + * socket. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param buffers One or more buffers into which the data will be received. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param flags Flags specifying how the receive call is to be made. * - * @param handler The handler to be called when the receive operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the receive completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes received. + * std::size_t bytes_transferred // Number of bytes received. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -950,18 +968,18 @@ class basic_datagram_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_receive(const MutableBufferSequence& buffers, socket_base::message_flags flags, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_receive(this), handler, buffers, flags); + initiate_async_receive(this), token, buffers, flags); } /// Receive a datagram with the endpoint of the sender. @@ -1055,29 +1073,32 @@ class basic_datagram_socket /// Start an asynchronous receive. /** - * This function is used to asynchronously receive a datagram. The function - * call always returns immediately. + * This function is used to asynchronously receive a datagram. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * @param buffers One or more buffers into which the data will be received. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param sender_endpoint An endpoint object that receives the endpoint of * the remote sender of the datagram. Ownership of the sender_endpoint object * is retained by the caller, which must guarantee that it is valid until the - * handler is called. + * completion handler is called. * - * @param handler The handler to be called when the receive operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the receive completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes received. + * std::size_t bytes_transferred // Number of bytes received. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1104,48 +1125,51 @@ class basic_datagram_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_receive_from(const MutableBufferSequence& buffers, endpoint_type& sender_endpoint, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_receive_from(this), handler, buffers, + initiate_async_receive_from(this), token, buffers, &sender_endpoint, socket_base::message_flags(0)); } /// Start an asynchronous receive. /** - * This function is used to asynchronously receive a datagram. The function - * call always returns immediately. + * This function is used to asynchronously receive a datagram. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * @param buffers One or more buffers into which the data will be received. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param sender_endpoint An endpoint object that receives the endpoint of * the remote sender of the datagram. Ownership of the sender_endpoint object * is retained by the caller, which must guarantee that it is valid until the - * handler is called. + * completion handler is called. * * @param flags Flags specifying how the receive call is to be made. * - * @param handler The handler to be called when the receive operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the receive completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes received. + * std::size_t bytes_transferred // Number of bytes received. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1163,18 +1187,18 @@ class basic_datagram_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_receive_from(const MutableBufferSequence& buffers, endpoint_type& sender_endpoint, socket_base::message_flags flags, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_receive_from(this), handler, + initiate_async_receive_from(this), token, buffers, &sender_endpoint, flags); } diff --git a/include/boost/asio/basic_deadline_timer.hpp b/include/boost/asio/basic_deadline_timer.hpp index d1c77bb976..1676dba751 100644 --- a/include/boost/asio/basic_deadline_timer.hpp +++ b/include/boost/asio/basic_deadline_timer.hpp @@ -608,33 +608,36 @@ class basic_deadline_timer /// Start an asynchronous wait on the timer. /** * This function may be used to initiate an asynchronous wait against the - * timer. It always returns immediately. + * timer. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * - * For each call to async_wait(), the supplied handler will be called exactly - * once. The handler will be called when: + * For each call to async_wait(), the completion handler will be called + * exactly once. The completion handler will be called when: * * @li The timer has expired. * * @li The timer was cancelled, in which case the handler is passed the error * code boost::asio::error::operation_aborted. * - * @param handler The handler to be called when the timer expires. Copies - * will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the timer expires. Potential + * completion tokens include @ref use_future, @ref use_awaitable, @ref + * yield_context, or a function object with the correct completion signature. + * The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature * @code void(boost::system::error_code) @endcode * * @par Per-Operation Cancellation - * On POSIX or Windows operating systems, this asynchronous operation supports - * cancellation for the following boost::asio::cancellation_type values: + * This asynchronous operation supports cancellation for the following + * boost::asio::cancellation_type values: * * @li @c cancellation_type::terminal * @@ -644,15 +647,15 @@ class basic_deadline_timer */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code)) - WaitHandler BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WaitHandler, + WaitToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WaitToken, void (boost::system::error_code)) async_wait( - BOOST_ASIO_MOVE_ARG(WaitHandler) handler + BOOST_ASIO_MOVE_ARG(WaitToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_wait(this), handler); + return async_initiate( + initiate_async_wait(this), token); } private: diff --git a/include/boost/asio/basic_random_access_file.hpp b/include/boost/asio/basic_random_access_file.hpp index 28ee41ebda..248eb0aea1 100644 --- a/include/boost/asio/basic_random_access_file.hpp +++ b/include/boost/asio/basic_random_access_file.hpp @@ -404,25 +404,28 @@ class basic_random_access_file /// Start an asynchronous write at the specified offset. /** * This function is used to asynchronously write data to the random-access - * handle. The function call always returns immediately. + * handle. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param offset The offset at which the data will be written. * * @param buffers One or more data buffers to be written to the handle. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes written. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -453,18 +456,18 @@ class basic_random_access_file */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_some_at(uint64_t offset, const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_write_some_at(this), handler, offset, buffers); + initiate_async_write_some_at(this), token, offset, buffers); } /// Read some data from the handle at the specified offset. @@ -537,25 +540,28 @@ class basic_random_access_file /// Start an asynchronous read at the specified offset. /** * This function is used to asynchronously read data from the random-access - * handle. The function call always returns immediately. + * handle. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param offset The offset at which the data will be read. * * @param buffers One or more buffers into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes read. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -587,18 +593,18 @@ class basic_random_access_file */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_some_at(uint64_t offset, const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_read_some_at(this), handler, offset, buffers); + initiate_async_read_some_at(this), token, offset, buffers); } private: diff --git a/include/boost/asio/basic_raw_socket.hpp b/include/boost/asio/basic_raw_socket.hpp index c93825ef88..e1f3a513c6 100644 --- a/include/boost/asio/basic_raw_socket.hpp +++ b/include/boost/asio/basic_raw_socket.hpp @@ -415,24 +415,27 @@ class basic_raw_socket /// Start an asynchronous send on a connected socket. /** - * This function is used to send data on the raw socket. The function call - * will block until the data has been sent successfully or an error occurs. + * This function is used to asynchronously send data on the raw socket. It is + * an initiating function for an @ref asynchronous_operation, and always + * returns immediately. * * @param buffers One or more data buffers to be sent on the socket. Although * the buffers object may be copied as necessary, ownership of the underlying * memory blocks is retained by the caller, which must guarantee that they - * remain valid until the handler is called. + * remain valid until the completion handler is called. * - * @param handler The handler to be called when the send operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the send completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes sent. + * std::size_t bytes_transferred // Number of bytes sent. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -463,42 +466,45 @@ class basic_raw_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_send(const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_send(this), handler, + initiate_async_send(this), token, buffers, socket_base::message_flags(0)); } /// Start an asynchronous send on a connected socket. /** - * This function is used to send data on the raw socket. The function call - * will block until the data has been sent successfully or an error occurs. + * This function is used to asynchronously send data on the raw socket. It is + * an initiating function for an @ref asynchronous_operation, and always + * returns immediately. * * @param buffers One or more data buffers to be sent on the socket. Although * the buffers object may be copied as necessary, ownership of the underlying * memory blocks is retained by the caller, which must guarantee that they - * remain valid until the handler is called. + * remain valid until the completion handler is called. * * @param flags Flags specifying how the send call is to be made. * - * @param handler The handler to be called when the send operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the send completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes sent. + * std::size_t bytes_transferred // Number of bytes sent. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -520,18 +526,18 @@ class basic_raw_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_send(const ConstBufferSequence& buffers, socket_base::message_flags flags, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_send(this), handler, buffers, flags); + initiate_async_send(this), token, buffers, flags); } /// Send raw data to the specified endpoint. @@ -625,26 +631,29 @@ class basic_raw_socket /// Start an asynchronous send. /** * This function is used to asynchronously send raw data to the specified - * remote endpoint. The function call always returns immediately. + * remote endpoint. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param buffers One or more data buffers to be sent to the remote endpoint. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param destination The remote endpoint to which the data will be sent. * Copies will be made of the endpoint as required. * - * @param handler The handler to be called when the send operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the send completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes sent. + * std::size_t bytes_transferred // Number of bytes sent. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -674,46 +683,49 @@ class basic_raw_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_send_to(const ConstBufferSequence& buffers, const endpoint_type& destination, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_send_to(this), handler, buffers, + initiate_async_send_to(this), token, buffers, destination, socket_base::message_flags(0)); } /// Start an asynchronous send. /** * This function is used to asynchronously send raw data to the specified - * remote endpoint. The function call always returns immediately. + * remote endpoint. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param buffers One or more data buffers to be sent to the remote endpoint. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param flags Flags specifying how the send call is to be made. * * @param destination The remote endpoint to which the data will be sent. * Copies will be made of the endpoint as required. * - * @param handler The handler to be called when the send operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the send completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes sent. + * std::size_t bytes_transferred // Number of bytes sent. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -731,18 +743,18 @@ class basic_raw_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_send_to(const ConstBufferSequence& buffers, const endpoint_type& destination, socket_base::message_flags flags, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_send_to(this), handler, buffers, destination, flags); + initiate_async_send_to(this), token, buffers, destination, flags); } /// Receive some data on a connected socket. @@ -837,23 +849,26 @@ class basic_raw_socket /// Start an asynchronous receive on a connected socket. /** * This function is used to asynchronously receive data from the raw - * socket. The function call always returns immediately. + * socket. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param buffers One or more buffers into which the data will be received. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * - * @param handler The handler to be called when the receive operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the receive completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes received. + * std::size_t bytes_transferred // Number of bytes received. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -885,42 +900,45 @@ class basic_raw_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_receive(const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_receive(this), handler, + initiate_async_receive(this), token, buffers, socket_base::message_flags(0)); } /// Start an asynchronous receive on a connected socket. /** * This function is used to asynchronously receive data from the raw - * socket. The function call always returns immediately. + * socket. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param buffers One or more buffers into which the data will be received. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param flags Flags specifying how the receive call is to be made. * - * @param handler The handler to be called when the receive operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the receive completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes received. + * std::size_t bytes_transferred // Number of bytes received. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -942,18 +960,18 @@ class basic_raw_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_receive(const MutableBufferSequence& buffers, socket_base::message_flags flags, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_receive(this), handler, buffers, flags); + initiate_async_receive(this), token, buffers, flags); } /// Receive raw data with the endpoint of the sender. @@ -1047,29 +1065,32 @@ class basic_raw_socket /// Start an asynchronous receive. /** - * This function is used to asynchronously receive raw data. The function - * call always returns immediately. + * This function is used to asynchronously receive raw data. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * @param buffers One or more buffers into which the data will be received. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param sender_endpoint An endpoint object that receives the endpoint of * the remote sender of the data. Ownership of the sender_endpoint object * is retained by the caller, which must guarantee that it is valid until the - * handler is called. + * completion handler is called. * - * @param handler The handler to be called when the receive operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the receive completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes received. + * std::size_t bytes_transferred // Number of bytes received. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1096,48 +1117,51 @@ class basic_raw_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_receive_from(const MutableBufferSequence& buffers, endpoint_type& sender_endpoint, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_receive_from(this), handler, buffers, + initiate_async_receive_from(this), token, buffers, &sender_endpoint, socket_base::message_flags(0)); } /// Start an asynchronous receive. /** - * This function is used to asynchronously receive raw data. The function - * call always returns immediately. + * This function is used to asynchronously receive raw data. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * @param buffers One or more buffers into which the data will be received. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param sender_endpoint An endpoint object that receives the endpoint of * the remote sender of the data. Ownership of the sender_endpoint object * is retained by the caller, which must guarantee that it is valid until the - * handler is called. + * completion handler is called. * * @param flags Flags specifying how the receive call is to be made. * - * @param handler The handler to be called when the receive operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the receive completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes received. + * std::size_t bytes_transferred // Number of bytes received. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1155,18 +1179,18 @@ class basic_raw_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_receive_from(const MutableBufferSequence& buffers, endpoint_type& sender_endpoint, socket_base::message_flags flags, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_receive_from(this), handler, + initiate_async_receive_from(this), token, buffers, &sender_endpoint, flags); } diff --git a/include/boost/asio/basic_readable_pipe.hpp b/include/boost/asio/basic_readable_pipe.hpp index ebb8eb7800..e69a053d11 100644 --- a/include/boost/asio/basic_readable_pipe.hpp +++ b/include/boost/asio/basic_readable_pipe.hpp @@ -417,24 +417,27 @@ class basic_readable_pipe /// Start an asynchronous read. /** - * This function is used to asynchronously read data from the pipe. The - * function call always returns immediately. + * This function is used to asynchronously read data from the pipe. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * @param buffers One or more buffers into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes read. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -457,17 +460,17 @@ class basic_readable_pipe */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_some(const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_read_some(this), handler, buffers); + initiate_async_read_some(this), token, buffers); } private: diff --git a/include/boost/asio/basic_seq_packet_socket.hpp b/include/boost/asio/basic_seq_packet_socket.hpp index dc1ebe289c..9d139be3a8 100644 --- a/include/boost/asio/basic_seq_packet_socket.hpp +++ b/include/boost/asio/basic_seq_packet_socket.hpp @@ -406,25 +406,28 @@ class basic_seq_packet_socket /// Start an asynchronous send. /** * This function is used to asynchronously send data on the sequenced packet - * socket. The function call always returns immediately. + * socket. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param buffers One or more data buffers to be sent on the socket. Although * the buffers object may be copied as necessary, ownership of the underlying * memory blocks is retained by the caller, which must guarantee that they - * remain valid until the handler is called. + * remain valid until the completion handler is called. * * @param flags Flags specifying how the send call is to be made. * - * @param handler The handler to be called when the send operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the send completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes sent. + * std::size_t bytes_transferred // Number of bytes sent. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -451,18 +454,18 @@ class basic_seq_packet_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_send(const ConstBufferSequence& buffers, socket_base::message_flags flags, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_send(this), handler, buffers, flags); + initiate_async_send(this), token, buffers, flags); } /// Receive some data on the socket. @@ -587,29 +590,32 @@ class basic_seq_packet_socket /// Start an asynchronous receive. /** * This function is used to asynchronously receive data from the sequenced - * packet socket. The function call always returns immediately. + * packet socket. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param buffers One or more buffers into which the data will be received. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param out_flags Once the asynchronous operation completes, contains flags * associated with the received data. For example, if the * socket_base::message_end_of_record bit is set then the received data marks * the end of a record. The caller must guarantee that the referenced - * variable remains valid until the handler is called. + * variable remains valid until the completion handler is called. * - * @param handler The handler to be called when the receive operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the receive completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes received. + * std::size_t bytes_transferred // Number of bytes received. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -637,30 +643,31 @@ class basic_seq_packet_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_receive(const MutableBufferSequence& buffers, socket_base::message_flags& out_flags, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_receive_with_flags(this), handler, + initiate_async_receive_with_flags(this), token, buffers, socket_base::message_flags(0), &out_flags); } /// Start an asynchronous receive. /** * This function is used to asynchronously receive data from the sequenced - * data socket. The function call always returns immediately. + * data socket. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param buffers One or more buffers into which the data will be received. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param in_flags Flags specifying how the receive call is to be made. * @@ -668,18 +675,20 @@ class basic_seq_packet_socket * associated with the received data. For example, if the * socket_base::message_end_of_record bit is set then the received data marks * the end of a record. The caller must guarantee that the referenced - * variable remains valid until the handler is called. + * variable remains valid until the completion handler is called. * - * @param handler The handler to be called when the receive operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the receive completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes received. + * std::size_t bytes_transferred // Number of bytes received. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -709,20 +718,20 @@ class basic_seq_packet_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_receive(const MutableBufferSequence& buffers, socket_base::message_flags in_flags, socket_base::message_flags& out_flags, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( initiate_async_receive_with_flags(this), - handler, buffers, in_flags, &out_flags); + token, buffers, in_flags, &out_flags); } private: diff --git a/include/boost/asio/basic_serial_port.hpp b/include/boost/asio/basic_serial_port.hpp index 9c8f1cf96a..fd0d4bdf28 100644 --- a/include/boost/asio/basic_serial_port.hpp +++ b/include/boost/asio/basic_serial_port.hpp @@ -657,23 +657,26 @@ class basic_serial_port /// Start an asynchronous write. /** * This function is used to asynchronously write data to the serial port. - * The function call always returns immediately. + * It is an initiating function for an @ref asynchronous_operation, and always + * returns immediately. * * @param buffers One or more data buffers to be written to the serial port. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes written. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -705,17 +708,17 @@ class basic_serial_port */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_some(const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_write_some(this), handler, buffers); + initiate_async_write_some(this), token, buffers); } /// Read some data from the serial port. @@ -784,23 +787,26 @@ class basic_serial_port /// Start an asynchronous read. /** * This function is used to asynchronously read data from the serial port. - * The function call always returns immediately. + * It is an initiating function for an @ref asynchronous_operation, and always + * returns immediately. * * @param buffers One or more buffers into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes read. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -833,17 +839,17 @@ class basic_serial_port */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_some(const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_read_some(this), handler, buffers); + initiate_async_read_some(this), token, buffers); } private: diff --git a/include/boost/asio/basic_signal_set.hpp b/include/boost/asio/basic_signal_set.hpp index df6f48a63c..1ac834839a 100644 --- a/include/boost/asio/basic_signal_set.hpp +++ b/include/boost/asio/basic_signal_set.hpp @@ -495,26 +495,29 @@ class basic_signal_set /// Start an asynchronous operation to wait for a signal to be delivered. /** * This function may be used to initiate an asynchronous wait against the - * signal set. It always returns immediately. + * signal set. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * - * For each call to async_wait(), the supplied handler will be called exactly - * once. The handler will be called when: + * For each call to async_wait(), the completion handler will be called + * exactly once. The completion handler will be called when: * * @li One of the registered signals in the signal set occurs; or * * @li The signal set was cancelled, in which case the handler is passed the * error code boost::asio::error::operation_aborted. * - * @param handler The handler to be called when the signal occurs. Copies - * will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the wait completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. * int signal_number // Indicates which signal occurred. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -532,15 +535,15 @@ class basic_signal_set */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, int)) - SignalHandler BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(SignalHandler, + SignalToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(SignalToken, void (boost::system::error_code, int)) async_wait( - BOOST_ASIO_MOVE_ARG(SignalHandler) handler + BOOST_ASIO_MOVE_ARG(SignalToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_wait(this), handler); + return async_initiate( + initiate_async_wait(this), token); } private: diff --git a/include/boost/asio/basic_socket.hpp b/include/boost/asio/basic_socket.hpp index 385d1b4486..a718ca1861 100644 --- a/include/boost/asio/basic_socket.hpp +++ b/include/boost/asio/basic_socket.hpp @@ -908,7 +908,8 @@ class basic_socket /// Start an asynchronous connect. /** * This function is used to asynchronously connect a socket to the specified - * remote endpoint. The function call always returns immediately. + * remote endpoint. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * The socket is automatically opened if it is not already open. If the * connect fails, and the socket was automatically opened, the socket is @@ -917,15 +918,17 @@ class basic_socket * @param peer_endpoint The remote endpoint to which the socket will be * connected. Copies will be made of the endpoint object as required. * - * @param handler The handler to be called when the connection operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the connect completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error // Result of operation + * const boost::system::error_code& 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -961,11 +964,11 @@ class basic_socket */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code)) - ConnectHandler BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ConnectHandler, + ConnectToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ConnectToken, void (boost::system::error_code)) async_connect(const endpoint_type& peer_endpoint, - BOOST_ASIO_MOVE_ARG(ConnectHandler) handler + BOOST_ASIO_MOVE_ARG(ConnectToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { boost::system::error_code open_ec; @@ -975,8 +978,8 @@ class basic_socket impl_.get_service().open(impl_.get_implementation(), protocol, open_ec); } - return async_initiate( - initiate_async_connect(this), handler, peer_endpoint, open_ec); + return async_initiate( + initiate_async_connect(this), token, peer_endpoint, open_ec); } /// Set an option on the socket. @@ -1760,19 +1763,23 @@ class basic_socket /// write, or to have pending error conditions. /** * This function is used to perform an asynchronous wait for a socket to enter - * a ready to read, write or error condition state. + * a ready to read, write or error condition state. It is an initiating + * function for an @ref asynchronous_operation, and always returns + * immediately. * * @param w Specifies the desired socket state. * - * @param handler The handler to be called when the wait operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the wait completes. Potential + * completion tokens include @ref use_future, @ref use_awaitable, @ref + * yield_context, or a function object with the correct completion signature. + * The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error // Result of operation + * const boost::system::error_code& 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1807,15 +1814,15 @@ class basic_socket */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code)) - WaitHandler BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WaitHandler, + WaitToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WaitToken, void (boost::system::error_code)) async_wait(wait_type w, - BOOST_ASIO_MOVE_ARG(WaitHandler) handler + BOOST_ASIO_MOVE_ARG(WaitToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_wait(this), handler, w); + return async_initiate( + initiate_async_wait(this), token, w); } protected: diff --git a/include/boost/asio/basic_socket_acceptor.hpp b/include/boost/asio/basic_socket_acceptor.hpp index 83b3c6de1d..fe048266f5 100644 --- a/include/boost/asio/basic_socket_acceptor.hpp +++ b/include/boost/asio/basic_socket_acceptor.hpp @@ -1197,19 +1197,23 @@ class basic_socket_acceptor /// write, or to have pending error conditions. /** * This function is used to perform an asynchronous wait for an acceptor to - * enter a ready to read, write or error condition state. + * enter a ready to read, write or error condition state. It is an initiating + * function for an @ref asynchronous_operation, and always returns + * immediately. * * @param w Specifies the desired acceptor state. * - * @param handler The handler to be called when the wait operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the wait completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error // Result of operation + * const boost::system::error_code& 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1246,15 +1250,15 @@ class basic_socket_acceptor */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code)) - WaitHandler BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WaitHandler, + WaitToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WaitToken, void (boost::system::error_code)) async_wait(wait_type w, - BOOST_ASIO_MOVE_ARG(WaitHandler) handler + BOOST_ASIO_MOVE_ARG(WaitToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_wait(this), handler, w); + return async_initiate( + initiate_async_wait(this), token, w); } #if !defined(BOOST_ASIO_NO_EXTENSIONS) @@ -1326,21 +1330,25 @@ class basic_socket_acceptor /// Start an asynchronous accept. /** * This function is used to asynchronously accept a new connection into a - * socket. The function call always returns immediately. + * socket, and additionally obtain the endpoint of the remote peer. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * @param peer The socket into which the new connection will be accepted. * Ownership of the peer object is retained by the caller, which must - * guarantee that it is valid until the handler is called. + * guarantee that it is valid until the completion handler is called. * - * @param handler The handler to be called when the accept operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the accept completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1376,18 +1384,18 @@ class basic_socket_acceptor */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(AcceptHandler, + AcceptToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(AcceptToken, void (boost::system::error_code)) async_accept(basic_socket& peer, - BOOST_ASIO_MOVE_ARG(AcceptHandler) handler + BOOST_ASIO_MOVE_ARG(AcceptToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type), typename constraint< is_convertible::value >::type = 0) { - return async_initiate( - initiate_async_accept(this), handler, + return async_initiate( + initiate_async_accept(this), token, &peer, static_cast(0)); } @@ -1464,27 +1472,30 @@ class basic_socket_acceptor /// Start an asynchronous accept. /** * This function is used to asynchronously accept a new connection into a - * socket, and additionally obtain the endpoint of the remote peer. The - * function call always returns immediately. + * socket, and additionally obtain the endpoint of the remote peer. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * @param peer The socket into which the new connection will be accepted. * Ownership of the peer object is retained by the caller, which must - * guarantee that it is valid until the handler is called. + * guarantee that it is valid until the completion handler is called. * * @param peer_endpoint An endpoint object into which the endpoint of the * remote peer will be written. Ownership of the peer_endpoint object is * retained by the caller, which must guarantee that it is valid until the * handler is called. * - * @param handler The handler to be called when the accept operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the accept completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1502,16 +1513,16 @@ class basic_socket_acceptor */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(AcceptHandler, + AcceptToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(AcceptToken, void (boost::system::error_code)) async_accept(basic_socket& peer, endpoint_type& peer_endpoint, - BOOST_ASIO_MOVE_ARG(AcceptHandler) handler + BOOST_ASIO_MOVE_ARG(AcceptToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_accept(this), handler, &peer, &peer_endpoint); + return async_initiate( + initiate_async_accept(this), token, &peer, &peer_endpoint); } #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) @@ -1583,25 +1594,29 @@ class basic_socket_acceptor /// Start an asynchronous accept. /** - * This function is used to asynchronously accept a new connection. The - * function call always returns immediately. + * This function is used to asynchronously accept a new connection. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * This overload requires that the Protocol template parameter satisfy the * AcceptableProtocol type requirements. * - * @param handler The handler to be called when the accept operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the accept completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, + * * // On success, the newly accepted socket. * typename Protocol::socket::template * rebind_executor::other peer * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1640,20 +1655,20 @@ class basic_socket_acceptor template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, typename Protocol::socket::template rebind_executor< - executor_type>::other)) MoveAcceptHandler + executor_type>::other)) MoveAcceptToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(MoveAcceptHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(MoveAcceptToken, void (boost::system::error_code, typename Protocol::socket::template rebind_executor::other)) async_accept( - BOOST_ASIO_MOVE_ARG(MoveAcceptHandler) handler + BOOST_ASIO_MOVE_ARG(MoveAcceptToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate::other)>( - initiate_async_move_accept(this), handler, + initiate_async_move_accept(this), token, impl_.get_executor(), static_cast(0), static_cast::other*>(0)); @@ -1823,8 +1838,9 @@ class basic_socket_acceptor /// Start an asynchronous accept. /** - * This function is used to asynchronously accept a new connection. The - * function call always returns immediately. + * This function is used to asynchronously accept a new connection. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * This overload requires that the Protocol template parameter satisfy the * AcceptableProtocol type requirements. @@ -1832,17 +1848,22 @@ class basic_socket_acceptor * @param ex The I/O executor object to be used for the newly accepted * socket. * - * @param handler The handler to be called when the accept operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the accept completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, + * + * // On success, the newly accepted socket. * typename Protocol::socket::template rebind_executor< - * Executor1>::other peer // On success, the newly accepted socket. + * Executor1>::other peer * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1881,14 +1902,14 @@ class basic_socket_acceptor template ::other)) MoveAcceptHandler + Executor1>::other)) MoveAcceptToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(MoveAcceptHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(MoveAcceptToken, void (boost::system::error_code, typename Protocol::socket::template rebind_executor< Executor1>::other)) async_accept(const Executor1& ex, - BOOST_ASIO_MOVE_ARG(MoveAcceptHandler) handler + BOOST_ASIO_MOVE_ARG(MoveAcceptToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type), typename constraint< is_executor::value @@ -1898,17 +1919,18 @@ class basic_socket_acceptor typedef typename Protocol::socket::template rebind_executor< Executor1>::other other_socket_type; - return async_initiate( - initiate_async_move_accept(this), handler, + initiate_async_move_accept(this), token, ex, static_cast(0), static_cast(0)); } /// Start an asynchronous accept. /** - * This function is used to asynchronously accept a new connection. The - * function call always returns immediately. + * This function is used to asynchronously accept a new connection. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * This overload requires that the Protocol template parameter satisfy the * AcceptableProtocol type requirements. @@ -1916,18 +1938,22 @@ class basic_socket_acceptor * @param context The I/O execution context object to be used for the newly * accepted socket. * - * @param handler The handler to be called when the accept operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the accept completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, + * + * // On success, the newly accepted socket. * typename Protocol::socket::template rebind_executor< * typename ExecutionContext::executor_type>::other peer - * // On success, the newly accepted socket. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1966,14 +1992,14 @@ class basic_socket_acceptor template ::other)) MoveAcceptHandler + typename ExecutionContext::executor_type>::other)) MoveAcceptToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(MoveAcceptHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(MoveAcceptToken, void (boost::system::error_code, typename Protocol::socket::template rebind_executor< typename ExecutionContext::executor_type>::other)) async_accept(ExecutionContext& context, - BOOST_ASIO_MOVE_ARG(MoveAcceptHandler) handler + BOOST_ASIO_MOVE_ARG(MoveAcceptToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type), typename constraint< is_convertible::value @@ -1982,9 +2008,9 @@ class basic_socket_acceptor typedef typename Protocol::socket::template rebind_executor< typename ExecutionContext::executor_type>::other other_socket_type; - return async_initiate( - initiate_async_move_accept(this), handler, + initiate_async_move_accept(this), token, context.get_executor(), static_cast(0), static_cast(0)); } @@ -2066,8 +2092,9 @@ class basic_socket_acceptor /// Start an asynchronous accept. /** - * This function is used to asynchronously accept a new connection. The - * function call always returns immediately. + * This function is used to asynchronously accept a new connection. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * This overload requires that the Protocol template parameter satisfy the * AcceptableProtocol type requirements. @@ -2075,21 +2102,24 @@ class basic_socket_acceptor * @param peer_endpoint An endpoint object into which the endpoint of the * remote peer will be written. Ownership of the peer_endpoint object is * retained by the caller, which must guarantee that it is valid until the - * handler is called. + * completion handler is called. * - * @param handler The handler to be called when the accept operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the accept completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, + * * // On success, the newly accepted socket. * typename Protocol::socket::template * rebind_executor::other peer * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -2129,20 +2159,20 @@ class basic_socket_acceptor template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, typename Protocol::socket::template rebind_executor< - executor_type>::other)) MoveAcceptHandler + executor_type>::other)) MoveAcceptToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(MoveAcceptHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(MoveAcceptToken, void (boost::system::error_code, typename Protocol::socket::template rebind_executor::other)) async_accept(endpoint_type& peer_endpoint, - BOOST_ASIO_MOVE_ARG(MoveAcceptHandler) handler + BOOST_ASIO_MOVE_ARG(MoveAcceptToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate::other)>( - initiate_async_move_accept(this), handler, + initiate_async_move_accept(this), token, impl_.get_executor(), &peer_endpoint, static_cast::other*>(0)); @@ -2338,8 +2368,9 @@ class basic_socket_acceptor /// Start an asynchronous accept. /** - * This function is used to asynchronously accept a new connection. The - * function call always returns immediately. + * This function is used to asynchronously accept a new connection. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * This overload requires that the Protocol template parameter satisfy the * AcceptableProtocol type requirements. @@ -2350,19 +2381,24 @@ class basic_socket_acceptor * @param peer_endpoint An endpoint object into which the endpoint of the * remote peer will be written. Ownership of the peer_endpoint object is * retained by the caller, which must guarantee that it is valid until the - * handler is called. + * completion handler is called. * - * @param handler The handler to be called when the accept operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the accept completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, + * + * // On success, the newly accepted socket. * typename Protocol::socket::template rebind_executor< - * Executor1>::other peer // On success, the newly accepted socket. + * Executor1>::other peer * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -2402,14 +2438,14 @@ class basic_socket_acceptor template ::other)) MoveAcceptHandler + Executor1>::other)) MoveAcceptToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(MoveAcceptHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(MoveAcceptToken, void (boost::system::error_code, typename Protocol::socket::template rebind_executor< Executor1>::other)) async_accept(const Executor1& ex, endpoint_type& peer_endpoint, - BOOST_ASIO_MOVE_ARG(MoveAcceptHandler) handler + BOOST_ASIO_MOVE_ARG(MoveAcceptToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type), typename constraint< is_executor::value @@ -2419,17 +2455,18 @@ class basic_socket_acceptor typedef typename Protocol::socket::template rebind_executor< Executor1>::other other_socket_type; - return async_initiate( - initiate_async_move_accept(this), handler, + initiate_async_move_accept(this), token, ex, &peer_endpoint, static_cast(0)); } /// Start an asynchronous accept. /** - * This function is used to asynchronously accept a new connection. The - * function call always returns immediately. + * This function is used to asynchronously accept a new connection. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * This overload requires that the Protocol template parameter satisfy the * AcceptableProtocol type requirements. @@ -2440,20 +2477,24 @@ class basic_socket_acceptor * @param peer_endpoint An endpoint object into which the endpoint of the * remote peer will be written. Ownership of the peer_endpoint object is * retained by the caller, which must guarantee that it is valid until the - * handler is called. + * completion handler is called. * - * @param handler The handler to be called when the accept operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the accept completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, + * + * // On success, the newly accepted socket. * typename Protocol::socket::template rebind_executor< * typename ExecutionContext::executor_type>::other peer - * // On success, the newly accepted socket. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -2493,15 +2534,15 @@ class basic_socket_acceptor template ::other)) MoveAcceptHandler + typename ExecutionContext::executor_type>::other)) MoveAcceptToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(MoveAcceptHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(MoveAcceptToken, void (boost::system::error_code, typename Protocol::socket::template rebind_executor< typename ExecutionContext::executor_type>::other)) async_accept(ExecutionContext& context, endpoint_type& peer_endpoint, - BOOST_ASIO_MOVE_ARG(MoveAcceptHandler) handler + BOOST_ASIO_MOVE_ARG(MoveAcceptToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type), typename constraint< is_convertible::value @@ -2510,9 +2551,9 @@ class basic_socket_acceptor typedef typename Protocol::socket::template rebind_executor< typename ExecutionContext::executor_type>::other other_socket_type; - return async_initiate( - initiate_async_move_accept(this), handler, + initiate_async_move_accept(this), token, context.get_executor(), &peer_endpoint, static_cast(0)); } diff --git a/include/boost/asio/basic_stream_file.hpp b/include/boost/asio/basic_stream_file.hpp index d2ad9bb5b3..188981c29e 100644 --- a/include/boost/asio/basic_stream_file.hpp +++ b/include/boost/asio/basic_stream_file.hpp @@ -469,23 +469,26 @@ class basic_stream_file /// Start an asynchronous write. /** * This function is used to asynchronously write data to the stream file. - * The function call always returns immediately. + * It is an initiating function for an @ref asynchronous_operation, and always + * returns immediately. * * @param buffers One or more data buffers to be written to the file. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes written. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -516,17 +519,17 @@ class basic_stream_file */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_some(const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_write_some(this), handler, buffers); + initiate_async_write_some(this), token, buffers); } /// Read some data from the file. @@ -594,23 +597,26 @@ class basic_stream_file /// Start an asynchronous read. /** * This function is used to asynchronously read data from the stream file. - * The function call always returns immediately. + * It is an initiating function for an @ref asynchronous_operation, and always + * returns immediately. * * @param buffers One or more buffers into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes read. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -642,17 +648,17 @@ class basic_stream_file */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_some(const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_read_some(this), handler, buffers); + initiate_async_read_some(this), token, buffers); } private: diff --git a/include/boost/asio/basic_stream_socket.hpp b/include/boost/asio/basic_stream_socket.hpp index 8834c12d43..6764670399 100644 --- a/include/boost/asio/basic_stream_socket.hpp +++ b/include/boost/asio/basic_stream_socket.hpp @@ -439,23 +439,26 @@ class basic_stream_socket /// Start an asynchronous send. /** * This function is used to asynchronously send data on the stream socket. - * The function call always returns immediately. + * It is an initiating function for an @ref asynchronous_operation, and always + * returns immediately. * * @param buffers One or more data buffers to be sent on the socket. Although * the buffers object may be copied as necessary, ownership of the underlying * memory blocks is retained by the caller, which must guarantee that they - * remain valid until the handler is called. + * remain valid until the completion handler is called. * - * @param handler The handler to be called when the send operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the send completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes sent. + * std::size_t bytes_transferred // Number of bytes sent. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -486,42 +489,45 @@ class basic_stream_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_send(const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_send(this), handler, + initiate_async_send(this), token, buffers, socket_base::message_flags(0)); } /// Start an asynchronous send. /** * This function is used to asynchronously send data on the stream socket. - * The function call always returns immediately. + * It is an initiating function for an @ref asynchronous_operation, and always + * returns immediately. * * @param buffers One or more data buffers to be sent on the socket. Although * the buffers object may be copied as necessary, ownership of the underlying * memory blocks is retained by the caller, which must guarantee that they - * remain valid until the handler is called. + * remain valid until the completion handler is called. * * @param flags Flags specifying how the send call is to be made. * - * @param handler The handler to be called when the send operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the send completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes sent. + * std::size_t bytes_transferred // Number of bytes sent. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -552,18 +558,18 @@ class basic_stream_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_send(const ConstBufferSequence& buffers, socket_base::message_flags flags, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_send(this), handler, buffers, flags); + initiate_async_send(this), token, buffers, flags); } /// Receive some data on the socket. @@ -674,23 +680,26 @@ class basic_stream_socket /// Start an asynchronous receive. /** * This function is used to asynchronously receive data from the stream - * socket. The function call always returns immediately. + * socket. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param buffers One or more buffers into which the data will be received. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * - * @param handler The handler to be called when the receive operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the receive completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes received. + * std::size_t bytes_transferred // Number of bytes received. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -723,42 +732,45 @@ class basic_stream_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_receive(const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_receive(this), handler, + initiate_async_receive(this), token, buffers, socket_base::message_flags(0)); } /// Start an asynchronous receive. /** * This function is used to asynchronously receive data from the stream - * socket. The function call always returns immediately. + * socket. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param buffers One or more buffers into which the data will be received. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param flags Flags specifying how the receive call is to be made. * - * @param handler The handler to be called when the receive operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the receive completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes received. + * std::size_t bytes_transferred // Number of bytes received. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -791,18 +803,18 @@ class basic_stream_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_receive(const MutableBufferSequence& buffers, socket_base::message_flags flags, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_receive(this), handler, buffers, flags); + initiate_async_receive(this), token, buffers, flags); } /// Write some data to the socket. @@ -869,23 +881,26 @@ class basic_stream_socket /// Start an asynchronous write. /** * This function is used to asynchronously write data to the stream socket. - * The function call always returns immediately. + * It is an initiating function for an @ref asynchronous_operation, and always + * returns immediately. * * @param buffers One or more data buffers to be written to the socket. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes written. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -916,17 +931,17 @@ class basic_stream_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_some(const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_send(this), handler, + initiate_async_send(this), token, buffers, socket_base::message_flags(0)); } @@ -996,23 +1011,26 @@ class basic_stream_socket /// Start an asynchronous read. /** * This function is used to asynchronously read data from the stream socket. - * The function call always returns immediately. + * socket. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param buffers One or more buffers into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes read. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1044,17 +1062,17 @@ class basic_stream_socket */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_some(const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_receive(this), handler, + initiate_async_receive(this), token, buffers, socket_base::message_flags(0)); } diff --git a/include/boost/asio/basic_waitable_timer.hpp b/include/boost/asio/basic_waitable_timer.hpp index 9cea564955..da68c9c1b5 100644 --- a/include/boost/asio/basic_waitable_timer.hpp +++ b/include/boost/asio/basic_waitable_timer.hpp @@ -727,25 +727,28 @@ class basic_waitable_timer /// Start an asynchronous wait on the timer. /** * This function may be used to initiate an asynchronous wait against the - * timer. It always returns immediately. + * timer. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * - * For each call to async_wait(), the supplied handler will be called exactly - * once. The handler will be called when: + * For each call to async_wait(), the completion handler will be called + * exactly once. The completion handler will be called when: * * @li The timer has expired. * * @li The timer was cancelled, in which case the handler is passed the error * code boost::asio::error::operation_aborted. * - * @param handler The handler to be called when the timer expires. Copies - * will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the timer expires. Potential + * completion tokens include @ref use_future, @ref use_awaitable, @ref + * yield_context, or a function object with the correct completion signature. + * The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -763,15 +766,15 @@ class basic_waitable_timer */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code)) - WaitHandler BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WaitHandler, + WaitToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WaitToken, void (boost::system::error_code)) async_wait( - BOOST_ASIO_MOVE_ARG(WaitHandler) handler + BOOST_ASIO_MOVE_ARG(WaitToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_wait(this), handler); + return async_initiate( + initiate_async_wait(this), token); } private: diff --git a/include/boost/asio/basic_writable_pipe.hpp b/include/boost/asio/basic_writable_pipe.hpp index 916bc6447c..b883c23d60 100644 --- a/include/boost/asio/basic_writable_pipe.hpp +++ b/include/boost/asio/basic_writable_pipe.hpp @@ -415,24 +415,27 @@ class basic_writable_pipe /// Start an asynchronous write. /** - * This function is used to asynchronously write data to the pipe. The - * function call always returns immediately. + * This function is used to asynchronously write data to the pipe. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. * * @param buffers One or more data buffers to be written to the pipe. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes written. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -453,17 +456,17 @@ class basic_writable_pipe */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_some(const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_write_some(this), handler, buffers); + initiate_async_write_some(this), token, buffers); } private: diff --git a/include/boost/asio/co_spawn.hpp b/include/boost/asio/co_spawn.hpp index 3ccec760c6..b453fc0ec7 100644 --- a/include/boost/asio/co_spawn.hpp +++ b/include/boost/asio/co_spawn.hpp @@ -55,7 +55,7 @@ struct awaitable_signature> * @param a The boost::asio::awaitable object that is the result of calling the * coroutine's entry point function. * - * @param token The completion token that will handle the notification that + * @param token The @ref completion_token that will handle the notification that * the thread of execution has completed. The function signature of the * completion handler must be: * @code void handler(std::exception_ptr, T); @endcode @@ -127,7 +127,7 @@ co_spawn(const Executor& ex, awaitable a, * @param a The boost::asio::awaitable object that is the result of calling the * coroutine's entry point function. * - * @param token The completion token that will handle the notification that + * @param token The @ref completion_token that will handle the notification that * the thread of execution has completed. The function signature of the * completion handler must be: * @code void handler(std::exception_ptr); @endcode @@ -191,7 +191,7 @@ co_spawn(const Executor& ex, awaitable a, * @param a The boost::asio::awaitable object that is the result of calling the * coroutine's entry point function. * - * @param token The completion token that will handle the notification that + * @param token The @ref completion_token that will handle the notification that * the thread of execution has completed. The function signature of the * completion handler must be: * @code void handler(std::exception_ptr); @endcode @@ -266,7 +266,7 @@ co_spawn(ExecutionContext& ctx, awaitable a, * @param a The boost::asio::awaitable object that is the result of calling the * coroutine's entry point function. * - * @param token The completion token that will handle the notification that + * @param token The @ref completion_token that will handle the notification that * the thread of execution has completed. The function signature of the * completion handler must be: * @code void handler(std::exception_ptr); @endcode @@ -334,8 +334,8 @@ co_spawn(ExecutionContext& ctx, awaitable a, * @c boost::asio::awaitable that will be used as the coroutine's entry * point. * - * @param token The completion token that will handle the notification that the - * thread of execution has completed. If @c R is @c void, the function + * @param token The @ref completion_token that will handle the notification + * that the thread of execution has completed. If @c R is @c void, the function * signature of the completion handler must be: * * @code void handler(std::exception_ptr); @endcode @@ -427,8 +427,8 @@ co_spawn(const Executor& ex, F&& f, * @c boost::asio::awaitable that will be used as the coroutine's entry * point. * - * @param token The completion token that will handle the notification that the - * thread of execution has completed. If @c R is @c void, the function + * @param token The @ref completion_token that will handle the notification + * that the thread of execution has completed. If @c R is @c void, the function * signature of the completion handler must be: * * @code void handler(std::exception_ptr); @endcode diff --git a/include/boost/asio/connect.hpp b/include/boost/asio/connect.hpp index 8839b0677c..0aa8be6305 100644 --- a/include/boost/asio/connect.hpp +++ b/include/boost/asio/connect.hpp @@ -611,16 +611,19 @@ Iterator connect(basic_socket& s, * This function attempts to connect a socket to one of a sequence of * endpoints. It does this by repeated calls to the socket's @c async_connect * member function, once for each endpoint in the sequence, until a connection - * is successfully established. + * is successfully established. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param s The socket to be connected. If the socket is already open, it will * be closed. * * @param endpoints A sequence of endpoints. * - * @param handler The handler to be called when the connect operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the connect completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. if the sequence is empty, set to * // boost::asio::error::not_found. Otherwise, contains the @@ -632,8 +635,8 @@ Iterator connect(basic_socket& s, * const typename Protocol::endpoint& endpoint * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -681,13 +684,13 @@ Iterator connect(basic_socket& s, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectToken, void (boost::system::error_code, typename Protocol::endpoint)) async_connect(basic_socket& s, const EndpointSequence& endpoints, - BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler + BOOST_ASIO_MOVE_ARG(RangeConnectToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor), typename constraint::value>::type = 0); @@ -699,16 +702,19 @@ async_connect(basic_socket& s, * This function attempts to connect a socket to one of a sequence of * endpoints. It does this by repeated calls to the socket's @c async_connect * member function, once for each endpoint in the sequence, until a connection - * is successfully established. + * is successfully established. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param s The socket to be connected. If the socket is already open, it will * be closed. * * @param begin An iterator pointing to the start of a sequence of endpoints. * - * @param handler The handler to be called when the connect operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the connect completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. if the sequence is empty, set to * // boost::asio::error::not_found. Otherwise, contains the @@ -720,8 +726,8 @@ async_connect(basic_socket& s, * Iterator iterator * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -743,12 +749,12 @@ async_connect(basic_socket& s, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectToken, void (boost::system::error_code, Iterator)) async_connect(basic_socket& s, Iterator begin, - BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler + BOOST_ASIO_MOVE_ARG(IteratorConnectToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor), typename constraint::value>::type = 0); #endif // !defined(BOOST_ASIO_NO_DEPRECATED) @@ -759,7 +765,8 @@ async_connect(basic_socket& s, Iterator begin, * This function attempts to connect a socket to one of a sequence of * endpoints. It does this by repeated calls to the socket's @c async_connect * member function, once for each endpoint in the sequence, until a connection - * is successfully established. + * is successfully established. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param s The socket to be connected. If the socket is already open, it will * be closed. @@ -768,9 +775,11 @@ async_connect(basic_socket& s, Iterator begin, * * @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. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the connect completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. if the sequence is empty, set to * // boost::asio::error::not_found. Otherwise, contains the @@ -782,8 +791,8 @@ async_connect(basic_socket& s, Iterator begin, * Iterator iterator * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -817,12 +826,12 @@ async_connect(basic_socket& s, Iterator begin, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectToken, void (boost::system::error_code, Iterator)) async_connect(basic_socket& s, Iterator begin, Iterator end, - BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler + BOOST_ASIO_MOVE_ARG(IteratorConnectToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor)); /// Asynchronously establishes a socket connection by trying each endpoint in a @@ -831,7 +840,8 @@ async_connect(basic_socket& s, Iterator begin, Iterator end, * This function attempts to connect a socket to one of a sequence of * endpoints. It does this by repeated calls to the socket's @c async_connect * member function, once for each endpoint in the sequence, until a connection - * is successfully established. + * is successfully established. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param s The socket to be connected. If the socket is already open, it will * be closed. @@ -849,9 +859,11 @@ async_connect(basic_socket& s, Iterator begin, Iterator end, * 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. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the connect completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. if the sequence is empty, set to * // boost::asio::error::not_found. Otherwise, contains the @@ -863,8 +875,8 @@ async_connect(basic_socket& s, Iterator begin, Iterator end, * Iterator iterator * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -936,13 +948,13 @@ async_connect(basic_socket& s, Iterator begin, Iterator end, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectToken, void (boost::system::error_code, typename Protocol::endpoint)) async_connect(basic_socket& s, const EndpointSequence& endpoints, ConnectCondition connect_condition, - BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler + BOOST_ASIO_MOVE_ARG(RangeConnectToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor), typename constraint::value>::type = 0); @@ -954,7 +966,8 @@ async_connect(basic_socket& s, * This function attempts to connect a socket to one of a sequence of * endpoints. It does this by repeated calls to the socket's @c async_connect * member function, once for each endpoint in the sequence, until a connection - * is successfully established. + * is successfully established. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param s The socket to be connected. If the socket is already open, it will * be closed. @@ -972,9 +985,11 @@ async_connect(basic_socket& s, * 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. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the connect completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. if the sequence is empty, set to * // boost::asio::error::not_found. Otherwise, contains the @@ -986,8 +1001,8 @@ async_connect(basic_socket& s, * Iterator iterator * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1010,13 +1025,13 @@ async_connect(basic_socket& s, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectToken, void (boost::system::error_code, Iterator)) async_connect(basic_socket& s, Iterator begin, ConnectCondition connect_condition, - BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler + BOOST_ASIO_MOVE_ARG(IteratorConnectToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor), typename constraint::value>::type = 0); #endif // !defined(BOOST_ASIO_NO_DEPRECATED) @@ -1027,7 +1042,8 @@ async_connect(basic_socket& s, Iterator begin, * This function attempts to connect a socket to one of a sequence of * endpoints. It does this by repeated calls to the socket's @c async_connect * member function, once for each endpoint in the sequence, until a connection - * is successfully established. + * is successfully established. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param s The socket to be connected. If the socket is already open, it will * be closed. @@ -1047,9 +1063,11 @@ async_connect(basic_socket& s, Iterator begin, * 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. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the connect completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. if the sequence is empty, set to * // boost::asio::error::not_found. Otherwise, contains the @@ -1061,8 +1079,8 @@ async_connect(basic_socket& s, Iterator begin, * Iterator iterator * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1135,13 +1153,13 @@ async_connect(basic_socket& s, Iterator begin, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectToken, void (boost::system::error_code, Iterator)) async_connect(basic_socket& s, Iterator begin, Iterator end, ConnectCondition connect_condition, - BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler + BOOST_ASIO_MOVE_ARG(IteratorConnectToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor)); /*@}*/ diff --git a/include/boost/asio/impl/connect.hpp b/include/boost/asio/impl/connect.hpp index b1c37534bc..37f1ed9f19 100644 --- a/include/boost/asio/impl/connect.hpp +++ b/include/boost/asio/impl/connect.hpp @@ -800,103 +800,103 @@ struct associator -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectHandler, + typename Protocol::endpoint)) RangeConnectToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectToken, void (boost::system::error_code, typename Protocol::endpoint)) async_connect(basic_socket& s, const EndpointSequence& endpoints, - BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler, + BOOST_ASIO_MOVE_ARG(RangeConnectToken) token, typename constraint::value>::type) { - return async_initiate( detail::initiate_async_range_connect(s), - handler, endpoints, detail::default_connect_condition()); + token, endpoints, detail::default_connect_condition()); } #if !defined(BOOST_ASIO_NO_DEPRECATED) template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler, + Iterator)) IteratorConnectToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectToken, void (boost::system::error_code, Iterator)) async_connect(basic_socket& s, Iterator begin, - BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler, + BOOST_ASIO_MOVE_ARG(IteratorConnectToken) token, typename constraint::value>::type) { - return async_initiate( detail::initiate_async_iterator_connect(s), - handler, begin, Iterator(), detail::default_connect_condition()); + token, begin, Iterator(), detail::default_connect_condition()); } #endif // !defined(BOOST_ASIO_NO_DEPRECATED) template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler, + Iterator)) IteratorConnectToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectToken, void (boost::system::error_code, Iterator)) async_connect(basic_socket& s, Iterator begin, Iterator end, - BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler) + BOOST_ASIO_MOVE_ARG(IteratorConnectToken) token) { - return async_initiate( detail::initiate_async_iterator_connect(s), - handler, begin, end, detail::default_connect_condition()); + token, begin, end, detail::default_connect_condition()); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectHandler, + typename Protocol::endpoint)) RangeConnectToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectToken, void (boost::system::error_code, typename Protocol::endpoint)) async_connect(basic_socket& s, const EndpointSequence& endpoints, ConnectCondition connect_condition, - BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler, + BOOST_ASIO_MOVE_ARG(RangeConnectToken) token, typename constraint::value>::type) { - return async_initiate( detail::initiate_async_range_connect(s), - handler, endpoints, connect_condition); + token, endpoints, connect_condition); } #if !defined(BOOST_ASIO_NO_DEPRECATED) template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler, + Iterator)) IteratorConnectToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectToken, void (boost::system::error_code, Iterator)) async_connect(basic_socket& s, Iterator begin, ConnectCondition connect_condition, - BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler, + BOOST_ASIO_MOVE_ARG(IteratorConnectToken) token, typename constraint::value>::type) { - return async_initiate( detail::initiate_async_iterator_connect(s), - handler, begin, Iterator(), connect_condition); + token, begin, Iterator(), connect_condition); } #endif // !defined(BOOST_ASIO_NO_DEPRECATED) template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler, + Iterator)) IteratorConnectToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectToken, void (boost::system::error_code, Iterator)) async_connect(basic_socket& s, Iterator begin, Iterator end, ConnectCondition connect_condition, - BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler) + BOOST_ASIO_MOVE_ARG(IteratorConnectToken) token) { - return async_initiate( detail::initiate_async_iterator_connect(s), - handler, begin, end, connect_condition); + token, begin, end, connect_condition); } } // namespace asio diff --git a/include/boost/asio/impl/read.hpp b/include/boost/asio/impl/read.hpp index c403141def..c6ca3db903 100644 --- a/include/boost/asio/impl/read.hpp +++ b/include/boost/asio/impl/read.hpp @@ -562,37 +562,37 @@ struct associator -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_mutable_buffer_sequence::value >::type) { - return async_initiate( - detail::initiate_async_read_buffer_sequence(s), handler, + detail::initiate_async_read_buffer_sequence(s), token, buffers, BOOST_ASIO_MOVE_CAST(CompletionCondition)(completion_condition)); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_mutable_buffer_sequence::value >::type) { - return async_initiate( detail::initiate_async_read_buffer_sequence(s), - handler, buffers, transfer_all()); + token, buffers, transfer_all()); } #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) @@ -837,12 +837,12 @@ struct associator -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_dynamic_buffer_v1::type>::value >::type, @@ -852,19 +852,19 @@ async_read(AsyncReadStream& s, { return async_read(s, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v1)(buffers), - transfer_all(), BOOST_ASIO_MOVE_CAST(ReadHandler)(handler)); + transfer_all(), BOOST_ASIO_MOVE_CAST(ReadToken)(token)); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_dynamic_buffer_v1::type>::value >::type, @@ -872,10 +872,10 @@ async_read(AsyncReadStream& s, !is_dynamic_buffer_v2::type>::value >::type) { - return async_initiate( detail::initiate_async_read_dynbuf_v1(s), - handler, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v1)(buffers), + token, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v1)(buffers), BOOST_ASIO_MOVE_CAST(CompletionCondition)(completion_condition)); } @@ -884,29 +884,29 @@ async_read(AsyncReadStream& s, template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, basic_streambuf& b, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler) + BOOST_ASIO_MOVE_ARG(ReadToken) token) { return async_read(s, basic_streambuf_ref(b), - BOOST_ASIO_MOVE_CAST(ReadHandler)(handler)); + BOOST_ASIO_MOVE_CAST(ReadToken)(token)); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, basic_streambuf& b, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler) + BOOST_ASIO_MOVE_ARG(ReadToken) token) { return async_read(s, basic_streambuf_ref(b), BOOST_ASIO_MOVE_CAST(CompletionCondition)(completion_condition), - BOOST_ASIO_MOVE_CAST(ReadHandler)(handler)); + BOOST_ASIO_MOVE_CAST(ReadToken)(token)); } #endif // !defined(BOOST_ASIO_NO_IOSTREAM) @@ -1159,37 +1159,37 @@ struct associator -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_dynamic_buffer_v2::value >::type) { return async_read(s, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v2)(buffers), - transfer_all(), BOOST_ASIO_MOVE_CAST(ReadHandler)(handler)); + transfer_all(), BOOST_ASIO_MOVE_CAST(ReadToken)(token)); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_dynamic_buffer_v2::value >::type) { - return async_initiate( detail::initiate_async_read_dynbuf_v2(s), - handler, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v2)(buffers), + token, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v2)(buffers), BOOST_ASIO_MOVE_CAST(CompletionCondition)(completion_condition)); } diff --git a/include/boost/asio/impl/read_at.hpp b/include/boost/asio/impl/read_at.hpp index 8410b0068d..a41ec76c99 100644 --- a/include/boost/asio/impl/read_at.hpp +++ b/include/boost/asio/impl/read_at.hpp @@ -424,36 +424,36 @@ struct associator -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, const MutableBufferSequence& buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler) + BOOST_ASIO_MOVE_ARG(ReadToken) token) { - return async_initiate( detail::initiate_async_read_at_buffer_sequence< AsyncRandomAccessReadDevice>(d), - handler, offset, buffers, + token, offset, buffers, BOOST_ASIO_MOVE_CAST(CompletionCondition)(completion_condition)); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler) + BOOST_ASIO_MOVE_ARG(ReadToken) token) { - return async_initiate( detail::initiate_async_read_at_buffer_sequence< AsyncRandomAccessReadDevice>(d), - handler, offset, buffers, transfer_all()); + token, offset, buffers, transfer_all()); } #if !defined(BOOST_ASIO_NO_EXTENSIONS) @@ -694,34 +694,34 @@ struct associator -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, boost::asio::basic_streambuf& b, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler) + BOOST_ASIO_MOVE_ARG(ReadToken) token) { - return async_initiate( detail::initiate_async_read_at_streambuf(d), - handler, offset, &b, + token, offset, &b, BOOST_ASIO_MOVE_CAST(CompletionCondition)(completion_condition)); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, boost::asio::basic_streambuf& b, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler) + BOOST_ASIO_MOVE_ARG(ReadToken) token) { - return async_initiate( detail::initiate_async_read_at_streambuf(d), - handler, offset, &b, transfer_all()); + token, offset, &b, transfer_all()); } #endif // !defined(BOOST_ASIO_NO_IOSTREAM) diff --git a/include/boost/asio/impl/read_until.hpp b/include/boost/asio/impl/read_until.hpp index ce7432dd54..249f42c116 100644 --- a/include/boost/asio/impl/read_until.hpp +++ b/include/boost/asio/impl/read_until.hpp @@ -1073,12 +1073,12 @@ struct associator -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, - char delim, BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + char delim, BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_dynamic_buffer_v1::type>::value >::type, @@ -1086,10 +1086,10 @@ async_read_until(AsyncReadStream& s, !is_dynamic_buffer_v2::type>::value >::type) { - return async_initiate( detail::initiate_async_read_until_delim_v1(s), - handler, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v1)(buffers), delim); + token, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v1)(buffers), delim); } namespace detail @@ -1375,13 +1375,13 @@ struct associator -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, BOOST_ASIO_STRING_VIEW_PARAM delim, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_dynamic_buffer_v1::type>::value >::type, @@ -1389,10 +1389,10 @@ async_read_until(AsyncReadStream& s, !is_dynamic_buffer_v2::type>::value >::type) { - return async_initiate( detail::initiate_async_read_until_delim_string_v1(s), - handler, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v1)(buffers), + token, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v1)(buffers), static_cast(delim)); } @@ -1684,13 +1684,13 @@ struct associator -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, const boost::regex& expr, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_dynamic_buffer_v1::type>::value >::type, @@ -1698,10 +1698,10 @@ async_read_until(AsyncReadStream& s, !is_dynamic_buffer_v2::type>::value >::type) { - return async_initiate( detail::initiate_async_read_until_expr_v1(s), - handler, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v1)(buffers), expr); + token, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v1)(buffers), expr); } #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX) @@ -1992,12 +1992,12 @@ struct associator -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, - MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_match_condition::value >::type, @@ -2008,9 +2008,9 @@ async_read_until(AsyncReadStream& s, !is_dynamic_buffer_v2::type>::value >::type) { - return async_initiate( - detail::initiate_async_read_until_match_v1(s), handler, + detail::initiate_async_read_until_match_v1(s), token, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v1)(buffers), match_condition); } @@ -2018,60 +2018,60 @@ async_read_until(AsyncReadStream& s, template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, boost::asio::basic_streambuf& b, - char delim, BOOST_ASIO_MOVE_ARG(ReadHandler) handler) + char delim, BOOST_ASIO_MOVE_ARG(ReadToken) token) { return async_read_until(s, basic_streambuf_ref(b), - delim, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler)); + delim, BOOST_ASIO_MOVE_CAST(ReadToken)(token)); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, boost::asio::basic_streambuf& b, BOOST_ASIO_STRING_VIEW_PARAM delim, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler) + BOOST_ASIO_MOVE_ARG(ReadToken) token) { return async_read_until(s, basic_streambuf_ref(b), - delim, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler)); + delim, BOOST_ASIO_MOVE_CAST(ReadToken)(token)); } #if defined(BOOST_ASIO_HAS_BOOST_REGEX) template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, boost::asio::basic_streambuf& b, const boost::regex& expr, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler) + BOOST_ASIO_MOVE_ARG(ReadToken) token) { return async_read_until(s, basic_streambuf_ref(b), - expr, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler)); + expr, BOOST_ASIO_MOVE_CAST(ReadToken)(token)); } #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX) template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, boost::asio::basic_streambuf& b, - MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint::value>::type) { return async_read_until(s, basic_streambuf_ref(b), - match_condition, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler)); + match_condition, BOOST_ASIO_MOVE_CAST(ReadToken)(token)); } #endif // !defined(BOOST_ASIO_NO_IOSTREAM) @@ -2357,19 +2357,19 @@ struct associator -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, - char delim, BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + char delim, BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_dynamic_buffer_v2::value >::type) { - return async_initiate( detail::initiate_async_read_until_delim_v2(s), - handler, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v2)(buffers), delim); + token, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v2)(buffers), delim); } namespace detail @@ -2664,20 +2664,20 @@ struct associator -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, BOOST_ASIO_STRING_VIEW_PARAM delim, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_dynamic_buffer_v2::value >::type) { - return async_initiate( detail::initiate_async_read_until_delim_string_v2(s), - handler, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v2)(buffers), + token, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v2)(buffers), static_cast(delim)); } @@ -2978,19 +2978,19 @@ struct associator -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, - const boost::regex& expr, BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + const boost::regex& expr, BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_dynamic_buffer_v2::value >::type) { - return async_initiate( detail::initiate_async_read_until_expr_v2(s), - handler, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v2)(buffers), expr); + token, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v2)(buffers), expr); } #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX) @@ -3289,11 +3289,11 @@ struct associator -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + std::size_t)) ReadToken> +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, - MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadHandler) handler, + MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadToken) token, typename constraint< is_match_condition::value >::type, @@ -3301,9 +3301,9 @@ async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, is_dynamic_buffer_v2::value >::type) { - return async_initiate( - detail::initiate_async_read_until_match_v2(s), handler, + detail::initiate_async_read_until_match_v2(s), token, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v2)(buffers), match_condition); } diff --git a/include/boost/asio/impl/write.hpp b/include/boost/asio/impl/write.hpp index b4e7ec76d6..d87e6bbf36 100644 --- a/include/boost/asio/impl/write.hpp +++ b/include/boost/asio/impl/write.hpp @@ -527,38 +527,38 @@ struct associator -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler, + BOOST_ASIO_MOVE_ARG(WriteToken) token, typename constraint< is_const_buffer_sequence::value >::type) { - return async_initiate( detail::initiate_async_write_buffer_sequence(s), - handler, buffers, + token, buffers, BOOST_ASIO_MOVE_CAST(CompletionCondition)(completion_condition)); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler, + BOOST_ASIO_MOVE_ARG(WriteToken) token, typename constraint< is_const_buffer_sequence::value >::type) { - return async_initiate( detail::initiate_async_write_buffer_sequence(s), - handler, buffers, transfer_all()); + token, buffers, transfer_all()); } #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) @@ -761,12 +761,12 @@ struct associator -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler, + BOOST_ASIO_MOVE_ARG(WriteToken) token, typename constraint< is_dynamic_buffer_v1::type>::value >::type, @@ -776,19 +776,19 @@ async_write(AsyncWriteStream& s, { return async_write(s, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v1)(buffers), - transfer_all(), BOOST_ASIO_MOVE_CAST(WriteHandler)(handler)); + transfer_all(), BOOST_ASIO_MOVE_CAST(WriteToken)(token)); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler, + BOOST_ASIO_MOVE_ARG(WriteToken) token, typename constraint< is_dynamic_buffer_v1::type>::value >::type, @@ -796,10 +796,10 @@ async_write(AsyncWriteStream& s, !is_dynamic_buffer_v2::type>::value >::type) { - return async_initiate( detail::initiate_async_write_dynbuf_v1(s), - handler, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v1)(buffers), + token, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v1)(buffers), BOOST_ASIO_MOVE_CAST(CompletionCondition)(completion_condition)); } @@ -808,31 +808,31 @@ async_write(AsyncWriteStream& s, template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, boost::asio::basic_streambuf& b, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler) + BOOST_ASIO_MOVE_ARG(WriteToken) token) { return async_write(s, basic_streambuf_ref(b), - BOOST_ASIO_MOVE_CAST(WriteHandler)(handler)); + BOOST_ASIO_MOVE_CAST(WriteToken)(token)); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, boost::asio::basic_streambuf& b, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler) + BOOST_ASIO_MOVE_ARG(WriteToken) token) { return async_write(s, basic_streambuf_ref(b), BOOST_ASIO_MOVE_CAST(CompletionCondition)(completion_condition), - BOOST_ASIO_MOVE_CAST(WriteHandler)(handler)); + BOOST_ASIO_MOVE_CAST(WriteToken)(token)); } #endif // !defined(BOOST_ASIO_NO_IOSTREAM) @@ -1060,37 +1060,37 @@ struct associated_cancellation_slot< template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, DynamicBuffer_v2 buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler, + BOOST_ASIO_MOVE_ARG(WriteToken) token, typename constraint< is_dynamic_buffer_v2::value >::type) { return async_write(s, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v2)(buffers), - transfer_all(), BOOST_ASIO_MOVE_CAST(WriteHandler)(handler)); + transfer_all(), BOOST_ASIO_MOVE_CAST(WriteToken)(token)); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, DynamicBuffer_v2 buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler, + BOOST_ASIO_MOVE_ARG(WriteToken) token, typename constraint< is_dynamic_buffer_v2::value >::type) { - return async_initiate( detail::initiate_async_write_dynbuf_v2(s), - handler, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v2)(buffers), + token, BOOST_ASIO_MOVE_CAST(DynamicBuffer_v2)(buffers), BOOST_ASIO_MOVE_CAST(CompletionCondition)(completion_condition)); } diff --git a/include/boost/asio/impl/write_at.hpp b/include/boost/asio/impl/write_at.hpp index 89b5f8b35d..1e01cfd88d 100644 --- a/include/boost/asio/impl/write_at.hpp +++ b/include/boost/asio/impl/write_at.hpp @@ -409,36 +409,36 @@ struct associator -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, const ConstBufferSequence& buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler) + BOOST_ASIO_MOVE_ARG(WriteToken) token) { - return async_initiate( detail::initiate_async_write_at_buffer_sequence< AsyncRandomAccessWriteDevice>(d), - handler, offset, buffers, + token, offset, buffers, BOOST_ASIO_MOVE_CAST(CompletionCondition)(completion_condition)); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler) + BOOST_ASIO_MOVE_ARG(WriteToken) token) { - return async_initiate( detail::initiate_async_write_at_buffer_sequence< AsyncRandomAccessWriteDevice>(d), - handler, offset, buffers, transfer_all()); + token, offset, buffers, transfer_all()); } #if !defined(BOOST_ASIO_NO_EXTENSIONS) @@ -603,36 +603,36 @@ struct associator -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, boost::asio::basic_streambuf& b, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler) + BOOST_ASIO_MOVE_ARG(WriteToken) token) { - return async_initiate( detail::initiate_async_write_at_streambuf< AsyncRandomAccessWriteDevice>(d), - handler, offset, &b, + token, offset, &b, BOOST_ASIO_MOVE_CAST(CompletionCondition)(completion_condition)); } template -inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +inline BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, boost::asio::basic_streambuf& b, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler) + BOOST_ASIO_MOVE_ARG(WriteToken) token) { - return async_initiate( detail::initiate_async_write_at_streambuf< AsyncRandomAccessWriteDevice>(d), - handler, offset, &b, transfer_all()); + token, offset, &b, transfer_all()); } #endif // !defined(BOOST_ASIO_NO_IOSTREAM) diff --git a/include/boost/asio/ip/basic_resolver.hpp b/include/boost/asio/ip/basic_resolver.hpp index 372a395cfe..8b611a44dd 100644 --- a/include/boost/asio/ip/basic_resolver.hpp +++ b/include/boost/asio/ip/basic_resolver.hpp @@ -648,20 +648,23 @@ class basic_resolver /// Asynchronously perform forward resolution of a query to a list of entries. /** * This function is used to asynchronously resolve a query into a list of - * endpoint entries. + * endpoint entries. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param q A query object that determines what endpoints will be returned. * - * @param handler The handler to be called when the resolve operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the resolve completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. * resolver::results_type results // Resolved endpoints as a range. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * A successful resolve operation is guaranteed to pass a non-empty range to @@ -672,17 +675,17 @@ class basic_resolver */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, - results_type)) ResolveHandler + results_type)) ResolveToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveToken, void (boost::system::error_code, results_type)) async_resolve(const query& q, - BOOST_ASIO_MOVE_ARG(ResolveHandler) handler + BOOST_ASIO_MOVE_ARG(ResolveToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return boost::asio::async_initiate( - initiate_async_resolve(this), handler, q); + initiate_async_resolve(this), token, q); } #endif // !defined(BOOST_ASIO_NO_DEPRECATED) @@ -702,16 +705,18 @@ class basic_resolver * be an empty string, in which case all resolved endpoints will have a port * number of 0. * - * @param handler The handler to be called when the resolve operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the resolve completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. * resolver::results_type results // Resolved endpoints as a range. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * A successful resolve operation is guaranteed to pass a non-empty range to @@ -733,23 +738,24 @@ class basic_resolver */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, - results_type)) ResolveHandler + results_type)) ResolveToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveToken, void (boost::system::error_code, results_type)) async_resolve(BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service, - BOOST_ASIO_MOVE_ARG(ResolveHandler) handler + BOOST_ASIO_MOVE_ARG(ResolveToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { return async_resolve(host, service, resolver_base::flags(), - BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler)); + BOOST_ASIO_MOVE_CAST(ResolveToken)(token)); } /// Asynchronously perform forward resolution of a query to a list of entries. /** * This function is used to resolve host and service names into a list of - * endpoint entries. + * endpoint entries. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param host A string identifying a location. May be a descriptive name or * a numeric address string. If an empty string and the passive flag has been @@ -767,16 +773,18 @@ class basic_resolver * remote hosts. See the @ref resolver_base documentation for the set of * available flags. * - * @param handler The handler to be called when the resolve operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the resolve completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. * resolver::results_type results // Resolved endpoints as a range. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * A successful resolve operation is guaranteed to pass a non-empty range to @@ -798,28 +806,29 @@ class basic_resolver */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, - results_type)) ResolveHandler + results_type)) ResolveToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveToken, void (boost::system::error_code, results_type)) async_resolve(BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service, resolver_base::flags resolve_flags, - BOOST_ASIO_MOVE_ARG(ResolveHandler) handler + BOOST_ASIO_MOVE_ARG(ResolveToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { basic_resolver_query q(static_cast(host), static_cast(service), resolve_flags); - return boost::asio::async_initiate( - initiate_async_resolve(this), handler, q); + initiate_async_resolve(this), token, q); } /// Asynchronously perform forward resolution of a query to a list of entries. /** * This function is used to resolve host and service names into a list of - * endpoint entries. + * endpoint entries. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param protocol A protocol object, normally representing either the IPv4 or * IPv6 version of an internet protocol. @@ -835,16 +844,18 @@ class basic_resolver * be an empty string, in which case all resolved endpoints will have a port * number of 0. * - * @param handler The handler to be called when the resolve operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the resolve completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. * resolver::results_type results // Resolved endpoints as a range. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * A successful resolve operation is guaranteed to pass a non-empty range to @@ -866,23 +877,24 @@ class basic_resolver */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, - results_type)) ResolveHandler + results_type)) ResolveToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveToken, void (boost::system::error_code, results_type)) async_resolve(const protocol_type& protocol, BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service, - BOOST_ASIO_MOVE_ARG(ResolveHandler) handler + BOOST_ASIO_MOVE_ARG(ResolveToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { return async_resolve(protocol, host, service, resolver_base::flags(), - BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler)); + BOOST_ASIO_MOVE_CAST(ResolveToken)(token)); } /// Asynchronously perform forward resolution of a query to a list of entries. /** * This function is used to resolve host and service names into a list of - * endpoint entries. + * endpoint entries. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param protocol A protocol object, normally representing either the IPv4 or * IPv6 version of an internet protocol. @@ -903,16 +915,18 @@ class basic_resolver * remote hosts. See the @ref resolver_base documentation for the set of * available flags. * - * @param handler The handler to be called when the resolve operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the resolve completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. * resolver::results_type results // Resolved endpoints as a range. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * A successful resolve operation is guaranteed to pass a non-empty range to @@ -934,23 +948,23 @@ class basic_resolver */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, - results_type)) ResolveHandler + results_type)) ResolveToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveToken, void (boost::system::error_code, results_type)) async_resolve(const protocol_type& protocol, BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service, resolver_base::flags resolve_flags, - BOOST_ASIO_MOVE_ARG(ResolveHandler) handler + BOOST_ASIO_MOVE_ARG(ResolveToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { basic_resolver_query q( protocol, static_cast(host), static_cast(service), resolve_flags); - return boost::asio::async_initiate( - initiate_async_resolve(this), handler, q); + initiate_async_resolve(this), token, q); } /// Perform reverse resolution of an endpoint to a list of entries. @@ -999,21 +1013,24 @@ class basic_resolver /// entries. /** * This function is used to asynchronously resolve an endpoint into a list of - * endpoint entries. + * endpoint entries. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param e An endpoint object that determines what endpoints will be * returned. * - * @param handler The handler to be called when the resolve operation - * completes. Copies will be made of the handler as required. The function - * signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the resolve completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. * resolver::results_type results // Resolved endpoints as a range. * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * A successful resolve operation is guaranteed to pass a non-empty range to @@ -1024,17 +1041,17 @@ class basic_resolver */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, - results_type)) ResolveHandler + results_type)) ResolveToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveToken, void (boost::system::error_code, results_type)) async_resolve(const endpoint_type& e, - BOOST_ASIO_MOVE_ARG(ResolveHandler) handler + BOOST_ASIO_MOVE_ARG(ResolveToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return boost::asio::async_initiate( - initiate_async_resolve(this), handler, e); + initiate_async_resolve(this), token, e); } private: diff --git a/include/boost/asio/posix/basic_descriptor.hpp b/include/boost/asio/posix/basic_descriptor.hpp index c6ded97a9b..18d2269033 100644 --- a/include/boost/asio/posix/basic_descriptor.hpp +++ b/include/boost/asio/posix/basic_descriptor.hpp @@ -598,19 +598,23 @@ class basic_descriptor /// write, or to have pending error conditions. /** * This function is used to perform an asynchronous wait for a descriptor to - * enter a ready to read, write or error condition state. + * enter a ready to read, write or error condition state. It is an initiating + * function for an @ref asynchronous_operation, and always returns + * immediately. * * @param w Specifies the desired descriptor state. * - * @param handler The handler to be called when the wait operation completes. - * Copies will be made of the handler as required. The function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the wait completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error // Result of operation + * const boost::system::error_code& 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -647,15 +651,15 @@ class basic_descriptor */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code)) - WaitHandler BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WaitHandler, + WaitToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WaitToken, void (boost::system::error_code)) async_wait(wait_type w, - BOOST_ASIO_MOVE_ARG(WaitHandler) handler + BOOST_ASIO_MOVE_ARG(WaitToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_wait(this), handler, w); + return async_initiate( + initiate_async_wait(this), token, w); } protected: diff --git a/include/boost/asio/posix/basic_stream_descriptor.hpp b/include/boost/asio/posix/basic_stream_descriptor.hpp index 18c3b63a2f..24da0cc795 100644 --- a/include/boost/asio/posix/basic_stream_descriptor.hpp +++ b/include/boost/asio/posix/basic_stream_descriptor.hpp @@ -242,23 +242,26 @@ class basic_stream_descriptor /// Start an asynchronous write. /** * This function is used to asynchronously write data to the stream - * descriptor. The function call always returns immediately. + * descriptor. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param buffers One or more data buffers to be written to the descriptor. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes written. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -289,17 +292,17 @@ class basic_stream_descriptor */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_some(const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_write_some(this), handler, buffers); + initiate_async_write_some(this), token, buffers); } /// Read some data from the descriptor. @@ -368,23 +371,26 @@ class basic_stream_descriptor /// Start an asynchronous read. /** * This function is used to asynchronously read data from the stream - * descriptor. The function call always returns immediately. + * descriptor. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param buffers One or more buffers into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes read. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -416,17 +422,17 @@ class basic_stream_descriptor */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_some(const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_read_some(this), handler, buffers); + initiate_async_read_some(this), token, buffers); } private: diff --git a/include/boost/asio/read.hpp b/include/boost/asio/read.hpp index 9e3450bda6..138ecc8991 100644 --- a/include/boost/asio/read.hpp +++ b/include/boost/asio/read.hpp @@ -712,9 +712,9 @@ std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers, /// stream. /** * This function is used to asynchronously read a certain number of bytes of - * data from a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions is - * true: + * data from a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The supplied buffers are full. That is, the bytes transferred is equal to * the sum of the buffer sizes. @@ -734,23 +734,25 @@ std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers, * of the buffer sizes indicates the maximum number of bytes to read from the * stream. Although the buffers object may be copied as necessary, ownership of * the underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes copied into the - * // buffers. If an error occurred, - * // this will be the number of - * // bytes successfully transferred - * // prior to the error. + * // Number of bytes copied into the buffers. If an error + * // occurred, this will be the number of bytes successfully + * // transferred prior to the error. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -784,13 +786,13 @@ std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< @@ -801,9 +803,9 @@ async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, /// stream. /** * This function is used to asynchronously read a certain number of bytes of - * data from a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions is - * true: + * data from a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The supplied buffers are full. That is, the bytes transferred is equal to * the sum of the buffer sizes. @@ -817,7 +819,7 @@ async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, * of the buffer sizes indicates the maximum number of bytes to read from the * stream. Although the buffers object may be copied as necessary, ownership of * the underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param completion_condition The function object to be called to determine * whether the read operation is complete. The signature of the function object @@ -833,21 +835,23 @@ async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, * return value indicates the maximum number of bytes to be read on the next * call to the stream's async_read_some function. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes copied into the - * // buffers. If an error occurred, - * // this will be the number of - * // bytes successfully transferred - * // prior to the error. + * // Number of bytes copied into the buffers. If an error + * // occurred, this will be the number of bytes successfully + * // transferred prior to the error. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -877,14 +881,14 @@ async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< @@ -897,9 +901,9 @@ async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, /// stream. /** * This function is used to asynchronously read a certain number of bytes of - * data from a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions is - * true: + * data from a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The specified dynamic buffer sequence is full (that is, it has reached * maximum size). @@ -918,23 +922,25 @@ async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, * @param buffers The dynamic buffer sequence into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes copied into the - * // buffers. If an error occurred, - * // this will be the number of - * // bytes successfully transferred - * // prior to the error. + * // Number of bytes copied into the buffers. If an error + * // occurred, this will be the number of bytes successfully + * // transferred prior to the error. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -959,14 +965,14 @@ async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< @@ -980,9 +986,9 @@ async_read(AsyncReadStream& s, /// stream. /** * This function is used to asynchronously read a certain number of bytes of - * data from a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions is - * true: + * data from a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The specified dynamic buffer sequence is full (that is, it has reached * maximum size). @@ -1001,7 +1007,7 @@ async_read(AsyncReadStream& s, * @param buffers The dynamic buffer sequence into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param completion_condition The function object to be called to determine * whether the read operation is complete. The signature of the function object @@ -1017,21 +1023,23 @@ async_read(AsyncReadStream& s, * return value indicates the maximum number of bytes to be read on the next * call to the stream's async_read_some function. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes copied into the - * // buffers. If an error occurred, - * // this will be the number of - * // bytes successfully transferred - * // prior to the error. + * // Number of bytes copied into the buffers. If an error + * // occurred, this will be the number of bytes successfully + * // transferred prior to the error. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1051,15 +1059,15 @@ async_read(AsyncReadStream& s, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< @@ -1076,9 +1084,9 @@ async_read(AsyncReadStream& s, /// stream. /** * This function is used to asynchronously read a certain number of bytes of - * data from a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions is - * true: + * data from a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The supplied buffer is full (that is, it has reached maximum size). * @@ -1095,23 +1103,25 @@ async_read(AsyncReadStream& s, * * @param b A basic_streambuf object into which the data will be read. Ownership * of the streambuf is retained by the caller, which must guarantee that it - * remains valid until the handler is called. + * remains valid until the completion 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 function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes copied into the - * // buffers. If an error occurred, - * // this will be the number of - * // bytes successfully transferred - * // prior to the error. + * // Number of bytes copied into the buffers. If an error + * // occurred, this will be the number of bytes successfully + * // transferred prior to the error. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1136,13 +1146,13 @@ async_read(AsyncReadStream& s, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, basic_streambuf& b, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type)); @@ -1150,9 +1160,9 @@ async_read(AsyncReadStream& s, basic_streambuf& b, /// stream. /** * This function is used to asynchronously read a certain number of bytes of - * data from a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions is - * true: + * data from a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The supplied buffer is full (that is, it has reached maximum size). * @@ -1169,7 +1179,7 @@ async_read(AsyncReadStream& s, basic_streambuf& b, * * @param b A basic_streambuf object into which the data will be read. Ownership * of the streambuf is retained by the caller, which must guarantee that it - * remains valid until the handler is called. + * remains valid until the completion handler is called. * * @param completion_condition The function object to be called to determine * whether the read operation is complete. The signature of the function object @@ -1185,21 +1195,23 @@ async_read(AsyncReadStream& s, basic_streambuf& b, * return value indicates the maximum number of bytes to be read on the next * call to the stream's async_read_some function. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes copied into the - * // buffers. If an error occurred, - * // this will be the number of - * // bytes successfully transferred - * // prior to the error. + * // Number of bytes copied into the buffers. If an error + * // occurred, this will be the number of bytes successfully + * // transferred prior to the error. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1219,14 +1231,14 @@ async_read(AsyncReadStream& s, basic_streambuf& b, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, basic_streambuf& b, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type)); @@ -1238,9 +1250,9 @@ async_read(AsyncReadStream& s, basic_streambuf& b, /// stream. /** * This function is used to asynchronously read a certain number of bytes of - * data from a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions is - * true: + * data from a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The specified dynamic buffer sequence is full (that is, it has reached * maximum size). @@ -1259,23 +1271,25 @@ async_read(AsyncReadStream& s, basic_streambuf& b, * @param buffers The dynamic buffer sequence into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes copied into the - * // buffers. If an error occurred, - * // this will be the number of - * // bytes successfully transferred - * // prior to the error. + * // Number of bytes copied into the buffers. If an error + * // occurred, this will be the number of bytes successfully + * // transferred prior to the error. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1300,13 +1314,13 @@ async_read(AsyncReadStream& s, basic_streambuf& b, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< @@ -1317,9 +1331,9 @@ async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers, /// stream. /** * This function is used to asynchronously read a certain number of bytes of - * data from a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions is - * true: + * data from a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The specified dynamic buffer sequence is full (that is, it has reached * maximum size). @@ -1338,7 +1352,7 @@ async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers, * @param buffers The dynamic buffer sequence into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param completion_condition The function object to be called to determine * whether the read operation is complete. The signature of the function object @@ -1354,21 +1368,23 @@ async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers, * return value indicates the maximum number of bytes to be read on the next * call to the stream's async_read_some function. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes copied into the - * // buffers. If an error occurred, - * // this will be the number of - * // bytes successfully transferred - * // prior to the error. + * // Number of bytes copied into the buffers. If an error + * // occurred, this will be the number of bytes successfully + * // transferred prior to the error. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1388,14 +1404,14 @@ async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< diff --git a/include/boost/asio/read_at.hpp b/include/boost/asio/read_at.hpp index 750c9d1f65..56d8555553 100644 --- a/include/boost/asio/read_at.hpp +++ b/include/boost/asio/read_at.hpp @@ -404,9 +404,10 @@ std::size_t read_at(SyncRandomAccessReadDevice& d, /// specified offset. /** * This function is used to asynchronously read a certain number of bytes of - * data from a random access device at the specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data from a random access device at the specified offset. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. The asynchronous operation will continue until one of the + * following conditions is true: * * @li The supplied buffers are full. That is, the bytes transferred is equal to * the sum of the buffer sizes. @@ -425,11 +426,13 @@ std::size_t read_at(SyncRandomAccessReadDevice& d, * of the buffer sizes indicates the maximum number of bytes to read from the * device. Although the buffers object may be copied as necessary, ownership of * the underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -440,8 +443,8 @@ std::size_t read_at(SyncRandomAccessReadDevice& d, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -475,14 +478,14 @@ std::size_t read_at(SyncRandomAccessReadDevice& d, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncRandomAccessReadDevice::executor_type)); @@ -490,9 +493,10 @@ async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, /// specified offset. /** * This function is used to asynchronously read a certain number of bytes of - * data from a random access device at the specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data from a random access device at the specified offset. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. The asynchronous operation will continue until one of the + * following conditions is true: * * @li The supplied buffers are full. That is, the bytes transferred is equal to * the sum of the buffer sizes. @@ -508,7 +512,7 @@ async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, * of the buffer sizes indicates the maximum number of bytes to read from the * device. Although the buffers object may be copied as necessary, ownership of * the underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param completion_condition The function object to be called to determine * whether the read operation is complete. The signature of the function object @@ -524,9 +528,11 @@ async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, * return value indicates the maximum number of bytes to be read on the next * call to the device's async_read_some_at function. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -537,8 +543,8 @@ async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -568,15 +574,15 @@ async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, const MutableBufferSequence& buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncRandomAccessReadDevice::executor_type)); @@ -587,9 +593,10 @@ async_read_at(AsyncRandomAccessReadDevice& d, /// specified offset. /** * This function is used to asynchronously read a certain number of bytes of - * data from a random access device at the specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data from a random access device at the specified offset. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. The asynchronous operation will continue until one of the + * following conditions is true: * * @li An error occurred. * @@ -603,11 +610,13 @@ async_read_at(AsyncRandomAccessReadDevice& d, * * @param b A basic_streambuf object into which the data will be read. Ownership * of the streambuf is retained by the caller, which must guarantee that it - * remains valid until the handler is called. + * remains valid until the completion 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 function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -618,8 +627,8 @@ async_read_at(AsyncRandomAccessReadDevice& d, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -644,14 +653,14 @@ async_read_at(AsyncRandomAccessReadDevice& d, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, basic_streambuf& b, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncRandomAccessReadDevice::executor_type)); @@ -659,9 +668,10 @@ async_read_at(AsyncRandomAccessReadDevice& d, /// specified offset. /** * This function is used to asynchronously read a certain number of bytes of - * data from a random access device at the specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data from a random access device at the specified offset. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. The asynchronous operation will continue until one of the + * following conditions is true: * * @li The completion_condition function object returns 0. * @@ -675,7 +685,7 @@ async_read_at(AsyncRandomAccessReadDevice& d, * * @param b A basic_streambuf object into which the data will be read. Ownership * of the streambuf is retained by the caller, which must guarantee that it - * remains valid until the handler is called. + * remains valid until the completion handler is called. * * @param completion_condition The function object to be called to determine * whether the read operation is complete. The signature of the function object @@ -691,9 +701,11 @@ async_read_at(AsyncRandomAccessReadDevice& d, * return value indicates the maximum number of bytes to be read on the next * call to the device's async_read_some_at function. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -704,8 +716,8 @@ async_read_at(AsyncRandomAccessReadDevice& d, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -725,15 +737,15 @@ async_read_at(AsyncRandomAccessReadDevice& d, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, basic_streambuf& b, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncRandomAccessReadDevice::executor_type)); diff --git a/include/boost/asio/read_until.hpp b/include/boost/asio/read_until.hpp index bb0b077f39..ca5e1babde 100644 --- a/include/boost/asio/read_until.hpp +++ b/include/boost/asio/read_until.hpp @@ -1546,9 +1546,9 @@ std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers, /** * This function is used to asynchronously read data into the specified dynamic * buffer sequence until the dynamic buffer sequence's get area contains the - * specified delimiter. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * specified delimiter. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The get area of the dynamic buffer sequence contains the specified * delimiter. @@ -1569,25 +1569,26 @@ std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers, * @param buffers The dynamic buffer sequence into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param delim The delimiter character. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, * * // The number of bytes in the dynamic buffer sequence's * // get area up to and including the delimiter. - * // 0 if an error occurred. * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1639,14 +1640,14 @@ std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, char delim, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< @@ -1661,9 +1662,9 @@ async_read_until(AsyncReadStream& s, /** * This function is used to asynchronously read data into the specified dynamic * buffer sequence until the dynamic buffer sequence's get area contains the - * specified delimiter. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * specified delimiter. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The get area of the dynamic buffer sequence contains the specified * delimiter. @@ -1684,25 +1685,26 @@ async_read_until(AsyncReadStream& s, * @param buffers The dynamic buffer sequence into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param delim The delimiter string. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, * * // The number of bytes in the dynamic buffer sequence's * // get area up to and including the delimiter. - * // 0 if an error occurred. * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1754,15 +1756,15 @@ async_read_until(AsyncReadStream& s, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, BOOST_ASIO_STRING_VIEW_PARAM delim, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< @@ -1781,9 +1783,10 @@ async_read_until(AsyncReadStream& s, /** * This function is used to asynchronously read data into the specified dynamic * buffer sequence until the dynamic buffer sequence's get area contains some - * data that matches a regular expression. The function call always returns - * immediately. The asynchronous operation will continue until one of the - * following conditions is true: + * data that matches a regular expression. It is an initiating function for an + * @ref asynchronous_operation, and always returns immediately. The + * asynchronous operation will continue until one of the following conditions + * is true: * * @li A substring of the dynamic buffer sequence's get area matches the regular * expression. @@ -1805,13 +1808,15 @@ async_read_until(AsyncReadStream& s, * @param buffers The dynamic buffer sequence into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param expr The regular expression. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -1823,8 +1828,8 @@ async_read_until(AsyncReadStream& s, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1877,15 +1882,15 @@ async_read_until(AsyncReadStream& s, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, const boost::regex& expr, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< @@ -1904,9 +1909,9 @@ async_read_until(AsyncReadStream& s, * This function is used to asynchronously read data into the specified dynamic * buffer sequence until a user-defined match condition function object, when * applied to the data contained in the dynamic buffer sequence, indicates a - * successful match. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * successful match. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The match condition function object returns a std::pair where the second * element evaluates to true. @@ -1927,7 +1932,7 @@ async_read_until(AsyncReadStream& s, * @param buffers The dynamic buffer sequence into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param match_condition The function object to be called to determine whether * a match exists. The signature of the function object must be: @@ -1944,9 +1949,11 @@ async_read_until(AsyncReadStream& s, * @c second member of the return value is true if a match has been found, false * otherwise. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -1957,8 +1964,8 @@ async_read_until(AsyncReadStream& s, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @note After a successful async_read_until operation, the dynamic buffer @@ -2043,15 +2050,15 @@ async_read_until(AsyncReadStream& s, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, MatchCondition match_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< @@ -2071,8 +2078,9 @@ async_read_until(AsyncReadStream& s, /** * This function is used to asynchronously read data into the specified * streambuf until the streambuf's get area contains the specified delimiter. - * The function call always returns immediately. The asynchronous operation - * will continue until one of the following conditions is true: + * It is an initiating function for an @ref asynchronous_operation, and always + * returns immediately. The asynchronous operation will continue until one of + * the following conditions is true: * * @li The get area of the streambuf contains the specified delimiter. * @@ -2091,13 +2099,15 @@ async_read_until(AsyncReadStream& s, * * @param b A streambuf object into which the data will be read. Ownership of * the streambuf is retained by the caller, which must guarantee that it remains - * valid until the handler is called. + * valid until the completion handler is called. * * @param delim The delimiter character. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -2108,8 +2118,8 @@ async_read_until(AsyncReadStream& s, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -2160,14 +2170,14 @@ async_read_until(AsyncReadStream& s, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, boost::asio::basic_streambuf& b, char delim, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type)); @@ -2176,8 +2186,9 @@ async_read_until(AsyncReadStream& s, /** * This function is used to asynchronously read data into the specified * streambuf until the streambuf's get area contains the specified delimiter. - * The function call always returns immediately. The asynchronous operation - * will continue until one of the following conditions is true: + * It is an initiating function for an @ref asynchronous_operation, and always + * returns immediately. The asynchronous operation will continue until one of + * the following conditions is true: * * @li The get area of the streambuf contains the specified delimiter. * @@ -2196,13 +2207,15 @@ async_read_until(AsyncReadStream& s, * * @param b A streambuf object into which the data will be read. Ownership of * the streambuf is retained by the caller, which must guarantee that it remains - * valid until the handler is called. + * valid until the completion handler is called. * * @param delim The delimiter string. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -2213,8 +2226,8 @@ async_read_until(AsyncReadStream& s, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -2265,15 +2278,15 @@ async_read_until(AsyncReadStream& s, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, boost::asio::basic_streambuf& b, BOOST_ASIO_STRING_VIEW_PARAM delim, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type)); @@ -2285,9 +2298,9 @@ async_read_until(AsyncReadStream& s, /** * This function is used to asynchronously read data into the specified * streambuf until the streambuf's get area contains some data that matches a - * regular expression. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * regular expression. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li A substring of the streambuf's get area matches the regular expression. * @@ -2307,13 +2320,15 @@ async_read_until(AsyncReadStream& s, * * @param b A streambuf object into which the data will be read. Ownership of * the streambuf is retained by the caller, which must guarantee that it remains - * valid until the handler is called. + * valid until the completion handler is called. * * @param expr The regular expression. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -2325,8 +2340,8 @@ async_read_until(AsyncReadStream& s, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -2378,14 +2393,14 @@ async_read_until(AsyncReadStream& s, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, boost::asio::basic_streambuf& b, const boost::regex& expr, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type)); @@ -2397,9 +2412,10 @@ async_read_until(AsyncReadStream& s, /** * This function is used to asynchronously read data into the specified * streambuf until a user-defined match condition function object, when applied - * to the data contained in the streambuf, indicates a successful match. The - * function call always returns immediately. The asynchronous operation will - * continue until one of the following conditions is true: + * to the data contained in the streambuf, indicates a successful match. It is + * an initiating function for an @ref asynchronous_operation, and always + * returns immediately. The asynchronous operation will continue until one of + * the following conditions is true: * * @li The match condition function object returns a std::pair where the second * element evaluates to true. @@ -2434,9 +2450,11 @@ async_read_until(AsyncReadStream& s, * @c second member of the return value is true if a match has been found, false * otherwise. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -2447,8 +2465,8 @@ async_read_until(AsyncReadStream& s, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @note After a successful async_read_until operation, the streambuf may @@ -2531,15 +2549,15 @@ async_read_until(AsyncReadStream& s, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, boost::asio::basic_streambuf& b, MatchCondition match_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint::value>::type = 0); @@ -2553,9 +2571,9 @@ async_read_until(AsyncReadStream& s, /** * This function is used to asynchronously read data into the specified dynamic * buffer sequence until the dynamic buffer sequence's get area contains the - * specified delimiter. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * specified delimiter. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The get area of the dynamic buffer sequence contains the specified * delimiter. @@ -2576,13 +2594,15 @@ async_read_until(AsyncReadStream& s, * @param buffers The dynamic buffer sequence into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param delim The delimiter character. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -2593,8 +2613,8 @@ async_read_until(AsyncReadStream& s, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -2646,13 +2666,13 @@ async_read_until(AsyncReadStream& s, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, char delim, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< @@ -2664,9 +2684,9 @@ async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, char delim, /** * This function is used to asynchronously read data into the specified dynamic * buffer sequence until the dynamic buffer sequence's get area contains the - * specified delimiter. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * specified delimiter. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The get area of the dynamic buffer sequence contains the specified * delimiter. @@ -2687,25 +2707,26 @@ async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, char delim, * @param buffers The dynamic buffer sequence into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param delim The delimiter string. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, * * // The number of bytes in the dynamic buffer sequence's * // get area up to and including the delimiter. - * // 0 if an error occurred. * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -2757,14 +2778,14 @@ async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, char delim, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, BOOST_ASIO_STRING_VIEW_PARAM delim, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< @@ -2780,9 +2801,10 @@ async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, /** * This function is used to asynchronously read data into the specified dynamic * buffer sequence until the dynamic buffer sequence's get area contains some - * data that matches a regular expression. The function call always returns - * immediately. The asynchronous operation will continue until one of the - * following conditions is true: + * data that matches a regular expression. It is an initiating function for an + * @ref asynchronous_operation, and always returns immediately. The + * asynchronous operation will continue until one of the following conditions + * is true: * * @li A substring of the dynamic buffer sequence's get area matches the regular * expression. @@ -2804,13 +2826,15 @@ async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, * @param buffers The dynamic buffer sequence into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param expr The regular expression. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -2822,8 +2846,8 @@ async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -2876,14 +2900,14 @@ async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, const boost::regex& expr, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< @@ -2899,9 +2923,9 @@ async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, * This function is used to asynchronously read data into the specified dynamic * buffer sequence until a user-defined match condition function object, when * applied to the data contained in the dynamic buffer sequence, indicates a - * successful match. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * successful match. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li The match condition function object returns a std::pair where the second * element evaluates to true. @@ -2922,7 +2946,7 @@ async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, * @param buffers The dynamic buffer sequence into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param match_condition The function object to be called to determine whether * a match exists. The signature of the function object must be: @@ -2939,9 +2963,11 @@ async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, * @c second member of the return value is true if a match has been found, false * otherwise. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -2952,8 +2978,8 @@ async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @note After a successful async_read_until operation, the dynamic buffer @@ -3038,14 +3064,14 @@ async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, MatchCondition match_condition, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncReadStream::executor_type), typename constraint< diff --git a/include/boost/asio/spawn.hpp b/include/boost/asio/spawn.hpp index 60cf33e397..43ad24a4f3 100644 --- a/include/boost/asio/spawn.hpp +++ b/include/boost/asio/spawn.hpp @@ -31,11 +31,12 @@ namespace boost { namespace asio { -/// Context object the represents the currently executing coroutine. +/// A completion token that represents the currently executing coroutine. /** - * The basic_yield_context class is used to represent the currently executing - * stackful coroutine. A basic_yield_context may be passed as a handler to an - * asynchronous operation. For example: + * The basic_yield_context class is a completion token type that is used to + * represent the currently executing stackful coroutine. A basic_yield_context + * object may be passed as a completion token to an asynchronous operation. For + * example: * * @code template * void my_coroutine(basic_yield_context yield) diff --git a/include/boost/asio/ssl/stream.hpp b/include/boost/asio/ssl/stream.hpp index 899e50e3c3..b82da1cd03 100644 --- a/include/boost/asio/ssl/stream.hpp +++ b/include/boost/asio/ssl/stream.hpp @@ -475,17 +475,24 @@ class stream : /// Start an asynchronous SSL handshake. /** * This function is used to asynchronously perform an SSL handshake on the - * stream. This function call always returns immediately. + * stream. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param type The type of handshaking to be performed, i.e. as a client or as * a server. * - * @param handler The handler to be called when the handshake operation - * completes. Copies will be made of the handler as required. The equivalent - * function signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the handshake completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error // Result of operation. * ); @endcode + * Regardless of whether the asynchronous operation completes immediately or + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using boost::asio::post(). * * @par Completion Signature * @code void(boost::system::error_code) @endcode @@ -503,23 +510,24 @@ class stream : */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code)) - HandshakeHandler + HandshakeToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(HandshakeHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(HandshakeToken, void (boost::system::error_code)) async_handshake(handshake_type type, - BOOST_ASIO_MOVE_ARG(HandshakeHandler) handler + BOOST_ASIO_MOVE_ARG(HandshakeToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_handshake(this), handler, type); + initiate_async_handshake(this), token, type); } /// Start an asynchronous SSL handshake. /** * This function is used to asynchronously perform an SSL handshake on the - * stream. This function call always returns immediately. + * stream. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param type The type of handshaking to be performed, i.e. as a client or as * a server. @@ -527,15 +535,21 @@ class stream : * @param buffers The buffered data to be reused for the handshake. Although * the 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. + * valid until the completion handler is called. * - * @param handler The handler to be called when the handshake operation - * completes. Copies will be made of the handler as required. The equivalent - * function signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the handshake completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. * std::size_t bytes_transferred // Amount of buffers used in handshake. * ); @endcode + * Regardless of whether the asynchronous operation completes immediately or + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using boost::asio::post(). * * @par Completion Signature * @code void(boost::system::error_code, std::size_t) @endcode @@ -553,17 +567,17 @@ class stream : */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(BufferedHandshakeHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(BufferedHandshakeToken, void (boost::system::error_code, std::size_t)) async_handshake(handshake_type type, const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(BufferedHandshakeHandler) handler + BOOST_ASIO_MOVE_ARG(BufferedHandshakeToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_buffered_handshake(this), handler, type, buffers); + initiate_async_buffered_handshake(this), token, type, buffers); } /// Shut down SSL on the stream. @@ -595,15 +609,22 @@ class stream : /// Asynchronously shut down SSL on the stream. /** - * This function is used to asynchronously shut down SSL on the stream. This - * function call always returns immediately. - * - * @param handler The handler to be called when the handshake operation - * completes. Copies will be made of the handler as required. The equivalent - * function signature of the handler must be: + * This function is used to asynchronously shut down SSL on the stream. It is + * an initiating function for an @ref asynchronous_operation, and always + * returns immediately. + * + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the shutdown completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error // Result of operation. * ); @endcode + * Regardless of whether the asynchronous operation completes immediately or + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using boost::asio::post(). * * @par Completion Signature * @code void(boost::system::error_code) @endcode @@ -621,17 +642,17 @@ class stream : */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code)) - ShutdownHandler + ShutdownToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ShutdownHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ShutdownToken, void (boost::system::error_code)) async_shutdown( - BOOST_ASIO_MOVE_ARG(ShutdownHandler) handler + BOOST_ASIO_MOVE_ARG(ShutdownToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_shutdown(this), handler); + initiate_async_shutdown(this), token); } /// Write some data to the stream. @@ -686,20 +707,27 @@ class stream : /// Start an asynchronous write. /** * This function is used to asynchronously write one or more bytes of data to - * the stream. The function call always returns immediately. + * the stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param buffers The data to be written to the stream. Although the 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. + * the completion 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 token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes written. + * std::size_t bytes_transferred // Number of bytes written. * ); @endcode + * Regardless of whether the asynchronous operation completes immediately or + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using boost::asio::post(). * * @par Completion Signature * @code void(boost::system::error_code, std::size_t) @endcode @@ -722,17 +750,17 @@ class stream : */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_some(const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_write_some(this), handler, buffers); + initiate_async_write_some(this), token, buffers); } /// Read some data from the stream. @@ -787,20 +815,27 @@ class stream : /// Start an asynchronous read. /** * This function is used to asynchronously read one or more bytes of data from - * the stream. The function call always returns immediately. + * the stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * * @param buffers The buffers into which the data will be read. Although the * 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. + * valid until the completion 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 token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes read. + * std::size_t bytes_transferred // Number of bytes read. * ); @endcode + * Regardless of whether the asynchronous operation completes immediately or + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using boost::asio::post(). * * @par Completion Signature * @code void(boost::system::error_code, std::size_t) @endcode @@ -823,17 +858,17 @@ class stream : */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_some(const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_read_some(this), handler, buffers); + initiate_async_read_some(this), token, buffers); } private: diff --git a/include/boost/asio/use_future.hpp b/include/boost/asio/use_future.hpp index 3e802f7bdc..a8d9a96f4c 100644 --- a/include/boost/asio/use_future.hpp +++ b/include/boost/asio/use_future.hpp @@ -38,12 +38,14 @@ class packaged_handler; } // namespace detail -/// Class used to specify that an asynchronous operation should return a future. +/// A completion token type that causes an asynchronous operation to return a +/// future. /** - * The use_future_t class is used to indicate that an asynchronous operation - * should return a std::future object. A use_future_t object may be passed as a - * handler to an asynchronous operation, typically using the special value @c - * boost::asio::use_future. For example: + * The use_future_t class is a completion token type that is used to indicate + * that an asynchronous operation should return a std::future object. A + * use_future_t object may be passed as a completion token to an asynchronous + * operation, typically using the special value @c boost::asio::use_future. For + * example: * * @code std::future my_future * = my_socket.async_read_some(my_buffer, boost::asio::use_future); @endcode @@ -139,7 +141,8 @@ class use_future_t std_allocator_void, Allocator>::type allocator_; }; -/// A special value, similar to std::nothrow. +/// A completion token object that causes an asynchronous operation to return a +/// future. /** * See the documentation for boost::asio::use_future_t for a usage example. */ diff --git a/include/boost/asio/windows/basic_object_handle.hpp b/include/boost/asio/windows/basic_object_handle.hpp index ce5090f95d..b5358d807e 100644 --- a/include/boost/asio/windows/basic_object_handle.hpp +++ b/include/boost/asio/windows/basic_object_handle.hpp @@ -358,17 +358,20 @@ class basic_object_handle /// Start an asynchronous wait on the object handle. /** * This function is be used to initiate an asynchronous wait against the - * object handle. It always returns immediately. + * object handle. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. * - * @param handler The handler to be called when the object handle is set to - * the signalled state. Copies will be made of the handler as required. The - * function signature of the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the wait completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -376,15 +379,15 @@ class basic_object_handle */ template < BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code)) - WaitHandler BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WaitHandler, + WaitToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)> + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WaitToken, void (boost::system::error_code)) async_wait( - BOOST_ASIO_MOVE_ARG(WaitHandler) handler + BOOST_ASIO_MOVE_ARG(WaitToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_wait(this), handler); + return async_initiate( + initiate_async_wait(this), token); } private: diff --git a/include/boost/asio/windows/basic_random_access_handle.hpp b/include/boost/asio/windows/basic_random_access_handle.hpp index 4bbc7882df..991faad7fe 100644 --- a/include/boost/asio/windows/basic_random_access_handle.hpp +++ b/include/boost/asio/windows/basic_random_access_handle.hpp @@ -76,8 +76,8 @@ class basic_random_access_handle /// Construct a random-access handle without opening it. /** * This constructor creates a random-access handle without opening it. The - * handle needs to be opened or assigned before data can be sent or received - * on it. + * handle needs to be opened or assigned before data can be written to or read + * from it. * * @param context An execution context which provides the I/O executor that * the random-access handle will use, by default, to dispatch handlers for any @@ -240,25 +240,28 @@ class basic_random_access_handle /// Start an asynchronous write at the specified offset. /** * This function is used to asynchronously write data to the random-access - * handle. The function call always returns immediately. + * handle. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param offset The offset at which the data will be written. * * @param buffers One or more data buffers to be written to the handle. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes written. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -289,18 +292,18 @@ class basic_random_access_handle */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_some_at(uint64_t offset, const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_write_some_at(this), handler, offset, buffers); + initiate_async_write_some_at(this), token, offset, buffers); } /// Read some data from the handle at the specified offset. @@ -374,25 +377,28 @@ class basic_random_access_handle /// Start an asynchronous read at the specified offset. /** * This function is used to asynchronously read data from the random-access - * handle. The function call always returns immediately. + * handle. It is an initiating function for an @ref asynchronous_operation, + * and always returns immediately. * * @param offset The offset at which the data will be read. * * @param buffers One or more buffers into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes read. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -424,18 +430,18 @@ class basic_random_access_handle */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_some_at(uint64_t offset, const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_read_some_at(this), handler, offset, buffers); + initiate_async_read_some_at(this), token, offset, buffers); } private: diff --git a/include/boost/asio/windows/basic_stream_handle.hpp b/include/boost/asio/windows/basic_stream_handle.hpp index c7d88884f3..9884c22418 100644 --- a/include/boost/asio/windows/basic_stream_handle.hpp +++ b/include/boost/asio/windows/basic_stream_handle.hpp @@ -79,7 +79,8 @@ class basic_stream_handle /// Construct a stream handle without opening it. /** * This constructor creates a stream handle without opening it. The handle - * needs to be opened or assigned before data can be sent or received on it. + * needs to be opened or assigned before data can be written to or read from + * it. * * @param context An execution context which provides the I/O executor that * the stream handle will use, by default, to dispatch handlers for any @@ -235,23 +236,26 @@ class basic_stream_handle /// Start an asynchronous write. /** * This function is used to asynchronously write data to the stream handle. - * The function call always returns immediately. + * It is an initiating function for an @ref asynchronous_operation, and always + * returns immediately. * * @param buffers One or more data buffers to be written to the handle. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes written. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -282,17 +286,17 @@ class basic_stream_handle */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_some(const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_write_some(this), handler, buffers); + initiate_async_write_some(this), token, buffers); } /// Read some data from the handle. @@ -361,23 +365,26 @@ class basic_stream_handle /// Start an asynchronous read. /** * This function is used to asynchronously read data from the stream handle. - * The function call always returns immediately. + * It is an initiating function for an @ref asynchronous_operation, and always + * returns immediately. * * @param buffers One or more buffers into which the data will be read. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * const boost::system::error_code& error, // Result of operation. - * std::size_t bytes_transferred // Number of bytes read. + * 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. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -409,17 +416,17 @@ class basic_stream_handle */ template - BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, + BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken, void (boost::system::error_code, std::size_t)) async_read_some(const MutableBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(ReadHandler) handler + BOOST_ASIO_MOVE_ARG(ReadToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type)) { - return async_initiate( - initiate_async_read_some(this), handler, buffers); + initiate_async_read_some(this), token, buffers); } private: diff --git a/include/boost/asio/write.hpp b/include/boost/asio/write.hpp index b08d48c720..b19e7ce45c 100644 --- a/include/boost/asio/write.hpp +++ b/include/boost/asio/write.hpp @@ -714,9 +714,9 @@ std::size_t write(SyncWriteStream& s, DynamicBuffer_v2 buffers, /// stream. /** * This function is used to asynchronously write a certain number of bytes of - * data to a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * data to a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li All of the data in the supplied buffers has been written. That is, the * bytes transferred is equal to the sum of the buffer sizes. @@ -735,22 +735,24 @@ std::size_t write(SyncWriteStream& s, DynamicBuffer_v2 buffers, * @param buffers One or more buffers containing the data to be written. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes written from the - * // buffers. If an error occurred, - * // this will be less than the sum - * // of the buffer sizes. + * // Number of bytes written from the buffers. If an error + * // occurred, this will be less than the sum of the buffer sizes. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -778,13 +780,13 @@ std::size_t write(SyncWriteStream& s, DynamicBuffer_v2 buffers, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncWriteStream::executor_type), typename constraint< @@ -795,9 +797,9 @@ async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, /// stream. /** * This function is used to asynchronously write a certain number of bytes of - * data to a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * data to a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li All of the data in the supplied buffers has been written. That is, the * bytes transferred is equal to the sum of the buffer sizes. @@ -816,7 +818,7 @@ async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, * @param buffers One or more buffers containing the data to be written. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param completion_condition The function object to be called to determine * whether the write operation is complete. The signature of the function object @@ -832,20 +834,22 @@ async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, * non-zero return value indicates the maximum number of bytes to be written on * the next call to the stream's async_write_some function. * - * @param handler The handler to be called when the write operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes written from the - * // buffers. If an error occurred, - * // this will be less than the sum - * // of the buffer sizes. + * // Number of bytes written from the buffers. If an error + * // occurred, this will be less than the sum of the buffer sizes. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -875,12 +879,12 @@ async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler, + BOOST_ASIO_MOVE_ARG(WriteToken) token, typename constraint< is_const_buffer_sequence::value >::type = 0); @@ -891,9 +895,9 @@ async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, /// stream. /** * This function is used to asynchronously write a certain number of bytes of - * data to a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * data to a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li All of the data in the supplied dynamic buffer sequence has been written. * @@ -911,23 +915,25 @@ async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, * @param buffers The dynamic buffer sequence from which data will be written. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. Successfully written - * data is automatically consumed from the buffers. - * - * @param handler The handler to be called when the write operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * that they remain valid until the completion handler is called. Successfully + * written data is automatically consumed from the buffers. + * + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes written from the - * // buffers. If an error occurred, - * // this will be less than the sum - * // of the buffer sizes. + * // Number of bytes written from the buffers. If an error + * // occurred, this will be less than the sum of the buffer sizes. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -946,14 +952,14 @@ async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncWriteStream::executor_type), typename constraint< @@ -967,9 +973,9 @@ async_write(AsyncWriteStream& s, /// stream. /** * This function is used to asynchronously write a certain number of bytes of - * data to a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * data to a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li All of the data in the supplied dynamic buffer sequence has been written. * @@ -987,8 +993,8 @@ async_write(AsyncWriteStream& s, * @param buffers The dynamic buffer sequence from which data will be written. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. Successfully written - * data is automatically consumed from the buffers. + * that they remain valid until the completion handler is called. Successfully + * written data is automatically consumed from the buffers. * * @param completion_condition The function object to be called to determine * whether the write operation is complete. The signature of the function object @@ -1004,20 +1010,22 @@ async_write(AsyncWriteStream& s, * non-zero return value indicates the maximum number of bytes to be written on * the next call to the stream's async_write_some function. * - * @param handler The handler to be called when the write operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes written from the - * // buffers. If an error occurred, - * // this will be less than the sum - * // of the buffer sizes. + * // Number of bytes written from the buffers. If an error + * // occurred, this will be less than the sum of the buffer sizes. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1037,13 +1045,13 @@ async_write(AsyncWriteStream& s, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler, + BOOST_ASIO_MOVE_ARG(WriteToken) token, typename constraint< is_dynamic_buffer_v1::type>::value >::type = 0, @@ -1058,9 +1066,9 @@ async_write(AsyncWriteStream& s, /// stream. /** * This function is used to asynchronously write a certain number of bytes of - * data to a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * data to a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li All of the data in the supplied basic_streambuf has been written. * @@ -1077,22 +1085,24 @@ async_write(AsyncWriteStream& s, * * @param b A basic_streambuf object from which data will be written. Ownership * of the streambuf is retained by the caller, which must guarantee that it - * remains valid until the handler is called. + * remains valid until the completion 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 function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes written from the - * // buffers. If an error occurred, - * // this will be less than the sum - * // of the buffer sizes. + * // Number of bytes written from the buffers. If an error + * // occurred, this will be less than the sum of the buffer sizes. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1111,13 +1121,13 @@ async_write(AsyncWriteStream& s, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, basic_streambuf& b, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncWriteStream::executor_type)); @@ -1125,9 +1135,9 @@ async_write(AsyncWriteStream& s, basic_streambuf& b, /// stream. /** * This function is used to asynchronously write a certain number of bytes of - * data to a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * data to a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li All of the data in the supplied basic_streambuf has been written. * @@ -1144,7 +1154,7 @@ async_write(AsyncWriteStream& s, basic_streambuf& b, * * @param b A basic_streambuf object from which data will be written. Ownership * of the streambuf is retained by the caller, which must guarantee that it - * remains valid until the handler is called. + * remains valid until the completion handler is called. * * @param completion_condition The function object to be called to determine * whether the write operation is complete. The signature of the function object @@ -1160,20 +1170,22 @@ async_write(AsyncWriteStream& s, basic_streambuf& b, * non-zero return value indicates the maximum number of bytes to be written on * the next call to the stream's async_write_some function. * - * @param handler The handler to be called when the write operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes written from the - * // buffers. If an error occurred, - * // this will be less than the sum - * // of the buffer sizes. + * // Number of bytes written from the buffers. If an error + * // occurred, this will be less than the sum of the buffer sizes. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1193,12 +1205,12 @@ async_write(AsyncWriteStream& s, basic_streambuf& b, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, basic_streambuf& b, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler); + BOOST_ASIO_MOVE_ARG(WriteToken) token); #endif // !defined(BOOST_ASIO_NO_IOSTREAM) #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) @@ -1208,9 +1220,9 @@ async_write(AsyncWriteStream& s, basic_streambuf& b, /// stream. /** * This function is used to asynchronously write a certain number of bytes of - * data to a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * data to a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li All of the data in the supplied dynamic buffer sequence has been written. * @@ -1228,23 +1240,25 @@ async_write(AsyncWriteStream& s, basic_streambuf& b, * @param buffers The dynamic buffer sequence from which data will be written. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. Successfully written - * data is automatically consumed from the buffers. - * - * @param handler The handler to be called when the write operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * that they remain valid until the completion handler is called. Successfully + * written data is automatically consumed from the buffers. + * + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes written from the - * // buffers. If an error occurred, - * // this will be less than the sum - * // of the buffer sizes. + * // Number of bytes written from the buffers. If an error + * // occurred, this will be less than the sum of the buffer sizes. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1263,13 +1277,13 @@ async_write(AsyncWriteStream& s, basic_streambuf& b, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, DynamicBuffer_v2 buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncWriteStream::executor_type), typename constraint< @@ -1280,9 +1294,9 @@ async_write(AsyncWriteStream& s, DynamicBuffer_v2 buffers, /// stream. /** * This function is used to asynchronously write a certain number of bytes of - * data to a stream. The function call always returns immediately. The - * asynchronous operation will continue until one of the following conditions - * is true: + * data to a stream. It is an initiating function for an @ref + * asynchronous_operation, and always returns immediately. The asynchronous + * operation will continue until one of the following conditions is true: * * @li All of the data in the supplied dynamic buffer sequence has been written. * @@ -1300,8 +1314,8 @@ async_write(AsyncWriteStream& s, DynamicBuffer_v2 buffers, * @param buffers The dynamic buffer sequence from which data will be written. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. Successfully written - * data is automatically consumed from the buffers. + * that they remain valid until the completion handler is called. Successfully + * written data is automatically consumed from the buffers. * * @param completion_condition The function object to be called to determine * whether the write operation is complete. The signature of the function object @@ -1317,20 +1331,22 @@ async_write(AsyncWriteStream& s, DynamicBuffer_v2 buffers, * non-zero return value indicates the maximum number of bytes to be written on * the next call to the stream's async_write_some function. * - * @param handler The handler to be called when the write operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( - * const boost::system::error_code& error, // Result of operation. + * // Result of operation. + * const boost::system::error_code& error, * - * std::size_t bytes_transferred // Number of bytes written from the - * // buffers. If an error occurred, - * // this will be less than the sum - * // of the buffer sizes. + * // Number of bytes written from the buffers. If an error + * // occurred, this will be less than the sum of the buffer sizes. + * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -1350,12 +1366,12 @@ async_write(AsyncWriteStream& s, DynamicBuffer_v2 buffers, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, + std::size_t)) WriteToken> +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write(AsyncWriteStream& s, DynamicBuffer_v2 buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler, + BOOST_ASIO_MOVE_ARG(WriteToken) token, typename constraint< is_dynamic_buffer_v2::value >::type = 0); diff --git a/include/boost/asio/write_at.hpp b/include/boost/asio/write_at.hpp index d0e549bf58..71ac505673 100644 --- a/include/boost/asio/write_at.hpp +++ b/include/boost/asio/write_at.hpp @@ -404,9 +404,10 @@ std::size_t write_at(SyncRandomAccessWriteDevice& d, uint64_t offset, /// specified offset. /** * This function is used to asynchronously write a certain number of bytes of - * data to a random access device at a specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data to a random access device at a specified offset. It is an initiating + * function for an @ref asynchronous_operation, and always returns immediately. + * The asynchronous operation will continue until one of the following + * conditions is true: * * @li All of the data in the supplied buffers has been written. That is, the * bytes transferred is equal to the sum of the buffer sizes. @@ -429,11 +430,13 @@ std::size_t write_at(SyncRandomAccessWriteDevice& d, uint64_t offset, * @param buffers One or more buffers containing the data to be written. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion 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 function signature of - * the handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -443,8 +446,8 @@ std::size_t write_at(SyncRandomAccessWriteDevice& d, uint64_t offset, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -472,14 +475,14 @@ std::size_t write_at(SyncRandomAccessWriteDevice& d, uint64_t offset, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, const ConstBufferSequence& buffers, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncRandomAccessWriteDevice::executor_type)); @@ -487,9 +490,10 @@ async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, /// specified offset. /** * This function is used to asynchronously write a certain number of bytes of - * data to a random access device at a specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data to a random access device at a specified offset. It is an initiating + * function for an @ref asynchronous_operation, and always returns immediately. + * The asynchronous operation will continue until one of the following + * conditions is true: * * @li All of the data in the supplied buffers has been written. That is, the * bytes transferred is equal to the sum of the buffer sizes. @@ -512,7 +516,7 @@ async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, * @param buffers One or more buffers containing the data to be written. * Although the buffers object may be copied as necessary, ownership of the * underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param completion_condition The function object to be called to determine * whether the write operation is complete. The signature of the function object @@ -528,9 +532,11 @@ async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, * non-zero return value indicates the maximum number of bytes to be written on * the next call to the device's async_write_some_at function. * - * @param handler The handler to be called when the write operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -540,8 +546,8 @@ async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -571,15 +577,15 @@ async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, const ConstBufferSequence& buffers, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncRandomAccessWriteDevice::executor_type)); @@ -590,9 +596,10 @@ async_write_at(AsyncRandomAccessWriteDevice& d, /// specified offset. /** * This function is used to asynchronously write a certain number of bytes of - * data to a random access device at a specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data to a random access device at a specified offset. It is an initiating + * function for an @ref asynchronous_operation, and always returns immediately. + * The asynchronous operation will continue until one of the following + * conditions is true: * * @li All of the data in the supplied basic_streambuf has been written. * @@ -613,11 +620,13 @@ async_write_at(AsyncRandomAccessWriteDevice& d, * * @param b A basic_streambuf object from which data will be written. Ownership * of the streambuf is retained by the caller, which must guarantee that it - * remains valid until the handler is called. + * remains valid until the completion 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 function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -627,8 +636,8 @@ async_write_at(AsyncRandomAccessWriteDevice& d, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -647,14 +656,14 @@ async_write_at(AsyncRandomAccessWriteDevice& d, */ template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, basic_streambuf& b, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncRandomAccessWriteDevice::executor_type)); @@ -662,9 +671,10 @@ async_write_at(AsyncRandomAccessWriteDevice& d, /// specified offset. /** * This function is used to asynchronously write a certain number of bytes of - * data to a random access device at a specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data to a random access device at a specified offset. It is an initiating + * function for an @ref asynchronous_operation, and always returns immediately. + * The asynchronous operation will continue until one of the following + * conditions is true: * * @li All of the data in the supplied basic_streambuf has been written. * @@ -685,7 +695,7 @@ async_write_at(AsyncRandomAccessWriteDevice& d, * * @param b A basic_streambuf object from which data will be written. Ownership * of the streambuf is retained by the caller, which must guarantee that it - * remains valid until the handler is called. + * remains valid until the completion handler is called. * * @param completion_condition The function object to be called to determine * whether the write operation is complete. The signature of the function object @@ -701,9 +711,11 @@ async_write_at(AsyncRandomAccessWriteDevice& d, * non-zero return value indicates the maximum number of bytes to be written on * the next call to the device's async_write_some_at function. * - * @param handler The handler to be called when the write operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the write completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const boost::system::error_code& error, @@ -713,8 +725,8 @@ async_write_at(AsyncRandomAccessWriteDevice& d, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. On - * immediate completion, invocation of the handler will be performed in a + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a * manner equivalent to using boost::asio::post(). * * @par Completion Signature @@ -734,14 +746,14 @@ async_write_at(AsyncRandomAccessWriteDevice& d, template -BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler, +BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken, void (boost::system::error_code, std::size_t)) async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, basic_streambuf& b, CompletionCondition completion_condition, - BOOST_ASIO_MOVE_ARG(WriteHandler) handler + BOOST_ASIO_MOVE_ARG(WriteToken) token BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( typename AsyncRandomAccessWriteDevice::executor_type));