* 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

 * are given special treatment by the virtual machine:

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

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

 * </li>

 *

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

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

 * behavior.

 * </li>

 *

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

 * to dynamically resolve custom constant values.

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

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

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

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

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

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

 * 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.

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

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

 *

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

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

 * equipped with bootstrap methods which perform their resolution.

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

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

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

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

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

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

 *

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

 * Resolving a dynamically-computed call site or constant

 * starts with resolving constants from the constant pool for the

 * following items:

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

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

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

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

 * dynamically-computed constants)</li>

 * The bootstrap method is then invoked, as if by

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

 * with the following arguments:

 * <ul>

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

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

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

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

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

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

 * </ul>

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

 * 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.

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

 * as the resolved constant value.

 * <p>

 * 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

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

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

 * dynamically-computed constant.

 *

 * <h2>Timing of resolution</h2>

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

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

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

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

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

 * 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

 * results are ignored.

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

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

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

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

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

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

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

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

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

 *

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

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

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

 * static methods and constructors.)

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

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

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

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

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

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

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

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

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

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

 * the return type of the bootstrap method must be convertible

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

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

 * {@code ConstantCallSite}.

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

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

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

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

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

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

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