Page History

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

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

This visibility 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 (hereafter known as the aka referents) by volatile object references are beyond the scope of the visibility safe publication guarantee. Consequently, declaring an object reference to be volatile is insufficient to guarantee that changes to the members of the referent are visible. That is, a 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, if when the referent is immutable, declaring the reference volatile suffices to guarantee visibility safe publication of the members of the referent. Consequently, programmers must not Programmers cannot use the volatile keyword to guarantee visibility to safe publication of mutable objects; use . Use of the volatile keyword to guarantee visibility only to can only guarantee safe publication of primitive fields, object references, or fields of immutable object referents is permitted.

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.

...

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

The root of the problem is that 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 read from a volatile variable—the variable—the volatile reference to the array; neither . 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 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 it 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.

...

Synchronization establishes a 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 the Foo that instance, so visibility safe publication is guaranteed.

Noncompliant Code Example (Mutable Object)

This noncompliant code example declares the Properties instance Map instance field volatile. The instance of the Properties object can be mutated using the Map object is mutable because of its put() method; consequently, it is a mutable object.

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

Interleaved calls to get() and put() may result in the retrieval of internally inconsistent values being retrieved from the Properties object because the operations within Map object because put() modify modifies its state. Declaring the object reference volatile is insufficient to eliminate this data race.

The put() method lacks a time-of-check, time-of-use (TOCTOU) vulnerability, despite the presence of the validation logic, because the validation is performed on the immutable value argument rather than on the shared Properties instance.

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

This noncompliant code example attempts to use the volatile-read, synchronized-write technique described by Goetz in Java Theory and Practice [Goetz 2007]. The properties field map field is declared volatile to synchronize its reads and writes. The put() method is also synchronized to ensure that its statements are executed atomically.

final class Foo {
  private volatile Properties properties;
Map<String, String> map;
  public Foo() {
    propertiesmap = new HashMap<String, PropertiesString>();
    // Load some useful values into propertiesmap
  }

  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();
    }
    propertiesmap.setPropertyput(key, value);
  }
}

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 does not work with fails for mutable objects because the visibility safe publication guarantee provided by volatile extends only to the field itself (the primitive value or object reference); the referent (and hence is excluded from the guarantee, as are the referent's members) is excluded from the guarantee. Consequently. In effect, the write and a subsequent read of the property map lack a 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 method synchronization to guarantee visibility.:

final class Foo {
  private final Properties propertiesMap<String, String> map;

  public Foo() {
    propertiesmap = new PropertiesHashMap<String, String>();
    // Load some useful values into propertiesmap
  }

  public synchronized 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();
    }
    propertiesmap.setPropertyput(key, value);
  }
}

It is unnecessary to declare the properties field 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 rule TSM03-J. Do not publish partially initialized objects for more information).

Noncompliant Code Example (Mutable Subobject)

In this noncompliant code example, the volatile format field stores a reference to a mutable object, java.text.DateFormat.:

final class DateHandler {
  private static volatile DateFormat format =
    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 20062013], the value for Date returned by the parse() method might fail to 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 20062013].:

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

This solution complies with rule OBJ05-J. Defensively copy private mutable class members before returning their references because the class no longer contains internal mutable state.

Compliant Solution (Synchronization)

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

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

Exceptions

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.

CON50-EX0: Technically, strict immutability of the referent is a stronger condition than is fundamentally required for safe visibilitypublication. 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.

Risk Assessment

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

...

Guideline

...

Severity

...

Likelihood

...

Remediation Cost

...

Priority

...

Level

...

CON50-JG

...

medium

...

probable

...

medium

...

...

L2

Bibliography

 Image Removed      07. Visibility and Atomicity (VNA)      08. Locking (LCK)

...

Image Modified Image Modified Image Modified