From bbdd638bd56f38a1a0aacc3b949ef4e0d9e32935 Mon Sep 17 00:00:00 2001 From: Scot Breitenfeld Date: Mon, 4 Nov 2024 15:44:45 -0600 Subject: [PATCH] renamed H5VLstart_lib_state and H5VLfinish_lib_state, updated documentation --- doxygen/aliases | 2 ++ release_docs/RELEASE.txt | 8 +++--- src/H5VL.c | 48 +++--------------------------------- src/H5VLconnector_passthru.h | 43 ++++++++++++++++++++++++++++++-- 4 files changed, 52 insertions(+), 49 deletions(-) diff --git a/doxygen/aliases b/doxygen/aliases index ba073c6f3a8..c45b791772e 100644 --- a/doxygen/aliases +++ b/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 ################################################################################ diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt index 83d72f69c5c..730fbc010cb 100644 --- a/release_docs/RELEASE.txt +++ b/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 diff --git a/src/H5VL.c b/src/H5VL.c index 6eb04ea5c80..11a91cfd2c2 100644 --- a/src/H5VL.c +++ b/src/H5VL.c @@ -768,27 +768,8 @@ H5VLretrieve_lib_state(void **state /*out*/) 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 @@ H5VLrestore_lib_state(const void *state) 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 diff --git a/src/H5VLconnector_passthru.h b/src/H5VLconnector_passthru.h index 9438ed117f8..8070495a05a 100644 --- a/src/H5VLconnector_passthru.h +++ b/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 + * H5VLfinish_lib_state() 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 H5VLstart_lib_state(). This function must be called as a \em pair + * with H5VLstart_lib_state(). 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 */