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