org.graalvm.libgraal

Class LibGraal

java.lang.Object

org.graalvm.libgraal.LibGraal

public class LibGraal
extends Object

Access to libgraal, a shared library containing an AOT compiled version of Graal produced by GraalVM Native Image. The libgraal library is only available if:

• the current runtime is libgraal, or
• the HotSpot UseJVMCINativeLibrary flag is true and the current runtime includes the relevant JVMCI API additions for accessing libgraal.

The LibGraal.isAvailable() method is provided to test these conditions. It must be used to guard usage of all other methods in this class. In addition, only the following methods can be called from within libgraal:

• LibGraal.isAvailable()
• LibGraal.inLibGraal()
• LibGraal.translate(Object)
• LibGraal.unhand(Class, long)

The typical usage of this class is to link and call CEntryPoints in libgraal. Each call to a CEntryPoint requires an IsolateThread argument which can be obtained from a LibGraalScope.

Constructor Summary

Constructors

Constructor and Description
LibGraal()

Method Summary

Modifier and Type	Method and Description
static boolean	attachCurrentThread(boolean isDaemon, long[] isolate) Ensures the current thread is attached to the peer runtime.
static boolean	detachCurrentThread(boolean release) Detaches the current thread from the peer runtime.
static long	getFailedSpeculationsAddress(HotSpotSpeculationLog log) Invokes the method getFailedSpeculationsAddress on a HotSpotSpeculationLog, if the method exists.
static boolean	inLibGraal() Determines if the current runtime is libgraal.
static boolean	isAvailable() Determines if libgraal is available for use.
static boolean	isSupported() Determines if the current runtime supports building a libgraal image.
static void	registerNativeMethods(Class<?> clazz) Links each native method in clazz to a CEntryPoint in libgraal.
static long	translate(Object obj) Creates or retrieves an object in the peer runtime that mirrors obj.
static <T> T	unhand(Class<T> type, long handle) Dereferences and returns the object referred to by the JNI global reference handle.

Methods inherited from class java.lang.Object

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

Constructor Detail

LibGraal

public LibGraal()

Method Detail

isAvailable

public static boolean isAvailable()

Determines if libgraal is available for use.

isSupported

public static boolean isSupported()

Determines if the current runtime supports building a libgraal image.

inLibGraal

public static boolean inLibGraal()

Determines if the current runtime is libgraal.

registerNativeMethods

public static void registerNativeMethods(Class<?> clazz)

Links each native method in clazz to a CEntryPoint in libgraal. This cannot be called from within libgraal.

Throws:

NullPointerException - if clazz == null

UnsupportedOperationException - if libgraal is not enabled (i.e. -XX:-UseJVMCINativeLibrary)

IllegalArgumentException - if clazz is Class.isPrimitive()

IllegalStateException - if libgraal is unavailable or LibGraal.inLibGraal() returns true

UnsatisfiedLinkError - if there's a problem linking a native method in clazz (no matching JNI symbol or the native method is already linked to a different address)

translate

public static long translate(Object obj)

Creates or retrieves an object in the peer runtime that mirrors obj. This mechanism can be used to pass and return values between the HotSpot and libgraal runtimes. In the receiving runtime, the value can be converted back to an object with LibGraal.unhand.

Parameters:

obj - an object for which an equivalent instance in the peer runtime is requested

Returns:

a JNI global reference to the mirror of obj in the peer runtime

Throws:

IllegalArgumentException - if obj is not of a translatable type

unhand

public static <T> T unhand(Class<T> type,
                           long handle)

Dereferences and returns the object referred to by the JNI global reference handle. The global reference is deleted prior to returning. Any further use of handle is invalid.

Parameters:

handle - a JNI global reference to an object in the current runtime

Returns:

the object referred to by handle

Throws:

ClassCastException - if the returned object cannot be cast to type

attachCurrentThread

public static boolean attachCurrentThread(boolean isDaemon,
                                          long[] isolate)

Ensures the current thread is attached to the peer runtime.

Parameters:

isDaemon - if the thread is not yet attached, should it be attached as a daemon

isolate - if non-null, the isolate for the current thread is returned in element 0

Returns:

true if this call attached the current thread, false if the current thread was already attached

detachCurrentThread

public static boolean detachCurrentThread(boolean release)

Detaches the current thread from the peer runtime.

Parameters:

release - if true and the VM supports releasing the JavaVM associated with libgraal runtimes and this is the last thread attached to a libgraal runtime, then this call destroys the associated JavaVM instance, releasing its resources

Returns:

true if the JavaVM associated with the libgraal runtime was destroyed as a result of this call

getFailedSpeculationsAddress

public static long getFailedSpeculationsAddress(HotSpotSpeculationLog log)

Invokes the method getFailedSpeculationsAddress on a HotSpotSpeculationLog, if the method exists.

Returns:

the address of the pointer to the native failed speculations list.

Throws:

UnsupportedOperationException - if unsupported