RFR 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit (original) (raw)

Peter Levart peter.levart at gmail.com
Fri May 3 10:07:52 UTC 2013

Hi Paul,

Maybe the JavaDoc could also suggest that the trySplit producing N+0 result should converge so that returned Spliterator eventualy produces either null+N or n+m (n<N, m<N) and splitting terminates in finite number of steps. Also I don't know why would any Spliterator implementation want to return 0+N from trySplit (the N+0 return can be useful because the returned instance can be of different class/implementation, but the 0+N has no utility), so the javaDoc could be more strict:

   * Upon non-null return:
   * <ul>
   * <li>the value reported for {@code estimateSize()} before splitting,
   * must, after splitting, be greater than {@code estimateSize()}
   * for this and greater than or equal than {@code estimateSize()}
   * for the returned Spliterator; and</li>
   * <li>if this Spliterator is {@code SUBSIZED}, then {@code estimateSize()}
   * for this spliterator before splitting must be equal to the sum of
   * {@code estimateSize()} for this and the returned Spliterator after

Regards, Peter

On 05/03/2013 11:10 AM, Paul Sandoz wrote:

Hi,

Please review the patch below for some minor fixes to the Spltierator JavaDoc and a tweak to the spec of Spliterator.trySplit. http://bugs.sun.com/viewbug.do?bugid=8013334 Paul. # HG changeset patch # User psandoz # Date 1367571917 -7200 # Node ID fda6ca78a7c299349f201c310ec480351a855ed1 # Parent 470f19b6bfdd07aed3ca6e0debdabcd8cd7f8083 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit Summary: In addition to fixing 8013334 this changeset containts some minor, non spec, related fixes to tidy up other areas of the JavaDoc. Reviewed-by: Contributed-by: John Rose <john.r.rose at oracle.com>, Mike Duigou <mike.duigou at oracle.com>, Paul Sandoz <paul.sandoz at oracle.com> diff -r 470f19b6bfdd -r fda6ca78a7c2 src/share/classes/java/util/Spliterator.java --- a/src/share/classes/java/util/Spliterator.java Thu May 02 13:21:09 2013 +0200 +++ b/src/share/classes/java/util/Spliterator.java Fri May 03 11:05:17 2013 +0200 @@ -140,32 +140,32 @@ * (in approximate order of decreasing desirability): *

    *
  • The source cannot be structurally interfered with.
    •  - *
    For example, an instance of     + *
    For example, an instance of     * {@link java.util.concurrent.CopyOnWriteArrayList} is an immutable source. * A Spliterator created from the source reports a characteristic of * {@code IMMUTABLE}. *
  • The source manages concurrent modifications.
    •  - *
    For example, a key set of a {@link java.util.concurrent.ConcurrentHashMap}     + *
    For example, a key set of a {@link java.util.concurrent.ConcurrentHashMap}     * is a concurrent source. A Spliterator created from the source reports a * characteristic of {@code CONCURRENT}. *
  • The mutable source provides a late-binding and fail-fast Spliterator.
    •  - *
    Late binding narrows the window during which interference can affect     + *
    Late binding narrows the window during which interference can affect     * the calculation; fail-fast detects, on a best-effort basis, that structural * interference has occurred after traversal has commenced and throws * {@link ConcurrentModificationException}. For example, {@link ArrayList}, * and many other non-concurrent {@code Collection} classes in the JDK, provide * a late-binding, fail-fast spliterator. *
  • The mutable source provides a non-late-binding but fail-fast Spliterator.
    •  - *
    The source increases the likelihood of throwing     + *
    The source increases the likelihood of throwing     * {@code ConcurrentModificationException} since the window of potential * interference is larger. *
  • The mutable source provides a late-binding and non-fail-fast Spliterator.
    •  - *
    The source risks arbitrary, non-deterministic behavior after traversal     + *
    The source risks arbitrary, non-deterministic behavior after traversal     * has commenced since interference is not detected. * *
  • The mutable source provides a non-late-binding and non-fail-fast
    •  * Spliterator. - *
    The source increases the risk of arbitrary, non-deterministic behavior     + *
    The source increases the risk of arbitrary, non-deterministic behavior     * since non-detected interference may occur after construction. * * @@ -284,6 +284,8 @@ * is set to {@code true} then diagnostic warnings are reported if boxing of * primitive values occur when operating on primitive subtype specializations. * + * @param the type of elements returned by this Spliterator + * * @see Collection * @since 1.8 */ @@ -333,9 +335,8 @@ * Upon non-null return: *
      *
    • the value reported for {@code estimateSize()} before splitting,
      •  - * if not already zero or {@code Long.MAXVALUE}, must, after splitting, be - * greater than {@code estimateSize()} for this and the returned - * Spliterator; and + * must, after splitting, be greater than or equal to {@code estimateSize()} + * for this and the returned Spliterator; and *
    • if this Spliterator is {@code SUBSIZED}, then {@code estimateSize()}
      •  * for this spliterator before splitting must be equal to the sum of * {@code estimateSize()} for this and the returned Spliterator after

      More information about the core-libs-dev mailing list