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 is called with num_threads > 0 .
• H5Pset_io_threads() was not called with threads_enabled set to false .
• Selection I/O is not used. See H5Pset_selection_io().
• At least one chunk exists on disk and is not cached by the dataset chunk cache.
• For unfiltered datasets, the chunk cache is large enough to fit at least one chunk. See H5Pset_chunk_cache().

Note

This function is only present when the library is compiled with HDF5_ENABLE_CONCURRENCY=ON.

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