[thread.req] - C++17 → C++20

Files changed (1) hide show

tmp/tmp7a0gz189/{from.md → to.md} +71 -80

tmp/tmp7a0gz189/{from.md → to.md} RENAMED Viewed

@@ -3,35 +3,37 @@
 ### Template parameter names <a id="thread.req.paramname">[[thread.req.paramname]]</a>
 Throughout this Clause, the names of template parameters are used to
 express type requirements. If a template parameter is named `Predicate`,
 `operator()` applied to the template argument shall return a value that
-is convertible to `bool`.
 ### Exceptions <a id="thread.req.exception">[[thread.req.exception]]</a>
 Some functions described in this Clause are specified to throw
-exceptions of type `system_error` ([[syserr.syserr]]). Such exceptions
-shall be thrown if any of the function’s error conditions is detected or
-a call to an operating system or other underlying API results in an
-error that prevents the library function from meeting its
-specifications. Failure to allocate storage shall be reported as
-described in  [[res.on.exception.handling]].
 [*Example 1*: Consider a function in this clause that is specified to
 throw exceptions of type `system_error` and specifies error conditions
 that include `operation_not_permitted` for a thread that does not have
 the privilege to perform the operation. Assume that, during the
 execution of this function, an `errno` of `EPERM` is reported by a POSIX
 API call used by the implementation. Since POSIX specifies an `errno` of
 `EPERM` when “the caller does not have the privilege to perform the
 operation”, the implementation maps `EPERM` to an `error_condition` of
-`operation_not_permitted` ([[syserr]]) and an exception of type
 `system_error` is thrown. — *end example*]
 The `error_code` reported by such an exception’s `code()` member
-function shall compare equal to one of the conditions specified in the
 function’s error condition element.
 ### Native handles <a id="thread.req.native">[[thread.req.native]]</a>
 Several classes described in this Clause have members
@@ -55,98 +57,98 @@ induces a “quality of implementation” delay, expressed as duration Dᵢ.
 Ideally, this delay would be zero. Further, any contention for processor
 and memory resources induces a “quality of management” delay, expressed
 as duration Dₘ. The delay durations may vary from timeout to timeout,
 but in all cases shorter is better.
-The member functions whose names end in `_for` take an argument that
-specifies a duration. These functions produce relative timeouts.
-Implementations should use a steady clock to measure time for these
-functions.[^1] Given a duration argument Dₜ, the real-time duration of
-the timeout is Dₜ + Dᵢ + Dₘ.
-The member functions whose names end in `_until` take an argument that
 specifies a time point. These functions produce absolute timeouts.
 Implementations should use the clock specified in the time point to
 measure time for these functions. Given a clock time point argument Cₜ,
 the clock time point of the return from timeout should be Cₜ + Dᵢ + Dₘ
 when the clock is not adjusted during the timeout. If the clock is
 adjusted to the time Cₐ during the timeout, the behavior should be as
 follows:
-- if Cₐ > Cₜ, the waiting function should wake as soon as possible, i.e.
-  Cₐ + Dᵢ + Dₘ, since the timeout is already satisfied. \[*Note 1*: This
   specification may result in the total duration of the wait decreasing
-  when measured against a steady clock. — *end note*]
-- if Cₐ <= Cₜ, the waiting function should not time out until
-  `Clock::now()` returns a time Cₙ >= Cₜ, i.e. waking at Cₜ + Dᵢ + Dₘ.
-  \[*Note 2*: When the clock is adjusted backwards, this specification
- may result in the total duration of the wait increasing when measured
   against a steady clock. When the clock is adjusted forwards, this
-  specification may result in the total duration of the wait decreasing
   when measured against a steady clock. — *end note*]
-An implementation shall return from such a timeout at any point from the
-time specified above to the time it would return from a steady-clock
-relative timeout on the difference between Cₜ and the time point of the
-call to the `_until` function.
-[*Note 3*: Implementations should decrease the duration of the wait
 when the clock is adjusted forwards. — *end note*]
-[*Note 4*: If the clock is not synchronized with a steady clock, e.g.,
 a CPU time clock, these timeouts might not provide useful
 functionality. — *end note*]
 The resolution of timing provided by an implementation depends on both
 operating system and hardware. The finest resolution provided by an
 implementation is called the *native resolution*.
-Implementation-provided clocks that are used for these functions shall
-meet the `TrivialClock` requirements ([[time.clock.req]]).
 A function that takes an argument which specifies a timeout will throw
 if, during its execution, a clock, time point, or time duration throws
 an exception. Such exceptions are referred to as *timeout-related
 exceptions*.
