From Jason Turner

[stopsource]

C++17 → C++20 5.0 KB 173 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/tmp79df5xxa/{from.md → to.md} +170 -0
tmp/tmp79df5xxa/{from.md → to.md} RENAMED
@@ -0,0 +1,170 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### Class `stop_source` <a id="stopsource">[[stopsource]]</a>
2
+
3
+ The class `stop_source` implements the semantics of making a stop
4
+ request. A stop request made on a `stop_source` object is visible to all
5
+ associated `stop_source` and `stop_token` ([[stoptoken]]) objects. Once
6
+ a stop request has been made it cannot be withdrawn (a subsequent stop
7
+ request has no effect).
8
+
9
+ ``` cpp
10
+ namespace std {
11
+ // no-shared-stop-state indicator
12
+ struct nostopstate_t {
13
+ explicit nostopstate_t() = default;
14
+ };
15
+ inline constexpr nostopstate_t nostopstate{};
16
+
17
+ class stop_source {
18
+ public:
19
+ // [stopsource.cons], constructors, copy, and assignment
20
+ stop_source();
21
+ explicit stop_source(nostopstate_t) noexcept;
22
+
23
+ stop_source(const stop_source&) noexcept;
24
+ stop_source(stop_source&&) noexcept;
25
+ stop_source& operator=(const stop_source&) noexcept;
26
+ stop_source& operator=(stop_source&&) noexcept;
27
+ ~stop_source();
28
+ void swap(stop_source&) noexcept;
29
+
30
+ // [stopsource.mem], stop handling
31
+ [[nodiscard]] stop_token get_token() const noexcept;
32
+ [[nodiscard]] bool stop_possible() const noexcept;
33
+ [[nodiscard]] bool stop_requested() const noexcept;
34
+ bool request_stop() noexcept;
35
+
36
+ [[nodiscard]] friend bool
37
+ operator==(const stop_source& lhs, const stop_source& rhs) noexcept;
38
+ friend void swap(stop_source& lhs, stop_source& rhs) noexcept;
39
+ };
40
+ }
41
+ ```
42
+
43
+ #### Constructors, copy, and assignment <a id="stopsource.cons">[[stopsource.cons]]</a>
44
+
45
+ ``` cpp
46
+ stop_source();
47
+ ```
48
+
49
+ *Effects:* Initialises `*this` to have ownership of a new stop state.
50
+
51
+ *Ensures:* `stop_possible()` is `true` and `stop_requested()` is
52
+ `false`.
53
+
54
+ *Throws:* `bad_alloc` if memory could not be allocated for the stop
55
+ state.
56
+
57
+ ``` cpp
58
+ explicit stop_source(nostopstate_t) noexcept;
59
+ ```
60
+
61
+ *Ensures:* `stop_possible()` is `false` and `stop_requested()` is
62
+ `false`.
63
+
64
+ [*Note 1*: No resources are allocated for the state. — *end note*]
65
+
66
+ ``` cpp
67
+ stop_source(const stop_source& rhs) noexcept;
68
+ ```
69
+
70
+ *Ensures:* `*this == rhs` is `true`.
71
+
72
+ [*Note 2*: `*this` and `rhs` share the ownership of the same stop
73
+ state, if any. — *end note*]
74
+
75
+ ``` cpp
76
+ stop_source(stop_source&& rhs) noexcept;
77
+ ```
78
+
79
+ *Ensures:* `*this` contains the value of `rhs` prior to the start of
80
+ construction and `rhs.stop_possible()` is `false`.
81
+
82
+ ``` cpp
83
+ ~stop_source();
84
+ ```
85
+
86
+ *Effects:* Releases ownership of the stop state, if any.
87
+
88
+ ``` cpp
89
+ stop_source& operator=(const stop_source& rhs) noexcept;
90
+ ```
91
+
92
+ *Effects:* Equivalent to: `stop_source(rhs).swap(*this)`.
93
+
94
+ *Returns:* `*this`.
95
+
96
+ ``` cpp
97
+ stop_source& operator=(stop_source&& rhs) noexcept;
98
+ ```
99
+
100
+ *Effects:* Equivalent to: `stop_source(std::move(rhs)).swap(*this)`.
101
+
102
+ *Returns:* `*this`.
103
+
104
+ ``` cpp
105
+ void swap(stop_source& rhs) noexcept;
106
+ ```
107
+
108
+ *Effects:* Exchanges the values of `*this` and `rhs`.
109
+
110
+ #### Members <a id="stopsource.mem">[[stopsource.mem]]</a>
111
+
112
+ ``` cpp
113
+ [[nodiscard]] stop_token get_token() const noexcept;
114
+ ```
115
+
116
+ *Returns:* `stop_token()` if `stop_possible()` is `false`; otherwise a
117
+ new associated `stop_token` object.
118
+
119
+ ``` cpp
120
+ [[nodiscard]] bool stop_possible() const noexcept;
121
+ ```
122
+
123
+ *Returns:* `true` if `*this` has ownership of a stop state; otherwise,
124
+ `false`.
125
+
126
+ ``` cpp
127
+ [[nodiscard]] bool stop_requested() const noexcept;
128
+ ```
129
+
130
+ *Returns:* `true` if `*this` has ownership of a stop state that has
131
+ received a stop request; otherwise, `false`.
132
+
133
+ ``` cpp
134
+ bool request_stop() noexcept;
135
+ ```
136
+
137
+ *Effects:* If `*this` does not have ownership of a stop state, returns
138
+ `false`. Otherwise, atomically determines whether the owned stop state
139
+ has received a stop request, and if not, makes a stop request. The
140
+ determination and making of the stop request are an atomic
141
+ read-modify-write operation [[intro.races]]. If the request was made,
142
+ the callbacks registered by associated `stop_callback` objects are
143
+ synchronously called. If an invocation of a callback exits via an
144
+ exception then `terminate` is called [[except.terminate]].
145
+
146
+ [*Note 1*: A stop request includes notifying all condition variables of
147
+ type `condition_variable_any` temporarily registered during an
148
+ interruptible wait [[thread.condvarany.intwait]]. — *end note*]
149
+
150
+ *Ensures:* `stop_possible()` is `false` or `stop_requested()` is `true`.
151
+
152
+ *Returns:* `true` if this call made a stop request; otherwise `false`.
153
+
154
+ #### Non-member functions <a id="stopsource.nonmembers">[[stopsource.nonmembers]]</a>
155
+
156
+ ``` cpp
157
+ [[nodiscard]] friend bool
158
+ operator==(const stop_source& lhs, const stop_source& rhs) noexcept;
159
+ ```
160
+
161
+ *Returns:* `true` if `lhs` and `rhs` have ownership of the same stop
162
+ state or if both `lhs` and `rhs` do not have ownership of a stop state;
163
+ otherwise `false`.
164
+
165
+ ``` cpp
166
+ friend void swap(stop_source& x, stop_source& y) noexcept;
167
+ ```
168
+
169
+ *Effects:* Equivalent to: `x.swap(y)`.
170
+