123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220 |
- [/
- / 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]
|