Added support for files. This introduces new classes for stream-oriented and random-access files. For example, to write to a newly created stream-oriented file:

asio::stream_file file(
    my_io_context, "/path/to/file",
    asio::stream_file::write_only
      | asio::stream_file::create
      | asio::stream_file::truncate);

file.async_write_some(my_buffer,
    [](error_code e, size_t n)
    {
      // ...
    });

or to read from a random-access file:

asio::random_access_file file(
    my_io_context, "/path/to/file",
    asio::random_access_file::read_only);

file.async_read_some_at(1234, my_buffer,
    [](error_code e, size_t n)
    {
      // ...
    });

This feature currently supports I/O completion ports on Windows, and io_uring on Linux (define ASIO_HAS_IO_URING to enable).

Added support for portable pipes. This change add supports for pipes on POSIX and Windows (when I/O completion ports are available). For example, to create and use a connected pair of pipe objects:

asio::readable_pipe read_end;
asio::writable_pipe write_end;
asio::connect_pipe(read_end, write_end);

write_end.async_write_some(my_write_buffer,
    [](error_code e, size_t n)
    {
      // ...
    });

read_end.async_read_some(my_read_buffer,
    [](error_code e, size_t n)
    {
      // ...
    });

Added support for registered buffers. The mutable_registered_buffer and const_registered_buffer classes are buffer sequence types that represent registered buffers. These buffers are obtained by first performing a buffer registration:

auto my_registration =
  asio::register_buffers(
      my_execution_context,
      my_buffer_sequence);

The registration object must be maintained for as long as the buffer registration is required. The supplied buffer sequence represents the memory location or locations that will be registered, and the caller must ensure they remain valid for as long as they are registered. The registration is automatically removed when the registration object is destroyed. There can be at most one active registration per execution context.

The registration object is a container of registered buffers. Buffers may be obtained from it by iterating over the container, or via direct index access:

asio::mutable_registered_buffer my_buffer
  = my_registration[i];

The registered buffers may then be passed directly to operations:

asio::async_read(my_socket, my_buffer,
    [](error_code ec, size_t n)
    {
      // ...
    });

Buffer registration supports the io_uring backend when used with read and write operations on descriptors, files, pipes, and sockets. For portability, the facility may be used on other platforms, but the registered buffers will behave as normal buffers.

Added experimental support for channels. This adds templates experimental::basic_channel and experimental::basic_concurrent_channel, with aliases experimental::channel and experimental::concurrent_channel. Channels may be used to send completions as messages. For example:

// Create a channel with no buffer space.
channel<void(error_code, size_t)> ch(ctx);

// The call to try_send fails as there is no buffer
// space and no waiting receive operations.
bool ok = ch.try_send(asio::error::eof, 123);
assert(!ok);

// The async_send operation is outstanding until
// a receive operation consumes the message.
ch.async_send(asio::error::eof, 123,
    [](error_code ec)
    {
      // ...
    });

// The async_receive consumes the message. Both the
// async_send and async_receive operations complete
// immediately.
ch.async_receive(
    [](error_code ec, size_t n)
    {
      // ...
    });

Added the associator trait. The associator trait is used to generically forward associators, such as associated_executor and associated_allocator, through intermediate completion handlers. For example:

template <typename Handler>
struct intermediate_handler
{
  Handler handler_;

  template <typename... Args>
  void operator()(Args&... args)
  {
    // ...
  }
};

namespace asio {
  template <
      template <typename, typename> class Associator,
      typename Handler,
      typename DefaultCandidate>
  struct associator<
      Associator,
      intermediate_handler<Handler>,
      DefaultCandidate>
  {
    using type =
      typename Associator<Handler, DefaultCandidate>::type;

    static type get(
        const intermediate_handler<Handler>& h,
        const DefaultCandidate& c = DefaultCandidate()) noexcept
    {
      return Associator<Handler, DefaultCandidate>::get(
          h.handler_, c);
    }
  };
} // namespace asio

Added support for asynchronous operations with multiple completion signatures. Completion signatures may also specify that they are noexcept, and whether they are lvalue-invocable (and thus do not "consume" the completion handler) or rvalue-invocable (and thus do "consume" the handler, indicating an end to the asynchronous operation). For example:

auto my_async_operation(...,
    asio::completion_token_for<
      void(intermediate_result_type) & noexcept,
      void(final_result_type) &&
    > auto&& token)
{
  // ...
}

Added operator&& and operator|| for awaitable<>. The logical operators || and && have been overloaded for awaitable<>, to allow coroutines to be trivially awaited in parallel.

When awaited using &&, the co_await expression waits until both operations have completed successfully. As a "short-circuit" evaluation, if one operation fails with an exception, the other is immediately cancelled. For example:

