Page History

A consistent locking policy guarantees that multiple threads cannot simultaneously access or modify shared data. If When two or more operations need to must be performed as a single atomic operation, it is necessary to implement a consistent locking policy by must be implemented using 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 caseWhen 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 may might incorrectly assume that using use of a thread-safe Collection does not require explicit synchronization 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 where in which the standard thread-safe API does not provide lacks a single method both to both find a particular person's record in a Hashtable and also update the corresponding to update that person's payroll information. In such cases, a custom atomic the two method invocations must be designed and usedperformed 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 CON01(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 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. Operations that use two atomic references independently, are guaranteed to be atomic, however, if an operation involves using both together, the resulting combined operation is not atomicHowever, 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 as synchronized to guarantee atomicity. :

final class Adder {
  // ...

  publicprivate synchronizedfinal void update(BigInteger f, BigInteger s){
    first.setAtomicReference<BigInteger> first;
  private final AtomicReference<BigInteger> second;

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



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

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

Prefer using block synchronization instead of method 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 private final lock objects. Non-atomic operations can be decoupled from those that require synchronization and executed outside the synchronized block. The guideline CON04-J. Use private final lock objects to synchronize classes that may interact with untrusted code has more details on using private final lock objects and block synchronization.

Noncompliant Code Example (synchronizedList)

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

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 

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

Even though the Collection wrapper offers thread-safety guarantees, atomicity related issues manifest themselves when calling methods of this class. When the addAndPrintIPAddresses() method is invoked on the same object from multiple threads, different sequences of IP addresses are produced from every other thread, which indicates that the code is operating under race conditions. The statements in method addAndPrintIPAddresses() are not sequentially consistentIndividually, 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)

To eliminate the race conditions, ensure atomicity by using The race condition can be eliminated by synchronizing on the underlying list's lock. This compliant solution includes all statements that use encapsulates all references to the array list within a synchronized block that locks on the list. synchronized blocks:

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

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

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

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) {
    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) {
    return map.get(key);
  }
}

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)

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 valueoldValue = (old == null) ? 10 : old.intValue() + 1;
      map.put(key, value);if (oldValue == Integer.MAX_VALUE) {
    }
  }

  publicthrow Integernew getCount(String key) {ArithmeticException("Out of range");
    synchronized (lock) {}
      return map.getput(key, oldValue + 1);
    }
  }

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

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 class KeyedCounter {
  private final ConcurrentMap<String, AtomicInteger> map =
      new ConcurrentHashMap<String, AtomicInteger>();
  private final Object lock = new Object();

  public void increment(String key) {
    AtomicInteger value = new AtomicInteger();
    AtomicInteger old = map.putIfAbsent(key, value);

    if (old != null

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)old;
    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|AA. Java References#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|AA. Java References#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|AA. Java References#API 06]\] 
\[[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, 5.2.1. ConcurrentHashMap
\[[Lee 09|AA. Java References#Lee 09]\] "Map & Compound Operation"

synchronized (lock) {
      if (value.get() == Integer.MAX_VALUE) {
        throw new ArithmeticException("Out of range");
      }
      value.incrementAndGet(); // Increment the value atomically
    }
  }

  public Integer getCount(String key) {
    AtomicInteger value = map.get(key);
    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 VOID CON06-J. Do not defer a thread that is holding a lock      11. Concurrency (CON)      Image Modified