com.surelogic

Annotation Type NotThreadSafe

@Documented
@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface NotThreadSafe

The type to which this annotation is applied is not thread-safe. This annotation primarily exists for clarifying the non-thread-safety of a class that might otherwise be assumed to be thread-safe, despite the fact that it is a bad idea to assume a class is thread-safe without good reason.

This annotation is not verified, it is intended for documentation of programmer intent only.

A type may not be annotated with both @ThreadSafe and @NotThreadSafe.

Relationship with @Immutable

Thread safety and immutability are two points along the same axis. This set of annotations can actually describe three points along the axis:

@Mutable and @NotThreadSafe

This is the same as being unannotated, or just @Mutable , or just @NotThreadSafe. The type contains mutable state that is not safe to access concurrently from multiple threads.

@Mutable and @ThreadSafe

This is the same as @ThreadSafe. The type contains mutable state that is safe to access concurrently from multiple threads.

@Immutable and @ThreadSafe

This is the same as @Immutable. The type contains no mutable state, and is thus safe to access concurrently from multiple threads.

The combination @Immutable and @NotThreadSafe is a modeling error because an immutable type is obviously thread safe.

Semantics:

Documenting that a type is not thread-safe does not constrain the implementation of the program, it simply clarifies the programmer's intent.

Examples:

Most of the collection implementations provided in java.util are not thread-safe. This could be documented for java.util.ArrayList, for example, as shown below.

 package java.util;
 
 @NotThreadSafe
 public class ArrayList extends ... {
   ...
 }
 

Javadoc usage notes:

This annotation may placed in Javadoc, which can be useful for Java 1.4 code which does not include language support for annotations, via the @annotate tag.

 /**
  * @annotate NotThreadSafe
  */
 public class ArrayList extends ... {
   ...
 }
 

Implementation note: This annotation is derived from @NotThreadSafe proposed by Brian Goetz and Tim Peierls in the book Java Concurrency in Practice (Addison-Wesley 2006) we have simply adapted it to have semantics as a promise. Further, the annotation in net.jcip.annotations may be used instead of this one with the same tool behavior.

See Also:

ThreadSafe