Specs

[Doug Lea]

On 09/03/2013 02:52 PM, Brian Goetz wrote:
> 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.

I agree that people need some advice on the fine points of using
parallel to avoid unexpected slowdowns, but Javadocs are not
an ideal place to describe possibly-transient facts about
crummy performance in various cases. (They belong in the bug database! :-)

I think the only kinds of implicit advice suitable for Javadocs
are based on good examples of good usages.

-Doug