1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Executor requirements</title> 5<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../boost_asio.html" title="Boost.Asio"> 8<link rel="up" href="../reference.html" title="Reference"> 9<link rel="prev" href="ExecutionContext.html" title="Execution context requirements"> 10<link rel="next" href="GettableSerialPortOption.html" title="Gettable serial port option requirements"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> 15<td align="center"><a href="../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="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> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="boost_asio.reference.Executor1"></a><a class="link" href="Executor1.html" title="Executor requirements">Executor requirements</a> 28</h3></div></div></div> 29<h5> 30<a name="boost_asio.reference.Executor1.h0"></a> 31 <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 32 executors</a> 33 </h5> 34<p> 35 Let <code class="computeroutput">executor-of-impl</code> be the exposition-only concept 36 </p> 37<pre class="programlisting">template<class E, class F> 38 concept executor-of-impl = 39 invocable<decay_t<F>&> && 40 constructible_from<decay_t<F>, F> && 41 move_constructible<decay_t<F>> && 42 copy_constructible<E> && 43 is_nothrow_copy_constructible_v<E> && 44 equality_comparable<E> /* nothrow */ && 45 requires(const E& e, F&& f) { 46 execution::execute(e, (F&&)f); 47 }; 48</pre> 49<p> 50 Then the <code class="computeroutput">executor</code> and <code class="computeroutput">executor_of</code> concepts are 51 defined as follows: 52 </p> 53<pre class="programlisting">template<class E> 54 concept executor = 55 executor-of-impl<E, execution::invocable_archetype>; 56 57template<class E, class F> 58 concept executor_of = 59 executor<E> && 60 executor-of-impl<E, F>; 61</pre> 62<p> 63 Neither an executor's equality comparison nor <code class="computeroutput">swap</code> operation 64 shall exit via an exception. 65 </p> 66<p> 67 None of an executor type's copy constructor, destructor, equality comparison, 68 <code class="computeroutput">swap</code> function, <code class="computeroutput">execute</code> function, or associated 69 <code class="computeroutput">query</code> functions shall introduce data races as a result of concurrent 70 invocations of those functions from different threads. 71 </p> 72<p> 73 For any two (possibly const) values <code class="computeroutput">x1</code> and <code class="computeroutput">x2</code> of 74 some executor type <code class="computeroutput">X</code>, <code class="computeroutput">x1 == x2</code> shall return <code class="computeroutput">true</code> 75 only if <code class="computeroutput">boost::asio::query(x1,p) == boost::asio::query(x2,p)</code> 76 for every property <code class="computeroutput">p</code> where both <code class="computeroutput">boost::asio::query(x1,p)</code> 77 and <code class="computeroutput">boost::asio::query(x2,p)</code> are well-formed and result in a 78 non-void type that is <code class="computeroutput">equality_comparable</code> (C++Std [equalitycomparable]). 79 [<span class="emphasis"><em>Note:</em></span> The above requirements imply that <code class="computeroutput">x1 == 80 x2</code> returns <code class="computeroutput">true</code> if <code class="computeroutput">x1</code> and <code class="computeroutput">x2</code> 81 can be interchanged with identical effects. An executor may conceptually 82 contain additional properties which are not exposed by a named property type 83 that can be observed via <code class="computeroutput">boost::asio::query</code>; in this case, it 84 is up to the concrete executor implementation to decide if these properties 85 affect equality. Returning <code class="computeroutput">false</code> does not necessarily imply 86 that the effects are not identical. —<span class="emphasis"><em>end note</em></span>] 87 </p> 88<p> 89 An executor type's destructor shall not block pending completion of the submitted 90 function objects. [<span class="emphasis"><em>Note:</em></span> The ability to wait for completion 91 of submitted function objects may be provided by the associated execution 92 context. —<span class="emphasis"><em>end note</em></span>] 93 </p> 94<p> 95 In addition to the above requirements, types <code class="computeroutput">E</code> and <code class="computeroutput">F</code> 96 model <code class="computeroutput">executor_of</code> only if they satisfy the requirements of the 97 Table below. 98 </p> 99<p> 100 Let: 101 </p> 102<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 103<li class="listitem"> 104 <code class="computeroutput">e</code> denotes a (possibly const) executor object of type <code class="computeroutput">E</code>, 105 </li> 106<li class="listitem"> 107 <code class="computeroutput">cf</code> denotes the function object <code class="computeroutput">DECAY_COPY(std::forward<F>(f))</code> 108 </li> 109<li class="listitem"> 110 <code class="computeroutput">f</code> denotes a function of type <code class="computeroutput">F&&</code> invocable 111 as <code class="computeroutput">cf()</code> and where <code class="computeroutput">decay_t<F></code> models 112 <code class="computeroutput">move_constructible</code>. 113 </li> 114</ul></div> 115<p> 116 The expression <code class="computeroutput">execution::execute(e, f)</code>: 117 </p> 118<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 119<li class="listitem"> 120 Evaluates <code class="computeroutput">DECAY_COPY(std::forward<F>(f))</code> on the calling 121 thread to create <code class="computeroutput">cf</code> that will be invoked at most once by 122 an execution agent. 123 </li> 124<li class="listitem"> 125 May block pending completion of this invocation. Synchronizes with [intro.multithread] 126 the invocation of <code class="computeroutput">f</code>. 127 </li> 128<li class="listitem"> 129 Shall not propagate any exception thrown by the function object or any 130 other function submitted to the executor. 131 </li> 132</ul></div> 133<p> 134 [<span class="emphasis"><em>Note:</em></span> The treatment of exceptions thrown by one-way 135 submitted functions is implementation-defined. The forward progress guarantee 136 of the associated execution agent(s) is implementation-defined. —<span class="emphasis"><em>end 137 note</em></span>] 138 </p> 139<h5> 140<a name="boost_asio.reference.Executor1.h1"></a> 141 <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 142 TS-style executors</a> 143 </h5> 144<p> 145 The library describes a standard set of requirements for <span class="emphasis"><em>executors</em></span>. 146 A type meeting the <code class="computeroutput">Executor</code> requirements embodies a set of rules 147 for determining how submitted function objects are to be executed. 148 </p> 149<p> 150 A type <code class="computeroutput">X</code> meets the <code class="computeroutput">Executor</code> requirements if it 151 satisfies the requirements of <code class="computeroutput">CopyConstructible</code> (C++Std [copyconstructible]) 152 and <code class="computeroutput">Destructible</code> (C++Std [destructible]), as well as the additional 153 requirements listed below. 154 </p> 155<p> 156 No constructor, comparison operator, copy operation, move operation, swap 157 operation, or member functions <code class="computeroutput">context</code>, <code class="computeroutput">on_work_started</code>, 158 and <code class="computeroutput">on_work_finished</code> on these types shall exit via an exception. 159 </p> 160<p> 161 The executor copy constructor, comparison operators, and other member functions 162 defined in these requirements shall not introduce data races as a result 163 of concurrent calls to those functions from different threads. 164 </p> 165<p> 166 Let <code class="computeroutput">ctx</code> be the execution context returned by the executor's 167 <code class="computeroutput">context()</code> member function. An executor becomes <span class="emphasis"><em>invalid</em></span> 168 when the first call to <code class="computeroutput">ctx.shutdown()</code> returns. The effect of 169 calling <code class="computeroutput">on_work_started</code>, <code class="computeroutput">on_work_finished</code>, <code class="computeroutput">dispatch</code>, 170 <code class="computeroutput">post</code>, or <code class="computeroutput">defer</code> on an invalid executor is undefined. 171 [<span class="emphasis"><em>Note:</em></span> The copy constructor, comparison operators, and 172 <code class="computeroutput">context()</code> member function continue to remain valid until <code class="computeroutput">ctx</code> 173 is destroyed. —<span class="emphasis"><em>end note</em></span>] 174 </p> 175<p> 176 In the table below, <code class="computeroutput">x1</code> and <code class="computeroutput">x2</code> denote (possibly 177 const) values of type <code class="computeroutput">X</code>, <code class="computeroutput">mx1</code> denotes an xvalue 178 of type <code class="computeroutput">X</code>, <code class="computeroutput">f</code> denotes a <code class="computeroutput">MoveConstructible</code> 179 (C++Std [moveconstructible]) function object callable with zero arguments, 180 <code class="computeroutput">a</code> denotes a (possibly const) value of type <code class="computeroutput">A</code> meeting 181 the <code class="computeroutput">Allocator</code> requirements (C++Std [allocator.requirements]), 182 and <code class="computeroutput">u</code> denotes an identifier. 183 </p> 184<div class="table"> 185<a name="boost_asio.reference.Executor1.t0"></a><p class="title"><b>Table 15. Executor requirements</b></p> 186<div class="table-contents"><table class="table" summary="Executor requirements"> 187<colgroup> 188<col> 189<col> 190<col> 191</colgroup> 192<thead><tr> 193<th> 194 <p> 195 expression 196 </p> 197 </th> 198<th> 199 <p> 200 type 201 </p> 202 </th> 203<th> 204 <p> 205 assertion/note<br> pre/post-conditions 206 </p> 207 </th> 208</tr></thead> 209<tbody> 210<tr> 211<td> 212 <p> 213 <code class="computeroutput">X u(x1);</code> 214 </p> 215 </td> 216<td> 217 </td> 218<td> 219 <p> 220 Shall not exit via an exception.<br> <br> post: <code class="computeroutput">u == 221 x1</code> and <code class="computeroutput">std::addressof(u.context()) == std::addressof(x1.context()).</code> 222 </p> 223 </td> 224</tr> 225<tr> 226<td> 227 <p> 228 <code class="computeroutput">X u(mx1);</code> 229 </p> 230 </td> 231<td> 232 </td> 233<td> 234 <p> 235 Shall not exit via an exception.<br> <br> post: <code class="computeroutput">u</code> 236 equals the prior value of <code class="computeroutput">mx1</code> and <code class="computeroutput">std::addressof(u.context())</code> 237 equals the prior value of <code class="computeroutput">std::addressof(mx1.context())</code>. 238 </p> 239 </td> 240</tr> 241<tr> 242<td> 243 <p> 244 <code class="computeroutput">x1 == x2</code> 245 </p> 246 </td> 247<td> 248 <p> 249 <code class="computeroutput">bool</code> 250 </p> 251 </td> 252<td> 253 <p> 254 Returns <code class="computeroutput">true</code> only if <code class="computeroutput">x1</code> and <code class="computeroutput">x2</code> 255 can be interchanged with identical effects in any of the expressions 256 defined in these type requirements. [<span class="emphasis"><em>Note:</em></span> 257 Returning <code class="computeroutput">false</code> does not necessarily imply that the 258 effects are not identical. —<span class="emphasis"><em>end note</em></span>] <br> 259 <br> <code class="computeroutput">operator==</code> shall be reflexive, symmetric, and 260 transitive, and shall not exit via an exception. 261 </p> 262 </td> 263</tr> 264<tr> 265<td> 266 <p> 267 <code class="computeroutput">x1 != x2</code> 268 </p> 269 </td> 270<td> 271 <p> 272 <code class="computeroutput">bool</code> 273 </p> 274 </td> 275<td> 276 <p> 277 Same as <code class="computeroutput">!(x1 == x2)</code>. 278 </p> 279 </td> 280</tr> 281<tr> 282<td> 283 <p> 284 <code class="computeroutput">x1.context()</code> 285 </p> 286 </td> 287<td> 288 <p> 289 <code class="computeroutput">execution_context&</code>, or <code class="computeroutput">E&</code> where 290 <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> 291 requirements. 292 </p> 293 </td> 294<td> 295 <p> 296 Shall not exit via an exception.<br> <br> The comparison operators 297 and member functions defined in these requirements shall not alter 298 the reference returned by this function. 299 </p> 300 </td> 301</tr> 302<tr> 303<td> 304 <p> 305 <code class="computeroutput">x1.on_work_started()</code> 306 </p> 307 </td> 308<td> 309 </td> 310<td> 311 <p> 312 Shall not exit via an exception. 313 </p> 314 </td> 315</tr> 316<tr> 317<td> 318 <p> 319 <code class="computeroutput">x1.on_work_finished()</code> 320 </p> 321 </td> 322<td> 323 </td> 324<td> 325 <p> 326 Shall not exit via an exception.<br> <br> Precondition: A preceding 327 call <code class="computeroutput">x2.on_work_started()</code> where <code class="computeroutput">x1 == x2</code>. 328 </p> 329 </td> 330</tr> 331<tr> 332<td> 333 <p> 334 <code class="computeroutput">x1.dispatch(std::move(f),a)</code> 335 </p> 336 </td> 337<td> 338 </td> 339<td> 340 <p> 341 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> 342 (C++Std [thread.decaycopy]) in the current thread of execution 343 . Calls <code class="computeroutput">f1()</code> at most once. The executor may block 344 forward progress of the caller until <code class="computeroutput">f1()</code> finishes 345 execution.<br> <br> Executor implementations should use the 346 supplied allocator to allocate any memory required to store the 347 function object. Prior to invoking the function object, the executor 348 shall deallocate any memory allocated. [<span class="emphasis"><em>Note:</em></span> 349 Executors defined in this Technical Specification always use the 350 supplied allocator unless otherwise specified. —<span class="emphasis"><em>end note</em></span>] 351 <br> <br> Synchronization: The invocation of <code class="computeroutput">dispatch</code> 352 synchronizes with (C++Std [intro.multithread]) the invocation of 353 <code class="computeroutput">f1</code>. 354 </p> 355 </td> 356</tr> 357<tr> 358<td> 359 <p> 360 <code class="computeroutput">x1.post(std::move(f),a)</code><br> <code class="computeroutput">x1.defer(std::move(f),a)</code> 361 </p> 362 </td> 363<td> 364 </td> 365<td> 366 <p> 367 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> 368 in the current thread of execution. Calls <code class="computeroutput">f1()</code> at 369 most once. The executor shall not block forward progress of the 370 caller pending completion of <code class="computeroutput">f1()</code>.<br> <br> Executor 371 implementations should use the supplied allocator to allocate any 372 memory required to store the function object. Prior to invoking 373 the function object, the executor shall deallocate any memory allocated. 374 [<span class="emphasis"><em>Note:</em></span> Executors defined in this Technical 375 Specification always use the supplied allocator unless otherwise 376 specified. —<span class="emphasis"><em>end note</em></span>] <br> <br> Synchronization: 377 The invocation of <code class="computeroutput">post</code> or <code class="computeroutput">defer</code> synchronizes 378 with (C++Std [intro.multithread]) the invocation of <code class="computeroutput">f1</code>.<br> 379 <br> [<span class="emphasis"><em>Note:</em></span> Although the requirements placed 380 on <code class="computeroutput">defer</code> are identical to <code class="computeroutput">post</code>, the use 381 of <code class="computeroutput">post</code> conveys a preference that the caller <span class="emphasis"><em>does 382 not</em></span> block the first step of <code class="literal">f1</code>'s 383 progress, whereas <code class="computeroutput">defer</code> conveys a preference that 384 the caller <span class="emphasis"><em>does</em></span> block the first step of <code class="literal">f1</code>. 385 One use of <code class="computeroutput">defer</code> is to convey the intention of the 386 caller that <code class="literal">f1</code> is a continuation of the current 387 call context. The executor may use this information to optimize 388 or otherwise adjust the way in which <code class="computeroutput">f1</code> is invoked. 389 —<span class="emphasis"><em>end note</em></span>] 390 </p> 391 </td> 392</tr> 393</tbody> 394</table></div> 395</div> 396<br class="table-break"> 397</div> 398<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 399<td align="left"></td> 400<td align="right"><div class="copyright-footer">Copyright © 2003-2020 Christopher M. 401 Kohlhoff<p> 402 Distributed under the Boost Software License, Version 1.0. (See accompanying 403 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>) 404 </p> 405</div></td> 406</tr></table> 407<hr> 408<div class="spirit-nav"> 409<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> 410</div> 411</body> 412</html> 413
