From Jason Turner

[thread.lock.shared]

C++14 → C++17 10.7 KB 117 lines
Current Draft | LaTeX Source
Archived: C++14 | C++17
Markdown: C++14 | C++17
Explore in Adventure Game
C++ Weekly: Ep 72

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpamflj5dz/{from.md → to.md} +59 -47
tmp/tmpamflj5dz/{from.md → to.md} RENAMED
@@ -1,16 +1,15 @@
1
  #### Class template `shared_lock` <a id="thread.lock.shared">[[thread.lock.shared]]</a>
2
 
3
  ``` cpp
4
  namespace std {
5
-
6
  template <class Mutex>
7
  class shared_lock {
8
  public:
9
- typedef Mutex mutex_type;
10
 
11
- // Shared locking
12
  shared_lock() noexcept;
13
  explicit shared_lock(mutex_type& m); // blocking
14
  shared_lock(mutex_type& m, defer_lock_t) noexcept;
15
  shared_lock(mutex_type& m, try_to_lock_t);
16
  shared_lock(mutex_type& m, adopt_lock_t);
@@ -20,42 +19,44 @@ public:
20
  template <class Rep, class Period>
21
  shared_lock(mutex_type& m,
22
  const chrono::duration<Rep, Period>& rel_time);
23
  ~shared_lock();
24
 
25
- shared_lock(shared_lock const&) = delete;
26
- shared_lock& operator=(shared_lock const&) = delete;
27
 
28
  shared_lock(shared_lock&& u) noexcept;
29
  shared_lock& operator=(shared_lock&& u) noexcept;
30
 
 
31
  void lock(); // blocking
32
  bool try_lock();
33
  template <class Rep, class Period>
34
  bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
35
  template <class Clock, class Duration>
36
  bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
37
  void unlock();
38
 
39
- // Setters
40
  void swap(shared_lock& u) noexcept;
41
  mutex_type* release() noexcept;
42
 
43
- // Getters
44
  bool owns_lock() const noexcept;
45
  explicit operator bool () const noexcept;
46
  mutex_type* mutex() const noexcept;
47
 
48
  private:
49
  mutex_type* pm; // exposition only
50
  bool owns; // exposition only
51
  };
52
 
 
 
53
  template <class Mutex>
54
  void swap(shared_lock<Mutex>& x, shared_lock<Mutex>& y) noexcept;
55
-
56
- } // std
57
  ```
58
 
59
  An object of type `shared_lock` controls the shared ownership of a
60
  lockable object within a scope. Shared ownership of the lockable object
61
  may be acquired at construction or after construction, and may be
@@ -65,12 +66,12 @@ a program is undefined if the contained pointer `pm` is not null and the
65
  lockable object pointed to by `pm` does not exist for the entire
66
  remaining lifetime ([[basic.life]]) of the `shared_lock` object. The
67
  supplied `Mutex` type shall meet the shared mutex requirements (
68
  [[thread.sharedtimedmutex.requirements]]).
69
 
70
- `shared_lock<Mutex>` meets the `TimedLockable` requirements (
71
- [[thread.req.lockable.timed]]).
72
 
73
  ##### `shared_lock` constructors, destructor, and assignment <a id="thread.lock.shared.cons">[[thread.lock.shared.cons]]</a>
74
 
75
  ``` cpp
76
  shared_lock() noexcept;
@@ -88,19 +89,19 @@ explicit shared_lock(mutex_type& m);
88
  mode.
89
 
90
  *Effects:* Constructs an object of type `shared_lock` and calls
91
  `m.lock_shared()`.
92
 
93
- *Postconditions:* `pm == &m` and `owns == true`.
94
 
95
  ``` cpp
96
  shared_lock(mutex_type& m, defer_lock_t) noexcept;
97
  ```
98
 
99
  *Effects:* Constructs an object of type `shared_lock`.
100
 
101
- *Postconditions:* `pm == &m` and `owns == false`.
102
 
103
  ``` cpp
104
  shared_lock(mutex_type& m, try_to_lock_t);
105
  ```
106
 
@@ -108,22 +109,22 @@ shared_lock(mutex_type& m, try_to_lock_t);
108
  mode.
109
 
110
  *Effects:* Constructs an object of type `shared_lock` and calls
111
  `m.try_lock_shared()`.
112
 
113
- *Postconditions:* `pm == &m` and `owns == res` where `res` is the value
114
- returned by the call to `m.try_lock_shared()`.
115
 
116
  ``` cpp
