diff -r ef8a98bc71f8 -r c4d9d1b08e2e src/java.base/share/classes/java/lang/invoke/package-info.java --- a/src/java.base/share/classes/java/lang/invoke/package-info.java Wed Jan 31 10:55:49 2018 -0800 +++ b/src/java.base/share/classes/java/lang/invoke/package-info.java Fri Sep 08 10:46:46 2017 -0700 @@ -24,13 +24,12 @@ */ /** - * The {@code java.lang.invoke} package contains dynamic language support provided directly by - * the Java core class libraries and virtual machine. + * The {@code java.lang.invoke} package provides low-level primitives for interacting + * with the Java Virtual Machine. * *

- * As described in the Java Virtual Machine Specification, - * certain types in this package have special relations to dynamic - * language support in the virtual machine: + * As described in the Java Virtual Machine Specification, certain types in this package + * are given special treatment by the virtual machine: *

* - *

Summary of relevant Java Virtual Machine changes

+ *

Dynamic resolution of call sites and constants

* The following low-level information summarizes relevant parts of the * Java Virtual Machine specification. For full details, please see the * current version of that specification. * - * Each occurrence of an {@code invokedynamic} instruction is called a dynamic call site. - *

{@code invokedynamic} instructions

- * A dynamic call site is originally in an unlinked state. In this state, there is - * no target method for the call site to invoke. + *

Dynamically-computed call sites

+ * An {@code invokedynamic} instruction is originally in an unlinked state. + * In this state, there is no target method for the instruction to invoke. *

- * Before the JVM can execute a dynamic call site (an {@code invokedynamic} instruction), - * the call site must first be linked. + * Before the JVM can execute an {@code invokedynamic} instruction, + * the instruction must first be linked. * Linking is accomplished by calling a bootstrap method - * which is given the static information content of the call site, - * and which must produce a {@link java.lang.invoke.MethodHandle method handle} - * that gives the behavior of the call site. + * which is given the static information content of the call, + * and which must produce a {@link java.lang.invoke.CallSite} + * that gives the behavior of the invocation. *

* Each {@code invokedynamic} instruction statically specifies its own * bootstrap method as a constant pool reference. - * The constant pool reference also specifies the call site's name and type descriptor, - * just like {@code invokevirtual} and the other invoke instructions. + * The constant pool reference also specifies the invocation's name and method type descriptor, + * just like {@code invokestatic} and the other invoke instructions. + * + *

Dynamically-computed constants

+ * The constant pool may contain constants tagged {@code CONSTANT_Dynamic}, + * equipped with bootstrap methods which perform their resolution. + * Such a dynamic constant is originally in an unresolved state. + * Before the JVM can use a dynamically-computed constant, it must first be resolved. + * Dynamically-computed constant resolution is accomplished by calling a bootstrap method + * which is given the static information content of the constant, + * and which must produce a value of the constant's statically declared type. *

- * Linking starts with resolving the constant pool entry for the - * bootstrap method, and resolving a {@link java.lang.invoke.MethodType MethodType} object for - * the type descriptor of the dynamic call site. - * This resolution process may trigger class loading. - * It may therefore throw an error if a class fails to load. - * This error becomes the abnormal termination of the dynamic - * call site execution. - * Linkage does not trigger class initialization. - *

- * 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}.) + * + *

Execution of bootstrap methods

+ * Resolving a dynamically-computed call site or constant + * starts with resolving constants from the constant pool for the + * following items: * *

- * In all cases, bootstrap method invocation is as if by - * {@link java.lang.invoke.MethodHandle#invokeWithArguments MethodHandle.invokeWithArguments}, - * (This is also equivalent to - * {@linkplain java.lang.invoke.MethodHandle#invoke generic invocation} - * if the number of arguments is small enough.) + * The bootstrap method is then invoked, as if by + * {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke}, + * with the following arguments: + *

*

- * For an {@code invokedynamic} instruction, the - * returned result must be convertible to a non-null reference to a + * For a dynamically-computed call site, the returned result must be a non-null reference to a * {@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 - * derived from the dynamic call site's type descriptor and passed to - * the bootstrap method, otherwise a {@code BootstrapMethodError} is thrown. - * On success the call site then becomes permanently linked to the dynamic call - * site. + * derived from the invocation's type descriptor and passed to + * the bootstrap method. If these conditions are not met, a {@code BootstrapMethodError} is thrown. + * On success the call site then becomes permanently linked to the {@code invokedynamic} + * instruction. *

- * If an exception, {@code E} say, occurs when linking the call site then the - * linkage fails and terminates abnormally. {@code E} is rethrown if the type of + * For a dynamically-computed constant, the result of the bootstrap method is cached + * 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 BootstrapMethodError} that wraps {@code E} is thrown. - * If this happens, the same {@code Error} or subclass will the thrown for all - * subsequent attempts to execute the dynamic call site. - *

timing of linkage

- * A dynamic call site is linked just before its first execution. + * If this happens, the same error will be thrown for all + * subsequent attempts to execute the {@code invokedynamic} instruction or load the + * dynamically-computed constant. + * + *

Timing of resolution

+ * An {@code invokedynamic} instruction is linked just before its first execution. + * A dynamically-computed constant is resolved just before the first time it is used + * (by pushing it on the stack or linking it as a bootstrap method parameter). * The bootstrap method call implementing the linkage occurs within - * a thread that is attempting a first execution. + * a thread that is attempting a first execution or first use. *

* If there are several such threads, the bootstrap method may be * invoked in several threads concurrently. @@ -119,7 +147,7 @@ * In any case, every {@code invokedynamic} instruction is either * 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 * {@link java.lang.invoke.CallSite CallSite} objects, one for each linkage request. * Alternatively, an application can link a single {@code CallSite} object @@ -127,53 +155,46 @@ * a change to the target method will become visible at each of * the instructions. *

- * If several threads simultaneously execute a bootstrap method for a single dynamic - * call site, the JVM must choose one {@code CallSite} object and install it visibly to + * If several threads simultaneously execute a bootstrap method for a single dynamically-computed + * call site or constant, the JVM must choose one bootstrap method result and install it visibly to * 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 - * chosen target object. + * results are ignored. *

* 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. - * 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. * There is no way to undo the effect of a completed bootstrap method call. * - *

types of bootstrap methods

- * As long as each bootstrap method can be correctly invoked - * by {@code MethodHandle.invoke}, its detailed type is arbitrary. + *

Types of bootstrap methods

+ * For a dynamically-computed call site, the bootstrap method is invoked with parameter + * types {@code MethodHandles.Lookup}, {@code String}, {@code MethodType}, and the types + * of any static arguments; the return type is {@code CallSite}. For a + * dynamically-computed constant, the bootstrap method is invoked with parameter types + * {@code MethodHandles.Lookup}, {@code String}, {@code Class}, and the types of any + * static arguments; the return type is the type represented by the {@code Class}. + * + * Because {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke} allows for + * adaptations between the invoked method type and the method handle's method type, + * there is flexibility in the declaration of the bootstrap method. * For example, the first argument could be {@code Object} * instead of {@code MethodHandles.Lookup}, and the return type * could also be {@code Object} instead of {@code CallSite}. * (Note that the types and number of the stacked arguments limit * the legal kinds of bootstrap methods to appropriately typed - * static methods and constructors of {@code CallSite} subclasses.) + * static methods and constructors.) *

- * 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 arguments. - * For example, if a pushed value is a primitive type, it may be converted to a reference by boxing conversion. + * If a pushed value is a primitive type, it may be converted to a reference by boxing conversion. * 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 parameter. * (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, * and the {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transformation.) *

- * Given these rules, here are examples of legal bootstrap method declarations, - * given various numbers {@code N} of extra arguments. + * Given these rules, here are examples of legal bootstrap method declarations for + * 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. * * @@ -208,28 +229,27 @@ * {@code String}. * The other examples work with all types of extra arguments. *

- * As noted above, the actual method type of the bootstrap method can vary. - * For example, the fourth argument could be {@code MethodHandle}, - * 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. + * Since dynamically-computed constants can be provided as static arguments to bootstrap + * methods, there are no limitations on the types of bootstrap arguments. * 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 - * represented in the constant pool, and the invocation of the bootstrap method will + * cannot be directly supplied by {@code CONSTANT_Integer} + * constant pool entries, since the {@code asType} conversions do * not perform the necessary narrowing primitive conversions. *

- * Extra bootstrap method arguments are intended to allow language implementors - * to safely and compactly encode metadata. - * In principle, the name and extra arguments are redundant, - * since each call site could be given its own unique bootstrap method. - * Such a practice would be likely to produce large class files and constant pools. + * In the above examples, the return type is always {@code CallSite}, + * but that is not a necessary feature of bootstrap methods. + * In the case of a dynamically-computed call site, the only requirement is that + * the return type of the bootstrap method must be convertible + * (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 * @since 1.7

Static argument types