From Jason Turner

[thread.lock.shared]

C++17 → C++20 11.3 KB 138 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game
C++ Weekly: Ep 72

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp6j_qz8tx/{from.md → to.md} +55 -73
tmp/tmp6j_qz8tx/{from.md → to.md} RENAMED
@@ -12,15 +12,13 @@ namespace std {
12
  explicit shared_lock(mutex_type& m); // blocking
13
  shared_lock(mutex_type& m, defer_lock_t) noexcept;
14
  shared_lock(mutex_type& m, try_to_lock_t);
15
  shared_lock(mutex_type& m, adopt_lock_t);
16
  template<class Clock, class Duration>
17
- shared_lock(mutex_type& m,
18
- const chrono::time_point<Clock, Duration>& abs_time);
19
  template<class Rep, class Period>
20
- shared_lock(mutex_type& m,
21
- const chrono::duration<Rep, Period>& rel_time);
22
  ~shared_lock();
23
 
24
  shared_lock(const shared_lock&) = delete;
25
  shared_lock& operator=(const shared_lock&) = delete;
26
 
@@ -48,12 +46,10 @@ namespace std {
48
  private:
49
  mutex_type* pm; // exposition only
50
  bool owns; // exposition only
51
  };
52
 
53
- template<class Mutex> shared_lock(shared_lock<Mutex>) -> shared_lock<Mutex>;
54
-
55
  template<class Mutex>
56
  void swap(shared_lock<Mutex>& x, shared_lock<Mutex>& y) noexcept;
57
  }
58
  ```
59
 
@@ -62,99 +58,89 @@ lockable object within a scope. Shared ownership of the lockable object
62
  may be acquired at construction or after construction, and may be
63
  transferred, after acquisition, to another `shared_lock` object. Objects
64
  of type `shared_lock` are not copyable but are movable. The behavior of
65
  a program is undefined if the contained pointer `pm` is not null and the
66
  lockable object pointed to by `pm` does not exist for the entire
67
- remaining lifetime ([[basic.life]]) of the `shared_lock` object. The
68
- supplied `Mutex` type shall meet the shared mutex requirements (
69
- [[thread.sharedtimedmutex.requirements]]).
70
 
71
- [*Note 1*: `shared_lock<Mutex>` meets the `TimedLockable`
72
- requirements ([[thread.req.lockable.timed]]). — *end note*]
73
 
74
- ##### `shared_lock` constructors, destructor, and assignment <a id="thread.lock.shared.cons">[[thread.lock.shared.cons]]</a>
75
 
76
  ``` cpp
77
  shared_lock() noexcept;
78
  ```
79
 
80
- *Effects:* Constructs an object of type `shared_lock`.
81
-
82
- *Postconditions:* `pm == nullptr` and `owns == false`.
83
 
84
  ``` cpp
85
  explicit shared_lock(mutex_type& m);
86
  ```
87
 
88
- *Requires:* The calling thread does not own the mutex for any ownership
89
- mode.
90
 
91
- *Effects:* Constructs an object of type `shared_lock` and calls
92
- `m.lock_shared()`.
93
 
94
- *Postconditions:* `pm == addressof(m)` and `owns == true`.
95
 
96
  ``` cpp
97
  shared_lock(mutex_type& m, defer_lock_t) noexcept;
98
  ```
99
 
100
- *Effects:* Constructs an object of type `shared_lock`.
101
-
102
- *Postconditions:* `pm == addressof(m)` and `owns == false`.
103
 
104
  ``` cpp
105
  shared_lock(mutex_type& m, try_to_lock_t);
106
  ```
107
 
108
- *Requires:* The calling thread does not own the mutex for any ownership
109
- mode.
110
 
111
- *Effects:* Constructs an object of type `shared_lock` and calls
112
- `m.try_lock_shared()`.
113
 
114
- *Postconditions:* `pm == addressof(m)` and `owns == res` where `res` is
115
- the value returned by the call to `m.try_lock_shared()`.
116
 
117
  ``` cpp
118
  shared_lock(mutex_type& m, adopt_lock_t);
119
  ```
120
 
121
- *Requires:* The calling thread has shared ownership of the mutex.
122
 
123
- *Effects:* Constructs an object of type `shared_lock`.
124
-
125
- *Postconditions:* `pm == addressof(m)` and `owns == true`.
126
 
127
  ``` cpp
