From Jason Turner

[stopsource]

C++23 → Trunk 6.3 KB 147 lines
Current Draft | LaTeX Source
Archived: C++23
Markdown: C++23 | Trunk
Explore in Adventure Game

Diff to HTML by rtfpessoa

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