EQ2EMu/EQ2/source/depends/boost_1_72_0/libs/asio/doc/overview/handler_tracking.qbk

[/
 / Copyright (c) 2003-2019 Christopher M. Kohlhoff (chris at kohlhoff dot com)
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section:handler_tracking Handler Tracking]

To aid in debugging asynchronous programs, Boost.Asio provides support for handler
tracking. When enabled by defining `BOOST_ASIO_ENABLE_HANDLER_TRACKING`, Boost.Asio
writes debugging output to the standard error stream. The output records
asynchronous operations and the relationships between their handlers.

[teletype]
This feature is useful when debugging and you need to know how your
asynchronous operations are chained together, or what the pending asynchronous
operations are. As an illustration, here is the output when you run the HTTP
Server example, handle a single request, then shut down via Ctrl+C:

  @asio|1512254357.979980|0*1|signal_set@0x7ffeaaaa20d8.async_wait
  @asio|1512254357.980127|0*2|socket@0x7ffeaaaa20f8.async_accept
  @asio|1512254357.980150|.2|non_blocking_accept,ec=asio.system:11
  @asio|1512254357.980162|0|resolver@0x7ffeaaaa1fd8.cancel
  @asio|1512254368.457147|.2|non_blocking_accept,ec=system:0
  @asio|1512254368.457193|>2|ec=system:0
  @asio|1512254368.457219|2*3|socket@0x55cf39f0a238.async_receive
  @asio|1512254368.457244|.3|non_blocking_recv,ec=system:0,bytes_transferred=141
  @asio|1512254368.457275|2*4|socket@0x7ffeaaaa20f8.async_accept
  @asio|1512254368.457293|.4|non_blocking_accept,ec=asio.system:11
  @asio|1512254368.457301|<2|
  @asio|1512254368.457310|>3|ec=system:0,bytes_transferred=141
  @asio|1512254368.457441|3*5|socket@0x55cf39f0a238.async_send
  @asio|1512254368.457502|.5|non_blocking_send,ec=system:0,bytes_transferred=156
  @asio|1512254368.457511|<3|
  @asio|1512254368.457519|>5|ec=system:0,bytes_transferred=156
  @asio|1512254368.457544|5|socket@0x55cf39f0a238.close
  @asio|1512254368.457559|<5|
  @asio|1512254371.385106|>1|ec=system:0,signal_number=2
  @asio|1512254371.385130|1|socket@0x7ffeaaaa20f8.close
  @asio|1512254371.385163|<1|
  @asio|1512254371.385175|>4|ec=asio.system:125
  @asio|1512254371.385182|<4|
  @asio|1512254371.385202|0|signal_set@0x7ffeaaaa20d8.cancel

Each line is of the form:

  <tag>|<timestamp>|<action>|<description>

The `<tag>` is always `@asio`, and is used to identify and extract the handler
tracking messages from the program output.

The `<timestamp>` is seconds and microseconds from 1 Jan 1970 UTC.

The `<action>` takes one of the following forms:

[variablelist
  [
    [>n]
    [The program entered the handler number `n`. The `<description>` shows the
    arguments to the handler.]
  ]
  [
    [<n]
    [The program left handler number `n`.]
  ]
  [
    [!n]
    [The program left handler number n due to an exception.]
  ]
  [
    [~n]
    [The handler number `n` was destroyed without having been invoked. This is
    usually the case for any unfinished asynchronous operations when the
    `io_context` is destroyed.]
  ]
  [
    [n*m]
    [The handler number `n` created a new asynchronous operation with completion
    handler number `m`. The `<description>` shows what asynchronous operation
    was started.]
  ]
  [
    [n]
    [The handler number `n` performed some other operation. The `<description>`
    shows what function was called. Currently only `close()` and `cancel()`
    operations are logged, as these may affect the state of pending
    asynchronous operations.]
  ]
  [
    [.n]
    [The implementation performed a system call as part of the asynchronous
    operation for which handler number `n` is the completion handler. The
    `<description>` shows what function was called and its results. These
    tracking events are only emitted when using a reactor-based
    implementation.]
  ]
]

Where the `<description>` shows a synchronous or asynchronous operation, the
format is `<object-type>@<pointer>.<operation>`. For handler entry, it shows a
comma-separated list of arguments and their values.

