CON07-J. Do not assume that a grouping of calls to independently atomic methods is atomic

A consistent locking policy guarantees that no two threads can simultaneously access or modify some shared data. In the absence of such a policy, it is possible for two threads to read some shared value, independently perform operations on it and induce a race condition while storing the final result. If two or more operations need to be performed as a single atomic operation, it is necessary to implement a consistent locking policy by either using synchronization or the java.util.concurrent utilities.

In presence of an invariant involving two objects, it is tempting to believe that if operations on the two objects are individually atomic, no additional locking is required; however this is not the case. Similarly, programmers sometimes incorrectly assume that using a thread-safe Collection does not require explicit synchronization to preserve an invariant involving the collection's elements. A thread-safe class can only guarantee atomicity of its individual methods. A grouping of calls to such methods requires additional synchronization.

For instance, consider a scenario where the standard thread-safe API does not provide a method to both find a particular person's record in a Hashtable and also update the corresponding payroll information. In such cases, a custom atomic method must be designed and used. This guideline discusses the rationale behind using such a method and provides the necessary implementation advice.

This guideline applies to all Collection classes including the thread-safe Hashtable class. Enumerations of objects of a Collection and iterators also require explicit synchronization on the Collection object (client-side locking) or any single internal private lock object.

Expressions involving compound operators are also non-atomic. Refer to CON01-J. Ensure that compound operations on shared variables are atomic for more information.

Noncompliant Code Example (AtomicReference)

This noncompliant code example uses two AtomicReference objects that hold one BigInteger object reference, each.

final class AtomicAdder {
  private final AtomicReference<BigInteger> first;	
  private final AtomicReference<BigInteger> second; 

  public AtomicAdder(BigInteger f, BigInteger s) {
    first  = new AtomicReference<BigInteger>(f);
    second = new AtomicReference<BigInteger>(s);
  }

  public void update(BigInteger f, BigInteger s) { // Unsafe
    first.set(f);
    second.set(s);
  }

  public BigInteger add() { // Unsafe
    return first.get().add(second.get()); 
  }
}

An AtomicReference is an object reference that can be updated atomically. Operations that use these two atomic references independently, are guaranteed to be atomic, however, if an operation involves using both together, thread-safety issues arise. In this noncompliant code example, one thread may call update() while a second thread may call add(). This might cause the add() operation to add the new value of first to the old value of second, yielding an erroneous result.

Compliant Solution (method synchronization)

This compliant solution declares the update() and add() methods as synchronized to guarantee atomicity.

final class AtomicAdder {
  // ...

  public synchronized void update(BigInteger f, BigInteger s){
    first.set(f);
    second.set(s);
  }

  public synchronized BigInteger add() {
    return first.get().add(second.get()); 
  }
}

Prefer using block synchronization when the method contains non-atomic operations that either do not require any synchronization or can use a more fine-grained locking scheme involving multiple internal private lock objects. Non-atomic operations can be decoupled from those that require synchronization and executed outside the synchronized block. The guideline CON04-J. Synchronize using an internal private final lock object has more details on using private internal lock objects and block synchronization.

Noncompliant Code Example (synchronizedList)

This noncompliant code example is comprised of a java.util.ArrayList<E> collection which is not thread-safe by default. However, most classes that are not thread-safe have a synchronized thread-safe version, for example, Collections.synchronizedList is a good substitute for ArrayList and Collections.synchronizedMap is a good alternative to HashMap. The atomicity pitfall described in the subsequent paragraph, remains to be addressed even when the particular Collection offers thread-safety guarantees.

final class IPHolder {
  private final List<InetAddress> ips = Collections.synchronizedList(new ArrayList<InetAddress>());
  
  public void addIPAddress(InetAddress address) {
    // Validate address
    ips.add(address);
  }
  
  public void addAndPrintIP() throws UnknownHostException {
    addIPAddress(InetAddress.getLocalHost());
    InetAddress[] ia = (InetAddress[]) ips.toArray(new InetAddress[0]);      
    System.out.println("Number of IPs: " + ia.length);     
  }
}

When the addAndPrintIP() method is invoked on the same object from multiple threads, the output, consisting of varying array lengths, may indicate a race condition between the threads. In other words, the statements in method addAndPrintIP() that are responsible for adding an IP address and printing out the length of the list, are not sequentially consistent.

Compliant Solution (Synchronized block)

To eliminate the race condition, ensure atomicity by using the underlying list's lock. This can be achieved by including all statements that use the array list within a synchronized block that locks on the list.

final class IPHolder {
  private final List<InetAddress> ips = Collections.synchronizedList(new ArrayList<InetAddress>());

  public void addIPAddress(InetAddress address) { 
    synchronized (ips) { 
      // Validate
      ips.add(address);
    }
  }

