27  * The {@code java.lang.invoke} package contains dynamic language support provided directly by

    27  * The {@code java.lang.invoke} package provides low-level primitives for interacting

    28  * the Java core class libraries and virtual machine.

    28  * with the Java Virtual Machine.

    29  *

    29  *

    30  * <p>

    30  * <p>

    31  * As described in the Java Virtual Machine Specification,

    31  * As described in the Java Virtual Machine Specification, certain types in this package

    32  * certain types in this package have special relations to dynamic

    32  * are given special treatment by the virtual machine:

    33  * language support in the virtual machine:

    43  * the classes {@link java.lang.invoke.MethodHandle MethodHandle} and {@link java.lang.invoke.MethodType MethodType}.

    42  * the classes {@link java.lang.invoke.MethodHandle MethodHandle} and

    43  * {@link java.lang.invoke.MethodType MethodType}.

    44  * </li>

    45  *

    46  * <li>The {@code invokedynamic} instruction makes use of bootstrap {@code MethodHandle}

    47  * constants to dynamically resolve {@code CallSite} objects for custom method invocation

    48  * behavior.

    49  * </li>

    50  *

    51  * <li>The {@code ldc} instruction makes use of bootstrap {@code MethodHandle} constants

    52  * to dynamically resolve custom constant values.

    47  * <h1><a id="jvm_mods"></a>Summary of relevant Java Virtual Machine changes</h1>

    56  * <h1><a id="jvm_mods"></a>Dynamic resolution of call sites and constants</h1>

    52  * Each occurrence of an {@code invokedynamic} instruction is called a <em>dynamic call site</em>.

    61  * <h2><a id="indyinsn"></a>Dynamically-computed call sites</h2>

    53  * <h2><a id="indyinsn"></a>{@code invokedynamic} instructions</h2>

    62  * An {@code invokedynamic} instruction is originally in an unlinked state.

    54  * A dynamic call site is originally in an unlinked state.  In this state, there is

    63  * In this state, there is no target method for the instruction to invoke.

    55  * no target method for the call site to invoke.

    64  * <p>

    56  * <p>

    65  * Before the JVM can execute an {@code invokedynamic} instruction,

    57  * Before the JVM can execute a dynamic call site (an {@code invokedynamic} instruction),

    66  * the instruction must first be <em>linked</em>.

    58  * the call site must first be <em>linked</em>.

    60  * which is given the static information content of the call site,

    68  * which is given the static information content of the call,

    61  * and which must produce a {@link java.lang.invoke.MethodHandle method handle}

    69  * and which must produce a {@link java.lang.invoke.CallSite}

    62  * that gives the behavior of the call site.

    70  * that gives the behavior of the invocation.

    66  * The constant pool reference also specifies the call site's name and type descriptor,

    74  * The constant pool reference also specifies the invocation's name and method type descriptor,

    67  * just like {@code invokevirtual} and the other invoke instructions.

    75  * just like {@code invokestatic} and the other invoke instructions.

    68  * <p>

    76  *

    69  * Linking starts with resolving the constant pool entry for the

    77  * <h2><a id="condycon"></a>Dynamically-computed constants</h2>

    70  * bootstrap method, and resolving a {@link java.lang.invoke.MethodType MethodType} object for

    78  * The constant pool may contain constants tagged {@code CONSTANT_Dynamic},

    71  * the type descriptor of the dynamic call site.

    79  * equipped with bootstrap methods which perform their resolution.

    72  * This resolution process may trigger class loading.

    80  * Such a <em>dynamic constant</em> is originally in an unresolved state.

    73  * It may therefore throw an error if a class fails to load.

    81  * Before the JVM can use a dynamically-computed constant, it must first be <em>resolved</em>.

    74  * This error becomes the abnormal termination of the dynamic

    82  * Dynamically-computed constant resolution is accomplished by calling a <em>bootstrap method</em>

    75  * call site execution.

    83  * which is given the static information content of the constant,

    76  * Linkage does not trigger class initialization.

    84  * and which must produce a value of the constant's statically declared type.

    77  * <p>

    85  * <p>

    78  * The bootstrap method is invoked on at least three values:

    86  * Each dynamically-computed constant statically specifies its own

    87  * bootstrap method as a constant pool reference.

    88  * The constant pool reference also specifies the constant's name and field type descriptor,

    89  * just like {@code getstatic} and the other field reference instructions.

    90  * (Roughly speaking, a dynamically-computed constant is to a dynamically-computed call site

    91  * as a {@code CONSTANT_Fieldref} is to a {@code CONSTANT_Methodref}.)

    92  *

    93  * <h2><a id="bsm"></a>Execution of bootstrap methods</h2>

    94  * Resolving a dynamically-computed call site or constant

    95  * starts with resolving constants from the constant pool for the

    96  * following items:

    80  * <li>a {@code MethodHandles.Lookup}, a lookup object on the <em>caller class</em>

    98  * <li>the bootstrap method, a {@code CONSTANT_MethodHandle}</li>

    81  *     in which dynamic call site occurs </li>

    99  * <li>the {@code Class} or {@code MethodType} derived from

    82  * <li>a {@code String}, the method name mentioned in the call site </li>

   100  * type component of the {@code CONSTANT_NameAndType} descriptor</li>

    83  * <li>a {@code MethodType}, the resolved type descriptor of the call </li>

   101  * <li>static arguments, if any (note that static arguments can themselves be

    84  * <li>optionally, any number of additional static arguments taken from the constant pool </li>

   102  * dynamically-computed constants)</li>

    87  * In all cases, bootstrap method invocation is as if by

   105  * The bootstrap method is then invoked, as if by

    88  * {@link java.lang.invoke.MethodHandle#invokeWithArguments MethodHandle.invokeWithArguments},

   106  * {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke},

    89  * (This is also equivalent to

   107  * with the following arguments:

    90  * {@linkplain java.lang.invoke.MethodHandle#invoke generic invocation}

   108  * <ul>

    91  * if the number of arguments is small enough.)

   109  * <li>a {@code MethodHandles.Lookup}, which is a lookup object on the <em>caller class</em>

    92  * <p>

   110  * in which dynamically-computed constant or call site occurs</li>

    93  * For an {@code invokedynamic} instruction, the

   111  * <li>a {@code String}, the name mentioned in the {@code CONSTANT_NameAndType}</li>

    94  * returned result must be convertible to a non-null reference to a

   112  * <li>a {@code MethodType} or {@code Class}, the resolved type descriptor of the {@code CONSTANT_NameAndType}</li>

   113  * <li>a {@code Class}, the resolved type descriptor of the constant, if it is a dynamic constant </li>

   114  * <li>the additional resolved static arguments, if any</li>

   115  * </ul>

   116  * <p>

   117  * For a dynamically-computed call site, the returned result must be a non-null reference to a

    99  * derived from the dynamic call site's type descriptor and passed to

   120  * derived from the invocation's type descriptor and passed to

   100  * the bootstrap method, otherwise a {@code BootstrapMethodError} is thrown.

   121  * the bootstrap method. If these conditions are not met, a {@code BootstrapMethodError} is thrown.

   101  * On success the call site then becomes permanently linked to the dynamic call

   122  * On success the call site then becomes permanently linked to the {@code invokedynamic}

   102  * site.

   123  * instruction.

   103  * <p>

   124  * <p>

   104  * If an exception, {@code E} say, occurs when linking the call site then the

   125  * For a dynamically-computed constant, the result of the bootstrap method is cached

   105  * linkage fails and terminates abnormally. {@code E} is rethrown if the type of

   126  * as the resolved constant value.

   127  * <p>

   128  * If an exception, {@code E} say, occurs during execution of the bootstrap method, then

   129  * resolution fails and terminates abnormally. {@code E} is rethrown if the type of

   108  * If this happens, the same {@code Error} or subclass will the thrown for all

   132  * If this happens, the same error will be thrown for all

   109  * subsequent attempts to execute the dynamic call site.

   133  * subsequent attempts to execute the {@code invokedynamic} instruction or load the

   110  * <h2>timing of linkage</h2>

   134  * dynamically-computed constant.

   111  * A dynamic call site is linked just before its first execution.

   135  *

   136  * <h2>Timing of resolution</h2>

   137  * An {@code invokedynamic} instruction is linked just before its first execution.

   138  * A dynamically-computed constant is resolved just before the first time it is used

   139  * (by pushing it on the stack or linking it as a bootstrap method parameter).

   113  * a thread that is attempting a first execution.

   141  * a thread that is attempting a first execution or first use.

   122  * In an application which requires dynamic call sites with individually

   150  * In an application which requires {@code invokedynamic} instructions with individually

   130  * If several threads simultaneously execute a bootstrap method for a single dynamic

   158  * If several threads simultaneously execute a bootstrap method for a single dynamically-computed

   131  * call site, the JVM must choose one {@code CallSite} object and install it visibly to

   159  * call site or constant, the JVM must choose one bootstrap method result and install it visibly to

   133  * results are ignored, and their dynamic call site invocations proceed with the originally

   161  * results are ignored.

   134  * chosen target object.

   138  * These rules do not enable the JVM to duplicate dynamic call sites,

   165  * These rules do not enable the JVM to share call sites,

   140  * Every dynamic call site transitions at most once from unlinked to linked,

   167  * Every {@code invokedynamic} instruction transitions at most once from unlinked to linked,

   144  * <h2>types of bootstrap methods</h2>

   171  * <h2>Types of bootstrap methods</h2>

   145  * As long as each bootstrap method can be correctly invoked

   172  * For a dynamically-computed call site, the bootstrap method is invoked with parameter

   146  * by {@code MethodHandle.invoke}, its detailed type is arbitrary.

   173  * types {@code MethodHandles.Lookup}, {@code String}, {@code MethodType}, and the types

   174  * of any static arguments; the return type is {@code CallSite}. For a

   175  * dynamically-computed constant, the bootstrap method is invoked with parameter types

   176  * {@code MethodHandles.Lookup}, {@code String}, {@code Class}, and the types of any

   177  * static arguments; the return type is the type represented by the {@code Class}.

   178  *

   179  * Because {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke} allows for

   180  * adaptations between the invoked method type and the method handle's method type,

   181  * there is flexibility in the declaration of the bootstrap method.

   152  * static methods and constructors of {@code CallSite} subclasses.)

   187  * static methods and constructors.)

   153  * <p>

   188  * <p>

   154  * If a given {@code invokedynamic} instruction specifies no static arguments,

   189  * If a pushed value is a primitive type, it may be converted to a reference by boxing conversion.

   155  * the instruction's bootstrap method will be invoked on three arguments,

   156  * conveying the instruction's caller class, name, and method type.

   157  * If the {@code invokedynamic} instruction specifies one or more static arguments,

   158  * those values will be passed as additional arguments to the method handle.

   159  * (Note that because there is a limit of 255 arguments to any method,

   160  * at most 251 extra arguments can be supplied to a non-varargs bootstrap method,

   161  * since the bootstrap method

   162  * handle itself and its first three arguments must also be stacked.)

   163  * The bootstrap method will be invoked as if by {@code MethodHandle.invokeWithArguments}.

   164  * A variable-arity bootstrap method can accept thousands of static arguments,

   165  * subject only by limits imposed by the class-file format.

   166  * <p>

   167  * The normal argument conversion rules for {@code MethodHandle.invoke} apply to all stacked arguments.

   168  * For example, if a pushed value is a primitive type, it may be converted to a reference by boxing conversion.

   175  * Given these rules, here are examples of legal bootstrap method declarations,

   196  * Given these rules, here are examples of legal bootstrap method declarations for

   176  * given various numbers {@code N} of extra arguments.

   197  * dynamically-computed call sites, given various numbers {@code N} of extra arguments.

   211  * As noted above, the actual method type of the bootstrap method can vary.

   232  * Since dynamically-computed constants can be provided as static arguments to bootstrap

   212  * For example, the fourth argument could be {@code MethodHandle},

   233  * methods, there are no limitations on the types of bootstrap arguments.

   213  * if that is the type of the corresponding constant in

   214  * the {@code CONSTANT_InvokeDynamic} entry.

   215  * In that case, the {@code MethodHandle.invoke} call will pass the extra method handle

   216  * constant as an {@code Object}, but the type matching machinery of {@code MethodHandle.invoke}

   217  * will cast the reference back to {@code MethodHandle} before invoking the bootstrap method.

   218  * (If a string constant were passed instead, by badly generated code, that cast would then fail,

   219  * resulting in a {@code BootstrapMethodError}.)

   220  * <p>

   221  * Note that, as a consequence of the above rules, the bootstrap method may accept a primitive

   222  * argument, if it can be represented by a constant pool entry.

   224  * cannot be created for bootstrap methods, since such constants cannot be directly

   235  * cannot be <em>directly</em> supplied by {@code CONSTANT_Integer}

   225  * represented in the constant pool, and the invocation of the bootstrap method will

   236  * constant pool entries, since the {@code asType} conversions do

   228  * Extra bootstrap method arguments are intended to allow language implementors

   239  * In the above examples, the return type is always {@code CallSite},

   229  * to safely and compactly encode metadata.

   240  * but that is not a necessary feature of bootstrap methods.

   230  * In principle, the name and extra arguments are redundant,

   241  * In the case of a dynamically-computed call site, the only requirement is that

   231  * since each call site could be given its own unique bootstrap method.

   242  * the return type of the bootstrap method must be convertible

   232  * Such a practice would be likely to produce large class files and constant pools.

   243  * (using the {@code asType} conversions) to {@code CallSite}, which

   244  * means the bootstrap method return type might be {@code Object} or

   245  * {@code ConstantCallSite}.

   246  * In the case of a dynamically-resolved constant, the return type of the bootstrap

   247  * method must be convertible to the type of the constant, as

   248  * represented by its field type descriptor.  For example, if the

   249  * dynamic constant has a field type descriptor of {@code "C"}

   250  * ({@code char}) then the bootstrap method return type could be

   251  * {@code Object}, {@code Character}, or {@code char}, but not

   252  * {@code int} or {@code Integer}.