com.oracle.svm.jvmtiagentbase

Class JvmtiAgentBase<T extends JNIHandleSet>

java.lang.Object

com.oracle.svm.jvmtiagentbase.JvmtiAgentBase<T>

Type Parameters:

T - The class or subclass of JNIHandleSet containg the JNI handles this agent requires.

public abstract class JvmtiAgentBase<T extends JNIHandleSet>
extends Object

Base class for a JVMTI agent. In order to create a new JVMTI agent, you must:

1. (Optional) Subclass JNIHandleSet.
2. Subclass this class and parametrize it with your @{link JNIHandleSet class}.
3. Create a org.graalvm.nativeimage.hosted.Feature that will register the agent using JvmtiAgentBase.registerAgent(JvmtiAgentBase) in its' org.graalvm.nativeimage.hosted.Feature#afterRegistration callback.

The created feature must then be passed to native-image on creation of shared library. This agent contains the bare minimum of the JVMTI events. In order to receive a a JVMTI event that is not implemented here, you must:

1. Create a callback method annotated with CEntryPoint that matches the signature (parameters and the return type) of the desired JVMTI event. The method must also be annotated with CEntryPointOptions and must use the AgentIsolate.Prologue prologue.
2. Create a CEntryPointLiteral from your callback method.
3. Set the callback in the callbacks argument of your JvmtiAgentBase.onLoadCallback(com.oracle.svm.jni.nativeapi.JNIJavaVM, com.oracle.svm.jvmtiagentbase.jvmti.JvmtiEnv, com.oracle.svm.jvmtiagentbase.jvmti.JvmtiEventCallbacks, java.lang.String) method.
4. Enable the event using JvmtiEventMode.

Only one agent can be created in a single native image.

Constructor Summary

Constructors

Constructor and Description
JvmtiAgentBase()

Method Summary

Modifier and Type	Method and Description
protected abstract JNIHandleSet	constructJavaHandles(com.oracle.svm.jni.nativeapi.JNIEnvironment env) Callback method that should create your subclass of JNIHandleSet.
protected abstract int	getRequiredJvmtiVersion() Returns the JVMTI version required by the agent.
T	handles() Returns the JNI handle set constructed with JvmtiAgentBase.constructJavaHandles(com.oracle.svm.jni.nativeapi.JNIEnvironment).
boolean	isDestroyed() Checks if the agent cleanup code had ran.
static int	onLoad(com.oracle.svm.jni.nativeapi.JNIJavaVM vm, org.graalvm.nativeimage.c.type.CCharPointer options, org.graalvm.word.PointerBase reserved)
protected abstract int	onLoadCallback(com.oracle.svm.jni.nativeapi.JNIJavaVM vm, JvmtiEnv jvmti, JvmtiEventCallbacks callbacks, String options) JVMTI Agent_OnLoad callback.
static void	onThreadEnd(JvmtiEnv jvmti, com.oracle.svm.jni.nativeapi.JNIEnvironment jni, com.oracle.svm.jni.nativeapi.JNIObjectHandle thread)
static int	onUnload(com.oracle.svm.jni.nativeapi.JNIJavaVM vm)
protected abstract int	onUnloadCallback(com.oracle.svm.jni.nativeapi.JNIJavaVM vm) JVMTI Agent_OnUnload callback.
static void	onVMDeath(JvmtiEnv jvmti, com.oracle.svm.jni.nativeapi.JNIEnvironment jni)
protected abstract void	onVMDeathCallback(JvmtiEnv jvmti, com.oracle.svm.jni.nativeapi.JNIEnvironment jni) JVMTI VMDeath event callback.
static void	onVMInit(JvmtiEnv jvmti, com.oracle.svm.jni.nativeapi.JNIEnvironment jni, com.oracle.svm.jni.nativeapi.JNIObjectHandle thread)
protected abstract void	onVMInitCallback(JvmtiEnv jvmti, com.oracle.svm.jni.nativeapi.JNIEnvironment jni, com.oracle.svm.jni.nativeapi.JNIObjectHandle thread) JVMTI VMInit event callback.
static void	onVMStart(JvmtiEnv jvmti, com.oracle.svm.jni.nativeapi.JNIEnvironment jni)
protected abstract void	onVMStartCallback(JvmtiEnv jvmti, com.oracle.svm.jni.nativeapi.JNIEnvironment jni) JVMTI VMStart event callback.
protected static <T extends JNIHandleSet> void	registerAgent(JvmtiAgentBase<T> agentSingleton) Registers the agent singleton.
static <T extends JNIHandleSet,U extends JvmtiAgentBase<T>> U	singleton()
protected void	unload(com.oracle.svm.jni.nativeapi.JNIJavaVM vm) Releases all global JNI references and resources aquired by the framework.

Methods inherited from class java.lang.Object

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

Constructor Detail

JvmtiAgentBase

public JvmtiAgentBase()

Method Detail

constructJavaHandles

protected abstract JNIHandleSet constructJavaHandles(com.oracle.svm.jni.nativeapi.JNIEnvironment env)

Callback method that should create your subclass of JNIHandleSet.

Parameters:

env - JNI environment of the thread running the JVMTI callback.

