From Jason Turner

[thread.lock.shared]

C++20 → C++23 6.7 KB 71 lines
Current Draft | LaTeX Source
Archived: C++20 | C++23
Markdown: C++20 | C++23
Explore in Adventure Game
C++ Weekly: Ep 72

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpb3d54ke1/{from.md → to.md} +31 -28
tmp/tmpb3d54ke1/{from.md → to.md} RENAMED
@@ -1,7 +1,9 @@
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:
@@ -45,13 +47,10 @@ namespace std {
45
 
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
 
56
  An object of type `shared_lock` controls the shared ownership of a
57
  lockable object within a scope. Shared ownership of the lockable object
@@ -59,15 +58,19 @@ 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;
@@ -77,13 +80,10 @@ shared_lock() noexcept;
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
@@ -94,34 +94,31 @@ shared_lock(mutex_type& m, defer_lock_t) noexcept;
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)`.
@@ -130,12 +127,12 @@ value returned by the call to `m.try_lock_shared_until(abs_time)`.
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)`.
@@ -186,15 +183,15 @@ when an exception is required [[thread.req.exception]].
186
  bool try_lock();
187
  ```
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
 
@@ -204,18 +201,21 @@ to `pm->try_lock_shared()`.
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
 
@@ -225,18 +225,21 @@ to `pm->try_lock_shared_until(abs_time)`.
225
  ``` cpp
226
  template<class Rep, class Period>
227
  bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
228
  ```
229
 
 
 
 
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
 
@@ -268,14 +271,14 @@ void swap(shared_lock& sl) noexcept;
268
 
269
  ``` cpp
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
 
 
1
  #### Class template `shared_lock` <a id="thread.lock.shared">[[thread.lock.shared]]</a>
2
 
3
+ ##### General <a id="thread.lock.shared.general">[[thread.lock.shared.general]]</a>
4
+
5
  ``` cpp
6
  namespace std {
7
  template<class Mutex>
8
  class shared_lock {
9
  public:
 
47
 
48
  private:
49
  mutex_type* pm; // exposition only
50
  bool owns; // exposition only
51
  };
 
 
 
52
  }
53
  ```
54
 
55
  An object of type `shared_lock` controls the shared ownership of a
56
  lockable object within a scope. Shared ownership of the lockable object
 
58
  transferred, after acquisition, to another `shared_lock` object. Objects
59
  of type `shared_lock` are not copyable but are movable. The behavior of
60
  a program is undefined if the contained pointer `pm` is not null and the
61
  lockable object pointed to by `pm` does not exist for the entire
62
  remaining lifetime [[basic.life]] of the `shared_lock` object. The
63
+ supplied `Mutex` type shall meet the *Cpp17SharedLockable* requirements
64
+ [[thread.req.lockable.shared]].
65
 
66
+ [*Note 1*: `shared_lock<Mutex>` meets the *Cpp17Lockable* requirements
67
+ [[thread.req.lockable.req]]. If `Mutex` meets the
68
+ *Cpp17SharedTimedLockable* requirements
69
+ [[thread.req.lockable.shared.timed]], `shared_lock<Mutex>` also meets
70
+ the *Cpp17TimedLockable* requirements
71
+ [[thread.req.lockable.timed]]. — *end note*]
72
 
73
  ##### Constructors, destructor, and assignment <a id="thread.lock.shared.cons">[[thread.lock.shared.cons]]</a>
74
 
75
  ``` cpp
76
  shared_lock() noexcept;
 
80
 
81
  ``` cpp
82
  explicit shared_lock(mutex_type& m);
83
  ```
84
 
 
 
 
85
  *Effects:* Calls `m.lock_shared()`.
86
 
87
  *Ensures:* `pm == addressof(m)` and `owns == true`.
88
 
89
  ``` cpp
 
94
 
95
  ``` cpp
96
  shared_lock(mutex_type& m, try_to_lock_t);
97
  ```
98
 
 
 
 
99
  *Effects:* Calls `m.try_lock_shared()`.
