From Jason Turner

[thread.condition.condvar]

C++14 → C++17 10.0 KB 128 lines
Current Draft | LaTeX Source
Archived: C++14 | C++17
Markdown: C++14 | C++17
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp82pzdw_g/{from.md → to.md} +65 -50
tmp/tmp82pzdw_g/{from.md → to.md} RENAMED
@@ -30,11 +30,11 @@ namespace std {
30
  template <class Rep, class Period, class Predicate>
31
  bool wait_for(unique_lock<mutex>& lock,
32
  const chrono::duration<Rep, Period>& rel_time,
33
  Predicate pred);
34
 
35
- typedef implementation-defined native_handle_type; // See~[thread.req.native]
36
  native_handle_type native_handle(); // See~[thread.req.native]
37
  };
38
  }
39
  ```
40
 
@@ -57,19 +57,21 @@ required ([[thread.req.exception]]).
57
 
58
  ``` cpp
59
  ~condition_variable();
60
  ```
61
 
62
- There shall be no thread blocked on `*this`. That is, all threads shall
63
- have been notified; they may subsequently block on the lock specified in
64
- the wait. This relaxes the usual rules, which would have required all
65
- wait calls to happen before destruction. Only the notification to
66
- unblock the wait must happen before destruction. The user must take care
67
- to ensure that no threads wait on `*this` once the destructor has been
68
- started, especially when the waiting threads are calling the wait
69
- functions in a loop or using the overloads of `wait`, `wait_for`, or
70
- `wait_until` that take a predicate.
 
 
71
 
72
  *Effects:* Destroys the object.
73
 
74
  ``` cpp
75
  void notify_one() noexcept;
@@ -86,12 +88,12 @@ void notify_all() noexcept;
86
 
87
  ``` cpp
88
  void wait(unique_lock<mutex>& lock);
89
  ```
90
 
91
- `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
92
- thread, and either
93
 
94
  - no other thread is waiting on this `condition_variable` object or
95
  - `lock.mutex()` returns the same value for each of the `lock` arguments
96
  supplied by all concurrently waiting (via `wait`, `wait_for`, or
97
  `wait_until`) threads.
@@ -103,15 +105,17 @@ thread, and either
103
  then returns.
104
  - The function will unblock when signaled by a call to `notify_one()` or
105
  a call to `notify_all()`, or spuriously.
106
 
107
  *Remarks:* If the function fails to meet the postcondition,
108
- `std::terminate()` shall be called ([[except.terminate]]). This can
109
- happen if the re-locking of the mutex throws an exception.
110
 
111
- `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
112
- thread.
 
 
 
113
 
114
  *Throws:* Nothing.
115
 
116
  ``` cpp
117
  template <class Predicate>
@@ -132,27 +136,28 @@ the calling thread, and either
132
  while (!pred())
133
  wait(lock);
134
  ```
135
 
136
  *Remarks:* If the function fails to meet the postcondition,
137
- `std::terminate()` shall be called ([[except.terminate]]). This can
138
- happen if the re-locking of the mutex throws an exception.
139
 
140
- `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
141
- thread.
142
 
143
- *Throws:* Timeout-related exceptions ([[thread.req.timing]]) or any
144
- exception thrown by `pred`.
 
 
145
 
146
  ``` cpp
147
  template <class Clock, class Duration>
148
  cv_status wait_until(unique_lock<mutex>& lock,
149
  const chrono::time_point<Clock, Duration>& abs_time);
150
  ```
151
 
152
- `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
153
- thread, and either
154
 
155
  - no other thread is waiting on this `condition_variable` object or
156
  - `lock.mutex()` returns the same value for each of the `lock` arguments
157
  supplied by all concurrently waiting (via `wait`, `wait_for`, or
158
  `wait_until`) threads.
@@ -168,15 +173,17 @@ thread, and either
168
  spuriously.
169
  - If the function exits via an exception, `lock.lock()` shall be called
170
  prior to exiting the function.
171
 
