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

Tagir Valeev amaembo at gmail.com
Tue Aug 4 04:37:14 UTC 2015

Hello, Stuart!

On Tue, Aug 4, 2015 at 5:09 AM, Stuart Marks <stuart.marks at oracle.com>

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

That's fine. In this case it's probably should be explicitly mentioned
something like "note that further change of the stream mode from parallel
to sequential and vice versa is *not guaranteed* to propagate to the source
streams". It would still be better than not speaking about this at all.

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?

It would be nice if it can be fixed, but given the current API I see no
easy way to do this. Probably Paul can comment on this.

With best regards,
Tagir Valeev.

> 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>
> 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/
>> Thanks,
>> s'marks

More information about the core-libs-dev mailing list