128
  template<class Clock, class Duration>
129
  shared_lock(mutex_type& m,
130
  const chrono::time_point<Clock, Duration>& abs_time);
131
  ```
132
 
133
- *Requires:* The calling thread does not own the mutex for any ownership
134
- mode.
135
 
136
- *Effects:* Constructs an object of type `shared_lock` and calls
137
- `m.try_lock_shared_until(abs_time)`.
138
 
139
- *Postconditions:* `pm == addressof(m)` and `owns == res` where `res` is
140
- the value returned by the call to `m.try_lock_shared_until(abs_time)`.
141
 
142
  ``` cpp
143
  template<class Rep, class Period>
144
  shared_lock(mutex_type& m,
145
  const chrono::duration<Rep, Period>& rel_time);
146
  ```
147
 
148
- *Requires:* The calling thread does not own the mutex for any ownership
149
- mode.
150
 
151
- *Effects:* Constructs an object of type `shared_lock` and calls
152
- `m.try_lock_shared_for(rel_time)`.
153
 
154
- *Postconditions:* `pm == addressof(m)` and `owns == res` where `res` is
155
- the value returned by the call to `m.try_lock_shared_for(rel_time)`.
156
 
157
  ``` cpp
158
  ~shared_lock();
159
  ```
160
 
@@ -162,36 +148,36 @@ the value returned by the call to `m.try_lock_shared_for(rel_time)`.
162
 
163
  ``` cpp
164
  shared_lock(shared_lock&& sl) noexcept;
165
  ```
166
 
167
- *Postconditions:* `pm == sl_p.pm` and `owns == sl_p.owns` (where `sl_p`
168
- is the state of `sl` just prior to this construction),
169
- `sl.pm == nullptr` and `sl.owns == false`.
170
 
171
  ``` cpp
172
  shared_lock& operator=(shared_lock&& sl) noexcept;
173
  ```
174
 
175
  *Effects:* If `owns` calls `pm->unlock_shared()`.
176
 
177
- *Postconditions:* `pm == sl_p.pm` and `owns == sl_p.owns` (where `sl_p`
178
- is the state of `sl` just prior to this assignment), `sl.pm == nullptr`
179
- and `sl.owns == false`.
180
 
181
- ##### `shared_lock` locking <a id="thread.lock.shared.locking">[[thread.lock.shared.locking]]</a>
182
 
183
  ``` cpp
184
  void lock();
185
  ```
186
 
187
  *Effects:* As if by `pm->lock_shared()`.
188
 
189
- *Postconditions:* `owns == true`.
190
 
191
  *Throws:* Any exception thrown by `pm->lock_shared()`. `system_error`
192
- when an exception is required ([[thread.req.exception]]).
193
 
194
  *Error conditions:*
195
 
196
  - `operation_not_permitted` — if `pm` is `nullptr`.
197
  - `resource_deadlock_would_occur` — if on entry `owns` is `true`.
@@ -202,39 +188,36 @@ bool try_lock();
202
 
203
  *Effects:* As if by `pm->try_lock_shared()`.
204
 
205
  *Returns:* The value returned by the call to `pm->try_lock_shared()`.
206
 
207
- *Postconditions:* `owns == res`, where `res` is the value returned by
208
- the call to `pm->try_lock_shared()`.
209
 
210
  *Throws:* Any exception thrown by `pm->try_lock_shared()`.
211
- `system_error` when an exception is
212
- required ([[thread.req.exception]]).
213
 
214
  *Error conditions:*
215
 
216
  - `operation_not_permitted` — if `pm` is `nullptr`.
217
  - `resource_deadlock_would_occur` — if on entry `owns` is `true`.
218
 
219
  ``` cpp
220
  template<class Clock, class Duration>
