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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* 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 0 /* (hid_t) */
/* 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_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 */
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 */
/* 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 */
/* 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) */
} H5ES_op_info_t;
//! <!-- [H5ES_err_info_t_snip] -->
/**
* Information about failed operations in event set
*/
typedef struct H5ES_err_info_t {
/* API call info */
char *api_name; /**< Name of HDF5 API routine called */
char *api_args; /**< "Argument string" for arguments to HDF5 API routine called */
/* Application info */
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 */
/* 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) */
/* Error info */
hid_t err_stack_id; /**< ID for error stack from failed operation */
} H5ES_err_info_t;
//! <!-- [H5ES_err_info_t_snip] -->
/*
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?
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>
*/
typedef int (*H5ES_event_insert_func_t)(const H5ES_op_info_t *op_info, void *ctx);
typedef int (*H5ES_event_complete_func_t)(const H5ES_op_info_t *op_info, H5ES_status_t status,
hid_t err_stack, void *ctx);
/********************/
/* Public Variables */
/********************/
/*********************/
/* Public Prototypes */
/*********************/
#ifdef __cplusplus
extern "C" {
#endif
/**
* \ingroup H5ES
*
* \brief Creates an event set
*
* \returns \hid_ti{event set}
*
* \details H5EScreate() creates a new event set and returns a corresponding
* event set identifier.
*
* \since 1.13.0
*
*/
H5_DLL hid_t H5EScreate(void);
/**
* \ingroup H5ES
*
* \brief Waits for operations in event set to complete
*
* \es_id
* \param[in] timeout Total time in nanoseconds to wait for all operations in
* the event set to complete
* \param[out] num_in_progress The number of operations still in progress
* \param[out] err_occurred Flag if an operation in the event set failed
* \returns \herr_t
*
* \details H5ESwait() waits for operations in an event set \p es_id to wait
* with \p timeout.
*
* Timeout value is in nanoseconds, and is for the H5ESwait() call and
* not for each individual operation in the event set. For example, if
* "10" is passed as a timeout value and the event set waited 4
* nanoseconds for the first operation to complete, the remaining
* operations would be allowed to wait for at most 6 nanoseconds more,
* i.e., the timeout value used across all operations in the event set
* until it reaches 0, then any remaining operations are only checked
* for completion, not waited on.
*
* This call will stop waiting on operations and will return
* immediately if an operation fails. If a failure occurs, the value
* returned for the number of operations in progress may be inaccurate.
*
* \since 1.13.0
*
*/
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 H5EScancel(hid_t es_id, size_t *num_not_canceled, hbool_t *err_occurred);
/**
* \ingroup H5ES
*
* \brief Retrieves number of events in an event set
*
* \es_id
* \param[out] count The number of events in the event set
* \returns \herr_t
*
* \details H5ESget_count() retrieves number of events in an event set specified
* by \p es_id.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5ESget_count(hid_t es_id, size_t *count);
/**
* \ingroup H5ES
*
* \todo Fill in the blanks!
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5ESget_op_counter(hid_t es_id, uint64_t *counter);
/**
* \ingroup H5ES
*
* \brief Checks for failed operations
*
* \es_id
* \param[out] err_occurred Status indicating if error is present in the event
* set
* \returns \herr_t
*
* \details H5ESget_err_status() checks if event set specified by es_id has
* failed operations.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5ESget_err_status(hid_t es_id, hbool_t *err_occurred);
/**
* \ingroup H5ES
*
* \brief Retrieves the number of failed operations
*
* \es_id
* \param[out] num_errs Number of errors
* \returns \herr_t
*
* \details H5ESget_err_count() retrieves the number of failed operations in an
* event set specified by \p es_id.
*
* The function does not wait for active operations to complete, so
* count may not include all failures.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5ESget_err_count(hid_t es_id, size_t *num_errs);
/**
* \ingroup H5ES
*
* \brief Retrieves information about failed operations
*
* \es_id
* \param[in] num_err_info The number of elements in \p err_info array
* \param[out] err_info Array of structures
* \param[out] err_cleared Number of cleared errors
* \returns \herr_t
*
* \details H5ESget_err_info() retrieves information about failed operations in
* an event set specified by \p es_id. The strings retrieved for each
* error info must be released by calling H5free_memory().
*
* Below is the description of the \ref H5ES_err_info_t structure:
* \snippet this H5ES_err_info_t_snip
* \click4more
*
* \since 1.13.0
*
*/
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 H5ESfree_err_info(size_t num_err_info, H5ES_err_info_t err_info[]);
H5_DLL herr_t H5ESregister_insert_func(hid_t es_id, H5ES_event_insert_func_t func, void *ctx);
H5_DLL herr_t H5ESregister_complete_func(hid_t es_id, H5ES_event_complete_func_t func, void *ctx);
/**
* \ingroup H5ES
*
* \brief Terminates access to an event set
*
* \es_id
* \returns \herr_t
*
* \details H5ESclose() terminates access to an event set specified by \p es_id.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5ESclose(hid_t es_id);
#ifdef __cplusplus
}
#endif
#endif /* H5ESpublic_H */
|
