ConcurrentHashMap/ConcurrentMap/Map.compute

[Brian Goetz]

These look great to me!  This default method thing was a pretty good 
idea!  :)

Nit: uses Scala fat arrow instead of Java thin arrow in examples.

Bikeshed: The name "replaceIfPresent" seems nicer than 
"computeIfPresent" and fits in with existing replace naming.

For the value-oriented CHM methods (putIfAbsent, remove, replace), I 
think it is reasonable to move these up to Map with the obvious 
defaults, with no promises about atomicity, and adjust the ConcurrentMap 
spec to add a comment about "unlike the Map versions, these are atomic." 
  The null rules get more ad-hoc for these, but can still be reasonably 
consistent with the lambda versions; NPE on any key being null.  For 
replace(K,V,null), we can treat that as remove-if-present and 
replace(K,null) can be unconditional remove.  putIfAbsent(k, null) 
should be a no-op.  remove(key, null) becomes "remove if get() returns 
null", I guess.

ObAndIWantAPony: I would also love to have Map.merge(otherMap, 
mergeLambda) whose default uses your merge below, but for which you 
could define a better override in Map implementations that offer a 
better than element-wise merge.

On 12/5/2012 4:10 PM, Doug Lea wrote:
> On 12/05/12 07:39, Doug Lea wrote:
>
>> ... method Map.compute(). Three other similar methods
>> computeIfAbsent(), computeIfPresent(), and merge()
>> amount to special cases that are generally simpler to
>> use and more efficient when they apply.
>>
>> After a few stabs at it, I think that the only sane way
>> to spec and default-implement it is to say that, even
>> if your Map implementation otherwise allows null keys/values,
>> that this method will act as if it doesn't.
>
> Since people seem not to mind this (and Brian's and Tim's
> responses on other thread seem to even encourage it), the
> set of all four are below. Please skim through and
> see if you still agree.
>
> Brian: We had discussed also defining and default-implementing
> in Map the other ConcurrentMap methods:
>
> V putIfAbsent(K key, V value);
> boolean remove(Object key, Object value);
> boolean replace(K key, V oldValue, V newValue);
> V replace(K key, V value);
>
> Any thoughts?
>
> ....
>
>
> Additions to interface Map (with actual default implementations
> elided for now):
>
>
>      /**
>       * Attempts to compute a mapping given a key and its current
>       * mapped value (or {@code null} if there is no current
>       * mapping). The default implementation is equivalent to
>       *
>       *  <pre> {@code
>       *   V value = remappingFunction.apply(key, map.get(key));
>       *   if (value != null)
>       *     map.put(key, value);
>       *   else
>       *     map.remove(key);
>       * }</pre>
>       *
>       * If the function returns {@code null}, the mapping is removed
>       * (or remains absent if initially absent).  If the function
>       * itself throws an (unchecked) exception, the exception is
>       * rethrown to its caller, and the current mapping is left
>       * unchanged.  For example, to either create or append new
>       * messages to a value mapping:
>       *
>       * <pre> {@code
>       * Map<Key, String> map = ...;
>       * final String msg = ...;
>       * map.compute(key, (k, v, msg) => (v == null) ? msg : v + msg)</pre>
>       *
>       * <p>The default implementation makes no guarantees about
>       * synchronization or atomicity properties of this method. Any
>       * class overriding this method must specify its concurrency
>       * properties.
>       *
>       * @param key key with which the specified value is to be associated
>       * @param remappingFunction the function to compute a value
>       * @return the new value associated with the specified key, or null
> if none
>       * @throws NullPointerException if the specified key is null and
>       *         this map does not support null keys, or the
>       *         remappingFunction is null
>       * @throws RuntimeException or Error if the remappingFunction does so,
>       *         in which case the mapping is unchanged
>       */
>      V compute(K key,
>                BiFunction<? super K, ? super V, ? extends V>
> remappingFunction);
>
>      /**
>       * If the specified key is not already associated with a value,
>       * attempts to compute its value using the given mappingFunction
>       * and enters it into the map unless null.  This is equivalent to:
>       *
>       * <pre> {@code
>       * if (map.containsKey(key))
>       *   return map.get(key);
>       * value = mappingFunction.apply(key);
>       * if (value != null)
>       *   map.put(key, value);
>       * return value;}</pre>
>       *
>       * If the function returns {@code null} no mapping is recorded. If
>       * the function itself throws an (unchecked) exception, the
>       * exception is rethrown to its caller, and no mapping is
>       * recorded.  The most common usage is to construct a new object
>       * serving as an initial mapped value, or memoized result, as in:
>       *
>       *  <pre> {@code
>       * map.computeIfAbsent(key, k -> new Value(f(k)));} </pre>
>       *
>       * <p>The default implementation makes no guarantees about
>       * synchronization or atomicity properties of this method. Any
>       * class overriding this method must specify its concurrency
>       * properties.
>       *
>       * @param key key with which the specified value is to be associated
>       * @param mappingFunction the function to compute a value
>       * @return the current (existing or computed) value associated with
>       *         the specified key, or null if the computed value is null
>       * @throws NullPointerException if the specified key is null and
>       *         this map does not support null keys, or the
>       *         mappingFunction is null
>       * @throws RuntimeException or Error if the mappingFunction does so,
>       *         in which case the mapping is left unestablished
>       */
>      V computeIfAbsent(K key, Function<? super K, ? extends V>
> mappingFunction);
>
>      /**
>       * If the given key is present, attempts to compute a new mapping
>       * given the key and its current mapped value. This is equivalent
>       * to:
>       *
>       *  <pre> {@code
>       *   if (map.containsKey(key)) {
>       *     value = remappingFunction.apply(key, map.get(key));
>       *     if (value != null)
>       *       map.put(key, value);
>       *     else
>       *       map.remove(key);
>       *   }
>       * }</pre>
>       *
>       * If the function returns {@code null}, the mapping is removed
>       * (or remains absent if initially absent).  If the function
>       * itself throws an (unchecked) exception, the exception is
>       * rethrown to its caller, and the current mapping is left
>       * unchanged.
>       *
>       * <p>The default implementation makes no guarantees about
>       * synchronization or atomicity properties of this method. Any
>       * class overriding this method must specify its concurrency
>       * properties.
>       *
>       * @param key key with which the specified value is to be associated
>       * @param remappingFunction the function to compute a value
>       * @return the new value associated with the specified key, or null
> if none
>       * @throws NullPointerException if the specified key is null and
>       *         this map does not support null keys, or the
>       *         remappingFunction is null
>       * @throws RuntimeException or Error if the remappingFunction does so,
>       *         in which case the mapping is unchanged
>       */
>      computeIfPresent(K key,
>                       BiFunction<? super K, ? super V, ? extends V>
> remappingFunction);
>
>      /**
>       * If the specified key is not already associated with a value,
>       * associates it with the given value.  Otherwise, replaces the
>       * value with the results of the given remapping function, or
>       * removes if {@code null}. This is equivalent to:
>       *
>       *  <pre> {@code
>       *   V newValue;
>       *   if (!map.containsKey(key))
>       *     newValue = value;
>       *   else
>       *     newValue = remappingFunction.apply(map.get(key), value);
>       *   if (newValue != null)
>       *     map.put(key, newValue);
>       *   else
>       *     map.remove(key);
>       * }</pre>
>       *
>       * If the function returns {@code null}, the mapping is removed
>       * (or remains absent if initially absent).  If the function
>       * itself throws an (unchecked) exception, the exception is
>       * rethrown to its caller, and the current mapping is left
>       * unchanged.
>       *
>       * <p>The default implementation makes no guarantees about
>       * synchronization or atomicity properties of this method. Any
>       * class overriding this method must specify its concurrency
>       * properties.
>       *
>       * @param key key with which the specified value is to be associated
>       * @param value the value to use if absent
>       * @param remappingFunction the function to recompute a value if
> present
>       * @return the new value associated with the specified key, or null
> if none
>       * @throws NullPointerException if the specified key is null and
>       *         this map does not support null keys, or the
>       *         remappingFunction is null
>       * @throws RuntimeException or Error if the remappingFunction does so,
>       *         in which case the mapping is unchanged
>       */
>      V merge(K key, V value,
>              BiFunction<? super V, ? super V, ? extends V>
> remappingFunction);
>
>
>