1 /* 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * 4 * This code is free software; you can redistribute it and/or modify it 5 * under the terms of the GNU General Public License version 2 only, as 6 * published by the Free Software Foundation. Oracle designates this 7 * particular file as subject to the "Classpath" exception as provided 8 * by Oracle in the LICENSE file that accompanied this code. 9 * 10 * This code is distributed in the hope that it will be useful, but WITHOUT 11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 13 * version 2 for more details (a copy is included in the LICENSE file that 14 * accompanied this code). 15 * 16 * You should have received a copy of the GNU General Public License version 17 * 2 along with this work; if not, write to the Free Software Foundation, 18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 19 * 20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 21 * or visit www.oracle.com if you need additional information or have any 22 * questions. 23 */ 24 25 /* 26 * This file is available under and governed by the GNU General Public 27 * License version 2 only, as published by the Free Software Foundation. 28 * However, the following notice accompanied the original version of this 29 * file: 30 * 31 * Written by Doug Lea with assistance from members of JCP JSR-166 32 * Expert Group and released to the public domain, as explained at 33 * http://creativecommons.org/publicdomain/zero/1.0/ 34 */ 35 36 package java.util.concurrent.atomic; 37 38 import java.io.Serializable; 39 import java.util.function.LongBinaryOperator; 40 41 /** 42 * One or more variables that together maintain a running {@code long} 43 * value updated using a supplied function. When updates (method 44 * {@link #accumulate}) are contended across threads, the set of variables 45 * may grow dynamically to reduce contention. Method {@link #get} 46 * (or, equivalently, {@link #longValue}) returns the current value 47 * across the variables maintaining updates. 48 * 49 * <p>This class is usually preferable to {@link AtomicLong} when 50 * multiple threads update a common value that is used for purposes such 51 * as collecting statistics, not for fine-grained synchronization 52 * control. Under low update contention, the two classes have similar 53 * characteristics. But under high contention, expected throughput of 54 * this class is significantly higher, at the expense of higher space 55 * consumption. 56 * 57 * <p>The order of accumulation within or across threads is not 58 * guaranteed and cannot be depended upon, so this class is only 59 * applicable to functions for which the order of accumulation does 60 * not matter. The supplied accumulator function should be 61 * side-effect-free, since it may be re-applied when attempted updates 62 * fail due to contention among threads. For predictable results, the 63 * accumulator function should be associative and commutative. The 64 * function is applied with an existing value (or identity) as one 65 * argument, and a given update as the other argument. For example, 66 * to maintain a running maximum value, you could supply {@code 67 * Long::max} along with {@code Long.MIN_VALUE} as the identity. 68 * 69 * <p>Class {@link LongAdder} provides analogs of the functionality of 70 * this class for the common special case of maintaining counts and 71 * sums. The call {@code new LongAdder()} is equivalent to {@code new 72 * LongAccumulator((x, y) -> x + y, 0L)}. 73 * 74 * <p>This class extends {@link Number}, but does <em>not</em> define 75 * methods such as {@code equals}, {@code hashCode} and {@code 76 * compareTo} because instances are expected to be mutated, and so are 77 * not useful as collection keys. 78 * 79 * @since 1.8 80 * @author Doug Lea 81 */ 82 public class LongAccumulator extends Striped64 implements Serializable { 83 private static final long serialVersionUID = 7249069246863182397L; 84 85 @SuppressWarnings("serial") // Not statically typed as Serializable 86 private final LongBinaryOperator function; 87 private final long identity; 88 89 /** 90 * Creates a new instance using the given accumulator function 91 * and identity element. 92 * @param accumulatorFunction a side-effect-free function of two arguments 93 * @param identity identity (initial value) for the accumulator function 94 */ 95 public LongAccumulator(LongBinaryOperator accumulatorFunction, 96 long identity) { 97 this.function = accumulatorFunction; 98 base = this.identity = identity; 99 } 100 101 /** 102 * Updates with the given value. 103 * 104 * @param x the value 105 */ 106 public void accumulate(long x) { 107 Cell[] cs; long b, v, r; int m; Cell c; 108 if ((cs = cells) != null 109 || ((r = function.applyAsLong(b = base, x)) != b 110 && !casBase(b, r))) { 111 boolean uncontended = true; 112 if (cs == null 113 || (m = cs.length - 1) < 0 114 || (c = cs[getProbe() & m]) == null 115 || !(uncontended = 116 (r = function.applyAsLong(v = c.value, x)) == v 117 || c.cas(v, r))) 118 longAccumulate(x, function, uncontended); 119 } 120 } 121 122 /** 123 * Returns the current value. The returned value is <em>NOT</em> 124 * an atomic snapshot; invocation in the absence of concurrent 125 * updates returns an accurate result, but concurrent updates that 126 * occur while the value is being calculated might not be 127 * incorporated. 128 * 129 * @return the current value 130 */ 131 public long get() { 132 Cell[] cs = cells; 133 long result = base; 134 if (cs != null) { 135 for (Cell c : cs) 136 if (c != null) 137 result = function.applyAsLong(result, c.value); 138 } 139 return result; 140 } 141 142 /** 143 * Resets variables maintaining updates to the identity value. 144 * This method may be a useful alternative to creating a new 145 * updater, but is only effective if there are no concurrent 146 * updates. Because this method is intrinsically racy, it should 147 * only be used when it is known that no threads are concurrently 148 * updating. 149 */ 150 public void reset() { 151 Cell[] cs = cells; 152 base = identity; 153 if (cs != null) { 154 for (Cell c : cs) 155 if (c != null) 156 c.reset(identity); 157 } 158 } 159 160 /** 161 * Equivalent in effect to {@link #get} followed by {@link 162 * #reset}. This method may apply for example during quiescent 163 * points between multithreaded computations. If there are 164 * updates concurrent with this method, the returned value is 165 * <em>not</em> guaranteed to be the final value occurring before 166 * the reset. 167 * 168 * @return the value before reset 169 */ 170 public long getThenReset() { 171 Cell[] cs = cells; 172 long result = getAndSetBase(identity); 173 if (cs != null) { 174 for (Cell c : cs) { 175 if (c != null) { 176 long v = c.getAndSet(identity); 177 result = function.applyAsLong(result, v); 178 } 179 } 180 } 181 return result; 182 } 183 184 /** 185 * Returns the String representation of the current value. 186 * @return the String representation of the current value 187 */ 188 public String toString() { 189 return Long.toString(get()); 190 } 191 192 /** 193 * Equivalent to {@link #get}. 194 * 195 * @return the current value 196 */ 197 public long longValue() { 198 return get(); 199 } 200 201 /** 202 * Returns the {@linkplain #get current value} as an {@code int} 203 * after a narrowing primitive conversion. 204 */ 205 public int intValue() { 206 return (int)get(); 207 } 208 209 /** 210 * Returns the {@linkplain #get current value} as a {@code float} 211 * after a widening primitive conversion. 212 */ 213 public float floatValue() { 214 return (float)get(); 215 } 216 217 /** 218 * Returns the {@linkplain #get current value} as a {@code double} 219 * after a widening primitive conversion. 220 */ 221 public double doubleValue() { 222 return (double)get(); 223 } 224 225 /** 226 * Serialization proxy, used to avoid reference to the non-public 227 * Striped64 superclass in serialized forms. 228 * @serial include 229 */ 230 private static class SerializationProxy implements Serializable { 231 private static final long serialVersionUID = 7249069246863182397L; 232 233 /** 234 * The current value returned by get(). 235 * @serial 236 */ 237 private final long value; 238 239 /** 240 * The function used for updates. 241 * @serial 242 */ 243 @SuppressWarnings("serial") // Not statically typed as Serializable 244 private final LongBinaryOperator function; 245 246 /** 247 * The identity value. 248 * @serial 249 */ 250 private final long identity; 251 252 SerializationProxy(long value, 253 LongBinaryOperator function, 254 long identity) { 255 this.value = value; 256 this.function = function; 257 this.identity = identity; 258 } 259 260 /** 261 * Returns a {@code LongAccumulator} object with initial state 262 * held by this proxy. 263 * 264 * @return a {@code LongAccumulator} object with initial state 265 * held by this proxy 266 */ 267 private Object readResolve() { 268 LongAccumulator a = new LongAccumulator(function, identity); 269 a.base = value; 270 return a; 271 } 272 } 273 274 /** 275 * Returns a 276 * <a href="{@docRoot}/serialized-form.html#java.util.concurrent.atomic.LongAccumulator.SerializationProxy"> 277 * SerializationProxy</a> 278 * representing the state of this instance. 279 * 280 * @return a {@link SerializationProxy} 281 * representing the state of this instance 282 */ 283 private Object writeReplace() { 284 return new SerializationProxy(get(), function, identity); 285 } 286 287 /** 288 * @param s the stream 289 * @throws java.io.InvalidObjectException always 290 */ 291 private void readObject(java.io.ObjectInputStream s) 292 throws java.io.InvalidObjectException { 293 throw new java.io.InvalidObjectException("Proxy required"); 294 } 295 296 }