]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | / Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com) | |
3 | / | |
4 | / Distributed under the Boost Software License, Version 1.0. (See accompanying | |
5 | / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
6 | /] | |
7 | ||
8 | [section:handler_tracking Handler Tracking] | |
9 | ||
10 | To aid in debugging asynchronous programs, Boost.Asio provides support for handler | |
11 | tracking. When enabled by defining `BOOST_ASIO_ENABLE_HANDLER_TRACKING`, Boost.Asio | |
12 | writes debugging output to the standard error stream. The output records | |
13 | asynchronous operations and the relationships between their handlers. | |
14 | ||
15 | [teletype] | |
16 | This feature is useful when debugging and you need to know how your | |
17 | asynchronous operations are chained together, or what the pending asynchronous | |
18 | operations are. As an illustration, here is the output when you run the HTTP | |
19 | Server example, handle a single request, then shut down via Ctrl+C: | |
20 | ||
21 | @asio|1298160085.070638|0*1|signal_set@0x7fff50528f40.async_wait | |
22 | @asio|1298160085.070888|0*2|socket@0x7fff50528f60.async_accept | |
23 | @asio|1298160085.070913|0|resolver@0x7fff50528e28.cancel | |
24 | @asio|1298160118.075438|>2|ec=asio.system:0 | |
25 | @asio|1298160118.075472|2*3|socket@0xb39048.async_receive | |
26 | @asio|1298160118.075507|2*4|socket@0x7fff50528f60.async_accept | |
27 | @asio|1298160118.075527|<2| | |
28 | @asio|1298160118.075540|>3|ec=asio.system:0,bytes_transferred=122 | |
29 | @asio|1298160118.075731|3*5|socket@0xb39048.async_send | |
30 | @asio|1298160118.075778|<3| | |
31 | @asio|1298160118.075793|>5|ec=asio.system:0,bytes_transferred=156 | |
32 | @asio|1298160118.075831|5|socket@0xb39048.close | |
33 | @asio|1298160118.075855|<5| | |
34 | @asio|1298160122.827317|>1|ec=asio.system:0,signal_number=2 | |
35 | @asio|1298160122.827333|1|socket@0x7fff50528f60.close | |
36 | @asio|1298160122.827359|<1| | |
37 | @asio|1298160122.827370|>4|ec=asio.system:125 | |
38 | @asio|1298160122.827378|<4| | |
39 | @asio|1298160122.827394|0|signal_set@0x7fff50528f40.cancel | |
40 | ||
41 | Each line is of the form: | |
42 | ||
43 | <tag>|<timestamp>|<action>|<description> | |
44 | ||
45 | The `<tag>` is always `@asio`, and is used to identify and extract the handler | |
46 | tracking messages from the program output. | |
47 | ||
48 | The `<timestamp>` is seconds and microseconds from 1 Jan 1970 UTC. | |
49 | ||
50 | The `<action>` takes one of the following forms: | |
51 | ||
52 | [variablelist | |
53 | [ | |
54 | [>n] | |
55 | [The program entered the handler number `n`. The `<description>` shows the | |
56 | arguments to the handler.] | |
57 | ] | |
58 | [ | |
59 | [<n] | |
60 | [The program left handler number `n`.] | |
61 | ] | |
62 | [ | |
63 | [!n] | |
64 | [The program left handler number n due to an exception.] | |
65 | ] | |
66 | [ | |
67 | [~n] | |
68 | [The handler number `n` was destroyed without having been invoked. This is | |
69 | usually the case for any unfinished asynchronous operations when the | |
70 | `io_service` is destroyed.] | |
71 | ] | |
72 | [ | |
73 | [n*m] | |
74 | [The handler number `n` created a new asynchronous operation with completion | |
75 | handler number `m`. The `<description>` shows what asynchronous operation | |
76 | was started.] | |
77 | ] | |
78 | [ | |
79 | [n] | |
80 | [The handler number n performed some other operation. The `<description>` | |
81 | shows what function was called. Currently only `close()` and `cancel()` | |
82 | operations are logged, as these may affect the state of pending | |
83 | asynchronous operations.] | |
84 | ] | |
85 | ] | |
86 | ||
87 | Where the `<description>` shows a synchronous or asynchronous operation, the | |
88 | format is `<object-type>@<pointer>.<operation>`. For handler entry, it shows a | |
89 | comma-separated list of arguments and their values. | |
90 | ||
91 | As shown above, Each handler is assigned a numeric identifier. Where the | |
92 | handler tracking output shows a handler number of 0, it means that the action | |
93 | was performed outside of any handler. | |
94 | ||
95 | [heading Visual Representations] | |
96 | ||
97 | The handler tracking output may be post-processed using the included | |
98 | [^handlerviz.pl] tool to create a visual representation of the handlers | |
99 | (requires the GraphViz tool [^dot]). | |
100 | [c++] | |
101 | ||
102 | [endsect] |