com.surelogic
Annotation Type ThreadSafe

@Documented
@Target(value=TYPE)
public @interface ThreadSafe

The class to which this annotation is applied is thread-safe. This means that no sequences of accesses (reads and writes to public fields, calls to public methods) may put the object into an invalid state, regardless of the interleaving of those actions by the runtime, and without requiring any additional synchronization or coordination on the part of the caller. Even if one or more RegionLock models has been developed to document the locking policy of a class this annotation can help to clarify that the overall class is thread-safe.

This annotation does not imply anything about how the class is implemented. Of course, it also does not imply that a sequence of calls to methods of this class are atomic. It is a the responsibility of the caller to insure that such call sequences execute atomically

This annotation is trusted, i.e., it is not verified by analysis. Its use is for documentation and to quiet warnings that would otherwise be raised when accessing an object through a field protected by a lock.

Implementation note: This annotation is derived from @ThreadSafe 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. One difference between the two annotations is that the one in net.jcip.annotations has retention policy of RetentionPolicy.RUNTIME while the one in com.surelogic defaults to RetentionPolicy.CLASS.

Examples:

The Aircraft class declares that it is thread-safe as part of its lock policy documentation.

 @ThreadSafe
 @Region("private AircraftState")
 @RegionLock("StateLock is stateLock protects AircraftState")
 public 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();
     }
   }
   ...
 }
 

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 ThreadSafe
  * @annotate Region("private AircraftState")
  * @annotate RegionLock("StateLock is stateLock protects AircraftState")
  */
 public class Aircraft {
   ...
 }
 

See Also:

Immutable, NotThreadSafe, RegionLock