1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>io_context::strand</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="io_context__service/_service.html" title="io_context::service::~service"> 10<link rel="next" href="io_context__strand/context.html" title="io_context::strand::context"> 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="io_context__service/_service.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="io_context__strand/context.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.io_context__strand"></a><a class="link" href="io_context__strand.html" title="io_context::strand">io_context::strand</a> 28</h3></div></div></div> 29<p> 30 Provides serialised handler execution. 31 </p> 32<pre class="programlisting">class strand 33</pre> 34<h5> 35<a name="boost_asio.reference.io_context__strand.h0"></a> 36 <span class="phrase"><a name="boost_asio.reference.io_context__strand.member_functions"></a></span><a class="link" href="io_context__strand.html#boost_asio.reference.io_context__strand.member_functions">Member 37 Functions</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="io_context__strand/context.html" title="io_context::strand::context"><span class="bold"><strong>context</strong></span></a> 61 </p> 62 </td> 63<td> 64 <p> 65 Obtain the underlying execution context. 66 </p> 67 </td> 68</tr> 69<tr> 70<td> 71 <p> 72 <a class="link" href="io_context__strand/defer.html" title="io_context::strand::defer"><span class="bold"><strong>defer</strong></span></a> 73 </p> 74 </td> 75<td> 76 <p> 77 Request the strand to invoke the given function object. 78 </p> 79 </td> 80</tr> 81<tr> 82<td> 83 <p> 84 <a class="link" href="io_context__strand/dispatch.html" title="io_context::strand::dispatch"><span class="bold"><strong>dispatch</strong></span></a> 85 </p> 86 </td> 87<td> 88 <p> 89 Request the strand to invoke the given function object. <br> 90 <span class="silver"> —</span><br> (Deprecated: Use boost::asio::dispatch().) Request the strand 91 to invoke the given handler. 92 </p> 93 </td> 94</tr> 95<tr> 96<td> 97 <p> 98 <a class="link" href="io_context__strand/on_work_finished.html" title="io_context::strand::on_work_finished"><span class="bold"><strong>on_work_finished</strong></span></a> 99 </p> 100 </td> 101<td> 102 <p> 103 Inform the strand that some work is no longer outstanding. 104 </p> 105 </td> 106</tr> 107<tr> 108<td> 109 <p> 110 <a class="link" href="io_context__strand/on_work_started.html" title="io_context::strand::on_work_started"><span class="bold"><strong>on_work_started</strong></span></a> 111 </p> 112 </td> 113<td> 114 <p> 115 Inform the strand that it has some outstanding work to do. 116 </p> 117 </td> 118</tr> 119<tr> 120<td> 121 <p> 122 <a class="link" href="io_context__strand/post.html" title="io_context::strand::post"><span class="bold"><strong>post</strong></span></a> 123 </p> 124 </td> 125<td> 126 <p> 127 Request the strand to invoke the given function object. <br> 128 <span class="silver"> —</span><br> (Deprecated: Use boost::asio::post().) Request the strand 129 to invoke the given handler and return immediately. 130 </p> 131 </td> 132</tr> 133<tr> 134<td> 135 <p> 136 <a class="link" href="io_context__strand/running_in_this_thread.html" title="io_context::strand::running_in_this_thread"><span class="bold"><strong>running_in_this_thread</strong></span></a> 137 </p> 138 </td> 139<td> 140 <p> 141 Determine whether the strand is running in the current thread. 142 </p> 143 </td> 144</tr> 145<tr> 146<td> 147 <p> 148 <a class="link" href="io_context__strand/strand.html" title="io_context::strand::strand"><span class="bold"><strong>strand</strong></span></a> <span class="silver">[constructor]</span> 149 </p> 150 </td> 151<td> 152 <p> 153 Constructor. 154 </p> 155 </td> 156</tr> 157<tr> 158<td> 159 <p> 160 <a class="link" href="io_context__strand/wrap.html" title="io_context::strand::wrap"><span class="bold"><strong>wrap</strong></span></a> 161 </p> 162 </td> 163<td> 164 <p> 165 (Deprecated: Use boost::asio::bind_executor().) Create a new handler 166 that automatically dispatches the wrapped handler on the strand. 167 </p> 168 </td> 169</tr> 170<tr> 171<td> 172 <p> 173 <a class="link" href="io_context__strand/_strand.html" title="io_context::strand::~strand"><span class="bold"><strong>~strand</strong></span></a> <span class="silver">[destructor]</span> 174 </p> 175 </td> 176<td> 177 <p> 178 Destructor. 179 </p> 180 </td> 181</tr> 182</tbody> 183</table></div> 184<h5> 185<a name="boost_asio.reference.io_context__strand.h1"></a> 186 <span class="phrase"><a name="boost_asio.reference.io_context__strand.friends"></a></span><a class="link" href="io_context__strand.html#boost_asio.reference.io_context__strand.friends">Friends</a> 187 </h5> 188<div class="informaltable"><table class="table"> 189<colgroup> 190<col> 191<col> 192</colgroup> 193<thead><tr> 194<th> 195 <p> 196 Name 197 </p> 198 </th> 199<th> 200 <p> 201 Description 202 </p> 203 </th> 204</tr></thead> 205<tbody> 206<tr> 207<td> 208 <p> 209 <a class="link" href="io_context__strand/operator_not__eq_.html" title="io_context::strand::operator!="><span class="bold"><strong>operator!=</strong></span></a> 210 </p> 211 </td> 212<td> 213 <p> 214 Compare two strands for inequality. 215 </p> 216 </td> 217</tr> 218<tr> 219<td> 220 <p> 221 <a class="link" href="io_context__strand/operator_eq__eq_.html" title="io_context::strand::operator=="><span class="bold"><strong>operator==</strong></span></a> 222 </p> 223 </td> 224<td> 225 <p> 226 Compare two strands for equality. 227 </p> 228 </td> 229</tr> 230</tbody> 231</table></div> 232<p> 233 The <a class="link" href="io_context__strand.html" title="io_context::strand"><code class="computeroutput">io_context::strand</code></a> 234 class provides the ability to post and dispatch handlers with the guarantee 235 that none of those handlers will execute concurrently. 236 </p> 237<h5> 238<a name="boost_asio.reference.io_context__strand.h2"></a> 239 <span class="phrase"><a name="boost_asio.reference.io_context__strand.order_of_handler_invocation"></a></span><a class="link" href="io_context__strand.html#boost_asio.reference.io_context__strand.order_of_handler_invocation">Order 240 of handler invocation</a> 241 </h5> 242<p> 243 Given: 244 </p> 245<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 246<li class="listitem"> 247 a strand object <code class="computeroutput">s</code> 248 </li> 249<li class="listitem"> 250 an object <code class="computeroutput">a</code> meeting completion handler requirements 251 </li> 252<li class="listitem"> 253 an object <code class="computeroutput">a1</code> which is an arbitrary copy of <code class="computeroutput">a</code> 254 made by the implementation 255 </li> 256<li class="listitem"> 257 an object <code class="computeroutput">b</code> meeting completion handler requirements 258 </li> 259<li class="listitem"> 260 an object <code class="computeroutput">b1</code> which is an arbitrary copy of <code class="computeroutput">b</code> 261 made by the implementation 262 </li> 263</ul></div> 264<p> 265 if any of the following conditions are true: 266 </p> 267<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 268<li class="listitem"> 269 <code class="computeroutput">s.post(a)</code> happens-before <code class="computeroutput">s.post(b)</code> 270 </li> 271<li class="listitem"> 272 <code class="computeroutput">s.post(a)</code> happens-before <code class="computeroutput">s.dispatch(b)</code>, where 273 the latter is performed outside the strand 274 </li> 275<li class="listitem"> 276 <code class="computeroutput">s.dispatch(a)</code> happens-before <code class="computeroutput">s.post(b)</code>, where 277 the former is performed outside the strand 278 </li> 279<li class="listitem"> 280 <code class="computeroutput">s.dispatch(a)</code> happens-before <code class="computeroutput">s.dispatch(b)</code>, 281 where both are performed outside the strand 282 </li> 283</ul></div> 284<p> 285 then <code class="computeroutput">asio_handler_invoke(a1, &a1)</code> happens-before <code class="computeroutput">asio_handler_invoke(b1, 286 &b1)</code>. 287 </p> 288<p> 289 Note that in the following case: 290 </p> 291<pre class="programlisting">async_op_1(..., s.wrap(a)); 292async_op_2(..., s.wrap(b)); 293</pre> 294<p> 295 the completion of the first async operation will perform <code class="computeroutput">s.dispatch(a)</code>, 296 and the second will perform <code class="computeroutput">s.dispatch(b)</code>, but the order in 297 which those are performed is unspecified. That is, you cannot state whether 298 one happens-before the other. Therefore none of the above conditions are 299 met and no ordering guarantee is made. 300 </p> 301<h5> 302<a name="boost_asio.reference.io_context__strand.h3"></a> 303 <span class="phrase"><a name="boost_asio.reference.io_context__strand.remarks"></a></span><a class="link" href="io_context__strand.html#boost_asio.reference.io_context__strand.remarks">Remarks</a> 304 </h5> 305<p> 306 The implementation makes no guarantee that handlers posted or dispatched 307 through different <code class="computeroutput">strand</code> objects will be invoked concurrently. 308 </p> 309<h5> 310<a name="boost_asio.reference.io_context__strand.h4"></a> 311 <span class="phrase"><a name="boost_asio.reference.io_context__strand.thread_safety"></a></span><a class="link" href="io_context__strand.html#boost_asio.reference.io_context__strand.thread_safety">Thread Safety</a> 312 </h5> 313<p> 314 <span class="emphasis"><em>Distinct</em></span> <span class="emphasis"><em>objects:</em></span> Safe. 315 </p> 316<p> 317 <span class="emphasis"><em>Shared</em></span> <span class="emphasis"><em>objects:</em></span> Safe. 318 </p> 319<h5> 320<a name="boost_asio.reference.io_context__strand.h5"></a> 321 <span class="phrase"><a name="boost_asio.reference.io_context__strand.requirements"></a></span><a class="link" href="io_context__strand.html#boost_asio.reference.io_context__strand.requirements">Requirements</a> 322 </h5> 323<p> 324 <span class="emphasis"><em>Header: </em></span><code class="literal">boost/asio/io_context_strand.hpp</code> 325 </p> 326<p> 327 <span class="emphasis"><em>Convenience header: </em></span><code class="literal">boost/asio.hpp</code> 328 </p> 329</div> 330<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 331<td align="left"></td> 332<td align="right"><div class="copyright-footer">Copyright © 2003-2020 Christopher M. 333 Kohlhoff<p> 334 Distributed under the Boost Software License, Version 1.0. (See accompanying 335 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>) 336 </p> 337</div></td> 338</tr></table> 339<hr> 340<div class="spirit-nav"> 341<a accesskey="p" href="io_context__service/_service.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="io_context__strand/context.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> 342</div> 343</body> 344</html> 345