As shown above, Each handler is assigned a numeric identifier. Where the
handler tracking output shows a handler number of 0, it means that the action
was performed outside of any handler.

[heading Visual Representations]

The handler tracking output may be post-processed using the included
[^handlerviz.pl] tool to create a visual representation of the handlers
(requires the GraphViz tool [^dot]).
[c++]

[heading Custom Tracking]

Handling tracking may be customised by defining the
`BOOST_ASIO_CUSTOM_HANDLER_TRACKING` macro to the name of a header file
(enclosed in `""` or `<>`). This header file must implement the following
preprocessor macros:

[table
  [[Macro] [Description]]
  [
    [`BOOST_ASIO_INHERIT_TRACKED_HANDLER`]
    [Specifies a base class for classes that implement asynchronous operations.
    When used, the macro immediately follows the class name, so it must have
    the form `: public my_class`.]
  ]
  [
    [`BOOST_ASIO_ALSO_INHERIT_TRACKED_HANDLER`]
    [Specifies a base class for classes that implement asynchronous operations.
    When used, the macro follows other base classes, so it must have the form
    `, public my_class`.]
  ]
  [
    [`BOOST_ASIO_HANDLER_TRACKING_INIT(args)`]
    [An expression that is used to initialise the tracking mechanism.]
  ]
  [
    [`BOOST_ASIO_HANDLER_CREATION(args)`]
    [An expression that is called on creation of an asynchronous operation.
    `args` is a parenthesised function argument list containing the owning
    execution context, the tracked handler, the name of the object type, a
    pointer to the object, the object's native handle, and the operation name.]
  ]
  [
    [`BOOST_ASIO_HANDLER_COMPLETION(args)`]
    [An expression that is called on completion of an asynchronous operation.
    `args` is a parenthesised function argument list containing the tracked
    handler.]
  ]
  [
    [`BOOST_ASIO_HANDLER_INVOCATION_BEGIN(args)`]
    [An expression that is called immediately before a completion handler is
    invoked. `args` is a parenthesised function argument list containing the
    arguments to the completion handler.]
  ]
  [
    [`BOOST_ASIO_HANDLER_INVOCATION_END`]
    [An expression that is called immediately after a completion handler is
    invoked.]
  ]
  [
    [`BOOST_ASIO_HANDLER_OPERATION(args)`]
    [An expression that is called when some synchronous object operation is
    called (such as `close()` or `cancel()`). `args` is a parenthesised
    function argument list containing the owning execution context, the name
    of the object type, a pointer to the object, the object's native handle,
    and the operation name.]
  ]
  [
    [`BOOST_ASIO_HANDLER_REACTOR_REGISTRATION(args)`]
    [An expression that is called when an object is registered with the
    reactor. `args` is a parenthesised function argument list containing the
    owning execution context, the object's native handle, and a unique
    registration key.]
  ]
  [
    [`BOOST_ASIO_HANDLER_REACTOR_DEREGISTRATION(args)`]
    [An expression that is called when an object is deregistered from the
    reactor. `args` is a parenthesised function argument list containing the
    owning execution context, the object's native handle, and a unique
    registration key.]
  ]
  [
    [`BOOST_ASIO_HANDLER_REACTOR_READ_EVENT`]
    [A bitmask constant used to identify reactor read readiness events.]
  ]
  [
    [`BOOST_ASIO_HANDLER_REACTOR_WRITE_EVENT`]
    [A bitmask constant used to identify reactor write readiness events.]
  ]
  [
    [`BOOST_ASIO_HANDLER_REACTOR_ERROR_EVENT`]
    [A bitmask constant used to identify reactor error readiness events.]
  ]
  [
    [`BOOST_ASIO_HANDLER_REACTOR_EVENTS(args)`]
    [An expression that is called when an object registered with the reactor
    becomes ready. `args` is a parenthesised function argument list containing
    the owning execution context, the unique registration key, and a bitmask of
    the ready events.]
  ]
  [
    [`BOOST_ASIO_HANDLER_REACTOR_OPERATION(args)`]
    [An expression that is called when the implementation performs a system
    call as part of a reactor-based asynchronous operation. `args` is a
    parenthesised function argument list containing the tracked handler, the
    operation name, the error code produced by the operation, and (optionally)
    the number of bytes transferred.]
  ]
]

[heading See Also]

[link boost_asio.examples.cpp11_examples.handler_tracking Custom handler tracking
example].

[endsect]