diff options
Diffstat (limited to 'src/H5VL.c')
| -rw-r--r-- | src/H5VL.c | 136 |
1 files changed, 96 insertions, 40 deletions
@@ -31,8 +31,11 @@ #include "H5private.h" /* Generic Functions */ #include "H5Eprivate.h" /* Error handling */ #include "H5Iprivate.h" /* IDs */ +#include "H5Pprivate.h" /* Property lists */ #include "H5VLpkg.h" /* Virtual Object Layer */ +/* VOL connectors */ +#include "H5VLnative.h" /* Native VOL connector */ /****************/ /* Local Macros */ @@ -71,6 +74,9 @@ * Purpose: Registers a new VOL connector as a member of the virtual object * layer class. * + * VIPL_ID is a VOL initialization property list which must be + * created with H5Pcreate(H5P_VOL_INITIALIZE) (or H5P_DEFAULT). + * * Return: Success: A VOL connector ID which is good until the * library is closed or the connector is * unregistered. @@ -99,6 +105,13 @@ H5VLregister_connector(const H5VL_class_t *cls, hid_t vipl_id) if (cls->wrap_cls.get_wrap_ctx && !cls->wrap_cls.free_wrap_ctx) HGOTO_ERROR(H5E_VOL, H5E_CANTREGISTER, H5I_INVALID_HID, "VOL connector must provide free callback for object wrapping contexts when a get callback is provided") + /* Check VOL initialization property list */ + if(H5P_DEFAULT == vipl_id) + vipl_id = H5P_VOL_INITIALIZE_DEFAULT; + else + if(TRUE != H5P_isa_class(vipl_id, H5P_VOL_INITIALIZE)) + HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a VOL initialize property list") + /* Register connector */ if((ret_value = H5VL__register_connector(cls, TRUE, vipl_id)) < 0) HGOTO_ERROR(H5E_VOL, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to register VOL connector") @@ -114,6 +127,9 @@ done: * Purpose: Registers a new VOL connector as a member of the virtual object * layer class. * + * VIPL_ID is a VOL initialization property list which must be + * created with H5Pcreate(H5P_VOL_INITIALIZE) (or H5P_DEFAULT). + * * Return: Success: A VOL connector ID which is good until the * library is closed or the connector is * unregistered. @@ -136,6 +152,13 @@ H5VLregister_connector_by_name(const char *name, hid_t vipl_id) if (0 == HDstrlen(name)) HGOTO_ERROR(H5E_ARGS, H5E_UNINITIALIZED, H5I_INVALID_HID, "zero-length VOL connector name is disallowed") + /* Check VOL initialization property list */ + if(H5P_DEFAULT == vipl_id) + vipl_id = H5P_VOL_INITIALIZE_DEFAULT; + else + if(TRUE != H5P_isa_class(vipl_id, H5P_VOL_INITIALIZE)) + HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a VOL initialize property list") + /* Register connector */ if((ret_value = H5VL__register_connector_by_name(name, TRUE, vipl_id)) < 0) HGOTO_ERROR(H5E_VOL, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to register VOL connector") @@ -151,6 +174,9 @@ done: * Purpose: Registers a new VOL connector as a member of the virtual object * layer class. * + * VIPL_ID is a VOL initialization property list which must be + * created with H5Pcreate(H5P_VOL_INITIALIZE) (or H5P_DEFAULT). + * * Return: Success: A VOL connector ID which is good until the * library is closed or the connector is * unregistered. @@ -171,6 +197,13 @@ H5VLregister_connector_by_value(H5VL_class_value_t value, hid_t vipl_id) if(value < 0) HGOTO_ERROR(H5E_ARGS, H5E_UNINITIALIZED, H5I_INVALID_HID, "negative VOL connector value is disallowed") + /* Check VOL initialization property list */ + if(H5P_DEFAULT == vipl_id) + vipl_id = H5P_VOL_INITIALIZE_DEFAULT; + else + if(TRUE != H5P_isa_class(vipl_id, H5P_VOL_INITIALIZE)) + HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a VOL initialize property list") + /* Register connector */ if((ret_value = H5VL__register_connector_by_value(value, TRUE, vipl_id)) < 0) HGOTO_ERROR(H5E_VOL, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to register VOL connector") @@ -185,9 +218,9 @@ done: * * Purpose: Tests whether a VOL class has been registered or not * - * Return: >0 if the VOL class has been registered - * 0 if it is unregistered - * <0 on error (if the class is not a valid class ID) + * Return: >0 if a VOL connector with that name has been registered + * 0 if a VOL connector with that name has NOT been registered + * <0 on errors * * Programmer: Dana Robinson * June 17, 2017 @@ -216,8 +249,12 @@ done: * * Purpose: Retrieves the ID for a registered VOL connector. * - * Return: Positive if the VOL class has been registered - * Negative on error (if the class is not a valid class or not registered) + * Return: A valid VOL connector ID if a connector by that name has + * been registered. This ID will need to be closed using + * H5VLclose(). + * + * H5I_INVALID_HID on error or if a VOL connector of that + * name has not been registered. * * Programmer: Dana Robinson * June 17, 2017 @@ -245,7 +282,12 @@ done: * Function: H5VLget_connector_name * * Purpose: Returns the connector name for the VOL associated with the - * object or file ID + * object or file ID. + * + * This works like other calls where the caller must provide a + * buffer of the appropriate size for the library to fill in. + * i.e., passing in a NULL pointer for NAME will return the + * required size of the buffer. * * Return: Success: The length of the connector name * @@ -312,6 +354,9 @@ done: * this VOL connector or files which are already opened under with * this connector. * + * The native VOL connector cannot be unregistered and attempts + * to do so are considered an error. + * * Return: Success: Non-negative * * Failure: Negative @@ -321,6 +366,7 @@ done: herr_t H5VLunregister_connector(hid_t vol_id) { + hid_t native_id = H5I_INVALID_HID; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) @@ -328,13 +374,23 @@ H5VLunregister_connector(hid_t vol_id) /* Check arguments */ if(NULL == H5I_object_verify(vol_id, H5I_VOL)) - HGOTO_ERROR(H5E_VOL, H5E_BADTYPE, FAIL, "not a VOL connector") + HGOTO_ERROR(H5E_VOL, H5E_BADTYPE, FAIL, "not a VOL connector ID") + + /* For the time being, we disallow unregistering the native VOL connector */ + if(H5I_INVALID_HID == (native_id = H5VL__get_connector_id(H5VL_NATIVE_NAME, FALSE))) + HGOTO_ERROR(H5E_VOL, H5E_CANTGET, FAIL, "unable to find the native VOL connector ID") + if(vol_id == native_id) + HGOTO_ERROR(H5E_VOL, H5E_BADVALUE, FAIL, "unregistering the native VOL connector is not allowed") /* The H5VL_class_t struct will be freed by this function */ - if (H5I_dec_app_ref(vol_id) < 0) + if(H5I_dec_app_ref(vol_id) < 0) HGOTO_ERROR(H5E_VOL, H5E_CANTDEC, FAIL, "unable to unregister VOL connector") done: + if(native_id != H5I_INVALID_HID) + if(H5I_dec_ref(native_id) < 0) + HGOTO_ERROR(H5E_VOL, H5E_CANTDEC, FAIL, "unable to decrement count on native_id") + FUNC_LEAVE_API(ret_value) } /* end H5VLunregister_connector() */ @@ -344,8 +400,8 @@ done: * * Purpose: Compares two connector classes (based on their value field) * - * Note: This routine is _only_ for HDF5 VOL connector authors! It is - * _not_ part of the public API for HDF5 application developers. + * Note: This routine is _only_ for HDF5 VOL connector authors! It is + * _not_ part of the public API for HDF5 application developers. * * Return: Success: Non-negative, *cmp set to a value like strcmp * @@ -381,11 +437,11 @@ done: * Function: H5VLwrap_register * * Purpose: Wrap an internal object with a "wrap context" and register an - * hid_t for the resulting object. + * hid_t for the resulting object. * - * Note: This routine is mainly targeted toward wrapping objects for - * iteration routine callbacks (i.e. the callbacks from H5Aiterate*, - * H5Literate* / H5Lvisit*, and H5Ovisit* ). + * Note: This routine is mainly targeted toward wrapping objects for + * iteration routine callbacks (i.e. the callbacks from H5Aiterate*, + * H5Literate* / H5Lvisit*, and H5Ovisit* ). * * Return: Success: Non-negative hid_t for the object. * Failure: Negative (H5I_INVALID_HID) @@ -420,10 +476,10 @@ done: * Function: H5VLobject * * Purpose: Retrieve the object pointer associated with an hid_t for a. - * VOL object. + * VOL object. * - * Note: This routine is mainly targeted toward unwrapping objects for - * testing. + * Note: This routine is mainly targeted toward unwrapping objects for + * testing. * * Return: Success: Object pointer * Failure: NULL @@ -451,16 +507,16 @@ done: * Function: H5VLretrieve_lib_state * * Purpose: Retrieves a copy of the internal state of the HDF5 library, - * so that it can be restored later. + * so that it can be restored later. * - * Note: This routine is _only_ for HDF5 VOL connector authors! It is - * _not_ part of the public API for HDF5 application developers. + * Note: This routine is _only_ for HDF5 VOL connector authors! It is + * _not_ part of the public API for HDF5 application developers. * * Return: Success: Non-negative, *state set * Failure: Negative, *state unset * - * Programmer: Quincey Koziol - * Thursday, January 10, 2019 + * Programmer: Quincey Koziol + * Thursday, January 10, 2019 * *--------------------------------------------------------------------------- */ @@ -491,14 +547,14 @@ done: * * Purpose: Restores the internal state of the HDF5 library. * - * Note: This routine is _only_ for HDF5 VOL connector authors! It is - * _not_ part of the public API for HDF5 application developers. + * Note: This routine is _only_ for HDF5 VOL connector authors! It is + * _not_ part of the public API for HDF5 application developers. * * Return: Success: Non-negative * Failure: Negative * - * Programmer: Quincey Koziol - * Thursday, January 10, 2019 + * Programmer: Quincey Koziol + * Thursday, January 10, 2019 * *--------------------------------------------------------------------------- */ @@ -528,20 +584,20 @@ done: * Function: H5VLreset_lib_state * * Purpose: Resets the internal state of the HDF5 library, undoing the - * affects of H5VLrestore_lib_state. + * affects of H5VLrestore_lib_state. * - * Note: This routine is _only_ for HDF5 VOL connector authors! It is - * _not_ part of the public API for HDF5 application developers. + * Note: This routine is _only_ for HDF5 VOL connector authors! It is + * _not_ part of the public API for HDF5 application developers. * - * Note: This routine must be called as a "pair" with - * H5VLrestore_lib_state. It can be called before / after / - * independently of H5VLfree_lib_state. + * Note: This routine must be called as a "pair" with + * H5VLrestore_lib_state. It can be called before / after / + * independently of H5VLfree_lib_state. * * Return: Success: Non-negative * Failure: Negative * - * Programmer: Quincey Koziol - * Saturday, February 23, 2019 + * Programmer: Quincey Koziol + * Saturday, February 23, 2019 * *--------------------------------------------------------------------------- */ @@ -568,17 +624,17 @@ done: * * Purpose: Free a retrieved library state. * - * Note: This routine is _only_ for HDF5 VOL connector authors! It is - * _not_ part of the public API for HDF5 application developers. + * Note: This routine is _only_ for HDF5 VOL connector authors! It is + * _not_ part of the public API for HDF5 application developers. * - * Note: This routine must be called as a "pair" with - * H5VLretrieve_lib_state. + * Note: This routine must be called as a "pair" with + * H5VLretrieve_lib_state. * * Return: Success: Non-negative * Failure: Negative * - * Programmer: Quincey Koziol - * Thursday, January 10, 2019 + * Programmer: Quincey Koziol + * Thursday, January 10, 2019 * *--------------------------------------------------------------------------- */ |