|
- Freeing Memory Allocated by the HDF5 Library
+ @ref freeing_memory
|
Describes how inconsistent memory management can cause heap corruption or resource leaks and possible solutions.
diff --git a/doxygen/dox/UsingIdentifiers.dox b/doxygen/dox/UsingIdentifiers.dox
new file mode 100644
index 00000000000..7fe1923990c
--- /dev/null
+++ b/doxygen/dox/UsingIdentifiers.dox
@@ -0,0 +1,97 @@
+/** \page UsingIdentifiers Using Identifiers
+ *
+ * \section sec_using_identifiers Using Identifiers
+ *
+ * The purpose of this topic is to describe how identifiers behave and how they should be treated by application programs.
+ *
+ * When an application program uses the HDF5 library to create or open an item, a unique identifier is
+ * returned. The items that return a unique identifier when they are created or opened include the following:
+ * \li dataset
+ * \li group
+ * \li datatype
+ * \li dataspace
+ * \li file
+ * \li attribute
+ * \li property list
+ * \li referenced object
+ * \li error stack
+ * \li error message
+ *
+ * An application may open one of the items listed above more than once at the same time. For example, an
+ * application might open a group twice, receiving two identifiers. Information from one dataset in the
+ * group could be handled through one identifier, and the information from another dataset in the group
+ * could be handled by a different identifier.
+ *
+ * An application program should track every identifier it receives as a result of creating or opening one of
+ * the items listed above. In order for an application to close properly, it must release every identifier it
+ * has opened. If an application opened a group twice for example, it would need to issue two #H5Gclose
+ * commands, one for each identifier. Not releasing identifiers causes resource leaks. Until an identifier
+ * is released, the item associated with the identifier is still open.
+ *
+ * The library considers a file open until all of the identifiers associated with the file and with the file’s
+ * various items have been released. The identifiers associated with these open items must be released separately.
+ * This means that an application can close a file and still work with one or more portions of the file. Suppose
+ * an application opened a file, a group within the file, and two datasets within the group. If the application
+ * closed the file with #H5Fclose, then the file would be considered closed to the application, but the group
+ * and two datasets would still be open.
+ *
+ * There are several exceptions to the above file closing rule. One is when the #H5close function is used
+ * instead of #H5Fclose. #H5close causes a general shut down of the library: all data is written to disk,
+ * all identifiers are closed, and all memory used by the library is cleaned up. Another exception occurs on
+ * parallel processing systems. Suppose on a parallel system an application has opened a file, a group in the
+ * file, and two datasets in the group. If the application uses the #H5Fclose function to close the file, the
+ * call will fail with an error. The open group and datasets must be closed before the file can be closed.
+ * A third exception is when the file access property list includes the property #H5F_CLOSE_STRONG. This
+ * property causes the closing of all of the file’s open items when the file is closed with #H5Fclose. For
+ * more information about #H5close, #H5Fclose, and #H5Pset_fclose_degree, see the \ref RM.
+ *
+ * The reference manual entries for functions that return identifiers describe what might be returned as
+ * follows:
+ * \b Returns:
+ * Returns an identifier if successful; otherwise returns a negative value.
+ *
+ * In other words, a successful operation will return a non-negative identifier which will never be 0
+ * (zero) and will always be a positive value.
+ *
+ * \subsection subsec_using_identifiers_func Functions that Return Identifiers
+ *
+ * Some of the functions that return identifiers are listed below.
+ *
+ * \li #H5Acreate
+ * \li #H5Acreate_by_name
+ * \li #H5Aget_type
+ * \li #H5Aopen
+ * \li #H5Aopen_by_idx
+ * \li #H5Aopen_by_name
+ * \li #H5Dcreate
+ * \li #H5Dcreate_anon
+ * \li #H5Dget_access_plist
+ * \li #H5Dget_create_plist
+ * \li #H5Dget_space
+ * \li #H5Dget_type
+ * \li #H5Dopen
+ * \li #H5Ecreate_msg
+ * \li #H5Ecreate_stack
+ * \li #H5Fcreate
+ * \li #H5Fopen
+ * \li #H5Freopen
+ * \li #H5Gcreate
+ * \li #H5Gcreate_anon
+ * \li #H5Gopen
+ * \li #H5Oopen
+ * \li #H5Oopen_by_addr
+ * \li #H5Oopen_by_idx
+ * \li #H5Pcreate
+ * \li #H5Pget_virtual_srcspace
+ * \li #H5Pget_virtual_vspace
+ * \li #H5Rdereference
+ * \li #H5Rget_region
+ * \li #H5Screate
+ * \li #H5Screate_simple
+ * \li #H5Tcopy
+ * \li #H5Tcreate
+ * \li #H5Tdecode
+ * \li #H5Tget_member_type
+ * \li #H5Tget_super
+ * \li #H5Topen
+*/
diff --git a/doxygen/dox/branches-explained.dox b/doxygen/dox/branches-explained.dox
new file mode 100644
index 00000000000..46f9c00b70b
--- /dev/null
+++ b/doxygen/dox/branches-explained.dox
@@ -0,0 +1,63 @@
+/** \page BRANCHEXPL HDF5 Git Branching Model Explained
+
+This document describes current HDF5 branches.
+
+Branches are tested nightly and testing results are available at
+https://my.cdash.org/index.php?project=HDF5.
+Commits that break daily testing should be fixed by 3:00 pm Central time or reverted.
+We encourage code contributors to check the status of their commits. If you have any questions,
+please contact help@hdfgroup.org.
+
+\section sec_branchexpl_develop develop branch
+Develop is the main branch whose source code always reflects a state with the latest delivered
+development changes for the next major release of HDF5.
+This is also considered the integration branch, as \b all new features are integrated into this
+branch from respective feature branches. Although
+develop is considered an integration branch, it is not an unstable branch. All code merged to
+develop is expected to pass all GitHub actions and daily tests.
+
+\section sec_branchexpl_maintenace Maintenance branches
+Each currently supported release line of HDF5 (e.g. 1.8.x, 1.10.x, 1.12.x, 1.14.x) has an associated
+branch with the name hdf5_1_10, etc..
+Maintenance branches are similar to the develop branch, except the source code in a maintenance
+branch always reflects a state
+with the latest delivered development changes for the next \b maintenance release of that particular
+supported release-line of HDF5.
+\b Some new features will be integrated into a release maintenance branch, depending on whether or
+not those features can be
+introduced in minor releases. Maintenance branches are removed when a release-line is retired from
+support.
+
+\section sec_branchexpl_release Release branches
+Release branches are used to prepare a new production release. They are primarily used to allow for
+last minute dotting of i's and crossing of t's
+(things like setting the release version, finalizing release notes, and generating Autotools files)
+and do not include new development.
+They are created from the maintenance branch at the time of the maintenance release and have
+names like hdf5_1_10_N, where N is the minor release number. Once the release is done it is
+tagged, with a slightly different format: hdf5-1_10_N.
+Release branches are deleted after the tag has been created. If we have to create a patch version
+of a release (which is rare), we create a branch off of the tag.
+
+\section sec_branchexpl_feature feature/\*
+Feature branches are temporary branches used to develop new features in HDF5.
+Feature branches branch off of develop and exist as long as the feature is under development.
+When the feature is complete, the branch is merged back into develop, as well as into any support
+branches in which the change will be included, and then the feature branch is removed.
+
+Ideally, all feature branches should contain a BRANCH.md file in the root directory that explains
+the purpose of the branch, contact information for the person responsible, and, if possible, some
+clues about the branch's life cycle (so we have an idea about when it can be deleted, merged, or
+declared inactive).
+
+Minor bug fixes and refactoring work usually takes place on personal forks, not feature branches.
+
+\section sec_branchexpl_inactive inactive/\*
+These branches are for experimental features that were developed in the past, have not been merged
+to develop, and are not under active development. The exception to this is that some feature branches
+are labeled inactive and preserved for a short time after merging to develop. Integration branches
+are usually not kept in sync with the develop branch.
+
+As for feature branches, inactive branches should have a BRANCH.md file as described above.
+
+*/
diff --git a/doc/cmake-vols-fetchcontent.md b/doxygen/dox/cmake-vols-fetchcontent.dox
similarity index 59%
rename from doc/cmake-vols-fetchcontent.md
rename to doxygen/dox/cmake-vols-fetchcontent.dox
index f7b395dec7b..2d1d9420469 100644
--- a/doc/cmake-vols-fetchcontent.md
+++ b/doxygen/dox/cmake-vols-fetchcontent.dox
@@ -1,70 +1,64 @@
-# Building and testing HDF5 VOL connectors with CMake FetchContent
+/** \page CMakeVols HDF5 Building and testing HDF5 VOL connectors with CMake FetchContent
+\section sec_cmakevols_intro Introduction
This document details the process of using CMake options to build and test
an HDF5 VOL connector alongside the HDF5 library when building HDF5 from
source. There are several benefits that this may provide, but among them
are the following:
-
- * A VOL connector built this way can be tested at the same time that
+\li A VOL connector built this way can be tested at the same time that
HDF5 is, which eliminates the need to have a multi-step build process
where one builds HDF5, uses it to build the VOL connector and then
uses the external [HDF5 VOL tests](https://github.com/hdfGroup/vol-tests)
repository to test their connector.
- * Building VOL connectors in this manner will usually install the built
+\li Building VOL connectors in this manner will usually install the built
connector library alongside the HDF5 library, allowing future opportunities
- for HDF5 to set a default plugin path such that the HDF5_PLUGIN_PATH
+ for HDF5 to set a default plugin path such that the #HDF5_PLUGIN_PATH
environment variable doesn't need to be set.
-## Building
-
+\section sec_cmakevols_build Building
To enable building of an HDF5 VOL connector using HDF5's CMake functionality,
a CMake variable must first be set:
-
- HDF5_VOL_ALLOW_EXTERNAL (Default: "NO")
+\li HDF5_VOL_ALLOW_EXTERNAL (Default: "NO")
This variable is a string that specifies the manner in which the source code for
an external VOL connector will be retrieved. This variable must be set
- to "GIT" for building external VOL connectors from a Github repository, or
- set to "LOCAL_DIR" to build from a local source directory.
-
+ to GIT for building external VOL connectors from a Github repository, or
+ set to LOCAL_DIR to build from a local source directory.
-### Building
-
-If the `HDF5_VOL_ALLOW_EXTERNAL` option is set to "GIT", the CMake cache will be populated with a predefined
-(currently 10) amount of new variables, named:
-
- HDF5_VOL_URL01
- HDF5_VOL_URL02
- HDF5_VOL_URL03
- ...
+\subsection subsec_cmakevols_build_git Building From GIT
+If the HDF5_VOL_ALLOW_EXTERNAL option is set to GIT, the CMake cache
+will be populated with a predefined (currently 10) amount of new variables, named:
+\li HDF5_VOL_URL01
+\li HDF5_VOL_URL02
+\li HDF5_VOL_URL03
+\li ...
For each of these variables, a URL that points to an HDF5 VOL connector Git
repository can be specified. These URLs should currently be HTTPS URLs. For
example, to specify the HDF5 Asynchronous I/O VOL Connector developed by the
-ECP team, one can provide the following option to `cmake`:
-
- -DHDF5_VOL_URL01=https://github.com/hpc-io/vol-async.git
+ECP team, one can provide the following option to CMake:
+\li -DHDF5_VOL_URL01=https://github.com/hpc-io/vol-async.git
For each URL specified, HDF5's CMake code will attempt to use CMake's
[FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html)
functionality to retrieve the source code for a VOL connector pointed to by
that URL and will try to build that VOL connector as part of the HDF5 library
-build process.
+build process.
-If `HDF5_VOL_ALLOW_EXTERNAL` is instead set to "LOCAL_DIR", then the CMake cache
-will instead be populated with the variables:
+\subsection subsec_cmakevols_build_local Building From Local Folder
+If HDF5_VOL_ALLOW_EXTERNAL is instead set to LOCAL_DIR,
+then the CMake cache will instead be populated with the variables:
- HDF5_VOL_PATH01
- HDF5_VOL_PATH02
- HDF5_VOL_PATH03
- ...
+\li HDF5_VOL_PATH01
+\li HDF5_VOL_PATH02
+\li HDF5_VOL_PATH03
+\li ...
-For each of these variables, an absolute path that points to a local
+For each of these variables, an absolute path that points to a local
directory containing source code for an HDF5 VOL connector
-can be specified. For example, to specify a local clone of the
-REST VOL connector stored under one's home directory, one can provide
-the following option to `cmake`:
-
- -DHDF5_VOL_PATH01=/home/vol-rest
+can be specified. For example, to specify a local clone of the
+REST VOL connector stored under one's home directory, one can provide
+the following option to CMake:
+\li -DHDF5_VOL_PATH01=/home/vol-rest
Regardless of the method used to obtain the VOL source code,
the VOL connector must be able to be built by CMake and currently
@@ -81,23 +75,21 @@ If the source was retrieved from a URL, then the name is generated
by stripping off the last part of the Git repository URL given for the connector,
removing the ".git" suffix and any whitespace and then upper-casing the result.
For example, the name of the VOL connector located at the URL
-https://github.com/hpc-io/vol-async.git would become "VOL-ASYNC". If the source was
-retrieved from a local directory, then the source directory's name is trimmed of whitespace,
-upper-cased, and has any trailing slashes removed.
+https://github.com/hpc-io/vol-async.git would become VOL-ASYNC.
+If the source was retrieved from a local directory, then the source directory's name is
+trimmed of whitespace, upper-cased, and has any trailing slashes removed.
After the VOL's internal name is generated, the following new variables get created:
-
- HDF5_VOL__NAME (Default: "")
+\li HDF5_VOL__NAME (Default: "")
This variable specifies the string that should be used when setting the
- HDF5_VOL_CONNECTOR environment variable for testing the VOL connector
- with the CMake-internal name ''. The value for this variable
+ #HDF5_VOL_CONNECTOR environment variable for testing the VOL connector
+ with the CMake-internal name \. The value for this variable
can be determined according to the canonical name given to the connector
by the connector's author(s), as well as any extra info that needs to be
passed to the connector for its configuration (see example below). This
variable must be set in order for the VOL connector to be testable with
HDF5's tests.
-
- HDF5_VOL__CMAKE_PACKAGE_NAME (Default: ">")
+\li HDF5_VOL__CMAKE_PACKAGE_NAME (Default: "\\>")
This variable specifies the exact name that would be passed to CMake
find_package(...) calls for the VOL connector in question. It is used as
the dependency name when making CMake FetchContent calls to try to ensure
@@ -105,43 +97,40 @@ After the VOL's internal name is generated, the following new variables get crea
can make find_package(...) calls for this VOL connector at configure time.
By default, this variable is set to a lowercased version of the internal
name generated for the VOL connector (described above).
-
- HDF5_VOL__TEST_PARALLEL (Default: OFF)
+\li HDF5_VOL__TEST_PARALLEL (Default: OFF)
This variable determines whether the VOL connector with the CMake-internal
- name '' should be tested against HDF5's parallel tests.
+ name \ should be tested against HDF5's parallel tests.
If the source was retrieved from a Git URL, then the following variable will additionally be created:
-
- HDF5_VOL__BRANCH (Default: "main")
+\li HDF5_VOL__BRANCH (Default: "main")
This variable specifies the git branch name or tag to use when fetching
the source code for the VOL connector with the CMake-internal name
- ''.
+ \.
As an example, this would create the following variables for the
previously-mentioned VOL connector if it is retrieved from a URL:
+\li HDF5_VOL_VOL-ASYNC_NAME ""
+\li HDF5_VOL_VOL-ASYNC_CMAKE_PACKAGE_NAME "vol-async"
+\li HDF5_VOL_VOL-ASYNC_BRANCH "main"
+\li HDF5_VOL_VOL-ASYNC_TEST_PARALLEL OFF
- HDF5_VOL_VOL-ASYNC_NAME ""
- HDF5_VOL_VOL-ASYNC_CMAKE_PACKAGE_NAME "vol-async"
- HDF5_VOL_VOL-ASYNC_BRANCH "main"
- HDF5_VOL_VOL-ASYNC_TEST_PARALLEL OFF
-
-**NOTE**
+NOTE
If a VOL connector requires extra information to be passed in its
-HDF5_VOL__NAME variable and that information contains any semicolons,
+HDF5_VOL__NAME variable and that information contains any semicolons,
those semicolons should be escaped with a single backslash so that CMake
-doesn't parse the string as a list. If `cmake` is run from a shell, extra care
+doesn't parse the string as a list. If CMake is run from a shell, extra care
may need to be taken when escaping the semicolons depending on how the
shell interprets backslashes.
-### Example - Build and test HDF5 Asynchronous I/O VOL connector from GIT
-
+\subsection subsec_cmakevols_build_ex Example - Build and test HDF5 Asynchronous I/O VOL connector from GIT
Assuming that the HDF5 source code has been checked out and a build directory
-has been created, running the following cmake command from that build directory
+has been created, running the following CMake command from that build directory
will retrieve, build and test the HDF5 Asynchronous I/O VOL connector while
-building HDF5. Note that `[hdf5 options]` represents other build options that
-would typically be passed when building HDF5, such as `CMAKE_INSTALL_PREFIX`,
-`HDF5_BUILD_CPP_LIB`, etc.
+building HDF5. Note that [hdf5 options] represents other build options that
+would typically be passed when building HDF5, such as CMAKE_INSTALL_PREFIX,
+HDF5_BUILD_CPP_LIB, etc.
+\code
cmake [hdf5 options]
-DHDF5_ENABLE_THREADSAFE=ON
-DHDF5_ENABLE_PARALLEL=ON
@@ -153,78 +142,77 @@ would typically be passed when building HDF5, such as `CMAKE_INSTALL_PREFIX`,
-DHDF5_VOL_VOL-ASYNC_NAME="async under_vol=0\;under_info={}"
-DHDF5_VOL_VOL-ASYNC_TEST_PARALLEL=ON
..
+\endcode
Here, we are specifying that:
-
- * HDF5 should be built with thread-safety enabled (required by Async VOL connector)
- * HDF5 should be built with parallel enabled (required by Async VOL connector)
- * Allow unsupported HDF5 combinations (thread-safety and HL, which is on by default)
- * Enable the API tests so that they can be tested with the Async VOL connector
- * Build and use the HDF5 Asynchronous I/O VOL connector, located at
+\li HDF5 should be built with thread-safety enabled (required by Async VOL connector)
+\li HDF5 should be built with parallel enabled (required by Async VOL connector)
+\li Allow unsupported HDF5 combinations (thread-safety and HL, which is on by default)
+\li Enable the API tests so that they can be tested with the Async VOL connector
+\li Build and use the HDF5 Asynchronous I/O VOL connector, located at
https://github.com/hpc-io/vol-async.git
- * Clone the Asynchronous I/O VOL connector from the repository's 'develop' branch
- * When testing the Asynchronous I/O VOL connector, the `HDF5_VOL_CONNECTOR` environment
- variable should be set to "async under_vol=0\;under_info={}", which
- specifies that the VOL connector with the canonical name "async" should
- be loaded and it should be passed the string "under_vol=0;under_info={}"
+\li Clone the Asynchronous I/O VOL connector from the repository's develop branch
+\li When testing the Asynchronous I/O VOL connector, the #HDF5_VOL_CONNECTOR environment
+ variable should be set to "async under_vol=0\;under_info={}", which
+ specifies that the VOL connector with the canonical name async should
+ be loaded and it should be passed the string "under_vol=0;under_info={}"
for its configuration (note the backslash-escaping of semicolons in the string
provided)
- * The Asynchronous I/O VOL connector should be tested against HDF5's parallel API tests
+\li The Asynchronous I/O VOL connector should be tested against HDF5's parallel API tests
-Note that this also assumes that the Asynchronous I/O VOL connector's
+Note that this also assumes that the Asynchronous I\/O VOL connector's
[other dependencies](https://hdf5-vol-async.readthedocs.io/en/latest/gettingstarted.html#preparation)
are installed on the system in a way that CMake can find them. If that is not
the case, the locations for these dependencies may need to be provided to CMake
by passing extra options, such as:
-
+\code
-DABT_INCLUDE_DIR=/path/to/argobots/build/include
-DABT_LIBRARY=/path/to/argbots/build/lib/libabt.so
-
+\endcode
which would help CMake find an argobots installation in a non-standard location.
-## Testing
-
+\section sec_cmakevols_test Testing
To facilitate testing of HDF5 VOL connectors when building HDF5, tests from
the [HDF5 VOL tests](https://github.com/hdfGroup/vol-tests) repository were
integrated back into the library and the following new CMake options were
added to HDF5 builds for the 1.14.1 release:
-
- HDF5_TEST_API (Default: OFF)
+\li HDF5_TEST_API (Default: OFF)
This variable determines whether the HDF5 API tests will be built and tested.
-
- HDF5_TEST_API_INSTALL (Default: OFF)
+\li HDF5_TEST_API_INSTALL (Default: OFF)
This variable determines whether the HDF5 API test executables will be installed
on the system alongside the HDF5 library.
-
- HDF5_TEST_API_ENABLE_ASYNC (Default: OFF)
+\li HDF5_TEST_API_ENABLE_ASYNC (Default: OFF)
This variable determines whether the HDF5 Asynchronous I/O API tests will be
built and tested. These tests will only run if a VOL connector reports that
- it supports asynchronous I/O operations when queried via the H5Pget_vol_cap_flags
+ it supports asynchronous I/O operations when queried via the #H5Pget_vol_cap_flags
API routine.
-
- HDF5_TEST_API_ENABLE_DRIVER (Default: OFF)
+\li HDF5_TEST_API_ENABLE_DRIVER (Default: OFF)
This variable determines whether the HDF5 API test driver program will be
built and used for testing. This driver program is useful when a VOL connector
- uses a client/server model where the server program needs to be up and running
+ uses a client\/server model where the server program needs to be up and running
before the VOL connector can function. This option is currently not functional.
-When the `HDF5_TEST_API` option is set to ON, HDF5's CMake code builds and tests
+When the HDF5_TEST_API option is set to ON, HDF5's CMake code builds and tests
the new API tests using the native VOL connector. When one or more external VOL
connectors are built successfully with the process described in this document,
the CMake code will duplicate some of these API tests by adding separate
versions of the tests (for each VOL connector that was built) that set the
-`HDF5_VOL_CONNECTOR` environment variable to the value specified for the
-HDF5_VOL__NAME variable for each external VOL connector at build time.
-Running the `ctest` command will then run these new tests which load and run with
-each VOL connector that was built in turn. When run via the `ctest` command, the
+#HDF5_VOL_CONNECTOR environment variable to the value specified for the
+HDF5_VOL__NAME variable for each external VOL connector at build time.
+Running the ctest command will then run these new tests which load and run with
+each VOL connector that was built in turn. When run via the ctest command, the
new tests typically follow the naming scheme:
-
+\code
HDF5_VOL_-h5_api_test_
HDF5_VOL_-h5_api_test_parallel_
+\endcode
-**NOTE**
+\section sec_cmakevols_note NOTE
If dependencies of a built VOL connector are installed on the system in
-a non-standard location that would typically require one to set `LD_LIBRARY_PATH`
+a non-standard location that would typically require one to set LD_LIBRARY_PATH
or similar, one should ensure that those environment variables are set before
running tests. Otherwise, the tests that run with that connector will likely
fail due to being unable to load the necessary libraries for its dependencies.
+
+*/
+
diff --git a/doxygen/dox/code-conventions.dox b/doxygen/dox/code-conventions.dox
new file mode 100644
index 00000000000..54aa5155160
--- /dev/null
+++ b/doxygen/dox/code-conventions.dox
@@ -0,0 +1,58 @@
+/** \page CODECONV HDF5 Library Code Conventions
+
+This document describes some practices that are new, or newly
+documented, starting in 2020.
+
+\section sec_codeconv_func Function / Variable Attributes
+
+In H5private.h, the library provides platform-independent macros
+for qualifying function and variable definitions.
+
+\subsection subsec_codeconv_func_1 Functions that accept printf(3) and scanf(3) format strings
+
+Label functions that accept a printf(3)-compliant format string with
+H5_ATTR_FORMAT(printf,format_argno,variadic_argno), where
+the format string is the format_argnoth argument (counting from 1)
+and the variadic arguments start with the variadic_argnoth.
+
+Functions that accept a scanf(3)-compliant format string should
+be labeled H5_ATTR_FORMAT(scanf,format_argno,variadic_argno).
+
+\subsection subsec_codeconv_func_2 Functions that do never return
+
+The definition of a function that always causes the program to abort and hang
+should be labeled H5_ATTR_NORETURN to help the compiler see which flows of
+control are infeasible.
+
+\subsection subsec_codeconv_func_other Other attributes
+
+**TBD**
+
+\subsection subsec_codeconv_func_unused Unused variables and parameters
+
+Compilers will warn about unused parameters and variables—developers should pay
+attention to those warnings and make an effort to prevent them.
+
+Some function parameters and variables are unused in \b all configurations of
+the project. Ordinarily, such parameters and variables should be deleted.
+However, sometimes it is possible to foresee a parameter being used, or
+removing it would change an API, or a parameter has to be defined to conform a
+function to some function pointer type. In those cases, it's permissible to
+mark a symbol H5_ATTR_UNUSED.
+
+Other parameters and variables are unused in \b some configurations of the
+project, but not all. A symbol may fall into disuse in some configuration in
+the future—then the compiler should warn, and the symbol should not be
+defined—so developers should try to label a sometimes-unused symbol with an
+attribute that's specific to the configurations where the symbol is (or is not)
+expected to be used. The library provides the following attributes for that
+purpose:
+\li H5_ATTR_DEPRECATED_USED: used only if deprecated symbols \b are enabled
+\li H5_ATTR_NDEBUG_UNUSED: used only if NDEBUG is \b not \#defined
+\li H5_ATTR_DEBUG_API_USED: used if the debug API \b is enabled
+\li H5_ATTR_PARALLEL_UNUSED: used only if Parallel HDF5 is \b not configured
+\li H5_ATTR_PARALLEL_USED: used only if Parallel HDF5 \b is configured
+
+Some attributes may be phased in or phased out in the future.
+
+*/
diff --git a/doc/file-locking.md b/doxygen/dox/file-locking.dox
similarity index 57%
rename from doc/file-locking.md
rename to doxygen/dox/file-locking.dox
index 067f7ab3993..aacf2135b04 100644
--- a/doc/file-locking.md
+++ b/doxygen/dox/file-locking.dox
@@ -1,5 +1,6 @@
-# File Locking in HDF5
+/** \page FileLock HDF5 File Locking in HDF5
+\section sec_filelock_intro Introduction
This document describes the file locking scheme that was added to HDF5 in
version 1.10.0 and how you can work around it, if you choose to do so. I'll
try to keep it understandable for everyone, though diving into technical
@@ -7,8 +8,7 @@ details is unavoidable, given the complexity of the material. We're in the
process of converting the HDF5 user guide (UG) to Doxygen and this document
will eventually be rolled up into those files as we update things.
-**Parallel HDF5 Note**
-
+Parallel HDF5 Note
Everything written here is from the perspective of serial HDF5. When we say
that you can't access a file for write access from more than one process, we
mean "from more than one independent, serial process". Parallel HDF5 can
@@ -16,18 +16,15 @@ obviously write to a file from more than one process, but that involves
IPC and multiple processes working together, not independent processes with
no knowledge of each other, which is what the file locks are for.
-
-## Why file locks?
-
+\section sec_filelock_why Why file locks?
The short answer is: "To prevent you from corrupting your HDF5 files and/or
crashing your reader processes."
The long answer is more complicated.
An HDF5 file's state exists in two places when it is open for writing:
-
-1. The HDF5 file itself
-2. The HDF5 library's various caches
+\li The HDF5 file itself
+\li The HDF5 library's various caches
One of those caches is the metadata cache, which stores things like B-tree
nodes that we use to locate data in the file. Problems arise when parent
@@ -55,7 +52,7 @@ it wrong could result in corrupt files or crashed readers, we decided to add
a file locking scheme to help users get it right. Since this would also help
prevent harmful accesses when SWMR is not in use, we decided to switch the
file locking scheme on by default. This scheme has been carried forward into
-HDF5 1.12 and 1.13 (soon to be 1.14).
+HDF5 1.12 and 1.14 (soon to be 2.0).
Note that the current implementation of SWMR is only useful for appending to chunked
datasets. Creating file objects like groups and datasets is not supported
@@ -67,8 +64,7 @@ on parallel file systems, especially when file locks have been disabled, which
often causes lock calls to fail. As a result of this, we've added work-arounds
to disable the file locking scheme over the years.
-## The existing scheme
-
+\section sec_filelock_scheme The existing scheme
There are two parts to the file locking scheme. One is the file lock itself.
The second is a mark we make in the HDF5 file's superblock. The superblock
mark isn't really that important for understanding the file locking, but since
@@ -82,11 +78,10 @@ SWMR and prevent dangerous file access.
Here's how it all works:
1. The first thing we do is check if we're using file locks
-
- - We first check the file locking property in the file access property list
+ \li We first check the file locking property in the file access property list
(fapl). The default value of this property is set at configure time when
the library is built.
- - Next we check the value of the `HDF5_USE_FILE_LOCKING` environment variable,
+ \li Next we check the value of the `HDF5_USE_FILE_LOCKING` environment variable,
which was previously parsed at library startup. If this is set,
we use the value to override the property list setting.
@@ -97,16 +92,14 @@ Here's how it all works:
take place.
2. We also check for ignoring file locks when they are disabled on the file system.
-
- - The environment variable setting for this is checked at VFD initialization
+ \li The environment variable setting for this is checked at VFD initialization
time for all library VFDs.
- - We check the value in the fapl in the `open` callback. The default value for
+ \li We check the value in the fapl in the `open` callback. The default value for
this property was set at configure time when the library was built.
3. When we open a file, we lock it based on the file access flags:
-
- - If the `H5F_ACC_RDWR` flag is set, use an exclusive lock
- - Otherwise use a shared lock
+ \li If the `H5F_ACC_RDWR` flag is set, use an exclusive lock
+ \li Otherwise use a shared lock
If we are ignoring disabled file locks (see below), we will silently swallow
lock API call failure when locks are not implemented on the file system.
@@ -115,26 +108,23 @@ Here's how it all works:
file consistency flags in the file's superblock to indicate this.
**NOTE!**
-
- - The VFD has to have a lock callback for this to happen. It doesn't matter if
+ \li The VFD has to have a lock callback for this to happen. It doesn't matter if
the locking was disabled - the check is simply for the callback.
- - We mark the superblock in **ANY** write case - both SWMR and non-SWMR.
- - Only the latest version of the superblock is marked in this way. If you
+ \li We mark the superblock in **ANY** write case - both SWMR and non-SWMR.
+ \li Only the latest version of the superblock is marked in this way. If you
open up a file that wasn't created with the 1.10.0 or later file format,
it won't get the superblock mark, even if it's been opened for writing.
According to the file format document and H5Fpkg.h:
-
- - Bit 0 is set if the file is open for writing (`H5F_SUPER_WRITE_ACCESS`)
- - Bit 2 is set if the file is open for SWMR writing (`H5F_SUPER_SWMR_WRITE_ACCESS`)
+ \li Bit 0 is set if the file is open for writing (`H5F_SUPER_WRITE_ACCESS`)
+ \li Bit 2 is set if the file is open for SWMR writing (`H5F_SUPER_SWMR_WRITE_ACCESS`)
We check these superblock flags on file open and error out if they are
unsuitable.
-
- - If the file is already opened for non-SWMR writing, no other process can open
+ \li If the file is already opened for non-SWMR writing, no other process can open
it.
- - If the file is open for SWMR writing, only SWMR readers can open the file.
- - If you try to open a file for reading with `H5F_ACC_SWMR_READ` set and the
+ \li If the file is open for SWMR writing, only SWMR readers can open the file.
+ \li If you try to open a file for reading with `H5F_ACC_SWMR_READ` set and the
file does not have the SWMR writer bits set in the superblock, the open
call will fail.
@@ -148,196 +138,178 @@ Here's how it all works:
handle it when the file descriptors are closed since file locks don't
normally surivive closing the underlying file descriptor.
-**TL;DR**
-
When locks are available, HDF5 files will be exclusively locked while they are
in use. The exception to this are files that are opened for SWMR writing, which
are unlocked. Files that are open for any kind of writing get a "writing"
superblock mark that HDF5 1.10.0+ will respect and refuse to open outside of SWMR.
-## `H5Fstart_swmr_write()`
-
-This API call can be used to switch an open file to "SWMR writing" mode as
-if it had been opened with the `H5F_ACC_SWMR_WRITE` flag set. This is used
+\section sec_filelock_smrfunc H5Fstart_swmr_write
+This #H5Fstart_swmr_write API call can be used to switch an open file to "SWMR writing" mode as
+if it had been opened with the #H5F_ACC_SWMR_WRITE flag set. This is used
when code needs to perform SWMR-forbidden operations like creating groups
and datasets before appending data to datasets using SWMR.
Most of the work of this API call involves flushing out the library caches
in preparation for SWMR access, but there are a few locking operations that
take place under the hood:
-
-- The file's superblock is marked as in the SWMR writer case, above.
-- For a brief period of time in the call, we convert the exclusive lock to
- a shared lock. It's unclear why this was done and we'll look into removing
- this.
-- At the end of the call, the lock is removed, as in the SWMR write open
- case described above.
-
-## Disabling the locks
-
+\li The file's superblock is marked as in the SWMR writer case, above.
+\li For a brief period of time in the call, we convert the exclusive lock to
+ a shared lock. It's unclear why this was done and we'll look into removing
+ this.
+\li At the end of the call, the lock is removed, as in the SWMR write open
+ case described above.
+
+\section sec_filelock_disable Disabling the locks
There are several ways to disable the locks, depending on which version of the
HDF5 library you are working with. This section will describe the file lock
disable schemes as they exist in late 2022. The current library versions at
-this time are 1.10.9, 1.12.3, and 1.13.2. File locks are not present in HDF5
+this time were 1.10.9, 1.12.3, and 1.13.2. File locks are not present in HDF5
1.8. The lock feature matrix later in this document will describe the
limitations of earlier versions.
-### Configure option
-
+\subsection subsec_filelock_disable_config Configure option
You can set the file locking defaults at configure time. This sets the defaults
for the associated properties in the fapl. Users can override the configure
-defaults using `H5Pset_file_locking()` or the `HDF5_USE_FILE_LOCKING`
+defaults using #H5Pset_file_locking or the HDF5_USE_FILE_LOCKING
environment variable.
-- Autotools
-
- `--enable-file-locking=(yes|no|best-effort)` sets the file locking behavior.
- `on` and `off` should be self-explanatory. `best-effort` turns file locking
- on but ignores file locks when they are disabled (default: `best-effort`).
-
-- CMake
+Autotools
+\li --enable-file-locking=(yes | no | best-effort) sets the file locking behavior.
+ on and off should be self-explanatory. best-effort turns file locking
+ on but ignores file locks when they are disabled (default: best-effort).
- - set `IGNORE_DISABLED_FILE_LOCK` to `ON` to ignore file locks when they
- are disabled on the file system (default: `ON`).
- - set `HDF5_USE_FILE_LOCKING` to `OFF` to disable file locks (default: `ON`)
+CMake
+\li set IGNORE_DISABLED_FILE_LOCK to ON to ignore file locks when they
+\li are disabled on the file system (default: ON).
+\li set HDF5_USE_FILE_LOCKING to OFF to disable file locks (default: ON)
-### `H5Pset_file_locking()`
-
-This API call can be used to override the configure defaults. It takes
-`hbool_t` parameters for both the file locking and "ignore file locks when
+\section sec_filelock_funcset H5Pset_file_locking
+This #H5Pset_file_locking API call can be used to override the configure defaults. It takes
+#hbool_t parameters for both the file locking and "ignore file locks when
disabled on the file system" parameters. The values set here can be
overridden by the file locking environment variable.
-There is a corresponding `H5Pget_file_locking()` call that can be used to check
-the currently set values of both properties in the fapl. **NOTE** that this
-call just checks the property list values. It does **NOT** check the
+There is a corresponding #H5Pget_file_locking call that can be used to check
+the currently set values of both properties in the fapl. NOTE that this
+call just checks the property list values. It does NOT check the
environment variables!
-### Environment variables
-
-The `HDF5_USE_FILE_LOCKING` environment variable overrides all other file
+\section sec_filelock_env Environment variables
+The HDF5_USE_FILE_LOCKING environment variable overrides all other file
locking settings.
HDF5 1.10.0
-- No file locking environment variable
+\li No file locking environment variable
HDF5 1.10.1 - 1.10.6, 1.12.0:
-- `FALSE` turns file locking off
-- Anything else turns file locking on
-- Neither of these values ignores disabled file locks
-- Environment variable parsed at file create/open time
-
-HDF5 1.10.7+, 1.12.1+, 1.13.x:
-- `FALSE` or `0` disables file locking
-- `TRUE` or `1` enables file locking
-- `BEST_EFFORT` enables file locking and ignores disabled file locks
-- Anything else gives you the defaults
-- Environment variable parsed at library startup
-
-### Lock disable scheme interactions
-
+\li FALSE turns file locking off
+\li Anything else turns file locking on
+\li Neither of these values ignores disabled file locks
+\li Environment variable parsed at file create/open time
+
+HDF5 1.10.7+, 1.12.1+, 1.14.x:
+\li FALSE or 0 disables file locking
+\li TRUE or 1 enables file locking
+\li BEST_EFFORT enables file locking and ignores disabled file locks
+\li Anything else gives you the defaults
+\li Environment variable parsed at library startup
+
+\section sec_filelock_lockdisable Lock disable scheme interactions
As mentioned above and reiterated here:
-- Configure-time settings set fapl defaults
-- `H5Pset_file_locking()` overrides configure-time defaults
-- The environment variable setting overrides all
+\li Configure-time settings set fapl defaults
+\li #H5Pset_file_locking overrides configure-time defaults
+\li The environment variable setting overrides all
If you want to check that file locking is on, you'll need to check the fapl
setting AND check the environment variable, which can override the fapl.
-**!!! WARNING !!!**
-
+\subsection subsec_filelock_lockdisable_warn !!! WARNING !!!
Disabling the file locks is at your own risk. If more than one writer process
modifies an HDF5 file at the same time, the file could be corrupted. If a
reader process reads a file that is being modified by a writer, the reader
process might attempt to read garbage and encounter errors or even crash.
In the case of:
-
-- A single process accessing a file with write access
-- Any number of processes accessing a file read-only
+\li A single process accessing a file with write access
+\li Any number of processes accessing a file read-only
You can safely disable the file locking scheme.
If you are trying to set up SWMR without the benefit of the file locks, you'll
just need to be extra careful that you hold to rules for SWMR access.
-## Feature Matrix
-
+\section sec_filelock_feat Feature Matrix
The following table indicates which versions of the library support which file
lock features. 1.13.0 and 1.13.1 are experimental releases (basically glorified
release candidates) so they are not included here.
-**Locks**
-
-- P = POSIX locks only, Windows was a no-op that always succeeded
-- WP = POSIX and Windows locks
-- (-) = POSIX no-op lock fails
-- (+) = POSIX no-op lock passes
-
-**Configure Option and Environment Variable**
-
-- on/off = sets file locks on/off
-- try = can also set "best effort", where locks are on but ignored if disabled
-
-|Version|Has locks|Configure option|`H5Pset_file_locking()`|`HDF5_USE_FILE_LOCKING`|
-|-------|---------|----------------|-----------------------|-----------------------|
-|1.8.x|No|-|-|-|
-|1.10.0|P(-)|-|-|-|
-|1.10.1|P(-)|-|-|on/off|
-|1.10.2|P(-)|-|-|on/off|
-|1.10.3|P(-)|-|-|on/off|
-|1.10.4|P(-)|-|-|on/off|
-|1.10.5|P(-)|-|-|on/off|
-|1.10.6|P(-)|-|-|on/off|
-|1.10.7|P(+)|try|Y|try|
-|1.10.8|WP(+)|try|Y|try|
-|1.10.9|WP(+)|try|Y|try|
-|1.12.0|P(-)|-|-|on/off|
-|1.12.1|WP(+)|try|Y|try|
-|1.12.2|WP(+)|try|Y|try|
-|1.13.2|WP(+)|try|Y|try|
-
-
-## Appendix: File lock implementation
-
-The file lock system is implemented with `flock(2)` as the archetype since it
+\subsection subsec_filelock_feat_locks Locks
+\li P = POSIX locks only, Windows was a no-op that always succeeded
+\li WP = POSIX and Windows locks
+\li (-) = POSIX no-op lock fails
+\li (+) = POSIX no-op lock passes
+
+\subsection subsec_filelock_feat_var Configure Option and Environment Variable
+\li on/off = sets file locks on/off
+\li try = can also set "best effort", where locks are on but ignored if disabled
+
+
+| Version | Has locks | Configure option | #H5Pset_file_locking | HDF5_USE_FILE_LOCKING |
|---|
+| 1.8.x | No | - | - | - |
+| 1.10.0 | P(-) | - | - | - |
+| 1.10.1 | P(-) | - | - | on/off |
+| 1.10.2 | P(-) | - | - | on/off |
+| 1.10.3 | P(-) | - | - | on/off |
+| 1.10.4 | P(-) | - | - | on/off |
+| 1.10.5 | P(-) | - | - | on/off |
+| 1.10.6 | P(-) | - | - | on/off |
+| 1.10.7 | P(+) | try | Y | try |
+| 1.10.8 | WP(+) | try | Y | try |
+| 1.10.9 | WP(+) | try | Y | try |
+| 1.12.0 | P(-) | - | - | on/off |
+| 1.12.1 | WP(+) | try | Y | try |
+| 1.12.2 | WP(+) | try | Y | try |
+| 1.13.2 | WP(+) | try | Y | try |
+
+
+\section sec_filelock_appd Appendix: File lock implementation
+The file lock system is implemented with flock(2) as the archetype since it
has simple semantics and we don't need range locking. Locks are advisory on many
systems, but this shouldn't be a problem for most users since the HDF5 library
always respects them. If you have a program that parses or modifies HDF5 files
independently of the HDF5 library, you'll want to be mindful of any potential
for concurrent access across processes.
-On Unix systems, we call `flock()` directly when it's available and pass
-`LOCK_SH` (shared lock), `LOCK_EX` (exclusive lock), and `LOCK_UN` (unlock) as
+On Unix systems, we call flock() directly when it's available and pass
+LOCK_SH (shared lock), LOCK_EX (exclusive lock), and LOCK_UN (unlock) as
described in the algorithm section. All locks are non-blocking, so we set the
-`LOCK_NB` flag. Sadly, `flock(2)` is not POSIX and it doesn't lock files over
+LOCK_NB flag. Sadly, flock(2) is not POSIX and it doesn't lock files over
NFS. We didn't consider a lack of NFS support a problem since SWMR isn't
supported on networked file systems like NFS (write order preservation isn't
-guaranteed) and `flock(2)` usually doesn't fail when you attempt to lock NFS
+guaranteed) and flock(2) usually doesn't fail when you attempt to lock NFS
files.
-On Unix systems without `flock(2)`, we implement a scheme based on `fcntl(2)`
-(`Pflock()` in `H5system.c`). On these systems we use `F_SETLK` (non-blocking)
-as the operation and set `l_type` in `struct flock` to be:
-
-- `F_UNLOCK` for `LOCK_UN`
-- `F_WRLOCK` for `LOCK_EX`
-- `F_RDLOCK` for `LOCK_SH`
+On Unix systems without flock(2), we implement a scheme based on fcntl(2)
+(Pflock() in H5system.c). On these systems we use F_SETLK (non-blocking)
+as the operation and set l_type in struct flock to be:
+\li F_UNLOCK for LOCK_UNc
+\li F_WRLOCK for LOCK_EXc
+\li F_RDLOCK for LOCK_SHc
-We set the range to be the entire file. Most Unix-like systems have `flock()`
+We set the range to be the entire file. Most Unix-like systems have flock()
these days, so this system probably isn't very well tested.
-We don't use `fcntl`-based open file locks or mandatory locking anywhere. The
+We don't use fcntl-based open file locks or mandatory locking anywhere. The
former scheme is non-POSIX and the latter is deprecated.
-On Windows, we use `LockFileEx()` and `UnlockFileEx()` to lock the entire file
-(`Wflock()` in `H5system.c`). We set `LOCKFILE_FAIL_IMMEDIATELY` to get
-non-blocking locks and set `LOCKFILE_EXCLUSIVE_LOCK` when we want an exclusive
+On Windows, we use LockFileEx() and UnlockFileEx() to lock the entire file
+(Wflock() in H5system.c). We set LOCKFILE_FAIL_IMMEDIATELY to get
+non-blocking locks and set LOCKFILE_EXCLUSIVE_LOCK when we want an exclusive
lock. SWMR isn't well-tested on Windows, so this scheme hasn't been as
-thoroughly vetted as the `flock`-based scheme.
+thoroughly vetted as the flock-based scheme.
-On non-Windows systems where neither `flock(2)` nor `fcntl(2)` is available,
-we substitute a no-op stub that always succeeds (`Nflock()` in `H5system.c`).
+On non-Windows systems where neither flock(2) nor fcntl(2) is available,
+we substitute a no-op stub that always succeeds (Nflock() in H5system.c).
In the past, the stub always failed (see the matrix for when we made the switch).
We currently know of no non-Windows systems where neither call is available
so this scheme is not well-tested.
@@ -347,15 +319,15 @@ locking, is that all of these schemes have subtly different semantics. We're
using file locking in a fairly crude manner, though, and lock use has always
been optional, so we consider this a lower-order concern.
-Locks are implemented at the VFD level via `lock` and `unlock` callbacks. The
+Locks are implemented at the VFD level via lock and unlock callbacks. The
VFDs that implement file locks are: core (w/ backing store), direct, log, sec2,
-and stdio (`flock(2)` locks only). The family, multi, and splitter VFDs invoke
+and stdio (flock(2) locks only). The family, multi, and splitter VFDs invoke
the lock callback of their underlying sub-files. The onion and MPI-IO VFDs do NOT
use locks, even though they create normal, on-disk native HDF5 files. The
read-only S3 VFD and HDFS VFDs do not use file locking since they use
alternative storage schemes.
-Lock failures are detected by checking to see if `errno` is set to `ENOSYS`.
+Lock failures are detected by checking to see if errno is set to ENOSYS.
This is not particularly sophisticated and was implemented as a way of working
around disabled locks on popular parallel file systems.
@@ -363,4 +335,7 @@ One other thing to note here is that, in all of the locking schemes we use, the
file locks do not survive process termination, so you don't have to worry
about files being locked forever if a process exits abnormally. If a writer
crashed and the library didn't clear the superblock mark, you can remove it with
-the h5clear command-line tool, which is built with the library.
+the \ref sec_cltools_h5clear command-line tool, which is built with the library.
+
+*/
+
diff --git a/doxygen/dox/high_level/extension.dox b/doxygen/dox/high_level/extension.dox
index fc0da48ee83..456692ed868 100644
--- a/doxygen/dox/high_level/extension.dox
+++ b/doxygen/dox/high_level/extension.dox
@@ -7,16 +7,14 @@
* for working with region references, hyperslab selections, and bit-fields.
* These functions were created as part of a project supporting
* NPP/NPOESS Data Production and Exploitation (
- *
- * project,
- * software ).
+ * project,
+ * software).
* While they were written to facilitate access to NPP, NPOESS, and JPSS
* data in the HDF5 format, these functions may be useful to anyone working
* with region references, hyperslab selections, or bit-fields.
*
* Note that these functions are not part of the standard HDF5 distribution;
- * the
- * software
+ * the software
* must be separately downloaded and installed.
*
* A comprehensive guide to this library,
diff --git a/doxygen/dox/library-init-shutdown.dox b/doxygen/dox/library-init-shutdown.dox
new file mode 100644
index 00000000000..0c48ee49d53
--- /dev/null
+++ b/doxygen/dox/library-init-shutdown.dox
@@ -0,0 +1,55 @@
+/** \page InitShut HDF5 Library initialization and shutdown
+
+\section sec_initshut_app Application perspective
+
+\subsection subsec_initshut_app_implicit Implicit initialization and shutdown
+When a developer exports a new symbol as part of the HDF5 library,
+they should make sure that an application cannot enter the library in an
+uninitialized state through a new API function, or read an uninitialized
+value from a non-function HDF5 symbol.
+
+The HDF5 library initializes itself when an application either enters
+the library through an API function call such as #H5Fopen, or when
+an application evaluates an HDF5 symbol that represents either a
+property-list identifier such as #H5F_ACC_RDONLY or #H5F_ACC_RDWR,
+a property-list class identifier such as #H5P_FILE_ACCESS, a VFD
+identifier such as #H5FD_FAMILY or #H5FD_SEC2, or a type identifier
+such as #H5T_NATIVE_INT64.
+
+The library sets a flag when initialization occurs and as long as the
+flag is set, skips initialization.
+
+The library provides a couple of macros that initialize the library
+as necessary. The library is initialized as a side-effect of the
+FUNC_ENTER_API* macros used at the top of most API functions. HDF5
+library symbols other than functions are provided through \#defines
+that use #H5OPEN to introduce a library-initialization call (#H5open)
+at each site where a non-function symbol is used.
+
+Ordinarily the library registers an atexit(3) handler to shut itself
+down when the application exits.
+
+\subsection subsec_initshut_app_explicit Explicit initialization and shutdown
+An application may use an API call, #H5open, to explicitly initialize
+the library. #H5close explicitly shuts down the library.
+
+\section sec_initshut_int Library internals perspective
+No matter how library initialization begins, eventually the internal
+function H5_init_library will be called. H5_init_library is
+responsible for calling the initializers for every internal HDF5
+library module (aka "package") in the correct order so that no module is
+initialized before its prerequisite modules. A table in H5_init_library
+establishes the order of initialization. If a developer adds a
+module to the library that it is appropriate to initialize with the rest
+of the library, then they should insert its initializer into the right
+place in the table.
+
+H5_term_library drives library shutdown. Library shutdown is
+table-driven, too. If a developer adds a module that needs to release
+resources during library shutdown, then they should add a call at the
+right place to the shutdown table. Note that some entries in the shutdown
+table are marked as "barriers," and if a new module should only be
+shutdown strictly after the preceding modules, then it should be marked
+as a barrier. See the comments in H5_term_library for more information.
+
+*/
diff --git a/doc/parallel-compression.md b/doxygen/dox/parallel-compression.dox
similarity index 76%
rename from doc/parallel-compression.md
rename to doxygen/dox/parallel-compression.dox
index 523aa758fec..962b9907857 100644
--- a/doc/parallel-compression.md
+++ b/doxygen/dox/parallel-compression.dox
@@ -1,7 +1,6 @@
-# HDF5 Parallel Compression
-
-## Introduction
+/** \page ParCompr HDF5 Parallel Compression
+\section sec_parcompr_intro Introduction
When an HDF5 dataset is created, the application can specify
optional data filters to be applied to the dataset (as long as
the dataset uses a chunked data layout). These filters may
@@ -45,28 +44,28 @@ their modifications to the owning MPI rank.
The parallel compression feature is always enabled when HDF5
is built with parallel enabled, but the feature may be disabled
if the necessary MPI-3 routines are not available. Therefore,
-HDF5 conditionally defines the macro `H5_HAVE_PARALLEL_FILTERED_WRITES`
+HDF5 conditionally defines the macro H5_HAVE_PARALLEL_FILTERED_WRITES
which an application can check for to see if the feature is
available.
-## Examples
+\section sec_parcompr_ex Examples
Using the parallel compression feature is very similar to using
compression in serial HDF5, except that dataset writes **must**
be collective:
-```
+\code
hid_t dxpl_id = H5Pcreate(H5P_DATASET_XFER);
H5Pset_dxpl_mpio(dxpl_id, H5FD_MPIO_COLLECTIVE);
H5Dwrite(..., dxpl_id, ...);
-```
+\endcode
The following are two simple examples of using the parallel
compression feature:
-[ph5_filtered_writes.c][u1]
+ph5_filtered_writes.c
-[ph5_filtered_writes_no_sel.c][u2]
+ph5_filtered_writes_no_sel.c
The former contains simple examples of using the parallel
compression feature to write to compressed datasets, while the
@@ -76,10 +75,10 @@ Remember that the feature requires these writes to use collective
I/O, so the MPI ranks which have nothing to contribute must still
participate in the collective write call.
-## Multi-dataset I/O support
+\section sec_parcompr_multi Multi-dataset I/O support
The parallel compression feature is supported when using the
-multi-dataset I/O API routines ([H5Dwrite_multi][u3]/[H5Dread_multi][u4]), but the
+multi-dataset I/O API routines (#H5Dwrite_multi/#H5Dread_multi), but the
following should be kept in mind:
- Parallel writes to filtered datasets **must** still be collective,
@@ -97,17 +96,17 @@ following should be kept in mind:
datasets if desired, while still performing collective writes to
the filtered datasets.
-## Incremental file space allocation support
+\section sec_parcompr_incr Incremental file space allocation support
-HDF5's [file space allocation time][u5]
+HDF5's file space allocation time function. #H5Pset_alloc_time,
is a dataset creation property that can have significant effects
on application performance, especially if the application uses
parallel HDF5. In a serial HDF5 application, the default file space
-allocation time for chunked datasets is "incremental". This means
+allocation time for chunked datasets is incremental. This means
that allocation of space in the HDF5 file for data chunks is
deferred until data is first written to those chunks. In parallel
HDF5, the file space allocation time was previously always forced
-to "early", which allocates space in the file for all of a dataset's
+to early, which allocates space in the file for all of a dataset's
data chunks at creation time (or during the first open of a dataset
if it was created serially). This would ensure that all the necessary
file space was allocated so MPI ranks could perform independent I/O
@@ -118,7 +117,7 @@ While this strategy has worked in the past, it has some noticeable
drawbacks. For one, the larger the chunked dataset being created,
the more noticeable overhead there will be during dataset creation
as all of the data chunks are being allocated in the HDF5 file.
-Further, these data chunks will, by default, be [filled][u6]
+Further, these data chunks will, by default, be filled, using #H5Pset_fill_value,
with HDF5's default fill data value, leading to extraordinary
dataset creation overhead and resulting in pre-filling large
portions of a dataset that the application might have been planning
@@ -126,16 +125,16 @@ to overwrite anyway. Even worse, there will be more initial overhead
from compressing that fill data before writing it out, only to have
it read back in, unfiltered and modified the first time a chunk is
written to. In the past, it was typically suggested that parallel
-HDF5 applications should use [H5Pset_fill_time][u7]
-with a value of `H5D_FILL_TIME_NEVER` in order to disable writing of
+HDF5 applications should use #H5Pset_fill_time
+with a value of #H5D_FILL_TIME_NEVER in order to disable writing of
the fill value to dataset chunks, but this isn't ideal if the
application actually wishes to make use of fill values.
-With [improvements made][u8]
-to the parallel compression feature for the HDF5 1.13.1 release,
-"incremental" file space allocation is now the default for datasets
-created in parallel *only if they have filters applied to them*.
-"Early" file space allocation is still supported for these datasets
+With improvements made
+to the parallel compression feature for the HDF5 1.14.0 release,
+incremental file space allocation is now the default for datasets
+created in parallel only if they have filters applied to them.
+Early file space allocation is still supported for these datasets
if desired and is still forced for datasets created in parallel that
do *not* have filters applied to them. This change should significantly
reduce the overhead of creating filtered datasets in parallel HDF5
@@ -144,7 +143,7 @@ use a fill value for these datasets. It should also help significantly
reduce the size of the HDF5 file, as file space for the data chunks
is allocated as needed rather than all at once.
-## Performance Considerations
+\section sec_parcompr_perf Performance Considerations
Since getting good performance out of HDF5's parallel compression
feature involves several factors, the following is a list of
@@ -152,9 +151,9 @@ performance considerations (generally from most to least important)
and best practices to take into account when trying to get the
optimal performance out of the parallel compression feature.
-### Begin with a good chunking strategy
+\subsection subsec_parcompr_perf_begin Begin with a good chunking strategy
-[Starting with a good chunking strategy][u9]
+Starting with a good \ref hdf5_chunking strategy
will generally have the largest impact on overall application
performance. The different chunking parameters can be difficult
to fine-tune, but it is essential to start with a well-performing
@@ -166,11 +165,11 @@ chosen chunk size becomes a very important factor when compression
is involved, as data chunks have to be completely read and
re-written to perform partial writes to the chunk.
-[Improving I/O performance with HDF5 compressed datasets][u10]
+\ref improve_compressed_perf
is a useful reference for more information on getting good
performance when using a chunked dataset layout.
-### Avoid chunk sharing
+\subsection subsec_parcompr_perf_avoid Avoid chunk sharing
Since the parallel compression feature has to assign ownership
of data chunks to a single MPI rank in order to avoid the
@@ -185,7 +184,7 @@ application will get the best performance out of parallel compression
if it can avoid writing in a way that causes more than 1 MPI rank
to write to any given data chunk in a dataset.
-### Collective metadata operations
+\subsection subsec_parcompr_perf_coll Collective metadata operations
The parallel compression feature typically works with a significant
amount of metadata related to the management of the data chunks
@@ -203,7 +202,7 @@ performance and scalability and is generally always recommended
unless application performance shows negative benefits by doing
so.
-```
+\code
...
hid_t fapl_id = H5Pcreate(H5P_FILE_ACCESS);
H5Pset_fapl_mpio(fapl_id, MPI_COMM_WORLD, MPI_INFO_NULL);
@@ -211,23 +210,23 @@ H5Pset_all_coll_metadata_ops(fapl_id, 1);
H5Pset_coll_metadata_write(fapl_id, 1);
hid_t file_id = H5Fcreate("file.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl_id);
...
-```
+\endcode
-### Align chunks in the file
+\subsection subsec_parcompr_perf_align Align chunks in the file
The natural layout of an HDF5 file may cause dataset data
chunks to end up at addresses in the file that do not align
well with the underlying file system, possibly leading to
poor performance. As an example, Lustre performance is generally
good when writes are aligned with the chosen stripe size.
-The HDF5 application can use [H5Pset_alignment][u11]
+The HDF5 application can use #H5Pset_alignment
to have a bit more control over where objects in the HDF5
file end up. However, do note that setting the alignment
of objects generally wastes space in the file and has the
potential to dramatically increase its resulting size, so
caution should be used when choosing the alignment parameters.
-[H5Pset_alignment][u11]
+#H5Pset_alignment
has two parameters that control the alignment of objects in
the HDF5 file, the "threshold" value and the alignment
value. The threshold value specifies that any object greater
@@ -246,16 +245,16 @@ the Lustre stripe size), this should cause dataset data
chunks to be well-aligned and generally give good write
performance.
-```
+\code
hid_t fapl_id = H5Pcreate(H5P_FILE_ACCESS);
H5Pset_fapl_mpio(fapl_id, MPI_COMM_WORLD, MPI_INFO_NULL);
/* Assuming Lustre stripe size is 1MiB, align data chunks
in the file to address multiples of 1MiB. */
H5Pset_alignment(fapl_id, dataset_chunk_size, 1048576);
hid_t file_id = H5Fcreate("file.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl_id);
-```
+\endcode
-### File free space managers
+\subsection subsec_parcompr_perf_space File free space managers
As data chunks in a dataset get written to and compressed,
they can change in size and be relocated in the HDF5 file.
@@ -264,29 +263,29 @@ in a file, this can create significant amounts of free space
in the file over its lifetime and eventually cause performance
issues.
-An HDF5 application can use [H5Pset_file_space_strategy][u12]
-with a value of `H5F_FSPACE_STRATEGY_PAGE` to enable the paged
+An HDF5 application can use #H5Pset_file_space_strategy
+with a value of #H5F_FSPACE_STRATEGY_PAGE to enable the paged
aggregation feature, which can accumulate metadata and raw
data for dataset data chunks into well-aligned, configurably
-sized "pages" for better performance. However, note that using
+sized pages for better performance. However, note that using
the paged aggregation feature will cause any setting from
-[H5Pset_alignment][u11]
+#H5Pset_alignment
to be ignored. While an application should be able to get
-comparable performance effects by [setting the size of these pages][u13]
-to be equal to the value that would have been set for [H5Pset_alignment][u11],
+comparable performance effects by setting the size of these pages, using #H5Pset_file_space_page_size,
+to be equal to the value that would have been set for #H5Pset_alignment,
this may not necessarily be the case and should be studied.
-Note that [H5Pset_file_space_strategy][u12]
-has a `persist` parameter. This determines whether or not the
+Note that #H5Pset_file_space_strategy
+has a persist parameter. This determines whether or not the
file free space manager should include extra metadata in the
HDF5 file about free space sections in the file. If this
-parameter is `false`, any free space in the HDF5 file will
+parameter is false, any free space in the HDF5 file will
become unusable once the HDF5 file is closed. For parallel
-compression, it's generally recommended that `persist` be set
-to `true`, as this will keep better track of file free space
+compression, it's generally recommended that persist be set
+to true, as this will keep better track of file free space
for data chunks between accesses to the HDF5 file.
-```
+\code
hid_t fcpl_id = H5Pcreate(H5P_FILE_CREATE);
/* Use persistent free space manager with paged aggregation */
H5Pset_file_space_strategy(fcpl_id, H5F_FSPACE_STRATEGY_PAGE, 1, 1);
@@ -294,58 +293,43 @@ H5Pset_file_space_strategy(fcpl_id, H5F_FSPACE_STRATEGY_PAGE, 1, 1);
H5Pset_file_space_page_size(fcpl_id, 1048576);
...
hid_t file_id = H5Fcreate("file.h5", H5F_ACC_TRUNC, fcpl_id, fapl_id);
-```
+\endcode
-### Low-level collective vs. independent I/O
+\subsection subsec_parcompr_perf_low Low-level collective vs. independent I/O
While the parallel compression feature requires that the HDF5
application set and maintain collective I/O at the application
-interface level (via [H5Pset_dxpl_mpio][u14]),
+interface level (via #H5Pset_dxpl_mpio),
it does not require that the actual MPI I/O that occurs at
the lowest layers of HDF5 be collective; independent I/O may
perform better depending on the application I/O patterns and
parallel file system performance, among other factors. The
-application may use [H5Pset_dxpl_mpio_collective_opt][u15]
+application may use #H5Pset_dxpl_mpio_collective_opt
to control this setting and see which I/O method provides the
best performance.
-```
+\code
hid_t dxpl_id = H5Pcreate(H5P_DATASET_XFER);
H5Pset_dxpl_mpio(dxpl_id, H5FD_MPIO_COLLECTIVE);
H5Pset_dxpl_mpio_collective_opt(dxpl_id, H5FD_MPIO_INDIVIDUAL_IO); /* Try independent I/O */
H5Dwrite(..., dxpl_id, ...);
-```
+\endcode
-### Runtime HDF5 Library version
+\subsection subsec_parcompr_perf_libver Runtime HDF5 Library version
-An HDF5 application can use the [H5Pset_libver_bounds][u16]
+An HDF5 application can use the #H5Pset_libver_bounds
routine to set the upper and lower bounds on library versions
to use when creating HDF5 objects. For parallel compression
specifically, setting the library version to the latest available
version can allow access to better/more efficient chunk indexing
types and data encoding methods. For example:
-```
+\code
...
hid_t fapl_id = H5Pcreate(H5P_FILE_ACCESS);
H5Pset_libver_bounds(fapl_id, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST);
hid_t file_id = H5Fcreate("file.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl_id);
...
-```
-
-[u1]: https://github.com/HDFGroup/hdf5/blob/develop/HDF5Examples/C/H5PAR/ph5_filtered_writes.c
-[u2]: https://github.com/HDFGroup/hdf5/blob/develop/HDF5Examples/C/H5PAR/ph5_filtered_writes_no_sel.c
-[u3]: https://hdfgroup.github.io/hdf5/develop/group___h5_d.html#gaf6213bf3a876c1741810037ff2bb85d8
-[u4]: https://hdfgroup.github.io/hdf5/develop/group___h5_d.html#ga8eb1c838aff79a17de385d0707709915
-[u5]: https://hdfgroup.github.io/hdf5/develop/group___d_c_p_l.html#ga85faefca58387bba409b65c470d7d851
-[u6]: https://hdfgroup.github.io/hdf5/develop/group___d_c_p_l.html#ga4335bb45b35386daa837b4ff1b9cd4a4
-[u7]: https://hdfgroup.github.io/hdf5/develop/group___d_c_p_l.html#ga6bd822266b31f86551a9a1d79601b6a2
-[u8]: https://www.hdfgroup.org/2022/03/04/parallel-compression-improvements-in-hdf5-1-13-1/
-[u9]: https://hdfgroup.github.io/hdf5/develop/chunking__in__hdf5_8dox.html
-[u10]: https://support.hdfgroup.org/releases/hdf5/documentation/hdf5_topics/HDF5ImprovingIOPerformanceCompressedDatasets.pdf
-[u11]: https://hdfgroup.github.io/hdf5/develop/group___f_a_p_l.html#gab99d5af749aeb3896fd9e3ceb273677a
-[u12]: https://hdfgroup.github.io/hdf5/develop/group___f_c_p_l.html#ga167ff65f392ca3b7f1933b1cee1b9f70
-[u13]: https://hdfgroup.github.io/hdf5/develop/group___f_c_p_l.html#gad012d7f3c2f1e1999eb1770aae3a4963
-[u14]: https://hdfgroup.github.io/hdf5/develop/group___d_x_p_l.html#ga001a22b64f60b815abf5de8b4776f09e
-[u15]: https://hdfgroup.github.io/hdf5/develop/group___d_x_p_l.html#gacb30d14d1791ec7ff9ee73aa148a51a3
-[u16]: https://hdfgroup.github.io/hdf5/develop/group___f_a_p_l.html#gacbe1724e7f70cd17ed687417a1d2a910
+\endcode
+
+*/
diff --git a/doxygen/dox/threadsafety-warning.dox b/doxygen/dox/threadsafety-warning.dox
new file mode 100644
index 00000000000..16194f22a96
--- /dev/null
+++ b/doxygen/dox/threadsafety-warning.dox
@@ -0,0 +1,42 @@
+/** \page ThrdSafe HDF5 Threadsafety Warning
+Any application that creates threads that use the HDF5 library must join those threads before
+either process exit or library close through H5close(). If all HDF5-using threads aren't joined,
+the threads may exhibit undefined behavior.
+
+\section sec_thrdsafe Discussion for Developers on Potential Improvements
+
+It would in principle be possible to make it safe to have threads continue using HDF5 resources
+after a call to #H5close by keeping a count of threads within the library. (There is probably
+no solution to an early process exit producing undefined behavior within threads.) This method
+would only be able to count (and presumably, only _need_ to count) threads that directly interact
+with the library. Because each thread would need to be counted exactly once, this would most
+likely be done by use of a thread-local key with e.g. a boolean value used to track whether the
+a global atomic thread counter has already counted this thread. Then, if #H5close is invoked
+while this thread counter is above one (because one thread must be doing the closing), the library
+would not close, and instead keep its resources valid to hopefully avoid bad behavior with the threads.
+
+The issues with this approach are as follows:
+
+- The process of checking for the existence/value of the thread-local key is slow, or at least
+ slow enough that it's probably not worth adding this to almost every single API call to prevent
+ this particular edge case.
+- Even with this approach, bad behavior would still be possible if the application does something
+ like expose HDF5 resources to threads indirectly via a global variable.
+- How to allow #H5close to fail is nonobvious. #H5close could be allowed to return an error
+ indicating a failure to close, but the number of applications which could usefully respond to such
+ an error by joining threads is small. If an application were able/willing to join its created
+ threads, presumably it would have done so before calling #H5close. Alternatively, #H5close could
+ succeed but silently leave the library open. This creates the potential for confusing, unexpected
+ behavior when the user thinks they are closing and re-opening the library, e.g. if environment
+ variables are modified between close and re-open, or if resources such as default property lists
+ are modified.
+- Applications should join threads before closing libraries that those threads are using, so all
+ of this work would constitute an above-and-beyond effort to maintain safe and defined behavior in
+ the face of an unsafe application.
+
+
+Despite these issues, if a more performant method was found to perform threadcounting like this,
+it might still constitute a worthwhile change.
+
+*/
+
\ No newline at end of file
diff --git a/doxygen/examples/tables/fileDriverLists.dox b/doxygen/examples/tables/fileDriverLists.dox
index 437d32a7b93..c321284944b 100644
--- a/doxygen/examples/tables/fileDriverLists.dox
+++ b/doxygen/examples/tables/fileDriverLists.dox
@@ -71,7 +71,7 @@
*
//! [supported_file_driver_table]
-Supported file drivers
+Supported file drivers
| Driver Name |
Driver Identifier |
diff --git a/doxygen/examples/tables/propertyLists.dox b/doxygen/examples/tables/propertyLists.dox
index 76727b58a59..4480cabc64f 100644
--- a/doxygen/examples/tables/propertyLists.dox
+++ b/doxygen/examples/tables/propertyLists.dox
@@ -2,7 +2,7 @@
*
//! [plcr_table]
-Property list class root functions (H5P)
+Property list class root functions (H5P)
| Function |
Purpose |
@@ -32,7 +32,7 @@
*
//! [plcra_table]
-Property list class root (Advanced) functions (H5P)
+Property list class root (Advanced) functions (H5P)
| Function |
Purpose |
@@ -102,7 +102,7 @@
*
//! [fcpl_table]
-File creation property list functions (H5P)
+File creation property list functions (H5P)
| Function |
Purpose |
@@ -157,7 +157,7 @@ creation property list.
*
//! [fapl_table]
-File access property list functions (H5P)
+File access property list functions (H5P)
| Function |
Purpose |
@@ -298,7 +298,7 @@ versions used when creating objects.
*
//! [fd_pl_table]
-File driver property list functions (H5P)
+File driver property list functions (H5P)
| Function |
Purpose |
@@ -418,7 +418,7 @@ and one raw data file.
*
//! [dcpl_table]
-Dataset creation property list functions (H5P)
+Dataset creation property list functions (H5P)
| Function |
Purpose |
@@ -579,7 +579,7 @@ encoding for object names.
*
//! [dapl_table]
-Dataset access property list functions (H5P)
+Dataset access property list functions (H5P)
| Function |
Purpose |
@@ -621,7 +621,7 @@ encoding for object names.
*
//! [dxpl_table]
-Data transfer property list functions (H5P)
+Data transfer property list functions (H5P)
| C Function |
Purpose |
@@ -727,7 +727,7 @@ of the library for reading or writing the actual data.
*
//! [gcpl_table]
-Group creation property list functions (H5P)
+Group creation property list functions (H5P)
| Function |
Purpose |
@@ -820,7 +820,7 @@ encoding for object names.
*
//! [gapl_table]
-Group access property list functions (H5P)
+Group access property list functions (H5P)
| Function |
Purpose |
@@ -834,7 +834,7 @@ encoding for object names.
*
//! [lapl_table]
-Link access property list functions (H5P)
+Link access property list functions (H5P)
| Function |
Purpose |
@@ -864,7 +864,7 @@ encoding for object names.
*
//! [ocpl_table]
-Object creation property list functions (H5P)
+Object creation property list functions (H5P)
| Function |
Purpose |
@@ -910,7 +910,7 @@ encoding for object names.
*
//! [ocpypl_table]
-Object copy property list functions (H5P)
+Object copy property list functions (H5P)
| Function |
Purpose |
@@ -936,7 +936,7 @@ encoding for object names.
*
//! [strcpl_table]
-String creation property list functions (H5P)
+String creation property list functions (H5P)
| Function |
Purpose |
@@ -950,7 +950,7 @@ encoding for object names.
*
//! [lcpl_table]
-Link creation property list functions (H5P)
+Link creation property list functions (H5P)
| Function |
Purpose |
@@ -964,7 +964,7 @@ encoding for object names.
*
//! [acpl_table]
-Attribute creation property list functions (H5P)
+Attribute creation property list functions (H5P)
| Function |
Purpose |
diff --git a/doxygen/img/FreeingMemory_fig1.png b/doxygen/img/FreeingMemory_fig1.png
new file mode 100644
index 0000000000000000000000000000000000000000..811857869cae6d6a73ec3bd19fb5fddde99088ab
GIT binary patch
literal 49954
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 |