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

A consistent locking policy guarantees that multiple threads cannot simultaneously access or modify shared data. 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 intrinsic synchronization or the java.util.concurrent utilities. In the absence of such a policy, the code is susceptible to race conditions.

Given an invariant involving multiple objects, a programmer may incorrectly assume that individually atomic operations require no additional locking; however, this is not the case. Similarly, programmers may incorrectly assume that using a thread-safe Collection does not require explicit synchronization to preserve an invariant that involves 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.

Consider, for example, a scenario where the standard thread-safe API does not provide a single method to both find a particular person's record in a Hashtable and update the corresponding payroll information. In such cases, the two method invocations must be performed atomically.

Enumerations and iterators also require explicit synchronization on the collection object (client-side locking) or a private final lock object.

Compound operations on shared variables are also non-atomic. See [CON01-J. Ensure that compound operations on shared variables are atomic] for more information.

[CON30-J. Do not use method chaining implementations in a multi-threaded environment] describes a specialized case of this guideline.

Noncompliant Code Example (AtomicReference)

This noncompliant code example wraps BigInteger objects within thread-safe AtomicReference objects.

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

  public Adder(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. However, operations combining

more than one atomic reference are not atomic. In this noncompliant code example, one thread may call update() while a second thread may call add(). This might cause the add() method 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 Adder {
  // ...

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

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

Noncompliant Code Example (synchronizedList)

This noncompliant code example uses a java.util.ArrayList<E> collection, which is not thread-safe. However, the Collections.synchronizedList is used as a synchronization wrapper for ArrayList.

final class IPHolder {
  private final List<InetAddress> ips = Collections.synchronizedList(new ArrayList<InetAddress>());
  
  public void addIPAddress(InetAddress address) {
    ips.add(address);
  }
  
  public void addAndPrintIPAddresses(InetAddress address) {
    addIPAddress(address);
    InetAddress[] ia = (InetAddress[]) ips.toArray(new InetAddress[0]);      
    // Iterate through array ia ...
  }
}

Even though the Collection wrapper offers thread-safety guarantees for individual method invocations, a sequence of method calls is not atomic. In this example, when multiple threads invoke the addAndPrintIPAddresses() method to iterate over the array, each thread can potentially observe the array to contain a different number of IP addresses. This indicates that the addAndPrintIPAddresses() method has race conditions.

Compliant Solution (Synchronized block)

To eliminate the race conditions, ensure atomicity by using the underlying list's lock. This compliant solution includes 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) { 
      ips.add(address);
    }
  }

  public void addAndPrintIPAddresses(InetAddress address) {
    synchronized (ips) {
      addIPAddress(address);
      InetAddress[] ia = (InetAddress[]) ips.toArray(new InetAddress[0]);           
      // Iterate through array ia ...
    }
  }
}

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

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).

This code does not violate [CON40-J. Do not synchronize on a collection view if the backing collection is accessible], because while it does synchronize on a collection view (the synchronizedList), the backing collection is not accessible, and hence cannot be modified by any code.

Noncompliant Code Example (synchronizedMap)

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

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);
    }
  }

  // Other accessors ...
}

Because the check for integer overflow following the addition is absent, the caller must ensure that the increment() method is called no more than Integer.MAX_VALUE times for any key. Refer to [INT00-J. Perform explicit range checking to ensure integer operations do not overflow] for more information.

Compliant Solution (atomic method)

To ensure atomicity, this compliant solution uses a method that guarantees atomicity (AtomicInteger.incrementAndGet()). This provides a happens-before relationship between reading and writing any integer values in the map.

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.get();
  }

  // Other accessors ...
}

This compliant solution does not use Collections.synchronizedMap() because locking on the (unsynchronized) map provides sufficient thread-safety for this application. The guideline [CON40-J. Do not synchronize on a collection view if the backing collection is accessible] provides more information about synchronizing on synchronizedMap objects.

To prevent overflow, the caller must ensure that the increment() method is called no more than Integer.MAX_VALUE times for any key. Refer to [INT00-J. Perform explicit range checking to ensure integer operations do not overflow] for more information.

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 for performing atomic operations and is often a good choice, as demonstrated in this compliant solution [[Lee 09]].

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

  public void increment(String key) {
    AtomicInteger value = new AtomicInteger();
    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.get();
  }

  // Other accessors ...
}

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]] Section 8.2, "Synchronization and Collection Classes"
[[Goetz 06]] Section 4.4.1, "Client-side Locking", Section 5.2.1, "ConcurrentHashMap"
[[Lee 09]] "Map & Compound Operation"

[!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_left.png!]      [!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_up.png!]      null