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      */
LongAccumulator(LongBinaryOperator accumulatorFunction, long identity)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      */
accumulate(long x)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             int index = getProbe();
112             boolean uncontended = true;
113             if (cs == null
114                 || (m = cs.length - 1) < 0
115                 || (c = cs[index & m]) == null
116                 || !(uncontended =
117                      (r = function.applyAsLong(v = c.value, x)) == v
118                      || c.cas(v, r)))
119                 longAccumulate(x, function, uncontended, index);
120         }
121     }
122 
123     /**
124      * Returns the current value.  The returned value is <em>NOT</em>
125      * an atomic snapshot; invocation in the absence of concurrent
126      * updates returns an accurate result, but concurrent updates that
127      * occur while the value is being calculated might not be
128      * incorporated.
129      *
130      * @return the current value
131      */
get()132     public long get() {
133         Cell[] cs = cells;
134         long result = base;
135         if (cs != null) {
136             for (Cell c : cs)
137                 if (c != null)
138                     result = function.applyAsLong(result, c.value);
139         }
140         return result;
141     }
142 
143     /**
144      * Resets variables maintaining updates to the identity value.
145      * This method may be a useful alternative to creating a new
146      * updater, but is only effective if there are no concurrent
147      * updates.  Because this method is intrinsically racy, it should
148      * only be used when it is known that no threads are concurrently
149      * updating.
150      */
reset()151     public void reset() {
152         Cell[] cs = cells;
153         base = identity;
154         if (cs != null) {
155             for (Cell c : cs)
156                 if (c != null)
157                     c.reset(identity);
158         }
159     }
160 
161     /**
162      * Equivalent in effect to {@link #get} followed by {@link
163      * #reset}. This method may apply for example during quiescent
164      * points between multithreaded computations.  If there are
165      * updates concurrent with this method, the returned value is
166      * <em>not</em> guaranteed to be the final value occurring before
167      * the reset.
168      *
169      * @return the value before reset
170      */
getThenReset()171     public long getThenReset() {
172         Cell[] cs = cells;
173         long result = getAndSetBase(identity);
174         if (cs != null) {
175             for (Cell c : cs) {
176                 if (c != null) {
177                     long v = c.getAndSet(identity);
178                     result = function.applyAsLong(result, v);
179                 }
180             }
181         }
182         return result;
183     }
184 
185     /**
186      * Returns the String representation of the current value.
187      * @return the String representation of the current value
188      */
toString()189     public String toString() {
190         return Long.toString(get());
191     }
192 
193     /**
194      * Equivalent to {@link #get}.
195      *
196      * @return the current value
197      */
longValue()198     public long longValue() {
199         return get();
200     }
201 
202     /**
203      * Returns the {@linkplain #get current value} as an {@code int}
204      * after a narrowing primitive conversion.
205      */
intValue()206     public int intValue() {
207         return (int)get();
208     }
209 
210     /**
211      * Returns the {@linkplain #get current value} as a {@code float}
212      * after a widening primitive conversion.
213      */
floatValue()214     public float floatValue() {
215         return (float)get();
216     }
217 
218     /**
219      * Returns the {@linkplain #get current value} as a {@code double}
220      * after a widening primitive conversion.
221      */
doubleValue()222     public double doubleValue() {
223         return (double)get();
224     }
225 
226     /**
227      * Serialization proxy, used to avoid reference to the non-public
228      * Striped64 superclass in serialized forms.
229      * @serial include
230      */
231     private static class SerializationProxy implements Serializable {
232         private static final long serialVersionUID = 7249069246863182397L;
233 
234         /**
235          * The current value returned by get().
236          * @serial
237          */
238         private final long value;
239 
240         /**
241          * The function used for updates.
242          * @serial
243          */
244         @SuppressWarnings("serial") // Not statically typed as Serializable
245         private final LongBinaryOperator function;
246 
247         /**
248          * The identity value.
249          * @serial
250          */
251         private final long identity;
252 
SerializationProxy(long value, LongBinaryOperator function, long identity)253         SerializationProxy(long value,
254                            LongBinaryOperator function,
255                            long identity) {
256             this.value = value;
257             this.function = function;
258             this.identity = identity;
259         }
260 
261         /**
262          * Returns a {@code LongAccumulator} object with initial state
263          * held by this proxy.
264          *
265          * @return a {@code LongAccumulator} object with initial state
266          * held by this proxy
267          */
readResolve()268         private Object readResolve() {
269             LongAccumulator a = new LongAccumulator(function, identity);
270             a.base = value;
271             return a;
272         }
273     }
274 
275     /**
276      * Returns a
277      * <a href="{@docRoot}/serialized-form.html#java.util.concurrent.atomic.LongAccumulator.SerializationProxy">
278      * SerializationProxy</a>
279      * representing the state of this instance.
280      *
281      * @return a {@link SerializationProxy}
282      * representing the state of this instance
283      */
writeReplace()284     private Object writeReplace() {
285         return new SerializationProxy(get(), function, identity);
286     }
287 
288     /**
289      * @param s the stream
290      * @throws java.io.InvalidObjectException always
291      */
readObject(java.io.ObjectInputStream s)292     private void readObject(java.io.ObjectInputStream s)
293         throws java.io.InvalidObjectException {
294         throw new java.io.InvalidObjectException("Proxy required");
295     }
296 
297 }
298