ceph/src/boost/libs/asio/doc/overview/handler_tracking.qbk

   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]