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 * @since 1.10
94 */
95 // public
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 }