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 
40 /**
41  * One or more variables that together maintain an initially zero
42  * {@code long} sum.  When updates (method {@link #add}) are contended
43  * across threads, the set of variables may grow dynamically to reduce
44  * contention. Method {@link #sum} (or, equivalently, {@link
45  * #longValue}) returns the current total combined across the
46  * variables maintaining the sum.
47  *
48  * <p>This class is usually preferable to {@link AtomicLong} when
49  * multiple threads update a common sum that is used for purposes such
50  * as collecting statistics, not for fine-grained synchronization
51  * control.  Under low update contention, the two classes have similar
52  * characteristics. But under high contention, expected throughput of
53  * this class is significantly higher, at the expense of higher space
54  * consumption.
55  *
56  * <p>LongAdders can be used with a {@link
57  * java.util.concurrent.ConcurrentHashMap} to maintain a scalable
58  * frequency map (a form of histogram or multiset). For example, to
59  * add a count to a {@code ConcurrentHashMap<String,LongAdder> freqs},
60  * initializing if not already present, you can use {@code
61  * freqs.computeIfAbsent(key, k -> new LongAdder()).increment();}
62  *
63  * <p>This class extends {@link Number}, but does <em>not</em> define
64  * methods such as {@code equals}, {@code hashCode} and {@code
65  * compareTo} because instances are expected to be mutated, and so are
66  * not useful as collection keys.
67  *
68  * @since 1.8
69  * @author Doug Lea
70  */
71 public class LongAdder extends Striped64 implements Serializable {
72     private static final long serialVersionUID = 7249069246863182397L;
73 
74     /**
75      * Creates a new adder with initial sum of zero.
76      */
LongAdder()77     public LongAdder() {
78     }
79 
80     /**
81      * Adds the given value.
82      *
83      * @param x the value to add
84      */
add(long x)85     public void add(long x) {
86         Cell[] as; long b, v; int m; Cell a;
87         if ((as = cells) != null || !casBase(b = base, b + x)) {
88             boolean uncontended = true;
89             if (as == null || (m = as.length - 1) < 0 ||
90                 (a = as[getProbe() & m]) == null ||
91                 !(uncontended = a.cas(v = a.value, v + x)))
92                 longAccumulate(x, null, uncontended);
93         }
94     }
95 
96     /**
97      * Equivalent to {@code add(1)}.
98      */
increment()99     public void increment() {
100         add(1L);
101     }
102 
103     /**
104      * Equivalent to {@code add(-1)}.
105      */
decrement()106     public void decrement() {
107         add(-1L);
108     }
109 
110     /**
111      * Returns the current sum.  The returned value is <em>NOT</em> an
112      * atomic snapshot; invocation in the absence of concurrent
113      * updates returns an accurate result, but concurrent updates that
114      * occur while the sum is being calculated might not be
115      * incorporated.
116      *
117      * @return the sum
118      */
sum()119     public long sum() {
120         Cell[] as = cells;
121         long sum = base;
122         if (as != null) {
123             for (Cell a : as)
124                 if (a != null)
125                     sum += a.value;
126         }
127         return sum;
128     }
129 
130     /**
131      * Resets variables maintaining the sum to zero.  This method may
132      * be a useful alternative to creating a new adder, but is only
133      * effective if there are no concurrent updates.  Because this
134      * method is intrinsically racy, it should only be used when it is
135      * known that no threads are concurrently updating.
136      */
reset()137     public void reset() {
138         Cell[] as = cells;
139         base = 0L;
140         if (as != null) {
141             for (Cell a : as)
142                 if (a != null)
143                     a.reset();
144         }
145     }
146 
147     /**
148      * Equivalent in effect to {@link #sum} followed by {@link
149      * #reset}. This method may apply for example during quiescent
150      * points between multithreaded computations.  If there are
151      * updates concurrent with this method, the returned value is
152      * <em>not</em> guaranteed to be the final value occurring before
153      * the reset.
154      *
155      * @return the sum
156      */
sumThenReset()157     public long sumThenReset() {
158         Cell[] as = cells;
159         long sum = base;
160         base = 0L;
161         if (as != null) {
162             for (Cell a : as) {
163                 if (a != null) {
164                     sum += a.value;
165                     a.reset();
166                 }
167             }
168         }
169         return sum;
170     }
171 
172     /**
173      * Returns the String representation of the {@link #sum}.
174      * @return the String representation of the {@link #sum}
175      */
toString()176     public String toString() {
177         return Long.toString(sum());
178     }
179 
180     /**
181      * Equivalent to {@link #sum}.
182      *
183      * @return the sum
184      */
longValue()185     public long longValue() {
186         return sum();
187     }
188 
189     /**
190      * Returns the {@link #sum} as an {@code int} after a narrowing
191      * primitive conversion.
192      */
intValue()193     public int intValue() {
194         return (int)sum();
195     }
196 
197     /**
198      * Returns the {@link #sum} as a {@code float}
199      * after a widening primitive conversion.
200      */
floatValue()201     public float floatValue() {
202         return (float)sum();
203     }
204 
205     /**
206      * Returns the {@link #sum} as a {@code double} after a widening
207      * primitive conversion.
208      */
doubleValue()209     public double doubleValue() {
210         return (double)sum();
211     }
212 
213     /**
214      * Serialization proxy, used to avoid reference to the non-public
215      * Striped64 superclass in serialized forms.
216      * @serial include
217      */
218     private static class SerializationProxy implements Serializable {
219         private static final long serialVersionUID = 7249069246863182397L;
220 
221         /**
222          * The current value returned by sum().
223          * @serial
224          */
225         private final long value;
226 
SerializationProxy(LongAdder a)227         SerializationProxy(LongAdder a) {
228             value = a.sum();
229         }
230 
231         /**
232          * Returns a {@code LongAdder} object with initial state
233          * held by this proxy.
234          *
235          * @return a {@code LongAdder} object with initial state
236          * held by this proxy
237          */
readResolve()238         private Object readResolve() {
239             LongAdder a = new LongAdder();
240             a.base = value;
241             return a;
242         }
243     }
244 
245     /**
246      * Returns a
247      * <a href="../../../../serialized-form.html#java.util.concurrent.atomic.LongAdder.SerializationProxy">
248      * SerializationProxy</a>
249      * representing the state of this instance.
250      *
251      * @return a {@link SerializationProxy}
252      * representing the state of this instance
253      */
writeReplace()254     private Object writeReplace() {
255         return new SerializationProxy(this);
256     }
257 
258     /**
259      * @param s the stream
260      * @throws java.io.InvalidObjectException always
261      */
readObject(java.io.ObjectInputStream s)262     private void readObject(java.io.ObjectInputStream s)
263         throws java.io.InvalidObjectException {
264         throw new java.io.InvalidObjectException("Proxy required");
265     }
266 
267 }
268