HDF5 Software Changes

HDF5 documents and links Introduction to HDF5 | HDF5 User’s Guide HDF5 Reference Manual HDF5 Application Developer's Guide

# HDF5 Software Changes from Release to Release

This document is designed to help developers maintain HDF5-based applications as they are used with successive releases of HDF5. To that end, this document lists the changes at each release that a maintenance developer needs to be aware of:

- New or changed features or tools
- Syntax and behavioral changes in the existing application programming interface (the API)
- Certain types of changes in configuration or build processes

Bugfixes and performance enhancements in the C library are automatically picked up by the C++ and Fortran libraries. The Java library will pick up the same bugfixes and enhancements at its next subsequent release as it is always built with the latest released version of the C library.

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 of the distributed HDF5 source code.

`RELEASE.txt` | Technical notes regarding the current release of the HDF5 Library
`HISTORY-1_8.txt` | Technical notes for previous 1.8 releases of the HDF5 Library by release
`HISTORY-1_0-1_8_0_rc3.txt` `` | Technical notes for releases prior to the 1.8.0 release of the HDF5 Library by release

Are you porting an existing application from HDF5 Release 1.6.x to HDF5 Release 1.8.x?
If you are porting an existing application from any HDF5 version in the Release 1.6.x series to any version in the Release 1.8.x series, refer to “What's New in HDF5 1.8.0”. This document, with the documents linked in its introduction, provides a guide to the changes introduced in the transition from the 1.6.x series to HDF5 Release 1.8.0 and discussions of various compatibility issues.

## Release 1.8.16 of November 2015 (current release) versus Release 1.8.15

This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.15 to Release 1.8.16.

### New and Changed Functions, Classes, Subroutines, Wrappers, and Macros

In the C Interface (main library)
New HDF5 Plugin Interface (H5PL)
  A new HDF5 Plugin Interface (H5PL), enabling programmatic control of dynamically loaded plugins, was introduced at HDF5 Release 1.8.15. This interface was only partially documented at that time, but more complete documentation is now available:
  - “Dynamic Plugins in HDF5” in Advanced Topics in HDF5
  - “H5PL: Plugin Interface” in the HDF5 Reference Manual
  - `H5PLset_loading_state`
  - `H5PLget_loading_state`

The following new C function has been added:
  This function reports whether the linked version of the HDF5 Library was built with the thread-safety feature enabled.
  - `H5is_library_threadsafe`

The following flag has been removed:
  `H5F_ACC_DEBUG` flag for `H5Fopen/create`
  The flag `H5F_ACC_DEBUG` was used to provide extra debugging information for HDF Library developers. This flag and the underlying functionality have been removed from the library due to disuse. The symbol remains defined since it was visible in `H5Fpublic.h`, but it has been set to zero (`0`) and has no effect anywhere in the library.
  - `H5Fopen`

In the C++ Interface
The following features have been added:
  - New class `H5::ObjCreatPropList` for the object creation property list class

    The new class `H5::ObjCreatPropList` is derived from `H5::PropList` and is a baseclass of `H5::DSetCreatPropList`. Additional property list classes will be added to the library in future releases and some of those will be derived from `H5::ObjCreatPropList`.
  - New wrappers for the C functions `H5P[s/g]et_attr_phase_change` and `H5P[s/g]et_attr_creation_order`

    The following wrappers were added to the class `H5::ObjCreatPropList` for the respective C functions:

    C Function | C++ Wrapper
    `H5Pset_attr_phase_change` | `H5::ObjCreatPropList::setAttrPhaseChange`
    `H5Pget_attr_phase_change` | `H5::ObjCreatPropList::getAttrPhaseChange`
    `H5Pset_attr_creation_order` | `H5::ObjCreatPropList::setAttrCrtOrder`
    `H5Pget_attr_creation_order` | `H5::ObjCreatPropList::getAttrCrtOrder`

### Library Configuration

Use of thread-safety with the HDF5 High-level Library has been declared unsupported in the build tools: Autotools and CMake.
  The global lock used by the thread-safety mechanism is not raised to the high-level library level, making it possible that the library state could change if a context switch were to occur in a high-level library call. Because of this, the combination of thread-safety and the high-level library is officially unsupported by The HDF Group.

  Though this combination has never been supported in HDF5, this was not enforced by the build systems. With this release, the combination has been explicitly flagged as unsupported in Autotools and CMake, the build systems used with HDF5.

  The new unsupported declaration will cause an Autotools configure step to fail if `--enable-threadsafe` and `--enable-hl` are combined unless additional options are specified (see below). Since the high-level library is built by default, this means that these extra configuration options will need to be used any time `--enable-threadsafe` is selected.

  To use Autotools to build an application with `--enable-threadsafe`, use one of the following approaches:

  - Use `--disable-hl` to disable the high-level library. (Recommended)
  - Use `--enable-unsupported` to build the high-level library with the thread-safety feature.

  To use CMake to build an application with `HDF5_ENABLE_THREADSAFE=ON`, use one of the following approaches:

  - Use `HDF5_BUILD_HL_LIB=OFF` to disable the high-level library. (Recommended)
  - Use `HDF5_ALLOW_UNSUPPORTED=ON` to build the high-level library with the thread-safety feature.

  Since this combination is unsupported, applications using it must be carefully tested for potential thread-safety failures.

### Compatibility Notes and Report

Decoupled shared object version numbers (`soname`)
  Shared object version numbers, `soname`, for HDF5 wrapper libraries, such as the C++ and Fortran libraries, have been decoupled from the shared object version number for the HDF5 library. In this and future releases, each library’s `soname` will be maintained on an individual basis according to the interface changes specific to each wrapper library.

Changed shared library interface version numbers (`soname`)
  For HDF5 Release 1.8.16, the shared object version number have changed as follows.

  Library | Release 1.8.15 | Release 1.8.16 | Reason for Change
  --- | --- | --- | ---
  HDF5 Library | 10.0.1 | 10.1.0 | Added APIs
  C++ Library | 10.0.1 | 11.0.0 | Changes in existing APIs
  High‐level C++ Library | 10.0.1 | 11.0.0 | Changes in existing APIs
  All others | 10.0.1 | 10.0.2 | Code changes that did not result in interface changes

Compatibility report for Release 1.8.16 versus Release 1.8.15
  The following interface compatibility report provides a full list of the changed symbols:

  API compatibility report for the HDF5 Library between 1.8.15 and 1.8.16 versions on x86

## Prior Releases in the 1.8.x Series

Change notes for HDF5 Release 1.8.0 to the release immediately preceding the current release are published in “HDF5 Software Changes from Release to Release for HDF5 Releases 1.8.x”.

## Releases 1.6.x and 1.4.x

Change notes for HDF5 Release 1.6.10 and earlier releases are published in “HDF5 Software Changes from Release to Release for HDF5 Releases 1.4.0 through 1.6.10”.

HDF5 documents and links Introduction to HDF5 | HDF5 User’s Guide HDF5 Reference Manual HDF5 Application Developer's Guide

Last modified: 10 November 2015