ThreadSafe 1.3.3 released
24.July.2014ThreadSafe 1.3.3 is now available. This release provides support for the @GuardedBy annotation.
A free and fully functional trial of ThreadSafe Solo is available. This includes access to the Eclipse plugin and the Command Line Interface for two weeks. See About ThreadSafe below for a full list of licensing options.
What’s new in ThreadSafe 1.3.3?
ThreadSafe 1.3.3 adds support for the @GuardedBy annotation. This annotation is used on fields to indicate which locks should be held when that field is accessed. ThreadSafe checks that the specified lock is held when the annotated field is accessed, indicate the error if the lock is not held.
The code below shows an example of its use:
import javax.annotation.concurrent.GuardedBy;
class Counter {
private Object lock = new Object();
@GuardedBy("lock")
private int count;
public void increment() {
synchronized (lock) {
count++;
}
}
}
The count
field is annotated with @GuardedBy("lock")
to indicate that it should only be accessed while synchronized on the lock
field. If the count++;
statement is moved outside the synchronized
block, then ThreadSafe will report the violation of the @GuardedBy annotation.
If the field referenced by the @GuardedBy annotation is a java.util.concurrent
Lock, such as a ReentrantLock, then it is expected that the annotated field is guarded by calling the appropriate lock()
method on that Lock instead of by using synchronized blocks.
ThreadSafe 1.3.3 checks the use of @GuardedBy
annotations, and provides three new rules:
GuardedBy annotation violated
The GuardedBy annotation violated rule indicates that a field annotated with @GuardedBy
is accessed without the specified lock held. ThreadSafe reports the locations of the accesses without the lock held.
Guard is not final
The Guard is not final rule indicates that the @GuardedBy
annotation refers to a field which is not final. It is recommended that fields for lock objects are declared final, because typically they should not be reassigned.
Guard expression is not valid
The Guard expression is not valid rule indicates a problem with the @GuardedBy annotation parameter. The following problems are detected:
- Field not found.
- Field is not a valid guard because its type is primitive.
- Field is static and must not be qualified with ‘this’.
- Field is not static and must not be qualified with a class name.
- Class not found in this package.
- Instance field used to guard static field.
- Could not parse @GuardedBy annotation value.
- The @GuardedBy annotation does not have the expected type.
How do I use the @GuardedBy annotation?
The @GuardedBy annotation must be available on the compilation classpath before it can be used. A quick guide to setting up the classpath and using it is provided below.
Full documentation on the above rules can be found in the rule documentation included with ThreadSafe, and further information on how to use the @GuardedBy annotation can be found in the Tasks section of the Eclipse plug-in documentation.
Include @GuardedBy
in your project
In order to use the @GuardedBy
annotation in your code, you must first add a jar containing the annotation to the compilation classpath of your project. There are two definitions of the @GuardedBy
annotation in common use.
- The newer, recommended, definition is in the
javax.annotation.concurrent
package, as defined by JSR305. The Maven Central Repository provides an example of how to add the jar as a project dependency for some popular build systems. See the ‘Dependency Information’ section of the ‘Artifact Details’ page. The jar can also be downloaded from the same page. - The older definition is in the package
net.jcip.annotations
, named after the book Java Concurrency in Practice (JCIP). The dependency information and download link can be found on the JCIP Annotations ‘Artifact Details’ page.
The two definitions are defined in different packages, but are otherwise equivalent. ThreadSafe supports both.
Add @GuardedBy annotations to fields as necessary
The @GuardedBy annotation value is a String that identifies the lock that should be held when the annotated field is accessed. Guards can be specified using strings in the following formats:
- this
- fieldName
- this.fieldName
- ClassName.fieldName
- ClassName.class
For example, if a field is annotated with @GuardedBy("this")
, then the field must only be accessed in synchronized methods or in synchronized (this) { ... }
blocks.
About ThreadSafe
ThreadSafe is a static analysis tool for finding concurrency bugs and potential performance issues in Java programs.
ThreadSafe is available in three different packages:
- ThreadSafe for Eclipse, providing IDE integration;
- ThreadSafe for SonarQube, for use with the SonarQube quality management platform; and
- ThreadSafe Command Line Interface, a standalone application for generating HTML reports.
ThreadSafe is available via different licensing options: ThreadSafe Solo, ThreadSafe for SonarQube and ThreadSafe Enterprise. Free trials are available for ThreadSafe Solo.
ThreadSafe Solo licenses can be used with ThreadSafe for Eclipse and the ThreadSafe Command Line Interface, which are available as separate downloads.
A ThreadSafe Enterprise package includes multiple licenses for ThreadSafe for Eclipse and the ThreadSafe Command Line Interface, plus ThreadSafe for SonarQube to allow your team to see and track issues reported by ThreadSafe. It also includes enhanced, priority support.