From Jason Turner

[thread]

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp0i86jmbz/{from.md → to.md} +723 -217
tmp/tmp0i86jmbz/{from.md → to.md} RENAMED
@@ -12,23 +12,23 @@ Table  [[tab:thread.lib.summary]].
12
  | Subclause | | Header |
13
  | -------------------- | ------------------- | ---------------------- |
14
  | [[thread.req]] | Requirements | |
15
  | [[thread.threads]] | Threads | `<thread>` |
16
  | [[thread.mutex]] | Mutual exclusion | `<mutex>` |
 
17
  | [[thread.condition]] | Condition variables | `<condition_variable>` |
18
  | [[futures]] | Futures | `<future>` |
19
 
20
 
21
  ## Requirements <a id="thread.req">[[thread.req]]</a>
22
 
23
  ### Template parameter names <a id="thread.req.paramname">[[thread.req.paramname]]</a>
24
 
25
  Throughout this Clause, the names of template parameters are used to
26
- express type requirements.
27
-
28
- If a parameter is `Predicate`, `operator()` applied to the actual
29
- template argument shall return a value that is convertible to `bool`.
30
 
31
  ### Exceptions <a id="thread.req.exception">[[thread.req.exception]]</a>
32
 
33
  Some functions described in this Clause are specified to throw
34
  exceptions of type `system_error` ([[syserr.syserr]]). Such exceptions
@@ -117,10 +117,17 @@ operating system and hardware. The finest resolution provided by an
117
  implementation is called the *native resolution*.
118
 
119
  Implementation-provided clocks that are used for these functions shall
120
  meet the `TrivialClock` requirements ([[time.clock.req]]).
121
 
 
 
 
 
 
 
 
122
  ### Requirements for Lockable types <a id="thread.req.lockable">[[thread.req.lockable]]</a>
123
 
124
  #### In general <a id="thread.req.lockable.general">[[thread.req.lockable.general]]</a>
125
 
126
  An *execution agent* is an entity such as a thread that may perform work
@@ -230,11 +237,11 @@ been acquired for the current execution agent.
230
  In several places in this Clause the operation *DECAY_COPY(x)* is used.
231
  All such uses mean call the function `decay_copy(x)` and use the result,
232
  where `decay_copy` is defined as follows:
233
 
234
  ``` cpp
235
- template <class T> typename decay<T>::type decay_copy(T&& v)
236
  { return std::forward<T>(v); }
237
  ```
238
 
239
  ## Threads <a id="thread.threads">[[thread.threads]]</a>
240
 
@@ -410,12 +417,12 @@ representations.
410
 
411
  ``` cpp
412
  template <> struct hash<thread::id>;
413
  ```
414
 
415
- *Requires:* the template specialization shall meet the requirements of
416
- class template `hash` ([[unord.hash]]).
417
 
418
  #### `thread` constructors <a id="thread.thread.constr">[[thread.thread.constr]]</a>
419
 
420
  ``` cpp
421
  thread() noexcept;
@@ -433,10 +440,13 @@ template <class F, class ...Args> explicit thread(F&& f, Args&&... args);
433
  *Requires:*  `F` and each `Ti` in `Args` shall satisfy the
434
  `MoveConstructible` requirements. *`INVOKE`*`(`*`DECAY_COPY`*`(`
435
  `std::forward<F>(f)), `*`DECAY_COPY`*`(std::forward<Args>(args))...)` ([[func.require]])
436
  shall be a valid expression.
437
 
 
 
 
438
  *Effects:*  Constructs an object of type `thread`. The new thread of
439
  execution executes
440
  *`INVOKE`*`(`*`DECAY_COPY`*`(` `std::forward<F>(f)), `*`DECAY_COPY`*`(std::forward<Args>(args))...)`
441
  with the calls to *`DECAY_COPY`* being evaluated in the constructing
442
  thread. Any return value from this invocation is ignored. This implies
@@ -627,15 +637,11 @@ template <class Clock, class Duration>
627
  *Effects:* Blocks the calling thread for the absolute
628
  timeout ([[thread.req.timing]]) specified by `abs_time`.
629
 
630
  *Synchronization:* None.
631
 
632
- *Throws:* Nothing if `Clock` satisfies the `TrivialClock`
633
- requirements ([[time.clock.req]]) and operations of `Duration` do not
634
- throw exceptions. instantiations of time point types and clocks supplied
635
- by the implementation as specified in  [[time.clock]] do not throw
636
- exceptions.
637
 
638
  ``` cpp
639
  template <class Rep, class Period>
640
  void sleep_for(const chrono::duration<Rep, Period>& rel_time);
641
  ```
@@ -643,13 +649,11 @@ template <class Rep, class Period>
643
  *Effects:* Blocks the calling thread for the relative
644
  timeout ([[thread.req.timing]]) specified by `rel_time`.
645
 
646
  *Synchronization:* None.
647
 
648
- *Throws:* Nothing if operations of `chrono::duration<Rep, Period>` do
649
- not throw exceptions. instantiations of duration types supplied by the
650
- implementation as specified in  [[time.clock]] do not throw exceptions.
651
 
652
  ## Mutual exclusion <a id="thread.mutex">[[thread.mutex]]</a>
653
 
654
  This section provides mechanisms for mutual exclusion: mutexes, locks,
655
  and call once. These mechanisms ease the production of race-free
@@ -685,11 +689,20 @@ namespace std {
685
  once_flag(const once_flag&) = delete;
686
  once_flag& operator=(const once_flag&) = delete;
687
  };
688
 
689
  template<class Callable, class ...Args>
690
- void call_once(once_flag& flag, Callable func, Args&&... args);
 
 
 
 
 
 
 
 
 
691
  }
692
  ```
693
 
694
  ### Mutex requirements <a id="thread.mutex.requirements">[[thread.mutex.requirements]]</a>
695
 
