[thread.condition.condvarany]

Files changed (1) hide show

tmp/tmpz4jb_ft9/{from.md → to.md} +132 -39

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

@@ -1,14 +1,14 @@
 ### Class `condition_variable_any` <a id="thread.condition.condvarany">[[thread.condition.condvarany]]</a>
-A `Lock` type shall meet the `BasicLockable` requirements (
-[[thread.req.lockable.basic]]).
 [*Note 1*: All of the standard mutex types meet this requirement. If a
 `Lock` type other than one of the standard mutex types or a
 `unique_lock` wrapper for a standard mutex type is used with
-`condition_variable_any`, the user must ensure that any necessary
 synchronization is in place with respect to the predicate associated
 with the `condition_variable_any` instance. — *end note*]
 ``` cpp
 namespace std {
@@ -20,10 +20,12 @@ namespace std {
     condition_variable_any(const condition_variable_any&) = delete;
     condition_variable_any& operator=(const condition_variable_any&) = delete;
     void notify_one() noexcept;
     void notify_all() noexcept;
     template<class Lock>
       void wait(Lock& lock);
     template<class Lock, class Predicate>
       void wait(Lock& lock, Predicate pred);
@@ -33,24 +35,31 @@ namespace std {
       bool wait_until(Lock& lock, const chrono::time_point<Clock, Duration>& abs_time,
                       Predicate pred);
     template<class Lock, class Rep, class Period>
       cv_status wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time);
     template<class Lock, class Rep, class Period, class Predicate>
-      bool wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time,
-        Predicate pred);
   };
 }
 ```
 ``` cpp
 condition_variable_any();
 ```
-*Effects:* Constructs an object of type `condition_variable_any`.
 *Throws:* `bad_alloc` or `system_error` when an exception is
-required ([[thread.req.exception]]).
 *Error conditions:*
 - `resource_unavailable_try_again` — if some non-memory resource
   limitation prevents initialization.
@@ -59,24 +68,22 @@ required ([[thread.req.exception]]).
 ``` cpp
 ~condition_variable_any();
 ```
-*Requires:* There shall be no thread blocked on `*this`.
-[*Note 1*: That is, all threads shall have been notified; they may
 subsequently block on the lock specified in the wait. This relaxes the
 usual rules, which would have required all wait calls to happen before
-destruction. Only the notification to unblock the wait must happen
-before destruction. The user must take care to ensure that no threads
 wait on `*this` once the destructor has been started, especially when
 the waiting threads are calling the wait functions in a loop or using
 the overloads of `wait`, `wait_for`, or `wait_until` that take a
 predicate. — *end note*]
-*Effects:* Destroys the object.
 ``` cpp
 void notify_one() noexcept;
 ```
 *Effects:* If any threads are blocked waiting for `*this`, unblocks one
@@ -86,34 +93,32 @@ of those threads.
 void notify_all() noexcept;
 ```
 *Effects:* Unblocks all threads that are blocked waiting for `*this`.
 ``` cpp
 template<class Lock>
   void wait(Lock& lock);
 ```
-[*Note 2*: If any of the `wait` functions exits via an exception, it is
-unspecified whether the `Lock` is held. One can use a `Lock` type that
-allows to query that, such as the `unique_lock` wrapper. — *end note*]
 *Effects:*
 - Atomically calls `lock.unlock()` and blocks on `*this`.
 - When unblocked, calls `lock.lock()` (possibly blocking on the lock)
   and returns.
 - The function will unblock when signaled by a call to `notify_one()`, a
   call to `notify_all()`, or spuriously.
 *Remarks:* If the function fails to meet the postcondition,
-`terminate()` shall be called ([[except.terminate]]).
-[*Note 3*: This can happen if the re-locking of the mutex throws an
 exception. — *end note*]
-*Postconditions:* `lock` is locked by the calling thread.
 *Throws:* Nothing.
 ``` cpp
 template<class Lock, class Predicate>
