From 8af30f782015ad415c104216c66716f720296cbb Mon Sep 17 00:00:00 2001 From: mattjala <124107509+mattjala@users.noreply.github.com> Date: Tue, 16 May 2023 14:38:04 -0500 Subject: Warn about changing collections during iteration (#2962) --- src/H5Apublic.h | 9 +++++++++ src/H5Dpublic.h | 2 ++ src/H5Gpublic.h | 5 ++++- src/H5Ipublic.h | 3 +++ src/H5Lpublic.h | 25 ++++++++++++------------- src/H5Mpublic.h | 6 ++++++ src/H5Ppublic.h | 2 +- 7 files changed, 37 insertions(+), 15 deletions(-) diff --git a/src/H5Apublic.h b/src/H5Apublic.h index 92df94a..46a6cad 100644 --- a/src/H5Apublic.h +++ b/src/H5Apublic.h @@ -664,6 +664,9 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); * * \note This function is also available through the H5Aiterate() macro. * + * \warning Adding or removing attributes to the object during iteration + * will lead to undefined behavior. + * * \since 1.8.0 * */ @@ -721,6 +724,9 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord * information regarding the properties of links required to access * the object, \p obj_name. * + * \warning Adding or removing attributes to the object during iteration + * will lead to undefined behavior. + * * \since 1.8.0 * */ @@ -1188,6 +1194,9 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id); * \p op, is returned in \p idx. If \p idx is the null pointer, * then all attributes are processed. * + * \warning Adding or removing attributes to the object during iteration + * will lead to undefined behavior. + * * \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1() * and deprecated in this release. * \since 1.0.0 diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index 4315c7b..04795fa 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -1289,6 +1289,8 @@ H5_DLL herr_t H5Dread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, * be restarted at the point of exit; a second H5Diterate() * call will always restart at the beginning. * + * \warning Modifying the selection of \p space_id during iteration + * will lead to undefined behavior. * * \since 1.10.2 * diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h index 0e0a58b..5e237df 100644 --- a/src/H5Gpublic.h +++ b/src/H5Gpublic.h @@ -1008,7 +1008,10 @@ H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char * * examine the members of \c subgroup_a. When recursive iteration is * required, the application must handle the recursion, explicitly * calling H5Giterate() on discovered subgroups. - + * + * \warning Adding or removing members to the group during iteration + * will lead to undefined behavior. + * * \version 1.8.0 Function deprecated in this release. * */ diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h index 69b2450..c7ca78b 100644 --- a/src/H5Ipublic.h +++ b/src/H5Ipublic.h @@ -589,6 +589,9 @@ H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key); * to continue, as long as there are other identifiers remaining in * type. * + * \warning Adding or removing members of the identifier type during iteration + * will lead to undefined behavior. + * * \since 1.12.0 * */ diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h index 653bf27..0782090 100644 --- a/src/H5Lpublic.h +++ b/src/H5Lpublic.h @@ -983,6 +983,12 @@ H5_DLL herr_t H5Literate_async(hid_t group_id, H5_index_t idx_type, H5_iter_orde * passed in by the application with a starting point and returned by * the library with the point at which the iteration stopped. * + * \warning H5Literate_by_name2() assumes that the membership of the group being + * iterated over remains unchanged through the iteration; if any of the + * links in the group change during the iteration, the function’s + * behavior is undefined. Note, however, that objects pointed to by the + * links can be modified. + * * \note H5Literate_by_name2() is not recursive. In particular, if a member of * \p group_name is found to be a group, call it \c subgroup_a, * H5Literate_by_name2() does not examine the members of \c subgroup_a. @@ -990,12 +996,6 @@ H5_DLL herr_t H5Literate_async(hid_t group_id, H5_index_t idx_type, H5_iter_orde * recursion, explicitly calling H5Literate_by_name2() on discovered * subgroups. * - * \note H5Literate_by_name2() assumes that the membership of the group being - * iterated over remains unchanged through the iteration; if any of the - * links in the group change during the iteration, the function’s - * behavior is undefined. Note, however, that objects pointed to by the - * links can be modified. - * * \note H5Literate_by_name2() is the same as H5Literate2(), except that * H5Literate2() always proceeds in alphanumeric order. * @@ -1673,7 +1673,6 @@ H5_DLL herr_t H5Lget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index * This does not limit the ability to change link destinations * while iterating, but caution is advised. * - * * \version 1.12.0 Function was deprecated in this release. * \since 1.8.0 * @@ -1730,6 +1729,12 @@ H5_DLL herr_t H5Literate1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t ord * passed in by the application with a starting point and returned by * the library with the point at which the iteration stopped. * + * \warning H5Literate_by_name1() assumes that the membership of the group being + * iterated over remains unchanged through the iteration; if any of the + * links in the group change during the iteration, the function’s + * behavior is undefined. Note, however, that objects pointed to by the + * links can be modified. + * * \note H5Literate_by_name1() is not recursive. In particular, if a member of * \p group_name is found to be a group, call it \c subgroup_a, * H5Literate_by_name1() does not examine the members of \c subgroup_a. @@ -1737,12 +1742,6 @@ H5_DLL herr_t H5Literate1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t ord * recursion, explicitly calling H5Literate_by_name1() on discovered * subgroups. * - * \note H5Literate_by_name1() assumes that the membership of the group being - * iterated over remains unchanged through the iteration; if any of the - * links in the group change during the iteration, the function’s - * behavior is undefined. Note, however, that objects pointed to by the - * links can be modified. - * * \note H5Literate_by_name1() is the same as H5Giterate(), except that * H5Giterate() always proceeds in lexicographic order. * diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h index f5874e8..213636d 100644 --- a/src/H5Mpublic.h +++ b/src/H5Mpublic.h @@ -542,6 +542,9 @@ H5_DLL herr_t H5Mexists(hid_t map_id, hid_t key_mem_type_id, const void *key, hb * * Any further options can be specified through the property list \p dxpl_id. * + * \warning Adding or removing key-value pairs to the map during iteration + * will lead to undefined behavior. + * * \since 1.12.0 * */ @@ -583,6 +586,9 @@ H5_DLL herr_t H5Miterate(hid_t map_id, hsize_t *idx, hid_t key_mem_type_id, H5M_ * * Any further options can be specified through the property list \p dxpl_id. * + * \warning Adding or removing key-value pairs to the map during iteration + * will lead to undefined behavior. + * * \since 1.12.0 * */ diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index a08119d..2f6ca71 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -1462,7 +1462,7 @@ H5_DLL htri_t H5Pisa_class(hid_t plist_id, hid_t pclass_id); * and the pointer to the operator data passed in to H5Piterate(), * \p iter_data. * - * H5Piterate() assumes that the properties in the object + * \warning H5Piterate() assumes that the properties in the object * identified by \p id remain unchanged through the iteration. * If the membership changes during the iteration, the function's * behavior is undefined. -- cgit v0.12