std::tuple<std::size_t, std::size_t> results =
  co_await (
    async_read(socket, input_buffer, use_awaitable)
      && async_write(socket, output_buffer, use_awaitable)
  );

When awaited using ||, the co_await expression waits until either operation succeeds. As a "short-circuit" evaluation, if one operation succeeds without throwing an exception, the other is immediately cancelled. For example:

std::variant<std::size_t, std::monostate> results =
  co_await (
    async_read(socket, input_buffer, use_awaitable)
      || timer.async_wait(use_awaitable)
  );

The operators may be enabled by adding the #include:

#include <asio/experimental/awaitable_operators.hpp>

and then bringing the contents of the experimental::awaitable_operators namespace into scope:

using namespace asio::experimental::awaitable_operators;

Added the experimental::as_tuple completion token adapter. 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));
  // ...
}

Added the experimental::append completion token adapter. The append completion token adapter can be used to pass additional completion handler arguments at the end of the completion signature. For example:

timer.async_wait(
    asio::experimental::append(
      [](std::error_code ec, int i)
      {
        // ...
      },
    42)
  );

std::future<int> f = timer.async_wait(
    asio::experimental::append(
      asio::use_future,
      42
    )
  );

Added the experimental::prepend completion token adapter. The prepend completion token adapter can be used to pass additional arguments before the existing completion handler arguments. For example:

timer.async_wait(
    asio::experimental::prepend(
      [](int i, std::error_code ec)
      {
        // ...
      },
    42)
  );

std::future<std::tuple<int, std::error_code>> f = timer.async_wait(
    asio::experimental::prepend(
      asio::use_future,
      42
    )
  );

Added the experimental::deferred completion token. The deferred completion token takes a call to an asynchronous operation's initiating function and turns it into a function object that accepts a completion token. For example:

auto deferred_op =
  timer.async_wait(
    asio::experimental::deferred);
...
std::move(deferred_op)(
    [](std::error_code ec){ ... });

or:

auto deferred_op =
  timer.async_wait(
    asio::experimental::deferred);
...
std::future<void> =
  std::move(deferred_op)(
    asio::use_future);

The deferred token also supports chaining, to create simple compositions:

