1 |
/* |
2 |
* Written by Doug Lea with assistance from members of JCP JSR-166 |
3 |
* Expert Group and released to the public domain, as explained at |
4 |
* http://creativecommons.org/publicdomain/zero/1.0/ |
5 |
*/ |
6 |
|
7 |
package java.util.concurrent.atomic; |
8 |
|
9 |
import static java.lang.Double.doubleToRawLongBits; |
10 |
import static java.lang.Double.longBitsToDouble; |
11 |
|
12 |
import java.io.Serializable; |
13 |
import java.util.function.DoubleBinaryOperator; |
14 |
|
15 |
/** |
16 |
* One or more variables that together maintain a running {@code double} |
17 |
* value updated using a supplied function. When updates (method |
18 |
* {@link #accumulate}) are contended across threads, the set of variables |
19 |
* may grow dynamically to reduce contention. Method {@link #get} |
20 |
* (or, equivalently, {@link #doubleValue}) returns the current value |
21 |
* across the variables maintaining updates. |
22 |
* |
23 |
* <p>This class is usually preferable to alternatives when multiple |
24 |
* threads update a common value that is used for purposes such as |
25 |
* summary statistics that are frequently updated but less frequently |
26 |
* read. |
27 |
* |
28 |
* <p>The supplied accumulator function should be side-effect-free, |
29 |
* since it may be re-applied when attempted updates fail due to |
30 |
* contention among threads. The function is applied with the current |
31 |
* value as its first argument, and the given update as the second |
32 |
* argument. For example, to maintain a running maximum value, you |
33 |
* could supply {@code Double::max} along with {@code |
34 |
* Double.NEGATIVE_INFINITY} as the identity. The order of |
35 |
* accumulation within or across threads is not guaranteed. Thus, this |
36 |
* class may not be applicable if numerical stability is required, |
37 |
* especially when combining values of substantially different orders |
38 |
* of magnitude. |
39 |
* |
40 |
* <p>Class {@link DoubleAdder} provides analogs of the functionality |
41 |
* of this class for the common special case of maintaining sums. The |
42 |
* call {@code new DoubleAdder()} is equivalent to {@code new |
43 |
* DoubleAccumulator((x, y) -> x + y, 0.0)}. |
44 |
* |
45 |
* <p>This class extends {@link Number}, but does <em>not</em> define |
46 |
* methods such as {@code equals}, {@code hashCode} and {@code |
47 |
* compareTo} because instances are expected to be mutated, and so are |
48 |
* not useful as collection keys. |
49 |
* |
50 |
* @since 1.8 |
51 |
* @author Doug Lea |
52 |
*/ |
53 |
public class DoubleAccumulator extends Striped64 implements Serializable { |
54 |
private static final long serialVersionUID = 7249069246863182397L; |
55 |
|
56 |
private final DoubleBinaryOperator function; |
57 |
private final long identity; // use long representation |
58 |
|
59 |
/** |
60 |
* Creates a new instance using the given accumulator function |
61 |
* and identity element. |
62 |
* @param accumulatorFunction a side-effect-free function of two arguments |
63 |
* @param identity identity (initial value) for the accumulator function |
64 |
*/ |
65 |
public DoubleAccumulator(DoubleBinaryOperator accumulatorFunction, |
66 |
double identity) { |
67 |
this.function = accumulatorFunction; |
68 |
base = this.identity = doubleToRawLongBits(identity); |
69 |
} |
70 |
|
71 |
/** |
72 |
* Updates with the given value. |
73 |
* |
74 |
* @param x the value |
75 |
*/ |
76 |
public void accumulate(double x) { |
77 |
Cell[] as; long b, v, r; int m; Cell a; |
78 |
if ((as = cells) != null |
79 |
|| ((r = doubleToRawLongBits |
80 |
(function.applyAsDouble(longBitsToDouble(b = base), x))) != b |
81 |
&& !casBase(b, r))) { |
82 |
boolean uncontended = true; |
83 |
if (as == null |
84 |
|| (m = as.length - 1) < 0 |
85 |
|| (a = as[getProbe() & m]) == null |
86 |
|| !(uncontended = |
87 |
((r = doubleToRawLongBits |
88 |
(function.applyAsDouble |
89 |
(longBitsToDouble(v = a.value), x))) == v) |
90 |
|| a.cas(v, r))) |
91 |
doubleAccumulate(x, function, uncontended); |
92 |
} |
93 |
} |
94 |
|
95 |
/** |
96 |
* Returns the current value. The returned value is <em>NOT</em> |
97 |
* an atomic snapshot; invocation in the absence of concurrent |
98 |
* updates returns an accurate result, but concurrent updates that |
99 |
* occur while the value is being calculated might not be |
100 |
* incorporated. |
101 |
* |
102 |
* @return the current value |
103 |
*/ |
104 |
public double get() { |
105 |
Cell[] as = cells; |
106 |
double result = longBitsToDouble(base); |
107 |
if (as != null) { |
108 |
for (Cell a : as) |
109 |
if (a != null) |
110 |
result = function.applyAsDouble |
111 |
(result, longBitsToDouble(a.value)); |
112 |
} |
113 |
return result; |
114 |
} |
115 |
|
116 |
/** |
117 |
* Resets variables maintaining updates to the identity value. |
118 |
* This method may be a useful alternative to creating a new |
119 |
* updater, but is only effective if there are no concurrent |
120 |
* updates. Because this method is intrinsically racy, it should |
121 |
* only be used when it is known that no threads are concurrently |
122 |
* updating. |
123 |
*/ |
124 |
public void reset() { |
125 |
Cell[] as = cells; |
126 |
base = identity; |
127 |
if (as != null) { |
128 |
for (Cell a : as) |
129 |
if (a != null) |
130 |
a.reset(identity); |
131 |
} |
132 |
} |
133 |
|
134 |
/** |
135 |
* Equivalent in effect to {@link #get} followed by {@link |
136 |
* #reset}. This method may apply for example during quiescent |
137 |
* points between multithreaded computations. If there are |
138 |
* updates concurrent with this method, the returned value is |
139 |
* <em>not</em> guaranteed to be the final value occurring before |
140 |
* the reset. |
141 |
* |
142 |
* @return the value before reset |
143 |
*/ |
144 |
public double getThenReset() { |
145 |
Cell[] as = cells; |
146 |
double result = longBitsToDouble(base); |
147 |
base = identity; |
148 |
if (as != null) { |
149 |
for (Cell a : as) { |
150 |
if (a != null) { |
151 |
double v = longBitsToDouble(a.value); |
152 |
a.reset(identity); |
153 |
result = function.applyAsDouble(result, v); |
154 |
} |
155 |
} |
156 |
} |
157 |
return result; |
158 |
} |
159 |
|
160 |
/** |
161 |
* Returns the String representation of the current value. |
162 |
* @return the String representation of the current value |
163 |
*/ |
164 |
public String toString() { |
165 |
return Double.toString(get()); |
166 |
} |
167 |
|
168 |
/** |
169 |
* Equivalent to {@link #get}. |
170 |
* |
171 |
* @return the current value |
172 |
*/ |
173 |
public double doubleValue() { |
174 |
return get(); |
175 |
} |
176 |
|
177 |
/** |
178 |
* Returns the {@linkplain #get current value} as a {@code long} |
179 |
* after a narrowing primitive conversion. |
180 |
*/ |
181 |
public long longValue() { |
182 |
return (long)get(); |
183 |
} |
184 |
|
185 |
/** |
186 |
* Returns the {@linkplain #get current value} as an {@code int} |
187 |
* after a narrowing primitive conversion. |
188 |
*/ |
189 |
public int intValue() { |
190 |
return (int)get(); |
191 |
} |
192 |
|
193 |
/** |
194 |
* Returns the {@linkplain #get current value} as a {@code float} |
195 |
* after a narrowing primitive conversion. |
196 |
*/ |
197 |
public float floatValue() { |
198 |
return (float)get(); |
199 |
} |
200 |
|
201 |
/** |
202 |
* Serialization proxy, used to avoid reference to the non-public |
203 |
* Striped64 superclass in serialized forms. |
204 |
* @serial include |
205 |
*/ |
206 |
private static class SerializationProxy implements Serializable { |
207 |
private static final long serialVersionUID = 7249069246863182397L; |
208 |
|
209 |
/** |
210 |
* The current value returned by get(). |
211 |
* @serial |
212 |
*/ |
213 |
private final double value; |
214 |
|
215 |
/** |
216 |
* The function used for updates. |
217 |
* @serial |
218 |
*/ |
219 |
private final DoubleBinaryOperator function; |
220 |
|
221 |
/** |
222 |
* The identity value, represented as a long, as converted by |
223 |
* {@link Double#doubleToRawLongBits}. The original identity |
224 |
* can be recovered using {@link Double#longBitsToDouble}. |
225 |
* @serial |
226 |
*/ |
227 |
private final long identity; |
228 |
|
229 |
SerializationProxy(double value, |
230 |
DoubleBinaryOperator function, |
231 |
long identity) { |
232 |
this.value = value; |
233 |
this.function = function; |
234 |
this.identity = identity; |
235 |
} |
236 |
|
237 |
/** |
238 |
* Returns a {@code DoubleAccumulator} object with initial state |
239 |
* held by this proxy. |
240 |
* |
241 |
* @return a {@code DoubleAccumulator} object with initial state |
242 |
* held by this proxy |
243 |
*/ |
244 |
private Object readResolve() { |
245 |
double d = longBitsToDouble(identity); |
246 |
DoubleAccumulator a = new DoubleAccumulator(function, d); |
247 |
a.base = doubleToRawLongBits(value); |
248 |
return a; |
249 |
} |
250 |
} |
251 |
|
252 |
/** |
253 |
* Returns a |
254 |
* <a href="../../../../serialized-form.html#java.util.concurrent.atomic.DoubleAccumulator.SerializationProxy"> |
255 |
* SerializationProxy</a> |
256 |
* representing the state of this instance. |
257 |
* |
258 |
* @return a {@link SerializationProxy} |
259 |
* representing the state of this instance |
260 |
*/ |
261 |
private Object writeReplace() { |
262 |
return new SerializationProxy(get(), function, identity); |
263 |
} |
264 |
|
265 |
/** |
266 |
* @param s the stream |
267 |
* @throws java.io.InvalidObjectException always |
268 |
*/ |
269 |
private void readObject(java.io.ObjectInputStream s) |
270 |
throws java.io.InvalidObjectException { |
271 |
throw new java.io.InvalidObjectException("Proxy required"); |
272 |
} |
273 |
|
274 |
} |