Document that concurrent modification is bad, m'kay.

sdk/lib/collection/queue.dart

Index: sdk/lib/collection/queue.dart
diff --git a/sdk/lib/collection/queue.dart b/sdk/lib/collection/queue.dart
index 4e2c5aa4200bd2e60ab56c7b1b51c57d33aa455c..b441369b3007a13574deaf7a2c1e27fe0c6442ff 100644
--- a/sdk/lib/collection/queue.dart
+++ b/sdk/lib/collection/queue.dart
@@ -8,6 +8,14 @@ part of dart.collection;
  * A [Queue] is a collection that can be manipulated at both ends. One
  * can iterate over the elements of a queue through [forEach] or with
  * an [Iterator].
+ *
+ * It is generally not allowed to modify the queue (add or remove entries) while
+ * an operation on the queue is being performed, for example during a call to
+ * [forEach].
+ * Modifying the queue while it is being iterated will most likely break the
+ * iteration.
+ * This goes both for using the [iteator] directly, or for iterating an

[floitsch, 2013/10/15 15:32:24]

iterator

[Lasse Reichstein Nielsen, 2013/10/16 05:41:24]

Done.

+ * `Iterable` returned by a method like [map] or [where].
  */
 abstract class Queue<E> implements Iterable<E>, EfficientLength {