Page History

Thread-safety A consistent locking policy guarantees that no two multiple threads can cannot simultaneously access or modify some shared data. However, if When two or more operations need to must be performed safely, it becomes necessary to enforce atomicity. 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. For example, programmers sometimes assume that a thread-safe Collection does not require explicit synchronization which is a misleading thought. It follows that using a thread-safe Collection by itself may not ensure program correctness.

Noncompliant Code Example

This noncompliant code example is comprised of an ArrayList collection which is non-thread-safe by default. There is, however, a way around this drawback. Most thread-unsafe classes 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 coming lines, remains to be addressed even when the particular Collection offers thread-safety benefits.

as a single atomic operation, a consistent locking policy must be implemented using either intrinsic synchronization or java.util.concurrent utilities. In the absence of such a policy, the code is susceptible to race conditions.

When presented with a set of operations, where each is guaranteed to be atomic, it is tempting to assume that a single operation consisting of individually atomic operations is guaranteed to be collectively atomic without additional locking. Similarly, programmers might incorrectly assume that use of a thread-safe Collection is sufficient to preserve an invariant that involves the collection's elements without additional synchronization. A thread-safe class can only guarantee atomicity of its individual methods. A grouping of calls to such methods requires additional synchronization for the group.

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

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

Compound operations on shared variables are also non-atomic (see VNA02-J. Ensure that compound operations on shared variables are atomic for more information).

VNA04-J. Ensure that calls to chained methods are atomic describes a specialized case of this rule.

Noncompliant Code Example (AtomicReference)

This noncompliant code example wraps references to 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

class RaceCollection implements Runnable {
  private List<InetAddress> ips = Collections.synchronizedList(new ArrayList<InetAddress>());
  
  public void addIPAddress(InetAddress ia) {
    // Validate
    ips.add(ia);
  }
  
  public void run() {
    try {
      addIPAddress(InetAddress.getLocalHost());
    second = InetAddress[] ia = (InetAddress[]) ips.toArray(new InetAddress[0]);      
  new AtomicReference<BigInteger>(s);
  }

  public void update(BigInteger f, BigInteger s) { // Unsafe
    Systemfirst.out.println("Number of IPs: " + ia.length);     
    } catch (UnknownHostException eset(f);
    second.set(s);
  }

  public BigInteger add() { /* Forward to handler */ }Unsafe
     		return first.get().add(second.get());
  }
  
  public static void main(String[] args) {
    RaceCollection rc = new RaceCollection();
    for(int i = 0; i < 2; i++) {
      new Thread(rc).start();
    }	  	  
  }
}

The operations within a thread's run() method are non-atomic. That is, it is possible for the first thread to operate on data that it does not expect. This noncompliant code's output, consisting of varying array lengths, indicates a race condition between threads. In other words, the statements are not sequentially consistent.

