java.lang.invoke.package-info Maven / Gradle / Ivy
Show all versions of qbicc-rt-java.base Show documentation
/*
* Copyright (c) 2008, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
* 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.VarHandle VarHandle} contain
* signature polymorphic methods
* which can be linked regardless of their type descriptor.
* Normally, method linkage requires exact matching of type descriptors.
*
*
* - The JVM bytecode format supports immediate constants of
* the classes {@link java.lang.invoke.MethodHandle MethodHandle} and
* {@link java.lang.invoke.MethodType MethodType}.
*
*
* - The {@code invokedynamic} instruction makes use of bootstrap {@code MethodHandle}
* constants to dynamically resolve {@code CallSite} objects for custom method invocation
* behavior.
*
*
* - The {@code ldc} instruction makes use of bootstrap {@code MethodHandle} constants
* to dynamically resolve custom constant values.
*
*
*
* Dynamic resolution of call sites and constants
* The following low-level information summarizes relevant parts of the
* Java Virtual Machine specification. For full details, please see the
* current version of that specification.
*
* Dynamically-computed call sites
* 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 linked.
* Linking is accomplished by calling a bootstrap method
* 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.
*
* Each {@code invokedynamic} instruction statically specifies its own
* bootstrap method as a constant pool reference.
* The constant pool reference also specifies the invocation's name and method type descriptor,
* just like {@code invokestatic} and the other invoke instructions.
*
*
Dynamically-computed constants
* The constant pool may contain constants tagged {@code CONSTANT_Dynamic},
* equipped with bootstrap methods which perform their resolution.
* Such a dynamic constant is originally in an unresolved state.
* Before the JVM can use a dynamically-computed constant, it must first be resolved.
* Dynamically-computed constant resolution is accomplished by calling a bootstrap method
* 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}.)
*
*
Execution of bootstrap methods
* Resolving a dynamically-computed call site or constant
* starts with resolving constants from the constant pool for the
* following items:
*
* - the bootstrap method, a {@code CONSTANT_MethodHandle}
* - the {@code Class} or {@code MethodType} derived from
* type component of the {@code CONSTANT_NameAndType} descriptor
* - static arguments, if any (note that static arguments can themselves be
* dynamically-computed constants)
*
*
* The bootstrap method is then invoked, as if by
* {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke},
* with the following arguments:
*
* - a {@code MethodHandles.Lookup}, which is a lookup object on the caller class
* in which dynamically-computed constant or call site occurs
* - a {@code String}, the name mentioned in the {@code CONSTANT_NameAndType}
* - a {@code MethodType} or {@code Class}, the resolved type descriptor of the {@code CONSTANT_NameAndType}
* - a {@code Class}, the resolved type descriptor of the constant, if it is a dynamic constant
* - the additional resolved static arguments, if any
*
*
* For a dynamically-computed call site, the returned result must be a non-null reference to a
* {@link java.lang.invoke.CallSite CallSite}.
* The type of the call site's target must be exactly equal to the type
* 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 first parameter of the bootstrap
* method must be assignable to {@code MethodHandles.Lookup}. If this condition
* is not met, a {@code BootstrapMethodError} is thrown.
* On success the result of the bootstrap method is cached as the resolved
* constant value.
*
* 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
* {@code E} is {@code Error} or a subclass, otherwise a
* {@code BootstrapMethodError} that wraps {@code E} is thrown.
* 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.
*
*
Timing of resolution
* 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).
* The bootstrap method call implementing the linkage occurs within
* a thread that is attempting a first execution or first use.
*
* 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 {@code invokedynamic} instructions with individually
* mutable behaviors, their bootstrap methods should produce distinct
* {@link java.lang.invoke.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 dynamically-computed
* call site or constant, the JVM must choose one bootstrap method result and install it visibly to
* all threads. Any other bootstrap method calls are allowed to complete, but their
* results are ignored.
*
* Discussion:
* These rules do not enable the JVM to share call sites,
* or to issue “causeless” bootstrap method calls.
* Every {@code invokedynamic} instruction transitions at most once from unlinked to linked,
* just before its first invocation.
* There is no way to undo the effect of a completed bootstrap method call.
*
*
Types of bootstrap methods
* 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 bootstrap method handle's method type,
* there is flexibility in the declaration of the bootstrap method.
* For a dynamically-computed constant the first parameter type of the bootstrap method handle
* must be assignable to {@code MethodHandles.Lookup}, other than that constraint the same degree
* of flexibility applies to bootstrap methods of dynamically-computed call sites and
* dynamically-computed constants.
* Note: this constraint allows for the future possibility where the bootstrap method is
* invoked with just the parameter types of static arguments, thereby supporting a wider
* range of methods compatible with the static arguments (such as methods that don't declare
* or require the lookup, name, and type meta-data parameters).
*
For example, for dynamically-computed call site, 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}.
* (Note that the types and number of the stacked arguments limit
* the legal kinds of bootstrap methods to appropriately typed
* static methods and constructors.)
*
* If a pushed value is a primitive type, it may be converted to a reference by boxing conversion.
* If the bootstrap method is a variable arity method (its modifier bit {@code 0x0080} is set),
* then some or all of the arguments specified here may be collected into a trailing array parameter.
* (This is not a special rule, but rather a useful consequence of the interaction
* between {@code CONSTANT_MethodHandle} constants, the modifier bit for variable arity methods,
* and the {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transformation.)
*
* Given these rules, here are examples of legal bootstrap method declarations for
* dynamically-computed call sites, given various numbers {@code N} of extra arguments.
* The first row (marked {@code *}) will work for any number of extra arguments.
*
*
*
* N Sample bootstrap method *
*
* - {@code CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)}
*
- {@code CallSite bootstrap(Object... args)}
*
- {@code CallSite bootstrap(Object caller, Object... nameAndTypeWithArgs)}
*
0
*
* - {@code CallSite bootstrap(Lookup caller, String name, MethodType type)}
*
- {@code CallSite bootstrap(Lookup caller, Object... nameAndType)}
*
1
* {@code CallSite bootstrap(Lookup caller, String name, MethodType type, Object arg)} 2
*
* - {@code CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)}
*
- {@code CallSite bootstrap(Lookup caller, String name, MethodType type, String... args)}
*
- {@code CallSite bootstrap(Lookup caller, String name, MethodType type, String x, int y)}
*
* The last example assumes that the extra arguments are of type
* {@code String} and {@code Integer} (or {@code int}), respectively.
* The second-to-last example assumes that all extra arguments are of type
* {@code String}.
* The other examples work with all types of extra arguments. Note that all
* the examples except the second and third also work with dynamically-computed
* constants if the return type is changed to be compatible with the
* constant's declared type (such as {@code Object}, which is always compatible).
*
* Since dynamically-computed constants can be provided as static arguments to bootstrap
* methods, there are no limitations on the types of bootstrap arguments.
* However, arguments of type {@code boolean}, {@code byte}, {@code short}, or {@code char}
* cannot be directly supplied by {@code CONSTANT_Integer}
* constant pool entries, since the {@code asType} conversions do
* not perform the necessary narrowing primitive conversions.
*
* 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}.
*
* @author John Rose, JSR 292 EG
* @since 1.7
*/
package java.lang.invoke;