100
 
101
  *Ensures:* `pm == addressof(m)` and `owns == res` where `res` is the
102
  value returned by the call to `m.try_lock_shared()`.
103
 
104
  ``` cpp
105
  shared_lock(mutex_type& m, adopt_lock_t);
106
  ```
107
 
108
+ *Preconditions:* The calling thread holds a shared lock on `m`.
109
 
110
  *Ensures:* `pm == addressof(m)` and `owns == true`.
111
 
112
  ``` cpp
113
  template<class Clock, class Duration>
114
  shared_lock(mutex_type& m,
115
  const chrono::time_point<Clock, Duration>& abs_time);
116
  ```
117
 
118
+ *Preconditions:* `Mutex` meets the *Cpp17SharedTimedLockable*
119
+ requirements [[thread.req.lockable.shared.timed]].
120
 
121
  *Effects:* Calls `m.try_lock_shared_until(abs_time)`.
122
 
123
  *Ensures:* `pm == addressof(m)` and `owns == res` where `res` is the
124
  value returned by the call to `m.try_lock_shared_until(abs_time)`.
 
127
  template<class Rep, class Period>
128
  shared_lock(mutex_type& m,
129
  const chrono::duration<Rep, Period>& rel_time);
130
  ```
131
 
132
+ *Preconditions:* `Mutex` meets the *Cpp17SharedTimedLockable*
133
+ requirements [[thread.req.lockable.shared.timed]].
134
 
135
  *Effects:* Calls `m.try_lock_shared_for(rel_time)`.
136
 
137
  *Ensures:* `pm == addressof(m)` and `owns == res` where `res` is the
138
  value returned by the call to `m.try_lock_shared_for(rel_time)`.
 
183
  bool try_lock();
184
  ```
185
 
186
  *Effects:* As if by `pm->try_lock_shared()`.
187
 
 
 
188
  *Ensures:* `owns == res`, where `res` is the value returned by the call
189
  to `pm->try_lock_shared()`.
190
 
191
+ *Returns:* The value returned by the call to `pm->try_lock_shared()`.
192
+
193
  *Throws:* Any exception thrown by `pm->try_lock_shared()`.
194
  `system_error` when an exception is required [[thread.req.exception]].
195
 
196
  *Error conditions:*
197
 
 
201
  ``` cpp
202
  template<class Clock, class Duration>
203
  bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
204
  ```
205
 
206
+ *Preconditions:* `Mutex` meets the *Cpp17SharedTimedLockable*
207
+ requirements [[thread.req.lockable.shared.timed]].
208
+
209
  *Effects:* As if by `pm->try_lock_shared_until(abs_time)`.
210
 
 
 
 
211
  *Ensures:* `owns == res`, where `res` is the value returned by the call
212
  to `pm->try_lock_shared_until(abs_time)`.
213
 
214
+ *Returns:* The value returned by the call to
215
+ `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
 
 
225
  ``` cpp
226
  template<class Rep, class Period>
227
  bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
228
  ```
229
 
230
+ *Preconditions:* `Mutex` meets the *Cpp17SharedTimedLockable*
231
+ requirements [[thread.req.lockable.shared.timed]].
232
+
233
  *Effects:* As if by `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
+ *Returns:* The value returned by the call to
239
+ `pm->try_lock_shared_for(rel_time)`.
240
+
241
  *Throws:* Any exception thrown by `pm->try_lock_shared_for(rel_time)`.
242
  `system_error` when an exception is required [[thread.req.exception]].
243
 
244
  *Error conditions:*
245
 
 
271
 
272
  ``` cpp
273
  mutex_type* release() noexcept;
274
  ```
275
 
276
+ *Ensures:* `pm == nullptr` and `owns == false`.
277
+
278
  *Returns:* The previous value of `pm`.
279
 
 
 
280
  ``` cpp
281
  template<class Mutex>
282
  void swap(shared_lock<Mutex>& x, shared_lock<Mutex>& y) noexcept;
283
  ```
284