com.android.dx.cf.code

Class LocalsArraySet

java.lang.Object

com.android.dx.util.MutabilityControl

com.android.dx.cf.code.LocalsArray

com.android.dx.cf.code.LocalsArraySet

All Implemented Interfaces:

ToHuman

public class LocalsArraySet
extends LocalsArray

Representation of a set of local variable arrays, with Java semantics. This peculiar case is to support in-method subroutines, which can have different locals sets for each caller.

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

Constructor Summary

Constructors

Constructor and Description
LocalsArraySet(int maxLocals) Constructs an instance.
LocalsArraySet(OneLocalsArray primary, java.util.ArrayList<LocalsArray> secondaries) Constructs an instance with the specified primary and secondaries set.

Method Summary

Modifier and Type	Method and Description
void	annotate(ExceptionWithContext ex) Annotates (adds context to) the given exception with information about this instance.
LocalsArray	copy() Makes and returns a mutable copy of this instance.
TypeBearer	get(int idx) Gets the type stored at the given local index, only succeeding if the given local contains a valid type (though it is allowed to be an uninitialized instance).
TypeBearer	getCategory1(int idx) Gets the type stored at the given local index, which is expected to be an initialized category-1 value.
TypeBearer	getCategory2(int idx) Gets the type stored at the given local index, which is expected to be a category-2 value.
int	getMaxLocals() Gets the maximum number of locals this instance can refer to.
TypeBearer	getOrNull(int idx) Gets the type stored at the given local index, or null if the given local is uninitialized / invalid.
protected OneLocalsArray	getPrimary() Gets the locals set appropriate for the current execution context.
void	invalidate(int idx) Invalidates the local at the given index.
void	makeInitialized(Type type) Replaces all the occurrences of the given uninitialized type in this array with its initialized equivalent.
LocalsArraySet	merge(LocalsArray other) Merges this instance with other.
LocalsArraySet	mergeWithSubroutineCaller(LocalsArray other, int predLabel) Merges this instance with a LocalsSet from a subroutine caller.
void	set(int idx, TypeBearer type) Sets the type stored at the given local index.
void	set(RegisterSpec spec) Sets the type for the local indicated by the given register spec to that register spec (which includes type and optional name information).
void	setImmutable() Makes this instance immutable.
LocalsArray	subArrayForLabel(int subLabel) Returns a LocalsArray instance representing the locals state that should be used when returning to a subroutine caller.
java.lang.String	toHuman() Return the "human" string form of this instance.

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

isImmutable, isMutable, throwIfImmutable, throwIfMutable

Methods inherited from class java.lang.Object

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

Constructor Detail

LocalsArraySet

public LocalsArraySet(int maxLocals)

Constructs an instance. The locals array initially consists of all-uninitialized values (represented as nulls).

Parameters:

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

LocalsArraySet

public LocalsArraySet(OneLocalsArray primary,
                      java.util.ArrayList<LocalsArray> secondaries)

Constructs an instance with the specified primary and secondaries set.

Parameters:

primary - non-null; primary locals to use

secondaries - non-null; secondaries set, indexed by subroutine caller label.

Method Detail

setImmutable

public void setImmutable()

Makes this instance immutable.

Overrides:

setImmutable in class MutabilityControl

copy

public LocalsArray copy()

Makes and returns a mutable copy of this instance.

Specified by:

copy in class LocalsArray

Returns:

non-null; the copy

annotate

public void annotate(ExceptionWithContext ex)

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

Specified by:

annotate in class LocalsArray

Parameters:

ex - non-null; the exception to annotate

toHuman

public java.lang.String toHuman()

Return the "human" string form of this instance. This is generally less "debuggy" than toString().

Returns:

non-null; the human string form

makeInitialized

public void makeInitialized(Type type)

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

Specified by:

makeInitialized in class LocalsArray

Parameters:

type - non-null; type to replace

getMaxLocals

public int getMaxLocals()

Gets the maximum number of locals this instance can refer to.

Specified by:

getMaxLocals in class LocalsArray

Returns:

the max locals

set

public void set(int idx,
                TypeBearer type)

Sets the type stored at the given local index. If the given type is category-2, then (a) the index must be at least two less than LocalsArray.getMaxLocals() and (b) the next index gets invalidated by the operation. In case of either category, if the previous local contains a category-2 value, then it too is invalidated by this operation.

Specified by:

set in class LocalsArray

Parameters:

idx - >= 0, < getMaxLocals(); which local

type - non-null; new type for the local at idx

set

public void set(RegisterSpec spec)

Sets the type for the local indicated by the given register spec to that register spec (which includes type and optional name information). This is identical to calling set(spec.getReg(), spec).

Specified by:

set in class LocalsArray

Parameters:

spec - non-null; register spec to use as the basis for the update

invalidate

public void invalidate(int idx)

Invalidates the local at the given index.

Specified by:

invalidate in class LocalsArray

Parameters:

idx - >= 0, < getMaxLocals(); which local

getOrNull

public TypeBearer getOrNull(int idx)

Gets the type stored at the given local index, or null if the given local is uninitialized / invalid.

Specified by:

getOrNull in class LocalsArray

Parameters:

idx - >= 0, < getMaxLocals(); which local

Returns:

null-ok; the type of value stored in that local

get

public TypeBearer get(int idx)

Gets the type stored at the given local index, only succeeding if the given local contains a valid type (though it is allowed to be an uninitialized instance).

Specified by:

get in class LocalsArray

Parameters:

idx - >= 0, < getMaxLocals(); which local

Returns:

non-null; the type of value stored in that local

getCategory1

public TypeBearer getCategory1(int idx)

Gets the type stored at the given local index, which is expected to be an initialized category-1 value.

Specified by:

getCategory1 in class LocalsArray

Parameters:

idx - >= 0, < getMaxLocals(); which local

Returns:

non-null; the type of value stored in that local

getCategory2

public TypeBearer getCategory2(int idx)

Gets the type stored at the given local index, which is expected to be a category-2 value.

Specified by:

getCategory2 in class LocalsArray

Parameters:

idx - >= 0, < getMaxLocals(); which local

Returns:

non-null; the type of value stored in that local

merge

public LocalsArraySet merge(LocalsArray other)

Merges this instance with other. If the merged result is the same as this instance, then this is returned (not a copy).

Specified by:

merge in class LocalsArray

Parameters:

other - non-null; another LocalsArray

Returns:

non-null; the merge result, a new instance or this

mergeWithSubroutineCaller

public LocalsArraySet mergeWithSubroutineCaller(LocalsArray other,
                                                int predLabel)

Merges this instance with a LocalsSet from a subroutine caller. To be used when merging in the first block of a subroutine.

Specified by:

mergeWithSubroutineCaller in class LocalsArray

Parameters:

other - other non-null; another LocalsArray. The final locals state of a subroutine caller.

predLabel - the label of the subroutine caller block.

Returns:

non-null; the merge result, a new instance or this

subArrayForLabel

public LocalsArray subArrayForLabel(int subLabel)

Returns a LocalsArray instance representing the locals state that should be used when returning to a subroutine caller.

Parameters:

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

Returns:

null-ok; an instance for this subroutine, or null if subroutine is not in this set.

getPrimary

protected OneLocalsArray getPrimary()

Gets the locals set appropriate for the current execution context. That is, if this is a OneLocalsArray instance, then return this, otherwise return LocalsArraySet's primary.

Specified by:

getPrimary in class LocalsArray

Returns:

locals for this execution context.