ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ConcurrentMap.java
Revision: 1.65
Committed: Wed Sep 30 00:03:02 2015 UTC (8 years, 8 months ago) by jsr166
Branch: MAIN
Changes since 1.64: +2 -2 lines
Log Message: 
fix all the (optional) broken links using -Xdocrootparent hack

File Contents

# User Rev Content
1 dl 1.2 /*
2     * Written by Doug Lea with assistance from members of JCP JSR-166
3 dl 1.17 * Expert Group and released to the public domain, as explained at
4 jsr166 1.31 * http://creativecommons.org/publicdomain/zero/1.0/
5 dl 1.2 */
6    
7 tim 1.1 package java.util.concurrent;
8 jsr166 1.53
9 tim 1.1 import java.util.Map;
10 dl 1.46 import java.util.Objects;
11     import java.util.function.BiConsumer;
12 dl 1.44 import java.util.function.BiFunction;
13 dl 1.46 import java.util.function.Function;
14 tim 1.1
15     /**
16 jsr166 1.43 * A {@link java.util.Map} providing thread safety and atomicity
17 dl 1.42 * guarantees.
18 dl 1.19 *
19 dl 1.55 * <p>To maintain the specified guarantees, default implementations of
20     * methods including {@link #putIfAbsent} inherited from {@link Map}
21     * must be overridden by implementations of this interface. Similarly,
22     * implementations of the collections returned by methods {@link
23     * #keySet}, {@link #values}, and {@link #entrySet} must override
24     * methods such as {@code removeIf} when necessary to
25     * preserve atomicity guarantees.
26 dl 1.46 *
27 jsr166 1.29 * <p>Memory consistency effects: As with other concurrent
28     * collections, actions in a thread prior to placing an object into a
29     * {@code ConcurrentMap} as a key or value
30     * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
31     * actions subsequent to the access or removal of that object from
32     * the {@code ConcurrentMap} in another thread.
33     *
34 dl 1.19 * <p>This interface is a member of the
35 jsr166 1.30 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
36 jsr166 1.47 * Java Collections Framework</a>.
37 jsr166 1.21 *
38 dl 1.4 * @since 1.5
39     * @author Doug Lea
40 dl 1.13 * @param <K> the type of keys maintained by this map
41 jsr166 1.21 * @param <V> the type of mapped values
42 dl 1.4 */
43 jsr166 1.56 public interface ConcurrentMap<K,V> extends Map<K,V> {
44 dl 1.41
45     /**
46     * {@inheritDoc}
47     *
48 dl 1.55 * @implNote This implementation assumes that the ConcurrentMap cannot
49     * contain null values and {@code get()} returning null unambiguously means
50     * the key is absent. Implementations which support null values
51     * <strong>must</strong> override this default implementation.
52 dl 1.46 *
53     * @throws ClassCastException {@inheritDoc}
54     * @throws NullPointerException {@inheritDoc}
55     * @since 1.8
56 dl 1.41 */
57     @Override
58     default V getOrDefault(Object key, V defaultValue) {
59     V v;
60     return ((v = get(key)) != null) ? v : defaultValue;
61     }
62    
63 jsr166 1.64 /**
64 dl 1.46 * {@inheritDoc}
65     *
66     * @implSpec The default implementation is equivalent to, for this
67     * {@code map}:
68 jsr166 1.52 * <pre> {@code
69 jsr166 1.57 * for (Map.Entry<K,V> entry : map.entrySet()) {
70 jsr166 1.56 * action.accept(entry.getKey(), entry.getValue());
71 jsr166 1.57 * }}</pre>
72 dl 1.55 *
73     * @implNote The default implementation assumes that
74     * {@code IllegalStateException} thrown by {@code getKey()} or
75     * {@code getValue()} indicates that the entry has been removed and cannot
76     * be processed. Operation continues for subsequent entries.
77 dl 1.46 *
78     * @throws NullPointerException {@inheritDoc}
79     * @since 1.8
80     */
81     @Override
82     default void forEach(BiConsumer<? super K, ? super V> action) {
83     Objects.requireNonNull(action);
84 jsr166 1.56 for (Map.Entry<K,V> entry : entrySet()) {
85 dl 1.46 K k;
86     V v;
87     try {
88     k = entry.getKey();
89     v = entry.getValue();
90 jsr166 1.56 } catch (IllegalStateException ise) {
91 dl 1.46 // this usually means the entry is no longer in the map.
92     continue;
93     }
94     action.accept(k, v);
95     }
96     }
97    
98 tim 1.1 /**
99     * If the specified key is not already associated
100 jsr166 1.60 * with a value, associates it with the given value.
101     * This is equivalent to, for this {@code map}:
102 jsr166 1.59 * <pre> {@code
103 dl 1.55 * if (!map.containsKey(key))
104     * return map.put(key, value);
105     * else
106 jsr166 1.59 * return map.get(key);}</pre>
107 jsr166 1.36 *
108 jsr166 1.21 * except that the action is performed atomically.
109     *
110 dl 1.55 * @implNote This implementation intentionally re-abstracts the
111     * inappropriate default provided in {@code Map}.
112 dl 1.46 *
113 jsr166 1.24 * @param key key with which the specified value is to be associated
114     * @param value value to be associated with the specified key
115 jsr166 1.25 * @return the previous value associated with the specified key, or
116 jsr166 1.38 * {@code null} if there was no mapping for the key.
117     * (A {@code null} return can also indicate that the map
118     * previously associated {@code null} with the key,
119 jsr166 1.25 * if the implementation supports null values.)
120 jsr166 1.38 * @throws UnsupportedOperationException if the {@code put} operation
121 jsr166 1.24 * is not supported by this map
122 tim 1.1 * @throws ClassCastException if the class of the specified key or value
123 jsr166 1.24 * prevents it from being stored in this map
124     * @throws NullPointerException if the specified key or value is null,
125     * and this map does not permit null keys or values
126     * @throws IllegalArgumentException if some property of the specified key
127     * or value prevents it from being stored in this map
128 dl 1.18 */
129 jsr166 1.57 V putIfAbsent(K key, V value);
130 dl 1.6
131     /**
132 jsr166 1.21 * Removes the entry for a key only if currently mapped to a given value.
133 jsr166 1.60 * This is equivalent to, for this {@code map}:
134 jsr166 1.59 * <pre> {@code
135 jsr166 1.61 * if (map.containsKey(key)
136     * && Objects.equals(map.get(key), value)) {
137 jsr166 1.36 * map.remove(key);
138     * return true;
139 jsr166 1.59 * } else {
140 dl 1.55 * return false;
141 jsr166 1.59 * }}</pre>
142 jsr166 1.36 *
143 dl 1.6 * except that the action is performed atomically.
144 jsr166 1.21 *
145 dl 1.55 * @implNote This implementation intentionally re-abstracts the
146     * inappropriate default provided in {@code Map}.
147 dl 1.46 *
148 jsr166 1.24 * @param key key with which the specified value is associated
149 jsr166 1.25 * @param value value expected to be associated with the specified key
150 jsr166 1.38 * @return {@code true} if the value was removed
151     * @throws UnsupportedOperationException if the {@code remove} operation
152 jsr166 1.24 * is not supported by this map
153 jsr166 1.25 * @throws ClassCastException if the key or value is of an inappropriate
154 jsr166 1.35 * type for this map
155 jsr166 1.65 * (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
156 jsr166 1.24 * @throws NullPointerException if the specified key or value is null,
157 dl 1.32 * and this map does not permit null keys or values
158 jsr166 1.65 * (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
159 dl 1.6 */
160 dl 1.7 boolean remove(Object key, Object value);
161 dl 1.14
162     /**
163 jsr166 1.21 * Replaces the entry for a key only if currently mapped to a given value.
164 jsr166 1.60 * This is equivalent to, for this {@code map}:
165 jsr166 1.59 * <pre> {@code
166 jsr166 1.61 * if (map.containsKey(key)
167     * && Objects.equals(map.get(key), oldValue)) {
168 jsr166 1.36 * map.put(key, newValue);
169     * return true;
170 jsr166 1.59 * } else {
171 dl 1.55 * return false;
172 jsr166 1.59 * }}</pre>
173 jsr166 1.36 *
174 dl 1.14 * except that the action is performed atomically.
175 jsr166 1.21 *
176 dl 1.55 * @implNote This implementation intentionally re-abstracts the
177     * inappropriate default provided in {@code Map}.
178 dl 1.46 *
179 jsr166 1.24 * @param key key with which the specified value is associated
180     * @param oldValue value expected to be associated with the specified key
181     * @param newValue value to be associated with the specified key
182 jsr166 1.38 * @return {@code true} if the value was replaced
183     * @throws UnsupportedOperationException if the {@code put} operation
184 jsr166 1.24 * is not supported by this map
185 jsr166 1.25 * @throws ClassCastException if the class of a specified key or value
186     * prevents it from being stored in this map
187 jsr166 1.24 * @throws NullPointerException if a specified key or value is null,
188     * and this map does not permit null keys or values
189 jsr166 1.25 * @throws IllegalArgumentException if some property of a specified key
190     * or value prevents it from being stored in this map
191 dl 1.14 */
192     boolean replace(K key, V oldValue, V newValue);
193 dl 1.6
194 dl 1.15 /**
195 jsr166 1.21 * Replaces the entry for a key only if currently mapped to some value.
196 jsr166 1.60 * This is equivalent to, for this {@code map}:
197 jsr166 1.59 * <pre> {@code
198 jsr166 1.63 * if (map.containsKey(key))
199 jsr166 1.36 * return map.put(key, value);
200 jsr166 1.63 * else
201     * return null;}</pre>
202 jsr166 1.36 *
203 dl 1.15 * except that the action is performed atomically.
204 jsr166 1.21 *
205 dl 1.55 * @implNote This implementation intentionally re-abstracts the
206     * inappropriate default provided in {@code Map}.
207 dl 1.46 *
208 jsr166 1.24 * @param key key with which the specified value is associated
209     * @param value value to be associated with the specified key
210 jsr166 1.25 * @return the previous value associated with the specified key, or
211 jsr166 1.38 * {@code null} if there was no mapping for the key.
212     * (A {@code null} return can also indicate that the map
213     * previously associated {@code null} with the key,
214 jsr166 1.25 * if the implementation supports null values.)
215 jsr166 1.38 * @throws UnsupportedOperationException if the {@code put} operation
216 jsr166 1.24 * is not supported by this map
217 jsr166 1.25 * @throws ClassCastException if the class of the specified key or value
218     * prevents it from being stored in this map
219 jsr166 1.24 * @throws NullPointerException if the specified key or value is null,
220     * and this map does not permit null keys or values
221 jsr166 1.25 * @throws IllegalArgumentException if some property of the specified key
222     * or value prevents it from being stored in this map
223 dl 1.15 */
224 dl 1.16 V replace(K key, V value);
225 dl 1.44
226     /**
227     * {@inheritDoc}
228     *
229 dl 1.46 * @implSpec
230     * <p>The default implementation is equivalent to, for this {@code map}:
231 jsr166 1.52 * <pre> {@code
232 jsr166 1.57 * for (Map.Entry<K,V> entry : map.entrySet()) {
233 jsr166 1.62 * K k;
234     * V v;
235 jsr166 1.56 * do {
236 jsr166 1.62 * k = entry.getKey();
237     * v = entry.getValue();
238     * } while (!map.replace(k, v, function.apply(k, v)));
239 jsr166 1.57 * }}</pre>
240 dl 1.46 *
241     * The default implementation may retry these steps when multiple
242 dl 1.55 * threads attempt updates including potentially calling the function
243     * repeatedly for a given key.
244     *
245     * <p>This implementation assumes that the ConcurrentMap cannot contain null
246     * values and {@code get()} returning null unambiguously means the key is
247     * absent. Implementations which support null values <strong>must</strong>
248     * override this default implementation.
249 dl 1.46 *
250     * @throws UnsupportedOperationException {@inheritDoc}
251     * @throws NullPointerException {@inheritDoc}
252     * @throws ClassCastException {@inheritDoc}
253     * @throws IllegalArgumentException {@inheritDoc}
254     * @since 1.8
255 dl 1.44 */
256     @Override
257     default void replaceAll(BiFunction<? super K, ? super V, ? extends V> function) {
258 dl 1.46 Objects.requireNonNull(function);
259     forEach((k,v) -> {
260 jsr166 1.56 while (!replace(k, v, function.apply(k, v))) {
261 dl 1.46 // v changed or k is gone
262     if ( (v = get(k)) == null) {
263     // k is no longer in the map.
264     break;
265     }
266 dl 1.44 }
267 dl 1.46 });
268     }
269    
270     /**
271     * {@inheritDoc}
272     *
273     * @implSpec
274     * The default implementation is equivalent to the following steps for this
275     * {@code map}, then returning the current value or {@code null} if now
276     * absent:
277     *
278 jsr166 1.52 * <pre> {@code
279 dl 1.46 * if (map.get(key) == null) {
280 jsr166 1.59 * V newValue = mappingFunction.apply(key);
281     * if (newValue != null)
282     * return map.putIfAbsent(key, newValue);
283     * }}</pre>
284 dl 1.46 *
285     * The default implementation may retry these steps when multiple
286 dl 1.55 * threads attempt updates including potentially calling the mapping
287     * function multiple times.
288     *
289     * <p>This implementation assumes that the ConcurrentMap cannot contain null
290     * values and {@code get()} returning null unambiguously means the key is
291     * absent. Implementations which support null values <strong>must</strong>
292     * override this default implementation.
293 dl 1.46 *
294     * @throws UnsupportedOperationException {@inheritDoc}
295     * @throws ClassCastException {@inheritDoc}
296     * @throws NullPointerException {@inheritDoc}
297     * @since 1.8
298     */
299     @Override
300     default V computeIfAbsent(K key,
301     Function<? super K, ? extends V> mappingFunction) {
302     Objects.requireNonNull(mappingFunction);
303     V v, newValue;
304     return ((v = get(key)) == null &&
305     (newValue = mappingFunction.apply(key)) != null &&
306     (v = putIfAbsent(key, newValue)) == null) ? newValue : v;
307     }
308 dl 1.44
309 dl 1.46 /**
310     * {@inheritDoc}
311     *
312     * @implSpec
313     * The default implementation is equivalent to performing the following
314     * steps for this {@code map}, then returning the current value or
315 jsr166 1.59 * {@code null} if now absent:
316 dl 1.46 *
317 jsr166 1.52 * <pre> {@code
318 dl 1.46 * if (map.get(key) != null) {
319 jsr166 1.59 * V oldValue = map.get(key);
320     * V newValue = remappingFunction.apply(key, oldValue);
321     * if (newValue != null)
322     * map.replace(key, oldValue, newValue);
323     * else
324     * map.remove(key, oldValue);
325     * }}</pre>
326 dl 1.46 *
327 dl 1.55 * The default implementation may retry these steps when multiple threads
328     * attempt updates including potentially calling the remapping function
329 dl 1.46 * multiple times.
330     *
331 dl 1.55 * <p>This implementation assumes that the ConcurrentMap cannot contain null
332     * values and {@code get()} returning null unambiguously means the key is
333     * absent. Implementations which support null values <strong>must</strong>
334     * override this default implementation.
335     *
336 dl 1.46 * @throws UnsupportedOperationException {@inheritDoc}
337     * @throws ClassCastException {@inheritDoc}
338     * @throws NullPointerException {@inheritDoc}
339     * @since 1.8
340     */
341     @Override
342     default V computeIfPresent(K key,
343     BiFunction<? super K, ? super V, ? extends V> remappingFunction) {
344     Objects.requireNonNull(remappingFunction);
345     V oldValue;
346 jsr166 1.56 while ((oldValue = get(key)) != null) {
347 dl 1.46 V newValue = remappingFunction.apply(key, oldValue);
348     if (newValue != null) {
349     if (replace(key, oldValue, newValue))
350     return newValue;
351     } else if (remove(key, oldValue))
352 jsr166 1.57 return null;
353 dl 1.46 }
354     return oldValue;
355     }
356    
357     /**
358     * {@inheritDoc}
359     *
360     * @implSpec
361     * The default implementation is equivalent to performing the following
362     * steps for this {@code map}, then returning the current value or
363     * {@code null} if absent:
364     *
365 jsr166 1.52 * <pre> {@code
366 dl 1.46 * V oldValue = map.get(key);
367     * V newValue = remappingFunction.apply(key, oldValue);
368     * if (oldValue != null ) {
369 jsr166 1.59 * if (newValue != null)
370     * map.replace(key, oldValue, newValue);
371     * else
372     * map.remove(key, oldValue);
373 dl 1.46 * } else {
374 jsr166 1.59 * if (newValue != null)
375     * map.putIfAbsent(key, newValue);
376     * else
377     * return null;
378     * }}</pre>
379 dl 1.46 *
380     * The default implementation may retry these steps when multiple
381 dl 1.55 * threads attempt updates including potentially calling the remapping
382     * function multiple times.
383     *
384     * <p>This implementation assumes that the ConcurrentMap cannot contain null
385     * values and {@code get()} returning null unambiguously means the key is
386     * absent. Implementations which support null values <strong>must</strong>
387     * override this default implementation.
388 dl 1.46 *
389     * @throws UnsupportedOperationException {@inheritDoc}
390     * @throws ClassCastException {@inheritDoc}
391     * @throws NullPointerException {@inheritDoc}
392     * @since 1.8
393     */
394     @Override
395     default V compute(K key,
396     BiFunction<? super K, ? super V, ? extends V> remappingFunction) {
397     Objects.requireNonNull(remappingFunction);
398     V oldValue = get(key);
399 jsr166 1.56 for (;;) {
400 dl 1.46 V newValue = remappingFunction.apply(key, oldValue);
401     if (newValue == null) {
402     // delete mapping
403     if (oldValue != null || containsKey(key)) {
404     // something to remove
405     if (remove(key, oldValue)) {
406     // removed the old value as expected
407     return null;
408     }
409    
410     // some other value replaced old value. try again.
411     oldValue = get(key);
412     } else {
413     // nothing to do. Leave things as they were.
414     return null;
415     }
416     } else {
417     // add or replace old mapping
418     if (oldValue != null) {
419     // replace
420     if (replace(key, oldValue, newValue)) {
421     // replaced as expected.
422     return newValue;
423     }
424    
425     // some other value replaced old value. try again.
426     oldValue = get(key);
427     } else {
428     // add (replace if oldValue was null)
429     if ((oldValue = putIfAbsent(key, newValue)) == null) {
430     // replaced
431     return newValue;
432     }
433    
434     // some other value replaced old value. try again.
435     }
436 dl 1.44 }
437     }
438     }
439    
440 dl 1.46 /**
441     * {@inheritDoc}
442     *
443     * @implSpec
444     * The default implementation is equivalent to performing the following
445     * steps for this {@code map}, then returning the current value or
446     * {@code null} if absent:
447     *
448 jsr166 1.52 * <pre> {@code
449 dl 1.46 * V oldValue = map.get(key);
450     * V newValue = (oldValue == null) ? value :
451 jsr166 1.59 * remappingFunction.apply(oldValue, value);
452 dl 1.46 * if (newValue == null)
453 jsr166 1.59 * map.remove(key);
454 dl 1.46 * else
455 jsr166 1.59 * map.put(key, newValue);}</pre>
456 dl 1.46 *
457 dl 1.55 * <p>The default implementation may retry these steps when multiple
458     * threads attempt updates including potentially calling the remapping
459     * function multiple times.
460     *
461     * <p>This implementation assumes that the ConcurrentMap cannot contain null
462     * values and {@code get()} returning null unambiguously means the key is
463     * absent. Implementations which support null values <strong>must</strong>
464     * override this default implementation.
465 dl 1.46 *
466     * @throws UnsupportedOperationException {@inheritDoc}
467     * @throws ClassCastException {@inheritDoc}
468     * @throws NullPointerException {@inheritDoc}
469     * @since 1.8
470     */
471     @Override
472     default V merge(K key, V value,
473     BiFunction<? super V, ? super V, ? extends V> remappingFunction) {
474     Objects.requireNonNull(remappingFunction);
475     Objects.requireNonNull(value);
476     V oldValue = get(key);
477     for (;;) {
478     if (oldValue != null) {
479     V newValue = remappingFunction.apply(oldValue, value);
480     if (newValue != null) {
481     if (replace(key, oldValue, newValue))
482     return newValue;
483     } else if (remove(key, oldValue)) {
484     return null;
485     }
486     oldValue = get(key);
487     } else {
488     if ((oldValue = putIfAbsent(key, value)) == null) {
489     return value;
490     }
491     }
492     }
493     }
494 tim 1.1 }