1 /*

     2  * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 /**

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

    28  * the Java core class libraries and virtual machine.

    29  *

    30  * <p>

    31  * As described in the Java Virtual Machine Specification,

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

    33  * language support in the virtual machine:

    34  * <ul>

    35  * <li>The class {@link java.lang.invoke.MethodHandle MethodHandle} contains

    36  * <a href="MethodHandle.html#sigpoly">signature polymorphic methods</a>

    37  * which can be linked regardless of their type descriptor.

    38  * Normally, method linkage requires exact matching of type descriptors.

    39  * </li>

    40  *

    41  * <li>The JVM bytecode format supports immediate constants of

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

    43  * </li>

    44  * </ul>

    45  *

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

    47  * The following low-level information summarizes relevant parts of the

    48  * Java Virtual Machine specification.  For full details, please see the

    49  * current version of that specification.

    50  *

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

    52  * <h2><a name="indyinsn"></a>{@code invokedynamic} instructions</h2>

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

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

    55  * <p>

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

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

    58  * Linking is accomplished by calling a <em>bootstrap method</em>

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

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

    61  * that gives the behavior of the call site.

    62  * <p>

    63  * Each {@code invokedynamic} instruction statically specifies its own

    64  * bootstrap method as a constant pool reference.

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

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

    67  * <p>

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

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

    70  * the type descriptor of the dynamic call site.

    71  * This resolution process may trigger class loading.

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

    73  * This error becomes the abnormal termination of the dynamic

    74  * call site execution.

    75  * Linkage does not trigger class initialization.

    76  * <p>

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

    78  * <ul>

    79  * <li>a {@code MethodHandles.Lookup}, a lookup object on the <em>caller class</em> in which dynamic call site occurs </li>

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

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

    82  * <li>optionally, between 1 and 251 additional static arguments taken from the constant pool </li>

    83  * </ul>

    84  * Invocation is as if by

    85  * {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke}.

    86  * The returned result must be a {@link java.lang.invoke.CallSite CallSite} (or a subclass).

    87  * The type of the call site's target must be exactly equal to the type

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

    89  * the bootstrap method.

    90  * The call site then becomes permanently linked to the dynamic call site.

    91  * <p>

    92  * As documented in the JVM specification, all failures arising from

    93  * the linkage of a dynamic call site are reported

    94  * by a {@link java.lang.BootstrapMethodError BootstrapMethodError},

    95  * which is thrown as the abnormal termination of the dynamic call

    96  * site execution.

    97  * If this happens, the same error will the thrown for all subsequent

    98  * attempts to execute the dynamic call site.

    99  *

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

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

   102  * The bootstrap method call implementing the linkage occurs within

   103  * a thread that is attempting a first execution.

   104  * <p>

   105  * If there are several such threads, the bootstrap method may be

   106  * invoked in several threads concurrently.

   107  * Therefore, bootstrap methods which access global application

   108  * data must take the usual precautions against race conditions.

   109  * In any case, every {@code invokedynamic} instruction is either

   110  * unlinked or linked to a unique {@code CallSite} object.

   111  * <p>

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

   113  * mutable behaviors, their bootstrap methods should produce distinct

   114  * {@link java.lang.invoke.CallSite CallSite} objects, one for each linkage request.

   115  * Alternatively, an application can link a single {@code CallSite} object

   116  * to several {@code invokedynamic} instructions, in which case

   117  * a change to the target method will become visible at each of

   118  * the instructions.

   119  * <p>

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

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

   122  * all threads.  Any other bootstrap method calls are allowed to complete, but their

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

   124  * chosen target object.

   125 

   126  * <p style="font-size:smaller;">

   127  * <em>Discussion:</em>

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

   129  * or to issue “causeless” bootstrap method calls.

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

   131  * just before its first invocation.

   132  * There is no way to undo the effect of a completed bootstrap method call.

   133  *

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

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

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

   137  * For example, the first argument could be {@code Object}

   138  * instead of {@code MethodHandles.Lookup}, and the return type

   139  * could also be {@code Object} instead of {@code CallSite}.

   140  * (Note that the types and number of the stacked arguments limit

   141  * the legal kinds of bootstrap methods to appropriately typed

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

   143  * <p>

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

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

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

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

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

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

   150  * at most 251 extra arguments can be supplied, since the bootstrap method

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

   152  * The bootstrap method will be invoked as if by either {@code MethodHandle.invoke}

   153  * or {@code invokeWithArguments}.  (There is no way to tell the difference.)

   154  * <p>

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

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

   157  * If the bootstrap method is a variable arity method (its modifier bit {@code 0x0080} is set),

   158  * then some or all of the arguments specified here may be collected into a trailing array parameter.

   159  * (This is not a special rule, but rather a useful consequence of the interaction

   160  * between {@code CONSTANT_MethodHandle} constants, the modifier bit for variable arity methods,

   161  * and the {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transformation.)

   162  * <p>

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

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

   165  * The first rows (marked {@code *}) will work for any number of extra arguments.

   166  * <table border=1 cellpadding=5 summary="Static argument types">

   167  * <tr><th>N</th><th>sample bootstrap method</th></tr>

   168  * <tr><td>*</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)</code></td></tr>

   169  * <tr><td>*</td><td><code>CallSite bootstrap(Object... args)</code></td></tr>

   170  * <tr><td>*</td><td><code>CallSite bootstrap(Object caller, Object... nameAndTypeWithArgs)</code></td></tr>

   171  * <tr><td>0</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type)</code></td></tr>

   172  * <tr><td>0</td><td><code>CallSite bootstrap(Lookup caller, Object... nameAndType)</code></td></tr>

   173  * <tr><td>1</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object arg)</code></td></tr>

   174  * <tr><td>2</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)</code></td></tr>

   175  * <tr><td>2</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, String... args)</code></td></tr>

   176  * <tr><td>2</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, String x, int y)</code></td></tr>

   177  * </table>

   178  * The last example assumes that the extra arguments are of type

   179  * {@code CONSTANT_String} and {@code CONSTANT_Integer}, respectively.

   180  * The second-to-last example assumes that all extra arguments are of type

   181  * {@code CONSTANT_String}.

   182  * The other examples work with all types of extra arguments.

   183  * <p>

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

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

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

   187  * the {@code CONSTANT_InvokeDynamic} entry.

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

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

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

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

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

   193  * <p>

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

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

   196  * However, arguments of type {@code boolean}, {@code byte}, {@code short}, or {@code char}

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

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

   199  * not perform the necessary narrowing primitive conversions.

   200  * <p>

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

   202  * to safely and compactly encode metadata.

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

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

   205  * Such a practice is likely to produce large class files and constant pools.

   206  *

   207  * @author John Rose, JSR 292 EG

   208  * @since 1.7

   209  */

   210 

   211 package java.lang.invoke;