From Jason Turner

[stoptoken.concepts]

C++23 → Trunk 9.2 KB 187 lines
Current Draft | LaTeX Source
Archived: C++23
Markdown: C++23 | Trunk
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpfl6zwa1g/{from.md → to.md} +184 -0
tmp/tmpfl6zwa1g/{from.md → to.md} RENAMED
@@ -0,0 +1,184 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### Stop token concepts <a id="stoptoken.concepts">[[stoptoken.concepts]]</a>
2
+
3
+ The exposition-only `stoppable-callback-for` concept checks for a
4
+ callback compatible with a given `Token` type.
5
+
6
+ ``` cpp
7
+ template<class CallbackFn, class Token, class Initializer = CallbackFn>
8
+ concept stoppable-callback-for = // exposition only
9
+ invocable<CallbackFn> &&
10
+ constructible_from<CallbackFn, Initializer> &&
11
+ requires { typename stop_callback_for_t<Token, CallbackFn>; } &&
12
+ constructible_from<stop_callback_for_t<Token, CallbackFn>, const Token&, Initializer>;
13
+ ```
14
+
15
+ Let `t` and `u` be distinct, valid objects of type `Token` that
16
+ reference the same logical stop state; let `init` be an expression such
17
+ that `same_as<decltype(init), Initializer>` is `true`; and let `SCB`
18
+ denote the type `stop_callback_for_t<Token, CallbackFn>`.
19
+
20
+ The concept `stoppable-callback-for<CallbackFn, Token, Initializer>` is
21
+ modeled only if:
22
+
23
+ - The following concepts are modeled:
24
+ - `\texttt{constructible_from}<SCB, Token, Initializer>`
25
+ - `\texttt{constructible_from}<SCB, Token&, Initializer>`
26
+ - `\texttt{constructible_from}<SCB, const Token, Initializer>`
27
+ - An object of type `SCB` has an associated callback function of type
28
+ `CallbackFn`. Let `scb` be an object of type `SCB` and let
29
+ `callback_fn` denote `scb`’s associated callback function.
30
+ Direct-non-list-initializing `scb` from arguments `t` and `init` shall
31
+ execute a *stoppable callback registration* as follows:
32
+ - If `t.stop_possible()` is `true`:
33
+ - `callback_fn` shall be direct-initialized with `init`.
34
+ - Construction of `scb` shall only throw exceptions thrown by the
35
+ initialization of `callback_fn` from `init`.
36
+ - The callback invocation `std::forward<CallbackFn>(callback_fn)()`
37
+ shall be registered with `t`’s associated stop state as follows:
38
+ - If `t.stop_requested()` evaluates to `false` at the time of
39
+ registration, the callback invocation is added to the stop
40
+ state’s list of callbacks such that
41
+ `std::forward<CallbackFn>( callback_fn)()` is evaluated if a
42
+ stop request is made on the stop state.
43
+ - Otherwise, `std::forward<CallbackFn>(callback_fn)()` shall be
44
+ immediately evaluated on the thread executing `scb`’s
45
+ constructor, and the callback invocation shall not be added to
46
+ the list of callback invocations.
47
+
48
+ If the callback invocation was added to stop state’s list of
49
+ callbacks, `scb` shall be associated with the stop state.
50
+ - \[*Note 1*: If `t.stop_possible()` is `false`, there is no
51
+ requirement that the initialization of `scb` causes the
52
+ initialization of `callback_fn`. — *end note*]
53
+ - Destruction of `scb` shall execute a
54
+ *stoppable callback deregistration* as follows (in order):
55
+ - If the constructor of `scb` did not register a callback invocation
56
+ with `t`’s stop state, then the stoppable callback deregistration
57
+ shall have no effect other than destroying `callback_fn` if it was
58
+ constructed.
59
+ - Otherwise, the invocation of `callback_fn` shall be removed from the
60
+ associated stop state.
61
+ - If `callback_fn` is concurrently executing on another thread, then
62
+ the stoppable callback deregistration shall block [[defns.block]]
63
+ until the invocation of `callback_fn` returns such that the return
64
+ from the invocation of `callback_fn` strongly happens before
65
+ [[intro.races]] the destruction of `callback_fn`.
66
+ - If `callback_fn` is executing on the current thread, then the
67
+ destructor shall not block waiting for the return from the
68
+ invocation of `callback_fn`.
69
+ - A stoppable callback deregistration shall not block on the
70
+ completion of the invocation of some other callback registered with
71
+ the same logical stop state.
72
+ - The stoppable callback deregistration shall destroy `callback_fn`.
73
+
74
+ The `stoppable_token` concept checks for the basic interface of a stop
75
+ token that is copyable and allows polling to see if stop has been
76
+ requested and also whether a stop request is possible. The
77
+ `unstoppable_token` concept checks for a `stoppable_token` type that
78
+ does not allow stopping.
79
+
80
+ ``` cpp
81
+ template<template<class> class>
82
+ struct check-type-alias-exists; // exposition only
83
+
84
+ template<class Token>
85
+ concept stoppable_token =
86
+ requires (const Token tok) {
87
+ typename check-type-alias-exists<Token::template callback_type>;
88
+ { tok.stop_requested() } noexcept -> same_as<bool>;
89
+ { tok.stop_possible() } noexcept -> same_as<bool>;
90
+ { Token(tok) } noexcept; // see implicit expression variations[concepts.equality]
91
+ } &&
92
+ copyable<Token> &&
93
+ equality_comparable<Token>;
94
+
95
+ template<class Token>
96
+ concept unstoppable_token =
97
+ stoppable_token<Token> &&
98
+ requires (const Token tok) {
99
+ requires bool_constant<(!tok.stop_possible())>::value;
100
+ };
101
+ ```
102
+
103
+ An object whose type models `stoppable_token` has at most one associated
104
+ logical stop state. A `stoppable_token` object with no associated stop
105
+ state is said to be *disengaged*.
106
+
107
+ Let `SP` be an evaluation of `t.stop_possible()` that is `false`, and
108
+ let SR be an evaluation of `t.stop_requested()` that is `true`.
109
+
110
+ The type `Token` models `stoppable_token` only if:
111
+
112
+ - Any evaluation of `u.stop_possible()` or `u.stop_requested()` that
113
+ happens after [[intro.races]] `SP` is `false`.
114
+ - Any evaluation of `u.stop_possible()` or `u.stop_requested()` that
115
+ happens after `SR` is `true`.
116
+ - For any types `CallbackFn` and `Initializer` such that
117
+ `stoppable-callback-for<CallbackFn, Token, Initializer>` is satisfied,
118
+ `stoppable-callback-for<CallbackFn, Token, Initializer>` is modeled.
119
+ - If `t` is disengaged, evaluations of `t.stop_possible()` and
120
+ `t.stop_requested()` are `false`.
121
+ - If `t` and `u` reference the same stop state, or if both `t` and `u`
122
+ are disengaged, `t == u` is `true`; otherwise, it is `false`.
123
+
124
+ An object whose type models the exposition-only `stoppable-source`
125
+ concept can be queried whether stop has been requested
126
+ (`stop_requested`) and whether stop is possible (`stop_possible`). It is
127
+ a factory for associated stop tokens (`get_token`), and a stop request
128
+ can be made on it (`request_stop`). It maintains a list of registered
129
+ stop callback invocations that it executes when a stop request is first
130
+ made.
131
+
132
+ ``` cpp
133
+ template<class Source>
134
+ concept stoppable-source = // exposition only
135
+ requires (Source& src, const Source csrc) { // see implicit expression variations[concepts.equality]
136
+ { csrc.get_token() } -> stoppable_token;
137
+ { csrc.stop_possible() } noexcept -> same_as<bool>;
138
+ { csrc.stop_requested() } noexcept -> same_as<bool>;
139
+ { src.request_stop() } -> same_as<bool>;
140
+ };
141
+ ```
142
+
143
+ An object whose type models `stoppable-source` has at most one
144
+ associated logical stop state. If it has no associated stop state, it is
145
+ said to be disengaged. Let `s` be an object whose type models
146
+ `stoppable-source` and that is disengaged. `s.stop_possible()` and
147
+ `s.stop_requested()` shall be `false`.
148
+
149
+ Let `t` be an object whose type models `stoppable-source`. If `t` is
150
+ disengaged, `t.get_token()` shall return a disengaged stop token;
151
+ otherwise, it shall return a stop token that is associated with the stop
152
+ state of `t`.
153
+
154
+ Calls to the member functions `request_stop`, `stop_requested`, and
155
+ `stop_possible` and similarly named member functions on associated
156
+ `stoppable_token` objects do not introduce data races. A call to
157
+ `request_stop` that returns `true` synchronizes with a call to
158
+ `stop_requested` on an associated `stoppable_token` or
159
+ `stoppable-source` object that returns `true`. Registration of a
160
+ callback synchronizes with the invocation of that callback.
161
+
162
+ If the `stoppable-source` is disengaged, `request_stop` shall have no
163
+ effect and return `false`. Otherwise, it shall execute a
164
+ *stop request operation* on the associated stop state. A stop request
165
+ operation determines whether the stop state has received a stop request,
166
+ and if not, makes a stop request. The determination and making of the
167
+ stop request shall happen atomically, as-if by a read-modify-write
168
+ operation [[intro.races]]. If the request was made, the stop state’s
169
+ registered callback invocations shall be synchronously executed. If an
170
+ invocation of a callback exits via an exception then `terminate` shall
171
+ be invoked [[except.terminate]].
172
+
173
+ [*Note 2*: No constraint is placed on the order in which the callback
174
+ invocations are executed. — *end note*]
175
+
176
+ `request_stop` shall return `true` if a stop request was made, and
177
+ `false` otherwise. After a call to `request_stop` either a call to
178
+ `stop_possible` shall return `false` or a call to `stop_requested` shall
179
+ return `true`.
180
+
181
+ [*Note 3*: A stop request includes notifying all condition variables of
182
+ type `condition_variable_any` temporarily registered during an
183
+ interruptible wait [[thread.condvarany.intwait]]. — *end note*]
184
+