From Jason Turner

[thread.latch]

C++17 → C++20 3.1 KB 119 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/tmp6o9xnlc3/{from.md → to.md} +116 -0
tmp/tmp6o9xnlc3/{from.md → to.md} RENAMED
@@ -0,0 +1,116 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### Latches <a id="thread.latch">[[thread.latch]]</a>
2
+
3
+ A latch is a thread coordination mechanism that allows any number of
4
+ threads to block until an expected number of threads arrive at the latch
5
+ (via the `count_down` function). The expected count is set when the
6
+ latch is created. An individual latch is a single-use object; once the
7
+ expected count has been reached, the latch cannot be reused.
8
+
9
+ #### Header `<latch>` synopsis <a id="latch.syn">[[latch.syn]]</a>
10
+
11
+ ``` cpp
12
+ namespace std {
13
+ class latch;
14
+ }
15
+ ```
16
+
17
+ #### Class `latch` <a id="thread.latch.class">[[thread.latch.class]]</a>
18
+
19
+ ``` cpp
20
+ namespace std {
21
+ class latch {
22
+ public:
23
+ static constexpr ptrdiff_t max() noexcept;
24
+
25
+ constexpr explicit latch(ptrdiff_t expected);
26
+ ~latch();
27
+
28
+ latch(const latch&) = delete;
29
+ latch& operator=(const latch&) = delete;
30
+
31
+ void count_down(ptrdiff_t update = 1);
32
+ bool try_wait() const noexcept;
33
+ void wait() const;
34
+ void arrive_and_wait(ptrdiff_t update = 1);
35
+
36
+ private:
37
+ ptrdiff_t counter; // exposition only
38
+ };
39
+ }
40
+ ```
41
+
42
+ A `latch` maintains an internal counter that is initialized when the
43
+ latch is created. Threads can block on the latch object, waiting for
44
+ counter to be decremented to zero.
45
+
46
+ Concurrent invocations of the member functions of `latch`, other than
47
+ its destructor, do not introduce data races.
48
+
49
+ ``` cpp
50
+ static constexpr ptrdiff_t max() noexcept;
51
+ ```
52
+
53
+ *Returns:* The maximum value of `counter` that the implementation
54
+ supports.
55
+
56
+ ``` cpp
57
+ constexpr explicit latch(ptrdiff_t expected);
58
+ ```
59
+
60
+ *Preconditions:* `expected >= 0` is `true` and `expected <= max()` is
61
+ `true`.
62
+
63
+ *Effects:* Initializes `counter` with `expected`.
64
+
65
+ *Throws:* Nothing.
66
+
67
+ ``` cpp
68
+ void count_down(ptrdiff_t update = 1);
69
+ ```
70
+
71
+ *Preconditions:* `update >= 0` is `true`, and `update <= counter` is
72
+ `true`.
73
+
74
+ *Effects:* Atomically decrements `counter` by `update`. If `counter` is
75
+ equal to zero, unblocks all threads blocked on `*this`.
76
+
77
+ *Synchronization:* Strongly happens before the returns from all calls
78
+ that are unblocked.
79
+
80
+ *Throws:* `system_error` when an exception is
81
+ required [[thread.req.exception]].
82
+
83
+ *Error conditions:* Any of the error conditions allowed for mutex
84
+ types [[thread.mutex.requirements.mutex]].
85
+
86
+ ``` cpp
87
+ bool try_wait() const noexcept;
88
+ ```
89
+
90
+ *Returns:* With very low probability `false`. Otherwise `counter == 0`.
91
+
92
+ ``` cpp
93
+ void wait() const;
94
+ ```
95
+
96
+ *Effects:* If `counter` equals zero, returns immediately. Otherwise,
97
+ blocks on `*this` until a call to `count_down` that decrements `counter`
98
+ to zero.
99
+
100
+ *Throws:* `system_error` when an exception is
101
+ required [[thread.req.exception]].
102
+
103
+ *Error conditions:* Any of the error conditions allowed for mutex
104
+ types [[thread.mutex.requirements.mutex]].
105
+
106
+ ``` cpp
107
+ void arrive_and_wait(ptrdiff_t update = 1);
108
+ ```
109
+
110
+ *Effects:* Equivalent to:
111
+
112
+ ``` cpp
113
+ count_down(update);
114
+ wait();
115
+ ```
116
+