Page History

Thread-safety guarantees that no two threads can simultaneously access or modify some shared data. However, if two or more operations need to be performed safelyas a single large atomic operation, it becomes necessary to add additional locking in order 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.

Programmers If an invariant exists involving two objects, it is tempting to believe that if the objects are atomic, no additional locking is required; however this is not the case. Likewise, programmers sometimes assume that using a thread-safe Collection does not require explicit synchronization in order to preserve an invariant involving the collection's elements. Any object that guarantees atomicity can only guarantee atomicity over the individual methods it promises to be thread-safe.

which is a misleading thought. It follows that using a thread-safe Collection by itself does not ensure program correctness unless special care is taken to ensure that the client performs all related and independently atomic operations, as one atomic operation. For example, the standard thread-safe API may 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 thread-safe atomic method must be designed and used. This guideline shows the need of such a method that performs to perform a group of independently atomic operations as one atomic operation, and also suggests techniques for incorporating the method using a custom API. The custom API is essential because the standard API cannot be changed without breaking other code that relies on it.

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.

Noncompliant Code Example (

...

AtomicReference)

This noncompliant code example comprises 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. uses two AtomicReference objects to hold one BigInteger object reference each.

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

  public AtomicAdder(BigInteger f, BigInteger s)

class RaceCollection {
  private final List<InetAddress>first ips = new Collections.synchronizedList(new ArrayList<InetAddress>()AtomicReference<BigInteger>(f);
    second = new AtomicReference<BigInteger>(s);
  }

  public void addIPAddress(InetAddress iaupdate(BigInteger f, BigInteger s) { // Unsafe
    // Validatefirst.set(f);
    ipssecond.addset(ias);
  }
  
  public voidBigInteger addAndPrintIPadd() throws{ UnknownHostException// {Unsafe
    return addIPAddress(InetAddressfirst.getLocalHostget());
    InetAddress[] ia = (InetAddress[]) ips.toArray(new InetAddress[0].add(second.get()); 
     
    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, indicates a race condition between the threads. In other words, the statements in method addAndPrint() that are responsible for adding an IP address and printing it out are not sequentially consistent. Likewise, the operations within a thread's run() method are nonatomic.

Noncompliant Code Example (Subclass)

}
}

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. For instance, in this noncompliant code example, one thread could call update() while a second thread calls add(), with the result that the add() operation adds the newer value of first to the older value of second, yielding an erroneous result.

Compliant Solution (method synchronization)

This compliant solution declares the update() and add() methods as synchronized to guarantee atomicityThis noncompliant code example extends the base class and synchronizes the addAndPrintIP() method which is required to be atomic.

public class RaceCollectionSub extends RaceCollectionAtomicAdder {

  public synchronized void addAndPrintIPupdate()BigInteger throwsf, UnknownHostExceptionBigInteger s){
    addIPAddress(InetAddressfirst.getLocalHostset(f));
    InetAddress[] ia = (InetAddress[]) ips.toArray(new InetAddress[0]);      
    System.out.println("Number of IPs: " + ia.length);     
  }
}

However, this 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.

Moreover, when a wrapper such as {{Collections.synchronizedList()}} is used (as shown in the previous noncompliant code example), it is unwieldy for a client to determine the type of the class ({{List}}) that is being wrapped. Consequently, it is not directly possible to extend the class \[[Goetz 06|AA. Java References#Goetz 06]\].

Noncompliant Code Example (Method synchronization)

This noncompliant code example appears to use synchronization when defining the addAndPrintIP() method, however, it acquires an intrinsic lock instead of the lock of the List object. This means that another thread may modify the value of the List instance when the addAndPrintIP() method is executing.

class Helper {
  public final List<InetAddress> ips = Collections.synchronizedList(new ArrayList<InetAddress>());
  
  public synchronized void addIPAddress(InetAddress ia) {
    // Validate
    ips.add(ia);
  }

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

This noncompliant code example also violates OBJ00-J. Declare data members private. It does not violate CON02-J. Always synchronize on the appropriate object because ips is declared as final and consequently, the lock object cannot be changed by another thread.

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

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

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

second.set(s);
  }

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

Prefer using the block form of synchronization for better performance, when there are nonatomic operations within the method that do not require any synchronization. These operations can be decoupled from those that require synchronization and executed outside the synchronized block.

Noncompliant Code Example (synchronizedList)

This noncompliant code example comprises an ArrayList collection which is non-thread-safe by default. However, 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.

class RaceCollection {
  private final List<InetAddress> ips = Collections.synchronizedList(new ArrayList<InetAddress>());
  
  public void addIPAddress(InetAddress ia) {
    // Validate
    ips.add(ia);
  }
  
  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 addAndPrint() that are responsible for adding an IP address and printing it out are not sequentially consistent.

Noncompliant Code Example (Subclass)

This noncompliant code example extends the base class and synchronizes the addAndPrintIP() method which is required to be atomic.

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

However, this 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.

Moreover, when a wrapper such as {{Collections.synchronizedList()}} is used (as shown in the previous noncompliant code example), it is unwieldy for a client to determine the type of the class ({{List}}) that is being wrapped. Consequently, it is not directly possible to extend the class \[[Goetz 06|AA. Java References#Goetz 06]\].

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.

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

public void addAndPrintIP() throws UnknownHostException {
  synchronized(ips) {
    addIPAddress(InetAddress.getLocalHost());
    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|AA. Java References#Goetz 06]\], because the class holds a lock on an object that presumably might be accessible to other classes. 

Goetz et al. \[[Goetz 06|AA. Java References#Goetz 06]\] caution against misuse of client-side locking:

...

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 (see [MSC13-J. Do not modify the underlying collection when an iteration is in progress]).    

Compliant Solution (Composition)

Composition offers more 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 approach 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. Moreover, this permits the underlying collection to be thread-unsafe because the {{CompositeCollection}} wrapper prevents direct accesses to its methods by exposing its own synchronized equivalents. This approach also 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]\]

Noncompliant Code Example (synchronizedMap)

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]\]   

public 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 method)

This compliant solution declares the {{increment()}} method and {{getCount}} methods as {{synchronized}} to ensure atomicity \[[Lee 09|AA. Java References#Lee 09]\]. 

...

Also, note that this would be a violation of a previously discussed noncompliant code example if the field map were to refer to a Collections.synchronizedMap object. This compliant solution uses the intrinsic lock of the class for all purposes.

Compliant Solution (ConcurrentHashMap)

The previous compliant solution does not scale very well because a class with several {{synchronized}} methods iscan abe potential bottleneck as far as acquiring locks is concerned and may further lead to contention or deadlock. The class {{ConcurrentHashMap}}, through a more preferable approach, provides several utility methods to perform atomic operations and is used in this compliant solution \[[Lee 09|AA. Java References#Lee 09]\]. 

...

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.

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"

...