Document that concurrent modification is bad, m'kay.

sdk/lib/collection/queue.dart

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 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 {
 
   /**
    * Creates a queue.
    */
   factory Queue() = ListQueue<E>;
 
   /**
    * Creates a queue with the elements of [other]. The order in
@@ skipping 669 matching lines @@
     _queue._checkModification(_modificationCount);
     if (_position == _end) {
       _current = null;
       return false;
     }
     _current = _queue._table[_position];
     _position = (_position + 1) & (_queue._table.length - 1);
     return true;
   }
 }