From 32fec52d3e187b4d7ad81b2c8340ba90cf123943 Mon Sep 17 00:00:00 2001 From: Matthew Larson Date: Mon, 16 Sep 2024 12:53:03 -0500 Subject: [PATCH] Document usage for H5TSmutex_release/acquire() --- src/H5TS.c | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/src/H5TS.c b/src/H5TS.c index 590e20b70ff..05d700c4652 100644 --- a/src/H5TS.c +++ b/src/H5TS.c @@ -67,10 +67,12 @@ H5TS_api_info_t H5TS_api_info_p; /*-------------------------------------------------------------------------- * Function: H5TSmutex_acquire * - * Purpose: Attempts to acquire the HDF5 library global lock + * Purpose: Attempts to acquire the HDF5 library global lock. Should be preceded by a call to + * H5TSmutex_release(). * - * Note: On success, the 'acquired' flag indicates if the HDF5 library - * global lock was acquired. + * Parameters: + * lock_count; IN: The lock count that was held on the mutex before its release + * acquired; OUT: Whether the HDF5 library global lock was acquired * * Return: Non-negative on success / Negative on failure * @@ -118,10 +120,17 @@ H5TSmutex_get_attempt_count(unsigned *count) /*-------------------------------------------------------------------------- * Function: H5TSmutex_release * - * Purpose: Releases the HDF5 library global lock + * Purpose: Releases the HDF5 library global lock. Should be followed by a call to H5TSmutex_acquire(). * - * Return: Non-negative on success / Negative on failure + * This should be used by applications to temporarily release the lock in order to either perform + * multi-threaded work of their own or yield control to another thread using HDF5. The value + * returned in lock_count should be provided to H5TSmutex_acquire() in order to resume a + * consistent library state. + * + * Parameters: + * lock_count; OUT: The current lock count for the calling thread. * + * Return: Non-negative on success / Negative on failure *-------------------------------------------------------------------------- */ herr_t