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

Files changed (1) hide show

tmp/tmpebofzy3c/{from.md → to.md} +115 -22

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

@@ -1,15 +1,20 @@
 ## Requirements <a id="thread.req">[[thread.req]]</a>
 ### 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
@@ -17,11 +22,11 @@ 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
@@ -59,12 +64,13 @@ 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
@@ -72,15 +78,15 @@ 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
@@ -89,15 +95,15 @@ follows:
 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*.
@@ -108,11 +114,11 @@ 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>
@@ -135,17 +141,31 @@ 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`).
@@ -160,13 +180,15 @@ acquired for the current execution agent.
 ``` 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>
@@ -183,11 +205,11 @@ m.try_lock()
 without blocking. 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.
 #### *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
@@ -207,11 +229,11 @@ within the relative timeout [[thread.req.timing]] specified by
 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)
 ```
@@ -222,7 +244,78 @@ before the absolute timeout [[thread.req.timing]] specified by
 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.

 ## Requirements <a id="thread.req">[[thread.req]]</a>
 ### 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. `Predicate` is a function object type
+[[function.objects]]. Let `pred` denote an lvalue of type `Predicate`.
+Then the expression `pred()` shall be well-formed and the type
+`decltype(pred())` shall model `boolean-testable`
+[[concept.booleantestable]]. The return value of `pred()`, converted to
+`bool`, yields `true` if the corresponding test condition is satisfied,
+and `false` otherwise. If a template parameter is named `Clock`, the
+corresponding template argument shall be a type `C` that meets the
+*Cpp17Clock* requirements [[time.clock.req]]; the program is ill-formed
+if `is_clock_v<C>` is `false`.
 ### 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
 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
 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
 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
 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.
+*Recommended practice:* Implementations should decrease the duration of
+the wait when the clock is adjusted forwards.
+[*Note 2*: If the clock is not synchronized with a steady clock, e.g.,
+a CPU time clock, these timeouts can fail to 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*.
 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 3*: 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>
 `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, the *Cpp17TimedLockable* requirements, the
+*Cpp17SharedLockable* requirements, and the *Cpp17SharedTimedLockable*
+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*]
+A lock on an object `m` is said to be
+- a *non-shared lock* if it is acquired by a call to `lock`, `try_lock`,
+  `try_lock_for`, or `try_lock_until` on `m`, or
+- a *shared lock* if it is acquired by a call to `lock_shared`,
+  `try_lock_shared`, `try_lock_shared_for`, or `try_lock_shared_until`
+  on `m`.
+[*Note 4*: Only the method of lock acquisition is considered; the
+nature of any lock ownership is not part of these
+definitions. — *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.unlock()
 ```
+*Preconditions:* The current execution agent holds a non-shared lock on
+`m`.
+*Effects:* Releases a non-shared lock on `m` held by the current
+execution agent.
 *Throws:* Nothing.
 #### *Cpp17Lockable* requirements <a id="thread.req.lockable.req">[[thread.req.lockable.req]]</a>
 without blocking. 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, otherwise `false`.
 #### *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
 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, otherwise `false`.
 ``` cpp
 m.try_lock_until(abs_time)
 ```
 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, otherwise `false`.
+#### *Cpp17SharedLockable* requirements <a id="thread.req.lockable.shared">[[thread.req.lockable.shared]]</a>
+A type `L` meets the *Cpp17SharedLockable* requirements if the following
+expressions are well-formed, have the specified semantics, and the
+expression `m.try_lock_shared()` has type `bool` (`m` denotes a value of
+type `L`):
+``` cpp
+m.lock_shared()
+```
+*Effects:* Blocks until a lock can be acquired for the current execution
+agent. If an exception is thrown then a lock shall not have been
+acquired for the current execution agent.
+``` cpp
+m.try_lock_shared()
+```
+*Effects:* Attempts to acquire a lock for the current execution agent
+without blocking. If an exception is thrown then a lock shall not have
+been acquired for the current execution agent.
+*Returns:* `true` if the lock was acquired, `false` otherwise.
+``` cpp
+m.unlock_shared()
+```
+*Preconditions:* The current execution agent holds a shared lock on `m`.
+*Effects:* Releases a shared lock on `m` held by the current execution
+agent.
+*Throws:* Nothing.
+#### *Cpp17SharedTimedLockable* requirements <a id="thread.req.lockable.shared.timed">[[thread.req.lockable.shared.timed]]</a>
+A type `L` meets the *Cpp17SharedTimedLockable* requirements if it meets
+the *Cpp17SharedLockable* requirements, and the following expressions
+are well-formed, have type `bool`, and have the specified semantics (`m`
+denotes a value of type `L`, `rel_time` denotes a value of a
+specialization of `chrono::duration`, and `abs_time` denotes a value of
+a specialization of `chrono::time_point`).
+``` cpp
+m.try_lock_shared_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.
+*Returns:* `true` if the lock was acquired, `false` otherwise.
+``` cpp
+m.try_lock_shared_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.
 *Returns:* `true` if the lock was acquired, `false` otherwise.

Diff to HTML by rtfpessoa