From 8e1db99fd66adb544d5ef4c16e8b419bb4be854a Mon Sep 17 00:00:00 2001 From: Doug Lea Date: Sat, 22 Jul 2017 09:08:50 -0700 Subject: [PATCH] 8178956: Misleading description of arguments to accumulator function called by LongAccumulator Reviewed-by: martin, psandoz, dholmes, darcy --- .../util/concurrent/atomic/DoubleAccumulator.java | 12 +++++++----- .../java/util/concurrent/atomic/LongAccumulator.java | 11 ++++++----- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/DoubleAccumulator.java b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/DoubleAccumulator.java index 0d0346f02d6..20c9efa5f2e 100644 --- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/DoubleAccumulator.java +++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/DoubleAccumulator.java @@ -56,11 +56,13 @@ import java.util.function.DoubleBinaryOperator; * *

The supplied accumulator function should be side-effect-free, * since it may be re-applied when attempted updates fail due to - * contention among threads. The function is applied with the current - * value as its first argument, and the given update as the second - * argument. For example, to maintain a running maximum value, you - * could supply {@code Double::max} along with {@code - * Double.NEGATIVE_INFINITY} as the identity. The order of + * contention among threads. For predictable results, the accumulator + * function should be commutative and associative within the floating + * point tolerance required in usage contexts. The function is applied + * with an existing value (or identity) as one argument, and a given + * update as the other argument. For example, to maintain a running + * maximum value, you could supply {@code Double::max} along with + * {@code Double.NEGATIVE_INFINITY} as the identity. The order of * accumulation within or across threads is not guaranteed. Thus, this * class may not be applicable if numerical stability is required, * especially when combining values of substantially different orders diff --git a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/LongAccumulator.java b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/LongAccumulator.java index 8c6e332ad79..71fa3e40651 100644 --- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/LongAccumulator.java +++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/LongAccumulator.java @@ -59,11 +59,12 @@ import java.util.function.LongBinaryOperator; * applicable to functions for which the order of accumulation does * not matter. The supplied accumulator function should be * side-effect-free, since it may be re-applied when attempted updates - * fail due to contention among threads. The function is applied with - * the current value as its first argument, and the given update as - * the second argument. For example, to maintain a running maximum - * value, you could supply {@code Long::max} along with {@code - * Long.MIN_VALUE} as the identity. + * fail due to contention among threads. For predictable results, the + * accumulator function should be associative and commutative. The + * function is applied with an existing value (or identity) as one + * argument, and a given update as the other argument. For example, + * to maintain a running maximum value, you could supply {@code + * Long::max} along with {@code Long.MIN_VALUE} as the identity. * *

Class {@link LongAdder} provides analogs of the functionality of * this class for the common special case of maintaining counts and