diff --git a/boost/include/boost/any.hpp b/boost/include/boost/any.hpp index a4e598f4e..9d2e92141 100644 --- a/boost/include/boost/any.hpp +++ b/boost/include/boost/any.hpp @@ -335,7 +335,7 @@ namespace boost } // Copyright Kevlin Henney, 2000, 2001, 2002. All rights reserved. -// Copyright Antony Polukhin, 2013-2021. +// Copyright Antony Polukhin, 2013-2022. // // Distributed under the Boost Software License, Version 1.0. (See // accompanying file LICENSE_1_0.txt or copy at diff --git a/boost/include/boost/any/bad_any_cast.hpp b/boost/include/boost/any/bad_any_cast.hpp index f33e1ed85..bba142da5 100644 --- a/boost/include/boost/any/bad_any_cast.hpp +++ b/boost/include/boost/any/bad_any_cast.hpp @@ -1,4 +1,4 @@ -// Copyright Antony Polukhin, 2020-2021. +// Copyright Antony Polukhin, 2020-2022. // // Distributed under the Boost Software License, Version 1.0. (See // accompanying file LICENSE_1_0.txt or copy at diff --git a/boost/include/boost/any/basic_any.hpp b/boost/include/boost/any/basic_any.hpp index d5a77ef61..980abed19 100644 --- a/boost/include/boost/any/basic_any.hpp +++ b/boost/include/boost/any/basic_any.hpp @@ -1,5 +1,5 @@ // Copyright Ruslan Arutyunyan, 2019-2021. -// Copyright Antony Polukhin, 2021. +// Copyright Antony Polukhin, 2021-2022. // // Distributed under the Boost Software License, Version 1.0. (See // accompanying file LICENSE_1_0.txt or copy at diff --git a/boost/include/boost/any/fwd.hpp b/boost/include/boost/any/fwd.hpp index 78846d64b..6905b2644 100644 --- a/boost/include/boost/any/fwd.hpp +++ b/boost/include/boost/any/fwd.hpp @@ -1,4 +1,4 @@ -// Copyright Antony Polukhin, 2021. +// Copyright Antony Polukhin, 2021-2022. // // Distributed under the Boost Software License, Version 1.0. (See // accompanying file LICENSE_1_0.txt or copy at diff --git a/boost/include/boost/any/unique_any.hpp b/boost/include/boost/any/unique_any.hpp new file mode 100644 index 000000000..a56dd6c8c --- /dev/null +++ b/boost/include/boost/any/unique_any.hpp @@ -0,0 +1,283 @@ +// Copyright Antony Polukhin, 2020-2022. +// +// 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) + +// See http://www.boost.org/libs/any for Documentation. + +#ifndef BOOST_ANYS_UNIQUE_ANY_HPP_INCLUDED +#define BOOST_ANYS_UNIQUE_ANY_HPP_INCLUDED + +#include +#ifdef BOOST_HAS_PRAGMA_ONCE +# pragma once +#endif + +#ifdef BOOST_NO_CXX11_RVALUE_REFERENCES +#error Header requires C++11 compatible compiler with move semantics +#endif + +#ifdef BOOST_NO_CXX11_DEFAULTED_FUNCTIONS +#error Header requires C++11 compatible compiler with defaulted functions +#endif + +#ifdef BOOST_NO_CXX11_SMART_PTR +#error Header requires C++11 compatible standard library with std::unique_ptr +#endif +#include + +#ifdef BOOST_NO_CXX11_HDR_INITIALIZER_LIST +#include +#endif + +#include + +#include + +#include +#include + +namespace boost { namespace anys { + +template +struct in_place_type_t +{ +}; + +#if !defined(BOOST_NO_CXX14_VARIABLE_TEMPLATES) +template +constexpr in_place_type_t in_place_type{}; +#endif + +class unique_any { +public: + + BOOST_CONSTEXPR unique_any() BOOST_NOEXCEPT = default; + + unique_any(unique_any&& other) BOOST_NOEXCEPT = default; + + // Perfect forwarding of T + template + unique_any(T&& value + , typename boost::disable_if >::type* = 0 // disable if value has type `unique_any&` + , typename boost::disable_if >::type* = 0) // disable if value has type `const T&&` + : content(new holder< typename boost::decay::type >(std::forward(value))) + { + } + + template + explicit unique_any(in_place_type_t, Args&&... args) + : content(new holder::type>(std::forward(args)...)) + { + } + +#ifdef BOOST_NO_CXX11_HDR_INITIALIZER_LIST + template + explicit unique_any(in_place_type_t, std::initializer_list il, Args&&... args) + : content(new holder::type>(il, std::forward(args)...)) + { + } +#endif + + ~unique_any() BOOST_NOEXCEPT = default; + + unique_any & operator=(unique_any&& rhs) BOOST_NOEXCEPT = default; + + template + unique_any & operator=(T&& rhs) + { + unique_any(std::forward(rhs)).swap(*this); + return *this; + } + + template + typename boost::decay::type& emplace(Args&&... args) { + content = std::unique_ptr( + new holder::type>(std::forward(args)...) + ); + } + +#ifdef BOOST_NO_CXX11_HDR_INITIALIZER_LIST + template + typename boost::decay::type& emplace(initializer_list il, Args&&... args) { + content = std::unique_ptr( + new holder::type>(il, std::forward(args)...) + ); + } +#endif + + void reset() BOOST_NOEXCEPT + { + content.reset(); + } + + unique_any& swap(unique_any& rhs) BOOST_NOEXCEPT + { + content.swap(rhs.content); + return *this; + } + + + bool has_value() const BOOST_NOEXCEPT + { + return !content; + } + + const boost::typeindex::type_info& type() const BOOST_NOEXCEPT + { + return content ? content->type() : boost::typeindex::type_id().type_info(); + } + +private: // types + class BOOST_SYMBOL_VISIBLE placeholder + { + virtual ~placeholder() + { + } + + virtual const boost::typeindex::type_info& type() const BOOST_NOEXCEPT = 0; + + }; + + template + class holder BOOST_FINAL: public placeholder + { + public: // structors + + template + holder(Args&&... args) + : held(std::forward(args)...) + { + } + +#ifdef BOOST_NO_CXX11_HDR_INITIALIZER_LIST + template + holder(std::initializer_list il, Args&&... args) + : held(il, std::forward(args)...) + { + } +#endif + + const boost::typeindex::type_info& type() const BOOST_NOEXCEPT BOOST_OVERRIDE + { + return boost::typeindex::type_id().type_info(); + } + + public: // representation + + T held; + }; + + +private: // representation + + template + friend T * any_cast(unique_any *) BOOST_NOEXCEPT; + + template + friend T * unsafe_any_cast(unique_any *) BOOST_NOEXCEPT; + + std::unique_ptr content; +}; + +inline void swap(unique_any & lhs, unique_any & rhs) BOOST_NOEXCEPT +{ + lhs.swap(rhs); +} + +template +T * any_cast(unique_any * operand) BOOST_NOEXCEPT +{ + return operand && operand->type() == boost::typeindex::type_id() + ? boost::addressof( + static_cast::type>&>(*operand->content).held + ) + : 0; +} + +template +inline const T * any_cast(const unique_any * operand) BOOST_NOEXCEPT +{ + return any_cast(const_cast(operand)); +} + +template +T any_cast(unique_any & operand) +{ + typedef BOOST_DEDUCED_TYPENAME remove_reference::type nonref; + + + nonref * result = any_cast(boost::addressof(operand)); + if(!result) + boost::throw_exception(bad_any_cast()); + + // Attempt to avoid construction of a temporary object in cases when + // `T` is not a reference. Example: + // `static_cast(*result);` + // which is equal to `std::string(*result);` + typedef BOOST_DEDUCED_TYPENAME boost::conditional< + boost::is_reference::value, + T, + BOOST_DEDUCED_TYPENAME boost::add_reference::type + >::type ref_type; + +#ifdef BOOST_MSVC +# pragma warning(push) +# pragma warning(disable: 4172) // "returning address of local variable or temporary" but *result is not local! +#endif + return static_cast(*result); +#ifdef BOOST_MSVC +# pragma warning(pop) +#endif +} + +template +inline T any_cast(const unique_any & operand) +{ + typedef BOOST_DEDUCED_TYPENAME remove_reference::type nonref; + return any_cast(const_cast(operand)); +} + +#ifndef BOOST_NO_CXX11_RVALUE_REFERENCES +template +inline T any_cast(unique_any&& operand) +{ + BOOST_STATIC_ASSERT_MSG( + boost::is_rvalue_reference::value /*true if T is rvalue or just a value*/ + || boost::is_const< typename boost::remove_reference::type >::value, + "boost::any_cast shall not be used for getting nonconst references to temporary objects" + ); + return any_cast(operand); +} +#endif + + +// Note: The "unsafe" versions of any_cast are not part of the +// public interface and may be removed at any time. They are +// required where we know what type is stored in the any and can't +// use typeid() comparison, e.g., when our types may travel across +// different shared libraries. +template +inline T * unsafe_any_cast(unique_any * operand) BOOST_NOEXCEPT +{ + return boost::addressof( + static_cast&>(*operand->content)->held + ); +} + +template +inline const T * unsafe_any_cast(const unique_any * operand) BOOST_NOEXCEPT +{ + return unsafe_any_cast(const_cast(operand)); +} + +} // namespace anys + +using boost::anys::any_cast; +using boost::anys::unsafe_any_cast; + +} // namespace boost + + +#endif // BOOST_ANYS_UNIQUE_ANY_HPP_INCLUDED diff --git a/boost/include/boost/asio.hpp b/boost/include/boost/asio.hpp index b2e1c53f2..a1c1c378e 100644 --- a/boost/include/boost/asio.hpp +++ b/boost/include/boost/asio.hpp @@ -2,7 +2,7 @@ // asio.hpp // ~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -42,6 +42,7 @@ #include #include #include +#include #include #include #include @@ -160,6 +161,7 @@ #include #include #include +#include #include #include #include diff --git a/boost/include/boost/asio/any_io_executor.hpp b/boost/include/boost/asio/any_io_executor.hpp index 47d11e7b2..6dc8731fd 100644 --- a/boost/include/boost/asio/any_io_executor.hpp +++ b/boost/include/boost/asio/any_io_executor.hpp @@ -2,7 +2,7 @@ // any_io_executor.hpp // ~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) diff --git a/boost/include/boost/asio/associated_allocator.hpp b/boost/include/boost/asio/associated_allocator.hpp index 46b269e69..01c020269 100644 --- a/boost/include/boost/asio/associated_allocator.hpp +++ b/boost/include/boost/asio/associated_allocator.hpp @@ -2,7 +2,7 @@ // associated_allocator.hpp // ~~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -38,7 +38,7 @@ struct has_allocator_type : false_type template struct has_allocator_type::type> + typename void_type::type> : true_type { }; @@ -123,7 +123,7 @@ struct associated_allocator * @returns associated_allocator::get(t) */ template -inline typename associated_allocator::type +BOOST_ASIO_NODISCARD inline typename associated_allocator::type get_associated_allocator(const T& t) BOOST_ASIO_NOEXCEPT { return associated_allocator::get(t); @@ -134,7 +134,7 @@ get_associated_allocator(const T& t) BOOST_ASIO_NOEXCEPT * @returns associated_allocator::get(t, a) */ template -inline typename associated_allocator::type +BOOST_ASIO_NODISCARD inline typename associated_allocator::type get_associated_allocator(const T& t, const Allocator& a) BOOST_ASIO_NOEXCEPT { return associated_allocator::get(t, a); diff --git a/boost/include/boost/asio/associated_cancellation_slot.hpp b/boost/include/boost/asio/associated_cancellation_slot.hpp index ccba8d951..f3f52e733 100644 --- a/boost/include/boost/asio/associated_cancellation_slot.hpp +++ b/boost/include/boost/asio/associated_cancellation_slot.hpp @@ -2,7 +2,7 @@ // associated_cancellation_slot.hpp // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -123,7 +123,7 @@ struct associated_cancellation_slot * @returns associated_cancellation_slot::get(t) */ template -inline typename associated_cancellation_slot::type +BOOST_ASIO_NODISCARD inline typename associated_cancellation_slot::type get_associated_cancellation_slot(const T& t) BOOST_ASIO_NOEXCEPT { return associated_cancellation_slot::get(t); @@ -135,7 +135,8 @@ get_associated_cancellation_slot(const T& t) BOOST_ASIO_NOEXCEPT * CancellationSlot>::get(t, st) */ template -inline typename associated_cancellation_slot::type +BOOST_ASIO_NODISCARD inline +typename associated_cancellation_slot::type get_associated_cancellation_slot(const T& t, const CancellationSlot& st) BOOST_ASIO_NOEXCEPT { diff --git a/boost/include/boost/asio/associated_executor.hpp b/boost/include/boost/asio/associated_executor.hpp index dfd0b8f65..02738aac8 100644 --- a/boost/include/boost/asio/associated_executor.hpp +++ b/boost/include/boost/asio/associated_executor.hpp @@ -2,7 +2,7 @@ // associated_executor.hpp // ~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -125,7 +125,7 @@ struct associated_executor * @returns associated_executor::get(t) */ template -inline typename associated_executor::type +BOOST_ASIO_NODISCARD inline typename associated_executor::type get_associated_executor(const T& t) BOOST_ASIO_NOEXCEPT { return associated_executor::get(t); @@ -136,7 +136,7 @@ get_associated_executor(const T& t) BOOST_ASIO_NOEXCEPT * @returns associated_executor::get(t, ex) */ template -inline typename associated_executor::type +BOOST_ASIO_NODISCARD inline typename associated_executor::type get_associated_executor(const T& t, const Executor& ex, typename constraint< is_executor::value || execution::is_executor::value @@ -151,7 +151,7 @@ get_associated_executor(const T& t, const Executor& ex, * ExecutionContext::executor_type>::get(t, ctx.get_executor()) */ template -inline typename associated_executor::type get_associated_executor(const T& t, ExecutionContext& ctx, typename constraint #endif // defined(BOOST_ASIO_HAS_STD_COROUTINE) +#include #include #include diff --git a/boost/include/boost/asio/basic_datagram_socket.hpp b/boost/include/boost/asio/basic_datagram_socket.hpp index 3844c340a..bd4b952a3 100644 --- a/boost/include/boost/asio/basic_datagram_socket.hpp +++ b/boost/include/boost/asio/basic_datagram_socket.hpp @@ -2,7 +2,7 @@ // basic_datagram_socket.hpp // ~~~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -424,25 +424,31 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The async_send operation can only be used with a connected socket. * Use the async_send_to function to send data on an unconnected datagram * socket. @@ -468,44 +474,50 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The async_send operation can only be used with a connected socket. * Use the async_send_to function to send data on an unconnected datagram * socket. @@ -522,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. @@ -627,28 +639,34 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @par Example * To send a single data buffer use the @ref buffer function as follows: * @code @@ -673,48 +691,54 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @par Per-Operation Cancellation * On POSIX or Windows operating systems, this asynchronous operation supports * cancellation for the following boost::asio::cancellation_type values: @@ -727,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. @@ -833,25 +857,31 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The async_receive operation can only be used with a connected socket. * Use the async_receive_from function to receive data on an unconnected * datagram socket. @@ -878,44 +908,50 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The async_receive operation can only be used with a connected socket. * Use the async_receive_from function to receive data on an unconnected * datagram socket. @@ -932,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. @@ -1037,31 +1073,37 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @par Example * To receive into a single data buffer use the @ref buffer function as * follows: @@ -1083,50 +1125,56 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @par Per-Operation Cancellation * On POSIX or Windows operating systems, this asynchronous operation supports * cancellation for the following boost::asio::cancellation_type values: @@ -1139,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/boost/include/boost/asio/basic_deadline_timer.hpp b/boost/include/boost/asio/basic_deadline_timer.hpp index 4a0129469..1676dba75 100644 --- a/boost/include/boost/asio/basic_deadline_timer.hpp +++ b/boost/include/boost/asio/basic_deadline_timer.hpp @@ -2,7 +2,7 @@ // basic_deadline_timer.hpp // ~~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -608,30 +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 * @@ -641,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/boost/include/boost/asio/basic_file.hpp b/boost/include/boost/asio/basic_file.hpp index 048ce3ad3..fb862994d 100644 --- a/boost/include/boost/asio/basic_file.hpp +++ b/boost/include/boost/asio/basic_file.hpp @@ -2,7 +2,7 @@ // basic_file.hpp // ~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) diff --git a/boost/include/boost/asio/basic_io_object.hpp b/boost/include/boost/asio/basic_io_object.hpp index 97b26b12d..ff6321d49 100644 --- a/boost/include/boost/asio/basic_io_object.hpp +++ b/boost/include/boost/asio/basic_io_object.hpp @@ -2,7 +2,7 @@ // basic_io_object.hpp // ~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) diff --git a/boost/include/boost/asio/basic_random_access_file.hpp b/boost/include/boost/asio/basic_random_access_file.hpp index 09c75a7c3..248eb0aea 100644 --- a/boost/include/boost/asio/basic_random_access_file.hpp +++ b/boost/include/boost/asio/basic_random_access_file.hpp @@ -2,7 +2,7 @@ // basic_random_access_file.hpp // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -404,27 +404,33 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The write operation may not write all of the data to the file. * Consider using the @ref async_write_at function if you need to ensure that * all data is written before the asynchronous operation completes. @@ -450,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. @@ -534,27 +540,33 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The read operation may not read all of the requested number of bytes. * Consider using the @ref async_read_at function if you need to ensure that * the requested amount of data is read before the asynchronous operation @@ -581,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/boost/include/boost/asio/basic_raw_socket.hpp b/boost/include/boost/asio/basic_raw_socket.hpp index 2168c2920..e1f3a513c 100644 --- a/boost/include/boost/asio/basic_raw_socket.hpp +++ b/boost/include/boost/asio/basic_raw_socket.hpp @@ -2,7 +2,7 @@ // basic_raw_socket.hpp // ~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -415,26 +415,32 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The async_send operation can only be used with a connected socket. * Use the async_send_to function to send data on an unconnected raw * socket. @@ -460,44 +466,50 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The async_send operation can only be used with a connected socket. * Use the async_send_to function to send data on an unconnected raw * socket. @@ -514,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. @@ -619,28 +631,34 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @par Example * To send a single data buffer use the @ref buffer function as follows: * @code @@ -665,48 +683,54 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @par Per-Operation Cancellation * On POSIX or Windows operating systems, this asynchronous operation supports * cancellation for the following boost::asio::cancellation_type values: @@ -719,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. @@ -825,25 +849,31 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The async_receive operation can only be used with a connected socket. * Use the async_receive_from function to receive data on an unconnected * raw socket. @@ -870,44 +900,50 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The async_receive operation can only be used with a connected socket. * Use the async_receive_from function to receive data on an unconnected * raw socket. @@ -924,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. @@ -1029,31 +1065,37 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @par Example * To receive into a single data buffer use the @ref buffer function as * follows: @@ -1075,50 +1117,56 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @par Per-Operation Cancellation * On POSIX or Windows operating systems, this asynchronous operation supports * cancellation for the following boost::asio::cancellation_type values: @@ -1131,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/boost/include/boost/asio/basic_readable_pipe.hpp b/boost/include/boost/asio/basic_readable_pipe.hpp index ee7c69559..e69a053d1 100644 --- a/boost/include/boost/asio/basic_readable_pipe.hpp +++ b/boost/include/boost/asio/basic_readable_pipe.hpp @@ -2,7 +2,7 @@ // basic_readable_pipe.hpp // ~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -417,26 +417,32 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The read operation may not read all of the requested number of bytes. * Consider using the @ref async_read function if you need to ensure that the * requested amount of data is read before the asynchronous operation @@ -454,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/boost/include/boost/asio/basic_seq_packet_socket.hpp b/boost/include/boost/asio/basic_seq_packet_socket.hpp index b6f6ac80b..9d139be3a 100644 --- a/boost/include/boost/asio/basic_seq_packet_socket.hpp +++ b/boost/include/boost/asio/basic_seq_packet_socket.hpp @@ -2,7 +2,7 @@ // basic_seq_packet_socket.hpp // ~~~~~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -406,27 +406,33 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @par Example * To send a single data buffer use the @ref buffer function as follows: * @code @@ -448,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. @@ -584,31 +590,37 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @par Example * To receive into a single data buffer use the @ref buffer function as * follows: @@ -631,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. * @@ -662,20 +675,25 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @par Example * To receive into a single data buffer use the @ref buffer function as * follows: @@ -700,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/boost/include/boost/asio/basic_serial_port.hpp b/boost/include/boost/asio/basic_serial_port.hpp index edb3f650b..fd0d4bdf2 100644 --- a/boost/include/boost/asio/basic_serial_port.hpp +++ b/boost/include/boost/asio/basic_serial_port.hpp @@ -2,7 +2,7 @@ // basic_serial_port.hpp // ~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) // Copyright (c) 2008 Rep Invariant Systems, Inc. (info@repinvariant.com) // // Distributed under the Boost Software License, Version 1.0. (See accompanying @@ -657,25 +657,31 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The write operation may not transmit all of the data to the peer. * Consider using the @ref async_write function if you need to ensure that all * data is written before the asynchronous operation completes. @@ -689,20 +695,30 @@ class basic_serial_port * See the @ref buffer documentation for information on writing multiple * buffers in one go, and how to use it with arrays, boost::array or * std::vector. + * + * @par Per-Operation Cancellation + * On POSIX or Windows operating systems, this asynchronous operation supports + * cancellation for the following boost::asio::cancellation_type values: + * + * @li @c cancellation_type::terminal + * + * @li @c cancellation_type::partial + * + * @li @c cancellation_type::total */ 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. @@ -771,25 +787,31 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The read operation may not read all of the requested number of bytes. * Consider using the @ref async_read function if you need to ensure that the * requested amount of data is read before the asynchronous operation @@ -804,20 +826,30 @@ class basic_serial_port * See the @ref buffer documentation for information on reading into multiple * buffers in one go, and how to use it with arrays, boost::array or * std::vector. + * + * @par Per-Operation Cancellation + * On POSIX or Windows operating systems, this asynchronous operation supports + * cancellation for the following boost::asio::cancellation_type values: + * + * @li @c cancellation_type::terminal + * + * @li @c cancellation_type::partial + * + * @li @c cancellation_type::total */ 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/boost/include/boost/asio/basic_signal_set.hpp b/boost/include/boost/asio/basic_signal_set.hpp index 20b6f0c0b..1ac834839 100644 --- a/boost/include/boost/asio/basic_signal_set.hpp +++ b/boost/include/boost/asio/basic_signal_set.hpp @@ -2,7 +2,7 @@ // basic_signal_set.hpp // ~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -495,39 +495,55 @@ 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 + * @code void(boost::system::error_code, int) @endcode + * + * @par Per-Operation Cancellation + * This asynchronous operation supports cancellation for the following + * boost::asio::cancellation_type values: + * + * @li @c cancellation_type::terminal + * + * @li @c cancellation_type::partial + * + * @li @c cancellation_type::total */ 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/boost/include/boost/asio/basic_socket.hpp b/boost/include/boost/asio/basic_socket.hpp index 2d36f0df9..a718ca186 100644 --- a/boost/include/boost/asio/basic_socket.hpp +++ b/boost/include/boost/asio/basic_socket.hpp @@ -2,7 +2,7 @@ // basic_socket.hpp // ~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -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,17 +918,22 @@ 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 + * @code void(boost::system::error_code) @endcode + * * @par Example * @code * void connect_handler(const boost::system::error_code& error) @@ -958,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; @@ -972,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. @@ -1757,21 +1763,28 @@ 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 + * @code void(boost::system::error_code) @endcode + * * @par Example * @code * void wait_handler(const boost::system::error_code& error) @@ -1801,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/boost/include/boost/asio/basic_socket_acceptor.hpp b/boost/include/boost/asio/basic_socket_acceptor.hpp index 1ca766ab6..fe048266f 100644 --- a/boost/include/boost/asio/basic_socket_acceptor.hpp +++ b/boost/include/boost/asio/basic_socket_acceptor.hpp @@ -2,7 +2,7 @@ // basic_socket_acceptor.hpp // ~~~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -1197,21 +1197,28 @@ 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 + * @code void(boost::system::error_code) @endcode + * * @par Example * @code * void wait_handler(const boost::system::error_code& error) @@ -1243,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) @@ -1323,23 +1330,30 @@ 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 + * @code void(boost::system::error_code) @endcode + * * @par Example * @code * void accept_handler(const boost::system::error_code& error) @@ -1370,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)); } @@ -1458,29 +1472,35 @@ 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 + * @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: @@ -1493,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) @@ -1574,27 +1594,36 @@ 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 + * @code void(boost::system::error_code, + * typename Protocol::socket::template + * rebind_executor::other)) @endcode + * * @par Example * @code * void accept_handler(const boost::system::error_code& error, @@ -1626,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)); @@ -1809,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. @@ -1818,19 +1848,29 @@ 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 + * @code void(boost::system::error_code, + * typename Protocol::socket::template rebind_executor< + * Executor1>::other)) @endcode + * * @par Example * @code * void accept_handler(const boost::system::error_code& error, @@ -1862,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 @@ -1879,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. @@ -1897,20 +1938,29 @@ 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 + * @code void(boost::system::error_code, + * typename Protocol::socket::template rebind_executor< + * typename ExecutionContext::executor_type>::other)) @endcode + * * @par Example * @code * void accept_handler(const boost::system::error_code& error, @@ -1942,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 @@ -1958,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)); } @@ -2042,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. @@ -2051,23 +2102,31 @@ 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 + * @code void(boost::system::error_code, + * typename Protocol::socket::template + * rebind_executor::other)) @endcode + * * @par Example * @code * void accept_handler(const boost::system::error_code& error, @@ -2100,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)); @@ -2309,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. @@ -2321,21 +2381,31 @@ 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 + * @code void(boost::system::error_code, + * typename Protocol::socket::template rebind_executor< + * Executor1>::other)) @endcode + * * @par Example * @code * void accept_handler(const boost::system::error_code& error, @@ -2368,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 @@ -2385,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. @@ -2406,22 +2477,31 @@ 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 + * @code void(boost::system::error_code, + * typename Protocol::socket::template rebind_executor< + * typename ExecutionContext::executor_type>::other)) @endcode + * * @par Example * @code * void accept_handler(const boost::system::error_code& error, @@ -2454,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 @@ -2471,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/boost/include/boost/asio/basic_socket_iostream.hpp b/boost/include/boost/asio/basic_socket_iostream.hpp index 51d1103d7..3223ac77a 100644 --- a/boost/include/boost/asio/basic_socket_iostream.hpp +++ b/boost/include/boost/asio/basic_socket_iostream.hpp @@ -2,7 +2,7 @@ // basic_socket_iostream.hpp // ~~~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) diff --git a/boost/include/boost/asio/basic_socket_streambuf.hpp b/boost/include/boost/asio/basic_socket_streambuf.hpp index bd9c8d8d5..3173c01bc 100644 --- a/boost/include/boost/asio/basic_socket_streambuf.hpp +++ b/boost/include/boost/asio/basic_socket_streambuf.hpp @@ -2,7 +2,7 @@ // basic_socket_streambuf.hpp // ~~~~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) diff --git a/boost/include/boost/asio/basic_stream_file.hpp b/boost/include/boost/asio/basic_stream_file.hpp index 0cc43f50c..188981c29 100644 --- a/boost/include/boost/asio/basic_stream_file.hpp +++ b/boost/include/boost/asio/basic_stream_file.hpp @@ -2,7 +2,7 @@ // basic_stream_file.hpp // ~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -469,25 +469,31 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The write operation may not transmit all of the data to the peer. * Consider using the @ref async_write function if you need to ensure that all * data is written before the asynchronous operation completes. @@ -513,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. @@ -591,25 +597,31 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The read operation may not read all of the requested number of bytes. * Consider using the @ref async_read function if you need to ensure that the * requested amount of data is read before the asynchronous operation @@ -636,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/boost/include/boost/asio/basic_stream_socket.hpp b/boost/include/boost/asio/basic_stream_socket.hpp index 035c6ed72..676467039 100644 --- a/boost/include/boost/asio/basic_stream_socket.hpp +++ b/boost/include/boost/asio/basic_stream_socket.hpp @@ -2,7 +2,7 @@ // basic_stream_socket.hpp // ~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -439,25 +439,31 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The send operation may not transmit all of the data to the peer. * Consider using the @ref async_write function if you need to ensure that all * data is written before the asynchronous operation completes. @@ -483,44 +489,50 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The send operation may not transmit all of the data to the peer. * Consider using the @ref async_write function if you need to ensure that all * data is written before the asynchronous operation completes. @@ -546,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. @@ -668,25 +680,31 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The receive operation may not receive all of the requested number of * bytes. Consider using the @ref async_read function if you need to ensure * that the requested amount of data is received before the asynchronous @@ -714,44 +732,50 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The receive operation may not receive all of the requested number of * bytes. Consider using the @ref async_read function if you need to ensure * that the requested amount of data is received before the asynchronous @@ -779,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. @@ -857,25 +881,31 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The write operation may not transmit all of the data to the peer. * Consider using the @ref async_write function if you need to ensure that all * data is written before the asynchronous operation completes. @@ -901,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)); } @@ -981,25 +1011,31 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The read operation may not read all of the requested number of bytes. * Consider using the @ref async_read function if you need to ensure that the * requested amount of data is read before the asynchronous operation @@ -1026,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/boost/include/boost/asio/basic_streambuf.hpp b/boost/include/boost/asio/basic_streambuf.hpp index 897d13367..bfcc71e30 100644 --- a/boost/include/boost/asio/basic_streambuf.hpp +++ b/boost/include/boost/asio/basic_streambuf.hpp @@ -2,7 +2,7 @@ // basic_streambuf.hpp // ~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) diff --git a/boost/include/boost/asio/basic_streambuf_fwd.hpp b/boost/include/boost/asio/basic_streambuf_fwd.hpp index 3f88d3669..64260128f 100644 --- a/boost/include/boost/asio/basic_streambuf_fwd.hpp +++ b/boost/include/boost/asio/basic_streambuf_fwd.hpp @@ -2,7 +2,7 @@ // basic_streambuf_fwd.hpp // ~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) diff --git a/boost/include/boost/asio/basic_waitable_timer.hpp b/boost/include/boost/asio/basic_waitable_timer.hpp index 549a7817f..da68c9c1b 100644 --- a/boost/include/boost/asio/basic_waitable_timer.hpp +++ b/boost/include/boost/asio/basic_waitable_timer.hpp @@ -2,7 +2,7 @@ // basic_waitable_timer.hpp // ~~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -727,27 +727,33 @@ 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 + * @code void(boost::system::error_code) @endcode + * * @par Per-Operation Cancellation * This asynchronous operation supports cancellation for the following * boost::asio::cancellation_type values: @@ -760,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/boost/include/boost/asio/basic_writable_pipe.hpp b/boost/include/boost/asio/basic_writable_pipe.hpp index bc69834a0..b883c23d6 100644 --- a/boost/include/boost/asio/basic_writable_pipe.hpp +++ b/boost/include/boost/asio/basic_writable_pipe.hpp @@ -2,7 +2,7 @@ // basic_writable_pipe.hpp // ~~~~~~~~~~~~~~~~~~~~~~~ // -// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// 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) @@ -415,26 +415,32 @@ 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 + * @code void(boost::system::error_code, std::size_t) @endcode + * * @note The write operation may not transmit all of the data to the peer. * Consider using the @ref async_write function if you need to ensure that all * data is written before the asynchronous operation completes. @@ -450,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/boost/include/boost/asio/bind_allocator.hpp b/boost/include/boost/asio/bind_allocator.hpp new file mode 100644 index 000000000..42c0ae86c --- /dev/null +++ b/boost/include/boost/asio/bind_allocator.hpp @@ -0,0 +1,724 @@ +// +// bind_allocator.hpp +// ~~~~~~~~~~~~~~~~~~ +// +// 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) +// + +#ifndef BOOST_ASIO_BIND_ALLOCATOR_HPP +#define BOOST_ASIO_BIND_ALLOCATOR_HPP + +#if defined(_MSC_VER) && (_MSC_VER >= 1200) +# pragma once +#endif // defined(_MSC_VER) && (_MSC_VER >= 1200) + +#include +#include +#include +#include +#include +#include + +#include + +namespace boost { +namespace asio { +namespace detail { + +// Helper to automatically define nested typedef result_type. + +template +struct allocator_binder_result_type +{ +protected: + typedef void result_type_or_void; +}; + +template +struct allocator_binder_result_type::type> +{ + typedef typename T::result_type result_type; +protected: + typedef result_type result_type_or_void; +}; + +template +struct allocator_binder_result_type +{ + typedef R result_type; +protected: + typedef result_type result_type_or_void; +}; + +template +struct allocator_binder_result_type +{ + typedef R result_type; +protected: + typedef result_type result_type_or_void; +}; + +template +struct allocator_binder_result_type +{ + typedef R result_type; +protected: + typedef result_type result_type_or_void; +}; + +template +struct allocator_binder_result_type +{ + typedef R result_type; +protected: + typedef result_type result_type_or_void; +}; + +template +struct allocator_binder_result_type +{ + typedef R result_type; +protected: + typedef result_type result_type_or_void; +}; + +template +struct allocator_binder_result_type +{ + typedef R result_type; +protected: + typedef result_type result_type_or_void; +}; + +// Helper to automatically define nested typedef argument_type. + +template +struct allocator_binder_argument_type {}; + +template +struct allocator_binder_argument_type::type> +{ + typedef typename T::argument_type argument_type; +}; + +template +struct allocator_binder_argument_type +{ + typedef A1 argument_type; +}; + +template +struct allocator_binder_argument_type +{ + typedef A1 argument_type; +}; + +// Helper to automatically define nested typedefs first_argument_type and +// second_argument_type. + +template +struct allocator_binder_argument_types {}; + +template +struct allocator_binder_argument_types::type> +{ + typedef typename T::first_argument_type first_argument_type; + typedef typename T::second_argument_type second_argument_type; +}; + +template +struct allocator_binder_argument_type +{ + typedef A1 first_argument_type; + typedef A2 second_argument_type; +}; + +template +struct allocator_binder_argument_type +{ + typedef A1 first_argument_type; + typedef A2 second_argument_type; +}; + +// Helper to enable SFINAE on zero-argument operator() below. + +template +struct allocator_binder_result_of0 +{ + typedef void type; +}; + +template +struct allocator_binder_result_of0::type>::type> +{ + typedef typename result_of::type type; +}; + +} // namespace detail + +/// A call wrapper type to bind an allocator of type @c Allocator +/// to an object of type @c T. +template +class allocator_binder +#if !defined(GENERATING_DOCUMENTATION) + : public detail::allocator_binder_result_type, + public detail::allocator_binder_argument_type, + public detail::allocator_binder_argument_types +#endif // !defined(GENERATING_DOCUMENTATION) +{ +public: + /// The type of the target object. + typedef T target_type; + + /// The type of the associated allocator. + typedef Allocator allocator_type; + +#if defined(GENERATING_DOCUMENTATION) + /// The return type if a function. + /** + * The type of @c result_type is based on the type @c T of the wrapper's + * target object: + * + * @li if @c T is a pointer to function type, @c result_type is a synonym for + * the return type of @c T; + * + * @li if @c T is a class type with a member type @c result_type, then @c + * result_type is a synonym for @c T::result_type; + * + * @li otherwise @c result_type is not defined. + */ + typedef see_below result_type; + + /// The type of the function's argument. + /** + * The type of @c argument_type is based on the type @c T of the wrapper's + * target object: + * + * @li if @c T is a pointer to a function type accepting a single argument, + * @c argument_type is a synonym for the return type of @c T; + * + * @li if @c T is a class type with a member type @c argument_type, then @c + * argument_type is a synonym for @c T::argument_type; + * + * @li otherwise @c argument_type is not defined. + */ + typedef see_below argument_type; + + /// The type of the function's first argument. + /** + * The type of @c first_argument_type is based on the type @c T of the + * wrapper's target object: + * + * @li if @c T is a pointer to a function type accepting two arguments, @c + * first_argument_type is a synonym for the return type of @c T; + * + * @li if @c T is a class type with a member type @c first_argument_type, + * then @c first_argument_type is a synonym for @c T::first_argument_type; + * + * @li otherwise @c first_argument_type is not defined. + */ + typedef see_below first_argument_type; + + /// The type of the function's second argument. + /** + * The type of @c second_argument_type is based on the type @c T of the + * wrapper's target object: + * + * @li if @c T is a pointer to a function type accepting two arguments, @c + * second_argument_type is a synonym for the return type of @c T; + * + * @li if @c T is a class type with a member type @c first_argument_type, + * then @c second_argument_type is a synonym for @c T::second_argument_type; + * + * @li otherwise @c second_argument_type is not defined. + */ + typedef see_below second_argument_type; +#endif // defined(GENERATING_DOCUMENTATION) + + /// Construct an allocator wrapper for the specified object. + /** + * This constructor is only valid if the type @c T is constructible from type + * @c U. + */ + template + allocator_binder(const allocator_type& s, + BOOST_ASIO_MOVE_ARG(U) u) + : allocator_(s), + target_(BOOST_ASIO_MOVE_CAST(U)(u)) + { + } + + /// Copy constructor. + allocator_binder(const allocator_binder& other) + : allocator_(other.get_allocator()), + target_(other.get()) + { + } + + /// Construct a copy, but specify a different allocator. + allocator_binder(const allocator_type& s, + const allocator_binder& other) + : allocator_(s), + target_(other.get()) + { + } + + /// Construct a copy of a different allocator wrapper type. + /** + * This constructor is only valid if the @c Allocator type is + * constructible from type @c OtherAllocator, and the type @c T is + * constructible from type @c U. + */ + template + allocator_binder( + const allocator_binder& other) + : allocator_(other.get_allocator()), + target_(other.get()) + { + } + + /// Construct a copy of a different allocator wrapper type, but + /// specify a different allocator. + /** + * This constructor is only valid if the type @c T is constructible from type + * @c U. + */ + template + allocator_binder(const allocator_type& s, + const allocator_binder& other) + : allocator_(s), + target_(other.get()) + { + } + +#if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION) + + /// Move constructor. + allocator_binder(allocator_binder&& other) + : allocator_(BOOST_ASIO_MOVE_CAST(allocator_type)( + other.get_allocator())), + target_(BOOST_ASIO_MOVE_CAST(T)(other.get())) + { + } + + /// Move construct the target object, but specify a different allocator. + allocator_binder(const allocator_type& s, + allocator_binder&& other) + : allocator_(s), + target_(BOOST_ASIO_MOVE_CAST(T)(other.get())) + { + } + + /// Move construct from a different allocator wrapper type. + template + allocator_binder( + allocator_binder&& other) + : allocator_(BOOST_ASIO_MOVE_CAST(OtherAllocator)( + other.get_allocator())), + target_(BOOST_ASIO_MOVE_CAST(U)(other.get())) + { + } + + /// Move construct from a different allocator wrapper type, but + /// specify a different allocator. + template + allocator_binder(const allocator_type& s, + allocator_binder&& other) + : allocator_(s), + target_(BOOST_ASIO_MOVE_CAST(U)(other.get())) + { + } + +#endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION) + + /// Destructor. + ~allocator_binder() + { + } + + /// Obtain a reference to the target object. + target_type& get() BOOST_ASIO_NOEXCEPT + { + return target_; + } + + /// Obtain a reference to the target object. + const target_type& get() const BOOST_ASIO_NOEXCEPT + { + return target_; + } + + /// Obtain the associated allocator. + allocator_type get_allocator() const BOOST_ASIO_NOEXCEPT + { + return allocator_; + } + +#if defined(GENERATING_DOCUMENTATION) + + template auto operator()(Args&& ...); + template auto operator()(Args&& ...) const; + +#elif defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES) + + /// Forwarding function call operator. + template + typename result_of::type operator()( + BOOST_ASIO_MOVE_ARG(Args)... args) + { + return target_(BOOST_ASIO_MOVE_CAST(Args)(args)...); + } + + /// Forwarding function call operator. + template + typename result_of::type operator()( + BOOST_ASIO_MOVE_ARG(Args)... args) const + { + return target_(BOOST_ASIO_MOVE_CAST(Args)(args)...); + } + +#elif defined(BOOST_ASIO_HAS_STD_TYPE_TRAITS) && !defined(_MSC_VER) + + typename detail::allocator_binder_result_of0::type operator()() + { + return target_(); + } + + typename detail::allocator_binder_result_of0::type + operator()() const + { + return target_(); + } + +#define BOOST_ASIO_PRIVATE_BINDER_CALL_DEF(n) \ + template \ + typename result_of::type operator()( \ + BOOST_ASIO_VARIADIC_MOVE_PARAMS(n)) \ + { \ + return target_(BOOST_ASIO_VARIADIC_MOVE_ARGS(n)); \ + } \ + \ + template \ + typename result_of::type operator()( \ + BOOST_ASIO_VARIADIC_MOVE_PARAMS(n)) const \ + { \ + return target_(BOOST_ASIO_VARIADIC_MOVE_ARGS(n)); \ + } \ + /**/ + BOOST_ASIO_VARIADIC_GENERATE(BOOST_ASIO_PRIVATE_BINDER_CALL_DEF) +#undef BOOST_ASIO_PRIVATE_BINDER_CALL_DEF + +#else // defined(BOOST_ASIO_HAS_STD_TYPE_TRAITS) && !defined(_MSC_VER) + + typedef typename detail::allocator_binder_result_type< + T>::result_type_or_void result_type_or_void; + + result_type_or_void operator()() + { + return target_(); + } + + result_type_or_void operator()() const + { + return target_(); + } + +#define BOOST_ASIO_PRIVATE_BINDER_CALL_DEF(n) \ + template \ + result_type_or_void operator()( \ + BOOST_ASIO_VARIADIC_MOVE_PARAMS(n)) \ + { \ + return target_(BOOST_ASIO_VARIADIC_MOVE_ARGS(n)); \ + } \ + \ + template \ + result_type_or_void operator()( \ + BOOST_ASIO_VARIADIC_MOVE_PARAMS(n)) const \ + { \ + return target_(BOOST_ASIO_VARIADIC_MOVE_ARGS(n)); \ + } \ + /**/ + BOOST_ASIO_VARIADIC_GENERATE(BOOST_ASIO_PRIVATE_BINDER_CALL_DEF) +#undef BOOST_ASIO_PRIVATE_BINDER_CALL_DEF + +#endif // defined(BOOST_ASIO_HAS_STD_TYPE_TRAITS) && !defined(_MSC_VER) + +private: + Allocator allocator_; + T target_; +}; + +/// Associate an object of type @c T with an allocator of type +/// @c Allocator. +template +BOOST_ASIO_NODISCARD inline allocator_binder::type, Allocator> +bind_allocator(const Allocator& s, BOOST_ASIO_MOVE_ARG(T) t) +{ + return allocator_binder< + typename decay::type, Allocator>( + s, BOOST_ASIO_MOVE_CAST(T)(t)); +} + +#if !defined(GENERATING_DOCUMENTATION) + +namespace detail { + +template +struct allocator_binder_async_result_completion_handler_type +{ +}; + +template +struct allocator_binder_async_result_completion_handler_type< + TargetAsyncResult, Allocator, + typename void_type< + typename TargetAsyncResult::completion_handler_type + >::type> +{ + typedef allocator_binder< + typename TargetAsyncResult::completion_handler_type, Allocator> + completion_handler_type; +}; + +template +struct allocator_binder_async_result_return_type +{ +}; + +template +struct allocator_binder_async_result_return_type< + TargetAsyncResult, + typename void_type< + typename TargetAsyncResult::return_type + >::type> +{ + typedef typename TargetAsyncResult::return_type return_type; +}; + +} // namespace detail + +template +class async_result, Signature> : + public detail::allocator_binder_async_result_completion_handler_type< + async_result, Allocator>, + public detail::allocator_binder_async_result_return_type< + async_result > +{ +public: + explicit async_result(allocator_binder& b) + : target_(b.get()) + { + } + + typename async_result::return_type get() + { + return target_.get(); + } + + template + struct init_wrapper + { + template + init_wrapper(const Allocator& allocator, BOOST_ASIO_MOVE_ARG(Init) init) + : allocator_(allocator), + initiation_(BOOST_ASIO_MOVE_CAST(Init)(init)) + { + } + +#if defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES) + + template + void operator()( + BOOST_ASIO_MOVE_ARG(Handler) handler, + BOOST_ASIO_MOVE_ARG(Args)... args) + { + BOOST_ASIO_MOVE_CAST(Initiation)(initiation_)( + allocator_binder< + typename decay::type, Allocator>( + allocator_, BOOST_ASIO_MOVE_CAST(Handler)(handler)), + BOOST_ASIO_MOVE_CAST(Args)(args)...); + } + + template + void operator()( + BOOST_ASIO_MOVE_ARG(Handler) handler, + BOOST_ASIO_MOVE_ARG(Args)... args) const + { + initiation_( + allocator_binder< + typename decay::type, Allocator>( + allocator_, BOOST_ASIO_MOVE_CAST(Handler)(handler)), + BOOST_ASIO_MOVE_CAST(Args)(args)...); + } + +#else // defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES) + + template + void operator()( + BOOST_ASIO_MOVE_ARG(Handler) handler) + { + BOOST_ASIO_MOVE_CAST(Initiation)(initiation_)( + allocator_binder< + typename decay::type, Allocator>( + allocator_, BOOST_ASIO_MOVE_CAST(Handler)(handler))); + } + + template + void operator()( + BOOST_ASIO_MOVE_ARG(Handler) handler) const + { + initiation_( + allocator_binder< + typename decay::type, Allocator>( + allocator_, BOOST_ASIO_MOVE_CAST(Handler)(handler))); + } + +#define BOOST_ASIO_PRIVATE_INIT_WRAPPER_DEF(n) \ + template \ + void operator()( \ + BOOST_ASIO_MOVE_ARG(Handler) handler, \ + BOOST_ASIO_VARIADIC_MOVE_PARAMS(n)) \ + { \ + BOOST_ASIO_MOVE_CAST(Initiation)(initiation_)( \ + allocator_binder< \ + typename decay::type, Allocator>( \ + allocator_, BOOST_ASIO_MOVE_CAST(Handler)(handler)), \ + BOOST_ASIO_VARIADIC_MOVE_ARGS(n)); \ + } \ + \ + template \ + void operator()( \ + BOOST_ASIO_MOVE_ARG(Handler) handler, \ + BOOST_ASIO_VARIADIC_MOVE_PARAMS(n)) const \ + { \ + initiation_( \ + allocator_binder< \ + typename decay::type, Allocator>( \ + allocator_, BOOST_ASIO_MOVE_CAST(Handler)(handler)), \ + BOOST_ASIO_VARIADIC_MOVE_ARGS(n)); \ + } \ + /**/ + BOOST_ASIO_VARIADIC_GENERATE(BOOST_ASIO_PRIVATE_INIT_WRAPPER_DEF) +#undef BOOST_ASIO_PRIVATE_INIT_WRAPPER_DEF + +#endif // defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES) + + Allocator allocator_; + Initiation initiation_; + }; + +#if defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES) + + template + static BOOST_ASIO_INITFN_DEDUCED_RESULT_TYPE(T, Signature, + (async_initiate( + declval::type> >(), + declval().get(), + declval()...))) + initiate( + BOOST_ASIO_MOVE_ARG(Initiation) initiation, + BOOST_ASIO_MOVE_ARG(RawCompletionToken) token, + BOOST_ASIO_MOVE_ARG(Args)... args) + { + return async_initiate( + init_wrapper::type>( + token.get_allocator(), + BOOST_ASIO_MOVE_CAST(Initiation)(initiation)), + token.get(), BOOST_ASIO_MOVE_CAST(Args)(args)...); + } + +#else // defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES) + + template + static BOOST_ASIO_INITFN_DEDUCED_RESULT_TYPE(T, Signature, + (async_initiate( + declval::type> >(), + declval().get()))) + initiate( + BOOST_ASIO_MOVE_ARG(Initiation) initiation, + BOOST_ASIO_MOVE_ARG(RawCompletionToken) token) + { + return async_initiate( + init_wrapper::type>( + token.get_allocator(), + BOOST_ASIO_MOVE_CAST(Initiation)(initiation)), + token.get()); + } + +#define BOOST_ASIO_PRIVATE_INITIATE_DEF(n) \ + template \ + static BOOST_ASIO_INITFN_DEDUCED_RESULT_TYPE(T, Signature, \ + (async_initiate( \ + declval::type> >(), \ + declval().get(), \ + BOOST_ASIO_VARIADIC_MOVE_DECLVAL(n)))) \ + initiate( \ + BOOST_ASIO_MOVE_ARG(Initiation) initiation, \ + BOOST_ASIO_MOVE_ARG(RawCompletionToken) token, \ + BOOST_ASIO_VARIADIC_MOVE_PARAMS(n)) \ + { \ + return async_initiate( \ + init_wrapper::type>( \ + token.get_allocator(), \ + BOOST_ASIO_MOVE_CAST(Initiation)(initiation)), \ + token.get(), BOOST_ASIO_VARIADIC_MOVE_ARGS(n)); \ + } \ + /**/ + BOOST_ASIO_VARIADIC_GENERATE(BOOST_ASIO_PRIVATE_INITIATE_DEF) +#undef BOOST_ASIO_PRIVATE_INITIATE_DEF + +#endif // defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES) + +private: + async_result(const async_result&) BOOST_ASIO_DELETED; + async_result& operator=(const async_result&) BOOST_ASIO_DELETED; + + async_result target_; +}; + +template