Adding a new API function to get the number of revisions for an onion file (#1692)

* Removes unused definitions from module headers (#1624)

* Fix these Doxygen warnings #1581 (#1589)

* Fixes a typo in H5.c (#1639)

* free MPI_Group/MPI_Comm/MPI_Datatype objects (#1638)

* free MPI_Group/MPI_Comm/MPI_Datatype objects

* fix clang-format style

* Adds build and license shields to README.md (#1641)

* First stab at a Github status bar

* Adds a .tokeignore file for counting lines of code accurately

* Yanks lines of code calculation since it wildly overcounts

* not depend on doIO to free an MPI_Comm object (#1642)

* free MPI datatypes previously created (#1637)

* Retrieve MPI-IO hints used by MPI library after file open (#1636)

H5Pget_fapl_mpio() should return an MPI info object containing all the
MPI-IO hints used by the MPI library underneath, after the file is
opened. Some hints, such as cb_nodes (number of I/O aggregators), are
useful for HDF5 applications and I/O libraries built on top of HDF5.

* OESS-168: Remove clang warnings. (#1309)

* OESS-168: Remove clang warnings.

* OESS-168: Address @lrknox review.

* OESS-168: Remove clang warnings. (#1376)

* Adding a new API function to get the number of revisions for an onion file. This function uses H5FD_ctl().

* Committing clang-format changes

* Removed a few unused variables.

* Modified the way that the API function H5FDget_onion_revision_count is organized and added Doxygen comments for the three API functions.

* Committing clang-format changes

* Minor changes: modified some Doxygen comments.

Co-authored-by: Dana Robinson <43805+derobins@users.noreply.github.com>
Co-authored-by: Allen Byrne <50328838+byrnHDF@users.noreply.github.com>
Co-authored-by: Wei-keng Liao <wkliao@users.noreply.github.com>
Co-authored-by: H. Joe Lee <hyoklee@hdfgroup.org>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

4 files changed, 122 insertions, 25 deletions

diff --git a/src/H5FDonion.c b/src/H5FDonion.c
index f8ef824..a7a6fe8 100644
--- a/src/H5FDonion.c
+++ b/src/H5FDonion.c
@@ -147,6 +147,8 @@ H5FL_DEFINE_STATIC(H5FD_onion_t);
 /* 2^n for uint64_t types -- H5_EXP2 unsafe past 32 bits */
 #define U64_EXP2(n) ((uint64_t)1 << (n))
 
+#define H5FD_CTL__GET_NUM_REVISIONS 20001
+
 /* Prototypes */
 static herr_t  H5FD__onion_close(H5FD_t *);
 static haddr_t H5FD__onion_get_eoa(const H5FD_t *, H5FD_mem_t);
@@ -170,6 +172,7 @@ static herr_t  H5FD__onion_sb_decode(H5FD_t *_file, const char *name, const unsi
 static hsize_t H5FD__onion_sb_size(H5FD_t *_file);
 static herr_t  H5FD__onion_ctl(H5FD_t *_file, uint64_t op_code, uint64_t flags,
                                const void H5_ATTR_UNUSED *input, void H5_ATTR_UNUSED **output);
+static herr_t  H5FD__get_onion_revision_count(H5FD_t *file, size_t *revision_count);
 
 static const H5FD_class_t H5FD_onion_g = {
     H5FD_CLASS_VERSION,             /* struct version       */
@@ -351,6 +354,66 @@ done:
     FUNC_LEAVE_API(ret_value)
 } /* end H5Pset_fapl_onion() */
 
+herr_t
+H5FDget_onion_revision_count(const char *filename, hid_t fapl_id, size_t *revision_count)
+{
+    H5P_genplist_t *plist        = NULL;
+    herr_t          ret_value    = SUCCEED;
+    H5FD_t *        file_drv_ptr = NULL;
+    FUNC_ENTER_API(FAIL)
+
+    /* Check the file name */
+    if (!filename || !HDstrcmp(filename, ""))
+        HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a valid file name")
+
+    /* Make sure using the correct driver */
+    if (NULL == (plist = H5P_object_verify(fapl_id, H5P_FILE_ACCESS)))
+        HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a valid FAPL ID")
+
+    if (H5FD_ONION != H5P_peek_driver(plist))
+        HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a Onion VFL driver")
+
+    if (!revision_count)
+        HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "revision count can't be null")
+
+    /* Open the file with the driver */
+    if (NULL == (file_drv_ptr = H5FD_open(filename, H5F_ACC_RDONLY, fapl_id, HADDR_UNDEF)))
+        HGOTO_ERROR(H5E_VFL, H5E_CANTOPENFILE, FAIL, "unable to open file with onion driver")
+
+    /* Call the private function */
+    if (H5FD__get_onion_revision_count(file_drv_ptr, revision_count) < 0)
+        HGOTO_ERROR(H5E_VFL, H5E_CANTGET, FAIL, "failed to get the number of revisions")
+
+    /* Close H5FD_t structure pointer */
+    if (H5FD_close(file_drv_ptr) < 0)
+        HGOTO_ERROR(H5E_VFL, H5E_CANTCLOSEFILE, FAIL, "unable to close file")
+
+    file_drv_ptr = NULL;
+
+done:
+    FUNC_LEAVE_API(ret_value)
+}
+
+static herr_t
+H5FD__get_onion_revision_count(H5FD_t *file, size_t *revision_count)
+{
+    herr_t   ret_value = SUCCEED;
+    uint64_t op_code;
+    uint64_t flags;
+
+    FUNC_ENTER_PACKAGE
+
+    op_code = H5FD_CTL__GET_NUM_REVISIONS;
+    flags   = H5FD_CTL__FAIL_IF_UNKNOWN_FLAG;
+
+    /* Call private function */
+    if (H5FD_ctl(file, op_code, flags, NULL, (void **)&revision_count) < 0)
+        HGOTO_ERROR(H5E_VFL, H5E_FCNTL, FAIL, "VFD ctl request failed")
+
+done:
+    FUNC_LEAVE_NOAPI(ret_value)
+}
+
 /*-------------------------------------------------------------------------
  * Function:    H5FD__onion_sb_size
  *
diff --git a/src/H5FDonion.h b/src/H5FDonion.h
index 0e45b80..bca6526 100644
--- a/src/H5FDonion.h
+++ b/src/H5FDonion.h
@@ -128,10 +128,61 @@ typedef struct H5FD_onion_fapl_info_t {
 extern "C" {
 #endif
 
-H5_DLL hid_t  H5FD_onion_init(void);
+H5_DLL hid_t H5FD_onion_init(void);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5P
+ *
+ * \brief get the onion info from the file access property list
+ *
+ * \param[in] fapl_id The ID of the file access property list
+ * \param[out] fa_out The pointer to the structure H5FD_onion_fapl_info_t
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_fapl_onion() retrieves the structure H5FD_onion_fapl_info_t
+ *          from the file access property list that is set for the onion VFD
+ *          driver.
+ */
 H5_DLL herr_t H5Pget_fapl_onion(hid_t fapl_id, H5FD_onion_fapl_info_t *fa_out);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5P
+ *
+ * \brief set the onion info for the file access property list
+ *
+ * \param[in] fapl_id The ID of the file access property list
+ * \param[in] fa The pointer to the structure H5FD_onion_fapl_info_t
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_fapl_onion() sets the structure H5FD_onion_fapl_info_t
+ *          for the file access property list that is set for the onion VFD
+ *          driver.
+ */
 H5_DLL herr_t H5Pset_fapl_onion(hid_t fapl_id, const H5FD_onion_fapl_info_t *fa);
 
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5FD
+ *
+ * \brief get the number of revisions
+ *
+ * \param[in] filename The name of the onion file
+ * \param[in] fapl_id The ID of the file access property list
+ * \param[out] revision_count The number of revisions
+ *
+ * \return \herr_t
+ *
+ * \details H5FDget_onion_revision_count() returns the number of revisions
+ *          for an onion file. It takes the file name and file access property
+ *          list that is set for the onion VFD driver.
+ *
+ */
+H5_DLL herr_t H5FDget_onion_revision_count(const char *filename, hid_t fapl_id, size_t *revision_count);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/src/H5FDpublic.h b/src/H5FDpublic.h
index bd748f6..f8f88f3 100644
--- a/src/H5FDpublic.h
+++ b/src/H5FDpublic.h
@@ -197,7 +197,6 @@
 #define H5FD_CTL__MEM_ALLOC                   5
 #define H5FD_CTL__MEM_FREE                    6
 #define H5FD_CTL__MEM_COPY                    7
-#define H5FD_CTL__GET_NUM_REVISIONS           8
 
 /* ctl function flags: */
 
diff --git a/test/onion.c b/test/onion.c
index a8c0491..6722191 100644
--- a/test/onion.c
+++ b/test/onion.c
@@ -4073,10 +4073,10 @@ test_integration_ctl(void)
         0,               /* creation flags, was H5FD_ONION_FAPL_INFO_CREATE_FLAG_ENABLE_PAGE_ALIGNMENT */
         "initial commit" /* comment */
     };
-    H5FD_t *  file_drv_ptr = NULL;
-    uint64_t  op_code;
-    uint64_t  flags;
-    uint64_t *num_revisions = NULL;
+    H5FD_t * file_drv_ptr = NULL;
+    uint64_t op_code;
+    uint64_t flags;
+    size_t   revision_count;
 
     TESTING("onion-created HDF5 file with revisions testing H5FDctl");
 
@@ -4182,28 +4182,13 @@ test_integration_ctl(void)
     file = H5I_INVALID_HID;
 
     /*----------------------------------------------------------------------
-     *  Start to verify the revision
+     *  Start to verify the number of revisions
      *----------------------------------------------------------------------
      */
-
-    if (NULL == (file_drv_ptr = H5FDopen(basename, H5F_ACC_RDONLY, fapl_id, HADDR_UNDEF)))
+    if (H5FDget_onion_revision_count(basename, fapl_id, &revision_count) < 0)
         TEST_ERROR
 
-    if (NULL == (num_revisions = HDmalloc(sizeof(uint64_t))))
-        TEST_ERROR
-    op_code = H5FD_CTL__GET_NUM_REVISIONS;
-    flags   = H5FD_CTL__FAIL_IF_UNKNOWN_FLAG;
-
-    if (H5FDctl(file_drv_ptr, op_code, flags, NULL, (void **)&num_revisions) < 0)
-        TEST_ERROR
-
-    if (*num_revisions != 2) {
-        HDprintf("the number of revisions should be 2 but got %" PRIu64 "\n", *num_revisions);
-        TEST_ERROR
-    }
-
-    /* Close H5FD_t structure pointer */
-    if (H5FDclose(file_drv_ptr) < 0)
+    if (2 != revision_count)
         TEST_ERROR
 
     /* Close and release resources */
@@ -4213,7 +4198,6 @@ test_integration_ctl(void)
         TEST_ERROR
     if (H5Sclose(space) < 0)
         TEST_ERROR
-    HDfree(num_revisions);
 
     HDremove(paths->canon);
     HDremove(paths->onion);