tri11paragon
/
Insane_DNS
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Insane_DNS/libraries/asio-1.28.1/doc/asio/reference/asynchronous_operations.html

602 lines
54 KiB
HTML
Raw Normal View History

can extract domain names
2023-10-24 21:59:30 -04:00
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Requirements on asynchronous operations</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="../../index.html" title="Asio">
<link rel="up" href="../reference.html" title="Reference">
<link rel="prev" href="../reference.html" title="Reference">
<link rel="next" href="read_write_operations.html" title="Requirements on read and write operations">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="asio C++ library" width="250" height="60" src="../../asio.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../reference.html"><img src="../../prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../home.png" alt="Home"></a><a accesskey="n" href="read_write_operations.html"><img src="../../next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="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"><span class="identifier">Alloc1</span></code>,
<code class="computeroutput"><span class="identifier">Alloc2</span></code>, <code class="computeroutput"><span class="identifier">alloc1</span></code>,
<code class="computeroutput"><span class="identifier">alloc2</span></code>, <code class="computeroutput"><span class="identifier">Args</span></code>,
<code class="computeroutput"><span class="identifier">CompletionHandler</span></code>, <code class="computeroutput"><span class="identifier">completion_handler</span></code>, <code class="computeroutput"><span class="identifier">Executor1</span></code>,
<code class="computeroutput"><span class="identifier">Executor2</span></code>, <code class="computeroutput"><span class="identifier">ex1</span></code>, <code class="computeroutput"><span class="identifier">ex2</span></code>,
<code class="computeroutput"><span class="identifier">f</span></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"><span class="identifier">Signatures</span></code>,
<code class="computeroutput"><span class="identifier">token</span></code>, <code class="computeroutput"><span class="identifier">initiation</span></code>,
<code class="computeroutput"><span class="identifier">Initiation</span></code>, <code class="literal">T<sub><span class="emphasis"><em>i</em></span></sub></code>,
<code class="literal">t<sub><span class="emphasis"><em>i</em></span></sub></code>, <code class="computeroutput"><span class="identifier">work1</span></code>,
and <code class="computeroutput"><span class="identifier">work2</span></code> as placeholders
for specifying the requirements below.
</p>
<h5>
<a name="asio.reference.asynchronous_operations.h0"></a>
<span><a name="asio.reference.asynchronous_operations.general_asynchronous_operation_concepts"></a></span><a class="link" href="asynchronous_operations.html#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"><span class="identifier">async_</span></code>
are initiating functions.
</p>
<h5>
<a name="asio.reference.asynchronous_operations.h1"></a>
<span><a name="asio.reference.asynchronous_operations.completion_tokens_and_handlers"></a></span><a class="link" href="asynchronous_operations.html#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"><span class="identifier">CompletionToken</span></code>;
</p>
<p>
— accept, as the final parameter, a <span class="emphasis"><em>completion token</em></span> object
<code class="computeroutput"><span class="identifier">token</span></code> of type <code class="computeroutput"><span class="identifier">CompletionToken</span></code>;
</p>
<p>
— specify one or more <span class="emphasis"><em>completion signatures</em></span>, referred
to below as a variadic pack of call signatures (C++Std [func.def]) <code class="computeroutput"><span class="identifier">Signatures</span></code>, that determine the possible
argument sets to the completion handler.
</p>
<p>
In this library, initiating functions specify a <span class="emphasis"><em>Completion signature</em></span>
element that defines the call signatures <code class="computeroutput"><span class="identifier">Signatures</span></code>.
The <span class="emphasis"><em>Completion signature</em></span> elements in this library may
have named parameters, and the results of an asynchronous operation may be
specified in terms of these names.
</p>
<p>
Completion token behaviour is determined through specialisation of the <code class="computeroutput"><span class="identifier">async_result</span></code> trait. These specialisations
must have the form:
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">CompletionToken</span><span class="special">,</span> <span class="keyword">class</span><span class="special">...</span> <span class="identifier">Signatures</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">async_result</span>
<span class="special">{</span>
<span class="keyword">template</span><span class="special">&lt;</span>
<span class="keyword">class</span> <span class="identifier">Initiation</span><span class="special">,</span>
<span class="keyword">class</span> <span class="identifier">RawCompletionToken</span><span class="special">,</span>
<span class="keyword">class</span><span class="special">...</span> <span class="identifier">Args</span>
<span class="special">&gt;</span>
<span class="keyword">static</span> <span class="identifier">initiating</span><span class="special">-</span><span class="identifier">fn</span><span class="special">-</span><span class="keyword">return</span><span class="special">-</span><span class="identifier">type</span> <span class="identifier">initiate</span><span class="special">(</span>
<span class="identifier">Initiation</span><span class="special">&amp;&amp;</span> <span class="identifier">initiation</span><span class="special">,</span>
<span class="identifier">RawCompletionToken</span><span class="special">&amp;&amp;</span> <span class="identifier">token</span><span class="special">,</span>
<span class="identifier">Args</span><span class="special">&amp;&amp;...</span> <span class="identifier">args</span>
<span class="special">);</span>
<span class="special">};</span>
</pre>
<p>
An <code class="computeroutput"><span class="identifier">async_result</span></code> specialisation’s
implementation of the <code class="computeroutput"><span class="identifier">initiate</span><span class="special">()</span></code> static member function must:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
Transform the completion token into an object <code class="computeroutput"><span class="identifier">completion_handler</span></code>
of type <code class="computeroutput"><span class="identifier">CompletionHandler</span></code>.
The type <code class="computeroutput"><span class="identifier">CompletionHandler</span></code>
must satisfy the requirements of <code class="computeroutput"><span class="identifier">Destructible</span></code>
(C++Std [destructible]) and <code class="computeroutput"><span class="identifier">MoveConstructible</span></code>
(C++Std [moveconstructible]), and be callable with the specified call
signatures.
</li>
<li class="listitem">
<p class="simpara">
Cause the invocation of the function object <code class="computeroutput"><span class="identifier">initiation</span></code>
as if by calling:
</p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">forward</span><span class="special">&lt;</span><span class="identifier">Initiation</span><span class="special">&gt;(</span><span class="identifier">initiation</span><span class="special">)(</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">completion_handler</span><span class="special">),</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">forward</span><span class="special">&lt;</span><span class="identifier">Args</span><span class="special">&gt;(</span><span class="identifier">args</span><span class="special">)...);</span>
</pre>
</li>
</ul></div>
<p>
This invocation of <code class="computeroutput"><span class="identifier">initiation</span></code>
may be immediate, or it may be deferred (e.g. to support lazy evaluation).
If <code class="computeroutput"><span class="identifier">initiation</span></code> is deferred,
the <code class="computeroutput"><span class="identifier">initiation</span></code> and <code class="computeroutput"><span class="identifier">args</span><span class="special">...</span></code>
objects must be decay-copied and moved as required.
</p>
<p>
The <code class="computeroutput"><span class="identifier">async_result</span></code> trait must
be specialised for the decayed type of a <code class="computeroutput"><span class="identifier">CompletionToken</span></code>.
A helper function template <code class="computeroutput"><span class="identifier">async_initiate</span></code>
is provided to simplify correct invocation of <code class="computeroutput"><span class="identifier">async_result</span><span class="special">&lt;&gt;::</span><span class="identifier">initiate</span></code>
for the appropriate specialisation:
</p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span>
<span class="keyword">class</span> <span class="identifier">CompletionToken</span><span class="special">,</span>
<span class="identifier">completion_signature</span><span class="special">...</span> <span class="identifier">Signatures</span><span class="special">,</span>
<span class="keyword">class</span> <span class="identifier">Initiation</span><span class="special">,</span>
<span class="keyword">class</span><span class="special">...</span> <span class="identifier">Args</span>
<span class="special">&gt;</span>
<span class="emphasis"><em>DEDUCED</em></span> <span class="identifier">async_initiate</span><span class="special">(</span>
<span class="identifier">Initiation</span><span class="special">&amp;&amp;</span> <span class="identifier">initiation</span><span class="special">,</span>
<span class="identifier">CompletionToken</span><span class="special">&amp;</span> <span class="identifier">token</span><span class="special">,</span>
<span class="identifier">Args</span><span class="special">&amp;&amp;...</span> <span class="identifier">args</span>
<span class="special">);</span>
</pre>
<p>
[<span class="emphasis"><em>Note:</em></span> No other requirements are placed on the type
<code class="computeroutput"><span class="identifier">CompletionToken</span></code>. —<span class="emphasis"><em>end
note</em></span>]
</p>
<h5>
<a name="asio.reference.asynchronous_operations.h2"></a>
<span><a name="asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type"></a></span><a class="link" href="asynchronous_operations.html#asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type">Automatic
deduction of initiating function return type</a>
</h5>
<p>
An initiating function returns <code class="literal">async_initiate&lt;CompletionToken,
Signatures...&gt;(initiation, token, <span class="emphasis"><em>unspecified-args...</em></span>)</code>,
where <code class="computeroutput"><span class="identifier">initiation</span></code> is a function
object of unspecified type <code class="computeroutput"><span class="identifier">Initiation</span></code>,
which is defined as:
</p>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">Initiation</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">using</span> <span class="identifier">executor_type</span> <span class="special">=</span> <span class="identifier">Executor</span><span class="special">;</span> <span class="comment">// optional</span>
<span class="identifier">executor_type</span> <span class="identifier">get_executor</span><span class="special">()</span> <span class="keyword">const</span> <span class="keyword">noexcept</span><span class="special">;</span> <span class="comment">// optional</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">CompletionHandler</span><span class="special">,</span> <span class="emphasis"><em>unspecified-args...</em></span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">CompletionHandler</span><span class="special">&amp;&amp;</span> <span class="identifier">completion_handler</span><span class="special">,</span> <span class="emphasis"><em>unspecified-args...</em></span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<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 an automatically deduced return type, having
the type of the expression <code class="literal">async_initiate&lt;CompletionToken, Signatures...&gt;(initiation,
token, <span class="emphasis"><em>unspecified-args...</em></span>)</code>.
</p>
<p>
[<span class="emphasis"><em>Example:</em></span> Given an asynchronous operation with a single
<span class="emphasis"><em>Completion signature</em></span> <code class="computeroutput"><span class="keyword">void</span><span class="special">(</span><span class="identifier">R1</span> <span class="identifier">r1</span><span class="special">,</span> <span class="identifier">R2</span> <span class="identifier">r2</span><span class="special">)</span></code>, an initiating function meeting these requirements
may be implemented as follows:
</p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">CompletionToken</span><span class="special">&gt;</span>
<span class="keyword">auto</span> <span class="identifier">async_xyz</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">t1</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">t2</span><span class="special">,</span> <span class="identifier">CompletionToken</span><span class="special">&amp;&amp;</span> <span class="identifier">token</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">async_initiate</span><span class="special">&lt;</span><span class="identifier">CompletionToken</span><span class="special">,</span> <span class="keyword">void</span><span class="special">(</span><span class="identifier">R1</span><span class="special">,</span> <span class="identifier">R2</span><span class="special">)&gt;(</span>
<span class="special">[](</span><span class="keyword">auto</span> <span class="identifier">completion_handler</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">t1</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">t2</span><span class="special">)</span>
<span class="special">{</span>
<span class="comment">// initiate the operation and cause completion_handler to be invoked</span>
<span class="comment">// with the result</span>
<span class="special">},</span> <span class="identifier">token</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">t1</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">t2</span><span class="special">));</span>
<span class="special">}</span>
</pre>
<p>
The concepts <code class="computeroutput"><span class="identifier">completion_token_for</span></code>
and <code class="computeroutput"><span class="identifier">completion_handler_for</span></code>
may also be used to improve compile-time diagnostics:
</p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="identifier">completion_token_for</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">(</span><span class="identifier">R1</span><span class="special">,</span> <span class="identifier">R2</span><span class="special">)&gt;</span> <span class="identifier">CompletionToken</span><span class="special">&gt;</span>
<span class="keyword">auto</span> <span class="identifier">async_xyz</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">t1</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">t2</span><span class="special">,</span> <span class="identifier">CompletionToken</span><span class="special">&amp;&amp;</span> <span class="identifier">token</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">async_initiate</span><span class="special">&lt;</span><span class="identifier">CompletionToken</span><span class="special">,</span> <span class="keyword">void</span><span class="special">(</span><span class="identifier">R1</span><span class="special">,</span> <span class="identifier">R2</span><span class="special">)&gt;(</span>
<span class="special">[](</span><span class="identifier">completion_handler_for</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">(</span><span class="identifier">R1</span><span class="special">,</span> <span class="identifier">R2</span><span class="special">)&gt;</span> <span class="keyword">auto</span> <span class="identifier">completion_handler</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">t1</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">t2</span><span class="special">)</span>
<span class="special">{</span>
<span class="comment">// initiate the operation and cause completion_handler to be invoked</span>
<span class="comment">// with the result</span>
<span class="special">},</span> <span class="identifier">token</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">t1</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">t2</span><span class="special">));</span>
<span class="special">}</span>
</pre>
<p>
Initiation functions may also be implemented using the <code class="computeroutput"><span class="identifier">async_result</span></code>
trait directly:
</p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">CompletionToken</span><span class="special">&gt;</span>
<span class="keyword">auto</span> <span class="identifier">async_xyz</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">t1</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">t2</span><span class="special">,</span> <span class="identifier">CompletionToken</span><span class="special">&amp;&amp;</span> <span class="identifier">token</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">async_result</span><span class="special">&lt;</span><span class="identifier">decay_t</span><span class="special">&lt;</span><span class="identifier">CompletionToken</span><span class="special">&gt;,</span> <span class="keyword">void</span><span class="special">(</span><span class="identifier">R1</span><span class="special">,</span> <span class="identifier">R2</span><span class="special">)&gt;::</span><span class="identifier">initiate</span><span class="special">(</span>
<span class="special">[](</span><span class="keyword">auto</span> <span class="identifier">completion_handler</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">t1</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">t2</span><span class="special">)</span>
<span class="special">{</span>
<span class="comment">// initiate the operation and cause completion_handler to be invoked</span>
<span class="comment">// with the result</span>
<span class="special">},</span> <span class="identifier">forward</span><span class="special">&lt;</span><span class="identifier">CompletionToken</span><span class="special">&gt;(</span><span class="identifier">token</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">t1</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">t2</span><span class="special">));</span>
<span class="special">}</span>
</pre>
<p>
Note the use of <code class="computeroutput"><span class="identifier">decay_t</span></code> and
<code class="computeroutput"><span class="identifier">forward</span></code> applied to the <code class="computeroutput"><span class="identifier">CompletionToken</span></code> type. However, the first
form is preferred as it preserves compatibility with legacy completion token
requirements.
</p>
<p>
—<span class="emphasis"><em>end example</em></span>]
</p>
<h5>
<a name="asio.reference.asynchronous_operations.h3"></a>
<span><a name="asio.reference.asynchronous_operations.lifetime_of_initiating_function_arguments"></a></span><a class="link" href="asynchronous_operations.html#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="asio.reference.asynchronous_operations.h4"></a>
<span><a name="asio.reference.asynchronous_operations.non_blocking_requirements_on_initiating_functions"></a></span><a class="link" href="asynchronous_operations.html#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>
[<span class="emphasis"><em>Note:</em></span> 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. —<span class="emphasis"><em>end note</em></span>]
</p>
<h5>
<a name="asio.reference.asynchronous_operations.h5"></a>
<span><a name="asio.reference.asynchronous_operations.associated_executor"></a></span><a class="link" href="asynchronous_operations.html#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="asio.reference.asynchronous_operations.h6"></a>
<span><a name="asio.reference.asynchronous_operations.associated_i_o_executor"></a></span><a class="link" href="asynchronous_operations.html#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"><span class="identifier">Executor</span></code></a>
requirements. If not otherwise specified by the asynchronous operation, this
associated executor is an object of type <code class="computeroutput"><span class="identifier">system_executor</span></code>.
</p>
<p>
All asynchronous operations in this library have an associated I/O 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"><span class="identifier">get_executor</span></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"><span class="identifier">get_executor</span></code>
member function of the first argument to the initiating function.
</p>
<p>
The operation's associated I/O executor may be exposed via the <code class="computeroutput"><span class="identifier">Initiation</span></code> function object's <code class="computeroutput"><span class="identifier">executor_type</span></code> type alias and <code class="computeroutput"><span class="identifier">get_executor</span><span class="special">()</span></code>
member function.
</p>
<p>
Let <code class="computeroutput"><span class="identifier">Executor1</span></code> be the type
of the associated executor. Let <code class="computeroutput"><span class="identifier">ex1</span></code>
be a value of type <code class="computeroutput"><span class="identifier">Executor1</span></code>,
representing the associated executor object obtained as described above.
</p>
<h5>
<a name="asio.reference.asynchronous_operations.h7"></a>
<span><a name="asio.reference.asynchronous_operations.associated_completion_handler_executor"></a></span><a class="link" href="asynchronous_operations.html#asio.reference.asynchronous_operations.associated_completion_handler_executor">Associated
completion handler executor</a>
</h5>
<p>
A completion handler object of type <code class="computeroutput"><span class="identifier">CompletionHandler</span></code>
has an associated executor of type <code class="computeroutput"><span class="identifier">Executor2</span></code>
satisfying the <a class="link" href="Executor1.html" title="Executor requirements">Executor requirements</a>.
The type <code class="computeroutput"><span class="identifier">Executor2</span></code> is <code class="computeroutput"><span class="identifier">associated_executor_t</span><span class="special">&lt;</span><span class="identifier">CompletionHandler</span><span class="special">,</span>
<span class="identifier">Executor1</span><span class="special">&gt;</span></code>.
Let <code class="computeroutput"><span class="identifier">ex2</span></code> be a value of type
<code class="computeroutput"><span class="identifier">Executor2</span></code> obtained by performing
<code class="computeroutput"><span class="identifier">get_associated_executor</span><span class="special">(</span><span class="identifier">completion_handler</span><span class="special">,</span>
<span class="identifier">ex1</span><span class="special">)</span></code>.
</p>
<h5>
<a name="asio.reference.asynchronous_operations.h8"></a>
<span><a name="asio.reference.asynchronous_operations.associated_immediate_completion_executor"></a></span><a class="link" href="asynchronous_operations.html#asio.reference.asynchronous_operations.associated_immediate_completion_executor">Associated
immediate completion executor</a>
</h5>
<p>
A completion handler object of type <code class="computeroutput"><span class="identifier">CompletionHandler</span></code>
has an associated immediate executor of type <code class="computeroutput"><span class="identifier">Executor3</span></code>
satisfying the <a class="link" href="Executor1.html" title="Executor requirements">Executor requirements</a>.
The type <code class="computeroutput"><span class="identifier">Executor3</span></code> is <code class="computeroutput"><span class="identifier">associated_immediate_executor_t</span><span class="special">&lt;</span><span class="identifier">CompletionHandler</span><span class="special">,</span>
<span class="identifier">Executor1</span><span class="special">&gt;</span></code>.
Let <code class="computeroutput"><span class="identifier">ex3</span></code> be a value of type
<code class="computeroutput"><span class="identifier">Executor3</span></code> obtained by performing
<code class="computeroutput"><span class="identifier">get_associated_immediate_executor</span><span class="special">(</span><span class="identifier">completion_handler</span><span class="special">,</span> <span class="identifier">ex1</span><span class="special">)</span></code>.
</p>
<h5>
<a name="asio.reference.asynchronous_operations.h9"></a>
<span><a name="asio.reference.asynchronous_operations.outstanding_work"></a></span><a class="link" href="asynchronous_operations.html#asio.reference.asynchronous_operations.outstanding_work">Outstanding
work</a>
</h5>
<p>
If the operation does not complete immediately (that is, the operation does
not complete within the thread of execution calling the initiating function,
before the initiating function returns) then, until the asynchronous operation
has completed, the asynchronous operation shall maintain:
</p>
<p>
— an object <code class="computeroutput"><span class="identifier">work1</span></code> of type
<code class="computeroutput"><span class="identifier">executor_work_guard</span><span class="special">&lt;</span><span class="identifier">Executor1</span><span class="special">&gt;</span></code>,
initialized as <code class="computeroutput"><span class="identifier">work1</span><span class="special">(</span><span class="identifier">ex1</span><span class="special">)</span></code>, and
where <code class="computeroutput"><span class="identifier">work1</span><span class="special">.</span><span class="identifier">owns_work</span><span class="special">()</span> <span class="special">==</span> <span class="keyword">true</span></code>; and
</p>
<p>
— an object <code class="computeroutput"><span class="identifier">work2</span></code> of type
<code class="computeroutput"><span class="identifier">executor_work_guard</span><span class="special">&lt;</span><span class="identifier">Executor2</span><span class="special">&gt;</span></code>,
initialized as <code class="computeroutput"><span class="identifier">work2</span><span class="special">(</span><span class="identifier">ex2</span><span class="special">)</span></code>, and
where <code class="computeroutput"><span class="identifier">work2</span><span class="special">.</span><span class="identifier">owns_work</span><span class="special">()</span> <span class="special">==</span> <span class="keyword">true</span></code>.
</p>
<h5>
<a name="asio.reference.asynchronous_operations.h10"></a>
<span><a name="asio.reference.asynchronous_operations.allocation_of_intermediate_storage"></a></span><a class="link" href="asynchronous_operations.html#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"><span class="identifier">completion_handler</span></code>
object and the initiating function's arguments. —<span class="emphasis"><em>end note</em></span>]
</p>
<p>
Let <code class="computeroutput"><span class="identifier">Alloc1</span></code> be a type, satisfying
the <a class="link" href="ProtoAllocator.html" title="Proto-allocator requirements"><code class="computeroutput"><span class="identifier">ProtoAllocator</span></code></a>
requirements, that represents the asynchronous operation's default allocation
strategy. [<span class="emphasis"><em>Note:</em></span> Typically <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span></code>.
—<span class="emphasis"><em>end note</em></span>] Let <code class="computeroutput"><span class="identifier">alloc1</span></code>
be a value of type <code class="computeroutput"><span class="identifier">Alloc1</span></code>.
</p>
<p>
A completion handler object of type <code class="computeroutput"><span class="identifier">CompletionHandler</span></code>
has an associated allocator object <code class="computeroutput"><span class="identifier">alloc2</span></code>
of type <code class="computeroutput"><span class="identifier">Alloc2</span></code> satisfying
the <a class="link" href="ProtoAllocator.html" title="Proto-allocator requirements"><code class="computeroutput"><span class="identifier">ProtoAllocator</span></code></a>
requirements. The type <code class="computeroutput"><span class="identifier">Alloc2</span></code>
is <code class="computeroutput"><span class="identifier">associated_allocator_t</span><span class="special">&lt;</span><span class="identifier">CompletionHandler</span><span class="special">,</span> <span class="identifier">Alloc1</span><span class="special">&gt;</span></code>. Let <code class="computeroutput"><span class="identifier">alloc2</span></code>
be a value of type <code class="computeroutput"><span class="identifier">Alloc2</span></code>
obtained by performing <code class="computeroutput"><span class="identifier">get_associated_allocator</span><span class="special">(</span><span class="identifier">completion_handler</span><span class="special">,</span> <span class="identifier">alloc1</span><span class="special">)</span></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>
[<span class="emphasis"><em>Note:</em></span> 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]). —<span class="emphasis"><em>end note</em></span>]
</p>
<h5>
<a name="asio.reference.asynchronous_operations.h11"></a>
<span><a name="asio.reference.asynchronous_operations.execution_of_completion_handler_on_completion_of_asynchronous_operation"></a></span><a class="link" href="asynchronous_operations.html#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"><span class="identifier">Args</span><span class="special">...</span></code>
be the argument types of a completion signature in <code class="computeroutput"><span class="identifier">Signatures</span><span class="special">...</span></code> and let <code class="literal"><span class="emphasis"><em>N</em></span></code>
be <code class="computeroutput"><span class="keyword">sizeof</span><span class="special">...(</span><span class="identifier">Args</span><span class="special">)</span></code>.
Let <code class="literal"><span class="emphasis"><em>i</em></span></code> be in the range [<code class="computeroutput"><span class="number">0</span></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></sub></code> be the <code class="literal"><span class="emphasis"><em>i</em></span></code>th
type in <code class="computeroutput"><span class="identifier">Args</span><span class="special">...</span></code>
and let <code class="literal">t<sub><span class="emphasis"><em>i</em></span></sub></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></sub></code>.
</p>
<p>
Let <code class="computeroutput"><span class="identifier">f</span></code> be a function object
that:
</p>
<p>
— is callable as <code class="computeroutput"><span class="identifier">f</span><span class="special">()</span></code>,
and when so called invokes <code class="computeroutput"><span class="identifier">completion_handler</span></code>
as if by <code class="literal">std::move(completion_handler)(forward&lt;T<sub><span class="emphasis"><em>0</em></span></sub>&gt;(t<sub><span class="emphasis"><em>0</em></span></sub>),
..., forward&lt;T<sub><span class="emphasis"><em>N-1</em></span></sub>&gt;(t<sub><span class="emphasis"><em>N-1</em></span></sub>))</code>;
</p>
<p>
— has an associated executor such that <code class="computeroutput"><span class="identifier">get_associated_executor</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span>
<span class="identifier">ex1</span><span class="special">)</span></code>
returns an executor that is equal to <code class="computeroutput"><span class="identifier">ex2</span></code>;
and
</p>
<p>
— has an associated allocator such that <code class="computeroutput"><span class="identifier">get_associated_allocator</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span>
<span class="identifier">alloc1</span><span class="special">)</span></code>
returns an allocator that is equal to <code class="computeroutput"><span class="identifier">alloc2</span></code>.
</p>
<p>
[<span class="emphasis"><em>Note:</em></span> These associated executor and allocator requirements
on <code class="computeroutput"><span class="identifier">f</span></code> are typically implemented
by specialising the associator traits for <code class="computeroutput"><span class="identifier">f</span></code>
so that they forward to the associator traits for <code class="computeroutput"><span class="identifier">completion_handler</span></code>.
—<span class="emphasis"><em>end note</em></span>]
</p>
<p>
If an asynchonous operation completes immediately (that is, the operation
completes 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"><span class="identifier">post</span><span class="special">(</span><span class="identifier">ex1</span><span class="special">,</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">f</span><span class="special">))</span></code>.
</p>
<p>
Otherwise, when the operation completes, the completion handler shall be
submitted for execution as if by performing <code class="computeroutput"><span class="identifier">dispatch</span><span class="special">(</span><span class="identifier">ex2</span><span class="special">,</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">f</span><span class="special">))</span></code>.
</p>
<h5>
<a name="asio.reference.asynchronous_operations.h12"></a>
<span><a name="asio.reference.asynchronous_operations.optimisation_of_immediate_completion"></a></span><a class="link" href="asynchronous_operations.html#asio.reference.asynchronous_operations.optimisation_of_immediate_completion">Optimisation
of immediate completion</a>
</h5>
<p>
If an asynchronous operation completes immediately then, as an optimisation,
the operation may either:
</p>
<p>
— obtain the associated immediate completion executor <code class="computeroutput"><span class="identifier">ex3</span></code>
by performing <code class="computeroutput"><span class="identifier">get_associated_immediate_executor</span><span class="special">(</span><span class="identifier">completion_handler</span><span class="special">,</span> <span class="identifier">ex1</span><span class="special">)</span></code>,
and then submit the completion handler for execution as if by performing
<code class="computeroutput"><span class="identifier">dispatch</span><span class="special">(</span><span class="identifier">ex3</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">f</span><span class="special">))</span></code>;
or
</p>
<p>
— submit the completion handler for execution by performing the expression
<code class="computeroutput"><span class="identifier">post</span><span class="special">(</span><span class="identifier">ex2</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">f</span><span class="special">))</span></code>,
if that expression is well-formed.
</p>
<p>
[<span class="emphasis"><em>Note:</em></span> If <code class="computeroutput"><span class="identifier">completion_handler</span></code>
does not customise the associated immediate executor, the behaviour of the
first optimisation is equivalent to <code class="computeroutput"><span class="identifier">post</span><span class="special">(</span><span class="identifier">ex1</span><span class="special">,</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">f</span><span class="special">))</span></code>. —<span class="emphasis"><em>end note</em></span>]
</p>
<h5>
<a name="asio.reference.asynchronous_operations.h13"></a>
<span><a name="asio.reference.asynchronous_operations.completion_handlers_and_exceptions"></a></span><a class="link" href="asynchronous_operations.html#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>
<h5>
<a name="asio.reference.asynchronous_operations.h14"></a>
<span><a name="asio.reference.asynchronous_operations.default_completion_tokens"></a></span><a class="link" href="asynchronous_operations.html#asio.reference.asynchronous_operations.default_completion_tokens">Default
completion tokens</a>
</h5>
<p>
Every I/O executor type has an associated default completion token type.
This is specified via the <code class="computeroutput"><span class="identifier">default_completion_token</span></code>
trait. This trait may be used in asynchronous operation declarations as follows:
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span>
<span class="keyword">typename</span> <span class="identifier">IoObject</span><span class="special">,</span>
<span class="keyword">typename</span> <span class="identifier">CompletionToken</span> <span class="special">=</span>
<span class="keyword">typename</span> <span class="identifier">default_completion_token</span><span class="special">&lt;</span>
<span class="keyword">typename</span> <span class="identifier">IoObject</span><span class="special">::</span><span class="identifier">executor_type</span>
<span class="special">&gt;::</span><span class="identifier">type</span>
<span class="special">&gt;</span>
<span class="keyword">auto</span> <span class="identifier">async_xyz</span><span class="special">(</span>
<span class="identifier">IoObject</span><span class="special">&amp;</span> <span class="identifier">io_object</span><span class="special">,</span>
<span class="identifier">CompletionToken</span><span class="special">&amp;&amp;</span> <span class="identifier">token</span> <span class="special">=</span>
<span class="keyword">typename</span> <span class="identifier">default_completion_token</span><span class="special">&lt;</span>
<span class="keyword">typename</span> <span class="identifier">IoObject</span><span class="special">::</span><span class="identifier">executor_type</span>
<span class="special">&gt;::</span><span class="identifier">type</span><span class="special">{}</span>
<span class="special">);</span>
</pre>
<p>
If not specialised, this trait type is <code class="computeroutput"><span class="keyword">void</span></code>,
meaning no default completion token type is available for the given I/O executor.
</p>
<p>
[<span class="emphasis"><em>Example:</em></span> The <code class="computeroutput"><span class="identifier">default_completion_token</span></code>
trait is specialised for the <code class="computeroutput"><span class="identifier">use_awaitable</span></code>
completion token so that it may be used as shown in the following example:
</p>
<pre class="programlisting"><span class="keyword">auto</span> <span class="identifier">socket</span> <span class="special">=</span> <span class="identifier">use_awaitable</span><span class="special">.</span><span class="identifier">as_default_on</span><span class="special">(</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">(</span><span class="identifier">my_context</span><span class="special">));</span>
<span class="comment">// ...</span>
<span class="identifier">co_await</span> <span class="identifier">socket</span><span class="special">.</span><span class="identifier">async_connect</span><span class="special">(</span><span class="identifier">my_endpoint</span><span class="special">);</span> <span class="comment">// Defaults to use_awaitable.</span>
</pre>
<p>
In this example, the type of the <code class="computeroutput"><span class="identifier">socket</span></code>
object is transformed from <code class="computeroutput"><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span></code>
to have an I/O executor with the default completion token set to <code class="computeroutput"><span class="identifier">use_awaitable</span></code>.
</p>
<p>
Alternatively, the socket type may be computed directly:
</p>
<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">tcp_socket</span> <span class="special">=</span> <span class="identifier">use_awaitable_t</span><span class="special">&lt;&gt;::</span><span class="identifier">as_default_on_t</span><span class="special">&lt;</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">&gt;;</span>
<span class="identifier">tcp_socket</span> <span class="identifier">socket</span><span class="special">(</span><span class="identifier">my_context</span><span class="special">);</span>
<span class="comment">// ...</span>
<span class="identifier">co_await</span> <span class="identifier">socket</span><span class="special">.</span><span class="identifier">async_connect</span><span class="special">(</span><span class="identifier">my_endpoint</span><span class="special">);</span> <span class="comment">// Defaults to use_awaitable.</span>
</pre>
<p>
—<span class="emphasis"><em>end example</em></span>]
</p>
</div>
<div class="copyright-footer">Copyright © 2003-2023 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>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../reference.html"><img src="../../prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../home.png" alt="Home"></a><a accesskey="n" href="read_write_operations.html"><img src="../../next.png" alt="Next"></a>
</div>
</body>
</html>