From Jason Turner

[thread.barrier.class]

C++17 → C++20 6.7 KB 186 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpr2onk6fi/{from.md → to.md} +183 -0
tmp/tmpr2onk6fi/{from.md → to.md} RENAMED
@@ -0,0 +1,183 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #### Class template `barrier` <a id="thread.barrier.class">[[thread.barrier.class]]</a>
2
+
3
+ ``` cpp
4
+ namespace std {
5
+ template<class CompletionFunction = see below>
6
+ class barrier {
7
+ public:
8
+ using arrival_token = see below;
9
+
10
+ static constexpr ptrdiff_t max() noexcept;
11
+
12
+ constexpr explicit barrier(ptrdiff_t expected,
13
+ CompletionFunction f = CompletionFunction());
14
+ ~barrier();
15
+
16
+ barrier(const barrier&) = delete;
17
+ barrier& operator=(const barrier&) = delete;
18
+
19
+ [[nodiscard]] arrival_token arrive(ptrdiff_t update = 1);
20
+ void wait(arrival_token&& arrival) const;
21
+
22
+ void arrive_and_wait();
23
+ void arrive_and_drop();
24
+
25
+ private:
26
+ CompletionFunction completion; // exposition only
27
+ };
28
+ }
29
+ ```
30
+
31
+ Each *barrier phase* consists of the following steps:
32
+
33
+ - The expected count is decremented by each call to `arrive` or
34
+ `arrive_and_drop`.
35
+ - When the expected count reaches zero, the phase completion step is
36
+ run. For the specialization with the default value of the
37
+ `CompletionFunction` template parameter, the completion step is run as
38
+ part of the call to `arrive` or `arrive_and_drop` that caused the
39
+ expected count to reach zero. For other specializations, the
40
+ completion step is run on one of the threads that arrived at the
41
+ barrier during the phase.
42
+ - When the completion step finishes, the expected count is reset to what
43
+ was specified by the `expected` argument to the constructor, possibly
44
+ adjusted by calls to `arrive_and_drop`, and the next phase starts.
45
+
46
+ Each phase defines a *phase synchronization point*. Threads that arrive
47
+ at the barrier during the phase can block on the phase synchronization
48
+ point by calling `wait`, and will remain blocked until the phase
49
+ completion step is run.
50
+
51
+ The *phase completion step* that is executed at the end of each phase
52
+ has the following effects:
53
+
54
+ - Invokes the completion function, equivalent to `completion()`.
55
+ - Unblocks all threads that are blocked on the phase synchronization
56
+ point.
57
+
58
+ The end of the completion step strongly happens before the returns from
59
+ all calls that were unblocked by the completion step. For
60
+ specializations that do not have the default value of the
61
+ `CompletionFunction` template parameter, the behavior is undefined if
62
+ any of the barrier object’s member functions other than `wait` are
63
+ called while the completion step is in progress.
64
+
65
+ Concurrent invocations of the member functions of `barrier`, other than
66
+ its destructor, do not introduce data races. The member functions
67
+ `arrive` and `arrive_and_drop` execute atomically.
68
+
69
+ `CompletionFunction` shall meet the *Cpp17MoveConstructible* (
70
+ [[cpp17.moveconstructible]]) and *Cpp17Destructible* (
71
+ [[cpp17.destructible]]) requirements.
72
+ `is_nothrow_invocable_v<CompletionFunction&>` shall be `true`.
73
+
74
+ The default value of the `CompletionFunction` template parameter is an
75
+ unspecified type, such that, in addition to satisfying the requirements
76
+ of `CompletionFunction`, it meets the *Cpp17DefaultConstructible*
77
+ requirements ([[cpp17.defaultconstructible]]) and `completion()` has no
78
+ effects.
79
+
80
+ `barrier::arrival_token` is an unspecified type, such that it meets the
81
+ *Cpp17MoveConstructible* ([[cpp17.moveconstructible]]),
82
+ *Cpp17MoveAssignable* ([[cpp17.moveassignable]]), and
83
+ *Cpp17Destructible* ([[cpp17.destructible]]) requirements.
84
+
85
+ ``` cpp
86
+ static constexpr ptrdiff_t max() noexcept;
87
+ ```
88
+
89
+ *Returns:* The maximum expected count that the implementation supports.
90
+
91
+ ``` cpp
92
+ constexpr explicit barrier(ptrdiff_t expected,
93
+ CompletionFunction f = CompletionFunction());
94
+ ```
95
+
96
+ *Preconditions:* `expected >= 0` is `true` and `expected <= max()` is
97
+ `true`.
98
+
99
+ *Effects:* Sets both the initial expected count for each barrier phase
100
+ and the current expected count for the first phase to `expected`.
101
+ Initializes `completion` with `std::move(f)`. Starts the first phase.
102
+
103
+ [*Note 1*: If `expected` is 0 this object can only be
104
+ destroyed. — *end note*]
105
+
106
+ *Throws:* Any exception thrown by `CompletionFunction`’s move
107
+ constructor.
108
+
109
+ ``` cpp
110
+ [[nodiscard]] arrival_token arrive(ptrdiff_t update = 1);
111
+ ```
112
+
113
+ *Preconditions:* `update > 0` is `true`, and `update` is less than or
114
+ equal to the expected count for the current barrier phase.
115
+
116
+ *Effects:* Constructs an object of type `arrival_token` that is
117
+ associated with the phase synchronization point for the current phase.
118
+ Then, decrements the expected count by `update`.
119
+
120
+ *Synchronization:* The call to `arrive` strongly happens before the
121
+ start of the phase completion step for the current phase.
122
+
123
+ *Returns:* The constructed `arrival_token` object.
124
+
125
+ *Throws:* `system_error` when an exception is
126
+ required [[thread.req.exception]].
127
+
128
+ *Error conditions:* Any of the error conditions allowed for mutex
129
+ types [[thread.mutex.requirements.mutex]].
130
+
131
+ [*Note 2*: This call can cause the completion step for the current
132
+ phase to start. — *end note*]
133
+
134
+ ``` cpp
135
+ void wait(arrival_token&& arrival) const;
136
+ ```
137
+
138
+ *Preconditions:* `arrival` is associated with the phase synchronization
139
+ point for the current phase or the immediately preceding phase of the
140
+ same barrier object.
141
+
142
+ *Effects:* Blocks at the synchronization point associated with
143
+ `std::move(arrival)` until the phase completion step of the
144
+ synchronization point’s phase is run.
145
+
146
+ [*Note 3*: If `arrival` is associated with the synchronization point
147
+ for a previous phase, the call returns immediately. — *end note*]
148
+
149
+ *Throws:* `system_error` when an exception is
150
+ required [[thread.req.exception]].
151
+
152
+ *Error conditions:* Any of the error conditions allowed for mutex
153
+ types [[thread.mutex.requirements.mutex]].
154
+
155
+ ``` cpp
156
+ void arrive_and_wait();
157
+ ```
158
+
159
+ *Effects:* Equivalent to: `wait(arrive())`.
160
+
161
+ ``` cpp
162
+ void arrive_and_drop();
163
+ ```
164
+
165
+ *Preconditions:* The expected count for the current barrier phase is
166
+ greater than zero.
167
+
168
+ *Effects:* Decrements the initial expected count for all subsequent
169
+ phases by one. Then decrements the expected count for the current phase
170
+ by one.
171
+
172
+ *Synchronization:* The call to `arrive_and_drop` strongly happens before
173
+ the start of the phase completion step for the current phase.
174
+
175
+ *Throws:* `system_error` when an exception is
176
+ required [[thread.req.exception]].
177
+
178
+ *Error conditions:* Any of the error conditions allowed for mutex
179
+ types [[thread.mutex.requirements.mutex]].
180
+
181
+ [*Note 4*: This call can cause the completion step for the current
182
+ phase to start. — *end note*]
183
+