AuroraMiddleware/asio
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Document the new handler tracking features.

Browse Source
This commit is contained in:
Christopher Kohlhoff 2017-12-03 14:20:37 +11:00
parent ff9d69e2fc
commit cca13eefa0
1 changed files with 138 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
asio/src/doc/overview/handler_tracking.qbk
View File

@ -18,25 +18,30 @@ 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|1298160085.070638|0*1|signal_set@0x7fff50528f40.async_wait
@asio|1298160085.070888|0*2|socket@0x7fff50528f60.async_accept
@asio|1298160085.070913|0|resolver@0x7fff50528e28.cancel
@asio|1298160118.075438|>2|ec=asio.system:0
@asio|1298160118.075472|2*3|socket@0xb39048.async_receive
@asio|1298160118.075507|2*4|socket@0x7fff50528f60.async_accept
@asio|1298160118.075527|<2|
@asio|1298160118.075540|>3|ec=asio.system:0,bytes_transferred=122
@asio|1298160118.075731|3*5|socket@0xb39048.async_send
@asio|1298160118.075778|<3|
@asio|1298160118.075793|>5|ec=asio.system:0,bytes_transferred=156
@asio|1298160118.075831|5|socket@0xb39048.close
@asio|1298160118.075855|<5|
@asio|1298160122.827317|>1|ec=asio.system:0,signal_number=2
@asio|1298160122.827333|1|socket@0x7fff50528f60.close
@asio|1298160122.827359|<1|
@asio|1298160122.827370|>4|ec=asio.system:125
@asio|1298160122.827378|<4|
@asio|1298160122.827394|0|signal_set@0x7fff50528f40.cancel
@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:
@ -77,11 +82,19 @@ The `<action>` takes one of the following forms:
]
[
[n]
[The handler number n performed some other operation. The `<description>`
[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
@ -99,4 +112,109 @@ The handler tracking output may be post-processed using the included
(requires the GraphViz tool [^dot]).
[c++]
[heading Custom Tracking]
Handling tracking may be customised by defining the
`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]]
[
[`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`.]
]
[
[`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`.]
]
[
[`ASIO_HANDLER_TRACKING_INIT(args)`]
[An expression that is used to initialise the tracking mechanism.]
]
[
[`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.]
]
[
[`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.]
]
[
[`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.]
]
[
[`ASIO_HANDLER_INVOCATION_END`]
[An expression that is called immediately after a completion handler is
invoked.]
]
[
[`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.]
]
[
[`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.]
]
[
[`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.]
]
[
[`ASIO_HANDLER_REACTOR_READ_EVENT`]
[A bitmask constant used to identify reactor read readiness events.]
]
[
[`ASIO_HANDLER_REACTOR_WRITE_EVENT`]
[A bitmask constant used to identify reactor write readiness events.]
]
[
[`ASIO_HANDLER_REACTOR_ERROR_EVENT`]
[A bitmask constant used to identify reactor error readiness events.]
]
[
[`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.]
]
[
[`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 asio.examples.cpp11_examples.handler_tracking Custom handler tracking
example].
[endsect]