From fe3c7484d7643decb5d986a5baef928b837f6f39 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Fri, 22 Dec 2000 08:32:40 -0500 Subject: [svn-r3188] Purpose: Checking in MountingFiles.html and Performance.html. These documents were originally created in 1.2 branch and never checked in to the development branch. Platforms tested: IE 5 --- doc/html/MountingFiles.html | 419 ++++++++++++++++++++++++++++++++++++++++++++ doc/html/Performance.html | 162 +++++++++++++++++ 2 files changed, 581 insertions(+) create mode 100644 doc/html/MountingFiles.html create mode 100644 doc/html/Performance.html 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 @@ + + + Mounting Files + + + + + +
+
+ + + +
+ Introduction to HDF5 
+ HDF5 Reference Manual 
+ Other HDF5 documents and links 
+ +		 + And in this document, the + HDF5 User's Guide:     +
+ Files   + Datasets   + Datatypes   + Dataspaces   + Groups   +
+ References   + Attributes   + Property Lists   + Error Handling   +
+ Filters   + Caching   + Chunking   + Mounting Files   +
+ Performance   + Debugging   + Environment   + DDL   +
+ Ragged Arrays   +
+
+
+ + +

Mounting Files

+ +

Purpose

+ +

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. + +

Definitions

+ +

If file child is mounted on file + parent at group /mnt in + parent then the contents of the root group of + child will appear in the group /mnt of + parent. The group /mnt is called the + mount point of the child in the parent. + +

Common Features

+ +

These features are common to both mounting schemes. + +

+ +

Contrasting Features

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TreeGraph
The set of mount-related files makes a tree.The set of mount-related files makes a directed + graph.
A file can be mounted at only one mount point.A file can be mounted at any number of mount points.
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.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.
Closing a child causes it to be unmounted from the + parent.Closing a child has no effect on its relationship with + the parent. One can continue to access the child contents + through the parent.
Closing the parent recursively unmounts and closes all + mounted children.Closing the parent unmounts all children but + does not close them or unmount their children.
The current working group functions + H5Gset(), H5Gpush(), and + H5Gpop() operate on the root of the mount + tree.The current working group functions operate on the file + specified by their first argument.
Absolute name lookups (like for H5Dopen()) + are always performed with respect to the root of the mount + tree.Absolute name lookups are performed with respect to the + file specified by the first argument.
Relative name lookups (like for H5Dopen()) + are always performed with respect to the specified group + or the current working group of the root of the mount + tree.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.
Mounting a child temporarily hides the current working + group stack for that childMounting a child has no effect on its current working + group stack.
Calling H5Fflush() will flush all files of + the mount tree regardless of which file is specified as + the argument.Calling H5Fflush() will flush only the + specified file.
+
+ + +

Functions

+ +
+
herr_t H5Fmount(hid_t loc, const char + *name, hid_t child, hid_t + plist) +
The file child is mounted at the specified location + in the parent. The loc and name specify the + mount point, a group in the parent. The plist + argument is an optional mount property list. The call will + fail if some file is already mounted on the specified group. + + + + + + + + + + + + + + + + + + +
TreeGraph
The call will fail if the child is already mounted + elsewhere.A child can be mounted at numerous mount points.
The call will fail if the child is an ancestor of the + parent.The mount graph is allowed to have cycles.
Subsequently closing the child will cause it to be + unmounted from the parent.Closing the child has no effect on its mount + relationship with the parent.
+ +

+
herr_t H5Funmount(hid_t loc, const char + *name) +
Any file mounted at the group specified by loc and + name is unmounted. The child is not closed. This + function fails if no child is mounted at the specified point. + +

+
hid_t H5Pcreate(H5P_MOUNT) +
Creates and returns a new mount property list initialized + with default values. + +

+
herr_t H5Pset_symlink_locality(hid_t plist, + H5G_symlink_t locality) +
herr_t H5Pget_symlink_locality(hid_t plist, + H5G_symlink_t *locality) +
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 + H5G_SYMLINK_LOCAL or + H5G_SYMLINK_GLOBAL (the default). + +

+
hid_t H5Freopen(hid_t file) +
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. + + + + + + + + + + +
TreeGraph
The new handle is not mounted but the old handle + continues to be mounted.The new handle is mounted at the same location(s) as + the original handle.
+
+ +

Example

+ +

A file eos.h5 contains data which is constant for + all problems. The output of a particular physics application is + dumped into data1.h5 and data2.h5 and + the physics expects various constants from eos.h5 + in the eos group of the two data files. Instead of + copying the contents of eos.h5 into every physics + output file we simply mount eos.h5 as a read-only + child of data1.h5 and data2.h5. + +

+ + + +

Tree

+/* 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);
+

Graph

+/* 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);
+
+
+ + +
+
+ + + +
+ Introduction to HDF5 
+ HDF5 Reference Manual 
+ Other HDF5 documents and links 
+ +		 + And in this document, the + HDF5 User's Guide:     +
+ Files   + Datasets   + Datatypes   + Dataspaces   + Groups   +
+ References   + Attributes   + Property Lists   + Error Handling   +
+ Filters   + Caching   + Chunking   + Mounting Files   +
+ Performance   + Debugging   + Environment   + DDL   +
+ Ragged Arrays   +
+
+ + + +
+
+HDF Help Desk +
+ + + +Last modified: 14 October 1999 + + +
+Describes HDF5 Release 1.4 Beta, December 2000 + + + + 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 @@ + + + + Performance + + + + + +
+
+ + + +
+ Introduction to HDF5 
+ HDF5 Reference Manual 
+ Other HDF5 documents and links 
+ +		 + And in this document, the + HDF5 User's Guide:     +
+ Files   + Datasets   + Datatypes   + Dataspaces   + Groups   +
+ References   + Attributes   + Property Lists   + Error Handling   +
+ Filters   + Caching   + Chunking   + Mounting Files   +
+ Performance   + Debugging   + Environment   + DDL   +
+ Ragged Arrays   +
+
+
+ + +

Performance Analysis and Issues

+ +

1. Introduction

+ +

This section includes brief discussions of performance issues + in HDF5 and performance analysis tools for HDF5 or pointers to + such discussions. + +

2. Dataset Chunking

+ + Appropriate dataset chunking can make a siginificant difference + in HDF5 performance. This topic is discussed in + Dataset Chunking Issues elsewhere + in this User's Guide. + +

3. Use of the Pablo Instrumentation of HDF5

+ + Pablo HDF5 Trace software provides a means of measuring the + performance of programs using HDF5. + +

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. + +

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. + +

For further instructions, see the file READ_ME + in the $(toplevel)/hdf5/pablo/ subdirectory of + the HDF5 source code distribution. + +

For further information about Pablo and the + Self-Defining Data Format, visit the Pablo website at + http://www-pablo.cs.uiuc.edu/. + + +

+
+ + + +
+ Introduction to HDF5 
+ HDF5 Reference Manual 
+ Other HDF5 documents and links 
+ +		 + And in this document, the + HDF5 User's Guide:     +
+ Files   + Datasets   + Datatypes   + Dataspaces   + Groups   +
+ References   + Attributes   + Property Lists   + Error Handling   +
+ Filters   + Caching   + Chunking   + Mounting Files   +
+ Performance   + Debugging   + Environment   + DDL   +
+ Ragged Arrays   +
+
+ + + +
+
+HDF Help Desk +
+ + + +Last modified: 14 October 1999 + + +
+Describes HDF5 Release 1.4 Beta, December 2000 + + + + -- cgit v0.12