1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Handler Tracking</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="../core.html" title="Core Concepts and Functionality"> 9<link rel="prev" href="allocation.html" title="Custom Memory Allocation"> 10<link rel="next" href="concurrency_hint.html" title="Concurrency Hints"> 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="allocation.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.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="concurrency_hint.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h4 class="title"> 27<a name="boost_asio.overview.core.handler_tracking"></a><a class="link" href="handler_tracking.html" title="Handler Tracking">Handler 28 Tracking</a> 29</h4></div></div></div> 30<p> 31 To aid in debugging asynchronous programs, Boost.Asio provides support 32 for handler tracking. When enabled by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_ENABLE_HANDLER_TRACKING</span></code>, 33 Boost.Asio writes debugging output to the standard error stream. The output 34 records asynchronous operations and the relationships between their handlers. 35 </p> 36<p> 37 This feature is useful when debugging and you need to know how your asynchronous 38 operations are chained together, or what the pending asynchronous operations 39 are. As an illustration, here is the output when you run the HTTP Server 40 example, handle a single request, then shut down via Ctrl+C: 41 </p> 42<pre class="programlisting">@asio|1589424178.741850|0*1|signal_set@0x7ffee977d878.async_wait 43@asio|1589424178.742593|0*2|socket@0x7ffee977d8a8.async_accept 44@asio|1589424178.742619|.2|non_blocking_accept,ec=asio.system:11 45@asio|1589424178.742625|0|resolver@0x7ffee977d760.cancel 46@asio|1589424195.830382|.2|non_blocking_accept,ec=system:0 47@asio|1589424195.830413|>2|ec=system:0 48@asio|1589424195.830473|2*3|socket@0x7fa71d808230.async_receive 49@asio|1589424195.830496|.3|non_blocking_recv,ec=system:0,bytes_transferred=151 50@asio|1589424195.830503|2*4|socket@0x7ffee977d8a8.async_accept 51@asio|1589424195.830507|.4|non_blocking_accept,ec=asio.system:11 52@asio|1589424195.830510|<2| 53@asio|1589424195.830529|>3|ec=system:0,bytes_transferred=151 54@asio|1589424195.831143|3^5|in 'async_write' (./../../../boost/asio/impl/write.hpp:330) 55@asio|1589424195.831143|3*5|socket@0x7fa71d808230.async_send 56@asio|1589424195.831186|.5|non_blocking_send,ec=system:0,bytes_transferred=1090 57@asio|1589424195.831194|<3| 58@asio|1589424195.831218|>5|ec=system:0,bytes_transferred=1090 59@asio|1589424195.831263|5|socket@0x7fa71d808230.close 60@asio|1589424195.831298|<5| 61@asio|1589424199.793770|>1|ec=system:0,signal_number=2 62@asio|1589424199.793781|1|socket@0x7ffee977d8a8.close 63@asio|1589424199.793809|<1| 64@asio|1589424199.793840|>4|ec=asio.system:125 65@asio|1589424199.793854|<4| 66@asio|1589424199.793883|0|signal_set@0x7ffee977d878.cancel 67</pre> 68<p> 69 Each line is of the form: 70 </p> 71<pre class="programlisting"><tag>|<timestamp>|<action>|<description> 72</pre> 73<p> 74 The <code class="computeroutput"><tag></code> is always <code class="computeroutput">@asio</code>, and is used 75 to identify and extract the handler tracking messages from the program 76 output. 77 </p> 78<p> 79 The <code class="computeroutput"><timestamp></code> is seconds and microseconds from 1 Jan 80 1970 UTC. 81 </p> 82<p> 83 The <code class="computeroutput"><action></code> takes one of the following forms: 84 </p> 85<div class="variablelist"> 86<p class="title"><b></b></p> 87<dl class="variablelist"> 88<dt><span class="term">>n</span></dt> 89<dd><p> 90 The program entered the handler number <code class="computeroutput">n</code>. The <code class="computeroutput"><description></code> 91 shows the arguments to the handler. 92 </p></dd> 93<dt><span class="term"><n</span></dt> 94<dd><p> 95 The program left handler number <code class="computeroutput">n</code>. 96 </p></dd> 97<dt><span class="term">!n</span></dt> 98<dd><p> 99 The program left handler number n due to an exception. 100 </p></dd> 101<dt><span class="term">~n</span></dt> 102<dd><p> 103 The handler number <code class="computeroutput">n</code> was destroyed without having been 104 invoked. This is usually the case for any unfinished asynchronous 105 operations when the <code class="computeroutput">io_context</code> is destroyed. 106 </p></dd> 107<dt><span class="term">n^m</span></dt> 108<dd><p> 109 The handler number <code class="computeroutput">n</code> is about to create a new asynchronous 110 operation with completion handler number <code class="computeroutput">m</code>. The <code class="computeroutput"><description></code> 111 contains source location information to help identify where in the 112 program the asynchronous operation is being started. 113 </p></dd> 114<dt><span class="term">n*m</span></dt> 115<dd><p> 116 The handler number <code class="computeroutput">n</code> created a new asynchronous operation 117 with completion handler number <code class="computeroutput">m</code>. The <code class="computeroutput"><description></code> 118 shows what asynchronous operation was started. 119 </p></dd> 120<dt><span class="term">n</span></dt> 121<dd><p> 122 The handler number <code class="computeroutput">n</code> performed some other operation. 123 The <code class="computeroutput"><description></code> shows what function was called. 124 Currently only <code class="computeroutput">close()</code> and <code class="computeroutput">cancel()</code> operations 125 are logged, as these may affect the state of pending asynchronous 126 operations. 127 </p></dd> 128<dt><span class="term">.n</span></dt> 129<dd><p> 130 The implementation performed a system call as part of the asynchronous 131 operation for which handler number <code class="computeroutput">n</code> is the completion 132 handler. The <code class="computeroutput"><description></code> shows what function 133 was called and its results. These tracking events are only emitted 134 when using a reactor-based implementation. 135 </p></dd> 136</dl> 137</div> 138<p> 139 Where the <code class="computeroutput"><description></code> shows a synchronous or asynchronous 140 operation, the format is <code class="computeroutput"><object-type>@<pointer>.<operation></code>. 141 For handler entry, it shows a comma-separated list of arguments and their 142 values. 143 </p> 144<p> 145 As shown above, Each handler is assigned a numeric identifier. Where the 146 handler tracking output shows a handler number of 0, it means that the 147 action was performed outside of any handler. 148 </p> 149<h6> 150<a name="boost_asio.overview.core.handler_tracking.h0"></a> 151 <span class="phrase"><a name="boost_asio.overview.core.handler_tracking.adding_location_information"></a></span><a class="link" href="handler_tracking.html#boost_asio.overview.core.handler_tracking.adding_location_information">Adding 152 Location Information</a> 153 </h6> 154<p> 155 Programs may augment the handler tracking output's location information 156 by using the macro <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_LOCATION</span></code> 157 in the source code. For example: 158 </p> 159<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">HANDLER_LOCATION</span> <span class="special">\</span> 160 <span class="identifier">BOOST_ASIO_HANDLER_LOCATION</span><span class="special">((</span><span class="identifier">__FILE__</span><span class="special">,</span> <span class="identifier">__LINE__</span><span class="special">,</span> <span class="identifier">__func__</span><span class="special">))</span> 161 162<span class="comment">// ...</span> 163 164<span class="keyword">void</span> <span class="identifier">do_read</span><span class="special">()</span> 165<span class="special">{</span> 166 <span class="identifier">HANDLER_LOCATION</span><span class="special">;</span> 167 168 <span class="keyword">auto</span> <span class="identifier">self</span><span class="special">(</span><span class="identifier">shared_from_this</span><span class="special">());</span> 169 <span class="identifier">socket_</span><span class="special">.</span><span class="identifier">async_read_some</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">buffer</span><span class="special">(</span><span class="identifier">data_</span><span class="special">,</span> <span class="identifier">max_length</span><span class="special">),</span> 170 <span class="special">[</span><span class="keyword">this</span><span class="special">,</span> <span class="identifier">self</span><span class="special">](</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">length</span><span class="special">)</span> 171 <span class="special">{</span> 172 <span class="identifier">HANDLER_LOCATION</span><span class="special">;</span> 173 174 <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">ec</span><span class="special">)</span> 175 <span class="special">{</span> 176 <span class="identifier">do_write</span><span class="special">(</span><span class="identifier">length</span><span class="special">);</span> 177 <span class="special">}</span> 178 <span class="special">});</span> 179<span class="special">}</span> 180</pre> 181<p> 182 With the additional location information available, the handler tracking 183 output may include a call stack of source locations: 184 </p> 185<pre class="programlisting">@asio|1589423304.861944|>7|ec=system:0,bytes_transferred=5 186@asio|1589423304.861952|7^8|in 'async_write' (./../../../boost/asio/impl/write.hpp:330) 187@asio|1589423304.861952|7^8|called from 'do_write' (handler_tracking/async_tcp_echo_server.cpp:62) 188@asio|1589423304.861952|7^8|called from 'operator()' (handler_tracking/async_tcp_echo_server.cpp:51) 189@asio|1589423304.861952|7*8|socket@0x7ff61c008230.async_send 190@asio|1589423304.861975|.8|non_blocking_send,ec=system:0,bytes_transferred=5 191@asio|1589423304.861980|<7| 192</pre> 193<p> 194 Furthermore, if <code class="computeroutput">std::source_location</code> or <code class="computeroutput">std::experimental::source_location</code> 195 are available, the <a class="link" href="../../reference/use_awaitable_t.html" title="use_awaitable_t"><code class="computeroutput">use_awaitable_t</code></a> 196 token (when default-constructed or used as a default completion token) 197 will also cause handler tracking to output a source location for each newly 198 created asynchronous operation. A <code class="computeroutput">use_awaitable_t</code> object may 199 also be explicitly constructed with location information. 200 </p> 201<h6> 202<a name="boost_asio.overview.core.handler_tracking.h1"></a> 203 <span class="phrase"><a name="boost_asio.overview.core.handler_tracking.visual_representations"></a></span><a class="link" href="handler_tracking.html#boost_asio.overview.core.handler_tracking.visual_representations">Visual 204 Representations</a> 205 </h6> 206<p> 207 The handler tracking output may be post-processed using the included <code class="literal">handlerviz.pl</code> 208 tool to create a visual representation of the handlers (requires the GraphViz 209 tool <code class="literal">dot</code>). 210 </p> 211<h6> 212<a name="boost_asio.overview.core.handler_tracking.h2"></a> 213 <span class="phrase"><a name="boost_asio.overview.core.handler_tracking.custom_tracking"></a></span><a class="link" href="handler_tracking.html#boost_asio.overview.core.handler_tracking.custom_tracking">Custom 214 Tracking</a> 215 </h6> 216<p> 217 Handling tracking may be customised by defining the <code class="computeroutput"><span class="identifier">BOOST_ASIO_CUSTOM_HANDLER_TRACKING</span></code> 218 macro to the name of a header file (enclosed in <code class="computeroutput"><span class="string">""</span></code> 219 or <code class="computeroutput"><span class="special"><></span></code>). This header 220 file must implement the following preprocessor macros: 221 </p> 222<div class="informaltable"><table class="table"> 223<colgroup> 224<col> 225<col> 226</colgroup> 227<thead><tr> 228<th> 229 <p> 230 Macro 231 </p> 232 </th> 233<th> 234 <p> 235 Description 236 </p> 237 </th> 238</tr></thead> 239<tbody> 240<tr> 241<td> 242 <p> 243 <code class="computeroutput"><span class="identifier">BOOST_ASIO_INHERIT_TRACKED_HANDLER</span></code> 244 </p> 245 </td> 246<td> 247 <p> 248 Specifies a base class for classes that implement asynchronous 249 operations. When used, the macro immediately follows the class 250 name, so it must have the form <code class="computeroutput"><span class="special">:</span> 251 <span class="keyword">public</span> <span class="identifier">my_class</span></code>. 252 </p> 253 </td> 254</tr> 255<tr> 256<td> 257 <p> 258 <code class="computeroutput"><span class="identifier">BOOST_ASIO_ALSO_INHERIT_TRACKED_HANDLER</span></code> 259 </p> 260 </td> 261<td> 262 <p> 263 Specifies a base class for classes that implement asynchronous 264 operations. When used, the macro follows other base classes, 265 so it must have the form <code class="computeroutput"><span class="special">,</span> 266 <span class="keyword">public</span> <span class="identifier">my_class</span></code>. 267 </p> 268 </td> 269</tr> 270<tr> 271<td> 272 <p> 273 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_TRACKING_INIT</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span></code> 274 </p> 275 </td> 276<td> 277 <p> 278 An expression that is used to initialise the tracking mechanism. 279 </p> 280 </td> 281</tr> 282<tr> 283<td> 284 <p> 285 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_LOCATION</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span></code> 286 </p> 287 </td> 288<td> 289 <p> 290 A variable declaration that is used to define a source code location. 291 <code class="computeroutput"><span class="identifier">args</span></code> is a parenthesised 292 function argument list containing the file name, line number, 293 and function name. 294 </p> 295 </td> 296</tr> 297<tr> 298<td> 299 <p> 300 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_CREATION</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span></code> 301 </p> 302 </td> 303<td> 304 <p> 305 An expression that is called on creation of an asynchronous operation. 306 <code class="computeroutput"><span class="identifier">args</span></code> is a parenthesised 307 function argument list containing the owning execution context, 308 the tracked handler, the name of the object type, a pointer to 309 the object, the object's native handle, and the operation name. 310 </p> 311 </td> 312</tr> 313<tr> 314<td> 315 <p> 316 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_COMPLETION</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span></code> 317 </p> 318 </td> 319<td> 320 <p> 321 An expression that is called on completion of an asynchronous 322 operation. <code class="computeroutput"><span class="identifier">args</span></code> 323 is a parenthesised function argument list containing the tracked 324 handler. 325 </p> 326 </td> 327</tr> 328<tr> 329<td> 330 <p> 331 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_INVOCATION_BEGIN</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span></code> 332 </p> 333 </td> 334<td> 335 <p> 336 An expression that is called immediately before a completion 337 handler is invoked. <code class="computeroutput"><span class="identifier">args</span></code> 338 is a parenthesised function argument list containing the arguments 339 to the completion handler. 340 </p> 341 </td> 342</tr> 343<tr> 344<td> 345 <p> 346 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_INVOCATION_END</span></code> 347 </p> 348 </td> 349<td> 350 <p> 351 An expression that is called immediately after a completion handler 352 is invoked. 353 </p> 354 </td> 355</tr> 356<tr> 357<td> 358 <p> 359 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_OPERATION</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span></code> 360 </p> 361 </td> 362<td> 363 <p> 364 An expression that is called when some synchronous object operation 365 is called (such as <code class="computeroutput"><span class="identifier">close</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">cancel</span><span class="special">()</span></code>). <code class="computeroutput"><span class="identifier">args</span></code> 366 is a parenthesised function argument list containing the owning 367 execution context, the name of the object type, a pointer to 368 the object, the object's native handle, and the operation name. 369 </p> 370 </td> 371</tr> 372<tr> 373<td> 374 <p> 375 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_REACTOR_REGISTRATION</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span></code> 376 </p> 377 </td> 378<td> 379 <p> 380 An expression that is called when an object is registered with 381 the reactor. <code class="computeroutput"><span class="identifier">args</span></code> 382 is a parenthesised function argument list containing the owning 383 execution context, the object's native handle, and a unique registration 384 key. 385 </p> 386 </td> 387</tr> 388<tr> 389<td> 390 <p> 391 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_REACTOR_DEREGISTRATION</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span></code> 392 </p> 393 </td> 394<td> 395 <p> 396 An expression that is called when an object is deregistered from 397 the reactor. <code class="computeroutput"><span class="identifier">args</span></code> 398 is a parenthesised function argument list containing the owning 399 execution context, the object's native handle, and a unique registration 400 key. 401 </p> 402 </td> 403</tr> 404<tr> 405<td> 406 <p> 407 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_REACTOR_READ_EVENT</span></code> 408 </p> 409 </td> 410<td> 411 <p> 412 A bitmask constant used to identify reactor read readiness events. 413 </p> 414 </td> 415</tr> 416<tr> 417<td> 418 <p> 419 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_REACTOR_WRITE_EVENT</span></code> 420 </p> 421 </td> 422<td> 423 <p> 424 A bitmask constant used to identify reactor write readiness events. 425 </p> 426 </td> 427</tr> 428<tr> 429<td> 430 <p> 431 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_REACTOR_ERROR_EVENT</span></code> 432 </p> 433 </td> 434<td> 435 <p> 436 A bitmask constant used to identify reactor error readiness events. 437 </p> 438 </td> 439</tr> 440<tr> 441<td> 442 <p> 443 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_REACTOR_EVENTS</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span></code> 444 </p> 445 </td> 446<td> 447 <p> 448 An expression that is called when an object registered with the 449 reactor becomes ready. <code class="computeroutput"><span class="identifier">args</span></code> 450 is a parenthesised function argument list containing the owning 451 execution context, the unique registration key, and a bitmask 452 of the ready events. 453 </p> 454 </td> 455</tr> 456<tr> 457<td> 458 <p> 459 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HANDLER_REACTOR_OPERATION</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span></code> 460 </p> 461 </td> 462<td> 463 <p> 464 An expression that is called when the implementation performs 465 a system call as part of a reactor-based asynchronous operation. 466 <code class="computeroutput"><span class="identifier">args</span></code> is a parenthesised 467 function argument list containing the tracked handler, the operation 468 name, the error code produced by the operation, and (optionally) 469 the number of bytes transferred. 470 </p> 471 </td> 472</tr> 473</tbody> 474</table></div> 475<h6> 476<a name="boost_asio.overview.core.handler_tracking.h3"></a> 477 <span class="phrase"><a name="boost_asio.overview.core.handler_tracking.see_also"></a></span><a class="link" href="handler_tracking.html#boost_asio.overview.core.handler_tracking.see_also">See Also</a> 478 </h6> 479<p> 480 <a class="link" href="../../examples/cpp11_examples.html#boost_asio.examples.cpp11_examples.handler_tracking">Handler 481 tracking examples</a>. 482 </p> 483</div> 484<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 485<td align="left"></td> 486<td align="right"><div class="copyright-footer">Copyright © 2003-2020 Christopher M. 487 Kohlhoff<p> 488 Distributed under the Boost Software License, Version 1.0. (See accompanying 489 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>) 490 </p> 491</div></td> 492</tr></table> 493<hr> 494<div class="spirit-nav"> 495<a accesskey="p" href="allocation.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.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="concurrency_hint.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 496</div> 497</body> 498</html> 499
