com.surelogic

Annotation Type RequiresLock

@Documented
@Retention(value=RUNTIME)
@Target(value={METHOD,CONSTRUCTOR})
public @interface RequiresLock

Declares that the method or constructor to which this annotation applies assumes that the caller holds the named locks. Analysis of the method/constructor proceeds as if the named locks were held; call sites of the method are scrutinized to determine if the precondition is satisfied.

The list of locks is allowed to be empty, in which case it means that the method/constructor does not require any locks to be held by the caller.

Methods that override a method with a @RequiresLock annotation may remove locks from the set of required locks, but may not add any locks to the set. That is, the set of required locks is contravariant.

Semantics:

Each thread that invokes an annotated method or constructor must hold the lock on each object denoted by the lockSpecifications in the annotation.

Examples:

A locking policy, named StateLock, that indicates that synchronizing on the field stateLock (which must be declared to be final) protects the two long fields use to represent the position of the object. The RequiresLock annotation is used specify that StateLock must be held when invoking the setX or setY methods.

 @Region("private AircraftState")
 @RegionLock("StateLock is stateLock protects AircraftState")
 public class Aircraft {
   private final Object stateLock = new Object();
 
   @InRegion("AircraftState")
   private long x, y;
 
   public void setPosition(long x, long y) {
     synchronized(stateLock)
       setX(x);
       setY(y);
     }
   }
 
   @RequiresLock("StateLock")
   private void setX(long value) {
     x = value;
   }
 
   @RequiresLock("StateLock")
   private void setY(long value) {
     y = value;
   }
 }
 

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 Region("private AircraftState")
  * @annotate RegionLock("StateLock is stateLock protects AircraftState")
  */
 public class Aircraft {
   private final Object stateLock = new Object();
 
   /**
    * @annotate InRegion("AircraftState")
    */
   private long x, y;
 
   public void setPosition(long x, long y) {
     synchronized(stateLock)
       setX(x);
       setY(y);
     }
   }
 
   /**
    * @annotate RequiresLock("StateLock")
    */
   private void setX(long value) {
     x = value;
   }
 
   /**
    * @annotate RequiresLock("StateLock")
    */
   private void setY(long value) {
     y = value;
   }
 }
 

See Also:

RegionLock

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
String	value A comma-separated list of zero or more lock names.

Element Detail

value

public abstract String value

A comma-separated list of zero or more lock names. The value of this attribute must conform to the following grammar (in Augmented Backus–Naur Form):

 value = lockSpecification *("," lockSpecification)
 
 lockSpecification = qualifiedLockSpecification / simpleLockSpecification
 
 simpleLockSpecification = simpleLockName ["." ("readLock" / "writeLock")]
 
 qualifiedLockSpecification = qualifiedLockName ["." ("readLock" / "writeLock")]
 
 simpleLockName = IDENTIFIER  ; Lock from the receiver (same as "this:IDENTIFIER")
 
 qualifiedLockName = parameterLockName / typeQualifiedLockName / innerClassLockName
 
 parameterLockName = simpleExpression ":" IDENTIFIER  ; Lock from a method/constructor parameter
 
 simpleExpression = "this" / IDENTIFER  ; Receiver or parameter name
 
 typeQualifiedLockName = typeExpression ":" IDENTIFIER  ; Static lock qualified by a class name
 
 typeExpression = IDENTIFIER *("." IDENTIFIER)
 
 innerClassLockName = namedType "." "this" ":" IDENTIFIER ; Lock from an enclosing instance
 
 namedType = IDENTIFIER *("." IDENTIFIER)
 
 IDENTIFIER = Legal Java Identifier