com.ibm.wala.util.ssa

Class SSAValueManager

java.lang.Object

com.ibm.wala.util.ssa.SSAValueManager

public class SSAValueManager
extends java.lang.Object

Manage SSA-Variables in synthetic methods.

Since:

2013-09-19

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.String	breadCrumb User-Defined debugging info

Constructor Summary

Constructors

Constructor and Description
SSAValueManager(ParameterAccessor acc)

Method Summary

Modifier and Type	Method and Description
java.util.List<SSAValue>	getAllForPhi(SSAValue.VariableKey key) Returns all "free" and "allocated" variables and the invalid ones in a sub-scope.
SSAValue	getCurrent(SSAValue.VariableKey key) Retrieve the SSA-Number that is valid for a type in the current scope.
SSAValue	getException() Create new SSAValue with UniqueKey and Exception-Type.
SSAValue	getFree(TypeReference type, SSAValue.VariableKey key) Returns and registers a free SSA-Number to a Type.
SSAValue	getSuper(SSAValue.VariableKey key) Retrieve the SSA-Number that is valid for a type in the super-ordinate scope.
SSAValue	getUnallocated(TypeReference type, SSAValue.VariableKey key) Get an unused number to assign to.
SSAValue	getUnmanaged(TypeReference type, SSAValue.VariableKey key) Retrieve a SSA-Value that is not under management.
SSAValue	getUnmanaged(TypeReference type, java.lang.String name)
void	invalidate(SSAValue.VariableKey key) Marks all known instances of VariableKey invalid.
boolean	isSeen(SSAValue.VariableKey key) Return if the type is managed by this class.
boolean	isSeen(SSAValue.VariableKey key, boolean withSuper) Return if the type is managed by this class.
java.util.Map<java.lang.Integer,Atom>	makeLocalNames() Collect the variable-names of all known variables.
boolean	needsAllocation(SSAValue.VariableKey key) Returns if an instance for that type needs to be allocated.
boolean	needsPhi(SSAValue.VariableKey key) Returns if a PhiInstruction (still) has to be added.
int	scopeDown(boolean doesLoop) Enter a subordinate scope.
int	scopeUp() Leave a subordinate scope.
void	setAllocation(SSAValue value, SSAInstruction setBy) Register a variable _after_ allocation.
void	setPhi(SSAValue value, SSAInstruction setBy) Register a Phi-Instruction _after_ added to the model.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

breadCrumb

public java.lang.String breadCrumb

User-Defined debugging info

Constructor Detail

SSAValueManager

public SSAValueManager(ParameterAccessor acc)

Method Detail

setAllocation

public void setAllocation(SSAValue value,
                          SSAInstruction setBy)

Register a variable _after_ allocation.

The proper way to add an allocation is to get a Variable using getUnallocated(com.ibm.wala.types.TypeReference, com.ibm.wala.util.ssa.SSAValue.VariableKey). Then assign it a value. And at last call this function.

You can however directly call the function if the type has not been seen before.

Parameters:

value - an unallocated SSA-Variable to assign the allocation to

setBy - The instruction that set the value (optional)

Throws:

java.lang.IllegalStateException - if you set more than one allocation for that type (TODO better check!)

java.lang.IllegalArgumentException - if type is null or ssaValue is zero or negative

setPhi

public void setPhi(SSAValue value,
                   SSAInstruction setBy)

Register a Phi-Instruction _after_ added to the model.

Parameters:

value - the number the SSA-Instruction assigns to

setBy - the Phi-Instruction itself - may be null

Throws:

java.lang.IllegalArgumentException - if you assign to a number requested using getFree(com.ibm.wala.types.TypeReference, com.ibm.wala.util.ssa.SSAValue.VariableKey) but types mismatch.

java.lang.IllegalStateException - if you forgot to close some Phis

getFree

public SSAValue getFree(TypeReference type,
                        SSAValue.VariableKey key)

Returns and registers a free SSA-Number to a Type.

You have to set the type using a Phi-Instruction. Also you don't have to add that instruction immediately it is required that it is added before the Model gets finished.

You can request the List of unmet Phi-Instructions by using XXX

Returns:

an unused SSA-Number

Throws:

java.lang.IllegalArgumentException - if type is null

