From Jason Turner

[thread.req]

C++14 → C++17 10.3 KB 102 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/tmpzgmep_se/{from.md → to.md} +53 -40
tmp/tmpzgmep_se/{from.md → to.md} RENAMED
@@ -15,33 +15,35 @@ shall be thrown if any of the function’s error conditions is detected or
15
  a call to an operating system or other underlying API results in an
16
  error that prevents the library function from meeting its
17
  specifications. Failure to allocate storage shall be reported as
18
  described in  [[res.on.exception.handling]].
19
 
20
- Consider a function in this clause that is specified to throw exceptions
21
- of type `system_error` and specifies error conditions that include
22
- `operation_not_permitted` for a thread that does not have the privilege
23
- to perform the operation. Assume that, during the execution of this
24
- function, an `errno` of `EPERM` is reported by a POSIX API call used by
25
- the implementation. Since POSIX specifies an `errno` of `EPERM` when
26
- “the caller does not have the privilege to perform the operation”, the
27
- implementation maps `EPERM` to an `error_condition` of
28
  `operation_not_permitted` ([[syserr]]) and an exception of type
29
- `system_error` is thrown.
30
 
31
  The `error_code` reported by such an exception’s `code()` member
32
  function shall compare equal to one of the conditions specified in the
33
  function’s error condition element.
34
 
35
  ### Native handles <a id="thread.req.native">[[thread.req.native]]</a>
36
 
37
  Several classes described in this Clause have members
38
  `native_handle_type` and `native_handle`. The presence of these members
39
- and their semantics is *implementation-defined*. These members allow
40
- implementations to provide access to implementation details. Their names
41
- are specified to facilitate portable compile-time detection. Actual use
42
- of these members is inherently non-portable.
 
 
43
 
44
  ### Timing specifications <a id="thread.req.timing">[[thread.req.timing]]</a>
45
 
46
  Several functions described in this Clause take an argument to specify a
47
  timeout. These timeouts are specified as either a `duration` or a
@@ -69,29 +71,32 @@ the clock time point of the return from timeout should be Cₜ + Dᵢ + Dₘ
69
  when the clock is not adjusted during the timeout. If the clock is
70
  adjusted to the time Cₐ during the timeout, the behavior should be as
71
  follows:
72
 
73
  - if Cₐ > Cₜ, the waiting function should wake as soon as possible, i.e.
74
- Cₐ + Dᵢ + Dₘ, since the timeout is already satisfied. This
75
  specification may result in the total duration of the wait decreasing
76
- when measured against a steady clock.
77
  - if Cₐ <= Cₜ, the waiting function should not time out until
78
  `Clock::now()` returns a time Cₙ >= Cₜ, i.e. waking at Cₜ + Dᵢ + Dₘ.
79
- When the clock is adjusted backwards, this specification may result in
80
- the total duration of the wait increasing when measured against a
81
- steady clock. When the clock is adjusted forwards, this specification
82
- may result in the total duration of the wait decreasing when measured
83
- against a steady clock.
84
 
85
  An implementation shall return from such a timeout at any point from the
86
  time specified above to the time it would return from a steady-clock
87
  relative timeout on the difference between Cₜ and the time point of the
88
- call to the `_until` function. Implementations should decrease the
89
- duration of the wait when the clock is adjusted forwards.
90
 
91
- If the clock is not synchronized with a steady clock, e.g., a CPU time
92
- clock, these timeouts might not provide useful functionality.
 
 
 
 
93
 
94
  The resolution of timing provided by an implementation depends on both
95
  operating system and hardware. The finest resolution provided by an
96
  implementation is called the *native resolution*.
97
 
@@ -99,37 +104,45 @@ Implementation-provided clocks that are used for these functions shall
99
  meet the `TrivialClock` requirements ([[time.clock.req]]).
100
 
101
  A function that takes an argument which specifies a timeout will throw
102
  if, during its execution, a clock, time point, or time duration throws
