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
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* 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 H5I (ID management) developer
* support routines.
*/
#ifndef H5Idevelop_H
#define H5Idevelop_H
/* Include package's public header */
#include "H5Ipublic.h" /* ID management */
/*****************/
/* Public Macros */
/*****************/
/*******************/
/* Public Typedefs */
/*******************/
/**
* 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] -->
/********************/
/* Public Variables */
/********************/
/*********************/
/* Public Prototypes */
/*********************/
#ifdef __cplusplus
extern "C" {
#endif
/**
* \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 \p 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);
#ifdef __cplusplus
}
#endif
#endif /* H5Idevelop_H */
|
