com.android.dx.cf.code

Class Frame

java.lang.Object

com.android.dx.cf.code.Frame

public final class Frame
extends java.lang.Object

Representation of a Java method execution frame. A frame consists of a set of locals and a value stack, and it can be told to act on them to load and store values between them and an "arguments / results" area.

Constructor Summary

Constructors

Constructor and Description
Frame(int maxLocals, int maxStack) Constructs an instance.

Method Summary

Modifier and Type	Method and Description
void	annotate(ExceptionWithContext ex) Annotates (adds context to) the given exception with information about this frame.
Frame	copy() Makes and returns a mutable copy of this instance.
LocalsArray	getLocals() Gets the locals array for this instance.
ExecutionStack	getStack() Gets the execution stack for this instance.
IntList	getSubroutines() Returns the largest subroutine nesting this block may be in.
void	initializeWithParameters(StdTypeList params) Initialize this frame with the method's parameters.
Frame	makeExceptionHandlerStartFrame(CstType exceptionClass) Makes a new frame for an exception handler block invoked from this frame.
void	makeInitialized(Type type) Replaces all the occurrences of the given uninitialized type in this frame with its initialized equivalent.
Frame	makeNewSubroutineStartFrame(int subLabel, int callerLabel) Makes a frame for a subroutine start block, given that this is the ending frame of one of the subroutine's calling blocks.
Frame	mergeWith(Frame other) Merges two frames.
Frame	mergeWithSubroutineCaller(Frame other, int subLabel, int predLabel) Merges this frame with the frame of a subroutine caller at predLabel.
void	setImmutable() Makes this instance immutable.
Frame	subFrameForLabel(int startLabel, int subLabel) Returns a Frame instance representing the frame state that should be used when returning from a subroutine.

Methods inherited from class java.lang.Object

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

Constructor Detail

Frame

public Frame(int maxLocals,
             int maxStack)

Constructs an instance. The locals array initially consists of all-uninitialized values (represented as nulls) and the stack starts out empty.

Parameters:

maxLocals - >= 0; the maximum number of locals this instance can refer to

maxStack - >= 0; the maximum size of the stack for this instance

Method Detail

copy

public Frame copy()

Makes and returns a mutable copy of this instance. The copy contains copies of the locals and stack (that is, it doesn't share them with the original).

Returns:

non-null; the copy

setImmutable

public void setImmutable()

Makes this instance immutable.

makeInitialized

public void makeInitialized(Type type)

Replaces all the occurrences of the given uninitialized type in this frame with its initialized equivalent.

Parameters:

type - non-null; type to replace

getLocals

public LocalsArray getLocals()

Gets the locals array for this instance.

Returns:

non-null; the locals array

getStack

public ExecutionStack getStack()

Gets the execution stack for this instance.

Returns:

non-null; the execution stack

getSubroutines

public IntList getSubroutines()

Returns the largest subroutine nesting this block may be in. An empty list is returned if this block is not in any subroutine. Subroutines are identified by the label of their start block. The list is ordered such that the deepest nesting (the actual subroutine this block is in) is the last label in the list.

Returns:

non-null; list as noted above

initializeWithParameters

public void initializeWithParameters(StdTypeList params)

Initialize this frame with the method's parameters. Used for the first frame.

Parameters:

params - Type list of method parameters.

subFrameForLabel

public Frame subFrameForLabel(int startLabel,
                              int subLabel)

Returns a Frame instance representing the frame state that should be used when returning from a subroutine. The stack state of all subroutine invocations is identical, but the locals state may differ.

Parameters:

startLabel - >=0; The label of the returning subroutine's start block

subLabel - >=0; A calling label of a subroutine

Returns:

null-ok; an appropriatly-constructed instance, or null if label is not in the set

mergeWith

public Frame mergeWith(Frame other)

Merges two frames. If the merged result is the same as this frame, then this instance is returned.

Parameters:

other - non-null; another frame

Returns:

non-null; the result of merging the two frames

mergeWithSubroutineCaller

public Frame mergeWithSubroutineCaller(Frame other,
                                       int subLabel,
                                       int predLabel)

Merges this frame with the frame of a subroutine caller at predLabel. Only called on the frame at the first block of a subroutine.

Parameters:

other - non-null; another frame

subLabel - label of subroutine start block

predLabel - label of calling block

Returns:

non-null; the result of merging the two frames

makeNewSubroutineStartFrame

public Frame makeNewSubroutineStartFrame(int subLabel,
                                         int callerLabel)

Makes a frame for a subroutine start block, given that this is the ending frame of one of the subroutine's calling blocks. Subroutine calls may be nested and thus may have nested locals state, so we start with an initial state as seen by the subroutine, but keep track of the individual locals states that will be expected when the individual subroutine calls return.

Parameters:

subLabel - label of subroutine start block

callerLabel - >=0; label of the caller block where this frame came from.

Returns:

a new instance to begin a called subroutine.

makeExceptionHandlerStartFrame

public Frame makeExceptionHandlerStartFrame(CstType exceptionClass)

Makes a new frame for an exception handler block invoked from this frame.

Parameters:

exceptionClass - exception that the handler block will handle

Returns:

new frame

annotate

public void annotate(ExceptionWithContext ex)

Annotates (adds context to) the given exception with information about this frame.

Parameters:

ex - non-null; the exception to annotate