Add H5atclose and H5is_library_terminating routines. (#139)

* Add H5atclose and H5is_library_terminating routines.

* Add brief Doxygen comment for H5_atclose_func_t typedef.

* Added /*out*/ flag to parameter list, for the tracing script.

* Update doxygen comment for H5atclose with additional detail.

* Return FAIL for H5is_library_threadsafe and H5is_library_terminating when their parameters are NULL.

1 files changed, 117 insertions, 8 deletions

diff --git a/src/H5.c b/src/H5.c
index 03a8714..e5583be 100644
--- a/src/H5.c
+++ b/src/H5.c
@@ -44,6 +44,13 @@
 /* Package Typedefs */
 /********************/
 
+/* Node for list of 'atclose' routines to invoke at library shutdown */
+typedef struct H5_atclose_node_t {
+    H5_atclose_func_t         func; /* Function to invoke */
+    void *                    ctx;  /* Context to pass to function */
+    struct H5_atclose_node_t *next; /* Pointer to next node in list */
+} H5_atclose_node_t;
+
 /********************/
 /* Local Prototypes */
 /********************/
@@ -88,6 +95,12 @@ H5_debug_t     H5_debug_g; /* debugging info */
 /* Local Variables */
 /*******************/
 
+/* Linked list of registered 'atclose' functions to invoke at library shutdown */
+static H5_atclose_node_t *H5_atclose_head = NULL;
+
+/* Declare a free list to manage the H5_atclose_node_t struct */
+H5FL_DEFINE_STATIC(H5_atclose_node_t);
+
 /*--------------------------------------------------------------------------
 NAME
     H5__init_package -- Initialize interface-specific information
@@ -305,6 +318,28 @@ H5_term_library(void)
     /* Check if we should display error output */
     (void)H5Eget_auto2(H5E_DEFAULT, &func, NULL);
 
+    /* Iterate over the list of 'atclose' callbacks that have been registered */
+    if (H5_atclose_head) {
+        H5_atclose_node_t *curr_atclose; /* Current 'atclose' node */
+
+        /* Iterate over all 'atclose' nodes, making callbacks */
+        curr_atclose = H5_atclose_head;
+        while (curr_atclose) {
+            H5_atclose_node_t *tmp_atclose; /* Temporary pointer to 'atclose' node */
+
+            /* Invoke callback, providing context */
+            (*curr_atclose->func)(curr_atclose->ctx);
+
+            /* Advance to next node and free this one */
+            tmp_atclose  = curr_atclose;
+            curr_atclose = curr_atclose->next;
+            H5FL_FREE(H5_atclose_node_t, tmp_atclose);
+        } /* end while */
+
+        /* Reset list head, in case library is re-initialized */
+        H5_atclose_head = NULL;
+    } /* end if */
+
     /*
      * Terminate each interface. The termination functions return a positive
      * value if they do something that might affect some other interface in a
@@ -971,6 +1006,45 @@ done:
 } /* end H5open() */
 
 /*-------------------------------------------------------------------------
+ * Function:	H5atclose
+ *
+ * Purpose:	Register a callback for the library to invoke when it's
+ *		closing.  Callbacks are invoked in LIFO order.
+ *
+ * Return:	Non-negative on success/Negative on failure
+ *
+ *-------------------------------------------------------------------------
+ */
+herr_t
+H5atclose(H5_atclose_func_t func, void *ctx)
+{
+    H5_atclose_node_t *new_atclose;         /* New 'atclose' node */
+    herr_t             ret_value = SUCCEED; /* Return value */
+
+    FUNC_ENTER_API(FAIL)
+    H5TRACE2("e", "Hc*x", func, ctx);
+
+    /* Check arguments */
+    if (NULL == func)
+        HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "NULL func pointer")
+
+    /* Allocate space for the 'atclose' node */
+    if (NULL == (new_atclose = H5FL_MALLOC(H5_atclose_node_t)))
+        HGOTO_ERROR(H5E_RESOURCE, H5E_CANTALLOC, FAIL, "can't allocate 'atclose' node")
+
+    /* Set up 'atclose' node */
+    new_atclose->func = func;
+    new_atclose->ctx  = ctx;
+
+    /* Connector to linked-list of 'atclose' nodes */
+    new_atclose->next = H5_atclose_head;
+    H5_atclose_head   = new_atclose;
+
+done:
+    FUNC_LEAVE_API(ret_value)
+} /* end H5atclose() */
+
+/*-------------------------------------------------------------------------
  * Function:	H5close
  *
  * Purpose:	Terminate the library and release all resources.
@@ -1107,23 +1181,58 @@ H5free_memory(void *mem)
  *-------------------------------------------------------------------------
  */
 herr_t
-H5is_library_threadsafe(hbool_t *is_ts)
+H5is_library_threadsafe(hbool_t *is_ts /*out*/)
 {
-    FUNC_ENTER_API_NOINIT
-    H5TRACE1("e", "*b", is_ts);
+    herr_t ret_value = SUCCEED;         /* Return value */
 
-    HDassert(is_ts);
+    FUNC_ENTER_API_NOINIT
+    H5TRACE1("e", "x", is_ts);
 
-    /* At this time, it is impossible for this to fail. */
+    if(is_ts) {
 #ifdef H5_HAVE_THREADSAFE
-    *is_ts = TRUE;
+        *is_ts = TRUE;
 #else /* H5_HAVE_THREADSAFE */
-    *is_ts = FALSE;
+        *is_ts = FALSE;
 #endif /* H5_HAVE_THREADSAFE */
+    }
+    else
+        ret_value = FAIL;
 
-    FUNC_LEAVE_API_NOINIT(SUCCEED)
+    FUNC_LEAVE_API_NOINIT(ret_value)
 } /* end H5is_library_threadsafe() */
 
+/*-------------------------------------------------------------------------
+ * Function:	H5is_library_terminating
+ *
+ * Purpose:	Checks to see if the library is shutting down.
+ *
+ * Note:	Useful for plugins to detect when the library is terminating.
+ *		For example, a VOL connector could check if a "file close"
+ *		callback was the result of the library shutdown process, or
+ *		an API action from the application.
+ *
+ * Return:	SUCCEED/FAIL
+ *
+ *-------------------------------------------------------------------------
+ */
+herr_t
+H5is_library_terminating(hbool_t *is_terminating /*out*/)
+{
+    herr_t ret_value = SUCCEED;         /* Return value */
+
+    FUNC_ENTER_API_NOINIT
+    H5TRACE1("e", "x", is_terminating);
+
+    HDassert(is_terminating);
+
+    if(is_terminating)
+        *is_terminating = H5_TERM_GLOBAL;
+    else
+        ret_value = FAIL;
+
+    FUNC_LEAVE_API_NOINIT(ret_value)
+} /* end H5is_library_terminating() */
+
 #if defined(H5_HAVE_THREADSAFE) && defined(H5_BUILT_AS_DYNAMIC_LIB) && defined(H5_HAVE_WIN32_API) &&         \
     defined(H5_HAVE_WIN_THREADS)
 /*-------------------------------------------------------------------------