Renamed H5VLstart_lib_state and H5VLfinish_lib_state (#5070)

doxygen/aliases

@@ -69,6 +69,8 @@ ALIASES += op_data{1}="\param[in,out] \1 User-defined callback function context"
 ALIASES += op_data_in="\param[in] op_data User-defined callback function context"
 ALIASES += op_data_in{1}="\param[in] \1 User-defined callback function context"
 
+ALIASES += vol_only_api="This routine is exclusively for authors of HDF5 VOL connectors. It is not part of the public HDF5 APIs for HDF5 application developers."
+
 ################################################################################
 # Asynchronous
 ################################################################################

doxygen/dox/VOLConnGuide.dox

@@ -4205,7 +4205,7 @@ he type must be a VOL-managed object class:
 Retrieves a copy of the internal state of the HDF5 library, so that it can be restored later. Returns a positive
 value on success and a negative value on errors.
 
-\subsubsection subsubsecVOLNewPassstar H5VLstart_lib_state
+\subsubsection subsubsecVOLNewPassstar H5VLopen_lib_context
 <table>
 <tr>
 <th>Signature:</th>
@@ -4213,13 +4213,12 @@ value on success and a negative value on errors.
 <tr>
 <td>
 \code
-  herr_t H5VLstart_lib_state(void);
+  herr_t H5VLopen_lib_context(void **context);
 \endcode
 </td>
 </tr>
 </table>
-Opens a new internal state for the HDF5 library. Returns a positive value on success and a negative value
-on errors.
+Opens a new internal context for the HDF5 library. Returns a non-negative value if \p *context is set; otherwise returns negative value if \p *context is unset.
 
 \subsubsection subsubsecVOLNewPassrestore H5VLrestore_lib_state
 <table>
@@ -4246,7 +4245,7 @@ on errors.
 </table>
 Restores the internal state of the HDF5 library. Returns a positive value on success and a negative value on errors.
 
-\subsubsection subsubsecVOLNewPassfinish H5VLfinish_lib_state
+\subsubsection subsubsecVOLNewPassfinish H5VLclose_lib_context
 <table>
 <tr>
 <th>Signature:</th>
@@ -4254,12 +4253,12 @@ Restores the internal state of the HDF5 library. Returns a positive value on suc
 <tr>
 <td>
 \code
-  herr_t H5VLfinish_lib_state(void);
+ herr_t H5VLclose_lib_context(void *context);
 \endcode
 </td>
 </tr>
 </table>
-Closes the state of the library, undoing the effects of #H5VLstart_lib_state. Returns a positive value on
+Closes the state of the library, undoing the effects of #H5VLopen_lib_context. Returns a positive value on
 success and a negative value on errors.
 
 \subsubsection subsubsecVOLNewPassfree H5VLfree_lib_state

release_docs/RELEASE.txt

@@ -345,9 +345,11 @@ New Features
         - HDF5Examples/C/H5T/200/h5ex_t_complex_custom.c (Uses H5Tcomplex_create to create
                                                           a custom complex number type)
 
-    - The H5VLstart_lib_state / H5VLfinish_lib_state API routines for pass-
-      through connector authors now require a parameter that can be used to
-      store the library's context.
+    - FOR VOL DEVELOPERS: Renamed H5VLstart_lib_state and H5VLfinish_lib_state
+
+      The APIs H5VLstart_lib_state and H5VLfinish_lib_state have been renamed to
+      H5VLopen_lib_context and H5VLclose_lib_context, respectively, with the addition
+      of a "context" argument.
 
     - Removed H5FDperform_init API routine.  Virtual File Driver (VFD)
       developers who wish to provide an ID for their driver should create

src/H5VL.c

@@ -768,27 +768,8 @@ done:
     FUNC_LEAVE_API_NOINIT(ret_value)
 } /* H5VLretrieve_lib_state() */
 
-/*---------------------------------------------------------------------------
- * Function:    H5VLstart_lib_state
- *
- * Purpose:     Opens a new internal context for the HDF5 library.  The context
- *              returned (via the OUT parameter) must be passed to
- *              H5VLfinish_lib_state to conclude the library's context and
- *              release resources.
- *
- * Note:        This routine is _only_ for HDF5 VOL connector authors!  It is
- *              _not_ part of the public API for HDF5 application developers.
- *
- * Note:        Should probably rename this to 'H5VLopen_lib_context' or
- *              similar.
- *
- * Return:      Success:    Non-negative, *context set
- *              Failure:    Negative, *context unset
- *
- *---------------------------------------------------------------------------
- */
 herr_t
