From Jason Turner

[thread.sema.cnt]

C++17 → C++20 4.8 KB 140 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/tmpd1y3pvm1/{from.md → to.md} +137 -0
tmp/tmpd1y3pvm1/{from.md → to.md} RENAMED
@@ -0,0 +1,137 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### Class template `counting_semaphore` <a id="thread.sema.cnt">[[thread.sema.cnt]]</a>
2
+
3
+ ``` cpp
4
+ namespace std {
5
+ template<ptrdiff_t least_max_value = implementation-defined>
6
+ class counting_semaphore {
7
+ public:
8
+ static constexpr ptrdiff_t max() noexcept;
9
+
10
+ constexpr explicit counting_semaphore(ptrdiff_t desired);
11
+ ~counting_semaphore();
12
+
13
+ counting_semaphore(const counting_semaphore&) = delete;
14
+ counting_semaphore& operator=(const counting_semaphore&) = delete;
15
+
16
+ void release(ptrdiff_t update = 1);
17
+ void acquire();
18
+ bool try_acquire() noexcept;
19
+ template<class Rep, class Period>
20
+ bool try_acquire_for(const chrono::duration<Rep, Period>& rel_time);
21
+ template<class Clock, class Duration>
22
+ bool try_acquire_until(const chrono::time_point<Clock, Duration>& abs_time);
23
+
24
+ private:
25
+ ptrdiff_t counter; // exposition only
26
+ };
27
+ }
28
+ ```
29
+
30
+ Class template `counting_semaphore` maintains an internal counter that
31
+ is initialized when the semaphore is created. The counter is decremented
32
+ when a thread acquires the semaphore, and is incremented when a thread
33
+ releases the semaphore. If a thread tries to acquire the semaphore when
34
+ the counter is zero, the thread will block until another thread
35
+ increments the counter by releasing the semaphore.
36
+
37
+ `least_max_value` shall be non-negative; otherwise the program is
38
+ ill-formed.
39
+
40
+ Concurrent invocations of the member functions of `counting_semaphore`,
41
+ other than its destructor, do not introduce data races.
42
+
43
+ ``` cpp
44
+ static constexpr ptrdiff_t max() noexcept;
45
+ ```
46
+
47
+ *Returns:* The maximum value of `counter`. This value is greater than or
48
+ equal to `least_max_value`.
49
+
50
+ ``` cpp
51
+ constexpr explicit counting_semaphore(ptrdiff_t desired);
52
+ ```
53
+
54
+ *Preconditions:* `desired >= 0` is `true`, and `desired <= max()` is
55
+ `true`.
56
+
57
+ *Effects:* Initializes `counter` with `desired`.
58
+
59
+ *Throws:* Nothing.
60
+
61
+ ``` cpp
62
+ void release(ptrdiff_t update = 1);
63
+ ```
64
+
65
+ *Preconditions:* `update >= 0` is `true`, and
66
+ `update <= max() - counter` is `true`.
67
+
68
+ *Effects:* Atomically execute `counter += update`. Then, unblocks any
69
+ threads that are waiting for `counter` to be greater than zero.
70
+
71
+ *Synchronization:* Strongly happens before invocations of `try_acquire`
72
+ that observe the result of the effects.
73
+
74
+ *Throws:* `system_error` when an exception is
75
+ required [[thread.req.exception]].
76
+
77
+ *Error conditions:* Any of the error conditions allowed for mutex
78
+ types [[thread.mutex.requirements.mutex]].
79
+
80
+ ``` cpp
81
+ bool try_acquire() noexcept;
82
+ ```
83
+
84
+ *Effects:* Attempts to atomically decrement `counter` if it is positive,
85
+ without blocking. If `counter` is not decremented, there is no effect
86
+ and `try_acquire` immediately returns. An implementation may fail to
87
+ decrement `counter` even if it is positive.
88
+
89
+ [*Note 1*: This spurious failure is normally uncommon, but allows
90
+ interesting implementations based on a simple compare and
91
+ exchange [[atomics]]. — *end note*]
92
+
93
+ An implementation should ensure that `try_acquire` does not consistently
94
+ return `false` in the absence of contending semaphore operations.
95
+
96
+ *Returns:* `true` if `counter` was decremented, otherwise `false`.
97
+
98
+ ``` cpp
99
+ void acquire();
100
+ ```
101
+
102
+ *Effects:* Repeatedly performs the following steps, in order:
103
+
104
+ - Evaluates `try_acquire`. If the result is `true`, returns.
105
+ - Blocks on `*this` until `counter` is greater than zero.
106
+
107
+ *Throws:* `system_error` when an exception is
108
+ required [[thread.req.exception]].
109
+
110
+ *Error conditions:* Any of the error conditions allowed for mutex
111
+ types [[thread.mutex.requirements.mutex]].
112
+
113
+ ``` cpp
114
+ template<class Rep, class Period>
115
+ bool try_acquire_for(const chrono::duration<Rep, Period>& rel_time);
116
+ template<class Clock, class Duration>
117
+ bool try_acquire_until(const chrono::time_point<Clock, Duration>& abs_time);
118
+ ```
119
+
120
+ *Effects:* Repeatedly performs the following steps, in order:
121
+
122
+ - Evaluates `try_acquire()`. If the result is `true`, returns `true`.
123
+ - Blocks on `*this` until `counter` is greater than zero or until the
124
+ timeout expires. If it is unblocked by the timeout expiring, returns
125
+ `false`.
126
+
127
+ The timeout expires [[thread.req.timing]] when the current time is after
128
+ `abs_time` (for `try_acquire_until`) or when at least `rel_time` has
129
+ passed from the start of the function (for `try_acquire_for`).
130
+
131
+ *Throws:* Timeout-related exceptions [[thread.req.timing]], or
132
+ `system_error` when a non-timeout-related exception is
133
+ required [[thread.req.exception]].
134
+
135
+ *Error conditions:* Any of the error conditions allowed for mutex
136
+ types [[thread.mutex.requirements.mutex]].
137
+