103
  an exception. Such exceptions are referred to as *timeout-related
104
- exceptions*. instantiations of clock, time point and duration types
 
 
105
  supplied by the implementation as specified in  [[time.clock]] do not
106
- throw exceptions.
107
 
108
- ### Requirements for Lockable types <a id="thread.req.lockable">[[thread.req.lockable]]</a>
109
 
110
  #### In general <a id="thread.req.lockable.general">[[thread.req.lockable.general]]</a>
111
 
112
  An *execution agent* is an entity such as a thread that may perform work
113
- in parallel with other execution agents. Implementations or users may
114
- introduce other kinds of agents such as processes or thread-pool tasks.
 
 
 
115
  The calling agent is determined by context, e.g. the calling thread that
116
  contains the call, and so on.
117
 
118
- Some lockable objects are “agent oblivious” in that they work for any
119
- execution agent model because they do not determine or store the agent’s
120
- ID (e.g., an ordinary spin lock).
121
 
122
  The standard library templates `unique_lock` ([[thread.lock.unique]]),
123
- `lock_guard` ([[thread.lock.guard]]), `lock`, `try_lock` (
124
- [[thread.lock.algorithm]]), and `condition_variable_any` (
 
125
  [[thread.condition.condvarany]]) all operate on user-supplied lockable
126
  objects. The `BasicLockable` requirements, the `Lockable` requirements,
127
  and the `TimedLockable` requirements list the requirements imposed by
128
  these library types in order to acquire or release ownership of a `lock`
129
- by a given execution agent. The nature of any lock ownership and any
130
- synchronization it may entail are not part of these requirements.
 
 
131
 
132
  #### `BasicLockable` requirements <a id="thread.req.lockable.basic">[[thread.req.lockable.basic]]</a>
133
 
134
  A type `L` meets the `BasicLockable` requirements if the following
135
  expressions are well-formed and have the specified semantics (`m`
@@ -162,11 +175,11 @@ type `L`).
162
 
163
  ``` cpp
164
  m.try_lock()
165
  ```
166
 
167
- *Effects:* attempts to acquire a lock for the current execution agent
168
  without blocking. If an exception is thrown then a lock shall not have
169
  been acquired for the current execution agent.
170
 
171
  *Return type:* `bool`.
172
 
@@ -183,11 +196,11 @@ of `time_point` ([[time.point]])).
183
 
184
  ``` cpp
185
  m.try_lock_for(rel_time)
186
  ```
187
 
188
- *Effects:* attempts to acquire a lock for the current execution agent
189
  within the relative timeout ([[thread.req.timing]]) specified by
190
  `rel_time`. The function shall not return within the timeout specified
191
  by `rel_time` unless it has obtained a lock on `m` for the current
192
  execution agent. If an exception is thrown then a lock shall not have
193
  been acquired for the current execution agent.
@@ -198,11 +211,11 @@ been acquired for the current execution agent.
198
 
199
  ``` cpp
200
  m.try_lock_until(abs_time)
201
  ```
202
 
203
- *Effects:* attempts to acquire a lock for the current execution agent
204
  before the absolute timeout ([[thread.req.timing]]) specified by
205
  `abs_time`. The function shall not return before the timeout specified
206
  by `abs_time` unless it has obtained a lock on `m` for the current
207
  execution agent. If an exception is thrown then a lock shall not have
208
  been acquired for the current execution agent.
@@ -211,11 +224,11 @@ been acquired for the current execution agent.
211
 
212
  *Returns:* `true` if the lock was acquired, `false` otherwise.
213
 
214
  ### `decay_copy` <a id="thread.decaycopy">[[thread.decaycopy]]</a>
215
 
216
- In several places in this Clause the operation *DECAY_COPY(x)* is used.
217
  All such uses mean call the function `decay_copy(x)` and use the result,
218
  where `decay_copy` is defined as follows:
219
 
