From Jason Turner

[thread.sharedtimedmutex.requirements]

C++11 → C++14 7.9 KB 197 lines
Current Draft | LaTeX Source
Archived: C++11 | C++14
Markdown: C++11 | C++14
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpkofkyplm/{from.md → to.md} +194 -0
tmp/tmpkofkyplm/{from.md → to.md} RENAMED
@@ -0,0 +1,194 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #### Shared timed mutex types <a id="thread.sharedtimedmutex.requirements">[[thread.sharedtimedmutex.requirements]]</a>
2
+
3
+ The standard library type `std::shared_timed_mutex` is a *shared timed
4
+ mutex type*. Shared timed mutex types shall meet the requirements of
5
+ timed mutex types ([[thread.timedmutex.requirements]]), and
6
+ additionally shall meet the requirements set out below. In this
7
+ description, `m` denotes an object of a mutex type, `rel_type` denotes
8
+ an object of an instantiation of `duration` ([[time.duration]]), and
9
+ `abs_time` denotes an object of an instantiation of `time_point` (
10
+ [[time.point]]).
11
+
12
+ In addition to the exclusive lock ownership mode specified in 
13
+ [[thread.mutex.requirements.mutex]], shared mutex types provide a
14
+ *shared lock* ownership mode. Multiple execution agents can
15
+ simultaneously hold a shared lock ownership of a shared mutex type. But
16
+ no execution agent shall hold a shared lock while another execution
17
+ agent holds an exclusive lock on the same shared mutex type, and
18
+ vice-versa. The maximum number of execution agents which can share a
19
+ shared lock on a single shared mutex type is unspecified, but shall be
20
+ at least 10000. If more than the maximum number of execution agents
21
+ attempt to obtain a shared lock, the excess execution agents shall block
22
+ until the number of shared locks are reduced below the maximum amount by
23
+ other execution agents releasing their shared lock.
24
+
25
+ The expression `m.lock_shared()` shall be well-formed and have the
26
+ following semantics:
27
+
28
+ *Requires:* The calling thread has no ownership of the mutex.
29
+
30
+ *Effects:* Blocks the calling thread until shared ownership of the mutex
31
+ can be obtained for the calling thread. If an exception is thrown then a
32
+ shared lock shall not have been acquired for the current thread.
33
+
34
+ The calling thread has a shared lock on the mutex.
35
+
36
+ *Return type:* `void`.
37
+
38
+ *Synchronization:* Prior `unlock()` operations on the same object shall
39
+ synchronize with  ([[intro.multithread]]) this operation.
40
+
41
+ *Throws:* `system_error` when an exception is required
42
+  ([[thread.req.exception]]).
43
+
44
+ *Error conditions:*
45
+
46
+ - `operation_not_permitted` — if the thread does not have the privilege
47
+ to perform the operation.
48
+ - `resource_deadlock_would_occur` — if the implementation detects that a
49
+ deadlock would occur.
50
+ - `device_or_resource_busy` — if the mutex is already locked and
51
+ blocking is not possible.
52
+
53
+ The expression `m.unlock_shared()` shall be well-formed and have the
54
+ following semantics:
55
+
56
+ *Requires:* The calling thread shall hold a shared lock on the mutex.
57
+
58
+ *Effects:* Releases a shared lock on the mutex held by the calling
59
+ thread.
60
+
61
+ *Return type:* `void`.
62
+
63
+ *Synchronization:* This operation synchronizes
64
+ with ([[intro.multithread]]) subsequent `lock()` operations that obtain
65
+ ownership on the same object.
66
+
67
+ *Throws:* Nothing.
68
+
69
+ The expression `m.try_lock_shared()` shall be well-formed and have the
70
+ following semantics:
71
+
72
+ *Requires:* The calling thread has no ownership of the mutex.
73
+
74
+ *Effects:* Attempts to obtain shared ownership of the mutex for the
75
+ calling thread without blocking. If shared ownership is not obtained,
76
+ there is no effect and `try_lock_shared()` immediately returns. An
77
+ implementation may fail to obtain the lock even if it is not held by any
78
+ other thread.
79
+
80
+ *Return type:* `bool`.
81
+
82
+ *Returns:* `true` if the shared ownership lock was acquired, `false`
83
+ otherwise.
84
+
85
+ *Synchronization:* If `try_lock_shared()` returns `true`, prior
86
+ `unlock()` operations on the same object synchronize with
87
+  ([[intro.multithread]]) this operation.
88
+
89
+ *Throws:* Nothing.
90
+
91
+ The expression `m.try_lock_shared_for(rel_time)` shall be well-formed
92
+ and have the following semantics:
93
+
94
+ *Requires:* The calling thread has no ownership of the mutex.
95
+
96
+ *Effects:* Attempts to obtain shared lock ownership for the calling
97
+ thread within the relative timeout ([[thread.req.timing]]) specified by
98
+ `rel_time`. If the time specified by `rel_time` is less than or equal to
99
+ `rel_time.zero()`, the function attempts to obtain ownership without
100
+ blocking (as if by calling `try_lock_shared()`). The function shall
101
+ return within the timeout specified by `rel_time` only if it has
102
+ obtained shared ownership of the mutex object. As with `try_lock()`,
103
+ there is no guarantee that ownership will be obtained if the lock is
104
+ available, but implementations are expected to make a strong effort to
105
+ do so. If an exception is thrown then a shared lock shall not have been
106
+ acquired for the current thread.
107
+
108
+ *Return type:* `bool`.
109
+
110
+ *Returns:* `true` if the shared lock was acquired, `false` otherwise.
111
+
112
+ *Synchronization:* If `try_lock_shared_for()` returns `true`, prior
113
+ `unlock()` operations on the same object synchronize
114
+ with ([[intro.multithread]]) this operation.
115
+
116
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
117
+
118
+ The expression `m.try_lock_shared_until(abs_time)` shall be well-formed
119
+ and have the following semantics:
120
+
121
+ *Requires:* The calling thread has no ownership of the mutex.
122
+
123
+ *Effects:* The function attempts to obtain shared ownership of the
124
+ mutex. If `abs_time` has already passed, the function attempts to obtain
125
+ shared ownership without blocking (as if by calling
126
+ `try_lock_shared()`). The function shall return before the absolute
127
+ timeout ([[thread.req.timing]]) specified by `abs_time` only if it has
128
+ obtained shared ownership of the mutex object. As with `try_lock()`,
129
+ there is no guarantee that ownership will be obtained if the lock is
130
+ available, but implementations are expected to make a strong effort to
131
+ do so. If an exception is thrown then a shared lock shall not have been
132
+ acquired for the current thread.
133
+
134
+ *Return type:* `bool`.
135
+
136
+ *Returns:* `true` if the shared lock was acquired, `false` otherwise.
137
+
138
+ *Synchronization:* If `try_lock_shared_until()` returns `true`, prior
139
+ `unlock()` operations on the same object synchronize
140
+ with ([[intro.multithread]]) this operation.
141
+
142
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
143
+
144
+ ##### Class `shared_timed_mutex` <a id="thread.sharedtimedmutex.class">[[thread.sharedtimedmutex.class]]</a>
145
+
146
+ ``` cpp
147
+ namespace std {
148
+ class shared_timed_mutex {
149
+ public:
150
+ shared_timed_mutex();
151
+ ~shared_timed_mutex();
152
+
153
+ shared_timed_mutex(const shared_timed_mutex&) = delete;
154
+ shared_timed_mutex& operator=(const shared_timed_mutex&) = delete;
155
+
156
+ // Exclusive ownership
157
+ void lock(); // blocking
158
+ bool try_lock();
159
+ template <class Rep, class Period>
160
+ bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
161
+ template <class Clock, class Duration>
162
+ bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
163
+ void unlock();
164
+
165
+ // Shared ownership
166
+ void lock_shared(); // blocking
167
+ bool try_lock_shared();
168
+ template <class Rep, class Period>
169
+ bool
170
+ try_lock_shared_for(const chrono::duration<Rep, Period>& rel_time);
171
+ template <class Clock, class Duration>
172
+ bool
173
+ try_lock_shared_until(const chrono::time_point<Clock, Duration>& abs_time);
174
+ void unlock_shared();
175
+ };
176
+ }
177
+ ```
178
+
179
+ The class `shared_timed_mutex` provides a non-recursive mutex with
180
+ shared ownership semantics.
181
+
182
+ The class `shared_timed_mutex` shall satisfy all of the
183
+ `SharedTimedMutex` requirements (
184
+ [[thread.sharedtimedmutex.requirements]]). It shall be a standard-layout
185
+ class (Clause  [[class]]).
186
+
187
+ The behavior of a program is undefined if:
188
+
189
+ - it destroys a `shared_timed_mutex` object owned by any thread,
190
+ - a thread attempts to recursively gain any ownership of a
191
+ `shared_timed_mutex`, or
192
+ - a thread terminates while possessing any ownership of a
193
+ `shared_timed_mutex`.
194
+