@@ -698,22 +711,20 @@ namespace std {
698
  A mutex object facilitates protection against data races and allows safe
699
  synchronization of data between execution agents (
700
  [[thread.req.lockable]]). An execution agent *owns* a mutex from the
701
  time it successfully calls one of the lock functions until it calls
702
  unlock. Mutexes can be either recursive or non-recursive, and can grant
703
- simultaneous ownership to one or many execution agents. The mutex types
704
- supplied by the standard library provide exclusive ownership semantics:
705
- only one thread may own the mutex at a time. Both recursive and
706
- non-recursive mutexes are supplied.
707
 
708
  #### Mutex types <a id="thread.mutex.requirements.mutex">[[thread.mutex.requirements.mutex]]</a>
709
 
710
  The *mutex types* are the standard library types `std::mutex`,
711
- `std::recursive_mutex`, `std::timed_mutex`, and
712
- `std::recursive_timed_mutex`. They shall meet the requirements set out
713
- in this section. In this description, `m` denotes an object of a mutex
714
- type.
715
 
716
  The mutex types shall meet the `Lockable` requirements (
717
  [[thread.req.lockable.req]]).
718
 
719
  The mutex types shall be `DefaultConstructible` and `Destructible`. If
@@ -744,12 +755,12 @@ should be used to ensure that mutex objects are initialized and visible
744
  to other threads.
745
 
746
  The expression `m.lock()` shall be well-formed and have the following
747
  semantics:
748
 
749
- *Requires:* If `m` is of type `std::mutex` or `std::timed_mutex`, the
750
- calling thread does not own the mutex.
751
 
752
  *Effects:* Blocks the calling thread until ownership of the mutex can be
753
  obtained for the calling thread.
754
 
755
  The calling thread owns the mutex.
@@ -772,12 +783,12 @@ required ([[thread.req.exception]]).
772
  blocking is not possible.
773
 
774
  The expression `m.try_lock()` shall be well-formed and have the
775
  following semantics:
776
 
777
- *Requires:* If `m` is of type `std::mutex` or `std::timed_mutex`, the
778
- calling thread does not own the mutex.
779
 
780
  *Effects:* Attempts to obtain ownership of the mutex for the calling
781
  thread without blocking. If ownership is not obtained, there is no
782
  effect and `try_lock()` immediately returns. An implementation may fail
783
  to obtain the lock even if it is not held by any other thread. This
@@ -808,12 +819,12 @@ The calling thread shall own the mutex.
808
 
809
  *Effects:* Releases the calling thread’s ownership of the mutex.
810
 
811
  *Return type:* `void`
812
 
813
- *Synchronization:* This operation *synchronizes
814
- with* ([[intro.multithread]]) subsequent lock operations that obtain
815
  ownership on the same object.
816
 
817
  *Throws:* Nothing.
818
 
819
  ##### Class `mutex` <a id="thread.mutex.class">[[thread.mutex.class]]</a>
@@ -914,26 +925,25 @@ The behavior of a program is undefined if:
914
  - a thread terminates while owning a `recursive_mutex` object.
915
 
916
  #### Timed mutex types <a id="thread.timedmutex.requirements">[[thread.timedmutex.requirements]]</a>
917
 
918
  The *timed mutex types* are the standard library types
919
- `std::timed_mutex` and `std::recursive_timed_mutex`. They shall meet the
920
- requirements set out below. In this description, `m` denotes an object
921
- of a mutex type, `rel_time` denotes an object of an instantiation of
922
- `duration` ([[time.duration]]), and `abs_time` denotes an object of an
923
- instantiation of `time_point` ([[time.point]]).
 
924
 
925
  The timed mutex types shall meet the `TimedLockable` requirements (
926
  [[thread.req.lockable.timed]]).
927
 
928
  The expression `m.try_lock_for(rel_time)` shall be well-formed and have
929
  the following semantics:
930
 
931
- If the tick `period` of `rel_time` is not exactly convertible to the
932
- native tick `period`, the `duration` shall be rounded up to the nearest
933
- native tick `period`. If `m` is of type `std::timed_mutex`, the calling
934
- thread does not own the mutex.
935
 
936
  *Effects:* The function attempts to obtain ownership of the mutex within
937
  the relative timeout ([[thread.req.timing]]) specified by `rel_time`.
938
  If the time specified by `rel_time` is less than or equal to
939
  `rel_time.zero()`, the function attempts to obtain ownership without
@@ -949,17 +959,17 @@ implementations are expected to make a strong effort to do so.
949
 
950
  *Synchronization:* If `try_lock_for()` returns `true`, prior `unlock()`
951
  operations on the same object *synchronize
952
  with* ([[intro.multithread]]) this operation.
953
 
954
- *Throws:* Nothing.
955
 
956
  The expression `m.try_lock_until(abs_time)` shall be well-formed and
957
  have the following semantics:
958
 
959
- *Requires:* If `m` is of type `std::timed_mutex`, the calling thread
960
- does not own the mutex.
961
 
962
  *Effects:* The function attempts to obtain ownership of the mutex. If
963
  `abs_time` has already passed, the function attempts to obtain ownership
964
  without blocking (as if by calling `try_lock()`). The function shall
965
  return before the absolute timeout ([[thread.req.timing]]) specified by
@@ -974,11 +984,11 @@ strong effort to do so.
974
 
975
  *Synchronization:* If `try_lock_until()` returns `true`, prior
976
  `unlock()` operations on the same object *synchronize
977
  with* ([[intro.multithread]]) this operation.
978
 
979
- *Throws:* Nothing.
980
 
981
  ##### Class `timed_mutex` <a id="thread.timedmutex.class">[[thread.timedmutex.class]]</a>
982
 
983
  ``` cpp
984
  namespace std {
@@ -988,11 +998,11 @@ namespace std {
988
  ~timed_mutex();
989
 
990
  timed_mutex(const timed_mutex&) = delete;
991
  timed_mutex& operator=(const timed_mutex&) = delete;
992
 
993
- void lock();
994
  bool try_lock();
995
  template <class Rep, class Period>
996
  bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
997
  template <class Clock, class Duration>
998
  bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
@@ -1034,11 +1044,11 @@ namespace std {
1034
  ~recursive_timed_mutex();
1035
 
1036
  recursive_timed_mutex(const recursive_timed_mutex&) = delete;
1037
  recursive_timed_mutex& operator=(const recursive_timed_mutex&) = delete;
1038
 
1039
- void lock();
1040
  bool try_lock() noexcept;
1041
  template <class Rep, class Period>
1042
  bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
1043
  template <class Clock, class Duration>
1044
  bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
@@ -1078,10 +1088,204 @@ the object be acquired by another thread.
1078
  The behavior of a program is undefined if:
1079
 
1080
  - it destroys a `recursive_timed_mutex` object owned by any thread, or
1081
  - a thread terminates while owning a `recursive_timed_mutex` object.
1082
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1083
  ### Locks <a id="thread.lock">[[thread.lock]]</a>
1084
 
1085
  A *lock* is an object that holds a reference to a lockable object and
1086
  may unlock the lockable object during the lock’s destruction (such as
1087
  when leaving block scope). An execution agent may use a lock to aid in
@@ -1189,11 +1393,11 @@ namespace std {
1189
 
1190
  unique_lock(unique_lock const&) = delete;
1191
  unique_lock& operator=(unique_lock const&) = delete;
1192
 
1193
  unique_lock(unique_lock&& u) noexcept;
1194
- unique_lock& operator=(unique_lock&& u) noexcept;
1195
 
1196
  // [thread.lock.unique.locking], locking:
1197
  void lock();
1198
  bool try_lock();
1199
 
@@ -1333,11 +1537,11 @@ unique_lock(unique_lock&& u) noexcept;
1333
  *Postconditions:* `pm == u_p.pm` and `owns == u_p.owns` (where `u_p` is
1334
  the state of `u` just prior to this construction), `u.pm == 0` and
1335
  `u.owns == false`.
1336
 
1337
  ``` cpp
1338
- unique_lock& operator=(unique_lock&& u) noexcept;
1339
  ```
1340
 
1341
  *Effects:* If `owns` calls `pm->unlock()`.
1342
 
1343
  *Postconditions:* `pm == u_p.pm` and `owns == u_p.owns` (where `u_p` is
@@ -1346,10 +1550,12 @@ the state of `u` just prior to this construction), `u.pm == 0` and
1346
 
1347
  With a recursive mutex it is possible for both `*this` and `u` to own
1348
  the same mutex before the assignment. In this case, `*this` will own the
1349
  mutex after the assignment and `u` will not.
1350
 
 
 
1351
  ``` cpp
1352
  ~unique_lock();
1353
  ```
1354
 
1355
  *Effects:* If `owns` calls `pm->unlock()`.
@@ -1488,10 +1694,319 @@ explicit operator bool() const noexcept;
1488
  mutex_type *mutex() const noexcept;
1489
  ```
1490
 
1491
  *Returns:* `pm`
1492
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1493
  ### Generic locking algorithms <a id="thread.lock.algorithm">[[thread.lock.algorithm]]</a>
1494
 
1495
  ``` cpp
1496
  template <class L1, class L2, class... L3> int try_lock(L1&, L2&, L3&...);
1497
  ```
@@ -1503,11 +2018,11 @@ when suitably instantiated.
1503
  *Effects:* Calls `try_lock()` for each argument in order beginning with
1504
  the first until all arguments have been processed or a call to
1505
  `try_lock()` fails, either by returning `false` or by throwing an
1506
  exception. If a call to `try_lock()` fails, `unlock()` shall be called
1507
  for all prior arguments and there shall be no further calls to
1508
- try_lock().
1509
 
1510
  *Returns:* `-1` if all calls to `try_lock()` returned `true`, otherwise
1511
  a 0-based index value that indicates the argument for which `try_lock()`
1512
  returned `false`.
1513
 
@@ -1582,14 +2097,10 @@ order; and the returning execution synchronizes with the return from all
1582
  passive executions.
1583
 
1584
  *Throws:* `system_error` when an exception is
1585
  required ([[thread.req.exception]]), or any exception thrown by `func`.
1586
 
1587
- *Error conditions:*
1588
-
1589
- - `invalid_argument` — if the `once_flag` object is no longer valid.
1590
-
1591
  ``` cpp
1592
  // global flag, regular function
1593
  void init();
1594
  std::once_flag flag;
1595
 
@@ -1636,13 +2147,14 @@ three atomic parts:
1636
 
1637
  1. the release of the mutex and entry into the waiting state;
1638
  2. the unblocking of the wait; and
1639
  3. the reacquisition of the lock.
1640
 
1641
- The implementation shall behave as if `notify_one`, `notify_all`, and
1642
- each part of the `wait`, `wait_for`, and `wait_until` executions are
1643
- executed in some unspecified total order.
 
1644
 
1645
  Condition variable construction and destruction need not be
1646
  synchronized.
1647
 
1648
  ``` cpp
@@ -1676,14 +2188,13 @@ as if
1676
  ``` cpp
1677
  lk.unlock();
1678
  cond.notify_all();
1679
  ```
1680
 
1681
- *Synchronization:* The call to `notify_all_at_thread_exit` and the
1682
- completion of the destructors for all the current thread’s variables of
1683
- thread storage duration synchronize with ([[intro.multithread]]) calls
1684
- to functions waiting on `cond`.
1685
 
1686
  *Note:* The supplied lock will be held until the thread exits, and care
1687
  must be taken to ensure that this does not cause deadlock due to lock
1688
  ordering issues. After calling `notify_all_at_thread_exit` it is
1689
  recommended that the thread should be exited as soon as possible, and
@@ -1789,32 +2300,29 @@ void wait(unique_lock<mutex>& lock);
1789
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
1790
  thread, and either
1791
 
1792
  - no other thread is waiting on this `condition_variable` object or
1793
  - `lock.mutex()` returns the same value for each of the `lock` arguments
1794
- supplied by all concurrently waiting (via `wait` or `timed_wait`)
1795
- threads.
1796
 
1797
  *Effects:*
1798
 
1799
  - Atomically calls `lock.unlock()` and blocks on `*this`.
1800
  - When unblocked, calls `lock.lock()` (possibly blocking on the lock),
1801
  then returns.
1802
  - The function will unblock when signaled by a call to `notify_one()` or
1803
  a call to `notify_all()`, or spuriously.
1804
- - If the function exits via an exception, `lock.lock()` shall be called
1805
- prior to exiting the function scope.
 
 
1806
 
1807
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
1808
  thread.
1809
 
1810
- *Throws:* `system_error` when an exception is
1811
- required ([[thread.req.exception]]).
1812
-
1813
- *Error conditions:*
1814
-
1815
- - equivalent error condition from `lock.lock()` or `lock.unlock()`.
1816
 
1817
  ``` cpp
1818
  template <class Predicate>
1819
  void wait(unique_lock<mutex>& lock, Predicate pred);
1820
  ```
@@ -1822,29 +2330,29 @@ template <class Predicate>
1822
  *Requires:* `lock.owns_lock()` is `true` and `lock.mutex()` is locked by
1823
  the calling thread, and either
1824
 
1825
  - no other thread is waiting on this `condition_variable` object or
1826
  - `lock.mutex()` returns the same value for each of the `lock` arguments
1827
- supplied by all concurrently waiting (via `wait` or `timed_wait`)
1828
- threads.
1829
 
1830
- *Effects:*
1831
 
1832
  ``` cpp
1833
  while (!pred())
1834
  wait(lock);
1835
  ```
1836
 
 
 
 
 
1837
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
1838
  thread.
1839
 
1840
- *Throws:* `std::system_error` when an exception is
1841
- required ([[thread.req.exception]]).
1842
-
1843
- *Error conditions:*
1844
-
1845
- - equivalent error condition from `lock.lock()` or `lock.unlock()`.
1846
 
1847
  ``` cpp
1848
  template <class Clock, class Duration>
1849
  cv_status wait_until(unique_lock<mutex>& lock,
1850
  const chrono::time_point<Clock, Duration>& abs_time);
@@ -1866,25 +2374,24 @@ thread, and either
1866
  - The function will unblock when signaled by a call to `notify_one()`, a
1867
  call to `notify_all()`, expiration of the absolute
1868
  timeout ([[thread.req.timing]]) specified by `abs_time`, or
1869
  spuriously.
1870
  - If the function exits via an exception, `lock.lock()` shall be called
1871
- prior to exiting the function scope.
 
 
 
 
1872
 
1873
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
1874
  thread.
1875
 
1876
  *Returns:* `cv_status::timeout` if the absolute
1877
  timeout ([[thread.req.timing]]) specified by `abs_time` expired,
1878
  otherwise `cv_status::no_timeout`.
1879
 
1880
- *Throws:* `system_error` when an exception is
1881
- required ([[thread.req.exception]]).
1882
-
1883
- *Error conditions:*
1884
-
1885
- - equivalent error condition from `lock.lock()` or `lock.unlock()`.
1886
 
1887
  ``` cpp
1888
  template <class Rep, class Period>
1889
  cv_status wait_for(unique_lock<mutex>& lock,
1890
  const chrono::duration<Rep, Period>& rel_time);
@@ -1896,29 +2403,28 @@ thread, and either
1896
  - no other thread is waiting on this `condition_variable` object or
1897
  - `lock.mutex()` returns the same value for each of the `lock` arguments
1898
  supplied by all concurrently waiting (via `wait`, `wait_for`, or
1899
  `wait_until`) threads.
1900
 
1901
- *Effects:* as if
1902
 
1903
  ``` cpp
1904
  return wait_until(lock, chrono::steady_clock::now() + rel_time);
1905
  ```
1906
 
1907
  *Returns:* `cv_status::timeout` if the relative
1908
  timeout ([[thread.req.timing]]) specified by `rel_time` expired,
1909
  otherwise `cv_status::no_timeout`.
1910
 
 
 
 
 
1911
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
1912
  thread.
1913
 
1914
- *Throws:* `system_error` when an exception is
1915
- required ([[thread.req.exception]]).
1916
-
1917
- *Error conditions:*
1918
-
1919
- - equivalent error condition from `lock.lock()` or `lock.unlock()`.
1920
 
1921
  ``` cpp
1922
  template <class Clock, class Duration, class Predicate>
1923
  bool wait_until(unique_lock<mutex>& lock,
1924
  const chrono::time_point<Clock, Duration>& abs_time,
@@ -1928,36 +2434,34 @@ template <class Clock, class Duration, class Predicate>
1928
  *Requires:* `lock.owns_lock()` is `true` and `lock.mutex()` is locked by
1929
  the calling thread, and either
1930
 
1931
  - no other thread is waiting on this `condition_variable` object or
1932
  - `lock.mutex()` returns the same value for each of the `lock` arguments
1933
- supplied by all concurrently waiting (via `wait` or `timed_wait`)
1934
- threads.
1935
 
1936
- *Effects:*
1937
 
1938
  ``` cpp
1939
  while (!pred())
1940
  if (wait_until(lock, abs_time) == cv_status::timeout)
1941
  return pred();
1942
  return true;
1943
  ```
1944
 
1945
- *Returns:* `pred()`
 
 
1946
 
1947
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
1948
  thread.
1949
 
1950
  The returned value indicates whether the predicate evaluated to `true`
1951
  regardless of whether the timeout was triggered.
1952
 
1953
- *Throws:* `std::system_error` when an exception is
1954
- required ([[thread.req.exception]]).
1955
-
1956
- *Error conditions:*
1957
-
1958
- - equivalent error condition from `lock.lock()` or `lock.unlock()`.
1959
 
1960
  ``` cpp
1961
  template <class Rep, class Period, class Predicate>
1962
  bool wait_for(unique_lock<mutex>& lock,
1963
  const chrono::duration<Rep, Period>& rel_time,
@@ -1970,33 +2474,31 @@ thread, and either
1970
  - no other thread is waiting on this `condition_variable` object or
1971
  - `lock.mutex()` returns the same value for each of the `lock` arguments
1972
  supplied by all concurrently waiting (via `wait`, `wait_for`, or
1973
  `wait_until`) threads.
1974
 
1975
- *Effects:* as if
1976
 
1977
  ``` cpp
1978
  return wait_until(lock, chrono::steady_clock::now() + rel_time, std::move(pred));
1979
  ```
1980
 
1981
  There is no blocking if `pred()` is initially `true`, even if the
1982
  timeout has already expired.
1983
 
 
 
 
 
1984
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
1985
  thread.
1986
 
1987
- *Returns:* `pred()`
1988
-
1989
  The returned value indicates whether the predicate evaluates to `true`
1990
  regardless of whether the timeout was triggered.
1991
 
1992
- *Throws:* `system_error` when an exception is
1993
- required ([[thread.req.exception]]).
1994
-
1995
- *Error conditions:*
1996
-
1997
- - equivalent error condition from `lock.lock()` or `lock.unlock()`.
1998
 
1999
  ### Class `condition_variable_any` <a id="thread.condition.condvarany">[[thread.condition.condvarany]]</a>
2000
 
2001
  A `Lock` type shall meet the `BasicLockable` requirements (
2002
  [[thread.req.lockable.basic]]). All of the standard mutex types meet
@@ -2046,12 +2548,12 @@ condition_variable_any();
2046
  *Throws:* `bad_alloc` or `system_error` when an exception is
2047
  required ([[thread.req.exception]]).
2048
 
2049
  *Error conditions:*
2050
 
2051
- - `resource_unavailable_try_again` — if any native handle type
2052
- manipulated is not available.
2053
  - `operation_not_permitted` — if the thread does not have the privilege
2054
  to perform the operation.
2055
 
2056
  ``` cpp
2057
  ~condition_variable_any();
@@ -2096,28 +2598,25 @@ allows to query that, such as the `unique_lock` wrapper.
2096
  - Atomically calls `lock.unlock()` and blocks on `*this`.
2097
  - When unblocked, calls `lock.lock()` (possibly blocking on the lock)
2098
  and returns.
2099
  - The function will unblock when signaled by a call to `notify_one()`, a
2100
  call to `notify_all()`, or spuriously.
2101
- - If the function exits via an exception, `lock.lock()` shall be called
2102
- prior to exiting the function scope.
 
 
2103
 
2104
  `lock` is locked by the calling thread.
2105
 
2106
- *Throws:* `system_error` when an exception is
2107
- required ([[thread.req.exception]]).
2108
-
2109
- *Error conditions:*
2110
-
2111
- - equivalent error condition from `lock.lock()` or `lock.unlock()`.
2112
 
2113
  ``` cpp
2114
  template <class Lock, class Predicate>
2115
  void wait(Lock& lock, Predicate pred);
2116
  ```
2117
 
2118
- *Effects:*
2119
 
2120
  ``` cpp
2121
  while (!pred())
2122
  wait(lock);
2123
  ```
@@ -2135,96 +2634,78 @@ template <class Lock, class Clock, class Duration>
2135
  - The function will unblock when signaled by a call to `notify_one()`, a
2136
  call to `notify_all()`, expiration of the absolute
2137
  timeout ([[thread.req.timing]]) specified by `abs_time`, or
2138
  spuriously.
2139
  - If the function exits via an exception, `lock.lock()` shall be called
2140
- prior to exiting the function scope.
 
 
 
 
2141
 
2142
  `lock` is locked by the calling thread.
2143
 
2144
  *Returns:* `cv_status::timeout` if the absolute
2145
  timeout ([[thread.req.timing]]) specified by `abs_time` expired,
2146
  otherwise `cv_status::no_timeout`.
2147
 
2148
- *Throws:* `system_error` when an exception is
2149
- required ([[thread.req.exception]]).
2150
-
2151
- *Error conditions:*
2152
-
2153
- - equivalent error condition from `lock.lock()` or `lock.unlock()`.
2154
 
2155
  ``` cpp
2156
  template <class Lock, class Rep, class Period>
2157
  cv_status wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time);
2158
  ```
2159
 
2160
- *Effects:* as if
2161
 
2162
  ``` cpp
2163
  return wait_until(lock, chrono::steady_clock::now() + rel_time);
2164
  ```
2165
 
2166
  *Returns:* `cv_status::timeout` if the relative
2167
  timeout ([[thread.req.timing]]) specified by `rel_time` expired,
2168
  otherwise `cv_status::no_timeout`.
2169
 
 
 
 
 
2170
  `lock` is locked by the calling thread.
2171
 
2172
- *Throws:* `system_error` when an exception is
2173
- required ([[thread.req.exception]]).
2174
-
2175
- *Error conditions:*
2176
-
2177
- - equivalent error condition from `lock.lock()` or `lock.unlock()`.
2178
 
2179
  ``` cpp
2180
  template <class Lock, class Clock, class Duration, class Predicate>
2181
  bool wait_until(Lock& lock, const chrono::time_point<Clock, Duration>& abs_time, Predicate pred);
2182
  ```
2183
 
2184
- *Effects:*
2185
 
2186
  ``` cpp
2187
  while (!pred())
2188
  if (wait_until(lock, abs_time) == cv_status::timeout)
2189
  return pred();
2190
  return true;
2191
  ```
2192
 
2193
- *Returns:* `pred()`
 
2194
 
2195
  The returned value indicates whether the predicate evaluates to `true`
2196
  regardless of whether the timeout was triggered.
2197
 
2198
  ``` cpp
2199
  template <class Lock, class Rep, class Period, class Predicate>
2200
  bool wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time, Predicate pred);
