checker.src.org.checkerframework.checker.lock.qual.GuardSatisfied Maven / Gradle / Ivy
Show all versions of checker Show documentation
package org.checkerframework.checker.lock.qual;
import java.lang.annotation.*;
import org.checkerframework.framework.qual.SubtypeOf;
import org.checkerframework.framework.qual.TargetLocations;
import org.checkerframework.framework.qual.TypeUseLocation;
/**
* If a variable {@code x} has type {@code @GuardSatisfied}, then all
* lock expressions for {@code x}'s value are held.
*
*
* Written on a formal parameter (including the receiver), this annotation
* indicates that the {@literal @}{@link GuardedBy} type for
* the corresponding actual argument at the method call site
* is unknown at the method definition site, but any lock expressions
* that guard it are known to be held prior to the method call.
*
*
* For example, the formal parameter of the String copy constructor,
* {@link String#String(String s)}, is annotated with {@code @GuardSatisfied}.
* This requires that all locks guarding the actual argument are held when
* the constructor is called. However, the definition of the constructor
* does not need to know what those locks are (and it cannot know, because
* the constructor can be called by arbitrary code).
*
*
* @see GuardedBy
* @see Holding
* @checker_framework.manual #lock-checker Lock Checker
* @checker_framework.manual #lock-checker-polymorphism-example Lock Checker polymorphism example
*/
@SubtypeOf(GuardedByUnknown.class) // TODO: Should @GuardSatisfied be in its own hierarchy?
@Documented
@Retention(RetentionPolicy.RUNTIME)
@TargetLocations({ TypeUseLocation.RECEIVER, TypeUseLocation.PARAMETER, TypeUseLocation.RETURN })
@Target(ElementType.TYPE_USE)
public @interface GuardSatisfied {
/**
* The index on the GuardSatisfied polymorphic qualifier.
* Defaults to -1 so that the user can write any index starting from 0.
*/
int value() default -1;
}