A batch of life-cycle examples for different modules (#654)

* Create a tag file for permalinks.

* Added DOXYGEN_TAG_FILE.

* Added Doxygen life-cycle examples for different modules.

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

1 files changed, 80 insertions, 1 deletions

diff --git a/doxygen/examples/H5D_examples.c b/doxygen/examples/H5D_examples.c
index aad057d..4e54c1d 100644
--- a/doxygen/examples/H5D_examples.c
+++ b/doxygen/examples/H5D_examples.c
@@ -5,6 +5,86 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+//! <!-- [H5Dchunk_iter_cb] -->
+int
+chunk_cb(const hsize_t *offset, uint32_t filter_mask, haddr_t addr, uint32_t nbytes, void *op_data)
+{
+    // only print the allocated chunk size only
+    printf("%d\n", nbytes);
+    return EXIT_SUCCESS;
+}
+//! <!-- [H5Dchunk_iter_cb] -->
+
+//! <!-- [H5Ovisit_cb] -->
+herr_t
+H5Ovisit_cb(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data)
+{
+    herr_t retval    = 0;
+    char * base_path = (char *)op_data;
+
+    if (info->type == H5O_TYPE_DATASET) // current object is a dataset
+    {
+        hid_t dset, dcpl;
+        if ((dset = H5Dopen(obj, name, H5P_DEFAULT)) == H5I_INVALID_HID) {
+            retval = -1;
+            goto func_leave;
+        }
+        if ((dcpl = H5Dget_create_plist(dset)) == H5I_INVALID_HID) {
+            retval = -1;
+            goto fail_dcpl;
+        }
+        if (H5Pget_layout(dcpl) == H5D_CHUNKED) // dataset is chunked
+        {
+            __label__ fail_dtype, fail_dspace, fail_shape;
+            hid_t   dspace, dtype;
+            size_t  size, i;
+            int     rank;
+            hsize_t cdims[H5S_MAX_RANK];
+
+            // get resources
+            if ((dtype = H5Dget_type(dset)) < 0) {
+                retval = -1;
+                goto fail_dtype;
+            }
+            if ((dspace = H5Dget_space(dset)) < 0) {
+                retval = -1;
+                goto fail_dspace;
+            }
+            // get the shape
+            if ((size = H5Tget_size(dtype)) == 0 || (rank = H5Sget_simple_extent_ndims(dspace)) < 0 ||
+                H5Pget_chunk(dcpl, H5S_MAX_RANK, cdims) < 0) {
+                retval = -1;
+                goto fail_shape;
+            }
+            // calculate the nominal chunk size
+            size = 1;
+            for (i = 0; i < (size_t)rank; ++i)
+                size *= cdims[i];
+            // print dataset info
+            printf("%s%s : nominal chunk size %lu [B] \n", base_path, name, size);
+            // get the allocated chunk sizes
+            if (H5Dchunk_iter(dset, H5P_DEFAULT, &chunk_cb, NULL) < 0) {
+                retval = -1;
+                goto fail_fig;
+            }
+
+fail_shape:
+            H5Sclose(dspace);
+fail_dspace:
+            H5Tclose(dtype);
+fail_dtype:;
+        }
+
+        H5Pclose(dcpl);
+fail_dcpl:
+        H5Dclose(dset);
+    }
+
+func_leave:
+    return retval;
+}
+//! <!-- [H5Ovisit_cb] -->
+
 int
 main(void)
 {
@@ -166,7 +246,6 @@ fail_delete:
         H5Fclose(file);
 fail_file:;
     }
-
     //! <!-- [delete] -->
 
     return ret_val;