413 lines
21 KiB
HTML
413 lines
21 KiB
HTML
<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<class E, class F>
|
||
concept executor-of-impl =
|
||
invocable<decay_t<F>&> &&
|
||
constructible_from<decay_t<F>, F> &&
|
||
move_constructible<decay_t<F>> &&
|
||
copy_constructible<E> &&
|
||
is_nothrow_copy_constructible_v<E> &&
|
||
equality_comparable<E> /* nothrow */ &&
|
||
requires(const E& e, F&& f) {
|
||
execution::execute(e, (F&&)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<class E>
|
||
concept executor =
|
||
executor-of-impl<E, execution::invocable_archetype>;
|
||
|
||
template<class E, class F>
|
||
concept executor_of =
|
||
executor<E> &&
|
||
executor-of-impl<E, F>;
|
||
</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<F>(f))</code>
|
||
</li>
|
||
<li class="listitem">
|
||
<code class="computeroutput">f</code> denotes a function of type <code class="computeroutput">F&&</code> invocable
|
||
as <code class="computeroutput">cf()</code> and where <code class="computeroutput">decay_t<F></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<F>(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&</code>, or <code class="computeroutput">E&</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<Func>(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<Func>(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>
|