This class is usually preferable to alternatives when multiple * threads update a common value that is used for purposes such as * summary statistics that are frequently updated but less frequently * read. * *
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 DoubleAdder extends Striped64 implements Serializable { private static final long serialVersionUID = 7249069246863182397L; /* * Note that we must use "long" for underlying representations, * because there is no compareAndSet for double, due to the fact * that the bitwise equals used in any CAS implementation is not * the same as double-precision equals. However, we use CAS only * to detect and alleviate contention, for which bitwise equals * works best anyway. In principle, the long/double conversions * used here should be essentially free on most platforms since * they just re-interpret bits. */ /** * Creates a new adder with initial sum of zero. */ public DoubleAdder() { } /** * Adds the given value. * * @param x the value to add */ public void add(double x) { Cell[] cs; long b, v; int m; Cell c; if ((cs = cells) != null || !casBase(b = base, Double.doubleToRawLongBits (Double.longBitsToDouble(b) + x))) { boolean uncontended = true; if (cs == null || (m = cs.length - 1) < 0 || (c = cs[getProbe() & m]) == null || !(uncontended = c.cas(v = c.value, Double.doubleToRawLongBits (Double.longBitsToDouble(v) + x)))) doubleAccumulate(x, null, uncontended); } } /** * Returns the current sum. 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 sum is being calculated might not be * incorporated. Also, because floating-point arithmetic is not * strictly associative, the returned result need not be identical * to the value that would be obtained in a sequential series of * updates to a single variable. * * @return the sum */ public double sum() { Cell[] cs = cells; double sum = Double.longBitsToDouble(base); if (cs != null) { for (Cell c : cs) if (c != null) sum += Double.longBitsToDouble(c.value); } return sum; } /** * Resets variables maintaining the sum to zero. This method may * be a useful alternative to creating a new adder, 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[] cs = cells; base = 0L; // relies on fact that double 0 must have same rep as long if (cs != null) { for (Cell c : cs) if (c != null) c.reset(); } } /** * Equivalent in effect to {@link #sum} 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 sum */ public double sumThenReset() { Cell[] cs = cells; double sum = Double.longBitsToDouble(getAndSetBase(0L)); if (cs != null) { for (Cell c : cs) { if (c != null) sum += Double.longBitsToDouble(c.getAndSet(0L)); } } return sum; } /** * Returns the String representation of the {@link #sum}. * @return the String representation of the {@link #sum} */ public String toString() { return Double.toString(sum()); } /** * Equivalent to {@link #sum}. * * @return the sum */ public double doubleValue() { return sum(); } /** * Returns the {@link #sum} as a {@code long} after a * narrowing primitive conversion. */ public long longValue() { return (long)sum(); } /** * Returns the {@link #sum} as an {@code int} after a * narrowing primitive conversion. */ public int intValue() { return (int)sum(); } /** * Returns the {@link #sum} as a {@code float} * after a narrowing primitive conversion. */ public float floatValue() { return (float)sum(); } /** * Serialization proxy, used to avoid reference to the non-public * Striped64 superclass in serialized forms. * @serial include */ private static class SerializationProxy implements Serializable { private static final long serialVersionUID = 7249069246863182397L; /** * The current value returned by sum(). * @serial */ private final double value; SerializationProxy(DoubleAdder a) { value = a.sum(); } /** * Returns a {@code DoubleAdder} object with initial state * held by this proxy. * * @return a {@code DoubleAdder} object with initial state * held by this proxy */ private Object readResolve() { DoubleAdder a = new DoubleAdder(); a.base = Double.doubleToRawLongBits(value); return a; } } /** * Returns a * * SerializationProxy * representing the state of this instance. * * @return a {@link SerializationProxy} * representing the state of this instance */ private Object writeReplace() { return new SerializationProxy(this); } /** * @param s the stream * @throws java.io.InvalidObjectException always */ private void readObject(java.io.ObjectInputStream s) throws java.io.InvalidObjectException { throw new java.io.InvalidObjectException("Proxy required"); } }