117
  shared_lock(mutex_type& m, adopt_lock_t);
118
  ```
119
 
120
  *Requires:* The calling thread has shared ownership of the mutex.
121
 
122
  *Effects:* Constructs an object of type `shared_lock`.
123
 
124
- *Postconditions:* `pm == &m` and `owns == true`.
125
 
126
  ``` cpp
127
  template <class Clock, class Duration>
128
  shared_lock(mutex_type& m,
129
  const chrono::time_point<Clock, Duration>& abs_time);
@@ -133,12 +134,12 @@ template <class Clock, class Duration>
133
  mode.
134
 
135
  *Effects:* Constructs an object of type `shared_lock` and calls
136
  `m.try_lock_shared_until(abs_time)`.
137
 
138
- *Postconditions:* `pm == &m` and `owns == res` where `res` is the value
139
- returned by the call to `m.try_lock_shared_until(abs_time)`.
140
 
141
  ``` cpp
142
  template <class Rep, class Period>
143
  shared_lock(mutex_type& m,
144
  const chrono::duration<Rep, Period>& rel_time);
@@ -148,12 +149,12 @@ template <class Rep, class Period>
148
  mode.
149
 
150
  *Effects:* Constructs an object of type `shared_lock` and calls
151
  `m.try_lock_shared_for(rel_time)`.
152
 
153
- *Postconditions:* `pm == &m` and `owns == res` where `res` is the value
154
- returned by the call to `m.try_lock_shared_for(rel_time)`.
155
 
156
  ``` cpp
157
  ~shared_lock();
158
  ```
159
 
@@ -161,106 +162,117 @@ returned by the call to `m.try_lock_shared_for(rel_time)`.
161
 
162
  ``` cpp
163
  shared_lock(shared_lock&& sl) noexcept;
164
  ```
165
 
166
- *Postconditions:* `pm == &sl_p.pm` and `owns == sl_p.owns` (where `sl_p`
167
  is the state of `sl` just prior to this construction),
168
  `sl.pm == nullptr` and `sl.owns == false`.
169
 
170
  ``` cpp
171
  shared_lock& operator=(shared_lock&& sl) noexcept;
172
  ```
173
 
174
  *Effects:* If `owns` calls `pm->unlock_shared()`.
175
 
176
- *Postconditions:* `pm == &sl_p.pm` and `owns == sl_p.owns` (where `sl_p`
177
  is the state of `sl` just prior to this assignment), `sl.pm == nullptr`
178
  and `sl.owns == false`.
179
 
180
  ##### `shared_lock` locking <a id="thread.lock.shared.locking">[[thread.lock.shared.locking]]</a>
181
 
182
  ``` cpp
183
  void lock();
184
  ```
185
 
186
- *Effects:* `pm->lock_shared()`.
187
 
188
  *Postconditions:* `owns == true`.
189
 
190
- *Throws:* Any exception thrown by `pm->lock_shared()`. `system_error` if
191
- an exception is required ([[thread.req.exception]]). `system_error`
192
- with an error condition of `operation_not_permitted` if `pm` is
193
- `nullptr`. `system_error` with an error condition of
194
- `resource_deadlock_would_occur` if on entry `owns` is `true`.
 
 
195
 
196
  ``` cpp
197
  bool try_lock();
198
  ```
199
 
200
- *Effects:* `pm->try_lock_shared()`.
201
 
202
  *Returns:* The value returned by the call to `pm->try_lock_shared()`.
203
 
204
  *Postconditions:* `owns == res`, where `res` is the value returned by
205
  the call to `pm->try_lock_shared()`.
206
 
207
  *Throws:* Any exception thrown by `pm->try_lock_shared()`.
208
- `system_error` if an exception is required ([[thread.req.exception]]).
209
- `system_error` with an error condition of `operation_not_permitted` if
210
- `pm` is `nullptr`. `system_error` with an error condition of
211
- `resource_deadlock_would_occur` if on entry `owns` is `true`.
 
 
 
212
 
213
  ``` cpp
214
  template <class Clock, class Duration>
215
  bool
216
  try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