2201
  ```
2202
 
2203
- *Effects:* as if
2204
 
2205
  ``` cpp
2206
  return wait_until(lock, chrono::steady_clock::now() + rel_time, std::move(pred));
2207
  ```
2208
 
2209
- There is no blocking if `pred()` is initially `true`, even if the
2210
- timeout has already expired.
2211
-
2212
- `lock` is locked by the calling thread.
2213
-
2214
- *Returns:* `pred()`
2215
-
2216
- The returned value indicates whether the predicate evaluates to `true`
2217
- regardless of whether the timeout was triggered.
2218
-
2219
- *Throws:* `system_error` when an exception is
2220
- required ([[thread.req.exception]]).
2221
-
2222
- *Error conditions:*
2223
-
2224
- - equivalent error condition from `lock.lock()` or `lock.unlock()`.
2225
-
2226
  ## Futures <a id="futures">[[futures]]</a>
2227
 
2228
  ### Overview <a id="futures.overview">[[futures.overview]]</a>
2229
 
2230
  [[futures]] describes components that a C++program can use to retrieve
@@ -2234,20 +2715,20 @@ restricted to multi-threaded programs but can be useful in
2234
  single-threaded programs as well.
2235
 
2236
  ``` cpp
2237
  namespace std {
2238
  enum class future_errc {
2239
- broken_promise,
2240
- future_already_retrieved,
2241
- promise_already_satisfied,
2242
- no_state
2243
  };
2244
 
2245
  enum class launch : unspecified{} {
2246
  async = unspecified{},
2247
  deferred = unspecified{},
2248
- implementation-defined{}
2249
  };
2250
 
2251
  enum class future_status {
2252
  ready,
2253
  timeout,
@@ -2282,33 +2763,34 @@ namespace std {
2282
 
2283
  template <class> class packaged_task; // undefined
2284
  template <class R, class... ArgTypes>
2285
  class packaged_task<R(ArgTypes...)>;
2286
 
2287
- template <class R>
2288
  void swap(packaged_task<R(ArgTypes...)>&, packaged_task<R(ArgTypes...)>&) noexcept;
2289
 
2290
  template <class R, class Alloc>
2291
  struct uses_allocator<packaged_task<R>, Alloc>;
2292
 
2293
  template <class F, class... Args>
2294
- future<typename result_of<F(Args...)>::type>
2295
  async(F&& f, Args&&... args);
2296
  template <class F, class... Args>
2297
- future<typename result_of<F(Args...)>::type>
2298
  async(launch policy, F&& f, Args&&... args);
2299
  }
2300
  ```
2301
 
2302
- The `enum` type `launch` is an *implementation-defined* bitmask type (
2303
- [[bitmask.types]]) with `launch::async` and `launch::deferred` denoting
2304
- individual bits. Implementations can provide bitmasks to specify
2305
- restrictions on task interaction by functions launched by `async()`
2306
- applicable to a corresponding subset of available launch policies.
2307
- Implementations can extend the behavior of the first overload of
2308
- `async()` by adding their extensions to the launch policy under the “as
2309
- if” rule.
 
2310
 
2311
  ### Error handling <a id="futures.errors">[[futures.errors]]</a>
2312
 
2313
  ``` cpp
2314
  const error_category& future_category() noexcept;
@@ -2369,11 +2851,11 @@ a (possibly void) value or an exception. Futures, promises, and tasks
2369
  defined in this clause reference such shared state.
2370
 
2371
  The result can be any kind of object including a function to compute
2372
  that result, as used by `async` when `policy` is `launch::deferred`.
2373
 
2374
- An *asynchronous return object* is an object that reads results from an
2375
  shared state. A *waiting function* of an asynchronous return object is
2376
  one that potentially blocks to wait for the shared state to be made
2377
  ready. If a waiting function can return before the state is made ready
2378
  because of a timeout ([[thread.req.lockable]]), then it is a *timed
2379
  waiting function*, otherwise it is a *non-timed waiting function*.
@@ -2389,11 +2871,15 @@ When an asynchronous return object or an asynchronous provider is said
2389
  to release its shared state, it means:
2390
 
2391
  - if the return object or provider holds the last reference to its
2392
  shared state, the shared state is destroyed; and
2393
  - the return object or provider gives up its reference to its shared
2394
- state.
 
 
 
 
2395
 
2396
  When an asynchronous provider is said to make its shared state ready, it
2397
  means:
2398
 
2399
  - first, the provider marks its shared state as ready; and
@@ -2563,14 +3049,14 @@ that state ready ([[futures.state]]).
2563
 
2564
  *Throws:*
2565
 
2566
  - `future_error` if its shared state already has a stored value or
2567
  exception, or
2568
- - for the first version, any exception thrown by the copy constructor of
2569
- `R`, or
2570
- - for the second version, any exception thrown by the move constructor
2571
- of `R`.
2572
 
2573
  *Error conditions:*
2574
 
2575
  - `promise_already_satisfied` if its shared state already has a stored
2576
  value or exception.
@@ -2602,20 +3088,27 @@ void promise<void>::set_value_at_thread_exit();
2602
  *Effects:* Stores the value `r` in the shared state without making that
2603
  state ready immediately. Schedules that state to be made ready when the
2604
  current thread exits, after all objects of thread storage duration
2605
  associated with the current thread have been destroyed.
2606
 
2607
- *Throws:* `future_error` if an error condition occurs.
 
 
 
 
 
 
 
2608
 
2609
  *Error conditions:*
2610
 
2611
  - `promise_already_satisfied` if its shared state already has a stored
2612
  value or exception.
2613
  - `no_state` if `*this` has no shared state.
2614
 
2615
  ``` cpp
2616
- void promise::set_exception_at_thread_exit(exception_ptr p);
2617
  ```
2618
 
2619
  *Effects:* Stores the exception pointer `p` in the shared state without
2620
  making that state ready immediately. Schedules that state to be made
2621
  ready when the current thread exits, after all objects of thread storage
@@ -2693,11 +3186,11 @@ out in its description, below.
2693
  ``` cpp
2694
  future() noexcept;
2695
  ```
2696
 
2697
  *Effects:* constructs an *empty* `future` object that does not refer to
2698
- an shared state.
2699
 
2700
  `valid() == false`.
2701
 
2702
  ``` cpp
2703
  future(future&& rhs) noexcept;
@@ -2757,13 +3250,12 @@ member function `get`.
2757
  *Effects:* `wait()`s until the shared state is ready, then retrieves the
2758
  value stored in the shared state.
2759
 
2760
  *Returns:*
2761
 
2762
- - `future::get()` returns the value stored in the object’s shared state.
2763
- If the type of the value is `MoveAssignable` the returned value is
2764
- moved, otherwise it is copied.
2765
  - `future<R&>::get()` returns the reference stored as value in the
2766
  object’s shared state.
2767
  - `future<void>::get()` returns nothing.
2768
 
2769
  *Throws:* the stored exception, if an exception was stored in the shared
@@ -2800,10 +3292,12 @@ specified by `rel_time` has expired.
2800
  - `future_status::ready` if the shared state is ready.
2801
  - `future_status::timeout` if the function is returning because the
2802
  relative timeout ([[thread.req.timing]]) specified by `rel_time` has
2803
  expired.
2804
 
 
 
2805
  ``` cpp
2806
  template <class Clock, class Duration>
2807
  future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
2808
  ```
2809
 
@@ -2819,10 +3313,12 @@ specified by `abs_time` has expired.
2819
  - `future_status::ready` if the shared state is ready.
2820
  - `future_status::timeout` if the function is returning because the
2821
  absolute timeout ([[thread.req.timing]]) specified by `abs_time` has
2822
  expired.
2823
 
 
 
2824
  ### Class template `shared_future` <a id="futures.shared_future">[[futures.shared_future]]</a>
2825
 
2826
  The class template `shared_future` defines a type for asynchronous
2827
  return objects which may share their shared state with other
2828
  asynchronous return objects. A default-constructed `shared_future`
@@ -2879,11 +3375,11 @@ differ only in the return type and return value of the member function
2879
  ``` cpp
2880
  shared_future() noexcept;
2881
  ```
2882
 
2883
  *Effects:* constructs an *empty* `shared_future` object that does not
2884
- refer to an shared state.
2885
 
2886
  `valid() == false`.
2887
 
2888
  ``` cpp
2889
  shared_future(const shared_future& rhs);
@@ -3004,10 +3500,12 @@ specified by `rel_time` has expired.
3004
  - `future_status::ready` if the shared state is ready.
3005
  - `future_status::timeout` if the function is returning because the
3006
  relative timeout ([[thread.req.timing]]) specified by `rel_time` has
3007
  expired.
3008
 
 
 
3009
  ``` cpp
3010
  template <class Clock, class Duration>
3011
  future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
3012
  ```
3013
 
@@ -3023,23 +3521,23 @@ specified by `abs_time` has expired.
3023
  - `future_status::ready` if the shared state is ready.
3024
  - `future_status::timeout` if the function is returning because the
3025
  absolute timeout ([[thread.req.timing]]) specified by `abs_time` has
3026
  expired.
3027
 
 
 
3028
  ### Function template `async` <a id="futures.async">[[futures.async]]</a>
3029
 
3030
  The function template `async` provides a mechanism to launch a function
3031
  potentially in a new thread and provides the result of the function in a
3032
  `future` object with which it shares a shared state.
3033
 
3034
  ``` cpp
3035
  template <class F, class... Args>
3036
- future<typename result_of<F(Args...)>::type>
3037
- async(F&& f, Args&&... args);
3038
  template <class F, class... Args>
3039
- future<typename result_of<F(Args...)>::type>
3040
- async(launch policy, F&& f, Args&&... args);
3041
  ```
3042
 
3043
  *Requires:* `F` and each `Ti` in `Args` shall satisfy the
3044
  `MoveConstructible` requirements.
3045
  *`INVOKE`*`(`*`DECAY_COPY`*`(std::forward<F>(f)), `*`DECAY_COPY`*`(std::forward<Args>(args))...)`
@@ -3068,28 +3566,37 @@ implementation may choose any of the corresponding policies):
3068
  asynchronous return objects that reference that state.
3069
  - if `policy & launch::deferred` is non-zero — Stores
3070
  *`DECAY_COPY`*`(std::forward<F>(f))` and
3071
  *`DECAY_COPY`*`(std::forward<Args>(args))...` in the shared state.
3072
  These copies of `f` and `args` constitute a *deferred function*.
3073
- Invocation of the deferred function evaluates *`INVOKE`*`(g, xyz)`
3074
- where `g` is the stored value of *`DECAY_COPY`*`(std::forward<F>(f))`
3075
- and `xyz` is the stored copy of
3076
- *`DECAY_COPY`*`(std::forward<Args>(args))...`. The shared state is not
 
 
 
3077
  made ready until the function has completed. The first call to a
3078
  non-timed waiting function ([[futures.state]]) on an asynchronous
3079
  return object referring to this shared state shall invoke the deferred
3080
  function in the thread that called the waiting function. Once
3081
- evaluation of *`INVOKE`*`(g, xyz)` begins, the function is no longer
3082
- considered deferred. If this policy is specified together with other
3083
- policies, such as when using a `policy` value of
3084
  `launch::async | launch::deferred`, implementations should defer
3085
  invocation or the selection of the policy when no more concurrency can
3086
  be effectively exploited.
 
 
 
3087
 
3088
  *Returns:* An object of type
3089
- `future<typename result_of<F(Args...)>::type>` that refers to the shared
3090
- state created by this call to `async`.
 
 
 
3091
 
3092
  *Synchronization:* Regardless of the provided `policy` argument,
3093
 
3094
  - the invocation of `async` synchronizes with ([[intro.multithread]])
3095
  the invocation of `f`. This statement applies even when the
@@ -3100,29 +3607,26 @@ state created by this call to `async`.
3100
 
3101
  If the implementation chooses the `launch::async` policy,
3102
 
3103
  - a call to a waiting function on an asynchronous return object that
3104
  shares the shared state created by this `async` call shall block until
3105
- the associated thread has completed, as if
3106
- joined ([[thread.thread.member]]);
3107
  - the associated thread completion synchronizes
3108
  with ([[intro.multithread]]) the return from the first function that
3109
  successfully detects the ready status of the shared state or with the
3110
  return from the last function that releases the shared state,
3111
  whichever happens first.
3112
 
3113
- *Throws:* `system_error` if `policy` is `launch::async` and the
3114
  implementation is unable to start a new thread.
3115
 
3116
  *Error conditions:*
3117
 
3118
- - `resource_unavailable_try_again` — if `policy` is `launch::async` and
3119
  the system is unable to start a new thread.
3120
 
3121
- *Remarks:* The first signature shall not participate in overload
3122
- resolution if `decay<F>::type` is `std::launch`.
3123
-
3124
  ``` cpp
3125
  int work1(int value);
3126
  int work2(int value);
3127
  int work(int value) {
3128
  auto handle = std::async([=]{ return work2(value); });
@@ -3162,12 +3666,12 @@ namespace std {
3162
  template <class F, class Allocator>
3163
  explicit packaged_task(allocator_arg_t, const Allocator& a, F&& f);
3164
  ~packaged_task();
3165
 
3166
  // no copy
3167
- packaged_task(packaged_task&) = delete;
3168
- packaged_task& operator=(packaged_task&) = delete;
3169
 
3170
  // move support
3171
  packaged_task(packaged_task&& rhs) noexcept;
3172
  packaged_task& operator=(packaged_task&& rhs) noexcept;
3173
  void swap(packaged_task& other) noexcept;
@@ -3209,10 +3713,14 @@ template <class F, class Allocator>
3209
  *Requires:* *`INVOKE`*`(f, t1, t2, ..., tN, R)`, where `t1, t2, ..., tN`
3210
  are values of the corresponding types in `ArgTypes...`, shall be a valid
3211
  expression. Invoking a copy of `f` shall behave the same as invoking
3212
  `f`.
3213
 
 
 
 
 
3214
  *Effects:* constructs a new `packaged_task` object with a shared state
3215
  and initializes the object’s stored task with `std::forward<F>(f)`. The
3216
  constructors that take an `Allocator` argument use it to allocate memory
3217
  needed to store the internal data structures.
3218
 
@@ -3296,20 +3804,10 @@ or the stored task has already been invoked.
3296
 
3297
  - `promise_already_satisfied` if the stored task has already been
3298
  invoked.
3299
  - `no_state` if `*this` has no shared state.
3300
 
3301
- *Synchronization:* a successful call to `operator()` synchronizes
3302
- with ([[intro.multithread]]) a call to any member function of a
3303
- `future` or `shared_future` object that shares the shared state of
3304
- `*this`. The completion of the invocation of the stored task and the
3305
- storage of the result (whether normal or exceptional) into the shared
3306
- state synchronizes with ([[intro.multithread]]) the successful return
3307
- from any member function that detects that the state is set to ready.
3308
- `operator()` synchronizes and serializes with other functions through
3309
- the shared state.
3310
-
3311
  ``` cpp
3312
  void make_ready_at_thread_exit(ArgTypes... args);
3313
  ```
3314
 
3315
  *Effects:* *`INVOKE`*`(f, t1, t2, ..., tN, R)`, where `f` is the stored
@@ -3369,10 +3867,11 @@ template <class R, class Alloc>
3369
  [atomics]: atomics.md#atomics
3370
  [basic.life]: basic.md#basic.life
3371
  [basic.stc.thread]: basic.md#basic.stc.thread
3372
  [bitmask.types]: library.md#bitmask.types
3373
  [class]: class.md#class
 
3374
  [func.require]: utilities.md#func.require
3375
  [futures]: #futures
3376
  [futures.async]: #futures.async
3377
  [futures.errors]: #futures.errors
3378
  [futures.future_error]: #futures.future_error
@@ -3397,10 +3896,15 @@ template <class R, class Alloc>
3397
  [thread.decaycopy]: #thread.decaycopy
3398
  [thread.general]: #thread.general
3399
  [thread.lock]: #thread.lock
3400
  [thread.lock.algorithm]: #thread.lock.algorithm
3401
  [thread.lock.guard]: #thread.lock.guard
 
 
 
 
 
3402
  [thread.lock.unique]: #thread.lock.unique
3403
  [thread.lock.unique.cons]: #thread.lock.unique.cons
3404
  [thread.lock.unique.locking]: #thread.lock.unique.locking
3405
  [thread.lock.unique.mod]: #thread.lock.unique.mod
3406
  [thread.lock.unique.obs]: #thread.lock.unique.obs
@@ -3421,10 +3925,12 @@ template <class R, class Alloc>
3421
  [thread.req.lockable.req]: #thread.req.lockable.req
3422
  [thread.req.lockable.timed]: #thread.req.lockable.timed
3423
  [thread.req.native]: #thread.req.native
3424
  [thread.req.paramname]: #thread.req.paramname
3425
  [thread.req.timing]: #thread.req.timing
 
 
3426
  [thread.thread.algorithm]: #thread.thread.algorithm
3427
  [thread.thread.assign]: #thread.thread.assign
3428
  [thread.thread.class]: #thread.thread.class
3429
  [thread.thread.constr]: #thread.thread.constr
3430
  [thread.thread.destr]: #thread.thread.destr
 
12
  | Subclause | | Header |
13
  | -------------------- | ------------------- | ---------------------- |
14
  | [[thread.req]] | Requirements | |
15
  | [[thread.threads]] | Threads | `<thread>` |
16
  | [[thread.mutex]] | Mutual exclusion | `<mutex>` |
17
+ | | | `<shared_mutex>` |
18
  | [[thread.condition]] | Condition variables | `<condition_variable>` |
19
  | [[futures]] | Futures | `<future>` |
20
 
21
 
22
  ## Requirements <a id="thread.req">[[thread.req]]</a>
23
 
24
  ### Template parameter names <a id="thread.req.paramname">[[thread.req.paramname]]</a>
25
 
26
  Throughout this Clause, the names of template parameters are used to
27
+ express type requirements. If a template parameter is named `Predicate`,
28
+ `operator()` applied to the template argument shall return a value that
29
+ is convertible to `bool`.
 
30
 
31
  ### Exceptions <a id="thread.req.exception">[[thread.req.exception]]</a>
32
 
33
  Some functions described in this Clause are specified to throw
34
  exceptions of type `system_error` ([[syserr.syserr]]). Such exceptions
 
117
  implementation is called the *native resolution*.
118
 
119
  Implementation-provided clocks that are used for these functions shall
120
  meet the `TrivialClock` requirements ([[time.clock.req]]).
121
 
122
+ A function that takes an argument which specifies a timeout will throw
123
+ if, during its execution, a clock, time point, or time duration throws
124
+ an exception. Such exceptions are referred to as *timeout-related
125
+ exceptions*. instantiations of clock, time point and duration types
126
+ supplied by the implementation as specified in  [[time.clock]] do not
127
+ throw exceptions.
128
+
129
  ### Requirements for Lockable types <a id="thread.req.lockable">[[thread.req.lockable]]</a>
130
 
131
  #### In general <a id="thread.req.lockable.general">[[thread.req.lockable.general]]</a>
132
 
133
  An *execution agent* is an entity such as a thread that may perform work
 
237
  In several places in this Clause the operation *DECAY_COPY(x)* is used.
238
  All such uses mean call the function `decay_copy(x)` and use the result,
239
  where `decay_copy` is defined as follows:
240
 
241
  ``` cpp
242
+ template <class T> decay_t<T> decay_copy(T&& v)
243
  { return std::forward<T>(v); }
244
  ```
245
 
246
  ## Threads <a id="thread.threads">[[thread.threads]]</a>
247
 
 
417
 
418
  ``` cpp
419
  template <> struct hash<thread::id>;
420
  ```
421
 
422
+ The template specialization shall meet the requirements of class
423
+ template `hash` ([[unord.hash]]).
424
 
425
  #### `thread` constructors <a id="thread.thread.constr">[[thread.thread.constr]]</a>
426
 
427
  ``` cpp
428
  thread() noexcept;
 
440
  *Requires:*  `F` and each `Ti` in `Args` shall satisfy the
441
  `MoveConstructible` requirements. *`INVOKE`*`(`*`DECAY_COPY`*`(`
442
  `std::forward<F>(f)), `*`DECAY_COPY`*`(std::forward<Args>(args))...)` ([[func.require]])
443
  shall be a valid expression.
444
 
445
+ *Remarks:* This constructor shall not participate in overload resolution
446
+ if `decay_t<F>` is the same type as `std::thread`.
447
+
448
  *Effects:*  Constructs an object of type `thread`. The new thread of
449
  execution executes
450
  *`INVOKE`*`(`*`DECAY_COPY`*`(` `std::forward<F>(f)), `*`DECAY_COPY`*`(std::forward<Args>(args))...)`
451
  with the calls to *`DECAY_COPY`* being evaluated in the constructing
452
  thread. Any return value from this invocation is ignored. This implies
 
637
  *Effects:* Blocks the calling thread for the absolute
638
  timeout ([[thread.req.timing]]) specified by `abs_time`.
639
 
640
  *Synchronization:* None.
641
 
642
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
 
 
 
 
643
 
644
  ``` cpp
645
  template <class Rep, class Period>
646
  void sleep_for(const chrono::duration<Rep, Period>& rel_time);
647
  ```
 
649
  *Effects:* Blocks the calling thread for the relative
650
  timeout ([[thread.req.timing]]) specified by `rel_time`.
651
 
652
  *Synchronization:* None.
653
 
654
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
 
 
655
 
656
  ## Mutual exclusion <a id="thread.mutex">[[thread.mutex]]</a>
657
 
658
  This section provides mechanisms for mutual exclusion: mutexes, locks,
659
  and call once. These mechanisms ease the production of race-free
 
689
  once_flag(const once_flag&) = delete;
690
  once_flag& operator=(const once_flag&) = delete;
691
  };
