1 |
jsr166 |
1.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 |
jsr166 |
1.2 |
import static java.lang.Double.doubleToRawLongBits; |
10 |
|
|
import static java.lang.Double.longBitsToDouble; |
11 |
|
|
|
12 |
jsr166 |
1.1 |
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 |
jsr166 |
1.2 |
base = this.identity = doubleToRawLongBits(identity); |
69 |
jsr166 |
1.1 |
} |
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 |
jsr166 |
1.2 |
if ((as = cells) != null |
79 |
|
|
|| ((r = doubleToRawLongBits |
80 |
|
|
(function.applyAsDouble(longBitsToDouble(b = base), x))) != b |
81 |
|
|
&& !casBase(b, r))) { |
82 |
jsr166 |
1.1 |
boolean uncontended = true; |
83 |
jsr166 |
1.2 |
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 |
jsr166 |
1.1 |
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 |
jsr166 |
1.2 |
double result = longBitsToDouble(base); |
107 |
jsr166 |
1.1 |
if (as != null) { |
108 |
|
|
for (Cell a : as) |
109 |
|
|
if (a != null) |
110 |
|
|
result = function.applyAsDouble |
111 |
jsr166 |
1.2 |
(result, longBitsToDouble(a.value)); |
112 |
jsr166 |
1.1 |
} |
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 |
jsr166 |
1.2 |
double result = longBitsToDouble(base); |
147 |
jsr166 |
1.1 |
base = identity; |
148 |
|
|
if (as != null) { |
149 |
|
|
for (Cell a : as) { |
150 |
|
|
if (a != null) { |
151 |
jsr166 |
1.2 |
double v = longBitsToDouble(a.value); |
152 |
jsr166 |
1.1 |
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 |
jsr166 |
1.2 |
double d = longBitsToDouble(identity); |
246 |
jsr166 |
1.1 |
DoubleAccumulator a = new DoubleAccumulator(function, d); |
247 |
jsr166 |
1.2 |
a.base = doubleToRawLongBits(value); |
248 |
jsr166 |
1.1 |
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 |
|
|
} |