mirror of
https://github.com/boostorg/cobalt.git
synced 2026-01-19 04:02:16 +00:00
87 lines
2.3 KiB
Plaintext
87 lines
2.3 KiB
Plaintext
[#promise]
|
|
== cobalt/promise.hpp
|
|
|
|
A promise is an eager coroutine that can `co_await` and `co_return` values. That is, it cannot use `co_yield`.
|
|
|
|
[source,cpp]
|
|
----
|
|
cobalt::promise<void> delay(std::chrono::milliseconds ms)
|
|
{
|
|
asio::steady_timer tim{co_await cobalt::this_coro::executor, ms};
|
|
co_await tim.async_wait(cobalt::use_op);
|
|
}
|
|
|
|
cobalt::main co_main(int argc, char *argv[])
|
|
{
|
|
co_await delay(std::chrono::milliseconds(50));
|
|
co_return 0;
|
|
}
|
|
----
|
|
|
|
Promises are by default attached.
|
|
This means, that a cancellation is sent when the `promise` handles goes out of scope.
|
|
|
|
A promise can be detached by calling `detach` or by using the prefix `+` operator.
|
|
This is a runtime alternative to using <<detached, detached>>.
|
|
A detached promise will not send a cancellation on destruction.
|
|
|
|
[source,cpp]
|
|
----
|
|
cobalt::promise<void> my_task();
|
|
|
|
cobalt::main co_main(int argc, char *argv[])
|
|
{
|
|
+my_task(); // <1>
|
|
co_await delay(std::chrono::milliseconds(50));
|
|
co_return 0;
|
|
}
|
|
----
|
|
<1> By using `+` the task gets detached. Without it, the compiler would generate a `nodiscard` warning.
|
|
|
|
=== Executor
|
|
[#promise-executor]
|
|
|
|
The executor is taken from the `thread_local` <<this_thread, get_executor>> function, unless a `asio::executor_arg` is used
|
|
in any position followed by the executor argument.
|
|
|
|
[source, cpp]
|
|
----
|
|
cobalt::promise<int> my_gen(asio::executor_arg_t, asio::io_context::executor_type exec_to_use);
|
|
----
|
|
|
|
=== Memory Resource
|
|
[#promise-allocator]
|
|
|
|
The memory resource is taken from the `thread_local` <<this_thread, get_default_resource>> function,
|
|
unless a `std::allocator_arg` is used in any position followed by a `polymorphic_allocator` argument.
|
|
|
|
[source, cpp]
|
|
----
|
|
cobalt::promise<int> my_gen(std::allocator_arg_t, pmr::polymorphic_allocator<void> alloc);
|
|
----
|
|
|
|
[#promise-outline]
|
|
=== Outline
|
|
|
|
|
|
[source,cpp]
|
|
----
|
|
include::../../include/boost/cobalt/promise.hpp[tag=outline]
|
|
----
|
|
<1> Supports <<interrupt_await>>
|
|
<2> This allows to create promise running in parallel with a simple `+my_task()` expression.
|
|
<3> This allows code like `while (p) co_await p;`
|
|
|
|
[#promise-promise]
|
|
=== Promise
|
|
|
|
The coroutine promise (`promise::promise_type`) has the following properties.
|
|
|
|
- <<promise_memory_resource_base>>
|
|
- <<promise_cancellation_base>>
|
|
- <<promise_throw_if_cancelled_base>>
|
|
- <<enable_awaitables>>
|
|
- <<enable_await_allocator>>
|
|
- <<enable_await_executor>>
|
|
- <<enable_await_deferred>>
|