mirror of
https://github.com/HDFGroup/hdf5.git
synced 2026-09-25 04:09:44 +03:00
Scot Breitenfeld
a46a399230
Addresses the "multiple @ param documentation sections" warnings are caused by the interaction of three things:
1. MACRO_EXPANSION = YES with EXPAND_ONLY_PREDEF = NO in Doxyfile.in
2. Versioned API macros in H5version.h like:
\def documentation in APIVersions.dox like:
3. \def H5Tarray_create \api_vers_2{H5Tarray_create,H5Tarray_create1,H5Tarray_create2}
Because Doxygen expands all macros, it sees H5Tarray_create as an alias for H5Tarray_create1. It then associates documentation from both the \def block (for the macro) and the function's own doc block (with \param entries) with the same function — resulting in "multiple @ param documentation sections."
* Update Doxygen version from 1.16.0 to 1.16.1
Use Doxygen 1.16.1 for all platforms. This version includes the latest
bug fixes and improvements while maintaining compatibility with our
documentation format.
* Fix Windows Doxygen installation for version 1.16.1
Handle different Windows binary naming conventions across Doxygen versions:
- 1.16.1 uses: doxygen-VERSION.windows.x64.bin.zip
- 1.16.0 uses: doxygen-VERSION.x64.bin.zip
Try the newer naming convention first, then fall back to the older one
if the download fails. This ensures compatibility across versions.
* Use ssciwr/doxygen-install in setup-doxygen action
Replace direct installation of official Doxygen binaries with
ssciwr/doxygen-install action. This avoids Java documentation parsing
errors that occur with official binaries but not with distribution
builds.
The setup-doxygen action now serves as a thin wrapper around
ssciwr/doxygen-install@f13be16c83 (v1),
using commit hash for security and reproducibility.
* Remove redundant version specification from workflows
The setup-doxygen action already has a default version (1.16.1),
so explicit version specification in workflows is unnecessary.
This follows DRY principles and makes version updates simpler.
666 lines
38 KiB
Plaintext
666 lines
38 KiB
Plaintext
/** \page rel_spec_110_change Release Software Changes for HDF5 1.10
|
|
*
|
|
* Navigate back: \ref index "Main" / \ref release_specific_info / \ref rel_spec_110
|
|
* <hr>
|
|
|
|
\section sec_rel_spec_110_change Software Changes from Release to Release in HDF5 1.10
|
|
For a description of the major new features that were introduced,
|
|
please see \ref sec_rel_spec_110_feat.
|
|
|
|
This page provides information on the changes that a maintenance developer needs to be
|
|
aware of between successive releases of HDF5, such as:
|
|
\li New or changed features or tools
|
|
\li Syntax and behavioral changes in the existing application programming interface (API)
|
|
\li Certain types of changes in configuration or build processes
|
|
|
|
Note that bug fixes and performance enhancements in the C library are automatically picked
|
|
up by the C++, Fortran, and Java libraries.
|
|
|
|
The following information is included below.
|
|
\li \ref subsec_rel_spec_110_change_compatibility
|
|
\li \ref subsec_rel_spec_110_change_9versus8
|
|
\li \ref subsec_rel_spec_110_change_8versus7
|
|
\li \ref subsec_rel_spec_110_change_7versus6
|
|
\li \ref subsec_rel_spec_110_change_6versus5
|
|
\li \ref subsec_rel_spec_110_change_5versus4
|
|
\li \ref subsec_rel_spec_110_change_4versus3
|
|
\li \ref subsec_rel_spec_110_change_3versus2
|
|
\li \ref subsec_rel_spec_110_change_2versus1
|
|
\li \ref subsec_rel_spec_110_change_1versus0
|
|
\li \ref subsec_rel_spec_110_change_0versus8_16
|
|
|
|
See [API Compatibility Reports for 1.10]() for information regarding compatibility with previous releases.
|
|
|
|
\subsection subsec_rel_spec_110_change_compatibility Compatibility and Performance Issues
|
|
|
|
Not all HDF5-1.10 releases are compatible. Users should NOT be using 1.10 releases prior
|
|
to HDF5-1.10.3. See the compatibility matrix below for details on compatibility between 1.10 releases:
|
|
|
|
<table>
|
|
<tr><th>Release</th><th>1.10.5+</th><th>1.10.4</th><th>1.10.3</th><th>1.10.2</th><th>1.10.1</th><th>1.10.0-patch1</th><th>1.10.0</th></tr>
|
|
<tr><td>1.10.5+</td><td>.</td><td>Yes</td><td>Yes</td><td>No</td><td>No</td><td>No</td><td>No</td></tr>
|
|
<tr><td>1.10.4</td><td>Yes</td><td>.</td><td>Yes</td><td>No</td><td>No</td><td>No</td><td>No</td></tr>
|
|
<tr><td>1.10.3</td><td>Yes</td><td>Yes</td><td>.</td><td>No</td><td>No</td><td>No</td><td>No</td></tr>
|
|
<tr><td>1.10.2</td><td>No</td><td>No</td><td>No</td><td>.</td><td>No</td><td>No</td><td>No</td></tr>
|
|
</table>
|
|
|
|
The following images show how performance has changed from release to release.
|
|
|
|
<table>
|
|
<tr><td>\image html cgns.png</td></tr>
|
|
</table>
|
|
|
|
<table>
|
|
<tr><td>\image html writeLgNumDsets.png</td></tr>
|
|
</table>
|
|
|
|
The release notes also list changes made to the library, but these notes tend to be more at a more
|
|
detail-oriented level. The release notes may include new features, bugs fixed, supported configuration
|
|
features, platforms on which the library has been tested, and known problems. The release note files
|
|
are listed below and can be found at the top level of the HDF5 source code tree in the release_docs directory.
|
|
<table>
|
|
<tr><th>Filename</th><th>Description</th></tr>
|
|
<tr><th>Release Notes</th><td> Technical notes regarding the current release of the HDF5 library (RELEASE.txt in the source code)</td></tr>
|
|
<tr><th>HISTORY-1_10.txt</th><td>Release information for all HDF5-1.10 releases</td></tr>
|
|
<tr><th>HISTORY-1_8_0-1_10_0.txt</th><td>Development history between the HDF5-1.8.0 and HDF5-1.10.0 releases</td></tr>
|
|
<tr><th>HISTORY-1_8.txt</th><td>Release information for HDF5-1.8.0 through HDF5-1.8.21 releases</td></tr>
|
|
<tr><th>HISTORY-1_0-1_8_0_rc3.txt</th><td>Technical notes starting with HDF5-1.0.0 and ending with HDF5-1.8.0-rc3 (the state of the code prior to the HDF5-1.8.0 release)</td></tr>
|
|
</table>
|
|
|
|
\subsection subsec_rel_spec_110_change_9versus8 Release 1.10.9 versus 1.10.8
|
|
|
|
\subsection subsec_rel_spec_110_change_9versus8_func New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
|
|
<h4>In the Java API</h4>
|
|
One Java wrapper was added:
|
|
\li H5.H5export_dataset
|
|
|
|
\subsection subsec_rel_spec_110_change_9versus8_compat Compatibility Notes and Reports
|
|
See the [API compatibility report between 1.10.8 and 1.10.9]() for information regarding compatibility with the previous release.
|
|
|
|
\subsection subsec_rel_spec_110_change_8versus7 Release 1.10.8 versus 1.10.7
|
|
|
|
\subsection subsec_rel_spec_110_change_8versus7_func New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
|
|
<h4>In the C++ API</h4>
|
|
One C++ wrapper was added:
|
|
\li <code>DataSet::operator=</code>
|
|
|
|
\subsection subsec_rel_spec_110_change_8versus7_compat Compatibility Notes and Reports
|
|
See the [API compatibility report between 1.10.7 and 1.10.8]() for information regarding compatibility with the previous release.
|
|
|
|
\subsection subsec_rel_spec_110_change_7versus6 Release 1.10.7 versus 1.10.6
|
|
|
|
\subsubsection subsubsec_rel_spec_110_change_7versus6_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
|
|
<h4>In the C Interface (main library)</h4>
|
|
The following are new C functions in this release:
|
|
\li #H5Pget_fapl_splitter - Retrieves information for a splitter file access property list
|
|
\li #H5Pget_fapl_splitter - Retrieves information for a splitter file access property list
|
|
\li #H5Pset_fapl_splitter - Sets the file access property list to use the splitter driver
|
|
\li #H5Pget_file_locking - Gets the file locking property values
|
|
\li #H5Pset_file_locking - Sets the file locking property values
|
|
\li #H5get_free_list_sizes - Gets the current size of the free lists used to manage memory
|
|
\li #H5Scombine_hyperslab - Performs an operation on a hyperslab and an existing selection and returns the resulting selection
|
|
\li #H5Scombine_select - Combines two hyperslab selections with an operation, returning a dataspace with the resulting selection
|
|
\li #H5Smodify_select - Refines a hyperslab selection with an operation using a second hyperslab to modify it
|
|
\li #H5Sselect_adjust - Adjusts a selection by subtracting an offset
|
|
\li #H5Sselect_copy - Copies a selection from one dataspace to another
|
|
\li #H5Sselect_intersect_block - Checks if current selection intersects with a block
|
|
\li #H5Sselect_project_intersection - Projects the intersection of two source selections to a destination selection
|
|
\li #H5Sselect_shape_same - Checks if two selections are the same shape
|
|
|
|
<h4>In the C++ API</h4>
|
|
The following C++ wrappers were added:
|
|
\li <code>FileAccPropList::getFileLocking</code> - See #H5Pget_file_locking for details
|
|
\li <code>FileAccPropList::setFileLocking</code> - See #H5Pset_file_locking for details
|
|
|
|
\subsection subsec_rel_spec_110_change_7versus6_compat Compatibility Notes and Reports
|
|
See the [API compatibility report between 1.10.7 and 1.10.8]() for information regarding compatibility with the previous release.
|
|
|
|
\subsection subsec_rel_spec_110_change_6versus5 Release 1.10.6 versus 1.10.5
|
|
|
|
\subsubsection subsubsec_rel_spec_110_change_6versus5_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
|
|
<h4>In the C Interface (main library)</h4>
|
|
The following are new C functions in this release:
|
|
\li #H5Pget_fapl_hdfs - Gets the information of the given Read-Only HDFS virtual file driver
|
|
\li #H5Pget_fapl_ros3 - Gets the information of the given Read-Only S3 virtual file driver
|
|
\li #H5Pset_fapl_hdfs - Sets up Read-Only HDFS virtual file driver
|
|
\li #H5Pset_fapl_ros3 - Sets up Read-Only S3 virtual file driver
|
|
|
|
<h4>In the C++ API</h4>
|
|
|
|
The following C++ wrappers were added:
|
|
\li <code>LinkCreatPropList::getCreateIntermediateGroup() const</code> - See #H5Pget_create_intermediate_group
|
|
\li <code>LinkCreatPropList::setCreateIntermediateGroup(bool crt_intmd_group) const</code> - See #H5Pset_create_intermediate_group
|
|
|
|
\subsection subsec_rel_spec_110_change_6versus5_compat Compatibility Notes and Reports
|
|
See the [API compatibility report between 1.10.7 and 1.10.8]() for information regarding compatibility with the previous release.
|
|
|
|
\subsection subsec_rel_spec_110_change_5versus4 Release 1.10.5 versus 1.10.4
|
|
|
|
\subsubsection subsubsec_rel_spec_110_change_5versus4_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
|
|
<h4>In the C Interface (main library)</h4>
|
|
The following are new C functions in this release:
|
|
\li #H5Dget_chunk_info - Retrieves information about a chunk specified by the chunk index
|
|
\li #H5Dget_chunk_info_by_coord - Retrieves information about a chunk specified by its coordinates
|
|
\li #H5Dget_num_chunks - Retrieves number of chunks that have nonempty intersection with a specified selection
|
|
\li #H5Fget_dset_no_attrs_hint - Retrieves the setting for determining whether the specified file does or does not create minimized dataset object headers
|
|
\li #H5Fset_dset_no_attrs_hint - Sets the flag to create minimized dataset object headers
|
|
\li #H5Pget_dset_no_attrs_hint - Retrieves the setting for determining whether the specified DCPL does or does not create minimized dataset object headers
|
|
\li #H5Pset_dset_no_attrs_hint - Sets the flag to create minimized dataset object headers
|
|
|
|
|
|
The following changed in this release:
|
|
\li #H5Oget_info
|
|
\li #H5Oget_info_by_name
|
|
\li #H5Oget_info_by_idx
|
|
\li #H5Ovisit
|
|
\li #H5Ovisit_by_name
|
|
|
|
In 1.10.3 the original functions were versioned to H5Oget_info*1 and H5Ovisit*1 and the macros
|
|
H5Oget_info* and H5Ovisit* were created. This broke the API compatibility for a maintenance release.
|
|
In HDF5-1.10.5, the macros introduced in HDF5-1.10.3 were removed. The H5Oget_info*1 and H5Ovisit*1 APIs
|
|
were copied to H5Oget_Info* and H5Ovisit*. As an example, #H5Oget_info and #H5Oget_info1
|
|
are identical in this release.
|
|
|
|
<h4>In the C++ API</h4>
|
|
The following C++ wrapper was added:
|
|
\li <code>H5Object::visit()</code> - Wrapper for the C API #H5Ovisit2. Recursively visit elements
|
|
reachable from an HDF5 object and perform a common set of operations across all of those elements.
|
|
|
|
<h4>In the Fortran API</h4>
|
|
The following Fortran wrappers were added or changed:
|
|
\li `h5fget_dset_no_attrs_hint_f` - Wrappers for the dataset object header minimization calls. See #H5Fget_dset_no_attrs_hint.
|
|
\li `h5fset_dset_no_attrs_hint_f` - Wrappers for the dataset object header minimization calls. See #H5Fset_dset_no_attrs_hint.
|
|
\li `h5pget_dset_no_attrs_hint_f` - Wrappers for the dataset object header minimization calls. See #H5Pget_dset_no_attrs_hint.
|
|
\li `h5pset_dset_no_attrs_hint_f` - Wrappers for the dataset object header minimization calls. See #H5Pset_dset_no_attrs_hint.
|
|
\li \ref h5o::h5ovisit_f - Added new Fortran 'fields' optional parameter. See #H5Ovisit2.
|
|
\li \ref h5o::h5oget_info_by_name_f - Added new Fortran 'fields' optional parameter. See #H5Oget_info_by_name2.
|
|
\li \ref h5o::h5oget_info_f - Added new Fortran 'fields' optional parameter. See #H5Oget_info2.
|
|
\li \ref h5o::h5oget_info_by_idx_f - Added new Fortran 'fields' optional parameter. See #H5Oget_info_by_idx2.
|
|
\li \ref h5o::h5ovisit_by_name_f - Added new Fortran 'fields' optional parameter. See #H5Ovisit_by_name2.
|
|
|
|
|
|
The following Fortran utility function was added:
|
|
\li `h5gmtime` - converts (C) <code>time_t</code> structure to Fortran DATE AND TIME storage format
|
|
|
|
A new Fortran derived type was added:
|
|
\li c_h5o_info_t - This is interoperable with C's h5o_info_t. This is needed for callback functions which
|
|
pass C's h5o_info_t data type definition.
|
|
|
|
<h4>In the Java wrapper</h4>
|
|
The following Java wrappers were added or changed:
|
|
\li #H5Fset_libver_bounds
|
|
\li #H5Fget_dset_no_attrs_hint
|
|
\li #H5Fset_dset_no_attrs_hint
|
|
\li #H5Pget_dset_no_attrs_hint
|
|
\li #H5Pset_dset_no_attrs_hint
|
|
|
|
\subsection subsec_rel_spec_110_change_5versus4_compat Compatibility Notes and Reports
|
|
See the [API compatibility report between 1.10.5 and 1.10.2/1.10.3/1.10.4]() for details.
|
|
|
|
\subsection subsec_rel_spec_110_change_4versus3 Release 1.10.4 versus 1.10.3
|
|
See the [API compatibility report between 1.10.4 and 1.10.3]() for details.
|
|
|
|
\subsection subsec_rel_spec_110_change_3versus2 Release 1.10.3 versus 1.10.2
|
|
New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
|
|
<h4>In the C Interface (main library)</h4>
|
|
The following are new C functions in this release:
|
|
\li #H5Dread_chunk - Moved from HDF5 High Level Optimizations library to core library
|
|
\li #H5Dwrite_chunk - Moved from HDF5 High Level Optimizations library to core library
|
|
\li #H5Oget_info - The function #H5Oget_info was moved to #H5Oget_info1, and the macro #H5Oget_info
|
|
was created that can be mapped to either #H5Oget_info1 or #H5Oget_info2. For HDF5-1.10 and
|
|
earlier releases, #H5Oget_info is mapped to #H5Oget_info1 by default.
|
|
\li #H5Oget_info1
|
|
\li #H5Oget_info2
|
|
\li #H5Oget_info_by_idx - The function #H5Oget_info_by_idx was moved to #H5Oget_info_by_idx1, and
|
|
the macro #H5Oget_info_by_idx was created that can be mapped to either #H5Oget_info_by_idx1 or
|
|
#H5Oget_info_by_idx2. For HDF5-1.10 and earlier releases, #H5Oget_info_by_idx is mapped to #H5Oget_info_by_idx1 by default.
|
|
\li #H5Oget_info_by_idx1
|
|
\li #H5Oget_info_by_idx2
|
|
\li #H5Oget_info_by_name - The function #H5Oget_info_by_name was moved to #H5Oget_info_by_name1,
|
|
and the macro #H5Oget_info_by_name was created that can be mapped to either #H5Oget_info_by_name1
|
|
or #H5Oget_info_by_name2. For HDF5-1.10 and earlier releases, #H5Oget_info_by_name is mapped to
|
|
#H5Oget_info_by_name1 by default.
|
|
\li #H5Oget_info_by_name1
|
|
\li #H5Oget_info_by_name2
|
|
\li #H5Ovisit - The function #H5Ovisit was moved to #H5Ovisit1, and the macro H5Ovisit was created that
|
|
can be mapped to either #H5Ovisit1 or #H5Ovisit2. For HDF5-1.10 and earlier releases, #H5Ovisit is
|
|
mapped to #H5Ovisit1 by default.
|
|
\li #H5Ovisit1
|
|
\li #H5Ovisit2
|
|
\li #H5Ovisit_by_name - The function #H5Ovisit_by_name was moved to #H5Ovisit_by_name1, and the macro
|
|
#H5Ovisit_by_name was created that can be mapped to either #H5Ovisit_by_name1 or #H5Ovisit_by_name2.
|
|
For HDF5-1.10 and earlier releases, #H5Ovisit_by_name is mapped to #H5Ovisit_by_name1 by default.
|
|
\li #H5Ovisit_by_name1
|
|
\li #H5Ovisit_by_name2
|
|
|
|
<h4>In the C High Level Interface</h4>
|
|
The following C functions were deprecated in this release:
|
|
\li #H5DOread_chunk - Deprecated, moved to #H5Dread_chunk
|
|
\li #H5DOwrite_chunk - Deprecated, moved to #H5Dwrite_chunk
|
|
|
|
<h4>In the C++ API</h4>
|
|
Several C++ wrappers were added or modified to provide additional support. See the
|
|
API Compatibility Report for details.
|
|
|
|
\subsection subsec_rel_spec_110_change_4versus3_compat Compatibility Notes and Report
|
|
See the [API compatibility report between 1.10.4 and 1.10.3]() for details.
|
|
|
|
\subsection subsec_rel_spec_110_change_2versus1 Release 1.10.2 versus 1.10.1
|
|
This section lists interface-level changes and other user-visible changes in behavior in the
|
|
transition from HDF5 Release 1.10.1 to Release 1.10.2.
|
|
|
|
New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
|
|
<h4>In the C Interface (main library)</h4>
|
|
The following are new C functions in this release:
|
|
\li #H5Dget_chunk_storage_size - Returns storage amount allocated within a file for a raw data chunk in a dataset
|
|
\li #H5Fget_eoa - Retrieves the file's EOA
|
|
\li #H5Fincrement_filesize - Sets the file's EOA to the maximum of (EOA, EOF) + increment
|
|
\li #H5Fset_libver_bounds - Enables the switch of version bounds setting for a file
|
|
\li #H5FDdriver_query - Queries a VFL driver for its feature flags when a file is not available (not documented in Reference Manual)
|
|
\li #H5Pget_virtual_prefix - Retrieves prefix applied to VDS source file paths
|
|
\li #H5Pset_virtual_prefix - Sets prefix to be applied to VDS source file paths
|
|
|
|
The following C functions changed in this release:
|
|
\li #H5Pset_libver_bounds - HDF5-1.10 was added to the range of versions
|
|
\li #H5Pset_virtual - A change was made to the method of searching for VDS source files
|
|
\li H5PL* - The parameters for many of the H5PL APIs were renamed
|
|
|
|
<h4>In the C High Level Interface</h4>
|
|
The following new C function was added to this release:
|
|
\li #H5DOread_chunk - Reads a raw data chunk directly from a dataset in a file
|
|
|
|
<h4>In the C++ API</h4>
|
|
The following C++ wrappers were added:
|
|
\li #H5Lcreate_soft - Creates a soft link from link_name to target_name
|
|
\li #H5Lcreate_hard - Creates a hard link from new_name to curr_name
|
|
\li #H5Lcopy - Copy an object from a group of file
|
|
\li #H5Lmove - Rename an object in a group or file
|
|
\li #H5Ldelete - Removes the specified link from this location
|
|
\li #H5Tencode - Creates a binary object description of this datatype
|
|
\li #H5Tdecode - Returns the decoded type from the binary object description
|
|
\li #H5Lget_info - Returns the information of the named link
|
|
|
|
These were also added:
|
|
\li <code>Class LinkCreatPropList</code> for link create property list
|
|
|
|
Overloaded functions:
|
|
\li <code>H5Location::createGroup</code> to take a link creation property list
|
|
|
|
See the API Compatibility report for complete details.
|
|
|
|
<h4>In the Java API</h4>
|
|
The following Java wrappers were added:
|
|
\li #H5Pset_evict_on_close - Controls the library's behavior of evicting metadata associated with a closed object
|
|
\li #H5Pget_evict_on_close - Retrieves the file access property list setting that determines whether an HDF5 object will be evicted from the library's metadata cache when closed
|
|
\li #H5Pset_chunk_opts - Sets the edge chunk option in a dataset creation property list
|
|
\li #H5Pget_chunk_opts - Retrieves the edge chunk option setting from a dataset creation property list
|
|
\li #H5Pset_efile_prefix - Sets the external dataset storage file prefix in the dataset access property list
|
|
\li #H5Pget_efile_prefix - Retrieves the prefix for external raw data storage files as set in the dataset access property list
|
|
\li #H5Pset_virtual_prefix - Sets prefix to be applied to VDS source file paths
|
|
\li #H5Pget_virtual_prefix - Retrieves prefix applied to VDS source file paths
|
|
|
|
See the Release.txt file for details.
|
|
|
|
<h4>Tools</h4>
|
|
New options were added to the \ref sec_cltools_h5clear utility:
|
|
\li <code>--filesize</code> - Print the file's EOA and EOF
|
|
\li <code>--increment=C</code> - Set the file's EOA to the maximum of <code>(EOA, EOF) + C</code>
|
|
for the file <code>C is >= 0</code>; C is optional and will default to 1M when not set
|
|
|
|
A new option was added to \ref sec_cltools_h5diff
|
|
\li <code>--enable-error-stack</code> - Enable the error stack
|
|
|
|
\subsection subsec_rel_spec_110_change_2versus1_compat Compatibility Notes and Report
|
|
|
|
See the [API compatibility report between 1.10.4 and 1.10.3]() for details.
|
|
|
|
\subsection subsec_rel_spec_110_change_1versus0 Release 1.10.1 versus 1.10.0
|
|
This section lists interface-level changes and other user-visible changes in behavior in the
|
|
transition from HDF5 Release 1.10.0 (and HDF5-1.10.0-patch1) to Release 1.10.1.
|
|
|
|
\subsubsection subsubsec_rel_spec_110_change_1versus0_new New Features
|
|
Several new features are introduced in HDF5 Release 1.10.1.
|
|
\li Metadata Cache Image
|
|
\li Metadata Cache Evict on Close
|
|
\li Paged Aggregation
|
|
\li Page Buffering
|
|
|
|
<h4>New Features, including associated C Functions</h4>
|
|
The following features are described and documented in New Features in HDF5 Release 1.10.
|
|
Each new feature in 1.10.1 is listed below along with the associated C functions:
|
|
\li <strong>Metadata Cache Image:</strong><br />
|
|
<ul>
|
|
<li>#H5Pget_mdc_image_config - Retrieves the metadata cache image configuration values for a file access property list.</li>
|
|
<li>#H5Pset_mdc_image_config - Sets the metadata cache image option for a file access property list.</li>
|
|
<li>#H5Fget_mdc_image_info - Gets information about a metadata cache image if it exists.</li>
|
|
</ul>
|
|
\li <strong>Metadata Cache Evict on Close:</strong><br />
|
|
<ul>
|
|
<li>#H5Pget_evict_on_close - Retrieves the property list setting that determines whether an HDF5 object will be evicted from the library's metadata cache when it is closed.</li>
|
|
<li>#H5Pset_evict_on_close - Controls the library's behavior of evicting metadata associated with a closed object.</li>
|
|
</ul>
|
|
\li <strong>Paged Aggregation:</strong><br />
|
|
<ul>
|
|
<li>#H5Pget_file_space_page_size - Retrieves the file space page size for a file creation property list.
|
|
<li>#H5Pset_file_space_page_size - Sets the file space page size (used with paged aggregation) for a file creation property list.
|
|
<li>#H5Pget_file_space_strategy - Retrieves the file space handling strategy for a file creation property list.
|
|
<li>#H5Pset_file_space_strategy - Sets the file space allocation strategy for a file creation property list.
|
|
</ul>
|
|
\li <strong>Page Buffering:</strong><br />
|
|
<ul>
|
|
<li>#H5Pget_page_buffer_size - Retrieves the maximum size for the page buffer and the minimum percentage for metadata and raw data pages.</li>
|
|
<li>#H5Pset_page_buffer_size - Sets the maximum size for the page buffer and the minimum percentage for metadata and raw data pages.</li>
|
|
<li>#H5Fget_page_buffering_stats - Retrieves statistics about page access when it is enabled.</li>
|
|
<li>#H5Freset_page_buffering_stats - Resets the page buffer statistics.</li>
|
|
</ul>
|
|
|
|
New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
|
|
<h4>In the C Interface (main library)</h4>
|
|
The following new C functions were added:
|
|
\li #H5PLappend
|
|
\li #H5PLget
|
|
\li #H5PLinsert
|
|
\li #H5PLprepend
|
|
\li #H5PLremove
|
|
\li #H5PLreplace
|
|
\li #H5PLsize
|
|
|
|
<h4>In the C++ API</h4>
|
|
New member functions were added to provide const versions. For example, these methods,
|
|
\li <code>ArrayType::getArrayDims ( hsize_t* dims ) const</code>
|
|
\li <code>ArrayType::getArrayNDims ( ) const</code>
|
|
|
|
replace these:
|
|
\li <code>ArrayType::getArrayDims(hsize_t* dims)</code>
|
|
\li <code>ArrayType::getArrayNDims()</code>
|
|
|
|
Several functions were moved to other classes. For example, this method,
|
|
\li <code>H5Location::openDataSet (char const* name) const</code>
|
|
|
|
replaces:
|
|
\li <code>CommonFG::openDataSet (char const* name) const</code>
|
|
|
|
PLEASE review the Compatibility report below for complete information on the C++ changes in this release.
|
|
|
|
\subsection subsec_rel_spec_110_change_1versus0_compat Compatibility Report
|
|
|
|
See the [API compatibility report between 1.10.1 and 1.10.0-patch1]() for details.
|
|
|
|
\subsection subsec_rel_spec_110_change_0versus8_16 Release 1.10.0 versus Release 1.8.16
|
|
This section lists interface-level changes and other user-visible changes in behavior in
|
|
the transition from HDF5 Release 1.8.16 to Release 1.10.0.
|
|
|
|
Changed Type
|
|
\li hid_t - Changed from a 32-bit to a 64-bit value. hid_t is the type is used for all HDF5
|
|
identifiers. This change, which is necessary to accommodate the capacities of modern
|
|
computing systems, therefore affects all HDF5 applications. If an application has been
|
|
using HDF5's hid_t the type, recompilation will normally be sufficient to take advantage
|
|
of HDF5 Release 1.10.0. If an application uses an integer type instead of HDF5's hid_t
|
|
type, those identifiers must be changed to a 64-bit type when the application is ported
|
|
to the 1.10.x series.
|
|
|
|
<h4>New Features and Feature Sets</h4>
|
|
Several new features are introduced in HDF5 Release 1.10.0.
|
|
\li Single-Writer / Multiple-Reader or SWMR
|
|
\li Collective Metadata I/O
|
|
\li Fine-tuning the metadata cache
|
|
\li File Space Management
|
|
\li Virtual Datasets or VDS
|
|
\li Partial Edge Chunk Options
|
|
\li Relative Pathnames for External Links
|
|
\li Property List Encoding and Decoding
|
|
|
|
More substantial lists follow, including new and modified C functions and Fortran subroutines.
|
|
|
|
<h4>New Features, including associated C Functions and Fortran Wrappers</h4>
|
|
The following features are described and documented in New Features in HDF5 Release 1.10.0. On this
|
|
page, we list each feature and its associated C functions and Fortran wrappers.
|
|
|
|
<h4>Single-writer / Multiple-reader, commonly called SWMR:</h4>
|
|
\li #H5Fstart_swmr_write - Enables SWMR writing mode for a file.
|
|
\li #H5DOappend - Appends data to a dataset along a specified dimension. (This is a high-level API.)
|
|
\li #H5Pget_append_flush - Retrieves the values of the append property that is set up in the dataset access property list.
|
|
\li #H5Pset_append_flush - Sets two actions to perform when the size of a dataset's dimension being appended reaches a specified boundary.
|
|
\li #H5Pget_object_flush_cb - Retrieves the object flush property values from the file access property list.
|
|
\li #H5Pset_object_flush_cb - Sets a callback function to invoke when an object flush occurs in the file.
|
|
\li #H5Odisable_mdc_flushes - Prevents metadata entries for an HDF5 object from being flushed from the metadata cache to storage.
|
|
\li #H5Oenable_mdc_flushes - Returns the cache entries associated with an HDF5 object to the default metadata flush and eviction algorithm.
|
|
\li #H5Oare_mdc_flushes_disabled - Determines if an HDF5 object (dataset, group, committed datatype) has had flushes of metadata entries disabled.
|
|
\li H5Fdisable_mdc_flushes - Globally prevents dirty metadata entries from being flushed from the metadata cache to storage.
|
|
\li H5Fenable_mdc_flushes - Returns a file's metadata cache to the standard eviction and flushing algorithm.
|
|
\li H5Fare_mdc_flushes_disabled - Determines if flushes have been globally disabled for a file's metadata cache.
|
|
\li H5Fget_mdc_flush_disabled_obj_ids - Returns a list of all object identifiers for which flushes have been disabled in a file's metadata cache.
|
|
|
|
<h4>Command-line Tools:</h4>
|
|
\li \ref sec_cltools_h5watch - Allows users to output new records appended to a dataset under SWMR
|
|
access as it grows. The functionality is similar to the Unix user command tail with the follow
|
|
option, which outputs appended data as the file grows.
|
|
\li \ref sec_cltools_h5format_convert - This tool allows users to convert the indexing type of a
|
|
chunked dataset made with a 1.10.x version of the HDF5 Library when the latest file format is
|
|
used to the 1.8.x version 1 B-tree indexing type. For example, datasets created using SWMR access,
|
|
can be converted to be accessed by the HDF5 1.18 library and tools. The tool does not rewrite
|
|
raw data, but it does rewrite HDF5 metadata.
|
|
|
|
<h4>Collective Metadata I/O:</h4>
|
|
\li #H5Pset_coll_metadata_write and `h5pset_coll_metadata_write_f` - Establishes I/O mode property setting,
|
|
collective or independent, for metadata writes.
|
|
\li #H5Pget_coll_metadata_write and `h5pget_coll_metadata_write_f` - Retrieves I/O mode property setting
|
|
for metadata writes.
|
|
\li #H5Pset_all_coll_metadata_ops and `h5pset_all_coll_metadata_ops_f` - Establishes I/O mode, collective
|
|
or independent, for metadata read operations.
|
|
\li #H5Pget_all_coll_metadata_ops and `h5pget_all_coll_metadata_ops_f` - Retrieves I/O mode for metadata
|
|
read operations.
|
|
|
|
<h4>Fine-tuning the Metadata Cache:</h4>
|
|
\li #H5Fget_metadata_read_retry_info - Retrieves the collection of read retries for metadata items with checksum.
|
|
\li #H5Pget_metadata_read_attempts - Retrieves the number of read attempts from a file access property list.
|
|
\li #H5Pset_metadata_read_attempts - Sets the number of read attempts in a file access property list.
|
|
\li #H5Dflush - Causes all buffers associated with a dataset to be immediately written to disk without removing the data from the cache.
|
|
\li #H5Drefresh - Causes all buffers associated with a dataset to be cleared and immediately re-loaded with updated contents from disk storage.
|
|
\li #H5Gflush - Causes all buffers associated with a group to be immediately flushed to disk without removing the data from the cache.
|
|
\li #H5Grefresh - Causes all buffers associated with a group to be cleared and immediately re-loaded with updated contents from disk storage.
|
|
\li #H5Oflush - Causes all buffers associated with an object to be immediately flushed to disk without removing the data from the cache.
|
|
\li #H5Orefresh - Causes all buffers associated with an object to be cleared and immediately re-loaded with updated contents from disk storage.
|
|
\li #H5Tflush - Causes all buffers associated with a committed datatype to be immediately flushed to disk without removing the data from the cache.
|
|
\li #H5Trefresh - Causes all buffers associated with a committed datatype to be cleared and immediately re-loaded with updated contents from disk storage.
|
|
\li #H5Fget_intent - Determines the read/write or read-only status of a file.
|
|
|
|
<h4>Logging APIs:</h4>
|
|
\li #H5Pset_mdc_log_options - Sets metadata cache logging options.
|
|
\li #H5Pget_mdc_log_options - Gets metadata cache logging options.
|
|
\li #H5Fstart_mdc_logging - Starts logging metadata cache events if logging was previously enabled.
|
|
\li #H5Fstop_mdc_logging - Stops logging metadata cache events if logging was previously enabled and is currently ongoing.
|
|
\li H5Pget_mdc_logging_status - Gets the current metadata cache logging status.
|
|
|
|
<h4>File Space Management:</h4>
|
|
\li #H5Fget_free_sections - Retrieves free-space section information for a file.
|
|
\li #H5Fget_freespace - Returns the amount of free space in a file.
|
|
\li #H5Fget_info2 - Returns global information for a file.
|
|
\li #H5Pset_file_space - Sets the file space management strategy and/or the free-space section threshold for an HDF5 file.
|
|
\li #H5Pget_file_space - Retrieves the file space management strategy and/or the free-space section threshold for an HDF5 file.
|
|
|
|
The following tool has been modified to preserve or modify file freepace information appropriately
|
|
when processing files employing the VDS feature:
|
|
\li \ref sec_cltools_h5repack - Repacks HDF5 files with various options, including the ability
|
|
to change the applied filters. This version of \ref sec_cltools_h5repack understands the file free space feature
|
|
and handles the file and metadata appropriately.
|
|
|
|
<h4>Virtual Dataset or VDS:</h4>
|
|
\li #H5Pset_virtual and `h5pset_virtual_f` - Sets the mapping between virtual and source datasets.
|
|
\li #H5Pget_virtual_count and `h5pget_virtual_count_f` - Retrieves the number of mappings for the
|
|
virtual dataset.
|
|
\li #H5Pget_virtual_vspace and `h5pget_virtual_vspace_f` - Retrieves a dataspace identifier for the
|
|
selection within the virtual dataset used in the mapping.
|
|
\li #H5Pget_virtual_srcspace and `h5pget_virtual_srcspace_f` - Retrieves a dataspace identifier
|
|
for the selection within the source dataset used in the mapping.
|
|
\li #H5Pget_virtual_dsetname and `h5pget_virtual_dsetname_f` - Retrieves the name of a source
|
|
dataset used in the mapping.
|
|
\li #H5Pget_virtual_filename and `h5pget_virtual_filename_f` - Retrieves the filename of a source
|
|
dataset used in the mapping.
|
|
\li #H5Pset_virtual_printf_gap and `h5pset_virtual_printf_gap_f` - Sets maximum number of missing
|
|
source files and/or datasets with printf-style names when getting the extent of an unlimited virtual dataset.
|
|
\li #H5Pget_virtual_printf_gap and `h5pget_virtual_printf_gap_f` - Returns maximum number of missing
|
|
source files and/or datasets with printf-style names when getting the extent for an unlimited virtual dataset.
|
|
\li #H5Pset_virtual_view and `h5pset_virtual_view_f` - Sets the view of the virtual dataset to include
|
|
or exclude missing mapped elements.
|
|
\li #H5Pget_virtual_view and `h5pget_virtual_view_f` - Retrieves the view of a virtual dataset.
|
|
|
|
<h4>Supporting Functions:</h4>
|
|
\li #H5Sis_regular_hyperslab and `h5sis_regular_hyperslab_f` - Determines whether a hyperslab selection is regular.
|
|
\li #H5Sget_regular_hyperslab and `h5sget_regular_hyperslab_f` - Retrieves a regular hyperslab selection.
|
|
|
|
<h4>Modified Functions:</h4>
|
|
The following pre-exising functions have been modified to understand virtual datasets.
|
|
\li #H5Pset_layout and `h5pset_layout_f` - Specifies the layout to be used for a dataset.
|
|
Virtual dataset, #H5D_VIRTUAL, has been added to the list of layouts available through this function.
|
|
\li #H5Pget_layout and `h5pget_layout_f` - Retrieves the layout in use for a dataset.
|
|
Virtual dataset, #H5D_VIRTUAL, has been added to the list of layouts.
|
|
|
|
<h4>Partial Edge Chunks:</h4>
|
|
\li #H5Pset_chunk_opts - Sets a partial edge chunk option in a dataset access property list.
|
|
\li #H5Pget_chunk_opts - Retrieves partial edge chunk option setting from a dataset access property list.
|
|
|
|
<h4>Relative Pathnames for External Links:</h4>
|
|
\li #H5Pset_elink_prefix - Sets the prefix to be applied to external link paths.
|
|
\li #H5Pget_elink_prefix - Retrieves the prefix applied to external link paths.
|
|
|
|
These functions enable the user to specify the locations of external files.
|
|
(These functions are not yet documented as of the time of release for 1.10.0.)
|
|
\li #H5Pget_elink_prefix
|
|
|
|
<h4>Property List Encoding and Decoding:</h4>
|
|
\li #H5Pencode
|
|
\li #H5Pdecode
|
|
|
|
<h4>Additional New Functions:</h4>
|
|
The following new functions appear in HDF5 Release 1.10.0 but are not yet documented:
|
|
\li H5Dformat_convert
|
|
\li H5Dget_chunk_index_type
|
|
\li #H5FDlock
|
|
\li #H5FDunlock
|
|
\li H5Fformat_convert
|
|
\li #H5LDget_dset_dims
|
|
\li #H5LDget_dset_elmts
|
|
\li #H5LDget_dset_type_size
|
|
|
|
New and Changed Elements of the Packet Table (H5PT) High-level API
|
|
<h4>In the C Interface</h4>
|
|
<strong>Replacement functions:</strong><br />
|
|
\li #H5PTcreate - Takes a property list identifier to provide flexibility on creation properties. H5PTcreate_fl has been removed.
|
|
\li #H5PTfree_vlen_buff - Replaces H5PTfree_vlen_readbuff.
|
|
|
|
<strong>New functions:</strong><br />
|
|
Two accessor functions have been added.
|
|
\li #H5PTget_dataset - Returns the identifier of the dataset associated a packet table.
|
|
\li #H5PTget_type - Returns the identifier of the datatype used by a packet table.
|
|
\li #H5PTis_varlen - Determines whether a type is variable-length.
|
|
|
|
<h4>In the C++ Interface</h4>
|
|
<strong>Overloaded constructor</strong><br />
|
|
An overloaded constructor has been added.
|
|
\li FL_PacketTable - Takes a property list identifier to provide flexibility on creation properties.</dd>
|
|
\li H5PTfree_vlen_buff - Replaces H5PTfree_vlen_readbuff.
|
|
|
|
<strong>Accessor wrappers</strong><br />
|
|
Two accessor wrappers are added to class PacketTable.
|
|
\li PacketTable::GetDataset() - Returns the identifier of the dataset associated a packet table.
|
|
\li PacketTable::GetDatatype() - Returns the identifier of the datatype used by a packet table.
|
|
|
|
<strong>Other wrappers</strong>
|
|
\li PacketTable::FreeBuff() - Replaces VL_PacketTable::FreeReadBuff().
|
|
\li PacketTable::IsVariableLength() - Replaces VL_PacketTable::IsVariableLength().
|
|
|
|
<strong>Overloaded functions:</strong><br />
|
|
Where a member functions has a char* as an argument, an overloaded functions has been added to provide the const char* argument.
|
|
The existing version will be deprecated in a future release.
|
|
|
|
<h4>Java Interface Changes</h4>
|
|
\li Integration into Main HDF5 Library - The Java HDF5 JNI library has been integrated into the HDF5 repository.
|
|
|
|
<strong>Configure option:</strong>
|
|
\li <code>--enable-java</code>
|
|
|
|
<strong>CMake option:</strong>
|
|
\li <code>-DHDF5_BUILD_JAVA:BOOL=ON</code>
|
|
|
|
Prior to the 1.10.x series, the HDF5 Java tools were built from an independent repository
|
|
and were not as fully integrated with HDF5. were built from an independent repository
|
|
and were not as fully integrated with HDF5.
|
|
|
|
<strong>Package Hierarchy Change</strong>
|
|
\li The package hierarchy has changed to hdf.hdflib.hdf5.
|
|
\li Prior to the 1.10.x series, the hierarchy was ncsa.hdf.hdflib.hdf5.
|
|
|
|
<h4>New Java APIs</h4>
|
|
A number of new APIs have been added in the Java interface, including APIs for the VDS and SWMR features.
|
|
|
|
<h4>Functions with Changed Behavior</h4>
|
|
\li #H5Lexists - The behavior of this function has changed in this release. When testing the
|
|
pathname / (a slash representing the root of an HDF5 file) #H5Lexists now returns
|
|
successfully with the value 1 (one). See the entry in the \ref RM for #H5Lexists for more information.
|
|
|
|
\subsection subsec_rel_spec_110_change_0versus8_16_apicompat API Compatibility
|
|
See \ref api-compat-macros for details on the following.
|
|
|
|
<h4>New API Compatibility Flag</h4>
|
|
A new v18 flag was added enabling the building of HDF5 such that the default API is compatible
|
|
with the HDF5 Release 1.8.x API:
|
|
\li <code>--with-default-api-version=v18</code>
|
|
|
|
<h4>New versioned functions and associated compatibility macros</h4>
|
|
Two functions and a struct have been converted to a versioned form in this release.
|
|
Compatibility macros have been created for each.
|
|
\li #H5Fget_info - The original function is renamed to #H5Fget_info1 and deprecated.
|
|
A new version of the function, #H5Fget_info2, is introduced.
|
|
The compatibility macro #H5Fget_info is introduced.
|
|
\li #H5F_info_t - This is the struct used by the #H5Fget_info functions and macro.
|
|
The original struct is renamed to #H5F_info1_t and deprecated.
|
|
A new version of the struct, #H5F_info2_t, is introduced.
|
|
The compatibility macro #H5F_info_t is introduced.
|
|
\li #H5Rdereference - The original function is renamed to #H5Rdereference1 and deprecated.
|
|
A new version of the function, #H5Rdereference2, is introduced.
|
|
The compatibility macro #H5Rdereference is introduced.
|
|
|
|
\subsection subsec_rel_spec_110_change_0versus8_16_auto Autotools Configuration and Large File Support
|
|
Autotools configuration has been extensively reworked and autotool's handling of large
|
|
file support has been overhauled in this release.
|
|
|
|
See the following sections in RELEASE.txt:
|
|
\li Autotools Configuration Has Been Extensively Reworked
|
|
\li LFS Changes
|
|
|
|
RELEASE.txt can be found in the release_docs/ subdirectory at the root level of the HDF5 code distribution.
|
|
|
|
\subsection subsec_rel_spec_110_change_0versus8_16_compat Compatibility Report and Comments
|
|
|
|
[Compatibility report for Release 1.10.0 versus Release 1.8.16]()
|
|
|
|
Comments regarding the report
|
|
|
|
In the C interface, the hid_t change from 32-bit to 64-bit was made in order to address
|
|
a performance problem that arose when the library "ran out" of valid object identifiers
|
|
to issue and thus needed to employ an expensive algorithm to find previously issued
|
|
identifiers that could be re-issued. This problem is avoided by switching the size of
|
|
the hid_t type to 64-bit integers instead of 32-bit integers in order to make the pool
|
|
of available integers significantly larger. (#H5E_major_t and #H5E_minor_t are aliased to
|
|
hid_t which is why they changed size as well). (An alternate solution to this problem was
|
|
applied in release HDF5 1.8.5 but this is the cleaner/preferred solution and had to wait
|
|
until 1.10.0 to be included).
|
|
|
|
hbool_t will now be defined as a Bool type when configure determines that it's available.
|
|
|
|
Public structs that have members of type hid_t or hbool_t are affected by the above changes accordingly.
|
|
|
|
The #H5Fget_info function was renamed due to the introduction of a newer version of the
|
|
function which returns additional information. The #H5Rdereference function was renamed
|
|
due to the introduction of a newer version of the function which allows a data access
|
|
property list to be passed in. Both changes are accompanied with compatibility macros,
|
|
so while existing code will need to be recompiled in order to use the newer library version,
|
|
these functions do not need to be changed in application code using them provided that the
|
|
\ref api-compat-macros are configured appropriately.
|
|
|
|
*
|
|
* <hr>
|
|
* Navigate back: \ref index "Main" / \ref release_specific_info / \ref rel_spec_110
|
|
*/
|