Enhance API tracing (#120)

Enhance API tracing to handle more types, and to put tracing info in a string, allowing it to be used when reporting errors.  Also refactor ref-counted strings (H5RS) module to add capabilities needed for the tracing.  Refactored H5Gname.c routines to use new H5RS routines also.  Added /*out*/ tags to API routines that are returning information to the application.  Updated H5TRACE macros from running updated trace script over library code.  Added tests for new H5RS routines.

1 files changed, 45 insertions, 43 deletions

diff --git a/src/H5Pfapl.c b/src/H5Pfapl.c
index 09ff894..dd14e92 100644
--- a/src/H5Pfapl.c
+++ b/src/H5Pfapl.c
@@ -1551,13 +1551,13 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_family_offset(hid_t fapl_id, hsize_t *offset)
+H5Pget_family_offset(hid_t fapl_id, hsize_t *offset /*out*/)
 {
     H5P_genplist_t *plist;               /* Property list pointer */
     herr_t          ret_value = SUCCEED; /* Return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*h", fapl_id, offset);
+    H5TRACE2("e", "ix", fapl_id, offset);
 
     /* Get the plist structure */
     if (H5P_DEFAULT == fapl_id)
@@ -1629,13 +1629,13 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_multi_type(hid_t fapl_id, H5FD_mem_t *type)
+H5Pget_multi_type(hid_t fapl_id, H5FD_mem_t *type /*out*/)
 {
     H5P_genplist_t *plist;               /* Property list pointer */
     herr_t          ret_value = SUCCEED; /* Return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*Mt", fapl_id, type);
+    H5TRACE2("e", "ix", fapl_id, type);
 
     /* Get the plist structure */
     if (H5P_DEFAULT == fapl_id)
@@ -1723,13 +1723,14 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_cache(hid_t plist_id, int *mdc_nelmts, size_t *rdcc_nslots, size_t *rdcc_nbytes, double *rdcc_w0)
+H5Pget_cache(hid_t plist_id, int *mdc_nelmts, size_t *rdcc_nslots /*out*/, size_t *rdcc_nbytes /*out*/,
+             double *rdcc_w0 /*out*/)
 {
     H5P_genplist_t *plist;               /* Property list pointer */
     herr_t          ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE5("e", "i*Is*z*z*d", plist_id, mdc_nelmts, rdcc_nslots, rdcc_nbytes, rdcc_w0);
+    H5TRACE5("e", "i*Isxxx", plist_id, mdc_nelmts, rdcc_nslots, rdcc_nbytes, rdcc_w0);
 
     /* Get the plist structure */
     if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS)))
@@ -1775,7 +1776,7 @@ H5Pset_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config_ptr)
     herr_t          ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*x", plist_id, config_ptr);
+    H5TRACE2("e", "i*CC", plist_id, config_ptr);
 
     /* Get the plist structure */
     if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS)))
@@ -1816,13 +1817,13 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config)
+H5Pget_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config /*out*/)
 {
     H5P_genplist_t *plist;               /* Property list pointer */
     herr_t          ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*x", plist_id, config);
+    H5TRACE2("e", "ix", plist_id, config);
 
     /* Get the plist structure */
     if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS)))
@@ -1867,7 +1868,7 @@ H5Pset_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr)
     herr_t          ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*x", plist_id, config_ptr);
+    H5TRACE2("e", "i*Cc", plist_id, config_ptr);
 
     /* Get the plist structure */
     if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS)))
@@ -1908,13 +1909,13 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_mdc_config(hid_t plist_id, H5AC_cache_config_t *config)
+H5Pget_mdc_config(hid_t plist_id, H5AC_cache_config_t *config /*out*/)
 {
     H5P_genplist_t *plist;               /* Property list pointer */
     herr_t          ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*x", plist_id, config);
+    H5TRACE2("e", "ix", plist_id, config);
 
     /* Get the plist structure */
     if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS)))
@@ -2065,13 +2066,13 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_fclose_degree(hid_t plist_id, H5F_close_degree_t *degree)
+H5Pget_fclose_degree(hid_t plist_id, H5F_close_degree_t *degree /*out*/)
 {
     H5P_genplist_t *plist;               /* Property list pointer */
     herr_t          ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*Fd", plist_id, degree);
+    H5TRACE2("e", "ix", plist_id, degree);
 
     /* Get the plist structure */
     if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS)))
