Warn about changing collections during iteration (#2962)

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.