summaryrefslogtreecommitdiffstats
path: root/src/H5ESpublic.h
blob: 752218baa9cb1fd68101f4e2b15e72570163eca9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * All rights reserved.                                                      *
 *                                                                           *
 * This file is part of HDF5. The full HDF5 copyright notice, including      *
 * terms governing use, modification, and redistribution, is contained in    *
 * the COPYING file, which can be found at the root of the source code       *
 * distribution tree, or in https://www.hdfgroup.org/licenses.               *
 * If you do not have access to either file, you may request a copy from     *
 * help@hdfgroup.org.                                                        *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
 * This file contains public declarations for the H5ES (event set) module.
 */

#ifndef H5ESpublic_H
#define H5ESpublic_H

/* Public headers needed by this file */
#include "H5public.h" /* Generic Functions                    */

/*****************/
/* Public Macros */
/*****************/

/* Default value for "no event set" / synchronous execution */
#define H5ES_NONE (hid_t)0

/* Special "wait" timeout values */
#define H5ES_WAIT_FOREVER (UINT64_MAX) /* Wait until all operations complete */
#define H5ES_WAIT_NONE                                                                                       \
    (0) /* Don't wait for operations to complete,                                                            \
         *  just check their status.                                                                         \
         *  (this allows H5ESwait to behave                                                                  \
         *   like a 'test' operation)                                                                        \
         */

/*******************/
/* Public Typedefs */
/*******************/

/* 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_FAIL         /* An operation has completed, but failed                   */
} H5ES_status_t;

/* Information about failed operations in event set */
typedef struct H5ES_err_info_t {
    /* Operation info */
    char *   api_name;      /* Name of HDF5 API routine called */
    char *   api_args;      /* "Argument string" for arguments to HDF5 API routine called */
    char *   app_file_name; /* Name of source file where the HDF5 API routine was called */
    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 */
    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 */

    /* Error info */
    hid_t err_stack_id; /* ID for error stack from failed operation */
} H5ES_err_info_t;

/*
H5ES_op_info_t:
    const char *: API name (H5Dwrite_async, ...)
    const char *: Arg string
    const char *: Appl. source file name
    const char *: Appl. source function
    unsigned: Appl. source file line
    uint64_t: Insert Time Timestamp
    uint64_t: "event count" - n'th event inserted into event set
    uint64_t: Execution Time timestamp (*)

More Possible Info for H5ES_op_info_t:
    Parent Operation's request token (*) -> "parent event count"? -- Could be
        used to "prune" child operations from reported errors, with flag
        to H5ESget_err_info?

H5ES_err_info_t:
    H5ES_op_info_t: (above)
    hid_t: Error stack (*)

Possible debugging routines:  (Should also be configured from Env Var)
    H5ESdebug_signal(hid_t es_id, signal_t sig, uint64_t <event count>);
    H5ESdebug_err_trace_log(hid_t es_id, const char *filename);
    H5ESdebug_err_trace_fh(hid_t es_id, FILE *fh);
    H5ESdebug_err_signal(hid_t es_id, signal_t sig);
[Possibly option to allow operations to be inserted into event set with error?]

    Example usage:
        es_id = H5EScreate();
        H5ESdebug...(es_id, ...);
        ...
        H5Dwrite_async(..., es_id);

How to Trace Async Operations?
    <Example of stacking Logging VOL Connector w/Async VOL Connector>

"Library / wrapper developer" version of API routines: (Auto-generated)
    H5Dwrite_async_wrap(const char *app_file, const char *app_func,
        unsigned app_line_num, dset_id, mem_type_id, mem_space_id, ..., es_id);

    vs.

    H5Dwrite_async(dset_id, mem_type_id, mem_space_id, ..., es_id);
*/

/********************/
/* Public Variables */
/********************/

/*********************/
/* Public Prototypes */
/*********************/

#ifdef __cplusplus
extern "C" {
#endif

H5_DLL hid_t  H5EScreate(void);
H5_DLL herr_t H5ESwait(hid_t es_id, uint64_t timeout, size_t *num_in_progress, hbool_t *err_occurred);
H5_DLL herr_t H5ESget_count(hid_t es_id, size_t *count);
H5_DLL herr_t H5ESget_op_counter(hid_t es_id, uint64_t *counter);
H5_DLL herr_t H5ESget_err_status(hid_t es_id, hbool_t *err_occurred);
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);
H5_DLL herr_t H5ESclose(hid_t es_id);

#ifdef __cplusplus
}
#endif

#endif /* H5ESpublic_H */