RFR 8168745 Iterator.forEachRemaining vs. Iterator.remove

[Paul Sandoz]

Hi,

Please review these specification clarifications to the methods Iterator.forEachRemaining and Iterator.remove.

Implementations of Iterator.forEachRemaining should have some wiggle room to optimize traversal. (In hindsight we could have done a better job locking such behaviour down in Java 8.)

I also took the opportunity to update the Iterable.forEach method.

Thanks,
Paul.

diff -r 4bf7aaa0d611 src/java.base/share/classes/java/lang/Iterable.java
--- a/src/java.base/share/classes/java/lang/Iterable.java	Thu Nov 17 12:24:51 2016 -0800
+++ b/src/java.base/share/classes/java/lang/Iterable.java	Mon Nov 21 10:55:21 2016 -0800
@@ -53,10 +53,12 @@
     /**
      * Performs the given action for each element of the {@code Iterable}
      * until all elements have been processed or the action throws an
-     * exception.  Unless otherwise specified by the implementing class,
-     * actions are performed in the order of iteration (if an iteration order
-     * is specified).  Exceptions thrown by the action are relayed to the
+     * exception.  Actions are performed in the order of iteration, if that
+     * order is specified.  Exceptions thrown by the action are relayed to the
      * caller.
+     * <p>
+     * The behaviour of this method is unspecified if the action performs
+     * side-effects that modify the underlying source of elements.
      *
      * @implSpec
      * <p>The default implementation behaves as if:
diff -r 4bf7aaa0d611 src/java.base/share/classes/java/util/Iterator.java
--- a/src/java.base/share/classes/java/util/Iterator.java	Thu Nov 17 12:24:51 2016 -0800
+++ b/src/java.base/share/classes/java/util/Iterator.java	Mon Nov 21 10:55:21 2016 -0800
@@ -76,10 +76,15 @@
     /**
      * Removes from the underlying collection the last element returned
      * by this iterator (optional operation).  This method can be called
-     * only once per call to {@link #next}.  The behavior of an iterator
-     * is unspecified if the underlying collection is modified while the
-     * iteration is in progress in any way other than by calling this
-     * method.
+     * only once per call to {@link #next}.
+     * <p>
+     * The behavior of an iterator is unspecified if:
+     * <ul>
+     * <li>the underlying collection is modified while the iteration is in
+     * progress in any way other than by calling this method; or
+     * <li>this method is called after a call to the
+     * {@link #forEachRemaining forEachRemaining} method.
+     * </ul>
      *
      * @implSpec
      * The default implementation throws an instance of
@@ -102,6 +107,16 @@
      * have been processed or the action throws an exception.  Actions are
      * performed in the order of iteration, if that order is specified.
      * Exceptions thrown by the action are relayed to the caller.
+     * <p>
+     * The behavior of an iterator is unspecified if the action performs the
+     * following side-effects:
+     * <ul>
+     * <li>modifies the underlying collection; or
+     * <li>calls the {@link #remove remove} method.
+     * </ul>
+     * <p>
+     * Subsequent behavior of an iterator is unspecified if the action throws an
+     * exception.
      *
      * @implSpec
      * <p>The default implementation behaves as if: