com.surelogic
Annotation Type Borrowed

@Documented
@Target(value={CONSTRUCTOR,METHOD,PARAMETER})
public @interface Borrowed

Declares that the parameter or receiver to which this annotation is applied does not receive any new aliases during execution of the method or constructor. That is, Unique values can be safely passed to the parameter or used as the receiver with the guarantee that they will still be unique when the method returns.

Annotating @Borrowed("this") on a constructor is defined to be equivalent to annotating @Unique("return"). Either of these annotations indicates that the object being constructed is not aliased during construction, which implies that the reference "returned" by the new expression that invokes the constructor is unique. Which annotation is preferred, @Borrowed("this") or @Unique("return"), is a matter of programmer preference.

It is a modeling error to use this annotation on a parameter whose type is primitive, e.g., public void setValue(@Borrowed int value) would generate a modeling error. It is a modeling error to annotate @Borrowed("this") on a static method, e.g., @Borrowed("this") public static void process() would generate a modeling error.

Examples:

In the below example, the first parameter to the static method run promises that it will not hold onto an alias to the passed Cart object. The two methods go and log promise that they will not hold onto an alias to the receiver. The combination of these three promises allows the model to be verified.

 public class Cart {
 
   static void run(@Borrowed Cart cart) {
     cart.go(10);
     cart.log("started moving");
     cart.go(20);
     cart.log("moved again");
   }
 
   int x, y;
   final List<String> log = new ArrayList<String>();
 
   @Borrowed("this")
   void go(int value) {
     x += value;
     y += value;
   }
 
   @Borrowed("this")
   void log(String msg) {
     log.add(msg);
   }
   ...
 }
 

This annotation is often used to support a RegionLock assertion on a constructor because if the receiver is not leaked during object construction then the state under construction will remain within the thread that invoked new.

 @RegionLock("Lock is this protects Instance")
 public class Example {
 
   int x = 1;
   int y;
 
   @Borrowed("this")
   public Example(int y) {
     this.y = y;
   }
   ...
 }
 

The scoped promise Promise can be used if the constructor is implicit (i.e., generated by the compiler). It has the ability to place promises on implicit and explicit constructors.

 @RegionLock("Lock is this protects Instance")
 @Promise("@Borrowed(this) for new(**)")
 public class Example {
   int x = 1;
   int y = 1;
   ...
 }
 

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. One complication is that the parameter being annotated must be explicitly specified because the annotation can no longer appear in the context of the parameter declaration.

 /**
  * @annotate Borrowed("a, b, c")
  */
 public void m1(Object a, Object b, Object c) { ... }
 

This annotation states that the three parameters are borrowed. Alternatively, you can use several annotations as shown below.

 /**
  * @annotate Borrowed("a")
  * @annotate Borrowed("b")
  * @annotate Borrowed("c")
  */
 public void m1(Object a, Object b, Object c) { ... }
 

See Also:

Unique

Optional Element Summary

String

value When annotating a constructor or a method, this attribute must be "this" to clarify the intent that it is the receiver that is borrowed.

value

public abstract String value

When annotating a constructor or a method, this attribute must be "this" to clarify the intent that it is the receiver that is borrowed. It is a modeling error if the attribute is not "this" in this case.

 class C {
   @Borrowed("this")
   public C() { ... }
 
   @Borrowed("this")
   void method() { ... }
   ...
 }
 

This attribute is not used when annotating a parameter; it is a modeling error for the value to be anything other than the default when annotating a parameter.

 int proc(@Borrowed int value       /* Illegal: Parameter has primitive type */, 
          @Borrowed Object settings /* Legal: Parameter has reference type */) { ... }
 

The value of this attribute must conform to the following grammar (in Augmented Backus–Naur Form):

 value = ["this"] ; See above comments
 

Default:

""