@@ -137,28 +142,27 @@ template <class Lock, class Clock, class Duration>
 - Atomically calls `lock.unlock()` and blocks on `*this`.
 - When unblocked, calls `lock.lock()` (possibly blocking on the lock)
   and returns.
 - The function will unblock when signaled by a call to `notify_one()`, a
   call to `notify_all()`, expiration of the absolute
-  timeout ([[thread.req.timing]]) specified by `abs_time`, or
-  spuriously.
-- If the function exits via an exception, `lock.lock()` shall be called
-  prior to exiting the function.
 *Remarks:* If the function fails to meet the postcondition,
-`terminate()` shall be called ([[except.terminate]]).
-[*Note 4*: This can happen if the re-locking of the mutex throws an
 exception. — *end note*]
-*Postconditions:* `lock` is locked by the calling thread.
 *Returns:* `cv_status::timeout` if the absolute
-timeout ([[thread.req.timing]]) specified by `abs_time` expired,
-otherwise `cv_status::no_timeout`.
-*Throws:* Timeout-related exceptions ([[thread.req.timing]]).
 ``` cpp
 template<class Lock, class Rep, class Period>
   cv_status wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time);
 ```
@@ -168,22 +172,22 @@ template <class Lock, class Rep, class Period>
 ``` cpp
 return wait_until(lock, chrono::steady_clock::now() + rel_time);
 ```
 *Returns:* `cv_status::timeout` if the relative
-timeout ([[thread.req.timing]]) specified by `rel_time` expired,
-otherwise `cv_status::no_timeout`.
 *Remarks:* If the function fails to meet the postcondition,
-`terminate()` shall be called ([[except.terminate]]).
-[*Note 5*: This can happen if the re-locking of the mutex throws an
 exception. — *end note*]
-*Postconditions:* `lock` is locked by the calling thread.
-*Throws:* Timeout-related exceptions ([[thread.req.timing]]).
 ``` cpp
 template<class Lock, class Clock, class Duration, class Predicate>
   bool wait_until(Lock& lock, const chrono::time_point<Clock, Duration>& abs_time, Predicate pred);
 ```
@@ -195,14 +199,14 @@ while (!pred())
   if (wait_until(lock, abs_time) == cv_status::timeout)
     return pred();
 return true;
 ```
-[*Note 6*: There is no blocking if `pred()` is initially `true`, or if
 the timeout has already expired. — *end note*]
-[*Note 7*: The returned value indicates whether the predicate evaluates
 to `true` regardless of whether the timeout was
 triggered. — *end note*]
 ``` cpp
 template<class Lock, class Rep, class Period, class Predicate>
@@ -213,5 +217,94 @@ template <class Lock, class Rep, class Period, class Predicate>
 ``` cpp
 return wait_until(lock, chrono::steady_clock::now() + rel_time, std::move(pred));
 ```

 ### Class `condition_variable_any` <a id="thread.condition.condvarany">[[thread.condition.condvarany]]</a>
+A `Lock` type shall meet the *Cpp17BasicLockable* requirements
+[[thread.req.lockable.basic]].
 [*Note 1*: All of the standard mutex types meet this requirement. If a
 `Lock` type other than one of the standard mutex types or a
 `unique_lock` wrapper for a standard mutex type is used with
+`condition_variable_any`, the user should ensure that any necessary
 synchronization is in place with respect to the predicate associated
 with the `condition_variable_any` instance. — *end note*]
 ``` cpp
 namespace std {
     condition_variable_any(const condition_variable_any&) = delete;
     condition_variable_any& operator=(const condition_variable_any&) = delete;
     void notify_one() noexcept;
     void notify_all() noexcept;
+    // [thread.condvarany.wait], noninterruptible waits
     template<class Lock>
       void wait(Lock& lock);
     template<class Lock, class Predicate>
       void wait(Lock& lock, Predicate pred);
       bool wait_until(Lock& lock, const chrono::time_point<Clock, Duration>& abs_time,
                       Predicate pred);
     template<class Lock, class Rep, class Period>
       cv_status wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time);
     template<class Lock, class Rep, class Period, class Predicate>
+      bool wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time, Predicate pred);
+    // [thread.condvarany.intwait], interruptible waits
+    template<class Lock, class Predicate>
+      bool wait(Lock& lock, stop_token stoken, Predicate pred);
+    template<class Lock, class Clock, class Duration, class Predicate>
+      bool wait_until(Lock& lock, stop_token stoken,
+                      const chrono::time_point<Clock, Duration>& abs_time, Predicate pred);
+    template<class Lock, class Rep, class Period, class Predicate>
+      bool wait_for(Lock& lock, stop_token stoken,
+                    const chrono::duration<Rep, Period>& rel_time, Predicate pred);
   };
 }
 ```
 ``` cpp
 condition_variable_any();
 ```
 *Throws:* `bad_alloc` or `system_error` when an exception is