@@ -2553,13 +2554,13 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_elink_file_cache_size(hid_t plist_id, unsigned *efc_size)
+H5Pget_elink_file_cache_size(hid_t plist_id, unsigned *efc_size /*out*/)
 {
     H5P_genplist_t *plist;               /* Property list pointer */
     herr_t          ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*Iu", plist_id, efc_size);
+    H5TRACE2("e", "ix", plist_id, efc_size);
 
     /* Get the plist structure */
     if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS)))
@@ -2685,14 +2686,14 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_file_image(hid_t fapl_id, void **buf, size_t *buf_len)
+H5Pget_file_image(hid_t fapl_id, void **buf /*out*/, size_t *buf_len /*out*/)
 {
     H5P_genplist_t *       fapl;                /* Property list pointer */
     H5FD_file_image_info_t image_info;          /* File image info */
     herr_t                 ret_value = SUCCEED; /* Return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE3("e", "i**x*z", fapl_id, buf, buf_len);
+    H5TRACE3("e", "ixx", fapl_id, buf, buf_len);
 
     /* Get the plist structure */
     if (NULL == (fapl = H5P_object_verify(fapl_id, H5P_FILE_ACCESS)))
@@ -2767,7 +2768,7 @@ H5Pset_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callback
     herr_t                 ret_value = SUCCEED; /* Return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*x", fapl_id, callbacks_ptr);
+    H5TRACE2("e", "i*DI", fapl_id, callbacks_ptr);
 
     /* Get the plist structure */
     if (NULL == (fapl = H5P_object_verify(fapl_id, H5P_FILE_ACCESS)))
@@ -2836,14 +2837,14 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks)
+H5Pget_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks /*out*/)
 {
     H5P_genplist_t *       fapl;                /* Property list pointer */
     H5FD_file_image_info_t info;                /* File image info */
     herr_t                 ret_value = SUCCEED; /* Return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*x", fapl_id, callbacks);
+    H5TRACE2("e", "ix", fapl_id, callbacks);
 
     /* Get the plist structure */
     if (NULL == (fapl = H5P_object_verify(fapl_id, H5P_FILE_ACCESS)))
@@ -4144,7 +4145,7 @@ H5Pset_object_flush_cb(hid_t plist_id, H5F_flush_cb_t func, void *udata)
     herr_t             ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE3("e", "ix*x", plist_id, func, udata);
+    H5TRACE3("e", "iFF*x", plist_id, func, udata);
 
     /* Check if the callback function is NULL and the user data is non-NULL.
      * This is almost certainly an error as the user data will not be used. */
@@ -4180,14 +4181,14 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_object_flush_cb(hid_t plist_id, H5F_flush_cb_t *func, void **udata)
+H5Pget_object_flush_cb(hid_t plist_id, H5F_flush_cb_t *func /*out*/, void **udata /*out*/)
 {
     H5P_genplist_t *   plist; /* Property list pointer */
     H5F_object_flush_t flush_info;
     herr_t             ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE3("e", "i*x**x", plist_id, func, udata);
+    H5TRACE3("e", "ixx", plist_id, func, udata);
 
     /* Get the plist structure */
     if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS)))
@@ -4267,15 +4268,15 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_mdc_log_options(hid_t plist_id, hbool_t *is_enabled, char *location, size_t *location_size,
-                       hbool_t *start_on_access)
+H5Pget_mdc_log_options(hid_t plist_id, hbool_t *is_enabled /*out*/, char *location /*out*/,
+                       size_t *location_size /*out*/, hbool_t *start_on_access /*out*/)
 {
     H5P_genplist_t *plist;               /* Property list pointer */
     char *          location_ptr;        /* Pointer to location string */
     herr_t          ret_value = SUCCEED; /* Return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE5("e", "i*b*s*z*b", plist_id, is_enabled, location, location_size, start_on_access);
+    H5TRACE5("e", "ixxxx", plist_id, is_enabled, location, location_size, start_on_access);
 
     /* Get the property list structure */
     if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS)))
