Specs

[Brian Goetz]

Agreed.  We need to do more to seed the user's mental cost model, so 
they can reason about what is likely to be faster or slower.

So, what should we be saying, and where should it be said?  Clearly we 
can talk some in the "Parallelism" section.  Also, I think we should 
have some @implNote for some of the problematic operations, such as 
limit, where we describe the cases that work really well (e.g., parallel 
limit works great on SUBSIZED sources) or not so well (groupingBy with 
HashMap sucks in parallel, due to expensive merge.)

On 9/3/2013 2:50 PM, Sam Pullara wrote:
> I still don't think there is sufficient explanation of the motivations around why someone would use parallel() and what the performance implications of using it might be.
>
> Sam
>
> On Sep 3, 2013, at 11:37 AM, Brian Goetz <brian.goetz at oracle.com> wrote:
>
>> Plowing through all of these today...I've got just about all the directly actionable ones processed, stumbling a bit on the less actionable ones (e.g., "This section needs work.")
>>
>> I've updated the docs at the temporary site.
>>
>> Old docs: http://cr.openjdk.java.net/~briangoetz/doctmp/doc0
>> New docs: http://cr.openjdk.java.net/~briangoetz/doctmp/doc1
>>
>> And posted a "specdiff" between them at:
>>   http://cr.openjdk.java.net/~briangoetz/doctmp/diff1
>>
>>
>>
>>
>> On 9/2/2013 2:42 PM, Tim Peierls wrote:
>>> I sent Brian comments on the package summary a couple of days ago. I am
>>> curious to see whether there's any overlap or disagreement between what
>>> Joe wrote and what I wrote, but I'm sort of hoping Brian will summarize
>>> all of the responses rather than having to wade through them myself.
>>> (Yes, I know that just adds to Brian's work pile, but some sort of
>>> summary will be needed in any case.)
>>>
>>> --tim
>>>
>>>
>>> On Mon, Sep 2, 2013 at 12:15 PM, Joe Bowbeer <joe.bowbeer at gmail.com
>>> <mailto:joe.bowbeer at gmail.com>> wrote:
>>>
>>>     I just sent Brian comments on the package description and the
>>>     BaseStream family of interfaces.
>>>
>>>     Overall, I like the way this is coming together.  The package
>>>     description is substantial, but it's worth the programmer's time.
>>>       The references to package-description in the Stream methods are
>>>     effective.  Hey, I *feel* like I understand.
>>>
>>>     However, there's plenty of room for improvement.  I'd be happy to
>>>     send my detailed review - or a simplified summary - to this list if
>>>     there is interest.
>>>
>>>     --Joe
>>>
>>>
>>>     On Wed, Aug 28, 2013 at 2:58 PM, Brian Goetz <brian.goetz at oracle.com
>>>     <mailto:brian.goetz at oracle.com>> wrote:
>>>
>>>         Have I mentioned that reviews of the specs and package doc at:
>>>
>>>         http://cr.openjdk.java.net/~__briangoetz/doctmp/doc/
>>>         <http://cr.openjdk.java.net/~briangoetz/doctmp/doc/>
>>>
>>>         would be appreciated?
>>>
>>>
>>>
>