org.checkerframework.checker.lock.qual.GuardSatisfied Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of spring-cloud-contract-shade Show documentation

Spring Cloud Contract Shaded Dependencies

There is a newer version: 4.1.2

Show newest version

package org.checkerframework.checker.lock.qual;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
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;
}