RFR 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit

[Paul Sandoz]

Hi Peter,

On May 3, 2013, at 12:07 PM, Peter Levart <peter.levart at gmail.com> wrote:

> 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:
> 

N could be 0, which can occur for spliterators of maps, but for N > 0 i think it unlikely.

However, i am not sure we should explicitly rule it out given sizes may be estimates. I think it may be prudent to give spliterators the wiggle room, as some wiggle in unexpected ways, and document what the best way to wiggle is.

How about we add some non-normative text to the api note of trySplit? i can log another issue for that.

Paul.

>       * 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/view_bug.do?bug_id=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):
>>   * <ul>
>>   * <li>The source cannot be structurally interfered with.
>> - * </br>For example, an instance of
>> + * <br>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}.</li>
>>   * <li>The source manages concurrent modifications.
>> - * </br>For example, a key set of a {@link java.util.concurrent.ConcurrentHashMap}
>> + * <br>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}.</li>
>>   * <li>The mutable source provides a late-binding and fail-fast Spliterator.
>> - * </br>Late binding narrows the window during which interference can affect
>> + * <br>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.</li>
>>   * <li>The mutable source provides a non-late-binding but fail-fast Spliterator.
>> - * </br>The source increases the likelihood of throwing
>> + * <br>The source increases the likelihood of throwing
>>   * {@code ConcurrentModificationException} since the window of potential
>>   * interference is larger.</li>
>>   * <li>The mutable source provides a late-binding and non-fail-fast Spliterator.
>> - * </br>The source risks arbitrary, non-deterministic behavior after traversal
>> + * <br>The source risks arbitrary, non-deterministic behavior after traversal
>>   * has commenced since interference is not detected.
>>   * </li>
>>   * <li>The mutable source provides a non-late-binding and non-fail-fast
>>   * Spliterator.
>> - * </br>The source increases the risk of arbitrary, non-deterministic behavior
>> + * <br>The source increases the risk of arbitrary, non-deterministic behavior
>>   * since non-detected interference may occur after construction.
>>   * </li>
>>   * </ul>
>> @@ -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 <T> the type of elements returned by this Spliterator
>> + *
>>   * @see Collection
>>   * @since 1.8
>>   */
>> @@ -333,9 +335,8 @@
>>       * Upon non-null return:
>>       * <ul>
>>       * <li>the value reported for {@code estimateSize()} before splitting,
>> -     * if not already zero or {@code Long.MAX_VALUE}, must, after splitting, be
>> -     * greater than {@code estimateSize()} for this and the returned
>> -     * Spliterator; and</li>
>> +     * must, after splitting, be greater than or equal to {@code estimateSize()}
>> +     * for this and 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
>