From Jason Turner

[coroutine.handle]

C++20 → C++23 4.9 KB 65 lines
Current Draft | LaTeX Source
Archived: C++20 | C++23
Markdown: C++20 | C++23
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpexnvkx3f/{from.md → to.md} +49 -10
tmp/tmpexnvkx3f/{from.md → to.md} RENAMED
@@ -1,7 +1,9 @@
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
  {
@@ -26,30 +28,49 @@ namespace std {
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>
@@ -65,36 +86,54 @@ constexpr coroutine_handle(nullptr_t) noexcept;
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
 
@@ -115,19 +154,19 @@ 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;
 
1
  ### Class template `coroutine_handle` <a id="coroutine.handle">[[coroutine.handle]]</a>
2
 
3
+ #### General <a id="coroutine.handle.general">[[coroutine.handle.general]]</a>
4
+
5
  ``` cpp
6
  namespace std {
7
  template<>
8
  struct coroutine_handle<void>
9
  {
 
28
  private:
29
  void* ptr; // exposition only
30
  };
31
 
32
  template<class Promise>
33
+ struct coroutine_handle
34
  {
35
  // [coroutine.handle.con], construct/reset
36
+ constexpr coroutine_handle() noexcept;
37
+ constexpr coroutine_handle(nullptr_t) noexcept;
38
  static coroutine_handle from_promise(Promise&);
39
  coroutine_handle& operator=(nullptr_t) noexcept;
40
 
41
  // [coroutine.handle.export.import], export/import
42
+ constexpr void* address() const noexcept;
43
  static constexpr coroutine_handle from_address(void* addr);
44
 
45
+ // [coroutine.handle.conv], conversion
46
+ constexpr operator coroutine_handle<>() const noexcept;
47
+
48
+ // [coroutine.handle.observers], observers
49
+ constexpr explicit operator bool() const noexcept;
50
+ bool done() const;
51
+
52
+ // [coroutine.handle.resumption], resumption
53
+ void operator()() const;
54
+ void resume() const;
55
+ void destroy() const;
56
+
57
  // [coroutine.handle.promise], promise access
58
  Promise& promise() const;
59
+
60
+ private:
61
+ void* ptr; // exposition only
62
  };
63
  }
64
  ```
65
 
66
  An object of type `coroutine_handle<T>` is called a *coroutine handle*
67
  and can be used to refer to a suspended or executing coroutine. A
68
+ `coroutine_handle` object whose member `address()` returns a null
69
+ pointer value does not refer to any coroutine. Two `coroutine_handle`
70
+ objects refer to the same coroutine if and only if their member
71
+ `address()` returns the same non-null value.
72
 
73
  If a program declares an explicit or partial specialization of
74
  `coroutine_handle`, the behavior is undefined.
75
 
76
  #### Construct/reset <a id="coroutine.handle.con">[[coroutine.handle.con]]</a>
 
86
  static coroutine_handle from_promise(Promise& p);
87
  ```
88
 
89
  *Preconditions:* `p` is a reference to a promise object of a coroutine.
90
 
 
 
91
  *Ensures:* `addressof(h.promise()) == addressof(p)`.
92
 
93
+ *Returns:* A coroutine handle `h` referring to the coroutine.
94
+
95
  ``` cpp
96
  coroutine_handle& operator=(nullptr_t) noexcept;
97
  ```
98
 
99
  *Ensures:* `address() == nullptr`.
100
 
101
  *Returns:* `*this`.
102
 
103
+ #### Conversion <a id="coroutine.handle.conv">[[coroutine.handle.conv]]</a>
104
+
105
+ ``` cpp
106
+ constexpr operator coroutine_handle<>() const noexcept;
107
+ ```
108
+
109
+ *Effects:* Equivalent to:
110
+ `return coroutine_handle<>::from_address(address());`
111
+
112
  #### Export/import <a id="coroutine.handle.export.import">[[coroutine.handle.export.import]]</a>
113
 
114
  ``` cpp
115
  constexpr void* address() const noexcept;
116
  ```
117
 
118
  *Returns:* `ptr`.
119
 
120
  ``` cpp
121
  static constexpr coroutine_handle<> coroutine_handle<>::from_address(void* addr);
122
+ ```
123
+
124
+ *Preconditions:* `addr` was obtained via a prior call to `address` on an
125
+ object whose type is a specialization of `coroutine_handle`.
126
+
127
+ *Ensures:* `from_address(address()) == *this`.
128
+
129
+ ``` cpp
130
  static constexpr coroutine_handle<Promise> coroutine_handle<Promise>::from_address(void* addr);
131
  ```
132
 
133
+ *Preconditions:* `addr` was obtained via a prior call to `address` on an
134
+ object of type cv `coroutine_handle<Promise>`.
135
 
136
  *Ensures:* `from_address(address()) == *this`.
137
 
138
  #### Observers <a id="coroutine.handle.observers">[[coroutine.handle.observers]]</a>
139
 
 
154
 
155
  #### Resumption <a id="coroutine.handle.resumption">[[coroutine.handle.resumption]]</a>
156
 
157
  Resuming a coroutine via `resume`, `operator()`, or `destroy` on an
158
  execution agent other than the one on which it was suspended has
159
+ *implementation-defined* behavior unless each execution agent either is
160
+ an instance of `std::thread` or `std::jthread`, or is the thread that
161
  executes `main`.
162
 
163
  [*Note 1*: A coroutine that is resumed on a different execution agent
164
  should avoid relying on consistent thread identity throughout, such as
165
  holding a mutex object across a suspend point. — *end note*]
166
 
167
+ [*Note 2*: A concurrent resumption of the coroutine can result in a
168
  data race. — *end note*]
169
 
170
  ``` cpp
171
  void operator()() const;
172
  void resume() const;