*
* As described in the Java Virtual Machine Specification, | * As described in the Java Virtual Machine Specification, certain types in this package * certain types in this package have special relations to dynamic | * are given special treatment by the virtual machine: * language support in the virtual machine: < *
*
* Before the JVM can execute a dynamic call site (an {@code invokedynamic} instruction), | * Before the JVM can execute an {@code invokedynamic} instruction, * the call site must first be linked. | * the instruction must first be linked. * Linking is accomplished by calling a bootstrap method * Linking is accomplished by calling a bootstrap method * which is given the static information content of the call site, | * which is given the static information content of the call, * and which must produce a {@link java.lang.invoke.MethodHandle method handle} | * and which must produce a {@link java.lang.invoke.CallSite} * that gives the behavior of the call site. | * that gives the behavior of the invocation. *
*
* Each {@code invokedynamic} instruction statically specifies its own * Each {@code invokedynamic} instruction statically specifies its own * bootstrap method as a constant pool reference. * bootstrap method as a constant pool reference. * The constant pool reference also specifies the call site's name and type descriptor, | * The constant pool reference also specifies the invocation's name and method type descriptor, * just like {@code invokevirtual} and the other invoke instructions. | * just like {@code invokestatic} and the other invoke instructions. *
| * * Linking starts with resolving the constant pool entry for the | *
* The bootstrap method is invoked on at least three values: | * Each dynamically-computed constant statically specifies its own > * bootstrap method as a constant pool reference. > * The constant pool reference also specifies the constant's name and field type descriptor, > * just like {@code getstatic} and the other field reference instructions. > * (Roughly speaking, a dynamically-computed constant is to a dynamically-computed call site > * as a {@code CONSTANT_Fieldref} is to a {@code CONSTANT_Methodref}.) > * > *
*
* In all cases, bootstrap method invocation is as if by | * The bootstrap method is then invoked, as if by * {@link java.lang.invoke.MethodHandle#invokeWithArguments MethodHandle.invokeWithArguments}, | * {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke}, * (This is also equivalent to | * with the following arguments: * {@linkplain java.lang.invoke.MethodHandle#invoke generic invocation} | *
*
* For an {@code invokedynamic} instruction, the | * For a dynamically-computed call site, the returned result must be a non-null reference to a * returned result must be convertible to a non-null reference to a < * {@link java.lang.invoke.CallSite CallSite}. * {@link java.lang.invoke.CallSite CallSite}. * If the returned result cannot be converted to the expected type, < * {@link java.lang.BootstrapMethodError BootstrapMethodError} is thrown. < * The type of the call site's target must be exactly equal to the type * The type of the call site's target must be exactly equal to the type * derived from the dynamic call site's type descriptor and passed to | * derived from the invocation's type descriptor and passed to * the bootstrap method, otherwise a {@code BootstrapMethodError} is thrown. | * the bootstrap method. If these conditions are not met, a {@code BootstrapMethodError} is thro * On success the call site then becomes permanently linked to the dynamic call | * On success the call site then becomes permanently linked to the {@code invokedynamic} * site. | * instruction. *
*
* If an exception, {@code E} say, occurs when linking the call site then the | * For a dynamically-computed constant, the result of the bootstrap method is cached * linkage fails and terminates abnormally. {@code E} is rethrown if the type of | * as the resolved constant value. > *
> * If an exception, {@code E} say, occurs during execution of the bootstrap method, then > * resolution fails and terminates abnormally. {@code E} is rethrown if the type of * {@code E} is {@code Error} or a subclass, otherwise a * {@code E} is {@code Error} or a subclass, otherwise a * {@code BootstrapMethodError} that wraps {@code E} is thrown. * {@code BootstrapMethodError} that wraps {@code E} is thrown. * If this happens, the same {@code Error} or subclass will the thrown for all | * If this happens, the same error will be thrown for all * subsequent attempts to execute the dynamic call site. | * subsequent attempts to execute the {@code invokedynamic} instruction or load the *
*
* If there are several such threads, the bootstrap method may be * If there are several such threads, the bootstrap method may be * invoked in several threads concurrently. * invoked in several threads concurrently. * Therefore, bootstrap methods which access global application * Therefore, bootstrap methods which access global application * data must take the usual precautions against race conditions. * data must take the usual precautions against race conditions. * In any case, every {@code invokedynamic} instruction is either * In any case, every {@code invokedynamic} instruction is either * unlinked or linked to a unique {@code CallSite} object. * unlinked or linked to a unique {@code CallSite} object. *
*
* In an application which requires dynamic call sites with individually | * In an application which requires {@code invokedynamic} instructions with individually * mutable behaviors, their bootstrap methods should produce distinct * mutable behaviors, their bootstrap methods should produce distinct * {@link java.lang.invoke.CallSite CallSite} objects, one for each linkage request. * {@link java.lang.invoke.CallSite CallSite} objects, one for each linkage request. * Alternatively, an application can link a single {@code CallSite} object * Alternatively, an application can link a single {@code CallSite} object * to several {@code invokedynamic} instructions, in which case * to several {@code invokedynamic} instructions, in which case * a change to the target method will become visible at each of * a change to the target method will become visible at each of * the instructions. * the instructions. *
*
* If several threads simultaneously execute a bootstrap method for a single dynamic | * If several threads simultaneously execute a bootstrap method for a single dynamically-compute * call site, the JVM must choose one {@code CallSite} object and install it visibly to | * call site or constant, the JVM must choose one bootstrap method result and install it visibly * all threads. Any other bootstrap method calls are allowed to complete, but their * all threads. Any other bootstrap method calls are allowed to complete, but their * results are ignored, and their dynamic call site invocations proceed with the originally | * results are ignored. * chosen target object. < *
*
* Discussion: * Discussion: * These rules do not enable the JVM to duplicate dynamic call sites, | * These rules do not enable the JVM to share call sites, * or to issue “causeless” bootstrap method calls. * or to issue “causeless” bootstrap method calls. * Every dynamic call site transitions at most once from unlinked to linked, | * Every {@code invokedynamic} instruction transitions at most once from unlinked to linked, * just before its first invocation. * just before its first invocation. * There is no way to undo the effect of a completed bootstrap method call. * There is no way to undo the effect of a completed bootstrap method call. * * *
< * If a given {@code invokedynamic} instruction specifies no static arguments, < * the instruction's bootstrap method will be invoked on three arguments, < * conveying the instruction's caller class, name, and method type. < * If the {@code invokedynamic} instruction specifies one or more static arguments, < * those values will be passed as additional arguments to the method handle. < * (Note that because there is a limit of 255 arguments to any method, < * at most 251 extra arguments can be supplied to a non-varargs bootstrap method, < * since the bootstrap method < * handle itself and its first three arguments must also be stacked.) < * The bootstrap method will be invoked as if by {@code MethodHandle.invokeWithArguments}. < * A variable-arity bootstrap method can accept thousands of static arguments, < * subject only by limits imposed by the class-file format. < *
*
* The normal argument conversion rules for {@code MethodHandle.invoke} apply to all stacked arg | * If a pushed value is a primitive type, it may be converted to a reference by boxing conversio * For example, if a pushed value is a primitive type, it may be converted to a reference by box < * If the bootstrap method is a variable arity method (its modifier bit {@code 0x0080} is set), * If the bootstrap method is a variable arity method (its modifier bit {@code 0x0080} is set), * then some or all of the arguments specified here may be collected into a trailing array param * then some or all of the arguments specified here may be collected into a trailing array param * (This is not a special rule, but rather a useful consequence of the interaction * (This is not a special rule, but rather a useful consequence of the interaction * between {@code CONSTANT_MethodHandle} constants, the modifier bit for variable arity methods, * between {@code CONSTANT_MethodHandle} constants, the modifier bit for variable arity methods, * and the {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transform * and the {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transform *
*
* Given these rules, here are examples of legal bootstrap method declarations, | * Given these rules, here are examples of legal bootstrap method declarations for * given various numbers {@code N} of extra arguments. | * dynamically-computed call sites, given various numbers {@code N} of extra arguments. * The first row (marked {@code *}) will work for any number of extra arguments. * The first row (marked {@code *}) will work for any number of extra arguments. *
| N | Sample bootstrap method |
|---|---|
| N | Sample bootstrap method |
| * | * |
| * |
*
|
| 0 | * |
| 0 |
*
|
| 1 | * |
| 1 |
* CallSite bootstrap(Lookup caller, String name, MethodType type, Object arg)< * CallSite bootstrap(Lookup caller, String name, MethodType type, Object arg)<
* |
| 2 | * |
| 2 |
*
|
*
* As noted above, the actual method type of the bootstrap method can vary. | * Since dynamically-computed constants can be provided as static arguments to bootstrap * For example, the fourth argument could be {@code MethodHandle}, | * methods, there are no limitations on the types of bootstrap arguments. * if that is the type of the corresponding constant in < * the {@code CONSTANT_InvokeDynamic} entry. < * In that case, the {@code MethodHandle.invoke} call will pass the extra method handle < * constant as an {@code Object}, but the type matching machinery of {@code MethodHandle.invoke} < * will cast the reference back to {@code MethodHandle} before invoking the bootstrap method. < * (If a string constant were passed instead, by badly generated code, that cast would then fail < * resulting in a {@code BootstrapMethodError}.) < *
< * Note that, as a consequence of the above rules, the bootstrap method may accept a primitive < * argument, if it can be represented by a constant pool entry. < * However, arguments of type {@code boolean}, {@code byte}, {@code short}, or {@code char} * However, arguments of type {@code boolean}, {@code byte}, {@code short}, or {@code char} * cannot be created for bootstrap methods, since such constants cannot be directly | * cannot be directly supplied by {@code CONSTANT_Integer} * represented in the constant pool, and the invocation of the bootstrap method will | * constant pool entries, since the {@code asType} conversions do * not perform the necessary narrowing primitive conversions. * not perform the necessary narrowing primitive conversions. *
*
* Extra bootstrap method arguments are intended to allow language implementors | * In the above examples, the return type is always {@code CallSite}, * to safely and compactly encode metadata. | * but that is not a necessary feature of bootstrap methods. * In principle, the name and extra arguments are redundant, | * In the case of a dynamically-computed call site, the only requirement is that * since each call site could be given its own unique bootstrap method. | * the return type of the bootstrap method must be convertible * Such a practice would be likely to produce large class files and constant pools. | * (using the {@code asType} conversions) to {@code CallSite}, which > * means the bootstrap method return type might be {@code Object} or > * {@code ConstantCallSite}. > * In the case of a dynamically-resolved constant, the return type of the bootstrap > * method must be convertible to the type of the constant, as > * represented by its field type descriptor. For example, if the > * dynamic constant has a field type descriptor of {@code "C"} > * ({@code char}) then the bootstrap method return type could be > * {@code Object}, {@code Character}, or {@code char}, but not > * {@code int} or {@code Integer}. * * * @author John Rose, JSR 292 EG * @author John Rose, JSR 292 EG * @since 1.7 * @since 1.7 */ */ package java.lang.invoke; package java.lang.invoke;