@@ -4578,13 +4579,13 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_evict_on_close(hid_t fapl_id, hbool_t *evict_on_close)
+H5Pget_evict_on_close(hid_t fapl_id, hbool_t *evict_on_close /*out*/)
 {
     H5P_genplist_t *plist;               /* property list pointer */
     herr_t          ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*b", fapl_id, evict_on_close);
+    H5TRACE2("e", "ix", fapl_id, evict_on_close);
 
     /* Compare the property list's class against the other class */
     if (TRUE != H5P_isa_class(fapl_id, H5P_FILE_ACCESS))
@@ -4665,13 +4666,13 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_file_locking(hid_t fapl_id, hbool_t *use_file_locking, hbool_t *ignore_when_disabled)
+H5Pget_file_locking(hid_t fapl_id, hbool_t *use_file_locking /*out*/, hbool_t *ignore_when_disabled /*out*/)
 {
     H5P_genplist_t *plist;               /* property list pointer */
     herr_t          ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE3("e", "i*b*b", fapl_id, use_file_locking, ignore_when_disabled);
+    H5TRACE3("e", "ixx", fapl_id, use_file_locking, ignore_when_disabled);
 
     /* Make sure this is a fapl */
     if (TRUE != H5P_isa_class(fapl_id, H5P_FILE_ACCESS))
@@ -4839,12 +4840,12 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_all_coll_metadata_ops(hid_t plist_id, hbool_t *is_collective)
+H5Pget_all_coll_metadata_ops(hid_t plist_id, hbool_t *is_collective /*out*/)
 {
     herr_t ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*b", plist_id, is_collective);
+    H5TRACE2("e", "ix", plist_id, is_collective);
 
     /* Compare the property list's class against the other class */
     /* (Dataset, group, attribute, and named datype  access property lists
@@ -4928,13 +4929,13 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_mpi_params(hid_t plist_id, MPI_Comm *comm, MPI_Info *info)
+H5Pget_mpi_params(hid_t plist_id, MPI_Comm *comm /*out*/, MPI_Info *info /*out*/)
 {
     H5P_genplist_t *plist;               /* Property list pointer */
     herr_t          ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE3("e", "i*Mc*Mi", plist_id, comm, info);
+    H5TRACE3("e", "ixx", plist_id, comm, info);
 
     /* Make sure that the property list is a fapl */
     if (TRUE != H5P_isa_class(plist_id, H5P_FILE_ACCESS))
@@ -5378,13 +5379,13 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_coll_metadata_write(hid_t plist_id, hbool_t *is_collective)
+H5Pget_coll_metadata_write(hid_t plist_id, hbool_t *is_collective /*out*/)
 {
     H5P_genplist_t *plist;               /* Property list pointer */
     herr_t          ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*b", plist_id, is_collective);
+    H5TRACE2("e", "ix", plist_id, is_collective);
 
     /* Compare the property list's class against the other class */
     if (TRUE != H5P_isa_class(plist_id, H5P_FILE_ACCESS))
@@ -5465,13 +5466,14 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size, unsigned *min_meta_perc, unsigned *min_raw_perc)
+H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size /*out*/, unsigned *min_meta_perc /*out*/,
+                        unsigned *min_raw_perc /*out*/)
 {
     H5P_genplist_t *plist;               /* Property list pointer */
     herr_t          ret_value = SUCCEED; /* return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE4("e", "i*z*Iu*Iu", plist_id, buf_size, min_meta_perc, min_raw_perc);
+    H5TRACE4("e", "ixxx", plist_id, buf_size, min_meta_perc, min_raw_perc);
 
     /* Get the plist structure */
     if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS)))
@@ -5615,13 +5617,13 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_vol_id(hid_t plist_id, hid_t *vol_id)
+H5Pget_vol_id(hid_t plist_id, hid_t *vol_id /*out*/)
 {
     H5P_genplist_t *plist;               /* Property list pointer */
     herr_t          ret_value = SUCCEED; /* Return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i*i", plist_id, vol_id);
+    H5TRACE2("e", "ix", plist_id, vol_id);
 
     /* Get property list for ID */
     if (NULL == (plist = (H5P_genplist_t *)H5I_object_verify(plist_id, H5I_GENPROP_LST)))
@@ -5661,13 +5663,13 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pget_vol_info(hid_t plist_id, void **vol_info)
+H5Pget_vol_info(hid_t plist_id, void **vol_info /*out*/)
 {
     H5P_genplist_t *plist;               /* Property list pointer */
     herr_t          ret_value = SUCCEED; /* Return value */
 
     FUNC_ENTER_API(FAIL)
-    H5TRACE2("e", "i**x", plist_id, vol_info);
+    H5TRACE2("e", "ix", plist_id, vol_info);
 
     /* Get property list for ID */
     if (NULL == (plist = (H5P_genplist_t *)H5I_object_verify(plist_id, H5I_GENPROP_LST)))