org.checkerframework.checker.lock

Class LockVisitor

java.lang.Object

com.sun.source.util.TreeScanner<R,P>

com.sun.source.util.TreePathScanner<R,P>

org.checkerframework.framework.source.SourceVisitor<Void,Void>

org.checkerframework.common.basetype.BaseTypeVisitor<LockAnnotatedTypeFactory>

org.checkerframework.checker.lock.LockVisitor

All Implemented Interfaces:

TreeVisitor<Void,Void>

public class LockVisitor
extends BaseTypeVisitor<LockAnnotatedTypeFactory>

The LockVisitor enforces the special type-checking rules described in the Lock Checker manual chapter.

See the Checker Framework Manual:

Lock Checker

Nested Class Summary

Nested classes/interfaces inherited from class org.checkerframework.common.basetype.BaseTypeVisitor

BaseTypeVisitor.OverrideChecker

Field Summary

Fields

Modifier and Type	Field and Description
protected static Pattern	SELF_RECEIVER_PATTERN A pattern for spotting self receiver

Fields inherited from class org.checkerframework.common.basetype.BaseTypeVisitor

atypeFactory, checker, DETERMINISTIC, inferPurity, methodTree, positions, PURE, SIDE_EFFECT_FREE, TARGET, targetValueElement, typeValidator, unusedWhenElement

Fields inherited from class org.checkerframework.framework.source.SourceVisitor

elements, root, trees, treesWithSuppressWarnings, types

Constructor Summary

Constructors

Constructor and Description
LockVisitor(BaseTypeChecker checker) Constructs a LockVisitor.

Method Summary