221
- bool
222
- try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
223
  ```
224
 
225
  *Effects:* As if by `pm->try_lock_shared_until(abs_time)`.
226
 
227
  *Returns:* The value returned by the call to
228
  `pm->try_lock_shared_until(abs_time)`.
229
 
230
- *Postconditions:* `owns == res`, where `res` is the value returned by
231
- the call to `pm->try_lock_shared_until(abs_time)`.
232
 
233
  *Throws:* Any exception thrown by `pm->try_lock_shared_until(abs_time)`.
234
- `system_error` when an exception is
235
- required ([[thread.req.exception]]).
236
 
237
  *Error conditions:*
238
 
239
  - `operation_not_permitted` — if `pm` is `nullptr`.
240
  - `resource_deadlock_would_occur` — if on entry `owns` is `true`.
@@ -247,16 +230,15 @@ template <class Rep, class Period>
247
  *Effects:* As if by `pm->try_lock_shared_for(rel_time)`.
248
 
249
  *Returns:* The value returned by the call to
250
  `pm->try_lock_shared_for(rel_time)`.
251
 
252
- *Postconditions:* `owns == res`, where `res` is the value returned by
253
- the call to `pm->try_lock_shared_for(rel_time)`.
254
 
255
  *Throws:* Any exception thrown by `pm->try_lock_shared_for(rel_time)`.
256
- `system_error` when an exception is
257
- required ([[thread.req.exception]]).
258
 
259
  *Error conditions:*
260
 
261
  - `operation_not_permitted` — if `pm` is `nullptr`.
262
  - `resource_deadlock_would_occur` — if on entry `owns` is `true`.
@@ -265,20 +247,20 @@ required ([[thread.req.exception]]).
265
  void unlock();
266
  ```
267
 
268
  *Effects:* As if by `pm->unlock_shared()`.
269
 
270
- *Postconditions:* `owns == false`.
271
 
272
  *Throws:* `system_error` when an exception is
273
- required ([[thread.req.exception]]).
274
 
275
  *Error conditions:*
276
 
277
  - `operation_not_permitted` — if on entry `owns` is `false`.
278
 
279
- ##### `shared_lock` modifiers <a id="thread.lock.shared.mod">[[thread.lock.shared.mod]]</a>
280
 
281
  ``` cpp
282
  void swap(shared_lock& sl) noexcept;
283
  ```
284
 
@@ -288,20 +270,20 @@ void swap(shared_lock& sl) noexcept;
288
  mutex_type* release() noexcept;
289
  ```
290
 
291
  *Returns:* The previous value of `pm`.
292
 
293
- *Postconditions:* `pm == nullptr` and `owns == false`.
294
 
295
  ``` cpp
296
  template<class Mutex>
297
  void swap(shared_lock<Mutex>& x, shared_lock<Mutex>& y) noexcept;
298
  ```
299
 
300
  *Effects:* As if by `x.swap(y)`.
301
 
302
- ##### `shared_lock` observers <a id="thread.lock.shared.obs">[[thread.lock.shared.obs]]</a>
303
 
304
  ``` cpp
305
  bool owns_lock() const noexcept;
306
  ```
307
 
 
12
  explicit shared_lock(mutex_type& m); // blocking
13
  shared_lock(mutex_type& m, defer_lock_t) noexcept;
14
  shared_lock(mutex_type& m, try_to_lock_t);
15
  shared_lock(mutex_type& m, adopt_lock_t);
16
  template<class Clock, class Duration>
17
+ shared_lock(mutex_type& m, const chrono::time_point<Clock, Duration>& abs_time);
 
18
  template<class Rep, class Period>
19
+ shared_lock(mutex_type& m, const chrono::duration<Rep, Period>& rel_time);
 
20
  ~shared_lock();
21
 
22
  shared_lock(const shared_lock&) = delete;
23
  shared_lock& operator=(const shared_lock&) = delete;
24
 
 
46
  private:
47
  mutex_type* pm; // exposition only
48
  bool owns; // exposition only
49
  };
50
 
 
 
51
  template<class Mutex>
52
  void swap(shared_lock<Mutex>& x, shared_lock<Mutex>& y) noexcept;
53
  }
54
  ```
55
 
 
58
  may be acquired at construction or after construction, and may be
59
  transferred, after acquisition, to another `shared_lock` object. Objects
60
  of type `shared_lock` are not copyable but are movable. The behavior of
61
  a program is undefined if the contained pointer `pm` is not null and the
62
  lockable object pointed to by `pm` does not exist for the entire
