summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authormattjala <124107509+mattjala@users.noreply.github.com>2023-05-15 03:09:58 (GMT)
committerGitHub <noreply@github.com>2023-05-15 03:09:58 (GMT)
commit17750ea9c280784c90456ef81c0f13704483a5fa (patch)
tree4922d8edfd80edca7b17749c021a1b2c69adf92a
parent364145f144cb68a5635ad9f7dad0e4210e3d513a (diff)
downloadhdf5-17750ea9c280784c90456ef81c0f13704483a5fa.zip
hdf5-17750ea9c280784c90456ef81c0f13704483a5fa.tar.gz
hdf5-17750ea9c280784c90456ef81c0f13704483a5fa.tar.bz2
Warn about changing collections during iteration (#2950)
Resolves #92
-rw-r--r--src/H5Apublic.h9
-rw-r--r--src/H5Dpublic.h2
-rw-r--r--src/H5Gpublic.h5
-rw-r--r--src/H5Ipublic.h3
-rw-r--r--src/H5Lpublic.h25
-rw-r--r--src/H5Mpublic.h6
-rw-r--r--src/H5Ppublic.h2
7 files changed, 37 insertions, 15 deletions
diff --git a/src/H5Apublic.h b/src/H5Apublic.h
index de6851d..6e7ca7e 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 0dbd649..4ede564 100644
--- a/src/H5Dpublic.h
+++ b/src/H5Dpublic.h
@@ -1286,6 +1286,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 2609fb0..28cfcc4 100644
--- a/src/H5Gpublic.h
+++ b/src/H5Gpublic.h
@@ -1002,7 +1002,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 5f8fc28..6f25071 100644
--- a/src/H5Ipublic.h
+++ b/src/H5Ipublic.h
@@ -588,6 +588,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 fb46ad8..0016148 100644
--- a/src/H5Lpublic.h
+++ b/src/H5Lpublic.h
@@ -980,6 +980,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.
@@ -987,12 +993,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.
*
@@ -1670,7 +1670,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
*
@@ -1727,6 +1726,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.
@@ -1734,12 +1739,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 af6aa49..48625a5 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 2817551..53a455c 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -1459,7 +1459,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.