RFR(s): 8132800: clarify stream package documentation regarding sequential vs parallel modes

[Stuart Marks]

Hi Tagir,

Interesting issues.

Regarding Stream.concat, it may be that, today, changes to the 
sequential/parallel execution mode aren't propagated to the streams being 
concatenated. But is that something inherent to the specification of 
concatenation, or is it something that might change in the future? It's 
currently unspecified, so adding a clarification really sounds more like 
changing the specification to reflect the current implementation, which I'd 
prefer not to do.

Regarding the default implementations of takeWhile/dropWhile, again, today, they 
don't propagate the execution mode upstream. But is this just a bug? Granted the 
API for doing so isn't obvious, but isn't this something that could just be fixed?

s'marks

On 7/31/15 9:36 PM, Tagir Valeev wrote:
> Hello!
>
> Probably additional clarifications should be added about Stream.concat method 
> (and primitive analogs). Currently it's unclear that the resulting stream is 
> actually the new pipeline, which do not propagate parallel status to the 
> concatenated streams. See also my StackOverflow question:
> http://stackoverflow.com/q/30464397/4856258
>
> Also things become more complex in JDK9 with the introduction of 
> takeWhile/dropWhile. For JDK Stream implementation these two are normal 
> intermediate operations, but if it happens that user has his own stream 
> implementation or delegate to JDK stream, then the default takeWhile/dropWhile 
> implementation is used which is actually starts new pipeline at given point, 
> so further changes of parallel/sequential mode are not propagated to the 
> initial pipeline. In my StreamEx library I call such operations as 
> "quasi-intermediate", and explicitly clarify this point. See the JavaDoc:
> http://amaembo.github.io/streamex/javadoc/javax/util/streamex/package-summary.html#StreamOps
> Probably some clarification should be added to @implSpec section of 
> takeWhile/dropWhile.
>
> With best regards,
> Tagir Valeev.
>
> On Sat, Aug 1, 2015 at 3:19 AM, Stuart Marks <stuart.marks at oracle.com 
> <mailto:stuart.marks at oracle.com>> wrote:
>
>     Hi all,
>
>     The sequential() and parallel() methods on a stream set the execution mode
>     for the entire pipeline. Unfortunately this isn't particularly clear from
>     the documentation. This has been a recurring question. Please review this
>     change to the java.util.stream package documentation to help clarify this
>     point.
>
>     I've also added a couple anchor tags that were missing from various sections.
>
>     This is intended to be a purely editorial change, not a specification change.
>
>     Bug:
>
>     https://bugs.openjdk.java.net/browse/JDK-8132800
>
>     Webrev:
>
>     http://cr.openjdk.java.net/~smarks/reviews/8132800/webrev.0/
>     <http://cr.openjdk.java.net/%7Esmarks/reviews/8132800/webrev.0/>
>
>     Thanks,
>
>     s'marks
>
>