Follow HDF5 conventions.

1 files changed, 89 insertions, 30 deletions

diff --git a/src/H5TS.c b/src/H5TS.c
index 7a801e2..a3b7a14 100644
--- a/src/H5TS.c
+++ b/src/H5TS.c
@@ -39,26 +39,26 @@ H5TS_key_t H5TS_cancel_key_g;
 
 #ifndef H5_HAVE_WIN_THREADS
 
-/* An h5_tid_t is a record of a thread identifier that is
+/* An H5TS_tid_t is a record of a thread identifier that is
  * available for reuse.
  */
 struct _tid;
-typedef struct _tid h5_tid_t;
+typedef struct _tid H5TS_tid_t;
 
 struct _tid {
-    h5_tid_t *next;
+    H5TS_tid_t *next;
     uint64_t id;
 };
 
 /* Pointer to first free thread ID record or NULL. */
-static h5_tid_t *tid_next_free = NULL;
-static uint64_t tid_next_id = 0;
+static H5TS_tid_t *H5TS_tid_next_free = NULL;
+static uint64_t H5TS_tid_next_id = 0;
 
-/* Mutual exclusion for access to tid_next_free and tid_next_id. */
-static pthread_mutex_t tid_mtx;
+/* Mutual exclusion for access to H5TS_tid_next_free and H5TS_tid_next_id. */
+static pthread_mutex_t H5TS_tid_mtx;
 
 /* Key for thread-local storage of the thread ID. */
-static H5TS_key_t tid_key;
+static H5TS_key_t H5TS_tid_key;
 
 #endif /* H5_HAVE_WIN_THREADS */
 
@@ -93,29 +93,61 @@ H5TS_key_destructor(void *key_val)
 
 #ifndef H5_HAVE_WIN_THREADS
 
-/* When a thread shuts down, put its ID record on the free list. */
+/*--------------------------------------------------------------------------
+ * NAME
+ *    H5TS_tid_destructor
+ *
+ * USAGE
+ *    H5TS_tid_destructor()
+ *
+ * RETURNS
+ *
+ * DESCRIPTION
+ *   When a thread shuts down, put its ID record on the free list.
+ *
+ * PROGRAMMER: Rusty Shackleford
+ *             February 7, 2020
+ *
+ *--------------------------------------------------------------------------
+ */
 static void
-tid_destructor(void *_v)
+H5TS_tid_destructor(void *_v)
 {
-    h5_tid_t *tid = _v;
+    H5TS_tid_t *tid = _v;
 
     if (tid == NULL)
         return;
 
     /* XXX I can use mutexes in destructors, right? */
     /* TBD use an atomic CAS */
-    pthread_mutex_lock(&tid_mtx);
-    tid->next = tid_next_free;
-    tid_next_free = tid;
-    pthread_mutex_unlock(&tid_mtx);
+    pthread_mutex_lock(&H5TS_tid_mtx);
+    tid->next = H5TS_tid_next_free;
+    H5TS_tid_next_free = tid;
+    pthread_mutex_unlock(&H5TS_tid_mtx);
 }
 
-/* Initialize for integer thread identifiers. */
+/*--------------------------------------------------------------------------
+ * NAME
+ *    H5TS_tid_init
+ *
+ * USAGE
+ *    H5TS_tid_init()
+ *
+ * RETURNS
+ *
+ * DESCRIPTION
+ *   Initialize for integer thread identifiers.
+ *
+ * PROGRAMMER: Dale Alvin Gribble
+ *             February 7, 2020
+ *
+ *--------------------------------------------------------------------------
+ */
 static void
-tid_init(void)
+H5TS_tid_init(void)
 {
-    pthread_mutex_init(&tid_mtx, NULL);
-    pthread_key_create(&tid_key, tid_destructor);
+    pthread_mutex_init(&H5TS_tid_mtx, NULL);
+    pthread_key_create(&H5TS_tid_key, H5TS_tid_destructor);
 }
 
 /* Return an integer identifier, ID, for the current thread satisfying the
@@ -129,11 +161,38 @@ tid_init(void)
  * ID 0 is reserved.  H5TS_thread_id() returns 0 if the library was not built
  * with thread safety or if an error prevents it from assigning an ID.
  */
+/*--------------------------------------------------------------------------
+ * NAME
+ *    H5TS_thread_id
+ *
+ * USAGE
+ *    uint64_t id = H5TS_thread_id()
+ *
+ * RETURNS
+ *   Return an integer identifier, ID, for the current thread.
+ *
+ * DESCRIPTION
+ *   The ID satisfies the following properties:
+ *
+ *   1 1 <= ID <= UINT64_MAX
+ *   2 ID is constant over the thread's lifetime.
+ *   3 No two threads share an ID during their lifetimes.
+ *   4 A thread's ID is available for reuse as soon as it is joined.
+ *
+ *   ID 0 is reserved.  H5TS_thread_id() returns 0 if the library was not
+ *   built with thread safety or if an error prevents it from assigning an
+ *   ID.
+ *
+ * PROGRAMMER: Rusty Shackleford
+ *             February 7, 2020
+ *
+ *--------------------------------------------------------------------------
+ */
 uint64_t
 H5TS_thread_id(void)
 {
-    h5_tid_t *tid = pthread_getspecific(tid_key);
-    h5_tid_t proto_tid;
+    H5TS_tid_t *tid = pthread_getspecific(H5TS_tid_key);
+    H5TS_tid_t proto_tid;
 
     /* An ID is already assigned. */
     if (tid != NULL)
@@ -146,14 +205,14 @@ H5TS_thread_id(void)
      * point `tid` at `proto_tid` if we need to allocate some
      * memory.
      */
-    pthread_mutex_lock(&tid_mtx);
-    if ((tid = tid_next_free) != NULL)
-        tid_next_free = tid->next;
-    else if (tid_next_id != UINT64_MAX) {
+    pthread_mutex_lock(&H5TS_tid_mtx);
+    if ((tid = H5TS_tid_next_free) != NULL)
+        H5TS_tid_next_free = tid->next;
+    else if (H5TS_tid_next_id != UINT64_MAX) {
         tid = &proto_tid;
-        tid->id = ++tid_next_id;
+        tid->id = ++H5TS_tid_next_id;
     }
-    pthread_mutex_unlock(&tid_mtx);
+    pthread_mutex_unlock(&H5TS_tid_mtx);
 
     /* If a prototype ID record was established, copy it to the heap. */
     if (tid == &proto_tid) {
@@ -168,8 +227,8 @@ H5TS_thread_id(void)
      * to it.
      */
     tid->next = NULL;
-    if (pthread_setspecific(tid_key, tid) != 0) {
-        tid_destructor(tid);
+    if (pthread_setspecific(H5TS_tid_key, tid) != 0) {
+        H5TS_tid_destructor(tid);
         return 0;
     }
 
@@ -213,7 +272,7 @@ H5TS_pthread_first_thread_init(void)
     H5_g.init_lock.lock_count = 0;
 
     /* Initialize integer thread identifiers. */
-    tid_init();
+    H5TS_tid_init();
 
     /* initialize key for thread-specific error stacks */
     pthread_key_create(&H5TS_errstk_key_g, H5TS_key_destructor);