proguard.evaluation.util

Interface PartialEvaluatorStateTracker

All Known Implementing Classes:

DebugPrinter, JsonPrinter

public interface PartialEvaluatorStateTracker

Interface with callback methods called by the Partial Evaluator when it enters certain states. States are visualised in the Partial evaluator docs. Implementers of this interface are allowed to assume a fixed order in the calls. For example: startCodeAttribute is followed with a startInstructionBlock.

Method Summary

Modifier and Type	Method and Description
default void	afterInstructionEvaluation(Clazz clazz, Method method, int instructionOffset, Instruction instruction, TracedVariables variablesAfter, TracedStack stackAfter, BasicBranchUnit branchUnit, InstructionOffsetValue branchTarget) The instruction is evaluated and branching information is obtained.
default void	definitiveBranch(Clazz clazz, Method method, int instructionOffset, Instruction instruction, TracedVariables variablesAfter, TracedStack stackAfter, InstructionOffsetValue branchTargets) The instruction causes a definitive branch.
default void	endSubroutine(Clazz clazz, Method method, TracedVariables variablesAfter, TracedStack stackAfter, int subroutineStart, int subroutineEnd) The evaluation and generalization of the subroutine is done, the partial evaluator moves on.
default void	evaluationResults(Clazz clazz, Method method, CodeAttribute codeAttribute, PartialEvaluator evaluator) Partial evaluator is done evaluating the code attribute.
default void	generalizeInstructionBlock(Clazz clazz, Method method, int instructionOffset, Instruction instruction, TracedVariables variablesBefore, TracedStack stackBefore, int evaluationCount) The instruction has been seen a certain number of times and the evaluator deems it time to start generalizing the instruction.
default void	generalizeSubroutine(Clazz clazz, Method method, TracedVariables startVariables, TracedStack startStack, int subroutineStart, int subroutineEnd) The partial evaluator will start generalizing the results of the evaluated subroutine.
default void	instructionBlockDone(Clazz clazz, Method method, CodeAttribute codeAttribute, TracedVariables startVariables, TracedStack startStack, int startOffset) An instruction block has been evaluated.
default void	registerAlternativeBranch(Clazz clazz, Method method, int fromInstructionOffset, Instruction fromInstruction, TracedVariables variablesAfter, TracedStack stackAfter, int branchIndex, int branchTargetCount, int offset) The evaluator detects multiple branches need to be evaluated.
default void	registerException(Clazz clazz, Method method, CodeAttribute codeAttribute, PartialEvaluator evaluator, java.lang.Throwable cause) An exception has been thrown while evaluating the current code attribute.
default void	registerExceptionHandler(Clazz clazz, Method method, int startPC, int endPC, ExceptionInfo info) Partial evaluator starts evaluating a specific exception handler.
default void	registerSubroutineReturn(Clazz clazz, Method method, int returnOffset, TracedVariables returnVariables, TracedStack returnStack) The current instruction was RET and the partial evaluator pushes the return address to the branch stack of the calling partial evaluator.
default void	registerUnusedExceptionHandler(Clazz clazz, Method method, int startPC, int endPC, ExceptionInfo info) Partial evaluator detects that the evaluation of the exception handler over a certain range is not needed.
default void	skipInstructionBlock(Clazz clazz, Method method, int instructionOffset, Instruction instruction, TracedVariables variablesBefore, TracedStack stackBefore, int evaluationCount) The instruction within this instruction block has been seen with the those variables and this stack, and thus it is not needed to evaluate this block any further.
default void	startBranchCodeBlockEvaluation(java.util.List<PartialEvaluator.InstructionBlock> branchStack) Evaluation of the first general block has been done.
default void	startCodeAttribute(Clazz clazz, Method method, CodeAttribute codeAttribute, Variables parameters) The partial evaluator starts with the evaluation of a code block.
default void	startExceptionHandlingForBlock(Clazz clazz, Method method, int startOffset, int endOffset) Partial evaluator starts evaluating the exceptions handlers that catch over a certain instruction range.
default void	startInstructionBlock(Clazz clazz, Method method, CodeAttribute codeAttribute, TracedVariables startVariables, TracedStack startStack, int startOffset) Partial evaluator starts evaluating an instruction block, specified by an instruction range within the code attribute and the variables and stack it would start with.
default void	startInstructionEvaluation(Clazz clazz, Method method, int instructionOffset, Instruction instruction, TracedVariables variablesBefore, TracedStack stackBefore, int evaluationCount) The partial evaluator will forward the evaluation of the instruction.
default void	startSubroutine(Clazz clazz, Method method, TracedVariables startVariables, TracedStack startStack, int subroutineStart, int subroutineEnd) The current instruction was JSR or JSR_W and the partial evaluator starts with the evaluation of the subroutine.

Method Detail

startCodeAttribute

default void startCodeAttribute(Clazz clazz,
                                Method method,
                                CodeAttribute codeAttribute,
                                Variables parameters)

The partial evaluator starts with the evaluation of a code block.

registerException

default void registerException(Clazz clazz,
                               Method method,
                               CodeAttribute codeAttribute,
                               PartialEvaluator evaluator,
                               java.lang.Throwable cause)

An exception has been thrown while evaluating the current code attribute.

startExceptionHandlingForBlock

default void startExceptionHandlingForBlock(Clazz clazz,
                                            Method method,
                                            int startOffset,
                                            int endOffset)

