This is no longer an experimental facility. The names deferred and
deferred_t have been temporarily retained as deprecated entities under
the asio::experimental namespace, for backwards compatibility.
This is no longer an experimental facility. The names prepend and
prepend_t have been temporarily retained as deprecated entities under
the asio::experimental namespace, for backwards compatibility.
This is no longer an experimental facility. The names append and
append_t have been temporarily retained as deprecated entities under
the asio::experimental namespace, for backwards compatibility.
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.
This adds 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 blocks 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 overload so member functions can provide an explicit executor.
* Added co_spawn for coro tasks.
* Added reference and overview documentation.
* Adopted awaitable cancellation model.
* Refactored implementation.
The mutable_registered_buffer and const_registered_buffer classes are
buffer sequence types that represented 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.
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)
{
// ...
});
This change adds support 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 BOOST_ASIO_HAS_IO_URING to enable).
By default, awaitable<>-based coroutines now throw an exception if they
have been previously cancelled, and then try to perform a co_await
against another awaitable<>.
To disable this behaviour for the current awaitable<>-based "thread",
perform:
co_await boost::asio::this_coro::throw_if_error(false);
It is then the responsibility of the coroutine implementation to ensure
that it checks the cancellation state of the coroutine manually, by
doing something like:
auto cs = boost::asio::this_coro::cancellation_state;
// ...
if (cs.cancelled() != cancellation_type::none)
{
// ... handle cancellation ...
}
The logical operators || and && have been overloaded for awaitable<>, to
allow coroutines to be trivially awaited in parallel.
When awaited using &&, the 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 await expression waits until either operation
succceeds. 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 boost::asio::experimental::awaitable_operators;
The experimental::promise type allows eager execution and
synchronisation of async operations.
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)
{
});