auto deferred_op =
  timer.async_wait(
    asio::experimental::deferred(
      [&](std::error_code ec)
      {
        timer.expires_after(
            std::chrono::seconds(1));

        return timer.async_wait(
            asio::experimental::deferred);
      });
...
std::future<void> = std::move(deferred_op)(asio::use_future);

Added the experimental::parallel_group class and experimental::make_parallel_group function. This utility may be used to launch work that is performed in parallel, and wait for one or all of the operations to complete. A parallel_group implements automatic cancellation of incomplete operations. For example:

experimental::make_parallel_group(
    [&](auto token)
    {
      return stream.async_read_some(asio::buffer(data), token);
    },
    [&](auto token)
    {
      return timer.async_wait(token);
    }
  ).async_wait(
    experimental::wait_for_one(),
    [](
        std::array<std::size_t, 2> completion_order,
        std::error_code ec1, std::size_t n1,
        std::error_code ec2
    )
    {
      // ...
    }
  );

The conditions for completion of the group may be specified using one of the four provided function objects wait_for_all, wait_for_one, wait_for_one_success, and wait_for_one_error, or with a custom function. The parallel_group class can also be combined with deferred as follows:

experimental::make_parallel_group(
    stream.async_read_some(asio::buffer(data), experimental::deferred),
    timer.async_wait(experimental::deferred)
  ).async_wait(
    // ...
  );

Note: for maximum flexibility, parallel_group does not propagate the executor automatically to the operations within the group.

Added experimental::promise. The promise type allows eager execution and synchronisation of async operations. For example:

auto promise = async_read(
    stream, asio::buffer(my_buffer),
    asio::experimental::use_promise);

... do other stuff while the read is going on ...

promise.async_wait( // completion the operation
    [](error_code ec, std::size_t bytes_read)
    {
      ...
    });

Promises can be safely disregarded if the result is no longer required. Different operations can be combined to either wait for all to complete or for one to complete (and cancel the rest). For example, to wait for one to complete:

auto timeout_promise =
  timer.async_wait(
    asio::experimental::use_promise);

auto read_promise = async_read(
    stream, asio::buffer(my_buffer),
    asio::experimental::use_promise);

auto promise =
  asio::experimental::promise<>::race(
    timeout_promise, read_promise);

promise.async_wait(
    [](std::variant<error_code, std::tuple<error_code, std::size_t>> v)
    {
      if (v.index() == 0) {} //timed out
      else if (v.index() == 1) // completed in time
    });

or to wait for all to complete:

auto write_promise = async_write(
    stream, asio::buffer(my_write_buffer),
    asio::experimental::use_promise);

auto read_promise = async_read(
    stream, asio::buffer(my_buffer),
    asio::experimental::use_promise);

auto promise =
  asio::experimental::promise<>::all(
    write_promise, read_promise);

promise.async_wait(
    [](std::tuple<error_code, std::size_t> write_result,
      std::tuple<error_code, std::size_t> read_result)
    {
    });

Thanks go to Klemens Morgenstern for contributing this feature.

Added the experimental::coro class template. The coro type is a C++20 coroutine primitive for resumable functions, with the ability to combine both asynchronous waiting (co_await) and yielding (co_yield) into a single, stateful control flow. For example:

#include <asio.hpp>
#include <asio/experimental/coro.hpp>

using asio::ip::tcp;

asio::experimental::coro<std::string> reader(tcp::socket& sock)
{
  std::string buf;
  while (sock.is_open())
  {
    std::size_t n = co_await asio::async_read_until(
        sock, asio::dynamic_buffer(buf), '\n',
        asio::experimental::use_coro);
    co_yield buf.substr(0, n);
    buf.erase(0, n);
  }
}

asio::awaitable<void> consumer(tcp::socket sock)
{
  auto r = reader(sock);
  auto msg1 = co_await r.async_resume(asio::use_awaitable);
  std::cout << "Message 1: " << msg1.value_or("\n");
  auto msg2 = co_await r.async_resume(asio::use_awaitable);
  std::cout << "Message 2: " << msg2.value_or("\n");
}

asio::awaitable<void> listen(tcp::acceptor& acceptor)
{
  for (;;)
  {
    co_spawn(
        acceptor.get_executor(),
        consumer(co_await acceptor.async_accept(asio::use_awaitable)),
        asio::detached);
  }
}

int main()
{
  asio::io_context ctx;
  tcp::acceptor acceptor(ctx, {tcp::v4(), 54321});
  co_spawn(ctx, listen(acceptor), asio::detached);
  ctx.run();
}

Thanks go to Klemens Morgenstern for contributing this feature.

Added the experimental::as_single completion token adapter. 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(
    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(asio::buffer(data));
  // ...
}

Added converting move construction and assignment to basic_waitable_timer. This enables move construction and assignment between different timer types, provided the executor types are convertible. For example:

basic_waitable_timer<
    clock_type,
    traits_type,
    io_context::executor_type
  > timer1(my_io_context);

basic_waitable_timer<
    clock_type,
    traits_type,
    any_io_executor // polymorphic wrapper
  > timer2(std::move(timer1));

Added overloads of co_spawn that launch an awaitable. This change allows us to write:

co_spawn(executor,
    echo(std::move(socket)),
    detached);

instead of:

co_spawn(executor,
    [socket = std::move(socket)]() mutable
    {
      return echo(std::move(socket));
    },
    detached);

Added source location support to handler tracking. The new 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. Then, 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.

Added the handlerlive.pl tool, which processes handler tracking output to produce a list of "live" handlers. Live handlers are those that are associated with pending asynchronous operations, as well as handlers that are currently executing. For example:

cat output.txt | perl handlerlive.pl

or:

perl handerlive.pl < output.txt

or:

perl handlerlive.pl output.txt

Added the handlertree.pl tool, which filters handler tracking output to include only those events in the tree that produced the nominated handlers. For example, to filter the output to include only the events associated with handlers 123, 456, and their predecessors:

  cat output.txt | perl handlertree.pl 123 456

or:

  perl handlertree.pl 123 456 < output.txt

This script may be combined with handerlive.pl and handlerviz.pl to produce a graph of the "live" asynchronous operation chains. For example:

  cat output.txt | \
    perl handlertree.pl perl handlerlive.pl output.txt | \
    perl handlerviz.pl | \
    dot -Tsvg > output.svg

Added the nested template type rebind_executor to all I/O object types, as a way to generically rebind them to use alternative I/O executors. For example:

using my_socket_type = tcp::socket::rebind_executor<my_executor_type>::other;

Added the default_completion_token trait, so that every I/O executor type now has an associated default completion token type. This trait may be used in asynchronous operation declarations as follows:

template <
    typename IoObject,
    typename CompletionToken =
      typename default_completion_token<
        typename IoObject::executor_type
      >::type
  >
auto async_xyz(
    IoObject& io_object,
    CompletionToken&& token =
      typename default_completion_token<
        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.

Specialised the default_completion_token trait 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, the 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.

Ensured that the executor type is propagated to newly accepted sockets. When synchronously or asynchronously accepting a new connection, but without specifying an executor or execution context, the accept operation will now correctly propagate the executor type from the acceptor to the socket. For example, if your acceptor type is:

basic_socket_acceptor<ip::tcp, my_executor_type>

then your accepted socket type will be:

basic_stream_socket<ip::tcp, my_executor_type>