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="read_write_operations.html" title="Requirements on read and write operations">
  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="read_write_operations.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         This section uses the names <code class="computeroutput">Alloc1</code>, <code class="computeroutput">Alloc2</code>, <code class="computeroutput">alloc1</code>,
  32         <code class="computeroutput">alloc2</code>, <code class="computeroutput">Args</code>, <code class="computeroutput">CompletionHandler</code>,
  33         <code class="computeroutput">completion_handler</code>, <code class="computeroutput">Executor1</code>, <code class="computeroutput">Executor2</code>,
  34         <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>,
  35         <code class="literal"><span class="emphasis"><em>N</em></span></code>, <code class="computeroutput">Signature</code>, <code class="computeroutput">token</code>,
  36         <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>],
  37         <code class="computeroutput">work1</code>, and <code class="computeroutput">work2</code> as placeholders for specifying
  38         the requirements below.
  39       </p>
  40 <h5>
  41 <a name="boost_asio.reference.asynchronous_operations.h0"></a>
  42         <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
  43         asynchronous operation concepts</a>
  44       </h5>
  45 <p>
  46         An <span class="emphasis"><em>initiating function</em></span> is a function which may be called
  47         to start an asynchronous operation. A <span class="emphasis"><em>completion handler</em></span>
  48         is a function object that will be invoked, at most once, with the result
  49         of the asynchronous operation.
  50       </p>
  51 <p>
  52         The lifecycle of an asynchronous operation is comprised of the following
  53         events and phases:
  54       </p>
  55 <p>
  56         &#8212; Event 1: The asynchronous operation is started by a call to the initiating
  57         function.
  58       </p>
  59 <p>
  60         &#8212; Phase 1: The asynchronous operation is now <span class="emphasis"><em>outstanding</em></span>.
  61       </p>
  62 <p>
  63         &#8212; Event 2: The externally observable side effects of the asynchronous operation,
  64         if any, are fully established. The completion handler is submitted to an
  65         executor.
  66       </p>
  67 <p>
  68         &#8212; Phase 2: The asynchronous operation is now <span class="emphasis"><em>completed</em></span>.
  69       </p>
  70 <p>
  71         &#8212; Event 3: The completion handler is called with the result of the asynchronous
  72         operation.
  73       </p>
  74 <p>
  75         In this library, all functions with the prefix <code class="computeroutput">async_</code> are initiating
  76         functions.
  77       </p>
  78 <h5>
  79 <a name="boost_asio.reference.asynchronous_operations.h1"></a>
  80         <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
  81         tokens and handlers</a>
  82       </h5>
  83 <p>
  84         Initiating functions:
  85       </p>
  86 <p>
  87         &#8212; are function templates with template parameter <code class="computeroutput">CompletionToken</code>;
  88       </p>
  89 <p>
  90         &#8212; accept, as the final parameter, a <span class="emphasis"><em>completion token</em></span> object
  91         <code class="computeroutput">token</code> of type <code class="computeroutput">CompletionToken</code>;
  92       </p>
  93 <p>
  94         &#8212; specify a <span class="emphasis"><em>completion signature</em></span>, which is a call signature
  95         (C++Std [func.def]) <code class="computeroutput">Signature</code> that determines the arguments
  96         to the completion handler.
  97       </p>
  98 <p>
  99         An initiating function determines the type <code class="computeroutput">CompletionHandler</code>
 100         of its completion handler function object by performing <code class="computeroutput">typename async_result&lt;decay_t&lt;CompletionToken&gt;,
 101         Signature&gt;::completion_handler_type</code>. The completion handler object
 102         <code class="computeroutput">completion_handler</code> is initialized with <code class="computeroutput">forward&lt;CompletionToken&gt;(token)</code>.
 103         [<span class="emphasis"><em>Note:</em></span> No other requirements are placed on the type
 104         <code class="computeroutput">CompletionToken</code>. &#8212;<span class="emphasis"><em>end note</em></span>]
 105       </p>
 106 <p>
 107         The type <code class="computeroutput">CompletionHandler</code> must satisfy the requirements of
 108         <code class="computeroutput">Destructible</code> (C++Std [destructible]) and <code class="computeroutput">MoveConstructible</code>
 109         (C++Std [moveconstructible]), and be callable with the specified call signature.
 110       </p>
 111 <p>
 112         In this library, all initiating functions specify a <span class="emphasis"><em>Completion
 113         signature</em></span> element that defines the call signature <code class="computeroutput">Signature</code>.
 114         The <span class="emphasis"><em>Completion signature</em></span> elements in this Technical
 115         Specification have named parameters, and the results of an asynchronous operation
 116         are specified in terms of these names.
 117       </p>
 118 <h5>
 119 <a name="boost_asio.reference.asynchronous_operations.h2"></a>
 120         <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
 121         deduction of initiating function return type</a>
 122       </h5>
 123 <p>
 124         The return type of an initiating function is <code class="computeroutput">typename async_result&lt;decay_t&lt;CompletionToken&gt;,
 125         Signature&gt;::return_type</code>.
 126       </p>
 127 <p>
 128         For the sake of exposition, this library sometimes annotates functions with
 129         a return type <span class="emphasis"><em><code class="literal">DEDUCED</code></em></span>. For every
 130         function declaration that returns <span class="emphasis"><em><code class="literal">DEDUCED</code></em></span>,
 131         the meaning is equivalent to specifying the return type as <code class="computeroutput">typename
 132         async_result&lt;decay_t&lt;CompletionToken&gt;, Signature&gt;::return_type</code>.
 133       </p>
 134 <h5>
 135 <a name="boost_asio.reference.asynchronous_operations.h3"></a>
 136         <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
 137         of initiating function return value</a>
 138       </h5>
 139 <p>
 140         An initiating function produces its return type as follows:
 141       </p>
 142 <p>
 143         &#8212; constructing an object <code class="computeroutput">result</code> of type <code class="computeroutput">async_result&lt;decay_t&lt;CompletionToken&gt;,
 144         Signature&gt;</code>, initialized as <code class="computeroutput">result(completion_handler)</code>;
 145         and
 146       </p>
 147 <p>
 148         &#8212; using <code class="computeroutput">result.get()</code> as the operand of the return statement.
 149       </p>
 150 <p>
 151         [<span class="emphasis"><em>Example:</em></span> Given an asynchronous operation with <span class="emphasis"><em>Completion
 152         signature</em></span> <code class="computeroutput">void(R1 r1, R2 r2)</code>, an initiating function
 153         meeting these requirements may be implemented as follows:
 154       </p>
 155 <pre class="programlisting">template&lt;class CompletionToken&gt;
 156 auto async_xyz(T1 t1, T2 t2, CompletionToken&amp;&amp; token)
 157 {
 158   typename async_result&lt;decay_t&lt;CompletionToken&gt;, void(R1, R2)&gt;::completion_handler_type
 159     completion_handler(forward&lt;CompletionToken&gt;(token));
 160
 161   async_result&lt;decay_t&lt;CompletionToken&gt;, void(R1, R2)&gt; result(completion_handler);
 162
 163   // initiate the operation and cause completion_handler to be invoked with
 164   // the result
 165
 166   return result.get();
 167 }
 168 </pre>
 169 <p>
 170         For convenience, initiating functions may be implemented using the <code class="computeroutput">async_completion</code>
 171         template:
 172       </p>
 173 <pre class="programlisting">template&lt;class CompletionToken&gt;
 174 auto async_xyz(T1 t1, T2 t2, CompletionToken&amp;&amp; token)
 175 {
 176   async_completion&lt;CompletionToken, void(R1, R2)&gt; init(token);
 177
 178   // initiate the operation and cause init.completion_handler to be invoked
 179   // with the result
 180
 181   return init.result.get();
 182 }
 183 </pre>
 184 <p>
 185         &#8212;<span class="emphasis"><em>end example</em></span>]
 186       </p>
 187 <h5>
 188 <a name="boost_asio.reference.asynchronous_operations.h4"></a>
 189         <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
 190         of initiating function arguments</a>
 191       </h5>
 192 <p>
 193         Unless otherwise specified, the lifetime of arguments to initiating functions
 194         shall be treated as follows:
 195       </p>
 196 <p>
 197         &#8212; If the parameter has a pointer type or has a type of lvalue reference to
 198         non-const, the implementation may assume the validity of the pointee or referent,
 199         respectively, until the completion handler is invoked. [<span class="emphasis"><em>Note:</em></span>
 200         In other words, the program must guarantee the validity of the argument until
 201         the completion handler is invoked. &#8212;<span class="emphasis"><em>end note</em></span>]
 202       </p>
 203 <p>
 204         &#8212; Otherwise, the implementation must not assume the validity of the argument
 205         after the initiating function completes. [<span class="emphasis"><em>Note:</em></span> In other
 206         words, the program is not required to guarantee the validity of the argument
 207         after the initiating function completes. &#8212;<span class="emphasis"><em>end note</em></span>] The
 208         implementation may make copies of the argument, and all copies shall be destroyed
 209         no later than immediately after invocation of the completion handler.
 210       </p>
 211 <h5>
 212 <a name="boost_asio.reference.asynchronous_operations.h5"></a>
 213         <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
 214         requirements on initiating functions</a>
 215       </h5>
 216 <p>
 217         An initiating function shall not block (C++Std [defns.block]) the calling
 218         thread pending completion of the outstanding operation.
 219       </p>
 220 <p>
 221         [std_note Initiating functions may still block the calling thread for other
 222         reasons. For example, an initiating function may lock a mutex in order to
 223         synchronize access to shared data.]
 224       </p>
 225 <h5>
 226 <a name="boost_asio.reference.asynchronous_operations.h6"></a>
 227         <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
 228         executor</a>
 229       </h5>
 230 <p>
 231         Certain objects that participate in asynchronous operations have an <span class="emphasis"><em>associated
 232         executor</em></span>. These are obtained as specified in the sections below.
 233       </p>
 234 <h5>
 235 <a name="boost_asio.reference.asynchronous_operations.h7"></a>
 236         <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
 237         I/O executor</a>
 238       </h5>
 239 <p>
 240         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.
 241         If not otherwise specified by the asynchronous operation, this associated
 242         executor is an object of type <code class="computeroutput">system_executor</code>.
 243       </p>
 244 <p>
 245         All asynchronous operations in this library have an associated executor object
 246         that is determined as follows:
 247       </p>
 248 <p>
 249         &#8212; If the initiating function is a member function, the associated executor
 250         is that returned by the <code class="computeroutput">get_executor</code> member function on the
 251         same object.
 252       </p>
 253 <p>
 254         &#8212; If the initiating function is not a member function, the associated executor
 255         is that returned by the <code class="computeroutput">get_executor</code> member function of the
 256         first argument to the initiating function.
 257       </p>
 258 <p>
 259         Let <code class="computeroutput">Executor1</code> be the type of the associated executor. Let <code class="computeroutput">ex1</code>
 260         be a value of type <code class="computeroutput">Executor1</code>, representing the associated executor
 261         object obtained as described above.
 262       </p>
 263 <h5>
 264 <a name="boost_asio.reference.asynchronous_operations.h8"></a>
 265         <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
 266         completion handler executor</a>
 267       </h5>
 268 <p>
 269         A completion handler object of type <code class="computeroutput">CompletionHandler</code> has an
 270         associated executor of type <code class="computeroutput">Executor2</code> satisfying the <a class="link" href="Executor1.html" title="Executor requirements">Executor
 271         requirements</a>. The type <code class="computeroutput">Executor2</code> is <code class="computeroutput">associated_executor_t&lt;CompletionHandler,
 272         Executor1&gt;</code>. Let <code class="computeroutput">ex2</code> be a value of type <code class="computeroutput">Executor2</code>
 273         obtained by performing <code class="computeroutput">get_associated_executor(completion_handler,
 274         ex1)</code>.
 275       </p>
 276 <h5>
 277 <a name="boost_asio.reference.asynchronous_operations.h9"></a>
 278         <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
 279         work</a>
 280       </h5>
 281 <p>
 282         Until the asynchronous operation has completed, the asynchronous operation
 283         shall maintain:
 284       </p>
 285 <p>
 286         &#8212; an object <code class="computeroutput">work1</code> of type <code class="computeroutput">executor_work_guard&lt;Executor1&gt;</code>,
 287         initialized as <code class="computeroutput">work1(ex1)</code>, and where <code class="computeroutput">work1.owns_work()
 288         == true</code>; and
 289       </p>
 290 <p>
 291         &#8212; an object <code class="computeroutput">work2</code> of type <code class="computeroutput">executor_work_guard&lt;Executor2&gt;</code>,
 292         initialized as <code class="computeroutput">work2(ex2)</code>, and where <code class="computeroutput">work2.owns_work()
 293         == true</code>.
 294       </p>
 295 <h5>
 296 <a name="boost_asio.reference.asynchronous_operations.h10"></a>
 297         <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
 298         of intermediate storage</a>
 299       </h5>
 300 <p>
 301         Asynchronous operations may allocate memory. [<span class="emphasis"><em>Note:</em></span>
 302         Such as a data structure to store copies of the <code class="computeroutput">completion_handler</code>
 303         object and the initiating function's arguments. &#8212;<span class="emphasis"><em>end note</em></span>]
 304       </p>
 305 <p>
 306         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>
 307         requirements, that represents the asynchronous operation's default allocation
 308         strategy. [<span class="emphasis"><em>Note:</em></span> Typically <code class="computeroutput">std::allocator&lt;void&gt;</code>.
 309         &#8212;<span class="emphasis"><em>end note</em></span>] Let <code class="computeroutput">alloc1</code> be a value of type
 310         <code class="computeroutput">Alloc1</code>.
 311       </p>
 312 <p>
 313         A completion handler object of type <code class="computeroutput">CompletionHandler</code> has an
 314         associated allocator object <code class="computeroutput">alloc2</code> of type <code class="computeroutput">Alloc2</code>
 315         satisfying the <a class="link" href="ProtoAllocator.html" title="Proto-allocator requirements"><code class="computeroutput">ProtoAllocator</code></a>
 316         requirements. The type <code class="computeroutput">Alloc2</code> is <code class="computeroutput">associated_allocator_t&lt;CompletionHandler,
 317         Alloc1&gt;</code>. Let <code class="computeroutput">alloc2</code> be a value of type <code class="computeroutput">Alloc2</code>
 318         obtained by performing <code class="computeroutput">get_associated_allocator(completion_handler,
 319         alloc1)</code>.
 320       </p>
 321 <p>
 322         The asynchronous operations defined in this library:
 323       </p>
 324 <p>
 325         &#8212; If required, allocate memory using only the completion handler's associated
 326         allocator.
 327       </p>
 328 <p>
 329         &#8212; Prior to completion handler execution, deallocate any memory allocated using
 330         the completion handler's associated allocator.
 331       </p>
 332 <p>
 333         [std_note The implementation may perform operating system or underlying API
 334         calls that perform memory allocations not using the associated allocator.
 335         Invocations of the allocator functions may not introduce data races (See
 336         C++Std [res.on.data.races]).]
 337       </p>
 338 <h5>
 339 <a name="boost_asio.reference.asynchronous_operations.h11"></a>
 340         <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
 341         of completion handler on completion of asynchronous operation</a>
 342       </h5>
 343 <p>
 344         Let <code class="computeroutput">Args...</code> be the argument types of the completion signature
 345         <code class="computeroutput">Signature</code> and let <code class="literal"><span class="emphasis"><em>N</em></span></code>
 346         be <code class="computeroutput">sizeof...(Args)</code>. Let <code class="literal"><span class="emphasis"><em>i</em></span></code>
 347         be in the range [<code class="computeroutput">0</code>,<code class="literal"><span class="emphasis"><em>N</em></span></code>).
 348         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
 349         type in <code class="computeroutput">Args...</code> and let <code class="literal">t[sub <span class="emphasis"><em>i</em></span></code>]
 350         be the <code class="literal"><span class="emphasis"><em>i</em></span></code>th completion handler argument
 351         associated with <code class="literal">T[sub <span class="emphasis"><em>i</em></span></code>].
 352       </p>
 353 <p>
 354         Let <code class="computeroutput">f</code> be a function object, callable as <code class="computeroutput">f()</code>, that
 355         invokes <code class="computeroutput">completion_handler</code> as if by <code class="literal">completion_handler(forward&lt;T[sub
 356         <span class="emphasis"><em>0</em></span></code>&gt;(t[sub <span class="emphasis"><em>0</em></span>]), ...,
 357         forward&lt;T[sub <span class="emphasis"><em>N-1</em></span>]&gt;(t[sub <span class="emphasis"><em>N-1</em></span>]))].
 358       </p>
 359 <p>
 360         If an asynchonous operation completes immediately (that is, within the thread
 361         of execution calling the initiating function, and before the initiating function
 362         returns), the completion handler shall be submitted for execution as if by
 363         performing <code class="computeroutput">ex2.post(std::move(f), alloc2)</code>. Otherwise, the completion
 364         handler shall be submitted for execution as if by performing <code class="computeroutput">ex2.dispatch(std::move(f),
 365         alloc2)</code>.
 366       </p>
 367 <h5>
 368 <a name="boost_asio.reference.asynchronous_operations.h12"></a>
 369         <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
 370         handlers and exceptions</a>
 371       </h5>
 372 <p>
 373         Completion handlers are permitted to throw exceptions. The effect of any
 374         exception propagated from the execution of a completion handler is determined
 375         by the executor which is executing the completion handler.
 376       </p>
 377 <h5>
 378 <a name="boost_asio.reference.asynchronous_operations.h13"></a>
 379         <span class="phrase"><a name="boost_asio.reference.asynchronous_operations.default_completion_tokens"></a></span><a class="link" href="asynchronous_operations.html#boost_asio.reference.asynchronous_operations.default_completion_tokens">Default
 380         completion tokens</a>
 381       </h5>
 382 <p>
 383         Every I/O executor type has an associated default completion token type.
 384         This is specified via the <code class="computeroutput">default_completion_token</code> trait. This
 385         trait may be used in asynchronous operation declarations as follows:
 386       </p>
 387 <pre class="programlisting">template &lt;
 388     typename IoObject,
 389     typename CompletionToken =
 390       typename default_completion_token&lt;
 391         typename IoObject::executor_type
 392       &gt;::type
 393   &gt;
 394 auto async_xyz(
 395     IoObject&amp; io_object,
 396     CompletionToken&amp;&amp; token =
 397       typename default_completion_token&lt;
 398         typename IoObject::executor_type
 399       &gt;::type{}
 400   );
 401 </pre>
 402 <p>
 403         If not specialised, this trait type is <code class="computeroutput">void</code>, meaning no default
 404         completion token type is available for the given I/O executor.
 405       </p>
 406 <p>
 407         [<span class="emphasis"><em>Example:</em></span> The <code class="computeroutput">default_completion_token</code>
 408         trait is specialised for the <code class="computeroutput">use_awaitable</code> completion token
 409         so that it may be used as shown in the following example:
 410       </p>
 411 <pre class="programlisting">auto socket = use_awaitable.as_default_on(tcp::socket(my_context));
 412 // ...
 413 co_await socket.async_connect(my_endpoint); // Defaults to use_awaitable.
 414 </pre>
 415 <p>
 416         In this example, the type of the <code class="computeroutput">socket</code> object is transformed
 417         from <code class="computeroutput">tcp::socket</code> to have an I/O executor with the default completion
 418         token set to <code class="computeroutput">use_awaitable</code>.
 419       </p>
 420 <p>
 421         Alternatively, the socket type may be computed directly:
 422       </p>
 423 <pre class="programlisting">using tcp_socket = use_awaitable_t&lt;&gt;::as_default_on_t&lt;tcp::socket&gt;;
 424 tcp_socket socket(my_context);
 425 // ...
 426 co_await socket.async_connect(my_endpoint); // Defaults to use_awaitable.
 427 </pre>
 428 <p>
 429         &#8212;<span class="emphasis"><em>end example</em></span>]
 430       </p>
 431 </div>
 432 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 433 <td align="left"></td>
 434 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2019 Christopher M. Kohlhoff<p>
 435         Distributed under the Boost Software License, Version 1.0. (See accompanying
 436         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>)
 437       </p>
 438 </div></td>
 439 </tr></table>
 440 <hr>
 441 <div class="spirit-nav">
 442 <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>
 443 </div>
 444 </body>
 445 </html>