mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-12-09 07:32:32 +08:00
768b7465a1
---------------------- ./MANIFEST Alphabetized. `d' comes before `e' :-) ./bin/release Added the `-batch' option which causes the script to not ask questions and to automatically update the minor version number and set the patch level back to `a'. This is intended to be used for the daily snapshots: #! /bin/sh set -e cd ~/hdf5 make distclean make test bin/release -batch tar compress gzip bzip2 mv ./releases/* /repository ./src/H5Z.c Removed warnings about unused variables when the zlib.h header file is present but libz.a isn't. ./INSTALL ./configure.in ./doc/html/tracing.html Made API tracing the default (you still need to define the HDF5_TRACE environment variable to get results) and change the name from `--disable-tracing' to `--disable-trace' to make it consistent with the other switches. Changed `site config file' to `host config file' to match the documentation. ./doc/html/H5.user.html Added a reference to the `tracing.html' file.
194 lines
6.4 KiB
HTML
194 lines
6.4 KiB
HTML
<!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-trace</code> switch (the default;
|
|
`--disable-trace' is the alternative). 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-trace
|
|
$ 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 Jul 8 14:07:23 EDT 1998
|
|
<!-- hhmts end -->
|
|
</body>
|
|
</html>
|