doc/html/boost_asio/reference/asynchronous_operations.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Requirements on asynchronous operations</title>
   5 <link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../../boost_asio.html" title="Boost.Asio">
   8 <link rel="up" href="../reference.html" title="Reference">
   9 <link rel="prev" href="../reference.html" title="Reference">
  10 <link rel="next" href="AcceptHandler.html" title="Accept handler requirements">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <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>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="boost_asio.reference.asynchronous_operations"></a><a class="link" href="asynchronous_operations.html" title="Requirements on asynchronous operations">Requirements
  28       on asynchronous operations</a>
  29 </h3></div></div></div>
  30 <p>
  31         In Boost.Asio, an asynchronous operation is initiated by a function that
  32         is named with the prefix <code class="computeroutput"><span class="identifier">async_</span></code>.
  33         These functions will be referred to as <span class="emphasis"><em>initiating functions</em></span>.
  34       </p>
  35 <p>
  36         All initiating functions in Boost.Asio take a function object meeting <a class="link" href="Handler.html" title="Handlers">handler</a> requirements as the
  37         final parameter. These handlers accept as their first parameter an lvalue
  38         of type <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">error_code</span></code>.
  39       </p>
  40 <p>
  41         Implementations of asynchronous operations in Boost.Asio may call the application
  42         programming interface (API) provided by the operating system. If such an
  43         operating system API call results in an error, the handler will be invoked
  44         with a <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">error_code</span></code>
  45         lvalue that evaluates to true. Otherwise the handler will be invoked with
  46         a <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">error_code</span></code>
  47         lvalue that evaluates to false.
  48       </p>
  49 <p>
  50         Unless otherwise noted, when the behaviour of an asynchronous operation is
  51         defined "as if" implemented by a <span class="emphasis"><em>POSIX</em></span> function,
  52         the handler will be invoked with a value of type <code class="computeroutput"><span class="identifier">error_code</span></code>
  53         that corresponds to the failure condition described by <span class="emphasis"><em>POSIX</em></span>
  54         for that function, if any. Otherwise the handler will be invoked with an
  55         implementation-defined <code class="computeroutput"><span class="identifier">error_code</span></code>
  56         value that reflects the operating system error.
  57       </p>
  58 <p>
  59         Asynchronous operations will not fail with an error condition that indicates
  60         interruption by a signal (<span class="emphasis"><em>POSIX</em></span> <code class="computeroutput"><span class="identifier">EINTR</span></code>).
  61         Asynchronous operations will not fail with any error condition associated
  62         with non-blocking operations (<span class="emphasis"><em>POSIX</em></span> <code class="computeroutput"><span class="identifier">EWOULDBLOCK</span></code>,
  63         <code class="computeroutput"><span class="identifier">EAGAIN</span></code> or <code class="computeroutput"><span class="identifier">EINPROGRESS</span></code>;
  64         <span class="emphasis"><em>Windows</em></span> <code class="computeroutput"><span class="identifier">WSAEWOULDBLOCK</span></code>
  65         or <code class="computeroutput"><span class="identifier">WSAEINPROGRESS</span></code>).
  66       </p>
  67 <p>
  68         All asynchronous operations have an associated <code class="computeroutput"><span class="identifier">io_service</span></code>
  69         object. Where the initiating function is a member function, the associated
  70         <code class="computeroutput"><span class="identifier">io_service</span></code> is that returned
  71         by the <code class="computeroutput"><span class="identifier">get_io_service</span><span class="special">()</span></code>
  72         member function on the same object. Where the initiating function is not
  73         a member function, the associated <code class="computeroutput"><span class="identifier">io_service</span></code>
  74         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
  75         the initiating function.
  76       </p>
  77 <p>
  78         Arguments to initiating functions will be treated as follows:
  79       </p>
  80 <p>
  81         &#8212; If the parameter is declared as a const reference or by-value, the program
  82         is not required to guarantee the validity of the argument after the initiating
  83         function completes. The implementation may make copies of the argument, and
  84         all copies will be destroyed no later than immediately after invocation of
  85         the handler.
  86       </p>
  87 <p>
  88         &#8212; If the parameter is declared as a non-const reference, const pointer or non-const
  89         pointer, the program must guarantee the validity of the argument until the
  90         handler is invoked.
  91       </p>
  92 <p>
  93         The library implementation is only permitted to make calls to an initiating
  94         function's arguments' copy constructors or destructors from a thread that
  95         satisfies one of the following conditions:
  96       </p>
  97 <p>
  98         &#8212; The thread is executing any member function of the associated <code class="computeroutput"><span class="identifier">io_service</span></code> object.
  99       </p>
 100 <p>
 101         &#8212; The thread is executing the destructor of the associated <code class="computeroutput"><span class="identifier">io_service</span></code>
 102         object.
 103       </p>
 104 <p>
 105         &#8212; The thread is executing one of the <code class="computeroutput"><span class="identifier">io_service</span></code>
 106         service access functions <code class="computeroutput"><span class="identifier">use_service</span></code>,
 107         <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
 108         the associated <code class="computeroutput"><span class="identifier">io_service</span></code>
 109         object.
 110       </p>
 111 <p>
 112         &#8212; The thread is executing any member function, constructor or destructor of
 113         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>
 114         member function returns the associated <code class="computeroutput"><span class="identifier">io_service</span></code>
 115         object.
 116       </p>
 117 <p>
 118         &#8212; The thread is executing any function defined in this clause, where any argument
 119         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
 120         <code class="computeroutput"><span class="identifier">io_service</span></code> object.
 121       </p>
 122 <div class="sidebar">
 123 <div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div>
 124 <p>
 125         Boost.Asio may use one or more hidden threads to emulate asynchronous functionality.
 126         The above requirements are intended to prevent these hidden threads from
 127         making calls to program code. This means that a program can, for example,
 128         use thread-unsafe reference counting in handler objects, provided the program
 129         ensures that all calls to an <code class="computeroutput"><span class="identifier">io_service</span></code>
 130         and related objects occur from the one thread.
 131       </p>
 132 </div>
 133 <p>
 134         The <code class="computeroutput"><span class="identifier">io_service</span></code> object associated
 135         with an asynchronous operation will have unfinished work, as if by maintaining
 136         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>
 137         constructed using the <code class="computeroutput"><span class="identifier">io_service</span></code>,
 138         until immediately after the handler for the asynchronous operation has been
 139         invoked.
 140       </p>
 141 <p>
 142         When an asynchronous operation is complete, the handler for the operation
 143         will be invoked as if by:
 144       </p>
 145 <div class="orderedlist"><ol class="orderedlist" type="1">
 146 <li class="listitem">
 147             Constructing a bound completion handler <code class="computeroutput"><span class="identifier">bch</span></code>
 148             for the handler, as described below.
 149           </li>
 150 <li class="listitem">
 151             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>
 152             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>.
 153           </li>
 154 </ol></div>
 155 <p>
 156         This implies that the handler must not be called directly from within the
 157         initiating function, even if the asynchronous operation completes immediately.
 158       </p>
 159 <p>
 160         A bound completion handler is a handler object that contains a copy of a
 161         user-supplied handler, where the user-supplied handler accepts one or more
 162         arguments. The bound completion handler does not accept any arguments, and
 163         contains values to be passed as arguments to the user-supplied handler. The
 164         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
 165         the user-supplied handler. A bound completion handler meets the requirements
 166         for a <a class="link" href="CompletionHandler.html" title="Completion handler requirements">completion handler</a>.
 167       </p>
 168 <p>
 169         For example, a bound completion handler for a <code class="computeroutput"><span class="identifier">ReadHandler</span></code>
 170         may be implemented as follows:
 171       </p>
 172 <pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">ReadHandler</span><span class="special">&gt;</span>
 173 <span class="keyword">struct</span> <span class="identifier">bound_read_handler</span>
 174 <span class="special">{</span>
 175   <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">&amp;</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>
 176     <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>
 177   <span class="special">{</span>
 178   <span class="special">}</span>
 179
 180   <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()()</span>
 181   <span class="special">{</span>
 182     <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>
 183   <span class="special">}</span>
 184
 185   <span class="identifier">ReadHandler</span> <span class="identifier">handler_</span><span class="special">;</span>
 186   <span class="keyword">const</span> <span class="identifier">error_code</span> <span class="identifier">ec_</span><span class="special">;</span>
 187   <span class="keyword">const</span> <span class="identifier">size_t</span> <span class="identifier">s_</span><span class="special">;</span>
 188 <span class="special">};</span>
 189
 190 <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">ReadHandler</span><span class="special">&gt;</span>
 191 <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>
 192                             <span class="identifier">bound_read_handler</span><span class="special">&lt;</span><span class="identifier">ReadHandler</span><span class="special">&gt;*</span> <span class="identifier">this_handler</span><span class="special">)</span>
 193 <span class="special">{</span>
 194   <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>
 195   <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">&amp;</span><span class="identifier">this_handler</span><span class="special">-&gt;</span><span class="identifier">handler_</span><span class="special">);</span>
 196 <span class="special">}</span>
 197
 198 <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">ReadHandler</span><span class="special">&gt;</span>
 199 <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>
 200                              <span class="identifier">bound_read_handler</span><span class="special">&lt;</span><span class="identifier">ReadHandler</span><span class="special">&gt;*</span> <span class="identifier">this_handler</span><span class="special">)</span>
 201 <span class="special">{</span>
 202   <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>
 203   <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">&amp;</span><span class="identifier">this_handler</span><span class="special">-&gt;</span><span class="identifier">handler_</span><span class="special">);</span>
 204 <span class="special">}</span>
 205
 206 <span class="keyword">template</span><span class="special">&lt;</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">&gt;</span>
 207 <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">&amp;</span> <span class="identifier">f</span><span class="special">,</span>
 208                          <span class="identifier">bound_read_handler</span><span class="special">&lt;</span><span class="identifier">ReadHandler</span><span class="special">&gt;*</span> <span class="identifier">this_handler</span><span class="special">)</span>
 209 <span class="special">{</span>
 210   <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>
 211   <span class="identifier">asio_handler_invoke</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">this_handler</span><span class="special">-&gt;</span><span class="identifier">handler_</span><span class="special">);</span>
 212 <span class="special">}</span>
 213 </pre>
 214 <p>
 215         If the thread that initiates an asynchronous operation terminates before
 216         the associated handler is invoked, the behaviour is implementation-defined.
 217         Specifically, on <span class="emphasis"><em>Windows</em></span> versions prior to Vista, unfinished
 218         operations are cancelled when the initiating thread exits.
 219       </p>
 220 <p>
 221         The handler argument to an initiating function defines a handler identity.
 222         That is, the original handler argument and any copies of the handler argument
 223         will be considered equivalent. If the implementation needs to allocate storage
 224         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">&amp;</span><span class="identifier">h</span><span class="special">)</span></code>, where <code class="computeroutput"><span class="identifier">size</span></code>
 225         is the required size in bytes, and <code class="computeroutput"><span class="identifier">h</span></code>
 226         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>
 227         <span class="identifier">size</span><span class="special">,</span>
 228         <span class="special">&amp;</span><span class="identifier">h</span><span class="special">)</span></code>, where <code class="computeroutput"><span class="identifier">p</span></code>
 229         is a pointer to the storage, to deallocate the storage prior to the invocation
 230         of the handler via <code class="computeroutput"><span class="identifier">asio_handler_invoke</span></code>.
 231         Multiple storage blocks may be allocated for a single asynchronous operation.
 232       </p>
 233 <h5>
 234 <a name="boost_asio.reference.asynchronous_operations.h0"></a>
 235         <span class="phrase"><a name="boost_asio.reference.asynchronous_operations.return_type_of_an_initiating_function"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.return_type_of_an_initiating_function">Return
 236         type of an initiating function</a>
 237       </h5>
 238 <p>
 239         By default, initiating functions return <code class="computeroutput"><span class="keyword">void</span></code>.
 240         This is always the case when the handler is a function pointer, C++11 lambda,
 241         or a function object produced by <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span></code>
 242         or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind</span></code>.
 243       </p>
 244 <p>
 245         For other types, the return type may be customised via a two-step process:
 246       </p>
 247 <div class="orderedlist"><ol class="orderedlist" type="1">
 248 <li class="listitem">
 249             A specialisation of the <a class="link" href="handler_type.html" title="handler_type"><code class="computeroutput"><span class="identifier">handler_type</span></code></a> template, which
 250             is used to determine the true handler type based on the asynchronous
 251             operation's handler's signature.
 252           </li>
 253 <li class="listitem">
 254             A specialisation of the <a class="link" href="async_result.html" title="async_result"><code class="computeroutput"><span class="identifier">async_result</span></code></a> template, which
 255             is used both to determine the return type and to extract the return value
 256             from the handler.
 257           </li>
 258 </ol></div>
 259 <p>
 260         These two templates have been specialised to provide support for <a class="link" href="../overview/core/spawn.html" title="Stackful Coroutines">stackful
 261         coroutines</a> and the C++11 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">future</span></code>
 262         class.
 263       </p>
 264 <p>
 265         As an example, consider what happens when enabling <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">future</span></code>
 266         support by using the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">use_future</span></code>
 267         special value, as in:
 268       </p>
 269 <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">future</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">&gt;</span> <span class="identifier">length</span> <span class="special">=</span>
 270   <span class="identifier">my_socket</span><span class="special">.</span><span class="identifier">async_read_some</span><span class="special">(</span><span class="identifier">my_buffer</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">use_future</span><span class="special">);</span>
 271 </pre>
 272 <p>
 273         When a handler signature has the form:
 274       </p>
 275 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">handler</span><span class="special">(</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">,</span> <span class="identifier">result_type</span> <span class="identifier">result</span><span class="special">);</span>
 276 </pre>
 277 <p>
 278         the initiating function returns a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">future</span></code>
 279         templated on <code class="computeroutput"><span class="identifier">result_type</span></code>.
 280         In the above <code class="computeroutput"><span class="identifier">async_read_some</span></code>
 281         example, this is <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>. If the asynchronous operation fails,
 282         the <code class="computeroutput"><span class="identifier">error_code</span></code> is converted
 283         into a <code class="computeroutput"><span class="identifier">system_error</span></code> exception
 284         and passed back to the caller through the future.
 285       </p>
 286 <p>
 287         Where a handler signature has the form:
 288       </p>
 289 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">handler</span><span class="special">(</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">);</span>
 290 </pre>
 291 <p>
 292         the initiating function instead returns <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">future</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span></code>.
 293       </p>
 294 </div>
 295 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 296 <td align="left"></td>
 297 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2017 Christopher M. Kohlhoff<p>
 298         Distributed under the Boost Software License, Version 1.0. (See accompanying
 299         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>)
 300       </p>
 301 </div></td>
 302 </tr></table>
 303 <hr>
 304 <div class="spirit-nav">
 305 <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>
 306 </div>
 307 </body>
 308 </html>