[DEV] add v1.76.0

This commit is contained in:
2021-10-05 21:37:46 +02:00
parent a97e9ae7d4
commit d0115b733d
45133 changed files with 4744437 additions and 1026325 deletions

View File

@@ -0,0 +1,412 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Executor requirements</title>
<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../boost_asio.html" title="Boost.Asio">
<link rel="up" href="../reference.html" title="Reference">
<link rel="prev" href="ExecutionContext.html" title="Execution context requirements">
<link rel="next" href="GettableSerialPortOption.html" title="Gettable serial port option requirements">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
<td align="center"><a href="../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="ExecutionContext.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="GettableSerialPortOption.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_asio.reference.Executor1"></a><a class="link" href="Executor1.html" title="Executor requirements">Executor requirements</a>
</h3></div></div></div>
<h5>
<a name="boost_asio.reference.Executor1.h0"></a>
<span class="phrase"><a name="boost_asio.reference.Executor1.standard_executors"></a></span><a class="link" href="Executor1.html#boost_asio.reference.Executor1.standard_executors">Standard
executors</a>
</h5>
<p>
Let <code class="computeroutput">executor-of-impl</code> be the exposition-only concept
</p>
<pre class="programlisting">template&lt;class E, class F&gt;
concept executor-of-impl =
invocable&lt;decay_t&lt;F&gt;&amp;&gt; &amp;&amp;
constructible_from&lt;decay_t&lt;F&gt;, F&gt; &amp;&amp;
move_constructible&lt;decay_t&lt;F&gt;&gt; &amp;&amp;
copy_constructible&lt;E&gt; &amp;&amp;
is_nothrow_copy_constructible_v&lt;E&gt; &amp;&amp;
equality_comparable&lt;E&gt; /* nothrow */ &amp;&amp;
requires(const E&amp; e, F&amp;&amp; f) {
execution::execute(e, (F&amp;&amp;)f);
};
</pre>
<p>
Then the <code class="computeroutput">executor</code> and <code class="computeroutput">executor_of</code> concepts are
defined as follows:
</p>
<pre class="programlisting">template&lt;class E&gt;
concept executor =
executor-of-impl&lt;E, execution::invocable_archetype&gt;;
template&lt;class E, class F&gt;
concept executor_of =
executor&lt;E&gt; &amp;&amp;
executor-of-impl&lt;E, F&gt;;
</pre>
<p>
Neither an executor's equality comparison nor <code class="computeroutput">swap</code> operation
shall exit via an exception.
</p>
<p>
None of an executor type's copy constructor, destructor, equality comparison,
<code class="computeroutput">swap</code> function, <code class="computeroutput">execute</code> function, or associated
<code class="computeroutput">query</code> functions shall introduce data races as a result of concurrent
invocations of those functions from different threads.
</p>
<p>
For any two (possibly const) values <code class="computeroutput">x1</code> and <code class="computeroutput">x2</code> of
some executor type <code class="computeroutput">X</code>, <code class="computeroutput">x1 == x2</code> shall return <code class="computeroutput">true</code>
only if <code class="computeroutput">boost::asio::query(x1,p) == boost::asio::query(x2,p)</code>
for every property <code class="computeroutput">p</code> where both <code class="computeroutput">boost::asio::query(x1,p)</code>
and <code class="computeroutput">boost::asio::query(x2,p)</code> are well-formed and result in a
non-void type that is <code class="computeroutput">equality_comparable</code> (C++Std [equalitycomparable]).
[<span class="emphasis"><em>Note:</em></span> The above requirements imply that <code class="computeroutput">x1 ==
x2</code> returns <code class="computeroutput">true</code> if <code class="computeroutput">x1</code> and <code class="computeroutput">x2</code>
can be interchanged with identical effects. An executor may conceptually
contain additional properties which are not exposed by a named property type
that can be observed via <code class="computeroutput">boost::asio::query</code>; in this case, it
is up to the concrete executor implementation to decide if these properties
affect equality. Returning <code class="computeroutput">false</code> does not necessarily imply
that the effects are not identical. —<span class="emphasis"><em>end note</em></span>]
</p>
<p>
An executor type's destructor shall not block pending completion of the submitted
function objects. [<span class="emphasis"><em>Note:</em></span> The ability to wait for completion
of submitted function objects may be provided by the associated execution
context. —<span class="emphasis"><em>end note</em></span>]
</p>
<p>
In addition to the above requirements, types <code class="computeroutput">E</code> and <code class="computeroutput">F</code>
model <code class="computeroutput">executor_of</code> only if they satisfy the requirements of the
Table below.
</p>
<p>
Let:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<code class="computeroutput">e</code> denotes a (possibly const) executor object of type <code class="computeroutput">E</code>,
</li>
<li class="listitem">
<code class="computeroutput">cf</code> denotes the function object <code class="computeroutput">DECAY_COPY(std::forward&lt;F&gt;(f))</code>
</li>
<li class="listitem">
<code class="computeroutput">f</code> denotes a function of type <code class="computeroutput">F&amp;&amp;</code> invocable
as <code class="computeroutput">cf()</code> and where <code class="computeroutput">decay_t&lt;F&gt;</code> models
<code class="computeroutput">move_constructible</code>.
</li>
</ul></div>
<p>
The expression <code class="computeroutput">execution::execute(e, f)</code>:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Evaluates <code class="computeroutput">DECAY_COPY(std::forward&lt;F&gt;(f))</code> on the calling
thread to create <code class="computeroutput">cf</code> that will be invoked at most once by
an execution agent.
</li>
<li class="listitem">
May block pending completion of this invocation. Synchronizes with [intro.multithread]
the invocation of <code class="computeroutput">f</code>.
</li>
<li class="listitem">
Shall not propagate any exception thrown by the function object or any
other function submitted to the executor.
</li>
</ul></div>
<p>
[<span class="emphasis"><em>Note:</em></span> The treatment of exceptions thrown by one-way
submitted functions is implementation-defined. The forward progress guarantee
of the associated execution agent(s) is implementation-defined. —<span class="emphasis"><em>end
note</em></span>]
</p>
<h5>
<a name="boost_asio.reference.Executor1.h1"></a>
<span class="phrase"><a name="boost_asio.reference.Executor1.networking_ts_style_executors"></a></span><a class="link" href="Executor1.html#boost_asio.reference.Executor1.networking_ts_style_executors">Networking
TS-style executors</a>
</h5>
<p>
The library describes a standard set of requirements for <span class="emphasis"><em>executors</em></span>.
A type meeting the <code class="computeroutput">Executor</code> requirements embodies a set of rules
for determining how submitted function objects are to be executed.
</p>
<p>
A type <code class="computeroutput">X</code> meets the <code class="computeroutput">Executor</code> requirements if it
satisfies the requirements of <code class="computeroutput">CopyConstructible</code> (C++Std [copyconstructible])
and <code class="computeroutput">Destructible</code> (C++Std [destructible]), as well as the additional
requirements listed below.
</p>
<p>
No constructor, comparison operator, copy operation, move operation, swap
operation, or member functions <code class="computeroutput">context</code>, <code class="computeroutput">on_work_started</code>,
and <code class="computeroutput">on_work_finished</code> on these types shall exit via an exception.
</p>
<p>
The executor copy constructor, comparison operators, and other member functions
defined in these requirements shall not introduce data races as a result
of concurrent calls to those functions from different threads.
</p>
<p>
Let <code class="computeroutput">ctx</code> be the execution context returned by the executor's
<code class="computeroutput">context()</code> member function. An executor becomes <span class="emphasis"><em>invalid</em></span>
when the first call to <code class="computeroutput">ctx.shutdown()</code> returns. The effect of
calling <code class="computeroutput">on_work_started</code>, <code class="computeroutput">on_work_finished</code>, <code class="computeroutput">dispatch</code>,
<code class="computeroutput">post</code>, or <code class="computeroutput">defer</code> on an invalid executor is undefined.
[<span class="emphasis"><em>Note:</em></span> The copy constructor, comparison operators, and
<code class="computeroutput">context()</code> member function continue to remain valid until <code class="computeroutput">ctx</code>
is destroyed. —<span class="emphasis"><em>end note</em></span>]
</p>
<p>
In the table below, <code class="computeroutput">x1</code> and <code class="computeroutput">x2</code> denote (possibly
const) values of type <code class="computeroutput">X</code>, <code class="computeroutput">mx1</code> denotes an xvalue
of type <code class="computeroutput">X</code>, <code class="computeroutput">f</code> denotes a <code class="computeroutput">MoveConstructible</code>
(C++Std [moveconstructible]) function object callable with zero arguments,
<code class="computeroutput">a</code> denotes a (possibly const) value of type <code class="computeroutput">A</code> meeting
the <code class="computeroutput">Allocator</code> requirements (C++Std [allocator.requirements]),
and <code class="computeroutput">u</code> denotes an identifier.
</p>
<div class="table">
<a name="boost_asio.reference.Executor1.t0"></a><p class="title"><b>Table 15. Executor requirements</b></p>
<div class="table-contents"><table class="table" summary="Executor requirements">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
expression
</p>
</th>
<th>
<p>
type
</p>
</th>
<th>
<p>
assertion/note<br> pre/post-conditions
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput">X u(x1);</code>
</p>
</td>
<td>
</td>
<td>
<p>
Shall not exit via an exception.<br> <br> post: <code class="computeroutput">u ==
x1</code> and <code class="computeroutput">std::addressof(u.context()) == std::addressof(x1.context()).</code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">X u(mx1);</code>
</p>
</td>
<td>
</td>
<td>
<p>
Shall not exit via an exception.<br> <br> post: <code class="computeroutput">u</code>
equals the prior value of <code class="computeroutput">mx1</code> and <code class="computeroutput">std::addressof(u.context())</code>
equals the prior value of <code class="computeroutput">std::addressof(mx1.context())</code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1 == x2</code>
</p>
</td>
<td>
<p>
<code class="computeroutput">bool</code>
</p>
</td>
<td>
<p>
Returns <code class="computeroutput">true</code> only if <code class="computeroutput">x1</code> and <code class="computeroutput">x2</code>
can be interchanged with identical effects in any of the expressions
defined in these type requirements. [<span class="emphasis"><em>Note:</em></span>
Returning <code class="computeroutput">false</code> does not necessarily imply that the
effects are not identical. —<span class="emphasis"><em>end note</em></span>] <br>
<br> <code class="computeroutput">operator==</code> shall be reflexive, symmetric, and
transitive, and shall not exit via an exception.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1 != x2</code>
</p>
</td>
<td>
<p>
<code class="computeroutput">bool</code>
</p>
</td>
<td>
<p>
Same as <code class="computeroutput">!(x1 == x2)</code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1.context()</code>
</p>
</td>
<td>
<p>
<code class="computeroutput">execution_context&amp;</code>, or <code class="computeroutput">E&amp;</code> where
<code class="computeroutput">E</code> is a type that satifisfies the <a class="link" href="ExecutionContext.html" title="Execution context requirements"><code class="computeroutput">ExecutionContext</code></a>
requirements.
</p>
</td>
<td>
<p>
Shall not exit via an exception.<br> <br> The comparison operators
and member functions defined in these requirements shall not alter
the reference returned by this function.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1.on_work_started()</code>
</p>
</td>
<td>
</td>
<td>
<p>
Shall not exit via an exception.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1.on_work_finished()</code>
</p>
</td>
<td>
</td>
<td>
<p>
Shall not exit via an exception.<br> <br> Precondition: A preceding
call <code class="computeroutput">x2.on_work_started()</code> where <code class="computeroutput">x1 == x2</code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1.dispatch(std::move(f),a)</code>
</p>
</td>
<td>
</td>
<td>
<p>
Effects: Creates an object <code class="computeroutput">f1</code> initialized with <code class="literal"><span class="emphasis"><em>DECAY_COPY</em></span></code><code class="computeroutput">(forward&lt;Func&gt;(f))</code>
(C++Std [thread.decaycopy]) in the current thread of execution
. Calls <code class="computeroutput">f1()</code> at most once. The executor may block
forward progress of the caller until <code class="computeroutput">f1()</code> finishes
execution.<br> <br> Executor implementations should use the
supplied allocator to allocate any memory required to store the
function object. Prior to invoking the function object, the executor
shall deallocate any memory allocated. [<span class="emphasis"><em>Note:</em></span>
Executors defined in this Technical Specification always use the
supplied allocator unless otherwise specified. —<span class="emphasis"><em>end note</em></span>]
<br> <br> Synchronization: The invocation of <code class="computeroutput">dispatch</code>
synchronizes with (C++Std [intro.multithread]) the invocation of
<code class="computeroutput">f1</code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">x1.post(std::move(f),a)</code><br> <code class="computeroutput">x1.defer(std::move(f),a)</code>
</p>
</td>
<td>
</td>
<td>
<p>
Effects: Creates an object <code class="computeroutput">f1</code> initialized with <code class="literal"><span class="emphasis"><em>DECAY_COPY</em></span></code><code class="computeroutput">(forward&lt;Func&gt;(f))</code>
in the current thread of execution. Calls <code class="computeroutput">f1()</code> at
most once. The executor shall not block forward progress of the
caller pending completion of <code class="computeroutput">f1()</code>.<br> <br> Executor
implementations should use the supplied allocator to allocate any
memory required to store the function object. Prior to invoking
the function object, the executor shall deallocate any memory allocated.
[<span class="emphasis"><em>Note:</em></span> Executors defined in this Technical
Specification always use the supplied allocator unless otherwise
specified. —<span class="emphasis"><em>end note</em></span>] <br> <br> Synchronization:
The invocation of <code class="computeroutput">post</code> or <code class="computeroutput">defer</code> synchronizes
with (C++Std [intro.multithread]) the invocation of <code class="computeroutput">f1</code>.<br>
<br> [<span class="emphasis"><em>Note:</em></span> Although the requirements placed
on <code class="computeroutput">defer</code> are identical to <code class="computeroutput">post</code>, the use
of <code class="computeroutput">post</code> conveys a preference that the caller <span class="emphasis"><em>does
not</em></span> block the first step of <code class="literal">f1</code>'s
progress, whereas <code class="computeroutput">defer</code> conveys a preference that
the caller <span class="emphasis"><em>does</em></span> block the first step of <code class="literal">f1</code>.
One use of <code class="computeroutput">defer</code> is to convey the intention of the
caller that <code class="literal">f1</code> is a continuation of the current
call context. The executor may use this information to optimize
or otherwise adjust the way in which <code class="computeroutput">f1</code> is invoked.
<span class="emphasis"><em>end note</em></span>]
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2003-2021 Christopher
M. Kohlhoff<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="ExecutionContext.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="GettableSerialPortOption.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>