217
  ```
218
 
219
- *Effects:* `pm->try_lock_shared_until(abs_time)`.
220
 
221
  *Returns:* The value returned by the call to
222
  `pm->try_lock_shared_until(abs_time)`.
223
 
224
  *Postconditions:* `owns == res`, where `res` is the value returned by
225
  the call to `pm->try_lock_shared_until(abs_time)`.
226
 
227
  *Throws:* Any exception thrown by `pm->try_lock_shared_until(abs_time)`.
228
- `system_error` if an exception is required ([[thread.req.exception]]).
229
- `system_error` with an error condition of `operation_not_permitted` if
230
- `pm` is `nullptr`. `system_error` with an error condition of
231
- `resource_deadlock_would_occur` if on entry `owns` is `true`.
 
 
 
232
 
233
  ``` cpp
234
  template <class Rep, class Period>
235
  bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
236
  ```
237
 
238
- *Effects:* `pm->try_lock_shared_for(rel_time)`.
239
 
240
  *Returns:* The value returned by the call to
241
  `pm->try_lock_shared_for(rel_time)`.
242
 
243
  *Postconditions:* `owns == res`, where `res` is the value returned by
244
  the call to `pm->try_lock_shared_for(rel_time)`.
245
 
246
  *Throws:* Any exception thrown by `pm->try_lock_shared_for(rel_time)`.
247
- `system_error` if an exception is required  ([[thread.req.exception]]).
248
- `system_error` with an error condition of `operation_not_permitted` if
249
- `pm` is `nullptr`. `system_error` with an error condition of
250
- `resource_deadlock_would_occur` if on entry `owns` is `true`.
 
 
 
251
 
252
  ``` cpp
253
  void unlock();
254
  ```
255
 
256
- *Effects:* `pm->unlock_shared()`.
257
 
258
  *Postconditions:* `owns == false`.
259
 
260
- *Throws:* `system_error` when an exception is required
261
-  ([[thread.req.exception]]).
262
 
263
  *Error conditions:*
264
 
265
  - `operation_not_permitted` — if on entry `owns` is `false`.
266
 
@@ -283,11 +295,11 @@ mutex_type* release() noexcept;
283
  ``` cpp
284
  template <class Mutex>
285
  void swap(shared_lock<Mutex>& x, shared_lock<Mutex>& y) noexcept;
286
  ```
287
 
288
- *Effects:* `x.swap(y)`.
289
 
290
  ##### `shared_lock` observers <a id="thread.lock.shared.obs">[[thread.lock.shared.obs]]</a>
291
 
292
  ``` cpp
293
  bool owns_lock() const noexcept;
 
1
  #### Class template `shared_lock` <a id="thread.lock.shared">[[thread.lock.shared]]</a>
2
 
3
  ``` cpp
4
  namespace std {
 
5
  template <class Mutex>
6
  class shared_lock {
7
  public:
8
+ using mutex_type = Mutex;
9
 
10
+ // [thread.lock.shared.cons], construct/copy/destroy
11
  shared_lock() noexcept;
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);
 
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
 
27
  shared_lock(shared_lock&& u) noexcept;
28
  shared_lock& operator=(shared_lock&& u) noexcept;
29
 
30
+ // [thread.lock.shared.locking], locking
31
  void lock(); // blocking
32
  bool try_lock();
33
  template <class Rep, class Period>
34
  bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
35
  template <class Clock, class Duration>
36
  bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
37
  void unlock();
38
 
39
+ // [thread.lock.shared.mod], modifiers
40
  void swap(shared_lock& u) noexcept;
41
  mutex_type* release() noexcept;
42
 
43
+ // [thread.lock.shared.obs], observers
44
  bool owns_lock() const noexcept;
45
  explicit operator bool () const noexcept;
46
  mutex_type* mutex() const noexcept;
47
 
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
 
60
  An object of type `shared_lock` controls the shared ownership of a
61
  lockable object within a scope. Shared ownership of the lockable object
62
  may be acquired at construction or after construction, and may be
 
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;
 
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
 
 
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);
 
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);
 
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
 
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`.
198
 
199
  ``` cpp
200
  bool try_lock();
201
  ```
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`.
241
 
242
  ``` cpp
243
  template <class Rep, class Period>
244
  bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
245
  ```
246
 
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`.
263
 
264
  ``` cpp
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
 
 
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;