220
  ``` cpp
221
  template <class T> decay_t<T> decay_copy(T&& v)
 
15
  a call to an operating system or other underlying API results in an
16
  error that prevents the library function from meeting its
17
  specifications. Failure to allocate storage shall be reported as
18
  described in  [[res.on.exception.handling]].
19
 
20
+ [*Example 1*: Consider a function in this clause that is specified to
21
+ throw exceptions of type `system_error` and specifies error conditions
22
+ that include `operation_not_permitted` for a thread that does not have
23
+ the privilege to perform the operation. Assume that, during the
24
+ execution of this function, an `errno` of `EPERM` is reported by a POSIX
25
+ API call used by the implementation. Since POSIX specifies an `errno` of
26
+ `EPERM` when “the caller does not have the privilege to perform the
27
+ operation”, the implementation maps `EPERM` to an `error_condition` of
28
  `operation_not_permitted` ([[syserr]]) and an exception of type
29
+ `system_error` is thrown. — *end example*]
30
 
31
  The `error_code` reported by such an exception’s `code()` member
32
  function shall compare equal to one of the conditions specified in the
33
  function’s error condition element.
34
 
35
  ### Native handles <a id="thread.req.native">[[thread.req.native]]</a>
36
 
37
  Several classes described in this Clause have members
38
  `native_handle_type` and `native_handle`. The presence of these members
39
+ and their semantics is *implementation-defined*.
40
+
41
+ [*Note 1*: These members allow implementations to provide access to
42
+ implementation details. Their names are specified to facilitate portable
43
+ compile-time detection. Actual use of these members is inherently
44
+ non-portable. — *end note*]
45
 
46
  ### Timing specifications <a id="thread.req.timing">[[thread.req.timing]]</a>
47
 
48
  Several functions described in this Clause take an argument to specify a
49
  timeout. These timeouts are specified as either a `duration` or a
 
71
  when the clock is not adjusted during the timeout. If the clock is
72
  adjusted to the time Cₐ during the timeout, the behavior should be as
73
  follows:
74
 
75
  - if Cₐ > Cₜ, the waiting function should wake as soon as possible, i.e.
76
+ Cₐ + Dᵢ + Dₘ, since the timeout is already satisfied. \[*Note 1*: This
77
  specification may result in the total duration of the wait decreasing
78
+ when measured against a steady clock. — *end note*]
79
  - if Cₐ <= Cₜ, the waiting function should not time out until
80
  `Clock::now()` returns a time Cₙ >= Cₜ, i.e. waking at Cₜ + Dᵢ + Dₘ.
81
+ \[*Note 2*: When the clock is adjusted backwards, this specification
82
+ may result in the total duration of the wait increasing when measured
83
+ against a steady clock. When the clock is adjusted forwards, this
84
+ specification may result in the total duration of the wait decreasing
85
+ when measured against a steady clock. — *end note*]
86
 
87
  An implementation shall return from such a timeout at any point from the
88
  time specified above to the time it would return from a steady-clock
89
  relative timeout on the difference between Cₜ and the time point of the
90
+ call to the `_until` function.
 
91
 
92
+ [*Note 3*: Implementations should decrease the duration of the wait
93
+ when the clock is adjusted forwards. — *end note*]
94
+
95
+ [*Note 4*: If the clock is not synchronized with a steady clock, e.g.,
96
+ a CPU time clock, these timeouts might not provide useful
97
+ functionality. — *end note*]
98
 
99
  The resolution of timing provided by an implementation depends on both
100
  operating system and hardware. The finest resolution provided by an
101
  implementation is called the *native resolution*.
102
 
 
104
  meet the `TrivialClock` requirements ([[time.clock.req]]).
105
 
106
  A function that takes an argument which specifies a timeout will throw
107
  if, during its execution, a clock, time point, or time duration throws
108
  an exception. Such exceptions are referred to as *timeout-related
109
+ exceptions*.
110
+
111
+ [*Note 5*: Instantiations of clock, time point and duration types
112
  supplied by the implementation as specified in  [[time.clock]] do not
113
+ throw exceptions. — *end note*]
114
 
115
+ ### Requirements for `Lockable` types <a id="thread.req.lockable">[[thread.req.lockable]]</a>
116
 
117
  #### In general <a id="thread.req.lockable.general">[[thread.req.lockable.general]]</a>
118
 
119
  An *execution agent* is an entity such as a thread that may perform work
120
+ in parallel with other execution agents.
121
+
122
+ [*Note 1*: Implementations or users may introduce other kinds of agents
123
+ such as processes or thread-pool tasks. — *end note*]
124
+
125
  The calling agent is determined by context, e.g. the calling thread that
126
  contains the call, and so on.
127
 
128
+ [*Note 2*: Some lockable objects are “agent oblivious” in that they
129
+ work for any execution agent model because they do not determine or
130
+ store the agent’s ID (e.g., an ordinary spin lock). — *end note*]
131
 
132
  The standard library templates `unique_lock` ([[thread.lock.unique]]),
133
+ `shared_lock` ([[thread.lock.shared]]), `scoped_lock` (
134
+ [[thread.lock.scoped]]), `lock_guard` ([[thread.lock.guard]]), `lock`,
135
+ `try_lock` ([[thread.lock.algorithm]]), and `condition_variable_any` (
136
  [[thread.condition.condvarany]]) all operate on user-supplied lockable
137
  objects. The `BasicLockable` requirements, the `Lockable` requirements,
138
  and the `TimedLockable` requirements list the requirements imposed by
139
  these library types in order to acquire or release ownership of a `lock`
140
+ by a given execution agent.
141
+
142
+ [*Note 3*: The nature of any lock ownership and any synchronization it
143
+ may entail are not part of these requirements. — *end note*]
144
 
145
  #### `BasicLockable` requirements <a id="thread.req.lockable.basic">[[thread.req.lockable.basic]]</a>
146
 
147
  A type `L` meets the `BasicLockable` requirements if the following
148
  expressions are well-formed and have the specified semantics (`m`
 
175
 
176
  ``` cpp
