| /* |
| * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package java.lang.invoke; |
| |
| import java.util.List; |
| import java.util.NoSuchElementException; |
| import java.util.function.IntFunction; |
| |
| /** |
| * An ordered sequence of constants, some of which may not yet |
| * be present. This type is used by {@link BootstrapCallInfo} |
| * to represent the sequence of bootstrap arguments associated |
| * with a bootstrap method, without forcing their immediate |
| * resolution. |
| * <p> |
| * If you use the |
| * {@linkplain ConstantGroup#get(int) simple get method}, |
| * the constant will be resolved, if this has not already |
| * happened. An occasional side effect of resolution is a |
| * {@code LinkageError}, which happens if the system |
| * could not resolve the constant in question. |
| * <p> |
| * In order to peek at a constant without necessarily |
| * resolving it, use the |
| * {@linkplain ConstantGroup#get(int,Object) |
| * non-throwing get method}. |
| * This method will never throw a resolution error. |
| * Instead, if the resolution would result in an error, |
| * or if the implementation elects not to attempt |
| * resolution at this point, then the method will |
| * return the user-supplied sentinel value. |
| * <p> |
| * To iterate through the constants, resolving as you go, |
| * use the iterator provided on the {@link List}-typed view. |
| * If you supply a sentinel, resolution will be suppressed. |
| * <p> |
| * Typically the constant is drawn from a constant pool entry |
| * in the virtual machine. Constant pool entries undergo a |
| * one-time state transition from unresolved to resolved, |
| * with a permanently recorded result. Usually that result |
| * is the desired constant value, but it may also be an error. |
| * In any case, the results displayed by a {@code ConstantGroup} |
| * are stable in the same way. If a query to a particular |
| * constant in a {@code ConstantGroup} throws an exception once, |
| * it will throw the same kind of exception forever after. |
| * If the query returns a constant value once, it will return |
| * the same value forever after. |
| * <p> |
| * The only possible change in the status of a constant is |
| * from the unresolved to the resolved state, and that |
| * happens exactly once. A constant will never revert to |
| * an unlinked state. However, from the point of view of |
| * this interface, constants may appear to spontaneously |
| * resolve. This is so because constant pools are global |
| * structures shared across threads, and because |
| * prefetching of some constants may occur, there are no |
| * strong guarantees when the virtual machine may resolve |
| * constants. |
| * <p> |
| * When choosing sentinel values, be aware that a constant |
| * pool which has {@code CONSTANT_Dynamic} entries |
| * can contain potentially any representable value, |
| * and arbitrary implementations of {@code ConstantGroup} |
| * are also free to produce arbitrary values. |
| * This means some obvious choices for sentinel values, |
| * such as {@code null}, may sometimes fail to distinguish |
| * a resolved from an unresolved constant in the group. |
| * The most reliable sentinel is a privately created object, |
| * or perhaps the {@code ConstantGroup} itself. |
| * @since 1.10 |
| */ |
| // public |
| interface ConstantGroup { |
| /// Access |
| |
| /** |
| * Returns the number of constants in this group. |
| * This value never changes, for any particular group. |
| * @return the number of constants in this group |
| */ |
| int size(); |
| |
| /** |
| * Returns the selected constant, resolving it if necessary. |
| * Throws a linkage error if resolution proves impossible. |
| * @param index which constant to select |
| * @return the selected constant |
| * @throws LinkageError if the selected constant needs resolution and cannot be resolved |
| */ |
| Object get(int index) throws LinkageError; |
| |
| /** |
| * Returns the selected constant, |
| * or the given sentinel value if there is none available. |
| * If the constant cannot be resolved, the sentinel will be returned. |
| * If the constant can (perhaps) be resolved, but has not yet been resolved, |
| * then the sentinel <em>may</em> be returned, at the implementation's discretion. |
| * To force resolution (and a possible exception), call {@link #get(int)}. |
| * @param index the selected constant |
| * @param ifNotPresent the sentinel value to return if the constant is not present |
| * @return the selected constant, if available, else the sentinel value |
| */ |
| Object get(int index, Object ifNotPresent); |
| |
| /** |
| * Returns an indication of whether a constant may be available. |
| * If it returns {@code true}, it will always return true in the future, |
| * and a call to {@link #get(int)} will never throw an exception. |
| * <p> |
| * After a normal return from {@link #get(int)} or a present |
| * value is reported from {@link #get(int,Object)}, this method |
| * must always return true. |
| * <p> |
| * If this method returns {@code false}, nothing in particular |
| * can be inferred, since the query only concerns the internal |
| * logic of the {@code ConstantGroup} object which ensures that |
| a successful * query to a constant will always remain successful. |
| * The only way to force a permanent decision about whether |
| * a constant is available is to call {@link #get(int)} and |
| * be ready for an exception if the constant is unavailable. |
| * @param index the selected constant |
| * @return {@code true} if the selected constant is known by |
| * this object to be present, {@code false} if it is known |
| * not to be present or |
| */ |
| boolean isPresent(int index); |
| |
| /// Views |
| |
| /** |
| * Create a view on this group as a {@link List} view. |
| * Any request for a constant through this view will |
| * force resolution. |
| * @return a {@code List} view on this group which will force resolution |
| */ |
| default List<Object> asList() { |
| return new AbstractConstantGroup.AsList(this, 0, size()); |
| } |
| |
| /** |
| * Create a view on this group as a {@link List} view. |
| * Any request for a constant through this view will |
| * return the given sentinel value, if the corresponding |
| * call to {@link #get(int,Object)} would do so. |
| * @param ifNotPresent the sentinel value to return if a constant is not present |
| * @return a {@code List} view on this group which will not force resolution |
| */ |
| default List<Object> asList(Object ifNotPresent) { |
| return new AbstractConstantGroup.AsList(this, 0, size(), ifNotPresent); |
| } |
| |
| /** |
| * Create a view on a sub-sequence of this group. |
| * @param start the index to begin the view |
| * @param end the index to end the view |
| * @return a view on the selected sub-group |
| */ |
| default ConstantGroup subGroup(int start, int end) { |
| return new AbstractConstantGroup.SubGroup(this, start, end); |
| } |
| |
| /// Bulk operations |
| |
| /** |
| * Copy a sequence of constant values into a given buffer. |
| * This is equivalent to {@code end-offset} separate calls to {@code get}, |
| * for each index in the range from {@code offset} up to but not including {@code end}. |
| * For the first constant that cannot be resolved, |
| * a {@code LinkageError} is thrown, but only after |
| * preceding constant value have been stored. |
| * @param start index of first constant to retrieve |
| * @param end limiting index of constants to retrieve |
| * @param buf array to receive the requested values |
| * @param pos position in the array to offset storing the values |
| * @return the limiting index, {@code end} |
| * @throws LinkageError if a constant cannot be resolved |
| */ |
| default int copyConstants(int start, int end, |
| Object[] buf, int pos) |
| throws LinkageError |
| { |
| int bufBase = pos - start; // buf[bufBase + i] = get(i) |
| for (int i = start; i < end; i++) { |
| buf[bufBase + i] = get(i); |
| } |
| return end; |
| } |
| |
| /** |
| * Copy a sequence of constant values into a given buffer. |
| * This is equivalent to {@code end-offset} separate calls to {@code get}, |
| * for each index in the range from {@code offset} up to but not including {@code end}. |
| * Any constants that cannot be resolved are replaced by the |
| * given sentinel value. |
| * @param start index of first constant to retrieve |
| * @param end limiting index of constants to retrieve |
| * @param buf array to receive the requested values |
| * @param pos position in the array to offset storing the values |
| * @param ifNotPresent sentinel value to store if a value is not available |
| * @return the limiting index, {@code end} |
| * @throws LinkageError if {@code resolve} is true and a constant cannot be resolved |
| */ |
| default int copyConstants(int start, int end, |
| Object[] buf, int pos, |
| Object ifNotPresent) { |
| int bufBase = pos - start; // buf[bufBase + i] = get(i) |
| for (int i = start; i < end; i++) { |
| buf[bufBase + i] = get(i, ifNotPresent); |
| } |
| return end; |
| } |
| |
| /** |
| * Make a new constant group with the given constants. |
| * The value of {@code ifNotPresent} may be any reference. |
| * If this value is encountered as an element of the |
| * {@code constants} list, the new constant group will |
| * regard that element of the list as logically missing. |
| * If the new constant group is called upon to resolve |
| * a missing element of the group, it will refer to the |
| * given {@code constantProvider}, by calling it on the |
| * index of the missing element. |
| * The {@code constantProvider} must be stable, in the sense |
| * that the outcome of calling it on the same index twice |
| * will produce equivalent results. |
| * If {@code constantProvider} is the null reference, then |
| * it will be treated as if it were a function which raises |
| * {@link NoSuchElementException}. |
| * @param constants the elements of this constant group |
| * @param ifNotPresent sentinel value provided instead of a missing constant |
| * @param constantProvider function to call when a missing constant is resolved |
| * @return a new constant group with the given constants and resolution behavior |
| */ |
| static ConstantGroup makeConstantGroup(List<Object> constants, |
| Object ifNotPresent, |
| IntFunction<Object> constantProvider) { |
| class Impl extends AbstractConstantGroup.WithCache { |
| Impl() { |
| super(constants.size()); |
| initializeCache(constants, ifNotPresent); |
| } |
| @Override |
| Object fillCache(int index) { |
| if (constantProvider == null) super.fillCache(index); |
| return constantProvider.apply(index); |
| } |
| } |
| return new Impl(); |
| } |
| |
| /** |
| * Make a new constant group with the given constant values. |
| * The constants will be copied from the given list into the |
| * new constant group, forcing resolution if any are missing. |
| * @param constants the constants of this constant group |
| * @return a new constant group with the given constants |
| */ |
| static ConstantGroup makeConstantGroup(List<Object> constants) { |
| final Object NP = AbstractConstantGroup.WithCache.NOT_PRESENT; |
| assert(!constants.contains(NP)); // secret value |
| return makeConstantGroup(constants, NP, null); |
| } |
| |
| } |
