summaryrefslogtreecommitdiffstats
path: root/doxygen/examples/H5I_examples.c
blob: 4aa47831b8821cd216a7a4f90ff1df94b51f6bff (plain)
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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
/* -*- c-file-style: "stroustrup" -*- */

#include "hdf5.h"

#include <assert.h>
#include <stdio.h>
#include <stdlib.h>

int
main(void)
{
    int ret_val = EXIT_SUCCESS;

    //! <!-- [create] -->
    {
        __label__ fail_dcpl;
        hid_t dcpl;

        // create an ID of a pre-defined ID type
        if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) {
            ret_val = EXIT_FAILURE;
            goto fail_dcpl;
        }

        // we can reliably predict the ID type
        assert(H5Iget_type(dcpl) == H5I_GENPROP_LST);
        printf("%d\n", H5Iget_type(dcpl));

        H5Pclose(dcpl);
fail_dcpl:;
    }
    //! <!-- [create] -->

    //! <!-- [read] -->
    {
        __label__ fail_dcpl;
        hid_t dcpl;

        // create an ID of a pre-defined ID type
        if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) {
            ret_val = EXIT_FAILURE;
            goto fail_dcpl;
        }

        // this better be valid
        assert(H5Iis_valid(dcpl) > 0);

        // this ID is NOT associated with any HDF5 file;
        // see the error message
        assert(H5Iget_file_id(dcpl) == H5I_INVALID_HID);

        H5Pclose(dcpl);
fail_dcpl:;
    }
    //! <!-- [read] -->

    //! <!-- [update] -->
    {
        __label__ fail_rc, fail_dcpl;
        hid_t dcpl;
        int   rc;

        // create an ID of a pre-defined ID type
        if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) {
            ret_val = EXIT_FAILURE;
            goto fail_dcpl;
        }

        // retrieve the IDs reference count
        if ((rc = H5Iget_ref(dcpl)) < 0) {
            ret_val = EXIT_FAILURE;
            goto fail_rc;
        }
        printf("Reference count: %d\n", rc);

        // bump its reference count (by 1)
        if ((rc = H5Iinc_ref(dcpl)) < 0) {
            ret_val = EXIT_FAILURE;
            goto fail_rc;
        }
        printf("Reference count: %d\n", rc);

fail_rc:
        H5Pclose(dcpl);
fail_dcpl:;
    }
    //! <!-- [update] -->

    //! <!-- [delete] -->
    {
        __label__ fail_rc, fail_dcpl;
        hid_t dcpl;
        int   rc;

        // create an ID of a pre-defined ID type
        if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) {
            ret_val = EXIT_FAILURE;
            goto fail_dcpl;
        }

        // decrease its reference count (from 1) to 0
        if ((rc = H5Idec_ref(dcpl)) < 0) {
            ret_val = EXIT_FAILURE;
            goto fail_rc;
        }
        printf("Reference count: %d\n", rc);

        // at this point, the ID is no longer valid
        assert(H5Iis_valid(dcpl) == 0);

        // dropping the ref. count to 0 has the side-effect of closing
        // the associated item, and calling H5Pclose would create an error
        goto fail_dcpl;

fail_rc:
        H5Pclose(dcpl);
fail_dcpl:;
    }
    //! <!-- [delete] -->

    //! <!-- [create_ud] -->
    herr_t free_func(void *obj)
    {
        printf("Calling free_func...\n");
        H5free_memory(obj);
        return 0;
    }

    {
        __label__ fail_id, fail_obj, fail_register;
        H5I_type_t type;
        int *      obj;
        hid_t      obj_id;

        // register a new ID type
        if ((type = H5Iregister_type(128, 1024, &free_func)) < 0) {
            ret_val = EXIT_FAILURE;
            goto fail_register;
        }
        printf("New identifier type ID: %d\n", type);

        // create a new object
        if ((obj = H5allocate_memory(10 * sizeof(int), 0)) == NULL) {
            ret_val = EXIT_FAILURE;
            goto fail_obj;
        }

        // obtain an ID for the new object
        if ((obj_id = H5Iregister(type, obj)) == H5I_INVALID_HID) {
            ret_val = EXIT_FAILURE;
            goto fail_id;
        }
        printf("New object identifier: %ld\n", obj_id);

fail_id:
        H5Iclear_type(type, 1);
fail_obj:
        H5Idestroy_type(type);
fail_register:;
    }
    //! <!-- [create_ud] -->

    //! <!-- [read_ud] -->
    {
        __label__ fail_query, fail_register;
        H5I_type_t type;
        hsize_t    count;

        // register a new ID type
        if ((type = H5Iregister_type(128, 1024, NULL)) < 0) {
            ret_val = EXIT_FAILURE;
            goto fail_register;
        }
        printf("New FOO identifier type ID: %d\n", type);

        // return the number of identifiers of TYPE currently in use
        if (H5Inmembers(type, &count) < 0) {
            ret_val = EXIT_FAILURE;
            goto fail_query;
        }
        printf("%llu FOO identifiers in use\n", count);

fail_query:
        H5Idestroy_type(type);
fail_register:;
    }
    //! <!-- [read_ud] -->

    //! <!-- [update_ud] -->
    {
        __label__ fail_id, fail_register;
        H5I_type_t type;
        int        obj = 42;
        hid_t      obj_id;

        // register a new ID type
        if ((type = H5Iregister_type(128, 1024, NULL)) < 0) {
            ret_val = EXIT_FAILURE;
            goto fail_register;
        }
        printf("New identifier type ID: %d\n", type);

        // obtain an ID for the new object
        if ((obj_id = H5Iregister(type, &obj)) == H5I_INVALID_HID) {
            ret_val = EXIT_FAILURE;
            goto fail_id;
        }
        printf("New object identifier: %ld\n", obj_id);

        // bump the reference count
        assert(H5Iinc_ref(obj_id) == 2);

        // force the deletion of all IDs regardless of reference count
        H5Iclear_type(type, 1);
fail_id:
        H5Idestroy_type(type);
fail_register:;
    }
    //! <!-- [update_ud] -->

    //! <!-- [delete_ud] -->
    {
        __label__ fail_register;
        H5I_type_t type;

        // register a new ID type
        if ((type = H5Iregister_type(128, 1024, NULL)) < 0) {
            ret_val = EXIT_FAILURE;
            goto fail_register;
        }
        printf("New identifier type ID: %d\n", type);

        // decrementing the identifier type's ref. count to 0 triggers
        // the type to be destroyed
        assert(H5Idec_type_ref(type) == 0);

fail_register:;
    }
    //! <!-- [delete_ud] -->

    return ret_val;
}