Quincey Koziol
331193f357
Added infrastructure support for multithreaded concurrency by adding an optional way to switch to using a non-recursive R/W lock for the global API lock. This is enabled with a new 'concurrency' configuration flag for the autotools & CMake builds, which is disabled by default. When the 'concurrency' build option is chosen, the global API lock will use the R/W lock and all API calls currently will acquire a write lock, ensuring exclusive access by one thread. Over time, the API routines that are converted to support multithreaded concurrency will switch to acquiring a read lock instead. Reentering the library from application callbacks is managed by the 'disable locking for this thread' (DLFTT) threadsafety protocol. This is internally handled within the H5_API_LOCK / H5_API_UNLOCK macros in H5private.h (as before), which invoke the 'dlftt' routines in H5TSint.c. To support this change, the threadsafety configuration macros for the library have been updated: - --enable-threadsafe now defines the H5_HAVE_THREADSAFE macro - --enable-concurrency defines the H5_HAVE_CONCURRENCY macro The new H5_HAVE_THREADSAFE_API macro is set if either H5_HAVE_THREADSAFE or H5_HAVE_CONCURRENCY is enabled. New Github actions are added to include the concurrency configuration in the CI for the develop branch. To support the new non-recursive R/W locking for API routines, some other changes are necessary: Added macro wrappers around all callback invocations that could call an application function, and therefore re-enter the library: H5_BEFORE_USER_CB* / H5_AFTER_USER_CB* Added H5_user_cb_prepare / H5_user_cb_restore routines that save the state of the library when callback leaves the library. Includes error stack and threadsafe reentry state currently. There's also some small cleanups to various places in the library: Moved the H5E_mpi_error_str / H5E_mpi_error_str_len globals to be local for pushing MPI errors, so that multiple threads can't interfere with each other. Added H5TS_rwlock_trywrlock() routine to R/W lock interface. Emulate R/W locks on MacOS because its implementation of pthread_rwlock_wrlock() does not conform to the POSIX standard. Don't acquire the global API lock in H5close, since it's acquired in H5_term_library, which is necessary because H5_term_library is invoked via other code paths that don't hold the global API lock. Don't call H5Eget_auto2 API routine within H5_term_library. Switched 'return NULL' in H5allocate_memory to HGOTO_DONE(NULL). Switched H5Pget_file_space_strategy / H5Pset_file_space_strategy to use internal routines instead of API routines. Switched H5Oopen_by_addr & H5Ovisit1 to use internal routines instead of API routines. Fixed a few places in src/H5Odeprec.c where a major error ID was passed as a minor ID.
The release_docs directory
Intro
This directory contains instructions for building and using the library as well as the HDF5 history files.
HISTORY files
The HISTORY files contain the history of this branch of HDF5. They fall into
three categories.
HISTORY-[VERSION 1]-[VERSION 2].txt
These files are created when we release a new major version and include all
the changes that were made to the develop branch while creating a major release.
HISTORY-[VERSION].txt
This file contains the changes that were made to a maintenance branch since
it split off from develop. It will also be found in the develop branch
when experimental releases have been created.
RELEASE.txt
This is the changelog for the current version of the library.
For a MAJOR release (or in develop) this files lists all the changes since the
last major version. For a MINOR release (or in a maintenance branch), this file
lists all the changes since the last release in the maintenance branch.
Examples:
- The file for HDF5 1.14.0 includes all the changes since HDF5 1.12.0
- The file for HDF5 1.10.9 includes all the changes since HDF5 1.10.8
- The file in
developincludes all the changes since the last major release - The file in
hdf5_1_14includes all the changes since the last minor HDF5 1.14 release
Note that we make no effort to bring maintenance branch HISTORY files back to
develop. If you want to compare, say, 1.10.4 with 1.12.3, you'd have to get
the history files from those releases and compare them by hand.
Creating new releases
MAJOR release
-
If there were experimental releases, merge the experimental
HISTORYfile and the currentRELEASE.txtby category to create a separate, unified file that ignores the experimental releases. Don't check this in yet or clobber any existingHISTORY/RELEASEfiles, but put it someplace handy for use in later steps. -
Create the new maintenance branch
In develop:
- Create the new
HISTORY-\[VERSION 1\]-\[VERSION 2\].txtfile- If there is an experimental
HISTORYfile, addRELEASE.txtto the beginning of it and use that - Otherwise, start with
RELEASE.txt - Add the introduction boilerplate like in the other
HISTORYfiles (TOC, etc.)
- If there is an experimental
- Delete any experimental
HISTORYfile - Clear out
RELEASE.txt
Note that we're KEEPING any experimental release history information in the
HISTORY-\[VERSION 1\]-\[VERSION 2\].txt file, so do NOT use the merged file in
the above steps!
In the new maintenance branch:
-
Create the new
HISTORY-\[VERSION\].txtfile- If there is an experimental
HISTORYfile use the combined file you created earlier - Otherwise, start with
RELEASE.txt - Add the introduction boilerplate like in the other
HISTORYfiles (TOC, etc.)
- If there is an experimental
-
Delete any experimental
HISTORYfile -
Clear out
RELEASE.txt -
Create the new release branch
In the new release branch:
- If there were experimental releases, use the combined file you created earlier as
RELEASE.txt - Otherwise the
RELEASE.txtwill be used as-is
MINOR release
- Create the release branch
In the maintenance branch:
- Add the contents of
RELEASE.txtto the beginnnig ofHISTORY-\[VERSION\].txt - Clear out
RELEASE.txt
EXPERIMENTAL release
- Add the contents of
RELEASE.txtto the beginnnig ofHISTORY-\[VERSION\].txt - Clear out
RELEASE.txt
INSTALL files
These files include instructions for building and installing HDF5 on various platforms.
USING files
These files document how to build HDF5 applications with an installed HDF5 library.