Summary

j.u.c.atomic Accumulator specs are misleading

Problem

User complains:

The documentation says: 'The function is applied with the current value as its first argument, and the given update as the second argument." This is not true, since the function may actually be called with two "update values".

Solution

We should also add that:

accumulator function should be associative and commutative

Specification

http://cr.openjdk.java.net/~martin/webrevs/openjdk10/jsr166-integration/Accumulator-specs/

--- old/src/java.base/share/classes/java/util/concurrent/atomic/DoubleAccumulator.java  2017-05-31 13:29:10.364188933 -0700
+++ new/src/java.base/share/classes/java/util/concurrent/atomic/DoubleAccumulator.java  2017-05-31 13:29:10.160189201 -0700
@@ -56,11 +56,12 @@
  *
  * <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 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 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
--- old/src/java.base/share/classes/java/util/concurrent/atomic/LongAccumulator.java    2017-05-31 13:29:11.112187950 -0700
+++ new/src/java.base/share/classes/java/util/concurrent/atomic/LongAccumulator.java    2017-05-31 13:29:10.920188202 -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