Returns:

An instance of your JNIHandleSet subclass.

onLoadCallback

protected abstract int onLoadCallback(com.oracle.svm.jni.nativeapi.JNIJavaVM vm,
                                      JvmtiEnv jvmti,
                                      JvmtiEventCallbacks callbacks,
                                      String options)

JVMTI Agent_OnLoad callback.

Parameters:

vm - The JNI Java VM.

jvmti - The JVMTI environment.

callbacks - A structure that allows setting the callbacks for JVMTI events.

options - Command line options passed to the agent.

Returns:

0 on success, anything else on failure.

onUnloadCallback

protected abstract int onUnloadCallback(com.oracle.svm.jni.nativeapi.JNIJavaVM vm)

JVMTI Agent_OnUnload callback.

Parameters:

vm - The JNI Java VM.

Returns:

0 on success, anything else on failure.

onVMStartCallback

protected abstract void onVMStartCallback(JvmtiEnv jvmti,
                                          com.oracle.svm.jni.nativeapi.JNIEnvironment jni)

JVMTI VMStart event callback.

Parameters:

jvmti - The JVMTI environment.

jni - The JNI environment of the thread running the JVMTI callback.

onVMInitCallback

protected abstract void onVMInitCallback(JvmtiEnv jvmti,
                                         com.oracle.svm.jni.nativeapi.JNIEnvironment jni,
                                         com.oracle.svm.jni.nativeapi.JNIObjectHandle thread)

JVMTI VMInit event callback.

Parameters:

jvmti - The JVMTI environment.

jni - The JNI environment of the thread running the JVMTI callback.

thread - The initial thread.

onVMDeathCallback

protected abstract void onVMDeathCallback(JvmtiEnv jvmti,
                                          com.oracle.svm.jni.nativeapi.JNIEnvironment jni)

JVMTI VMDeath event callback.

Parameters:

jvmti - The JVMTI environment.

jni - The JNi environment of the thead running the JVMTI callback.

getRequiredJvmtiVersion

protected abstract int getRequiredJvmtiVersion()

Returns the JVMTI version required by the agent.

Returns:

The JVMTI version required by the agent.

isDestroyed

public boolean isDestroyed()

Checks if the agent cleanup code had ran.

Returns:

Whether the agent cleanup code had ran.

handles

public T handles()

Returns the JNI handle set constructed with JvmtiAgentBase.constructJavaHandles(com.oracle.svm.jni.nativeapi.JNIEnvironment). The handles are guaranteed to be created before JvmtiAgentBase.onLoadCallback(com.oracle.svm.jni.nativeapi.JNIJavaVM, com.oracle.svm.jvmtiagentbase.jvmti.JvmtiEnv, com.oracle.svm.jvmtiagentbase.jvmti.JvmtiEventCallbacks, java.lang.String) is called.

Returns:

The JNI handle set constructed with JvmtiAgentBase.constructJavaHandles(com.oracle.svm.jni.nativeapi.JNIEnvironment).

singleton

public static <T extends JNIHandleSet,U extends JvmtiAgentBase<T>> U singleton()

registerAgent

protected static <T extends JNIHandleSet> void registerAgent(JvmtiAgentBase<T> agentSingleton)

Registers the agent singleton. This method must be called only once during a native image build.

Parameters:

agentSingleton - The agent implementation.

onLoad

public static int onLoad(com.oracle.svm.jni.nativeapi.JNIJavaVM vm,
                         org.graalvm.nativeimage.c.type.CCharPointer options,
                         org.graalvm.word.PointerBase reserved)

unload

protected void unload(com.oracle.svm.jni.nativeapi.JNIJavaVM vm)

Releases all global JNI references and resources aquired by the framework. This function may only be called once and must be called from the JvmtiAgentBase.onUnloadCallback(com.oracle.svm.jni.nativeapi.JNIJavaVM). During the call to unload some JVMTI event handlers may still be running. As such, it is necessary to provide proper synchronization that ensures all events finish before this call, and events that happen after it do not access any JNI handles. To check if this function has been called, use JvmtiAgentBase.isDestroyed().

Parameters:

vm - The JNIJavaVM received from the JvmtiAgentBase.onUnloadCallback(com.oracle.svm.jni.nativeapi.JNIJavaVM) function.

onUnload

public static int onUnload(com.oracle.svm.jni.nativeapi.JNIJavaVM vm)

onVMStart

public static void onVMStart(JvmtiEnv jvmti,
                             com.oracle.svm.jni.nativeapi.JNIEnvironment jni)

onVMInit

public static void onVMInit(JvmtiEnv jvmti,
                            com.oracle.svm.jni.nativeapi.JNIEnvironment jni,
                            com.oracle.svm.jni.nativeapi.JNIObjectHandle thread)

onVMDeath

public static void onVMDeath(JvmtiEnv jvmti,
                             com.oracle.svm.jni.nativeapi.JNIEnvironment jni)

onThreadEnd

public static void onThreadEnd(JvmtiEnv jvmti,
                               com.oracle.svm.jni.nativeapi.JNIEnvironment jni,
                               com.oracle.svm.jni.nativeapi.JNIObjectHandle thread)