692
 
693
  template<class Callable, class ...Args>
694
+ void call_once(once_flag& flag, Callable&& func, Args&&... args);
695
+ }
696
+ ```
697
+
698
+ ``` cpp
699
+ namespace std {
700
+ class shared_timed_mutex;
701
+ template <class Mutex> class shared_lock;
702
+ template <class Mutex>
703
+ void swap(shared_lock<Mutex>& x, shared_lock<Mutex>& y) noexcept;
704
  }
705
  ```
706
 
707
  ### Mutex requirements <a id="thread.mutex.requirements">[[thread.mutex.requirements]]</a>
708
 
 
711
  A mutex object facilitates protection against data races and allows safe
712
  synchronization of data between execution agents (
713
  [[thread.req.lockable]]). An execution agent *owns* a mutex from the
714
  time it successfully calls one of the lock functions until it calls
715
  unlock. Mutexes can be either recursive or non-recursive, and can grant
716
+ simultaneous ownership to one or many execution agents. Both recursive
717
+ and non-recursive mutexes are supplied.
 
 
718
 
719
  #### Mutex types <a id="thread.mutex.requirements.mutex">[[thread.mutex.requirements.mutex]]</a>
720
 
721
  The *mutex types* are the standard library types `std::mutex`,
722
+ `std::recursive_mutex`, `std::timed_mutex`,
723
+ `std::recursive_timed_mutex`, and `std::shared_timed_mutex`. They shall
724
+ meet the requirements set out in this section. In this description, `m`
725
+ denotes an object of a mutex type.
726
 
727
  The mutex types shall meet the `Lockable` requirements (
728
  [[thread.req.lockable.req]]).
729
 
730
  The mutex types shall be `DefaultConstructible` and `Destructible`. If
 
755
  to other threads.
756
 
757
  The expression `m.lock()` shall be well-formed and have the following
758
  semantics:
759
 
760
+ *Requires:* If `m` is of type `std::mutex`, `std::timed_mutex`, or
761
+ `std::shared_timed_mutex`, the calling thread does not own the mutex.
762
 
763
  *Effects:* Blocks the calling thread until ownership of the mutex can be
764
  obtained for the calling thread.
765
 
766
  The calling thread owns the mutex.
 
783
  blocking is not possible.
784
 
785
  The expression `m.try_lock()` shall be well-formed and have the
786
  following semantics:
787
 
788
+ *Requires:* If `m` is of type `std::mutex`, `std::timed_mutex`, or
789
+ `std::shared_timed_mutex`, the calling thread does not own the mutex.
790
 
791
  *Effects:* Attempts to obtain ownership of the mutex for the calling
792
  thread without blocking. If ownership is not obtained, there is no
793
  effect and `try_lock()` immediately returns. An implementation may fail
794
  to obtain the lock even if it is not held by any other thread. This
 
819
 
820
  *Effects:* Releases the calling thread’s ownership of the mutex.
821
 
822
  *Return type:* `void`
823
 
824
+ *Synchronization:* This operation synchronizes
825
+ with ([[intro.multithread]]) subsequent lock operations that obtain
826
  ownership on the same object.
827
 
828
  *Throws:* Nothing.
829
 
830
  ##### Class `mutex` <a id="thread.mutex.class">[[thread.mutex.class]]</a>
 
925
  - a thread terminates while owning a `recursive_mutex` object.
926
 
927
  #### Timed mutex types <a id="thread.timedmutex.requirements">[[thread.timedmutex.requirements]]</a>
928
 
929
  The *timed mutex types* are the standard library types
930
+ `std::timed_mutex`, `std::recursive_timed_mutex`, and
931
+ `std::shared_timed_mutex`. They shall meet the requirements set out
932
+ below. In this description, `m` denotes an object of a mutex type,
933
+ `rel_time` denotes an object of an instantiation of `duration` (
934
+ [[time.duration]]), and `abs_time` denotes an object of an instantiation
935
+ of `time_point` ([[time.point]]).
936
 
937
  The timed mutex types shall meet the `TimedLockable` requirements (
938
  [[thread.req.lockable.timed]]).
939
 
940
  The expression `m.try_lock_for(rel_time)` shall be well-formed and have
941
  the following semantics:
942
 
943
+ If `m` is of type `std::timed_mutex` or `std::shared_timed_mutex`, the
944
+ calling thread does not own the mutex.
 
 
945
 
946
  *Effects:* The function attempts to obtain ownership of the mutex within
947
  the relative timeout ([[thread.req.timing]]) specified by `rel_time`.
948
  If the time specified by `rel_time` is less than or equal to
949
  `rel_time.zero()`, the function attempts to obtain ownership without
 
959
 
960
  *Synchronization:* If `try_lock_for()` returns `true`, prior `unlock()`
961
  operations on the same object *synchronize
962
  with* ([[intro.multithread]]) this operation.
963
 
964
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
965
 
966
  The expression `m.try_lock_until(abs_time)` shall be well-formed and
967
  have the following semantics:
968
 
969
+ *Requires:* If `m` is of type `std::timed_mutex` or
970
+ `std::shared_timed_mutex`, the calling thread does not own the mutex.
971
 
972
  *Effects:* The function attempts to obtain ownership of the mutex. If
973
  `abs_time` has already passed, the function attempts to obtain ownership
974
  without blocking (as if by calling `try_lock()`). The function shall
975
  return before the absolute timeout ([[thread.req.timing]]) specified by
 
984
 
985
  *Synchronization:* If `try_lock_until()` returns `true`, prior
986
  `unlock()` operations on the same object *synchronize
987
  with* ([[intro.multithread]]) this operation.
988
 
989
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
990
 
991
  ##### Class `timed_mutex` <a id="thread.timedmutex.class">[[thread.timedmutex.class]]</a>
992
 
993
  ``` cpp
