1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
|
[#thread]
== cobalt/thread.hpp
The thread type is another way to create an environment that is similar to `main`, but doesn't use a `signal_set`.
[source,cpp]
----
cobalt::thread my_thread()
{
auto exec = co_await cobalt::this_coro::executor; // <1>
asio::steady_timer tim{exec, std::chrono::milliseconds(50)}; // <2>
co_await tim.async_wait(cobalt::use_op); // <3>
co_return 0;
}
----
<1> get the executor `thread` running on
<2> Use it with an asio object
<3> `co_await` an cobalt operation
To use a thread you can use it like a `std::thread`:
[source,cpp]
----
int main(int argc, char * argv[])
{
auto thr = my_thread();
thr.join();
return 0;
}
----
A thread is also an `awaitable` (including cancellation).
[source,cpp]
----
cobalt::main co_main(int argc, char * argv[])
{
auto thr = my_thread();
co_await thr;
co_return 0;
}
----
NOTE: Destructing a detached thread will cause a hard stop (`io_context::stop`) and join the thread.
WARNING: Nothing in this library, except for awaiting a <<thread>> and <<spawn>>, is thread-safe.
If you need to transfer data across threads, you'll need a thread-safe utility like https://www.boost.org/doc/libs/master/doc/html/boost_asio/reference/experimental__basic_concurrent_channel.html[`asio::concurrent_channel`].
You cannot share any cobalt primitives between threads,
with the sole exception of being able to <<spawn, spawn>> a <<task, task>> onto another thread's executor.
=== Executor
[#thread-executor]
It will also create an `asio::io_context` to run on, which you can get through the `this_coro::executor`.
It will be assigned to the `cobalt::this_thread::get_executor()` .
=== Memory Resource
[#thread-allocator]
It also creates a memory resource that will be used as a default for internal memory allocations.
It will be assigned to the `thread_local` to the `cobalt::this_thread::get_default_resource()`.
[#thread-outline]
=== Outline
[source,cpp]
----
include::../../include/boost/cobalt/thread.hpp[tag=outline]
----
<1> Supports <<interrupt_await>>
<2> Always forward cancel
[#thread-promise]
=== Promise
The thread promise has the following properties.
- <<promise_cancellation_base>>
- <<promise_throw_if_cancelled_base>>
- <<enable_awaitables>>
- <<enable_await_allocator>>
- <<enable_await_executor>>
- <<enable_await_deferred>>
|