172
  *Remarks:* If the function fails to meet the postcondition,
173
- `std::terminate()` shall be called ([[except.terminate]]). This can
174
- happen if the re-locking of the mutex throws an exception.
175
 
176
- `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
177
- thread.
 
 
 
178
 
179
  *Returns:* `cv_status::timeout` if the absolute
180
  timeout ([[thread.req.timing]]) specified by `abs_time` expired,
181
  otherwise `cv_status::no_timeout`.
182
 
@@ -186,12 +193,12 @@ otherwise `cv_status::no_timeout`.
186
  template <class Rep, class Period>
187
  cv_status wait_for(unique_lock<mutex>& lock,
188
  const chrono::duration<Rep, Period>& rel_time);
189
  ```
190
 
191
- `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
192
- thread, and either
193
 
194
  - no other thread is waiting on this `condition_variable` object or
195
  - `lock.mutex()` returns the same value for each of the `lock` arguments
196
  supplied by all concurrently waiting (via `wait`, `wait_for`, or
197
  `wait_until`) threads.
@@ -205,15 +212,17 @@ return wait_until(lock, chrono::steady_clock::now() + rel_time);
205
  *Returns:* `cv_status::timeout` if the relative
206
  timeout ([[thread.req.timing]]) specified by `rel_time` expired,
207
  otherwise `cv_status::no_timeout`.
208
 
209
  *Remarks:* If the function fails to meet the postcondition,
210
- `std::terminate()` shall be called ([[except.terminate]]). This can
211
- happen if the re-locking of the mutex throws an exception.
212
 
213
- `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
214
- thread.
 
 
 
215
 
216
  *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
217
 
218
  ``` cpp
219
  template <class Clock, class Duration, class Predicate>
@@ -238,18 +247,21 @@ while (!pred())
238
  return pred();
239
  return true;
240
  ```
241
 
242
  *Remarks:* If the function fails to meet the postcondition,
243
- `std::terminate()` shall be called ([[except.terminate]]). This can
244
- happen if the re-locking of the mutex throws an exception.
245
 
246
- `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
247
- thread.
248
 
249
- The returned value indicates whether the predicate evaluated to `true`
250
- regardless of whether the timeout was triggered.
 
 
 
 
251
 
252
  *Throws:* Timeout-related exceptions ([[thread.req.timing]]) or any
253
  exception thrown by `pred`.
254
 
255
  ``` cpp
@@ -257,12 +269,12 @@ template <class Rep, class Period, class Predicate>
257
  bool wait_for(unique_lock<mutex>& lock,
258
  const chrono::duration<Rep, Period>& rel_time,
259
  Predicate pred);
260
  ```
261
 
262
- `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
263
- thread, and either
264
 
265
  - no other thread is waiting on this `condition_variable` object or
266
  - `lock.mutex()` returns the same value for each of the `lock` arguments
267
  supplied by all concurrently waiting (via `wait`, `wait_for`, or
268
  `wait_until`) threads.
@@ -271,21 +283,24 @@ thread, and either
271
 
272
  ``` cpp
273
  return wait_until(lock, chrono::steady_clock::now() + rel_time, std::move(pred));
274
  ```
275
 
276
- There is no blocking if `pred()` is initially `true`, even if the
277
- timeout has already expired.
278
 
279
  *Remarks:* If the function fails to meet the postcondition,
280
- `std::terminate()` shall be called ([[except.terminate]]). This can
281
- happen if the re-locking of the mutex throws an exception.
282
 
283
- `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
284
- thread.
285
 
286
- The returned value indicates whether the predicate evaluates to `true`
287
- regardless of whether the timeout was triggered.
 
 
 
 
288
 
289
  *Throws:* Timeout-related exceptions ([[thread.req.timing]]) or any
290
  exception thrown by `pred`.
291
 
 
30
  template <class Rep, class Period, class Predicate>
31
  bool wait_for(unique_lock<mutex>& lock,
32
  const chrono::duration<Rep, Period>& rel_time,
33
  Predicate pred);
34
 
35
+ using native_handle_type = implementation-defined; // See~[thread.req.native]
36
  native_handle_type native_handle(); // See~[thread.req.native]
37
  };
38
  }
39
  ```