-H5VLstart_lib_state(void **context)
+H5VLopen_lib_context(void **context)
 {
     herr_t ret_value = SUCCEED; /* Return value */
 
@@ -805,7 +786,7 @@ H5VLstart_lib_state(void **context)
 
 done:
     FUNC_LEAVE_API_NOINIT(ret_value)
-} /* H5VLstart_lib_state() */
+} /* H5VLopen_lib_context() */
 
 /*---------------------------------------------------------------------------
  * Function:    H5VLrestore_lib_state
@@ -840,29 +821,8 @@ done:
     FUNC_LEAVE_API_NOINIT(ret_value)
 } /* H5VLrestore_lib_state() */
 
-/*---------------------------------------------------------------------------
- * Function:    H5VLfinish_lib_state
- *
- * Purpose:     Closes the internal state of the HDF5 library, undoing the
- *              affects of H5VLstart_lib_state.
- *
- * Note:        This routine is _only_ for HDF5 VOL connector authors!  It is
- *              _not_ part of the public API for HDF5 application developers.
- *
- * Note:        This routine must be called as a "pair" with
- *              H5VLstart_lib_state.  It can be called before / after /
- *              independently of H5VLfree_lib_state.
- *
- * Note:        Should probably rename this to 'H5VLclose_lib_context' or
- *              similar.
- *
- * Return:      Success:    Non-negative
- *              Failure:    Negative
- *
- *---------------------------------------------------------------------------
- */
 herr_t
-H5VLfinish_lib_state(void *context)
+H5VLclose_lib_context(void *context)
 {
     herr_t ret_value = SUCCEED; /* Return value */
 
@@ -879,7 +839,7 @@ H5VLfinish_lib_state(void *context)
 
 done:
     FUNC_LEAVE_API_NOINIT(ret_value)
-} /* H5VLfinish_lib_state() */
+} /* H5VLclose_lib_context() */
 
 /*---------------------------------------------------------------------------
  * Function:    H5VLfree_lib_state

src/H5VLconnector_passthru.h

@@ -84,9 +84,48 @@ H5_DLL hid_t H5VLwrap_register(void *obj, H5I_type_t type);
 
 /* Library context and state routines */
 H5_DLL herr_t H5VLretrieve_lib_state(void **state);
-H5_DLL herr_t H5VLstart_lib_state(void **context);
+/**
+ * \ingroup H5VLDEV
+ *
+ * \brief Opens a new internal context for the HDF5 library.
+ *
+ * \param[out] context library's context
+ *
+ * \return Returns a non-negative value if \p *context is set; otherwise returns
+ *         negative value if \p *context is unset.
+ *
+ * \details Opens a new internal context for the HDF5 library.  The context
+ *          returned (via the OUT parameter) must be passed to
+ *          H5VLclose_lib_context() to conclude the library's context and
+ *          release resources.
+ *
+ * \note \vol_only_api
+ *
+ * \since 2.0.0
+ *
+ */
+H5_DLL herr_t H5VLopen_lib_context(void **context);
 H5_DLL herr_t H5VLrestore_lib_state(const void *state);
-H5_DLL herr_t H5VLfinish_lib_state(void *context);
+/**
+ * \ingroup H5VLDEV
+ *
+ * \brief Closes the internal state of the HDF5 library.
+ *
+ * \param[in] context library's context
+ *
+ * \return \herr_t
+ *
+ * \details Closes the internal state of the HDF5 library, undoing the effects
+ *          of H5VLopen_lib_context(). This function must be called as a \em pair
+ *          with H5VLopen_lib_context(). It can be invoked before, after, or
+ *          independently of H5VLfree_lib_state().
+ *
+ * \note \vol_only_api
+ *
+ * \since 2.0.0
+ *
+ */
+H5_DLL herr_t H5VLclose_lib_context(void *context);
 H5_DLL herr_t H5VLfree_lib_state(void *state);
 
 /* Pass-through callbacks */