Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5  1.15.0
API Reference
Event Set Interface (H5ES)

Detailed Description

Event Set Interface.

Todo:
Add the event set life cycle.

This interface can only be used with the HDF5 VOL connectors that enable the asynchronous feature in HDF5. The native HDF5 library has only synchronous operations.

HDF5 VOL connectors with support for asynchronous operations:

Example:
fid = H5Fopen(..);
gid = H5Gopen(fid, ..); //Starts when H5Fopen completes
did = H5Dopen(gid, ..); //Starts when H5Gopen completes
es_id = H5EScreate(); // Create event set for tracking async operations
status = H5Dwrite_async(did, .., es_id); //Asynchronous, starts when H5Dopen completes,
// may run concurrently with other H5Dwrite_async
// in event set.
status = H5Dwrite_async(did, .., es_id); //Asynchronous, starts when H5Dopen completes,
// may run concurrently with other H5Dwrite_async
// in event set....
<other user code>
...
H5ESwait(es_id); // Wait for operations in event set to complete, buffers
// used for H5Dwrite_async must only be changed after wait
// returns.
#define H5Dopen
Definition: H5version.h:903
herr_t H5Dwrite_async(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, const void *buf, hid_t es_id)
hid_t H5EScreate(void)
Creates an event set.
hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id)
Opens an existing HDF5 file.
#define H5Gopen
Definition: H5version.h:1008

Functions

hid_t H5EScreate (void)
 Creates an event set. More...
 
herr_t H5ESwait (hid_t es_id, uint64_t timeout, size_t *num_in_progress, hbool_t *err_occurred)
 Waits for operations in event set to complete. More...
 
herr_t H5EScancel (hid_t es_id, size_t *num_not_canceled, hbool_t *err_occurred)
 Attempt to cancel operations in an event set. More...
 
herr_t H5ESget_count (hid_t es_id, size_t *count)
 Retrieves number of events in an event set. More...
 
herr_t H5ESget_op_counter (hid_t es_id, uint64_t *counter)
 Retrieves the accumulative operation counter for an event set. More...
 
herr_t H5ESget_err_status (hid_t es_id, hbool_t *err_occurred)
 Checks for failed operations. More...
 
herr_t H5ESget_err_count (hid_t es_id, size_t *num_errs)
 Retrieves the number of failed operations. More...
 
herr_t H5ESget_err_info (hid_t es_id, size_t num_err_info, H5ES_err_info_t err_info[], size_t *err_cleared)
 Retrieves information about failed operations. More...
 
herr_t H5ESfree_err_info (size_t num_err_info, H5ES_err_info_t err_info[])
 Convenience routine to free an array of H5ES_err_info_t structs. More...
 
herr_t H5ESregister_insert_func (hid_t es_id, H5ES_event_insert_func_t func, void *ctx)
 Registers a callback to invoke when a new operation is inserted into an event set. More...
 
herr_t H5ESregister_complete_func (hid_t es_id, H5ES_event_complete_func_t func, void *ctx)
 Registers a callback to invoke when an operation completes within an event set. More...
 
herr_t H5ESclose (hid_t es_id)
 Terminates access to an event set. More...
 

Function Documentation

◆ H5EScancel()

herr_t H5EScancel ( hid_t  es_id,
size_t *  num_not_canceled,
hbool_t err_occurred 
)

Attempt to cancel operations in an event set.

Parameters
[in]es_idEvent set identifier
[out]num_not_canceledThe number of events not canceled
[out]err_occurredStatus indicating if error is present in the event set
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5EScancel() attempts to cancel operations in an event set specified by es_id. H5ES_NONE is a valid value for es_id, but functions as a no-op.

Since
1.14.0

◆ H5ESclose()

herr_t H5ESclose ( hid_t  es_id)

Terminates access to an event set.

Parameters
[in]es_idEvent set identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5ESclose() terminates access to an event set specified by es_id.

Since
1.14.0

◆ H5EScreate()

hid_t H5EScreate ( void  )

Creates an event set.

Returns
Returns a event set identifier if successful; otherwise returns H5I_INVALID_HID.

H5EScreate() creates a new event set and returns a corresponding event set identifier.

Since
1.14.0

◆ H5ESfree_err_info()

herr_t H5ESfree_err_info ( size_t  num_err_info,
H5ES_err_info_t  err_info[] 
)

Convenience routine to free an array of H5ES_err_info_t structs.

Parameters
[in]num_err_infoThe number of elements in err_info array
[in]err_infoArray of structures
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Since
1.14.0

◆ H5ESget_count()

herr_t H5ESget_count ( hid_t  es_id,
size_t *  count 
)

