RFR 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit

Fri May 3 19:42:29 UTC 2013

On 05/03/2013 09:10 PM, Paul Sandoz wrote:
> Hi Peter,
>
> On May 3, 2013, at 12:07 PM, Peter Levart <peter.levart at gmail.com 
> <mailto: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.

Now looking at the whole JavaDoc, I see there is already the following 
at the top of trySplit:

      * <p>Unless this Spliterator covers an infinite number of elements,
      * repeated calls to {@code trySplit()} must eventually return 
{@code null}.

Which I think is enough of a hint for the eventual implementor of the 
interface to conclude that this (and not N+0 or 0+N) is the sole 
terminating condition for the process of splitting.

Regards, Peter

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