getUnallocated

public SSAValue getUnallocated(TypeReference type,
                               SSAValue.VariableKey key)

Get an unused number to assign to.

There may only be one unallocated value for each type at a time. XXX: Really?

Returns:

SSA-Variable

Throws:

java.lang.IllegalStateException - if there is already an unallocated variable of that type

java.lang.IllegalArgumentException - if type is null

getUnmanaged

public SSAValue getUnmanaged(TypeReference type,
                             SSAValue.VariableKey key)

Retrieve a SSA-Value that is not under management.

Use instead of 'nextLocal++', else SSA-Values will clash!

Returns:

SSA-Variable

getUnmanaged

public SSAValue getUnmanaged(TypeReference type,
                             java.lang.String name)

getCurrent

public SSAValue getCurrent(SSAValue.VariableKey key)

Retrieve the SSA-Number that is valid for a type in the current scope.

Either that number origins from an allocation or a PhiInstruction (to be).

Returns:

a ssa number

Throws:

java.lang.IllegalStateException - if no number is assignable

java.lang.IllegalArgumentException - if type was not seen before or is null

getSuper

public SSAValue getSuper(SSAValue.VariableKey key)

Retrieve the SSA-Number that is valid for a type in the super-ordinate scope.

Either that number origins from an allocation or a PhiInstruction (to be).

Returns:

a ssa number

Throws:

java.lang.IllegalStateException - if no number is assignable

java.lang.IllegalArgumentException - if type was not seen before or is null

getAllForPhi

public java.util.List<SSAValue> getAllForPhi(SSAValue.VariableKey key)

Returns all "free" and "allocated" variables and the invalid ones in a sub-scope.

This is a suggestion which variables to considder as parameter to a Phi-Function.

Throws:

java.lang.IllegalArgumentException - if type was not seen before or is null

isSeen

public boolean isSeen(SSAValue.VariableKey key,
                      boolean withSuper)

Return if the type is managed by this class.

Parameters:

withSuper - when true return true if a managed key may be cast to type, when false type has to match exactly

key - the type in question

Throws:

java.lang.IllegalArgumentException - if key is null

isSeen

public boolean isSeen(SSAValue.VariableKey key)

Return if the type is managed by this class.

This variant respects super-types. Use isSeen(VariableKey, boolean) with a setting for withSuper of false to enforce exact matches.

Returns:

if the type is managed by this class.

needsAllocation

public boolean needsAllocation(SSAValue.VariableKey key)

Returns if an instance for that type needs to be allocated.

However this function does not respect weather a PhiInstruction is needed.

Throws:

java.lang.IllegalArgumentException - if type is null

needsPhi

public boolean needsPhi(SSAValue.VariableKey key)

Returns if a PhiInstruction (still) has to be added.

This is true if the Value has changed in a deeper scope, has been invalidated or requested using getFree

Throws:

java.lang.IllegalArgumentException - if type is null or has not been seen before

invalidate

public void invalidate(SSAValue.VariableKey key)

Marks all known instances of VariableKey invalid.

A call to this method is useful before a call to setAllocation. This methods sets all known instances to invalid, setAllocation will assign the new "current" instance to use.

Parameters:

key - Which variables to invalidate.

Throws:

java.lang.IllegalArgumentException - if type was not seen before or is null

scopeDown

public int scopeDown(boolean doesLoop)

Enter a subordinate scope.

Call this whenever a new code block starts i.e. when ever you would have to put a left curly-bracket in the java code.

This function influences the placement of Phi-Functions. Thus if you don't change values you don't have to call it.

Parameters:

doesLoop - set to true if the scope is introduced for a loop

Returns:

The depth

scopeUp

public int scopeUp()

Leave a subordinate scope.

All changes are marked invalid thus to be expected to be collected by a PhiInstruction.

Throws:

java.lang.IllegalStateException - if already at top level

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getException

public SSAValue getException()

Create new SSAValue with UniqueKey and Exception-Type.

The generated SSAValue will be unmanaged. It is mainly useful for SSAInvokeInstructions.

Returns:

new unmanaged SSAValue with Exception-Type

makeLocalNames

public java.util.Map<java.lang.Integer,Atom> makeLocalNames()

Collect the variable-names of all known variables.