+required [[thread.req.exception]].
 *Error conditions:*
 - `resource_unavailable_try_again` — if some non-memory resource
   limitation prevents initialization.
 ``` cpp
 ~condition_variable_any();
 ```
+*Preconditions:* There is no thread blocked on `*this`.
+[*Note 1*: That is, all threads have been notified; they could
 subsequently block on the lock specified in the wait. This relaxes the
 usual rules, which would have required all wait calls to happen before
+destruction. Only the notification to unblock the wait needs to happen
+before destruction. The user should take care to ensure that no threads
 wait on `*this` once the destructor has been started, especially when
 the waiting threads are calling the wait functions in a loop or using
 the overloads of `wait`, `wait_for`, or `wait_until` that take a
 predicate. — *end note*]
 ``` cpp
 void notify_one() noexcept;
 ```
 *Effects:* If any threads are blocked waiting for `*this`, unblocks one
 void notify_all() noexcept;
 ```
 *Effects:* Unblocks all threads that are blocked waiting for `*this`.
+#### Noninterruptible waits <a id="thread.condvarany.wait">[[thread.condvarany.wait]]</a>
 ``` cpp
 template<class Lock>
   void wait(Lock& lock);
 ```
 *Effects:*
 - Atomically calls `lock.unlock()` and blocks on `*this`.
 - When unblocked, calls `lock.lock()` (possibly blocking on the lock)
   and returns.
 - The function will unblock when signaled by a call to `notify_one()`, a
   call to `notify_all()`, or spuriously.
 *Remarks:* If the function fails to meet the postcondition,
+`terminate()` is called [[except.terminate]].
+[*Note 1*: This can happen if the re-locking of the mutex throws an
 exception. — *end note*]
+*Ensures:* `lock` is locked by the calling thread.
 *Throws:* Nothing.
 ``` cpp
 template<class Lock, class Predicate>
 - Atomically calls `lock.unlock()` and blocks on `*this`.
 - When unblocked, calls `lock.lock()` (possibly blocking on the lock)
   and returns.
 - The function will unblock when signaled by a call to `notify_one()`, a
   call to `notify_all()`, expiration of the absolute
+  timeout [[thread.req.timing]] specified by `abs_time`, or spuriously.
+- If the function exits via an exception, `lock.lock()` is called prior
+  to exiting the function.
 *Remarks:* If the function fails to meet the postcondition,
+`terminate()` is called [[except.terminate]].
+[*Note 2*: This can happen if the re-locking of the mutex throws an
 exception. — *end note*]
+*Ensures:* `lock` is locked by the calling thread.
 *Returns:* `cv_status::timeout` if the absolute
+timeout [[thread.req.timing]] specified by `abs_time` expired, otherwise
+`cv_status::no_timeout`.
+*Throws:* Timeout-related exceptions [[thread.req.timing]].
 ``` cpp
 template<class Lock, class Rep, class Period>
   cv_status wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time);
 ```
 ``` cpp
 return wait_until(lock, chrono::steady_clock::now() + rel_time);
 ```
 *Returns:* `cv_status::timeout` if the relative
+timeout [[thread.req.timing]] specified by `rel_time` expired, otherwise
+`cv_status::no_timeout`.
 *Remarks:* If the function fails to meet the postcondition,
