diff options
Diffstat (limited to 'doc/html/tracing.html')
| -rw-r--r-- | doc/html/tracing.html | 192 |
1 files changed, 192 insertions, 0 deletions
diff --git a/doc/html/tracing.html b/doc/html/tracing.html new file mode 100644 index 0000000..18ef556 --- /dev/null +++ b/doc/html/tracing.html @@ -0,0 +1,192 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>API Tracing</title> + </head> + + <body> + <h1>API Tracing</h1> + + <h2>Introduction</h2> + + <p>The HDF5 library is now able to trace API calls by printing the + function name, the argument names and their values, and the + return value. Some people like to see lots of output during + program execution instead of using a good symbolic debugger, and + this feature is intended for their consumption. For example, + the output from <code>h5ls foo</code> after turning on tracing, + includes: + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><b>Sample Output</b></caption> + <tr> + <td> + <code><pre> +H5Tcopy(type=184549388) = 184549419 (type); +H5Tcopy(type=184549392) = 184549424 (type); +H5Tlock(type=184549424) = SUCCEED; +H5Tcopy(type=184549393) = 184549425 (type); +H5Tlock(type=184549425) = SUCCEED; +H5Fopen(filename="foo", flags=0, access=H5P_DEFAULT) = FAIL; +HDF5-DIAG: Error detected in thread 0. Back trace follows. + #000: H5F.c line 1245 in H5Fopen(): unable to open file + major(04): File interface + minor(10): Unable to open file + #001: H5F.c line 846 in H5F_open(): file does not exist + major(04): File interface + minor(10): Unable to open file + </pre></code> + </td> + </tr> + </table> + </center> + + <h2>Configuation</h2> + + <p>This all happens with some magic in the configuration script, + the makefiles, and macros. First, from the end-user point of + view, the library must be configured with the + <code>--enable-tracing</code> switch. This causes the library to + include the support necessary for API tracing. + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><b>Configuration</b></caption> + <tr> + <td> + <code><pre> +$ make distclean +$ sh configure --enable-tracing +$ make + </pre></code> + </td> + </tr> + </table> + </center> + + <h2>Execution</h2> + + <p>In order to actually get tracing output one must turn tracing + on and specify a file descriptor where the tracing output should + be written. This is done by assigning a file descriptor number + to the <code>HDF5_TRACE</code> environment variable. + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><b>Execution Examples</b></caption> + <tr> + <td>To display the trace on the standard error stream: + <code><pre> +$ export HDF5_TRACE=2 +$ a.out + </pre></code> + </td> + </tr> + <tr> + <td>To send the trace to a file: + <code><pre> +$ export HDF5_TRACE=255 +$ a.out 255>trace-output + </pre></code> + </td> + </tr> + </table> + </center> + + <h2>Performance</h2> + + <p>If the library was not configured for tracing then there is no + unnecessary overhead since all tracing code is + excluded. + + <p>However, if tracing is enabled but not used there is a + small penalty. First, code size is larger because of extra + statically-declared character strings used to store argument + types and names and extra auto variable pointer in each + function. Also, execution is slower because each function sets + and tests a local variable and each API function calls the + <code>H5_trace()</code> function. + + <p>If tracing is enabled and turned on then the penalties from the + previous paragraph apply plus the time required to format each + line of tracing information. There is also an extra call to + H5_trace() for each API function to print the return value. + + <h2>Safety</h2> + + <p>The tracing mechanism is invoked for each API function before + arguments are checked for validity. If bad arguments are passed + to an API function it could result in a segmentation fault. + However, the tracing output is line-buffered so all previous + output will appear. + + <h2>Completeness</h2> + + <p>There are two API functions that don't participate in + tracing. They are <code>H5Eprint()</code> and + <code>H5Eprint_cb()</code> because their participation would + mess up output during automatic error reporting. + + <p>On the other hand, a number of API functions are called during + library initialization and they print tracing information. + + <h2>Implementation</h2> + + <p>For those interested in the implementation here is a + description. Each API function should have a call to one of the + <code>H5TRACE()</code> macros immediately after the + <code>FUNC_ENTER()</code> macro. The first argument is the + return type encoded as a string. The second argument is the + types of all the function arguments encoded as a string. The + remaining arguments are the function arguments. This macro was + designed to be as terse and unobtrousive as possible. + + <p>In order to keep the <code>H5TRACE()</code> calls synchronized + with the source code we've written a perl script which gets + called automatically just before Makefile dependencies are + calculated for the file. However, this only works when one is + using GNU make. To reinstrument the tracing explicitly, invoke + the <code>trace</code> program from the hdf5 bin directory with + the names of the source files that need to be updated. If any + file needs to be modified then a backup is created by appending + a tilde to the file name. + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><b>Explicit Instrumentation</b></caption> + <tr> + <td> + <code><pre> +$ ../bin/trace *.c +H5E.c: in function `H5Ewalk_cb': +H5E.c:336: warning: trace info was not inserted + </pre></code> + </td> + </tr> + </table> + </center> + + <p>Note: The warning message is the result of a comment of the + form <code>/*NO TRACE*/</code> somewhere in the function + body. Tracing information will not be updated or inserted if + such a comment exists. + + <p>Error messages have the same format as a compiler so that they + can be parsed from program development environments like + Emacs. Any function which generates an error will not be + modified. + + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Wed Jun 17 12:29:12 EDT 1998 --> +<!-- hhmts start --> +Last modified: Wed Jun 17 15:45:50 EDT 1998 +<!-- hhmts end --> + </body> +</html> |