summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/html/MountingFiles.html419
-rw-r--r--doc/html/Performance.html162
2 files changed, 581 insertions, 0 deletions
diff --git a/doc/html/MountingFiles.html b/doc/html/MountingFiles.html
new file mode 100644
index 0000000..5e35e74
--- /dev/null
+++ b/doc/html/MountingFiles.html
@@ -0,0 +1,419 @@
+<html>
+ <head>
+ <title>Mounting Files</title>
+ </head>
+
+ <body bgcolor="#FFFFFF">
+
+
+<hr>
+<center>
+<table border=0 width=98%>
+<tr><td valign=top align=left>
+ <a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
+ <a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;<br>
+ <a href="index.html">Other HDF5 documents and links</a>&nbsp;<br>
+ <!--
+ <a href="Glossary.html">Glossary</a><br>
+ -->
+</td>
+<td valign=top align=right>
+ And in this document, the
+ <a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>&nbsp;&nbsp;&nbsp;&nbsp;
+ <br>
+ <a href="Files.html">Files</a>&nbsp;&nbsp;
+ <a href="Datasets.html">Datasets</a>&nbsp;&nbsp;
+ <a href="Datatypes.html">Datatypes</a>&nbsp;&nbsp;
+ <a href="Dataspaces.html">Dataspaces</a>&nbsp;&nbsp;
+ <a href="Groups.html">Groups</a>&nbsp;&nbsp;
+ <br>
+ <a href="References.html">References</a>&nbsp;&nbsp;
+ <a href="Attributes.html">Attributes</a>&nbsp;&nbsp;
+ <a href="Properties.html">Property Lists</a>&nbsp;&nbsp;
+ <a href="Errors.html">Error Handling</a>&nbsp;&nbsp;
+ <br>
+ <a href="Filters.html">Filters</a>&nbsp;&nbsp;
+ <a href="Caching.html">Caching</a>&nbsp;&nbsp;
+ <a href="Chunking.html">Chunking</a>&nbsp;&nbsp;
+ Mounting Files&nbsp;&nbsp;
+ <br>
+ <a href="Performance.html">Performance</a>&nbsp;&nbsp;
+ <a href="Debugging.html">Debugging</a>&nbsp;&nbsp;
+ <a href="Environment.html">Environment</a>&nbsp;&nbsp;
+ <a href="ddl.html">DDL</a>&nbsp;&nbsp;
+ <br>
+ <a href="Ragged.html">Ragged Arrays</a>&nbsp;&nbsp;
+</td></tr>
+</table>
+</center>
+<hr>
+
+
+ <h1>Mounting Files</h1>
+
+ <h2>Purpose</h2>
+
+ <p>This document contrasts two methods for mounting an hdf5 file
+ on another hdf5 file: the case where the relationship between
+ files is a tree and the case where it's a graph. The tree case
+ simplifies current working group functions and allows symbolic
+ links to point into ancestor files whereas the graph case is
+ more consistent with the organization of groups within a
+ particular file.
+
+ <h2>Definitions</h2>
+
+ <p>If file <code>child</code> is mounted on file
+ <code>parent</code> at group <code>/mnt</code> in
+ <code>parent</code> then the contents of the root group of
+ <code>child</code> will appear in the group <code>/mnt</code> of
+ <code>parent</code>. The group <code>/mnt</code> is called the
+ <em>mount point</em> of the child in the parent.
+
+ <h2>Common Features</h2>
+
+ <p>These features are common to both mounting schemes.
+
+ <ul>
+ <li>The previous contents of <code>/mnt</code> in
+ <code>parent</code> is temporarily hidden. If objects in that
+ group had names from other groups then the objects will still
+ be visible by those other names.
+
+ <li>The mount point is actually an OID (not a name) so if there
+ are other names besides <code>/mnt</code> for that group then
+ the root group of the child will be visible in all those
+ names.
+
+ <li>At most one file can be mounted per mount point but a parent
+ can have any number of mounted children.
+
+ <li>Name lookups will entail a search through the mount table at
+ each stage of the lookup. The search will be O(log
+ <em>N</em>) where <em>N</em> is the number of children mounted
+ on that file.
+
+ <li>Files open for read-only can be mounted on other files that
+ are open for read-only. Mounting a file in no way changes the
+ contents of the file.
+
+ <li>Mounting a child may hide mount points that exist below the
+ child's mount point, but it does not otherwise affect mounted
+ files.
+
+ <li>Hard links cannot cross file boundaries. An object cannot
+ be moved or renamed with <code>H5Gmove()</code> in such a way
+ that the new location would be in a different file than the
+ original location.
+
+ <li>The child can be accessed in a manner different from the
+ parent. For instance, a read-write child in a read-only
+ parent, a parallel child in a serial parent, <em>etc</em>.
+
+ <li>If some object in the child is open and the child is
+ unmounted and/or closed, the object will remain open and
+ accessible until explicitly closed. As in the mountless case,
+ the underlying UNIX file will be held open until all member
+ objects are closed.
+
+ <li>Current working groups that point into a child will remain
+ open and usable even after the child has been unmounted and/or
+ closed.
+
+ <li>Datasets that share a committed datatype must reside in the
+ same file as the datatype.
+
+ </ul>
+
+ <h2>Contrasting Features</h2>
+
+ <center>
+ <table border width="90%">
+ <tr>
+ <th width="50%">Tree</th>
+ <th width="50%">Graph</th>
+ </tr>
+
+ <tr valign=top>
+ <td>The set of mount-related files makes a tree.</td>
+ <td>The set of mount-related files makes a directed
+ graph.</td>
+ </tr>
+
+ <tr valign=top>
+ <td>A file can be mounted at only one mount point.</td>
+ <td>A file can be mounted at any number of mount points.</td>
+ </tr>
+
+ <tr valign=top>
+ <td>Symbolic links in the child that have a link value which
+ is an absolute name can be interpreted with respect to the
+ root group of either the child or the root of the mount
+ tree, a property which is determined when the child is
+ mounted.</td>
+ <td>Symbolic links in the child that have a link value which
+ is an absolute name are interpreted with respect to the
+ root group of the child.</td>
+ </tr>
+
+ <tr valign=top>
+ <td>Closing a child causes it to be unmounted from the
+ parent.</td>
+ <td>Closing a child has no effect on its relationship with
+ the parent. One can continue to access the child contents
+ through the parent.</td>
+ </tr>
+
+ <tr valign=top>
+ <td>Closing the parent recursively unmounts and closes all
+ mounted children.</td>
+ <td>Closing the parent unmounts all children but
+ does not close them or unmount their children.</td>
+ </tr>
+
+ <tr valign=top>
+ <td>The current working group functions
+ <code>H5Gset()</code>, <code>H5Gpush()</code>, and
+ <code>H5Gpop()</code> operate on the root of the mount
+ tree.</td>
+ <td>The current working group functions operate on the file
+ specified by their first argument.</td>
+ </tr>
+
+ <tr valign=top>
+ <td>Absolute name lookups (like for <code>H5Dopen()</code>)
+ are always performed with respect to the root of the mount
+ tree.</td>
+ <td>Absolute name lookups are performed with respect to the
+ file specified by the first argument.</td>
+ </tr>
+
+ <tr valign=top>
+ <td>Relative name lookups (like for <code>H5Dopen()</code>)
+ are always performed with respect to the specified group
+ or the current working group of the root of the mount
+ tree.</td>
+ <td>Relative name lookups are always performed with respect
+ to the specified group or the current working group of the
+ file specified by the first argument.</td>
+ </tr>
+
+ <tr valign=top>
+ <td>Mounting a child temporarily hides the current working
+ group stack for that child</td>
+ <td>Mounting a child has no effect on its current working
+ group stack.</td>
+ </tr>
+
+ <tr valign=top>
+ <td>Calling <code>H5Fflush()</code> will flush all files of
+ the mount tree regardless of which file is specified as
+ the argument.</td>
+ <td>Calling <code>H5Fflush()</code> will flush only the
+ specified file.</td>
+ </tr>
+
+
+ </table>
+ </center>
+
+
+ <h2>Functions</h2>
+
+ <dl>
+ <dt><code>herr_t H5Fmount(hid_t <em>loc</em>, const char
+ *<em>name</em>, hid_t <em>child</em>, hid_t
+ <em>plist</em>)</code>
+ <dd>The file <em>child</em> is mounted at the specified location
+ in the parent. The <em>loc</em> and <em>name</em> specify the
+ mount point, a group in the parent. The <em>plist</em>
+ argument is an optional mount property list. The call will
+ fail if some file is already mounted on the specified group.
+
+ <table border>
+ <tr>
+ <th width="50%">Tree</th>
+ <th width="50%">Graph</th>
+ </tr>
+ <tr valign=top>
+ <td>The call will fail if the child is already mounted
+ elsewhere.</td>
+ <td>A child can be mounted at numerous mount points.</td>
+ </tr>
+ <tr valign=top>
+ <td>The call will fail if the child is an ancestor of the
+ parent.</td>
+ <td>The mount graph is allowed to have cycles.</td>
+ </tr>
+ <tr valign=top>
+ <td>Subsequently closing the child will cause it to be
+ unmounted from the parent.</td>
+ <td>Closing the child has no effect on its mount
+ relationship with the parent.</td>
+ </tr>
+ </table>
+
+ <br><br>
+ <dt><code>herr_t H5Funmount(hid_t <em>loc</em>, const char
+ *<em>name</em>)</code>
+ <dd>Any file mounted at the group specified by <em>loc</em> and
+ <em>name</em> is unmounted. The child is not closed. This
+ function fails if no child is mounted at the specified point.
+
+ <br><br>
+ <dt><code>hid_t H5Pcreate(H5P_MOUNT)</code>
+ <dd>Creates and returns a new mount property list initialized
+ with default values.
+
+ <br><br>
+ <dt><code>herr_t H5Pset_symlink_locality(hid_t <em>plist</em>,
+ H5G_symlink_t <em>locality</em>)</code>
+ <dt><code>herr_t H5Pget_symlink_locality(hid_t <em>plist</em>,
+ H5G_symlink_t *<em>locality</em>)</code>
+ <dd>These functions exist only for the tree scheme. They set or
+ query the property that determines whether symbolic links with
+ absolute name value in the child are looked up with respect to
+ the child or to the mount root. The possible values are
+ <code>H5G_SYMLINK_LOCAL</code> or
+ <code>H5G_SYMLINK_GLOBAL</code> (the default).
+
+ <br><br>
+ <dt><code>hid_t H5Freopen(hid_t <em>file</em>)</code>
+ <dd>A file handle is reopened, creating an additional file
+ handle. The new file handle refers to the same file but has an
+ empty current working group stack.
+
+ <table border>
+ <tr>
+ <th width="50%">Tree</th>
+ <th width="50%">Graph</th>
+ </tr>
+ <tr valign=top>
+ <td>The new handle is not mounted but the old handle
+ continues to be mounted.</td>
+ <td>The new handle is mounted at the same location(s) as
+ the original handle.</td>
+ </tr>
+ </table>
+ </dl>
+
+ <h2>Example</h2>
+
+ <p>A file <code>eos.h5</code> contains data which is constant for
+ all problems. The output of a particular physics application is
+ dumped into <code>data1.h5</code> and <code>data2.h5</code> and
+ the physics expects various constants from <code>eos.h5</code>
+ in the <code>eos</code> group of the two data files. Instead of
+ copying the contents of <code>eos.h5</code> into every physics
+ output file we simply mount <code>eos.h5</code> as a read-only
+ child of <code>data1.h5</code> and <code>data2.h5</code>.
+
+ <center>
+ <table border width="90%">
+ <tr><td><h3>Tree</h3><code><pre>
+/* Create data1.h5 */
+data1 = H5Fcreate("data1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+H5Gclose(H5Gcreate(data1, "/eos", 0));
+H5Gset_comment(data1, "/eos", "EOS mount point");
+
+/* Create data2.h5 */
+data2 = H5Fcreate("data2.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+H5Gclose(H5Gcreate(data2, "/eos", 0));
+H5Gset_comment(data2, "/eos", "EOS mount point");
+
+/* Open eos.h5 and mount it in both files */
+eos1 = H5Fopen("eos.h5", H5F_ACC_RDONLY, H5P_DEFAULT);
+H5Fmount(data1, "/eos", eos1, H5P_DEFAULT);
+eos2 = H5Freopen(eos1);
+H5Fmount(data2, "/eos", eos2, H5P_DEFAULT);
+
+ ... physics output ...
+
+H5Fclose(data1);
+H5Fclose(data2);
+ </pre></code></td></tr>
+ <tr><td><h3>Graph</h3><code><pre>
+/* Create data1.h5 */
+data1 = H5Fcreate("data1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+H5Gclose(H5Gcreate(data1, "/eos", 0));
+H5Gset_comment(data1, "/eos", "EOS mount point");
+
+/* Create data2.h5 */
+data2 = H5Fcreate("data2.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+H5Gclose(H5Gcreate(data2, "/eos", 0));
+H5Gset_comment(data2, "/eos", "EOS mount point");
+
+/* Open eos.h5 and mount it in both files */
+eos = H5Fopen("eos.h5", H5F_ACC_RDONLY, H5P_DEFAULT);
+H5Fmount(data1, "/eos", eos, H5P_DEFAULT);
+H5Fmount(data2, "/eos", eos, H5P_DEFAULT);
+H5Fclose(eos);
+
+ ... physics output ...
+
+H5Fclose(data1);
+H5Fclose(data2);
+ </pre></code></td></tr>
+ </table>
+ </center>
+
+
+<hr>
+<center>
+<table border=0 width=98%>
+<tr><td valign=top align=left>
+ <a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
+ <a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;<br>
+ <a href="index.html">Other HDF5 documents and links</a>&nbsp;<br>
+ <!--
+ <a href="Glossary.html">Glossary</a><br>
+ -->
+</td>
+<td valign=top align=right>
+ And in this document, the
+ <a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>&nbsp;&nbsp;&nbsp;&nbsp;
+ <br>
+ <a href="Files.html">Files</a>&nbsp;&nbsp;
+ <a href="Datasets.html">Datasets</a>&nbsp;&nbsp;
+ <a href="Datatypes.html">Datatypes</a>&nbsp;&nbsp;
+ <a href="Dataspaces.html">Dataspaces</a>&nbsp;&nbsp;
+ <a href="Groups.html">Groups</a>&nbsp;&nbsp;
+ <br>
+ <a href="References.html">References</a>&nbsp;&nbsp;
+ <a href="Attributes.html">Attributes</a>&nbsp;&nbsp;
+ <a href="Properties.html">Property Lists</a>&nbsp;&nbsp;
+ <a href="Errors.html">Error Handling</a>&nbsp;&nbsp;
+ <br>
+ <a href="Filters.html">Filters</a>&nbsp;&nbsp;
+ <a href="Caching.html">Caching</a>&nbsp;&nbsp;
+ <a href="Chunking.html">Chunking</a>&nbsp;&nbsp;
+ Mounting Files&nbsp;&nbsp;
+ <br>
+ <a href="Performance.html">Performance</a>&nbsp;&nbsp;
+ <a href="Debugging.html">Debugging</a>&nbsp;&nbsp;
+ <a href="Environment.html">Environment</a>&nbsp;&nbsp;
+ <a href="ddl.html">DDL</a>&nbsp;&nbsp;
+ <br>
+ <a href="Ragged.html">Ragged Arrays</a>&nbsp;&nbsp;
+</td></tr>
+</table>
+</center>
+
+
+
+<hr>
+<address>
+<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
+</address>
+
+<!-- Created: Spring 1999 -->
+<!-- hhmts start -->
+Last modified: 14 October 1999
+<!-- hhmts end -->
+
+<br>
+Describes HDF5 Release 1.4 Beta, December 2000
+
+
+ </body>
+</html>
diff --git a/doc/html/Performance.html b/doc/html/Performance.html
new file mode 100644
index 0000000..b43dd78
--- /dev/null
+++ b/doc/html/Performance.html
@@ -0,0 +1,162 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+ <head>
+ <title>Performance</title>
+ </head>
+
+ <body bgcolor="#FFFFFF">
+
+
+<hr>
+<center>
+<table border=0 width=98%>
+<tr><td valign=top align=left>
+ <a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
+ <a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;<br>
+ <a href="index.html">Other HDF5 documents and links</a>&nbsp;<br>
+ <!--
+ <a href="Glossary.html">Glossary</a><br>
+ -->
+</td>
+<td valign=top align=right>
+ And in this document, the
+ <a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>&nbsp;&nbsp;&nbsp;&nbsp;
+ <br>
+ <a href="Files.html">Files</a>&nbsp;&nbsp;
+ <a href="Datasets.html">Datasets</a>&nbsp;&nbsp;
+ <a href="Datatypes.html">Datatypes</a>&nbsp;&nbsp;
+ <a href="Dataspaces.html">Dataspaces</a>&nbsp;&nbsp;
+ <a href="Groups.html">Groups</a>&nbsp;&nbsp;
+ <br>
+ <a href="References.html">References</a>&nbsp;&nbsp;
+ <a href="Attributes.html">Attributes</a>&nbsp;&nbsp;
+ <a href="Properties.html">Property Lists</a>&nbsp;&nbsp;
+ <a href="Errors.html">Error Handling</a>&nbsp;&nbsp;
+ <br>
+ <a href="Filters.html">Filters</a>&nbsp;&nbsp;
+ <a href="Caching.html">Caching</a>&nbsp;&nbsp;
+ <a href="Chunking.html">Chunking</a>&nbsp;&nbsp;
+ <a href="MountingFiles.html">Mounting Files</a>&nbsp;&nbsp;
+ <br>
+ Performance&nbsp;&nbsp;
+ <a href="Debugging.html">Debugging</a>&nbsp;&nbsp;
+ <a href="Environment.html">Environment</a>&nbsp;&nbsp;
+ <a href="ddl.html">DDL</a>&nbsp;&nbsp;
+ <br>
+ <a href="Ragged.html">Ragged Arrays</a>&nbsp;&nbsp;
+</td></tr>
+</table>
+</center>
+<hr>
+
+
+ <h1>Performance Analysis and Issues</h1>
+
+ <h2>1. Introduction</h2>
+
+ <p>This section includes brief discussions of performance issues
+ in HDF5 and performance analysis tools for HDF5 or pointers to
+ such discussions.
+
+ <h2>2. Dataset Chunking</h2>
+
+ Appropriate dataset chunking can make a siginificant difference
+ in HDF5 performance. This topic is discussed in
+ <a href="Chunking.html">Dataset Chunking Issues</a> elsewhere
+ in this <cite>User's Guide</cite>.
+
+ <h2>3. Use of the Pablo Instrumentation of HDF5</h2>
+
+ Pablo HDF5 Trace software provides a means of measuring the
+ performance of programs using HDF5.
+
+ <p>The Pablo software consists
+ of an instrumented copy of the HDF5 library, the Pablo Trace and
+ Trace Extensions libraries, and some utilities for processing the
+ output. The instrumented version of the HDF5 library has hooks
+ inserted into the HDF5 code which call routines in the Pablo Trace
+ library just after entry to each instrumented HDF5 routine and
+ just prior to exit from the routine. The Pablo Trace Extension
+ library has programs that track the I/O activity between the
+ entry and exit of the HDF5 routine during execution.
+
+ <p>A few lines of code must be inserted in the user's main program
+ to enable tracing and to specify which HDF5 procedures are to be
+ traced. The program is linked with the special HDF5 and Pablo
+ libraries to produce an executable. Running this executable on
+ a single processor produces an output file called the trace file
+ which contains records, called Pablo Self-Defining Data Format
+ (SDDF) records, which can later be analyzed using the
+ HDF5 Analysis Utilities. The HDF5 Analysis Utilites can be used
+ to interpret the SDDF records in the trace files to produce a
+ report describing the HDF5 IO activity that occurred during
+ execution.
+
+ <p>For further instructions, see the file <code>READ_ME</code>
+ in the <code> $(toplevel)/hdf5/pablo/ </code> subdirectory of
+ the HDF5 source code distribution.
+
+ <p>For further information about Pablo and the
+ Self-Defining Data Format, visit the Pablo website at
+ <code><a href="http://www-pablo.cs.uiuc.edu/">http://www-pablo.cs.uiuc.edu/</a></code>.
+
+
+<hr>
+<center>
+<table border=0 width=98%>
+<tr><td valign=top align=left>
+ <a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
+ <a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;<br>
+ <a href="index.html">Other HDF5 documents and links</a>&nbsp;<br>
+ <!--
+ <a href="Glossary.html">Glossary</a><br>
+ -->
+</td>
+<td valign=top align=right>
+ And in this document, the
+ <a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>&nbsp;&nbsp;&nbsp;&nbsp;
+ <br>
+ <a href="Files.html">Files</a>&nbsp;&nbsp;
+ <a href="Datasets.html">Datasets</a>&nbsp;&nbsp;
+ <a href="Datatypes.html">Datatypes</a>&nbsp;&nbsp;
+ <a href="Dataspaces.html">Dataspaces</a>&nbsp;&nbsp;
+ <a href="Groups.html">Groups</a>&nbsp;&nbsp;
+ <br>
+ <a href="References.html">References</a>&nbsp;&nbsp;
+ <a href="Attributes.html">Attributes</a>&nbsp;&nbsp;
+ <a href="Properties.html">Property Lists</a>&nbsp;&nbsp;
+ <a href="Errors.html">Error Handling</a>&nbsp;&nbsp;
+ <br>
+ <a href="Filters.html">Filters</a>&nbsp;&nbsp;
+ <a href="Caching.html">Caching</a>&nbsp;&nbsp;
+ <a href="Chunking.html">Chunking</a>&nbsp;&nbsp;
+ <a href="MountingFiles.html">Mounting Files</a>&nbsp;&nbsp;
+ <br>
+ Performance&nbsp;&nbsp;
+ <a href="Debugging.html">Debugging</a>&nbsp;&nbsp;
+ <a href="Environment.html">Environment</a>&nbsp;&nbsp;
+ <a href="ddl.html">DDL</a>&nbsp;&nbsp;
+ <br>
+ <a href="Ragged.html">Ragged Arrays</a>&nbsp;&nbsp;
+</td></tr>
+</table>
+</center>
+
+
+
+<hr>
+<address>
+<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
+</address>
+
+<!-- Created: Thu Oct 14 16:46:00 CDT 1999 -->
+<!-- hhmts start -->
+Last modified: 14 October 1999
+<!-- hhmts end -->
+
+<br>
+Describes HDF5 Release 1.4 Beta, December 2000
+
+
+ </body>
+</html>