From Jason Turner

[coroutine.handle]

C++17 → C++20 5.3 KB 183 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpvarf2aj2/{from.md → to.md} +180 -0
tmp/tmpvarf2aj2/{from.md → to.md} RENAMED
@@ -0,0 +1,180 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### Class template `coroutine_handle` <a id="coroutine.handle">[[coroutine.handle]]</a>
2
+
3
+ ``` cpp
4
+ namespace std {
5
+ template<>
6
+ struct coroutine_handle<void>
7
+ {
8
+ // [coroutine.handle.con], construct/reset
9
+ constexpr coroutine_handle() noexcept;
10
+ constexpr coroutine_handle(nullptr_t) noexcept;
11
+ coroutine_handle& operator=(nullptr_t) noexcept;
12
+
13
+ // [coroutine.handle.export.import], export/import
14
+ constexpr void* address() const noexcept;
15
+ static constexpr coroutine_handle from_address(void* addr);
16
+
17
+ // [coroutine.handle.observers], observers
18
+ constexpr explicit operator bool() const noexcept;
19
+ bool done() const;
20
+
21
+ // [coroutine.handle.resumption], resumption
22
+ void operator()() const;
23
+ void resume() const;
24
+ void destroy() const;
25
+
26
+ private:
27
+ void* ptr; // exposition only
28
+ };
29
+
30
+ template<class Promise>
31
+ struct coroutine_handle : coroutine_handle<>
32
+ {
33
+ // [coroutine.handle.con], construct/reset
34
+ using coroutine_handle<>::coroutine_handle;
35
+ static coroutine_handle from_promise(Promise&);
36
+ coroutine_handle& operator=(nullptr_t) noexcept;
37
+
38
+ // [coroutine.handle.export.import], export/import
39
+ static constexpr coroutine_handle from_address(void* addr);
40
+
41
+ // [coroutine.handle.promise], promise access
42
+ Promise& promise() const;
43
+ };
44
+ }
45
+ ```
46
+
47
+ An object of type `coroutine_handle<T>` is called a *coroutine handle*
48
+ and can be used to refer to a suspended or executing coroutine. A
49
+ default-constructed `coroutine_handle` object does not refer to any
50
+ coroutine.
51
+
52
+ If a program declares an explicit or partial specialization of
53
+ `coroutine_handle`, the behavior is undefined.
54
+
55
+ #### Construct/reset <a id="coroutine.handle.con">[[coroutine.handle.con]]</a>
56
+
57
+ ``` cpp
58
+ constexpr coroutine_handle() noexcept;
59
+ constexpr coroutine_handle(nullptr_t) noexcept;
60
+ ```
61
+
62
+ *Ensures:* `address() == nullptr`.
63
+
64
+ ``` cpp
65
+ static coroutine_handle from_promise(Promise& p);
66
+ ```
67
+
68
+ *Preconditions:* `p` is a reference to a promise object of a coroutine.
69
+
70
+ *Returns:* A coroutine handle `h` referring to the coroutine.
71
+
72
+ *Ensures:* `addressof(h.promise()) == addressof(p)`.
73
+
74
+ ``` cpp
75
+ coroutine_handle& operator=(nullptr_t) noexcept;
76
+ ```
77
+
78
+ *Ensures:* `address() == nullptr`.
79
+
80
+ *Returns:* `*this`.
81
+
82
+ #### Export/import <a id="coroutine.handle.export.import">[[coroutine.handle.export.import]]</a>
83
+
84
+ ``` cpp
85
+ constexpr void* address() const noexcept;
86
+ ```
87
+
88
+ *Returns:* `ptr`.
89
+
90
+ ``` cpp
91
+ static constexpr coroutine_handle<> coroutine_handle<>::from_address(void* addr);
92
+ static constexpr coroutine_handle<Promise> coroutine_handle<Promise>::from_address(void* addr);
93
+ ```
94
+
95
+ *Preconditions:* `addr` was obtained via a prior call to `address`.
96
+
97
+ *Ensures:* `from_address(address()) == *this`.
98
+
99
+ #### Observers <a id="coroutine.handle.observers">[[coroutine.handle.observers]]</a>
100
+
101
+ ``` cpp
102
+ constexpr explicit operator bool() const noexcept;
103
+ ```
104
+
105
+ *Returns:* `address() != nullptr`.
106
+
107
+ ``` cpp
108
+ bool done() const;
109
+ ```
110
+
111
+ *Preconditions:* `*this` refers to a suspended coroutine.
112
+
113
+ *Returns:* `true` if the coroutine is suspended at its final suspend
114
+ point, otherwise `false`.
115
+
116
+ #### Resumption <a id="coroutine.handle.resumption">[[coroutine.handle.resumption]]</a>
117
+
118
+ Resuming a coroutine via `resume`, `operator()`, or `destroy` on an
119
+ execution agent other than the one on which it was suspended has
120
+ implementation-defined behavior unless each execution agent either is an
121
+ instance of `std::thread` or `std::jthread`, or is the thread that
122
+ executes `main`.
123
+
124
+ [*Note 1*: A coroutine that is resumed on a different execution agent
125
+ should avoid relying on consistent thread identity throughout, such as
126
+ holding a mutex object across a suspend point. — *end note*]
127
+
128
+ [*Note 2*: A concurrent resumption of the coroutine may result in a
129
+ data race. — *end note*]
130
+
131
+ ``` cpp
132
+ void operator()() const;
133
+ void resume() const;
134
+ ```
135
+
136
+ *Preconditions:* `*this` refers to a suspended coroutine. The coroutine
137
+ is not suspended at its final suspend point.
138
+
139
+ *Effects:* Resumes the execution of the coroutine.
140
+
141
+ ``` cpp
142
+ void destroy() const;
143
+ ```
144
+
145
+ *Preconditions:* `*this` refers to a suspended coroutine.
146
+
147
+ *Effects:* Destroys the coroutine [[dcl.fct.def.coroutine]].
148
+
149
+ #### Promise access <a id="coroutine.handle.promise">[[coroutine.handle.promise]]</a>
150
+
151
+ ``` cpp
152
+ Promise& promise() const;
153
+ ```
154
+
155
+ *Preconditions:* `*this` refers to a coroutine.
156
+
157
+ *Returns:* A reference to the promise of the coroutine.
158
+
159
+ #### Comparison operators <a id="coroutine.handle.compare">[[coroutine.handle.compare]]</a>
160
+
161
+ ``` cpp
162
+ constexpr bool operator==(coroutine_handle<> x, coroutine_handle<> y) noexcept;
163
+ ```
164
+
165
+ *Returns:* `x.address() == y.address()`.
166
+
167
+ ``` cpp
168
+ constexpr strong_ordering operator<=>(coroutine_handle<> x, coroutine_handle<> y) noexcept;
169
+ ```
170
+
171
+ *Returns:* `compare_three_way()(x.address(), y.address())`.
172
+
173
+ #### Hash support <a id="coroutine.handle.hash">[[coroutine.handle.hash]]</a>
174
+
175
+ ``` cpp
176
+ template<class P> struct hash<coroutine_handle<P>>;
177
+ ```
178
+
179
+ The specialization is enabled [[unord.hash]].
180
+