Page History

According to the Java Language Specification, §8.3.1.4, "volatile Fields" [JLS 2013],

A field may be declared volatile, in which case the Java Memory Model ensures that all threads see a consistent value for the variable (§17.4).

This safe publication guarantee applies only to primitive fields and object references. Programmers commonly use imprecise terminology and speak about "member objects." For the purposes of this visibility guarantee, the actual member is the object reference; the objects referred to (aka referents) by volatile object references are beyond the scope of the safe publication guarantee. Consequently, declaring an object reference to be volatile is insufficient to guarantee that changes to the members of the referent are published to other threads. A thread may fail to observe a recent write from another thread to a member field of such an object referent.

Furthermore, when the referent is mutable and lacks thread safety, other threads might see a partially constructed object or an object in a (temporarily) inconsistent state [Goetz 2007]. However, when the referent is immutable, declaring the reference volatile suffices to guarantee safe publication of the members of the referent. Programmers cannot use the volatile keyword to guarantee safe publication of mutable objects. Use of the volatile keyword can only guarantee safe publication of primitive fields, object references, or fields of immutable object referents.

Confusing a volatile object with the volatility of its member objects is a similar error to the one described in OBJ50-J. Never confuse the immutability of a reference with that of the referenced object.

Noncompliant Code Example (Arrays)

This noncompliant code example declares a volatile reference to an array object.

final class Foo {
  private volatile int[] arr = new int[20];

  public int getFirst() {
    return arr[0];
  }

  public void setFirst(int n) {
    arr[0] = n;
  }

  // ...
}

Values assigned to an array element by one thread—for example, by calling setFirst()—might not be visible to another thread calling getFirst() because the volatile keyword guarantees safe publication only for the array reference; it makes no guarantee regarding the actual data contained within the array.

This problem arises when the thread that calls setFirst() and the thread that calls getFirst() lack a happens-before  relationship. A happens-before relationship exists between a thread that writes to a volatile variable and a thread that subsequently reads it. However, setFirst() and getFirst() read only from a volatile variable—the volatile reference to the array. Neither method writes to the volatile variable.

Compliant Solution (AtomicIntegerArray)

To ensure that the writes to array elements are atomic and that the resulting values are visible to other threads, this compliant solution uses the AtomicIntegerArray class defined in java.util.concurrent.atomic.

final class Foo {
  private final AtomicIntegerArray atomicArray = 
    new AtomicIntegerArray(20);

  public int getFirst() {
    return atomicArray.get(0);
  }

  public void setFirst(int n) {
    atomicArray.set(0, 10);
  }

  // ...
}

AtomicIntegerArray guarantees a happens-before relationship between a thread that calls atomicArray.set() and a thread that subsequently calls atomicArray.get().

Compliant Solution (Synchronization)

To ensure visibility, accessor methods may synchronize access while performing operations on nonvolatile elements of an array, whether the array is referred to by a volatile or a nonvolatile reference. Note that the code is thread-safe even though the array reference is not volatile.

final class Foo {
  private int[] arr = new int[20];

  public synchronized int getFirst() {
    return arr[0];
  }

  public synchronized void setFirst(int n) {
    arr[0] = n;
  }
}

Synchronization establishes a happens-before relationship between threads that synchronize on the same lock. In this case, the thread that calls setFirst() and the thread that subsequently calls getFirst() on the same object instance both synchronize on that instance, so safe publication is guaranteed.

Noncompliant Code Example (Mutable Object)

This noncompliant code example declares the Map instance field volatile. The instance of the Map object is mutable because of its 

Declaring an object volatile in order to ensure visibility of the most up-to-date object state does not work without the use of explicit synchronization, unless the object is effectively immutable.

In the absence of synchronization, the effect of declaring an object reference {{volatile}} is that when one thread sets the object to a new value, other threads can see the change immediately. In other words, the new value is immediately visible. If the object is immutable, then this has the effect that other threads see a clear change in the object's state. However, if one thread modifies an object, then other threads may see a partially-modified object, or an object in a (temporarily) inconsistent state \[[Goetz 07|AA. Java References#Goetz 07]\]. {{volatile}} does not prevent this.

