JDK 8 code review request forJDK-8024354: Explicitly permit DoubleStream.sum()/average() implementations to use higher precision summation

[Joe Darcy]

On 10/08/2013 08:08 PM, Mike Duigou wrote:
> This seems to contradict the main documentation for these methods.

The general guidance is still valid, bug we want to allow algorithms 
with better worst-case behavior than simple summation.

(I didn't think it would be helpful for most readers to start talking 
about error bounds or to otherwise explain the desired quality of 
implementation constraints on the behavior of the method.)

>   Perhaps instead we should remove the "The average returned can vary depending upon the order in which values are recorded. This is due to accumulated rounding error in addition of values of differing magnitudes. Values sorted by increasing absolute magnitude tend to yield more accurate results." into an @implNote?
>
> I also suspect that having this documentation only in DoubleSummaryStatistics may be too hidden away. Perhaps similar docs on DoubleStream sum() and average() methods as well?

Numerically, using similar techniques in DoubleStream is preferable, but 
specification like

     /**
      * Returns the sum of elements in this stream.  The sum returned 
can vary
      * depending upon the order in which elements are encountered. This 
is due
      * to accumulated rounding error in addition of values of differing
      * magnitudes. Elements sorted by increasing absolute magnitude tend to
      * yield more accurate results.  If any stream element is a {@code 
NaN} or
      * the sum is at any point a {@code NaN} then the sum will be 
{@code NaN}.
      * This is a special case of a
      * <a href="package-summary.html#Reduction">reduction</a> and is
      * equivalent to:
      * <pre>{@code
      *     return reduce(0, Double::sum);
      * }</pre>
      *
      * <p>This is a <a href="package-summary.html#StreamOps">terminal
      * operation</a>.
      *
      * @return the sum of elements in this stream
      */
     double sum();

would need to be updated.

-Joe

>
> Mike
>
> On Oct 8 2013, at 18:56 , Joe Darcy wrote:
>
>> Hello,
>>
>> Please review the patch below which addresses
>>
>>         JDK-8024354 Explicitly permit DoubleStream.sum()/average() implementations to use higher precision summation
>>
>> Thanks,
>>
>> -Joe
>>
>> diff -r f1e31376f419 src/share/classes/java/util/DoubleSummaryStatistics.java
>> --- a/src/share/classes/java/util/DoubleSummaryStatistics.java Wed Oct 09 00:10:02 2013 +0100
>> +++ b/src/share/classes/java/util/DoubleSummaryStatistics.java Tue Oct 08 18:54:55 2013 -0700
>> @@ -118,6 +118,11 @@
>>       * value is a {@code NaN} or the sum is at any point a {@code NaN} then the
>>       * sum will be {@code NaN}.
>>       *
>> +     * @implNote This method may be implemented using compensated
>> +     * summation or other technique to reduce the error bound in the
>> +     * numerical sum compared to a simple summation of {@code double}
>> +     * values.
>> +     *
>>       * @return the sum of values, or zero if none
>>       */
>>      public final double getSum() {
>> @@ -161,6 +166,10 @@
>>       * value is a {@code NaN} or the sum is at any point a {@code NaN} then the
>>       * average will be {@code NaN}.
>>       *
>> +     * @implNote This method may be implemented using compensated
>> +     * summation or other technique to reduce the error bound in the
>> +     * numerical sum used to compute the average.
>> +     *
>>       * @return the arithmetic mean of values, or zero if none
>>       */
>>      public final double getAverage() {
>>