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
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* 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. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*
* Programmer: Quincey Koziol
* Monday, April 6, 2020
*
* Purpose: This file contains declarations which define macros for the
* H5ES package. Including this header means that the source file
* is part of the H5ES package.
*/
#ifndef H5ESmodule_H
#define H5ESmodule_H
/* Define the proper control macros for the generic FUNC_ENTER/LEAVE and error
* reporting macros.
*/
#define H5ES_MODULE
#define H5_MY_PKG H5ES
#define H5_MY_PKG_ERR H5E_EVENTSET
/** \page H5ES_UG The HDF5 Event Set
* @todo Under Construction
*
* \section sec_async The HDF5 Event Set Interface
*
* \section subsec_async_intro Introduction
* HDF5 provides asynchronous APIs for the HDF5 VOL connectors that support asynchronous HDF5
* operations using the HDF5 Event Set (H5ES) API. This allows I/O to proceed in the background
* while the application is performing other tasks.
*
* To support AIO capabilities for the HDF5 VOL connectors, the AIO versions for the functions
* listed in the table below were added to HDF5 library version 1.14.0 and later. The async version
* of the function has “_async” suffix added to the function name. For example, the async version
* for H5Fcreate is H5Fcreate_async.
*
* <table>
* <tr>
* <th>Interface</th>
* <th>Functions</th>
* </tr>
* <tr>
* <th>H5F</th>
* <td>#H5Fcreate, #H5Fflush, #H5Fis_accessible, #H5Fopen, #H5Fclose
* </td>
* </tr>
* <tr>
* <th>H5G</th>
* <td>#H5Gcreate, #H5Gget_info, #H5Gget_info_by_idx, #H5Gget_info_by_name, #H5Gclose
* </td>
* </tr>
* <tr>
* <th>H5D</th>
* <td>#H5Dcreate, #H5Dopen, #H5Dset_extent, #H5Dwrite, #H5Dread, #H5Dget_space, #H5Dclose
* </td>
* </tr>
* <tr>
* <th>H5A</th>
* <td>#H5Acreate, #H5Acreate_by_name, #H5Aopen, #H5Aopen_by_name, #H5Aexists, #H5Awrite, #H5Aread,
#H5Aclose, #H5Aopen_by_idx, #H5Arename, #H5Arename_by_name
* </td>
* </tr>
* <tr>
* <th>H5L</th>
* <td>#H5Lcreate_hard, #H5Lcreate_soft, #H5Ldelete, #H5Ldelete_by_idx, #H5Lexists
* </td>
* </tr>
* <tr>
* <th>H5O</th>
* <td>#H5Ocopy, #H5Orefresh, #H5Oflush, #H5Oclose, #H5Oopen, #H5Oopen_by_idx
* </td>
* </tr>
* <tr>
* <th>H5R</th>
* <td>#H5Ropen_attr, #H5Ropen_object #H5Ropen_region, #H5Rdereference
* </td>
* </tr>
* <tr>
* <th>H5M</th>
* <td>#H5Mcreate, #H5Mopen, #H5Mput, #H5Mget, #H5Mclose
* </td>
* </tr>
* <tr>
* <th>H5T</th>
* <td>#H5Tcommit, #H5Topen, #H5Tcopy, #H5Tclose
* </td>
* </tr>
* </table>
*
* Async versions of the functions have an extra parameter called the event set parameter or es_id.
* For example, compare the signatures of #H5Dclose and #H5Dclose_async:
* \code
* herr_t H5Dclose(hid_t dset_id);
* herr_t H5Dclose_async(hid_t dset_id, hid_t es_id);
* \endcode
*
* An event set is an in-memory object that is created by an application and used to track many
* asynchronous operations with a single object. They function like a "bag" -- holding request
* tokens from one or more asynchronous operations and provide a simple interface for inspecting
* the status of the entire set of operations.
*
* See the \ref H5ES APIs that were added to the HDF5 library to manage event sets.
*
* Previous Chapter \ref sec_vol - Next Chapter \ref sec_map
*
*/
/**\defgroup H5ES Event Set Interface (H5ES)
*
* \todo Add the event set life cycle.
*
* \brief Event Set Interface
*
* \details \Bold{This interface can be only 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:
* - ASYNC
* - DAOS
*
* \par Example:
* \code
* 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.
* \endcode
*/
#endif /* H5ESmodule_H */
|
