ThreadSafe 1.3.3 released

24.July.2014

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

Download a free trial

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