Thread Safety (H5TS)

Detailed Description

Use the functions in this module to manage threads in HDF5.

Functions
herr_t	H5TSset_internal_threads (unsigned num_threads)
	Sets the number of internal threads to use for internal multithreading.

Function Documentation

H5TSset_internal_threads()

herr_t H5TSset_internal_threads

(

unsigned

num_threads

)

Sets the number of internal threads to use for internal multithreading.

Parameters

[in]

num_threads

Number of threads to use for internal multithreading

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TSset_internal_threads() directs the HDF5 library to us num_threads threads to accelerate parallelizable operations.

This is currently only used to accelerate read operations for chunked datasets that either have data filters applied or for which the chunks are small enough to fit in cache. In this case, the library parallelizes the reads from disk, the data filter operations, and the memory scatter operation. However, all of these operations are currently protected by a mutex so no performance gain is expected and this feature is purely experimental. These mutexes will be relaxed in the future to enable performance acceleration.

Currently, the library will immediately create num_threads threads and retain them until this function is called again. Calling this function with num_threads set to 0 will terminate these threads and disable internal multithreading.

This is currently only used to accelerate raw data reads of chunked datasets. This will occur when the following conditions are met:

• This function must be called with num_threads > 0 .
• H5Pset_io_threads() must not be called with threads_enabled set to false .
• Selection I/O must not be used. See H5Pset_selection_io().
• At least one chunk must exist on disk and not be cached by the dataset chunk cache.
• For unfiltered datasets, the chunk cache must be large enough to fit at least one chunk. See H5Pset_chunk_cache().
• No data filters re-enter the HDF5 API. All data filters must set the H5Z_FEAT_FILTER_NO_H5_CALLS capability flag.
• The file driver must not re-enter the HDF5 API. It must set the H5FD_FEAT_READWRITE_NO_H5_CALLS capability flag.
• For concurrent execution of the data filter, that filter must be thread-safe and report that capability with the H5Z_FEAT_FILTER_THREADSAFE capability flag.
• The file must not use an MPI-based file driver.

Note

This function is only present when the library is built with thread support, i.e. when H5_HAVE_THREADS is defined. This is the usual case; the exceptions are builds without a threading package and static libraries on Windows.

Use of this function may increase memory usage during concurrent operations due to the need to maintain state for each thread simultaneously.

Warning

Errors that are printed inside the threaded area, for example by the data filters, do not currently respect non-default error settings, and print their errors to stderr upon thread completion.

Since

2.3.0