From 644a222a8972b8bbc9a524f36bc9054a14459bdd Mon Sep 17 00:00:00 2001 From: Christopher Kohlhoff Date: Wed, 2 Mar 2022 21:59:47 +1100 Subject: [PATCH] Regenerate documentation. --- doc/reference.qbk | 5886 ++++++++++++++++++++++++++++++++------------- doc/tutorial.qbk | 4 +- 2 files changed, 4235 insertions(+), 1655 deletions(-) diff --git a/doc/reference.qbk b/doc/reference.qbk index a78972e657..32d05ca3a0 100644 --- a/doc/reference.qbk +++ b/doc/reference.qbk @@ -15,17 +15,20 @@ [include requirements/asynchronous_socket_operations.qbk] [include requirements/AcceptableProtocol.qbk] [include requirements/AcceptHandler.qbk] +[include requirements/AcceptToken.qbk] [include requirements/AsyncRandomAccessReadDevice.qbk] [include requirements/AsyncRandomAccessWriteDevice.qbk] [include requirements/AsyncReadStream.qbk] [include requirements/AsyncWriteStream.qbk] [include requirements/BufferedHandshakeHandler.qbk] +[include requirements/BufferedHandshakeToken.qbk] [include requirements/CancellationHandler.qbk] [include requirements/CancellationSlot.qbk] [include requirements/CompletionCondition.qbk] [include requirements/CompletionHandler.qbk] [include requirements/ConnectCondition.qbk] [include requirements/ConnectHandler.qbk] +[include requirements/ConnectToken.qbk] [include requirements/ConstBufferSequence.qbk] [include requirements/DynamicBuffer.qbk] [include requirements/DynamicBuffer_v1.qbk] @@ -38,37 +41,716 @@ [include requirements/GettableSocketOption.qbk] [include requirements/Handler.qbk] [include requirements/HandshakeHandler.qbk] +[include requirements/HandshakeToken.qbk] [include requirements/InternetProtocol.qbk] [include requirements/IoControlCommand.qbk] [include requirements/IoObjectService.qbk] [include requirements/IteratorConnectHandler.qbk] +[include requirements/IteratorConnectToken.qbk] [include requirements/LegacyCompletionHandler.qbk] [include requirements/MoveAcceptHandler.qbk] +[include requirements/MoveAcceptToken.qbk] [include requirements/MutableBufferSequence.qbk] [include requirements/OperationState.qbk] [include requirements/ProtoAllocator.qbk] [include requirements/Protocol.qbk] [include requirements/RangeConnectHandler.qbk] +[include requirements/RangeConnectToken.qbk] [include requirements/ReadHandler.qbk] +[include requirements/ReadToken.qbk] [include requirements/Receiver.qbk] [include requirements/ResolveHandler.qbk] +[include requirements/ResolveToken.qbk] [include requirements/Scheduler.qbk] [include requirements/Sender.qbk] [include requirements/Service.qbk] [include requirements/SettableSerialPortOption.qbk] [include requirements/SettableSocketOption.qbk] [include requirements/ShutdownHandler.qbk] +[include requirements/ShutdownToken.qbk] [include requirements/SignalHandler.qbk] +[include requirements/SignalToken.qbk] [include requirements/SyncRandomAccessReadDevice.qbk] [include requirements/SyncRandomAccessWriteDevice.qbk] [include requirements/SyncReadStream.qbk] [include requirements/SyncWriteStream.qbk] [include requirements/TimeTraits.qbk] [include requirements/WaitHandler.qbk] +[include requirements/WaitToken.qbk] [include requirements/WaitTraits.qbk] [include requirements/WriteHandler.qbk] +[include requirements/WriteToken.qbk] +[section:allocator_binder allocator_binder] + +[indexterm1 boost_asio.indexterm.allocator_binder..allocator_binder] + + +A call wrapper type to bind an allocator of type `Allocator` to an object of type `T`. + + + template< + typename T, + typename Allocator> + class allocator_binder + + +[heading Types] +[table + [[Name][Description]] + + [ + + [[link boost_asio.reference.allocator_binder.allocator_type [*allocator_type]]] + [The type of the associated allocator. ] + + ] + + [ + + [[link boost_asio.reference.allocator_binder.argument_type [*argument_type]]] + [The type of the function's argument. ] + + ] + + [ + + [[link boost_asio.reference.allocator_binder.first_argument_type [*first_argument_type]]] + [The type of the function's first argument. ] + + ] + + [ + + [[link boost_asio.reference.allocator_binder.result_type [*result_type]]] + [The return type if a function. ] + + ] + + [ + + [[link boost_asio.reference.allocator_binder.second_argument_type [*second_argument_type]]] + [The type of the function's second argument. ] + + ] + + [ + + [[link boost_asio.reference.allocator_binder.target_type [*target_type]]] + [The type of the target object. ] + + ] + +] + +[heading Member Functions] +[table + [[Name][Description]] + + [ + [[link boost_asio.reference.allocator_binder.allocator_binder [*allocator_binder]] [constructor]] + [Construct an allocator wrapper for the specified object. + [hr] + Copy constructor. + [hr] + Construct a copy, but specify a different allocator. + [hr] + Construct a copy of a different allocator wrapper type. + [hr] + Construct a copy of a different allocator wrapper type, but specify a different allocator. + [hr] + Move constructor. + [hr] + Move construct the target object, but specify a different allocator. + [hr] + Move construct from a different allocator wrapper type. + [hr] + Move construct from a different allocator wrapper type, but specify a different allocator. ] + ] + + [ + [[link boost_asio.reference.allocator_binder.get [*get]]] + [Obtain a reference to the target object. ] + ] + + [ + [[link boost_asio.reference.allocator_binder.get_allocator [*get_allocator]]] + [Obtain the associated allocator. ] + ] + + [ + [[link boost_asio.reference.allocator_binder.operator_lp__rp_ [*operator()]]] + [] + ] + + [ + [[link boost_asio.reference.allocator_binder._allocator_binder [*~allocator_binder]] [destructor]] + [Destructor. ] + ] + +] + +[heading Requirements] + +['Header: ][^boost/asio/bind_allocator.hpp] + +['Convenience header: ][^boost/asio.hpp] + +[section:allocator_binder allocator_binder::allocator_binder] + +[indexterm2 boost_asio.indexterm.allocator_binder.allocator_binder..allocator_binder..allocator_binder] +Construct an allocator wrapper for the specified object. + + + template< + typename U> + ``[link boost_asio.reference.allocator_binder.allocator_binder.overload1 allocator_binder]``( + const allocator_type & s, + U && u); + `` [''''»''' [link boost_asio.reference.allocator_binder.allocator_binder.overload1 more...]]`` + + +Copy constructor. + + + ``[link boost_asio.reference.allocator_binder.allocator_binder.overload2 allocator_binder]``( + const allocator_binder & other); + `` [''''»''' [link boost_asio.reference.allocator_binder.allocator_binder.overload2 more...]]`` + + +Construct a copy, but specify a different allocator. + + + ``[link boost_asio.reference.allocator_binder.allocator_binder.overload3 allocator_binder]``( + const allocator_type & s, + const allocator_binder & other); + `` [''''»''' [link boost_asio.reference.allocator_binder.allocator_binder.overload3 more...]]`` + + +Construct a copy of a different allocator wrapper type. + + + template< + typename U, + typename OtherAllocator> + ``[link boost_asio.reference.allocator_binder.allocator_binder.overload4 allocator_binder]``( + const allocator_binder< U, OtherAllocator > & other); + `` [''''»''' [link boost_asio.reference.allocator_binder.allocator_binder.overload4 more...]]`` + + +Construct a copy of a different allocator wrapper type, but specify a different allocator. + + + template< + typename U, + typename OtherAllocator> + ``[link boost_asio.reference.allocator_binder.allocator_binder.overload5 allocator_binder]``( + const allocator_type & s, + const allocator_binder< U, OtherAllocator > & other); + `` [''''»''' [link boost_asio.reference.allocator_binder.allocator_binder.overload5 more...]]`` + + +Move constructor. + + + ``[link boost_asio.reference.allocator_binder.allocator_binder.overload6 allocator_binder]``( + allocator_binder && other); + `` [''''»''' [link boost_asio.reference.allocator_binder.allocator_binder.overload6 more...]]`` + + +Move construct the target object, but specify a different allocator. + + + ``[link boost_asio.reference.allocator_binder.allocator_binder.overload7 allocator_binder]``( + const allocator_type & s, + allocator_binder && other); + `` [''''»''' [link boost_asio.reference.allocator_binder.allocator_binder.overload7 more...]]`` + + +Move construct from a different allocator wrapper type. + + + template< + typename U, + typename OtherAllocator> + ``[link boost_asio.reference.allocator_binder.allocator_binder.overload8 allocator_binder]``( + allocator_binder< U, OtherAllocator > && other); + `` [''''»''' [link boost_asio.reference.allocator_binder.allocator_binder.overload8 more...]]`` + + +Move construct from a different allocator wrapper type, but specify a different allocator. + + + template< + typename U, + typename OtherAllocator> + ``[link boost_asio.reference.allocator_binder.allocator_binder.overload9 allocator_binder]``( + const allocator_type & s, + allocator_binder< U, OtherAllocator > && other); + `` [''''»''' [link boost_asio.reference.allocator_binder.allocator_binder.overload9 more...]]`` + + +[section:overload1 allocator_binder::allocator_binder (1 of 9 overloads)] + + +Construct an allocator wrapper for the specified object. + + + template< + typename U> + allocator_binder( + const allocator_type & s, + U && u); + + +This constructor is only valid if the type `T` is constructible from type `U`. + + +[endsect] + + + +[section:overload2 allocator_binder::allocator_binder (2 of 9 overloads)] + + +Copy constructor. + + + allocator_binder( + const allocator_binder & other); + + + +[endsect] + + + +[section:overload3 allocator_binder::allocator_binder (3 of 9 overloads)] + + +Construct a copy, but specify a different allocator. + + + allocator_binder( + const allocator_type & s, + const allocator_binder & other); + + + +[endsect] + + + +[section:overload4 allocator_binder::allocator_binder (4 of 9 overloads)] + + +Construct a copy of a different allocator wrapper type. + + + template< + typename U, + typename OtherAllocator> + allocator_binder( + const allocator_binder< U, OtherAllocator > & other); + + +This constructor is only valid if the `Allocator` type is constructible from type `OtherAllocator`, and the type `T` is constructible from type `U`. + + +[endsect] + + + +[section:overload5 allocator_binder::allocator_binder (5 of 9 overloads)] + + +Construct a copy of a different allocator wrapper type, but specify a different allocator. + + + template< + typename U, + typename OtherAllocator> + allocator_binder( + const allocator_type & s, + const allocator_binder< U, OtherAllocator > & other); + + +This constructor is only valid if the type `T` is constructible from type `U`. + + +[endsect] + + + +[section:overload6 allocator_binder::allocator_binder (6 of 9 overloads)] + + +Move constructor. + + + allocator_binder( + allocator_binder && other); + + + +[endsect] + + + +[section:overload7 allocator_binder::allocator_binder (7 of 9 overloads)] + + +Move construct the target object, but specify a different allocator. + + + allocator_binder( + const allocator_type & s, + allocator_binder && other); + + + +[endsect] + + + +[section:overload8 allocator_binder::allocator_binder (8 of 9 overloads)] + + +Move construct from a different allocator wrapper type. + + + template< + typename U, + typename OtherAllocator> + allocator_binder( + allocator_binder< U, OtherAllocator > && other); + + + +[endsect] + + + +[section:overload9 allocator_binder::allocator_binder (9 of 9 overloads)] + + +Move construct from a different allocator wrapper type, but specify a different allocator. + + + template< + typename U, + typename OtherAllocator> + allocator_binder( + const allocator_type & s, + allocator_binder< U, OtherAllocator > && other); + + + +[endsect] + + +[endsect] + + +[section:allocator_type allocator_binder::allocator_type] + +[indexterm2 boost_asio.indexterm.allocator_binder.allocator_type..allocator_type..allocator_binder] +The type of the associated allocator. + + + typedef Allocator allocator_type; + + + +[heading Requirements] + +['Header: ][^boost/asio/bind_allocator.hpp] + +['Convenience header: ][^boost/asio.hpp] + + +[endsect] + + + +[section:argument_type allocator_binder::argument_type] + +[indexterm2 boost_asio.indexterm.allocator_binder.argument_type..argument_type..allocator_binder] +The type of the function's argument. + + + typedef see_below argument_type; + + + +The type of `argument_type` is based on the type `T` of the wrapper's target object: + + +* if `T` is a pointer to a function type accepting a single argument, `argument_type` is a synonym for the return type of `T`; + + +* if `T` is a class type with a member type `argument_type`, then `argument_type` is a synonym for `T::argument_type`; + + +* otherwise `argument_type` is not defined. + + + +[heading Requirements] + +['Header: ][^boost/asio/bind_allocator.hpp] + +['Convenience header: ][^boost/asio.hpp] + + +[endsect] + + + +[section:first_argument_type allocator_binder::first_argument_type] + +[indexterm2 boost_asio.indexterm.allocator_binder.first_argument_type..first_argument_type..allocator_binder] +The type of the function's first argument. + + + typedef see_below first_argument_type; + + + +The type of `first_argument_type` is based on the type `T` of the wrapper's target object: + + +* if `T` is a pointer to a function type accepting two arguments, `first_argument_type` is a synonym for the return type of `T`; + + +* if `T` is a class type with a member type `first_argument_type`, then `first_argument_type` is a synonym for `T::first_argument_type`; + + +* otherwise `first_argument_type` is not defined. + + + +[heading Requirements] + +['Header: ][^boost/asio/bind_allocator.hpp] + +['Convenience header: ][^boost/asio.hpp] + + +[endsect] + + +[section:get allocator_binder::get] + +[indexterm2 boost_asio.indexterm.allocator_binder.get..get..allocator_binder] +Obtain a reference to the target object. + + + target_type & ``[link boost_asio.reference.allocator_binder.get.overload1 get]``(); + `` [''''»''' [link boost_asio.reference.allocator_binder.get.overload1 more...]]`` + + const target_type & ``[link boost_asio.reference.allocator_binder.get.overload2 get]``() const; + `` [''''»''' [link boost_asio.reference.allocator_binder.get.overload2 more...]]`` + + +[section:overload1 allocator_binder::get (1 of 2 overloads)] + + +Obtain a reference to the target object. + + + target_type & get(); + + + +[endsect] + + + +[section:overload2 allocator_binder::get (2 of 2 overloads)] + + +Obtain a reference to the target object. + + + const target_type & get() const; + + + +[endsect] + + +[endsect] + + +[section:get_allocator allocator_binder::get_allocator] + +[indexterm2 boost_asio.indexterm.allocator_binder.get_allocator..get_allocator..allocator_binder] +Obtain the associated allocator. + + + allocator_type get_allocator() const; + + + +[endsect] + + +[section:operator_lp__rp_ allocator_binder::operator()] + +[indexterm2 boost_asio.indexterm.allocator_binder.operator_lp__rp_..operator()..allocator_binder] + + template< + typename... Args> + auto ``[link boost_asio.reference.allocator_binder.operator_lp__rp_.overload1 operator()]``( + Args && ...); + `` [''''»''' [link boost_asio.reference.allocator_binder.operator_lp__rp_.overload1 more...]]`` + + template< + typename... Args> + auto ``[link boost_asio.reference.allocator_binder.operator_lp__rp_.overload2 operator()]``( + Args && ...) const; + `` [''''»''' [link boost_asio.reference.allocator_binder.operator_lp__rp_.overload2 more...]]`` + + +[section:overload1 allocator_binder::operator() (1 of 2 overloads)] + + + + template< + typename... Args> + auto operator()( + Args && ...); + + + +[endsect] + + + +[section:overload2 allocator_binder::operator() (2 of 2 overloads)] + + + + template< + typename... Args> + auto operator()( + Args && ...) const; + + + +[endsect] + + +[endsect] + + +[section:result_type allocator_binder::result_type] + +[indexterm2 boost_asio.indexterm.allocator_binder.result_type..result_type..allocator_binder] +The return type if a function. + + + typedef see_below result_type; + + + +The type of `result_type` is based on the type `T` of the wrapper's target object: + + +* if `T` is a pointer to function type, `result_type` is a synonym for the return type of `T`; + + +* if `T` is a class type with a member type `result_type`, then `result_type` is a synonym for `T::result_type`; + + +* otherwise `result_type` is not defined. + + + +[heading Requirements] + +['Header: ][^boost/asio/bind_allocator.hpp] + +['Convenience header: ][^boost/asio.hpp] + + +[endsect] + + + +[section:second_argument_type allocator_binder::second_argument_type] + +[indexterm2 boost_asio.indexterm.allocator_binder.second_argument_type..second_argument_type..allocator_binder] +The type of the function's second argument. + + + typedef see_below second_argument_type; + + + +The type of `second_argument_type` is based on the type `T` of the wrapper's target object: + + +* if `T` is a pointer to a function type accepting two arguments, `second_argument_type` is a synonym for the return type of `T`; + + +* if `T` is a class type with a member type `first_argument_type`, then `second_argument_type` is a synonym for `T::second_argument_type`; + + +* otherwise `second_argument_type` is not defined. + + + +[heading Requirements] + +['Header: ][^boost/asio/bind_allocator.hpp] + +['Convenience header: ][^boost/asio.hpp] + + +[endsect] + + + +[section:target_type allocator_binder::target_type] + +[indexterm2 boost_asio.indexterm.allocator_binder.target_type..target_type..allocator_binder] +The type of the target object. + + + typedef T target_type; + + + +[heading Requirements] + +['Header: ][^boost/asio/bind_allocator.hpp] + +['Convenience header: ][^boost/asio.hpp] + + +[endsect] + + + +[section:_allocator_binder allocator_binder::~allocator_binder] + +[indexterm2 boost_asio.indexterm.allocator_binder._allocator_binder..~allocator_binder..allocator_binder] +Destructor. + + + ~allocator_binder(); + + + +[endsect] + + + +[endsect] + [section:any_io_executor any_io_executor] [indexterm1 boost_asio.indexterm.any_io_executor..any_io_executor] @@ -1114,7 +1796,8 @@ Destructor. [section:asio_handler_allocate asio_handler_allocate] -[indexterm1 boost_asio.indexterm.asio_handler_allocate..asio_handler_allocate] +[indexterm1 boost_asio.indexterm.asio_handler_allocate..asio_handler_allocate] + (Deprecated: Use the [link boost_asio.reference.associated_allocator `associated_allocator`] trait.) Default allocation function for handlers. @@ -1170,7 +1853,8 @@ All temporary objects associated with a handler will be deallocated before the u [section:asio_handler_deallocate asio_handler_deallocate] -[indexterm1 boost_asio.indexterm.asio_handler_deallocate..asio_handler_deallocate] +[indexterm1 boost_asio.indexterm.asio_handler_deallocate..asio_handler_deallocate] + Default deallocation function for handlers. @@ -1199,7 +1883,8 @@ The default implementation of these allocation hooks uses `operator new` and `op [section:asio_handler_invoke asio_handler_invoke] -[indexterm1 boost_asio.indexterm.asio_handler_invoke..asio_handler_invoke] +[indexterm1 boost_asio.indexterm.asio_handler_invoke..asio_handler_invoke] + (Deprecated: Use the [link boost_asio.reference.associated_executor `associated_executor`] trait.) Default invoke function for handlers. @@ -1299,7 +1984,8 @@ Default handler invocation hook used for const function objects. [section:asio_handler_is_continuation asio_handler_is_continuation] -[indexterm1 boost_asio.indexterm.asio_handler_is_continuation..asio_handler_is_continuation] +[indexterm1 boost_asio.indexterm.asio_handler_is_continuation..asio_handler_is_continuation] + Default continuation function for handlers. @@ -2095,7 +2781,8 @@ The result of the asynchronous operation's initiating function. [section:async_compose async_compose] -[indexterm1 boost_asio.indexterm.async_compose..async_compose] +[indexterm1 boost_asio.indexterm.async_compose..async_compose] + Launch an asynchronous operation with a stateful implementation. @@ -2201,7 +2888,8 @@ The async\_compose function simplifies the implementation of composed asynchrono [section:async_connect async_connect] -[indexterm1 boost_asio.indexterm.async_connect..async_connect] +[indexterm1 boost_asio.indexterm.async_connect..async_connect] + The `async_connect` function is a composed asynchronous operation that establishes a socket connection by trying each endpoint in a sequence. @@ -2211,11 +2899,11 @@ Asynchronously establishes a socket connection by trying each endpoint in a sequ typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename ``[link boost_asio.reference.EndpointSequence EndpointSequence]``, - typename ``[link boost_asio.reference.RangeConnectHandler RangeConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.RangeConnectToken RangeConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_connect.overload1 async_connect]``( basic_socket< Protocol, Executor > & s, const EndpointSequence & endpoints, - RangeConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + RangeConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_endpoint_sequence< EndpointSequence >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_connect.overload1 more...]]`` @@ -2225,11 +2913,11 @@ Asynchronously establishes a socket connection by trying each endpoint in a sequ typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, - typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.IteratorConnectToken IteratorConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_connect.overload2 async_connect]``( basic_socket< Protocol, Executor > & s, Iterator begin, - IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + IteratorConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_connect.overload2 more...]]`` @@ -2239,12 +2927,12 @@ Asynchronously establishes a socket connection by trying each endpoint in a sequ typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, - typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.IteratorConnectToken IteratorConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_connect.overload3 async_connect]``( basic_socket< Protocol, Executor > & s, Iterator begin, Iterator end, - IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + IteratorConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_connect.overload3 more...]]`` template< @@ -2252,12 +2940,12 @@ Asynchronously establishes a socket connection by trying each endpoint in a sequ typename ``[link boost_asio.reference.Executor1 Executor]``, typename ``[link boost_asio.reference.EndpointSequence EndpointSequence]``, typename ``[link boost_asio.reference.ConnectCondition ConnectCondition]``, - typename ``[link boost_asio.reference.RangeConnectHandler RangeConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.RangeConnectToken RangeConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_connect.overload4 async_connect]``( basic_socket< Protocol, Executor > & s, const EndpointSequence & endpoints, ConnectCondition connect_condition, - RangeConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + RangeConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_endpoint_sequence< EndpointSequence >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_connect.overload4 more...]]`` @@ -2268,12 +2956,12 @@ Asynchronously establishes a socket connection by trying each endpoint in a sequ typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, typename ``[link boost_asio.reference.ConnectCondition ConnectCondition]``, - typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.IteratorConnectToken IteratorConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_connect.overload5 async_connect]``( basic_socket< Protocol, Executor > & s, Iterator begin, ConnectCondition connect_condition, - IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + IteratorConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_connect.overload5 more...]]`` @@ -2284,13 +2972,13 @@ Asynchronously establishes a socket connection by trying each endpoint in a sequ typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, typename ``[link boost_asio.reference.ConnectCondition ConnectCondition]``, - typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.IteratorConnectToken IteratorConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_connect.overload6 async_connect]``( basic_socket< Protocol, Executor > & s, Iterator begin, Iterator end, ConnectCondition connect_condition, - IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + IteratorConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_connect.overload6 more...]]`` [heading Requirements] @@ -2310,15 +2998,15 @@ Asynchronously establishes a socket connection by trying each endpoint in a sequ typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename ``[link boost_asio.reference.EndpointSequence EndpointSequence]``, - typename ``[link boost_asio.reference.RangeConnectHandler RangeConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.RangeConnectToken RangeConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( basic_socket< Protocol, Executor > & s, const EndpointSequence & endpoints, - RangeConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + RangeConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_endpoint_sequence< EndpointSequence >::value >::type = 0); -This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. +This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -2330,7 +3018,7 @@ This function attempts to connect a socket to one of a sequence of endpoints. It [[endpoints][A sequence of endpoints.]] -[[handler][The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the connect completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. if the sequence is empty, set to @@ -2343,11 +3031,21 @@ This function attempts to connect a socket to one of a sequence of endpoints. It const typename Protocol::endpoint& endpoint ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, typename Protocol::endpoint) + + + + + [heading Example] @@ -2412,15 +3110,15 @@ if they are also supported by the socket's `async_connect` operation. typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, - typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.IteratorConnectToken IteratorConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( basic_socket< Protocol, Executor > & s, Iterator begin, - IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + IteratorConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint::value >::type = 0); -This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. +This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -2432,7 +3130,7 @@ This function attempts to connect a socket to one of a sequence of endpoints. It [[begin][An iterator pointing to the start of a sequence of endpoints.]] -[[handler][The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the connect completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. if the sequence is empty, set to @@ -2445,11 +3143,21 @@ This function attempts to connect a socket to one of a sequence of endpoints. It Iterator iterator ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, Iterator) + + + + + [heading Remarks] This overload assumes that a default constructed object of type `Iterator` represents the end of the sequence. This is a valid assumption for iterator types such as `boost::asio::ip::tcp::resolver::iterator`. @@ -2482,15 +3190,15 @@ Asynchronously establishes a socket connection by trying each endpoint in a sequ typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, - typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.IteratorConnectToken IteratorConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( basic_socket< Protocol, Executor > & s, Iterator begin, Iterator end, - IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + IteratorConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. +This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -2504,7 +3212,7 @@ This function attempts to connect a socket to one of a sequence of endpoints. It [[end][An iterator pointing to the end of a sequence of endpoints.]] -[[handler][The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the connect completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. if the sequence is empty, set to @@ -2517,11 +3225,21 @@ This function attempts to connect a socket to one of a sequence of endpoints. It Iterator iterator ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, Iterator) + + + + + [heading Example] @@ -2573,16 +3291,16 @@ Asynchronously establishes a socket connection by trying each endpoint in a sequ typename ``[link boost_asio.reference.Executor1 Executor]``, typename ``[link boost_asio.reference.EndpointSequence EndpointSequence]``, typename ``[link boost_asio.reference.ConnectCondition ConnectCondition]``, - typename ``[link boost_asio.reference.RangeConnectHandler RangeConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.RangeConnectToken RangeConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( basic_socket< Protocol, Executor > & s, const EndpointSequence & endpoints, ConnectCondition connect_condition, - RangeConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + RangeConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_endpoint_sequence< EndpointSequence >::value >::type = 0); -This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. +This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -2602,7 +3320,153 @@ This function attempts to connect a socket to one of a sequence of endpoints. It `` The `ec` parameter contains the result from the most recent connect operation. Before the first connection attempt, `ec` is always set to indicate success. The `next` parameter is the next endpoint to be tried. The function object should return true if the next endpoint should be tried, and false if it should be skipped.]] -[[handler][The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the connect completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: +`` + void handler( + // Result of operation. if the sequence is empty, set to + // boost::asio::error::not_found. Otherwise, contains the + // error from the last connection attempt. + const boost::system::error_code& error, + + // On success, an iterator denoting the successfully + // connected endpoint. Otherwise, the end iterator. + Iterator iterator + ); +`` +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] + +] + + +[heading Completion Signature] + + + + void(boost::system::error_code, typename Protocol::endpoint) + + + + + +[heading Example] + +The following connect condition function object can be used to output information about the individual connection attempts: + + struct my_connect_condition + { + bool operator()( + const boost::system::error_code& ec, + const::tcp::endpoint& next) + { + if (ec) std::cout << "Error: " << ec.message() << std::endl; + std::cout << "Trying: " << next << std::endl; + return true; + } + }; + + +It would be used with the `boost::asio::connect` function as follows: + + tcp::resolver r(my_context); + tcp::resolver::query q("host", "service"); + tcp::socket s(my_context); + + // ... + + r.async_resolve(q, resolve_handler); + + // ... + + void resolve_handler( + const boost::system::error_code& ec, + tcp::resolver::results_type results) + { + if (!ec) + { + boost::asio::async_connect(s, results, + my_connect_condition(), + connect_handler); + } + } + + // ... + + void connect_handler( + const boost::system::error_code& ec, + const tcp::endpoint& endpoint) + { + if (ec) + { + // An error occurred. + } + else + { + std::cout << "Connected to: " << endpoint << std::endl; + } + } + + + + + +[heading Per-Operation Cancellation] + +This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: + + +* `cancellation_type::terminal` + + +* `cancellation_type::partial` + +if they are also supported by the socket's `async_connect` operation. + + +[endsect] + + + +[section:overload5 async_connect (5 of 6 overloads)] + + +(Deprecated: Use range overload.) Asynchronously establishes a socket connection by trying each endpoint in a sequence. + + + template< + typename ``[link boost_asio.reference.Protocol Protocol]``, + typename ``[link boost_asio.reference.Executor1 Executor]``, + typename Iterator, + typename ``[link boost_asio.reference.ConnectCondition ConnectCondition]``, + typename ``[link boost_asio.reference.IteratorConnectToken IteratorConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( + basic_socket< Protocol, Executor > & s, + Iterator begin, + ConnectCondition connect_condition, + IteratorConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + typename constraint::value >::type = 0); + + +This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. + + +[heading Parameters] + + +[variablelist + +[[s][The socket to be connected. If the socket is already open, it will be closed.]] + +[[begin][An iterator pointing to the start of a sequence of endpoints.]] + +[[connect_condition][A function object that is called prior to each connection attempt. The signature of the function object must be: +`` + bool connect_condition( + const boost::system::error_code& ec, + const typename Protocol::endpoint& next); +`` +The `ec` parameter contains the result from the most recent connect operation. Before the first connection attempt, `ec` is always set to indicate success. The `next` parameter is the next endpoint to be tried. The function object should return true if the next endpoint should be tried, and false if it should be skipped.]] + +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the connect completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. if the sequence is empty, set to @@ -2615,146 +3479,20 @@ The `ec` parameter contains the result from the most recent connect operation. B Iterator iterator ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] -[heading Example] - -The following connect condition function object can be used to output information about the individual connection attempts: - - struct my_connect_condition - { - bool operator()( - const boost::system::error_code& ec, - const::tcp::endpoint& next) - { - if (ec) std::cout << "Error: " << ec.message() << std::endl; - std::cout << "Trying: " << next << std::endl; - return true; - } - }; - - -It would be used with the `boost::asio::connect` function as follows: - - tcp::resolver r(my_context); - tcp::resolver::query q("host", "service"); - tcp::socket s(my_context); - - // ... - - r.async_resolve(q, resolve_handler); - - // ... - - void resolve_handler( - const boost::system::error_code& ec, - tcp::resolver::results_type results) - { - if (!ec) - { - boost::asio::async_connect(s, results, - my_connect_condition(), - connect_handler); - } - } - - // ... - - void connect_handler( - const boost::system::error_code& ec, - const tcp::endpoint& endpoint) - { - if (ec) - { - // An error occurred. - } - else - { - std::cout << "Connected to: " << endpoint << std::endl; - } - } - - - - - -[heading Per-Operation Cancellation] +[heading Completion Signature] -This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: - -* `cancellation_type::terminal` + void(boost::system::error_code, Iterator) -* `cancellation_type::partial` -if they are also supported by the socket's `async_connect` operation. -[endsect] - - - -[section:overload5 async_connect (5 of 6 overloads)] - - -(Deprecated: Use range overload.) Asynchronously establishes a socket connection by trying each endpoint in a sequence. - - - template< - typename ``[link boost_asio.reference.Protocol Protocol]``, - typename ``[link boost_asio.reference.Executor1 Executor]``, - typename Iterator, - typename ``[link boost_asio.reference.ConnectCondition ConnectCondition]``, - typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> - ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( - basic_socket< Protocol, Executor > & s, - Iterator begin, - ConnectCondition connect_condition, - IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, - typename constraint::value >::type = 0); - - -This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. - - -[heading Parameters] - - -[variablelist - -[[s][The socket to be connected. If the socket is already open, it will be closed.]] - -[[begin][An iterator pointing to the start of a sequence of endpoints.]] - -[[connect_condition][A function object that is called prior to each connection attempt. The signature of the function object must be: -`` - bool connect_condition( - const boost::system::error_code& ec, - const typename Protocol::endpoint& next); -`` -The `ec` parameter contains the result from the most recent connect operation. Before the first connection attempt, `ec` is always set to indicate success. The `next` parameter is the next endpoint to be tried. The function object should return true if the next endpoint should be tried, and false if it should be skipped.]] - -[[handler][The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be: -`` - void handler( - // Result of operation. if the sequence is empty, set to - // boost::asio::error::not_found. Otherwise, contains the - // error from the last connection attempt. - const boost::system::error_code& error, - - // On success, an iterator denoting the successfully - // connected endpoint. Otherwise, the end iterator. - Iterator iterator - ); -`` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] - -] - [heading Remarks] @@ -2789,16 +3527,16 @@ Asynchronously establishes a socket connection by trying each endpoint in a sequ typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, typename ``[link boost_asio.reference.ConnectCondition ConnectCondition]``, - typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.IteratorConnectToken IteratorConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( basic_socket< Protocol, Executor > & s, Iterator begin, Iterator end, ConnectCondition connect_condition, - IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + IteratorConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. +This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -2820,7 +3558,7 @@ This function attempts to connect a socket to one of a sequence of endpoints. It `` The `ec` parameter contains the result from the most recent connect operation. Before the first connection attempt, `ec` is always set to indicate success. The `next` parameter is the next endpoint to be tried. The function object should return true if the next endpoint should be tried, and false if it should be skipped.]] -[[handler][The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the connect completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. if the sequence is empty, set to @@ -2833,11 +3571,21 @@ The `ec` parameter contains the result from the most recent connect operation. B Iterator iterator ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, Iterator) + + + + + [heading Example] The following connect condition function object can be used to output information about the individual connection attempts: @@ -2921,7 +3669,8 @@ if they are also supported by the socket's `async_connect` operation. [section:async_initiate async_initiate] -[indexterm1 boost_asio.indexterm.async_initiate..async_initiate] +[indexterm1 boost_asio.indexterm.async_initiate..async_initiate] + template< typename CompletionToken, @@ -2946,7 +3695,8 @@ if they are also supported by the socket's `async_connect` operation. [section:async_read async_read] -[indexterm1 boost_asio.indexterm.async_read..async_read] +[indexterm1 boost_asio.indexterm.async_read..async_read] + The `async_read` function is a composed asynchronous operation that reads a certain amount of data from a stream before completion. @@ -2955,11 +3705,11 @@ Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload1 async_read]``( AsyncReadStream & s, const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_mutable_buffer_sequence< MutableBufferSequence >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read.overload1 more...]]`` @@ -2967,23 +3717,23 @@ Start an asynchronous operation to read a certain amount of data from a stream. typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload2 async_read]``( AsyncReadStream & s, const MutableBufferSequence & buffers, CompletionCondition completion_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_mutable_buffer_sequence< MutableBufferSequence >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read.overload2 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload3 async_read]``( AsyncReadStream & s, DynamicBuffer_v1 && buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read.overload3 more...]]`` @@ -2992,12 +3742,12 @@ Start an asynchronous operation to read a certain amount of data from a stream. typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload4 async_read]``( AsyncReadStream & s, DynamicBuffer_v1 && buffers, CompletionCondition completion_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read.overload4 more...]]`` @@ -3005,33 +3755,33 @@ Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload5 async_read]``( AsyncReadStream & s, basic_streambuf< Allocator > & b, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read.overload5 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload6 async_read]``( AsyncReadStream & s, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read.overload6 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload7 async_read]``( AsyncReadStream & s, DynamicBuffer_v2 buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read.overload7 more...]]`` @@ -3039,12 +3789,12 @@ Start an asynchronous operation to read a certain amount of data from a stream. typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload8 async_read]``( AsyncReadStream & s, DynamicBuffer_v2 buffers, CompletionCondition completion_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read.overload8 more...]]`` @@ -3064,15 +3814,15 @@ Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_mutable_buffer_sequence< MutableBufferSequence >::value >::type = 0); -This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read a certain number of bytes of data from a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes. @@ -3090,33 +3840,43 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the stream. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the stream. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes copied into the - // buffers. If an error occurred, - // this will be the number of - // bytes successfully transferred - // prior to the error. + // Number of bytes copied into the buffers. If an error + // occurred, this will be the number of bytes successfully + // transferred prior to the error. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_read(s, boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Remarks] @@ -3159,16 +3919,16 @@ Start an asynchronous operation to read a certain amount of data from a stream. typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, const MutableBufferSequence & buffers, CompletionCondition completion_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_mutable_buffer_sequence< MutableBufferSequence >::value >::type = 0); -This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read a certain number of bytes of data from a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes. @@ -3184,7 +3944,7 @@ This function is used to asynchronously read a certain number of bytes of data f [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the stream. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the stream. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be: `` @@ -3198,26 +3958,36 @@ This function is used to asynchronously read a certain number of bytes of data f `` A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the stream's async\_read\_some function.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes copied into the - // buffers. If an error occurred, - // this will be the number of - // bytes successfully transferred - // prior to the error. + // Number of bytes copied into the buffers. If an error + // occurred, this will be the number of bytes successfully + // transferred prior to the error. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_read(s, boost::asio::buffer(data, size), @@ -3225,7 +3995,7 @@ To read into a single data buffer use the [link boost_asio.reference.buffer `buf handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -3254,16 +4024,16 @@ Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, DynamicBuffer_v1 && buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); -This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read a certain number of bytes of data from a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The specified dynamic buffer sequence is full (that is, it has reached maximum size). @@ -3281,25 +4051,35 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes copied into the - // buffers. If an error occurred, - // this will be the number of - // bytes successfully transferred - // prior to the error. + // Number of bytes copied into the buffers. If an error + // occurred, this will be the number of bytes successfully + // transferred prior to the error. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] This overload is equivalent to calling: @@ -3340,17 +4120,17 @@ Start an asynchronous operation to read a certain amount of data from a stream. typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, DynamicBuffer_v1 && buffers, CompletionCondition completion_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); -This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read a certain number of bytes of data from a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The specified dynamic buffer sequence is full (that is, it has reached maximum size). @@ -3368,7 +4148,7 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be: `` @@ -3382,23 +4162,33 @@ This operation is implemented in terms of zero or more calls to the stream's asy `` A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the stream's async\_read\_some function.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes copied into the - // buffers. If an error occurred, - // this will be the number of - // bytes successfully transferred - // prior to the error. + // Number of bytes copied into the buffers. If an error + // occurred, this will be the number of bytes successfully + // transferred prior to the error. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -3425,14 +4215,14 @@ Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, basic_streambuf< Allocator > & b, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read a certain number of bytes of data from a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The supplied buffer is full (that is, it has reached maximum size). @@ -3450,25 +4240,35 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] +[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes copied into the - // buffers. If an error occurred, - // this will be the number of - // bytes successfully transferred - // prior to the error. + // Number of bytes copied into the buffers. If an error + // occurred, this will be the number of bytes successfully + // transferred prior to the error. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] This overload is equivalent to calling: @@ -3499,7 +4299,101 @@ if they are also supported by the `AsyncReadStream` type's `async_read_some` ope -[section:overload6 async_read (6 of 8 overloads)] +[section:overload6 async_read (6 of 8 overloads)] + + +Start an asynchronous operation to read a certain amount of data from a stream. + + + template< + typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, + typename Allocator, + typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( + AsyncReadStream & s, + basic_streambuf< Allocator > & b, + CompletionCondition completion_condition, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + + +This function is used to asynchronously read a certain number of bytes of data from a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: + + +* The supplied buffer is full (that is, it has reached maximum size). + + +* The completion\_condition function object returns 0. + +This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. The program must ensure that the stream performs no other read operations (such as async\_read, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. + + +[heading Parameters] + + +[variablelist + +[[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] + +[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the completion handler is called.]] + +[[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be: +`` + std::size_t completion_condition( + // Result of latest async_read_some operation. + const boost::system::error_code& error, + + // Number of bytes transferred so far. + std::size_t bytes_transferred + ); +`` +A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the stream's async\_read\_some function.]] + +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: +`` + void handler( + // Result of operation. + const boost::system::error_code& error, + + // Number of bytes copied into the buffers. If an error + // occurred, this will be the number of bytes successfully + // transferred prior to the error. + std::size_t bytes_transferred + ); +`` +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] + +] + + +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + +[heading Per-Operation Cancellation] + +This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: + + +* `cancellation_type::terminal` + + +* `cancellation_type::partial` + +if they are also supported by the `AsyncReadStream` type's `async_read_some` operation. + + +[endsect] + + + +[section:overload7 async_read (7 of 8 overloads)] Start an asynchronous operation to read a certain amount of data from a stream. @@ -3507,23 +4401,22 @@ Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, - typename Allocator, - typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, - basic_streambuf< Allocator > & b, - CompletionCondition completion_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + DynamicBuffer_v2 buffers, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); -This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read a certain number of bytes of data from a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: -* The supplied buffer is full (that is, it has reached maximum size). +* The specified dynamic buffer sequence is full (that is, it has reached maximum size). -* The completion\_condition function object returns 0. +* An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. The program must ensure that the stream performs no other read operations (such as async\_read, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. @@ -3535,107 +4428,34 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] +[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] -[[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` - std::size_t completion_condition( - // Result of latest async_read_some operation. + void handler( + // Result of operation. const boost::system::error_code& error, - // Number of bytes transferred so far. + // Number of bytes copied into the buffers. If an error + // occurred, this will be the number of bytes successfully + // transferred prior to the error. std::size_t bytes_transferred ); `` -A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the stream's async\_read\_some function.]] - -[[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: -`` - void handler( - const boost::system::error_code& error, // Result of operation. - - std::size_t bytes_transferred // Number of bytes copied into the - // buffers. If an error occurred, - // this will be the number of - // bytes successfully transferred - // prior to the error. - ); -`` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] -[heading Per-Operation Cancellation] +[heading Completion Signature] -This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: - - -* `cancellation_type::terminal` - - -* `cancellation_type::partial` - -if they are also supported by the `AsyncReadStream` type's `async_read_some` operation. - - -[endsect] - - - -[section:overload7 async_read (7 of 8 overloads)] - - -Start an asynchronous operation to read a certain amount of data from a stream. - - - template< - typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, - typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> - ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( - AsyncReadStream & s, - DynamicBuffer_v2 buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, - typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); - - -This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: - -* The specified dynamic buffer sequence is full (that is, it has reached maximum size). + void(boost::system::error_code, std::size_t) -* An error occurred. -This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. The program must ensure that the stream performs no other read operations (such as async\_read, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. -[heading Parameters] - - -[variablelist - -[[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] - -[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] - -[[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: -`` - void handler( - const boost::system::error_code& error, // Result of operation. - - std::size_t bytes_transferred // Number of bytes copied into the - // buffers. If an error occurred, - // this will be the number of - // bytes successfully transferred - // prior to the error. - ); -`` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] - -] - [heading Remarks] @@ -3677,16 +4497,16 @@ Start an asynchronous operation to read a certain amount of data from a stream. typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, DynamicBuffer_v2 buffers, CompletionCondition completion_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); -This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read a certain number of bytes of data from a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The specified dynamic buffer sequence is full (that is, it has reached maximum size). @@ -3704,7 +4524,7 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be: `` @@ -3718,23 +4538,33 @@ This operation is implemented in terms of zero or more calls to the stream's asy `` A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the stream's async\_read\_some function.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes copied into the - // buffers. If an error occurred, - // this will be the number of - // bytes successfully transferred - // prior to the error. + // Number of bytes copied into the buffers. If an error + // occurred, this will be the number of bytes successfully + // transferred prior to the error. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -3755,7 +4585,8 @@ if they are also supported by the `AsyncReadStream` type's `async_read_some` ope [section:async_read_at async_read_at] -[indexterm1 boost_asio.indexterm.async_read_at..async_read_at] +[indexterm1 boost_asio.indexterm.async_read_at..async_read_at] + The `async_read_at` function is a composed asynchronous operation that reads a certain amount of data at the specified offset. @@ -3764,49 +4595,49 @@ Start an asynchronous operation to read a certain amount of data at the specifie template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_at.overload1 async_read_at]``( AsyncRandomAccessReadDevice & d, uint64_t offset, const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_at.overload1 more...]]`` template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_at.overload2 async_read_at]``( AsyncRandomAccessReadDevice & d, uint64_t offset, const MutableBufferSequence & buffers, CompletionCondition completion_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_at.overload2 more...]]`` template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename Allocator, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_at.overload3 async_read_at]``( AsyncRandomAccessReadDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_at.overload3 more...]]`` template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_at.overload4 async_read_at]``( AsyncRandomAccessReadDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_at.overload4 more...]]`` [heading Requirements] @@ -3825,15 +4656,15 @@ Start an asynchronous operation to read a certain amount of data at the specifie template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_at( AsyncRandomAccessReadDevice & d, uint64_t offset, const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes. @@ -3853,9 +4684,9 @@ This operation is implemented in terms of zero or more calls to the device's asy [[offset][The offset at which the data will be read.]] -[[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the device. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the device. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -3867,19 +4698,29 @@ This operation is implemented in terms of zero or more calls to the device's asy std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_read_at(d, 42, boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Remarks] @@ -3922,16 +4763,16 @@ Start an asynchronous operation to read a certain amount of data at the specifie typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_at( AsyncRandomAccessReadDevice & d, uint64_t offset, const MutableBufferSequence & buffers, CompletionCondition completion_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes. @@ -3949,7 +4790,7 @@ This function is used to asynchronously read a certain number of bytes of data f [[offset][The offset at which the data will be read.]] -[[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the device. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the device. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be: `` @@ -3963,7 +4804,7 @@ This function is used to asynchronously read a certain number of bytes of data f `` A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the device's async\_read\_some\_at function.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -3975,14 +4816,24 @@ A return value of 0 indicates that the read operation is complete. A non-zero re std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_read_at(d, 42, boost::asio::buffer(data, size), @@ -3990,7 +4841,7 @@ To read into a single data buffer use the [link boost_asio.reference.buffer `buf handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -4019,15 +4870,15 @@ Start an asynchronous operation to read a certain amount of data at the specifie template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename Allocator, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_at( AsyncRandomAccessReadDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * An error occurred. @@ -4044,9 +4895,9 @@ This operation is implemented in terms of zero or more calls to the device's asy [[offset][The offset at which the data will be read.]] -[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] +[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -4058,11 +4909,21 @@ This operation is implemented in terms of zero or more calls to the device's asy std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] This overload is equivalent to calling: @@ -4103,16 +4964,16 @@ Start an asynchronous operation to read a certain amount of data at the specifie typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_at( AsyncRandomAccessReadDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The completion\_condition function object returns 0. @@ -4129,7 +4990,7 @@ This operation is implemented in terms of zero or more calls to the device's asy [[offset][The offset at which the data will be read.]] -[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] +[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the completion handler is called.]] [[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be: `` @@ -4143,7 +5004,7 @@ This operation is implemented in terms of zero or more calls to the device's asy `` A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the device's async\_read\_some\_at function.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -4155,11 +5016,21 @@ A return value of 0 indicates that the read operation is complete. A non-zero re std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -4180,7 +5051,8 @@ if they are also supported by the `AsyncRandomAccessReadDevice` type's async\_re [section:async_read_until async_read_until] -[indexterm1 boost_asio.indexterm.async_read_until..async_read_until] +[indexterm1 boost_asio.indexterm.async_read_until..async_read_until] + The `async_read_until` function is a composed asynchronous operation that reads data into a dynamic buffer sequence, or into a streambuf, until it contains a delimiter, matches a regular expression, or a function object indicates a match. @@ -4189,12 +5061,12 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload1 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v1 && buffers, char delim, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload1 more...]]`` @@ -4202,12 +5074,12 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload2 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v1 && buffers, string_view delim, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload2 more...]]`` @@ -4217,12 +5089,12 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload3 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v1 && buffers, const boost::regex & expr, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload3 more...]]`` @@ -4233,12 +5105,12 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename MatchCondition, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload4 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v1 && buffers, MatchCondition match_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_match_condition< MatchCondition >::value >::type = 0, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); @@ -4249,23 +5121,23 @@ Start an asynchronous operation to read data into a streambuf until it contains template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload5 async_read_until]``( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, char delim, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_until.overload5 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload6 async_read_until]``( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, string_view delim, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_until.overload6 more...]]`` Start an asynchronous operation to read data into a streambuf until some part of its data matches a regular expression. @@ -4273,12 +5145,12 @@ Start an asynchronous operation to read data into a streambuf until some part of template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload7 async_read_until]``( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, const boost::regex & expr, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_until.overload7 more...]]`` Start an asynchronous operation to read data into a streambuf until a function object indicates a match. @@ -4287,12 +5159,12 @@ Start an asynchronous operation to read data into a streambuf until a function o typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename MatchCondition, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload8 async_read_until]``( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, MatchCondition match_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_match_condition< MatchCondition >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload8 more...]]`` @@ -4301,24 +5173,24 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload9 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v2 buffers, char delim, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload9 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload10 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v2 buffers, string_view delim, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload10 more...]]`` @@ -4327,12 +5199,12 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload11 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v2 buffers, const boost::regex & expr, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload11 more...]]`` @@ -4342,12 +5214,12 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename MatchCondition, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload12 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v2 buffers, MatchCondition match_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_match_condition< MatchCondition >::value >::type = 0, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload12 more...]]`` @@ -4368,17 +5240,17 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v1 && buffers, char delim, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); -This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains the specified delimiter. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The get area of the dynamic buffer sequence contains the specified delimiter. @@ -4396,11 +5268,11 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[delim][The delimiter character.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -4408,15 +5280,24 @@ This operation is implemented in terms of zero or more calls to the stream's asy // The number of bytes in the dynamic buffer sequence's // get area up to and including the delimiter. - // 0 if an error occurred. std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond the delimiter. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. @@ -4485,17 +5366,17 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v1 && buffers, string_view delim, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); -This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains the specified delimiter. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The get area of the dynamic buffer sequence contains the specified delimiter. @@ -4513,11 +5394,11 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[delim][The delimiter string.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -4525,15 +5406,24 @@ This operation is implemented in terms of zero or more calls to the stream's asy // The number of bytes in the dynamic buffer sequence's // get area up to and including the delimiter. - // 0 if an error occurred. std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond the delimiter. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. @@ -4602,17 +5492,17 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v1 && buffers, const boost::regex & expr, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); -This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains some data that matches a regular expression. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains some data that matches a regular expression. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * A substring of the dynamic buffer sequence's get area matches the regular expression. @@ -4630,11 +5520,11 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[expr][The regular expression.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -4647,11 +5537,21 @@ This operation is implemented in terms of zero or more calls to the stream's asy std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond that which matched the regular expression. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. @@ -4722,18 +5622,18 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename MatchCondition, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v1 && buffers, MatchCondition match_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_match_condition< MatchCondition >::value >::type = 0, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); -This function is used to asynchronously read data into the specified dynamic buffer sequence until a user-defined match condition function object, when applied to the data contained in the dynamic buffer sequence, indicates a successful match. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read data into the specified dynamic buffer sequence until a user-defined match condition function object, when applied to the data contained in the dynamic buffer sequence, indicates a successful match. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The match condition function object returns a std::pair where the second element evaluates to true. @@ -4751,7 +5651,7 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[match_condition][The function object to be called to determine whether a match exists. The signature of the function object must be: `` @@ -4763,7 +5663,7 @@ where `iterator` represents the type: `` The iterator parameters `begin` and `end` define the range of bytes to be scanned to determine whether there is a match. The `first` member of the return value is an iterator marking one-past-the-end of the bytes that have been consumed by the match function. This iterator is used to calculate the `begin` parameter for any subsequent invocation of the match condition. The `second` member of the return value is true if a match has been found, false otherwise.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -4775,7 +5675,7 @@ The iterator parameters `begin` and `end` define the range of bytes to be scanne std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] @@ -4784,6 +5684,19 @@ Regardless of whether the asynchronous operation completes immediately or not, t After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond that which matched the function object. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. + +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + +[heading Remarks] + The default implementation of the `is_match_condition` type trait evaluates to true for function pointers and function objects with a `result_type` typedef. It must be specialised for other user-defined function objects. @@ -4874,15 +5787,15 @@ Start an asynchronous operation to read data into a streambuf until it contains template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, char delim, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains the specified delimiter. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The get area of the streambuf contains the specified delimiter. @@ -4900,11 +5813,11 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[b][A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] +[[b][A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the completion handler is called.]] [[delim][The delimiter character.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -4916,11 +5829,21 @@ This operation is implemented in terms of zero or more calls to the stream's asy std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] After a successful async\_read\_until operation, the streambuf may contain additional data beyond the delimiter. An application will typically leave that data in the streambuf for a subsequent async\_read\_until operation to examine. @@ -4990,15 +5913,15 @@ Start an asynchronous operation to read data into a streambuf until it contains template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, string_view delim, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains the specified delimiter. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The get area of the streambuf contains the specified delimiter. @@ -5016,11 +5939,11 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[b][A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] +[[b][A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the completion handler is called.]] [[delim][The delimiter string.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -5032,11 +5955,21 @@ This operation is implemented in terms of zero or more calls to the stream's asy std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] After a successful async\_read\_until operation, the streambuf may contain additional data beyond the delimiter. An application will typically leave that data in the streambuf for a subsequent async\_read\_until operation to examine. @@ -5106,15 +6039,15 @@ Start an asynchronous operation to read data into a streambuf until some part of template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, const boost::regex & expr, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains some data that matches a regular expression. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains some data that matches a regular expression. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * A substring of the streambuf's get area matches the regular expression. @@ -5132,11 +6065,11 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[b][A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] +[[b][A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the completion handler is called.]] [[expr][The regular expression.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -5149,11 +6082,21 @@ This operation is implemented in terms of zero or more calls to the stream's asy std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] After a successful async\_read\_until operation, the streambuf may contain additional data beyond that which matched the regular expression. An application will typically leave that data in the streambuf for a subsequent async\_read\_until operation to examine. @@ -5224,16 +6167,16 @@ Start an asynchronous operation to read data into a streambuf until a function o typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename MatchCondition, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, MatchCondition match_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_match_condition< MatchCondition >::value >::type = 0); -This function is used to asynchronously read data into the specified streambuf until a user-defined match condition function object, when applied to the data contained in the streambuf, indicates a successful match. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read data into the specified streambuf until a user-defined match condition function object, when applied to the data contained in the streambuf, indicates a successful match. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The match condition function object returns a std::pair where the second element evaluates to true. @@ -5263,7 +6206,7 @@ where `iterator` represents the type: `` The iterator parameters `begin` and `end` define the range of bytes to be scanned to determine whether there is a match. The `first` member of the return value is an iterator marking one-past-the-end of the bytes that have been consumed by the match function. This iterator is used to calculate the `begin` parameter for any subsequent invocation of the match condition. The `second` member of the return value is true if a match has been found, false otherwise.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -5275,7 +6218,7 @@ The iterator parameters `begin` and `end` define the range of bytes to be scanne std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] @@ -5284,6 +6227,19 @@ Regardless of whether the asynchronous operation completes immediately or not, t After a successful async\_read\_until operation, the streambuf may contain additional data beyond that which matched the function object. An application will typically leave that data in the streambuf for a subsequent async\_read\_until operation to examine. + +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + +[heading Remarks] + The default implementation of the `is_match_condition` type trait evaluates to true for function pointers and function objects with a `result_type` typedef. It must be specialised for other user-defined function objects. @@ -5374,16 +6330,16 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v2 buffers, char delim, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); -This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains the specified delimiter. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The get area of the dynamic buffer sequence contains the specified delimiter. @@ -5401,11 +6357,11 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[delim][The delimiter character.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -5417,11 +6373,21 @@ This operation is implemented in terms of zero or more calls to the stream's asy std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond the delimiter. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. @@ -5490,16 +6456,16 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v2 buffers, string_view delim, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); -This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains the specified delimiter. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The get area of the dynamic buffer sequence contains the specified delimiter. @@ -5517,11 +6483,11 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[delim][The delimiter string.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -5529,15 +6495,24 @@ This operation is implemented in terms of zero or more calls to the stream's asy // The number of bytes in the dynamic buffer sequence's // get area up to and including the delimiter. - // 0 if an error occurred. std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond the delimiter. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. @@ -5606,16 +6581,16 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v2 buffers, const boost::regex & expr, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); -This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains some data that matches a regular expression. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains some data that matches a regular expression. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * A substring of the dynamic buffer sequence's get area matches the regular expression. @@ -5633,11 +6608,11 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[expr][The regular expression.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -5650,11 +6625,21 @@ This operation is implemented in terms of zero or more calls to the stream's asy std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond that which matched the regular expression. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. @@ -5725,17 +6710,17 @@ Start an asynchronous operation to read data into a dynamic buffer sequence unti typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename MatchCondition, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v2 buffers, MatchCondition match_condition, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_match_condition< MatchCondition >::value >::type = 0, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); -This function is used to asynchronously read data into the specified dynamic buffer sequence until a user-defined match condition function object, when applied to the data contained in the dynamic buffer sequence, indicates a successful match. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously read data into the specified dynamic buffer sequence until a user-defined match condition function object, when applied to the data contained in the dynamic buffer sequence, indicates a successful match. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The match condition function object returns a std::pair where the second element evaluates to true. @@ -5753,7 +6738,7 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] -[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The dynamic buffer sequence into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[match_condition][The function object to be called to determine whether a match exists. The signature of the function object must be: `` @@ -5765,7 +6750,7 @@ where `iterator` represents the type: `` The iterator parameters `begin` and `end` define the range of bytes to be scanned to determine whether there is a match. The `first` member of the return value is an iterator marking one-past-the-end of the bytes that have been consumed by the match function. This iterator is used to calculate the `begin` parameter for any subsequent invocation of the match condition. The `second` member of the return value is true if a match has been found, false otherwise.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -5777,7 +6762,7 @@ The iterator parameters `begin` and `end` define the range of bytes to be scanne std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] @@ -5786,6 +6771,19 @@ Regardless of whether the asynchronous operation completes immediately or not, t After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond that which matched the function object. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. + +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + +[heading Remarks] + The default implementation of the `is_match_condition` type trait evaluates to true for function pointers and function objects with a `result_type` typedef. It must be specialised for other user-defined function objects. @@ -6174,7 +7172,8 @@ The return type of the initiating function is the future obtained from the packa [section:async_write async_write] -[indexterm1 boost_asio.indexterm.async_write..async_write] +[indexterm1 boost_asio.indexterm.async_write..async_write] + The `async_write` function is a composed asynchronous operation that writes a certain amount of data to a stream before completion. @@ -6183,11 +7182,11 @@ Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload1 async_write]``( AsyncWriteStream & s, const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_const_buffer_sequence< ConstBufferSequence >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_write.overload1 more...]]`` @@ -6197,12 +7196,12 @@ Start an asynchronous operation to write a certain amount of data to a stream. typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload2 async_write]``( AsyncWriteStream & s, const ConstBufferSequence & buffers, CompletionCondition completion_condition, - WriteHandler && handler, + WriteToken && token, typename constraint< is_const_buffer_sequence< ConstBufferSequence >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_write.overload2 more...]]`` @@ -6211,11 +7210,11 @@ Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload3 async_write]``( AsyncWriteStream & s, DynamicBuffer_v1 && buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_write.overload3 more...]]`` @@ -6226,12 +7225,12 @@ Start an asynchronous operation to write a certain amount of data to a stream. typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload4 async_write]``( AsyncWriteStream & s, DynamicBuffer_v1 && buffers, CompletionCondition completion_condition, - WriteHandler && handler, + WriteToken && token, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_write.overload4 more...]]`` @@ -6241,11 +7240,11 @@ Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename Allocator, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload5 async_write]``( AsyncWriteStream & s, basic_streambuf< Allocator > & b, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_write.overload5 more...]]`` Start an asynchronous operation to write a certain amount of data to a stream. @@ -6254,12 +7253,12 @@ Start an asynchronous operation to write a certain amount of data to a stream. typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload6 async_write]``( AsyncWriteStream & s, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, - WriteHandler && handler); + WriteToken && token); `` [''''»''' [link boost_asio.reference.async_write.overload6 more...]]`` Start an asynchronous operation to write all of the supplied data to a stream. @@ -6267,11 +7266,11 @@ Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload7 async_write]``( AsyncWriteStream & s, DynamicBuffer_v2 buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_write.overload7 more...]]`` @@ -6281,12 +7280,12 @@ Start an asynchronous operation to write a certain amount of data to a stream. typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload8 async_write]``( AsyncWriteStream & s, DynamicBuffer_v2 buffers, CompletionCondition completion_condition, - WriteHandler && handler, + WriteToken && token, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); `` [''''»''' [link boost_asio.reference.async_write.overload8 more...]]`` @@ -6306,15 +7305,15 @@ Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_const_buffer_sequence< ConstBufferSequence >::value >::type = 0); -This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously write a certain number of bytes of data to a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes. @@ -6332,32 +7331,42 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] -[[buffers][One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes written from the - // buffers. If an error occurred, - // this will be less than the sum - // of the buffer sizes. + // Number of bytes written from the buffers. If an error + // occurred, this will be less than the sum of the buffer sizes. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_write(s, boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -6387,16 +7396,16 @@ Start an asynchronous operation to write a certain amount of data to a stream. typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, const ConstBufferSequence & buffers, CompletionCondition completion_condition, - WriteHandler && handler, + WriteToken && token, typename constraint< is_const_buffer_sequence< ConstBufferSequence >::value >::type = 0); -This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously write a certain number of bytes of data to a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes. @@ -6414,7 +7423,7 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] -[[buffers][One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be: `` @@ -6428,25 +7437,35 @@ This operation is implemented in terms of zero or more calls to the stream's asy `` A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the stream's async\_write\_some function.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes written from the - // buffers. If an error occurred, - // this will be less than the sum - // of the buffer sizes. + // Number of bytes written from the buffers. If an error + // occurred, this will be less than the sum of the buffer sizes. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_write(s, boost::asio::buffer(data, size), @@ -6454,7 +7473,7 @@ To write a single data buffer use the [link boost_asio.reference.buffer `buffer` handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -6483,16 +7502,16 @@ Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, DynamicBuffer_v1 && buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); -This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously write a certain number of bytes of data to a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied dynamic buffer sequence has been written. @@ -6510,24 +7529,34 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] -[[buffers][The dynamic buffer sequence from which data will be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called. Successfully written data is automatically consumed from the buffers.]] +[[buffers][The dynamic buffer sequence from which data will be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called. Successfully written data is automatically consumed from the buffers.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes written from the - // buffers. If an error occurred, - // this will be less than the sum - // of the buffer sizes. + // Number of bytes written from the buffers. If an error + // occurred, this will be less than the sum of the buffer sizes. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -6555,17 +7584,17 @@ Start an asynchronous operation to write a certain amount of data to a stream. typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, DynamicBuffer_v1 && buffers, CompletionCondition completion_condition, - WriteHandler && handler, + WriteToken && token, typename constraint< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0, typename constraint< !is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type = 0); -This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously write a certain number of bytes of data to a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied dynamic buffer sequence has been written. @@ -6583,7 +7612,7 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] -[[buffers][The dynamic buffer sequence from which data will be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called. Successfully written data is automatically consumed from the buffers.]] +[[buffers][The dynamic buffer sequence from which data will be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called. Successfully written data is automatically consumed from the buffers.]] [[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be: `` @@ -6597,22 +7626,32 @@ This operation is implemented in terms of zero or more calls to the stream's asy `` A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the stream's async\_write\_some function.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes written from the - // buffers. If an error occurred, - // this will be less than the sum - // of the buffer sizes. + // Number of bytes written from the buffers. If an error + // occurred, this will be less than the sum of the buffer sizes. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -6639,14 +7678,14 @@ Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename Allocator, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, basic_streambuf< Allocator > & b, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously write a certain number of bytes of data to a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied [link boost_asio.reference.basic_streambuf `basic_streambuf`] has been written. @@ -6664,24 +7703,34 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] -[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] +[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes written from the - // buffers. If an error occurred, - // this will be less than the sum - // of the buffer sizes. + // Number of bytes written from the buffers. If an error + // occurred, this will be less than the sum of the buffer sizes. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -6709,15 +7758,15 @@ Start an asynchronous operation to write a certain amount of data to a stream. typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, - WriteHandler && handler); + WriteToken && token); -This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously write a certain number of bytes of data to a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied [link boost_asio.reference.basic_streambuf `basic_streambuf`] has been written. @@ -6735,7 +7784,7 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] -[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] +[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the completion handler is called.]] [[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be: `` @@ -6749,22 +7798,32 @@ This operation is implemented in terms of zero or more calls to the stream's asy `` A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the stream's async\_write\_some function.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes written from the - // buffers. If an error occurred, - // this will be less than the sum - // of the buffer sizes. + // Number of bytes written from the buffers. If an error + // occurred, this will be less than the sum of the buffer sizes. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -6791,15 +7850,15 @@ Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, DynamicBuffer_v2 buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); -This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously write a certain number of bytes of data to a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied dynamic buffer sequence has been written. @@ -6817,24 +7876,34 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] -[[buffers][The dynamic buffer sequence from which data will be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called. Successfully written data is automatically consumed from the buffers.]] +[[buffers][The dynamic buffer sequence from which data will be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called. Successfully written data is automatically consumed from the buffers.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes written from the - // buffers. If an error occurred, - // this will be less than the sum - // of the buffer sizes. + // Number of bytes written from the buffers. If an error + // occurred, this will be less than the sum of the buffer sizes. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -6862,16 +7931,16 @@ Start an asynchronous operation to write a certain amount of data to a stream. typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, DynamicBuffer_v2 buffers, CompletionCondition completion_condition, - WriteHandler && handler, + WriteToken && token, typename constraint< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type = 0); -This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously write a certain number of bytes of data to a stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied dynamic buffer sequence has been written. @@ -6889,7 +7958,7 @@ This operation is implemented in terms of zero or more calls to the stream's asy [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] -[[buffers][The dynamic buffer sequence from which data will be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called. Successfully written data is automatically consumed from the buffers.]] +[[buffers][The dynamic buffer sequence from which data will be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called. Successfully written data is automatically consumed from the buffers.]] [[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be: `` @@ -6903,22 +7972,32 @@ This operation is implemented in terms of zero or more calls to the stream's asy `` A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the stream's async\_write\_some function.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error, // Result of operation. + // Result of operation. + const boost::system::error_code& error, - std::size_t bytes_transferred // Number of bytes written from the - // buffers. If an error occurred, - // this will be less than the sum - // of the buffer sizes. + // Number of bytes written from the buffers. If an error + // occurred, this will be less than the sum of the buffer sizes. + std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -6939,7 +8018,8 @@ if they are also supported by the `AsyncWriteStream` type's `async_write_some` o [section:async_write_at async_write_at] -[indexterm1 boost_asio.indexterm.async_write_at..async_write_at] +[indexterm1 boost_asio.indexterm.async_write_at..async_write_at] + The `async_write_at` function is a composed asynchronous operation that writes a certain amount of data at the specified offset before completion. @@ -6948,12 +8028,12 @@ Start an asynchronous operation to write all of the supplied data at the specifi template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write_at.overload1 async_write_at]``( AsyncRandomAccessWriteDevice & d, uint64_t offset, const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_write_at.overload1 more...]]`` Start an asynchronous operation to write a certain amount of data at the specified offset. @@ -6962,13 +8042,13 @@ Start an asynchronous operation to write a certain amount of data at the specifi typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write_at.overload2 async_write_at]``( AsyncRandomAccessWriteDevice & d, uint64_t offset, const ConstBufferSequence & buffers, CompletionCondition completion_condition, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_write_at.overload2 more...]]`` Start an asynchronous operation to write all of the supplied data at the specified offset. @@ -6976,12 +8056,12 @@ Start an asynchronous operation to write all of the supplied data at the specifi template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename Allocator, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write_at.overload3 async_write_at]``( AsyncRandomAccessWriteDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_write_at.overload3 more...]]`` Start an asynchronous operation to write a certain amount of data at the specified offset. @@ -6990,13 +8070,13 @@ Start an asynchronous operation to write a certain amount of data at the specifi typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write_at.overload4 async_write_at]``( AsyncRandomAccessWriteDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_write_at.overload4 more...]]`` [heading Requirements] @@ -7015,15 +8095,15 @@ Start an asynchronous operation to write all of the supplied data at the specifi template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_at( AsyncRandomAccessWriteDevice & d, uint64_t offset, const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes. @@ -7043,9 +8123,9 @@ This operation is implemented in terms of zero or more calls to the device's asy [[offset][The offset at which the data will be written.]] -[[buffers][One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -7056,19 +8136,29 @@ This operation is implemented in terms of zero or more calls to the device's asy std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_write_at(d, 42, boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -7098,16 +8188,16 @@ Start an asynchronous operation to write a certain amount of data at the specifi typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_at( AsyncRandomAccessWriteDevice & d, uint64_t offset, const ConstBufferSequence & buffers, CompletionCondition completion_condition, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes. @@ -7127,7 +8217,7 @@ This operation is implemented in terms of zero or more calls to the device's asy [[offset][The offset at which the data will be written.]] -[[buffers][One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] [[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be: `` @@ -7141,7 +8231,7 @@ This operation is implemented in terms of zero or more calls to the device's asy `` A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the device's async\_write\_some\_at function.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -7152,14 +8242,24 @@ A return value of 0 indicates that the write operation is complete. A non-zero r std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_write_at(d, 42, boost::asio::buffer(data, size), @@ -7167,7 +8267,7 @@ To write a single data buffer use the [link boost_asio.reference.buffer `buffer` handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -7196,15 +8296,15 @@ Start an asynchronous operation to write all of the supplied data at the specifi template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename Allocator, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_at( AsyncRandomAccessWriteDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied [link boost_asio.reference.basic_streambuf `basic_streambuf`] has been written. @@ -7224,9 +8324,9 @@ This operation is implemented in terms of zero or more calls to the device's asy [[offset][The offset at which the data will be written.]] -[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] +[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -7237,11 +8337,21 @@ This operation is implemented in terms of zero or more calls to the device's asy std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -7269,16 +8379,16 @@ Start an asynchronous operation to write a certain amount of data at the specifi typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_at( AsyncRandomAccessWriteDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: +This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied [link boost_asio.reference.basic_streambuf `basic_streambuf`] has been written. @@ -7298,7 +8408,7 @@ This operation is implemented in terms of zero or more calls to the device's asy [[offset][The offset at which the data will be written.]] -[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] +[[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the completion handler is called.]] [[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be: `` @@ -7312,7 +8422,7 @@ This operation is implemented in terms of zero or more calls to the device's asy `` A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the device's async\_write\_some\_at function.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( // Result of operation. @@ -7323,11 +8433,21 @@ A return value of 0 indicates that the write operation is complete. A non-zero r std::size_t bytes_transferred ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -7490,7 +8610,7 @@ The executor type that will be used for the coroutine. Move assignment. - awaitable operator=( + awaitable & operator=( awaitable && other); @@ -8111,13 +9231,13 @@ Start an asynchronous connect. template< - typename ``[link boost_asio.reference.ConnectHandler ConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ConnectToken ConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( const endpoint_type & peer_endpoint, - ConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously connect a socket to the specified remote endpoint. The function call always returns immediately. +This function is used to asynchronously connect a socket to the specified remote endpoint. It is an initiating function for an [link boost_asio.overview.model.async_ops 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 not returned to the closed state. @@ -8129,17 +9249,27 @@ The socket is automatically opened if it is not already open. If the connect fai [[peer_endpoint][The remote endpoint to which the socket will be connected. Copies will be made of the endpoint object as required.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the connect completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error // Result of operation + const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -8190,19 +9320,19 @@ Start an asynchronous receive on a connected socket. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_receive.overload1 async_receive]``( const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_receive.overload1 more...]]`` template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_receive.overload2 async_receive]``( const MutableBufferSequence & buffers, socket_base::message_flags flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_receive.overload2 more...]]`` @@ -8214,13 +9344,13 @@ Start an asynchronous receive on a connected socket. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive( const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously receive data from the datagram socket. The function call always returns immediately. +This function is used to asynchronously receive data from the datagram socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -8228,20 +9358,30 @@ This function is used to asynchronously receive data from the datagram socket. T [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the receive completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] 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. @@ -8249,12 +9389,12 @@ The async\_receive operation can only be used with a connected socket. Use the a [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_receive(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -8285,14 +9425,14 @@ Start an asynchronous receive on a connected socket. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive( const MutableBufferSequence & buffers, socket_base::message_flags flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously receive data from the datagram socket. The function call always returns immediately. +This function is used to asynchronously receive data from the datagram socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -8300,22 +9440,32 @@ This function is used to asynchronously receive data from the datagram socket. T [variablelist -[[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.]] +[[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 completion handler is called.]] [[flags][Flags specifying how the receive call is to be made.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the receive completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] 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. @@ -8350,21 +9500,21 @@ Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_receive_from.overload1 async_receive_from]``( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_receive_from.overload1 more...]]`` template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_receive_from.overload2 async_receive_from]``( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, socket_base::message_flags flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_receive_from.overload2 more...]]`` @@ -8376,14 +9526,14 @@ Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive_from( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -8391,31 +9541,41 @@ This function is used to asynchronously receive a datagram. The function call al [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the receive completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_receive_from( boost::asio::buffer(data, size), sender_endpoint, handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -8446,15 +9606,15 @@ Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive_from( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, socket_base::message_flags flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -8462,24 +9622,34 @@ This function is used to asynchronously receive a datagram. The function call al [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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.]] +[[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 completion handler is called.]] [[flags][Flags specifying how the receive call is to be made.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the receive completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] On POSIX or Windows operating systems, this asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -8509,19 +9679,19 @@ Start an asynchronous send on a connected socket. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_send.overload1 async_send]``( const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_send.overload1 more...]]`` template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_send.overload2 async_send]``( const ConstBufferSequence & buffers, socket_base::message_flags flags, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_send.overload2 more...]]`` @@ -8533,13 +9703,13 @@ Start an asynchronous send on a connected socket. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send( const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously send data on the datagram socket. The function call always returns immediately. +This function is used to asynchronously send data on the datagram socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -8547,20 +9717,30 @@ This function is used to asynchronously send data on the datagram socket. The fu [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the send completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] 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. @@ -8568,12 +9748,12 @@ The async\_send operation can only be used with a connected socket. Use the asyn [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_send(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -8604,14 +9784,14 @@ Start an asynchronous send on a connected socket. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send( const ConstBufferSequence & buffers, socket_base::message_flags flags, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously send data on the datagram socket. The function call always returns immediately. +This function is used to asynchronously send data on the datagram socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -8619,22 +9799,32 @@ This function is used to asynchronously send data on the datagram socket. The fu [variablelist -[[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.]] +[[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 completion handler is called.]] [[flags][Flags specifying how the send call is to be made.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the send completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] 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. @@ -8669,21 +9859,21 @@ Start an asynchronous send. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_send_to.overload1 async_send_to]``( const ConstBufferSequence & buffers, const endpoint_type & destination, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_send_to.overload1 more...]]`` template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_send_to.overload2 async_send_to]``( const ConstBufferSequence & buffers, const endpoint_type & destination, socket_base::message_flags flags, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_send_to.overload2 more...]]`` @@ -8695,14 +9885,14 @@ Start an asynchronous send. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send_to( const ConstBufferSequence & buffers, const endpoint_type & destination, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously send a datagram to the specified remote endpoint. The function call always returns immediately. +This function is used to asynchronously send a datagram to the specified remote endpoint. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -8710,25 +9900,35 @@ This function is used to asynchronously send a datagram to the specified remote [variablelist -[[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.]] +[[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 completion handler is called.]] [[destination][The remote endpoint to which the data will be sent. Copies will be made of the endpoint as required.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the send completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::ip::udp::endpoint destination( boost::asio::ip::address::from_string("1.2.3.4"), 12345); @@ -8736,7 +9936,7 @@ To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] boost::asio::buffer(data, size), destination, handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -8767,15 +9967,15 @@ Start an asynchronous send. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send_to( const ConstBufferSequence & buffers, const endpoint_type & destination, socket_base::message_flags flags, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously send a datagram to the specified remote endpoint. The function call always returns immediately. +This function is used to asynchronously send a datagram to the specified remote endpoint. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -8783,24 +9983,34 @@ This function is used to asynchronously send a datagram to the specified remote [variablelist -[[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.]] +[[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 completion handler is called.]] [[flags][Flags specifying how the send call is to be made.]] [[destination][The remote endpoint to which the data will be sent. Copies will be made of the endpoint as required.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the send completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] On POSIX or Windows operating systems, this asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -8833,13 +10043,13 @@ Asynchronously wait for the socket to become ready to read, ready to write, or t template< - typename ``[link boost_asio.reference.WaitHandler WaitHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WaitToken WaitToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_wait( wait_type w, - WaitHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WaitToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to perform an asynchronous wait for a socket to enter a ready to read, write or error condition state. +This function is used to perform an asynchronous wait for a socket to enter a ready to read, write or error condition state. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -8849,17 +10059,27 @@ This function is used to perform an asynchronous wait for a socket to enter a re [[w][Specifies the desired socket state.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the wait completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error // Result of operation + const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -12363,12 +13583,12 @@ The receive operation can only be used with a connected socket. Use the receive\ [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.receive(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -12609,14 +13829,14 @@ The number of bytes received. [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::ip::udp::endpoint sender_endpoint; socket.receive_from( boost::asio::buffer(data, size), sender_endpoint); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -13111,12 +14331,12 @@ The send operation can only be used with a connected socket. Use the send\_to fu [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.send(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -13411,14 +14631,14 @@ The number of bytes sent. [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::ip::udp::endpoint destination( boost::asio::ip::address::from_string("1.2.3.4"), 12345); socket.send_to(boost::asio::buffer(data, size), destination); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -14685,14 +15905,14 @@ Start an asynchronous wait on the timer. template< - typename ``[link boost_asio.reference.WaitHandler WaitHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WaitToken WaitToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_wait( - WaitHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WaitToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function may be used to initiate an asynchronous wait against the timer. It always returns immediately. +This function may be used to initiate an asynchronous wait against the timer. It is an initiating function for an [link boost_asio.overview.model.async_ops 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: * The timer has expired. @@ -14706,20 +15926,30 @@ For each call to `async_wait()`, the supplied handler will be called exactly onc [variablelist -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the timer expires. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Per-Operation Cancellation] -On POSIX or Windows operating systems, this asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: +This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: * `cancellation_type::terminal` @@ -16191,6 +17421,11 @@ Provides file functionality. [Open the file for reading and writing. ] ] + [ + [[link boost_asio.reference.basic_file.sync_all_on_write [*sync_all_on_write]] [static]] + [Open the file so that write operations automatically synchronise the file data and metadata to disk. ] + ] + [ [[link boost_asio.reference.basic_file.truncate [*truncate]] [static]] [Open the file with any existing contents truncated. ] @@ -17792,6 +19027,23 @@ This function synchronises the file data and metadata to disk. Note that the sem [endsect] + +[section:sync_all_on_write basic_file::sync_all_on_write] + + +['Inherited from file_base.] + +[indexterm2 boost_asio.indexterm.basic_file.sync_all_on_write..sync_all_on_write..basic_file] +Open the file so that write operations automatically synchronise the file data and metadata to disk. + + + static const flags sync_all_on_write = implementation_defined; + + + +[endsect] + + [section:sync_data basic_file::sync_data] [indexterm2 boost_asio.indexterm.basic_file.sync_data..sync_data..basic_file] @@ -18128,6 +19380,11 @@ The file type when rebound to the specified executor. [Open the file for reading and writing. ] ] + [ + [[link boost_asio.reference.basic_file.sync_all_on_write [*sync_all_on_write]] [static]] + [Open the file so that write operations automatically synchronise the file data and metadata to disk. ] + ] + [ [[link boost_asio.reference.basic_file.truncate [*truncate]] [static]] [Open the file with any existing contents truncated. ] @@ -18831,6 +20088,11 @@ Provides random-access file functionality. [Open the file for reading and writing. ] ] + [ + [[link boost_asio.reference.basic_random_access_file.sync_all_on_write [*sync_all_on_write]] [static]] + [Open the file so that write operations automatically synchronise the file data and metadata to disk. ] + ] + [ [[link boost_asio.reference.basic_random_access_file.truncate [*truncate]] [static]] [Open the file with any existing contents truncated. ] @@ -18940,14 +20202,14 @@ Start an asynchronous read at the specified offset. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_some_at( uint64_t offset, const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read data from the random-access handle. The function call always returns immediately. +This function is used to asynchronously read data from the random-access handle. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -18957,33 +20219,43 @@ This function is used to asynchronously read data from the random-access handle. [[offset][The offset at which the data will be read.]] -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read_at `async_read_at`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. +The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read_at `async_read_at`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: handle.async_read_some_at(42, boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -19014,14 +20286,14 @@ Start an asynchronous write at the specified offset. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_some_at( uint64_t offset, const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously write data to the random-access handle. The function call always returns immediately. +This function is used to asynchronously write data to the random-access handle. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -19031,33 +20303,43 @@ This function is used to asynchronously write data to the random-access handle. [[offset][The offset at which the data will be written.]] -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The write operation may not write all of the data to the file. Consider using the [link boost_asio.reference.async_write_at `async_write_at`] function if you need to ensure that all data is written before the asynchronous operation completes. +The write operation may not write all of the data to the file. Consider using the [link boost_asio.reference.async_write_at `async_write_at`] function if you need to ensure that all data is written before the asynchronous operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: handle.async_write_some_at(42, boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -20351,17 +21633,17 @@ The number of bytes read. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read_at `read_at`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read_at `read_at`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: handle.read_some_at(42, boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -20408,7 +21690,7 @@ The number of bytes read. Returns 0 if an error occurred. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read_at `read_at`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read_at `read_at`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. @@ -20813,6 +22095,23 @@ This function synchronises the file data and metadata to disk. Note that the sem [endsect] + +[section:sync_all_on_write basic_random_access_file::sync_all_on_write] + + +['Inherited from file_base.] + +[indexterm2 boost_asio.indexterm.basic_random_access_file.sync_all_on_write..sync_all_on_write..basic_random_access_file] +Open the file so that write operations automatically synchronise the file data and metadata to disk. + + + static const flags sync_all_on_write = implementation_defined; + + + +[endsect] + + [section:sync_data basic_random_access_file::sync_data] [indexterm2 boost_asio.indexterm.basic_random_access_file.sync_data..sync_data..basic_random_access_file] @@ -20992,17 +22291,17 @@ The number of bytes written. [heading Remarks] -The write\_some\_at operation may not write all of the data. Consider using the [link boost_asio.reference.write_at `write_at`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some\_at operation may not write all of the data. Consider using the [link boost_asio.reference.write_at `write_at`] function if you need to ensure that all data is written before the blocking operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: handle.write_some_at(42, boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -21049,7 +22348,7 @@ The number of bytes written. Returns 0 if an error occurred. [heading Remarks] -The write\_some operation may not write all of the data to the file. Consider using the [link boost_asio.reference.write_at `write_at`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not write all of the data to the file. Consider using the [link boost_asio.reference.write_at `write_at`] function if you need to ensure that all data is written before the blocking operation completes. @@ -21301,6 +22600,11 @@ The file type when rebound to the specified executor. [Open the file for reading and writing. ] ] + [ + [[link boost_asio.reference.basic_random_access_file.sync_all_on_write [*sync_all_on_write]] [static]] + [Open the file so that write operations automatically synchronise the file data and metadata to disk. ] + ] + [ [[link boost_asio.reference.basic_random_access_file.truncate [*truncate]] [static]] [Open the file with any existing contents truncated. ] @@ -21834,13 +23138,13 @@ Start an asynchronous connect. template< - typename ``[link boost_asio.reference.ConnectHandler ConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ConnectToken ConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( const endpoint_type & peer_endpoint, - ConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously connect a socket to the specified remote endpoint. The function call always returns immediately. +This function is used to asynchronously connect a socket to the specified remote endpoint. It is an initiating function for an [link boost_asio.overview.model.async_ops 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 not returned to the closed state. @@ -21852,17 +23156,27 @@ The socket is automatically opened if it is not already open. If the connect fai [[peer_endpoint][The remote endpoint to which the socket will be connected. Copies will be made of the endpoint object as required.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the connect completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error // Result of operation + const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -21913,19 +23227,19 @@ Start an asynchronous receive on a connected socket. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_raw_socket.async_receive.overload1 async_receive]``( const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_raw_socket.async_receive.overload1 more...]]`` template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_raw_socket.async_receive.overload2 async_receive]``( const MutableBufferSequence & buffers, socket_base::message_flags flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_raw_socket.async_receive.overload2 more...]]`` @@ -21937,13 +23251,13 @@ Start an asynchronous receive on a connected socket. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive( const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously receive data from the raw socket. The function call always returns immediately. +This function is used to asynchronously receive data from the raw socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -21951,20 +23265,30 @@ This function is used to asynchronously receive data from the raw socket. The fu [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the receive completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] 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. @@ -21972,12 +23296,12 @@ The async\_receive operation can only be used with a connected socket. Use the a [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_receive(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -22008,14 +23332,14 @@ Start an asynchronous receive on a connected socket. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive( const MutableBufferSequence & buffers, socket_base::message_flags flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously receive data from the raw socket. The function call always returns immediately. +This function is used to asynchronously receive data from the raw socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -22023,22 +23347,32 @@ This function is used to asynchronously receive data from the raw socket. The fu [variablelist -[[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.]] +[[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 completion handler is called.]] [[flags][Flags specifying how the receive call is to be made.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the receive completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] 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. @@ -22073,21 +23407,21 @@ Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_raw_socket.async_receive_from.overload1 async_receive_from]``( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_raw_socket.async_receive_from.overload1 more...]]`` template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_raw_socket.async_receive_from.overload2 async_receive_from]``( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, socket_base::message_flags flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_raw_socket.async_receive_from.overload2 more...]]`` @@ -22099,14 +23433,14 @@ Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive_from( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -22114,31 +23448,41 @@ This function is used to asynchronously receive raw data. The function call alwa [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the receive completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_receive_from( boost::asio::buffer(data, size), 0, sender_endpoint, handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -22169,15 +23513,15 @@ Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive_from( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, socket_base::message_flags flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -22185,24 +23529,34 @@ This function is used to asynchronously receive raw data. The function call alwa [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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.]] +[[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 completion handler is called.]] [[flags][Flags specifying how the receive call is to be made.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the receive completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] On POSIX or Windows operating systems, this asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -22232,19 +23586,19 @@ Start an asynchronous send on a connected socket. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_raw_socket.async_send.overload1 async_send]``( const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_raw_socket.async_send.overload1 more...]]`` template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_raw_socket.async_send.overload2 async_send]``( const ConstBufferSequence & buffers, socket_base::message_flags flags, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_raw_socket.async_send.overload2 more...]]`` @@ -22256,13 +23610,13 @@ Start an asynchronous send on a connected socket. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send( const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -22270,20 +23624,30 @@ This function is used to send data on the raw socket. The function call will blo [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the send completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] 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. @@ -22291,12 +23655,12 @@ The async\_send operation can only be used with a connected socket. Use the asyn [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_send(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -22327,14 +23691,14 @@ Start an asynchronous send on a connected socket. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send( const ConstBufferSequence & buffers, socket_base::message_flags flags, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -22342,22 +23706,32 @@ This function is used to send data on the raw socket. The function call will blo [variablelist -[[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.]] +[[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 completion handler is called.]] [[flags][Flags specifying how the send call is to be made.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the send completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] 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. @@ -22392,21 +23766,21 @@ Start an asynchronous send. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_raw_socket.async_send_to.overload1 async_send_to]``( const ConstBufferSequence & buffers, const endpoint_type & destination, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_raw_socket.async_send_to.overload1 more...]]`` template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_raw_socket.async_send_to.overload2 async_send_to]``( const ConstBufferSequence & buffers, const endpoint_type & destination, socket_base::message_flags flags, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_raw_socket.async_send_to.overload2 more...]]`` @@ -22418,14 +23792,14 @@ Start an asynchronous send. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send_to( const ConstBufferSequence & buffers, const endpoint_type & destination, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously send raw data to the specified remote endpoint. The function call always returns immediately. +This function is used to asynchronously send raw data to the specified remote endpoint. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -22433,25 +23807,35 @@ This function is used to asynchronously send raw data to the specified remote en [variablelist -[[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.]] +[[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 completion handler is called.]] [[destination][The remote endpoint to which the data will be sent. Copies will be made of the endpoint as required.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the send completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::ip::udp::endpoint destination( boost::asio::ip::address::from_string("1.2.3.4"), 12345); @@ -22459,7 +23843,7 @@ To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] boost::asio::buffer(data, size), destination, handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -22490,15 +23874,15 @@ Start an asynchronous send. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send_to( const ConstBufferSequence & buffers, const endpoint_type & destination, socket_base::message_flags flags, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously send raw data to the specified remote endpoint. The function call always returns immediately. +This function is used to asynchronously send raw data to the specified remote endpoint. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -22506,24 +23890,34 @@ This function is used to asynchronously send raw data to the specified remote en [variablelist -[[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.]] +[[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 completion handler is called.]] [[flags][Flags specifying how the send call is to be made.]] [[destination][The remote endpoint to which the data will be sent. Copies will be made of the endpoint as required.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the send completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] On POSIX or Windows operating systems, this asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -22556,13 +23950,13 @@ Asynchronously wait for the socket to become ready to read, ready to write, or t template< - typename ``[link boost_asio.reference.WaitHandler WaitHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WaitToken WaitToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_wait( wait_type w, - WaitHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WaitToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to perform an asynchronous wait for a socket to enter a ready to read, write or error condition state. +This function is used to perform an asynchronous wait for a socket to enter a ready to read, write or error condition state. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -22572,17 +23966,27 @@ This function is used to perform an asynchronous wait for a socket to enter a re [[w][Specifies the desired socket state.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the wait completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error // Result of operation + const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -26086,12 +27490,12 @@ The receive operation can only be used with a connected socket. Use the receive\ [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.receive(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -26332,14 +27736,14 @@ The number of bytes received. [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::ip::udp::endpoint sender_endpoint; socket.receive_from( boost::asio::buffer(data, size), sender_endpoint); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -26834,12 +28238,12 @@ The send operation can only be used with a connected socket. Use the send\_to fu [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.send(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -27134,14 +28538,14 @@ The number of bytes sent. [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::ip::udp::endpoint destination( boost::asio::ip::address::from_string("1.2.3.4"), 12345); socket.send_to(boost::asio::buffer(data, size), destination); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -28371,13 +29775,13 @@ Start an asynchronous read. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_some( const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -28385,34 +29789,44 @@ This function is used to asynchronously read data from the pipe. The function ca [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. +The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: basic_readable_pipe.async_read_some( boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -29174,17 +30588,17 @@ The number of bytes read. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: basic_readable_pipe.read_some(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -29228,7 +30642,7 @@ The number of bytes read. Returns 0 if an error occurred. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. @@ -29908,13 +31322,13 @@ Start an asynchronous connect. template< - typename ``[link boost_asio.reference.ConnectHandler ConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ConnectToken ConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( const endpoint_type & peer_endpoint, - ConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously connect a socket to the specified remote endpoint. The function call always returns immediately. +This function is used to asynchronously connect a socket to the specified remote endpoint. It is an initiating function for an [link boost_asio.overview.model.async_ops 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 not returned to the closed state. @@ -29926,17 +31340,27 @@ The socket is automatically opened if it is not already open. If the connect fai [[peer_endpoint][The remote endpoint to which the socket will be connected. Copies will be made of the endpoint object as required.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the connect completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error // Result of operation + const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -29987,21 +31411,21 @@ Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_seq_packet_socket.async_receive.overload1 async_receive]``( const MutableBufferSequence & buffers, socket_base::message_flags & out_flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_seq_packet_socket.async_receive.overload1 more...]]`` template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_seq_packet_socket.async_receive.overload2 async_receive]``( const MutableBufferSequence & buffers, socket_base::message_flags in_flags, socket_base::message_flags & out_flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_seq_packet_socket.async_receive.overload2 more...]]`` @@ -30013,14 +31437,14 @@ Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive( const MutableBufferSequence & buffers, socket_base::message_flags & out_flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously receive data from the sequenced packet socket. The function call always returns immediately. +This function is used to asynchronously receive data from the sequenced packet socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -30028,30 +31452,40 @@ This function is used to asynchronously receive data from the sequenced packet s [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the receive completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_receive(boost::asio::buffer(data, size), out_flags, handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -30082,15 +31516,15 @@ Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive( const MutableBufferSequence & buffers, socket_base::message_flags in_flags, socket_base::message_flags & out_flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously receive data from the sequenced data socket. The function call always returns immediately. +This function is used to asynchronously receive data from the sequenced data socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -30098,34 +31532,44 @@ This function is used to asynchronously receive data from the sequenced data soc [variablelist -[[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.]] +[[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 completion handler is called.]] [[in_flags][Flags specifying how the receive call is to be made.]] -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the receive completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_receive( boost::asio::buffer(data, size), 0, out_flags, handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -30158,14 +31602,14 @@ Start an asynchronous send. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send( const ConstBufferSequence & buffers, socket_base::message_flags flags, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously send data on the sequenced packet socket. The function call always returns immediately. +This function is used to asynchronously send data on the sequenced packet socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -30173,30 +31617,40 @@ This function is used to asynchronously send data on the sequenced packet socket [variablelist -[[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.]] +[[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 completion handler is called.]] [[flags][Flags specifying how the send call is to be made.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the send completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_send(boost::asio::buffer(data, size), 0, handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -30229,13 +31683,13 @@ Asynchronously wait for the socket to become ready to read, ready to write, or t template< - typename ``[link boost_asio.reference.WaitHandler WaitHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WaitToken WaitToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_wait( wait_type w, - WaitHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WaitToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to perform an asynchronous wait for a socket to enter a ready to read, write or error condition state. +This function is used to perform an asynchronous wait for a socket to enter a ready to read, write or error condition state. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -30245,17 +31699,27 @@ This function is used to perform an asynchronous wait for a socket to enter a re [[w][Specifies the desired socket state.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the wait completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error // Result of operation + const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -33764,12 +35228,12 @@ The number of bytes received. [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.receive(boost::asio::buffer(data, size), out_flags); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -33826,17 +35290,17 @@ The number of bytes received. [heading Remarks] -The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.receive(boost::asio::buffer(data, size), 0, out_flags); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -33886,7 +35350,7 @@ The number of bytes received. Returns 0 if an error occurred. [heading Remarks] -The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. @@ -34330,12 +35794,12 @@ The number of bytes sent. [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.send(boost::asio::buffer(data, size), 0); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -34382,7 +35846,7 @@ The number of bytes sent. Returns 0 if an error occurred. [heading Remarks] -The send operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The send operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. @@ -35638,13 +37102,13 @@ Start an asynchronous read. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_some( const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read data from the serial port. The function call always returns immediately. +This function is used to asynchronously read data from the serial port. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -35652,34 +37116,58 @@ This function is used to asynchronously read data from the serial port. The func [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. +The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: basic_serial_port.async_read_some( boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. + + +[heading Per-Operation Cancellation] + +On POSIX or Windows operating systems, this asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: + + +* `cancellation_type::terminal` + + +* `cancellation_type::partial` + + +* `cancellation_type::total` @@ -35696,13 +37184,13 @@ Start an asynchronous write. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_some( const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously write data to the serial port. The function call always returns immediately. +This function is used to asynchronously write data to the serial port. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -35710,34 +37198,58 @@ This function is used to asynchronously write data to the serial port. The funct [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. +The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: basic_serial_port.async_write_some( boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. + + +[heading Per-Operation Cancellation] + +On POSIX or Windows operating systems, this asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: + + +* `cancellation_type::terminal` + + +* `cancellation_type::partial` + + +* `cancellation_type::total` @@ -36881,17 +38393,17 @@ The number of bytes read. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: basic_serial_port.read_some(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -36935,7 +38447,7 @@ The number of bytes read. Returns 0 if an error occurred. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. @@ -37177,17 +38689,17 @@ The number of bytes written. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: basic_serial_port.write_some(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -37231,7 +38743,7 @@ The number of bytes written. Returns 0 if an error occurred. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. @@ -37712,14 +39224,14 @@ Start an asynchronous operation to wait for a signal to be delivered. template< - typename ``[link boost_asio.reference.SignalHandler SignalHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.SignalToken SignalToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_wait( - SignalHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + SignalToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function may be used to initiate an asynchronous wait against the signal set. It always returns immediately. +This function may be used to initiate an asynchronous wait against the signal set. It is an initiating function for an [link boost_asio.overview.model.async_ops 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: * One of the registered signals in the signal set occurs; or @@ -37733,18 +39245,42 @@ For each call to `async_wait()`, the supplied handler will be called exactly onc [variablelist -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the wait completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. int signal_number // Indicates which signal occurred. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`]. ]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, int) + + + + + +[heading Per-Operation Cancellation] + +This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: + + +* `cancellation_type::terminal` + + +* `cancellation_type::partial` + + +* `cancellation_type::total` + + [endsect] @@ -39151,13 +40687,13 @@ Start an asynchronous connect. template< - typename ``[link boost_asio.reference.ConnectHandler ConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ConnectToken ConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( const endpoint_type & peer_endpoint, - ConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously connect a socket to the specified remote endpoint. The function call always returns immediately. +This function is used to asynchronously connect a socket to the specified remote endpoint. It is an initiating function for an [link boost_asio.overview.model.async_ops 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 not returned to the closed state. @@ -39169,17 +40705,27 @@ The socket is automatically opened if it is not already open. If the connect fai [[peer_endpoint][The remote endpoint to which the socket will be connected. Copies will be made of the endpoint object as required.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the connect completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error // Result of operation + const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -39230,13 +40776,13 @@ Asynchronously wait for the socket to become ready to read, ready to write, or t template< - typename ``[link boost_asio.reference.WaitHandler WaitHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WaitToken WaitToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_wait( wait_type w, - WaitHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WaitToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to perform an asynchronous wait for a socket to enter a ready to read, write or error condition state. +This function is used to perform an asynchronous wait for a socket to enter a ready to read, write or error condition state. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -39246,17 +40792,27 @@ This function is used to perform an asynchronous wait for a socket to enter a re [[w][Specifies the desired socket state.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the wait completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error // Result of operation + const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -45426,70 +46982,70 @@ Start an asynchronous accept. template< typename ``[link boost_asio.reference.Protocol Protocol1]``, typename ``[link boost_asio.reference.Executor1 Executor1]``, - typename ``[link boost_asio.reference.AcceptHandler AcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.AcceptToken AcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_socket_acceptor.async_accept.overload1 async_accept]``( basic_socket< Protocol1, Executor1 > & peer, - AcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + AcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_convertible< Protocol, Protocol1 >::value >::type = 0); `` [''''»''' [link boost_asio.reference.basic_socket_acceptor.async_accept.overload1 more...]]`` template< typename ``[link boost_asio.reference.Executor1 Executor1]``, - typename ``[link boost_asio.reference.AcceptHandler AcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.AcceptToken AcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_socket_acceptor.async_accept.overload2 async_accept]``( basic_socket< protocol_type, Executor1 > & peer, endpoint_type & peer_endpoint, - AcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + AcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_socket_acceptor.async_accept.overload2 more...]]`` template< - typename ``[link boost_asio.reference.MoveAcceptHandler MoveAcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.MoveAcceptToken MoveAcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_socket_acceptor.async_accept.overload3 async_accept]``( - MoveAcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + MoveAcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_socket_acceptor.async_accept.overload3 more...]]`` template< typename ``[link boost_asio.reference.Executor1 Executor1]``, - typename ``[link boost_asio.reference.MoveAcceptHandler MoveAcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.MoveAcceptToken MoveAcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_socket_acceptor.async_accept.overload4 async_accept]``( const Executor1 & ex, - MoveAcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + MoveAcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_executor< Executor1 >::value||execution::is_executor< Executor1 >::value >::type = 0); `` [''''»''' [link boost_asio.reference.basic_socket_acceptor.async_accept.overload4 more...]]`` template< typename ExecutionContext, - typename ``[link boost_asio.reference.MoveAcceptHandler MoveAcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.MoveAcceptToken MoveAcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_socket_acceptor.async_accept.overload5 async_accept]``( ExecutionContext & context, - MoveAcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + MoveAcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_convertible< ExecutionContext &, execution_context & >::value >::type = 0); `` [''''»''' [link boost_asio.reference.basic_socket_acceptor.async_accept.overload5 more...]]`` template< - typename ``[link boost_asio.reference.MoveAcceptHandler MoveAcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.MoveAcceptToken MoveAcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_socket_acceptor.async_accept.overload6 async_accept]``( endpoint_type & peer_endpoint, - MoveAcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + MoveAcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_socket_acceptor.async_accept.overload6 more...]]`` template< typename ``[link boost_asio.reference.Executor1 Executor1]``, - typename ``[link boost_asio.reference.MoveAcceptHandler MoveAcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.MoveAcceptToken MoveAcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_socket_acceptor.async_accept.overload7 async_accept]``( const Executor1 & ex, endpoint_type & peer_endpoint, - MoveAcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + MoveAcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_executor< Executor1 >::value||execution::is_executor< Executor1 >::value >::type = 0); `` [''''»''' [link boost_asio.reference.basic_socket_acceptor.async_accept.overload7 more...]]`` template< typename ExecutionContext, - typename ``[link boost_asio.reference.MoveAcceptHandler MoveAcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.MoveAcceptToken MoveAcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_socket_acceptor.async_accept.overload8 async_accept]``( ExecutionContext & context, endpoint_type & peer_endpoint, - MoveAcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + MoveAcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_convertible< ExecutionContext &, execution_context & >::value >::type = 0); `` [''''»''' [link boost_asio.reference.basic_socket_acceptor.async_accept.overload8 more...]]`` @@ -45503,14 +47059,14 @@ Start an asynchronous accept. template< typename ``[link boost_asio.reference.Protocol Protocol1]``, typename ``[link boost_asio.reference.Executor1 Executor1]``, - typename ``[link boost_asio.reference.AcceptHandler AcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.AcceptToken AcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_accept( basic_socket< Protocol1, Executor1 > & peer, - AcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + AcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_convertible< Protocol, Protocol1 >::value >::type = 0); -This function is used to asynchronously accept a new connection into a socket. The function call always returns immediately. +This function is used to asynchronously accept a new connection into a socket, and additionally obtain the endpoint of the remote peer. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -45518,19 +47074,29 @@ This function is used to asynchronously accept a new connection into a socket. T [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the accept completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -45582,14 +47148,14 @@ Start an asynchronous accept. template< typename ``[link boost_asio.reference.Executor1 Executor1]``, - typename ``[link boost_asio.reference.AcceptHandler AcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.AcceptToken AcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_accept( basic_socket< protocol_type, Executor1 > & peer, endpoint_type & peer_endpoint, - AcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + AcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -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. +This function is used to asynchronously accept a new connection into a socket, and additionally obtain the endpoint of the remote peer. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -45597,21 +47163,31 @@ This function is used to asynchronously accept a new connection into a socket, a [variablelist -[[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.]] +[[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 completion handler is called.]] [[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.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the accept completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Per-Operation Cancellation] On POSIX or Windows operating systems, this asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -45639,12 +47215,12 @@ Start an asynchronous accept. template< - typename ``[link boost_asio.reference.MoveAcceptHandler MoveAcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.MoveAcceptToken MoveAcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_accept( - MoveAcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + MoveAcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. This overload requires that the Protocol template parameter satisfy the AcceptableProtocol type requirements. @@ -45654,21 +47230,34 @@ This overload requires that the Protocol template parameter satisfy the Acceptab [variablelist -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the accept completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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 ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, + typename Protocol::socket::template + rebind_executor::other)) + + + + + [heading Example] @@ -45720,14 +47309,14 @@ Start an asynchronous accept. template< typename ``[link boost_asio.reference.Executor1 Executor1]``, - typename ``[link boost_asio.reference.MoveAcceptHandler MoveAcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.MoveAcceptToken MoveAcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_accept( const Executor1 & ex, - MoveAcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + MoveAcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_executor< Executor1 >::value||execution::is_executor< Executor1 >::value >::type = 0); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. This overload requires that the Protocol template parameter satisfy the AcceptableProtocol type requirements. @@ -45739,19 +47328,34 @@ This overload requires that the Protocol template parameter satisfy the Acceptab [[ex][The I/O executor object to be used for the newly accepted socket.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the accept completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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 ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, + typename Protocol::socket::template rebind_executor< + Executor1>::other)) + + + + + [heading Example] @@ -45803,14 +47407,14 @@ Start an asynchronous accept. template< typename ExecutionContext, - typename ``[link boost_asio.reference.MoveAcceptHandler MoveAcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.MoveAcceptToken MoveAcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_accept( ExecutionContext & context, - MoveAcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + MoveAcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_convertible< ExecutionContext &, execution_context & >::value >::type = 0); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. This overload requires that the Protocol template parameter satisfy the AcceptableProtocol type requirements. @@ -45822,20 +47426,34 @@ This overload requires that the Protocol template parameter satisfy the Acceptab [[context][The I/O execution context object to be used for the newly accepted socket.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the accept completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, + typename Protocol::socket::template rebind_executor< + typename ExecutionContext::executor_type>::other)) + + + + + [heading Example] @@ -45886,13 +47504,13 @@ Start an asynchronous accept. template< - typename ``[link boost_asio.reference.MoveAcceptHandler MoveAcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.MoveAcceptToken MoveAcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_accept( endpoint_type & peer_endpoint, - MoveAcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + MoveAcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. This overload requires that the Protocol template parameter satisfy the AcceptableProtocol type requirements. @@ -45902,23 +47520,36 @@ This overload requires that the Protocol template parameter satisfy the Acceptab [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the accept completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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 ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, + typename Protocol::socket::template + rebind_executor::other)) + + + + + [heading Example] @@ -45971,15 +47602,15 @@ Start an asynchronous accept. template< typename ``[link boost_asio.reference.Executor1 Executor1]``, - typename ``[link boost_asio.reference.MoveAcceptHandler MoveAcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.MoveAcceptToken MoveAcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_accept( const Executor1 & ex, endpoint_type & peer_endpoint, - MoveAcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + MoveAcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_executor< Executor1 >::value||execution::is_executor< Executor1 >::value >::type = 0); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. This overload requires that the Protocol template parameter satisfy the AcceptableProtocol type requirements. @@ -45991,21 +47622,36 @@ This overload requires that the Protocol template parameter satisfy the Acceptab [[ex][The I/O executor object to be used for the newly accepted socket.]] -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the accept completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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 ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, + typename Protocol::socket::template rebind_executor< + Executor1>::other)) + + + + + [heading Example] @@ -46058,15 +47704,15 @@ Start an asynchronous accept. template< typename ExecutionContext, - typename ``[link boost_asio.reference.MoveAcceptHandler MoveAcceptHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.MoveAcceptToken MoveAcceptToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_accept( ExecutionContext & context, endpoint_type & peer_endpoint, - MoveAcceptHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, + MoveAcceptToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename constraint< is_convertible< ExecutionContext &, execution_context & >::value >::type = 0); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. This overload requires that the Protocol template parameter satisfy the AcceptableProtocol type requirements. @@ -46078,22 +47724,36 @@ This overload requires that the Protocol template parameter satisfy the Acceptab [[context][The I/O execution context object to be used for the newly accepted socket.]] -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the accept completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, + typename Protocol::socket::template rebind_executor< + typename ExecutionContext::executor_type>::other)) + + + + + [heading Example] @@ -46147,13 +47807,13 @@ Asynchronously wait for the acceptor to become ready to read, ready to write, or template< - typename ``[link boost_asio.reference.WaitHandler WaitHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WaitToken WaitToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_wait( wait_type w, - WaitHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WaitToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to perform an asynchronous wait for an acceptor to enter a ready to read, write or error condition state. +This function is used to perform an asynchronous wait for an acceptor to enter a ready to read, write or error condition state. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -46163,17 +47823,27 @@ This function is used to perform an asynchronous wait for an acceptor to enter a [[w][Specifies the desired acceptor state.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the wait completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error // Result of operation + const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -51466,6 +53136,11 @@ Provides stream-oriented file functionality. [Open the file for reading and writing. ] ] + [ + [[link boost_asio.reference.basic_stream_file.sync_all_on_write [*sync_all_on_write]] [static]] + [Open the file so that write operations automatically synchronise the file data and metadata to disk. ] + ] + [ [[link boost_asio.reference.basic_stream_file.truncate [*truncate]] [static]] [Open the file with any existing contents truncated. ] @@ -51576,13 +53251,13 @@ Start an asynchronous read. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_some( const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read data from the stream file. The function call always returns immediately. +This function is used to asynchronously read data from the stream file. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -51590,33 +53265,43 @@ This function is used to asynchronously read data from the stream file. The func [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. +The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: file.async_read_some(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -51647,13 +53332,13 @@ Start an asynchronous write. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_some( const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously write data to the stream file. The function call always returns immediately. +This function is used to asynchronously write data to the stream file. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -51661,33 +53346,43 @@ This function is used to asynchronously write data to the stream file. The funct [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. +The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: file.async_write_some(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -52976,17 +54671,17 @@ The number of bytes read. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: file.read_some(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -53030,7 +54725,7 @@ The number of bytes read. Returns 0 if an error occurred. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. @@ -53541,6 +55236,23 @@ This function synchronises the file data and metadata to disk. Note that the sem [endsect] + +[section:sync_all_on_write basic_stream_file::sync_all_on_write] + + +['Inherited from file_base.] + +[indexterm2 boost_asio.indexterm.basic_stream_file.sync_all_on_write..sync_all_on_write..basic_stream_file] +Open the file so that write operations automatically synchronise the file data and metadata to disk. + + + static const flags sync_all_on_write = implementation_defined; + + + +[endsect] + + [section:sync_data basic_stream_file::sync_data] [indexterm2 boost_asio.indexterm.basic_stream_file.sync_data..sync_data..basic_stream_file] @@ -53715,17 +55427,17 @@ The number of bytes written. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: file.write_some(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -53769,7 +55481,7 @@ The number of bytes written. Returns 0 if an error occurred. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. @@ -54026,6 +55738,11 @@ The file type when rebound to the specified executor. [Open the file for reading and writing. ] ] + [ + [[link boost_asio.reference.basic_stream_file.sync_all_on_write [*sync_all_on_write]] [static]] + [Open the file so that write operations automatically synchronise the file data and metadata to disk. ] + ] + [ [[link boost_asio.reference.basic_stream_file.truncate [*truncate]] [static]] [Open the file with any existing contents truncated. ] @@ -54565,13 +56282,13 @@ Start an asynchronous connect. template< - typename ``[link boost_asio.reference.ConnectHandler ConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ConnectToken ConnectToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( const endpoint_type & peer_endpoint, - ConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ConnectToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously connect a socket to the specified remote endpoint. The function call always returns immediately. +This function is used to asynchronously connect a socket to the specified remote endpoint. It is an initiating function for an [link boost_asio.overview.model.async_ops 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 not returned to the closed state. @@ -54583,17 +56300,27 @@ The socket is automatically opened if it is not already open. If the connect fai [[peer_endpoint][The remote endpoint to which the socket will be connected. Copies will be made of the endpoint object as required.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the connect completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error // Result of operation + const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -54645,13 +56372,13 @@ Start an asynchronous read. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_some( const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read data from the stream socket. The function call always returns immediately. +This function is used to asynchronously read data from the stream socket. socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -54659,33 +56386,43 @@ This function is used to asynchronously read data from the stream socket. The fu [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. +The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_read_some(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -54715,19 +56452,19 @@ Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_stream_socket.async_receive.overload1 async_receive]``( const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_stream_socket.async_receive.overload1 more...]]`` template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_stream_socket.async_receive.overload2 async_receive]``( const MutableBufferSequence & buffers, socket_base::message_flags flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_stream_socket.async_receive.overload2 more...]]`` @@ -54739,13 +56476,13 @@ Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive( const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously receive data from the stream socket. The function call always returns immediately. +This function is used to asynchronously receive data from the stream socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -54753,33 +56490,43 @@ This function is used to asynchronously receive data from the stream socket. The [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the receive completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is received before the asynchronous operation completes. +The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is received before the asynchronous operation completes. [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_receive(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -54810,14 +56557,14 @@ Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive( const MutableBufferSequence & buffers, socket_base::message_flags flags, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously receive data from the stream socket. The function call always returns immediately. +This function is used to asynchronously receive data from the stream socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -54825,35 +56572,45 @@ This function is used to asynchronously receive data from the stream socket. The [variablelist -[[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.]] +[[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 completion handler is called.]] [[flags][Flags specifying how the receive call is to be made.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the receive completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is received before the asynchronous operation completes. +The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is received before the asynchronous operation completes. [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_receive(boost::asio::buffer(data, size), 0, handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -54885,19 +56642,19 @@ Start an asynchronous send. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_stream_socket.async_send.overload1 async_send]``( const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_stream_socket.async_send.overload1 more...]]`` template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_stream_socket.async_send.overload2 async_send]``( const ConstBufferSequence & buffers, socket_base::message_flags flags, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_stream_socket.async_send.overload2 more...]]`` @@ -54909,13 +56666,13 @@ Start an asynchronous send. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send( const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously send data on the stream socket. The function call always returns immediately. +This function is used to asynchronously send data on the stream socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -54923,33 +56680,43 @@ This function is used to asynchronously send data on the stream socket. The func [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the send completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The send operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. +The send operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_send(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -54980,14 +56747,14 @@ Start an asynchronous send. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send( const ConstBufferSequence & buffers, socket_base::message_flags flags, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously send data on the stream socket. The function call always returns immediately. +This function is used to asynchronously send data on the stream socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -54995,35 +56762,45 @@ This function is used to asynchronously send data on the stream socket. The func [variablelist -[[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.]] +[[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 completion handler is called.]] [[flags][Flags specifying how the send call is to be made.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the send completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The send operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. +The send operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_send(boost::asio::buffer(data, size), 0, handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -55058,13 +56835,13 @@ Asynchronously wait for the socket to become ready to read, ready to write, or t template< - typename ``[link boost_asio.reference.WaitHandler WaitHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WaitToken WaitToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_wait( wait_type w, - WaitHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WaitToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to perform an asynchronous wait for a socket to enter a ready to read, write or error condition state. +This function is used to perform an asynchronous wait for a socket to enter a ready to read, write or error condition state. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -55074,17 +56851,27 @@ This function is used to perform an asynchronous wait for a socket to enter a re [[w][Specifies the desired socket state.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the wait completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error // Result of operation + const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -55135,13 +56922,13 @@ Start an asynchronous write. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_some( const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously write data to the stream socket. The function call always returns immediately. +This function is used to asynchronously write data to the stream socket. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -55149,33 +56936,43 @@ This function is used to asynchronously write data to the stream socket. The fun [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. +The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_write_some(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -58646,17 +60443,17 @@ The number of bytes read. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.read_some(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -58700,7 +60497,7 @@ The number of bytes read. Returns 0 if an error occurred. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. @@ -58784,17 +60581,17 @@ The number of bytes received. [heading Remarks] -The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.receive(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -58848,17 +60645,17 @@ The number of bytes received. [heading Remarks] -The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. [heading Example] -To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.receive(boost::asio::buffer(data, size), 0); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -58905,7 +60702,7 @@ The number of bytes received. Returns 0 if an error occurred. [heading Remarks] -The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The receive operation may not receive all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. @@ -59352,17 +61149,17 @@ The number of bytes sent. [heading Remarks] -The send operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The send operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.send(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -59416,17 +61213,17 @@ The number of bytes sent. [heading Remarks] -The send operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The send operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. [heading Example] -To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.send(boost::asio::buffer(data, size), 0); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -59473,7 +61270,7 @@ The number of bytes sent. Returns 0 if an error occurred. [heading Remarks] -The send operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The send operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. @@ -60102,17 +61899,17 @@ The number of bytes written. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.write_some(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -60156,7 +61953,7 @@ The number of bytes written. Returns 0 if an error occurred. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. @@ -62842,14 +64639,14 @@ Start an asynchronous wait on the timer. template< - typename ``[link boost_asio.reference.WaitHandler WaitHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WaitToken WaitToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_wait( - WaitHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WaitToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function may be used to initiate an asynchronous wait against the timer. It always returns immediately. +This function may be used to initiate an asynchronous wait against the timer. It is an initiating function for an [link boost_asio.overview.model.async_ops 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: * The timer has expired. @@ -62863,17 +64660,27 @@ For each call to `async_wait()`, the supplied handler will be called exactly onc [variablelist -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the timer expires. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -64588,13 +66395,13 @@ Start an asynchronous write. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_some( const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -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 [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -64602,33 +66409,43 @@ This function is used to asynchronously write data to the pipe. The function cal [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. +The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: pipe.async_write_some(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -65390,17 +67207,17 @@ The number of bytes written. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: pipe.write_some(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -65444,7 +67261,7 @@ The number of bytes written. Returns 0 if an error occurred. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. @@ -65651,7 +67468,7 @@ The [link boost_asio.reference.basic_writable_pipe `basic_writable_pipe`] class [indexterm1 boost_asio.indexterm.basic_yield_context..basic_yield_context] -Context object the represents the currently executing coroutine. +A completion token that represents the currently executing coroutine. template< @@ -65697,7 +67514,7 @@ Context object the represents the currently executing coroutine. ] -The [link boost_asio.reference.basic_yield_context `basic_yield_context`] class is used to represent the currently executing stackful coroutine. A [link boost_asio.reference.basic_yield_context `basic_yield_context`] may be passed as a handler to an asynchronous operation. For example: +The [link boost_asio.reference.basic_yield_context `basic_yield_context`] class is a completion token type that is used to represent the currently executing stackful coroutine. A [link boost_asio.reference.basic_yield_context `basic_yield_context`] object may be passed as a completion token to an asynchronous operation. For example: @@ -65886,9 +67703,36 @@ By default, when a yield context is used with an asynchronous operation, a non-s [endsect] +[section:bind_allocator bind_allocator] + +[indexterm1 boost_asio.indexterm.bind_allocator..bind_allocator] + +Associate an object of type `T` with an allocator of type `Allocator`. + + + template< + typename Allocator, + typename T> + allocator_binder< typename decay< T >::type, Allocator > bind_allocator( + const Allocator & s, + T && t); + + +[heading Requirements] + +['Header: ][^boost/asio/bind_allocator.hpp] + +['Convenience header: ][^boost/asio.hpp] + + +[endsect] + + + [section:bind_cancellation_slot bind_cancellation_slot] -[indexterm1 boost_asio.indexterm.bind_cancellation_slot..bind_cancellation_slot] +[indexterm1 boost_asio.indexterm.bind_cancellation_slot..bind_cancellation_slot] + Associate an object of type `T` with a cancellation slot of type `CancellationSlot`. @@ -65912,7 +67756,8 @@ Associate an object of type `T` with a cancellation slot of type `CancellationSl [section:bind_executor bind_executor] -[indexterm1 boost_asio.indexterm.bind_executor..bind_executor] +[indexterm1 boost_asio.indexterm.bind_executor..bind_executor] + Associate an object of type `T` with an executor of type `Executor`. template< @@ -65985,7 +67830,8 @@ Associate an object of type `T` with an execution context's executor. [section:buffer buffer] -[indexterm1 boost_asio.indexterm.buffer..buffer] +[indexterm1 boost_asio.indexterm.buffer..buffer] + The `boost::asio::buffer` function is used to create a buffer object to represent raw memory, an array of POD elements, a vector of POD elements, or a std::string. @@ -66326,16 +68172,16 @@ The contents of a buffer may be accessed using the `data()` and `size()` member The `data()` member function permits violations of type safety, so uses of it in application code should be carefully considered. -For convenience, a [link boost_asio.reference.buffer_size `buffer_size`] function is provided that works with both buffers and buffer sequences (that is, types meeting the ConstBufferSequence or MutableBufferSequence type requirements). In this case, the function returns the total size of all buffers in the sequence. +For convenience, a [link boost_asio.reference.buffer_size `buffer_size`] function is provided that works with both buffers and buffer sequences (that is, types meeting the ConstBufferSequence or MutableBufferSequence type requirements). In this case, the function returns the total size of all buffers in the sequence. [heading Buffer Copying] -The [link boost_asio.reference.buffer_copy `buffer_copy`] function may be used to copy raw bytes between individual buffers and buffer sequences. +The [link boost_asio.reference.buffer_copy `buffer_copy`] function may be used to copy raw bytes between individual buffers and buffer sequences. -In particular, when used with the [link boost_asio.reference.buffer_size `buffer_size`] function, the [link boost_asio.reference.buffer_copy `buffer_copy`] function can be used to linearise a sequence of buffers. For example: +In particular, when used with the [link boost_asio.reference.buffer_size `buffer_size`] function, the [link boost_asio.reference.buffer_copy `buffer_copy`] function can be used to linearise a sequence of buffers. For example: @@ -66347,7 +68193,7 @@ In particular, when used with the [link boost_asio.reference.buffer_size `buffer -Note that [link boost_asio.reference.buffer_copy `buffer_copy`] is implemented in terms of `memcpy`, and consequently it cannot be used to copy between overlapping memory regions. +Note that [link boost_asio.reference.buffer_copy `buffer_copy`] is implemented in terms of `memcpy`, and consequently it cannot be used to copy between overlapping memory regions. [heading Buffer Invalidation] @@ -67534,7 +69380,8 @@ Obtain a buffer representing part of a registered buffer. [section:buffer_cast buffer_cast] -[indexterm1 boost_asio.indexterm.buffer_cast..buffer_cast] +[indexterm1 boost_asio.indexterm.buffer_cast..buffer_cast] + (Deprecated: Use the `data()` member function.) The `boost::asio::buffer_cast` function is used to obtain a pointer to the underlying memory region associated with a buffer. @@ -67619,7 +69466,8 @@ Cast a non-modifiable buffer to a specified pointer to POD type. [section:buffer_copy buffer_copy] -[indexterm1 boost_asio.indexterm.buffer_copy..buffer_copy] +[indexterm1 boost_asio.indexterm.buffer_copy..buffer_copy] + The `boost::asio::buffer_copy` function is used to copy bytes from a source buffer (or buffer sequence) to a target buffer (or buffer sequence). @@ -67665,7 +69513,7 @@ Both forms return the number of bytes actually copied. The number of bytes copie This prevents buffer overflow, regardless of the buffer sizes used in the copy operation. -Note that [link boost_asio.reference.buffer_copy `buffer_copy`] is implemented in terms of `memcpy`, and consequently it cannot be used to copy between overlapping memory regions. +Note that [link boost_asio.reference.buffer_copy `buffer_copy`] is implemented in terms of `memcpy`, and consequently it cannot be used to copy between overlapping memory regions. [heading Requirements] @@ -68178,7 +70026,8 @@ Unregisters the buffers. [section:buffer_sequence_begin buffer_sequence_begin] -[indexterm1 boost_asio.indexterm.buffer_sequence_begin..buffer_sequence_begin] +[indexterm1 boost_asio.indexterm.buffer_sequence_begin..buffer_sequence_begin] + The `boost::asio::buffer_sequence_begin` function returns an iterator pointing to the first element in a buffer sequence. @@ -68334,7 +70183,8 @@ Get an iterator to the first element in a buffer sequence. [section:buffer_sequence_end buffer_sequence_end] -[indexterm1 boost_asio.indexterm.buffer_sequence_end..buffer_sequence_end] +[indexterm1 boost_asio.indexterm.buffer_sequence_end..buffer_sequence_end] + The `boost::asio::buffer_sequence_end` function returns an iterator pointing to one past the end element in a buffer sequence. @@ -68491,7 +70341,8 @@ Get an iterator to one past the end element in a buffer sequence. [section:buffer_size buffer_size] -[indexterm1 boost_asio.indexterm.buffer_size..buffer_size] +[indexterm1 boost_asio.indexterm.buffer_size..buffer_size] + Get the total number of bytes in a buffer sequence. @@ -68695,6 +70546,18 @@ Start an asynchronous fill. +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + + + [endsect] @@ -68714,6 +70577,18 @@ Start an asynchronous read. The buffer into which the data will be read must be +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + + + [endsect] @@ -68733,6 +70608,18 @@ Start an asynchronous write. The data being written must be valid for the lifeti +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + + + [endsect] @@ -69428,6 +71315,18 @@ Start an asynchronous fill. +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + + + [endsect] @@ -69445,6 +71344,18 @@ Start an asynchronous flush. +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + + + [endsect] @@ -69464,6 +71375,18 @@ Start an asynchronous read. The buffer into which the data will be read must be +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + + + [endsect] @@ -69483,6 +71406,18 @@ Start an asynchronous write. The data being written must be valid for the lifeti +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + + + [endsect] @@ -70213,6 +72148,18 @@ Start an asynchronous flush. +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + + + [endsect] @@ -70232,6 +72179,18 @@ Start an asynchronous read. The buffer into which the data will be read must be +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + + + [endsect] @@ -70251,6 +72210,18 @@ Start an asynchronous write. The data being written must be valid for the lifeti +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + + + [endsect] @@ -70783,7 +72754,8 @@ Write the given data to the stream. Returns the number of bytes written, or 0 if [section:buffers_begin buffers_begin] -[indexterm1 boost_asio.indexterm.buffers_begin..buffers_begin] +[indexterm1 boost_asio.indexterm.buffers_begin..buffers_begin] + Construct an iterator representing the beginning of the buffers' data. @@ -70806,7 +72778,8 @@ Construct an iterator representing the beginning of the buffers' data. [section:buffers_end buffers_end] -[indexterm1 boost_asio.indexterm.buffers_end..buffers_end] +[indexterm1 boost_asio.indexterm.buffers_end..buffers_end] + Construct an iterator representing the end of the buffers' data. @@ -73045,7 +75018,8 @@ This sub-slot is used with the operations that are being composed. [section:cancellation_type cancellation_type] -[indexterm1 boost_asio.indexterm.cancellation_type..cancellation_type] +[indexterm1 boost_asio.indexterm.cancellation_type..cancellation_type] + Enumeration representing the different types of cancellation that may be requested from or implemented by an asynchronous operation. enum class cancellation_type : unsigned int @@ -73100,7 +75074,8 @@ Enumeration representing the different types of cancellation that may be request [section:cancellation_type_t cancellation_type_t] -[indexterm1 boost_asio.indexterm.cancellation_type_t..cancellation_type_t] +[indexterm1 boost_asio.indexterm.cancellation_type_t..cancellation_type_t] + Portability typedef. @@ -73120,7 +75095,8 @@ Portability typedef. [section:co_spawn co_spawn] -[indexterm1 boost_asio.indexterm.co_spawn..co_spawn] +[indexterm1 boost_asio.indexterm.co_spawn..co_spawn] + Spawn a new coroutined-based thread of execution. template< @@ -73226,7 +75202,7 @@ Spawn a new coroutined-based thread of execution. [[a][The [link boost_asio.reference.awaitable `awaitable`] object that is the result of calling the coroutine's entry point function.]] -[[token][The completion token that will handle the notification that the thread of execution has completed. The function signature of the completion handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will handle the notification that the thread of execution has completed. The function signature of the completion handler must be: `` void handler(std::exception_ptr, T); `` @@ -73235,6 +75211,16 @@ Spawn a new coroutined-based thread of execution. ] +[heading Completion Signature] + + + + void(std::exception_ptr, T) + + + + + [heading Example] @@ -73315,7 +75301,7 @@ Spawn a new coroutined-based thread of execution. [[a][The [link boost_asio.reference.awaitable `awaitable`] object that is the result of calling the coroutine's entry point function.]] -[[token][The completion token that will handle the notification that the thread of execution has completed. The function signature of the completion handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will handle the notification that the thread of execution has completed. The function signature of the completion handler must be: `` void handler(std::exception_ptr); `` @@ -73324,6 +75310,16 @@ Spawn a new coroutined-based thread of execution. ] +[heading Completion Signature] + + + + void(std::exception_ptr) + + + + + [heading Example] @@ -73397,7 +75393,7 @@ Spawn a new coroutined-based thread of execution. [[a][The [link boost_asio.reference.awaitable `awaitable`] object that is the result of calling the coroutine's entry point function.]] -[[token][The completion token that will handle the notification that the thread of execution has completed. The function signature of the completion handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will handle the notification that the thread of execution has completed. The function signature of the completion handler must be: `` void handler(std::exception_ptr); `` @@ -73406,6 +75402,16 @@ Spawn a new coroutined-based thread of execution. ] +[heading Completion Signature] + + + + void(std::exception_ptr, T) + + + + + [heading Example] @@ -73486,7 +75492,7 @@ Spawn a new coroutined-based thread of execution. [[a][The [link boost_asio.reference.awaitable `awaitable`] object that is the result of calling the coroutine's entry point function.]] -[[token][The completion token that will handle the notification that the thread of execution has completed. The function signature of the completion handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will handle the notification that the thread of execution has completed. The function signature of the completion handler must be: `` void handler(std::exception_ptr); `` @@ -73495,6 +75501,16 @@ Spawn a new coroutined-based thread of execution. ] +[heading Completion Signature] + + + + void(std::exception_ptr) + + + + + [heading Example] @@ -73567,7 +75583,7 @@ Spawn a new coroutined-based thread of execution. [[f][A nullary function object with a return type of the form `boost::asio::awaitable` that will be used as the coroutine's entry point.]] -[[token][The completion token that will handle the notification that the thread of execution has completed. If `R` is `void`, the function signature of the completion handler must be:]] +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will handle the notification that the thread of execution has completed. If `R` is `void`, the function signature of the completion handler must be:]] ] @@ -73584,6 +75600,21 @@ Otherwise, the function signature of the completion handler must be: +[heading Completion Signature] + + + + void(std::exception_ptr, R) + + +where `R` is the first template argument to the `awaitable` returned by the supplied function object `F:` + + boost::asio::awaitable F() + + + + + [heading Example] @@ -73679,7 +75710,7 @@ Spawn a new coroutined-based thread of execution. [[f][A nullary function object with a return type of the form `boost::asio::awaitable` that will be used as the coroutine's entry point.]] -[[token][The completion token that will handle the notification that the thread of execution has completed. If `R` is `void`, the function signature of the completion handler must be:]] +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will handle the notification that the thread of execution has completed. If `R` is `void`, the function signature of the completion handler must be:]] ] @@ -73696,6 +75727,21 @@ Otherwise, the function signature of the completion handler must be: +[heading Completion Signature] + + + + void(std::exception_ptr, R) + + +where `R` is the first template argument to the `awaitable` returned by the supplied function object `F:` + + boost::asio::awaitable F() + + + + + [heading Example] @@ -73767,7 +75813,8 @@ The new thread of execution is created with a cancellation state that supports ` [section:connect connect] -[indexterm1 boost_asio.indexterm.connect..connect] +[indexterm1 boost_asio.indexterm.connect..connect] + The `connect` function is a composed operation that establishes a socket connection by trying each endpoint in a sequence. @@ -74801,7 +76848,8 @@ It would be used with the `boost::asio::connect` function as follows: [section:connect_pipe connect_pipe] -[indexterm1 boost_asio.indexterm.connect_pipe..connect_pipe] +[indexterm1 boost_asio.indexterm.connect_pipe..connect_pipe] + Connect two pipe ends using an anonymous pipe. template< @@ -76192,7 +78240,8 @@ Returns true if the coroutine is the parent of a fork. [section:deadline_timer deadline_timer] -[indexterm1 boost_asio.indexterm.deadline_timer..deadline_timer] +[indexterm1 boost_asio.indexterm.deadline_timer..deadline_timer] + Typedef for the typical usage of timer. Uses a UTC clock. @@ -76473,7 +78522,8 @@ If `T` has a nested type `default_completion_token_type`, `T::default_completion [section:defer defer] -[indexterm1 boost_asio.indexterm.defer..defer] +[indexterm1 boost_asio.indexterm.defer..defer] + Submits a completion token or function object for execution. template< @@ -76521,7 +78571,7 @@ Submits a completion token or function object for execution. This function submits an object for execution using the object's associated executor. The function object is queued for execution, and is never called from the current thread prior to returning from `defer()`. -The use of `defer()`, rather than [link boost_asio.reference.post `post`] , indicates the caller's preference that the executor defer the queueing of the function object. This may allow the executor to optimise queueing for cases when the function object represents a continuation of the current call context. +The use of `defer()`, rather than [link boost_asio.reference.post `post`], indicates the caller's preference that the executor defer the queueing of the function object. This may allow the executor to optimise queueing for cases when the function object represents a continuation of the current call context. This function has the following effects: @@ -76541,7 +78591,17 @@ This function has the following effects: * Performs `ex.defer(std::move(handler), alloc)`. -* Returns `result.get()`. +* Returns `result.get()`. + + +[heading Completion Signature] + + + + void() + + + @@ -76567,7 +78627,7 @@ Submits a completion token or function object for execution. This function submits an object for execution using the specified executor. The function object is queued for execution, and is never called from the current thread prior to returning from `defer()`. -The use of `defer()`, rather than [link boost_asio.reference.post `post`] , indicates the caller's preference that the executor defer the queueing of the function object. This may allow the executor to optimise queueing for cases when the function object represents a continuation of the current call context. +The use of `defer()`, rather than [link boost_asio.reference.post `post`], indicates the caller's preference that the executor defer the queueing of the function object. This may allow the executor to optimise queueing for cases when the function object represents a continuation of the current call context. This function has the following effects: @@ -76593,7 +78653,17 @@ This function has the following effects: * Performs `Executor(ex).defer(std::move(f), alloc)`. -* Returns `result.get()`. +* Returns `result.get()`. + + +[heading Completion Signature] + + + + void() + + + @@ -76620,7 +78690,17 @@ Submits a completion token or function object for execution. [heading Return Value] -`defer(ctx.get_executor(), forward(token))`. +`defer(ctx.get_executor(), forward(token))`. + + +[heading Completion Signature] + + + + void() + + + @@ -76633,7 +78713,8 @@ Submits a completion token or function object for execution. [section:detached detached] -[indexterm1 boost_asio.indexterm.detached..detached] +[indexterm1 boost_asio.indexterm.detached..detached] + A special value, similar to std::nothrow. @@ -76907,7 +78988,8 @@ Convert the specified executor to the inner executor type, then use that to cons [section:disable_cancellation disable_cancellation] -[indexterm1 boost_asio.indexterm.disable_cancellation..disable_cancellation] +[indexterm1 boost_asio.indexterm.disable_cancellation..disable_cancellation] + A cancellation filter that disables cancellation. @@ -76938,7 +79020,8 @@ A cancellation filter that disables cancellation. [section:dispatch dispatch] -[indexterm1 boost_asio.indexterm.dispatch..dispatch] +[indexterm1 boost_asio.indexterm.dispatch..dispatch] + Submits a completion token or function object for execution. template< @@ -77004,7 +79087,17 @@ This function has the following effects: * Performs `ex.dispatch(std::move(handler), alloc)`. -* Returns `result.get()`. +* Returns `result.get()`. + + +[heading Completion Signature] + + + + void() + + + @@ -77054,7 +79147,17 @@ This function has the following effects: * Performs `Executor(ex).dispatch(std::move(f), alloc)`. -* Returns `result.get()`. +* Returns `result.get()`. + + +[heading Completion Signature] + + + + void() + + + @@ -77081,7 +79184,17 @@ Submits a completion token or function object for execution. [heading Return Value] -`dispatch(ctx.get_executor(), forward(token))`. +`dispatch(ctx.get_executor(), forward(token))`. + + +[heading Completion Signature] + + + + void() + + + @@ -77093,7 +79206,8 @@ Submits a completion token or function object for execution. [section:dynamic_buffer dynamic_buffer] -[indexterm1 boost_asio.indexterm.dynamic_buffer..dynamic_buffer] +[indexterm1 boost_asio.indexterm.dynamic_buffer..dynamic_buffer] + The `boost::asio::dynamic_buffer` function is used to create a dynamically resized buffer from a `std::basic_string` or `std::vector`. @@ -78635,7 +80749,8 @@ Erases `n` bytes from the end of the vector by resizing the vector object. If `n [section:enable_partial_cancellation enable_partial_cancellation] -[indexterm1 boost_asio.indexterm.enable_partial_cancellation..enable_partial_cancellation] +[indexterm1 boost_asio.indexterm.enable_partial_cancellation..enable_partial_cancellation] + A cancellation filter that enables terminal and partial cancellation. @@ -78667,7 +80782,8 @@ A cancellation filter that enables terminal and partial cancellation. [section:enable_terminal_cancellation enable_terminal_cancellation] -[indexterm1 boost_asio.indexterm.enable_terminal_cancellation..enable_terminal_cancellation] +[indexterm1 boost_asio.indexterm.enable_terminal_cancellation..enable_terminal_cancellation] + A cancellation filter that enables terminal cancellation only. @@ -78699,7 +80815,8 @@ A cancellation filter that enables terminal cancellation only. [section:enable_total_cancellation enable_total_cancellation] -[indexterm1 boost_asio.indexterm.enable_total_cancellation..enable_total_cancellation] +[indexterm1 boost_asio.indexterm.enable_total_cancellation..enable_total_cancellation] + A cancellation filter that enables terminal, partial and total cancellation. @@ -78731,7 +80848,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__addrinfo_category error::addrinfo_category] -[indexterm1 boost_asio.indexterm.error__addrinfo_category..error::addrinfo_category] +[indexterm1 boost_asio.indexterm.error__addrinfo_category..error::addrinfo_category] + static const boost::system::error_category & addrinfo_category = boost::asio::error::get_addrinfo_category(); @@ -78749,7 +80867,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__addrinfo_errors error::addrinfo_errors] -[indexterm1 boost_asio.indexterm.error__addrinfo_errors..error::addrinfo_errors] +[indexterm1 boost_asio.indexterm.error__addrinfo_errors..error::addrinfo_errors] + enum addrinfo_errors [indexterm2 boost_asio.indexterm.error__addrinfo_errors.service_not_found..service_not_found..error::addrinfo_errors] @@ -78784,7 +80903,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__basic_errors error::basic_errors] -[indexterm1 boost_asio.indexterm.error__basic_errors..error::basic_errors] +[indexterm1 boost_asio.indexterm.error__basic_errors..error::basic_errors] + enum basic_errors [indexterm2 boost_asio.indexterm.error__basic_errors.access_denied..access_denied..error::basic_errors] @@ -79011,7 +81131,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__get_addrinfo_category error::get_addrinfo_category] -[indexterm1 boost_asio.indexterm.error__get_addrinfo_category..error::get_addrinfo_category] +[indexterm1 boost_asio.indexterm.error__get_addrinfo_category..error::get_addrinfo_category] + const boost::system::error_category & get_addrinfo_category(); @@ -79029,7 +81150,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__get_misc_category error::get_misc_category] -[indexterm1 boost_asio.indexterm.error__get_misc_category..error::get_misc_category] +[indexterm1 boost_asio.indexterm.error__get_misc_category..error::get_misc_category] + const boost::system::error_category & get_misc_category(); @@ -79047,7 +81169,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__get_netdb_category error::get_netdb_category] -[indexterm1 boost_asio.indexterm.error__get_netdb_category..error::get_netdb_category] +[indexterm1 boost_asio.indexterm.error__get_netdb_category..error::get_netdb_category] + const boost::system::error_category & get_netdb_category(); @@ -79065,7 +81188,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__get_ssl_category error::get_ssl_category] -[indexterm1 boost_asio.indexterm.error__get_ssl_category..error::get_ssl_category] +[indexterm1 boost_asio.indexterm.error__get_ssl_category..error::get_ssl_category] + const boost::system::error_category & get_ssl_category(); @@ -79083,7 +81207,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__get_system_category error::get_system_category] -[indexterm1 boost_asio.indexterm.error__get_system_category..error::get_system_category] +[indexterm1 boost_asio.indexterm.error__get_system_category..error::get_system_category] + const boost::system::error_category & get_system_category(); @@ -79100,7 +81225,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__make_error_code error::make_error_code] -[indexterm1 boost_asio.indexterm.error__make_error_code..error::make_error_code] +[indexterm1 boost_asio.indexterm.error__make_error_code..error::make_error_code] + boost::system::error_code ``[link boost_asio.reference.error__make_error_code.overload1 make_error_code]``( basic_errors e); `` [''''»''' [link boost_asio.reference.error__make_error_code.overload1 more...]]`` @@ -79197,7 +81323,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__misc_category error::misc_category] -[indexterm1 boost_asio.indexterm.error__misc_category..error::misc_category] +[indexterm1 boost_asio.indexterm.error__misc_category..error::misc_category] + static const boost::system::error_category & misc_category = boost::asio::error::get_misc_category(); @@ -79215,7 +81342,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__misc_errors error::misc_errors] -[indexterm1 boost_asio.indexterm.error__misc_errors..error::misc_errors] +[indexterm1 boost_asio.indexterm.error__misc_errors..error::misc_errors] + enum misc_errors [indexterm2 boost_asio.indexterm.error__misc_errors.already_open..already_open..error::misc_errors] @@ -79262,7 +81390,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__netdb_category error::netdb_category] -[indexterm1 boost_asio.indexterm.error__netdb_category..error::netdb_category] +[indexterm1 boost_asio.indexterm.error__netdb_category..error::netdb_category] + static const boost::system::error_category & netdb_category = boost::asio::error::get_netdb_category(); @@ -79280,7 +81409,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__netdb_errors error::netdb_errors] -[indexterm1 boost_asio.indexterm.error__netdb_errors..error::netdb_errors] +[indexterm1 boost_asio.indexterm.error__netdb_errors..error::netdb_errors] + enum netdb_errors [indexterm2 boost_asio.indexterm.error__netdb_errors.host_not_found..host_not_found..error::netdb_errors] @@ -79327,7 +81457,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__ssl_category error::ssl_category] -[indexterm1 boost_asio.indexterm.error__ssl_category..error::ssl_category] +[indexterm1 boost_asio.indexterm.error__ssl_category..error::ssl_category] + static const boost::system::error_category & ssl_category = boost::asio::error::get_ssl_category(); @@ -79345,7 +81476,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__ssl_errors error::ssl_errors] -[indexterm1 boost_asio.indexterm.error__ssl_errors..error::ssl_errors] +[indexterm1 boost_asio.indexterm.error__ssl_errors..error::ssl_errors] + enum ssl_errors @@ -79362,7 +81494,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:error__system_category error::system_category] -[indexterm1 boost_asio.indexterm.error__system_category..error::system_category] +[indexterm1 boost_asio.indexterm.error__system_category..error::system_category] + static const boost::system::error_category & system_category = boost::asio::error::get_system_category(); @@ -79380,7 +81513,8 @@ A cancellation filter that enables terminal, partial and total cancellation. [section:execution__allocator execution::allocator] -[indexterm1 boost_asio.indexterm.execution__allocator..execution::allocator] +[indexterm1 boost_asio.indexterm.execution__allocator..execution::allocator] + A special value used for accessing the [link boost_asio.reference.execution__allocator_t `execution::allocator_t`] property. @@ -80348,7 +82482,8 @@ Obtain message associated with exception. [section:execution__blocking execution::blocking] -[indexterm1 boost_asio.indexterm.execution__blocking..execution::blocking] +[indexterm1 boost_asio.indexterm.execution__blocking..execution::blocking] + A special value used for accessing the [link boost_asio.reference.execution__blocking_t `execution::blocking_t`] property. @@ -80368,7 +82503,8 @@ A special value used for accessing the [link boost_asio.reference.execution__blo [section:execution__blocking_adaptation execution::blocking_adaptation] -[indexterm1 boost_asio.indexterm.execution__blocking_adaptation..execution::blocking_adaptation] +[indexterm1 boost_asio.indexterm.execution__blocking_adaptation..execution::blocking_adaptation] + A special value used for accessing the [link boost_asio.reference.execution__blocking_adaptation_t `execution::blocking_adaptation_t`] property. @@ -81905,7 +84041,8 @@ Get the value associated with a property object. [section:execution__bulk_execute execution::bulk_execute] -[indexterm1 boost_asio.indexterm.execution__bulk_execute..execution::bulk_execute] +[indexterm1 boost_asio.indexterm.execution__bulk_execute..execution::bulk_execute] + A customisation point that creates a bulk sender. @@ -81961,7 +84098,8 @@ The name `execution::bulk_execute` denotes a customisation point object. If `is_ [section:execution__bulk_guarantee execution::bulk_guarantee] -[indexterm1 boost_asio.indexterm.execution__bulk_guarantee..execution::bulk_guarantee] +[indexterm1 boost_asio.indexterm.execution__bulk_guarantee..execution::bulk_guarantee] + A special value used for accessing the [link boost_asio.reference.execution__bulk_guarantee_t `execution::bulk_guarantee_t`] property. @@ -83070,7 +85208,8 @@ Class template `can_submit` is a trait that is derived from `true_type` if the e [section:execution__connect execution::connect] -[indexterm1 boost_asio.indexterm.execution__connect..execution::connect] +[indexterm1 boost_asio.indexterm.execution__connect..execution::connect] + A customisation point that connects a sender to a receiver. @@ -83205,7 +85344,8 @@ The type of the expression `execution::connect(std::declval(), std::declval>; @@ -94223,7 +96408,8 @@ Trait for detecting objects that are usable as deferred operations. [section:experimental__is_promise_v experimental::is_promise_v] -[indexterm1 boost_asio.indexterm.experimental__is_promise_v..experimental::is_promise_v] +[indexterm1 boost_asio.indexterm.experimental__is_promise_v..experimental::is_promise_v] + constexpr bool is_promise_v =is_promise::value; @@ -94241,7 +96427,8 @@ Trait for detecting objects that are usable as deferred operations. [section:experimental__make_parallel_group experimental::make_parallel_group] -[indexterm1 boost_asio.indexterm.experimental__make_parallel_group..experimental::make_parallel_group] +[indexterm1 boost_asio.indexterm.experimental__make_parallel_group..experimental::make_parallel_group] + Create a group of operations that may be launched in parallel. @@ -94302,7 +96489,8 @@ For example: [section:experimental__operator_pipe_ experimental::operator|] -[indexterm1 boost_asio.indexterm.experimental__operator_pipe_..experimental::operator|] +[indexterm1 boost_asio.indexterm.experimental__operator_pipe_..experimental::operator|] + Pipe operator used to chain deferred operations. @@ -94462,7 +96650,8 @@ The completion signature for the group of operations. [section:experimental__prepend experimental::prepend] -[indexterm1 boost_asio.indexterm.experimental__prepend..experimental::prepend] +[indexterm1 boost_asio.indexterm.experimental__prepend..experimental::prepend] + Completion token type used to specify that the completion handler arguments should be passed additional values before the results of the operation. @@ -95044,7 +97233,8 @@ The primary template is not defined. [section:experimental__use_coro experimental::use_coro] -[indexterm1 boost_asio.indexterm.experimental__use_coro..experimental::use_coro] +[indexterm1 boost_asio.indexterm.experimental__use_coro..experimental::use_coro] + A completion token object that represents the currently executing resumable coroutine. @@ -95334,7 +97524,8 @@ Construct the adapted executor from the inner executor type. [section:experimental__use_promise experimental::use_promise] -[indexterm1 boost_asio.indexterm.experimental__use_promise..experimental::use_promise] +[indexterm1 boost_asio.indexterm.experimental__use_promise..experimental::use_promise] + constexpr use_promise_t use_promise; @@ -95794,6 +97985,11 @@ The [link boost_asio.reference.file_base `file_base`] class is used as a base fo [Open the file for reading and writing. ] ] + [ + [[link boost_asio.reference.file_base.sync_all_on_write [*sync_all_on_write]] [static]] + [Open the file so that write operations automatically synchronise the file data and metadata to disk. ] + ] + [ [[link boost_asio.reference.file_base.truncate [*truncate]] [static]] [Open the file with any existing contents truncated. ] @@ -95941,6 +98137,20 @@ Basis for seeking in a file. +[section:sync_all_on_write file_base::sync_all_on_write] + +[indexterm2 boost_asio.indexterm.file_base.sync_all_on_write..sync_all_on_write..file_base] +Open the file so that write operations automatically synchronise the file data and metadata to disk. + + + static const flags sync_all_on_write = implementation_defined; + + + +[endsect] + + + [section:truncate file_base::truncate] [indexterm2 boost_asio.indexterm.file_base.truncate..truncate..file_base] @@ -99987,7 +102197,8 @@ Obtain an identifier for the type of the protocol. [section:get_associated_allocator get_associated_allocator] -[indexterm1 boost_asio.indexterm.get_associated_allocator..get_associated_allocator] +[indexterm1 boost_asio.indexterm.get_associated_allocator..get_associated_allocator] + Helper function to obtain an object's associated allocator. template< @@ -100064,7 +102275,8 @@ Helper function to obtain an object's associated allocator. [section:get_associated_cancellation_slot get_associated_cancellation_slot] -[indexterm1 boost_asio.indexterm.get_associated_cancellation_slot..get_associated_cancellation_slot] +[indexterm1 boost_asio.indexterm.get_associated_cancellation_slot..get_associated_cancellation_slot] + Helper function to obtain an object's associated [link boost_asio.reference.cancellation_slot `cancellation_slot`]. template< @@ -100141,7 +102353,8 @@ Helper function to obtain an object's associated [link boost_asio.reference.canc [section:get_associated_executor get_associated_executor] -[indexterm1 boost_asio.indexterm.get_associated_executor..get_associated_executor] +[indexterm1 boost_asio.indexterm.get_associated_executor..get_associated_executor] + Helper function to obtain an object's associated executor. template< @@ -100257,7 +102470,8 @@ Helper function to obtain an object's associated executor. [section:high_resolution_timer high_resolution_timer] -[indexterm1 boost_asio.indexterm.high_resolution_timer..high_resolution_timer] +[indexterm1 boost_asio.indexterm.high_resolution_timer..high_resolution_timer] + Typedef for a timer based on the high resolution clock. @@ -100838,7 +103052,7 @@ For example: -To submit functions to the [link boost_asio.reference.io_context `io_context`], use the [link boost_asio.reference.dispatch `dispatch`] , [link boost_asio.reference.post `post`] or [link boost_asio.reference.defer `defer`] free functions. +To submit functions to the [link boost_asio.reference.io_context `io_context`], use the [link boost_asio.reference.dispatch `dispatch`], [link boost_asio.reference.post `post`] or [link boost_asio.reference.defer `defer`] free functions. For example: @@ -104221,7 +106435,8 @@ The destructor is used to inform the [link boost_asio.reference.io_context `io_c [section:io_service io_service] -[indexterm1 boost_asio.indexterm.io_service..io_service] +[indexterm1 boost_asio.indexterm.io_service..io_service] + Typedef for backwards compatibility. @@ -104500,7 +106715,7 @@ For example: -To submit functions to the [link boost_asio.reference.io_context `io_context`], use the [link boost_asio.reference.dispatch `dispatch`] , [link boost_asio.reference.post `post`] or [link boost_asio.reference.defer `defer`] free functions. +To submit functions to the [link boost_asio.reference.io_context `io_context`], use the [link boost_asio.reference.dispatch `dispatch`], [link boost_asio.reference.post `post`] or [link boost_asio.reference.defer `defer`] free functions. For example: @@ -106688,7 +108903,8 @@ The type used to represent an address as an unsigned integer. [section:ip__address_v4_iterator ip::address_v4_iterator] -[indexterm1 boost_asio.indexterm.ip__address_v4_iterator..ip::address_v4_iterator] +[indexterm1 boost_asio.indexterm.ip__address_v4_iterator..ip::address_v4_iterator] + An input iterator that can be used for traversing IPv4 addresses. @@ -106709,7 +108925,8 @@ An input iterator that can be used for traversing IPv4 addresses. [section:ip__address_v4_range ip::address_v4_range] -[indexterm1 boost_asio.indexterm.ip__address_v4_range..ip::address_v4_range] +[indexterm1 boost_asio.indexterm.ip__address_v4_range..ip::address_v4_range] + Represents a range of IPv4 addresses. @@ -107958,7 +110175,8 @@ Get the address as a string. [section:ip__address_v6_iterator ip::address_v6_iterator] -[indexterm1 boost_asio.indexterm.ip__address_v6_iterator..ip::address_v6_iterator] +[indexterm1 boost_asio.indexterm.ip__address_v6_iterator..ip::address_v6_iterator] + An input iterator that can be used for traversing IPv6 addresses. @@ -107979,7 +110197,8 @@ An input iterator that can be used for traversing IPv6 addresses. [section:ip__address_v6_range ip::address_v6_range] -[indexterm1 boost_asio.indexterm.ip__address_v6_range..ip::address_v6_range] +[indexterm1 boost_asio.indexterm.ip__address_v6_range..ip::address_v6_range] + Represents a range of IPv6 addresses. @@ -111354,10 +113573,10 @@ If used with v4\_mapped, return all matching IPv6 and IPv4 addresses. template< - typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ResolveToken ResolveToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.ip__basic_resolver.async_resolve.overload1 async_resolve]``( const query & q, - ResolveHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ResolveToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.ip__basic_resolver.async_resolve.overload1 more...]]`` @@ -111365,39 +113584,39 @@ Asynchronously perform forward resolution of a query to a list of entries. template< - typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ResolveToken ResolveToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.ip__basic_resolver.async_resolve.overload2 async_resolve]``( string_view host, string_view service, - ResolveHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ResolveToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.ip__basic_resolver.async_resolve.overload2 more...]]`` template< - typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ResolveToken ResolveToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.ip__basic_resolver.async_resolve.overload3 async_resolve]``( string_view host, string_view service, resolver_base::flags resolve_flags, - ResolveHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ResolveToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.ip__basic_resolver.async_resolve.overload3 more...]]`` template< - typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ResolveToken ResolveToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.ip__basic_resolver.async_resolve.overload4 async_resolve]``( const protocol_type & protocol, string_view host, string_view service, - ResolveHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ResolveToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.ip__basic_resolver.async_resolve.overload4 more...]]`` template< - typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ResolveToken ResolveToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.ip__basic_resolver.async_resolve.overload5 async_resolve]``( const protocol_type & protocol, string_view host, string_view service, resolver_base::flags resolve_flags, - ResolveHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ResolveToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.ip__basic_resolver.async_resolve.overload5 more...]]`` @@ -111405,10 +113624,10 @@ Asynchronously perform reverse resolution of an endpoint to a list of entries. template< - typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ResolveToken ResolveToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.ip__basic_resolver.async_resolve.overload6 async_resolve]``( const endpoint_type & e, - ResolveHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ResolveToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.ip__basic_resolver.async_resolve.overload6 more...]]`` @@ -111419,13 +113638,13 @@ Asynchronously perform reverse resolution of an endpoint to a list of entries. template< - typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ResolveToken ResolveToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_resolve( const query & q, - ResolveHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ResolveToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously resolve a query into a list of endpoint entries. +This function is used to asynchronously resolve a query into a list of endpoint entries. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -111435,18 +113654,30 @@ This function is used to asynchronously resolve a query into a list of endpoint [[q][A query object that determines what endpoints will be returned.]] -[[handler][The handler to be called when the resolve operation completes. Copies will be made of the handler as required. The function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the resolve completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. resolver::results_type results // Resolved endpoints as a range. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] -A successful resolve operation is guaranteed to pass a non-empty range to the handler. +A successful resolve operation is guaranteed to pass a non-empty range to the handler. + + +[heading Completion Signature] + + + + void(boost::system::error_code, results_type) + + + + + [endsect] @@ -111460,11 +113691,11 @@ Asynchronously perform forward resolution of a query to a list of entries. template< - typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ResolveToken ResolveToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_resolve( string_view host, string_view service, - ResolveHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ResolveToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to resolve host and service names into a list of endpoint entries. @@ -111479,20 +113710,30 @@ This function is used to resolve host and service names into a list of endpoint [[service][A string identifying the requested service. This may be a descriptive name or a numeric string corresponding to a port number. May be an empty string, in which case all resolved endpoints will have a port number of 0.]] -[[handler][The handler to be called when the resolve operation completes. Copies will be made of the handler as required. The function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the resolve completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. resolver::results_type results // Resolved endpoints as a range. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] A successful resolve operation is guaranteed to pass a non-empty range to the handler. +[heading Completion Signature] + + + + void(boost::system::error_code, results_type) + + + + + [heading Remarks] On POSIX systems, host names may be locally defined in the file `/etc/hosts`. On Windows, host names may be defined in the file `c:\windows\system32\drivers\etc\hosts`. Remote host name resolution is performed using DNS. Operating systems may use additional locations when resolving host names (such as NETBIOS names on Windows). @@ -111511,15 +113752,15 @@ Asynchronously perform forward resolution of a query to a list of entries. template< - typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ResolveToken ResolveToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_resolve( string_view host, string_view service, resolver_base::flags resolve_flags, - ResolveHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ResolveToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to resolve host and service names into a list of endpoint entries. +This function is used to resolve host and service names into a list of endpoint entries. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -111531,22 +113772,32 @@ This function is used to resolve host and service names into a list of endpoint [[service][A string identifying the requested service. This may be a descriptive name or a numeric string corresponding to a port number. May be an empty string, in which case all resolved endpoints will have a port number of 0.]] -[[resolve_flags][A set of flags that determine how name resolution should be performed. The default flags are suitable for communication with remote hosts. See the [link boost_asio.reference.ip__resolver_base `ip::resolver_base`] documentation for the set of available flags.]] +[[resolve_flags][A set of flags that determine how name resolution should be performed. The default flags are suitable for communication with remote hosts. See the [link boost_asio.reference.ip__resolver_base `ip::resolver_base`] documentation for the set of available flags.]] -[[handler][The handler to be called when the resolve operation completes. Copies will be made of the handler as required. The function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the resolve completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. resolver::results_type results // Resolved endpoints as a range. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] A successful resolve operation is guaranteed to pass a non-empty range to the handler. +[heading Completion Signature] + + + + void(boost::system::error_code, results_type) + + + + + [heading Remarks] On POSIX systems, host names may be locally defined in the file `/etc/hosts`. On Windows, host names may be defined in the file `c:\windows\system32\drivers\etc\hosts`. Remote host name resolution is performed using DNS. Operating systems may use additional locations when resolving host names (such as NETBIOS names on Windows). @@ -111565,15 +113816,15 @@ Asynchronously perform forward resolution of a query to a list of entries. template< - typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ResolveToken ResolveToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_resolve( const protocol_type & protocol, string_view host, string_view service, - ResolveHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ResolveToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to resolve host and service names into a list of endpoint entries. +This function is used to resolve host and service names into a list of endpoint entries. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -111587,20 +113838,30 @@ This function is used to resolve host and service names into a list of endpoint [[service][A string identifying the requested service. This may be a descriptive name or a numeric string corresponding to a port number. May be an empty string, in which case all resolved endpoints will have a port number of 0.]] -[[handler][The handler to be called when the resolve operation completes. Copies will be made of the handler as required. The function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the resolve completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. resolver::results_type results // Resolved endpoints as a range. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] A successful resolve operation is guaranteed to pass a non-empty range to the handler. +[heading Completion Signature] + + + + void(boost::system::error_code, results_type) + + + + + [heading Remarks] On POSIX systems, host names may be locally defined in the file `/etc/hosts`. On Windows, host names may be defined in the file `c:\windows\system32\drivers\etc\hosts`. Remote host name resolution is performed using DNS. Operating systems may use additional locations when resolving host names (such as NETBIOS names on Windows). @@ -111619,16 +113880,16 @@ Asynchronously perform forward resolution of a query to a list of entries. template< - typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ResolveToken ResolveToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_resolve( const protocol_type & protocol, string_view host, string_view service, resolver_base::flags resolve_flags, - ResolveHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ResolveToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to resolve host and service names into a list of endpoint entries. +This function is used to resolve host and service names into a list of endpoint entries. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -111642,22 +113903,32 @@ This function is used to resolve host and service names into a list of endpoint [[service][A string identifying the requested service. This may be a descriptive name or a numeric string corresponding to a port number. May be an empty string, in which case all resolved endpoints will have a port number of 0.]] -[[resolve_flags][A set of flags that determine how name resolution should be performed. The default flags are suitable for communication with remote hosts. See the [link boost_asio.reference.ip__resolver_base `ip::resolver_base`] documentation for the set of available flags.]] +[[resolve_flags][A set of flags that determine how name resolution should be performed. The default flags are suitable for communication with remote hosts. See the [link boost_asio.reference.ip__resolver_base `ip::resolver_base`] documentation for the set of available flags.]] -[[handler][The handler to be called when the resolve operation completes. Copies will be made of the handler as required. The function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the resolve completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. resolver::results_type results // Resolved endpoints as a range. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] A successful resolve operation is guaranteed to pass a non-empty range to the handler. +[heading Completion Signature] + + + + void(boost::system::error_code, results_type) + + + + + [heading Remarks] On POSIX systems, host names may be locally defined in the file `/etc/hosts`. On Windows, host names may be defined in the file `c:\windows\system32\drivers\etc\hosts`. Remote host name resolution is performed using DNS. Operating systems may use additional locations when resolving host names (such as NETBIOS names on Windows). @@ -111676,13 +113947,13 @@ Asynchronously perform reverse resolution of an endpoint to a list of entries. template< - typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ResolveToken ResolveToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_resolve( const endpoint_type & e, - ResolveHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ResolveToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously resolve an endpoint into a list of endpoint entries. +This function is used to asynchronously resolve an endpoint into a list of endpoint entries. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -111692,18 +113963,30 @@ This function is used to asynchronously resolve an endpoint into a list of endpo [[e][An endpoint object that determines what endpoints will be returned.]] -[[handler][The handler to be called when the resolve operation completes. Copies will be made of the handler as required. The function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the resolve completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. resolver::results_type results // Resolved endpoints as a range. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] -A successful resolve operation is guaranteed to pass a non-empty range to the handler. +A successful resolve operation is guaranteed to pass a non-empty range to the handler. + + +[heading Completion Signature] + + + + void(boost::system::error_code, results_type) + + + + + [endsect] @@ -112738,7 +115021,7 @@ This function is used to resolve host and service names into a list of endpoint [[service][A string identifying the requested service. This may be a descriptive name or a numeric string corresponding to a port number. May be an empty string, in which case all resolved endpoints will have a port number of 0.]] -[[resolve_flags][A set of flags that determine how name resolution should be performed. The default flags are suitable for communication with remote hosts. See the [link boost_asio.reference.ip__resolver_base `ip::resolver_base`] documentation for the set of available flags.]] +[[resolve_flags][A set of flags that determine how name resolution should be performed. The default flags are suitable for communication with remote hosts. See the [link boost_asio.reference.ip__resolver_base `ip::resolver_base`] documentation for the set of available flags.]] ] @@ -112794,7 +115077,7 @@ This function is used to resolve host and service names into a list of endpoint [[service][A string identifying the requested service. This may be a descriptive name or a numeric string corresponding to a port number. May be an empty string, in which case all resolved endpoints will have a port number of 0.]] -[[resolve_flags][A set of flags that determine how name resolution should be performed. The default flags are suitable for communication with remote hosts. See the [link boost_asio.reference.ip__resolver_base `ip::resolver_base`] documentation for the set of available flags.]] +[[resolve_flags][A set of flags that determine how name resolution should be performed. The default flags are suitable for communication with remote hosts. See the [link boost_asio.reference.ip__resolver_base `ip::resolver_base`] documentation for the set of available flags.]] [[ec][Set to indicate what error occurred, if any.]] @@ -112947,7 +115230,7 @@ This function is used to resolve host and service names into a list of endpoint [[service][A string identifying the requested service. This may be a descriptive name or a numeric string corresponding to a port number. May be an empty string, in which case all resolved endpoints will have a port number of 0.]] -[[resolve_flags][A set of flags that determine how name resolution should be performed. The default flags are suitable for communication with remote hosts. See the [link boost_asio.reference.ip__resolver_base `ip::resolver_base`] documentation for the set of available flags.]] +[[resolve_flags][A set of flags that determine how name resolution should be performed. The default flags are suitable for communication with remote hosts. See the [link boost_asio.reference.ip__resolver_base `ip::resolver_base`] documentation for the set of available flags.]] ] @@ -113006,7 +115289,7 @@ This function is used to resolve host and service names into a list of endpoint [[service][A string identifying the requested service. This may be a descriptive name or a numeric string corresponding to a port number. May be an empty string, in which case all resolved endpoints will have a port number of 0.]] -[[resolve_flags][A set of flags that determine how name resolution should be performed. The default flags are suitable for communication with remote hosts. See the [link boost_asio.reference.ip__resolver_base `ip::resolver_base`] documentation for the set of available flags.]] +[[resolve_flags][A set of flags that determine how name resolution should be performed. The default flags are suitable for communication with remote hosts. See the [link boost_asio.reference.ip__resolver_base `ip::resolver_base`] documentation for the set of available flags.]] [[ec][Set to indicate what error occurred, if any.]] @@ -116700,7 +118983,8 @@ The [link boost_asio.reference.ip__basic_resolver_entry `ip::basic_resolver_entr [section:ip__host_name ip::host_name] -[indexterm1 boost_asio.indexterm.ip__host_name..ip::host_name] +[indexterm1 boost_asio.indexterm.ip__host_name..ip::host_name] + Get the current host name. std::string ``[link boost_asio.reference.ip__host_name.overload1 host_name]``(); @@ -117750,7 +120034,8 @@ Construct to represent the IPv6 ICMP protocol. [section:ip__multicast__enable_loopback ip::multicast::enable_loopback] -[indexterm1 boost_asio.indexterm.ip__multicast__enable_loopback..ip::multicast::enable_loopback] +[indexterm1 boost_asio.indexterm.ip__multicast__enable_loopback..ip::multicast::enable_loopback] + Socket option determining whether outgoing multicast packets will be received on the same socket if it is a member of the multicast group. @@ -117801,7 +120086,8 @@ Getting the current option value: [section:ip__multicast__hops ip::multicast::hops] -[indexterm1 boost_asio.indexterm.ip__multicast__hops..ip::multicast::hops] +[indexterm1 boost_asio.indexterm.ip__multicast__hops..ip::multicast::hops] + Socket option for time-to-live associated with outgoing multicast packets. @@ -117852,7 +120138,8 @@ Getting the current option value: [section:ip__multicast__join_group ip::multicast::join_group] -[indexterm1 boost_asio.indexterm.ip__multicast__join_group..ip::multicast::join_group] +[indexterm1 boost_asio.indexterm.ip__multicast__join_group..ip::multicast::join_group] + Socket option to join a multicast group on a specified interface. @@ -117893,7 +120180,8 @@ Setting the option to join a multicast group: [section:ip__multicast__leave_group ip::multicast::leave_group] -[indexterm1 boost_asio.indexterm.ip__multicast__leave_group..ip::multicast::leave_group] +[indexterm1 boost_asio.indexterm.ip__multicast__leave_group..ip::multicast::leave_group] + Socket option to leave a multicast group on a specified interface. @@ -117934,7 +120222,8 @@ Setting the option to leave a multicast group: [section:ip__multicast__outbound_interface ip::multicast::outbound_interface] -[indexterm1 boost_asio.indexterm.ip__multicast__outbound_interface..ip::multicast::outbound_interface] +[indexterm1 boost_asio.indexterm.ip__multicast__outbound_interface..ip::multicast::outbound_interface] + Socket option for local interface to use for outgoing multicast packets. @@ -119082,7 +121371,8 @@ Get the network as an address in dotted decimal format. [section:ip__port_type ip::port_type] -[indexterm1 boost_asio.indexterm.ip__port_type..ip::port_type] +[indexterm1 boost_asio.indexterm.ip__port_type..ip::port_type] + Type used for storing port numbers. @@ -119564,7 +121854,8 @@ Protected destructor to prevent deletion through this type. [section:ip__scope_id_type ip::scope_id_type] -[indexterm1 boost_asio.indexterm.ip__scope_id_type..ip::scope_id_type] +[indexterm1 boost_asio.indexterm.ip__scope_id_type..ip::scope_id_type] + Type used for storing IPv6 scope IDs. @@ -122186,7 +124477,8 @@ Construct to represent the IPv6 UDP protocol. [section:ip__unicast__hops ip::unicast::hops] -[indexterm1 boost_asio.indexterm.ip__unicast__hops..ip::unicast::hops] +[indexterm1 boost_asio.indexterm.ip__unicast__hops..ip::unicast::hops] + Socket option for time-to-live associated with outgoing unicast packets. @@ -122237,7 +124529,8 @@ Getting the current option value: [section:ip__v4_mapped_t ip::v4_mapped_t] -[indexterm1 boost_asio.indexterm.ip__v4_mapped_t..ip::v4_mapped_t] +[indexterm1 boost_asio.indexterm.ip__v4_mapped_t..ip::v4_mapped_t] + Tag type used for distinguishing overloads that deal in IPv4-mapped IPv6 addresses. enum v4_mapped_t @@ -122268,7 +124561,8 @@ Tag type used for distinguishing overloads that deal in IPv4-mapped IPv6 address [section:ip__v6_only ip::v6_only] -[indexterm1 boost_asio.indexterm.ip__v6_only..ip::v6_only] +[indexterm1 boost_asio.indexterm.ip__v6_only..ip::v6_only] + Socket option for determining whether an IPv6 socket supports IPv6 communication only. @@ -122276,7 +124570,7 @@ Socket option for determining whether an IPv6 socket supports IPv6 communication -Implements the IPPROTO\_IPV6/IP\_V6ONLY socket option. +Implements the IPPROTO\_IPV6/IPV6\_V6ONLY socket option. [heading Examples] @@ -123399,7 +125693,8 @@ Get the underlying size of the endpoint in the native type. [section:local__connect_pair local::connect_pair] -[indexterm1 boost_asio.indexterm.local__connect_pair..local::connect_pair] +[indexterm1 boost_asio.indexterm.local__connect_pair..local::connect_pair] + Create a pair of connected sockets. template< @@ -125403,11 +127698,12 @@ Obtain an identifier for the type of the protocol. [section:make_strand make_strand] -[indexterm1 boost_asio.indexterm.make_strand..make_strand] -The `boost::asio::make_strand` function creates a [link boost_asio.reference.strand `strand`] object for an executor or execution context. +[indexterm1 boost_asio.indexterm.make_strand..make_strand] +The `boost::asio::make_strand` function creates a [link boost_asio.reference.strand `strand`] object for an executor or execution context. -Create a [link boost_asio.reference.strand `strand`] object for an executor. + +Create a [link boost_asio.reference.strand `strand`] object for an executor. template< typename ``[link boost_asio.reference.Executor1 Executor]``> @@ -125416,7 +127712,7 @@ Create a [link boost_asio.reference.strand `strand`] object for an executor. typename constraint< is_executor< Executor >::value||execution::is_executor< Executor >::value >::type = 0); `` [''''»''' [link boost_asio.reference.make_strand.overload1 more...]]`` -Create a [link boost_asio.reference.strand `strand`] object for an execution context. +Create a [link boost_asio.reference.strand `strand`] object for an execution context. template< typename ExecutionContext> @@ -125435,7 +127731,7 @@ Create a [link boost_asio.reference.strand `strand`] object for an execution co [section:overload1 make_strand (1 of 2 overloads)] -Create a [link boost_asio.reference.strand `strand`] object for an executor. +Create a [link boost_asio.reference.strand `strand`] object for an executor. template< @@ -125453,7 +127749,7 @@ Create a [link boost_asio.reference.strand `strand`] object for an executor. [section:overload2 make_strand (2 of 2 overloads)] -Create a [link boost_asio.reference.strand `strand`] object for an execution context. +Create a [link boost_asio.reference.strand `strand`] object for an execution context. template< @@ -125471,8 +127767,9 @@ Create a [link boost_asio.reference.strand `strand`] object for an execution co [section:make_work_guard make_work_guard] -[indexterm1 boost_asio.indexterm.make_work_guard..make_work_guard] -Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] object. +[indexterm1 boost_asio.indexterm.make_work_guard..make_work_guard] + +Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] object. template< typename ``[link boost_asio.reference.Executor1 Executor]``> @@ -125528,7 +127825,7 @@ Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] [section:overload1 make_work_guard (1 of 5 overloads)] -Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] object. +Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] object. template< @@ -125546,7 +127843,7 @@ Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] [section:overload2 make_work_guard (2 of 5 overloads)] -Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] object. +Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] object. template< @@ -125564,7 +127861,7 @@ Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] [section:overload3 make_work_guard (3 of 5 overloads)] -Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] object. +Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] object. template< @@ -125584,7 +127881,7 @@ Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] [section:overload4 make_work_guard (4 of 5 overloads)] -Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] object. +Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] object. template< @@ -125604,7 +127901,7 @@ Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] [section:overload5 make_work_guard (5 of 5 overloads)] -Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] object. +Create an [link boost_asio.reference.executor_work_guard `executor_work_guard`] object. template< @@ -126723,7 +129020,8 @@ The `data()` member function permits violations of type safety, so uses of it in [section:placeholders__bytes_transferred placeholders::bytes_transferred] -[indexterm1 boost_asio.indexterm.placeholders__bytes_transferred..placeholders::bytes_transferred] +[indexterm1 boost_asio.indexterm.placeholders__bytes_transferred..placeholders::bytes_transferred] + An argument placeholder, for use with boost::bind(), that corresponds to the bytes\_transferred argument of a handler for asynchronous functions such as `boost::asio::basic_stream_socket::async_write_some` or `boost::asio::async_write`. @@ -126743,7 +129041,8 @@ An argument placeholder, for use with boost::bind(), that corresponds to the byt [section:placeholders__endpoint placeholders::endpoint] -[indexterm1 boost_asio.indexterm.placeholders__endpoint..placeholders::endpoint] +[indexterm1 boost_asio.indexterm.placeholders__endpoint..placeholders::endpoint] + An argument placeholder, for use with boost::bind(), that corresponds to the results argument of a handler for asynchronous functions such as `boost::asio::async_connect`. @@ -126763,7 +129062,8 @@ An argument placeholder, for use with boost::bind(), that corresponds to the res [section:placeholders__error placeholders::error] -[indexterm1 boost_asio.indexterm.placeholders__error..placeholders::error] +[indexterm1 boost_asio.indexterm.placeholders__error..placeholders::error] + An argument placeholder, for use with boost::bind(), that corresponds to the error argument of a handler for any of the asynchronous functions. @@ -126783,7 +129083,8 @@ An argument placeholder, for use with boost::bind(), that corresponds to the err [section:placeholders__iterator placeholders::iterator] -[indexterm1 boost_asio.indexterm.placeholders__iterator..placeholders::iterator] +[indexterm1 boost_asio.indexterm.placeholders__iterator..placeholders::iterator] + An argument placeholder, for use with boost::bind(), that corresponds to the iterator argument of a handler for asynchronous functions such as `boost::asio::async_connect`. @@ -126803,7 +129104,8 @@ An argument placeholder, for use with boost::bind(), that corresponds to the ite [section:placeholders__results placeholders::results] -[indexterm1 boost_asio.indexterm.placeholders__results..placeholders::results] +[indexterm1 boost_asio.indexterm.placeholders__results..placeholders::results] + An argument placeholder, for use with boost::bind(), that corresponds to the results argument of a handler for asynchronous functions such as boost::asio::basic\_resolver::async\_resolve. @@ -126823,7 +129125,8 @@ An argument placeholder, for use with boost::bind(), that corresponds to the res [section:placeholders__signal_number placeholders::signal_number] -[indexterm1 boost_asio.indexterm.placeholders__signal_number..placeholders::signal_number] +[indexterm1 boost_asio.indexterm.placeholders__signal_number..placeholders::signal_number] + An argument placeholder, for use with boost::bind(), that corresponds to the signal\_number argument of a handler for asynchronous functions such as `boost::asio::signal_set::async_wait`. @@ -127077,13 +129380,13 @@ Asynchronously wait for the descriptor to become ready to read, ready to write, template< - typename ``[link boost_asio.reference.WaitHandler WaitHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WaitToken WaitToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_wait( wait_type w, - WaitHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WaitToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to perform an asynchronous wait for a descriptor to enter a ready to read, write or error condition state. +This function is used to perform an asynchronous wait for a descriptor to enter a ready to read, write or error condition state. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -127093,17 +129396,27 @@ This function is used to perform an asynchronous wait for a descriptor to enter [[w][Specifies the desired descriptor state.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the wait completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error // Result of operation + const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -128962,13 +131275,13 @@ Start an asynchronous read. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_some( const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read data from the stream descriptor. The function call always returns immediately. +This function is used to asynchronously read data from the stream descriptor. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -128976,33 +131289,43 @@ This function is used to asynchronously read data from the stream descriptor. Th [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. +The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: descriptor.async_read_some(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -129035,13 +131358,13 @@ Asynchronously wait for the descriptor to become ready to read, ready to write, template< - typename ``[link boost_asio.reference.WaitHandler WaitHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WaitToken WaitToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_wait( wait_type w, - WaitHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WaitToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to perform an asynchronous wait for a descriptor to enter a ready to read, write or error condition state. +This function is used to perform an asynchronous wait for a descriptor to enter a ready to read, write or error condition state. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -129051,17 +131374,27 @@ This function is used to perform an asynchronous wait for a descriptor to enter [[w][Specifies the desired descriptor state.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the wait completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( - const boost::system::error_code& error // Result of operation + const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Example] @@ -129114,13 +131447,13 @@ Start an asynchronous write. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_some( const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously write data to the stream descriptor. The function call always returns immediately. +This function is used to asynchronously write data to the stream descriptor. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -129128,33 +131461,43 @@ This function is used to asynchronously write data to the stream descriptor. The [variablelist -[[buffers][One or more data buffers to be written to the descriptor. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][One or more data buffers to be written to the descriptor. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. +The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: descriptor.async_write_some(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -130613,17 +132956,17 @@ The number of bytes read. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: descriptor.read_some(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -130667,7 +133010,7 @@ The number of bytes read. Returns 0 if an error occurred. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. @@ -130911,17 +133254,17 @@ The number of bytes written. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: descriptor.write_some(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -130965,7 +133308,7 @@ The number of bytes written. Returns 0 if an error occurred. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. @@ -131210,7 +133553,8 @@ Synchronous `read_some` and `write_some` operations are thread safe with respect [section:posix__descriptor posix::descriptor] -[indexterm1 boost_asio.indexterm.posix__descriptor..posix::descriptor] +[indexterm1 boost_asio.indexterm.posix__descriptor..posix::descriptor] + Typedef for the typical usage of [link boost_asio.reference.posix__basic_descriptor `posix::basic_descriptor`]. @@ -131536,7 +133880,8 @@ Protected destructor to prevent deletion through this type. [section:posix__stream_descriptor posix::stream_descriptor] -[indexterm1 boost_asio.indexterm.posix__stream_descriptor..posix::stream_descriptor] +[indexterm1 boost_asio.indexterm.posix__stream_descriptor..posix::stream_descriptor] + Typedef for the typical usage of a stream-oriented descriptor. @@ -131729,7 +134074,8 @@ Synchronous `read_some` and `write_some` operations are thread safe with respect [section:post post] -[indexterm1 boost_asio.indexterm.post..post] +[indexterm1 boost_asio.indexterm.post..post] + Submits a completion token or function object for execution. template< @@ -131777,7 +134123,7 @@ Submits a completion token or function object for execution. This function submits an object for execution using the object's associated executor. The function object is queued for execution, and is never called from the current thread prior to returning from `post()`. -The use of `post()`, rather than [link boost_asio.reference.defer `defer`] , indicates the caller's preference that the function object be eagerly queued for execution. +The use of `post()`, rather than [link boost_asio.reference.defer `defer`], indicates the caller's preference that the function object be eagerly queued for execution. This function has the following effects: @@ -131797,7 +134143,17 @@ This function has the following effects: * Performs `ex.post(std::move(handler), alloc)`. -* Returns `result.get()`. +* Returns `result.get()`. + + +[heading Completion Signature] + + + + void() + + + @@ -131823,7 +134179,7 @@ Submits a completion token or function object for execution. This function submits an object for execution using the specified executor. The function object is queued for execution, and is never called from the current thread prior to returning from `post()`. -The use of `post()`, rather than [link boost_asio.reference.defer `defer`] , indicates the caller's preference that the function object be eagerly queued for execution. +The use of `post()`, rather than [link boost_asio.reference.defer `defer`], indicates the caller's preference that the function object be eagerly queued for execution. This function has the following effects: @@ -131849,7 +134205,17 @@ This function has the following effects: * Performs `Executor(ex).post(std::move(f), alloc)`. -* Returns `result.get()`. +* Returns `result.get()`. + + +[heading Completion Signature] + + + + void() + + + @@ -131876,7 +134242,17 @@ Submits a completion token or function object for execution. [heading Return Value] -`post(ctx.get_executor(), forward(token))`. +`post(ctx.get_executor(), forward(token))`. + + +[heading Completion Signature] + + + + void() + + + @@ -131889,7 +134265,8 @@ Submits a completion token or function object for execution. [section:prefer prefer] -[indexterm1 boost_asio.indexterm.prefer..prefer] +[indexterm1 boost_asio.indexterm.prefer..prefer] + A customisation point that attempts to apply a property to an object. @@ -131999,7 +134376,8 @@ The result of the `prefer` expression. [section:query query] -[indexterm1 boost_asio.indexterm.query..query] +[indexterm1 boost_asio.indexterm.query..query] + A customisation point that queries the value of a property. @@ -132097,7 +134475,8 @@ The result of the `query` expression. [section:random_access_file random_access_file] -[indexterm1 boost_asio.indexterm.random_access_file..random_access_file] +[indexterm1 boost_asio.indexterm.random_access_file..random_access_file] + Typedef for the typical usage of a random-access file. @@ -132285,6 +134664,11 @@ Typedef for the typical usage of a random-access file. [Open the file for reading and writing. ] ] + [ + [[link boost_asio.reference.basic_random_access_file.sync_all_on_write [*sync_all_on_write]] [static]] + [Open the file so that write operations automatically synchronise the file data and metadata to disk. ] + ] + [ [[link boost_asio.reference.basic_random_access_file.truncate [*truncate]] [static]] [Open the file with any existing contents truncated. ] @@ -132321,7 +134705,8 @@ Synchronous `read_some_at` and `write_some_at` operations are thread safe with r [section:read read] -[indexterm1 boost_asio.indexterm.read..read] +[indexterm1 boost_asio.indexterm.read..read] + The `read` function is a composed operation that reads a certain amount of data from a stream before returning. @@ -132557,12 +134942,12 @@ The number of bytes transferred. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::read(s, boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Remarks] @@ -132631,12 +135016,12 @@ The number of bytes transferred. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::read(s, boost::asio::buffer(data, size), ec); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Remarks] @@ -132726,13 +135111,13 @@ The number of bytes transferred. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::read(s, boost::asio::buffer(data, size), boost::asio::transfer_at_least(32)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -133632,7 +136017,8 @@ The number of bytes read. If an error occurs, returns the total number of bytes [section:read_at read_at] -[indexterm1 boost_asio.indexterm.read_at..read_at] +[indexterm1 boost_asio.indexterm.read_at..read_at] + The `read_at` function is a composed operation that reads a certain amount of data at the specified offset before returning. @@ -133786,12 +136172,12 @@ The number of bytes transferred. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::read_at(d, 42, boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Remarks] @@ -133862,13 +136248,13 @@ The number of bytes transferred. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::read_at(d, 42, boost::asio::buffer(data, size), ec); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Remarks] @@ -133960,13 +136346,13 @@ The number of bytes transferred. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::read_at(d, 42, boost::asio::buffer(data, size), boost::asio::transfer_at_least(32)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -134316,7 +136702,8 @@ The number of bytes read. If an error occurs, returns the total number of bytes [section:read_until read_until] -[indexterm1 boost_asio.indexterm.read_until..read_until] +[indexterm1 boost_asio.indexterm.read_until..read_until] + The `read_until` function is a composed operation that reads data into a dynamic buffer sequence, or into a streambuf, until it contains a delimiter, matches a regular expression, or a function object indicates a match. @@ -136615,7 +139002,8 @@ The default implementation of the `is_match_condition` type trait evaluates to t [section:readable_pipe readable_pipe] -[indexterm1 boost_asio.indexterm.readable_pipe..readable_pipe] +[indexterm1 boost_asio.indexterm.readable_pipe..readable_pipe] + Typedef for the typical usage of a readable pipe. @@ -136753,7 +139141,8 @@ The [link boost_asio.reference.basic_readable_pipe `basic_readable_pipe`] class [section:redirect_error redirect_error] -[indexterm1 boost_asio.indexterm.redirect_error..redirect_error] +[indexterm1 boost_asio.indexterm.redirect_error..redirect_error] + Create a completion token to capture error\_code values to a variable. @@ -136869,7 +139258,8 @@ Constructor. [section:register_buffers register_buffers] -[indexterm1 boost_asio.indexterm.register_buffers..register_buffers] +[indexterm1 boost_asio.indexterm.register_buffers..register_buffers] + Register buffers with an execution context. template< @@ -137165,7 +139555,8 @@ Default constructor creates an invalid registered buffer identifier. [section:require require] -[indexterm1 boost_asio.indexterm.require..require] +[indexterm1 boost_asio.indexterm.require..require] + A customisation point that applies a concept-preserving property to an object. @@ -137207,7 +139598,8 @@ The name `require` denotes a customisation point object. The expression `boost:: [section:require_concept require_concept] -[indexterm1 boost_asio.indexterm.require_concept..require_concept] +[indexterm1 boost_asio.indexterm.require_concept..require_concept] + A customisation point that applies a concept-enforcing property to an object. @@ -137364,7 +139756,8 @@ The result of the `require` expression. [section:resolver_errc__try_again resolver_errc::try_again] -[indexterm1 boost_asio.indexterm.resolver_errc__try_again..resolver_errc::try_again] +[indexterm1 boost_asio.indexterm.resolver_errc__try_again..resolver_errc::try_again] + const error::netdb_errors try_again = error::host_not_found_try_again; @@ -137382,7 +139775,8 @@ The result of the `require` expression. [section:serial_port serial_port] -[indexterm1 boost_asio.indexterm.serial_port..serial_port] +[indexterm1 boost_asio.indexterm.serial_port..serial_port] + Typedef for the typical usage of a serial port. @@ -138330,7 +140724,8 @@ Exception thrown when trying to add a duplicate service to an [link boost_asio.r [section:signal_set signal_set] -[indexterm1 boost_asio.indexterm.signal_set..signal_set] +[indexterm1 boost_asio.indexterm.signal_set..signal_set] + Typedef for the typical usage of a signal set. @@ -139515,7 +141910,8 @@ Protected destructor to prevent deletion through this type. [section:spawn spawn] -[indexterm1 boost_asio.indexterm.spawn..spawn] +[indexterm1 boost_asio.indexterm.spawn..spawn] + Start a new stackful coroutine. @@ -141644,7 +144040,7 @@ This function may be used to configure the peer verification mode used by the co [variablelist -[[v][A bitmask of peer verification modes. See [link boost_asio.reference.ssl__verify_mode `ssl::verify_mode`] for available values.]] +[[v][A bitmask of peer verification modes. See [link boost_asio.reference.ssl__verify_mode `ssl::verify_mode`] for available values.]] ] @@ -141689,7 +144085,7 @@ This function may be used to configure the peer verification mode used by the co [variablelist -[[v][A bitmask of peer verification modes. See [link boost_asio.reference.ssl__verify_mode `ssl::verify_mode`] for available values.]] +[[v][A bitmask of peer verification modes. See [link boost_asio.reference.ssl__verify_mode `ssl::verify_mode`] for available values.]] [[ec][Set to indicate what error occurred, if any.]] @@ -143272,7 +145668,8 @@ Protected destructor to prevent deletion through this type. [section:ssl__error__get_stream_category ssl::error::get_stream_category] -[indexterm1 boost_asio.indexterm.ssl__error__get_stream_category..ssl::error::get_stream_category] +[indexterm1 boost_asio.indexterm.ssl__error__get_stream_category..ssl::error::get_stream_category] + const boost::system::error_category & get_stream_category(); @@ -143290,7 +145687,8 @@ Protected destructor to prevent deletion through this type. [section:ssl__error__make_error_code ssl::error::make_error_code] -[indexterm1 boost_asio.indexterm.ssl__error__make_error_code..ssl::error::make_error_code] +[indexterm1 boost_asio.indexterm.ssl__error__make_error_code..ssl::error::make_error_code] + boost::system::error_code make_error_code( stream_errors e); @@ -143309,7 +145707,8 @@ Protected destructor to prevent deletion through this type. [section:ssl__error__stream_category ssl::error::stream_category] -[indexterm1 boost_asio.indexterm.ssl__error__stream_category..ssl::error::stream_category] +[indexterm1 boost_asio.indexterm.ssl__error__stream_category..ssl::error::stream_category] + static const boost::system::error_category & stream_category = boost::asio::ssl::error::get_stream_category(); @@ -143327,7 +145726,8 @@ Protected destructor to prevent deletion through this type. [section:ssl__error__stream_errors ssl::error::stream_errors] -[indexterm1 boost_asio.indexterm.ssl__error__stream_errors..ssl::error::stream_errors] +[indexterm1 boost_asio.indexterm.ssl__error__stream_errors..ssl::error::stream_errors] + enum stream_errors [indexterm2 boost_asio.indexterm.ssl__error__stream_errors.stream_truncated..stream_truncated..ssl::error::stream_errors] @@ -143778,6 +146178,8 @@ Provides stream-oriented functionality using SSL. [ [[link boost_asio.reference.ssl__stream.stream [*stream]] [constructor]] [Construct a stream. + [hr] + Construct a stream from an existing native implementation. [hr] Move-construct a stream from another. ] ] @@ -143831,19 +146233,19 @@ Start an asynchronous SSL handshake. template< - typename ``[link boost_asio.reference.HandshakeHandler HandshakeHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.HandshakeToken HandshakeToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.ssl__stream.async_handshake.overload1 async_handshake]``( handshake_type type, - HandshakeHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + HandshakeToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.ssl__stream.async_handshake.overload1 more...]]`` template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.BufferedHandshakeHandler BufferedHandshakeHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.BufferedHandshakeToken BufferedHandshakeToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.ssl__stream.async_handshake.overload2 async_handshake]``( handshake_type type, const ConstBufferSequence & buffers, - BufferedHandshakeHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + BufferedHandshakeToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.ssl__stream.async_handshake.overload2 more...]]`` @@ -143854,13 +146256,13 @@ Start an asynchronous SSL handshake. template< - typename ``[link boost_asio.reference.HandshakeHandler HandshakeHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.HandshakeToken HandshakeToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_handshake( handshake_type type, - HandshakeHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + HandshakeToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously perform an SSL handshake on the stream. This function call always returns immediately. +This function is used to asynchronously perform an SSL handshake on the stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -143870,17 +146272,27 @@ This function is used to asynchronously perform an SSL handshake on the stream. [[type][The type of handshaking to be performed, i.e. as a client or as a server.]] -[[handler][The handler to be called when the handshake operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the handshake completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error // Result of operation. ); `` -]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -143906,14 +146318,14 @@ Start an asynchronous SSL handshake. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.BufferedHandshakeHandler BufferedHandshakeHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.BufferedHandshakeToken BufferedHandshakeToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_handshake( handshake_type type, const ConstBufferSequence & buffers, - BufferedHandshakeHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + BufferedHandshakeToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously perform an SSL handshake on the stream. This function call always returns immediately. +This function is used to asynchronously perform an SSL handshake on the stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -143923,20 +146335,30 @@ This function is used to asynchronously perform an SSL handshake on the stream. [[type][The type of handshaking to be performed, i.e. as a client or as a server.]] -[[buffers][The buffered data to be reused for the handshake. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The buffered data to be reused for the handshake. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] -[[handler][The handler to be called when the handshake operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the handshake completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Amount of buffers used in handshake. ); `` -]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -143964,13 +146386,13 @@ Start an asynchronous read. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_some( const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read one or more bytes of data from the stream. The function call always returns immediately. +This function is used to asynchronously read one or more bytes of data from the stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -143978,23 +146400,33 @@ This function is used to asynchronously read one or more bytes of data from the [variablelist -[[buffers][The buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] -[[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The async\_read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. +The async\_read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. [heading Per-Operation Cancellation] @@ -144021,12 +146453,12 @@ Asynchronously shut down SSL on the stream. template< - typename ``[link boost_asio.reference.ShutdownHandler ShutdownHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ShutdownToken ShutdownToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_shutdown( - ShutdownHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ShutdownToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously shut down SSL on the stream. This function call always returns immediately. +This function is used to asynchronously shut down SSL on the stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -144034,17 +146466,27 @@ This function is used to asynchronously shut down SSL on the stream. This functi [variablelist -[[handler][The handler to be called when the handshake operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the shutdown completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error // Result of operation. ); `` -]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [heading Per-Operation Cancellation] This asynchronous operation supports cancellation for the following [link boost_asio.reference.cancellation_type `cancellation_type`] values: @@ -144070,13 +146512,13 @@ Start an asynchronous write. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_some( const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously write one or more bytes of data to the stream. The function call always returns immediately. +This function is used to asynchronously write one or more bytes of data to the stream. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -144084,23 +146526,33 @@ This function is used to asynchronously write one or more bytes of data to the s [variablelist -[[buffers][The data to be written to the stream. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called.]] +[[buffers][The data to be written to the stream. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the completion handler is called.]] -[[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The async\_write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. +The async\_write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. [heading Per-Operation Cancellation] @@ -144688,7 +147140,7 @@ The number of bytes read. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. @@ -144732,7 +147184,7 @@ The number of bytes read. Returns 0 if an error occurred. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. @@ -144994,7 +147446,7 @@ This function may be used to configure the peer verification mode used by the st [variablelist -[[v][A bitmask of peer verification modes. See [link boost_asio.reference.ssl__verify_mode `ssl::verify_mode`] for available values.]] +[[v][A bitmask of peer verification modes. See [link boost_asio.reference.ssl__verify_mode `ssl::verify_mode`] for available values.]] ] @@ -145039,7 +147491,7 @@ This function may be used to configure the peer verification mode used by the st [variablelist -[[v][A bitmask of peer verification modes. See [link boost_asio.reference.ssl__verify_mode `ssl::verify_mode`] for available values.]] +[[v][A bitmask of peer verification modes. See [link boost_asio.reference.ssl__verify_mode `ssl::verify_mode`] for available values.]] [[ec][Set to indicate what error occurred, if any.]] @@ -145144,15 +147596,26 @@ Construct a stream. `` [''''»''' [link boost_asio.reference.ssl__stream.stream.overload1 more...]]`` -Move-construct a stream from another. +Construct a stream from an existing native implementation. + template< + typename Arg> ``[link boost_asio.reference.ssl__stream.stream.overload2 stream]``( - stream && other); + Arg && arg, + native_handle_type handle); `` [''''»''' [link boost_asio.reference.ssl__stream.stream.overload2 more...]]`` -[section:overload1 ssl::stream::stream (1 of 2 overloads)] +Move-construct a stream from another. + + + ``[link boost_asio.reference.ssl__stream.stream.overload3 stream]``( + stream && other); + `` [''''»''' [link boost_asio.reference.ssl__stream.stream.overload3 more...]]`` + + +[section:overload1 ssl::stream::stream (1 of 3 overloads)] Construct a stream. @@ -145186,7 +147649,41 @@ This constructor creates a stream and initialises the underlying stream object. -[section:overload2 ssl::stream::stream (2 of 2 overloads)] +[section:overload2 ssl::stream::stream (2 of 3 overloads)] + + +Construct a stream from an existing native implementation. + + + template< + typename Arg> + stream( + Arg && arg, + native_handle_type handle); + + +This constructor creates a stream and initialises the underlying stream object. On success, ownership of the native implementation is transferred to the stream, and it will be cleaned up when the stream is destroyed. + + +[heading Parameters] + + +[variablelist + +[[arg][The argument to be passed to initialise the underlying stream.]] + +[[handle][An existing native SSL implementation. ]] + +] + + + + +[endsect] + + + +[section:overload3 ssl::stream::stream (3 of 3 overloads)] Move-construct a stream from another. @@ -145276,7 +147773,7 @@ The number of bytes written. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. @@ -145320,7 +147817,7 @@ The number of bytes written. Returns 0 if an error occurred. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. @@ -145489,8 +147986,9 @@ Protected destructor to prevent deletion through this type. [section:ssl__verify_client_once ssl::verify_client_once] -[indexterm1 boost_asio.indexterm.ssl__verify_client_once..ssl::verify_client_once] -Do not request client certificate on renegotiation. Ignored unless [link boost_asio.reference.ssl__verify_peer `ssl::verify_peer`] is set. +[indexterm1 boost_asio.indexterm.ssl__verify_client_once..ssl::verify_client_once] + +Do not request client certificate on renegotiation. Ignored unless [link boost_asio.reference.ssl__verify_peer `ssl::verify_peer`] is set. const int verify_client_once = implementation_defined; @@ -145618,8 +148116,9 @@ Constructor. [section:ssl__verify_fail_if_no_peer_cert ssl::verify_fail_if_no_peer_cert] -[indexterm1 boost_asio.indexterm.ssl__verify_fail_if_no_peer_cert..ssl::verify_fail_if_no_peer_cert] -Fail verification if the peer has no certificate. Ignored unless [link boost_asio.reference.ssl__verify_peer `ssl::verify_peer`] is set. +[indexterm1 boost_asio.indexterm.ssl__verify_fail_if_no_peer_cert..ssl::verify_fail_if_no_peer_cert] + +Fail verification if the peer has no certificate. Ignored unless [link boost_asio.reference.ssl__verify_peer `ssl::verify_peer`] is set. const int verify_fail_if_no_peer_cert = implementation_defined; @@ -145638,7 +148137,8 @@ Fail verification if the peer has no certificate. Ignored unless [link boost_asi [section:ssl__verify_mode ssl::verify_mode] -[indexterm1 boost_asio.indexterm.ssl__verify_mode..ssl::verify_mode] +[indexterm1 boost_asio.indexterm.ssl__verify_mode..ssl::verify_mode] + Bitmask type for peer verification. @@ -145649,13 +148149,13 @@ Bitmask type for peer verification. Possible values are: -* [link boost_asio.reference.ssl__verify_none `ssl::verify_none`] +* [link boost_asio.reference.ssl__verify_none `ssl::verify_none`] -* [link boost_asio.reference.ssl__verify_peer `ssl::verify_peer`] +* [link boost_asio.reference.ssl__verify_peer `ssl::verify_peer`] -* [link boost_asio.reference.ssl__verify_fail_if_no_peer_cert `ssl::verify_fail_if_no_peer_cert`] +* [link boost_asio.reference.ssl__verify_fail_if_no_peer_cert `ssl::verify_fail_if_no_peer_cert`] -* [link boost_asio.reference.ssl__verify_client_once `ssl::verify_client_once`] +* [link boost_asio.reference.ssl__verify_client_once `ssl::verify_client_once`] @@ -145672,7 +148172,8 @@ Possible values are: [section:ssl__verify_none ssl::verify_none] -[indexterm1 boost_asio.indexterm.ssl__verify_none..ssl::verify_none] +[indexterm1 boost_asio.indexterm.ssl__verify_none..ssl::verify_none] + No verification. @@ -145692,7 +148193,8 @@ No verification. [section:ssl__verify_peer ssl::verify_peer] -[indexterm1 boost_asio.indexterm.ssl__verify_peer..ssl::verify_peer] +[indexterm1 boost_asio.indexterm.ssl__verify_peer..ssl::verify_peer] + Verify the peer. @@ -145712,7 +148214,8 @@ Verify the peer. [section:static_thread_pool static_thread_pool] -[indexterm1 boost_asio.indexterm.static_thread_pool..static_thread_pool] +[indexterm1 boost_asio.indexterm.static_thread_pool..static_thread_pool] + typedef thread_pool static_thread_pool; @@ -145858,7 +148361,7 @@ The thread pool class is an execution context where functions are permitted to r -To submit functions to the thread pool, use the [link boost_asio.reference.dispatch `dispatch`] , [link boost_asio.reference.post `post`] or [link boost_asio.reference.defer `defer`] free functions. +To submit functions to the thread pool, use the [link boost_asio.reference.dispatch `dispatch`], [link boost_asio.reference.post `post`] or [link boost_asio.reference.defer `defer`] free functions. For example: @@ -145904,7 +148407,8 @@ For example: [section:steady_timer steady_timer] -[indexterm1 boost_asio.indexterm.steady_timer..steady_timer] +[indexterm1 boost_asio.indexterm.steady_timer..steady_timer] + Typedef for a timer based on the steady clock. @@ -146988,7 +149492,8 @@ Destructor. [section:stream_file stream_file] -[indexterm1 boost_asio.indexterm.stream_file..stream_file] +[indexterm1 boost_asio.indexterm.stream_file..stream_file] + Typedef for the typical usage of a stream-oriented file. @@ -147181,6 +149686,11 @@ Typedef for the typical usage of a stream-oriented file. [Open the file for reading and writing. ] ] + [ + [[link boost_asio.reference.basic_stream_file.sync_all_on_write [*sync_all_on_write]] [static]] + [Open the file so that write operations automatically synchronise the file data and metadata to disk. ] + ] + [ [[link boost_asio.reference.basic_stream_file.truncate [*truncate]] [static]] [Open the file with any existing contents truncated. ] @@ -147219,7 +149729,8 @@ The [link boost_asio.reference.basic_stream_file `basic_stream_file`] class temp [section:streambuf streambuf] -[indexterm1 boost_asio.indexterm.streambuf..streambuf] +[indexterm1 boost_asio.indexterm.streambuf..streambuf] + Typedef for the typical usage of [link boost_asio.reference.basic_streambuf `basic_streambuf`]. @@ -148124,7 +150635,8 @@ Destructor shuts down all threads in the system thread pool. [section:system_executor system_executor] -[indexterm1 boost_asio.indexterm.system_executor..system_executor] +[indexterm1 boost_asio.indexterm.system_executor..system_executor] + An executor that uses arbitrary threads. @@ -148246,7 +150758,8 @@ The system executor represents an execution context where functions are permitte [section:system_timer system_timer] -[indexterm1 boost_asio.indexterm.system_timer..system_timer] +[indexterm1 boost_asio.indexterm.system_timer..system_timer] + Typedef for a timer based on the system clock. @@ -148503,7 +151016,8 @@ This typedef uses the C++11 `` standard library facility, if available. [section:this_coro__cancellation_state this_coro::cancellation_state] -[indexterm1 boost_asio.indexterm.this_coro__cancellation_state..this_coro::cancellation_state] +[indexterm1 boost_asio.indexterm.this_coro__cancellation_state..this_coro::cancellation_state] + Awaitable object that returns the cancellation state of the current coroutine. @@ -148587,7 +151101,8 @@ Awaitable type that returns the cancellation state of the current coroutine. [section:this_coro__executor this_coro::executor] -[indexterm1 boost_asio.indexterm.this_coro__executor..this_coro::executor] +[indexterm1 boost_asio.indexterm.this_coro__executor..this_coro::executor] + Awaitable object that returns the executor of the current coroutine. @@ -148649,7 +151164,8 @@ Awaitable type that returns the executor of the current coroutine. [section:this_coro__reset_cancellation_state this_coro::reset_cancellation_state] -[indexterm1 boost_asio.indexterm.this_coro__reset_cancellation_state..this_coro::reset_cancellation_state] +[indexterm1 boost_asio.indexterm.this_coro__reset_cancellation_state..this_coro::reset_cancellation_state] + Returns an awaitable object that may be used to reset the cancellation state of the current coroutine. constexpr unspecified ``[link boost_asio.reference.this_coro__reset_cancellation_state.overload1 reset_cancellation_state]``(); @@ -148804,7 +151320,8 @@ The cancellation state is shared by all coroutines in the same "thread of execut [section:this_coro__throw_if_cancelled this_coro::throw_if_cancelled] -[indexterm1 boost_asio.indexterm.this_coro__throw_if_cancelled..this_coro::throw_if_cancelled] +[indexterm1 boost_asio.indexterm.this_coro__throw_if_cancelled..this_coro::throw_if_cancelled] + Returns an awaitable object that may be used to determine whether the coroutine throws if trying to suspend when it has been cancelled. constexpr unspecified ``[link boost_asio.reference.this_coro__throw_if_cancelled.overload1 throw_if_cancelled]``(); @@ -149041,7 +151558,7 @@ The thread pool class is an execution context where functions are permitted to r -To submit functions to the thread pool, use the [link boost_asio.reference.dispatch `dispatch`] , [link boost_asio.reference.post `post`] or [link boost_asio.reference.defer `defer`] free functions. +To submit functions to the thread pool, use the [link boost_asio.reference.dispatch `dispatch`], [link boost_asio.reference.post `post`] or [link boost_asio.reference.defer `defer`] free functions. For example: @@ -151743,7 +154260,8 @@ Convert to POSIX duration type. [section:transfer_all transfer_all] -[indexterm1 boost_asio.indexterm.transfer_all..transfer_all] +[indexterm1 boost_asio.indexterm.transfer_all..transfer_all] + Return a completion condition function object that indicates that a read or write operation should continue until all of the data has been transferred, or until an error occurs. @@ -151789,7 +154307,8 @@ Reading until a buffer is full: [section:transfer_at_least transfer_at_least] -[indexterm1 boost_asio.indexterm.transfer_at_least..transfer_at_least] +[indexterm1 boost_asio.indexterm.transfer_at_least..transfer_at_least] + Return a completion condition function object that indicates that a read or write operation should continue until a minimum number of bytes has been transferred, or until an error occurs. @@ -151836,7 +154355,8 @@ Reading until a buffer is full or contains at least 64 bytes: [section:transfer_exactly transfer_exactly] -[indexterm1 boost_asio.indexterm.transfer_exactly..transfer_exactly] +[indexterm1 boost_asio.indexterm.transfer_exactly..transfer_exactly] + Return a completion condition function object that indicates that a read or write operation should continue until an exact number of bytes has been transferred, or until an error occurs. @@ -151883,7 +154403,8 @@ Reading until a buffer is full or contains exactly 64 bytes: [section:use_awaitable use_awaitable] -[indexterm1 boost_asio.indexterm.use_awaitable..use_awaitable] +[indexterm1 boost_asio.indexterm.use_awaitable..use_awaitable] + A completion token object that represents the currently executing coroutine. @@ -152173,8 +154694,9 @@ Construct the adapted executor from the inner executor type. [section:use_future use_future] -[indexterm1 boost_asio.indexterm.use_future..use_future] -A special value, similar to std::nothrow. +[indexterm1 boost_asio.indexterm.use_future..use_future] + +A completion token object that causes an asynchronous operation to return a future. constexpr use_future_t use_future; @@ -152197,7 +154719,7 @@ See the documentation for [link boost_asio.reference.use_future_t `use_future_t` [indexterm1 boost_asio.indexterm.use_future_t..use_future_t] -Class used to specify that an asynchronous operation should return a future. +A completion token type that causes an asynchronous operation to return a future. template< @@ -152251,7 +154773,7 @@ Class used to specify that an asynchronous operation should return a future. ] -The [link boost_asio.reference.use_future_t `use_future_t`] class is used to indicate that an asynchronous operation should return a std::future object. A [link boost_asio.reference.use_future_t `use_future_t`] object may be passed as a handler to an asynchronous operation, typically using the special value `boost::asio::use_future`. For example: +The [link boost_asio.reference.use_future_t `use_future_t`] class is a completion token type that is used to indicate that an asynchronous operation should return a std::future object. A [link boost_asio.reference.use_future_t `use_future_t`] object may be passed as a completion token to an asynchronous operation, typically using the special value `boost::asio::use_future`. For example: @@ -152733,12 +155255,12 @@ Start an asynchronous wait on the object handle. template< - typename ``[link boost_asio.reference.WaitHandler WaitHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WaitToken WaitToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_wait( - WaitHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WaitToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is be used to initiate an asynchronous wait against the object handle. It always returns immediately. +This function is be used to initiate an asynchronous wait against the object handle. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -152746,17 +155268,27 @@ This function is be used to initiate an asynchronous wait against the object han [variablelist -[[handler][The handler to be called when the object handle is set to the signalled state. Copies will be made of the handler as required. The function signature of the handler must be: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the wait completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` void handler( const boost::system::error_code& error // Result of operation. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`]. ]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code) + + + + + [endsect] @@ -154953,14 +157485,14 @@ Start an asynchronous read at the specified offset. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_some_at( uint64_t offset, const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read data from the random-access handle. The function call always returns immediately. +This function is used to asynchronously read data from the random-access handle. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -154970,33 +157502,43 @@ This function is used to asynchronously read data from the random-access handle. [[offset][The offset at which the data will be read.]] -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read_at `async_read_at`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. +The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read_at `async_read_at`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: handle.async_read_some_at(42, boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -155027,14 +157569,14 @@ Start an asynchronous write at the specified offset. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_some_at( uint64_t offset, const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously write data to the random-access handle. The function call always returns immediately. +This function is used to asynchronously write data to the random-access handle. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -155044,33 +157586,43 @@ This function is used to asynchronously write data to the random-access handle. [[offset][The offset at which the data will be written.]] -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write_at `async_write_at`] function if you need to ensure that all data is written before the asynchronous operation completes. +The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write_at `async_write_at`] function if you need to ensure that all data is written before the asynchronous operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: handle.async_write_some_at(42, boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -155177,7 +157729,7 @@ Construct a random-access handle without opening it. typename constraint< is_convertible< ExecutionContext &, execution_context & >::value, defaulted_constraint >::type = defaulted_constraint()); -This constructor creates a random-access handle without opening it. The handle needs to be opened or assigned before data can be sent or received on it. +This constructor creates a random-access handle without opening it. The handle needs to be opened or assigned before data can be written to or read from it. [heading Parameters] @@ -155877,17 +158429,17 @@ The number of bytes read. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read_at `read_at`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read_at `read_at`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: handle.read_some_at(42, boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -155934,7 +158486,7 @@ The number of bytes read. Returns 0 if an error occurred. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read_at `read_at`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read_at `read_at`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. @@ -156011,17 +158563,17 @@ The number of bytes written. [heading Remarks] -The write\_some\_at operation may not write all of the data. Consider using the [link boost_asio.reference.write_at `write_at`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some\_at operation may not write all of the data. Consider using the [link boost_asio.reference.write_at `write_at`] function if you need to ensure that all data is written before the blocking operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: handle.write_some_at(42, boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -156068,7 +158620,7 @@ The number of bytes written. Returns 0 if an error occurred. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write_at `write_at`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write_at `write_at`] function if you need to ensure that all data is written before the blocking operation completes. @@ -156465,13 +159017,13 @@ Start an asynchronous read. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, - typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.ReadToken ReadToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_some( const MutableBufferSequence & buffers, - ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + ReadToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously read data from the stream handle. The function call always returns immediately. +This function is used to asynchronously read data from the stream handle. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -156479,33 +159031,43 @@ This function is used to asynchronously read data from the stream handle. The fu [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. +The read operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.async_read `async_read`] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: handle.async_read_some(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -156536,13 +159098,13 @@ Start an asynchronous write. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, - typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> + typename ``[link boost_asio.reference.WriteToken WriteToken]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_some( const ConstBufferSequence & buffers, - WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); + WriteToken && token = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); -This function is used to asynchronously write data to the stream handle. The function call always returns immediately. +This function is used to asynchronously write data to the stream handle. It is an initiating function for an [link boost_asio.overview.model.async_ops asynchronous operation], and always returns immediately. [heading Parameters] @@ -156550,33 +159112,43 @@ This function is used to asynchronously write data to the stream handle. The fun [variablelist -[[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.]] +[[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 completion handler is called.]] -[[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: +[[token][The [link boost_asio.overview.model.completion_tokens completion token] that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include [link boost_asio.reference.use_future `use_future`], [link boost_asio.reference.use_awaitable `use_awaitable`], [link boost_asio.reference.yield_context `yield_context`], or a function object with the correct completion signature. The function signature of the completion handler must be: `` 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. ); `` -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 manner equivalent to using [link boost_asio.reference.post `post`].]] +Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] +[heading Completion Signature] + + + + void(boost::system::error_code, std::size_t) + + + + + [heading Remarks] -The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. +The write operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.async_write `async_write`] function if you need to ensure that all data is written before the asynchronous operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: handle.async_write_some(boost::asio::buffer(data, size), handler); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Per-Operation Cancellation] @@ -156683,7 +159255,7 @@ Construct a stream handle without opening it. typename constraint< is_convertible< ExecutionContext &, execution_context & >::value, defaulted_constraint >::type = defaulted_constraint()); -This constructor creates a stream handle without opening it. The handle needs to be opened or assigned before data can be sent or received on it. +This constructor creates a stream handle without opening it. The handle needs to be opened or assigned before data can be written to or read from it. [heading Parameters] @@ -157378,17 +159950,17 @@ The number of bytes read. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. [heading Example] -To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: handle.read_some(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -157432,7 +160004,7 @@ The number of bytes read. Returns 0 if an error occurred. [heading Remarks] -The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. +The read\_some operation may not read all of the requested number of bytes. Consider using the [link boost_asio.reference.read `read`] function if you need to ensure that the requested amount of data is read before the blocking operation completes. @@ -157504,17 +160076,17 @@ The number of bytes written. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: handle.write_some(boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -157558,7 +160130,7 @@ The number of bytes written. Returns 0 if an error occurred. [heading Remarks] -The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. +The write\_some operation may not transmit all of the data to the peer. Consider using the [link boost_asio.reference.write `write`] function if you need to ensure that all data is written before the blocking operation completes. @@ -157753,7 +160325,8 @@ The [link boost_asio.reference.windows__basic_stream_handle `windows::basic_stre [section:windows__object_handle windows::object_handle] -[indexterm1 boost_asio.indexterm.windows__object_handle..windows::object_handle] +[indexterm1 boost_asio.indexterm.windows__object_handle..windows::object_handle] + Typedef for the typical usage of an object handle. @@ -157886,7 +160459,8 @@ The [link boost_asio.reference.windows__basic_object_handle `windows::basic_obje [section:windows__overlapped_handle windows::overlapped_handle] -[indexterm1 boost_asio.indexterm.windows__overlapped_handle..windows::overlapped_handle] +[indexterm1 boost_asio.indexterm.windows__overlapped_handle..windows::overlapped_handle] + Typedef for the typical usage of an overlapped handle. @@ -158352,7 +160926,8 @@ Destructor automatically frees the OVERLAPPED object unless released. [section:windows__random_access_handle windows::random_access_handle] -[indexterm1 boost_asio.indexterm.windows__random_access_handle..windows::random_access_handle] +[indexterm1 boost_asio.indexterm.windows__random_access_handle..windows::random_access_handle] + Typedef for the typical usage of a random-access handle. @@ -158495,7 +161070,8 @@ The [link boost_asio.reference.windows__basic_random_access_handle `windows::bas [section:windows__stream_handle windows::stream_handle] -[indexterm1 boost_asio.indexterm.windows__stream_handle..windows::stream_handle] +[indexterm1 boost_asio.indexterm.windows__stream_handle..windows::stream_handle] + Typedef for the typical usage of a stream-oriented handle. @@ -158639,7 +161215,8 @@ The [link boost_asio.reference.windows__basic_stream_handle `windows::basic_stre [section:writable_pipe writable_pipe] -[indexterm1 boost_asio.indexterm.writable_pipe..writable_pipe] +[indexterm1 boost_asio.indexterm.writable_pipe..writable_pipe] + Typedef for the typical usage of a writable pipe. @@ -158776,7 +161353,8 @@ The [link boost_asio.reference.basic_writable_pipe `basic_writable_pipe`] class [section:write write] -[indexterm1 boost_asio.indexterm.write..write] +[indexterm1 boost_asio.indexterm.write..write] + The `write` function is a composed operation that writes a certain amount of data to a stream before returning. @@ -159026,12 +161604,12 @@ The number of bytes transferred. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::write(s, boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Remarks] @@ -159100,12 +161678,12 @@ The number of bytes transferred. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::write(s, boost::asio::buffer(data, size), ec); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Remarks] @@ -159195,13 +161773,13 @@ The number of bytes transferred. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::write(s, boost::asio::buffer(data, size), boost::asio::transfer_at_least(32)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -160101,7 +162679,8 @@ The number of bytes written. If an error occurs, returns the total number of byt [section:write_at write_at] -[indexterm1 boost_asio.indexterm.write_at..write_at] +[indexterm1 boost_asio.indexterm.write_at..write_at] + The `write_at` function is a composed operation that writes a certain amount of data at a specified offset before returning. @@ -160261,12 +162840,12 @@ The number of bytes transferred. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::write_at(d, 42, boost::asio::buffer(data, size)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Remarks] @@ -160337,13 +162916,13 @@ The number of bytes transferred. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::write_at(d, 42, boost::asio::buffer(data, size), ec); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Remarks] @@ -160435,13 +163014,13 @@ The number of bytes transferred. [heading Example] -To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: +To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::write_at(d, 42, boost::asio::buffer(data, size), boost::asio::transfer_at_least(32)); -See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. +See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. @@ -160804,7 +163383,8 @@ The number of bytes written. If an error occurs, returns the total number of byt [section:yield_context yield_context] -[indexterm1 boost_asio.indexterm.yield_context..yield_context] +[indexterm1 boost_asio.indexterm.yield_context..yield_context] + Context object that represents the currently executing coroutine. @@ -160849,7 +163429,7 @@ Context object that represents the currently executing coroutine. ] -The [link boost_asio.reference.basic_yield_context `basic_yield_context`] class is used to represent the currently executing stackful coroutine. A [link boost_asio.reference.basic_yield_context `basic_yield_context`] may be passed as a handler to an asynchronous operation. For example: +The [link boost_asio.reference.basic_yield_context `basic_yield_context`] class is a completion token type that is used to represent the currently executing stackful coroutine. A [link boost_asio.reference.basic_yield_context `basic_yield_context`] object may be passed as a completion token to an asynchronous operation. For example: diff --git a/doc/tutorial.qbk b/doc/tutorial.qbk index 9d58c58c8e..21c52c43b8 100644 --- a/doc/tutorial.qbk +++ b/doc/tutorial.qbk @@ -2082,7 +2082,7 @@ We have created two lots of work for the [heading The tcp_connection and tcp_server classes] -The following two classes are taken from [link boost_asio.tutorial.tutdaytime3 Daytime.3] . +The following two classes are taken from [link boost_asio.tutorial.tutdaytime3 Daytime.3]. ``''''''``class tcp_connection @@ -2163,7 +2163,7 @@ The following two classes are taken from [link boost_asio.tutorial.tutdaytime3 D [heading The udp_server class] -Similarly, this next class is taken from the [link boost_asio.tutorial.tutdaytime6 previous tutorial step] . +Similarly, this next class is taken from the [link boost_asio.tutorial.tutdaytime6 previous tutorial step]. ``''''''``class udp_server