63
+ remaining lifetime [[basic.life]] of the `shared_lock` object. The
64
+ supplied `Mutex` type shall meet the shared mutex requirements
65
+ [[thread.sharedtimedmutex.requirements]].
66
 
67
+ [*Note 1*: `shared_lock<Mutex>` meets the *Cpp17TimedLockable*
68
+ requirements [[thread.req.lockable.timed]]. — *end note*]
69
 
70
+ ##### Constructors, destructor, and assignment <a id="thread.lock.shared.cons">[[thread.lock.shared.cons]]</a>
71
 
72
  ``` cpp
73
  shared_lock() noexcept;
74
  ```
75
 
76
+ *Ensures:* `pm == nullptr` and `owns == false`.
 
 
77
 
78
  ``` cpp
79
  explicit shared_lock(mutex_type& m);
80
  ```
81
 
82
+ *Preconditions:* The calling thread does not own the mutex for any
83
+ ownership mode.
84
 
85
+ *Effects:* Calls `m.lock_shared()`.
 
86
 
87
+ *Ensures:* `pm == addressof(m)` and `owns == true`.
88
 
89
  ``` cpp
90
  shared_lock(mutex_type& m, defer_lock_t) noexcept;
91
  ```
92
 
93
+ *Ensures:* `pm == addressof(m)` and `owns == false`.
 
 
94
 
95
  ``` cpp
96
  shared_lock(mutex_type& m, try_to_lock_t);
97
  ```
98
 
99
+ *Preconditions:* The calling thread does not own the mutex for any
100
+ ownership mode.
101
 
102
+ *Effects:* Calls `m.try_lock_shared()`.
 
103
 
104
+ *Ensures:* `pm == addressof(m)` and `owns == res` where `res` is the
105
+ value returned by the call to `m.try_lock_shared()`.
106
 
107
  ``` cpp
108
  shared_lock(mutex_type& m, adopt_lock_t);
109
  ```
110
 
111
+ *Preconditions:* The calling thread has shared ownership of the mutex.
112
 
113
+ *Ensures:* `pm == addressof(m)` and `owns == true`.
 
 
114
 
115
  ``` cpp
116
  template<class Clock, class Duration>
117
  shared_lock(mutex_type& m,
118
  const chrono::time_point<Clock, Duration>& abs_time);
119
  ```
120
 
121
+ *Preconditions:* The calling thread does not own the mutex for any
122
+ ownership mode.
123
 
124
+ *Effects:* Calls `m.try_lock_shared_until(abs_time)`.
 
125
 
126
+ *Ensures:* `pm == addressof(m)` and `owns == res` where `res` is the
127
+ value returned by the call to `m.try_lock_shared_until(abs_time)`.
128
 
129
  ``` cpp
130
  template<class Rep, class Period>
131
  shared_lock(mutex_type& m,
132
  const chrono::duration<Rep, Period>& rel_time);
133
  ```
134
 
135
+ *Preconditions:* The calling thread does not own the mutex for any
136
+ ownership mode.
137
 
138
+ *Effects:* Calls `m.try_lock_shared_for(rel_time)`.
 
139
 
140
+ *Ensures:* `pm == addressof(m)` and `owns == res` where `res` is the
141
+ value returned by the call to `m.try_lock_shared_for(rel_time)`.
142
 
143
  ``` cpp
144
  ~shared_lock();
145
  ```
146
 
 
148
 
149
  ``` cpp
150
  shared_lock(shared_lock&& sl) noexcept;
151
  ```
152
 
153
+ *Ensures:* `pm == sl_p.pm` and `owns == sl_p.owns` (where `sl_p` is the
154
+ state of `sl` just prior to this construction), `sl.pm == nullptr` and
155
+ `sl.owns == false`.
156
 
157
  ``` cpp
158
  shared_lock& operator=(shared_lock&& sl) noexcept;
159
  ```
160
 
161
  *Effects:* If `owns` calls `pm->unlock_shared()`.
162
 
163
+ *Ensures:* `pm == sl_p.pm` and `owns == sl_p.owns` (where `sl_p` is the
164
+ state of `sl` just prior to this assignment), `sl.pm == nullptr` and
165
+ `sl.owns == false`.
166
 
167
+ ##### Locking <a id="thread.lock.shared.locking">[[thread.lock.shared.locking]]</a>
168
 
