This class is usually preferable to {@link AtomicLong} when + * multiple threads update a common value that is used for purposes such + * as collecting statistics, not for fine-grained synchronization + * control. Under low update contention, the two classes have similar + * characteristics. But under high contention, expected throughput of + * this class is significantly higher, at the expense of higher space + * consumption. + * + *
The order of accumulation within or across threads is not + * guaranteed and cannot be depended upon, so this class is only + * 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. + * + *
Class {@link LongAdder} provides analogs of the functionality of + * this class for the common special case of maintaining counts and + * sums. The call {@code new LongAdder()} is equivalent to {@code new + * LongAccumulator((x, y) -> x + y, 0L}. + * + *
This class extends {@link Number}, but does not define + * methods such as {@code equals}, {@code hashCode} and {@code + * compareTo} because instances are expected to be mutated, and so are + * not useful as collection keys. + * + * @since 1.8 + * @author Doug Lea + */ +public class LongAccumulator extends Striped64 implements Serializable { + private static final long serialVersionUID = 7249069246863182397L; + + private final LongBinaryOperator function; + private final long identity; + + /** + * Creates a new instance using the given accumulator function + * and identity element. + */ + public LongAccumulator(LongBinaryOperator accumulatorFunction, + long identity) { + this.function = accumulatorFunction; + base = this.identity = identity; + } + + /** + * Updates with the given value. + * + * @param x the value + */ + public void accumulate(long x) { + Cell[] as; long b, v, r; int m; Cell a; + if ((as = cells) != null || + (r = function.operateAsLong(b = base, x)) != b && !casBase(b, r)) { + boolean uncontended = true; + if (as == null || (m = as.length - 1) < 0 || + (a = as[getProbe() & m]) == null || + !(uncontended = + (r = function.operateAsLong(v = a.value, x)) == v || + a.cas(v, r))) + longAccumulate(x, function, uncontended); + } + } + + /** + * Returns the current value. The returned value is NOT + * an atomic snapshot; invocation in the absence of concurrent + * updates returns an accurate result, but concurrent updates that + * occur while the value is being calculated might not be + * incorporated. + * + * @return the current value + */ + public long get() { + Cell[] as = cells; Cell a; + long result = base; + if (as != null) { + for (int i = 0; i < as.length; ++i) { + if ((a = as[i]) != null) + result = function.operateAsLong(result, a.value); + } + } + return result; + } + + /** + * Resets variables maintaining updates to the identity value. + * This method may be a useful alternative to creating a new + * updater, but is only effective if there are no concurrent + * updates. Because this method is intrinsically racy, it should + * only be used when it is known that no threads are concurrently + * updating. + */ + public void reset() { + Cell[] as = cells; Cell a; + base = identity; + if (as != null) { + for (int i = 0; i < as.length; ++i) { + if ((a = as[i]) != null) + a.value = identity; + } + } + } + + /** + * Equivalent in effect to {@link #get} followed by {@link + * #reset}. This method may apply for example during quiescent + * points between multithreaded computations. If there are + * updates concurrent with this method, the returned value is + * not guaranteed to be the final value occurring before + * the reset. + * + * @return the value before reset + */ + public long getThenReset() { + Cell[] as = cells; Cell a; + long result = base; + base = identity; + if (as != null) { + for (int i = 0; i < as.length; ++i) { + if ((a = as[i]) != null) { + long v = a.value; + a.value = identity; + result = function.operateAsLong(result, v); + } + } + } + return result; + } + + /** + * Returns the String representation of the current value. + * @return the String representation of the current value + */ + public String toString() { + return Long.toString(get()); + } + + /** + * Equivalent to {@link #get}. + * + * @return the current value + */ + public long longValue() { + return get(); + } + + /** + * Returns the {@linkplain #get current value} as an {@code int} + * after a narrowing primitive conversion. + */ + public int intValue() { + return (int)get(); + } + + /** + * Returns the {@linkplain #get current value} as a {@code float} + * after a widening primitive conversion. + */ + public float floatValue() { + return (float)get(); + } + + /** + * Returns the {@linkplain #get current value} as a {@code double} + * after a widening primitive conversion. + */ + public double doubleValue() { + return (double)get(); + } + + private void writeObject(java.io.ObjectOutputStream s) + throws java.io.IOException { + s.defaultWriteObject(); + s.writeLong(get()); + } + + private void readObject(java.io.ObjectInputStream s) + throws java.io.IOException, ClassNotFoundException { + s.defaultReadObject(); + cellsBusy = 0; + cells = null; + base = s.readLong(); + } + +}