40
 
 
57
 
58
  ``` cpp
59
  ~condition_variable();
60
  ```
61
 
62
+ *Requires:* There shall be no thread blocked on `*this`.
63
+
64
+ [*Note 1*: That is, all threads shall have been notified; they may
65
+ subsequently block on the lock specified in the wait. This relaxes the
66
+ usual rules, which would have required all wait calls to happen before
67
+ destruction. Only the notification to unblock the wait must happen
68
+ before destruction. The user must take care to ensure that no threads
69
+ wait on `*this` once the destructor has been started, especially when
70
+ the waiting threads are calling the wait functions in a loop or using
71
+ the overloads of `wait`, `wait_for`, or `wait_until` that take a
72
+ predicate. — *end note*]
73
 
74
  *Effects:* Destroys the object.
75
 
76
  ``` cpp
77
  void notify_one() noexcept;
 
88
 
89
  ``` cpp
90
  void wait(unique_lock<mutex>& lock);
91
  ```
92
 
93
+ *Requires:* `lock.owns_lock()` is `true` and `lock.mutex()` is locked by
94
+ the calling thread, and either
95
 
96
  - no other thread is waiting on this `condition_variable` object or
97
  - `lock.mutex()` returns the same value for each of the `lock` arguments
98
  supplied by all concurrently waiting (via `wait`, `wait_for`, or
99
  `wait_until`) threads.
 
105
  then returns.
106
  - The function will unblock when signaled by a call to `notify_one()` or
107
  a call to `notify_all()`, or spuriously.
108
 
109
  *Remarks:* If the function fails to meet the postcondition,
110
+ `terminate()` shall be called ([[except.terminate]]).
 
111
 
112
+ [*Note 2*: This can happen if the re-locking of the mutex throws an
113
+ exception. — *end note*]
114
+
115
+ *Postconditions:* `lock.owns_lock()` is `true` and `lock.mutex()` is
116
+ locked by the calling thread.
117
 
118
  *Throws:* Nothing.
119
 
120
  ``` cpp
121
  template <class Predicate>
 
136
  while (!pred())
137
  wait(lock);
138
  ```
139
 
140
  *Remarks:* If the function fails to meet the postcondition,
141
+ `terminate()` shall be called ([[except.terminate]]).
 
142
 
143
+ [*Note 3*: This can happen if the re-locking of the mutex throws an
144
+ exception. — *end note*]
145
 
146
+ *Postconditions:* `lock.owns_lock()` is `true` and `lock.mutex()` is
147
+ locked by the calling thread.
148
+
149
+ *Throws:* Any exception thrown by `pred`.
150
 
151
  ``` cpp
152
  template <class Clock, class Duration>
153
  cv_status wait_until(unique_lock<mutex>& lock,
154
  const chrono::time_point<Clock, Duration>& abs_time);
155
  ```
156
 
157
+ *Requires:* `lock.owns_lock()` is `true` and `lock.mutex()` is locked by
158
+ the calling thread, and either
159
 
160
  - no other thread is waiting on this `condition_variable` object or
161
  - `lock.mutex()` returns the same value for each of the `lock` arguments
162
  supplied by all concurrently waiting (via `wait`, `wait_for`, or
163
  `wait_until`) threads.
 
173
  spuriously.
174
  - If the function exits via an exception, `lock.lock()` shall be called
175
  prior to exiting the function.
176
 
177
  *Remarks:* If the function fails to meet the postcondition,
178
+ `terminate()` shall be called ([[except.terminate]]).
 
179
 
180
+ [*Note 4*: This can happen if the re-locking of the mutex throws an
181
+ exception. — *end note*]
182
+
183
+ *Postconditions:* `lock.owns_lock()` is `true` and `lock.mutex()` is
184
+ locked by the calling thread.
185
 
186
  *Returns:* `cv_status::timeout` if the absolute
187
  timeout ([[thread.req.timing]]) specified by `abs_time` expired,
188
  otherwise `cv_status::no_timeout`.
189
 
 
193
  template <class Rep, class Period>
194
  cv_status wait_for(unique_lock<mutex>& lock,
195
  const chrono::duration<Rep, Period>& rel_time);
196
  ```
