diff options
Diffstat (limited to 'src/H5Ipublic.h')
| -rw-r--r-- | src/H5Ipublic.h | 93 |
1 files changed, 92 insertions, 1 deletions
diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h index 3912252..0075018 100644 --- a/src/H5Ipublic.h +++ b/src/H5Ipublic.h @@ -50,6 +50,7 @@ typedef enum H5I_type_t { H5I_ERROR_MSG, /**< type ID for error messages */ H5I_ERROR_STACK, /**< type ID for error stacks */ H5I_SPACE_SEL_ITER, /**< type ID for dataspace selection iterator */ + H5I_EVENTSET, /**< type ID for event sets */ H5I_NTYPES /**< number of library types, MUST BE LAST! */ } H5I_type_t; @@ -96,6 +97,20 @@ typedef int (*H5I_search_func_t)(void *obj, hid_t id, void *key); typedef herr_t (*H5I_iterate_func_t)(hid_t id, void *udata); //! [H5I_iterate_func_t_snip] +/** + * The type of the realize_cb callback for H5Iregister_future + */ +//! [H5I_future_realize_func_t_snip] +typedef herr_t (*H5I_future_realize_func_t)(void *future_object, hid_t *actual_object_id); +//! [H5I_future_realize_func_t_snip] + +/** + * The type of the discard_cb callback for H5Iregister_future + */ +//! [H5I_future_discard_func_t_snip] +typedef herr_t (*H5I_future_discard_func_t)(void *future_object); +//! [H5I_future_discard_func_t_snip] + #ifdef __cplusplus extern "C" { #endif @@ -112,7 +127,7 @@ extern "C" { * * \return \hid_t{object} * - * \details H5Iregister() allocates and returns a new ID for an object. + * \details H5Iregister() creates and returns a new ID for an object. * * \details The \p type parameter is the identifier for the ID type to which * this new ID will belong. This identifier must have been created by @@ -127,6 +142,82 @@ H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); /** * \ingroup H5I * + * \brief Registers a "future" object under a type and returns an ID for it + * + * \param[in] type The identifier of the type of the new ID + * \param[in] object Pointer to "future" object for which a new ID is created + * \param[in] realize_cb Function pointer to realize a future object + * \param[in] discard_cb Function pointer to destroy a future object + * + * \return \hid_t{object} + * + * \details H5Iregister_future() creates and returns a new ID for a "future" object. + * Future objects are a special kind of object and represent a + * placeholder for an object that has not yet been created or opened. + * The \p realize_cb will be invoked by the HDF5 library to 'realize' + * the future object as an actual object. A call to H5Iobject_verify() + * will invoke the \p realize_cb callback and if it successfully + * returns, will return the actual object, not the future object. + * + * \details The \p type parameter is the identifier for the ID type to which + * this new future ID will belong. This identifier may have been created + * by a call to H5Iregister_type() or may be one of the HDF5 pre-defined + * ID classes (e.g. H5I_FILE, H5I_GROUP, H5I_DATASPACE, etc). + * + * \details The \p object parameter is a pointer to the memory which the new ID + * will be a reference to. This pointer will be stored by the library, + * but will not be returned to a call to H5Iobject_verify() until the + * \p realize_cb callback has returned the actual pointer for the object. + * + * A NULL value for \p object is allowed. + * + * \details The \p realize_cb parameter is a function pointer that will be + * invoked by the HDF5 library to convert a future object into an + * actual object. The \realize_cb function may be invoked by + * H5Iobject_verify() to return the actual object for a user-defined + * ID class (i.e. an ID class registered with H5Iregister_type()) or + * internally by the HDF5 library in order to use or get information + * from an HDF5 pre-defined ID type. For example, the \p realize_cb + * for a future dataspace object will be called during the process + * of returning information from H5Sget_simple_extent_dims(). + * + * Note that although the \p realize_cb routine returns + * an ID (as a parameter) for the actual object, the HDF5 library + * will swap the actual object in that ID for the future object in + * the future ID. This ensures that the ID value for the object + * doesn't change for the user when the object is realized. + * + * Note that the \p realize_cb callback could receive a NULL value + * for a future object pointer, if one was used when H5Iregister_future() + * was initially called. This is permitted as a means of allowing + * the \p realize_cb to act as a generator of new objects, without + * requiring creation of unnecessary future objects. + * + * It is an error to pass NULL for \p realize_cb. + * + * \details The \p discard_cb parameter is a function pointer that will be + * invoked by the HDF5 library to destroy a future object. This + * callback will always be invoked for _every_ future object, whether + * the \p realize_cb is invoked on it or not. It's possible that + * the \p discard_cb is invoked on a future object without the + * \p realize_cb being invoked, e.g. when a future ID is closed without + * requiring the future object to be realized into an actual one. + * + * Note that the \p discard_cb callback could receive a NULL value + * for a future object pointer, if one was used when H5Iregister_future() + * was initially called. + * + * It is an error to pass NULL for \p discard_cb. + * + * \note The H5Iregister_future() function is primarily targeted at VOL connector + * authors and is _not_ designed for general-purpose application use. + * + */ +H5_DLL hid_t H5Iregister_future(H5I_type_t type, const void *object, H5I_future_realize_func_t realize_cb, + H5I_future_discard_func_t discard_cb); +/** + * \ingroup H5I + * * \brief Returns the object referenced by an ID * * \param[in] id ID to be dereferenced |