jaroslav@1646: * As described in the Java Virtual Machine Specification, jaroslav@1646: * certain types in this package have special relations to dynamic jaroslav@1646: * language support in the virtual machine: jaroslav@1646: *
jaroslav@1646: * Before the JVM can execute a dynamic call site (an {@code invokedynamic} instruction), jaroslav@1646: * the call site must first be linked. jaroslav@1646: * Linking is accomplished by calling a bootstrap method jaroslav@1646: * which is given the static information content of the call site, jaroslav@1646: * and which must produce a {@link java.lang.invoke.MethodHandle method handle} jaroslav@1646: * that gives the behavior of the call site. jaroslav@1646: *
jaroslav@1646: * Each {@code invokedynamic} instruction statically specifies its own jaroslav@1646: * bootstrap method as a constant pool reference. jaroslav@1646: * The constant pool reference also specifies the call site's name and type descriptor, jaroslav@1646: * just like {@code invokevirtual} and the other invoke instructions. jaroslav@1646: *
jaroslav@1646: * Linking starts with resolving the constant pool entry for the jaroslav@1646: * bootstrap method, and resolving a {@link java.lang.invoke.MethodType MethodType} object for jaroslav@1646: * the type descriptor of the dynamic call site. jaroslav@1646: * This resolution process may trigger class loading. jaroslav@1646: * It may therefore throw an error if a class fails to load. jaroslav@1646: * This error becomes the abnormal termination of the dynamic jaroslav@1646: * call site execution. jaroslav@1646: * Linkage does not trigger class initialization. jaroslav@1646: *
jaroslav@1646: * The bootstrap method is invoked on at least three values: jaroslav@1646: *
jaroslav@1646: * As documented in the JVM specification, all failures arising from jaroslav@1646: * the linkage of a dynamic call site are reported jaroslav@1646: * by a {@link java.lang.BootstrapMethodError BootstrapMethodError}, jaroslav@1646: * which is thrown as the abnormal termination of the dynamic call jaroslav@1646: * site execution. jaroslav@1646: * If this happens, the same error will the thrown for all subsequent jaroslav@1646: * attempts to execute the dynamic call site. jaroslav@1646: * jaroslav@1646: *
jaroslav@1646: * If there are several such threads, the bootstrap method may be jaroslav@1646: * invoked in several threads concurrently. jaroslav@1646: * Therefore, bootstrap methods which access global application jaroslav@1646: * data must take the usual precautions against race conditions. jaroslav@1646: * In any case, every {@code invokedynamic} instruction is either jaroslav@1646: * unlinked or linked to a unique {@code CallSite} object. jaroslav@1646: *
jaroslav@1646: * In an application which requires dynamic call sites with individually jaroslav@1646: * mutable behaviors, their bootstrap methods should produce distinct jaroslav@1646: * {@link java.lang.invoke.CallSite CallSite} objects, one for each linkage request. jaroslav@1646: * Alternatively, an application can link a single {@code CallSite} object jaroslav@1646: * to several {@code invokedynamic} instructions, in which case jaroslav@1646: * a change to the target method will become visible at each of jaroslav@1646: * the instructions. jaroslav@1646: *
jaroslav@1646: * If several threads simultaneously execute a bootstrap method for a single dynamic jaroslav@1646: * call site, the JVM must choose one {@code CallSite} object and install it visibly to jaroslav@1646: * all threads. Any other bootstrap method calls are allowed to complete, but their jaroslav@1646: * results are ignored, and their dynamic call site invocations proceed with the originally jaroslav@1646: * chosen target object. jaroslav@1646: jaroslav@1646: *
jaroslav@1646: * Discussion: jaroslav@1646: * These rules do not enable the JVM to duplicate dynamic call sites, jaroslav@1646: * or to issue “causeless” bootstrap method calls. jaroslav@1646: * Every dynamic call site transitions at most once from unlinked to linked, jaroslav@1646: * just before its first invocation. jaroslav@1646: * There is no way to undo the effect of a completed bootstrap method call. jaroslav@1646: * jaroslav@1646: *
jaroslav@1646: * If a given {@code invokedynamic} instruction specifies no static arguments, jaroslav@1646: * the instruction's bootstrap method will be invoked on three arguments, jaroslav@1646: * conveying the instruction's caller class, name, and method type. jaroslav@1646: * If the {@code invokedynamic} instruction specifies one or more static arguments, jaroslav@1646: * those values will be passed as additional arguments to the method handle. jaroslav@1646: * (Note that because there is a limit of 255 arguments to any method, jaroslav@1646: * at most 251 extra arguments can be supplied, since the bootstrap method jaroslav@1646: * handle itself and its first three arguments must also be stacked.) jaroslav@1646: * The bootstrap method will be invoked as if by either {@code MethodHandle.invoke} jaroslav@1646: * or {@code invokeWithArguments}. (There is no way to tell the difference.) jaroslav@1646: *
jaroslav@1646: * The normal argument conversion rules for {@code MethodHandle.invoke} apply to all stacked arguments. jaroslav@1646: * For example, if a pushed value is a primitive type, it may be converted to a reference by boxing conversion. jaroslav@1646: * If the bootstrap method is a variable arity method (its modifier bit {@code 0x0080} is set), jaroslav@1646: * then some or all of the arguments specified here may be collected into a trailing array parameter. jaroslav@1646: * (This is not a special rule, but rather a useful consequence of the interaction jaroslav@1646: * between {@code CONSTANT_MethodHandle} constants, the modifier bit for variable arity methods, jaroslav@1646: * and the {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transformation.) jaroslav@1646: *
jaroslav@1646: * Given these rules, here are examples of legal bootstrap method declarations, jaroslav@1646: * given various numbers {@code N} of extra arguments. jaroslav@1646: * The first rows (marked {@code *}) will work for any number of extra arguments. jaroslav@1646: *
| N | sample bootstrap method |
|---|---|
| * | CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args) |
| * | CallSite bootstrap(Object... args) |
| * | CallSite bootstrap(Object caller, Object... nameAndTypeWithArgs) |
| 0 | CallSite bootstrap(Lookup caller, String name, MethodType type) |
| 0 | CallSite bootstrap(Lookup caller, Object... nameAndType) |
| 1 | CallSite bootstrap(Lookup caller, String name, MethodType type, Object arg) |
| 2 | CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args) |
| 2 | CallSite bootstrap(Lookup caller, String name, MethodType type, String... args) |
| 2 | CallSite bootstrap(Lookup caller, String name, MethodType type, String x, int y) |
jaroslav@1646: * As noted above, the actual method type of the bootstrap method can vary. jaroslav@1646: * For example, the fourth argument could be {@code MethodHandle}, jaroslav@1646: * if that is the type of the corresponding constant in jaroslav@1646: * the {@code CONSTANT_InvokeDynamic} entry. jaroslav@1646: * In that case, the {@code MethodHandle.invoke} call will pass the extra method handle jaroslav@1646: * constant as an {@code Object}, but the type matching machinery of {@code MethodHandle.invoke} jaroslav@1646: * will cast the reference back to {@code MethodHandle} before invoking the bootstrap method. jaroslav@1646: * (If a string constant were passed instead, by badly generated code, that cast would then fail, jaroslav@1646: * resulting in a {@code BootstrapMethodError}.) jaroslav@1646: *
jaroslav@1646: * Note that, as a consequence of the above rules, the bootstrap method may accept a primitive jaroslav@1646: * argument, if it can be represented by a constant pool entry. jaroslav@1646: * However, arguments of type {@code boolean}, {@code byte}, {@code short}, or {@code char} jaroslav@1646: * cannot be created for bootstrap methods, since such constants cannot be directly jaroslav@1646: * represented in the constant pool, and the invocation of the bootstrap method will jaroslav@1646: * not perform the necessary narrowing primitive conversions. jaroslav@1646: *
jaroslav@1646: * Extra bootstrap method arguments are intended to allow language implementors jaroslav@1646: * to safely and compactly encode metadata. jaroslav@1646: * In principle, the name and extra arguments are redundant, jaroslav@1646: * since each call site could be given its own unique bootstrap method. jaroslav@1646: * Such a practice is likely to produce large class files and constant pools. jaroslav@1646: * jaroslav@1646: * @author John Rose, JSR 292 EG jaroslav@1646: * @since 1.7 jaroslav@1646: */ jaroslav@1646: jaroslav@1646: package java.lang.invoke;