* Each instance of an {@code invokedynamic} instruction is called a dynamic call site. @@ -76,39 +76,38 @@ * no target method for the call site to invoke. * A dynamic call site is linked by means of a bootstrap method, * as described below. - *
- * (Historic Note: Some older JVMs may allow the index of a {@code CONSTANT_NameAndType}
+ *
+ *
+ * (Historic Note: Some older JVMs may allow the index of a {@code CONSTANT_NameAndType}
* instead of a {@code CONSTANT_InvokeDynamic}. In earlier, obsolete versions of this API, the
- * bootstrap method was specified dynamically, in a per-class basis, during class initialization.)
* The first index specifies a bootstrap method used by the associated dynamic call sites. * The second index specifies the method name, argument types, and return type of the dynamic call site. * The structure of such an entry is therefore analogous to a {@code CONSTANT_Methodref}, - * except that the bootstrap method reference replaces + * except that the bootstrap method specifier reference replaces * the {@code CONSTANT_Class} reference of a {@code CONSTANT_Methodref} entry. - * The remaining indexes (if there is a non-zero count) specify - * additional static arguments for the bootstrap method. *
* Some older JVMs may allow an older constant pool entry tag of decimal 17. * The format and behavior of a constant pool entry with this tag is identical to - * an entry with a tag of decimal 18, except that the constant pool entry must not - * contain extra static arguments or a static argument count. - * The fixed size of such an entry is therefore four bytes after the tag. - * The value of the missing static argument count is taken to be zero. - * (Note: The Proposed Final Draft of this specification is not likely to support - * both of these formats.) + * an entry with a tag of decimal 18, except that the first index refers directly + * to a {@code CONSTANT_MethodHandle} to use as the bootstrap method. + * This format does not require the bootstrap method table. + * + *
+ * (Note: The Proposed Final Draft of this specification is likely to support + * only the tag 18, not the tag 17.) * *
* After resolution, the linkage process may fail in a variety of ways. * All failures are reported by an {@link java.dyn.InvokeDynamicBootstrapError InvokeDynamicBootstrapError}, @@ -248,7 +247,12 @@ * site execution. * The following circumstances will cause this: *
- * Note: Unlike some previous versions of this specification,
+ *
+ *
+ * (Historic Note: Unlike some previous versions of this specification,
* these rules do not enable the JVM to duplicate dynamic call sites,
* or to issue “causeless” bootstrap method calls.
* Every dynamic call site transitions at most once from unlinked to linked,
- * just before its first invocation.
+ * Each bootstrap method specifier contains an index to a + * {@code CONSTANT_MethodHandle} constant, which is the bootstrap + * method itself. + * This is followed by a count, and then a sequence (perhaps empty) of + * indexes to additional static arguments + * for the bootstrap method. + *
+ * During class loading, the verifier must check the structure of the + * {@code BootstrapMethods} attribute. In particular, each constant + * pool index must be of the correct type. A bootstrap method index + * must refer to a {@code CONSTANT_MethodHandle} (tag 15). + * Every other index must refer to a valid operand of an + * {@code ldc_w} or {@code ldc2_w} instruction (tag 3..8 or 15..16). * *
- * The third byte pair in a {@code CONSTANT_InvokeDynamic} entry, if it is not zero, - * counts up to 65535 additional constant pool indexes which contribute to a static argument. - * Each of these indexes must refer to one of a type of constant entry which is compatible with - * the {@code ldc} instruction. + * Static arguments are specified constant pool indexes stored in the {@code BootstrapMethods} attribute. * Before the bootstrap method is invoked, each index is used to compute an {@code Object} * reference to the indexed value in the constant pool. * If the value is a primitive type, it is converted to a reference by boxing conversion. @@ -371,10 +396,58 @@ * In principle, the name and extra arguments are redundant, * since each call site could be given its own unique bootstrap method. * Such a practice is likely to produce large class files and constant pools. + * + *
+ * (Usage Note: There is no mechanism for specifying five or more positional arguments to the bootstrap method. + * If there are two or more arguments, the Java code of the bootstrap method is required to extract them from + * a varargs-style object array. + * This design uses varargs because it anticipates some use cases where bootstrap arguments + * contribute components of variable-length structures, such as virtual function tables + * or interpreter token streams. + * Such parameters would be awkward or impossible to manage if represented + * as normal positional method arguments, + * since there would need to be one Java method per length. + * On balance, leaving out the varargs feature would cause more trouble to users than keeping it. + * Also, this design allows bootstrap methods to be called in a limited JVM stack depth. + * At both the user and JVM level, the difference between varargs and non-varargs + * calling sequences can easily be bridged via the + * {@link java.dyn.MethodHandle#asSpreader asSpreader} + * and {@link java.dyn.MethodHandle#asSpreader asCollector} methods.) + * + *
// summary of constant and attribute structures
+struct CONSTANT_MethodHandle_info {
+ u1 tag = 15;
+ u1 reference_kind; // 1..8 (one of REF_invokeVirtual, etc.)
+ u2 reference_index; // index to CONSTANT_Fieldref or *Methodref
+}
+struct CONSTANT_MethodType_info {
+ u1 tag = 16;
+ u2 descriptor_index; // index to CONSTANT_Utf8, as in NameAndType
+}
+struct CONSTANT_InvokeDynamic_17_info {
+ u1 tag = 17;
+ u2 bootstrap_method_index; // index to CONSTANT_MethodHandle
+ u2 name_and_type_index; // same as for CONSTANT_Methodref, etc.
+}
+struct CONSTANT_InvokeDynamic_info {
+ u1 tag = 18;
+ u2 bootstrap_method_attr_index; // index into BootstrapMethods_attr
+ u2 name_and_type_index; // index to CONSTANT_NameAndType, as in Methodref
+}
+struct BootstrapMethods_attr {
+ u2 name; // CONSTANT_Utf8 = "BootstrapMethods"
+ u4 size;
+ u2 bootstrap_method_count;
+ struct bootstrap_method_specifier {
+ u2 bootstrap_method_ref; // index to CONSTANT_MethodHandle
+ u2 bootstrap_argument_count;
+ u2 bootstrap_arguments[bootstrap_argument_count]; // constant pool indexes
+ } bootstrap_methods[bootstrap_method_count];
+}
+ * - * The Proposed Final Draft of JSR 292 may remove extra static arguments, - * with the associated constant tag of 18, leaving the constant tag 17. - * If the constant tag of 18 is retained, the constant tag 17 may be removed + * Note: The Proposed Final Draft of JSR 292 may remove the constant tag 17, * for the sake of simplicity. * * @author John Rose, JSR 292 EG