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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Requirements on asynchronous operations</title>
<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../boost_asio.html" title="Boost.Asio">
<link rel="up" href="../reference.html" title="Reference">
<link rel="prev" href="../reference.html" title="Reference">
<link rel="next" href="read_write_operations.html" title="Requirements on read and write operations">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
<td align="center"><a href="../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../reference.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="read_write_operations.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_asio.reference.asynchronous_operations"></a><a class="link" href="asynchronous_operations.html" title="Requirements on asynchronous operations">Requirements
on asynchronous operations</a>
</h3></div></div></div>
<p>
This section uses the names <code class="computeroutput">Alloc1</code>, <code class="computeroutput">Alloc2</code>, <code class="computeroutput">alloc1</code>,
<code class="computeroutput">alloc2</code>, <code class="computeroutput">Args</code>, <code class="computeroutput">CompletionHandler</code>,
<code class="computeroutput">completion_handler</code>, <code class="computeroutput">Executor1</code>, <code class="computeroutput">Executor2</code>,
<code class="computeroutput">ex1</code>, <code class="computeroutput">ex2</code>, <code class="computeroutput">f</code>, <code class="literal"><span class="emphasis"><em>i</em></span></code>,
<code class="literal"><span class="emphasis"><em>N</em></span></code>, <code class="computeroutput">Signature</code>, <code class="computeroutput">token</code>,
<code class="literal">T[sub <span class="emphasis"><em>i</em></span></code>], <code class="literal">t[sub <span class="emphasis"><em>i</em></span></code>],
<code class="computeroutput">work1</code>, and <code class="computeroutput">work2</code> as placeholders for specifying
the requirements below.
</p>
<h5>
<a name="boost_asio.reference.asynchronous_operations.h0"></a>
<span class="phrase"><a name="boost_asio.reference.asynchronous_operations.general_asynchronous_operation_concepts"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.general_asynchronous_operation_concepts">General
asynchronous operation concepts</a>
</h5>
<p>
An <span class="emphasis"><em>initiating function</em></span> is a function which may be called
to start an asynchronous operation. A <span class="emphasis"><em>completion handler</em></span>
is a function object that will be invoked, at most once, with the result
of the asynchronous operation.
</p>
<p>
The lifecycle of an asynchronous operation is comprised of the following
events and phases:
</p>
<p>
— Event 1: The asynchronous operation is started by a call to the initiating
function.
</p>
<p>
— Phase 1: The asynchronous operation is now <span class="emphasis"><em>outstanding</em></span>.
</p>
<p>
— Event 2: The externally observable side effects of the asynchronous operation,
if any, are fully established. The completion handler is submitted to an
executor.
</p>
<p>
— Phase 2: The asynchronous operation is now <span class="emphasis"><em>completed</em></span>.
</p>
<p>
— Event 3: The completion handler is called with the result of the asynchronous
operation.
</p>
<p>
In this library, all functions with the prefix <code class="computeroutput">async_</code> are initiating
functions.
</p>
<h5>
<a name="boost_asio.reference.asynchronous_operations.h1"></a>
<span class="phrase"><a name="boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers">Completion
tokens and handlers</a>
</h5>
<p>
Initiating functions:
</p>
<p>
— are function templates with template parameter <code class="computeroutput">CompletionToken</code>;
</p>
<p>
— accept, as the final parameter, a <span class="emphasis"><em>completion token</em></span> object
<code class="computeroutput">token</code> of type <code class="computeroutput">CompletionToken</code>;
</p>
<p>
— specify a <span class="emphasis"><em>completion signature</em></span>, which is a call signature
(C++Std [func.def]) <code class="computeroutput">Signature</code> that determines the arguments
to the completion handler.
</p>
<p>
An initiating function determines the type <code class="computeroutput">CompletionHandler</code>
of its completion handler function object by performing <code class="computeroutput">typename async_result<decay_t<CompletionToken>,
Signature>::completion_handler_type</code>. The completion handler object
<code class="computeroutput">completion_handler</code> is initialized with <code class="computeroutput">forward<CompletionToken>(token)</code>.
[<span class="emphasis"><em>Note:</em></span> No other requirements are placed on the type
<code class="computeroutput">CompletionToken</code>. —<span class="emphasis"><em>end note</em></span>]
</p>
<p>
The type <code class="computeroutput">CompletionHandler</code> must satisfy the requirements of
<code class="computeroutput">Destructible</code> (C++Std [destructible]) and <code class="computeroutput">MoveConstructible</code>
(C++Std [moveconstructible]), and be callable with the specified call signature.
</p>
<p>
In this library, all initiating functions specify a <span class="emphasis"><em>Completion
signature</em></span> element that defines the call signature <code class="computeroutput">Signature</code>.
The <span class="emphasis"><em>Completion signature</em></span> elements in this Technical
Specification have named parameters, and the results of an asynchronous operation
are specified in terms of these names.
</p>
<h5>
<a name="boost_asio.reference.asynchronous_operations.h2"></a>
<span class="phrase"><a name="boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type">Automatic
deduction of initiating function return type</a>
</h5>
<p>
The return type of an initiating function is <code class="computeroutput">typename async_result<decay_t<CompletionToken>,
Signature>::return_type</code>.
</p>
<p>
For the sake of exposition, this library sometimes annotates functions with
a return type <span class="emphasis"><em><code class="literal">DEDUCED</code></em></span>. For every
function declaration that returns <span class="emphasis"><em><code class="literal">DEDUCED</code></em></span>,
the meaning is equivalent to specifying the return type as <code class="computeroutput">typename
async_result<decay_t<CompletionToken>, Signature>::return_type</code>.
</p>
<h5>
<a name="boost_asio.reference.asynchronous_operations.h3"></a>
<span class="phrase"><a name="boost_asio.reference.asynchronous_operations.production_of_initiating_function_return_value"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.production_of_initiating_function_return_value">Production
of initiating function return value</a>
</h5>
<p>
An initiating function produces its return type as follows:
</p>
<p>
— constructing an object <code class="computeroutput">result</code> of type <code class="computeroutput">async_result<decay_t<CompletionToken>,
Signature></code>, initialized as <code class="computeroutput">result(completion_handler)</code>;
and
</p>
<p>
— using <code class="computeroutput">result.get()</code> as the operand of the return statement.
</p>
<p>
[<span class="emphasis"><em>Example:</em></span> Given an asynchronous operation with <span class="emphasis"><em>Completion
signature</em></span> <code class="computeroutput">void(R1 r1, R2 r2)</code>, an initiating function
meeting these requirements may be implemented as follows:
</p>
<pre class="programlisting">template<class CompletionToken>
auto async_xyz(T1 t1, T2 t2, CompletionToken&& token)
{
typename async_result<decay_t<CompletionToken>, void(R1, R2)>::completion_handler_type
completion_handler(forward<CompletionToken>(token));
async_result<decay_t<CompletionToken>, void(R1, R2)> result(completion_handler);
// initiate the operation and cause completion_handler to be invoked with
// the result
return result.get();
}
</pre>
<p>
For convenience, initiating functions may be implemented using the <code class="computeroutput">async_completion</code>
template:
</p>
<pre class="programlisting">template<class CompletionToken>
auto async_xyz(T1 t1, T2 t2, CompletionToken&& token)
{
async_completion<CompletionToken, void(R1, R2)> init(token);
// initiate the operation and cause init.completion_handler to be invoked
// with the result
return init.result.get();
}
</pre>
<p>
—<span class="emphasis"><em>end example</em></span>]
</p>
<h5>
<a name="boost_asio.reference.asynchronous_operations.h4"></a>
<span class="phrase"><a name="boost_asio.reference.asynchronous_operations.lifetime_of_initiating_function_arguments"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.lifetime_of_initiating_function_arguments">Lifetime
of initiating function arguments</a>
</h5>
<p>
Unless otherwise specified, the lifetime of arguments to initiating functions
shall be treated as follows:
</p>
<p>
— If the parameter has a pointer type or has a type of lvalue reference to
non-const, the implementation may assume the validity of the pointee or referent,
respectively, until the completion handler is invoked. [<span class="emphasis"><em>Note:</em></span>
In other words, the program must guarantee the validity of the argument until
the completion handler is invoked. —<span class="emphasis"><em>end note</em></span>]
</p>
<p>
— Otherwise, the implementation must not assume the validity of the argument
after the initiating function completes. [<span class="emphasis"><em>Note:</em></span> In other
words, the program is not required to guarantee the validity of the argument
after the initiating function completes. —<span class="emphasis"><em>end note</em></span>] The
implementation may make copies of the argument, and all copies shall be destroyed
no later than immediately after invocation of the completion handler.
</p>
<h5>
<a name="boost_asio.reference.asynchronous_operations.h5"></a>
<span class="phrase"><a name="boost_asio.reference.asynchronous_operations.non_blocking_requirements_on_initiating_functions"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.non_blocking_requirements_on_initiating_functions">Non-blocking
requirements on initiating functions</a>
</h5>
<p>
An initiating function shall not block (C++Std [defns.block]) the calling
thread pending completion of the outstanding operation.
</p>
<p>
[std_note Initiating functions may still block the calling thread for other
reasons. For example, an initiating function may lock a mutex in order to
synchronize access to shared data.]
</p>
<h5>
<a name="boost_asio.reference.asynchronous_operations.h6"></a>
<span class="phrase"><a name="boost_asio.reference.asynchronous_operations.associated_executor"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.associated_executor">Associated
executor</a>
</h5>
<p>
Certain objects that participate in asynchronous operations have an <span class="emphasis"><em>associated
executor</em></span>. These are obtained as specified in the sections below.
</p>
<h5>
<a name="boost_asio.reference.asynchronous_operations.h7"></a>
<span class="phrase"><a name="boost_asio.reference.asynchronous_operations.associated_i_o_executor"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.associated_i_o_executor">Associated
I/O executor</a>
</h5>
<p>
An asynchronous operation has an associated executor satisfying the <a class="link" href="Executor1.html" title="Executor requirements"><code class="computeroutput">Executor</code></a> requirements.
If not otherwise specified by the asynchronous operation, this associated
executor is an object of type <code class="computeroutput">system_executor</code>.
</p>
<p>
All asynchronous operations in this library have an associated executor object
that is determined as follows:
</p>
<p>
— If the initiating function is a member function, the associated executor
is that returned by the <code class="computeroutput">get_executor</code> member function on the
same object.
</p>
<p>
— If the initiating function is not a member function, the associated executor
is that returned by the <code class="computeroutput">get_executor</code> member function of the
first argument to the initiating function.
</p>
<p>
Let <code class="computeroutput">Executor1</code> be the type of the associated executor. Let <code class="computeroutput">ex1</code>
be a value of type <code class="computeroutput">Executor1</code>, representing the associated executor
object obtained as described above.
</p>
<h5>
<a name="boost_asio.reference.asynchronous_operations.h8"></a>
<span class="phrase"><a name="boost_asio.reference.asynchronous_operations.associated_completion_handler_executor"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.associated_completion_handler_executor">Associated
completion handler executor</a>
</h5>
<p>
A completion handler object of type <code class="computeroutput">CompletionHandler</code> has an
associated executor of type <code class="computeroutput">Executor2</code> satisfying the <a class="link" href="Executor1.html" title="Executor requirements">Executor
requirements</a>. The type <code class="computeroutput">Executor2</code> is <code class="computeroutput">associated_executor_t<CompletionHandler,
Executor1></code>. Let <code class="computeroutput">ex2</code> be a value of type <code class="computeroutput">Executor2</code>
obtained by performing <code class="computeroutput">get_associated_executor(completion_handler,
ex1)</code>.
</p>
<h5>
<a name="boost_asio.reference.asynchronous_operations.h9"></a>
<span class="phrase"><a name="boost_asio.reference.asynchronous_operations.outstanding_work"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.outstanding_work">Outstanding
work</a>
</h5>
<p>
Until the asynchronous operation has completed, the asynchronous operation
shall maintain:
</p>
<p>
— an object <code class="computeroutput">work1</code> of type <code class="computeroutput">executor_work_guard<Executor1></code>,
initialized as <code class="computeroutput">work1(ex1)</code>, and where <code class="computeroutput">work1.owns_work()
== true</code>; and
</p>
<p>
— an object <code class="computeroutput">work2</code> of type <code class="computeroutput">executor_work_guard<Executor2></code>,
initialized as <code class="computeroutput">work2(ex2)</code>, and where <code class="computeroutput">work2.owns_work()
== true</code>.
</p>
<h5>
<a name="boost_asio.reference.asynchronous_operations.h10"></a>
<span class="phrase"><a name="boost_asio.reference.asynchronous_operations.allocation_of_intermediate_storage"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.allocation_of_intermediate_storage">Allocation
of intermediate storage</a>
</h5>
<p>
Asynchronous operations may allocate memory. [<span class="emphasis"><em>Note:</em></span>
Such as a data structure to store copies of the <code class="computeroutput">completion_handler</code>
object and the initiating function's arguments. —<span class="emphasis"><em>end note</em></span>]
</p>
<p>
Let <code class="computeroutput">Alloc1</code> be a type, satisfying the <a class="link" href="ProtoAllocator.html" title="Proto-allocator requirements"><code class="computeroutput">ProtoAllocator</code></a>
requirements, that represents the asynchronous operation's default allocation
strategy. [<span class="emphasis"><em>Note:</em></span> Typically <code class="computeroutput">std::allocator<void></code>.
—<span class="emphasis"><em>end note</em></span>] Let <code class="computeroutput">alloc1</code> be a value of type
<code class="computeroutput">Alloc1</code>.
</p>
<p>
A completion handler object of type <code class="computeroutput">CompletionHandler</code> has an
associated allocator object <code class="computeroutput">alloc2</code> of type <code class="computeroutput">Alloc2</code>
satisfying the <a class="link" href="ProtoAllocator.html" title="Proto-allocator requirements"><code class="computeroutput">ProtoAllocator</code></a>
requirements. The type <code class="computeroutput">Alloc2</code> is <code class="computeroutput">associated_allocator_t<CompletionHandler,
Alloc1></code>. Let <code class="computeroutput">alloc2</code> be a value of type <code class="computeroutput">Alloc2</code>
obtained by performing <code class="computeroutput">get_associated_allocator(completion_handler,
alloc1)</code>.
</p>
<p>
The asynchronous operations defined in this library:
</p>
<p>
— If required, allocate memory using only the completion handler's associated
allocator.
</p>
<p>
— Prior to completion handler execution, deallocate any memory allocated using
the completion handler's associated allocator.
</p>
<p>
[std_note The implementation may perform operating system or underlying API
calls that perform memory allocations not using the associated allocator.
Invocations of the allocator functions may not introduce data races (See
C++Std [res.on.data.races]).]
</p>
<h5>
<a name="boost_asio.reference.asynchronous_operations.h11"></a>
<span class="phrase"><a name="boost_asio.reference.asynchronous_operations.execution_of_completion_handler_on_completion_of_asynchronous_operation"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.execution_of_completion_handler_on_completion_of_asynchronous_operation">Execution
of completion handler on completion of asynchronous operation</a>
</h5>
<p>
Let <code class="computeroutput">Args...</code> be the argument types of the completion signature
<code class="computeroutput">Signature</code> and let <code class="literal"><span class="emphasis"><em>N</em></span></code>
be <code class="computeroutput">sizeof...(Args)</code>. Let <code class="literal"><span class="emphasis"><em>i</em></span></code>
be in the range [<code class="computeroutput">0</code>,<code class="literal"><span class="emphasis"><em>N</em></span></code>).
Let <code class="literal">T[sub <span class="emphasis"><em>i</em></span></code>] be the <code class="literal"><span class="emphasis"><em>i</em></span></code>th
type in <code class="computeroutput">Args...</code> and let <code class="literal">t[sub <span class="emphasis"><em>i</em></span></code>]
be the <code class="literal"><span class="emphasis"><em>i</em></span></code>th completion handler argument
associated with <code class="literal">T[sub <span class="emphasis"><em>i</em></span></code>].
</p>
<p>
Let <code class="computeroutput">f</code> be a function object, callable as <code class="computeroutput">f()</code>, that
invokes <code class="computeroutput">completion_handler</code> as if by <code class="literal">completion_handler(forward<T[sub
<span class="emphasis"><em>0</em></span></code>>(t[sub <span class="emphasis"><em>0</em></span>]), ...,
forward<T[sub <span class="emphasis"><em>N-1</em></span>]>(t[sub <span class="emphasis"><em>N-1</em></span>]))].
</p>
<p>
If an asynchonous operation completes immediately (that is, within the thread
of execution calling the initiating function, and before the initiating function
returns), the completion handler shall be submitted for execution as if by
performing <code class="computeroutput">ex2.post(std::move(f), alloc2)</code>. Otherwise, the completion
handler shall be submitted for execution as if by performing <code class="computeroutput">ex2.dispatch(std::move(f),
alloc2)</code>.
</p>
<h5>
<a name="boost_asio.reference.asynchronous_operations.h12"></a>
<span class="phrase"><a name="boost_asio.reference.asynchronous_operations.completion_handlers_and_exceptions"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.completion_handlers_and_exceptions">Completion
handlers and exceptions</a>
</h5>
<p>
Completion handlers are permitted to throw exceptions. The effect of any
exception propagated from the execution of a completion handler is determined
by the executor which is executing the completion handler.
</p>
</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-2019 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="../reference.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="read_write_operations.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