According to the Java Language Specification \[[JLS 05|AA. Java References#JLS 05]\], section, 8.3.1.4 {{volatile}} Fields:

A field may be declared volatile, in which case the Java memory model (§17) ensures that all threads see a consistent value for the variable.

Notably, this applies only to fields and not to the contents of arrays or objects that are declared volatile. A thread may not observe a recent write to the array's element or object's field from another thread.

Noncompliant Code Example (Properties)

This noncompliant code example declares an instance field of type Properties as volatile. The field can be mutated using the put() method.

publicfinal class Foo {
  private volatile Map<String, PropertiesString> propertiesmap;
 
  public Foo() {
    propertiesmap = new HashMap<String, PropertiesString>();
    // ...Load load some useful values into properties ...map
  }
 
  public String get(String s) {
    return propertiesmap.getPropertyget(s);
  }
 
  public void put(String key, String value) {
    // Perform validation of value Validate the values before inserting
    if (!value.matches("[\\w]*")) {
    properties.setProperty  throw new IllegalArgumentException();
    }
    map.put(key, value);
  }
}

This class permits a race condition. If one thread calls Interleaved calls to get() while another thread calls and put(), then the first thread might receive a stale value, or an internally inconsistent value from the properties object. Being declared volatile does not

Even if the client thread sees the new reference to properties, the object state that it observes may change in the meantime. The Java Memory Model does not guarantee that the properties field will have been properly initialized when it is necessary. Because the object is not immutable, it is unsafe for use in a multi-threaded environment.

Compliant Solution (immutable)

may result in the retrieval of internally inconsistent values from the Map object because put() modifies its state. Declaring the object reference volatile is insufficient to eliminate this data race.

Noncompliant Code Example (Volatile-Read, Synchronized-Write)

This noncompliant code example attempts to use the volatile-read, synchronized-write technique described in Java Theory and Practice [Goetz 2007]. The map field is declared volatile to synchronize its reads and writes. The put() method is also synchronized to ensure that its statements are executed atomicallyThis compliant solution renders the Foo class effectively immutable. Consequently, once it is properly constructed, no thread can modify properties and cause a race condition.

publicfinal class Foo {
  private volatile Map<String, PropertiesString> propertiesmap;

  public Foo() {
    propertiesmap = new HashMap<String, PropertiesString>();
    // ...Load load some useful values into properties ...map
  }

  public String get(String s) {
    return propertiesmap.getPropertyget(s);
  }
  public synchronized void put(String key, String value) {
    // Validate the values before inserting
    if (!value.matches("[\\w]*")) {
      throw new IllegalArgumentException();
    }
    map.put(key, value);

The obvious drawback of this solution is that the put() method cannot be accommodated if the goal is to ensure immutability. The Foo and Properties classes are both effectively immutable. They are not truly immutable because the Properties class is not final.

...

  }
}

The volatile-read, synchronized-write technique uses synchronization to preserve atomicity of compound operations, such as increment, and provides faster access times for atomic reads. However, it fails for mutable objects because the safe publication guarantee provided by volatile extends only to the field itself (the primitive value or object reference); the referent is excluded from the guarantee, as are the referent's members. In effect, the write and a subsequent read of the map lack a happens-before relationship.

This technique is also discussed in VNA02-J. Ensure that compound operations on shared variables are atomic.

Compliant Solution (Synchronized)

This compliant solution uses explicit synchronization to ensure thread safety. It declares the object volatile to guard retrievals that use the getter method. A synchronized setter method is used to set the value of the Properties object. method synchronization to guarantee visibility:

publicfinal class Foo {
  private volatile Properties propertiesfinal Map<String, String> map;

  public Foo() {
    propertiesmap = new HashMap<String, PropertiesString>();
    // ...Load load some useful values into properties ...map
  }

  public synchronized String get(String s) {
    return propertiesmap.getPropertyget(s);
  }

  public synchronized void put(String key, String value) {
    // Perform validation of value Validate the values before inserting
    if (!value.matches("[\\w]*")) {
      throw new IllegalArgumentException();
    properties.setProperty}
    map.put(key, value);
  }
}

This compliant solution has the advantage that it can accommodate the setter method. Declaring the object as volatile for safe publication using getter methods is cheaper in terms of performance, than declaring the getters as synchronized. However, synchronizing the setter methods is mandatoryIt is unnecessary to declare the map field volatile because the accessor methods are synchronized. The field is declared final to prevent publication of its reference when the referent is in a partially initialized state (see TSM03-J. Do not publish partially initialized objects for more information).

Noncompliant Code Example (

...

Mutable Subobject)

This In this noncompliant code example shows an array that is declared volatile. It appears that, when a value is written by a thread to one of the array elements, it will be visible to other threads immediately. This is misleading because the volatile keyword just makes the array reference visible to all threads and does not affect the actual data contained within the array. , the volatile format field stores a reference to a mutable object, java.text.DateFormat:

final class DateHandler {
  private static volatile int[]DateFormat arrformat =
  new int[20];
// ...
arr[1] = 10;

It is possible for one thread to set a new value to arr1 while another thread attempts to read the value of arr1, with the result that the reading thread receives an inconsistent value for arr1.

Compliant Solution (AtomicIntegerArray

This compliant solution suggests using the java.util.concurrent.atomic.AtomicIntegerArray concurrency utility. Using its set(index, value) method ensures that the write is atomic and the resulting value is immediately visible to other threads. The other threads can retrieve a value from a specific index by using the get(index) method.

AtomicIntegerArray aia = new AtomicIntegerArray(5);
// ...
aia.set(1, 10);

Risk Assessment

Failing to synchronize access to shared mutable data can cause different threads to observe different states of the object.

Automated Detection

TODO

Related Vulnerabilities

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

References

\[[Goetz 07|AA. Java References#Goetz 07]\] Pattern #2: "one-time safe publication"
\[[JLS 05|AA. Java References#JLS 05]\]

  DateFormat.getDateInstance(DateFormat.MEDIUM);

  public static java.util.Date parse(String str) 
      throws ParseException {
    return format.parse(str);
  }
}

Because DateFormat is not thread-safe [API 2013], the value for Date returned by the parse() method may not correspond to the str argument:

Compliant Solution (Instance per Call/Defensive Copying)

This compliant solution creates and returns a new DateFormat instance for each invocation of the parse() method [API 2013]:

final class DateHandler {
  public static java.util.Date parse(String str) 
      throws ParseException {
    return DateFormat.getDateInstance(
      DateFormat.MEDIUM).parse(str);
  }
}

Compliant Solution (Synchronization)

This compliant solution makes DateHandler thread-safe by synchronizing statements within the parse() method [API 2013]:

final class DateHandler {
  private static DateFormat format =
    DateFormat.getDateInstance(DateFormat.MEDIUM);

  public static java.util.Date parse(String str) 
      throws ParseException {
    synchronized (format) {
      return format.parse(str);
    }
  }
}

Compliant Solution (ThreadLocal Storage)

This compliant solution uses a ThreadLocal object to create a separate DateFormat instance per thread:

final class DateHandler {
  private static final ThreadLocal<DateFormat> format = 
    new ThreadLocal<DateFormat>() {
    @Override protected DateFormat initialValue() {
      return DateFormat.getDateInstance(DateFormat.MEDIUM);
    }
  };
  // ...
}

Applicability

Incorrectly assuming that declaring a field volatile guarantees safe publication of a referenced object's members can cause threads to observe stale or inconsistent values.

Technically, strict immutability of the referent is a stronger condition than is fundamentally required for safe publication. When it can be determined that a referent is thread-safe by design, the field that holds its reference may be declared volatile. However, this approach to using volatile decreases maintainability and should be avoided.

Bibliography

...

Image Added Image Added Image AddedFIO36-J. Do not create multiple buffered wrappers on an InputStream      09. Input Output (FIO)      09. Input Output (FIO)