[svn-r467] Restructuring documentation.

author: Quincey Koziol <koziol@hdfgroup.org> 1998-07-08 14:54:54 (GMT)
committer: Quincey Koziol <koziol@hdfgroup.org> 1998-07-08 14:54:54 (GMT)
commit: bd1e676c521d881b3143829f493a28b5ced1294b (patch)
tree: 69c50f9fe21ce87f293d8617a6bd51b4cc1e0244 /doc/html/tracing.html
parent: 73345095897d9698bb1f2f7df830bf80a56dc65a (diff)
download: hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.zip
hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.gz
hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.bz2
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>
author	Quincey Koziol <koziol@hdfgroup.org>	1998-07-08 14:54:54 (GMT)
committer	Quincey Koziol <koziol@hdfgroup.org>	1998-07-08 14:54:54 (GMT)
commit	bd1e676c521d881b3143829f493a28b5ced1294b (patch)
tree	69c50f9fe21ce87f293d8617a6bd51b4cc1e0244 /doc/html/tracing.html
parent	73345095897d9698bb1f2f7df830bf80a56dc65a (diff)
download	hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.zip hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.gz hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.bz2