Page History

{quote}
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.
{quote}

This visibility 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 _referents_) by volatile object references are beyond the scope of the visibility 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 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 \[java:[Goetz 2007|AA. Bibliography#Goetz 07]\].  However, if the referent is [immutable|java:BB. Definitions#immutable], declaring the reference volatile suffices to guarantee visibility of the members of the referent. Consequently, program must not use the {{volatile}} keyword to guarantee visibility to mutable objects; use of the {{volatile}} keyword to guarantee visibility only to primitive fields, object references, or fields of immutable object referents is permitted.



h2. Noncompliant Code Example (Arrays)

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

{code:bgColor=#FFcccc}
final class Foo {
  private volatile int[] arr = new int[20];

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

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

  // ...
}
{code}

}} both synchronize on the {{Foo}} instance, so visibility is guaranteed.


h2. Noncompliant Code Example (Mutable Object)

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

{code:bgColor=#FFcccc}
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);
  }
}
{code}

final class Foo {
  private volatile Map<String, String> map;
  public Foo() {
    map = new HashMap<String, String>();
    // Load some useful values into map
  }
  public String get(String s) {
    return map.get(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);
  }
}

final class Foo {
  private final Map<String, String> map;
  public Foo() {
    map = new HashMap<String, String>();
    // Load some useful values into map
  }
  public synchronized String get(String s) {
    return map.get(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 {{Properties}} object because the operations within {{put()}} modify 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.


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

This noncompliant code example attempts to use the volatile-read, synchronized-write technique described by Goetz \[java:[Goetz 2007|AA. Bibliography#Goetz 07]\]. The {{properties}} field is declared volatile to synchronize its reads and writes. The {{put()}} method is also synchronized to ensure that its statements are executed atomically.

{code:bgColor=#ffcccc}
final class Foo {
  private volatile Properties properties;

  public Foo() {
    properties = new Properties();
    // Load some useful values into properties
  }

  public String get(String s) {
    return properties.getProperty(s);
  }

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

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 mutable objects because the visibility guarantee provided by {{volatile}} extends only to the field itself (the primitive value or object reference); the referent (and hence the referent's members) is excluded from the guarantee. Consequently, the write and a subsequent read of the property lack a [happens-before|java:BB. Definitions#happens-before order] relationship.

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


h2. Compliant Solution (Synchronized)

This compliant solution uses method synchronization to guarantee visibility.

{code:bgColor=#ccccff}
final class Foo {
  private final Properties properties;

  public Foo() {
    properties = new Properties();
    // Load some useful values into properties
  }

  public synchronized String get(String s) {
    return properties.getProperty(s);
  }

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

It is unnecessary to declare the {{properties}} 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 [java:TSM03-J. Do not publish partially initialized objects] for more information).


h2. Noncompliant Code Example (Mutable Sub-Object)

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

{code:bgColor=#FFcccc}
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);
  }
}
{code}

Because {{DateFormat}} is not thread-safe \[java:[API 2006|AA. Bibliography#API 06]\], the value for {{Date}} returned by the {{parse()}} method might fail to correspond to the {{str}} argument.

{mc}
// Calls DateHandler, demo code
public class DateCaller implements Runnable {
  public void run(){
    try {
      System.out.println(DateHandler.parse("Jan 1, 2010"));
    } catch (ParseException e) {
  }

  public static void main(String[] args) {
    for(int i=0;i<10;i++)
      new Thread(new DateCaller()).start();
  }
}
{mc}

h2. Compliant Solution (Instance Per Call/Defensive Copying)

This compliant solution creates and returns a new {{DateFormat}} instance for each invocation of the {{parse()}} method. \[java:[API 2006|AA. Bibliography#API 06]\]

{code:bgColor=#ccccff}
final class DateHandler {
  public static java.util.Date parse(String str) throws ParseException {
    return DateFormat.getDateInstance(DateFormat.MEDIUM).parse(str);
  }
}
{code}

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


h2. Compliant Solution (Synchronization)

This compliant solution makes {{DateHandler}} thread-safe by synchronizing statements within the {{parse()}} method \[java:[API 2006|AA. Bibliography#API 06]\].

{code:bgColor=#ccccff}
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);
    }
  }
}
{code}


h2. Compliant Solution ({{ThreadLocal}} Storage)

This compliant solution uses a {{ThreadLocal}} object to create a separate {{DateFormat}} instance per thread.

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

h2. Exceptions

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


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

|| Rule || Severity || Likelihood || Remediation Cost || Priority || Level ||
| VNA06-J | medium | probable | medium | {color:#cc9900}{*}P8{*}{color} | {color:#cc9900}{*}L2{*}{color} |

h2. Bibliography

| \[java:[API 2006|AA. Bibliography#API 06]\] | Class {{java.text.DateFormat}} |
| \[java:[Goetz 2007|AA. Bibliography#Goetz 07]\]  | Pattern #2: "one-time safe publication" |
| \[java:[JLS 2005|AA. Bibliography#JLS 05]\] | |
| \[java:[Miller 2009|AA. Bibliography#Miller 09]\] | Mutable Statics |


----
[!The CERT Oracle Secure Coding Standard for Java^button_arrow_left.png!|java:VNA05-J. Ensure atomicity when reading and writing 64-bit values]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[!The CERT Oracle Secure Coding Standard for Java^button_arrow_up.png!|java:07. Visibility and Atomicity (VNA)]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[!The CERT Oracle Secure Coding Standard for Java^button_arrow_right.png!|java:08. Locking (LCK)]

getDateInstance(DateFormat.MEDIUM);

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

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

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

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