164 * bytecode instructions specified in the last column of the table. In particular, method handles to |
164 * bytecode instructions specified in the last column of the table. In particular, method handles to |
165 * private and protected members can be created in exactly those classes for which the corresponding |
165 * private and protected members can be created in exactly those classes for which the corresponding |
166 * normal accesses are legal. |
166 * normal accesses are legal. |
167 * <p> |
167 * <p> |
168 * A constant may refer to a method or constructor with the {@code varargs} |
168 * A constant may refer to a method or constructor with the {@code varargs} |
169 * bit (hexadecimal {@code 80}) set in its modifier bitmask. |
169 * bit (hexadecimal {@code 0x0080}) set in its modifier bitmask. |
170 * The method handle constant produced for such a method behaves the same |
170 * The method handle constant produced for such a method behaves as if |
|
171 * it were created by {@link java.dyn.MethodHandle#asVarargsCollector asVarargsCollector}. |
|
172 * In other words, the constant method handle will exhibit variable arity, |
|
173 * when invoked via {@code invokeGeneric}. |
|
174 * On the other hand, its behavior with respect to {@code invokeExact} will be the same |
171 * as if the {@code varargs} bit were not set. |
175 * as if the {@code varargs} bit were not set. |
172 * The argument-collecting behavior of {@code varargs} can be emulated by |
|
173 * adapting the method handle constant with |
|
174 * {@link java.dyn.MethodHandle#asCollector asCollector}. |
|
175 * There is no provision for doing this automatically. |
|
176 * <p> |
176 * <p> |
177 * Although the {@code CONSTANT_MethodHandle} and {@code CONSTANT_MethodType} constant types |
177 * Although the {@code CONSTANT_MethodHandle} and {@code CONSTANT_MethodType} constant types |
178 * resolve class names, they do not force class initialization. |
178 * resolve class names, they do not force class initialization. |
179 * Method handle constants for subtags {@code REF_getStatic}, {@code REF_putStatic}, and {@code REF_invokeStatic} |
179 * Method handle constants for subtags {@code REF_getStatic}, {@code REF_putStatic}, and {@code REF_invokeStatic} |
180 * may force class initialization on their first invocation, just like the corresponding bytecodes. |
180 * may force class initialization on their first invocation, just like the corresponding bytecodes. |
367 * <p> |
367 * <p> |
368 * If a given {@code invokedynamic} instruction specifies no static arguments, |
368 * If a given {@code invokedynamic} instruction specifies no static arguments, |
369 * the instruction's bootstrap method will be invoked on three arguments, |
369 * the instruction's bootstrap method will be invoked on three arguments, |
370 * conveying the instruction's caller class, name, and method type. |
370 * conveying the instruction's caller class, name, and method type. |
371 * If the {@code invokedynamic} instruction specifies one or more static arguments, |
371 * If the {@code invokedynamic} instruction specifies one or more static arguments, |
372 * a fourth argument will be passed to the bootstrap argument, |
372 * those values will be passed as additional arguments to the method handle. |
373 * either an {@code Object} reference to the sole extra argument (if there is one) |
373 * (Note that because there is a limit of 255 arguments to any method, |
374 * or an {@code Object} array of references to all the arguments (if there are two or more), |
374 * at most 252 extra arguments can be supplied.) |
375 * as if the bootstrap method is a variable-arity method. |
375 * The bootstrap method will be invoked as if by either {@code invokeGeneric} |
|
376 * or {@code invokeWithArguments}. (There is no way to tell the difference.) |
|
377 * If the bootstrap method is a variable arity method (its modifier bit {@code 0x0080} is set), |
|
378 * then some or all of the arguments specified here may be collected into a trailing array parameter. |
|
379 * (This is not a special rule, but rather a useful consequence of the interaction |
|
380 * between {@code CONSTANT_MethodHandle} constants, the modifier bit for variable arity methods, |
|
381 * and the {@code java.dyn.MethodHandle#asVarargsCollector asVarargsCollector} transformation.) |
|
382 * <p> |
|
383 * Given these rules, here are examples of legal bootstrap method declarations, |
|
384 * given various numbers {@code N} of extra arguments. |
|
385 * The first rows (marked {@code *}) will work for any number of extra arguments. |
376 * <code> |
386 * <code> |
377 * <table border=1 cellpadding=5 summary="Static argument types"> |
387 * <table border=1 cellpadding=5 summary="Static argument types"> |
378 * <tr><th>N</th><th>sample bootstrap method</th></tr> |
388 * <tr><th>N</th><th>sample bootstrap method</th></tr> |
|
389 * <tr><td>*</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)</code></td></tr> |
|
390 * <tr><td>*</td><td><code>CallSite bootstrap(Object... args)</code></td></tr> |
|
391 * <tr><td>*</td><td><code>CallSite bootstrap(Object caller, Object... nameAndTypeWithArgs)</code></td></tr> |
379 * <tr><td>0</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type)</code></td></tr> |
392 * <tr><td>0</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type)</code></td></tr> |
|
393 * <tr><td>0</td><td><code>CallSite bootstrap(Lookup caller, Object... nameAndType)</code></td></tr> |
380 * <tr><td>1</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object arg)</code></td></tr> |
394 * <tr><td>1</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object arg)</code></td></tr> |
381 * <tr><td>2</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)</code></td></tr> |
395 * <tr><td>2</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)</code></td></tr> |
|
396 * <tr><td>2</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, String... args)</code></td></tr> |
|
397 * <tr><td>2</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, String x, int y)</code></td></tr> |
382 * </table> |
398 * </table> |
383 * </code> |
399 * </code> |
384 * <p> |
400 * The last example assumes that the extra arguments are of type |
385 * The argument and return types listed here are used by the {@code invokeGeneric} |
401 * {@code CONSTANT_String} and {@code CONSTANT_Integer}, respectively. |
386 * call to the bootstrap method. |
402 * The second-to-last example assumes that all extra arguments are of type |
|
403 * {@code CONSTANT_String}. |
|
404 * The other examples work with all types of extra arguments. |
|
405 * <p> |
387 * As noted above, the actual method type of the bootstrap method can vary. |
406 * As noted above, the actual method type of the bootstrap method can vary. |
388 * For example, the fourth argument could be {@code MethodHandle}, |
407 * For example, the fourth argument could be {@code MethodHandle}, |
389 * if that is the type of the corresponding constant in |
408 * if that is the type of the corresponding constant in |
390 * the {@code CONSTANT_InvokeDynamic} entry. |
409 * the {@code CONSTANT_InvokeDynamic} entry. |
391 * In that case, the {@code invokeGeneric} call will pass the extra method handle |
410 * In that case, the {@code invokeGeneric} call will pass the extra method handle |
392 * constant as an {@code Object}, but the type matching machinery of {@code invokeGeneric} |
411 * constant as an {@code Object}, but the type matching machinery of {@code invokeGeneric} |
393 * will cast the reference back to {@code MethodHandle} before invoking the bootstrap method. |
412 * will cast the reference back to {@code MethodHandle} before invoking the bootstrap method. |
394 * (If a string constant were passed instead, by badly generated code, that cast would then fail.) |
413 * (If a string constant were passed instead, by badly generated code, that cast would then fail, |
395 * <p> |
414 * resulting in an {@code InvokeDynamicBootstrapError}.) |
396 * If the fourth argument is an array, the array element type must be {@code Object}, |
|
397 * since object arrays (as produced by the JVM at this point) cannot be converted |
|
398 * to other array types. |
|
399 * <p> |
|
400 * If an array is provided, it will appear to be freshly allocated. |
|
401 * That is, the same array will not appear to two bootstrap method calls. |
|
402 * <p> |
415 * <p> |
403 * Extra bootstrap method arguments are intended to allow language implementors |
416 * Extra bootstrap method arguments are intended to allow language implementors |
404 * to safely and compactly encode metadata. |
417 * to safely and compactly encode metadata. |
405 * In principle, the name and extra arguments are redundant, |
418 * In principle, the name and extra arguments are redundant, |
406 * since each call site could be given its own unique bootstrap method. |
419 * since each call site could be given its own unique bootstrap method. |
407 * Such a practice is likely to produce large class files and constant pools. |
420 * Such a practice is likely to produce large class files and constant pools. |
408 * |
|
409 * <p style="font-size:smaller;"> |
|
410 * <em>PROVISIONAL API, WORK IN PROGRESS:</em> |
|
411 * (Usage Note: There is no mechanism for specifying five or more positional arguments to the bootstrap method. |
|
412 * If there are two or more arguments, the Java code of the bootstrap method is required to extract them from |
|
413 * a varargs-style object array. |
|
414 * This design uses varargs because it anticipates some use cases where bootstrap arguments |
|
415 * contribute components of variable-length structures, such as virtual function tables |
|
416 * or interpreter token streams. |
|
417 * Such parameters would be awkward or impossible to manage if represented |
|
418 * as normal positional method arguments, |
|
419 * since there would need to be one Java method per length. |
|
420 * On balance, leaving out the varargs feature would cause more trouble to users than keeping it. |
|
421 * Also, this design allows bootstrap methods to be called in a limited JVM stack depth. |
|
422 * At both the user and JVM level, the difference between varargs and non-varargs |
|
423 * calling sequences can easily be bridged via the |
|
424 * {@link java.dyn.MethodHandle#asSpreader asSpreader} |
|
425 * and {@link java.dyn.MethodHandle#asSpreader asCollector} methods.) |
|
426 * |
421 * |
427 * <h2><a name="structs"></a>Structure Summary</h2> |
422 * <h2><a name="structs"></a>Structure Summary</h2> |
428 * <blockquote><pre>// summary of constant and attribute structures |
423 * <blockquote><pre>// summary of constant and attribute structures |
429 struct CONSTANT_MethodHandle_info { |
424 struct CONSTANT_MethodHandle_info { |
430 u1 tag = 15; |
425 u1 tag = 15; |