# HG changeset patch
# User dl
# Date 1500739730 25200
# Node ID 75c0f4d0ebeaf5cc5027fb2156435751ab251ef4
# Parent  59b4dd84cd5df1d1277d6470e5fda63bcbfbe367
8178956: Misleading description of arguments to accumulator function called by LongAccumulator
Reviewed-by: martin, psandoz, dholmes, darcy

diff -r 59b4dd84cd5d -r 75c0f4d0ebea jdk/src/java.base/share/classes/java/util/concurrent/atomic/DoubleAccumulator.java
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/DoubleAccumulator.java	Sat Jul 22 09:03:50 2017 -0700
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/DoubleAccumulator.java	Sat Jul 22 09:08:50 2017 -0700
@@ -56,11 +56,13 @@
  *
  * <p>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 -r 59b4dd84cd5d -r 75c0f4d0ebea jdk/src/java.base/share/classes/java/util/concurrent/atomic/LongAccumulator.java
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/LongAccumulator.java	Sat Jul 22 09:03:50 2017 -0700
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/LongAccumulator.java	Sat Jul 22 09:08:50 2017 -0700
@@ -59,11 +59,12 @@
  * 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.
  *
  * <p>Class {@link LongAdder} provides analogs of the functionality of
  * this class for the common special case of maintaining counts and