/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 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.13.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. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
InterfaceFunctions
H5F#H5Fcreate, #H5Fflush, #H5Fis_accessible, #H5Fopen, #H5Fclose *
H5G#H5Gcreate, #H5Gget_info, #H5Gget_info_by_idx, #H5Gget_info_by_name, #H5Gclose *
H5D#H5Dcreate, #H5Dopen, #H5Dset_extent, #H5Dwrite, #H5Dread, #H5Dget_space, #H5Dclose *
H5A#H5Acreate, #H5Acreate_by_name, #H5Aopen, #H5Aopen_by_name, #H5Aexists, #H5Awrite, #H5Aread, #H5Aclose, #H5Aopen_by_idx, #H5Arename, #H5Arename_by_name *
H5L#H5Lcreate_hard, #H5Lcreate_soft, #H5Ldelete, #H5Ldelete_by_idx, #H5Lexists *
H5O#H5Ocopy, #H5Orefresh, #H5Oflush, #H5Oclose, #H5Oopen, #H5Oopen_by_idx *
H5R#H5Ropen_attr, #H5Ropen_object #H5Ropen_region, #H5Rdereference *
H5M#H5Mcreate, #H5Mopen, #H5Mput, #H5Mget, #H5Mclose *
H5T#H5Tcommit, #H5Topen, #H5Tcopy, #H5Tclose *
* * 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.... * * ... * 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 */