diff options
Diffstat (limited to 'src/H5I.c')
| -rw-r--r-- | src/H5I.c | 942 |
1 files changed, 419 insertions, 523 deletions
@@ -12,25 +12,17 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * FILE: H5I.c - Internal storage routines for handling "IDs" + * FILE: H5I.c - Internal storage routines for handling "IDs" * - * REMARKS: ID's which allow objects (void *'s currently) to be bundled - * into "types" for more general storage. + * REMARKS: IDs which allow objects (void * currently) to be bundled + * into "types" for more general storage. * - * DESIGN: The types are stored in an array of pointers to store each - * type in an element. Each "type" node contains a link to a - * hash table to manage the IDs in each type. Allowed types are - * values within the range 1 to H5I_MAX_NUM_TYPES and are given out - * at run-time. Types used by the library are stored in global - * variables defined in H5Ipublic.h. - * - * AUTHOR: Quincey Koziol - * - * MODIFICATIONS: - * 1/3/96 - Starting writing specs & coding prototype - * 1/7/96 - Finished coding prototype - * 6/10/97 - Moved into HDF5 library - * 5/18/04 - Expanded to allow registration of new types at run-time + * DESIGN: The types are stored in an array of pointers to store each + * type in an element. Each "type" node contains a link to a + * hash table to manage the IDs in each type. Allowed types are + * values within the range 1 to H5I_MAX_NUM_TYPES and are given out + * at run-time. Types used by the library are stored in global + * variables defined in H5Ipublic.h. */ #define H5I_PACKAGE /*suppress error about including H5Ipkg */ @@ -71,10 +63,10 @@ /* Atom information structure used */ typedef struct H5I_id_info_t { - hid_t id; /* ID for this info */ - unsigned count; /* ref. count for this atom */ - unsigned app_count; /* ref. count of application visible atoms */ - const void *obj_ptr; /* pointer associated with the atom */ + hid_t id; /* ID for this info */ + unsigned count; /* ref. count for this atom */ + unsigned app_count; /* ref. count of application visible atoms */ + const void *obj_ptr; /* pointer associated with the atom */ } H5I_id_info_t; /* ID type structure used */ @@ -223,39 +215,35 @@ H5I_term_interface(void) } /* end H5I_term_interface() */ /*------------------------------------------------------------------------- - * Function: H5Iregister_type + * Function: H5Iregister_type * - * Purpose: Public interface to H5I_register_type. Creates a new type - * of ID's to give out. A specific number (RESERVED) of type - * entries may be reserved to enable "constant" values to be handed - * out which are valid IDs in the type, but which do not map to any - * data structures and are not allocated dynamically later. HASH_SIZE is - * the minimum hash table size to use for the type. FREE_FUNC is - * called with an object pointer when the object is removed from - * the type. + * Purpose: Public interface to H5I_register_type. Creates a new type + * of ID's to give out. A specific number (RESERVED) of type + * entries may be reserved to enable "constant" values to be handed + * out which are valid IDs in the type, but which do not map to any + * data structures and are not allocated dynamically later. HASH_SIZE is + * the minimum hash table size to use for the type. FREE_FUNC is + * called with an object pointer when the object is removed from + * the type. * - * Return: Success: Type ID of the new type - * Failure: H5I_BADID - * - * Programmers: Nathaniel Furrer - * James Laird - * Friday, April 30, 2004 + * Return: Success: Type ID of the new type + * Failure: H5I_BADID * *------------------------------------------------------------------------- */ H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func) { - H5I_class_t *cls = NULL; /* New ID class */ - H5I_type_t new_type; /* New ID type value */ - H5I_type_t ret_value; /* Return value */ + H5I_class_t *cls = NULL; /* New ID class */ + H5I_type_t new_type; /* New ID type value */ + H5I_type_t ret_value = H5I_BADID; /* Return value */ FUNC_ENTER_API(H5I_BADID) H5TRACE3("It", "zIux", hash_size, reserved, free_func); /* Generate a new H5I_type_t value */ - /* Increment the number of types*/ + /* Increment the number of types */ if (H5I_next_type < H5I_MAX_NUM_TYPES) { new_type = H5I_next_type; H5_INC_ENUM(H5I_type_t, H5I_next_type); @@ -298,27 +286,21 @@ H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func) done: /* Clean up on error */ - if (ret_value < 0) { + if (ret_value < 0) if (cls) cls = H5FL_FREE(H5I_class_t, cls); - } /* end if */ FUNC_LEAVE_API(ret_value) } /* end H5Iregister_type() */ /*------------------------------------------------------------------------- - * Function: H5I_register_type + * Function: H5I_register_type * - * Purpose: Creates a new type of ID's to give out. - * The class is initialized or its reference count is incremented + * Purpose: Creates a new type of ID's to give out. + * The class is initialized or its reference count is incremented * (if it is already initialized). * - * Return: Success: Type ID of the new type - * Failure: H5I_BADID - * - * Programmers: Nathaniel Furrer - * James Laird - * Friday, April 30, 2004 + * Return: SUCCEED/FAIL * *------------------------------------------------------------------------- */ @@ -377,17 +359,12 @@ done: } /* end H5I_register_type() */ /*------------------------------------------------------------------------- - * Function: H5Itype_exists + * Function: H5Itype_exists * * Purpose: Query function to inform the user if a given type is * currently registered with the library. * - * Return: Success: 1 if the type is registered, 0 if it is not - * Failure: Negative - * - * Programmer: James Laird - * Nathaniel Furrer - * Tuesday, June 29, 2004 + * Return: TRUE/FALSE/FAIL * *------------------------------------------------------------------------- */ @@ -413,18 +390,17 @@ done: } /* end H5Itype_exists() */ /*------------------------------------------------------------------------- - * Function: H5Inmembers + * Function: H5Inmembers * - * Purpose: Returns the number of members in a type. Public interface to - * H5I_nmembers. The public interface throws an error if the + * Purpose: Returns the number of members in a type. Public interface to + * H5I_nmembers. The public interface throws an error if the * supplied type does not exist. This is different than the * private interface, which will just return 0. * - * Return: Success: Zero - * Failure: Negative + * Return: SUCCEED/FAIL * - * Programmer: James Laird - * Nathaniel Furrer + * Programmer: James Laird + * Nathaniel Furrer * Friday, April 23, 2004 * *------------------------------------------------------------------------- @@ -463,16 +439,16 @@ done: } /* end H5Inmembers() */ /*------------------------------------------------------------------------- - * Function: H5I_nmembers + * Function: H5I_nmembers * - * Purpose: Returns the number of members in a type. + * Purpose: Returns the number of members in a type. * - * Return: Success: Number of members; zero if the type is empty - * or has been deleted. + * Return: Success: Number of members; zero if the type is empty + * or has been deleted. * - * Failure: Negative + * Failure: Negative * - * Programmer: Robb Matzke + * Programmer: Robb Matzke * Wednesday, March 24, 1999 * *------------------------------------------------------------------------- @@ -498,17 +474,16 @@ done: } /* end H5I_nmembers() */ /*------------------------------------------------------------------------- - * Function: H5Iclear_type + * Function: H5Iclear_type * - * Purpose: Removes all objects from the type, calling the free - * function for each object regardless of the reference count. - * Public interface to H5I_clear_type. + * Purpose: Removes all objects from the type, calling the free + * function for each object regardless of the reference count. + * Public interface to H5I_clear_type. * - * Return: Success: Non-negative - * Failure: negative + * Return: SUCCEED/FAIL * - * Programmer: James Laird - * Nathaniel Furrer + * Programmer: James Laird + * Nathaniel Furrer * Friday, April 23, 2004 * *------------------------------------------------------------------------- @@ -516,7 +491,7 @@ done: herr_t H5Iclear_type(H5I_type_t type, hbool_t force) { - herr_t ret_value; /* Return value */ + herr_t ret_value = FAIL; /* Return value */ FUNC_ENTER_API(FAIL) H5TRACE2("e", "Itb", type, force); @@ -559,15 +534,14 @@ H5I__free_cb(void *_item, void H5_ATTR_UNUSED *_key, void H5_ATTR_UNUSED *_udata } /* end H5I__free_cb() */ /*------------------------------------------------------------------------- - * Function: H5I_clear_type + * Function: H5I_clear_type * - * Purpose: Removes all objects from the type, calling the free - * function for each object regardless of the reference count. + * Purpose: Removes all objects from the type, calling the free + * function for each object regardless of the reference count. * - * Return: Success: Non-negative - * Failure: negative + * Return: SUCCEED/FAIL * - * Programmer: Robb Matzke + * Programmer: Robb Matzke * Wednesday, March 24, 1999 * *------------------------------------------------------------------------- @@ -609,11 +583,10 @@ done: /*------------------------------------------------------------------------- * Function: H5I__clear_type_cb * - * Purpose: Attempts to free the specified ID , calling the free + * Purpose: Attempts to free the specified ID, calling the free * function for the object. * - * Return: Success: Non-negative - * Failure: negative + * Return: TRUE/FALSE/FAIL * * Programmer: Neil Fortner * Friday, July 10, 2015 @@ -629,12 +602,12 @@ H5I__clear_type_cb(void *_id, void H5_ATTR_UNUSED *key, void *_udata) FUNC_ENTER_STATIC_NOERR + /* Sanity checks */ HDassert(id); HDassert(udata); HDassert(udata->type_ptr); - /* - * Do nothing to the object if the reference count is larger than + /* Do nothing to the object if the reference count is larger than * one and forcing is off. */ if (udata->force || (id->count - (!udata->app_ref * id->app_count)) <= 1) { @@ -674,25 +647,25 @@ H5I__clear_type_cb(void *_id, void H5_ATTR_UNUSED *key, void *_udata) } /* end H5I__clear_type_cb() */ /*------------------------------------------------------------------------- - * Function: H5Idestroy_type + * Function: H5Idestroy_type * - * Purpose: Destroys a type along with all atoms in that type - * regardless of their reference counts. Destroying IDs - * involves calling the free-func for each ID's object and - * then adding the ID struct to the ID free list. Public - * interface to H5I__destroy_type. + * Purpose: Destroys a type along with all atoms in that type + * regardless of their reference counts. Destroying IDs + * involves calling the free-func for each ID's object and + * then adding the ID struct to the ID free list. Public + * interface to H5I__destroy_type. * - * Return: Zero on success/Negative on failure + * Return: SUCCEED/FAIL * - * Programmer: Nathaniel Furrer - * James Laird + * Programmer: Nathaniel Furrer + * James Laird * *------------------------------------------------------------------------- */ herr_t H5Idestroy_type(H5I_type_t type) { - herr_t ret_value; /* Return value */ + herr_t ret_value = FAIL; /* Return value */ FUNC_ENTER_API(FAIL) H5TRACE1("e", "It", type); @@ -707,17 +680,17 @@ done: } /* end H5Idestroy_type() */ /*------------------------------------------------------------------------- - * Function: H5I__destroy_type + * Function: H5I__destroy_type * - * Purpose: Destroys a type along with all atoms in that type - * regardless of their reference counts. Destroying IDs - * involves calling the free-func for each ID's object and - * then adding the ID struct to the ID free list. + * Purpose: Destroys a type along with all atoms in that type + * regardless of their reference counts. Destroying IDs + * involves calling the free-func for each ID's object and + * then adding the ID struct to the ID free list. * - * Return: Zero on success/Negative on failure + * Return: SUCCEED/FAIL * - * Programmer: Nathaniel Furrer - * James Laird + * Programmer: Nathaniel Furrer + * James Laird * *------------------------------------------------------------------------- */ @@ -760,22 +733,19 @@ done: } /* end H5I__destroy_type() */ /*------------------------------------------------------------------------- - * Function: H5Iregister - * - * Purpose: Public interface to H5I_register. + * Function: H5Iregister * - * Return: Success: New object id. - * Failure: Negative + * Purpose: Public interface to H5I_register. * - * Programmer: Nathaniel Furrer - * James Laird + * Return: Success: New object ID + * Failure: H5I_INVALID_HID * *------------------------------------------------------------------------- */ hid_t H5Iregister(H5I_type_t type, const void *object) { - hid_t ret_value; /* Return value */ + hid_t ret_value = H5I_INVALID_HID; /* Return value */ FUNC_ENTER_API(H5I_INVALID_HID) H5TRACE2("i", "It*x", type, object); @@ -830,20 +800,18 @@ H5I__wrapped_cb(void *_item, void H5_ATTR_UNUSED *_key, void *_udata) } /* end H5I__wrapped_cb() */ /*------------------------------------------------------------------------- - * Function: H5I_register + * Function: H5I_register * - * Purpose: Registers an OBJECT in a TYPE and returns an ID for it. - * This routine does _not_ check for unique-ness of the objects, - * if you register an object twice, you will get two different - * IDs for it. This routine does make certain that each ID in a - * type is unique. IDs are created by getting a unique number - * for the type the ID is in and incorporating the type into - * the ID which is returned to the user. - * - * Return: Success: New object id. - * Failure: Negative + * Purpose: Registers an OBJECT in a TYPE and returns an ID for it. + * This routine does _not_ check for unique-ness of the objects, + * if you register an object twice, you will get two different + * IDs for it. This routine does make certain that each ID in a + * type is unique. IDs are created by getting a unique number + * for the type the ID is in and incorporating the type into + * the ID which is returned to the user. * - * Programmer: Unknown + * Return: Success: New object ID + * Failure: H5I_INVALID_HID * *------------------------------------------------------------------------- */ @@ -938,24 +906,24 @@ done: } /* end H5I_register() */ /*------------------------------------------------------------------------- - * Function: H5I_subst + * Function: H5I_subst * - * Purpose: Substitute a new object pointer for the specified ID. + * Purpose: Substitute a new object pointer for the specified ID. * - * Return: Success: Non-null previous object pointer associated - * with the specified ID. - * Failure: NULL + * Return: Success: Non-NULL previous object pointer associated + * with the specified ID. + * Failure: NULL * - * Programmer: Quincey Koziol - * Saturday, February 27, 2010 + * Programmer: Quincey Koziol + * Saturday, February 27, 2010 * *------------------------------------------------------------------------- */ void * H5I_subst(hid_t id, const void *new_object) { - H5I_id_info_t *id_ptr; /* Ptr to the atom */ - void * ret_value; /* Return value */ + H5I_id_info_t *id_ptr; /* Pointer to the atom */ + void * ret_value = NULL; /* Return value */ FUNC_ENTER_NOAPI(NULL) @@ -972,26 +940,25 @@ H5I_subst(hid_t id, const void *new_object) done: FUNC_LEAVE_NOAPI(ret_value) -} /* end if */ +} /* end H5I_subst() */ /*------------------------------------------------------------------------- - * Function: H5I_object + * Function: H5I_object * - * Purpose: Find an object pointer for the specified ID. + * Purpose: Find an object pointer for the specified ID. * - * Return: Success: Non-null object pointer associated with the - * specified ID. - * Failure: NULL + * Return: Success: Non-NULL object pointer associated with the + * specified ID * - * Programmer: Unknown + * Failure: NULL * *------------------------------------------------------------------------- */ void * H5I_object(hid_t id) { - H5I_id_info_t *id_ptr; /*ptr to the new atom */ - void * ret_value = NULL; /*return value */ + H5I_id_info_t *id_ptr; /* Pointer to the new atom */ + void * ret_value = NULL; /* Return value */ FUNC_ENTER_NOAPI(NULL) @@ -1004,36 +971,32 @@ H5I_object(hid_t id) done: FUNC_LEAVE_NOAPI(ret_value) -} /* end if */ +} /* end H5I_object() */ /*------------------------------------------------------------------------- - * Function: H5Iobject_verify + * Function: H5Iobject_verify * - * Purpose: Find an object pointer for the specified ID, verifying that - * its in a particular type. Public interface to - * H5I_object_verify. + * Purpose: Find an object pointer for the specified ID, verifying that + * its in a particular type. Public interface to + * H5I_object_verify. * - * Return: Success: Non-null object pointer associated with the - * specified ID. - * Failure: NULL - * - * Programmer: Nathaniel Furrer - * James Laird - * Friday, April 23, 2004 + * Return: Success: Non-NULL object pointer associated with the + * specified ID. + * Failure: NULL * *------------------------------------------------------------------------- */ void * H5Iobject_verify(hid_t id, H5I_type_t id_type) { - void *ret_value; /* Return value */ + void *ret_value = NULL; /* Return value */ FUNC_ENTER_API(NULL) H5TRACE2("*x", "iIt", id, id_type); + /* Validate parameters */ if (H5I_IS_LIB_TYPE(id_type)) HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, NULL, "cannot call public function on library type") - if (id_type < 1 || id_type >= H5I_next_type) HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, NULL, "identifier has invalid type") @@ -1044,25 +1007,25 @@ done: } /* end H5Iobject_verify() */ /*------------------------------------------------------------------------- - * Function: H5I_object_verify + * Function: H5I_object_verify * - * Purpose: Find an object pointer for the specified ID, verifying that - * its in a particular type. + * Purpose: Find an object pointer for the specified ID, verifying that + * its in a particular type. * - * Return: Success: Non-null object pointer associated with the - * specified ID. - * Failure: NULL + * Return: Success: Non-NULL object pointer associated with the + * specified ID. + * Failure: NULL * - * Programmer: Quincey Koziol - * Wednesday, July 31, 2002 + * Programmer: Quincey Koziol + * Wednesday, July 31, 2002 * *------------------------------------------------------------------------- */ void * H5I_object_verify(hid_t id, H5I_type_t id_type) { - H5I_id_info_t *id_ptr = NULL; /*ptr to the new atom */ - void * ret_value = NULL; /*return value */ + H5I_id_info_t *id_ptr = NULL; /* Pointer to the new atom */ + void * ret_value = NULL; /* Return value */ FUNC_ENTER_NOAPI(NULL) @@ -1080,25 +1043,27 @@ done: } /* H5I_object_verify() */ /*------------------------------------------------------------------------- - * Function: H5I_get_type + * Function: H5I_get_type * - * Purpose: Given an object ID return the type to which it - * belongs. The ID need not be the ID of an object which - * currently exists because the type number is encoded - * in the object ID. + * Purpose: Given an object ID return the type to which it + * belongs. The ID need not be the ID of an object which + * currently exists because the type number is encoded + * in the object ID. * - * Return: Success: A valid type number - * Failure: H5I_BADID, a negative value. + * Return: Success: A positive integer (corresponding to an H5I_type_t + * enum value for library ID types, but not for user + * ID types). + * Failure: H5I_BADID * - * Programmer: Robb Matzke - * Friday, February 19, 1999 + * Programmer: Robb Matzke + * Friday, February 19, 1999 * *------------------------------------------------------------------------- */ H5I_type_t H5I_get_type(hid_t id) { - H5I_type_t ret_value = H5I_BADID; + H5I_type_t ret_value = H5I_BADID; /* Return value */ FUNC_ENTER_NOAPI(H5I_BADID) @@ -1112,17 +1077,17 @@ done: } /* end H5I_get_type() */ /*------------------------------------------------------------------------- - * Function: H5Iget_type + * Function: H5Iget_type * - * Purpose: The public version of H5I_get_type(), obtains a type number - * when given an ID. The ID need not be the ID of an - * object which currently exists because the type number is - * encoded as part of the ID. + * Purpose: The public version of H5I_get_type(), obtains a type number + * when given an ID. The ID need not be the ID of an + * object which currently exists because the type number is + * encoded as part of the ID. * - * Return: Success: Type number - * Failure: H5I_BADID, a negative value - * - * Programmer: Unknown + * Return: Success: A positive integer (corresponding to an H5I_type_t + * enum value for library ID types, but not for user + * ID types). + * Failure: H5I_BADID * *------------------------------------------------------------------------- */ @@ -1144,26 +1109,26 @@ done: } /* end H5Iget_type() */ /*------------------------------------------------------------------------- - * Function: H5Iremove_verify + * Function: H5Iremove_verify * - * Purpose: Removes the specified ID from its type, first checking that the - * type of the ID and the type type are the same. Public interface to - * H5I__remove_verify. + * Purpose: Removes the specified ID from its type, first checking that the + * type of the ID and the type type are the same. Public interface to + * H5I__remove_verify. * - * Return: Success: A pointer to the object that was removed, the - * same pointer which would have been found by - * calling H5I_object(). - * Failure: NULL + * Return: Success: A pointer to the object that was removed, the + * same pointer which would have been found by + * calling H5I_object(). + * Failure: NULL * - * Programmer: James Laird - * Nathaniel Furrer + * Programmer: James Laird + * Nathaniel Furrer * *------------------------------------------------------------------------- */ void * H5Iremove_verify(hid_t id, H5I_type_t id_type) { - void *ret_value; /* Return value */ + void *ret_value = NULL; /* Return value */ FUNC_ENTER_API(NULL) H5TRACE2("*x", "iIt", id, id_type); @@ -1179,25 +1144,25 @@ done: } /* end H5Iremove_verify() */ /*------------------------------------------------------------------------- - * Function: H5I__remove_verify + * Function: H5I__remove_verify * - * Purpose: Removes the specified ID from its type, first checking that - * the ID's type is the same as the ID type supplied as an argument + * Purpose: Removes the specified ID from its type, first checking that + * the ID's type is the same as the ID type supplied as an argument * - * Return: Success: A pointer to the object that was removed, the - * same pointer which would have been found by - * calling H5I_object(). - * Failure: NULL + * Return: Success: A pointer to the object that was removed, the + * same pointer which would have been found by + * calling H5I_object(). + * Failure: NULL * - * Programmer: James Laird - * Nat Furrer + * Programmer: James Laird + * Nat Furrer * *------------------------------------------------------------------------- */ void * H5I__remove_verify(hid_t id, H5I_type_t id_type) { - void *ret_value = NULL; /*return value */ + void *ret_value = NULL; /*return value */ FUNC_ENTER_STATIC_NOERR @@ -1211,14 +1176,14 @@ H5I__remove_verify(hid_t id, H5I_type_t id_type) } /* end H5I__remove_verify() */ /*------------------------------------------------------------------------- - * Function: H5I__remove_common + * Function: H5I__remove_common * - * Purpose: Common code to remove a specified ID from its type. + * Purpose: Common code to remove a specified ID from its type. * - * Return: Success: A pointer to the object that was removed, the - * same pointer which would have been found by - * calling H5I_object(). - * Failure: NULL + * Return: Success: A pointer to the object that was removed, the + * same pointer which would have been found by + * calling H5I_object(). + * Failure: NULL * * Programmer: Quincey Koziol * October 3, 2013 @@ -1228,8 +1193,8 @@ H5I__remove_verify(hid_t id, H5I_type_t id_type) static void * H5I__remove_common(H5I_id_type_t *type_ptr, hid_t id) { - H5I_id_info_t *curr_id; /*ptr to the current atom */ - void * ret_value; /*return value */ + H5I_id_info_t *curr_id; /* Pointer to the current atom */ + void * ret_value = NULL; /* Return value */ FUNC_ENTER_STATIC @@ -1285,25 +1250,23 @@ done: } /* end H5I__remove_common() */ /*------------------------------------------------------------------------- - * Function: H5I_remove + * Function: H5I_remove * - * Purpose: Removes the specified ID from its type. + * Purpose: Removes the specified ID from its type. * - * Return: Success: A pointer to the object that was removed, the - * same pointer which would have been found by - * calling H5I_object(). - * Failure: NULL - * - * Programmer: Unknown + * Return: Success: A pointer to the object that was removed, the + * same pointer which would have been found by + * calling H5I_object(). + * Failure: NULL * *------------------------------------------------------------------------- */ void * H5I_remove(hid_t id) { - H5I_id_type_t *type_ptr; /*ptr to the atomic type */ - H5I_type_t type; /*atom's atomic type */ - void * ret_value; /*return value */ + H5I_id_type_t *type_ptr; /* Pointer to the atomic type */ + H5I_type_t type; /* Atom's atomic type */ + void * ret_value = NULL; /* Return value */ FUNC_ENTER_NOAPI(NULL) @@ -1324,14 +1287,14 @@ done: } /* end H5I_remove() */ /*------------------------------------------------------------------------- - * Function: H5Idec_ref + * Function: H5Idec_ref * - * Purpose: Decrements the number of references outstanding for an ID. + * Purpose: Decrements the number of references outstanding for an ID. * If the reference count for an ID reaches zero, the object * will be closed. * - * Return: Success: New reference count - * Failure: Negative + * Return: Success: New reference count + * Failure: -1 * * Programmer: Quincey Koziol * Dec 7, 2003 @@ -1341,57 +1304,54 @@ done: int H5Idec_ref(hid_t id) { - int ret_value; /* Return value */ + int ret_value = 0; /* Return value */ - FUNC_ENTER_API(FAIL) + FUNC_ENTER_API((-1)) H5TRACE1("Is", "i", id); /* Check arguments */ if (id < 0) - HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, FAIL, "invalid ID") + HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "invalid ID") /* Do actual decrement operation */ if ((ret_value = H5I_dec_app_ref(id)) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTDEC, FAIL, "can't decrement ID ref count") + HGOTO_ERROR(H5E_ATOM, H5E_CANTDEC, (-1), "can't decrement ID ref count") done: FUNC_LEAVE_API(ret_value) } /* end H5Idec_ref() */ /*------------------------------------------------------------------------- - * Function: H5I_dec_ref + * Function: H5I_dec_ref * - * Purpose: Decrements the number of references outstanding for an ID. - * This will fail if the type is not a reference counted type. - * The ID type's 'free' function will be called for the ID - * if the reference count for the ID reaches 0 and a free - * function has been defined at type creation time. + * Purpose: Decrements the number of references outstanding for an ID. + * This will fail if the type is not a reference counted type. + * The ID type's 'free' function will be called for the ID + * if the reference count for the ID reaches 0 and a free + * function has been defined at type creation time. * - * Return: Success: New reference count. + * Return: Success: New reference count * - * Failure: Negative - * - * Programmer: Unknown + * Failure: -1 * *------------------------------------------------------------------------- */ int H5I_dec_ref(hid_t id) { - H5I_id_info_t *id_ptr; /*ptr to the new ID */ - int ret_value; /* Return value */ + H5I_id_info_t *id_ptr; /* Pointer to the new ID */ + int ret_value = 0; /* Return value */ - FUNC_ENTER_NOAPI(FAIL) + FUNC_ENTER_NOAPI((-1)) /* Sanity check */ HDassert(id >= 0); /* General lookup of the ID */ if (NULL == (id_ptr = H5I__find_id(id))) - HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, FAIL, "can't locate ID") + HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "can't locate ID") - /* - * If this is the last reference to the object then invoke the type's + /* If this is the last reference to the object then invoke the type's * free method on the object. If the free method is undefined or * successful then remove the object from the type; otherwise leave * the object in the type without decrementing the reference @@ -1406,7 +1366,7 @@ H5I_dec_ref(hid_t id) * file. We have to close the dataset anyway. (SLU - 2010/9/7) */ if (1 == id_ptr->count) { - H5I_id_type_t *type_ptr; /*ptr to the type */ + H5I_id_type_t *type_ptr; /*ptr to the type */ /* Get the ID's type */ type_ptr = H5I_id_type_list_g[H5I_TYPE(id)]; @@ -1415,11 +1375,11 @@ H5I_dec_ref(hid_t id) if (!type_ptr->cls->free_func || (type_ptr->cls->free_func)((void *)id_ptr->obj_ptr) >= 0) { /* Remove the node from the type */ if (NULL == H5I__remove_common(type_ptr, id)) - HGOTO_ERROR(H5E_ATOM, H5E_CANTDELETE, FAIL, "can't remove ID node") + HGOTO_ERROR(H5E_ATOM, H5E_CANTDELETE, (-1), "can't remove ID node") ret_value = 0; } /* end if */ else - ret_value = FAIL; + ret_value = -1; } /* end if */ else { --(id_ptr->count); @@ -1431,13 +1391,13 @@ done: } /* end H5I_dec_ref() */ /*------------------------------------------------------------------------- - * Function: H5I_dec_app_ref + * Function: H5I_dec_app_ref * - * Purpose: H5I_dec_ref wrapper for case of modifying the application ref. - * count for an ID as well as normal reference count. + * Purpose: H5I_dec_ref wrapper for case of modifying the application ref. + * count for an ID as well as normal reference count. * - * Return: Success: New app. reference count. - * Failure: Negative + * Return: Success: New app. reference count + * Failure: -1 * * Programmer: Quincey Koziol * Sept 16, 2010 @@ -1447,23 +1407,23 @@ done: int H5I_dec_app_ref(hid_t id) { - H5I_id_info_t *id_ptr; /*ptr to the new ID */ - int ret_value; /* Return value */ + H5I_id_info_t *id_ptr; /* Pointer to the new ID */ + int ret_value = 0; /* Return value */ - FUNC_ENTER_NOAPI(FAIL) + FUNC_ENTER_NOAPI((-1)) /* Sanity check */ HDassert(id >= 0); /* Call regular decrement reference count routine */ if ((ret_value = H5I_dec_ref(id)) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTDEC, FAIL, "can't decrement ID ref count") + HGOTO_ERROR(H5E_ATOM, H5E_CANTDEC, (-1), "can't decrement ID ref count") /* Check if the ID still exists */ if (ret_value > 0) { /* General lookup of the ID */ if (NULL == (id_ptr = H5I__find_id(id))) - HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, FAIL, "can't locate ID") + HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "can't locate ID") /* Adjust app_ref */ --(id_ptr->app_count); @@ -1478,25 +1438,22 @@ done: } /* end H5I_dec_app_ref() */ /*------------------------------------------------------------------------- - * Function: H5I_dec_app_ref_always_close + * Function: H5I_dec_app_ref_always_close * - * Purpose: H5I_dec_app_ref wrapper for case of always closing the ID, - * even when the free routine fails + * Purpose: H5I_dec_app_ref wrapper for case of always closing the ID, + * even when the free routine fails * - * Return: Success: New app. reference count. - * Failure: Negative - * - * Programmer: Quincey Koziol - * Sept 16, 2010 + * Return: Success: New app. reference count + * Failure: -1 * *------------------------------------------------------------------------- */ int H5I_dec_app_ref_always_close(hid_t id) { - int ret_value; /* Return value */ + int ret_value = 0; /* Return value */ - FUNC_ENTER_NOAPI(FAIL) + FUNC_ENTER_NOAPI((-1)) /* Sanity check */ HDassert(id >= 0); @@ -1514,23 +1471,20 @@ H5I_dec_app_ref_always_close(hid_t id) */ H5I_remove(id); - HGOTO_ERROR(H5E_ATOM, H5E_CANTDEC, FAIL, "can't decrement ID ref count") - } /* end if */ + HGOTO_ERROR(H5E_ATOM, H5E_CANTDEC, (-1), "can't decrement ID ref count") + } done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5I_dec_app_ref_always_close() */ /*------------------------------------------------------------------------- - * Function: H5Iinc_ref - * - * Purpose: Increments the number of references outstanding for an ID. + * Function: H5Iinc_ref * - * Return: Success: New reference count - * Failure: Negative + * Purpose: Increments the number of references outstanding for an ID. * - * Programmer: Quincey Koziol - * Dec 7, 2003 + * Return: Success: New reference count + * Failure: -1 * *------------------------------------------------------------------------- */ @@ -1539,48 +1493,45 @@ H5Iinc_ref(hid_t id) { int ret_value; /* Return value */ - FUNC_ENTER_API(FAIL) + FUNC_ENTER_API((-1)) H5TRACE1("Is", "i", id); /* Check arguments */ if (id < 0) - HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, FAIL, "invalid ID") + HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "invalid ID") /* Do actual increment operation */ if ((ret_value = H5I_inc_ref(id, TRUE)) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTINC, FAIL, "can't increment ID ref count") + HGOTO_ERROR(H5E_ATOM, H5E_CANTINC, (-1), "can't increment ID ref count") done: FUNC_LEAVE_API(ret_value) } /* end H5Iinc_ref() */ /*------------------------------------------------------------------------- - * Function: H5I_inc_ref + * Function: H5I_inc_ref * - * Purpose: Increment the reference count for an object. + * Purpose: Increment the reference count for an object. * - * Return: Success: The new reference count. - * Failure: Negative - * - * Programmer: Robb Matzke - * Thursday, July 29, 1999 + * Return: Success: The new reference count + * Failure: -1 * *------------------------------------------------------------------------- */ int H5I_inc_ref(hid_t id, hbool_t app_ref) { - H5I_id_info_t *id_ptr; /*ptr to the ID */ - int ret_value; /* Return value */ + H5I_id_info_t *id_ptr; /* Pointer to the ID */ + int ret_value = 0; /* Return value */ - FUNC_ENTER_NOAPI(FAIL) + FUNC_ENTER_NOAPI((-1)) /* Sanity check */ HDassert(id >= 0); /* General lookup of the ID */ if (NULL == (id_ptr = H5I__find_id(id))) - HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, FAIL, "can't locate ID") + HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "can't locate ID") /* Adjust reference counts */ ++(id_ptr->count); @@ -1595,15 +1546,12 @@ done: } /* end H5I_inc_ref() */ /*------------------------------------------------------------------------- - * Function: H5Iget_ref + * Function: H5Iget_ref * - * Purpose: Retrieves the number of references outstanding for an ID. + * Purpose: Retrieves the number of references outstanding for an ID. * - * Return: Success: Reference count - * Failure: Negative - * - * Programmer: Quincey Koziol - * Dec 7, 2003 + * Return: Success: Reference count + * Failure: -1 * *------------------------------------------------------------------------- */ @@ -1612,48 +1560,45 @@ H5Iget_ref(hid_t id) { int ret_value; /* Return value */ - FUNC_ENTER_API(FAIL) + FUNC_ENTER_API((-1)) H5TRACE1("Is", "i", id); /* Check arguments */ if (id < 0) - HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, FAIL, "invalid ID") + HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "invalid ID") /* Do actual retrieve operation */ if ((ret_value = H5I_get_ref(id, TRUE)) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTGET, FAIL, "can't get ID ref count") + HGOTO_ERROR(H5E_ATOM, H5E_CANTGET, (-1), "can't get ID ref count") done: FUNC_LEAVE_API(ret_value) } /* end H5Iget_ref() */ /*------------------------------------------------------------------------- - * Function: H5I_get_ref - * - * Purpose: Retrieve the reference count for an object. + * Function: H5I_get_ref * - * Return: Success: The reference count. - * Failure: Negative + * Purpose: Retrieve the reference count for an object. * - * Programmer: Quincey Koziol - * Saturday, Decemeber 6, 2003 + * Return: Success: The reference count + * Failure: -1 * *------------------------------------------------------------------------- */ int H5I_get_ref(hid_t id, hbool_t app_ref) { - H5I_id_info_t *id_ptr; /*ptr to the ID */ - int ret_value; /* Return value */ + H5I_id_info_t *id_ptr; /* Pointer to the ID */ + int ret_value = 0; /* Return value */ - FUNC_ENTER_NOAPI(FAIL) + FUNC_ENTER_NOAPI((-1)) /* Sanity check */ HDassert(id >= 0); /* General lookup of the ID */ if (NULL == (id_ptr = H5I__find_id(id))) - HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, FAIL, "can't locate ID") + HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "can't locate ID") /* Set return value */ ret_value = (int)(app_ref ? id_ptr->app_count : id_ptr->count); @@ -1663,16 +1608,12 @@ done: } /* end H5I_get_ref() */ /*------------------------------------------------------------------------- - * Function: H5Iinc_type_ref - * - * Purpose: Increments the number of references outstanding for an ID type. + * Function: H5Iinc_type_ref * - * Return: Success: New reference count - * Failure: Negative + * Purpose: Increments the number of references outstanding for an ID type. * - * Programmer: Nat Furrer - * James Laird - * April 30, 2004 + * Return: Success: New reference count + * Failure: -1 * *------------------------------------------------------------------------- */ @@ -1681,43 +1622,38 @@ H5Iinc_type_ref(H5I_type_t type) { int ret_value; /* Return value */ - FUNC_ENTER_API(FAIL) + FUNC_ENTER_API((-1)) H5TRACE1("Is", "It", type); /* Check arguments */ if (type <= 0 || type >= H5I_next_type) - HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, FAIL, "invalid ID type") - + HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "invalid ID type") if (H5I_IS_LIB_TYPE(type)) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "cannot call public function on library type") + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, (-1), "cannot call public function on library type") /* Do actual increment operation */ if ((ret_value = H5I__inc_type_ref(type)) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTINC, FAIL, "can't increment ID type ref count") + HGOTO_ERROR(H5E_ATOM, H5E_CANTINC, (-1), "can't increment ID type ref count") done: FUNC_LEAVE_API(ret_value) } /* end H5Iinc_ref() */ /*------------------------------------------------------------------------- - * Function: H5I__inc_type_ref + * Function: H5I__inc_type_ref * - * Purpose: Increment the reference count for an ID type. + * Purpose: Increment the reference count for an ID type. * - * Return: Success: The new reference count. - * Failure: Negative - * - * Programmer: James Laird - * Nat Furrer - * Friday, April 30, 2004 + * Return: Success: The new reference count + * Failure: -1 * *------------------------------------------------------------------------- */ static int H5I__inc_type_ref(H5I_type_t type) { - H5I_id_type_t *type_ptr; /* ptr to the type */ - int ret_value; /* Return value */ + H5I_id_type_t *type_ptr; /* Pointer to the type */ + int ret_value = -1; /* Return value */ FUNC_ENTER_STATIC @@ -1726,8 +1662,8 @@ H5I__inc_type_ref(H5I_type_t type) /* Check arguments */ type_ptr = H5I_id_type_list_g[type]; - if (!type_ptr) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "invalid type") + if (NULL == type_ptr) + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, (-1), "invalid type") /* Set return value */ ret_value = (int)(++(type_ptr->init_count)); @@ -1737,37 +1673,39 @@ done: } /* end H5I__inc_type_ref() */ /*------------------------------------------------------------------------- - * Function: H5Idec_type_ref - * - * Purpose: Decrements the reference count on an entire type of IDs. - * If the type reference count becomes zero then the type is - * destroyed along with all atoms in that type regardless of - * their reference counts. Destroying IDs involves calling - * the free-func for each ID's object and then adding the ID - * struct to the ID free list. Public interface to - * H5I_dec_type_ref. - * Returns the number of references to the type on success; a - * return value of 0 means that the type will have to be - * re-initialized before it can be used again (and should probably - * be set to H5I_UNINIT). - * - * Return: Number of references to type on success/Negative on failure - * - * Programmer: Nathaniel Furrer - * James Laird + * Function: H5Idec_type_ref + * + * Purpose: Decrements the reference count on an entire type of IDs. + * If the type reference count becomes zero then the type is + * destroyed along with all atoms in that type regardless of + * their reference counts. Destroying IDs involves calling + * the free-func for each ID's object and then adding the ID + * struct to the ID free list. Public interface to + * H5I_dec_type_ref. + * Returns the number of references to the type on success; a + * return value of 0 means that the type will have to be + * re-initialized before it can be used again (and should probably + * be set to H5I_UNINIT). + * + * NOTE: Using an error type to also represent a count is semantially + * incorrect. We should consider fixing this in a future major + * release (DER). + * + * Return: Success: Number of references to type + * Failure: -1 * *------------------------------------------------------------------------- */ herr_t H5Idec_type_ref(H5I_type_t type) { - herr_t ret_value; /* Return value */ + herr_t ret_value = 0; /* Return value */ - FUNC_ENTER_API(FAIL) + FUNC_ENTER_API((-1)) H5TRACE1("e", "It", type); if (H5I_IS_LIB_TYPE(type)) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "cannot call public function on library type") + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, (-1), "cannot call public function on library type") ret_value = H5I_dec_type_ref(type); @@ -1776,30 +1714,29 @@ done: } /* end H5Idec_type_ref() */ /*------------------------------------------------------------------------- - * Function: H5I_dec_type_ref - * - * Purpose: Decrements the reference count on an entire type of IDs. - * If the type reference count becomes zero then the type is - * destroyed along with all atoms in that type regardless of - * their reference counts. Destroying IDs involves calling - * the free-func for each ID's object and then adding the ID - * struct to the ID free list. - * Returns the number of references to the type on success; a - * return value of 0 means that the type will have to be - * re-initialized before it can be used again (and should probably - * be set to H5I_UNINIT). - * - * Return: Number of references to type on success/Negative on failure - * - * Programmer: Unknown + * Function: H5I_dec_type_ref + * + * Purpose: Decrements the reference count on an entire type of IDs. + * If the type reference count becomes zero then the type is + * destroyed along with all atoms in that type regardless of + * their reference counts. Destroying IDs involves calling + * the free-func for each ID's object and then adding the ID + * struct to the ID free list. + * Returns the number of references to the type on success; a + * return value of 0 means that the type will have to be + * re-initialized before it can be used again (and should probably + * be set to H5I_UNINIT). + * + * Return: Success: Number of references to type + * Failure: -1 * *------------------------------------------------------------------------- */ herr_t H5I_dec_type_ref(H5I_type_t type) { - H5I_id_type_t *type_ptr; /* Pointer to the ID type */ - herr_t ret_value; /* Return value */ + H5I_id_type_t *type_ptr; /* Pointer to the ID type */ + herr_t ret_value = 0; /* Return value */ FUNC_ENTER_NOAPI(FAIL) @@ -1810,8 +1747,7 @@ H5I_dec_type_ref(H5I_type_t type) if (type_ptr == NULL || type_ptr->init_count <= 0) HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "invalid type") - /* - * Decrement the number of users of the atomic type. If this is the + /* Decrement the number of users of the atomic type. If this is the * last user of the type then release all atoms from the type and * free all memory it used. The free function is invoked for each atom * being freed. @@ -1819,27 +1755,23 @@ H5I_dec_type_ref(H5I_type_t type) if (1 == type_ptr->init_count) { H5I__destroy_type(type); ret_value = 0; - } /* end if */ + } else { --(type_ptr->init_count); ret_value = (herr_t)type_ptr->init_count; - } /* end else */ + } done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5I_dec_type_ref() */ /*------------------------------------------------------------------------- - * Function: H5Iget_type_ref + * Function: H5Iget_type_ref * - * Purpose: Retrieves the number of references outstanding for a type. + * Purpose: Retrieves the number of references outstanding for a type. * - * Return: Success: Reference count - * Failure: Negative - * - * Programmer: Nat Furrer - * James Laird - * April 30, 2004 + * Return: Success: Reference count + * Failure: -1 * *------------------------------------------------------------------------- */ @@ -1848,44 +1780,39 @@ H5Iget_type_ref(H5I_type_t type) { int ret_value; /* Return value */ - FUNC_ENTER_API(FAIL) + FUNC_ENTER_API((-1)) H5TRACE1("Is", "It", type); /* Check arguments */ if (type <= 0 || type >= H5I_next_type) - HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, FAIL, "invalid ID type") - + HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "invalid ID type") if (H5I_IS_LIB_TYPE(type)) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "cannot call public function on library type") + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, (-1), "cannot call public function on library type") /* Do actual retrieve operation */ if ((ret_value = H5I__get_type_ref(type)) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTGET, FAIL, "can't get ID type ref count") + HGOTO_ERROR(H5E_ATOM, H5E_CANTGET, (-1), "can't get ID type ref count") done: FUNC_LEAVE_API(ret_value) } /* end H5Iget_ref() */ /*------------------------------------------------------------------------- - * Function: H5I__get_type_ref - * - * Purpose: Retrieve the reference count for an ID type. + * Function: H5I__get_type_ref * - * Return: Success: The reference count. + * Purpose: Retrieve the reference count for an ID type. * - * Failure: Negative + * Return: Success: The reference count * - * Programmer: Nat Furrer - * James Laird - * April 30, 2004 + * Failure: -1 * *------------------------------------------------------------------------- */ static int H5I__get_type_ref(H5I_type_t type) { - H5I_id_type_t *type_ptr; /*ptr to the type */ - int ret_value; /* Return value */ + H5I_id_type_t *type_ptr; /* Pointer to the type */ + int ret_value = -1; /* Return value */ FUNC_ENTER_STATIC @@ -1905,17 +1832,12 @@ done: } /* end H5I__get_type_ref() */ /*------------------------------------------------------------------------- - * Function: H5Iis_valid + * Function: H5Iis_valid * - * Purpose: Check if the given id is valid. An id is valid if it is in + * Purpose: Check if the given id is valid. An id is valid if it is in * use and has an application reference count of at least 1. * - * Return: Success: TRUE if the id is valid, FALSE otherwise. - * - * Failure: Negative (never fails currently) - * - * Programmer: Neil Fortner - * Friday, October 31, 2008 (boo) + * Return: TRUE/FALSE/FAIL * *------------------------------------------------------------------------- */ @@ -1931,9 +1853,7 @@ H5Iis_valid(hid_t id) /* Find the ID */ if (NULL == (id_ptr = H5I__find_id(id))) ret_value = FALSE; - - /* Check if the found id is an internal id */ - else if (!id_ptr->app_count) + else if (!id_ptr->app_count) /* Check if the found id is an internal id */ ret_value = FALSE; done: @@ -1941,19 +1861,14 @@ done: } /* end H5Iis_valid() */ /*------------------------------------------------------------------------- - * Function: H5I__search_cb + * Function: H5I__search_cb * - * Purpose: Callback routine for H5Isearch, when it calls H5I_iterate. - * Calls "user" callback search function, and then sets return - * value, based on the result of that callback. + * Purpose: Callback routine for H5Isearch, when it calls H5I_iterate. + * Calls "user" callback search function, and then sets return + * value, based on the result of that callback. * - * Return: Success: The first object in the type for which FUNC - * returns non-zero. NULL if FUNC returned zero - * for every object in the type. - * Failure: NULL - * - * Programmer: Quincey Koziol - * Friday, March 30, 2012 + * Return: Success: H5_ITER_CONT (0) or H5_ITER_STOP (1) + * Failure: H5_ITER_ERROR (-1) * *------------------------------------------------------------------------- */ @@ -1973,26 +1888,22 @@ H5I__search_cb(void *obj, hid_t id, void *_udata) } /* end H5I__search_cb() */ /*------------------------------------------------------------------------- - * Function: H5Isearch - * - * Purpose: Apply function FUNC to each member of type TYPE and return a - * pointer to the first object for which FUNC returns non-zero. - * The FUNC should take a pointer to the object and the KEY as - * arguments and return non-zero to terminate the search (zero - * to continue). Public interface to H5I_search. + * Function: H5Isearch * - * Limitation: Currently there is no way to start searching from where a - * previous search left off. + * Purpose: Apply function FUNC to each member of type TYPE and return a + * pointer to the first object for which FUNC returns non-zero. + * The FUNC should take a pointer to the object and the KEY as + * arguments and return non-zero to terminate the search (zero + * to continue). Public interface to H5I_search. * - * Return: Success: The first object in the type for which FUNC - * returns non-zero. NULL if FUNC returned zero - * for every object in the type. + * Limitation: Currently there is no way to start searching from where a + * previous search left off. * - * Failure: NULL + * Return: Success: The first object in the type for which FUNC + * returns non-zero. NULL if FUNC returned zero + * for every object in the type. * - * Programmer: James Laird - * Nathaniel Furrer - * Friday, April 23, 2004 + * Failure: NULL * *------------------------------------------------------------------------- */ @@ -2027,17 +1938,14 @@ done: } /* end H5Isearch() */ /*------------------------------------------------------------------------- - * Function: H5I__iterate_cb + * Function: H5I__iterate_cb * - * Purpose: Callback routine for H5I_iterate, invokes "user" callback + * Purpose: Callback routine for H5I_iterate, invokes "user" callback * function, and then sets return value, based on the result of * that callback. * - * Return: Success: Non-negative on success - * Failure: Negative - * - * Programmer: Quincey Koziol - * Thursday, October 3, 2013 + * Return: Success: H5_ITER_CONT (0) or H5_ITER_STOP (1) + * Failure: H5_ITER_ERROR (-1) * *------------------------------------------------------------------------- */ @@ -2050,55 +1958,56 @@ H5I__iterate_cb(void *_item, void H5_ATTR_UNUSED *_key, void *_udata) FUNC_ENTER_STATIC_NOERR - /* Don't make callback if app_ref is set and the appl. ref count is 0 */ + /* Only invoke the callback function if this ID is visible externally and + * its reference count is positive. + */ if ((!udata->app_ref) || (item->app_count > 0)) { herr_t cb_ret_val; - /* (Casting away const OK) */ - cb_ret_val = (*udata->user_func)((void *)item->obj_ptr, item->id, udata->user_udata); + /* Invoke callback function */ + cb_ret_val = (*udata->user_func)((void *)item->obj_ptr, item->id, + udata->user_udata); /* (Casting away const OK) */ + + /* Set the return value based on the callback's return value */ if (cb_ret_val > 0) ret_value = H5_ITER_STOP; /* terminate iteration early */ else if (cb_ret_val < 0) ret_value = H5_ITER_ERROR; /* indicate failure (which terminates iteration) */ - } /* end if */ + } FUNC_LEAVE_NOAPI(ret_value) } /* end H5I__iterate_cb() */ /*------------------------------------------------------------------------- - * Function: H5I_iterate + * Function: H5I_iterate * - * Purpose: Apply function FUNC to each member of type TYPE (with - * non-zero application reference count if app_ref is TRUE). - * Stop if FUNC returns a non zero value (i.e. anything - * other than H5_ITER_CONT). + * Purpose: Apply function FUNC to each member of type TYPE (with + * non-zero application reference count if app_ref is TRUE). + * Stop if FUNC returns a non zero value (i.e. anything + * other than H5_ITER_CONT). * - * If FUNC returns a positive value (i.e. H5_ITER_STOP), - * return SUCCEED. + * If FUNC returns a positive value (i.e. H5_ITER_STOP), + * return SUCCEED. * - * If FUNC returns a negative value (i.e. H5_ITER_ERROR), - * return FAIL. + * If FUNC returns a negative value (i.e. H5_ITER_ERROR), + * return FAIL. * - * The FUNC should take a pointer to the object and the - * udata as arguments and return non-zero to terminate - * siteration, and zero to continue. + * The FUNC should take a pointer to the object and the + * udata as arguments and return non-zero to terminate + * siteration, and zero to continue. * - * Limitation: Currently there is no way to start the iteration from - * where a previous iteration left off. + * Limitation: Currently there is no way to start the iteration from + * where a previous iteration left off. * - * Return: Success: SUCCEED - * Failure: FAIL - * - * Programmer: John Mainzer - * Monday, December 6, 2011 + * Return: SUCCEED/FAIL * *------------------------------------------------------------------------- */ herr_t H5I_iterate(H5I_type_t type, H5I_search_func_t func, void *udata, hbool_t app_ref) { - H5I_id_type_t *type_ptr; /*ptr to the type */ - herr_t ret_value = SUCCEED; /*return value */ + H5I_id_type_t *type_ptr; /* Pointer to the type */ + herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_NOAPI(FAIL) @@ -2120,32 +2029,30 @@ H5I_iterate(H5I_type_t type, H5I_search_func_t func, void *udata, hbool_t app_re /* Iterate over IDs */ if ((iter_status = H5SL_iterate(type_ptr->ids, H5I__iterate_cb, &iter_udata)) < 0) HGOTO_ERROR(H5E_ATOM, H5E_BADITER, FAIL, "iteration failed") - } /* end if */ + } done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5I_iterate() */ /*------------------------------------------------------------------------- - * Function: H5I__find_id - * - * Purpose: Given an object ID find the info struct that describes the - * object. + * Function: H5I__find_id * - * Return: Success: Ptr to the object's info struct. + * Purpose: Given an object ID find the info struct that describes the + * object. * - * Failure: NULL + * Return: Success: A pointer to the object's info struct. * - * Programmer: Unknown + * Failure: NULL * *------------------------------------------------------------------------- */ static H5I_id_info_t * H5I__find_id(hid_t id) { - H5I_type_t type; /*ID's type */ - H5I_id_type_t *type_ptr; /*ptr to the type */ - H5I_id_info_t *ret_value; /*return value */ + H5I_type_t type; /*ID's type */ + H5I_id_type_t *type_ptr; /*ptr to the type */ + H5I_id_info_t *ret_value = NULL; /* Return value */ FUNC_ENTER_STATIC_NOERR @@ -2153,7 +2060,6 @@ H5I__find_id(hid_t id) type = H5I_TYPE(id); if (type <= H5I_BADID || type >= H5I_next_type) HGOTO_DONE(NULL) - type_ptr = H5I_id_type_list_g[type]; if (!type_ptr || type_ptr->init_count <= 0) HGOTO_DONE(NULL) @@ -2166,24 +2072,20 @@ done: } /* end H5I__find_id() */ /*------------------------------------------------------------------------- - * Function: H5Iget_name - * - * Purpose: Gets a name of an object from its ID. - * - * Return: Success: The length of name. + * Function: H5Iget_name * - * Failure: -1 + * Purpose: Gets a name of an object from its ID. * - * Programmer: Pedro Vicente, pvn@ncsa.uiuc.edu + * Return: Success: The length of the name * - * Date: July 26, 2002 + * Failure: -1 * * Comments: Public function - * If `name' is non-NULL then write up to `size' bytes into that + * If 'name' is non-NULL then write up to 'size' bytes into that * buffer and always return the length of the entry name. - * Otherwise `size' is ignored and the function does not store the name, + * Otherwise 'size' is ignored and the function does not store the name, * just returning the number of characters required to store the name. - * If an error occurs then the buffer pointed to by `name' (NULL or non-NULL) + * If an error occurs then the buffer pointed to by 'name' (NULL or non-NULL) * is unchanged and the function returns a negative value. * If a zero is returned for the name's length, then there is no name * associated with the ID. @@ -2196,33 +2098,30 @@ H5Iget_name(hid_t id, char *name /*out*/, size_t size) H5G_loc_t loc; /* Object location */ ssize_t ret_value; /* Return value */ - FUNC_ENTER_API(FAIL) + FUNC_ENTER_API((-1)) H5TRACE3("Zs", "ixz", id, name, size); /* Get object location */ if (H5G_loc(id, &loc) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTGET, FAIL, "can't retrieve object location") + HGOTO_ERROR(H5E_ATOM, H5E_CANTGET, (-1), "can't retrieve object location") /* Call internal group routine to retrieve object's name */ if ((ret_value = H5G_get_name(&loc, name, size, NULL, H5P_DEFAULT, H5AC_ind_dxpl_id)) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTGET, FAIL, "can't retrieve object name") + HGOTO_ERROR(H5E_ATOM, H5E_CANTGET, (-1), "can't retrieve object name") done: FUNC_LEAVE_API(ret_value) } /* end H5Iget_name() */ /*------------------------------------------------------------------------- - * Function: H5Iget_file_id - * - * Purpose: The public version of H5I_get_file_id(), obtains the file - * ID given an object ID. User has to close this ID. + * Function: H5Iget_file_id * - * Return: Success: file ID + * Purpose: Obtains the file ID given an object ID. The user has to + * close this ID. * - * Failure: a negative value + * Return: Success: The file ID associated with the object * - * Programmer: Raymond Lu - * Oct 27, 2003 + * Failure: H5I_INVALID_HID * *------------------------------------------------------------------------- */ @@ -2242,16 +2141,13 @@ done: } /* end H5Iget_file_id() */ /*------------------------------------------------------------------------- - * Function: H5I_get_file_id + * Function: H5I_get_file_id * - * Purpose: The private version of H5Iget_file_id(), obtains the file + * Purpose: The private version of H5Iget_file_id(), obtains the file * ID given an object ID. * - * Return: Success: file ID - * Failure: a negative value - * - * Programmer: Raymond Lu - * Oct 27, 2003 + * Return: Success: The file ID associated with the object + * Failure: H5I_INVALID_HID * *------------------------------------------------------------------------- */ |