-[*Note 5*: Instantiations of clock, time point and duration types
 supplied by the implementation as specified in  [[time.clock]] do not
 throw exceptions. — *end note*]
-### Requirements for `Lockable` types <a id="thread.req.lockable">[[thread.req.lockable]]</a>
 #### In general <a id="thread.req.lockable.general">[[thread.req.lockable.general]]</a>
 An *execution agent* is an entity such as a thread that may perform work
 in parallel with other execution agents.
-[*Note 1*: Implementations or users may introduce other kinds of agents
 such as processes or thread-pool tasks. — *end note*]
-The calling agent is determined by context, e.g. the calling thread that
-contains the call, and so on.
 [*Note 2*: Some lockable objects are “agent oblivious” in that they
 work for any execution agent model because they do not determine or
 store the agent’s ID (e.g., an ordinary spin lock). — *end note*]
-The standard library templates `unique_lock` ([[thread.lock.unique]]),
-`shared_lock` ([[thread.lock.shared]]), `scoped_lock` (
-[[thread.lock.scoped]]), `lock_guard` ([[thread.lock.guard]]), `lock`,
-`try_lock` ([[thread.lock.algorithm]]), and `condition_variable_any` (
-[[thread.condition.condvarany]]) all operate on user-supplied lockable
-objects. The `BasicLockable` requirements, the `Lockable` requirements,
-and the `TimedLockable` requirements list the requirements imposed by
-these library types in order to acquire or release ownership of a `lock`
-by a given execution agent.
 [*Note 3*: The nature of any lock ownership and any synchronization it
-may entail are not part of these requirements. — *end note*]
-#### `BasicLockable` requirements <a id="thread.req.lockable.basic">[[thread.req.lockable.basic]]</a>
-A type `L` meets the `BasicLockable` requirements if the following
 expressions are well-formed and have the specified semantics (`m`
 denotes a value of type `L`).
 ``` cpp
 m.lock()
@@ -158,20 +160,20 @@ acquired for the current execution agent.
 ``` cpp
 m.unlock()
 ```
-*Requires:* The current execution agent shall hold a lock on `m`.
 *Effects:* Releases a lock on `m` held by the current execution agent.
 *Throws:* Nothing.
-#### `Lockable` requirements <a id="thread.req.lockable.req">[[thread.req.lockable.req]]</a>
-A type `L` meets the `Lockable` requirements if it meets the
-`BasicLockable` requirements and the following expressions are
 well-formed and have the specified semantics (`m` denotes a value of
 type `L`).
 ``` cpp
 m.try_lock()
@@ -183,55 +185,44 @@ been acquired for the current execution agent.
 *Return type:* `bool`.
 *Returns:* `true` if the lock was acquired, `false` otherwise.
-#### `TimedLockable` requirements <a id="thread.req.lockable.timed">[[thread.req.lockable.timed]]</a>
-A type `L` meets the `TimedLockable` requirements if it meets the
-`Lockable` requirements and the following expressions are well-formed
-and have the specified semantics (`m` denotes a value of type `L`,
-`rel_time` denotes a value of an instantiation of `duration` (
-[[time.duration]]), and `abs_time` denotes a value of an instantiation
-of `time_point` ([[time.point]])).
 ``` cpp
 m.try_lock_for(rel_time)
 ```
 *Effects:* Attempts to acquire a lock for the current execution agent
-within the relative timeout ([[thread.req.timing]]) specified by
-`rel_time`. The function shall not return within the timeout specified
-by `rel_time` unless it has obtained a lock on `m` for the current
-execution agent. If an exception is thrown then a lock shall not have
-been acquired for the current execution agent.
 *Return type:* `bool`.
 *Returns:* `true` if the lock was acquired, `false` otherwise.
 ``` cpp
 m.try_lock_until(abs_time)
 ```
 *Effects:* Attempts to acquire a lock for the current execution agent
-before the absolute timeout ([[thread.req.timing]]) specified by
-`abs_time`. The function shall not return before the timeout specified
-by `abs_time` unless it has obtained a lock on `m` for the current
-execution agent. If an exception is thrown then a lock shall not have
-been acquired for the current execution agent.
 *Return type:* `bool`.
 *Returns:* `true` if the lock was acquired, `false` otherwise.
