1 /*
   2  * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.lang.invoke;
  27 
  28 import java.util.List;
  29 import java.util.NoSuchElementException;
  30 import java.util.function.IntFunction;
  31 
  32 /**
  33  * An ordered sequence of constants, some of which may not yet
  34  * be present.  This type is used by {@link BootstrapCallInfo}
  35  * to represent the sequence of bootstrap arguments associated
  36  * with a bootstrap method, without forcing their immediate
  37  * resolution.
  38  * <p>
  39  * If you use the
  40  * {@linkplain ConstantGroup#get(int) simple get method},
  41  * the constant will be resolved, if this has not already
  42  * happened.  An occasional side effect of resolution is a
  43  * {@code LinkageError}, which happens if the system
  44  * could not resolve the constant in question.
  45  * <p>
  46  * In order to peek at a constant without necessarily
  47  * resolving it, use the
  48  * {@linkplain ConstantGroup#get(int,Object)
  49  * non-throwing get method}.
  50  * This method will never throw a resolution error.
  51  * Instead, if the resolution would result in an error,
  52  * or if the implementation elects not to attempt
  53  * resolution at this point, then the method will
  54  * return the user-supplied sentinel value.
  55  * <p>
  56  * To iterate through the constants, resolving as you go,
  57  * use the iterator provided on the {@link List}-typed view.
  58  * If you supply a sentinel, resolution will be suppressed.
  59  * <p>
  60  * Typically the constant is drawn from a constant pool entry
  61  * in the virtual machine. Constant pool entries undergo a
  62  * one-time state transition from unresolved to resolved,
  63  * with a permanently recorded result.  Usually that result
  64  * is the desired constant value, but it may also be an error.
  65  * In any case, the results displayed by a {@code ConstantGroup}
  66  * are stable in the same way.  If a query to a particular
  67  * constant in a {@code ConstantGroup} throws an exception once,
  68  * it will throw the same kind of exception forever after.
  69  * If the query returns a constant value once, it will return
  70  * the same value forever after.
  71  * <p>
  72  * The only possible change in the status of a constant is
  73  * from the unresolved to the resolved state, and that
  74  * happens exactly once.  A constant will never revert to
  75  * an unlinked state.  However, from the point of view of
  76  * this interface, constants may appear to spontaneously
  77  * resolve.  This is so because constant pools are global
  78  * structures shared across threads, and because
  79  * prefetching of some constants may occur, there are no
  80  * strong guarantees when the virtual machine may resolve
  81  * constants.
  82  * <p>
  83  * When choosing sentinel values, be aware that a constant
  84  * pool which has {@code CONSTANT_Dynamic} entries
  85  * can contain potentially any representable value,
  86  * and arbitrary implementations of {@code ConstantGroup}
  87  * are also free to produce arbitrary values.
  88  * This means some obvious choices for sentinel values,
  89  * such as {@code null}, may sometimes fail to distinguish
  90  * a resolved from an unresolved constant in the group.
  91  * The most reliable sentinel is a privately created object,
  92  * or perhaps the {@code ConstantGroup} itself.
  93  *
  94  * @since 11
  95  */
  96 interface ConstantGroup {
  97     /// Access
  98 
  99     /**
 100      * Returns the number of constants in this group.
 101      * This value never changes, for any particular group.
 102      * @return the number of constants in this group
 103      */
 104     int size();
 105 
 106     /**
 107      * Returns the selected constant, resolving it if necessary.
 108      * Throws a linkage error if resolution proves impossible.
 109      * @param index which constant to select
 110      * @return the selected constant
 111      * @throws LinkageError if the selected constant needs resolution and cannot be resolved
 112      */
 113     Object get(int index) throws LinkageError;
 114 
 115     /**
 116      * Returns the selected constant,
 117      * or the given sentinel value if there is none available.
 118      * If the constant cannot be resolved, the sentinel will be returned.
 119      * If the constant can (perhaps) be resolved, but has not yet been resolved,
 120      * then the sentinel <em>may</em> be returned, at the implementation's discretion.
 121      * To force resolution (and a possible exception), call {@link #get(int)}.
 122      * @param index the selected constant
 123      * @param ifNotPresent the sentinel value to return if the constant is not present
 124      * @return the selected constant, if available, else the sentinel value
 125      */
 126     Object get(int index, Object ifNotPresent);
 127 
 128     /**
 129      * Returns an indication of whether a constant may be available.
 130      * If it returns {@code true}, it will always return true in the future,
 131      * and a call to {@link #get(int)} will never throw an exception.
 132      * <p>
 133      * After a normal return from {@link #get(int)} or a present
 134      * value is reported from {@link #get(int,Object)}, this method
 135      * must always return true.
 136      * <p>
 137      * If this method returns {@code false}, nothing in particular
 138      *  can be inferred, since the query only concerns the internal
 139      * logic of the {@code ConstantGroup} object which ensures that
 140      a successful * query to a constant will always remain successful.
 141      * The only way to force a permanent decision about whether
 142      * a constant is available is to call {@link #get(int)} and
 143      * be ready for an exception if the constant is unavailable.
 144      * @param index the selected constant
 145      * @return {@code true} if the selected constant is known by
 146      *     this object to be present, {@code false} if it is known
 147      *     not to be present or
 148      */
 149     boolean isPresent(int index);
 150 
 151     /// Views
 152 
 153     /**
 154      * Create a view on this group as a {@link List} view.
 155      * Any request for a constant through this view will
 156      * force resolution.
 157      * @return a {@code List} view on this group which will force resolution
 158      */
 159     default List<Object> asList() {
 160         return new AbstractConstantGroup.AsList(this, 0, size());
 161     }
 162 
 163     /**
 164      * Create a view on this group as a {@link List} view.
 165      * Any request for a constant through this view will
 166      * return the given sentinel value, if the corresponding
 167      * call to {@link #get(int,Object)} would do so.
 168      * @param ifNotPresent the sentinel value to return if a constant is not present
 169      * @return a {@code List} view on this group which will not force resolution
 170      */
 171     default List<Object> asList(Object ifNotPresent) {
 172         return new AbstractConstantGroup.AsList(this, 0, size(), ifNotPresent);
 173     }
 174 
 175     /**
 176      * Create a view on a sub-sequence of this group.
 177      * @param start the index to begin the view
 178      * @param end the index to end the view
 179      * @return a view on the selected sub-group
 180      */
 181     default ConstantGroup subGroup(int start, int end) {
 182         return new AbstractConstantGroup.SubGroup(this, start, end);
 183     }
 184 
 185     /// Bulk operations
 186 
 187     /**
 188      * Copy a sequence of constant values into a given buffer.
 189      * This is equivalent to {@code end-offset} separate calls to {@code get},
 190      * for each index in the range from {@code offset} up to but not including {@code end}.
 191      * For the first constant that cannot be resolved,
 192      * a {@code LinkageError} is thrown, but only after
 193      * preceding constant value have been stored.
 194      * @param start index of first constant to retrieve
 195      * @param end limiting index of constants to retrieve
 196      * @param buf array to receive the requested values
 197      * @param pos position in the array to offset storing the values
 198      * @return the limiting index, {@code end}
 199      * @throws LinkageError if a constant cannot be resolved
 200      */
 201     default int copyConstants(int start, int end,
 202                               Object[] buf, int pos)
 203             throws LinkageError
 204     {
 205         int bufBase = pos - start;  // buf[bufBase + i] = get(i)
 206         for (int i = start; i < end; i++) {
 207             buf[bufBase + i] = get(i);
 208         }
 209         return end;
 210     }
 211 
 212     /**
 213      * Copy a sequence of constant values into a given buffer.
 214      * This is equivalent to {@code end-offset} separate calls to {@code get},
 215      * for each index in the range from {@code offset} up to but not including {@code end}.
 216      * Any constants that cannot be resolved are replaced by the
 217      * given sentinel value.
 218      * @param start index of first constant to retrieve
 219      * @param end limiting index of constants to retrieve
 220      * @param buf array to receive the requested values
 221      * @param pos position in the array to offset storing the values
 222      * @param ifNotPresent sentinel value to store if a value is not available
 223      * @return the limiting index, {@code end}
 224      * @throws LinkageError if {@code resolve} is true and a constant cannot be resolved
 225      */
 226     default int copyConstants(int start, int end,
 227                               Object[] buf, int pos,
 228                               Object ifNotPresent) {
 229         int bufBase = pos - start;  // buf[bufBase + i] = get(i)
 230         for (int i = start; i < end; i++) {
 231             buf[bufBase + i] = get(i, ifNotPresent);
 232         }
 233         return end;
 234     }
 235 
 236     /**
 237      * Make a new constant group with the given constants.
 238      * The value of {@code ifNotPresent} may be any reference.
 239      * If this value is encountered as an element of the
 240      * {@code constants} list, the new constant group will
 241      * regard that element of the list as logically missing.
 242      * If the new constant group is called upon to resolve
 243      * a missing element of the group, it will refer to the
 244      * given {@code constantProvider}, by calling it on the
 245      * index of the missing element.
 246      * The {@code constantProvider} must be stable, in the sense
 247      * that the outcome of calling it on the same index twice
 248      * will produce equivalent results.
 249      * If {@code constantProvider} is the null reference, then
 250      * it will be treated as if it were a function which raises
 251      * {@link NoSuchElementException}.
 252      * @param constants the elements of this constant group
 253      * @param ifNotPresent sentinel value provided instead of a missing constant
 254      * @param constantProvider function to call when a missing constant is resolved
 255      * @return a new constant group with the given constants and resolution behavior
 256      */
 257     static ConstantGroup makeConstantGroup(List<Object> constants,
 258                                            Object ifNotPresent,
 259                                            IntFunction<Object> constantProvider) {
 260         class Impl extends AbstractConstantGroup.WithCache {
 261             Impl() {
 262                 super(constants.size());
 263                 initializeCache(constants, ifNotPresent);
 264             }
 265             @Override
 266             Object fillCache(int index) {
 267                 if (constantProvider == null)  super.fillCache(index);
 268                 return constantProvider.apply(index);
 269             }
 270         }
 271         return new Impl();
 272     }
 273 
 274     /**
 275      * Make a new constant group with the given constant values.
 276      * The constants will be copied from the given list into the
 277      * new constant group, forcing resolution if any are missing.
 278      * @param constants the constants of this constant group
 279      * @return a new constant group with the given constants
 280      */
 281     static ConstantGroup makeConstantGroup(List<Object> constants) {
 282         final Object NP = AbstractConstantGroup.WithCache.NOT_PRESENT;
 283         assert(!constants.contains(NP));  // secret value
 284         return makeConstantGroup(constants, NP, null);
 285     }
 286 
 287 }