+`terminate()` is called [[except.terminate]].
+[*Note 3*: This can happen if the re-locking of the mutex throws an
 exception. — *end note*]
+*Ensures:* `lock` is locked by the calling thread.
+*Throws:* Timeout-related exceptions [[thread.req.timing]].
 ``` cpp
 template<class Lock, class Clock, class Duration, class Predicate>
   bool wait_until(Lock& lock, const chrono::time_point<Clock, Duration>& abs_time, Predicate pred);
 ```
   if (wait_until(lock, abs_time) == cv_status::timeout)
     return pred();
 return true;
 ```
+[*Note 4*: There is no blocking if `pred()` is initially `true`, or if
 the timeout has already expired. — *end note*]
+[*Note 5*: The returned value indicates whether the predicate evaluates
 to `true` regardless of whether the timeout was
 triggered. — *end note*]
 ``` cpp
 template<class Lock, class Rep, class Period, class Predicate>
 ``` cpp
 return wait_until(lock, chrono::steady_clock::now() + rel_time, std::move(pred));
 ```
+#### Interruptible waits <a id="thread.condvarany.intwait">[[thread.condvarany.intwait]]</a>
+The following wait functions will be notified when there is a stop
+request on the passed `stop_token`. In that case the functions return
+immediately, returning `false` if the predicate evaluates to `false`.
+``` cpp
+template<class Lock, class Predicate>
+  bool wait(Lock& lock, stop_token stoken, Predicate pred);
+```
+*Effects:* Registers for the duration of this call `*this` to get
+notified on a stop request on `stoken` during this call and then
+equivalent to:
+``` cpp
+while (!stoken.stop_requested()) {
+  if (pred())
+    return true;
+  wait(lock);
+}
+return pred();
+```
+[*Note 1*: The returned value indicates whether the predicate evaluated
+to `true` regardless of whether there was a stop request. — *end note*]
+*Ensures:* `lock` is locked by the calling thread.
+*Remarks:* If the function fails to meet the postcondition, `terminate`
+is called [[except.terminate]].
+[*Note 2*: This can happen if the re-locking of the mutex throws an
+exception. — *end note*]
+*Throws:* Any exception thrown by `pred`.
+``` cpp
+template<class Lock, class Clock, class Duration, class Predicate>
+  bool wait_until(Lock& lock, stop_token stoken,
+                  const chrono::time_point<Clock, Duration>& abs_time, Predicate pred);
+```
+*Effects:* Registers for the duration of this call `*this` to get
+notified on a stop request on `stoken` during this call and then
+equivalent to:
+``` cpp
+while (!stoken.stop_requested()) {
+  if (pred())
+    return true;
+  if (cv.wait_until(lock, abs_time) == cv_status::timeout)
+    return pred();
+}
+return pred();
+```
+[*Note 3*: There is no blocking if `pred()` is initially `true`,
+`stoken.stop_requested()` was already `true` or the timeout has already
+expired. — *end note*]
+[*Note 4*: The returned value indicates whether the predicate evaluated
+to `true` regardless of whether the timeout was triggered or a stop
+request was made. — *end note*]
+*Ensures:* `lock` is locked by the calling thread.
+*Remarks:* If the function fails to meet the postcondition, `terminate`
+is called [[except.terminate]].
+[*Note 5*: This can happen if the re-locking of the mutex throws an
+exception. — *end note*]
+*Throws:* Timeout-related exceptions [[thread.req.timing]], or any
+exception thrown by `pred`.
+``` cpp
+template<class Lock, class Rep, class Period, class Predicate>
+  bool wait_for(Lock& lock, stop_token stoken,
+                const chrono::duration<Rep, Period>& rel_time, Predicate pred);
+```
+*Effects:* Equivalent to:
+``` cpp
+return wait_until(lock, std::move(stoken), chrono::steady_clock::now() + rel_time,
+                  std::move(pred));
+```

Diff to HTML by rtfpessoa