Package org.graalvm.nativeimage.hosted

Class RuntimeForeignAccess

java.lang.Object

org.graalvm.nativeimage.hosted.RuntimeForeignAccess

public final class RuntimeForeignAccess
extends Object

Method Summary

Modifier and Type	Method	Description
static void	registerForDirectUpcall(MethodHandle target, Object desc, Object... options)	Registers a specific static method (denoted by a method handle) as a fast upcall target.
static void	registerForDowncall(Object desc, Object... options)	Registers the provided function descriptor and options pair at image build time for downcalls into foreign code.
static void	registerForUpcall(Object desc, Object... options)	Registers the provided function descriptor and options pair at image build time for upcalls from foreign code.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

registerForDowncall

public static void registerForDowncall(Object desc,
 Object... options)

Registers the provided function descriptor and options pair at image build time for downcalls into foreign code. Required to get a downcall method handle using Linker.downcallHandle(java.lang.foreign.MemorySegment, java.lang.foreign.FunctionDescriptor, java.lang.foreign.Linker.Option...)^PREVIEW for the same descriptor and options at runtime.

Even though this method is weakly typed for compatibility reasons, runtime checks will be performed to ensure that the arguments have the expected type. It will be deprecated in favor of strongly typed variant as soon as possible.

Parameters:

desc - A FunctionDescriptor^PREVIEW to register for downcalls.

options - An array of Linker.Option^PREVIEW used for the downcalls.

Since:

23.1

registerForUpcall

public static void registerForUpcall(Object desc,
 Object... options)

Registers the provided function descriptor and options pair at image build time for upcalls from foreign code. Required to get an upcall stub function pointer using Linker.upcallStub(java.lang.invoke.MethodHandle, java.lang.foreign.FunctionDescriptor, java.lang.foreign.Arena, java.lang.foreign.Linker.Option...)^PREVIEW for the same descriptor and options at runtime.

Even though this method is weakly typed for compatibility reasons, runtime checks will be performed to ensure that the arguments have the expected type. It will be deprecated in favor of strongly typed variant as soon as possible.

Parameters:

desc - A FunctionDescriptor^PREVIEW to register for upcalls.

options - An array of Linker.Option^PREVIEW used for the upcalls.

Since:

24.1

registerForDirectUpcall

public static void registerForDirectUpcall(MethodHandle target,
 Object desc,
 Object... options)

Registers a specific static method (denoted by a method handle) as a fast upcall target. This will create a specialized upcall stub that will invoke only the specified method, which is much faster than using registerForUpcall(Object, Object...)).

The provided method handle must be a direct method handle. Those are most commonly created using MethodHandles.Lookup.findStatic(Class, String, MethodType). However, a strict requirement is that it must be possible to create a non-empty descriptor for the method handle using MethodHandle.describeConstable(). The denoted static method will also be registered for reflective access since run-time code will also create a method handle to denoted static method.

Even though this method is weakly typed for compatibility reasons, runtime checks will be performed to ensure that the arguments have the expected type. It will be deprecated in favor of strongly typed variant as soon as possible.

Parameters:

target - A direct method handle denoting a static method.

desc - A FunctionDescriptor^PREVIEW to register for upcalls.

options - An array of Linker.Option^PREVIEW used for the upcalls.

Since:

24.2