Executor1.html
20.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Executor requirements</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="../../index.html" title="Asio">
<link rel="up" href="../reference.html" title="Reference">
<link rel="prev" href="ExecutionContext.html" title="Execution context requirements">
<link rel="next" href="GettableSerialPortOption.html" title="Gettable serial port option requirements">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="asio C++ library" width="250" height="60" src="../../asio.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="ExecutionContext.html"><img src="../../prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../home.png" alt="Home"></a><a accesskey="n" href="GettableSerialPortOption.html"><img src="../../next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="asio.reference.Executor1"></a><a class="link" href="Executor1.html" title="Executor requirements">Executor requirements</a>
</h3></div></div></div>
<h5>
<a name="asio.reference.Executor1.h0"></a>
<span><a name="asio.reference.Executor1.standard_executors"></a></span><a class="link" href="Executor1.html#asio.reference.Executor1.standard_executors">Standard
executors</a>
</h5>
<p>
Let <code class="computeroutput">executor-of-impl</code> be the exposition-only concept
</p>
<pre class="programlisting">template<class E, class F>
concept executor-of-impl =
invocable<decay_t<F>&> &&
constructible_from<decay_t<F>, F> &&
move_constructible<decay_t<F>> &&
copy_constructible<E> &&
is_nothrow_copy_constructible_v<E> &&
equality_comparable<E> /* nothrow */ &&
requires(const E& e, F&& f) {
execution::execute(e, (F&&)f);
};
</pre>
<p>
Then the <code class="computeroutput">executor</code> and <code class="computeroutput">executor_of</code> concepts are
defined as follows:
</p>
<pre class="programlisting">template<class E>
concept executor =
executor-of-impl<E, execution::invocable_archetype>;
template<class E, class F>
concept executor_of =
executor<E> &&
executor-of-impl<E, F>;
</pre>
<p>
Neither an executor's equality comparison nor <code class="computeroutput">swap</code> operation
shall exit via an exception.
</p>
<p>
None of an executor type's copy constructor, destructor, equality comparison,
<code class="computeroutput">swap</code> function, <code class="computeroutput">execute</code> function, or associated
<code class="computeroutput">query</code> functions shall introduce data races as a result of concurrent
invocations of those functions from different threads.
</p>
<p>
For any two (possibly const) values <code class="computeroutput">x1</code> and <code class="computeroutput">x2</code> of
some executor type <code class="computeroutput">X</code>, <code class="computeroutput">x1 == x2</code> shall return <code class="computeroutput">true</code>
only if <code class="computeroutput">asio::query(x1,p) == asio::query(x2,p)</code> for every property
<code class="computeroutput">p</code> where both <code class="computeroutput">asio::query(x1,p)</code> and <code class="computeroutput">asio::query(x2,p)</code>
are well-formed and result in a non-void type that is <code class="computeroutput">equality_comparable</code>
(C++Std [equalitycomparable]). [<span class="emphasis"><em>Note:</em></span> The above requirements
imply that <code class="computeroutput">x1 == x2</code> returns <code class="computeroutput">true</code> if <code class="computeroutput">x1</code>
and <code class="computeroutput">x2</code> can be interchanged with identical effects. An executor
may conceptually contain additional properties which are not exposed by a
named property type that can be observed via <code class="computeroutput">asio::query</code>; in
this case, it is up to the concrete executor implementation to decide if
these properties affect equality. Returning <code class="computeroutput">false</code> does not necessarily
imply that the effects are not identical. —<span class="emphasis"><em>end note</em></span>]
</p>
<p>
An executor type's destructor shall not block pending completion of the submitted
function objects. [<span class="emphasis"><em>Note:</em></span> The ability to wait for completion
of submitted function objects may be provided by the associated execution
context. —<span class="emphasis"><em>end note</em></span>]
</p>
<p>
In addition to the above requirements, types <code class="computeroutput">E</code> and <code class="computeroutput">F</code>
model <code class="computeroutput">executor_of</code> only if they satisfy the requirements of the
Table below.
</p>
<p>
Let:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<code class="computeroutput">e</code> denotes a (possibly const) executor object of type <code class="computeroutput">E</code>,
</li>
<li class="listitem">
<code class="computeroutput">cf</code> denotes the function object <code class="computeroutput">DECAY_COPY(std::forward<F>(f))</code>
</li>
<li class="listitem">
<code class="computeroutput">f</code> denotes a function of type <code class="computeroutput">F&&</code> invocable
as <code class="computeroutput">cf()</code> and where <code class="computeroutput">decay_t<F></code> models
<code class="computeroutput">move_constructible</code>.
</li>
</ul></div>
<p>
The expression <code class="computeroutput">execution::execute(e, f)</code>:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
Evaluates <code class="computeroutput">DECAY_COPY(std::forward<F>(f))</code> on the calling
thread to create <code class="computeroutput">cf</code> that will be invoked at most once by
an execution agent.
</li>
<li class="listitem">
May block pending completion of this invocation. Synchronizes with [intro.multithread]
the invocation of <code class="computeroutput">f</code>.
</li>
<li class="listitem">
Shall not propagate any exception thrown by the function object or any
other function submitted to the executor.
</li>
</ul></div>
<p>
[<span class="emphasis"><em>Note:</em></span> The treatment of exceptions thrown by one-way
submitted functions is implementation-defined. The forward progress guarantee
of the associated execution agent(s) is implementation-defined. —<span class="emphasis"><em>end
note</em></span>]
</p>
<h5>
<a name="asio.reference.Executor1.h1"></a>
<span><a name="asio.reference.Executor1.networking_ts_style_executors"></a></span><a class="link" href="Executor1.html#asio.reference.Executor1.networking_ts_style_executors">Networking
TS-style executors</a>
</h5>
<p>
The library describes a standard set of requirements for <span class="emphasis"><em>executors</em></span>.
A type meeting the <code class="computeroutput">Executor</code> requirements embodies a set of rules
for determining how submitted function objects are to be executed.
</p>
<p>
A type <code class="computeroutput">X</code> meets the <code class="computeroutput">Executor</code> requirements if it
satisfies the requirements of <code class="computeroutput">CopyConstructible</code> (C++Std [copyconstructible])
and <code class="computeroutput">Destructible</code> (C++Std [destructible]), as well as the additional
requirements listed below.
</p>
<p>
No constructor, comparison operator, copy operation, move operation, swap
operation, or member functions <code class="computeroutput">context</code>, <code class="computeroutput">on_work_started</code>,
and <code class="computeroutput">on_work_finished</code> on these types shall exit via an exception.
</p>
<p>
The executor copy constructor, comparison operators, and other member functions
defined in these requirements shall not introduce data races as a result
of concurrent calls to those functions from different threads.
</p>
<p>
Let <code class="computeroutput">ctx</code> be the execution context returned by the executor's
<code class="computeroutput">context()</code> member function. An executor becomes <span class="emphasis"><em>invalid</em></span>
when the first call to <code class="computeroutput">ctx.shutdown()</code> returns. The effect of
calling <code class="computeroutput">on_work_started</code>, <code class="computeroutput">on_work_finished</code>, <code class="computeroutput">dispatch</code>,
<code class="computeroutput">post</code>, or <code class="computeroutput">defer</code> on an invalid executor is undefined.
[<span class="emphasis"><em>Note:</em></span> The copy constructor, comparison operators, and
<code class="computeroutput">context()</code> member function continue to remain valid until <code class="computeroutput">ctx</code>
is destroyed. —<span class="emphasis"><em>end note</em></span>]
</p>
<p>
In the table below, <code class="computeroutput">x1</code> and <code class="computeroutput">x2</code> denote (possibly
const) values of type <code class="computeroutput">X</code>, <code class="computeroutput">mx1</code> denotes an xvalue
of type <code class="computeroutput">X</code>, <code class="computeroutput">f</code> denotes a <code class="computeroutput">MoveConstructible</code>
(C++Std [moveconstructible]) function object callable with zero arguments,
<code class="computeroutput">a</code> denotes a (possibly const) value of type <code class="computeroutput">A</code> meeting
the <code class="computeroutput">Allocator</code> requirements (C++Std [allocator.requirements]),
and <code class="computeroutput">u</code> denotes an identifier.
</p>
<div class="table">
<a name="asio.reference.Executor1.t0"></a><p class="title"><b>Table 15. Executor requirements</b></p>
<div class="table-contents"><table class="table" summary="Executor requirements">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
expression
</p>
</th>
<th>
<p>
type
</p>
</th>
<th>
<p>
assertion/note<br> pre/post-conditions
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput">X u(x1);</code>
</p>
</td>
<td>
</td>
<td>
<p>
Shall not exit via an exception.<br> <br> post: <code class="computeroutput">u ==
x1</code> and <code class="computeroutput">std::addressof(u.context()) == std::addressof(x1.context()).</code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">X u(mx1);</code>
</p>
</td>
<td>
</td>
<td>
<p>
Shall not exit via an exception.<br> <br> post: <code class="computeroutput">u</code>
equals the prior value of <code class="computeroutput">mx1</code> and <code class="computeroutput">std::addressof(u.context())</code>
equals the prior value of <code class="computeroutput">std::addressof(mx1.context())</code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1 == x2</code>
</p>
</td>
<td>
<p>
<code class="computeroutput">bool</code>
</p>
</td>
<td>
<p>
Returns <code class="computeroutput">true</code> only if <code class="computeroutput">x1</code> and <code class="computeroutput">x2</code>
can be interchanged with identical effects in any of the expressions
defined in these type requirements. [<span class="emphasis"><em>Note:</em></span>
Returning <code class="computeroutput">false</code> does not necessarily imply that the
effects are not identical. —<span class="emphasis"><em>end note</em></span>] <br>
<br> <code class="computeroutput">operator==</code> shall be reflexive, symmetric, and
transitive, and shall not exit via an exception.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1 != x2</code>
</p>
</td>
<td>
<p>
<code class="computeroutput">bool</code>
</p>
</td>
<td>
<p>
Same as <code class="computeroutput">!(x1 == x2)</code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1.context()</code>
</p>
</td>
<td>
<p>
<code class="computeroutput">execution_context&</code>, or <code class="computeroutput">E&</code> where
<code class="computeroutput">E</code> is a type that satifisfies the <a class="link" href="ExecutionContext.html" title="Execution context requirements"><code class="computeroutput">ExecutionContext</code></a>
requirements.
</p>
</td>
<td>
<p>
Shall not exit via an exception.<br> <br> The comparison operators
and member functions defined in these requirements shall not alter
the reference returned by this function.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1.on_work_started()</code>
</p>
</td>
<td>
</td>
<td>
<p>
Shall not exit via an exception.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1.on_work_finished()</code>
</p>
</td>
<td>
</td>
<td>
<p>
Shall not exit via an exception.<br> <br> Precondition: A preceding
call <code class="computeroutput">x2.on_work_started()</code> where <code class="computeroutput">x1 == x2</code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1.dispatch(std::move(f),a)</code>
</p>
</td>
<td>
</td>
<td>
<p>
Effects: Creates an object <code class="computeroutput">f1</code> initialized with <code class="literal"><span class="emphasis"><em>DECAY_COPY</em></span></code><code class="computeroutput">(forward<Func>(f))</code>
(C++Std [thread.decaycopy]) in the current thread of execution
. Calls <code class="computeroutput">f1()</code> at most once. The executor may block
forward progress of the caller until <code class="computeroutput">f1()</code> finishes
execution.<br> <br> Executor implementations should use the
supplied allocator to allocate any memory required to store the
function object. Prior to invoking the function object, the executor
shall deallocate any memory allocated. [<span class="emphasis"><em>Note:</em></span>
Executors defined in this Technical Specification always use the
supplied allocator unless otherwise specified. —<span class="emphasis"><em>end note</em></span>]
<br> <br> Synchronization: The invocation of <code class="computeroutput">dispatch</code>
synchronizes with (C++Std [intro.multithread]) the invocation of
<code class="computeroutput">f1</code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1.post(std::move(f),a)</code><br> <code class="computeroutput">x1.defer(std::move(f),a)</code>
</p>
</td>
<td>
</td>
<td>
<p>
Effects: Creates an object <code class="computeroutput">f1</code> initialized with <code class="literal"><span class="emphasis"><em>DECAY_COPY</em></span></code><code class="computeroutput">(forward<Func>(f))</code>
in the current thread of execution. Calls <code class="computeroutput">f1()</code> at
most once. The executor shall not block forward progress of the
caller pending completion of <code class="computeroutput">f1()</code>.<br> <br> Executor
implementations should use the supplied allocator to allocate any
memory required to store the function object. Prior to invoking
the function object, the executor shall deallocate any memory allocated.
[<span class="emphasis"><em>Note:</em></span> Executors defined in this Technical
Specification always use the supplied allocator unless otherwise
specified. —<span class="emphasis"><em>end note</em></span>] <br> <br> Synchronization:
The invocation of <code class="computeroutput">post</code> or <code class="computeroutput">defer</code> synchronizes
with (C++Std [intro.multithread]) the invocation of <code class="computeroutput">f1</code>.<br>
<br> [<span class="emphasis"><em>Note:</em></span> Although the requirements placed
on <code class="computeroutput">defer</code> are identical to <code class="computeroutput">post</code>, the use
of <code class="computeroutput">post</code> conveys a preference that the caller <span class="emphasis"><em>does
not</em></span> block the first step of <code class="literal">f1</code>'s
progress, whereas <code class="computeroutput">defer</code> conveys a preference that
the caller <span class="emphasis"><em>does</em></span> block the first step of <code class="literal">f1</code>.
One use of <code class="computeroutput">defer</code> is to convey the intention of the
caller that <code class="literal">f1</code> is a continuation of the current
call context. The executor may use this information to optimize
or otherwise adjust the way in which <code class="computeroutput">f1</code> is invoked.
—<span class="emphasis"><em>end note</em></span>]
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2003-2020 Christopher M.
Kohlhoff<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="ExecutionContext.html"><img src="../../prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../home.png" alt="Home"></a><a accesskey="n" href="GettableSerialPortOption.html"><img src="../../next.png" alt="Next"></a>
</div>
</body>
</html>