diff options
author | Allen Byrne <50328838+byrnHDF@users.noreply.github.com> | 2021-09-07 21:08:41 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-09-07 21:08:41 (GMT) |
commit | d0507c23f30fc1ff66ae4a31d41f681612e51851 (patch) | |
tree | 18032d7c438334900adf45d22659b70cee072215 /src/H5Imodule.h | |
parent | f5709db18e10993de3bc4668ad07b66d14279877 (diff) | |
download | hdf5-d0507c23f30fc1ff66ae4a31d41f681612e51851.zip hdf5-d0507c23f30fc1ff66ae4a31d41f681612e51851.tar.gz hdf5-d0507c23f30fc1ff66ae4a31d41f681612e51851.tar.bz2 |
1.12 Merge A batch of life-cycle examples for different modules #654 (#987)
* Merge A batch of life-cycle examples for different modules #654
* Remove generated file
* Change doxygen generated file location
Diffstat (limited to 'src/H5Imodule.h')
-rw-r--r-- | src/H5Imodule.h | 81 |
1 files changed, 79 insertions, 2 deletions
diff --git a/src/H5Imodule.h b/src/H5Imodule.h index a2174d7..d77591d 100644 --- a/src/H5Imodule.h +++ b/src/H5Imodule.h @@ -30,8 +30,85 @@ #define H5_MY_PKG_INIT NO /**\defgroup H5I H5I - * \brief Identifier Interface - * \todo Describe concisely what the functions in this module are about. + * + * Use the functions in this module to manage identifiers defined by the HDF5 + * library. See \ref H5IUD for user-defined identifiers and identifier + * types. + * + * HDF5 identifiers are usually created as a side-effect of creating HDF5 + * entities such as groups, datasets, attributes, or property lists. + * + * Identifiers defined by the HDF5 library can be used to retrieve information + * such as path names and reference counts, and their validity can be checked. + * + * Identifiers can be updated by manipulating their reference counts. + * + * Unused identifiers should be reclaimed by closing the associated item, e.g., + * HDF5 object, or decrementing the reference count to 0. + * + * \note Identifiers (of type \ref hid_t) are run-time auxiliaries and + * not persisted in the file. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5I_examples.c create + * </td> + * <td> + * \snippet{lineno} H5I_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5I_examples.c update + * </td> + * <td> + * \snippet{lineno} H5I_examples.c delete + * </td> + * </tr> + * </table> + * + * \defgroup H5IUD User-defined ID Types + * \ingroup H5I + * + * The \ref H5I module contains functions to define new identifier types. + * For convenience, handles of type \ref hid_t can then be associated with the + * new identifier types and user objects. + * + * New identifier types can be created by registering a new identifier type + * with the HDF5 library. Once a new identifier type has bee registered, + * it can be used to generate identifiers for user objects. + * + * User-defined identifier types can be searched and iterated. + * + * Like library-defined identifiers, user-defined identifiers \Emph{and} + * identifier types are reference counted, and the reference counts can be + * manipulated accordingly. + * + * User-defined identifiers no longer in use should be deleted or reclaimed, + * and identifier types should be destroyed if they are no longer required. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5I_examples.c create_ud + * </td> + * <td> + * \snippet{lineno} H5I_examples.c read_ud + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5I_examples.c update_ud + * </td> + * <td> + * \snippet{lineno} H5I_examples.c delete_ud + * </td> + * </tr> + * </table> + * */ #endif /* H5Imodule_H */ |