accrue.analysis.interprocvarcontext

## Class AnalysisUtilVarContext<A extends Ordered<A>,T extends AbstractValue<T>>

- java.lang.Object
- - accrue.analysis.interprocanalysis.AnalysisUtil<A>
  - - accrue.analysis.interprocvarcontext.AnalysisUtilVarContext<A,T>

- Type Parameters:
    `A` - Type of analysis results
    `T` - Value type for analysis items in the context
  Direct Known Subclasses:
    AnalysisUtilVarContextDataFlow

      public abstract class AnalysisUtilVarContext<A extends Ordered<A>,T extends AbstractValue<T>>
      extends AnalysisUtil<A>

  Abstract utility class for performing an interprocedural analysis with a variable context.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `trackErrors` Should we track java.lang.Error `ExitMap.key`s?

    - ### Fields inherited from class accrue.analysis.interprocanalysis.AnalysisUtil

      `extInfo, instanceInitializersChecked, workQueue`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AnalysisUtilVarContext(WorkQueue<A> workQueue, AnalysisUnit currentAnalysisUnit, AccrueExtensionInfo extInfo)` Create a new utility class

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `VarContext<T>` | `addLocations(VarContext<T> c, java.util.Set<AbstractLocation> locs, T absVal)` Add a set of locations at the given value.
    `java.lang.String` | `analysisName()`
    `abstract T` | `bottomAbstractValue()`
    `FinalVarContext<T>` | `call(polyglot.types.ConstructorInstance ci, VarContext<T> input, T receiverAbsVal, polyglot.ast.New n, DataFlowNodeIdentifier callSiteNode)` Process a call to `ci` created with `new` with `VarContext` `input`.
    `FinalVarContext<T>` | `call(polyglot.types.MethodInstance mi, VarContext<T> input, polyglot.ast.Call n, DataFlowNodeIdentifier callSiteNode)` Process a call to `mi` with `VarContext` `input`.
    `protected java.util.Set<ExitMap.Key>` | `computeExpectedExits(polyglot.ast.Term n)`
    `FinalVarContext<T>` | `constructorCall(polyglot.types.ConstructorInstance ci, VarContext<T> input, polyglot.ast.ConstructorCall n, DataFlowNodeIdentifier callSiteNode)` Process a call to `ci` with `VarContext` `input`.
    `FinalVarContext<T>` | `createFinalVarContext(VarContext<T> normalTermination)` Create a `FinalVarContext` context from the given `VarContext` for normal termination
    `VarContext<T>` | `createInitContext()` Create an initial variable context
    `FinalVarContext<T>` | `emptyFinalVarContext()`
    `protected FinalVarContext<T>` | `getAnalysisForMissingReceiver(polyglot.types.ProcedureInstance pi, VarContext<T> input, polyglot.ast.Term n, DataFlowNodeIdentifier callSiteNode)` Provide a hook for subclasses to implementation functionality when procedure pi is called (e.g., "e.m()") but there is an empty points to set for the receiver expression.
    `protected abstract FinalVarContext<T>` | `getAnalysisResultsFromWorkQueue(AnalysisUnit callee, VarContext<T> beforeCall)` Get the analysis results for the given callee and variable context.
    `T` | `getLocationAbsVal(VarContext<T> c, java.util.Set<AbstractLocation> locs)` Compute the abstract values for the given abstract locations
    `protected LibrarySignature<A,T>` | `getSignatureForMissingCode(polyglot.types.ProcedureInstance pi, T receiverAbsVal, java.util.List<T> argAbsVals)` Subclasses can override to provide signature for missing code.
    `protected FinalVarContext<T>` | `guessAnalysisForMissingCode(polyglot.types.ProcedureInstance pi, AnalysisContext calleeContext, HContext receiver, VarContext<T> input, T receiverAbsVal, java.util.List<T> argAbsVals, java.util.Set<ExitMap.Key> expectedExits, polyglot.ast.Node node)` Subclasses can override as a stop gap measure before they have signature.
    `protected abstract FinalVarContext<T>` | `guessAnalysisForMissingReceiver(polyglot.types.ProcedureInstance pi, VarContext<T> input, T receiverAbsVal, java.util.List<T> argAbsVals, java.util.Set<ExitMap.Key> expectedExits, DataFlowNodeIdentifier callSiteNode)` Subclasses should override as a stop gap measure if the receiver is missing, i.e., if the points to set of the receiver expression is empty.
    `protected FinalVarContext<T>` | `handleRecursiveCall(FinalVarContext<T> res, VarContext<T> beforeCall, AnalysisUnit callee)` The call to callee is potentially recursive.
    `protected VarContext<T>` | `preCallNonVirtual(polyglot.types.ProcedureInstance pi, AnalysisContext calleeContext, VarContext<T> input, polyglot.ast.Term n)` Allow extensions a chance to modify the input before the analysis of a non-virtual procedure call.
    `void` | `recordRead(AbstractLocation loc)` Record a location that has been read
    `void` | `recordReads(java.util.Collection<AbstractLocation> locs)`
    `void` | `recordWrite(AbstractLocation loc)` Record a location that has been written
    `void` | `recordWrites(java.util.Collection<AbstractLocation> locs)`
    `protected java.util.List<java.lang.String>` | `signatureAnalysisNames()`

    - ### Methods inherited from class accrue.analysis.interprocanalysis.AnalysisUtil

      `abstractLocations, abstractLocations, abstractLocations, abstractLocations, abstractLocations, abstractLocations, abstractLocations, abstractLocations, abstractLocations, abstractLocationsForArray, abstractLocationsForArray, abstractLocationsForArray, abstractLocationsImplicitTarget, analyze, analyzeInitializers, analyzeStaticInitializers, createExitMap, currentAnalysisUnit, currentClass, currentContext, extensionInfo, instanceInitializers, leq, maybeRecursiveCall, pointsTo, pointsTo, pointsTo, pointsTo, pointsTo, pointsTo, pointsTo, pointsTo, pointsTo, pointsToGraph, pointsToThis, process, recordMissingCode, typeSystem, upperBound, workQueue`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### trackErrors

          protected boolean trackErrors

      Should we track java.lang.Error `ExitMap.key`s?

  - ### Constructor Detail

    - #### AnalysisUtilVarContext

          public AnalysisUtilVarContext(WorkQueue<A> workQueue,
                                AnalysisUnit currentAnalysisUnit,
                                AccrueExtensionInfo extInfo)

      Create a new utility class
      Parameters:
        `workQueue` - Queue of analysis units
        `currentAnalysisUnit` - Current analysis unit from the queue
        `extInfo` - compiler analysis unit

  - ### Method Detail

    - #### call

          public FinalVarContext<T> call(polyglot.types.MethodInstance mi,
                                VarContext<T> input,
                                polyglot.ast.Call n,
                                DataFlowNodeIdentifier callSiteNode)
                                                           throws polyglot.types.SemanticException

      Process a call to `mi` with `VarContext` `input`.
      Parameters:
        `mi` - method to analyze
        `input` - variable context before analyzing the method
        `n` - the call to the method
        `callSite` - AST node (and context) for the call site
      Returns:
        new map of variables to their values after the analysis
      Throws:
        `polyglot.types.SemanticException` - if analysis fails

    - #### emptyFinalVarContext

          public FinalVarContext<T> emptyFinalVarContext()

      Returns:
        an empty variable context

    - #### createFinalVarContext

          public FinalVarContext<T> createFinalVarContext(VarContext<T> normalTermination)

      Create a `FinalVarContext` context from the given `VarContext` for normal termination
      Parameters:
        `normalTermination` - `VarContext` for normal termination
      Returns:
        `FinalVarContext` just containing the normal termination map

    - #### call

          public FinalVarContext<T> call(polyglot.types.ConstructorInstance ci,
                                VarContext<T> input,
                                T receiverAbsVal,
                                polyglot.ast.New n,
                                DataFlowNodeIdentifier callSiteNode)
                                                           throws polyglot.types.SemanticException

      Process a call to `ci` created with `new` with `VarContext` `input`.
      Parameters:
        `ci` - constructor to analyze
        `input` - variable context before analyzing the method
        `receiverAbsVal` - The abstract value to use for the newly created object, i.e., the abstract value that "this" will map to in the invoked constructor.
        `n` - the call to the constructor
        `callSite` - AST node (and context) for the call site
      Returns:
        new map of variables to their values after the analysis
      Throws:
        `polyglot.types.SemanticException` - if analysis fails

    - #### constructorCall

          public FinalVarContext<T> constructorCall(polyglot.types.ConstructorInstance ci,
                                           VarContext<T> input,
                                           polyglot.ast.ConstructorCall n,
                                           DataFlowNodeIdentifier callSiteNode)
                                                                      throws polyglot.types.SemanticException

      Process a call to `ci` with `VarContext` `input`. This is different from call(ConstructorInstance ci, VarContext input, T receiverAbsVal, New n), which is used when a "new C(...)" expression is encountered. By contrast, this is used when a "this(...)" or "super(...)" constructor call is encountered.
      Parameters:
        `ci` - constructor to analyze
        `input` - variable context before analyzing the method
        `n` - the call to the constructor
        `callSite` - AST node (and context) for the call site
      Returns:
        new map of variables to their values after the analysis
      Throws:
        `polyglot.types.SemanticException` - if analysis fails

    - #### computeExpectedExits

          protected java.util.Set<ExitMap.Key> computeExpectedExits(polyglot.ast.Term n)

      Parameters:
        `n` - `Term` on which to compute exit keys
      Returns:
        Set of possible exit keys that can be reached from the given `Term`

    - #### getAnalysisResultsFromWorkQueue

          protected abstract FinalVarContext<T> getAnalysisResultsFromWorkQueue(AnalysisUnit callee,
                                                           VarContext<T> beforeCall)
                                                                                                  throws polyglot.types.SemanticException

      Get the analysis results for the given callee and variable context.
      Parameters:
        `callee` - Code for a callee that is to be analyzed
        `beforeCall` - variable context before the call to the callee
      Returns:
        new variable context after performing the analysis
      Throws:
        `polyglot.types.SemanticException` - thrown for an analysis error

    - #### preCallNonVirtual

          protected VarContext<T> preCallNonVirtual(polyglot.types.ProcedureInstance pi,
                                        AnalysisContext calleeContext,
                                        VarContext<T> input,
                                        polyglot.ast.Term n)

      Allow extensions a chance to modify the input before the analysis of a non-virtual procedure call.
      Parameters:
        `procedure` - to be called
        `calleeContext` - Procedure analysis context
        `input` - variable context before the call to the callee
        `n` - the call to the procedure

    - #### getSignatureForMissingCode

          protected LibrarySignature<A,T> getSignatureForMissingCode(polyglot.types.ProcedureInstance pi,
                                                         T receiverAbsVal,
                                                         java.util.List<T> argAbsVals)

      Subclasses can override to provide signature for missing code.
      Parameters:
        `pi` - missing procedure instance
        `receiverAbsVal` - analyis context value for the receiver
        `argAbsVals` - list of values for the procedure arguments

    - #### guessAnalysisForMissingCode

          protected FinalVarContext<T> guessAnalysisForMissingCode(polyglot.types.ProcedureInstance pi,
                                                       AnalysisContext calleeContext,
                                                       HContext receiver,
                                                       VarContext<T> input,
                                                       T receiverAbsVal,
                                                       java.util.List<T> argAbsVals,
                                                       java.util.Set<ExitMap.Key> expectedExits,
                                                       polyglot.ast.Node node)

      Subclasses can override as a stop gap measure before they have signature.
      Parameters:
        `pi` - missing procedure
        `calleeContext` - procedure context
        `receiver` - receiver heap object
        `input` - variable context before analysis
        `receiverAbsVal` - value for the receiver
        `argAbsVals` - list of values for the procedure arguments
        `expectedExits` - set of expected exit keys
        `node` - calling node
      Returns:
        New variable context updated from the input during analysis

    - #### getAnalysisForMissingReceiver

          protected FinalVarContext<T> getAnalysisForMissingReceiver(polyglot.types.ProcedureInstance pi,
                                                         VarContext<T> input,
                                                         polyglot.ast.Term n,
                                                         DataFlowNodeIdentifier callSiteNode)

      Provide a hook for subclasses to implementation functionality when procedure pi is called (e.g., "e.m()") but there is an empty points to set for the receiver expression.
      Parameters:
        `pi` - called procedure
        `input` - variable context before analysis
        `n` - calling term
        `callSite` - AST node (and context) for the call site

    - #### guessAnalysisForMissingReceiver

          protected abstract FinalVarContext<T> guessAnalysisForMissingReceiver(polyglot.types.ProcedureInstance pi,
                                                           VarContext<T> input,
                                                           T receiverAbsVal,
                                                           java.util.List<T> argAbsVals,
                                                           java.util.Set<ExitMap.Key> expectedExits,
                                                           DataFlowNodeIdentifier callSiteNode)

      Subclasses should override as a stop gap measure if the receiver is missing, i.e., if the points to set of the receiver expression is empty.
      Parameters:
        `pi` - missing procedure
        `input` - variable context before analysis
        `receiverAbsVal` - abstract value for the receiver
        `argAbsVals` - list of abstract values for the procedure arguments
        `expectedExits` - set of expected exit keys
        `callSite` - AST node (and context) for the call site
      Returns:
        New variable context updated from the input during analysis

    - #### handleRecursiveCall

          protected FinalVarContext<T> handleRecursiveCall(FinalVarContext<T> res,
                                               VarContext<T> beforeCall,
                                               AnalysisUnit callee)

      The call to callee is potentially recursive.
      Parameters:
        `res` - Variable context resulting from calling the calles
        `beforeCall` - variable context before analysis
        `callee` - Recursive procedure

    - #### analysisName

          public java.lang.String analysisName()

      Overrides:
        `analysisName` in class `AnalysisUtil<A extends Ordered<A>>`
      Returns:
        Name of the current analysis

    - #### signatureAnalysisNames

          protected java.util.List<java.lang.String> signatureAnalysisNames()

      Returns:
        List containing the analysis names

    - #### getLocationAbsVal

          public T getLocationAbsVal(VarContext<T> c,
                            java.util.Set<AbstractLocation> locs)

      Compute the abstract values for the given abstract locations
      Parameters:
        `c` - variable context
        `locs` - set of abstract locations
      Returns:
        abstract values for the given abstract locations

    - #### recordRead

          public void recordRead(AbstractLocation loc)

      Record a location that has been read
      Parameters:
        `loc` - location that was read

    - #### recordReads

          public void recordReads(java.util.Collection<AbstractLocation> locs)

    - #### recordWrite

          public void recordWrite(AbstractLocation loc)

      Record a location that has been written
      Parameters:
        `loc` - location that was written

    - #### recordWrites

          public void recordWrites(java.util.Collection<AbstractLocation> locs)

    - #### addLocations

          public VarContext<T> addLocations(VarContext<T> c,
                                   java.util.Set<AbstractLocation> locs,
                                   T absVal)

      Add a set of locations at the given value.
      Parameters:
        `c` - current context to add to
        `locs` - locations to add
        `absVal` - value for the locations
      Returns:
        variable context with the locations added

    - #### createInitContext

          public VarContext<T> createInitContext()

      Create an initial variable context
      Returns:
        initial variable context

    - #### bottomAbstractValue

          public abstract T bottomAbstractValue()

      Returns:
        The bottom value in the abstract value lattice