Compliant Solution

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. This technique is also called client-side locking \[[Goetz 06|AA. Java References#Goetz 06]\]. 

}

AtomicReference is an object reference that can be updated atomically. However, operations that combine more than one atomic reference are non-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 synchronized to guarantee atomicity:

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 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 example uses Collections.synchronizedList as a synchronization wrapper for the ArrayList. It subsequently uses an array, rather than an iterator, to iterate over the ArrayList to avoid a ConcurrentModificationException.

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

  public void addAndPrintIPAddresses(InetAddress address) {
    ips.add(address);
    InetAddress[] addressCopy = 
       

public void addIPAddress(InetAddress ia) { 
  synchronized(ips) { // Also synchronize this method
    // Validate
    ips.add(ia);
  }
}

public void run() {
  try {
    synchronized(ips) {
      addIPAddress(InetAddress.getLocalHost());
      ia = (InetAddress[]) ips.toArray(new InetAddress[0]);
    // Iterate through     
      System.out.println("Number of IPs: " + ia.length); array addressCopy ...
    }
  } catch (UnknownHostException e) { /* Forward to handler */ }     		
}

This form of synchronization is preferable over method synchronization for performance reasons. The advice suggested by this guideline applies to all uses of Collection classes including the thread-safe Hashtable class. Enumerations of the objects of a Collection and iterators also require explicit synchronization on the Collection object or any single lock object.

Although expensive, {{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, their use is limited to boosting performance in code where the writes are fewer (or non-existent) as compared to the reads  \[[JavaThreads 04|AA. Java References#JavaThreads 04]\]. In all other cases they must be avoided.    

Compliant Solution

Composition offers some benefits as compared to the previous solution, although at the cost of a slight performance penalty (refer to OBJ07-J. Understand how a superclass can affect a subclass for details on how to implement composition). This allows the CompositeCollection class to use its own intrinsic lock in a way that is completely independent of the lock of the underlying list class.

}

Individually, the add() and toArray() collection methods are atomic. However, when called in succession (as shown in the addAndPrintIPAddresses() method), there is no guarantee that the combined operation is atomic. The addAndPrintIPAddresses() method contains a race condition that allows one thread to add to the list and a second thread to race in and modify the list before the first thread completes. Consequently, the addressCopy array may contain more IP addresses than expected.

Compliant Solution (Synchronized Block)

The race condition can be eliminated by synchronizing on the underlying list's lock. This compliant solution encapsulates all references to the array list within synchronized blocks:

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

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

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

This code does not violate LCK04-J. Do not synchronize on a collection view if the backing collection is accessible because, although it synchronizes on a collection view (the synchronizedList result), the backing collection is inaccessible and consequently cannot be modified by any code.

Note that this compliant solution does not actually use the synchronization offered by Collections.synchronizedList(). If no other code in this solution used it, it could be eliminated.

Noncompliant Code Example (synchronizedMap())

This noncompliant code example defines the KeyedCounter class that is not thread-safe. Although the HashMap is wrapped in a synchronizedMap(), the overall increment operation is not atomic [Lee 2009].

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

  public void increment(String key

class CompositeCollection implements Runnable {
  private List<InetAddress> ips;
 
  public CompositeCollection(List<InetAddress> list) {
    this.ips = list;
  }
  
  public synchronized void addIPAddress(InetAddress ia) {
    //Integer Validate
old =   ipsmap.addget(iakey);
   }

 int publicoldValue void= run()old {
== null) ? 0 try {: old.intValue();
    if  InetAddress[] ia;   
(oldValue == Integer.MAX_VALUE) {
      throw new ia = (InetAddress[]) ips.toArray(new InetAddress[0]);ArithmeticException("Out of range");
     }
      System.out.println("Number of IPs: "map.put( key, oldValue + ia.length1); 
  }

  }public catchInteger getCount(UnknownHostExceptionString ekey) {
 /* Forward to handler */ }     		return map.get(key);
  }
}

This provides consistent locking even when the underlying list is not thread-safe or when it changes its locking policy. \[[Goetz 06|AA. Java References#Goetz 06]\]

Yet another method is to extend the base class and synchronize on the method that is desired to be atomic, however, it is not recommended because it goes against the spirit of limiting class extension ([OBJ05-J. Limit the extensibility of non-final classes and methods to only trusted subclasses]). Moreover, Goetz et al. \[[Goetz 06|AA. Java References#Goetz 06]\] cite other reasons:

Extension is more fragile than adding code directly to a class, because the implementation of the synchronization policy is now distributed over multiple, separately maintained source files. If the underlying class were to change its synchronization policy by choosing a different lock to guard its state variables, the subclass would subtly and silently break, because it no longer used the right lock to control concurrent access to the base class's state.

Noncompliant Code Example

This noncompliant code example defines a thread-unsafe {{KeyedCounter}} class. Even though the {{HashMap}} field is synchronized, the overall {{increment}} operation is not atomic. \[[Lee 09|AA. Java References#Lee 09]\]   

Compliant Solution (Synchronization)

This compliant solution ensures atomicity by using an internal private lock object to synchronize the statements of the increment() and getCount() methods:

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 oldValue = (old == null) ? 0 : old.intValue();
      if (oldValue == Integer.MAX_VALUE) {
        throw new ArithmeticException("Out of range");
      }
      map.put(key, oldValue + 1);
    }
  }

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

This compliant solution avoids using Collections.synchronizedMap() because locking on the unsynchronized map provides sufficient thread-safety for this application. LCK04-J. Do not synchronize on a collection view if the backing collection is accessible provides more information about synchronizing on synchronizedMap() objects.

Compliant Solution (ConcurrentHashMap)

The previous compliant solution is safe for multithreaded use but does not scale because of excessive synchronization, which can lead to decreased performance.

The ConcurrentHashMap class used in this compliant solution provides several utility methods for performing atomic operations and is often a good choice for algorithms that must scale [Lee 2009].

Note that this compliant solution still requires synchronization, because without it, the test to prevent overflow and the increment will not happen atomically, so two threads calling increment() can still cause overflow. The synchronization block is smaller and does not include the lookup or addition of new values, so it has less impact on performance than the previous compliant solution.

final

public class KeyedCounter {
  private Map<Stringfinal ConcurrentMap<String, Integer>AtomicInteger> map =
    Collections.synchronizedMap(  new HashMap<StringConcurrentHashMap<String, Integer>AtomicInteger>());

  publicprivate voidfinal increment(String key) {
    Integer old = map.get(key);Object lock = new Object();

  public void increment(String key) {
    intAtomicInteger value = (old == null) ? 1 : old.intValue() + 1;
    map.putnew AtomicInteger();
    AtomicInteger old = map.putIfAbsent(key, value);

  }

  publicif Integer getCount(String key(old != null) {
     return map.get(key) value = old;
    }
}

Compliant Solution

...

...

...

...

...

synchronized 

...

(lock)

...

public class KeyedCounter {
  private Map<String,Integer> map = new HashMap<String,Integer>();
 
  public synchronized void increment(String key) { {
      if (value.get() == Integer.MAX_VALUE) {
        throw new ArithmeticException("Out of range");
      }
    Integer old = mapvalue.getincrementAndGet(key);
 // Increment the int value =atomically
 (old == null) ? 1 : old.intValue()+1;
    map.put(key, value); }
  }

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

Compliant Solution

...

...

...

return 

...

(value 

...

== 

...

null) 

...

? 

...

null 

...

: value.get();
  }

  // Other accessors ...
}

According to Section 5.2.1., "ConcurrentHashMap," of the work of Goetz and colleagues [Goetz 2006]:

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 ConcurrentHashMap.size() and ConcurrentHashMap.isEmpty() are allowed to return an approximate result for performance reasons. Code should avoid relying on these return values when exact results are required.

Risk Assessment

Failure to ensure the atomicity of two or more operations that must be performed as a single atomic operation can result in race conditions in multithreaded applications.

Automated Detection

Some static analysis tools are capable of detecting violations of this rule.

Related Guidelines

Bibliography

...

Image Added Image Added Image Added

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.

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

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|AA. Java References#API 06]\] Class Vector, Class WeakReference
\[[JavaThreads 04|AA. Java References#JavaThreads 04]\] 8.2 "Synchronization and Collection Classes"
\[[Goetz 06|AA. Java References#Goetz 06]\] 4.4.1. Client-side Locking, 4.4.2. Composition and 5.2.1. ConcurrentHashMap
\[[Lee 09|AA. Java References#Lee 09]\] "Map & Compound Operation"

CON06-J. Do not defer a thread that is holding a lock      11. Concurrency (CON)      CON08-J. Do not invoke a superclass method or constructor from a synchronized region in the subclass