1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>execution_context</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="execution__submit.html" title="execution::submit"> 10<link rel="next" href="execution_context/add_service.html" title="execution_context::add_service"> 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="execution__submit.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="execution_context/add_service.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.execution_context"></a><a class="link" href="execution_context.html" title="execution_context">execution_context</a> 28</h3></div></div></div> 29<p> 30 A context for function object execution. 31 </p> 32<pre class="programlisting">class execution_context : 33 noncopyable 34</pre> 35<h5> 36<a name="boost_asio.reference.execution_context.h0"></a> 37 <span class="phrase"><a name="boost_asio.reference.execution_context.types"></a></span><a class="link" href="execution_context.html#boost_asio.reference.execution_context.types">Types</a> 38 </h5> 39<div class="informaltable"><table class="table"> 40<colgroup> 41<col> 42<col> 43</colgroup> 44<thead><tr> 45<th> 46 <p> 47 Name 48 </p> 49 </th> 50<th> 51 <p> 52 Description 53 </p> 54 </th> 55</tr></thead> 56<tbody> 57<tr> 58<td> 59 <p> 60 <a class="link" href="execution_context__id.html" title="execution_context::id"><span class="bold"><strong>id</strong></span></a> 61 </p> 62 </td> 63<td> 64 <p> 65 Class used to uniquely identify a service. 66 </p> 67 </td> 68</tr> 69<tr> 70<td> 71 <p> 72 <a class="link" href="execution_context__service.html" title="execution_context::service"><span class="bold"><strong>service</strong></span></a> 73 </p> 74 </td> 75<td> 76 <p> 77 Base class for all io_context services. 78 </p> 79 </td> 80</tr> 81<tr> 82<td> 83 <p> 84 <a class="link" href="execution_context/fork_event.html" title="execution_context::fork_event"><span class="bold"><strong>fork_event</strong></span></a> 85 </p> 86 </td> 87<td> 88 <p> 89 Fork-related event notifications. 90 </p> 91 </td> 92</tr> 93</tbody> 94</table></div> 95<h5> 96<a name="boost_asio.reference.execution_context.h1"></a> 97 <span class="phrase"><a name="boost_asio.reference.execution_context.member_functions"></a></span><a class="link" href="execution_context.html#boost_asio.reference.execution_context.member_functions">Member 98 Functions</a> 99 </h5> 100<div class="informaltable"><table class="table"> 101<colgroup> 102<col> 103<col> 104</colgroup> 105<thead><tr> 106<th> 107 <p> 108 Name 109 </p> 110 </th> 111<th> 112 <p> 113 Description 114 </p> 115 </th> 116</tr></thead> 117<tbody> 118<tr> 119<td> 120 <p> 121 <a class="link" href="execution_context/execution_context.html" title="execution_context::execution_context"><span class="bold"><strong>execution_context</strong></span></a> <span class="silver">[constructor]</span> 122 </p> 123 </td> 124<td> 125 <p> 126 Constructor. 127 </p> 128 </td> 129</tr> 130<tr> 131<td> 132 <p> 133 <a class="link" href="execution_context/notify_fork.html" title="execution_context::notify_fork"><span class="bold"><strong>notify_fork</strong></span></a> 134 </p> 135 </td> 136<td> 137 <p> 138 Notify the execution_context of a fork-related event. 139 </p> 140 </td> 141</tr> 142<tr> 143<td> 144 <p> 145 <a class="link" href="execution_context/_execution_context.html" title="execution_context::~execution_context"><span class="bold"><strong>~execution_context</strong></span></a> <span class="silver">[destructor]</span> 146 </p> 147 </td> 148<td> 149 <p> 150 Destructor. 151 </p> 152 </td> 153</tr> 154</tbody> 155</table></div> 156<h5> 157<a name="boost_asio.reference.execution_context.h2"></a> 158 <span class="phrase"><a name="boost_asio.reference.execution_context.protected_member_functions"></a></span><a class="link" href="execution_context.html#boost_asio.reference.execution_context.protected_member_functions">Protected 159 Member Functions</a> 160 </h5> 161<div class="informaltable"><table class="table"> 162<colgroup> 163<col> 164<col> 165</colgroup> 166<thead><tr> 167<th> 168 <p> 169 Name 170 </p> 171 </th> 172<th> 173 <p> 174 Description 175 </p> 176 </th> 177</tr></thead> 178<tbody> 179<tr> 180<td> 181 <p> 182 <a class="link" href="execution_context/destroy.html" title="execution_context::destroy"><span class="bold"><strong>destroy</strong></span></a> 183 </p> 184 </td> 185<td> 186 <p> 187 Destroys all services in the context. 188 </p> 189 </td> 190</tr> 191<tr> 192<td> 193 <p> 194 <a class="link" href="execution_context/shutdown.html" title="execution_context::shutdown"><span class="bold"><strong>shutdown</strong></span></a> 195 </p> 196 </td> 197<td> 198 <p> 199 Shuts down all services in the context. 200 </p> 201 </td> 202</tr> 203</tbody> 204</table></div> 205<h5> 206<a name="boost_asio.reference.execution_context.h3"></a> 207 <span class="phrase"><a name="boost_asio.reference.execution_context.friends"></a></span><a class="link" href="execution_context.html#boost_asio.reference.execution_context.friends">Friends</a> 208 </h5> 209<div class="informaltable"><table class="table"> 210<colgroup> 211<col> 212<col> 213</colgroup> 214<thead><tr> 215<th> 216 <p> 217 Name 218 </p> 219 </th> 220<th> 221 <p> 222 Description 223 </p> 224 </th> 225</tr></thead> 226<tbody> 227<tr> 228<td> 229 <p> 230 <a class="link" href="execution_context/add_service.html" title="execution_context::add_service"><span class="bold"><strong>add_service</strong></span></a> 231 </p> 232 </td> 233<td> 234 <p> 235 (Deprecated: Use make_service().) Add a service object to the execution_context. 236 </p> 237 </td> 238</tr> 239<tr> 240<td> 241 <p> 242 <a class="link" href="execution_context/has_service.html" title="execution_context::has_service"><span class="bold"><strong>has_service</strong></span></a> 243 </p> 244 </td> 245<td> 246 <p> 247 Determine if an execution_context contains a specified service 248 type. 249 </p> 250 </td> 251</tr> 252<tr> 253<td> 254 <p> 255 <a class="link" href="execution_context/make_service.html" title="execution_context::make_service"><span class="bold"><strong>make_service</strong></span></a> 256 </p> 257 </td> 258<td> 259 <p> 260 Creates a service object and adds it to the execution_context. 261 </p> 262 </td> 263</tr> 264<tr> 265<td> 266 <p> 267 <a class="link" href="execution_context/use_service.html" title="execution_context::use_service"><span class="bold"><strong>use_service</strong></span></a> 268 </p> 269 </td> 270<td> 271 <p> 272 Obtain the service object corresponding to the given type. 273 </p> 274 </td> 275</tr> 276</tbody> 277</table></div> 278<p> 279 An execution context represents a place where function objects will be executed. 280 An <code class="computeroutput">io_context</code> is an example of an execution context. 281 </p> 282<h5> 283<a name="boost_asio.reference.execution_context.h4"></a> 284 <span class="phrase"><a name="boost_asio.reference.execution_context.the_execution_context_class_and_services"></a></span><a class="link" href="execution_context.html#boost_asio.reference.execution_context.the_execution_context_class_and_services">The 285 execution_context class and services</a> 286 </h5> 287<p> 288 Class <a class="link" href="execution_context.html" title="execution_context"><code class="computeroutput">execution_context</code></a> 289 implements an extensible, type-safe, polymorphic set of services, indexed 290 by service type. 291 </p> 292<p> 293 Services exist to manage the resources that are shared across an execution 294 context. For example, timers may be implemented in terms of a single timer 295 queue, and this queue would be stored in a service. 296 </p> 297<p> 298 Access to the services of an <a class="link" href="execution_context.html" title="execution_context"><code class="computeroutput">execution_context</code></a> 299 is via three function templates, <code class="computeroutput">use_service()</code>, <code class="computeroutput">add_service()</code> 300 and <code class="computeroutput">has_service()</code>. 301 </p> 302<p> 303 In a call to <code class="computeroutput">use_service<Service>()</code>, the type argument 304 chooses a service, making available all members of the named type. If <code class="computeroutput">Service</code> 305 is not present in an <a class="link" href="execution_context.html" title="execution_context"><code class="computeroutput">execution_context</code></a>, 306 an object of type <code class="computeroutput">Service</code> is created and added to the <a class="link" href="execution_context.html" title="execution_context"><code class="computeroutput">execution_context</code></a>. 307 A C++ program can check if an <a class="link" href="execution_context.html" title="execution_context"><code class="computeroutput">execution_context</code></a> 308 implements a particular service with the function template <code class="computeroutput">has_service<Service>()</code>. 309 </p> 310<p> 311 Service objects may be explicitly added to an <a class="link" href="execution_context.html" title="execution_context"><code class="computeroutput">execution_context</code></a> 312 using the function template <code class="computeroutput">add_service<Service>()</code>. If 313 the <code class="computeroutput">Service</code> is already present, the <a class="link" href="service_already_exists.html" title="service_already_exists"><code class="computeroutput">service_already_exists</code></a> 314 exception is thrown. If the owner of the service is not the same object as 315 the <a class="link" href="execution_context.html" title="execution_context"><code class="computeroutput">execution_context</code></a> 316 parameter, the <a class="link" href="invalid_service_owner.html" title="invalid_service_owner"><code class="computeroutput">invalid_service_owner</code></a> 317 exception is thrown. 318 </p> 319<p> 320 Once a service reference is obtained from an <a class="link" href="execution_context.html" title="execution_context"><code class="computeroutput">execution_context</code></a> 321 object by calling <code class="computeroutput">use_service()</code>, that reference remains usable 322 as long as the owning <a class="link" href="execution_context.html" title="execution_context"><code class="computeroutput">execution_context</code></a> 323 object exists. 324 </p> 325<p> 326 All service implementations have <a class="link" href="execution_context__service.html" title="execution_context::service"><code class="computeroutput">execution_context::service</code></a> 327 as a public base class. Custom services may be implemented by deriving from 328 this class and then added to an <a class="link" href="execution_context.html" title="execution_context"><code class="computeroutput">execution_context</code></a> 329 using the facilities described above. 330 </p> 331<h5> 332<a name="boost_asio.reference.execution_context.h5"></a> 333 <span class="phrase"><a name="boost_asio.reference.execution_context.the_execution_context_as_a_base_class"></a></span><a class="link" href="execution_context.html#boost_asio.reference.execution_context.the_execution_context_as_a_base_class">The 334 execution_context as a base class</a> 335 </h5> 336<p> 337 Class <a class="link" href="execution_context.html" title="execution_context"><code class="computeroutput">execution_context</code></a> 338 may be used only as a base class for concrete execution context types. The 339 <code class="computeroutput">io_context</code> is an example of such a derived type. 340 </p> 341<p> 342 On destruction, a class that is derived from <a class="link" href="execution_context.html" title="execution_context"><code class="computeroutput">execution_context</code></a> 343 must perform <code class="computeroutput">execution_context::shutdown()</code> followed by <code class="computeroutput">execution_context::destroy()</code>. 344 </p> 345<p> 346 This destruction sequence permits programs to simplify their resource management 347 by using <code class="computeroutput">shared_ptr<></code>. Where an object's lifetime is tied 348 to the lifetime of a connection (or some other sequence of asynchronous operations), 349 a <code class="computeroutput">shared_ptr</code> to the object would be bound into the handlers 350 for all asynchronous operations associated with it. This works as follows: 351 </p> 352<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 353<li class="listitem"> 354 When a single connection ends, all associated asynchronous operations 355 complete. The corresponding handler objects are destroyed, and all <code class="computeroutput">shared_ptr</code> 356 references to the objects are destroyed. 357 </li> 358<li class="listitem"> 359 To shut down the whole program, the <a class="link" href="io_context.html" title="io_context"><code class="computeroutput">io_context</code></a> 360 function stop() is called to terminate any run() calls as soon as possible. 361 The <a class="link" href="io_context.html" title="io_context"><code class="computeroutput">io_context</code></a> 362 destructor calls <code class="computeroutput">shutdown()</code> and <code class="computeroutput">destroy()</code> to 363 destroy all pending handlers, causing all <code class="computeroutput">shared_ptr</code> references 364 to all connection objects to be destroyed. 365 </li> 366</ul></div> 367<h5> 368<a name="boost_asio.reference.execution_context.h6"></a> 369 <span class="phrase"><a name="boost_asio.reference.execution_context.requirements"></a></span><a class="link" href="execution_context.html#boost_asio.reference.execution_context.requirements">Requirements</a> 370 </h5> 371<p> 372 <span class="emphasis"><em>Header: </em></span><code class="literal">boost/asio/execution_context.hpp</code> 373 </p> 374<p> 375 <span class="emphasis"><em>Convenience header: </em></span><code class="literal">boost/asio/execution.hpp</code> 376 </p> 377</div> 378<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 379<td align="left"></td> 380<td align="right"><div class="copyright-footer">Copyright © 2003-2020 Christopher M. 381 Kohlhoff<p> 382 Distributed under the Boost Software License, Version 1.0. (See accompanying 383 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>) 384 </p> 385</div></td> 386</tr></table> 387<hr> 388<div class="spirit-nav"> 389<a accesskey="p" href="execution__submit.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="execution_context/add_service.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> 390</div> 391</body> 392</html> 393
