This is no longer an experimental facility. The names as_tuple and
as_tuple_t have been temporarily retained as deprecated entities under
the asio::experimental namespace, for backwards compatibility.
The as_tuple completion token adapter can be used to specify that the
completion handler arguments should be combined into a single tuple
argument.
The as_tuple adapter may be used in conjunction with use_awaitable and
structured bindings as follows:
auto [e, n] = co_await socket.async_read_some(
asio::buffer(data), as_tuple(use_awaitable));
Alternatively, it may be used as a default completion token like so:
using default_token = as_tuple_t<use_awaitable_t<>>;
using tcp_socket = default_token::as_default_on_t<tcp::socket>;
// ...
awaitable<void> do_read(tcp_socket socket)
{
// ...
auto [e, n] = co_await socket.async_read_some(asio::buffer(data));
// ...
}
The as_single completion token adapter can be used to specify that the
completion handler arguments should be combined into a single argument.
For completion signatures with a single parameter, the argument is
passed through as-is. For signatures with two or more parameters, the
arguments are combined into a tuple.
The as_single adapter may be used in conjunction with use_awaitable and
structured bindings as follows:
auto [e, n] = co_await socket.async_read_some(
boost::asio::buffer(data), as_single(use_awaitable));
Alternatively, it may be used as a default completion token like so:
using default_token = as_single_t<use_awaitable_t<>>;
using tcp_socket = default_token::as_default_on_t<tcp::socket>;
// ...
awaitable<void> do_read(tcp_socket socket)
{
// ...
auto [e, n] = co_await socket.async_read_some(boost::asio::buffer(data));
// ...
}
The BOOST_ASIO_HANDLER_LOCATION((file_name, line, function_name)) macro
may be used to inform the handler tracking mechanism of a source
location. This macro declares an object that is placed on the stack.
When an asynchronous operation is launched with location information, it
outputs lines using the <action> 'n^m', prior to the 'n*m' line that
signifies the beginning of the asynchronous operation. For example:
@asio|1589423304.861944|>7|ec=system:0,bytes_transferred=5
@asio|1589423304.861952|7^8|in 'async_write' (./../../../include/asio/impl/write.hpp:330)
@asio|1589423304.861952|7^8|called from 'do_write' (handler_tracking/async_tcp_echo_server.cpp:62)
@asio|1589423304.861952|7^8|called from 'operator()' (handler_tracking/async_tcp_echo_server.cpp:51)
@asio|1589423304.861952|7*8|socket@0x7ff61c008230.async_send
@asio|1589423304.861975|.8|non_blocking_send,ec=system:0,bytes_transferred=5
@asio|1589423304.861980|<7|
If std::source_location or std::experimental::source_location are
available, the use_awaitable_t token (when default-constructed or used
as a default completion token) will also cause handler tracking to
output a source location for each newly created asynchronous operation.
A use_awaitable_t object may also be explicitly constructed with location
information.
Every I/O executor type now has an associated default completion token
type. This is specified via the `default_completion_token_type` trait.
This trait may be used in asynchronous operation declarations as
follows:
template <
typename IoObject,
typename CompletionToken =
typename default_completion_token_type<
typename IoObject::executor_type
>::type
>
auto async_foo(
IoObject& io_object,
CompletionToken&& token =
typename default_completion_token_type<
typename IoObject::executor_type
>::type{}
);
If not specialised, this trait type is `void`, meaning no default
completion token type is available for the given I/O executor.
The `default_completion_token_type` trait is specialised for the
`use_awaitable` completion token so that it may be used as shown in the
following example:
auto socket = use_awaitable.as_default_on(tcp::socket(my_context));
// ...
co_await socket.async_connect(my_endpoint); // Defaults to use_awaitable.
In this example, type of the `socket` object is transformed from
`tcp::socket` to have an I/O executor with the default completion token
set to `use_awaitable`.
Alternatively, the socket type may be computed directly:
using tcp_socket = use_awaitable_t<>::as_default_on_t<tcp::socket>;
tcp_socket socket(my_context);
// ...
co_await socket.async_connect(my_endpoint); // Defaults to use_awaitable.
The awaitable<>, co_spawn(), this_coro, detached, and redirect_error
facilities have been moved from the asio::experimental namespace to
namespace asio. As part of this change, the this_coro::token() awaitable
has been superseded by the asio::use_awaitable completion token.
Please note that the use_awaitable and redirect_error completion tokens
work only with asynchronous operations that use the new form of
async_result with member function initiate(). Furthermore, when using
use_awaitable, please be aware that the asynchronous operation is not
initiated until co_await is applied to the awaitable<>.
All I/O objects now have an additional Executor template parameter. This
template parameter defaults to the asio::executor type (the polymorphic
executor wrapper) but can be used to specify a user-defined executor
type.
I/O objects' constructors and functions that previously took an
asio::io_context& now accept either an Executor or a reference to a
concrete ExecutionContext (such as asio::io_context or
asio::thread_pool).
One potential point of breakage in existing user code is when reusing an
I/O object's io_context for constructing another I/O object, as in:
asio::steady_timer my_timer(my_socket.get_executor().context());
To fix this, either construct the second I/O object using the first I/O
object's executor:
asio::steady_timer my_timer(my_socket.get_executor());
or otherwise explicitly pass the io_context:
asio::steady_timer my_timer(my_io_context);
