294 lines
14 KiB
HTML
294 lines
14 KiB
HTML
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<title>Proposed Standard Executors</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="../boost_asio.html" title="Boost.Asio">
|
|
<link rel="prev" href="net_ts.html" title="Networking TS compatibility">
|
|
<link rel="next" href="history.html" title="Revision History">
|
|
</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="net_ts.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_asio.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="history.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
|
<a name="boost_asio.std_executors"></a><a class="link" href="std_executors.html" title="Proposed Standard Executors">Proposed Standard Executors</a>
|
|
</h2></div></div></div>
|
|
<p>
|
|
Boost.Asio provides a complete implementation of the proposed standard executors,
|
|
as described in <a href="http://wg21.link/P0443r13" target="_top">P0443r13</a>, <a href="http://wg21.link/P1348r0" target="_top">P1348r0</a>, and <a href="http://wg21.link/P1393r0" target="_top">P1393r0</a>.
|
|
</p>
|
|
<p>
|
|
Just as with executors under the Networking TS model, a standard executor represents
|
|
a policy as to how, when, and where a piece of code should be executed. Most
|
|
existing code should continue to work with little or no change.
|
|
</p>
|
|
<h4>
|
|
<a name="boost_asio.std_executors.h0"></a>
|
|
<span class="phrase"><a name="boost_asio.std_executors.standard_executor_implementations_in_boost_asio"></a></span><a class="link" href="std_executors.html#boost_asio.std_executors.standard_executor_implementations_in_boost_asio">Standard
|
|
Executor Implementations in Boost.Asio</a>
|
|
</h4>
|
|
<p>
|
|
The <a class="link" href="reference/io_context/executor_type.html" title="io_context::executor_type"><code class="computeroutput">io_context::executor_type</code></a>,
|
|
<a class="link" href="reference/thread_pool/executor_type.html" title="thread_pool::executor_type"><code class="computeroutput">thread_pool::executor_type</code></a>,
|
|
<a class="link" href="reference/system_executor.html" title="system_executor"><code class="computeroutput">system_executor</code></a>,
|
|
and <a class="link" href="reference/strand.html" title="strand"><code class="computeroutput">strand</code></a>
|
|
executors meet the requirements for the proposed standard executors. For compatibility,
|
|
these classes also meet the requirements for the Networking TS model of executors.
|
|
</p>
|
|
<h4>
|
|
<a name="boost_asio.std_executors.h1"></a>
|
|
<span class="phrase"><a name="boost_asio.std_executors.standard_executor_use_in_boost_asio"></a></span><a class="link" href="std_executors.html#boost_asio.std_executors.standard_executor_use_in_boost_asio">Standard
|
|
Executor Use in Boost.Asio</a>
|
|
</h4>
|
|
<p>
|
|
All I/O objects such as <a class="link" href="reference/ip__tcp/socket.html" title="ip::tcp::socket"><code class="computeroutput">ip::tcp::socket</code></a>,
|
|
asynchronous operations, and utilities including <a class="link" href="reference/dispatch.html" title="dispatch"><code class="computeroutput">dispatch</code></a>,
|
|
<a class="link" href="reference/post.html" title="post"><code class="computeroutput">post</code></a>, <a class="link" href="reference/defer.html" title="defer"><code class="computeroutput">defer</code></a>,
|
|
<a class="link" href="reference/get_associated_executor.html" title="get_associated_executor"><code class="computeroutput">get_associated_executor</code></a>,
|
|
<a class="link" href="reference/bind_executor.html" title="bind_executor"><code class="computeroutput">bind_executor</code></a>,
|
|
<a class="link" href="reference/make_work_guard.html" title="make_work_guard"><code class="computeroutput">make_work_guard</code></a>,
|
|
<a class="link" href="reference/spawn.html" title="spawn"><code class="computeroutput">spawn</code></a>, <a class="link" href="reference/co_spawn.html" title="co_spawn"><code class="computeroutput">co_spawn</code></a>, <a class="link" href="reference/async_compose.html" title="async_compose"><code class="computeroutput">async_compose</code></a>,
|
|
<a class="link" href="reference/use_future.html" title="use_future"><code class="computeroutput">use_future</code></a>,
|
|
etc., can interoperate with both proposed standard executors, and with Networking
|
|
TS executors. Boost.Asio's implementation determines at compile time which
|
|
model a particular executor meets; the proposed standard executor model is
|
|
used in preference if both are detected.
|
|
</p>
|
|
<p>
|
|
Support for the existing Networking TS model of executors can be disabled by
|
|
defining <code class="computeroutput">BOOST_ASIO_NO_TS_EXECUTORS</code>.
|
|
</p>
|
|
<h4>
|
|
<a name="boost_asio.std_executors.h2"></a>
|
|
<span class="phrase"><a name="boost_asio.std_executors.polymorphic_i_o_executor"></a></span><a class="link" href="std_executors.html#boost_asio.std_executors.polymorphic_i_o_executor">Polymorphic
|
|
I/O Executor</a>
|
|
</h4>
|
|
<p>
|
|
The <a class="link" href="reference/any_io_executor.html" title="any_io_executor"><code class="computeroutput">any_io_executor</code></a>
|
|
type alias is the default runtime-polymorphic executor for all I/O objects.
|
|
This type alias points to the <a class="link" href="reference/execution__any_executor.html" title="execution::any_executor"><code class="computeroutput">execution::any_executor<></code></a>
|
|
template with a set of supportable properties specified for use with I/O.
|
|
</p>
|
|
<p>
|
|
This new name may break existing code that directly uses the old polymorphic
|
|
wrapper, <a class="link" href="reference/executor.html" title="executor"><code class="computeroutput">executor</code></a>.
|
|
If required for backward compatibility, <code class="computeroutput">BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT</code>
|
|
can be defined, which changes the <code class="computeroutput">any_io_executor</code> type alias to
|
|
instead point to the <code class="computeroutput">executor</code> polymorphic wrapper.
|
|
</p>
|
|
<h4>
|
|
<a name="boost_asio.std_executors.h3"></a>
|
|
<span class="phrase"><a name="boost_asio.std_executors.implementing_a_minimal_i_o_executor"></a></span><a class="link" href="std_executors.html#boost_asio.std_executors.implementing_a_minimal_i_o_executor">Implementing
|
|
a Minimal I/O Executor</a>
|
|
</h4>
|
|
<p>
|
|
Standard executor properties make what were previously hard requirements on
|
|
an executor (such as work counting, or the ability to distinguish between
|
|
<code class="computeroutput">post</code>, <code class="computeroutput">dispatch</code>, and <code class="computeroutput">defer</code>) into optional
|
|
facilities. With this relaxation, the minimal requirements for an I/O executor
|
|
are:
|
|
</p>
|
|
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
|
<li class="listitem">
|
|
Conformance to the <a class="link" href="reference/Executor1.html#boost_asio.reference.Executor1.standard_executors"><code class="computeroutput">executor</code></a>
|
|
concept.
|
|
</li>
|
|
<li class="listitem">
|
|
The ability to query the <a class="link" href="reference/execution__context.html" title="execution::context"><code class="computeroutput">execution::context</code></a>
|
|
property, with the result being <a class="link" href="reference/execution_context.html" title="execution_context"><code class="computeroutput">execution_context&</code></a>
|
|
or a reference to a class that is derived from <code class="computeroutput">execution_context</code>.
|
|
</li>
|
|
<li class="listitem">
|
|
The <code class="computeroutput">execute</code> operation having, at minimum, the <a class="link" href="reference/execution__blocking_t/never.html" title="execution::blocking_t::never"><code class="computeroutput">execution::blocking.never</code></a>
|
|
semantic.
|
|
</li>
|
|
</ul></div>
|
|
<p>
|
|
The following example shows a minimal I/O executor. Given a queue submission
|
|
operation implemented elsewhere:
|
|
</p>
|
|
<p>
|
|
</p>
|
|
<pre class="programlisting">queue_t queue_create();
|
|
template <typename F> void queue_submit(queue_t q, F f);
|
|
</pre>
|
|
<p>
|
|
</p>
|
|
<p>
|
|
the executor may be defined as follows:
|
|
</p>
|
|
<p>
|
|
</p>
|
|
<pre class="programlisting">struct minimal_io_executor
|
|
{
|
|
boost::asio::execution_context* context_;
|
|
queue_t queue_;
|
|
|
|
bool operator==(const minimal_io_executor& other) const noexcept
|
|
{
|
|
return context_ == other.context_ && queue_ == other.queue_;
|
|
}
|
|
|
|
bool operator!=(const minimal_io_executor& other) const noexcept
|
|
{
|
|
return !(*this == other);
|
|
}
|
|
|
|
boost::asio::execution_context& query(
|
|
boost::asio::execution::context_t) const noexcept
|
|
{
|
|
return *context_;
|
|
}
|
|
|
|
static constexpr boost::asio::execution::blocking_t::never_t query(
|
|
boost::asio::execution::blocking_t) noexcept
|
|
{
|
|
// This executor always has blocking.never semantics.
|
|
return boost::asio::execution::blocking.never;
|
|
}
|
|
|
|
template <class F>
|
|
void execute(F f) const
|
|
{
|
|
queue_submit(queue_, std::move(f));
|
|
}
|
|
};
|
|
</pre>
|
|
<p>
|
|
</p>
|
|
<p>
|
|
This executor may be created as follows:
|
|
</p>
|
|
<p>
|
|
</p>
|
|
<pre class="programlisting">boost::asio::execution_context context;
|
|
queue_t queue = queue_create();
|
|
minimal_io_executor executor{&context, queue};
|
|
</pre>
|
|
<p>
|
|
</p>
|
|
<p>
|
|
and then used with I/O objects:
|
|
</p>
|
|
<p>
|
|
</p>
|
|
<pre class="programlisting">boost::asio::ip::tcp::acceptor acceptor(executor);
|
|
</pre>
|
|
<p>
|
|
</p>
|
|
<p>
|
|
or assigned into the <a class="link" href="reference/any_io_executor.html" title="any_io_executor"><code class="computeroutput">any_io_executor</code></a>
|
|
polymorphic wrapper:
|
|
</p>
|
|
<p>
|
|
</p>
|
|
<pre class="programlisting">boost::asio::any_io_executor poly_executor = executor;
|
|
</pre>
|
|
<p>
|
|
</p>
|
|
<h4>
|
|
<a name="boost_asio.std_executors.h4"></a>
|
|
<span class="phrase"><a name="boost_asio.std_executors.traits_for_deducing_conformance_to_the_executor_concept"></a></span><a class="link" href="std_executors.html#boost_asio.std_executors.traits_for_deducing_conformance_to_the_executor_concept">Traits
|
|
for Deducing Conformance to the Executor Concept</a>
|
|
</h4>
|
|
<p>
|
|
Older C++ standards and compilers require some assistance to determine whether
|
|
an executor implementation conforms to the <code class="computeroutput">executor</code> concept and
|
|
type requirements. This is achieved through specialisation of traits. The following
|
|
code shows a specialisation of these traits for the <code class="computeroutput">minimal_io_executor</code>
|
|
example from above:
|
|
</p>
|
|
<p>
|
|
</p>
|
|
<pre class="programlisting">namespace boost { namespace asio {
|
|
namespace traits {
|
|
|
|
#if !defined(BOOST_ASIO_HAS_DEDUCED_EXECUTE_MEMBER_TRAIT)
|
|
|
|
template <typename F>
|
|
struct execute_member<minimal_io_executor, F>
|
|
{
|
|
static constexpr bool is_valid = true;
|
|
static constexpr bool is_noexcept = true;
|
|
typedef void result_type;
|
|
};
|
|
|
|
#endif // !defined(BOOST_ASIO_HAS_DEDUCED_EXECUTE_MEMBER_TRAIT)
|
|
#if !defined(BOOST_ASIO_HAS_DEDUCED_EQUALITY_COMPARABLE_TRAIT)
|
|
|
|
template <>
|
|
struct equality_comparable<minimal_io_executor>
|
|
{
|
|
static constexpr bool is_valid = true;
|
|
static constexpr bool is_noexcept = true;
|
|
};
|
|
|
|
#endif // !defined(BOOST_ASIO_HAS_DEDUCED_EQUALITY_COMPARABLE_TRAIT)
|
|
#if !defined(BOOST_ASIO_HAS_DEDUCED_QUERY_MEMBER_TRAIT)
|
|
|
|
template <>
|
|
struct query_member<minimal_io_executor,
|
|
boost::asio::execution::context_t>
|
|
{
|
|
static constexpr bool is_valid = true;
|
|
static constexpr bool is_noexcept = true;
|
|
typedef boost::asio::execution_context& result_type;
|
|
};
|
|
|
|
#endif // !defined(BOOST_ASIO_HAS_DEDUCED_QUERY_MEMBER_TRAIT)
|
|
#if !defined(BOOST_ASIO_HAS_DEDUCED_QUERY_STATIC_CONSTEXPR_MEMBER_TRAIT)
|
|
|
|
template <typename Property>
|
|
struct query_static_constexpr_member<minimal_io_executor, Property,
|
|
typename enable_if<
|
|
std::is_convertible<Property, boost::asio::execution::blocking_t>::value
|
|
>::type>
|
|
{
|
|
static constexpr bool is_valid = true;
|
|
static constexpr bool is_noexcept = true;
|
|
typedef boost::asio::execution::blocking_t::never_t result_type;
|
|
static constexpr result_type value() noexcept { return result_type(); }
|
|
};
|
|
|
|
#endif // !defined(BOOST_ASIO_HAS_DEDUCED_QUERY_STATIC_CONSTEXPR_MEMBER_TRAIT)
|
|
|
|
} // namespace traits
|
|
} } // namespace boost::asio
|
|
</pre>
|
|
<p>
|
|
</p>
|
|
<p>
|
|
Boost.Asio uses an extensive set of traits to implement all of the proposed
|
|
standard executor functionality on older C++ standards. These traits may be
|
|
found under the <code class="literal">boost/asio/traits</code> include directory.
|
|
</p>
|
|
</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="net_ts.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_asio.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="history.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
|
|
</div>
|
|
</body>
|
|
</html>
|