diff options
Diffstat (limited to 'src/H5Gmodule.h')
| -rw-r--r-- | src/H5Gmodule.h | 91 |
1 files changed, 88 insertions, 3 deletions
diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h index 219342d..fe26bd2 100644 --- a/src/H5Gmodule.h +++ b/src/H5Gmodule.h @@ -31,9 +31,94 @@ /** * \defgroup H5G H5G - * \brief Group Interface - * \details The HDF5 Group Interface, H5G, provides a mechanism for managing - * HDF5 groups and their members, which are other HDF5 objects. + * + * \details \Bold{Groups in HDF5:} A group associates names with objects and + * provides a mechanism for mapping a name to an object. Since all + * objects appear in at least one group (with the possible exception of + * the root object) and since objects can have names in more than one + * group, the set of all objects in an HDF5 file is a directed + * graph. The internal nodes (nodes with out-degree greater than zero) + * must be groups while the leaf nodes (nodes with out-degree zero) are + * either empty groups or objects of some other type. Exactly one + * object in every non-empty file is the root object. The root object + * always has a positive in-degree because it is pointed to by the file + * super block. + * + * \Bold{Locating objects in the HDF5 file hierarchy:} An object name + * consists of one or more components separated from one another by + * slashes. An absolute name begins with a slash and the object is + * located by looking for the first component in the root object, then + * looking for the second component in the first object, etc., until + * the entire name is traversed. A relative name does not begin with a + * slash and the traversal begins at the location specified by the + * create or access function. + * + * \Bold{Group implementations in HDF5:} The original HDF5 group + * implementation provided a single indexed structure for link + * storage. A new group implementation, in HDF5 Release 1.8.0, enables + * more efficient compact storage for very small groups, improved link + * indexing for large groups, and other advanced features. + * + * \li The \Emph{original indexed} format remains the default. Links + * are stored in a B-tree in the group’s local heap. + * \li Groups created in the new \Emph{compact-or-indexed} format, the + * implementation introduced with Release 1.8.0, can be tuned for + * performance, switching between the compact and indexed formats + * at thresholds set in the user application. + * - The \Emph{compact} format will conserve file space and processing + * overhead when working with small groups and is particularly + * valuable when a group contains no links. Links are stored + * as a list of messages in the group’s header. + * - The \Emph{indexed} format will yield improved + * performance when working with large groups, e.g., groups + * containing thousands to millions of members. Links are stored in + * a fractal heap and indexed with an improved B-tree. + * \li The new implementation also enables the use of link names consisting of + * non-ASCII character sets (see H5Pset_char_encoding()) and is + * required for all link types other than hard or soft links, e.g., + * external and user-defined links (see the \ref H5L APIs). + * + * The original group structure and the newer structures are not + * directly interoperable. By default, a group will be created in the + * original indexed format. An existing group can be changed to a + * compact-or-indexed format if the need arises; there is no capability + * to change back. As stated above, once in the compact-or-indexed + * format, a group can switch between compact and indexed as needed. + * + * Groups will be initially created in the compact-or-indexed format + * only when one or more of the following conditions is met: + * \li The low version bound value of the library version bounds property + * has been set to Release 1.8.0 or later in the file access property + * list (see H5Pset_libver_bounds()). Currently, that would require an + * H5Pset_libver_bounds() call with the low parameter set to + * #H5F_LIBVER_LATEST.\n When this property is set for an HDF5 file, + * all objects in the file will be created using the latest available + * format; no effort will be made to create a file that can be read by + * older libraries. + * \li The creation order tracking property, #H5P_CRT_ORDER_TRACKED, has been + * set in the group creation property list (see H5Pset_link_creation_order()). + * + * An existing group, currently in the original indexed format, will be + * converted to the compact-or-indexed format upon the occurrence of + * any of the following events: + * \li An external or user-defined link is inserted into the group. + * \li A link named with a string composed of non-ASCII characters is + * inserted into the group. + * + * The compact-or-indexed format offers performance improvements that + * will be most notable at the extremes, i.e., in groups with zero + * members and in groups with tens of thousands of members. But + * measurable differences may sometimes appear at a threshold as low as + * eight group members. Since these performance thresholds and criteria + * differ from application to application, tunable settings are + * provided to govern the switch between the compact and indexed + * formats (see H5Pset_link_phase_change()). Optimal thresholds will + * depend on the application and the operating environment. + * + * Future versions of HDF5 will retain the ability to create, read, + * write, and manipulate all groups stored in either the original + * indexed format or the compact-or-indexed format. + * */ #endif /* H5Gmodule_H */ |