Page History

...

The special methods internalMemberName and linkToStatic are explained on the page about direct method handles.

Method handle invocation

Internally to HotSpot (in rewriter.cpp) method handle invocations are rewritten to use a special instruction called invokehandle. This instruction in many ways is parallel to invokedynamic. It resolves to an adapter method pointer and an appendix. The appendix (if not null) is pushed after the explicit arguments to invoke or invokeExact.

The resolution is done via a call to trusted Java code, to a method called MethodHandleNatives.linkMethod. As with linkCallSite, the JVM passes all resolved constant pool references to linkMethod, and receives back a coordinated pair of values, a MemberName and an Object. After unpacking, these are plugged into the CPCE as the adapter and appendix.

The same degrees of freedom apply to invokehandle CPCE entries as apply to invokedynamic CPCE entries, and similar optimization opportunities apply.

There is one major difference from invokedynamic: Many invokehandle instructions can share a single CPCE entry, if they all have the same signature and method name ("invokeExact" vs. "invoke").

Adapter method for invokeExact

The standard semantics of an invokevirtual of MethodHandle.invokeExact are simple. The signature for the call site (which may contain any mix of any references and primitive types) is resolved (once, at link time) into a MethodType. Every time the method handle is invoked, the method type is checked against the type of the method handle being invoked. (Since the method handle is a computed value, it can of course be different every time, and the type does not necessarily match.) If the two types differ in any way, a WrongMethodTypeException is thrown. Otherwise, the method handle is invoked on the given types, and returns a value of the type expected by the caller.

An adapter method for invokeExact is correspondingly simple. It merely performs a method type check and then calls invokeBasic. The appendix is a reference to the resolved MethodType, required to make the type check.

Here is an example:

LambdaForm(a0:L,a1:L,a2:L)=>{
    t3:V=Invokers.checkExactType(a0:L,a2:L);
    t4:L=MethodHandle.invokeBasic(a0:L,a1:L);
    t4:L}

The leading argument a0 is a method handle. The trailing argument a2 is the method type appendix, computed when the call site is resolved. The middle argument a1 is the sole argument to the method handle.

First the subroutine Invokers.checkExactType is called on the method handle and the appendix, extracting the type from the method handle and comparing it with the static call site type. If no exception is thrown, control returns to the adapter method. No value is returned, and the name t3 has a pseudo-type of void.

(Since the appendix represents the static call site type, and the type of the method handle is the dynamically acceptable type, this could be viewed as a simple dynamic type check.)

Next, invokeBasic is used to jump into the method handle (which is now known to be completely safe for this call). The result comes back, briefly named t4, and is returned to the caller.

Adapter method for generic invoke

Method handles also support a more complex invocation mode, which can perform type conversions on individual arguments and return values, and even group arguments into varargs arrays.

As with invokeExact the resolution of such a call site is carried out by a call to MethodHandleNatives.linkMethod. In this case, the trusted Java code must return a more flexible and complex adapter method.

Here is an example:

LambdaForm(a0:L,a1:L,a2:I,a3:L)=>{
    t4:L=Invokers.checkGenericType(a0:L,a3:L);
    t5:I=MethodHandle.invokeBasic(t4:L,a3:L,a0:L,a1:L,a2:I);
    t5:I}

As before, a0 is the method handle and the trailing a3 is a method type. Here, there are two regular arguments, a reference and an int.

As before, the first job is to check the type, and this is done by Invokers.checkGenericType. Unlike the simpler check, this routine returns a value. (The routine can also throw WrongMethodTypeException if necessary.)

The value returned from checkGenericType is in fact a method handle t4. This method handle is immediately invoked on the original arguments, plus the original method handle a0, plus the desired call site type a3 (not in that order).

Depending on the match or mismatch between the type of a0 and the call site type a3, the actual behavior of t4 could be very simple (basically another invokeBasic) or very complex (an arity change with type conversions. That's up to the runtimeMore low-level details are explained on the page about invocation of method handles.