| package org.checkerframework.framework.qual; |
| |
| import java.lang.annotation.Annotation; |
| 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; |
| |
| /** |
| * A meta-annotation that indicates that a qualifier indicates that an expression goes monotonically |
| * from a type qualifier {@code T} to another qualifier {@code S}. The annotation {@code S} is |
| * called the <em>target</em> of the monotonic qualifier, and has to be indicated by {@link |
| * MonotonicQualifier#value()}. |
| * |
| * <p>This meta-annotation can be used on the declaration of the monotonic qualifier used for the |
| * type-system at hand, and is often called {@code MonoT} if the target is {@code T}. The subtyping |
| * hierarchy has to be defined as follows: |
| * |
| * <pre>{@code |
| * T <: MonoT <: S |
| * }</pre> |
| * |
| * where {@code <:} indicates the subtyping relation. |
| * |
| * <p>An expression of a monotonic type can only be assigned expressions of the target type {@code |
| * T}. This means that an expression of the monotonic type {@code MonoT} cannot be assigned to a |
| * variable of the same type. |
| * |
| * <p>Reading an expression of a monotonic type {@code MonoT} might always yield an expression of |
| * type {@code S}. However, once it has been observed that a variable has the target type {@code T}, |
| * the monotonic property ensures that it will stay of type {@code T} for the rest of the program |
| * execution. This is even true if arbitrary other code is executed. |
| * |
| * <p>Note that variables of a monotonic type can be re-assigned arbitrarily often, but only with |
| * expressions of the target type. |
| */ |
| @Documented |
| @Retention(RetentionPolicy.RUNTIME) |
| @Target({ElementType.ANNOTATION_TYPE}) |
| public @interface MonotonicQualifier { |
| Class<? extends Annotation> value(); |
| } |