  public void addAndPrintIP() throws UnknownHostException {
    synchronized (ips) {
      addIPAddress(InetAddress.getLocalHost());
       InetAddress[] ia = (InetAddress[]) ips.toArray(new InetAddress[0]);           
      System.out.println("Number of IPs: " + ia.length); 
    }
  }
}

This technique is also called client-side locking [[Goetz 06]], because the class holds a lock on an object that presumably might be accessible to other classes. Client-side locking should not be used when the underlying class does not commit to its locking strategy. For more information see [CON31-J. Avoid client-side locking when using classes that do not commit to their locking strategy].

Although expensive in terms of performance, the CopyOnWriteArrayList and CopyOnWriteArraySet classes are sometimes used to create copies of the core Collection so that iterators do not fail with a runtime exception when some data in the Collection is modified. However, any updates to the Collection are not immediately visible to other threads. Consequently, the use of these classes is limited to boosting performance in code where the writes are fewer (or non-existent) as compared to the reads [[JavaThreads 04]]. In most other cases they must be avoided (see [MSC13-J. Do not modify the underlying collection when an iteration is in progress] for details on using these classes).

Noncompliant Code Example (synchronizedMap)

This noncompliant code example defines a class KeyedCounter which is not thread-safe. Even though the HashMap is wrapped in synchronized Map, the overall increment operation is not atomic. [[Lee 09]]

final class KeyedCounter {
  private final Map<String, Integer> map =
    Collections.synchronizedMap(new HashMap<String, Integer>());

  public void increment(String key) {
    Integer old = map.get(key);
    int value = (old == null) ? 1 : old.intValue() + 1;
    map.put(key, value);
  }

  public Integer getCount(String key) {
    return map.get(key);
  }
}

Compliant Solution (synchronized blocks)

To ensure atomicity, this compliant solution uses a private internal lock object to synchronize the method bodies of the increment() and getCount() methods.

public final class KeyedCounter {
  private final Map<String,Integer> map = new HashMap<String, Integer>(); 
  private final Object lock = new Object();

  public void increment(String key) {
    synchronized (lock) {
      Integer old = map.get(key);
      int value = (old == null) ? 1 : old.intValue() + 1;
      map.put(key, value);
    }
  }

  public Integer getCount(String key) {
    synchronized (lock) {
      return map.get(key);
    }
  }
}

This compliant solution does not use Collections.synchronizedMap() because locking on the (unsynchronized) map provides sufficient thread-safety for this application. The guideline CON02-J. Always synchronize on the appropriate object enlists certain objects that should not be used for synchronization purposes, including any object returned by Collections.synchronizedMap().

Compliant Solution (ConcurrentHashMap)

The previous compliant solution does not scale very well because a class with several synchronized methods can be a potential bottleneck as far as acquiring locks is concerned, and may further yield a deadlock or livelock. The class ConcurrentHashMap provides several utility methods to perform atomic operations and is often a good choice, as demonstrated in this compliant solution [[Lee 09]].

public final class KeyedCounter {
  private final ConcurrentMap<String, AtomicInteger> map =
    new ConcurrentHashMap<String, AtomicInteger>();

  public void increment(String key) {
    AtomicInteger value = new AtomicInteger(0);
    AtomicInteger old = map.putIfAbsent(key, value);
   
    if (old != null) { 
      value = old; 
    }

    value.incrementAndGet(); // Increment the value atomically
  }

  public Integer getCount(String key) {
    AtomicInteger value = map.get(key);
    return (value == null) ? null : value.get();
  }
}

According to Goetz et al. [[Goetz 06]] section 5.2.1. ConcurrentHashMap:

ConcurrentHashMap, along with the other concurrent collections, further improve on the synchronized collection classes by providing iterators that do not throw ConcurrentModificationException, as a result eliminating the need to lock the collection during iteration. The iterators returned by ConcurrentHashMap are weakly consistent instead of fail-fast. A weakly consistent iterator can tolerate concurrent modification, traverses elements as they existed when the iterator was constructed, and may (but is not guaranteed to) reflect modifications to the collection after the construction of the iterator.

Note that methods such as size() and isEmpty() are allowed to return an approximate result for performance reasons. Code should not rely on these return values for deriving exact results.

Risk Assessment

Non-atomic code can induce race conditions and affect program correctness.

Automated Detection

TODO

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

References

[[API 06]]
[[JavaThreads 04]] 8.2 "Synchronization and Collection Classes"
[[Goetz 06]] 4.4.1. Client-side Locking, 5.2.1. ConcurrentHashMap
[[Lee 09]] "Map & Compound Operation"

VOID CON06-J. Do not defer a thread that is holding a lock      11. Concurrency (CON)