Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8181380

Misleading description of arguments to accumulator function called by LongAccumulator

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 10
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      no actual behavior change.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      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

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                martin Martin Buchholz
                Reporter:
                webbuggrp Webbug Group
                Reviewed By:
                David Holmes, Doug Lea
              • Votes:
                0 Vote for this issue
                Watchers:
                6 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: