* Certain types in this package have special relations to dynamic * language support in the virtual machine: *
* Each instance of an {@code invokedynamic} instruction is called a dynamic call site. * Multiple instances of an {@code invokedynamic} instruction can share a single * {@code CONSTANT_InvokeDynamic} entry. * In any case, distinct call sites always have distinct linkage state. *
* A dynamic call site is originally in an unlinked state. In this state, there is * 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} * 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 specifier reference replaces * the {@code CONSTANT_Class} reference of a {@code CONSTANT_Methodref} entry. *
* 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 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.) * *
* The JVM will ensure that on first * execution of an {@code ldc} instruction for this entry, a {@link java.dyn.MethodType MethodType} * will be created which represents the signature. * Any classes mentioned in the {@code MethodType} will be loaded if necessary, * but not initialized. * Access checking and error reporting is performed exactly as it is for * references by {@code ldc} instructions to {@code CONSTANT_Class} constants. * *
* The JVM will ensure that on first execution of an {@code ldc} instruction * for this entry, a {@link java.dyn.MethodHandle MethodHandle} will be created which represents * the field or method reference, according to the specific mode implied by the subtag. *
* As with {@code CONSTANT_Class} and {@code CONSTANT_MethodType} constants, * the {@code Class} or {@code MethodType} object which reifies the field or method's * type is created. Any classes mentioned in this reification will be loaded if necessary, * but not initialized, and access checking and error reporting performed as usual. *
* The method handle itself will have a type and behavior determined by the subtag as follows:
*
*
*
*
* N subtag name member MH type MH behavior 1 REF_getField C.f:T (C)T getfield C.f:T 2 REF_getStatic C.f:T ( )T getstatic C.f:T 3 REF_putField C.f:T (C,T)void putfield C.f:T 4 REF_putStatic C.f:T (T)void putstatic C.f:T 5 REF_invokeVirtual C.m(A*)T (C,A*)T invokevirtual C.m(A*)T 6 REF_invokeStatic C.m(A*)T (C,A*)T invokestatic C.m(A*)T 7 REF_invokeSpecial C.m(A*)T (C,A*)T invokespecial C.m(A*)T 8 REF_newInvokeSpecial C.<init>(A*)void (A*)C new C; dup; invokespecial C.<init>(A*)void 9 REF_invokeInterface C.m(A*)T (C,A*)T invokeinterface C.m(A*)T
* The special name {@code
* The JVM verifier and linker apply the same access checks and restrictions for these references as for the hypothetical
* bytecode instructions specified in the last column of the table. In particular, method handles to
* private and protected members can be created in exactly those classes for which the corresponding
* normal accesses are legal.
*
* A constant may refer to a method or constructor with the {@code varargs}
* bit (hexadecimal {@code 80}) set in its modifier bitmask.
* The method handle constant produced for such a method behaves the same
* as if the {@code varargs} bit were not set.
* The argument-collecting behavior of {@code varargs} can be emulated by
* adapting the method handle constant with
* {@link java.dyn.MethodHandle#asCollector asCollector}.
* There is no provision for doing this automatically.
*
* Although the {@code CONSTANT_MethodHandle} and {@code CONSTANT_MethodType} constant types
* resolve class names, they do not force class initialization.
* Method handle constants for subtags {@code REF_getStatic}, {@code REF_putStatic}, and {@code REF_invokeStatic}
* may force class initialization on their first invocation, just like the corresponding bytecodes.
*
* The rules of section 5.4.3 of the
* JVM Specification
* apply to the resolution of {@code CONSTANT_MethodType}, {@code CONSTANT_MethodHandle},
* and {@code CONSTANT_InvokeDynamic} constants,
* by the execution of {@code invokedynamic} and {@code ldc} instructions.
* (Roughly speaking, this means that every use of a constant pool entry
* must lead to the same outcome.
* If the resoultion succeeds, the same object reference is produced
* by every subsequent execution of the same instruction.
* If the resolution of the constant causes an error to occur,
* the same error will be re-thrown on every subsequent attempt
* to use this particular constant.)
*
* Constants created by the resolution of these constant pool types are not necessarily
* interned. Except for {@link CONSTANT_Class} and {@link CONSTANT_String} entries,
* two distinct constant pool entries might not resolve to the same reference
* even if they contain the same symbolic reference.
*
*
* 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 signature,
* just like {@code invokevirtual} and the other invoke instructions.
*
* Linking starts with resolving the constant pool entry for the
* bootstrap method, and resolving a {@link java.dyn.MethodType MethodType} object for
* the type signature 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.
*
* Next, the bootstrap method call is started, with four or five values being stacked:
*
* As long as each bootstrap method can be correctly invoked
* by
* As with any method handle constant, a {@code varargs} modifier bit
* on the bootstrap method is ignored.
*
* Note that the first argument of the bootstrap method cannot be
* a simple {@code Class} reference. (This is a change from earlier
* versions of this specification. If the caller class is needed,
* it is easy to {@linkplain java.dyn.MethodHandles.Lookup#lookupClass() extract it}
* from the {@code Lookup} object.)
*
* After resolution, the linkage process may fail in a variety of ways.
* All failures are reported by an {@link java.dyn.InvokeDynamicBootstrapError InvokeDynamicBootstrapError},
* which is thrown as the abnormal termination of the dynamic call
* site execution.
* The following circumstances will cause this:
*
* If there are several such threads, the bootstrap method may be
* invoked in several threads concurrently.
* Therefore, bootstrap methods which access global application
* data must take the usual precautions against race conditions.
* 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
* mutable behaviors, their bootstrap methods should produce distinct
* {@link java.dyn.CallSite CallSite} objects, one for each linkage request.
* Alternatively, an application can link a single {@code CallSite} object
* to several {@code invokedynamic} instructions, in which case
* 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
* 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.
*
*
* (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).
*
*
* Static arguments are used to communicate application-specific meta-data
* to the bootstrap method.
* Drawn from the constant pool, they may include references to classes, method handles,
* strings, or numeric data that may be relevant to the task of linking that particular call site.
*
* 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.
* The valid constant pool entries are listed in this table:
*
* 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,
* a fourth argument will be passed to the bootstrap argument,
* either an {@code Object} reference to the sole extra argument (if there is one)
* or an {@code Object} array of references to all the arguments (if there are two or more),
* as if the bootstrap method is a variable-arity method.
*
* The argument and return types listed here are used by the {@code invokeGeneric}
* call to the bootstrap method.
* 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 invokeGeneric} call will pass the extra method handle
* constant as an {@code Object}, but the type matching machinery of {@code invokeGeneric}
* 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.)
*
* If the fourth argument is an array, the array element type must be {@code Object},
* since object arrays (as produced by the JVM at this point) cannot be converted
* to other array types.
*
* If an array is provided, it will appear to be freshly allocated.
* That is, the same array will not appear to two bootstrap method calls.
*
* 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 is likely to produce large class files and constant pools.
*
*
* PROVISIONAL API, WORK IN PROGRESS:
* (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.)
*
*
* 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
*/
package java.dyn;
Bootstrap Methods
* Before the JVM can execute a dynamic call site (an {@code invokedynamic} instruction),
* the call site 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.dyn.MethodHandle method handle}
* that gives the behavior of the call site.
*
*
* The method handle is then applied to the other values as if by
* {@link java.dyn.MethodHandle#invokeGeneric invokeGeneric}.
* The returned result must be a {@link java.dyn.CallSite CallSite} (or a subclass).
* The type of the call site's target must be exactly equal to the type
* derived from the dynamic call site signature and passed to
* the bootstrap method.
* The call site then becomes permanently linked to the dynamic call site.
* invokeGeneric, its detailed type is arbitrary.
* 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}.
*
*
*
* timing of linkage
* A dynamic call site is linked just before its first execution.
* The bootstrap method call implementing the linkage occurs within
* a thread that is attempting a first execution.
* the {@code BootstrapMethods} attribute
* Each {@code CONSTANT_InvokeDynamic} entry contains an index which references
* a bootstrap method specifier; all such specifiers are contained in a separate array.
* This array is defined by a class attribute named {@code BootstrapMethods}.
* The body of this attribute consists of a sequence of byte pairs, all interpreted as
* as 16-bit counts or constant pool indexes, in the {@code u2} format.
* The attribute body starts with a count of bootstrap method specifiers,
* which is immediately followed by the sequence of specifiers.
* static arguments to the bootstrap method
* An {@code invokedynamic} instruction specifies at least three arguments
* to pass to its bootstrap method:
* The caller class (expressed as a {@link java.dyn.MethodHandles.Lookup Lookup object},
* the name (extracted from the {@code CONSTANT_NameAndType} entry),
* and the type (also extracted from the {@code CONSTANT_NameAndType} entry).
* The {@code invokedynamic} instruction may specify additional metadata values
* to pass to its bootstrap method.
* Collectively, these values are called static arguments to the
* {@code invokedynamic} instruction, because they are used once at link
* time to determine the instruction's behavior on subsequent sets of
* dynamic arguments.
*
*
*
*
* entry type argument type argument value CONSTANT_String java.lang.Stringthe indexed string literal CONSTANT_Class java.lang.Classthe indexed class, resolved CONSTANT_Integer java.lang.Integerthe indexed int value CONSTANT_Long java.lang.Longthe indexed long value CONSTANT_Float java.lang.Floatthe indexed float value CONSTANT_Double java.lang.Doublethe indexed double value CONSTANT_MethodHandle java.dyn.MethodHandlethe indexed method handle constant CONSTANT_MethodType java.dyn.MethodTypethe indexed method type constant
*
*
*
* N sample bootstrap method 0 CallSite bootstrap(Lookup caller, String name, MethodType type)1 CallSite bootstrap(Lookup caller, String name, MethodType type, Object arg)2 CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)Structure Summary
*
* // 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];
}
*