com.android.dx.cf.code
Class ExecutionStack

java.lang.Object
  com.android.dx.util.MutabilityControl
      com.android.dx.cf.code.ExecutionStack

public final class ExecutionStack
extends MutabilityControl

Representation of a Java method execution stack.

Note: For the most part, the documentation for this class ignores the distinction between Type and TypeBearer.

Constructor Summary

ExecutionStack(int maxStack)
Constructs an instance.

Method Summary

void	annotate(com.android.dex.util.ExceptionWithContext ex) Annotates (adds context to) the given exception with information about this instance.
void	change(int n, TypeBearer type) Changes an element already on a stack.
void	clear() Clears the stack.
ExecutionStack	copy() Makes and returns a mutable copy of this instance.
int	getMaxStack() Gets the maximum stack size for this instance.
void	makeInitialized(Type type) Replaces all the occurrences of the given uninitialized type in this stack with its initialized equivalent.
ExecutionStack	merge(ExecutionStack other) Merges this stack with another stack.
TypeBearer	peek(int n) Peeks at the nth element down from the top of the stack.
boolean	peekLocal(int n) Peeks at the nth element down from the top of the stack, returning whether or not it has local info.
Type	peekType(int n) Peeks at the nth element down from the top of the stack, returning the type per se, as opposed to the type-bearer.
TypeBearer	pop() Pops the top element off of the stack.
void	push(TypeBearer type) Pushes a value of the given type onto the stack.
void	setLocal() Flags the next value pushed onto the stack as having local info.
int	size() Gets the current stack size.

Methods inherited from class com.android.dx.util.MutabilityControl

isImmutable, isMutable, setImmutable, throwIfImmutable, throwIfMutable

Methods inherited from class java.lang.Object

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

Constructor Detail

ExecutionStack

public ExecutionStack(int maxStack)

Constructs an instance.

Parameters:

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

Method Detail

copy

public ExecutionStack copy()

Makes and returns a mutable copy of this instance.

Returns:

non-null; the copy

annotate

public void annotate(com.android.dex.util.ExceptionWithContext ex)

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

Parameters:

ex - non-null; the exception to annotate

makeInitialized

public void makeInitialized(Type type)

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

Parameters:

type - non-null; type to replace

getMaxStack

public int getMaxStack()

Gets the maximum stack size for this instance.

Returns:

>= 0; the max stack size

size

public int size()

Gets the current stack size.

Returns:

>= 0, < getMaxStack(); the current stack size

clear

public void clear()

Clears the stack. (That is, this method pops everything off.)

push

public void push(TypeBearer type)

Pushes a value of the given type onto the stack.

Parameters:

type - non-null; type of the value

Throws:

SimException - thrown if there is insufficient room on the stack for the value

setLocal

public void setLocal()

Flags the next value pushed onto the stack as having local info.

peek

public TypeBearer peek(int n)

Peeks at the nth element down from the top of the stack. n == 0 means to peek at the top of the stack. Note that this will return null if the indicated element is the deeper half of a category-2 value.

Parameters:

n - >= 0; which element to peek at

Returns:

null-ok; the type of value stored at that element

Throws:

SimException - thrown if n >= size()

peekLocal

public boolean peekLocal(int n)

Peeks at the nth element down from the top of the stack, returning whether or not it has local info.

Parameters:

n - >= 0; which element to peek at

Returns:

true if the value has local info, false otherwise

Throws:

SimException - thrown if n >= size()

peekType

public Type peekType(int n)

Peeks at the nth element down from the top of the stack, returning the type per se, as opposed to the type-bearer. This method is just a convenient shorthand for peek(n).getType().

See Also:

peek(int)

pop

public TypeBearer pop()

Pops the top element off of the stack.

Returns:

non-null; the type formerly on the top of the stack

Throws:

SimException - thrown if the stack is empty

change

public void change(int n,
                   TypeBearer type)

Changes an element already on a stack. This method is useful in limited contexts, particularly when merging two instances. As such, it places the following restriction on its behavior: You may only replace values with other values of the same category.

Parameters:

n - >= 0; which element to change, where 0 is the top element of the stack

type - non-null; type of the new value

Throws:

SimException - thrown if n >= size() or the action is otherwise prohibited

merge

public ExecutionStack merge(ExecutionStack other)

Merges this stack with another stack. A new instance is returned if this merge results in a change. If no change results, this instance is returned. See Merger.mergeStack()

Parameters:

other - non-null; a stack to merge with

Returns:

non-null; the result of the merge