Retrieves number of events in an event set.

Parameters
[in]es_idEvent set identifier
[out]countThe number of events in the event set
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5ESget_count() retrieves number of events in an event set specified by es_id.

Since
1.14.0

◆ H5ESget_err_count()

herr_t H5ESget_err_count ( hid_t  es_id,
size_t *  num_errs 
)

Retrieves the number of failed operations.

Parameters
[in]es_idEvent set identifier
[out]num_errsNumber of errors
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5ESget_err_count() retrieves the number of failed operations in an event set specified by es_id.

The function does not wait for active operations to complete, so count may not include all failures.

Since
1.14.0

◆ H5ESget_err_info()

herr_t H5ESget_err_info ( hid_t  es_id,
size_t  num_err_info,
H5ES_err_info_t  err_info[],
size_t *  err_cleared 
)

Retrieves information about failed operations.

Parameters
[in]es_idEvent set identifier
[in]num_err_infoThe number of elements in err_info array
[out]err_infoArray of structures
[out]err_clearedNumber of cleared errors
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5ESget_err_info() retrieves information about failed operations in an event set specified by es_id. The strings retrieved for each error info must be released by calling H5free_memory().

Below is the description of the H5ES_err_info_t structure:

typedef struct H5ES_err_info_t {
/* API call info */
char *api_name;
char *api_args;
/* Application info */
char *app_file_name;
char *app_func_name;
unsigned app_line_num;
/* Operation info */
uint64_t op_ins_count;
uint64_t op_ins_ts;
uint64_t op_exec_ts;
uint64_t op_exec_time;
/* Error info */
int64_t hid_t
Definition: H5Ipublic.h:60
Definition: H5ESpublic.h:80
char * app_func_name
Definition: H5ESpublic.h:87
char * api_args
Definition: H5ESpublic.h:83
uint64_t op_ins_count
Definition: H5ESpublic.h:91
uint64_t op_exec_time
Definition: H5ESpublic.h:94
unsigned app_line_num
Definition: H5ESpublic.h:88
char * api_name
Definition: H5ESpublic.h:82
char * app_file_name
Definition: H5ESpublic.h:86
uint64_t op_exec_ts
Definition: H5ESpublic.h:93
hid_t err_stack_id
Definition: H5ESpublic.h:97
uint64_t op_ins_ts
Definition: H5ESpublic.h:92

(Click on a enumerator, field, or type for more information.)

Since
1.14.0

◆ H5ESget_err_status()

herr_t H5ESget_err_status ( hid_t  es_id,
hbool_t err_occurred 
)

Checks for failed operations.

Parameters
[in]es_idEvent set identifier
[out]err_occurredStatus indicating if error is present in the event set
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5ESget_err_status() checks if event set specified by es_id has failed operations.

Since
1.14.0

◆ H5ESget_op_counter()

herr_t H5ESget_op_counter ( hid_t  es_id,
uint64_t *  counter 
)

Retrieves the accumulative operation counter for an event set.

Parameters
[in]es_idEvent set identifier
[out]counterThe accumulative counter value for an event set
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5ESget_op_counter() retrieves the current accumulative count of event set operations since the event set creation of es_id.

Note
This is designed for wrapper libraries mainly, to use as a mechanism for matching operations inserted into the event set with possible errors that occur.
Since
1.14.0

◆ H5ESregister_complete_func()

herr_t H5ESregister_complete_func ( hid_t  es_id,
H5ES_event_complete_func_t  func,
void *  ctx 
)

Registers a callback to invoke when an operation completes within an event set.

Parameters
[in]es_idEvent set identifier
[in]funcThe completion function to register
[in]ctxUser-specified information (context) to pass to func
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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.14.0

◆ H5ESregister_insert_func()

herr_t H5ESregister_insert_func ( hid_t  es_id,
H5ES_event_insert_func_t  func,
void *  ctx 
)

Registers a callback to invoke when a new operation is inserted into an event set.

Parameters
[in]es_idEvent set identifier
[in]funcThe insert function to register
[in]ctxUser-specified information (context) to pass to func
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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.14.0

◆ H5ESwait()

herr_t H5ESwait ( hid_t  es_id,
uint64_t  timeout,
size_t *  num_in_progress,
hbool_t err_occurred 
)

Waits for operations in event set to complete.

Parameters
[in]es_idEvent set identifier
[in]timeoutTotal time in nanoseconds to wait for all operations in the event set to complete
[out]num_in_progressThe number of operations still in progress
[out]err_occurredFlag if an operation in the event set failed
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5ESwait() waits for operations in an event set es_id to wait with 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.14.0