Package org.checkerframework.dataflow.util

Class PurityUtils

java.lang.Object

org.checkerframework.dataflow.util.PurityUtils

public final class PurityUtils
extends Object

A utility class for working with the SideEffectFree, Deterministic, and Pure annotations.

See Also:

• SideEffectFree
• Deterministic
• Pure

Method Summary

Modifier and Type	Method	Description
static void	addDeterminismOfVoidCall(EnumSet<PurityKind> kinds, TypeMirror returnType)	Adds PurityKind.DETERMINISTIC to kinds if kinds contains PurityKind.SIDE_EFFECT_FREE and returnType is void; see sideEffectFreeImpliesDeterministic(javax.lang.model.type.TypeMirror).
static EnumSet<PurityKind>	getPurityKinds(AnnotationProvider provider, MethodTree methodTree)	Returns the purity annotations on the method methodTree.
static EnumSet<PurityKind>	getPurityKinds(AnnotationProvider provider, ExecutableElement methodElement)	Returns the purity annotations on the method methodElement.
static boolean	hasPurityAnnotation(AnnotationProvider provider, MethodTree methodTree)	Does the method methodTree have any purity annotation?
static boolean	hasPurityAnnotation(AnnotationProvider provider, ExecutableElement methodElement)	Does the method methodElement have any purity annotation?
static boolean	isDeterministic(AnnotationProvider provider, MethodTree methodTree)	Is the method methodTree deterministic?
static boolean	isDeterministic(AnnotationProvider provider, ExecutableElement methodElement)	Is the method methodElement deterministic?
static boolean	isPure(AnnotationProvider provider, JavaExpression expression)	Returns true if the given expression is pure: evaluating it has no side effect, and, in an unchanged environment, every evaluation yields the same location or value.
static boolean	isSideEffectFree(AnnotationProvider provider, ExecutableElement methodElement)	Is the method methodElement side-effect-free?
static boolean	sideEffectFreeImpliesDeterministic(TypeMirror returnType)	Returns true if a side-effect-free call that returns returnType is also deterministic.

Methods inherited from class java.lang.Object

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

Method Details

hasPurityAnnotation

public static boolean hasPurityAnnotation(AnnotationProvider provider,
 MethodTree methodTree)

Does the method methodTree have any purity annotation?

Parameters:

provider - how to get annotations

methodTree - a method to test

Returns:

true if the method has any purity annotations

hasPurityAnnotation

public static boolean hasPurityAnnotation(AnnotationProvider provider,
 ExecutableElement methodElement)

Does the method methodElement have any purity annotation?

Parameters:

provider - how to get annotations

methodElement - a method to test

Returns:

true if the method has any purity annotations

isDeterministic

public static boolean isDeterministic(AnnotationProvider provider,
 MethodTree methodTree)

Is the method methodTree deterministic?

Parameters:

provider - how to get annotations

methodTree - a method to test

Returns:

true if the method is deterministic

isDeterministic

public static boolean isDeterministic(AnnotationProvider provider,
 ExecutableElement methodElement)

Is the method methodElement deterministic?

Parameters:

provider - how to get annotations

methodElement - a method to test

Returns:

true if the method is deterministic

isSideEffectFree

public static boolean isSideEffectFree(AnnotationProvider provider,
 ExecutableElement methodElement)

Is the method methodElement side-effect-free?

This method does not use, and has different semantics than, AnnotationProvider.isSideEffectFree(javax.lang.model.element.ExecutableElement). This method is concerned only with standard purity annotations.

Parameters:

provider - how to get annotations

methodElement - a method to test

Returns:

true if the method is side-effect-free

getPurityKinds

public static EnumSet<PurityKind> getPurityKinds(AnnotationProvider provider,
 MethodTree methodTree)

Returns the purity annotations on the method methodTree.

Parameters:

provider - how to get annotations. Its AnnotationProvider.isSideEffectFree(javax.lang.model.element.ExecutableElement) and AnnotationProvider.isDeterministic(javax.lang.model.element.ExecutableElement) methods are not used.

methodTree - a method to test

Returns:

the types of purity of the method methodTree; a new set, which the caller may modify

getPurityKinds

public static EnumSet<PurityKind> getPurityKinds(AnnotationProvider provider,
 ExecutableElement methodElement)

Returns the purity annotations on the method methodElement. @Pure is treated as an alias for @SideEffectFree and @Deterministic.

Parameters:

provider - how to get annotations. Its AnnotationProvider.isSideEffectFree(javax.lang.model.element.ExecutableElement) and AnnotationProvider.isDeterministic(javax.lang.model.element.ExecutableElement) methods are not used.

methodElement - a method to test

Returns:

the types of purity of the method methodElement; a new set, which the caller may modify

sideEffectFreeImpliesDeterministic

public static boolean sideEffectFreeImpliesDeterministic(TypeMirror returnType)

Returns true if a side-effect-free call that returns returnType is also deterministic. That holds when returnType is void: two calls of a side-effect-free method that returns no value return the same (absent) value.

Parameters:

returnType - the type of the value that a call returns

Returns:

true if a side-effect-free call that returns returnType is deterministic

addDeterminismOfVoidCall

public static void addDeterminismOfVoidCall(EnumSet<PurityKind> kinds,
 TypeMirror returnType)

Adds PurityKind.DETERMINISTIC to kinds if kinds contains PurityKind.SIDE_EFFECT_FREE and returnType is void; see sideEffectFreeImpliesDeterministic(javax.lang.model.type.TypeMirror).

getPurityKinds(org.checkerframework.javacutil.AnnotationProvider, com.sun.source.tree.MethodTree) and isDeterministic(org.checkerframework.javacutil.AnnotationProvider, com.sun.source.tree.MethodTree) do not apply this rule, for two reasons. First, a constructor's return type is void, but a new expression is not deterministic. Second, a caller may combine purity from several sources, such as the command-line assumptions, and this rule must be applied after all of them.

Parameters:

kinds - the purity of a call; modified by this method

returnType - the type of the value that the call returns

isPure

public static boolean isPure(AnnotationProvider provider,
 JavaExpression expression)

Returns true if the given expression is pure: evaluating it has no side effect, and, in an unchanged environment, every evaluation yields the same location or value.

In one way, this method is more conservative than isDeterministic: it returns false for an expression such as a + b, which is pure but denotes no location that a method could modify.

Parameters:

provider - how to get annotations

expression - an expression

Returns:

true if the given expression is pure