994
  namespace std {
 
998
  ~timed_mutex();
999
 
1000
  timed_mutex(const timed_mutex&) = delete;
1001
  timed_mutex& operator=(const timed_mutex&) = delete;
1002
 
1003
+ void lock(); // blocking
1004
  bool try_lock();
1005
  template <class Rep, class Period>
1006
  bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
1007
  template <class Clock, class Duration>
1008
  bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
 
1044
  ~recursive_timed_mutex();
1045
 
1046
  recursive_timed_mutex(const recursive_timed_mutex&) = delete;
1047
  recursive_timed_mutex& operator=(const recursive_timed_mutex&) = delete;
1048
 
1049
+ void lock(); // blocking
1050
  bool try_lock() noexcept;
1051
  template <class Rep, class Period>
1052
  bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
1053
  template <class Clock, class Duration>
1054
  bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
 
1088
  The behavior of a program is undefined if:
1089
 
1090
  - it destroys a `recursive_timed_mutex` object owned by any thread, or
1091
  - a thread terminates while owning a `recursive_timed_mutex` object.
1092
 
1093
+ #### Shared timed mutex types <a id="thread.sharedtimedmutex.requirements">[[thread.sharedtimedmutex.requirements]]</a>
1094
+
1095
+ The standard library type `std::shared_timed_mutex` is a *shared timed
1096
+ mutex type*. Shared timed mutex types shall meet the requirements of
1097
+ timed mutex types ([[thread.timedmutex.requirements]]), and
1098
+ additionally shall meet the requirements set out below. In this
1099
+ description, `m` denotes an object of a mutex type, `rel_type` denotes
1100
+ an object of an instantiation of `duration` ([[time.duration]]), and
1101
+ `abs_time` denotes an object of an instantiation of `time_point` (
1102
+ [[time.point]]).
1103
+
1104
+ In addition to the exclusive lock ownership mode specified in 
1105
+ [[thread.mutex.requirements.mutex]], shared mutex types provide a
1106
+ *shared lock* ownership mode. Multiple execution agents can
1107
+ simultaneously hold a shared lock ownership of a shared mutex type. But
1108
+ no execution agent shall hold a shared lock while another execution
1109
+ agent holds an exclusive lock on the same shared mutex type, and
1110
+ vice-versa. The maximum number of execution agents which can share a
1111
+ shared lock on a single shared mutex type is unspecified, but shall be
1112
+ at least 10000. If more than the maximum number of execution agents
1113
+ attempt to obtain a shared lock, the excess execution agents shall block
1114
+ until the number of shared locks are reduced below the maximum amount by
1115
+ other execution agents releasing their shared lock.
1116
+
1117
+ The expression `m.lock_shared()` shall be well-formed and have the
1118
+ following semantics:
1119
+
1120
+ *Requires:* The calling thread has no ownership of the mutex.
1121
+
1122
+ *Effects:* Blocks the calling thread until shared ownership of the mutex
1123
+ can be obtained for the calling thread. If an exception is thrown then a
1124
+ shared lock shall not have been acquired for the current thread.
1125
+
1126
+ The calling thread has a shared lock on the mutex.
1127
+
1128
+ *Return type:* `void`.
1129
+
1130
+ *Synchronization:* Prior `unlock()` operations on the same object shall
1131
+ synchronize with  ([[intro.multithread]]) this operation.
1132
+
1133
+ *Throws:* `system_error` when an exception is required
1134
+  ([[thread.req.exception]]).
1135
+
1136
+ *Error conditions:*
1137
+
1138
+ - `operation_not_permitted` — if the thread does not have the privilege
1139
+ to perform the operation.
1140
+ - `resource_deadlock_would_occur` — if the implementation detects that a
1141
+ deadlock would occur.
1142
+ - `device_or_resource_busy` — if the mutex is already locked and
1143
+ blocking is not possible.
1144
+
1145
+ The expression `m.unlock_shared()` shall be well-formed and have the
1146
+ following semantics:
1147
+
1148
+ *Requires:* The calling thread shall hold a shared lock on the mutex.
1149
+
1150
+ *Effects:* Releases a shared lock on the mutex held by the calling
1151
+ thread.
1152
+
1153
+ *Return type:* `void`.
1154
+
1155
+ *Synchronization:* This operation synchronizes
1156
+ with ([[intro.multithread]]) subsequent `lock()` operations that obtain
1157
+ ownership on the same object.
1158
+
1159
+ *Throws:* Nothing.
1160
+
1161
+ The expression `m.try_lock_shared()` shall be well-formed and have the
1162
+ following semantics:
1163
+
1164
+ *Requires:* The calling thread has no ownership of the mutex.
1165
+
1166
+ *Effects:* Attempts to obtain shared ownership of the mutex for the
1167
+ calling thread without blocking. If shared ownership is not obtained,
1168
+ there is no effect and `try_lock_shared()` immediately returns. An
1169
+ implementation may fail to obtain the lock even if it is not held by any
1170
+ other thread.
1171
+
1172
+ *Return type:* `bool`.
1173
+
1174
+ *Returns:* `true` if the shared ownership lock was acquired, `false`
1175
+ otherwise.
1176
+
1177
+ *Synchronization:* If `try_lock_shared()` returns `true`, prior
1178
+ `unlock()` operations on the same object synchronize with
1179
+  ([[intro.multithread]]) this operation.
1180
+
1181
+ *Throws:* Nothing.
1182
+
1183
+ The expression `m.try_lock_shared_for(rel_time)` shall be well-formed
1184
+ and have the following semantics:
1185
+
1186
+ *Requires:* The calling thread has no ownership of the mutex.
1187
+
1188
+ *Effects:* Attempts to obtain shared lock ownership for the calling
1189
+ thread within the relative timeout ([[thread.req.timing]]) specified by
1190
+ `rel_time`. If the time specified by `rel_time` is less than or equal to
1191
+ `rel_time.zero()`, the function attempts to obtain ownership without
1192
+ blocking (as if by calling `try_lock_shared()`). The function shall
1193
+ return within the timeout specified by `rel_time` only if it has
1194
+ obtained shared ownership of the mutex object. As with `try_lock()`,
1195
+ there is no guarantee that ownership will be obtained if the lock is
1196
+ available, but implementations are expected to make a strong effort to
1197
+ do so. If an exception is thrown then a shared lock shall not have been
1198
+ acquired for the current thread.
1199
+
1200
+ *Return type:* `bool`.
1201
+
1202
+ *Returns:* `true` if the shared lock was acquired, `false` otherwise.
1203
+
1204
+ *Synchronization:* If `try_lock_shared_for()` returns `true`, prior
1205
+ `unlock()` operations on the same object synchronize
1206
+ with ([[intro.multithread]]) this operation.
1207
+
1208
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
1209
+
1210
+ The expression `m.try_lock_shared_until(abs_time)` shall be well-formed
1211
+ and have the following semantics:
1212
+
1213
+ *Requires:* The calling thread has no ownership of the mutex.
1214
+
1215
+ *Effects:* The function attempts to obtain shared ownership of the
1216
+ mutex. If `abs_time` has already passed, the function attempts to obtain
1217
+ shared ownership without blocking (as if by calling
1218
+ `try_lock_shared()`). The function shall return before the absolute
1219
+ timeout ([[thread.req.timing]]) specified by `abs_time` only if it has
1220
+ obtained shared ownership of the mutex object. As with `try_lock()`,
1221
+ there is no guarantee that ownership will be obtained if the lock is
1222
+ available, but implementations are expected to make a strong effort to
1223
+ do so. If an exception is thrown then a shared lock shall not have been
1224
+ acquired for the current thread.
1225
+
1226
+ *Return type:* `bool`.
1227
+
1228
+ *Returns:* `true` if the shared lock was acquired, `false` otherwise.
1229
+
1230
+ *Synchronization:* If `try_lock_shared_until()` returns `true`, prior
1231
+ `unlock()` operations on the same object synchronize
1232
+ with ([[intro.multithread]]) this operation.
1233
+
1234
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
1235
+
1236
+ ##### Class `shared_timed_mutex` <a id="thread.sharedtimedmutex.class">[[thread.sharedtimedmutex.class]]</a>
1237
+
1238
+ ``` cpp
1239
+ namespace std {
1240
+ class shared_timed_mutex {
1241
+ public:
1242
+ shared_timed_mutex();
1243
+ ~shared_timed_mutex();
1244
+
1245
+ shared_timed_mutex(const shared_timed_mutex&) = delete;
1246
+ shared_timed_mutex& operator=(const shared_timed_mutex&) = delete;
1247
+
1248
+ // Exclusive ownership
1249
+ void lock(); // blocking
1250
+ bool try_lock();
1251
+ template <class Rep, class Period>
1252
+ bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
1253
+ template <class Clock, class Duration>
1254
+ bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
1255
+ void unlock();
1256
+
1257
+ // Shared ownership
1258
+ void lock_shared(); // blocking
1259
+ bool try_lock_shared();
1260
+ template <class Rep, class Period>
1261
+ bool
1262
+ try_lock_shared_for(const chrono::duration<Rep, Period>& rel_time);
1263
+ template <class Clock, class Duration>
1264
+ bool
1265
+ try_lock_shared_until(const chrono::time_point<Clock, Duration>& abs_time);
1266
+ void unlock_shared();
1267
+ };
1268
+ }
1269
+ ```
1270
+
1271
+ The class `shared_timed_mutex` provides a non-recursive mutex with
1272
+ shared ownership semantics.
1273
+
1274
+ The class `shared_timed_mutex` shall satisfy all of the
1275
+ `SharedTimedMutex` requirements (
1276
+ [[thread.sharedtimedmutex.requirements]]). It shall be a standard-layout
1277
+ class (Clause  [[class]]).
1278
+
1279
+ The behavior of a program is undefined if:
1280
+
1281
+ - it destroys a `shared_timed_mutex` object owned by any thread,
1282
+ - a thread attempts to recursively gain any ownership of a
1283
+ `shared_timed_mutex`, or
1284
+ - a thread terminates while possessing any ownership of a
1285
+ `shared_timed_mutex`.
1286
+
1287
  ### Locks <a id="thread.lock">[[thread.lock]]</a>
1288
 
1289
  A *lock* is an object that holds a reference to a lockable object and
1290
  may unlock the lockable object during the lock’s destruction (such as
1291
  when leaving block scope). An execution agent may use a lock to aid in
 
1393
 
1394
  unique_lock(unique_lock const&) = delete;
1395
  unique_lock& operator=(unique_lock const&) = delete;
1396
 
1397
  unique_lock(unique_lock&& u) noexcept;
1398
+ unique_lock& operator=(unique_lock&& u);
1399
 
1400
  // [thread.lock.unique.locking], locking:
1401
  void lock();
1402
  bool try_lock();
1403
 
 
1537
  *Postconditions:* `pm == u_p.pm` and `owns == u_p.owns` (where `u_p` is
1538
  the state of `u` just prior to this construction), `u.pm == 0` and
1539
  `u.owns == false`.
1540
 
1541
  ``` cpp
1542
+ unique_lock& operator=(unique_lock&& u);
1543
  ```
1544
 
1545
  *Effects:* If `owns` calls `pm->unlock()`.
1546
 
1547
  *Postconditions:* `pm == u_p.pm` and `owns == u_p.owns` (where `u_p` is
 
1550
 
1551
  With a recursive mutex it is possible for both `*this` and `u` to own
1552
  the same mutex before the assignment. In this case, `*this` will own the
1553
  mutex after the assignment and `u` will not.
1554
 
1555
+ *Throws:* Nothing.
1556
+
1557
  ``` cpp
1558
  ~unique_lock();
1559
  ```
1560
 
1561
  *Effects:* If `owns` calls `pm->unlock()`.
 
1694
  mutex_type *mutex() const noexcept;
1695
  ```
1696
 
1697
  *Returns:* `pm`
1698
 
1699
+ #### Class template `shared_lock` <a id="thread.lock.shared">[[thread.lock.shared]]</a>
1700
+
1701
+ ``` cpp
1702
+ namespace std {
1703
+
1704
+ template <class Mutex>
1705
+ class shared_lock {
1706
+ public:
1707
+ typedef Mutex mutex_type;
1708
+
1709
+ // Shared locking
1710
+ shared_lock() noexcept;
1711
+ explicit shared_lock(mutex_type& m); // blocking
1712
+ shared_lock(mutex_type& m, defer_lock_t) noexcept;
1713
+ shared_lock(mutex_type& m, try_to_lock_t);
1714
+ shared_lock(mutex_type& m, adopt_lock_t);
1715
+ template <class Clock, class Duration>
1716
+ shared_lock(mutex_type& m,
1717
+ const chrono::time_point<Clock, Duration>& abs_time);
1718
+ template <class Rep, class Period>
1719
+ shared_lock(mutex_type& m,
1720
+ const chrono::duration<Rep, Period>& rel_time);
1721
+ ~shared_lock();
1722
+
1723
+ shared_lock(shared_lock const&) = delete;
1724
+ shared_lock& operator=(shared_lock const&) = delete;
1725
+
1726
+ shared_lock(shared_lock&& u) noexcept;
1727
+ shared_lock& operator=(shared_lock&& u) noexcept;
1728
+
1729
+ void lock(); // blocking
1730
+ bool try_lock();
1731
+ template <class Rep, class Period>
1732
+ bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
1733
+ template <class Clock, class Duration>
1734
+ bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
1735
+ void unlock();
1736
+
1737
+ // Setters
1738
+ void swap(shared_lock& u) noexcept;
1739
+ mutex_type* release() noexcept;
1740
+
1741
+ // Getters
1742
+ bool owns_lock() const noexcept;
1743
+ explicit operator bool () const noexcept;
1744
+ mutex_type* mutex() const noexcept;
1745
+
1746
+ private:
1747
+ mutex_type* pm; // exposition only
1748
+ bool owns; // exposition only
1749
+ };
1750
+
1751
+ template <class Mutex>
1752
+ void swap(shared_lock<Mutex>& x, shared_lock<Mutex>& y) noexcept;
1753
+
1754
+ } // std
1755
+ ```
1756
+
1757
+ An object of type `shared_lock` controls the shared ownership of a
1758
+ lockable object within a scope. Shared ownership of the lockable object
1759
+ may be acquired at construction or after construction, and may be
1760
+ transferred, after acquisition, to another `shared_lock` object. Objects
1761
+ of type `shared_lock` are not copyable but are movable. The behavior of
1762
+ a program is undefined if the contained pointer `pm` is not null and the
1763
+ lockable object pointed to by `pm` does not exist for the entire
1764
+ remaining lifetime ([[basic.life]]) of the `shared_lock` object. The
1765
+ supplied `Mutex` type shall meet the shared mutex requirements (
1766
+ [[thread.sharedtimedmutex.requirements]]).
1767
+
1768
+ `shared_lock<Mutex>` meets the `TimedLockable` requirements (
1769
+ [[thread.req.lockable.timed]]).
1770
+
1771
+ ##### `shared_lock` constructors, destructor, and assignment <a id="thread.lock.shared.cons">[[thread.lock.shared.cons]]</a>
1772
+
1773
+ ``` cpp
1774
+ shared_lock() noexcept;
1775
+ ```
1776
+
1777
+ *Effects:* Constructs an object of type `shared_lock`.
1778
+
1779
+ *Postconditions:* `pm == nullptr` and `owns == false`.
1780
+
1781
+ ``` cpp
1782
+ explicit shared_lock(mutex_type& m);
1783
+ ```
1784
+
1785
+ *Requires:* The calling thread does not own the mutex for any ownership
1786
+ mode.
1787
+
1788
+ *Effects:* Constructs an object of type `shared_lock` and calls
1789
+ `m.lock_shared()`.
1790
+
1791
+ *Postconditions:* `pm == &m` and `owns == true`.
1792
+
1793
+ ``` cpp
1794
+ shared_lock(mutex_type& m, defer_lock_t) noexcept;
1795
+ ```
1796
+
1797
+ *Effects:* Constructs an object of type `shared_lock`.
1798
+
1799
+ *Postconditions:* `pm == &m` and `owns == false`.
1800
+
1801
+ ``` cpp
1802
+ shared_lock(mutex_type& m, try_to_lock_t);
1803
+ ```
1804
+
1805
+ *Requires:* The calling thread does not own the mutex for any ownership
1806
+ mode.
1807
+
1808
+ *Effects:* Constructs an object of type `shared_lock` and calls
1809
+ `m.try_lock_shared()`.
1810
+
1811
+ *Postconditions:* `pm == &m` and `owns == res` where `res` is the value
1812
+ returned by the call to `m.try_lock_shared()`.
1813
+
1814
+ ``` cpp
1815
+ shared_lock(mutex_type& m, adopt_lock_t);
1816
+ ```
1817
+
1818
+ *Requires:* The calling thread has shared ownership of the mutex.
1819
+
1820
+ *Effects:* Constructs an object of type `shared_lock`.
1821
+
1822
+ *Postconditions:* `pm == &m` and `owns == true`.
1823
+
1824
+ ``` cpp
1825
+ template <class Clock, class Duration>
1826
+ shared_lock(mutex_type& m,
1827
+ const chrono::time_point<Clock, Duration>& abs_time);
1828
+ ```
1829
+
1830
+ *Requires:* The calling thread does not own the mutex for any ownership
1831
+ mode.
1832
+
1833
+ *Effects:* Constructs an object of type `shared_lock` and calls
1834
+ `m.try_lock_shared_until(abs_time)`.
1835
+
1836
+ *Postconditions:* `pm == &m` and `owns == res` where `res` is the value
1837
+ returned by the call to `m.try_lock_shared_until(abs_time)`.
1838
+
1839
+ ``` cpp
1840
+ template <class Rep, class Period>
1841
+ shared_lock(mutex_type& m,
1842
+ const chrono::duration<Rep, Period>& rel_time);
1843
+ ```
1844
+
1845
+ *Requires:* The calling thread does not own the mutex for any ownership
1846
+ mode.
1847
+
1848
+ *Effects:* Constructs an object of type `shared_lock` and calls
1849
+ `m.try_lock_shared_for(rel_time)`.
1850
+
1851
+ *Postconditions:* `pm == &m` and `owns == res` where `res` is the value
1852
+ returned by the call to `m.try_lock_shared_for(rel_time)`.
1853
+
1854
+ ``` cpp
1855
+ ~shared_lock();
1856
+ ```
1857
+
1858
+ *Effects:* If `owns` calls `pm->unlock_shared()`.
1859
+
1860
+ ``` cpp
1861
+ shared_lock(shared_lock&& sl) noexcept;
1862
+ ```
1863
+
1864
+ *Postconditions:* `pm == &sl_p.pm` and `owns == sl_p.owns` (where `sl_p`
1865
+ is the state of `sl` just prior to this construction),
1866
+ `sl.pm == nullptr` and `sl.owns == false`.
1867
+
1868
+ ``` cpp
1869
+ shared_lock& operator=(shared_lock&& sl) noexcept;
1870
+ ```
1871
+
1872
+ *Effects:* If `owns` calls `pm->unlock_shared()`.
1873
+
1874
+ *Postconditions:* `pm == &sl_p.pm` and `owns == sl_p.owns` (where `sl_p`
1875
+ is the state of `sl` just prior to this assignment), `sl.pm == nullptr`
1876
+ and `sl.owns == false`.
1877
+
1878
+ ##### `shared_lock` locking <a id="thread.lock.shared.locking">[[thread.lock.shared.locking]]</a>
1879
+
1880
+ ``` cpp
1881
+ void lock();
1882
+ ```
1883
+
1884
+ *Effects:* `pm->lock_shared()`.
1885
+
1886
+ *Postconditions:* `owns == true`.
1887
+
1888
+ *Throws:* Any exception thrown by `pm->lock_shared()`. `system_error` if
1889
+ an exception is required ([[thread.req.exception]]). `system_error`
1890
+ with an error condition of `operation_not_permitted` if `pm` is
1891
+ `nullptr`. `system_error` with an error condition of
1892
+ `resource_deadlock_would_occur` if on entry `owns` is `true`.
1893
+
1894
+ ``` cpp
1895
+ bool try_lock();
1896
+ ```
1897
+
1898
+ *Effects:* `pm->try_lock_shared()`.
1899
+
1900
+ *Returns:* The value returned by the call to `pm->try_lock_shared()`.
1901
+
1902
+ *Postconditions:* `owns == res`, where `res` is the value returned by
1903
+ the call to `pm->try_lock_shared()`.
1904
+
1905
+ *Throws:* Any exception thrown by `pm->try_lock_shared()`.
1906
+ `system_error` if an exception is required ([[thread.req.exception]]).
1907
+ `system_error` with an error condition of `operation_not_permitted` if
1908
+ `pm` is `nullptr`. `system_error` with an error condition of
1909
+ `resource_deadlock_would_occur` if on entry `owns` is `true`.
1910
+
1911
+ ``` cpp
1912
+ template <class Clock, class Duration>
1913
+ bool
1914
+ try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
1915
+ ```
1916
+
1917
+ *Effects:* `pm->try_lock_shared_until(abs_time)`.
1918
+
1919
+ *Returns:* The value returned by the call to
1920
+ `pm->try_lock_shared_until(abs_time)`.
1921
+
1922
+ *Postconditions:* `owns == res`, where `res` is the value returned by
1923
+ the call to `pm->try_lock_shared_until(abs_time)`.
1924
+
1925
+ *Throws:* Any exception thrown by `pm->try_lock_shared_until(abs_time)`.
1926
+ `system_error` if an exception is required ([[thread.req.exception]]).
1927
+ `system_error` with an error condition of `operation_not_permitted` if
1928
+ `pm` is `nullptr`. `system_error` with an error condition of
1929
+ `resource_deadlock_would_occur` if on entry `owns` is `true`.
1930
+
1931
+ ``` cpp
1932
+ template <class Rep, class Period>
1933
+ bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
1934
+ ```
1935
+
1936
+ *Effects:* `pm->try_lock_shared_for(rel_time)`.
1937
+
1938
+ *Returns:* The value returned by the call to
1939
+ `pm->try_lock_shared_for(rel_time)`.
1940
+
1941
+ *Postconditions:* `owns == res`, where `res` is the value returned by
1942
+ the call to `pm->try_lock_shared_for(rel_time)`.
1943
+
1944
+ *Throws:* Any exception thrown by `pm->try_lock_shared_for(rel_time)`.
1945
+ `system_error` if an exception is required  ([[thread.req.exception]]).
1946
+ `system_error` with an error condition of `operation_not_permitted` if
1947
+ `pm` is `nullptr`. `system_error` with an error condition of
1948
+ `resource_deadlock_would_occur` if on entry `owns` is `true`.
1949
+
1950
+ ``` cpp
1951
+ void unlock();
1952
+ ```
1953
+
1954
+ *Effects:* `pm->unlock_shared()`.
1955
+
1956
+ *Postconditions:* `owns == false`.
1957
+
1958
+ *Throws:* `system_error` when an exception is required
1959
+  ([[thread.req.exception]]).
1960
+
1961
+ *Error conditions:*
1962
+
1963
+ - `operation_not_permitted` — if on entry `owns` is `false`.
1964
+
1965
+ ##### `shared_lock` modifiers <a id="thread.lock.shared.mod">[[thread.lock.shared.mod]]</a>
1966
+
1967
+ ``` cpp
1968
+ void swap(shared_lock& sl) noexcept;
1969
+ ```
1970
+
1971
+ *Effects:* Swaps the data members of `*this` and `sl`.
1972
+
1973
+ ``` cpp
1974
+ mutex_type* release() noexcept;
1975
+ ```
1976
+
1977
+ *Returns:* The previous value of `pm`.
1978
+
1979
+ *Postconditions:* `pm == nullptr` and `owns == false`.
1980
+
1981
+ ``` cpp
1982
+ template <class Mutex>
1983
+ void swap(shared_lock<Mutex>& x, shared_lock<Mutex>& y) noexcept;
1984
+ ```
1985
+
1986
+ *Effects:* `x.swap(y)`.
1987
+
1988
+ ##### `shared_lock` observers <a id="thread.lock.shared.obs">[[thread.lock.shared.obs]]</a>
1989
+
1990
+ ``` cpp
1991
+ bool owns_lock() const noexcept;
1992
+ ```
1993
+
1994
+ *Returns:* `owns`.
1995
+
1996
+ ``` cpp
1997
+ explicit operator bool () const noexcept;
1998
+ ```
1999
+
2000
+ *Returns:* `owns`.
2001
+
2002
+ ``` cpp
2003
+ mutex_type* mutex() const noexcept;
2004
+ ```
2005
+
2006
+ *Returns:* `pm`.
2007
+
2008
  ### Generic locking algorithms <a id="thread.lock.algorithm">[[thread.lock.algorithm]]</a>
2009
 
2010
  ``` cpp
2011
  template <class L1, class L2, class... L3> int try_lock(L1&, L2&, L3&...);
2012
  ```
 
2018
  *Effects:* Calls `try_lock()` for each argument in order beginning with
2019
  the first until all arguments have been processed or a call to
2020
  `try_lock()` fails, either by returning `false` or by throwing an
2021
  exception. If a call to `try_lock()` fails, `unlock()` shall be called
2022
  for all prior arguments and there shall be no further calls to
2023
+ `try_lock()`.
2024
 
2025
  *Returns:* `-1` if all calls to `try_lock()` returned `true`, otherwise
2026
  a 0-based index value that indicates the argument for which `try_lock()`
2027
  returned `false`.
2028
 
 
2097
  passive executions.
2098
 
2099
  *Throws:* `system_error` when an exception is
2100
  required ([[thread.req.exception]]), or any exception thrown by `func`.
2101
 
 
 
 
 
2102
  ``` cpp
2103
  // global flag, regular function
2104
  void init();
2105
  std::once_flag flag;
2106
 
 
2147
 
2148
  1. the release of the mutex and entry into the waiting state;
2149
  2. the unblocking of the wait; and
2150
  3. the reacquisition of the lock.
2151
 
2152
+ The implementation shall behave as if all executions of `notify_one`,
2153
+ `notify_all`, and each part of the `wait`, `wait_for`, and `wait_until`
2154
+ executions are executed in a single unspecified total order consistent
2155
+ with the "happens before" order.
2156
 
2157
  Condition variable construction and destruction need not be
2158
  synchronized.
2159
 
2160
  ``` cpp
 
2188
  ``` cpp
2189
  lk.unlock();
2190
  cond.notify_all();
2191
  ```
2192
 
2193
+ *Synchronization:* The implied `lk.unlock()` call is sequenced after the
2194
+ destruction of all objects with thread storage duration associated with
2195
+ the current thread.
 
2196
 
2197
  *Note:* The supplied lock will be held until the thread exits, and care
2198
  must be taken to ensure that this does not cause deadlock due to lock
2199
  ordering issues. After calling `notify_all_at_thread_exit` it is
2200
  recommended that the thread should be exited as soon as possible, and
 
2300
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
2301
  thread, and either
2302
 
2303
  - no other thread is waiting on this `condition_variable` object or
2304
  - `lock.mutex()` returns the same value for each of the `lock` arguments
2305
+ supplied by all concurrently waiting (via `wait`, `wait_for`, or
2306
+ `wait_until`) threads.
2307
 
2308
  *Effects:*
2309
 
2310
  - Atomically calls `lock.unlock()` and blocks on `*this`.
2311
  - When unblocked, calls `lock.lock()` (possibly blocking on the lock),
2312
  then returns.
2313
  - The function will unblock when signaled by a call to `notify_one()` or
2314
  a call to `notify_all()`, or spuriously.
2315
+
2316
+ *Remarks:* If the function fails to meet the postcondition,
2317
+ `std::terminate()` shall be called ([[except.terminate]]). This can
2318
+ happen if the re-locking of the mutex throws an exception.
2319
 
2320
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
2321
  thread.
2322
 
2323
+ *Throws:* Nothing.
 
 
 
 
 
2324
 
2325
  ``` cpp
2326
  template <class Predicate>
2327
  void wait(unique_lock<mutex>& lock, Predicate pred);
2328
  ```
 
2330
  *Requires:* `lock.owns_lock()` is `true` and `lock.mutex()` is locked by
2331
  the calling thread, and either
2332
 
2333
  - no other thread is waiting on this `condition_variable` object or
2334
  - `lock.mutex()` returns the same value for each of the `lock` arguments
2335
+ supplied by all concurrently waiting (via `wait`, `wait_for`, or
2336
+ `wait_until`) threads.
2337
 
2338
+ *Effects:* Equivalent to:
2339
 
2340
  ``` cpp
2341
  while (!pred())
2342
  wait(lock);
2343
  ```
2344
 
2345
+ *Remarks:* If the function fails to meet the postcondition,
2346
+ `std::terminate()` shall be called ([[except.terminate]]). This can
2347
+ happen if the re-locking of the mutex throws an exception.
2348
+
2349
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
2350
  thread.
2351
 
2352
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]) or any
2353
+ exception thrown by `pred`.
 
 
 
 
2354
 
2355
  ``` cpp
2356
  template <class Clock, class Duration>
2357
  cv_status wait_until(unique_lock<mutex>& lock,
2358
  const chrono::time_point<Clock, Duration>& abs_time);
 
2374
  - The function will unblock when signaled by a call to `notify_one()`, a
2375
  call to `notify_all()`, expiration of the absolute
2376
  timeout ([[thread.req.timing]]) specified by `abs_time`, or
2377
  spuriously.
2378
  - If the function exits via an exception, `lock.lock()` shall be called
2379
+ prior to exiting the function.
2380
+
2381
+ *Remarks:* If the function fails to meet the postcondition,
2382
+ `std::terminate()` shall be called ([[except.terminate]]). This can
2383
+ happen if the re-locking of the mutex throws an exception.
2384
 
2385
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
2386
  thread.
2387
 
2388
  *Returns:* `cv_status::timeout` if the absolute
2389
  timeout ([[thread.req.timing]]) specified by `abs_time` expired,
2390
  otherwise `cv_status::no_timeout`.
2391
 
2392
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
 
 
 
 
 
2393
 
2394
  ``` cpp
2395
  template <class Rep, class Period>
2396
  cv_status wait_for(unique_lock<mutex>& lock,
2397
  const chrono::duration<Rep, Period>& rel_time);
 
2403
  - no other thread is waiting on this `condition_variable` object or
2404
  - `lock.mutex()` returns the same value for each of the `lock` arguments
2405
  supplied by all concurrently waiting (via `wait`, `wait_for`, or
2406
  `wait_until`) threads.
2407
 
2408
+ *Effects:* Equivalent to:
2409
 
2410
  ``` cpp
2411
  return wait_until(lock, chrono::steady_clock::now() + rel_time);
2412
  ```
2413
 
2414
  *Returns:* `cv_status::timeout` if the relative
2415
  timeout ([[thread.req.timing]]) specified by `rel_time` expired,
2416
  otherwise `cv_status::no_timeout`.
2417
 
2418
+ *Remarks:* If the function fails to meet the postcondition,
2419
+ `std::terminate()` shall be called ([[except.terminate]]). This can
2420
+ happen if the re-locking of the mutex throws an exception.
2421
+
2422
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
2423
  thread.
2424
 
2425
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
 
 
 
 
 
2426
 
2427
  ``` cpp
2428
  template <class Clock, class Duration, class Predicate>
2429
  bool wait_until(unique_lock<mutex>& lock,
2430
  const chrono::time_point<Clock, Duration>& abs_time,
 
2434
  *Requires:* `lock.owns_lock()` is `true` and `lock.mutex()` is locked by
2435
  the calling thread, and either
2436
 
2437
  - no other thread is waiting on this `condition_variable` object or
2438
  - `lock.mutex()` returns the same value for each of the `lock` arguments
2439
+ supplied by all concurrently waiting (via `wait`, `wait_for`, or
2440
+ `wait_until`) threads.
2441
 
2442
+ *Effects:* Equivalent to:
2443
 
2444
  ``` cpp
2445
  while (!pred())
2446
  if (wait_until(lock, abs_time) == cv_status::timeout)
2447
  return pred();
2448
  return true;
2449
  ```
2450
 
2451
+ *Remarks:* If the function fails to meet the postcondition,
2452
+ `std::terminate()` shall be called ([[except.terminate]]). This can
2453
+ happen if the re-locking of the mutex throws an exception.
2454
 
2455
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
2456
  thread.
2457
 
2458
  The returned value indicates whether the predicate evaluated to `true`
2459
  regardless of whether the timeout was triggered.
2460
 
2461
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]) or any
2462
+ exception thrown by `pred`.
 
 
 
 
2463
 
2464
  ``` cpp
2465
  template <class Rep, class Period, class Predicate>
2466
  bool wait_for(unique_lock<mutex>& lock,
2467
  const chrono::duration<Rep, Period>& rel_time,
 
2474
  - no other thread is waiting on this `condition_variable` object or
2475
  - `lock.mutex()` returns the same value for each of the `lock` arguments
2476
  supplied by all concurrently waiting (via `wait`, `wait_for`, or
2477
  `wait_until`) threads.
2478
 
2479
+ *Effects:* Equivalent to:
2480
 
2481
  ``` cpp
2482
  return wait_until(lock, chrono::steady_clock::now() + rel_time, std::move(pred));
2483
  ```
2484
 
2485
  There is no blocking if `pred()` is initially `true`, even if the
2486
  timeout has already expired.
2487
 
2488
+ *Remarks:* If the function fails to meet the postcondition,
2489
+ `std::terminate()` shall be called ([[except.terminate]]). This can
2490
+ happen if the re-locking of the mutex throws an exception.
2491
+
2492
  `lock.owns_lock()` is `true` and `lock.mutex()` is locked by the calling
2493
  thread.
2494
 
 
 
2495
  The returned value indicates whether the predicate evaluates to `true`
2496
  regardless of whether the timeout was triggered.
2497
 
2498
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]) or any
2499
+ exception thrown by `pred`.
 
 
 
 
2500
 
2501
  ### Class `condition_variable_any` <a id="thread.condition.condvarany">[[thread.condition.condvarany]]</a>
2502
 
2503
  A `Lock` type shall meet the `BasicLockable` requirements (
2504
  [[thread.req.lockable.basic]]). All of the standard mutex types meet
 
2548
  *Throws:* `bad_alloc` or `system_error` when an exception is
2549
  required ([[thread.req.exception]]).
2550
 
2551
  *Error conditions:*
2552
 
2553
+ - `resource_unavailable_try_again` — if some non-memory resource
2554
+ limitation prevents initialization.
2555
  - `operation_not_permitted` — if the thread does not have the privilege
2556
  to perform the operation.
2557
 
2558
  ``` cpp
2559
  ~condition_variable_any();
 
2598
  - Atomically calls `lock.unlock()` and blocks on `*this`.
2599
  - When unblocked, calls `lock.lock()` (possibly blocking on the lock)
2600
  and returns.
2601
  - The function will unblock when signaled by a call to `notify_one()`, a
2602
  call to `notify_all()`, or spuriously.
2603
+
2604
+ *Remarks:* If the function fails to meet the postcondition,
2605
+ `std::terminate()` shall be called ([[except.terminate]]). This can
2606
+ happen if the re-locking of the mutex throws an exception.
2607
 
2608
  `lock` is locked by the calling thread.
2609
 
2610
+ *Throws:* Nothing.
 
 
 
 
 
2611
 
2612
  ``` cpp
2613
  template <class Lock, class Predicate>
2614
  void wait(Lock& lock, Predicate pred);
2615
  ```
2616
 
2617
+ *Effects:* Equivalent to:
2618
 
2619
  ``` cpp
2620
  while (!pred())
2621
  wait(lock);
2622
  ```
 
2634
  - The function will unblock when signaled by a call to `notify_one()`, a
2635
  call to `notify_all()`, expiration of the absolute
2636
  timeout ([[thread.req.timing]]) specified by `abs_time`, or
2637
  spuriously.
2638
  - If the function exits via an exception, `lock.lock()` shall be called
2639
+ prior to exiting the function.
2640
+
2641
+ *Remarks:* If the function fails to meet the postcondition,
2642
+ `std::terminate()` shall be called ([[except.terminate]]). This can
2643
+ happen if the re-locking of the mutex throws an exception.
2644
 
2645
  `lock` is locked by the calling thread.
2646
 
2647
  *Returns:* `cv_status::timeout` if the absolute
2648
  timeout ([[thread.req.timing]]) specified by `abs_time` expired,
2649
  otherwise `cv_status::no_timeout`.
2650
 
2651
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
 
 
 
 
 
2652
 
2653
  ``` cpp
2654
  template <class Lock, class Rep, class Period>
2655
  cv_status wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time);
2656
  ```
2657
 
2658
+ *Effects:* Equivalent to:
2659
 
2660
  ``` cpp
2661
  return wait_until(lock, chrono::steady_clock::now() + rel_time);
2662
  ```
2663
 
2664
  *Returns:* `cv_status::timeout` if the relative
2665
  timeout ([[thread.req.timing]]) specified by `rel_time` expired,
2666
  otherwise `cv_status::no_timeout`.
2667
 
2668
+ *Remarks:* If the function fails to meet the postcondition,
2669
+ `std::terminate()` shall be called ([[except.terminate]]). This can
2670
+ happen if the re-locking of the mutex throws an exception.
2671
+
2672
  `lock` is locked by the calling thread.
2673
 
2674
+ *Throws:* Timeout-related exceptions ([[thread.req.timing]]).
 
 
 
 
 
2675
 
2676
  ``` cpp
2677
  template <class Lock, class Clock, class Duration, class Predicate>
2678
  bool wait_until(Lock& lock, const chrono::time_point<Clock, Duration>& abs_time, Predicate pred);
2679
  ```
2680
 
2681
+ *Effects:* Equivalent to:
2682
 
2683
  ``` cpp
2684
  while (!pred())
2685
  if (wait_until(lock, abs_time) == cv_status::timeout)
2686
  return pred();
2687
  return true;
2688
  ```
2689
 
2690
+ There is no blocking if `pred()` is initially `true`, or if the timeout
2691
+ has already expired.
2692
 
2693
  The returned value indicates whether the predicate evaluates to `true`
2694
  regardless of whether the timeout was triggered.
2695
 
2696
  ``` cpp
2697
  template <class Lock, class Rep, class Period, class Predicate>
2698
  bool wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time, Predicate pred);
2699
  ```
2700
 
2701
+ *Effects:* Equivalent to:
2702
 
2703
  ``` cpp
2704
  return wait_until(lock, chrono::steady_clock::now() + rel_time, std::move(pred));
2705
  ```
2706
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2707
  ## Futures <a id="futures">[[futures]]</a>
2708
 
2709
  ### Overview <a id="futures.overview">[[futures.overview]]</a>
2710
 
2711
  [[futures]] describes components that a C++program can use to retrieve
 
2715
  single-threaded programs as well.
2716
 
2717
  ``` cpp
2718
  namespace std {
2719
  enum class future_errc {
2720
+ broken_promise = implementation-defined,
2721
+ future_already_retrieved = implementation-defined,
2722
+ promise_already_satisfied = implementation-defined,
2723
+ no_state = implementation-defined
2724
  };
2725
 
2726
  enum class launch : unspecified{} {
2727
  async = unspecified{},
2728
  deferred = unspecified{},
2729
+ implementation-defined
2730
  };
2731
 
2732
  enum class future_status {
2733
  ready,
2734
  timeout,
 
2763
 
2764
  template <class> class packaged_task; // undefined
2765
  template <class R, class... ArgTypes>
2766
  class packaged_task<R(ArgTypes...)>;
2767
 
2768
+ template <class R, class... ArgTypes>
2769
  void swap(packaged_task<R(ArgTypes...)>&, packaged_task<R(ArgTypes...)>&) noexcept;
2770
 
2771
  template <class R, class Alloc>
2772
  struct uses_allocator<packaged_task<R>, Alloc>;
2773
 
2774
  template <class F, class... Args>
2775
+ future<result_of_t<decay_t<F>(decay_t<Args>...)>>
2776
  async(F&& f, Args&&... args);
2777
  template <class F, class... Args>
2778
+ future<result_of_t<decay_t<F>(decay_t<Args>...)>>
2779
  async(launch policy, F&& f, Args&&... args);
2780
  }
2781
  ```
2782
 
2783
+ The `enum` type `launch` is a bitmask type ([[bitmask.types]]) with
2784
+ `launch::async` and `launch::deferred` denoting individual bits.
2785
+ Implementations can provide bitmasks to specify restrictions on task
2786
+ interaction by functions launched by `async()` applicable to a
2787
+ corresponding subset of available launch policies. Implementations can
2788
+ extend the behavior of the first overload of `async()` by adding their
2789
+ extensions to the launch policy under the “as if” rule.
2790
+
2791
+ The enum values of `future_errc` are distinct and not zero.
2792
 
2793
  ### Error handling <a id="futures.errors">[[futures.errors]]</a>
2794
 
2795
  ``` cpp
2796
  const error_category& future_category() noexcept;
 
2851
  defined in this clause reference such shared state.
2852
 
2853
  The result can be any kind of object including a function to compute
2854
  that result, as used by `async` when `policy` is `launch::deferred`.
2855
 
2856
+ An *asynchronous return object* is an object that reads results from a
2857
  shared state. A *waiting function* of an asynchronous return object is
2858
  one that potentially blocks to wait for the shared state to be made
2859
  ready. If a waiting function can return before the state is made ready
2860
  because of a timeout ([[thread.req.lockable]]), then it is a *timed
2861
  waiting function*, otherwise it is a *non-timed waiting function*.
 
2871
  to release its shared state, it means:
2872
 
2873
  - if the return object or provider holds the last reference to its
2874
  shared state, the shared state is destroyed; and
2875
  - the return object or provider gives up its reference to its shared
2876
+ state; and
2877
+ - these actions will not block for the shared state to become ready,
2878
+ except that it may block if all of the following are true: the shared
2879
+ state was created by a call to `std::async`, the shared state is not
2880
+ yet ready, and this was the last reference to the shared state.
2881
 
2882
  When an asynchronous provider is said to make its shared state ready, it
2883
  means:
2884
 
2885
  - first, the provider marks its shared state as ready; and
 
3049
 
3050
  *Throws:*
3051
 
3052
  - `future_error` if its shared state already has a stored value or
3053
  exception, or
3054
+ - for the first version, any exception thrown by the constructor
3055
+ selected to copy an object of `R`, or
3056
+ - for the second version, any exception thrown by the constructor
3057
+ selected to move an object of `R`.
3058
 
3059
  *Error conditions:*
3060
 
3061
  - `promise_already_satisfied` if its shared state already has a stored
3062
  value or exception.
 
3088
  *Effects:* Stores the value `r` in the shared state without making that
3089
  state ready immediately. Schedules that state to be made ready when the
3090
  current thread exits, after all objects of thread storage duration
3091
  associated with the current thread have been destroyed.
3092
 
3093
+ *Throws:*
3094
+
3095
+ - `future_error` if its shared state already has a stored value or
3096
+ exception, or
3097
+ - for the first version, any exception thrown by the constructor
3098
+ selected to copy an object of `R`, or
3099
+ - for the second version, any exception thrown by the constructor
3100
+ selected to move an object of `R`.
3101
 
3102
  *Error conditions:*
3103
 
3104
  - `promise_already_satisfied` if its shared state already has a stored
3105
  value or exception.
3106
  - `no_state` if `*this` has no shared state.
3107
 
3108
  ``` cpp
3109
+ void set_exception_at_thread_exit(exception_ptr p);
3110
  ```
3111
 
3112
  *Effects:* Stores the exception pointer `p` in the shared state without
3113
  making that state ready immediately. Schedules that state to be made
3114
  ready when the current thread exits, after all objects of thread storage
 
3186
  ``` cpp
3187
  future() noexcept;
3188
  ```
3189
 
3190
  *Effects:* constructs an *empty* `future` object that does not refer to
3191
+ a shared state.
3192
 
3193
  `valid() == false`.
3194
 
3195
  ``` cpp
3196
  future(future&& rhs) noexcept;
 
3250
  *Effects:* `wait()`s until the shared state is ready, then retrieves the
3251
  value stored in the shared state.
3252
 
3253
  *Returns:*
3254
 
3255
+ - `future::get()` returns the value `v` stored in the object’s shared
3256
+ state as `std::move(v)`.
 
3257
  - `future<R&>::get()` returns the reference stored as value in the
3258
  object’s shared state.
3259
  - `future<void>::get()` returns nothing.
3260
 
3261
  *Throws:* the stored exception, if an exception was stored in the shared
 
3292
  - `future_status::ready` if the shared state is ready.
3293
  - `future_status::timeout` if the function is returning because the
3294
  relative timeout ([[thread.req.timing]]) specified by `rel_time` has
3295
  expired.
3296
 
3297
+ *Throws:* timeout-related exceptions ([[thread.req.timing]]).
3298
+
3299
  ``` cpp
3300
  template <class Clock, class Duration>
3301
  future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
3302
  ```
3303
 
 
3313
  - `future_status::ready` if the shared state is ready.
3314
  - `future_status::timeout` if the function is returning because the
3315
  absolute timeout ([[thread.req.timing]]) specified by `abs_time` has
3316
  expired.
3317
 
3318
+ *Throws:* timeout-related exceptions ([[thread.req.timing]]).
3319
+
3320
  ### Class template `shared_future` <a id="futures.shared_future">[[futures.shared_future]]</a>
3321
 
3322
  The class template `shared_future` defines a type for asynchronous
3323
  return objects which may share their shared state with other
3324
  asynchronous return objects. A default-constructed `shared_future`
 
3375
  ``` cpp
3376
  shared_future() noexcept;
3377
  ```
3378
 
3379
  *Effects:* constructs an *empty* `shared_future` object that does not
3380
+ refer to a shared state.
3381
 
3382
  `valid() == false`.
3383
 
3384
  ``` cpp
3385
  shared_future(const shared_future& rhs);
 
3500
  - `future_status::ready` if the shared state is ready.
3501
  - `future_status::timeout` if the function is returning because the
3502
  relative timeout ([[thread.req.timing]]) specified by `rel_time` has
3503
  expired.
3504
 
3505
+ *Throws:* timeout-related exceptions ([[thread.req.timing]]).
3506
+
3507
  ``` cpp
3508
  template <class Clock, class Duration>
3509
  future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
3510
  ```
3511
 
 
3521
  - `future_status::ready` if the shared state is ready.
3522
  - `future_status::timeout` if the function is returning because the
3523
  absolute timeout ([[thread.req.timing]]) specified by `abs_time` has
3524
  expired.
3525
 
3526
+ *Throws:* timeout-related exceptions ([[thread.req.timing]]).
3527
+
3528
  ### Function template `async` <a id="futures.async">[[futures.async]]</a>
3529
 
3530
  The function template `async` provides a mechanism to launch a function
3531
  potentially in a new thread and provides the result of the function in a
3532
  `future` object with which it shares a shared state.
3533
 
3534
  ``` cpp
3535
  template <class F, class... Args>
3536
+ future<result_of_t<decay_t<F>(decay_t<Args>...)>> async(F&& f, Args&&... args);
 
3537
  template <class F, class... Args>
3538
+ future<result_of_t<decay_t<F>(decay_t<Args>...)>> async(launch policy, F&& f, Args&&... args);
 
3539
  ```
3540
 
3541
  *Requires:* `F` and each `Ti` in `Args` shall satisfy the
3542
  `MoveConstructible` requirements.
3543
  *`INVOKE`*`(`*`DECAY_COPY`*`(std::forward<F>(f)), `*`DECAY_COPY`*`(std::forward<Args>(args))...)`
 
3566
  asynchronous return objects that reference that state.
3567
  - if `policy & launch::deferred` is non-zero — Stores
3568
  *`DECAY_COPY`*`(std::forward<F>(f))` and
3569
  *`DECAY_COPY`*`(std::forward<Args>(args))...` in the shared state.
3570
  These copies of `f` and `args` constitute a *deferred function*.
3571
+ Invocation of the deferred function evaluates
3572
+ *`INVOKE`*`(std::move(g), std::move(xyz))` where `g` is the stored
3573
+ value of *`DECAY_COPY`*`(std::forward<F>(f))` and `xyz` is the stored
3574
+ copy of *`DECAY_COPY`*`(std::forward<Args>(args))...`. Any return
3575
+ value is stored as the result in the shared state. Any exception
3576
+ propagated from the execution of the deferred function is stored as
3577
+ the exceptional result in the shared state. The shared state is not
3578
  made ready until the function has completed. The first call to a
3579
  non-timed waiting function ([[futures.state]]) on an asynchronous
3580
  return object referring to this shared state shall invoke the deferred
3581
  function in the thread that called the waiting function. Once
3582
+ evaluation of *`INVOKE`*`(std::move(g), std::move(xyz))` begins, the
3583
+ function is no longer considered deferred. If this policy is specified
3584
+ together with other policies, such as when using a `policy` value of
3585
  `launch::async | launch::deferred`, implementations should defer
3586
  invocation or the selection of the policy when no more concurrency can
3587
  be effectively exploited.
3588
+ - If no value is set in the launch policy, or a value is set that is
3589
+ neither specified in this International Standard or by the
3590
+ implementation, the behaviour is undefined.
3591
 
3592
  *Returns:* An object of type
3593
+ `future<result_of_t<decay_t<F>(decay_t<Args>...)>``>` that refers to the
3594
+ shared state created by this call to `async`. If a future obtained from
3595
+ std::async is moved outside the local scope, other code that uses the
3596
+ future must be aware that the future’s destructor may block for the
3597
+ shared state to become ready.
3598
 
3599
  *Synchronization:* Regardless of the provided `policy` argument,
3600
 
3601
  - the invocation of `async` synchronizes with ([[intro.multithread]])
3602
  the invocation of `f`. This statement applies even when the
 
3607
 
3608
  If the implementation chooses the `launch::async` policy,
3609
 
3610
  - a call to a waiting function on an asynchronous return object that
3611
  shares the shared state created by this `async` call shall block until
3612
+ the associated thread has completed, as if joined, or else time
3613
+ out ([[thread.thread.member]]);
3614
  - the associated thread completion synchronizes
3615
  with ([[intro.multithread]]) the return from the first function that
3616
  successfully detects the ready status of the shared state or with the
3617
  return from the last function that releases the shared state,
3618
  whichever happens first.
3619
 
3620
+ *Throws:* `system_error` if `policy == launch::async` and the
3621
  implementation is unable to start a new thread.
3622
 
3623
  *Error conditions:*
3624
 
3625
+ - `resource_unavailable_try_again` — if `policy == launch::async` and
3626
  the system is unable to start a new thread.
3627
 
 
 
 
3628
  ``` cpp
3629
  int work1(int value);
3630
  int work2(int value);
3631
  int work(int value) {
3632
  auto handle = std::async([=]{ return work2(value); });
 
3666
  template <class F, class Allocator>
3667
  explicit packaged_task(allocator_arg_t, const Allocator& a, F&& f);
3668
  ~packaged_task();
3669
 
3670
  // no copy
3671
+ packaged_task(const packaged_task&) = delete;
3672
+ packaged_task& operator=(const packaged_task&) = delete;
3673
 
3674
  // move support
3675
  packaged_task(packaged_task&& rhs) noexcept;
3676
  packaged_task& operator=(packaged_task&& rhs) noexcept;
3677
  void swap(packaged_task& other) noexcept;
 
3713
  *Requires:* *`INVOKE`*`(f, t1, t2, ..., tN, R)`, where `t1, t2, ..., tN`
3714
  are values of the corresponding types in `ArgTypes...`, shall be a valid
3715
  expression. Invoking a copy of `f` shall behave the same as invoking
3716
  `f`.
3717
 
3718
+ *Remarks:* These constructors shall not participate in overload
3719
+ resolution if `decay_t<F>` is the same type as
3720
+ `std::packaged_task<R(ArgTypes...)>`.
3721
+
3722
  *Effects:* constructs a new `packaged_task` object with a shared state
3723
  and initializes the object’s stored task with `std::forward<F>(f)`. The
3724
  constructors that take an `Allocator` argument use it to allocate memory
3725
  needed to store the internal data structures.
3726
 
 
3804
 
3805
  - `promise_already_satisfied` if the stored task has already been
3806
  invoked.
3807
  - `no_state` if `*this` has no shared state.
3808
 
 
 
 
 
 
 
 
 
 
 
3809
  ``` cpp
3810
  void make_ready_at_thread_exit(ArgTypes... args);
3811
  ```
3812
 
3813
  *Effects:* *`INVOKE`*`(f, t1, t2, ..., tN, R)`, where `f` is the stored
 
3867
  [atomics]: atomics.md#atomics
3868
  [basic.life]: basic.md#basic.life
3869
  [basic.stc.thread]: basic.md#basic.stc.thread
3870
  [bitmask.types]: library.md#bitmask.types
3871
  [class]: class.md#class
3872
+ [except.terminate]: except.md#except.terminate
3873
  [func.require]: utilities.md#func.require
3874
  [futures]: #futures
3875
  [futures.async]: #futures.async
3876
  [futures.errors]: #futures.errors
3877
  [futures.future_error]: #futures.future_error
 
3896
  [thread.decaycopy]: #thread.decaycopy
3897
  [thread.general]: #thread.general
3898
  [thread.lock]: #thread.lock
3899
  [thread.lock.algorithm]: #thread.lock.algorithm
3900
  [thread.lock.guard]: #thread.lock.guard
3901
+ [thread.lock.shared]: #thread.lock.shared
3902
+ [thread.lock.shared.cons]: #thread.lock.shared.cons
3903
+ [thread.lock.shared.locking]: #thread.lock.shared.locking
3904
+ [thread.lock.shared.mod]: #thread.lock.shared.mod
3905
+ [thread.lock.shared.obs]: #thread.lock.shared.obs
3906
  [thread.lock.unique]: #thread.lock.unique
3907
  [thread.lock.unique.cons]: #thread.lock.unique.cons
3908
  [thread.lock.unique.locking]: #thread.lock.unique.locking
3909
  [thread.lock.unique.mod]: #thread.lock.unique.mod
3910
  [thread.lock.unique.obs]: #thread.lock.unique.obs
 
3925
  [thread.req.lockable.req]: #thread.req.lockable.req
3926
  [thread.req.lockable.timed]: #thread.req.lockable.timed
3927
  [thread.req.native]: #thread.req.native
3928
  [thread.req.paramname]: #thread.req.paramname
3929
  [thread.req.timing]: #thread.req.timing
3930
+ [thread.sharedtimedmutex.class]: #thread.sharedtimedmutex.class
3931
+ [thread.sharedtimedmutex.requirements]: #thread.sharedtimedmutex.requirements
3932
  [thread.thread.algorithm]: #thread.thread.algorithm
3933
  [thread.thread.assign]: #thread.thread.assign
3934
  [thread.thread.class]: #thread.thread.class
3935
  [thread.thread.constr]: #thread.thread.constr
3936
  [thread.thread.destr]: #thread.thread.destr