array: Warn about caveat with array_remove_at() and value based arrays

Because enumerate() for value based arrays returns a pointer directly to
the internal array elements and because array_remove_at() or rather the
called array_remove() may move elements over the element at the currently
enumerated position, the pointer passed to enumerate() will point to a
different array element after the array_remove_at() call.  The caller
will thus operate on the wrong element if that pointer is accessed again
before calling enumerate().

For performance reasons we currently don't change the implementation to copy
each array element during enumeration to a private member of the enumerator and
return a pointer to that.  Similarly, due to the danger of subtle bugs we don't
remember the pointer passed to enumerate() to later redirect it to a copy
created during the array_remove_at() call.

diff --git a/src/libstrongswan/collections/array.h b/src/libstrongswan/collections/array.h
index ce702ebfa794dfe282550c1194fc034d255c3c99..0659c70bddc66d114d6bf62cfacf0b5dab364ed6 100644 (file)
--- a/src/libstrongswan/collections/array.h
+++ b/src/libstrongswan/collections/array.h
@@ -100,6 +100,11 @@ enumerator_t* array_create_enumerator(array_t *array);
 /**
  * Remove an element at enumerator position.
  *
+ * @warning For **value based** arrays don't use the pointer returned by
+ * enumerate() anymore after calling this function.  For performance reasons
+ * that pointer will point to internal data structures that get modified when
+ * this function is called.
+ *
  * @param array                        array to remove element in
  * @param enumerator   enumerator position, from array_create_enumerator()
  */