From 298c7efe7606aa4c704267beb15138709e1330ab Mon Sep 17 00:00:00 2001 From: Dana Robinson <43805+derobins@users.noreply.github.com> Date: Tue, 27 Dec 2022 11:42:31 -0800 Subject: Adds missing Doxygen for H5ESpublic.h (#2364) * Adds missing Doxygen for H5ESpublic.h * Committing clang-format changes Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> --- src/H5ESpublic.h | 93 ++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 77 insertions(+), 16 deletions(-) diff --git a/src/H5ESpublic.h b/src/H5ESpublic.h index ecfd08f..768cfd5 100644 --- a/src/H5ESpublic.h +++ b/src/H5ESpublic.h @@ -40,30 +40,34 @@ /* Public Typedefs */ /*******************/ -/* Asynchronous operation status */ +/** + * Asynchronous operation status + */ typedef enum H5ES_status_t { - H5ES_STATUS_IN_PROGRESS, /* Operation(s) have not yet completed */ - H5ES_STATUS_SUCCEED, /* Operation(s) have completed, successfully */ - H5ES_STATUS_CANCELED, /* Operation(s) has been canceled */ - H5ES_STATUS_FAIL /* An operation has completed, but failed */ + H5ES_STATUS_IN_PROGRESS, /**< Operation(s) have not yet completed */ + H5ES_STATUS_SUCCEED, /**< Operation(s) have completed, successfully */ + H5ES_STATUS_CANCELED, /**< Operation(s) has been canceled */ + H5ES_STATUS_FAIL /**< An operation has completed, but failed */ } H5ES_status_t; -/* Information about operations in an event set */ +/** + * Information about operations in an event set + */ typedef struct H5ES_op_info_t { /* API call info */ - const char *api_name; /* Name of HDF5 API routine called */ - char *api_args; /* "Argument string" for arguments to HDF5 API routine called */ + const char *api_name; /**< Name of HDF5 API routine called */ + char *api_args; /**< "Argument string" for arguments to HDF5 API routine called */ /* Application info */ - const char *app_file_name; /* Name of source file where the HDF5 API routine was called */ - const char *app_func_name; /* Name of function where the HDF5 API routine was called */ - unsigned app_line_num; /* Line # of source file where the HDF5 API routine was called */ + const char *app_file_name; /**< Name of source file where the HDF5 API routine was called */ + const char *app_func_name; /**< Name of function where the HDF5 API routine was called */ + unsigned app_line_num; /**< Line # of source file where the HDF5 API routine was called */ /* Operation info */ - uint64_t op_ins_count; /* Counter of operation's insertion into event set */ - uint64_t op_ins_ts; /* Timestamp for when the operation was inserted into the event set */ - uint64_t op_exec_ts; /* Timestamp for when the operation began execution */ - uint64_t op_exec_time; /* Execution time for operation (in ns) */ + uint64_t op_ins_count; /**< Counter of operation's insertion into event set */ + uint64_t op_ins_ts; /**< Timestamp for when the operation was inserted into the event set */ + uint64_t op_exec_ts; /**< Timestamp for when the operation began execution */ + uint64_t op_exec_time; /**< Execution time for operation (in ns) */ } H5ES_op_info_t; //! @@ -115,7 +119,14 @@ How to Trace Async Operations? */ +/** + * Callback for H5ESregister_insert_func() + */ typedef int (*H5ES_event_insert_func_t)(const H5ES_op_info_t *op_info, void *ctx); + +/** + * Callback for H5ESregister_complete_func() + */ typedef int (*H5ES_event_complete_func_t)(const H5ES_op_info_t *op_info, H5ES_status_t status, hid_t err_stack, void *ctx); @@ -136,7 +147,7 @@ extern "C" { * * \brief Creates an event set * - * \returns \hid_ti{event set} + * \returns \hid_t{event set} * * \details H5EScreate() creates a new event set and returns a corresponding * event set identifier. @@ -297,8 +308,58 @@ H5_DLL herr_t H5ESget_err_count(hid_t es_id, size_t *num_errs); */ H5_DLL herr_t H5ESget_err_info(hid_t es_id, size_t num_err_info, H5ES_err_info_t err_info[], size_t *err_cleared); +/** + * \ingroup H5ES + * + * \brief Convenience routine to free an array of H5ES_err_info_t structs + * + * \param[in] num_err_info The number of elements in \p err_info array + * \param[in] err_info Array of structures + * \returns \herr_t + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5ESfree_err_info(size_t num_err_info, H5ES_err_info_t err_info[]); + +/** + * \ingroup H5ES + * + * \brief Registers a callback to invoke when a new operation is inserted into + * an event set + * + * \es_id + * \param[in] func The insert function to register + * \param[in] ctx User-specified information (context) to pass to \p func + * \returns \herr_t + * + * \details Only one insert callback can be registered for each event set. + * Registering a new callback will replace the existing one. + * H5ES_NONE is a valid value for 'es_id', but functions as a no-op + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5ESregister_insert_func(hid_t es_id, H5ES_event_insert_func_t func, void *ctx); + +/** + * \ingroup H5ES + * + * \brief Registers a callback to invoke when an operation completes within an + * event set + * + * \es_id + * \param[in] func The completion function to register + * \param[in] ctx User-specified information (context) to pass to \p func + * \returns \herr_t + * + * \details Only one complete callback can be registered for each event set. + * Registering a new callback will replace the existing one. + * H5ES_NONE is a valid value for 'es_id', but functions as a no-op + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5ESregister_complete_func(hid_t es_id, H5ES_event_complete_func_t func, void *ctx); /** -- cgit v0.12