VOL refactor and cleanup (HDFGroup#4856)

Cleanup and prepare for thread-safety changes. Big ideas: * Wrap H5VL_class_t with H5VL_connector_t, so use of the class can be refcounted within the H5VL package, instead of relying on storing an ID within the H5VL_t struct and incrementing & decrementing the ID's refcount. * Register H5VL_connector_t* for VOL connector IDs, instead of the H5VL_class_t* * Stop other packages from rummaging around inside H5VL_connector_t and H5VL_object_t data structures, so that the H5VL package can change implementation details without coupled changes throughout the library Small things: * Simplified the coding for creating links * Moved some routines into more logical locations
qkoziol · Oct 3, 2024 · 767282f · 767282f
1 parent 626f639
commit 767282f
Show file tree

Hide file tree

Showing 69 changed files with 2,405 additions and 2,080 deletions.
diff --git a/doxygen/dox/VOLConnGuide.dox b/doxygen/dox/VOLConnGuide.dox
@@ -4110,62 +4110,6 @@ Retrieves a pointer to the VOL object from an HDF5 file or object identifier.
 Returns a copy of the <em>dtype_id</em> parameter but with the location set to be in the file. Returns a negative
 value (#H5I_INVALID_HID) on errors.
 
-\subsubsection subsubsecVOLNewConnpeek_name H5VLpeek_connector_id_by_name
-<table>
-<tr>
-<th>Signature:</th>
-</tr>
-<tr>
-<td>
-\code
-  hid_t H5VLpeek_connector_id_by_name(const char *name);
-\endcode
-</td>
-</tr>
-<tr>
-<th>Arguments:</th>
-</tr>
-<tr>
-<td>
-\code
-  name (IN): name of the connector to query.
-\endcode
-</td>
-</tr>
-</table>
-Retrieves the ID for a registered VOL connector based on a connector name. This is done without duplicating
-the ID and transferring ownership to the caller (as it normally the case in the HDF5 library). The ID returned
-from this operation should not be closed. This is intended for use by VOL connectors to find their own ID.
-Returns a negative value (#H5I_INVALID_HID) on errors.
-
-\subsubsection subsubsecVOLNewConnpeek_value H5VLpeek_connector_id_by_value
-<table>
-<tr>
-<th>Signature:</th>
-</tr>
-<tr>
-<td>
-\code
-  hid_t H5VLpeek_connector_id_by_value(H5VL_class_value_t value);
-\endcode
-</td>
-</tr>
-<tr>
-<th>Arguments:</th>
-</tr>
-<tr>
-<td>
-\code
-  value (IN): value of the connector to query.
-\endcode
-</td>
-</tr>
-</table>
-Retrieves the ID for a registered VOL connector based on a connector value. This is done without duplicating
-the ID and transferring ownership to the caller (as it normally the case in the HDF5 library). The ID returned
-from this operation should not be closed. This is intended for use by VOL connectors to find their own ID.
-Returns a negative value (#H5I_INVALID_HID) on errors.
-
 \subsection subsecVOLNewPass H5VLconnector_passthru.h
 This functionality is intended for VOL connector authors who are writing pass-through connectors and
 includes helper functions that are useful for writing such connectors. Callback equivalent functions can be

diff --git a/fortran/src/H5VLff.F90 b/fortran/src/H5VLff.F90
@@ -401,6 +401,41 @@ END FUNCTION H5VLunregister_connector
 
   END SUBROUTINE H5VLunregister_connector_f
 
+!>
+!! \ingroup FH5VL
+!!
+!! \brief Determines whether two connector identifiers refer to the same connector.
+!!
+!! \param conn_id1 A valid identifier of the first connector to check
+!! \param conn_id2 A valid identifier of the second connector to check
+!! \param are_same Whether connector IDs refer to the same connector
+!! \param hdferr    \fortran_error
+!!
+!! See C API: @ref H5VLcmp_connector_cls()
+!!
+  SUBROUTINE H5VLcmp_connector_cls_f(are_same, conn_id1, conn_id2, hdferr)
+    IMPLICIT NONE
+    LOGICAL, INTENT(OUT) :: are_same
+    INTEGER(HID_T), INTENT(IN) :: conn_id1
+    INTEGER(HID_T), INTENT(IN) :: conn_id2
+    INTEGER, INTENT(OUT) :: hdferr
+    INTEGER :: are_same_c
+
+    INTERFACE
+       INTEGER(C_INT) FUNCTION H5VLcmp_connector_cls(cmp_value, conn_id1, conn_id2) BIND(C, NAME='H5VLcmp_connector_cls')
+         IMPORT :: HID_T, C_INT
+         INTEGER(C_INT), INTENT(OUT) :: cmp_value
+         INTEGER(HID_T), VALUE :: conn_id1
+         INTEGER(HID_T), VALUE :: conn_id2
+       END FUNCTION H5VLcmp_connector_cls
+    END INTERFACE
+
+    are_same = .FALSE.
+    hdferr = INT(H5VLcmp_connector_cls(are_same_c, conn_id1, conn_id2))
+    IF(are_same_c .EQ. 0) are_same = .TRUE.
+
+  END SUBROUTINE H5VLcmp_connector_cls_f
+
 !>
 !! \ingroup FH5VL
 !!

diff --git a/fortran/src/hdf5_fortrandll.def.in b/fortran/src/hdf5_fortrandll.def.in
@@ -593,6 +593,7 @@ H5VL_mp_H5VLGET_CONNECTOR_ID_BY_NAME_F
 H5VL_mp_H5VLGET_CONNECTOR_ID_BY_VALUE_F
 H5VL_mp_H5VLGET_CONNECTOR_NAME_F
 H5VL_mp_H5VLCLOSE_F
+H5VL_mp_H5VLCMP_CONNECTOR_CLS_F
 H5VL_mp_H5VLUNREGISTER_CONNECTOR_F
 H5VL_mp_H5VLNATIVE_ADDR_TO_TOKEN_F
 H5VL_mp_H5VLNATIVE_TOKEN_TO_ADDR_F

diff --git a/fortran/test/vol_connector.F90 b/fortran/test/vol_connector.F90
@@ -160,6 +160,7 @@ SUBROUTINE test_registration_by_fapl(total_error)
     INTEGER(hid_t) :: file_id
     INTEGER(hid_t) :: fapl_id
     TYPE(C_PTR) :: f_ptr
+    LOGICAL :: are_same = .FALSE.
 
     CALL H5VLis_connector_registered_by_name_f( "FAKE_VOL_CONNECTOR_NAME", is_registered, error)
 
@@ -189,22 +190,30 @@ SUBROUTINE test_registration_by_fapl(total_error)
 
        CALL H5Pget_vol_id_f(fapl_id, vol_id_out, error)
        CALL check("H5Pget_vol_id_f",error,total_error)
-       CALL VERIFY("H5Pget_vol_id_f", vol_id_out, vol_id, total_error)
+       CALL H5VLcmp_connector_cls_f(are_same, vol_id, vol_id_out, error)
+       CALL check("H5VLcmp_connector_cls_f",error,total_error)
+       CALL VERIFY("H5VLcmp_connector_cls_f", are_same, .TRUE., total_error)
 
        f_ptr = C_NULL_PTR
        CALL H5Pset_vol_f(fapl_id, vol_id, error, f_ptr)
        CALL check("H5Pset_vol_f",error,total_error)
 
        CALL H5Pget_vol_id_f(fapl_id, vol_id_out, error)
        CALL check("H5Pget_vol_id_f",error,total_error)
-       CALL VERIFY("H5Pget_vol_id_f", vol_id_out, vol_id, total_error)
+       are_same = .FALSE.
+       CALL H5VLcmp_connector_cls_f(are_same, vol_id, vol_id_out, error)
+       CALL check("H5VLcmp_connector_cls_f",error,total_error)
+       CALL VERIFY("H5VLcmp_connector_cls_f", are_same, .TRUE., total_error)
     ENDIF
 
     CALL H5VLget_connector_id_by_name_f(NATIVE_VOL_CONNECTOR_NAME, vol_id_out, error)
     CALL check("H5VLget_connector_id_by_name_f",error,total_error)
-    CALL VERIFY("H5VLget_connector_id_by_name_f", vol_id_out, vol_id, total_error)
-    CALL H5Fcreate_f("voltest.h5",H5F_ACC_TRUNC_F, file_id, error, H5P_DEFAULT_F, fapl_id)
+    are_same = .FALSE.
+    CALL H5VLcmp_connector_cls_f(are_same, vol_id, vol_id_out, error)
+    CALL check("H5VLcmp_connector_cls_f",error,total_error)
+    CALL VERIFY("H5VLcmp_connector_cls_f", are_same, .TRUE., total_error)
 
+    CALL H5Fcreate_f("voltest.h5",H5F_ACC_TRUNC_F, file_id, error, H5P_DEFAULT_F, fapl_id)
     CALL check("H5F_create_f",error,total_error)
 
     CALL H5VLclose_f(vol_id_out, error)

diff --git a/java/src/hdf/hdf5lib/H5.java b/java/src/hdf/hdf5lib/H5.java
@@ -15497,6 +15497,24 @@ public synchronized static native String H5VLget_connector_name(long object_id)
     public synchronized static native void H5VLunregister_connector(long connector_id)
         throws HDF5LibraryException;
 
+    /**
+     * @ingroup JH5VL
+     *
+     * H5VLcmp_connector_cls Determines whether two connector identifiers refer to the same connector.
+     *
+     * @param conn_id1
+     *            IN: Identifier of connector to compare.
+     * @param conn_id2
+     *            IN: Identifier of connector to compare.
+     *
+     * @return true if the connector identifiers refer to the same connector, else false.
+     *
+     * @exception HDF5LibraryException
+     *            Error from the HDF5 Library.
+     **/
+    public synchronized static native boolean H5VLcmp_connector_cls(long conn_id1, long conn_id2)
+        throws HDF5LibraryException;
+
     // /////// unimplemented ////////
     // hid_t H5VLregister_connector(const H5VL_class_t *cls, hid_t vipl_id);
 

diff --git a/java/src/jni/h5vlImp.c b/java/src/jni/h5vlImp.c
@@ -19,6 +19,7 @@ extern "C" {
 #include "hdf5.h"
 #include "h5jni.h"
 #include "h5vlImp.h"
+#include "H5VLconnector_passthru.h"
 
 /*
  * Class:     hdf_hdf5lib_H5
@@ -272,6 +273,29 @@ Java_hdf_hdf5lib_H5_H5VLunregister_1connector(JNIEnv *env, jclass clss, jlong co
     return;
 } /* end Java_hdf_hdf5lib_H5_H5VLunregister_1connector */
 
+/*
+ * Class:     hdf_hdf5lib_H5
+ * Method:    H5VLcmp_connector_cls
+ * Signature: (JJ)Z
+ */
+JNIEXPORT jboolean JNICALL
+Java_hdf_hdf5lib_H5_H5VLcmp_1connector_1cls(JNIEnv *env, jclass clss, jlong conn_id1, jlong conn_id2)
+{
+    int      cmp_value = 0;
+    jboolean bval      = JNI_FALSE;
+    herr_t   retValue  = FAIL;
+
+    UNUSED(clss);
+
+    if ((retValue = H5VLcmp_connector_cls(&cmp_value, (hid_t)conn_id1, (hid_t)conn_id2)) < 0)
+        H5_LIBRARY_ERROR(ENVONLY);
+
+    bval = (cmp_value == 0) ? JNI_TRUE : JNI_FALSE;
+
+done:
+    return bval;
+} /* end Java_hdf_hdf5lib_H5_H5VLcmp_connector_cls */
+
 #ifdef __cplusplus
 } /* end extern "C" */
 #endif /* __cplusplus */
diff --git a/java/src/jni/h5vlImp.h b/java/src/jni/h5vlImp.h
@@ -93,6 +93,13 @@ JNIEXPORT void JNICALL Java_hdf_hdf5lib_H5_H5VLclose(JNIEnv *, jclass, jlong);
  */
 JNIEXPORT void JNICALL Java_hdf_hdf5lib_H5_H5VLunregister_1connector(JNIEnv *, jclass, jlong);
 
+/*
+ * Class:     hdf_hdf5lib_H5
+ * Method:    H5VLcmp_connector_cls
+ * Signature: (JJ)Z
+ */
+JNIEXPORT jboolean JNICALL Java_hdf_hdf5lib_H5_H5VLcmp_1connector_1cls(JNIEnv *, jclass, jlong, jlong);
+
 #ifdef __cplusplus
 } /* end extern "C" */
 #endif /* __cplusplus */

diff --git a/java/test/TestH5VL.java b/java/test/TestH5VL.java
@@ -98,7 +98,8 @@ public void testH5VLget_connector_id()
              */
             String connector = System.getenv("HDF5_VOL_CONNECTOR");
             if (connector == null)
-                assertEquals(HDF5Constants.H5VL_NATIVE, native_id);
+                assertTrue("H5.H5VLcmp_connector_cls(H5VL_NATIVE_NAME, native_id)",
+                           H5.H5VLcmp_connector_cls(HDF5Constants.H5VL_NATIVE, native_id));
         }
         catch (Throwable err) {
             err.printStackTrace();
@@ -122,7 +123,8 @@ public void testH5VLget_connector_id_by_name()
         try {
             long native_id = H5.H5VLget_connector_id_by_name(HDF5Constants.H5VL_NATIVE_NAME);
             assertTrue("H5.H5VLget_connector_id_by_name H5VL_NATIVE_NAME", native_id >= 0);
-            assertEquals(HDF5Constants.H5VL_NATIVE, native_id);
+            assertTrue("H5.H5VLcmp_connector_cls(H5VL_NATIVE_NAME, native_id)",
+                       H5.H5VLcmp_connector_cls(HDF5Constants.H5VL_NATIVE, native_id));
         }
         catch (Throwable err) {
             err.printStackTrace();
@@ -136,7 +138,8 @@ public void testH5VLget_connector_id_by_value()
         try {
             long native_id = H5.H5VLget_connector_id_by_value(HDF5Constants.H5VL_NATIVE_VALUE);
             assertTrue("H5.H5VLget_connector_id_by_value H5VL_NATIVE_VALUE", native_id >= 0);
-            assertEquals(HDF5Constants.H5VL_NATIVE, native_id);
+            assertTrue("H5.H5VLcmp_connector_cls(H5VL_NATIVE_NAME, native_id)",
+                       H5.H5VLcmp_connector_cls(HDF5Constants.H5VL_NATIVE, native_id));
         }
         catch (Throwable err) {
             err.printStackTrace();