-### `decay_copy` <a id="thread.decaycopy">[[thread.decaycopy]]</a>
-In several places in this Clause the operation `DECAY_COPY(x)` is used.
-All such uses mean call the function `decay_copy(x)` and use the result,
-where `decay_copy` is defined as follows:
-``` cpp
-template <class T> decay_t<T> decay_copy(T&& v)
-  { return std::forward<T>(v); }
-```

 ### Template parameter names <a id="thread.req.paramname">[[thread.req.paramname]]</a>
 Throughout this Clause, the names of template parameters are used to
 express type requirements. If a template parameter is named `Predicate`,
 `operator()` applied to the template argument shall return a value that
+is convertible to `bool`. If a template parameter is named `Clock`, the
+corresponding template argument shall be a type `C` for which
+`is_clock_v<C>` is `true`; otherwise the program is ill-formed.
 ### Exceptions <a id="thread.req.exception">[[thread.req.exception]]</a>
 Some functions described in this Clause are specified to throw
+exceptions of type `system_error` [[syserr.syserr]]. Such exceptions are
+thrown if any of the function’s error conditions is detected or a call
+to an operating system or other underlying API results in an error that
+prevents the library function from meeting its specifications. Failure
+to allocate storage is reported as described in
+[[res.on.exception.handling]].
 [*Example 1*: Consider a function in this clause that is specified to
 throw exceptions of type `system_error` and specifies error conditions
 that include `operation_not_permitted` for a thread that does not have
 the privilege to perform the operation. Assume that, during the
 execution of this function, an `errno` of `EPERM` is reported by a POSIX
 API call used by the implementation. Since POSIX specifies an `errno` of
 `EPERM` when “the caller does not have the privilege to perform the
 operation”, the implementation maps `EPERM` to an `error_condition` of
+`operation_not_permitted` [[syserr]] and an exception of type
 `system_error` is thrown. — *end example*]
 The `error_code` reported by such an exception’s `code()` member
+function compares equal to one of the conditions specified in the
 function’s error condition element.
 ### Native handles <a id="thread.req.native">[[thread.req.native]]</a>
 Several classes described in this Clause have members
 Ideally, this delay would be zero. Further, any contention for processor
 and memory resources induces a “quality of management” delay, expressed
 as duration Dₘ. The delay durations may vary from timeout to timeout,
 but in all cases shorter is better.
+The functions whose names end in `_for` take an argument that specifies
+a duration. These functions produce relative timeouts. Implementations
+should use a steady clock to measure time for these functions.[^1] Given
+a duration argument Dₜ, the real-time duration of the timeout is
+Dₜ + Dᵢ + Dₘ.
+The functions whose names end in `_until` take an argument that
 specifies a time point. These functions produce absolute timeouts.
 Implementations should use the clock specified in the time point to
 measure time for these functions. Given a clock time point argument Cₜ,
 the clock time point of the return from timeout should be Cₜ + Dᵢ + Dₘ
 when the clock is not adjusted during the timeout. If the clock is
 adjusted to the time Cₐ during the timeout, the behavior should be as
 follows:
+- if Cₐ > Cₜ, the waiting function should wake as soon as possible,
+ i.e., Cₐ + Dᵢ + Dₘ, since the timeout is already satisfied. This
   specification may result in the total duration of the wait decreasing
+  when measured against a steady clock.
+- if Cₐ ≤ Cₜ, the waiting function should not time out until
+  `Clock::now()` returns a time Cₙ ≥ Cₜ, i.e., waking at Cₜ + Dᵢ + Dₘ.
+  \[*Note 1*: When the clock is adjusted backwards, this specification
+ can result in the total duration of the wait increasing when measured
   against a steady clock. When the clock is adjusted forwards, this
+  specification can result in the total duration of the wait decreasing
   when measured against a steady clock. — *end note*]
+An implementation returns from such a timeout at any point from the time
+specified above to the time it would return from a steady-clock relative
+timeout on the difference between Cₜ and the time point of the call to
+the `_until` function.
+[*Note 2*: Implementations should decrease the duration of the wait
 when the clock is adjusted forwards. — *end note*]
+[*Note 3*: If the clock is not synchronized with a steady clock, e.g.,
 a CPU time clock, these timeouts might not provide useful
 functionality. — *end note*]
 The resolution of timing provided by an implementation depends on both
 operating system and hardware. The finest resolution provided by an
 implementation is called the *native resolution*.
