...
According
...
to
...
the
...
Java
...
Language
...
Specification
...
[
...
...
...
]
...
,
...
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.
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 [Goetz 2007]. However, if the referent is immutable, declaring the reference volatile suffices to guarantee visibility of the members of the referent. Consequently, programmers 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.
Noncompliant Code Example (Arrays)
This noncompliant code example declares a volatile reference to an array object.
| Code Block | ||
|---|---|---|
| ||
{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 \[[Goetz 2007|AA. References#Goetz 07]\]. However, if the referent is [immutable|BB. Glossary#immutable], declaring the reference volatile suffices to guarantee visibility of the members of the referent. Consequently, programmers 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} |
Values
...
assigned
...
to
...
an
...
array
...
element
...
by
...
one
...
thread,
...
for
...
example,
...
by
...
calling
...
setFirst()
...
,
...
might
...
be
...
invisible
...
to
...
another
...
thread
...
calling
...
getFirst()
...
,
...
because
...
the volatile keyword only makes the array reference visible; it fails to affect the actual data contained within the array.
The root of the problem is that 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() only read 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
...
.
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} 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); } // ... } {code} {{AtomicIntegerArray}} guarantees a [happens-before|BB. Glossary#happens-before order] relationship between a thread that calls {{ |
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
...
it
...
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.
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} 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; } } {code} |
Synchronization
...
establishes
...
a
...
...
...
relationship
...
between
...
threads
...
that
...
synchronize
...
on
...
the
...
same
...
lock.
...
In
...
this
...
case,
...
the
...
thread
...
that
...
calls
...
setFirst()
...
and
...
the
...
thread
...
that
...
subsequently
...
calls
...
getFirst()
...
both
...
synchronize
...
on
...
the Foo instance,
...
so
...
visibility
...
is
...
guaranteed.
...
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 Block | ||||
|---|---|---|---|---|
| =
| |||
} 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 void put(String key, String value) { // Validate the values before inserting if (!value.matches("[\\w]*")) { throw new IllegalArgumentException(); } properties.setProperty(key, value); } } {code} |
Interleaved
...
calls
...
to
...
get()
...
and
...
put()
...
may
...
result
...
in
...
internally
...
inconsistent
...
values
...
being
...
retrieved
...
from
...
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.
...
Noncompliant
...
Code
...
Example
...
(Volatile-Read,
...
Synchronized-Write)
...
This
...
noncompliant
...
code
...
example
...
attempts
...
to
...
use
...
the
...
volatile-read,
...
synchronized-write
...
technique
...
described
...
by
...
Goetz
...
[
...
...
...
].
...
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 Block | ||||
|---|---|---|---|---|
| =
| |||
} 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
...
...
relationship.
...
This
...
technique
...
is
...
also
...
discussed
...
in
...
...
...
...
...
...
...
...
...
...
...
.
...
Compliant
...
Solution
...
(Synchronized)
...
This
...
compliant
...
solution
...
uses
...
method
...
synchronization
...
to
...
guarantee
...
visibility.
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} 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
...
...
...
...
...
...
...
...
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
...
.
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} 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 |
Because DateFormat is not thread-safe
...
[API
...
...
]
...
,
...
the
...
value
...
for
...
Date
...
returned
...
by
...
the
...
parse()
...
method
...
might
...
fail
...
to
...
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 2006].
| Code Block | ||
|---|---|---|
| ||
final class DateHandler}} argument. {mc} // Calls DateHandler, demo code public class DateCaller implements Runnable { public void run(){ try static java.util.Date parse(String str) throws ParseException { return System.out.println(DateHandlerDateFormat.getDateInstance(DateFormat.MEDIUM).parse("Jan 1, 2010")str); } catch (ParseException e) { } public static } |
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 2006].
| Code Block | ||
|---|---|---|
| ||
final class DateHandlervoid main(String[] args) { private for(int i=0;i<10;i++)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.
| Code Block | ||
|---|---|---|
| ||
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 \[[API 2006|AA. References#API 06]\]. {code:bgColor=#ccccff} final class DateHandler { publicprivate static java.util.Date parse(String str) throws ParseException { final ThreadLocal<DateFormat> format = new ThreadLocal<DateFormat>() { @Override protected DateFormat initialValue() { return DateFormat.getDateInstance(DateFormat.MEDIUM).parse(str); } } {code} 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. h2. Compliant Solution (Synchronization) This compliant solution makes {{DateHandler}} thread-safe by synchronizing statements within the {{parse()}} method \[[API 2006|AA. References#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 final ThreadLocal<DateFormat> format = new ThreadLocal<DateFormat>() { @Override protected DateFormat initialValue() { return DateFormat.getDateInstance(DateFormat.MEDIUM); } }; // ... } {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 | \[[API 2006|AA. References#API 06]\] | Class {{java.text.DateFormat}} | | \[[Goetz 2007|AA. References#Goetz 07]\] | Pattern #2: "One-time safe publication" | | \[[JLS 2005|AA. References#JLS 05]\] | | | \[[Miller 2009|AA. References#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] [!The CERT Oracle Secure Coding Standard for Java^button_arrow_up.png!|java:07. Visibility and Atomicity (VNA)] [!The CERT Oracle Secure Coding Standard for Java^button_arrow_right.png!|java:08. Locking (LCK)] }; // ... } |
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.
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 | P8 | L2 |
Bibliography
[API 2006] | Class |
Pattern #2: "One-time safe publication" | |
[JLS 2005] |
|
Mutable Statics |
...