Partial evaluator starts evaluating the exceptions handlers that catch over a certain instruction range.

registerExceptionHandler

default void registerExceptionHandler(Clazz clazz,
                                      Method method,
                                      int startPC,
                                      int endPC,
                                      ExceptionInfo info)

Partial evaluator starts evaluating a specific exception handler.

registerUnusedExceptionHandler

default void registerUnusedExceptionHandler(Clazz clazz,
                                            Method method,
                                            int startPC,
                                            int endPC,
                                            ExceptionInfo info)

Partial evaluator detects that the evaluation of the exception handler over a certain range is not needed. For example when the exceptionType can not be thrown from with the instruction range.

evaluationResults

default void evaluationResults(Clazz clazz,
                               Method method,
                               CodeAttribute codeAttribute,
                               PartialEvaluator evaluator)

Partial evaluator is done evaluating the code attribute. You can extract the results straight from the evaluator.

startInstructionBlock

default void startInstructionBlock(Clazz clazz,
                                   Method method,
                                   CodeAttribute codeAttribute,
                                   TracedVariables startVariables,
                                   TracedStack startStack,
                                   int startOffset)

Partial evaluator starts evaluating an instruction block, specified by an instruction range within the code attribute and the variables and stack it would start with.

startBranchCodeBlockEvaluation

default void startBranchCodeBlockEvaluation(java.util.List<PartialEvaluator.InstructionBlock> branchStack)

Evaluation of the first general block has been done. The evaluator now starts evaluating the blocks generated by branch instructions and will do this in a stack like behaviour.

instructionBlockDone

default void instructionBlockDone(Clazz clazz,
                                  Method method,
                                  CodeAttribute codeAttribute,
                                  TracedVariables startVariables,
                                  TracedStack startStack,
                                  int startOffset)

An instruction block has been evaluated.

skipInstructionBlock

default void skipInstructionBlock(Clazz clazz,
                                  Method method,
                                  int instructionOffset,
                                  Instruction instruction,
                                  TracedVariables variablesBefore,
                                  TracedStack stackBefore,
                                  int evaluationCount)

The instruction within this instruction block has been seen with the those variables and this stack, and thus it is not needed to evaluate this block any further.

generalizeInstructionBlock

default void generalizeInstructionBlock(Clazz clazz,
                                        Method method,
                                        int instructionOffset,
                                        Instruction instruction,
                                        TracedVariables variablesBefore,
                                        TracedStack stackBefore,
                                        int evaluationCount)

The instruction has been seen a certain number of times and the evaluator deems it time to start generalizing the instruction.

startInstructionEvaluation

default void startInstructionEvaluation(Clazz clazz,
                                        Method method,
                                        int instructionOffset,
                                        Instruction instruction,
                                        TracedVariables variablesBefore,
                                        TracedStack stackBefore,
                                        int evaluationCount)

The partial evaluator will forward the evaluation of the instruction. An exception right after this state is likely.

afterInstructionEvaluation

default void afterInstructionEvaluation(Clazz clazz,
                                        Method method,
                                        int instructionOffset,
                                        Instruction instruction,
                                        TracedVariables variablesAfter,
                                        TracedStack stackAfter,
                                        BasicBranchUnit branchUnit,
                                        InstructionOffsetValue branchTarget)

The instruction is evaluated and branching information is obtained.

definitiveBranch

default void definitiveBranch(Clazz clazz,
                              Method method,
                              int instructionOffset,
                              Instruction instruction,
                              TracedVariables variablesAfter,
                              TracedStack stackAfter,
                              InstructionOffsetValue branchTargets)

The instruction causes a definitive branch. This means the partial evaluator discovered a jump is used and is sure what the next instruction will be. This next instruction will be evaluated next and within the same instructionBlock evaluation.

registerAlternativeBranch

default void registerAlternativeBranch(Clazz clazz,
                                       Method method,
                                       int fromInstructionOffset,
                                       Instruction fromInstruction,
                                       TracedVariables variablesAfter,
                                       TracedStack stackAfter,
                                       int branchIndex,
                                       int branchTargetCount,
                                       int offset)

The evaluator detects multiple branches need to be evaluated. It adds these block evaluations to a stack of blocks that still need to be evaluated. After all branches have been registered, the evaluator exits the evaluation of the current instruction block.

startSubroutine

default void startSubroutine(Clazz clazz,
                             Method method,
                             TracedVariables startVariables,
                             TracedStack startStack,
                             int subroutineStart,
                             int subroutineEnd)

The current instruction was JSR or JSR_W and the partial evaluator starts with the evaluation of the subroutine.

registerSubroutineReturn

default void registerSubroutineReturn(Clazz clazz,
                                      Method method,
                                      int returnOffset,
                                      TracedVariables returnVariables,
                                      TracedStack returnStack)

The current instruction was RET and the partial evaluator pushes the return address to the branch stack of the calling partial evaluator.

generalizeSubroutine

default void generalizeSubroutine(Clazz clazz,
                                  Method method,
                                  TracedVariables startVariables,
                                  TracedStack startStack,
                                  int subroutineStart,
                                  int subroutineEnd)

The partial evaluator will start generalizing the results of the evaluated subroutine.

endSubroutine

default void endSubroutine(Clazz clazz,
                           Method method,
                           TracedVariables variablesAfter,
                           TracedStack stackAfter,
                           int subroutineStart,
                           int subroutineEnd)

The evaluation and generalization of the subroutine is done, the partial evaluator moves on.