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

Files changed (1) hide show

tmp/tmpdhoornq7/{from.md → to.md} +325 -0

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

	@@ -0,0 +1,325 @@

+## Coordination types <a id="thread.coord">[[thread.coord]]</a>
+This subclause describes various concepts related to thread
+coordination, and defines the coordination types `latch` and `barrier`.
+These types facilitate concurrent computation performed by a number of
+threads.
+### Latches <a id="thread.latch">[[thread.latch]]</a>
+A latch is a thread coordination mechanism that allows any number of
+threads to block until an expected number of threads arrive at the latch
+(via the `count_down` function). The expected count is set when the
+latch is created. An individual latch is a single-use object; once the
+expected count has been reached, the latch cannot be reused.
+#### Header `<latch>` synopsis <a id="latch.syn">[[latch.syn]]</a>
+``` cpp
+namespace std {
+  class latch;
+}
+```
+#### Class `latch` <a id="thread.latch.class">[[thread.latch.class]]</a>
+``` cpp
+namespace std {
+  class latch {
+  public:
+    static constexpr ptrdiff_t max() noexcept;
+    constexpr explicit latch(ptrdiff_t expected);
+    ~latch();
+    latch(const latch&) = delete;
+    latch& operator=(const latch&) = delete;
+    void count_down(ptrdiff_t update = 1);
+    bool try_wait() const noexcept;
+    void wait() const;
+    void arrive_and_wait(ptrdiff_t update = 1);
+  private:
+    ptrdiff_t counter;  // exposition only
+  };
+}
+```
+A `latch` maintains an internal counter that is initialized when the
+latch is created. Threads can block on the latch object, waiting for
+counter to be decremented to zero.
+Concurrent invocations of the member functions of `latch`, other than
+its destructor, do not introduce data races.
+``` cpp
+static constexpr ptrdiff_t max() noexcept;
+```
+*Returns:* The maximum value of `counter` that the implementation
+supports.
+``` cpp
+constexpr explicit latch(ptrdiff_t expected);
+```
+*Preconditions:* `expected >= 0` is `true` and `expected <= max()` is
+`true`.
+*Effects:* Initializes `counter` with `expected`.
+*Throws:* Nothing.
+``` cpp
+void count_down(ptrdiff_t update = 1);
+```
+*Preconditions:* `update >= 0` is `true`, and `update <= counter` is
+`true`.
+*Effects:* Atomically decrements `counter` by `update`. If `counter` is
+equal to zero, unblocks all threads blocked on `*this`.
+*Synchronization:* Strongly happens before the returns from all calls
+that are unblocked.
+*Throws:* `system_error` when an exception is
+required [[thread.req.exception]].
+*Error conditions:* Any of the error conditions allowed for mutex
+types [[thread.mutex.requirements.mutex]].
+``` cpp
+bool try_wait() const noexcept;
+```
+*Returns:* With very low probability `false`. Otherwise `counter == 0`.
+``` cpp
+void wait() const;
+```
+*Effects:* If `counter` equals zero, returns immediately. Otherwise,
+blocks on `*this` until a call to `count_down` that decrements `counter`
+to zero.
+*Throws:* `system_error` when an exception is
+required [[thread.req.exception]].
+*Error conditions:* Any of the error conditions allowed for mutex
+types [[thread.mutex.requirements.mutex]].
+``` cpp
+void arrive_and_wait(ptrdiff_t update = 1);
+```
+*Effects:* Equivalent to:
+``` cpp
+count_down(update);
+wait();
+```
+### Barriers <a id="thread.barrier">[[thread.barrier]]</a>
+A barrier is a thread coordination mechanism whose lifetime consists of
+a sequence of barrier phases, where each phase allows at most an
+expected number of threads to block until the expected number of threads
+arrive at the barrier.
+[*Note 1*: A barrier is useful for managing repeated tasks that are
+handled by multiple threads. — *end note*]
+#### Header `<barrier>` synopsis <a id="barrier.syn">[[barrier.syn]]</a>
+``` cpp
+namespace std {
+  template<class CompletionFunction = see below>
+    class barrier;
+}
+```
+#### Class template `barrier` <a id="thread.barrier.class">[[thread.barrier.class]]</a>
+``` cpp
+namespace std {
+  template<class CompletionFunction = see below>
+  class barrier {
+  public:
+    using arrival_token = see below;
+    static constexpr ptrdiff_t max() noexcept;
+    constexpr explicit barrier(ptrdiff_t expected,
+                               CompletionFunction f = CompletionFunction());
+    ~barrier();
+    barrier(const barrier&) = delete;
+    barrier& operator=(const barrier&) = delete;
+    [[nodiscard]] arrival_token arrive(ptrdiff_t update = 1);
+    void wait(arrival_token&& arrival) const;
+    void arrive_and_wait();
+    void arrive_and_drop();
+  private:
+    CompletionFunction completion;      // exposition only
+  };
+}
+```
+Each *barrier phase* consists of the following steps:
+- The expected count is decremented by each call to `arrive` or
+  `arrive_and_drop`.
+- When the expected count reaches zero, the phase completion step is
+  run. For the specialization with the default value of the
+  `CompletionFunction` template parameter, the completion step is run as
+  part of the call to `arrive` or `arrive_and_drop` that caused the
+  expected count to reach zero. For other specializations, the
+  completion step is run on one of the threads that arrived at the
+  barrier during the phase.
+- When the completion step finishes, the expected count is reset to what
+  was specified by the `expected` argument to the constructor, possibly
+  adjusted by calls to `arrive_and_drop`, and the next phase starts.
+Each phase defines a *phase synchronization point*. Threads that arrive
+at the barrier during the phase can block on the phase synchronization
+point by calling `wait`, and will remain blocked until the phase
+completion step is run.
+The *phase completion step* that is executed at the end of each phase
+has the following effects:
+- Invokes the completion function, equivalent to `completion()`.
+- Unblocks all threads that are blocked on the phase synchronization
+  point.
+The end of the completion step strongly happens before the returns from
+all calls that were unblocked by the completion step. For
+specializations that do not have the default value of the
+`CompletionFunction` template parameter, the behavior is undefined if
+any of the barrier object’s member functions other than `wait` are
+called while the completion step is in progress.
+Concurrent invocations of the member functions of `barrier`, other than
+its destructor, do not introduce data races. The member functions
+`arrive` and `arrive_and_drop` execute atomically.
+`CompletionFunction` shall meet the *Cpp17MoveConstructible* (
+[[cpp17.moveconstructible]]) and *Cpp17Destructible* (
+[[cpp17.destructible]]) requirements.
+`is_nothrow_invocable_v<CompletionFunction&>` shall be `true`.
+The default value of the `CompletionFunction` template parameter is an
+unspecified type, such that, in addition to satisfying the requirements
+of `CompletionFunction`, it meets the *Cpp17DefaultConstructible*
+requirements ([[cpp17.defaultconstructible]]) and `completion()` has no
+effects.
+`barrier::arrival_token` is an unspecified type, such that it meets the
+*Cpp17MoveConstructible* ([[cpp17.moveconstructible]]),
+*Cpp17MoveAssignable* ([[cpp17.moveassignable]]), and
+*Cpp17Destructible* ([[cpp17.destructible]]) requirements.
+``` cpp
+static constexpr ptrdiff_t max() noexcept;
+```
+*Returns:* The maximum expected count that the implementation supports.
+``` cpp
+constexpr explicit barrier(ptrdiff_t expected,
+                           CompletionFunction f = CompletionFunction());
+```
+*Preconditions:* `expected >= 0` is `true` and `expected <= max()` is
+`true`.
+*Effects:* Sets both the initial expected count for each barrier phase
+and the current expected count for the first phase to `expected`.
+Initializes `completion` with `std::move(f)`. Starts the first phase.
+[*Note 1*: If `expected` is 0 this object can only be
+destroyed. — *end note*]
+*Throws:* Any exception thrown by `CompletionFunction`’s move
+constructor.
+``` cpp
+[[nodiscard]] arrival_token arrive(ptrdiff_t update = 1);
+```
+*Preconditions:* `update > 0` is `true`, and `update` is less than or
+equal to the expected count for the current barrier phase.
+*Effects:* Constructs an object of type `arrival_token` that is
+associated with the phase synchronization point for the current phase.
+Then, decrements the expected count by `update`.
+*Synchronization:* The call to `arrive` strongly happens before the
+start of the phase completion step for the current phase.
+*Returns:* The constructed `arrival_token` object.
+*Throws:* `system_error` when an exception is
+required [[thread.req.exception]].
+*Error conditions:* Any of the error conditions allowed for mutex
+types [[thread.mutex.requirements.mutex]].
+[*Note 2*: This call can cause the completion step for the current
+phase to start. — *end note*]
+``` cpp
+void wait(arrival_token&& arrival) const;
+```
+*Preconditions:* `arrival` is associated with the phase synchronization
+point for the current phase or the immediately preceding phase of the
+same barrier object.
+*Effects:* Blocks at the synchronization point associated with
+`std::move(arrival)` until the phase completion step of the
+synchronization point’s phase is run.
+[*Note 3*: If `arrival` is associated with the synchronization point
+for a previous phase, the call returns immediately. — *end note*]
+*Throws:* `system_error` when an exception is
+required [[thread.req.exception]].
+*Error conditions:* Any of the error conditions allowed for mutex
+types [[thread.mutex.requirements.mutex]].
+``` cpp
+void arrive_and_wait();
+```
+*Effects:* Equivalent to: `wait(arrive())`.
+``` cpp
+void arrive_and_drop();
+```
+*Preconditions:* The expected count for the current barrier phase is
+greater than zero.
+*Effects:* Decrements the initial expected count for all subsequent
+phases by one. Then decrements the expected count for the current phase
+by one.
+*Synchronization:* The call to `arrive_and_drop` strongly happens before
+the start of the phase completion step for the current phase.
+*Throws:* `system_error` when an exception is
+required [[thread.req.exception]].
+*Error conditions:* Any of the error conditions allowed for mutex
+types [[thread.mutex.requirements.mutex]].
+[*Note 4*: This call can cause the completion step for the current
+phase to start. — *end note*]

Diff to HTML by rtfpessoa