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
|
<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.76.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="AcceptHandler.html" title="Accept handler requirements">
</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="AcceptHandler.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>
In Boost.Asio, an asynchronous operation is initiated by a function that
is named with the prefix <code class="computeroutput"><span class="identifier">async_</span></code>.
These functions will be referred to as <span class="emphasis"><em>initiating functions</em></span>.
</p>
<p>
All initiating functions in Boost.Asio take a function object meeting <a class="link" href="Handler.html" title="Handlers">handler</a> requirements as the
final parameter. These handlers accept as their first parameter an lvalue
of type <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">error_code</span></code>.
</p>
<p>
Implementations of asynchronous operations in Boost.Asio may call the application
programming interface (API) provided by the operating system. If such an
operating system API call results in an error, the handler will be invoked
with a <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">error_code</span></code>
lvalue that evaluates to true. Otherwise the handler will be invoked with
a <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">error_code</span></code>
lvalue that evaluates to false.
</p>
<p>
Unless otherwise noted, when the behaviour of an asynchronous operation is
defined "as if" implemented by a <span class="emphasis"><em>POSIX</em></span> function,
the handler will be invoked with a value of type <code class="computeroutput"><span class="identifier">error_code</span></code>
that corresponds to the failure condition described by <span class="emphasis"><em>POSIX</em></span>
for that function, if any. Otherwise the handler will be invoked with an
implementation-defined <code class="computeroutput"><span class="identifier">error_code</span></code>
value that reflects the operating system error.
</p>
<p>
Asynchronous operations will not fail with an error condition that indicates
interruption by a signal (<span class="emphasis"><em>POSIX</em></span> <code class="computeroutput"><span class="identifier">EINTR</span></code>).
Asynchronous operations will not fail with any error condition associated
with non-blocking operations (<span class="emphasis"><em>POSIX</em></span> <code class="computeroutput"><span class="identifier">EWOULDBLOCK</span></code>,
<code class="computeroutput"><span class="identifier">EAGAIN</span></code> or <code class="computeroutput"><span class="identifier">EINPROGRESS</span></code>;
<span class="emphasis"><em>Windows</em></span> <code class="computeroutput"><span class="identifier">WSAEWOULDBLOCK</span></code>
or <code class="computeroutput"><span class="identifier">WSAEINPROGRESS</span></code>).
</p>
<p>
All asynchronous operations have an associated <code class="computeroutput"><span class="identifier">io_service</span></code>
object. Where the initiating function is a member function, the associated
<code class="computeroutput"><span class="identifier">io_service</span></code> is that returned
by the <code class="computeroutput"><span class="identifier">get_io_service</span><span class="special">()</span></code>
member function on the same object. Where the initiating function is not
a member function, the associated <code class="computeroutput"><span class="identifier">io_service</span></code>
is that returned by the <code class="computeroutput"><span class="identifier">get_io_service</span><span class="special">()</span></code> member function of the first argument to
the initiating function.
</p>
<p>
Arguments to initiating functions will be treated as follows:
</p>
<p>
— If the parameter is declared as a const reference or by-value, the program
is not required to guarantee the validity of the argument after the initiating
function completes. The implementation may make copies of the argument, and
all copies will be destroyed no later than immediately after invocation of
the handler.
</p>
<p>
— If the parameter is declared as a non-const reference, const pointer or non-const
pointer, the program must guarantee the validity of the argument until the
handler is invoked.
</p>
<p>
The library implementation is only permitted to make calls to an initiating
function's arguments' copy constructors or destructors from a thread that
satisfies one of the following conditions:
</p>
<p>
— The thread is executing any member function of the associated <code class="computeroutput"><span class="identifier">io_service</span></code> object.
</p>
<p>
— The thread is executing the destructor of the associated <code class="computeroutput"><span class="identifier">io_service</span></code>
object.
</p>
<p>
— The thread is executing one of the <code class="computeroutput"><span class="identifier">io_service</span></code>
service access functions <code class="computeroutput"><span class="identifier">use_service</span></code>,
<code class="computeroutput"><span class="identifier">add_service</span></code> or <code class="computeroutput"><span class="identifier">has_service</span></code>, where the first argument is
the associated <code class="computeroutput"><span class="identifier">io_service</span></code>
object.
</p>
<p>
— The thread is executing any member function, constructor or destructor of
an object of a class defined in this clause, where the object's <code class="computeroutput"><span class="identifier">get_io_service</span><span class="special">()</span></code>
member function returns the associated <code class="computeroutput"><span class="identifier">io_service</span></code>
object.
</p>
<p>
— The thread is executing any function defined in this clause, where any argument
to the function has an <code class="computeroutput"><span class="identifier">get_io_service</span><span class="special">()</span></code> member function that returns the associated
<code class="computeroutput"><span class="identifier">io_service</span></code> object.
</p>
<div class="sidebar">
<div class="titlepage"></div>
<p>
Boost.Asio may use one or more hidden threads to emulate asynchronous functionality.
The above requirements are intended to prevent these hidden threads from
making calls to program code. This means that a program can, for example,
use thread-unsafe reference counting in handler objects, provided the program
ensures that all calls to an <code class="computeroutput"><span class="identifier">io_service</span></code>
and related objects occur from the one thread.
</p>
</div>
<p>
The <code class="computeroutput"><span class="identifier">io_service</span></code> object associated
with an asynchronous operation will have unfinished work, as if by maintaining
the existence of one or more objects of class <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">work</span></code>
constructed using the <code class="computeroutput"><span class="identifier">io_service</span></code>,
until immediately after the handler for the asynchronous operation has been
invoked.
</p>
<p>
When an asynchronous operation is complete, the handler for the operation
will be invoked as if by:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
Constructing a bound completion handler <code class="computeroutput"><span class="identifier">bch</span></code>
for the handler, as described below.
</li>
<li class="listitem">
Calling <code class="computeroutput"><span class="identifier">ios</span><span class="special">.</span><span class="identifier">post</span><span class="special">(</span><span class="identifier">bch</span><span class="special">)</span></code>
to schedule the handler for deferred invocation, where <code class="computeroutput"><span class="identifier">ios</span></code> is the associated <code class="computeroutput"><span class="identifier">io_service</span></code>.
</li>
</ol></div>
<p>
This implies that the handler must not be called directly from within the
initiating function, even if the asynchronous operation completes immediately.
</p>
<p>
A bound completion handler is a handler object that contains a copy of a
user-supplied handler, where the user-supplied handler accepts one or more
arguments. The bound completion handler does not accept any arguments, and
contains values to be passed as arguments to the user-supplied handler. The
bound completion handler forwards the <code class="computeroutput"><span class="identifier">asio_handler_allocate</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">asio_handler_deallocate</span><span class="special">()</span></code>, and <code class="computeroutput"><span class="identifier">asio_handler_invoke</span><span class="special">()</span></code> calls to the corresponding functions for
the user-supplied handler. A bound completion handler meets the requirements
for a <a class="link" href="CompletionHandler.html" title="Completion handler requirements">completion handler</a>.
</p>
<p>
For example, a bound completion handler for a <code class="computeroutput"><span class="identifier">ReadHandler</span></code>
may be implemented as follows:
</p>
<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">ReadHandler</span><span class="special">></span>
<span class="keyword">struct</span> <span class="identifier">bound_read_handler</span>
<span class="special">{</span>
<span class="identifier">bound_read_handler</span><span class="special">(</span><span class="identifier">ReadHandler</span> <span class="identifier">handler</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">,</span> <span class="identifier">size_t</span> <span class="identifier">s</span><span class="special">)</span>
<span class="special">:</span> <span class="identifier">handler_</span><span class="special">(</span><span class="identifier">handler</span><span class="special">),</span> <span class="identifier">ec_</span><span class="special">(</span><span class="identifier">ec</span><span class="special">),</span> <span class="identifier">s_</span><span class="special">(</span><span class="identifier">s</span><span class="special">)</span>
<span class="special">{</span>
<span class="special">}</span>
<span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()()</span>
<span class="special">{</span>
<span class="identifier">handler_</span><span class="special">(</span><span class="identifier">ec_</span><span class="special">,</span> <span class="identifier">s_</span><span class="special">);</span>
<span class="special">}</span>
<span class="identifier">ReadHandler</span> <span class="identifier">handler_</span><span class="special">;</span>
<span class="keyword">const</span> <span class="identifier">error_code</span> <span class="identifier">ec_</span><span class="special">;</span>
<span class="keyword">const</span> <span class="identifier">size_t</span> <span class="identifier">s_</span><span class="special">;</span>
<span class="special">};</span>
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">ReadHandler</span><span class="special">></span>
<span class="keyword">void</span><span class="special">*</span> <span class="identifier">asio_handler_allocate</span><span class="special">(</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">,</span>
<span class="identifier">bound_read_handler</span><span class="special"><</span><span class="identifier">ReadHandler</span><span class="special">>*</span> <span class="identifier">this_handler</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">asio_handler_allocate</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">asio_handler_allocate</span><span class="special">(</span><span class="identifier">size</span><span class="special">,</span> <span class="special">&</span><span class="identifier">this_handler</span><span class="special">-></span><span class="identifier">handler_</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">ReadHandler</span><span class="special">></span>
<span class="keyword">void</span> <span class="identifier">asio_handler_deallocate</span><span class="special">(</span><span class="keyword">void</span><span class="special">*</span> <span class="identifier">pointer</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">,</span>
<span class="identifier">bound_read_handler</span><span class="special"><</span><span class="identifier">ReadHandler</span><span class="special">>*</span> <span class="identifier">this_handler</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">asio_handler_deallocate</span><span class="special">;</span>
<span class="identifier">asio_handler_deallocate</span><span class="special">(</span><span class="identifier">pointer</span><span class="special">,</span> <span class="identifier">size</span><span class="special">,</span> <span class="special">&</span><span class="identifier">this_handler</span><span class="special">-></span><span class="identifier">handler_</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">ReadHandler</span><span class="special">></span>
<span class="keyword">void</span> <span class="identifier">asio_handler_invoke</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">F</span><span class="special">&</span> <span class="identifier">f</span><span class="special">,</span>
<span class="identifier">bound_read_handler</span><span class="special"><</span><span class="identifier">ReadHandler</span><span class="special">>*</span> <span class="identifier">this_handler</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">asio_handler_invoke</span><span class="special">;</span>
<span class="identifier">asio_handler_invoke</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">&</span><span class="identifier">this_handler</span><span class="special">-></span><span class="identifier">handler_</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
If the thread that initiates an asynchronous operation terminates before
the associated handler is invoked, the behaviour is implementation-defined.
Specifically, on <span class="emphasis"><em>Windows</em></span> versions prior to Vista, unfinished
operations are cancelled when the initiating thread exits.
</p>
<p>
The handler argument to an initiating function defines a handler identity.
That is, the original handler argument and any copies of the handler argument
will be considered equivalent. If the implementation needs to allocate storage
for an asynchronous operation, the implementation will perform <code class="computeroutput"><span class="identifier">asio_handler_allocate</span><span class="special">(</span><span class="identifier">size</span><span class="special">,</span> <span class="special">&</span><span class="identifier">h</span><span class="special">)</span></code>, where <code class="computeroutput"><span class="identifier">size</span></code>
is the required size in bytes, and <code class="computeroutput"><span class="identifier">h</span></code>
is the handler. The implementation will perform <code class="computeroutput"><span class="identifier">asio_handler_deallocate</span><span class="special">(</span><span class="identifier">p</span><span class="special">,</span>
<span class="identifier">size</span><span class="special">,</span>
<span class="special">&</span><span class="identifier">h</span><span class="special">)</span></code>, where <code class="computeroutput"><span class="identifier">p</span></code>
is a pointer to the storage, to deallocate the storage prior to the invocation
of the handler via <code class="computeroutput"><span class="identifier">asio_handler_invoke</span></code>.
Multiple storage blocks may be allocated for a single asynchronous operation.
</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-2012 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="AcceptHandler.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
