Summary

Explicitly state that the computeIfAbsent, computeIfPresent, compute, and merge methods in IdentityHashMap will throw ConcurrentModificationException when the (re)mapping function modifies the map.

Problem

Previously, with the default implementation provided by the Map interface, the 4 methods in IdentityHashMap will never throw ConcurrentModificationException, but the efficient override implementations requires the (re)mapping function to not modify this map when (re)mapping function's modification to the map is detected.

Solution

Adds documentation to specify the new behavior of the 4 methods in IdentityHashMap. Such behavior is compatible with that specified in the Map superinterface.

Specification

We propose to add these documentation for the 4 concurrency-hostile methods as follows: (implementations ignored)

/**
 * {@inheritDoc}
 *
 * <p>This method will, on a best-effort basis, throw a
 * {@link ConcurrentModificationException} if it is detected that the
 * mapping function modifies this map during computation.
 *
 * @throws ConcurrentModificationException if it is detected that the
 * mapping function modified this map
 */
@Override
public V computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction) {
}

/**
 * {@inheritDoc}
 *
 * <p>This method will, on a best-effort basis, throw a
 * {@link ConcurrentModificationException} if it is detected that the
 * remapping function modifies this map during computation.
 *
 * @throws ConcurrentModificationException if it is detected that the
 * remapping function modified this map
 */
@Override
public V computeIfPresent(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction) {
}

/**
 * {@inheritDoc}
 *
 * <p>This method will, on a best-effort basis, throw a
 * {@link ConcurrentModificationException} if it is detected that the
 * remapping function modifies this map during computation.
 *
 * @throws ConcurrentModificationException if it is detected that the
 * remapping function modified this map
 */
@Override
public V compute(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction) {
}

/**
 * {@inheritDoc}
 *
 * <p>This method will, on a best-effort basis, throw a
 * {@link ConcurrentModificationException} if it is detected that the
 * remapping function modifies this map during computation.
 *
 * @throws ConcurrentModificationException if it is detected that the
 * remapping function modified this map
 */
@Override
public V merge(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction) {
}