The Java language annotation facility is useful for documenting the design intent behind specific concurrency properties of code. Source code annotation is a mechanism for associating metadata with a program element and making it available to the compiler, analyzers, tools such as debuggers, or the VM Java Virtual Machine (JVM) for examination. Several annotations are available for documenting thread-safety , or the lack thereof.
Obtaining Concurrency Annotations
Wiki Markup
The second, larger , set of concurrency annotations is available from and supported by SureLogic. The SureLogic These annotations are released under the The Apache Software License, Version 2.0 and can be downloaded from via the Internet Archive at surelogic.com (jar, javadoc, source). These The annotations can be verified by the SureLogic JSure tool, and are they remain useful for documenting code even if when the tool is unavailable. The SureLogic These annotations also include the JCIP annotations because they are supported by the JSure tool. (JSure also supports use of the JCIP Jar JAR file.).
To use the annotations, download and add one or both of the above Jar aforementioned JAR files to the code's build path. The use of these annotations to document thread-safety is discussed belowis descr
| Warning | ||
|---|---|---|
| ||
These examples are based on SureLogic, as of 2010. The intent is still useful but the implementation is no longer supported. We recommend using an annotation package that still enjoys active support. |
Documenting Intended Thread-
...
Safety
JCIP provides three class-level annotations to describe the programmer's design intent with respect to thread-safety.
The @ThreadSafe annotation is applied to a class to indicate that it is thread-safe. This means that no sequences of accesses (reads and writes to public fields, calls to public methods) may can leave the object in an inconsistent state, regardless of the interleaving of these accesses by the runtime or any external synchronization or coordination on the part of the caller.
For example, the following Aircraft class shown below specifies that it is thread-safe as part of its locking policy documentation. This class protects the x and y fields using a ReentrantLockreentrant lock.
| Code Block | ||
|---|---|---|
| ||
@ThreadSafe
@Region("private AircraftState")
@RegionLock("StateLock is stateLock protects AircraftState")
public final class Aircraft {
private final Lock stateLock = new ReentrantLock();
// ...
@InRegion("AircraftState")
private long x, y;
// ...
public void setPosition(long x, long y) {
stateLock.lock();
try {
this.x = x;
this.y = y;
} finally {
stateLock.unlock();
}
}
// ...
}
|
The @Region and @RegionLock annotations document the precise locking policy that upon which the promise of thread-safety is predicated upon.
Even if when one or more @RegionLock or @GuardedBy annotations have been used to document the locking policy of a class, the @ThreadSafe annotation provides an intuitive way for reviewers to learn that the class is thread-safe.
The @Immutable: This annotation is applied to to immutable classes. Immutable objects are inherently thread-safe; they may be safely shared amongst multiple threads after they once they are fully constructed, and published by declaring the corresponding reference as volatilethey may be published via a reference and shared safely among multiple threads.
The following example shows an immutable Point class:
| Code Block | ||
|---|---|---|
| ||
@Immutable public final class Point { private final int f_x; private final int f_y; public Point(int x, int y) { f_x = x; f_y = y; } public int getX() { return f_x; } public int getY() { return f_y; } } |
According to Joshua Bloch [Bloch 2008],
It is not necessary to document the immutability of
enumtypes. Unless it is obvious from the return type, static factories must document the thread safety of the returned object, as demonstrated byCollections.synchronizedMap.
The @NotThreadSafe @NotThreadSafe This annotation is applied to classes that are not thread-safe. Several Many classes do not fail to document whether they are safe for multithreaded use or not. Consequently, a programmer has no easy way to determine whether the class is thread-safe. This annotation provides clear indication of the class's lack of thread-safety.
For example, most of the collection implementations provided in java.util are not thread-safe. The class java.util.ArrayList which is not thread-safe could document this as shown below.follows:
| Code Block | ||
|---|---|---|
| ||
package java.util.ArrayList; @NotThreadSafe public class ArrayListArrayList<E> extends ... { // ... } |
Documenting Locking Policies
Wiki Markup
For each mutable state variable that may be accessed by more than one thread, all accesses to that variable must be performed with the same lock held. In this case, we say that the variable is guarded by that lock. (p. 28)
Consequently, it is important to document all the locks that are being used to protect shared state. JCIP provides the @GuardedBy annotation for this purpose while , and SureLogic provides the @RegionLock annotation. @GuardedBy: The field or method to which this the @GuardedBy annotation is applied can only be accessed only when holding a particular lock, which . It may be an intrinsic lock , or a dynamic lock such as java.util.concurrent.Lock.
For example, the following MovablePoint class implements a movable point which has the capability of remembering that can remember its past locations using an the memo array list, memo.:
| Code Block | ||
|---|---|---|
| ||
@ThreadSafe public final class MovablePoint { @GuardedBy("this") double xPos = 1.0; @GuardedBy("this") double yPos = 1.0; @GuardedBy("itself") static final List<MovablePoint> memo = new ArrayList<MovablePoint>(); public void move(double slope, double distance) { synchronized rememberPoint(this); { synchronized rememberPoint(this) {; xPos += (1 / slope) * distance; yPos += slope * distance; } } public static void rememberPoint(MovablePoint value) { synchronized (memo) { memo.add(value); } } } |
The @GuardedBy annotations on the xPos and yPos fields indicate that access to these fields is protected by holding a lock on this (as is done in the . The move() method also synchronizes on this, which mutates modifies these fields). The The @GuardedBy annotation on the memo list indicates that a lock on the ArrayList object protects its contents (as is done in the . The rememberPoint() method )also synchronizes on the memo list.
One issue with the the @GuardedBy annotation is that it does not clarify that fails to indicate when there is a relationship between the two fields in the above examplefields of a class. This limitation can be overcome by using the SureLogic @RegionLock annotation.@RegionLock: Declares , which declares a new region lock for the class to which this annotation is applied. This declaration creates a new named lock that associates a particular lock object with a region of the class. The region may only be accessed only when the lock is held. For example, the SimpleLock locking policy indicates that synchronizing on the instance protects all of the instance's its state:
| Code Block | ||
|---|---|---|
| ||
@RegionLock("SimpleLock is this protects Instance")
class Simple { ... }
|
Unlike @GuardedBy, the @RegionLock annotation allows the programmer to give an explicit, and hopefully meaningful, name to the locking policy.
In addition to naming the locking policy, the @Region annotation allows a name to be given to the region of the state that is being protected. This That name makes it clear that the state belongs together with respect to the and locking policy . This is belong together, as demonstrated in the following example:
| Code Block | ||
|---|---|---|
| ||
@Region("private AircraftPosition")
@RegionLock("StateLock is stateLock protects AircraftPosition")
public final class Aircraft {
private final Lock stateLock = new ReentrantLock();
@InRegion("AircraftPosition")
private long x, y;
@InRegion("AircraftPosition")
private long altitude;
// ...
public void setPosition(long x, long y) {
stateLock.lock();
try {
this.x = x;
this.y = y;
} finally {
stateLock.unlock();
}
}
// ...
}
|
In this example, a locking policy named StateLock is used to indicate that locking on the java.util.concurrent.Lock stateLock protects the named AircraftPosition region, AircraftPosition, which includes the mutable state used to represent the position of the aircraft.
Construction of
...
Mutable Objects
Typically, object construction is considered an exception to the locking policy because objects are thread-confined when they are created. An object is confined to the thread that uses the new operator to create its instance. After creation, the object can be safely published to other threads safely. However, the object is not shared until the thread that created the instance allows it to be shared. Safe publication approaches discussed in CON14TSM01-J. Do not let the " this " reference escape during object construction can be expressed succinctly expressed with the @Unique("return") annotation.
For example, in the following code shown below, the @Unique("return") annotation documents that the object returned from the constructor is a unique reference.:
| Code Block | ||
|---|---|---|
| ||
@RegionLock("Lock is this protects Instance") public final class Example { private int x = 1; private int y; @Unique("return") public Example(int y) { this.y = y; } // ... } |
Documenting
...
Thread-
...
Confinement Policies
Dean Sutherland and William Scherlis propose annotations that can document thread-confinement policies. Their approach allows verification of the annotations against as-written code [Sutherland 2010]Wiki Markup
For example, to the following annotations express the design intent that a program has, at most, one Abstract Window Toolkit (AWT) event dispatch thread , and several Compute compute threads, and that the Compute compute threads are forbidden to handle AWT data structures or events, use the following annotations:
| Code Block | ||
|---|---|---|
| ||
@ColorDeclare@ThreadRole AWT, Compute @IncompatibleColors@IncompatibleThreadRoles AWT, Compute @MaxColorCount@MaxRoleCount AWT 1 |
Documenting
...
Wait-
...
Notify Protocols
According to Goetz and colleagues [Goetz 2006],
A state-dependent
...
class
...
should
...
either
...
fully
...
expose
...
(and
...
document)
...
its
...
waiting
...
and
...
notification
...
protocols
...
to
...
subclasses,
...
or
...
prevent
...
subclasses
...
from
...
participating
...
in
...
them
...
at
...
all.
...
(This
...
is
...
an
...
extension
...
of
...
"design
...
and
...
document
...
for
...
inheritance,
...
or
...
else
...
prohibit
...
it"
...
[EJ
...
Item
...
15
...
].)
...
At
...
the
...
very
...
least,
...
designing
...
a
...
state-dependent
...
class
...
for
...
inheritance
...
requires
...
exposing
...
the
...
condition
...
queues
...
and
...
locks
...
and
...
documenting
...
the
...
condition
...
predicates
...
and
...
synchronization
...
policy;
...
it
...
may
...
also
...
require
...
exposing
...
the
...
underlying
...
state
...
variables.
...
(The
...
worst
...
thing
...
a
...
state-dependent
...
class
...
can
...
do
...
is
...
expose
...
its
...
state
...
to
...
subclasses
...
but
...
not
...
document
...
its
...
protocols
...
for
...
waiting
...
and
...
notification;
...
this
...
is
...
like
...
a
...
class
...
exposing
...
its
...
state
...
variables
...
but
...
not
...
documenting
...
its
...
invariants.)
...
(p. 395)
Wait-notify protocols should be documented adequately documented. Currently, we are not aware of any annotations for this purpose.
Applicability
Annotating concurrent code helps document the design intent and can be used to automate the detection and prevention of race conditions and data races.
Automated Detection
Tool | Version | Checker | Description |
|---|---|---|---|
| The Checker Framework | 2.1.3 | GUI Effect Checker | Ensure that non-GUI threads do not access the UI which would crash the application (see Chapter 14) |
Bibliography
Item 70, "Document Thread Safety" | |
Java Concurrency in Practice | |
...