The Java language annotation facility is useful for documenting design intent. Source code annotation is a mechanism for associating metadata with a program element and making it available to the compiler, analyzers, debuggers, or Java Virtual Machine (JVM) for examination. Several annotations are available for documenting thread-safety or the lack thereof.
Obtaining Concurrency Annotations
Two sets of concurrency annotations are freely available and licensed for use in any code. The first set consists of four annotations described in Java Concurrency in Practice (JCIP) [Goetz 2006], which can be downloaded from jcip.net (jar, javadoc, source). The JCIP annotations are released under the Creative Commons Attribution License.
The second, larger set of concurrency annotations is available from and supported by SureLogic. These annotations are released under the Apache Software License, Version 2.0 and can be downloaded via the Internet Archive at surelogic.com (jar, javadoc, source). The annotations can be verified by the SureLogic JSure tool, and they remain useful for documenting code even when the tool is unavailable. These annotations include the JCIP annotations because they are supported by the JSure tool. (JSure also supports use of the JCIP JAR file.)
To use the annotations, download and add one or both of the aforementioned JAR files to the code's build path. The use of these annotations to document thread-safety is descr
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.
@ThreadSafe annotation is applied to a class to indicate that it is . This means that no sequences of accesses (reads and writes to public fields, calls to public methods) 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 specifies that it is thread-safe as part of its locking policy documentation. This class protects the
y fields using a reentrant lock.
Even when one or more
@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.
@Immutable annotation is applied to classes. Immutable objects are inherently thread-safe; once they are fully constructed, they may be published via a reference and shared safely among multiple threads.
The following example shows an immutable
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 by
@NotThreadSafe annotation is applied to classes that are not thread-safe. Many classes fail to document whether they are safe for multithreaded use. 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 could document this as follows:
Documenting Locking Policies
It is important to document all the locks that are being used to protect shared state. According to Brian Goetz and colleagues [Goetz 2006],
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)
JCIP provides the
@GuardedBy annotation for this purpose, and SureLogic provides the
@RegionLock annotation. The field or method to which the
@GuardedBy annotation is applied can be accessed only when holding a particular lock. It may be an intrinsic lock or a dynamic lock such as
For example, the following
MovablePoint class implements a movable point that can remember its past locations using the
memo array list:
@GuardedBy annotations on the
yPos fields indicate that access to these fields is protected by holding a lock on
move() method also synchronizes on
this, which modifies these fields. The
@GuardedBy annotation on the
memo list indicates that a lock on the
ArrayList object protects its contents. The
rememberPoint() method also synchronizes on the
One issue with the
@GuardedBy annotation is that it fails to indicate when there is a relationship between the fields of a class. This limitation can be overcome by using the SureLogic
@RegionLock annotation, 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 be accessed only when the lock is held. For example, the
SimpleLock locking policy indicates that synchronizing on the instance protects all of its state:
@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. That name makes it clear that the state and locking policy belong together, as demonstrated in the following example:
In this example, a locking policy named
StateLock is used to indicate that locking on
stateLock protects the named
AircraftPosition region, 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 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 TSM01-J. Do not let the this reference escape during object construction can be expressed succinctly with the
For example, in the following code, the
@Unique("return") annotation documents that the object returned from the constructor is a unique reference:
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].
For example, the following annotations express the design intent that a program has, at most, one Abstract Window Toolkit (AWT) event dispatch thread and several compute threads, and that the compute threads are forbidden to handle AWT data structures or events:
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. Currently, we are not aware of any annotations for this purpose.
Annotating concurrent code helps document the design intent and can be used to automate the detection and prevention of race conditions and data races.
|The Checker Framework|
|GUI Effect Checker||Ensure that non-GUI threads do not access the UI which would crash the application (see Chapter 14)|
Item 70, "Document Thread Safety"
Java Concurrency in Practice