+Implementation-provided clocks that are used for these functions meet
+the *Cpp17TrivialClock* requirements [[time.clock.req]].
 A function that takes an argument which specifies a timeout will throw
 if, during its execution, a clock, time point, or time duration throws
 an exception. Such exceptions are referred to as *timeout-related
 exceptions*.
+[*Note 4*: Instantiations of clock, time point and duration types
 supplied by the implementation as specified in  [[time.clock]] do not
 throw exceptions. — *end note*]
+### Requirements for *Cpp17Lockable* types <a id="thread.req.lockable">[[thread.req.lockable]]</a>
 #### In general <a id="thread.req.lockable.general">[[thread.req.lockable.general]]</a>
 An *execution agent* is an entity such as a thread that may perform work
 in parallel with other execution agents.
+[*Note 1*: Implementations or users can introduce other kinds of agents
 such as processes or thread-pool tasks. — *end note*]
+The calling agent is determined by context, e.g., the calling thread
+that contains the call, and so on.
 [*Note 2*: Some lockable objects are “agent oblivious” in that they
 work for any execution agent model because they do not determine or
 store the agent’s ID (e.g., an ordinary spin lock). — *end note*]
+The standard library templates `unique_lock` [[thread.lock.unique]],
+`shared_lock` [[thread.lock.shared]], `scoped_lock`
+[[thread.lock.scoped]], `lock_guard` [[thread.lock.guard]], `lock`,
+`try_lock` [[thread.lock.algorithm]], and `condition_variable_any`
+[[thread.condition.condvarany]] all operate on user-supplied lockable
+objects. The *Cpp17BasicLockable* requirements, the *Cpp17Lockable*
+requirements, and the *Cpp17TimedLockable* requirements list the
+requirements imposed by these library types in order to acquire or
+release ownership of a `lock` by a given execution agent.
 [*Note 3*: The nature of any lock ownership and any synchronization it
+entails are not part of these requirements. — *end note*]
+#### *Cpp17BasicLockable* requirements <a id="thread.req.lockable.basic">[[thread.req.lockable.basic]]</a>
+A type `L` meets the *Cpp17BasicLockable* requirements if the following
 expressions are well-formed and have the specified semantics (`m`
 denotes a value of type `L`).
 ``` cpp
 m.lock()
 ``` cpp
 m.unlock()
 ```
+*Preconditions:* The current execution agent holds a lock on `m`.
 *Effects:* Releases a lock on `m` held by the current execution agent.
 *Throws:* Nothing.
+#### *Cpp17Lockable* requirements <a id="thread.req.lockable.req">[[thread.req.lockable.req]]</a>
+A type `L` meets the *Cpp17Lockable* requirements if it meets the
+*Cpp17BasicLockable* requirements and the following expressions are
 well-formed and have the specified semantics (`m` denotes a value of
 type `L`).
 ``` cpp
 m.try_lock()
 *Return type:* `bool`.
 *Returns:* `true` if the lock was acquired, `false` otherwise.
+#### *Cpp17TimedLockable* requirements <a id="thread.req.lockable.timed">[[thread.req.lockable.timed]]</a>
+A type `L` meets the *Cpp17TimedLockable* requirements if it meets the
+*Cpp17Lockable* requirements and the following expressions are
+well-formed and have the specified semantics (`m` denotes a value of
+type `L`, `rel_time` denotes a value of an instantiation of `duration`
+[[time.duration]], and `abs_time` denotes a value of an instantiation of
+`time_point` [[time.point]]).
 ``` cpp
 m.try_lock_for(rel_time)
 ```
 *Effects:* Attempts to acquire a lock for the current execution agent
+within the relative timeout [[thread.req.timing]] specified by
+`rel_time`. The function will not return within the timeout specified by
+`rel_time` unless it has obtained a lock on `m` for the current
+execution agent. If an exception is thrown then a lock has not been
+acquired for the current execution agent.
 *Return type:* `bool`.
 *Returns:* `true` if the lock was acquired, `false` otherwise.
 ``` cpp
 m.try_lock_until(abs_time)
 ```
 *Effects:* Attempts to acquire a lock for the current execution agent
+before the absolute timeout [[thread.req.timing]] specified by
+`abs_time`. The function will not return before the timeout specified by
+`abs_time` unless it has obtained a lock on `m` for the current
+execution agent. If an exception is thrown then a lock has not been
+acquired for the current execution agent.
 *Return type:* `bool`.
 *Returns:* `true` if the lock was acquired, `false` otherwise.

Diff to HTML by rtfpessoa