source/include/H5ESpublic.h

0001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
0002  * Copyright by The HDF Group.                                               *
0003  * All rights reserved.                                                      *
0004  *                                                                           *
0005  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
0006  * terms governing use, modification, and redistribution, is contained in    *
0007  * the COPYING file, which can be found at the root of the source code       *
0008  * distribution tree, or in https://www.hdfgroup.org/licenses.               *
0009  * If you do not have access to either file, you may request a copy from     *
0010  * help@hdfgroup.org.                                                        *
0011  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
0012
0013 /*
0014  * This file contains public declarations for the H5ES (event set) module.
0015  */
0016
0017 #ifndef H5ESpublic_H
0018 #define H5ESpublic_H
0019
0020 #include "H5public.h"  /* Generic Functions                        */
0021 #include "H5Ipublic.h" /* Identifiers                              */
0022
0023 /*****************/
0024 /* Public Macros */
0025 /*****************/
0026
0027 /**
0028  * Default value for "no event set" / synchronous execution. Used in
0029  * place of a @ref hid_t identifier.
0030  */
0031 #define H5ES_NONE 0
0032
0033 /* Special "wait" timeout values */
0034 #define H5ES_WAIT_FOREVER (UINT64_MAX) /**< Wait until all operations complete */
0035
0036 /**
0037  * Don't wait for operations to complete, just check their status.
0038  * (This allows @ref H5ESwait to behave like a 'test' operation)
0039  */
0040 #define H5ES_WAIT_NONE (0)
0041
0042 /*******************/
0043 /* Public Typedefs */
0044 /*******************/
0045
0046 /**
0047  * Asynchronous operation status
0048  */
0049 typedef enum H5ES_status_t {
0050     H5ES_STATUS_IN_PROGRESS, /**< Operation(s) have not yet completed         */
0051     H5ES_STATUS_SUCCEED,     /**< Operation(s) have completed, successfully   */
0052     H5ES_STATUS_CANCELED,    /**< Operation(s) has been canceled              */
0053     H5ES_STATUS_FAIL         /**< An operation has completed, but failed      */
0054 } H5ES_status_t;
0055
0056 /**
0057  * Information about operations in an event set
0058  */
0059 typedef struct H5ES_op_info_t {
0060     /* API call info */
0061     const char *api_name; /**< Name of HDF5 API routine called */
0062     char       *api_args; /**< "Argument string" for arguments to HDF5 API routine called */
0063
0064     /* Application info */
0065     const char *app_file_name; /**< Name of source file where the HDF5 API routine was called */
0066     const char *app_func_name; /**< Name of function where the HDF5 API routine was called */
0067     unsigned    app_line_num;  /**< Line # of source file where the HDF5 API routine was called */
0068
0069     /* Operation info */
0070     uint64_t op_ins_count; /**< Counter of operation's insertion into event set */
0071     uint64_t op_ins_ts;    /**< Timestamp for when the operation was inserted into the event set */
0072     uint64_t op_exec_ts;   /**< Timestamp for when the operation began execution */
0073     uint64_t op_exec_time; /**< Execution time for operation (in ns) */
0074 } H5ES_op_info_t;
0075
0076 //! <!-- [H5ES_err_info_t_snip] -->
0077 /**
0078  * Information about failed operations in event set
0079  */
0080 typedef struct H5ES_err_info_t {
0081     /* API call info */
0082     char *api_name; /**< Name of HDF5 API routine called */
0083     char *api_args; /**< "Argument string" for arguments to HDF5 API routine called */
0084
0085     /* Application info */
0086     char    *app_file_name; /**< Name of source file where the HDF5 API routine was called */
0087     char    *app_func_name; /**< Name of function where the HDF5 API routine was called */
0088     unsigned app_line_num;  /**< Line # of source file where the HDF5 API routine was called */
0089
0090     /* Operation info */
0091     uint64_t op_ins_count; /**< Counter of operation's insertion into event set */
0092     uint64_t op_ins_ts;    /**< Timestamp for when the operation was inserted into the event set */
0093     uint64_t op_exec_ts;   /**< Timestamp for when the operation began execution */
0094     uint64_t op_exec_time; /**< Execution time for operation (in ns) */
0095
0096     /* Error info */
0097     hid_t err_stack_id; /**< ID for error stack from failed operation */
0098 } H5ES_err_info_t;
0099 //! <!-- [H5ES_err_info_t_snip] -->
0100
0101 /*
0102 More Possible Info for H5ES_op_info_t:
0103     Parent Operation's request token (*) -> "parent event count"? -- Could be
0104         used to "prune" child operations from reported errors, with flag
0105         to H5ESget_err_info?
0106
0107 Possible debugging routines:  (Should also be configured from Env Var)
0108     H5ESdebug_signal(hid_t es_id, signal_t sig, uint64_t <event count>);
0109     H5ESdebug_err_trace_log(hid_t es_id, const char *filename);
0110     H5ESdebug_err_trace_fh(hid_t es_id, FILE *fh);
0111     H5ESdebug_err_signal(hid_t es_id, signal_t sig);
0112 [Possibly option to allow operations to be inserted into event set with error?]
0113
0114     Example usage:
0115         es_id = H5EScreate();
0116         H5ESdebug...(es_id, ...);
0117         ...
0118         H5Dwrite_async(..., es_id);
0119
0120 How to Trace Async Operations?
0121     <Example of stacking Logging VOL Connector w/Async VOL Connector>
0122
0123 */
0124
0125 /**
0126  * Callback for H5ESregister_insert_func()
0127  */
0128 typedef int (*H5ES_event_insert_func_t)(const H5ES_op_info_t *op_info, void *ctx);
0129
0130 /**
0131  * Callback for H5ESregister_complete_func()
0132  */
0133 typedef int (*H5ES_event_complete_func_t)(const H5ES_op_info_t *op_info, H5ES_status_t status,
0134                                           hid_t err_stack, void *ctx);
0135
0136 /********************/
0137 /* Public Variables */
0138 /********************/
0139
0140 /*********************/
0141 /* Public Prototypes */
0142 /*********************/
0143
0144 #ifdef __cplusplus
0145 extern "C" {
0146 #endif
0147
0148 /**
0149  * \ingroup H5ES
0150  *
0151  * \brief Creates an event set
0152  *
0153  * \return \hid_t{event set}
0154  *
0155  * \details H5EScreate() creates a new event set and returns a corresponding
0156  *          event set identifier.
0157  *
0158  * \since 1.14.0
0159  *
0160  */
0161 H5_DLL hid_t H5EScreate(void);
0162
0163 /**
0164  * \ingroup H5ES
0165  *
0166  * \brief Waits for operations in event set to complete
0167  *
0168  * \es_id
0169  * \param[in] timeout Total time in nanoseconds to wait for all operations in
0170  *            the event set to complete
0171  * \param[out] num_in_progress The number of operations still in progress
0172  * \param[out] err_occurred Flag if an operation in the event set failed
0173  * \return \herr_t
0174  *
0175  * \details H5ESwait() waits for operations in an event set \p es_id to wait
0176  *          with \p timeout.
0177  *
0178  *          Timeout value is in nanoseconds, and is for the H5ESwait() call and
0179  *          not for each individual operation in the event set. For example, if
0180  *          "10" is passed as a timeout value and the event set waited 4
0181  *          nanoseconds for the first operation to complete, the remaining
0182  *          operations would be allowed to wait for at most 6 nanoseconds more,
0183  *          i.e., the timeout value used across all operations in the event set
0184  *          until it reaches 0, then any remaining operations are only checked
0185  *          for completion, not waited on.
0186  *
0187  *          This call will stop waiting on operations and will return
0188  *          immediately if an operation fails. If a failure occurs, the value
0189  *          returned for the number of operations in progress may be inaccurate.
0190  *
0191  * \since 1.14.0
0192  *
0193  */
0194 H5_DLL herr_t H5ESwait(hid_t es_id, uint64_t timeout, size_t *num_in_progress, hbool_t *err_occurred);
0195
0196 /**
0197  * \ingroup H5ES
0198  *
0199  * \brief Attempt to cancel operations in an event set
0200  *
0201  * \es_id
0202  * \param[out] num_not_canceled The number of events not canceled
0203  * \param[out] err_occurred Status indicating if error is present in the event set
0204  * \return \herr_t
0205  *
0206  * \details H5EScancel() attempts to cancel operations in an event set specified
0207  *          by \p es_id. H5ES_NONE is a valid value for \p es_id, but functions as a no-op.
0208  *
0209  * \since 1.14.0
0210  *
0211  */
0212 H5_DLL herr_t H5EScancel(hid_t es_id, size_t *num_not_canceled, hbool_t *err_occurred);
0213
0214 /**
0215  * \ingroup H5ES
0216  *
0217  * \brief Retrieves number of events in an event set
0218  *
0219  * \es_id
0220  * \param[out] count The number of events in the event set
0221  * \return \herr_t
0222  *
0223  * \details H5ESget_count() retrieves number of events in an event set specified
0224  *          by \p es_id.
0225  *
0226  * \since 1.14.0
0227  *
0228  */
0229 H5_DLL herr_t H5ESget_count(hid_t es_id, size_t *count);
0230
0231 /**
0232  * \ingroup H5ES
0233  *
0234  * \brief Retrieves the accumulative operation counter for an event set
0235  *
0236  * \es_id
0237  * \param[out] counter The accumulative counter value for an event set
0238  * \return \herr_t
0239  *
0240  * \details H5ESget_op_counter() retrieves the current accumulative count of
0241  *          event set operations since the event set creation of \p es_id.
0242  *
0243  * \note This is designed for wrapper libraries mainly, to use as a mechanism
0244  *       for matching operations inserted into the event set with possible
0245  *       errors that occur.
0246  *
0247  * \since 1.14.0
0248  *
0249  */
0250 H5_DLL herr_t H5ESget_op_counter(hid_t es_id, uint64_t *counter);
0251
0252 /**
0253  * \ingroup H5ES
0254  *
0255  * \brief Checks for failed operations
0256  *
0257  * \es_id
0258  * \param[out] err_occurred Status indicating if error is present in the event
0259  *             set
0260  * \return \herr_t
0261  *
0262  * \details H5ESget_err_status() checks if event set specified by es_id has
0263  *          failed operations.
0264  *
0265  * \since 1.14.0
0266  *
0267  */
0268 H5_DLL herr_t H5ESget_err_status(hid_t es_id, hbool_t *err_occurred);
0269
0270 /**
0271  * \ingroup H5ES
0272  *
0273  * \brief Retrieves the number of failed operations
0274  *
0275  * \es_id
0276  * \param[out] num_errs Number of errors
0277  * \return \herr_t
0278  *
0279  * \details H5ESget_err_count() retrieves the number of failed operations in an
0280  *          event set specified by \p es_id.
0281  *
0282  *          The function does not wait for active operations to complete, so
0283  *          count may not include all failures.
0284  *
0285  * \since 1.14.0
0286  *
0287  */
0288 H5_DLL herr_t H5ESget_err_count(hid_t es_id, size_t *num_errs);
0289
0290 /**
0291  * \ingroup H5ES
0292  *
0293  * \brief Retrieves information about failed operations
0294  *
0295  * \es_id
0296  * \param[in] num_err_info The number of elements in \p err_info array
0297  * \param[out] err_info Array of structures
0298  * \param[out] err_cleared Number of cleared errors
0299  * \return \herr_t
0300  *
0301  * \details H5ESget_err_info() retrieves information about failed operations in
0302  *          an event set specified by \p es_id.  The strings retrieved for each
0303  *          error info must be released by calling H5free_memory().
0304  *
0305  *          Below is the description of the \ref H5ES_err_info_t structure:
0306  *          \snippet this H5ES_err_info_t_snip
0307  *          \click4more
0308  *
0309  * \since 1.14.0
0310  *
0311  */
0312 H5_DLL herr_t H5ESget_err_info(hid_t es_id, size_t num_err_info, H5ES_err_info_t err_info[],
0313                                size_t *err_cleared);
0314 /**
0315  * \ingroup H5ES
0316  *
0317  * \brief Convenience routine to free an array of H5ES_err_info_t structs
0318  *
0319  * \param[in] num_err_info The number of elements in \p err_info array
0320  * \param[in] err_info Array of structures
0321  * \return \herr_t
0322  *
0323  * \since 1.14.0
0324  *
0325  */
0326 H5_DLL herr_t H5ESfree_err_info(size_t num_err_info, H5ES_err_info_t err_info[]);
0327
0328 /**
0329  * \ingroup H5ES
0330  *
0331  * \brief Registers a callback to invoke when a new operation is inserted into
0332  *        an event set
0333  *
0334  * \es_id
0335  * \param[in] func The insert function to register
0336  * \param[in] ctx User-specified information (context) to pass to \p func
0337  * \return \herr_t
0338  *
0339  * \details Only one insert callback can be registered for each event set.
0340  *          Registering a new callback will replace the existing one.
0341  *          H5ES_NONE is a valid value for 'es_id', but functions as a no-op
0342  *
0343  * \since 1.14.0
0344  *
0345  */
0346 H5_DLL herr_t H5ESregister_insert_func(hid_t es_id, H5ES_event_insert_func_t func, void *ctx);
0347
0348 /**
0349  * \ingroup H5ES
0350  *
0351  * \brief Registers a callback to invoke when an operation completes within an
0352  *        event set
0353  *
0354  * \es_id
0355  * \param[in] func The completion function to register
0356  * \param[in] ctx User-specified information (context) to pass to \p func
0357  * \return \herr_t
0358  *
0359  * \details Only one complete callback can be registered for each event set.
0360  *          Registering a new callback will replace the existing one.
0361  *          H5ES_NONE is a valid value for 'es_id', but functions as a no-op
0362  *
0363  * \since 1.14.0
0364  *
0365  */
0366 H5_DLL herr_t H5ESregister_complete_func(hid_t es_id, H5ES_event_complete_func_t func, void *ctx);
0367
0368 /**
0369  * \ingroup H5ES
0370  *
0371  * \brief Terminates access to an event set
0372  *
0373  * \es_id
0374  * \return \herr_t
0375  *
0376  * \details H5ESclose() terminates access to an event set specified by \p es_id.
0377  *
0378  * \since 1.14.0
0379  *
0380  */
0381 H5_DLL herr_t H5ESclose(hid_t es_id);
0382
0383 #ifdef __cplusplus
0384 }
0385 #endif
0386
0387 #endif /* H5ESpublic_H */