197
 
198
+ *Requires:* `lock.owns_lock()` is `true` and `lock.mutex()` is locked by
199
+ the calling thread, and either
200
 
201
  - no other thread is waiting on this `condition_variable` object or
202
  - `lock.mutex()` returns the same value for each of the `lock` arguments
203
  supplied by all concurrently waiting (via `wait`, `wait_for`, or
204
  `wait_until`) threads.
 
212
  *Returns:* `cv_status::timeout` if the relative
213
  timeout ([[thread.req.timing]]) specified by `rel_time` expired,
214
  otherwise `cv_status::no_timeout`.
215
 
216
  *Remarks:* If the function fails to meet the postcondition,
217
+ `terminate()` shall be called ([[except.terminate]]).
 
218
 
219
+ [*Note 5*: This can happen if the re-locking of the mutex throws an
220
+ exception. — *end note*]
221
+
222
+ *Postconditions:* `lock.owns_lock()` is `true` and `lock.mutex()` is
223
+ locked by the calling thread.
224
 
225
  *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
226
 
227
  ``` cpp
228
  template <class Clock, class Duration, class Predicate>
 
247
  return pred();
248
  return true;
249
  ```
250
 
251
  *Remarks:* If the function fails to meet the postcondition,
252
+ `terminate()` shall be called ([[except.terminate]]).
 
253
 
254
+ [*Note 6*: This can happen if the re-locking of the mutex throws an
255
+ exception. — *end note*]
256
 
257
+ *Postconditions:* `lock.owns_lock()` is `true` and `lock.mutex()` is
258
+ locked by the calling thread.
259
+
260
+ [*Note 7*: The returned value indicates whether the predicate evaluated
261
+ to `true` regardless of whether the timeout was
262
+ triggered. — *end note*]
263
 
264
  *Throws:* Timeout-related exceptions ([[thread.req.timing]]) or any
265
  exception thrown by `pred`.
266
 
267
  ``` cpp
 
269
  bool wait_for(unique_lock<mutex>& lock,
270
  const chrono::duration<Rep, Period>& rel_time,
271
  Predicate pred);
272
  ```
273
 
274
+ *Requires:* `lock.owns_lock()` is `true` and `lock.mutex()` is locked by
275
+ the calling thread, and either
276
 
277
  - no other thread is waiting on this `condition_variable` object or
278
  - `lock.mutex()` returns the same value for each of the `lock` arguments
279
  supplied by all concurrently waiting (via `wait`, `wait_for`, or
280
  `wait_until`) threads.
 
283
 
284
  ``` cpp
285
  return wait_until(lock, chrono::steady_clock::now() + rel_time, std::move(pred));
286
  ```
287
 
288
+ [*Note 8*: There is no blocking if `pred()` is initially `true`, even
289
+ if the timeout has already expired. — *end note*]
290
 
291
  *Remarks:* If the function fails to meet the postcondition,
292
+ `terminate()` shall be called ([[except.terminate]]).
 
293
 
294
+ [*Note 9*: This can happen if the re-locking of the mutex throws an
295
+ exception. — *end note*]
296
 
297
+ *Postconditions:* `lock.owns_lock()` is `true` and `lock.mutex()` is
298
+ locked by the calling thread.
299
+
300
+ [*Note 10*: The returned value indicates whether the predicate
301
+ evaluates to `true` regardless of whether the timeout was
302
+ triggered. — *end note*]
303
 
304
  *Throws:* Timeout-related exceptions ([[thread.req.timing]]) or any
305
  exception thrown by `pred`.
306