169
  ``` cpp
170
  void lock();
171
  ```
172
 
173
  *Effects:* As if by `pm->lock_shared()`.
174
 
175
+ *Ensures:* `owns == true`.
176
 
177
  *Throws:* Any exception thrown by `pm->lock_shared()`. `system_error`
178
+ when an exception is required [[thread.req.exception]].
179
 
180
  *Error conditions:*
181
 
182
  - `operation_not_permitted` — if `pm` is `nullptr`.
183
  - `resource_deadlock_would_occur` — if on entry `owns` is `true`.
 
188
 
189
  *Effects:* As if by `pm->try_lock_shared()`.
190
 
191
  *Returns:* The value returned by the call to `pm->try_lock_shared()`.
192
 
193
+ *Ensures:* `owns == res`, where `res` is the value returned by the call
194
+ to `pm->try_lock_shared()`.
195
 
196
  *Throws:* Any exception thrown by `pm->try_lock_shared()`.
197
+ `system_error` when an exception is required [[thread.req.exception]].
 
198
 
199
  *Error conditions:*
200
 
201
  - `operation_not_permitted` — if `pm` is `nullptr`.
202
  - `resource_deadlock_would_occur` — if on entry `owns` is `true`.
203
 
204
  ``` cpp
205
  template<class Clock, class Duration>
206
+ bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
 
207
  ```
208
 
209
  *Effects:* As if by `pm->try_lock_shared_until(abs_time)`.
210
 
211
  *Returns:* The value returned by the call to
212
  `pm->try_lock_shared_until(abs_time)`.
213
 
214
+ *Ensures:* `owns == res`, where `res` is the value returned by the call
215
+ to `pm->try_lock_shared_until(abs_time)`.
216
 
217
  *Throws:* Any exception thrown by `pm->try_lock_shared_until(abs_time)`.
218
+ `system_error` when an exception is required [[thread.req.exception]].
 
219
 
220
  *Error conditions:*
221
 
222
  - `operation_not_permitted` — if `pm` is `nullptr`.
223
  - `resource_deadlock_would_occur` — if on entry `owns` is `true`.
 
230
  *Effects:* As if by `pm->try_lock_shared_for(rel_time)`.
231
 
232
  *Returns:* The value returned by the call to
233
  `pm->try_lock_shared_for(rel_time)`.
234
 
235
+ *Ensures:* `owns == res`, where `res` is the value returned by the call
236
+ to `pm->try_lock_shared_for(rel_time)`.
237
 
238
  *Throws:* Any exception thrown by `pm->try_lock_shared_for(rel_time)`.
239
+ `system_error` when an exception is required [[thread.req.exception]].
 
240
 
241
  *Error conditions:*
242
 
243
  - `operation_not_permitted` — if `pm` is `nullptr`.
244
  - `resource_deadlock_would_occur` — if on entry `owns` is `true`.
 
247
  void unlock();
248
  ```
249
 
250
  *Effects:* As if by `pm->unlock_shared()`.
251
 
252
+ *Ensures:* `owns == false`.
253
 
254
  *Throws:* `system_error` when an exception is
255
+ required [[thread.req.exception]].
256
 
257
  *Error conditions:*
258
 
259
  - `operation_not_permitted` — if on entry `owns` is `false`.
260
 
261
+ ##### Modifiers <a id="thread.lock.shared.mod">[[thread.lock.shared.mod]]</a>
262
 
263
  ``` cpp
264
  void swap(shared_lock& sl) noexcept;
265
  ```
266
 
 
270
  mutex_type* release() noexcept;
271
  ```
272
 
273
  *Returns:* The previous value of `pm`.
274
 
275
+ *Ensures:* `pm == nullptr` and `owns == false`.
276
 
277
  ``` cpp
278
  template<class Mutex>
279
  void swap(shared_lock<Mutex>& x, shared_lock<Mutex>& y) noexcept;
280
  ```
281
 
282
  *Effects:* As if by `x.swap(y)`.
283
 
284
+ ##### Observers <a id="thread.lock.shared.obs">[[thread.lock.shared.obs]]</a>
285
 
286
  ``` cpp
287
  bool owns_lock() const noexcept;
288
  ```
289