| /* |
| * Copyright (C) 2007 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package com.android.dx.cf.code; |
| |
| import com.android.dx.rop.code.RegisterSpec; |
| import com.android.dx.rop.type.Type; |
| import com.android.dx.rop.type.TypeBearer; |
| import com.android.dx.util.ExceptionWithContext; |
| import com.android.dx.util.Hex; |
| import com.android.dx.util.MutabilityControl; |
| import com.android.dx.util.ToHuman; |
| |
| /** |
| * Representation of an array of local variables, with Java semantics. |
| * |
| * <p><b>Note:</b> For the most part, the documentation for this class |
| * ignores the distinction between {@link Type} and {@link |
| * TypeBearer}.</p> |
| */ |
| public abstract class LocalsArray extends MutabilityControl implements ToHuman { |
| |
| /** |
| * Constructs an instance, explicitly indicating the mutability. |
| * |
| * @param mutable {@code true} if this instance is mutable |
| */ |
| protected LocalsArray(boolean mutable) { |
| super(mutable); |
| } |
| |
| /** |
| * Makes and returns a mutable copy of this instance. |
| * |
| * @return {@code non-null;} the copy |
| */ |
| public abstract LocalsArray copy(); |
| |
| /** |
| * Annotates (adds context to) the given exception with information |
| * about this instance. |
| * |
| * @param ex {@code non-null;} the exception to annotate |
| */ |
| public abstract void annotate(ExceptionWithContext ex); |
| |
| /** |
| * Replaces all the occurrences of the given uninitialized type in |
| * this array with its initialized equivalent. |
| * |
| * @param type {@code non-null;} type to replace |
| */ |
| public abstract void makeInitialized(Type type); |
| |
| /** |
| * Gets the maximum number of locals this instance can refer to. |
| * |
| * @return the max locals |
| */ |
| public abstract int getMaxLocals(); |
| |
| /** |
| * 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 |
| * {@link #getMaxLocals} and (b) the next index gets invalidated |
| * by the operation. In case of either category, if the <i>previous</i> |
| * local contains a category-2 value, then it too is invalidated by |
| * this operation. |
| * |
| * @param idx {@code >= 0, < getMaxLocals();} which local |
| * @param type {@code non-null;} new type for the local at {@code idx} |
| */ |
| public abstract void set(int idx, TypeBearer type); |
| |
| /** |
| * 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 |
| * {@code set(spec.getReg(), spec)}. |
| * |
| * @param spec {@code non-null;} register spec to use as the basis for the update |
| */ |
| public abstract void set(RegisterSpec spec); |
| |
| /** |
| * Invalidates the local at the given index. |
| * |
| * @param idx {@code >= 0, < getMaxLocals();} which local |
| */ |
| public abstract void invalidate(int idx); |
| |
| /** |
| * Gets the type stored at the given local index, or {@code null} |
| * if the given local is uninitialized / invalid. |
| * |
| * @param idx {@code >= 0, < getMaxLocals();} which local |
| * @return {@code null-ok;} the type of value stored in that local |
| */ |
| public abstract TypeBearer getOrNull(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). |
| * |
| * @param idx {@code >= 0, < getMaxLocals();} which local |
| * @return {@code non-null;} the type of value stored in that local |
| * @throws SimException thrown if {@code idx} is valid, but |
| * the contents are invalid |
| */ |
| public abstract TypeBearer get(int idx); |
| |
| /** |
| * Gets the type stored at the given local index, which is expected |
| * to be an initialized category-1 value. |
| * |
| * @param idx {@code >= 0, < getMaxLocals();} which local |
| * @return {@code non-null;} the type of value stored in that local |
| * @throws SimException thrown if {@code idx} is valid, but |
| * one of the following holds: (a) the local is invalid; (b) the local |
| * contains an uninitialized instance; (c) the local contains a |
| * category-2 value |
| */ |
| public abstract TypeBearer getCategory1(int idx); |
| |
| /** |
| * Gets the type stored at the given local index, which is expected |
| * to be a category-2 value. |
| * |
| * @param idx {@code >= 0, < getMaxLocals();} which local |
| * @return {@code non-null;} the type of value stored in that local |
| * @throws SimException thrown if {@code idx} is valid, but |
| * one of the following holds: (a) the local is invalid; (b) the local |
| * contains a category-1 value |
| */ |
| public abstract TypeBearer getCategory2(int idx); |
| |
| /** |
| * Merges this instance with {@code other}. If the merged result is |
| * the same as this instance, then this is returned (not a copy). |
| * |
| * @param other {@code non-null;} another LocalsArray |
| * @return {@code non-null;} the merge result, a new instance or this |
| */ |
| public abstract LocalsArray merge(LocalsArray other); |
| |
| /** |
| * Merges this instance with a {@code LocalsSet} from a subroutine |
| * caller. To be used when merging in the first block of a subroutine. |
| * |
| * @param other {@code other non-null;} another LocalsArray. The final locals |
| * state of a subroutine caller. |
| * @param predLabel the label of the subroutine caller block. |
| * @return {@code non-null;} the merge result, a new instance or this |
| */ |
| public abstract LocalsArraySet mergeWithSubroutineCaller |
| (LocalsArray other, int predLabel); |
| |
| /** |
| * Gets the locals set appropriate for the current execution context. |
| * That is, if this is a {@code OneLocalsArray} instance, then return |
| * {@code this}, otherwise return {@code LocalsArraySet}'s |
| * primary. |
| * |
| * @return locals for this execution context. |
| */ |
| protected abstract OneLocalsArray getPrimary(); |
| |
| } |