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 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: Server example, handle a single request, then shut down via Ctrl+C:
@asio|1298160085.070638|0*1|signal_set@0x7fff50528f40.async_wait @asio|1512254357.979980|0*1|signal_set@0x7ffeaaaa20d8.async_wait
@asio|1298160085.070888|0*2|socket@0x7fff50528f60.async_accept @asio|1512254357.980127|0*2|socket@0x7ffeaaaa20f8.async_accept
@asio|1298160085.070913|0|resolver@0x7fff50528e28.cancel @asio|1512254357.980150|.2|non_blocking_accept,ec=asio.system:11
@asio|1298160118.075438|>2|ec=asio.system:0 @asio|1512254357.980162|0|resolver@0x7ffeaaaa1fd8.cancel
@asio|1298160118.075472|2*3|socket@0xb39048.async_receive @asio|1512254368.457147|.2|non_blocking_accept,ec=system:0
@asio|1298160118.075507|2*4|socket@0x7fff50528f60.async_accept @asio|1512254368.457193|>2|ec=system:0
@asio|1298160118.075527|<2| @asio|1512254368.457219|2*3|socket@0x55cf39f0a238.async_receive
@asio|1298160118.075540|>3|ec=asio.system:0,bytes_transferred=122 @asio|1512254368.457244|.3|non_blocking_recv,ec=system:0,bytes_transferred=141
@asio|1298160118.075731|3*5|socket@0xb39048.async_send @asio|1512254368.457275|2*4|socket@0x7ffeaaaa20f8.async_accept
@asio|1298160118.075778|<3| @asio|1512254368.457293|.4|non_blocking_accept,ec=asio.system:11
@asio|1298160118.075793|>5|ec=asio.system:0,bytes_transferred=156 @asio|1512254368.457301|<2|
@asio|1298160118.075831|5|socket@0xb39048.close @asio|1512254368.457310|>3|ec=system:0,bytes_transferred=141
@asio|1298160118.075855|<5| @asio|1512254368.457441|3*5|socket@0x55cf39f0a238.async_send
@asio|1298160122.827317|>1|ec=asio.system:0,signal_number=2 @asio|1512254368.457502|.5|non_blocking_send,ec=system:0,bytes_transferred=156
@asio|1298160122.827333|1|socket@0x7fff50528f60.close @asio|1512254368.457511|<3|
@asio|1298160122.827359|<1| @asio|1512254368.457519|>5|ec=system:0,bytes_transferred=156
@asio|1298160122.827370|>4|ec=asio.system:125 @asio|1512254368.457544|5|socket@0x55cf39f0a238.close
@asio|1298160122.827378|<4| @asio|1512254368.457559|<5|
@asio|1298160122.827394|0|signal_set@0x7fff50528f40.cancel @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: Each line is of the form:
@ -77,11 +82,19 @@ The `<action>` takes one of the following forms:
] ]
[ [
[n] [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()` shows what function was called. Currently only `close()` and `cancel()`
operations are logged, as these may affect the state of pending operations are logged, as these may affect the state of pending
asynchronous operations.] 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 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]). (requires the GraphViz tool [^dot]).
[c++] [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] [endsect]