RFR 8014824: Document Spliterator characteristics and binding policy of java util collection impls

[Paul Sandoz]

On Aug 12, 2013, at 1:00 PM, Peter Levart <peter.levart at gmail.com> wrote:
>> To be clear: computation may be altered (that is the why the characteristics are useful) but the results should be consistent. The characteristics allow for "wiggle room" to optimize.
>> 
>> This email thread promoted to me think a little more and while i don't think there is any issue spliterators of empty collections, there could be an issue with singletons when used with flatMap.
>> 
>>   Collections.singletonList(1).flatMap(x -> Stream.of(1, 2, 3)).parallel()...
>>   Collections.singleton(1).flatMap(x -> Stream.of(1, 2, 3)).parallel()...
>> 
>> The first stream should retain encounter order for 1 substituted for 1, 2, 3, where as the second stream does not have to. It just so happens the current flatMap implementation imputes order and thus preserves any order (elements are substituted sequentially at the leafs after splitting has occurred, which for this case is no splits).
>> 
>> The flatMap implementation could change to have better parallel performance, although it is currently hard to imagine it doing so at least for JDK 8. To be on the safe side the shared singleton implementation should report ORDERED (which it currently does), but this implies we will need to specify this for any shared use between singleton collections.
>> 
>> OK, i am gonna about turn on singletons, and keep things simple, and update the package private Collection.singletonSpliterator to take a characteristics parameter to ensure consistency with the collection type.
> 
> Hi Paul,
> 
> Concatenating two ORDERED streams normally produces an ORDERED stream. Now if one is concatenating an ORDERED stream with an empty stream, what comes out should also be an ORDERED stream, don't you think?
> 

Yes, good point, but I suppose the general expectation is that the stream returned from Stream.concat(s, Stream.emptyStream()) is equivalent to or is s.

We can easily do this by checking if a spliterator is SIZED and the estimate is zero, which will also work for any SIZED empty stream regardless of how it was created.

In this case it would appear sufficient to state that a spliterator of a collection covering zero elements need only report SIZED and is not required to report all the characters as defined by the collection.

Paul.