Modifier and Type	Method and Description
protected void	checkConstructorResult(AnnotatedTypeMirror.AnnotatedExecutableType constructorType, ExecutableElement constructorElement) Issue a warning if the result type of the constructor is not top.
protected boolean	checkOverride(MethodTree overriderTree, AnnotatedTypeMirror.AnnotatedDeclaredType enclosingType, AnnotatedTypeMirror.AnnotatedExecutableType overriddenMethodType, AnnotatedTypeMirror.AnnotatedDeclaredType overriddenType) Ensures that subclass methods are annotated with a stronger or equally strong side effect annotation than the parent class method.
protected void	commonAssignmentCheck(AnnotatedTypeMirror varType, AnnotatedTypeMirror valueType, Tree valueTree, @CompilerMessageKey String errorKey, Object... extraArgs) Checks the validity of an assignment (or pseudo-assignment) from a value to a variable and emits an error message (through the compiler's messaging interface) if it is not valid.
LockAnnotatedTypeFactory	createTypeFactory() Constructs an instance of the appropriate type factory for the implemented type system.
protected Set<? extends AnnotationMirror>	getExceptionParameterLowerBoundAnnotations() Returns a set of AnnotationMirrors that is a lower bound for exception parameters.
boolean	isValidUse(AnnotatedTypeMirror.AnnotatedDeclaredType declarationType, AnnotatedTypeMirror.AnnotatedDeclaredType useType, Tree tree) Skips the call to super and returns true.
protected boolean	skipReceiverSubtypeCheck(MethodInvocationTree methodInvocationTree, AnnotatedTypeMirror methodDefinitionReceiver, AnnotatedTypeMirror methodCallReceiver) When visiting a method call, if the receiver formal parameter has type @GuardSatisfied and the receiver actual parameter has type @GuardedBy(...), this method verifies that the guard is satisfied, and it returns true, indicating that the receiver subtype check should be skipped.
Void	visitAnnotation(AnnotationTree tree, Void p) Ensure that the annotation arguments comply to their declarations.
Void	visitArrayAccess(ArrayAccessTree tree, Void p)
Void	visitBinary(BinaryTree binaryTree, Void p)
Void	visitCompoundAssignment(CompoundAssignmentTree node, Void p) Performs assignability check.
Void	visitIdentifier(IdentifierTree tree, Void p)
Void	visitMemberSelect(MemberSelectTree tree, Void p)
Void	visitMethod(MethodTree node, Void p) Issues an error if a method (explicitly or implicitly) annotated with @MayReleaseLocks has a formal parameter or receiver (explicitly or implicitly) annotated with @GuardSatisfied.
Void	visitMethodInvocation(MethodInvocationTree node, Void p) When visiting a method invocation, issue an error if the side effect annotation on the called method causes the side effect guarantee of the enclosing method to be violated.
Void	visitSynchronized(SynchronizedTree node, Void p) When visiting a synchronized block, issue an error if the expression has a type that implements the java.util.concurrent.locks.Lock interface.
Void	visitVariable(VariableTree node, Void p)

Methods inherited from class org.checkerframework.common.basetype.BaseTypeVisitor

checkAccess, checkAccessAllowed, checkArguments, checkArrayInitialization, checkConditionalPostcondition, checkConstructorInvocation, checkContract, checkDefaultConstructor, checkExceptionParameter, checkExplicitAnnotationsOnIntersectionBounds, checkExtendsImplements, checkFieldInvariantDeclarations, checkForPolymorphicQualifiers, checkForPolymorphicQualifiers, checkMethodInvocability, checkMethodReferenceAsOverride, checkOverride, checkPostcondition, checkPreconditions, checkPurity, checkQualifierParameter, checkSuperConstructorCall, checkThisConstructorCall, checkThisOrSuperConstructorCall, checkThrownExpression, checkTypeArguments, checkTypecastRedundancy, checkTypecastSafety, checkVarargs, commonAssignmentCheck, commonAssignmentCheck, commonAssignmentCheckEndDiagnostic, commonAssignmentCheckEndDiagnostic, commonAssignmentCheckStartDiagnostic, createOverrideChecker, createTypeFactoryPublic, createTypeValidator, enclosingMemberSelect, enclosingStatement, getThrowUpperBoundAnnotations, getTypeFactory, isTypeCastSafe, isValidUse, isValidUse, processClassTree, reportMethodInvocabilityError, reportPurityErrors, scan, setRoot, shouldSkipUses, testAnnotationInsertion, testJointJavacJavaParserVisitor, testTypevarContainment, typeCheckVectorCopyIntoArgument, validateType, validateTypeOf, visitAnnotatedType, visitAnnotatedType, visitAssignment, visitCatch, visitClass, visitCompilationUnit, visitConditionalExpression, visitEnhancedForLoop, visitInstanceOf, visitLambdaExpression, visitMemberReference, visitNewArray, visitNewClass, visitReturn, visitThrow, visitTypeCast, visitTypeParameter, visitUnary, warnAboutIrrelevantJavaTypes

Methods inherited from class org.checkerframework.framework.source.SourceVisitor

visit

Methods inherited from class com.sun.source.util.TreePathScanner

getCurrentPath, scan

Methods inherited from class com.sun.source.util.TreeScanner

reduce, scan, visitArrayType, visitAssert, visitBlock, visitBreak, visitCase, visitContinue, visitDoWhileLoop, visitEmptyStatement, visitErroneous, visitExports, visitExpressionStatement, visitForLoop, visitIf, visitImport, visitIntersectionType, visitLabeledStatement, visitLiteral, visitModifiers, visitModule, visitOpens, visitOther, visitPackage, visitParameterizedType, visitParenthesized, visitPrimitiveType, visitProvides, visitRequires, visitSwitch, visitTry, visitUnionType, visitUses, visitWhileLoop, visitWildcard

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SELF_RECEIVER_PATTERN

protected static final Pattern SELF_RECEIVER_PATTERN

A pattern for spotting self receiver

Constructor Detail

LockVisitor

public LockVisitor(BaseTypeChecker checker)

Constructs a LockVisitor.

Parameters:

checker - the type checker to use.

Method Detail

visitVariable

public Void visitVariable(VariableTree node,
                          Void p)

Specified by:

visitVariable in interface TreeVisitor<Void,Void>

Overrides:

visitVariable in class BaseTypeVisitor<LockAnnotatedTypeFactory>

createTypeFactory

public LockAnnotatedTypeFactory createTypeFactory()

Description copied from class: BaseTypeVisitor

Constructs an instance of the appropriate type factory for the implemented type system.

The default implementation uses the checker naming convention to create the appropriate type factory. If no factory is found, it returns BaseAnnotatedTypeFactory. It reflectively invokes the constructor that accepts this checker and compilation unit tree (in that order) as arguments.

Subclasses have to override this method to create the appropriate visitor if they do not follow the checker naming convention.

Overrides:

createTypeFactory in class BaseTypeVisitor<LockAnnotatedTypeFactory>

Returns:

the appropriate type factory

visitMethod

public Void visitMethod(MethodTree node,
                        Void p)

Issues an error if a method (explicitly or implicitly) annotated with @MayReleaseLocks has a formal parameter or receiver (explicitly or implicitly) annotated with @GuardSatisfied. Also issues an error if a synchronized method has a @LockingFree, @SideEffectFree, or @Pure annotation.

Specified by:

visitMethod in interface TreeVisitor<Void,Void>

Overrides:

visitMethod in class BaseTypeVisitor<LockAnnotatedTypeFactory>

Parameters:

node - the MethodTree of the method definition to visit

skipReceiverSubtypeCheck

protected boolean skipReceiverSubtypeCheck(MethodInvocationTree methodInvocationTree,
                                           AnnotatedTypeMirror methodDefinitionReceiver,
                                           AnnotatedTypeMirror methodCallReceiver)

When visiting a method call, if the receiver formal parameter has type @GuardSatisfied and the receiver actual parameter has type @GuardedBy(...), this method verifies that the guard is satisfied, and it returns true, indicating that the receiver subtype check should be skipped. If the receiver actual parameter has type @GuardSatisfied, this method simply returns true without performing any other actions. The method returns false otherwise.

Overrides:

skipReceiverSubtypeCheck in class BaseTypeVisitor<LockAnnotatedTypeFactory>

Parameters:

methodInvocationTree - the MethodInvocationTree of the method being called

methodDefinitionReceiver - the ATM of the formal receiver parameter of the method being called

methodCallReceiver - the ATM of the receiver argument of the method call

Returns:

whether the caller can skip the receiver subtype check

getExceptionParameterLowerBoundAnnotations

protected Set<? extends AnnotationMirror> getExceptionParameterLowerBoundAnnotations()

Description copied from class: BaseTypeVisitor

Returns a set of AnnotationMirrors that is a lower bound for exception parameters.

This implementation returns top; subclasses can change this behavior.

Note: by default this method is called by BaseTypeVisitor.getThrowUpperBoundAnnotations(), so that this annotation is enforced.

Overrides:

getExceptionParameterLowerBoundAnnotations in class BaseTypeVisitor<LockAnnotatedTypeFactory>

Returns:

set of annotation mirrors, one per hierarchy, that form a lower bound of annotations that can be written on an exception parameter

checkConstructorResult

protected void checkConstructorResult(AnnotatedTypeMirror.AnnotatedExecutableType constructorType,
                                      ExecutableElement constructorElement)

Description copied from class: BaseTypeVisitor

Issue a warning if the result type of the constructor is not top. If it is a supertype of the class, then a conflicting.annos error will also be issued by BaseTypeVisitor.isValidUse(AnnotatedTypeMirror.AnnotatedDeclaredType,AnnotatedTypeMirror.AnnotatedDeclaredType,Tree).

Overrides:

checkConstructorResult in class BaseTypeVisitor<LockAnnotatedTypeFactory>

Parameters:

constructorType - AnnotatedExecutableType for the constructor

constructorElement - element that declares the constructor

commonAssignmentCheck

protected void commonAssignmentCheck(AnnotatedTypeMirror varType,
                                     AnnotatedTypeMirror valueType,
                                     Tree valueTree,
                                     @CompilerMessageKey String errorKey,
                                     Object... extraArgs)

Description copied from class: BaseTypeVisitor

Checks the validity of an assignment (or pseudo-assignment) from a value to a variable and emits an error message (through the compiler's messaging interface) if it is not valid.

Overrides:

commonAssignmentCheck in class BaseTypeVisitor<LockAnnotatedTypeFactory>

Parameters:

varType - the annotated type of the variable

valueType - the annotated type of the value

valueTree - the location to use when reporting the error message

errorKey - the error message key to use if the check fails

extraArgs - arguments to the error message key, before "found" and "expected" types

visitMemberSelect

public Void visitMemberSelect(MemberSelectTree tree,
                              Void p)

Specified by:

visitMemberSelect in interface TreeVisitor<Void,Void>

Overrides:

visitMemberSelect in class TreeScanner<Void,Void>

checkOverride

protected boolean checkOverride(MethodTree overriderTree,
                                AnnotatedTypeMirror.AnnotatedDeclaredType enclosingType,
                                AnnotatedTypeMirror.AnnotatedExecutableType overriddenMethodType,
                                AnnotatedTypeMirror.AnnotatedDeclaredType overriddenType)

Ensures that subclass methods are annotated with a stronger or equally strong side effect annotation than the parent class method.

Overrides:

checkOverride in class BaseTypeVisitor<LockAnnotatedTypeFactory>

Parameters:

overriderTree - declaration tree of overriding method

enclosingType - type of overriding class

overriddenMethodType - type of overridden method

overriddenType - type of overridden class

Returns:

true if the override is allowed

See Also:

BaseTypeVisitor.checkOverride(MethodTree, AnnotatedTypeMirror.AnnotatedExecutableType, AnnotatedTypeMirror.AnnotatedDeclaredType, AnnotatedTypeMirror.AnnotatedExecutableType, AnnotatedTypeMirror.AnnotatedDeclaredType)

visitArrayAccess

public Void visitArrayAccess(ArrayAccessTree tree,
                             Void p)

Specified by:

visitArrayAccess in interface TreeVisitor<Void,Void>

Overrides:

visitArrayAccess in class TreeScanner<Void,Void>

isValidUse

public boolean isValidUse(AnnotatedTypeMirror.AnnotatedDeclaredType declarationType,
                          AnnotatedTypeMirror.AnnotatedDeclaredType useType,
                          Tree tree)

Skips the call to super and returns true.

GuardedBy({}) is the default type on class declarations, which is a subtype of the top annotation @GuardedByUnknown. However, it is valid to declare an instance of a class with any annotation from the @GuardedBy hierarchy. Hence, this method returns true for annotations in the @GuardedBy hierarchy.

Also returns true for annotations in the @LockPossiblyHeld hierarchy since the default for that hierarchy is the top type and annotations from that hierarchy cannot be explicitly written in code.

Overrides:

isValidUse in class BaseTypeVisitor<LockAnnotatedTypeFactory>

Parameters:

declarationType - the type of the class (TypeElement)

useType - the use of the class (instance type)

tree - the tree where the type is used

Returns:

true if the useType is a valid use of elemType

visitMethodInvocation

public Void visitMethodInvocation(MethodInvocationTree node,
                                  Void p)

When visiting a method invocation, issue an error if the side effect annotation on the called method causes the side effect guarantee of the enclosing method to be violated. For example, a method annotated with @ReleasesNoLocks may not call a method annotated with @MayReleaseLocks. Also check that matching @GuardSatisfied(index) on a method's formal receiver/parameters matches those in corresponding locations on the method call site.

Specified by:

visitMethodInvocation in interface TreeVisitor<Void,Void>

Overrides:

visitMethodInvocation in class BaseTypeVisitor<LockAnnotatedTypeFactory>

Parameters:

node - the MethodInvocationTree of the method call being visited

visitSynchronized

public Void visitSynchronized(SynchronizedTree node,
                              Void p)

When visiting a synchronized block, issue an error if the expression has a type that implements the java.util.concurrent.locks.Lock interface. This prevents explicit locks from being accidentally used as built-in (monitor) locks. This is important because the Lock Checker does not have a mechanism to separately keep track of the explicit lock and the monitor lock of an expression that implements the Lock interface (i.e. there is a @LockHeld annotation used in dataflow, but there are not distinct @MonitorLockHeld and @ExplicitLockHeld annotations). It is assumed that both kinds of locks will never be held for any expression that implements Lock.

Additionally, a synchronized block may not be present in a method that has a @LockingFree guarantee or stronger. An error is issued in this case.

Specified by:

visitSynchronized in interface TreeVisitor<Void,Void>

Overrides:

visitSynchronized in class TreeScanner<Void,Void>

Parameters:

node - the SynchronizedTree for the synchronized block being visited

visitAnnotation

public Void visitAnnotation(AnnotationTree tree,
                            Void p)

Description copied from class: BaseTypeVisitor

Ensure that the annotation arguments comply to their declarations. This needs some special casing, as annotation arguments form special trees.

Specified by:

visitAnnotation in interface TreeVisitor<Void,Void>

Overrides:

visitAnnotation in class BaseTypeVisitor<LockAnnotatedTypeFactory>

visitIdentifier

public Void visitIdentifier(IdentifierTree tree,
                            Void p)

Specified by:

visitIdentifier in interface TreeVisitor<Void,Void>

Overrides:

visitIdentifier in class BaseTypeVisitor<LockAnnotatedTypeFactory>

visitBinary

public Void visitBinary(BinaryTree binaryTree,
                        Void p)

Specified by:

visitBinary in interface TreeVisitor<Void,Void>

Overrides:

visitBinary in class TreeScanner<Void,Void>

visitCompoundAssignment

public Void visitCompoundAssignment(CompoundAssignmentTree node,
                                    Void p)

Description copied from class: BaseTypeVisitor

Performs assignability check.

Specified by:

visitCompoundAssignment in interface TreeVisitor<Void,Void>

Overrides:

visitCompoundAssignment in class BaseTypeVisitor<LockAnnotatedTypeFactory>