177
  m.try_lock()
178
  ```
179
 
180
+ *Effects:* Attempts to acquire a lock for the current execution agent
181
  without blocking. If an exception is thrown then a lock shall not have
182
  been acquired for the current execution agent.
183
 
184
  *Return type:* `bool`.
185
 
 
196
 
197
  ``` cpp
198
  m.try_lock_for(rel_time)
199
  ```
200
 
201
+ *Effects:* Attempts to acquire a lock for the current execution agent
202
  within the relative timeout ([[thread.req.timing]]) specified by
203
  `rel_time`. The function shall not return within the timeout specified
204
  by `rel_time` unless it has obtained a lock on `m` for the current
205
  execution agent. If an exception is thrown then a lock shall not have
206
  been acquired for the current execution agent.
 
211
 
212
  ``` cpp
213
  m.try_lock_until(abs_time)
214
  ```
215
 
216
+ *Effects:* Attempts to acquire a lock for the current execution agent
217
  before the absolute timeout ([[thread.req.timing]]) specified by
218
  `abs_time`. The function shall not return before the timeout specified
219
  by `abs_time` unless it has obtained a lock on `m` for the current
220
  execution agent. If an exception is thrown then a lock shall not have
221
  been acquired for the current execution agent.
 
224
 
225
  *Returns:* `true` if the lock was acquired, `false` otherwise.
226
 
227
  ### `decay_copy` <a id="thread.decaycopy">[[thread.decaycopy]]</a>
228
 
229
+ In several places in this Clause the operation `DECAY_COPY(x)` is used.
230
  All such uses mean call the function `decay_copy(x)` and use the result,
231
  where `decay_copy` is defined as follows:
232
 
233
  ``` cpp
234
  template <class T> decay_t<T> decay_copy(T&& v)