JPMS: Changes to the JVM Tool Interface

• Introduction
  • What is the JVM Tool Interface?
  • Architecture
  • Writing Agents
  • Deploying Agents
  • Statically Linked Agents (since version 1.2.3)
  • Agent Command Line Options
  • Agent Start-Up
  • Agent Start-Up (OnLoad phase)
  • Agent Start-Up (Live phase)
  • Agent Shutdown
  • JAVA_TOOL_OPTIONS
  • Environments
  • Bytecode Instrumentation
  • Bytecode Instrumentation of code in modules
  • Modified UTF-8 String Encoding
  • Specification Context
• Functions
  • Accessing Functions
  • Function Return Values
  • Managing JNI Object References
  • Prerequisite State for Calling Functions
  • Exceptions and Functions
  • Function Index
    • Memory Management
    • Thread
    • Thread Group
    • Stack Frame
    • Force Early Return
    • Heap
    • Heap (1.0)
    • Local Variable
    • Breakpoint
    • Watched Field
    • Module
    • Class
    • Object
    • Field
    • Method
    • Raw Monitor
    • JNI Function Interception
    • Event Management
    • Extension Mechanism
    • Capability
    • Timers
    • Class Loader Search
    • System Properties
    • General
  • Error Codes
• Events
  • Event Index
• Data Types
  • JNI Types Used in the JVM Tool Interface
  • JVM Tool Interface Base Types
  • Structure Type Definitions
  • Function Type Definitions
  • Enumeration Definitions
  • Function Table
• Constant Index
• Change History

What is the JVM Tool Interface?

The JVM^TM Tool Interface (JVM TI) is a programming interface used by development and monitoring tools. It provides both a way to inspect the state and to control the execution of applications running in the Java^TM virtual machine (VM). JVM TI is intended to provide a VM interface for the full breadth of tools that need access to VM state, including but not limited to: profiling, debugging, monitoring, thread analysis, and coverage analysis tools. JVM TI may not be available in all implementations of the Java^TM virtual machine. JVM TI is a two-way interface. A client of JVM TI, hereafter called an agent, can be notified of interesting occurrences through events. JVM TI can query and control the application through many functions, either in response to events or independent of them. Agents run in the same process with and communicate directly with the virtual machine executing the application being examined. This communication is through a native interface (JVM TI). The native in-process interface allows maximal control with minimal intrusion on the part of a tool. Typically, agents are relatively compact. They can be controlled by a separate process which implements the bulk of a tool's function without interfering with the target application's normal execution.

Architecture

Tools can be written directly to JVM TI or indirectly through higher level interfaces. The Java Platform Debugger Architecture includes JVM TI, but also contains higher-level, out-of-process debugger interfaces. The higher-level interfaces are more appropriate than JVM TI for many tools. For more information on the Java Platform Debugger Architecture, see the Java Platform Debugger Architecture website.

Writing Agents

Agents can be written in any native language that supports C language calling conventions and C or C++ definitions. The function, event, data type, and constant definitions needed for using JVM TI are defined in the include file jvmti.h. To use these definitions add the J2SE^TM include directory to your include path and add

#include <jvmti.h>
    

to your source code.

Deploying Agents

An agent is deployed in a platform specific manner but is typically the platform equivalent of a dynamic library. On the Windows^TM operating system, for example, an agent library is a "Dynamic Linked Library" (DLL). On the Solaris^TM Operating Environment, an agent library is a shared object (.so file). An agent may be started at VM startup by specifying the agent library name using a command line option. Some implementations may support a mechanism to start agents in the live phase. The details of how this is initiated are implementation specific.

Statically Linked Agents (since version 1.2.3)

A native JVMTI Agent may be statically linked with the VM. The manner in which the library and VM image are combined is implementation-dependent. An agent L whose image has been combined with the VM is defined as statically linked if and only if the agent exports a function called Agent_OnLoad_L. If a statically linked agent L exports a function called Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad function will be ignored. If an agent L is statically linked, an Agent_OnLoad_L function will be invoked with the same arguments and expected return value as specified for the Agent_OnLoad function. An agent L that is statically linked will prohibit an agent of the same name from being loaded dynamically. The VM will invoke the Agent_OnUnload_L function of the agent, if such a function is exported, at the same point during VM execution as it would have called the dynamic entry point Agent_OnUnLoad. A statically loaded agent cannot be unloaded. The Agent_OnUnload_L function will still be called to do any other agent shutdown related tasks. If a statically linked agent L exports a function called Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad function will be ignored. If an agent L is statically linked, an Agent_OnAttach_L function will be invoked with the same arguments and expected return value as specified for the Agent_OnAttach function. If a statically linked agent L exports a function called Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach function will be ignored.

Agent Command Line Options

The term "command-line option" is used below to mean options supplied in the JavaVMInitArgs argument to the JNI_CreateJavaVM function of the JNI Invocation API. One of the two following command-line options is used on VM startup to properly load and run agents. These arguments identify the library containing the agent as well as an options string to be passed in at startup.

-agentlib:<agent-lib-name>=<options>

The name following -agentlib: is the name of the library to load. Lookup of the library, both its full name and location, proceeds in a platform-specific manner. Typically, the <agent-lib-name> is expanded to an operating system specific file name. The <options> will be passed to the agent on start-up. For example, if the option -agentlib:foo=opt1,opt2 is specified, the VM will attempt to load the shared library foo.dll from the system PATH under Windows^TM or libfoo.so from the LD_LIBRARY_PATH under the Solaris^TM operating environment. If the agent library is statically linked into the executable then no actual loading takes place.

-agentpath:<path-to-agent>=<options>

The path following -agentpath: is the absolute path from which to load the library. No library name expansion will occur. The <options> will be passed to the agent on start-up. For example, if the option -agentpath:c:\myLibs\foo.dll=opt1,opt2 is specified, the VM will attempt to load the shared library c:\myLibs\foo.dll. If the agent library is statically linked into the executable then no actual loading takes place.

For a dynamic shared library agent, the start-up routine Agent_OnLoad in the library will be invoked. If the agent library is statically linked into the executable then the system will attempt to invoke the Agent_OnLoad_<agent-lib-name> entry point where <agent-lib-name> is the basename of the agent. In the above example -agentpath:c:\myLibs\foo.dll=opt1,opt2, the system will attempt to find and call the Agent_OnLoad_foo start-up routine. Libraries loaded with -agentlib: or -agentpath: will be searched for JNI native method implementations to facilitate the use of Java programming language code in tools, as is needed for bytecode instrumentation. The agent libraries will be searched after all other libraries have been searched (agents wishing to override or intercept the native method implementations of non-agent methods can use the NativeMethodBind event). These switches do the above and nothing more - they do not change the state of the VM or JVM TI. No command line options are needed to enable JVM TI or aspects of JVM TI, this is handled programmatically by the use of capabilities.

Agent Start-Up

The VM starts each agent by invoking a start-up function. If the agent is started in the OnLoad phase the function Agent_OnLoad or Agent_OnLoad_L for statically linked agents will be invoked. If the agent is started in the live phase the function Agent_OnAttach or Agent_OnAttach_L for statically linked agents will be invoked. Exactly one call to a start-up function is made per agent.

Agent Start-Up (OnLoad phase)

If an agent is started during the OnLoad phase then its agent library must export a start-up function with the following prototype:

JNIEXPORT jint JNICALL

Agent_OnLoad(JavaVM *vm, char *options, void *reserved)

Or for a statically linked agent named 'L':

JNIEXPORT jint JNICALL

Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)

The VM will start the agent by calling this function. It will be called early enough in VM initialization that:

• system properties may be set before they have been used in the start-up of the VM
• the full set of capabilities is still available (note that capabilities that configure the VM may only be available at this time--see the Capability function section)
• no bytecodes have executed
• no classes have been loaded
• no objects have been created

The VM will call the Agent_OnLoad or Agent_OnLoad_<agent-lib-name> function with <options> as the second argument - that is, using the command-line option examples, "opt1,opt2" will be passed to the char *options argument of Agent_OnLoad. The options argument is encoded as a modified UTF-8 string. If =<options> is not specified, a zero length string is passed to options. The lifespan of the options string is the Agent_OnLoad or Agent_OnLoad_<agent-lib-name> call. If needed beyond this time the string or parts of the string must be copied. The period between when Agent_OnLoad is called and when it returns is called the OnLoad phase. Since the VM is not initialized during the OnLoad phase, the set of allowed operations inside Agent_OnLoad is restricted (see the function descriptions for the functionality available at this time). The agent can safely process the options and set event callbacks with SetEventCallbacks. Once the VM initialization event is received (that is, the VMInit callback is invoked), the agent can complete its initialization.

Rationale: Early startup is required so that agents can set the desired capabilities, many of which must be set before the VM is initialized. In JVMDI, the -Xdebug command-line option provided very coarse-grain control of capabilities. JVMPI implementations use various tricks to provide a single "JVMPI on" switch. No reasonable command-line option could provide the fine-grain of control required to balance needed capabilities vs performance impact. Early startup is also needed so that agents can control the execution environment - modifying the file system and system properties to install their functionality.

The return value from Agent_OnLoad or Agent_OnLoad_<agent-lib-name> is used to indicate an error. Any value other than zero indicates an error and causes termination of the VM.

Agent Start-Up (Live phase)

A VM may support a mechanism that allows agents to be started in the VM during the live phase. The details of how this is supported, are implementation specific. For example, a tool may use some platform specific mechanism, or implementation specific API, to attach to the running VM, and request it start a given agent. If an agent is started during the live phase then its agent library must export a start-up function with the following prototype:

JNIEXPORT jint JNICALL

Agent_OnAttach(JavaVM* vm, char *options, void *reserved)

Or for a statically linked agent named 'L':

JNIEXPORT jint JNICALL

Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)

The VM will start the agent by calling this function. It will be called in the context of a thread that is attached to the VM. The first argument <vm> is the Java VM. The <options> argument is the startup options provided to the agent. <options> is encoded as a modified UTF-8 string. If startup options were not provided, a zero length string is passed to options. The lifespan of the options string is the Agent_OnAttach or Agent_OnAttach_<agent-lib-name> call. If needed beyond this time the string or parts of the string must be copied. Note that some capabilities may not be available in the live phase. The Agent_OnAttach or Agent_OnAttach_<agent-lib-name > function initializes the agent and returns a value to the VM to indicate if an error occurred. Any value other than zero indicates an error. An error does not cause the VM to terminate. Instead the VM ignores the error, or takes some implementation specific action -- for example it might print an error to standard error, or record the error in a system log.

Agent Shutdown

The library may optionally export a shutdown function with the following prototype:

JNIEXPORT void JNICALL

Agent_OnUnload(JavaVM *vm)

Or for a statically linked agent named 'L':

JNIEXPORT void JNICALL

Agent_OnUnload_L(JavaVM *vm)

This function will be called by the VM when the library is about to be unloaded. The library will be unloaded (unless it is statically linked into the executable) and this function will be called if some platform specific mechanism causes the unload (an unload mechanism is not specified in this document) or the library is (in effect) unloaded by the termination of the VM whether through normal termination or VM failure, including start-up failure. Uncontrolled shutdown is, of couse, an exception to this rule. Note the distinction between this function and the VM Death event: for the VM Death event to be sent, the VM must have run at least to the point of initialization and a valid JVM TI environment must exist which has set a callback for VMDeath and enabled the event. None of these are required for Agent_OnUnload or Agent_OnUnload_<agent-lib-name> and this function is also called if the library is unloaded for other reasons. In the case that a VM Death event is sent, it will be sent before this function is called (assuming this function is called due to VM termination). This function can be used to clean-up resources allocated by the agent.

JAVA_TOOL_OPTIONS

Since the command-line cannot always be accessed or modified, for example in embedded VMs or simply VMs launched deep within scripts, a JAVA_TOOL_OPTIONS variable is provided so that agents may be launched in these cases. Platforms which support environment variables or other named strings, may support the JAVA_TOOL_OPTIONS variable. This variable will be broken into options at white-space boundaries. White-space characters include space, tab, carriage-return, new-line, vertical-tab, and form-feed. Sequences of white-space characters are considered equivalent to a single white-space character. No white-space is included in the options unless quoted. Quoting is as follows:

• All characters enclosed between a pair of single quote marks (''), except a single quote, are quoted.
• Double quote characters have no special meaning inside a pair of single quote marks.
• All characters enclosed between a pair of double quote marks (""), except a double quote, are quoted.
• Single quote characters have no special meaning inside a pair of double quote marks.
• A quoted part can start or end anywhere in the variable.
• White-space characters have no special meaning when quoted -- they are included in the option like any other character and do not mark white-space boundaries.
• The pair of quote marks is not included in the option.

JNI_CreateJavaVM (in the JNI Invocation API) will prepend these options to the options supplied in its JavaVMInitArgs argument. Platforms may disable this feature in cases where security is a concern; for example, the Reference Implementation disables this feature on Unix systems when the effective user or group ID differs from the real ID. This feature is intended to support the initialization of tools -- specifically including the launching of native or Java programming language agents. Multiple tools may wish to use this feature, so the variable should not be overwritten, instead, options should be appended to the variable. Note that since the variable is processed at the time of the JNI Invocation API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled.

Environments

The JVM TI specification supports the use of multiple simultaneous JVM TI agents. Each agent has its own JVM TI environment. That is, the JVM TI state is separate for each agent - changes to one environment do not affect the others. The state of a JVM TI environment includes:

• the event callbacks
• the set of events which are enabled
• the capabilities
• the memory allocation/deallocation hooks

Although their JVM TI state is separate, agents inspect and modify the shared state of the VM, they also share the native environment in which they execute. As such, an agent can perturb the results of other agents or cause them to fail. It is the responsibility of the agent writer to specify the level of compatibility with other agents. JVM TI implementations are not capable of preventing destructive interactions between agents. Techniques to reduce the likelihood of these occurrences are beyond the scope of this document. An agent creates a JVM TI environment by passing a JVM TI version as the interface ID to the JNI Invocation API function GetEnv. See Accessing JVM TI Functions for more details on the creation and use of JVM TI environments. Typically, JVM TI environments are created by calling GetEnv from Agent_OnLoad.

Bytecode Instrumentation

This interface does not include some events that one might expect in an interface with profiling support. Some examples include object allocation events and full speed method enter and exit events. The interface instead provides support for bytecode instrumentation, the ability to alter the Java virtual machine bytecode instructions which comprise the target program. Typically, these alterations are to add "events" to the code of a method - for example, to add, at the beginning of a method, a call to MyProfiler.methodEntered(). Since the changes are purely additive, they do not modify application state or behavior. Because the inserted agent code is standard bytecodes, the VM can run at full speed, optimizing not only the target program but also the instrumentation. If the instrumentation does not involve switching from bytecode execution, no expensive state transitions are needed. The result is high performance events. This approach also provides complete control to the agent: instrumentation can be restricted to "interesting" portions of the code (e.g., the end user's code) and can be conditional. Instrumentation can run entirely in Java programming language code or can call into the native agent. Instrumentation can simply maintain counters or can statistically sample events. Instrumentation can be inserted in one of three ways:

• Static Instrumentation: The class file is instrumented before it is loaded into the VM - for example, by creating a duplicate directory of *.class files which have been modified to add the instrumentation. This method is extremely awkward and, in general, an agent cannot know the origin of the class files which will be loaded.
• Load-Time Instrumentation: When a class file is loaded by the VM, the raw bytes of the class file are sent for instrumentation to the agent. The ClassFileLoadHook event, triggered by the class load, provides this functionality. This mechanism provides efficient and complete access to one-time instrumentation.
• Dynamic Instrumentation: A class which is already loaded (and possibly even running) is modified. This optional feature is provided by the ClassFileLoadHook event, triggered by calling the RetransformClasses function. Classes can be modified multiple times and can be returned to their original state. The mechanism allows instrumentation which changes during the course of execution.

The class modification functionality provided in this interface is intended to provide a mechanism for instrumentation (the ClassFileLoadHook event and the RetransformClasses function) and, during development, for fix-and-continue debugging (the RedefineClasses function). Care must be taken to avoid perturbing dependencies, especially when instrumenting core classes. For example, an approach to getting notification of every object allocation is to instrument the constructor on Object. Assuming that the constructor is initially empty, the constructor could be changed to:

      public Object() {
        MyProfiler.allocationTracker(this);
      }
    

However, if this change was made using the ClassFileLoadHook event then this might impact a typical VM as follows: the first created object will call the constructor causing a class load of MyProfiler; which will then cause object creation, and since MyProfiler isn't loaded yet, infinite recursion; resulting in a stack overflow. A refinement of this would be to delay invoking the tracking method until a safe time. For example, trackAllocations could be set in the handler for the VMInit event.

      static boolean trackAllocations = false;

      public Object() {
        if (trackAllocations) {
          MyProfiler.allocationTracker(this);
        }
      }
    

The SetNativeMethodPrefix allows native methods to be instrumented by the use of wrapper methods.

Bytecode Instrumentation of code in modules

Agents can use the functions AddModuleReads, AddModuleExports, AddModuleOpens, AddModuleUses and AddModuleProvides to update a module to expand the set of modules that it reads, the set of packages that it exports or opens to other modules, or the services that it uses and provides. As an aid to agents that deploy supporting classes on the search path of the bootstrap class loader, or the search path of the class loader that loads the main class, the Java virtual machine arranges for the module of classes transformed by the ClassFileLoadHook event to read the unnamed module of both class loaders.

Modified UTF-8 String Encoding

JVM TI uses modified UTF-8 to encode character strings. This is the same encoding used by JNI. Modified UTF-8 differs from standard UTF-8 in the representation of supplementary characters and of the null character. See the Modified UTF-8 Strings section of the JNI specification for details.

Specification Context

Since this interface provides access to the state of applications running in the Java virtual machine; terminology refers to the Java platform and not the native platform (unless stated otherwise). For example:

• "thread" means Java programming language thread.
• "stack frame" means Java virtual machine stack frame.
• "class" means Java programming language class.
• "heap" means Java virtual machine heap.
• "monitor" means Java programming language object monitor.

Sun, Sun Microsystems, the Sun logo, Java, and JVM are trademarks or registered trademarks of Oracle and/or its affiliates, in the U.S. and other countries.

Functions

Accessing Functions

Native code accesses JVM TI features by calling JVM TI functions. Access to JVM TI functions is by use of an interface pointer in the same manner as Java Native Interface (JNI) functions are accessed. The JVM TI interface pointer is called the environment pointer. An environment pointer is a pointer to an environment and has the type jvmtiEnv*. An environment has information about its JVM TI connection. The first value in the environment is a pointer to the function table. The function table is an array of pointers to JVM TI functions. Every function pointer is at a predefined offset inside the array. When used from the C language: double indirection is used to access the functions; the environment pointer provides context and is the first parameter of each function call; for example:

jvmtiEnv *jvmti;
...
jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &class_count, &classes);
    

When used from the C++ language: functions are accessed as member functions of jvmtiEnv; the environment pointer is not passed to the function call; for example:

jvmtiEnv *jvmti;
...
jvmtiError err = jvmti->GetLoadedClasses(&class_count, &classes);
    

Unless otherwise stated, all examples and declarations in this specification use the C language. A JVM TI environment can be obtained through the JNI Invocation API GetEnv function:

jvmtiEnv *jvmti;
...
(*jvm)->GetEnv(jvm, &jvmti, JVMTI_VERSION_1_0);
    

Each call to GetEnv creates a new JVM TI connection and thus a new JVM TI environment. The version argument of GetEnv must be a JVM TI version. The returned environment may have a different version than the requested version but the returned environment must be compatible. GetEnv will return JNI_EVERSION if a compatible version is not available, if JVM TI is not supported or JVM TI is not supported in the current VM configuration. Other interfaces may be added for creating JVM TI environments in specific contexts. Each environment has its own state (for example, desired events, event handling functions, and capabilities). An environment is released with DisposeEnvironment. Thus, unlike JNI which has one environment per thread, JVM TI environments work across threads and are created dynamically.

Function Return Values

JVM TI functions always return an error code via the jvmtiError function return value. Some functions can return additional values through pointers provided by the calling function. In some cases, JVM TI functions allocate memory that your program must explicitly deallocate. This is indicated in the individual JVM TI function descriptions. Empty lists, arrays, sequences, etc are returned as NULL. In the event that the JVM TI function encounters an error (any return value other than JVMTI_ERROR_NONE) the values of memory referenced by argument pointers is undefined, but no memory will have been allocated and no global references will have been allocated. If the error occurs because of invalid input, no action will have occurred.

Managing JNI Object References

JVM TI functions identify objects with JNI references (jobject and jclass) and their derivatives (jthread and jthreadGroup). References passed to JVM TI functions can be either global or local, but they must be strong references. All references returned by JVM TI functions are local references--these local references are created during the JVM TI call. Local references are a resource that must be managed (see the JNI Documentation). When threads return from native code all local references are freed. Note that some threads, including typical agent threads, will never return from native code. A thread is ensured the ability to create sixteen local references without the need for any explicit management. For threads executing a limited number of JVM TI calls before returning from native code (for example, threads processing events), it may be determined that no explicit management is needed. However, long running agent threads will need explicit local reference management--usually with the JNI functions PushLocalFrame and PopLocalFrame. Conversely, to preserve references beyond the return from native code, they must be converted to global references. These rules do not apply to jmethodID and jfieldID as they are not jobjects.

Prerequisite State for Calling Functions

Unless the function explicitly states that the agent must bring a thread or the VM to a particular state (for example, suspended), the JVM TI implementation is responsible for bringing the VM to a safe and consistent state for performing the function.

Exceptions and Functions

JVM TI functions never throw exceptions; error conditions are communicated via the function return value. Any existing exception state is preserved across a call to a JVM TI function. See the Java Exceptions section of the JNI specification for information on handling exceptions.

Function Index

• Memory Management
  • Allocate
  • Deallocate
• Thread
  • Get Thread State
  • Get Current Thread
  • Get All Threads
  • Suspend Thread
  • Suspend Thread List
  • Resume Thread
  • Resume Thread List
  • Stop Thread
  • Interrupt Thread
  • Get Thread Info
  • Get Owned Monitor Info
  • Get Owned Monitor Stack Depth Info
  • Get Current Contended Monitor
  • Run Agent Thread
  • Set Thread Local Storage
  • Get Thread Local Storage
• Thread Group
  • Get Top Thread Groups
  • Get Thread Group Info
  • Get Thread Group Children
• Stack Frame
  • Get Stack Trace
  • Get All Stack Traces
  • Get Thread List Stack Traces
  • Get Frame Count
  • Pop Frame
  • Get Frame Location
  • Notify Frame Pop
• Force Early Return
  • Force Early Return - Object
  • Force Early Return - Int
  • Force Early Return - Long
  • Force Early Return - Float
  • Force Early Return - Double
  • Force Early Return - Void
• Heap
  • Follow References
  • Iterate Through Heap
  • Get Tag
  • Set Tag
  • Get Objects With Tags
  • Force Garbage Collection
• Heap (1.0)
  • Iterate Over Objects Reachable From Object
  • Iterate Over Reachable Objects
  • Iterate Over Heap
  • Iterate Over Instances Of Class
• Local Variable
  • Get Local Variable - Object
  • Get Local Instance
  • Get Local Variable - Int
  • Get Local Variable - Long
  • Get Local Variable - Float
  • Get Local Variable - Double
  • Set Local Variable - Object
  • Set Local Variable - Int
  • Set Local Variable - Long
  • Set Local Variable - Float
  • Set Local Variable - Double
• Breakpoint
  • Set Breakpoint
  • Clear Breakpoint
• Watched Field
  • Set Field Access Watch
  • Clear Field Access Watch
  • Set Field Modification Watch
  • Clear Field Modification Watch
• Module
  • Get All Modules
  • Get Named Module
  • Add Module Reads
  • Add Module Exports
  • Add Module Opens
  • Add Module Uses
  • Add Module Provides
  • Is Modifiable Module
• Class
  • Get Loaded Classes
  • Get Classloader Classes
  • Get Class Signature
  • Get Class Status
  • Get Source File Name
  • Get Class Modifiers
  • Get Class Methods
  • Get Class Fields
  • Get Implemented Interfaces
  • Get Class Version Numbers
  • Get Constant Pool
  • Is Interface
  • Is Array Class
  • Is Modifiable Class
  • Get Class Loader
  • Get Source Debug Extension
  • Retransform Classes
  • Redefine Classes
• Object
  • Get Object Size
  • Get Object Hash Code
  • Get Object Monitor Usage
• Field
  • Get Field Name (and Signature)
  • Get Field Declaring Class
  • Get Field Modifiers
  • Is Field Synthetic
• Method
  • Get Method Name (and Signature)
  • Get Method Declaring Class
  • Get Method Modifiers
  • Get Max Locals
  • Get Arguments Size
  • Get Line Number Table
  • Get Method Location
  • Get Local Variable Table
  • Get Bytecodes
  • Is Method Native
  • Is Method Synthetic
  • Is Method Obsolete
  • Set Native Method Prefix
  • Set Native Method Prefixes
• Raw Monitor
  • Create Raw Monitor
  • Destroy Raw Monitor
  • Raw Monitor Enter
  • Raw Monitor Exit
  • Raw Monitor Wait
  • Raw Monitor Notify
  • Raw Monitor Notify All
• JNI Function Interception
  • Set JNI Function Table
  • Get JNI Function Table
• Event Management
  • Set Event Callbacks
  • Set Event Notification Mode
  • Generate Events
• Extension Mechanism
  • Get Extension Functions
  • Get Extension Events
  • Set Extension Event Callback
• Capability
  • Get Potential Capabilities
  • Add Capabilities
  • Relinquish Capabilities
  • Get Capabilities
• Timers
  • Get Current Thread CPU Timer Information
  • Get Current Thread CPU Time
  • Get Thread CPU Timer Information
  • Get Thread CPU Time
  • Get Timer Information
  • Get Time
  • Get Available Processors
• Class Loader Search
  • Add To Bootstrap Class Loader Search
  • Add To System Class Loader Search
• System Properties
  • Get System Properties
  • Get System Property
  • Set System Property
• General
  • Get Phase
  • Dispose Environment
  • Set Environment Local Storage
  • Get Environment Local Storage
  • Get Version Number
  • Get Error Name
  • Set Verbose Flag
  • Get JLocation Format

Memory Management

Memory Management functions:

• Allocate
• Deallocate

These functions provide for the allocation and deallocation of memory used by JVM TI functionality and can be used to provide working memory for agents. Memory managed by JVM TI is not compatible with other memory allocation libraries and mechanisms.

Allocate

jvmtiError
Allocate(jvmtiEnv* env,
            jlong size,
            unsigned char** mem_ptr)

Allocate an area of memory through the JVM TI allocator. The allocated memory should be freed with Deallocate.

Deallocate

jvmtiError
Deallocate(jvmtiEnv* env,
            unsigned char* mem)

Deallocate mem using the JVM TI allocator. This function should be used to deallocate any memory allocated and returned by a JVM TI function (including memory allocated with Allocate). All allocated memory must be deallocated or the memory cannot be reclaimed.

Thread

Thread functions:

• Get Thread State
• Get Current Thread
• Get All Threads
• Suspend Thread
• Suspend Thread List
• Resume Thread
• Resume Thread List
• Stop Thread
• Interrupt Thread
• Get Thread Info
• Get Owned Monitor Info
• Get Owned Monitor Stack Depth Info
• Get Current Contended Monitor
• Run Agent Thread
• Set Thread Local Storage
• Get Thread Local Storage

Thread function types:

• Agent Start Function

Thread types:

• jvmtiThreadInfo - Thread information structure
• jvmtiMonitorStackDepthInfo - Monitor stack depth information structure

Thread flags and constants:

• Thread State Flags
• java.lang.Thread.State Conversion Masks
• Thread Priority Constants

Get Thread State

jvmtiError
GetThreadState(jvmtiEnv* env,
            jthread thread,
            jint* thread_state_ptr)

Get the state of a thread. The state of the thread is represented by the answers to the hierarchical set of questions below:

• Alive?
  • Not alive.
    • Why not alive?
      • New.
      • Terminated (JVMTI_THREAD_STATE_TERMINATED)
  • Alive (JVMTI_THREAD_STATE_ALIVE)
    • Suspended?
      • Suspended (JVMTI_THREAD_STATE_SUSPENDED)
      • Not suspended
    • Interrupted?
      • Interrupted (JVMTI_THREAD_STATE_INTERRUPTED)
      • Not interrupted.
    • In native?
      • In native code (JVMTI_THREAD_STATE_IN_NATIVE)
      • In Java programming language code
    • What alive state?
      • Runnable (JVMTI_THREAD_STATE_RUNNABLE)
      • Blocked (JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER)
      • Waiting (JVMTI_THREAD_STATE_WAITING)
        • Timed wait?
          • Indefinite (JVMTI_THREAD_STATE_WAITING_INDEFINITELY
          • Timed (JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT)
        • Why waiting?
          • Object.wait (JVMTI_THREAD_STATE_IN_OBJECT_WAIT)
          • LockSupport.park (JVMTI_THREAD_STATE_PARKED)
          • Sleeping (JVMTI_THREAD_STATE_SLEEPING)

The answers are represented by the following bit vector.

Thread State Flags
Constant	Value	Description
JVMTI_THREAD_STATE_ALIVE	0x0001	Thread is alive. Zero if thread is new (not started) or terminated.
JVMTI_THREAD_STATE_TERMINATED	0x0002	Thread has completed execution.
JVMTI_THREAD_STATE_RUNNABLE	0x0004	Thread is runnable.
JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER	0x0400	Thread is waiting to enter a synchronization block/method or, after an Object.wait(), waiting to re-enter a synchronization block/method.
JVMTI_THREAD_STATE_WAITING	0x0080	Thread is waiting.
JVMTI_THREAD_STATE_WAITING_INDEFINITELY	0x0010	Thread is waiting without a timeout. For example, Object.wait().
JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT	0x0020	Thread is waiting with a maximum time to wait specified. For example, Object.wait(long).
JVMTI_THREAD_STATE_SLEEPING	0x0040	Thread is sleeping -- Thread.sleep(long).
JVMTI_THREAD_STATE_IN_OBJECT_WAIT	0x0100	Thread is waiting on an object monitor -- Object.wait.
JVMTI_THREAD_STATE_PARKED	0x0200	Thread is parked, for example: LockSupport.park, LockSupport.parkUtil and LockSupport.parkNanos.
JVMTI_THREAD_STATE_SUSPENDED	0x100000	Thread suspended. java.lang.Thread.suspend() or a JVM TI suspend function (such as SuspendThread) has been called on the thread. If this bit is set, the other bits refer to the thread state before suspension.
JVMTI_THREAD_STATE_INTERRUPTED	0x200000	Thread has been interrupted.
JVMTI_THREAD_STATE_IN_NATIVE	0x400000	Thread is in native code--that is, a native method is running which has not called back into the VM or Java programming language code. This flag is not set when running VM compiled Java programming language code nor is it set when running VM code or VM support code. Native VM interface functions, such as JNI and JVM TI functions, may be implemented as VM code.
JVMTI_THREAD_STATE_VENDOR_1	0x10000000	Defined by VM vendor.
JVMTI_THREAD_STATE_VENDOR_2	0x20000000	Defined by VM vendor.
JVMTI_THREAD_STATE_VENDOR_3	0x40000000	Defined by VM vendor.

The following definitions are used to convert JVM TI thread state to java.lang.Thread.State style states.

java.lang.Thread.State Conversion Masks
Constant	Value	Description
JVMTI_JAVA_LANG_THREAD_STATE_MASK	JVMTI_THREAD_STATE_TERMINATED | JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT	Mask the state with this before comparison
JVMTI_JAVA_LANG_THREAD_STATE_NEW	0	java.lang.Thread.State.NEW
JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED	JVMTI_THREAD_STATE_TERMINATED	java.lang.Thread.State.TERMINATED
JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE	JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE	java.lang.Thread.State.RUNNABLE
JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED	JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER	java.lang.Thread.State.BLOCKED
JVMTI_JAVA_LANG_THREAD_STATE_WAITING	JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY	java.lang.Thread.State.WAITING
JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING	JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT	java.lang.Thread.State.TIMED_WAITING

Rules There can be no more than one answer to a question, although there can be no answer (because the answer is unknown, does not apply, or none of the answers is correct). An answer is set only when the enclosing answers match. That is, no more than one of

• JVMTI_THREAD_STATE_RUNNABLE
• JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
• JVMTI_THREAD_STATE_WAITING

can be set (a J2SE^TM compliant implementation will always set one of these if JVMTI_THREAD_STATE_ALIVE is set). And if any of these are set, the enclosing answer JVMTI_THREAD_STATE_ALIVE is set. No more than one of

• JVMTI_THREAD_STATE_WAITING_INDEFINITELY
• JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT

can be set (a J2SE^TM compliant implementation will always set one of these if JVMTI_THREAD_STATE_WAITING is set). And if either is set, the enclosing answers JVMTI_THREAD_STATE_ALIVE and JVMTI_THREAD_STATE_WAITING are set. No more than one of

• JVMTI_THREAD_STATE_IN_OBJECT_WAIT
• JVMTI_THREAD_STATE_PARKED
• JVMTI_THREAD_STATE_SLEEPING

can be set. And if any of these is set, the enclosing answers JVMTI_THREAD_STATE_ALIVE and JVMTI_THREAD_STATE_WAITING are set. Also, if JVMTI_THREAD_STATE_SLEEPING is set, then JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT is set. If a state A is implemented using the mechanism of state B then it is state A which is returned by this function. For example, if Thread.sleep(long) is implemented using Object.wait(long) then it is still JVMTI_THREAD_STATE_SLEEPING which is returned. More than one of

• JVMTI_THREAD_STATE_SUSPENDED
• JVMTI_THREAD_STATE_INTERRUPTED
• JVMTI_THREAD_STATE_IN_NATIVE

can be set, but if any is set, JVMTI_THREAD_STATE_ALIVE is set. And finally, JVMTI_THREAD_STATE_TERMINATED cannot be set unless JVMTI_THREAD_STATE_ALIVE is not set. The thread state representation is designed for extension in future versions of the specification; thread state values should be used accordingly, that is they should not be used as ordinals. Most queries can be made by testing a single bit, if use in a switch statement is desired, the state bits should be masked with the interesting bits. All bits not defined above are reserved for future use. A VM, compliant to the current specification, must set reserved bits to zero. An agent should ignore reserved bits -- they should not be assumed to be zero and thus should not be included in comparisons. Examples Note that the values below exclude reserved and vendor bits. The state of a thread blocked at a synchronized-statement would be:

            JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
        

The state of a thread which hasn't started yet would be:

            0
        

The state of a thread at a Object.wait(3000) would be:

            JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING +
                 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT +
                 JVMTI_THREAD_STATE_MONITOR_WAITING
        

The state of a thread suspended while runnable would be:

            JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED
        

Testing the State In most cases, the thread state can be determined by testing the one bit corresponding to that question. For example, the code to test if a thread is sleeping:

        jint state;
        jvmtiError err;

        err = (*jvmti)->GetThreadState(jvmti, thread, &state);
        if (err == JVMTI_ERROR_NONE) {
           if (state & JVMTI_THREAD_STATE_SLEEPING) {  ...
        

For waiting (that is, in Object.wait, parked, or sleeping) it would be:

           if (state & JVMTI_THREAD_STATE_WAITING) {  ...
        

For some states, more than one bit will need to be tested as is the case when testing if a thread has not yet been started:

           if ((state & (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0)  {  ...
        

To distinguish timed from untimed Object.wait:

           if (state & JVMTI_THREAD_STATE_IN_OBJECT_WAIT)  {
               if (state & JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT)  {
               printf("in Object.wait(long timeout)\n");
             } else {
               printf("in Object.wait()\n");
             }
           }
        

Relationship to java.lang.Thread.State The thread state represented by java.lang.Thread.State returned from java.lang.Thread.getState() is a subset of the information returned from this function. The corresponding java.lang.Thread.State can be determined by using the provided conversion masks. For example, this returns the name of the java.lang.Thread.State thread state:

            err = (*jvmti)->GetThreadState(jvmti, thread, &state);
            abortOnError(err);
            switch (state & JVMTI_JAVA_LANG_THREAD_STATE_MASK) {
            case JVMTI_JAVA_LANG_THREAD_STATE_NEW:
              return "NEW";
            case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED:
              return "TERMINATED";
            case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE:
              return "RUNNABLE";
            case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED:
              return "BLOCKED";
            case JVMTI_JAVA_LANG_THREAD_STATE_WAITING:
              return "WAITING";
            case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING:
              return "TIMED_WAITING";
            }
        

Get Current Thread

jvmtiError
GetCurrentThread(jvmtiEnv* env,
            jthread* thread_ptr)

Get the current thread. The current thread is the Java programming language thread which has called the function. The function may return NULL in the start phase if the can_generate_early_vmstart capability is enabled and the java.lang.Thread class has not been initialized yet. Note that most JVM TI functions that take a thread as an argument will accept NULL to mean the current thread.

Get All Threads

jvmtiError
GetAllThreads(jvmtiEnv* env,
            jint* threads_count_ptr,
            jthread** threads_ptr)

Get all live threads. The threads are Java programming language threads; that is, threads that are attached to the VM. A thread is live if java.lang.Thread.isAlive() would return true, that is, the thread has been started and has not yet died. The universe of threads is determined by the context of the JVM TI environment, which typically is all threads attached to the VM. Note that this includes JVM TI agent threads (see RunAgentThread).

Suspend Thread

jvmtiError
SuspendThread(jvmtiEnv* env,
            jthread thread)

Suspend the specified thread. If the calling thread is specified, this function will not return until some other thread calls ResumeThread. If the thread is currently suspended, this function does nothing and returns an error.

Suspend Thread List

jvmtiError
SuspendThreadList(jvmtiEnv* env,
            jint request_count,
            const jthread* request_list,
            jvmtiError* results)

Suspend the request_count threads specified in the request_list array. Threads may be resumed with ResumeThreadList or ResumeThread. If the calling thread is specified in the request_list array, this function will not return until some other thread resumes it. Errors encountered in the suspension of a thread are returned in the results array, not in the return value of this function. Threads that are currently suspended do not change state.

Resume Thread

jvmtiError
ResumeThread(jvmtiEnv* env,
            jthread thread)

Resume a suspended thread. Any threads currently suspended through a JVM TI suspend function (eg. SuspendThread) or java.lang.Thread.suspend() will resume execution; all other threads are unaffected.

Resume Thread List

jvmtiError
ResumeThreadList(jvmtiEnv* env,
            jint request_count,
            const jthread* request_list,
            jvmtiError* results)

Resume the request_count threads specified in the request_list array. Any thread suspended through a JVM TI suspend function (eg. SuspendThreadList) or java.lang.Thread.suspend() will resume execution.

Stop Thread

jvmtiError
StopThread(jvmtiEnv* env,
            jthread thread,
            jobject exception)

Send the specified asynchronous exception to the specified thread (similar to java.lang.Thread.stop). Normally, this function is used to kill the specified thread with an instance of the exception ThreadDeath.

Interrupt Thread

jvmtiError
InterruptThread(jvmtiEnv* env,
            jthread thread)

Interrupt the specified thread (similar to java.lang.Thread.interrupt).

Get Thread Info

typedef struct {
    char* name;
    jint priority;
    jboolean is_daemon;
    jthreadGroup thread_group;
    jobject context_class_loader;
} jvmtiThreadInfo;

jvmtiError
GetThreadInfo(jvmtiEnv* env,
            jthread thread,
            jvmtiThreadInfo* info_ptr)

Get thread information. The fields of the jvmtiThreadInfo structure are filled in with details of the specified thread.

Get Owned Monitor Info

jvmtiError
GetOwnedMonitorInfo(jvmtiEnv* env,
            jthread thread,
            jint* owned_monitor_count_ptr,
            jobject** owned_monitors_ptr)

Get information about the monitors owned by the specified thread.

Get Owned Monitor Stack Depth Info

typedef struct {
    jobject monitor;
    jint stack_depth;
} jvmtiMonitorStackDepthInfo;

jvmtiError
GetOwnedMonitorStackDepthInfo(jvmtiEnv* env,
            jthread thread,
            jint* monitor_info_count_ptr,
            jvmtiMonitorStackDepthInfo** monitor_info_ptr)

Get information about the monitors owned by the specified thread and the depth of the stack frame which locked them.

Get Current Contended Monitor

jvmtiError
GetCurrentContendedMonitor(jvmtiEnv* env,
            jthread thread,
            jobject* monitor_ptr)

Get the object, if any, whose monitor the specified thread is waiting to enter or waiting to regain through java.lang.Object.wait.

Agent Start Function

Run Agent Thread

jvmtiError
RunAgentThread(jvmtiEnv* env,
            jthread thread,
            jvmtiStartFunction proc,
            const void* arg,
            jint priority)

Starts the execution of an agent thread. with the specified native function. The parameter arg is forwarded on to the start function (specified with proc) as its single argument. This function allows the creation of agent threads for handling communication with another process or for handling events without the need to load a special subclass of java.lang.Thread or implementer of java.lang.Runnable. Instead, the created thread can run entirely in native code. However, the created thread does require a newly created instance of java.lang.Thread (referenced by the argument thread) to which it will be associated. The thread object can be created with JNI calls. The following common thread priorities are provided for your convenience:

Thread Priority Constants
Constant	Value	Description
JVMTI_THREAD_MIN_PRIORITY	1	Minimum possible thread priority
JVMTI_THREAD_NORM_PRIORITY	5	Normal thread priority
JVMTI_THREAD_MAX_PRIORITY	10	Maximum possible thread priority

The new thread is started as a daemon thread with the specified priority. If enabled, a ThreadStart event will be sent. Since the thread has been started, the thread will be live when this function returns, unless the thread has died immediately. The thread group of the thread is ignored -- specifically, the thread is not added to the thread group and the thread is not seen on queries of the thread group at either the Java programming language or JVM TI levels. The thread is not visible to Java programming language queries but is included in JVM TI queries (for example, GetAllThreads and GetAllStackTraces). Upon execution of proc, the new thread will be attached to the VM -- see the JNI documentation on Attaching to the VM.

Set Thread Local Storage

jvmtiError
SetThreadLocalStorage(jvmtiEnv* env,
            jthread thread,
            const void* data)

The VM stores a pointer value associated with each environment-thread pair. This pointer value is called thread-local storage. This value is NULL unless set with this function. Agents can allocate memory in which they store thread specific information. By setting thread-local storage it can then be accessed with GetThreadLocalStorage. This function is called by the agent to set the value of the JVM TI thread-local storage. JVM TI supplies to the agent a pointer-size thread-local storage that can be used to record per-thread information.

Get Thread Local Storage

jvmtiError
GetThreadLocalStorage(jvmtiEnv* env,
            jthread thread,
            void** data_ptr)

Called by the agent to get the value of the JVM TI thread-local storage.

Thread Group

Thread Group functions:

• Get Top Thread Groups
• Get Thread Group Info
• Get Thread Group Children

Thread Group types:

• jvmtiThreadGroupInfo - Thread group information structure

Get Top Thread Groups

jvmtiError
GetTopThreadGroups(jvmtiEnv* env,
            jint* group_count_ptr,
            jthreadGroup** groups_ptr)

Return all top-level (parentless) thread groups in the VM.

Get Thread Group Info

typedef struct {
    jthreadGroup parent;
    char* name;
    jint max_priority;
    jboolean is_daemon;
} jvmtiThreadGroupInfo;

jvmtiError
GetThreadGroupInfo(jvmtiEnv* env,
            jthreadGroup group,
            jvmtiThreadGroupInfo* info_ptr)

Get information about the thread group. The fields of the jvmtiThreadGroupInfo structure are filled in with details of the specified thread group.

Get Thread Group Children

jvmtiError
GetThreadGroupChildren(jvmtiEnv* env,
            jthreadGroup group,
            jint* thread_count_ptr,
            jthread** threads_ptr,
            jint* group_count_ptr,
            jthreadGroup** groups_ptr)

Get the live threads and active subgroups in this thread group.

Stack Frame

Stack Frame functions:

• Get Stack Trace
• Get All Stack Traces
• Get Thread List Stack Traces
• Get Frame Count
• Pop Frame
• Get Frame Location
• Notify Frame Pop

Stack Frame types:

• jvmtiFrameInfo - Stack frame information structure
• jvmtiStackInfo - Stack information structure

These functions provide information about the stack of a thread. Stack frames are referenced by depth. The frame at depth zero is the current frame. Stack frames are as described in The Javaâ„¢ Virtual Machine Specification, Chapter 3.6, That is, they correspond to method invocations (including native methods) but do not correspond to platform native or VM internal frames. A JVM TI implementation may use method invocations to launch a thread and the corresponding frames may be included in the stack as presented by these functions -- that is, there may be frames shown deeper than main() and run(). However this presentation must be consistent across all JVM TI functionality which uses stack frames or stack depth.

Stack frame information structure

Information about a stack frame is returned in this structure.

typedef struct {
    jmethodID method;
    jlocation location;
} jvmtiFrameInfo;

jvmtiFrameInfo - Stack frame information structure
Field	Type	Description
method	jmethodID	The method executing in this frame.
location	jlocation	The index of the instruction executing in this frame. -1 if the frame is executing a native method.

Stack information structure

Information about a set of stack frames is returned in this structure.

typedef struct {
    jthread thread;
    jint state;
    jvmtiFrameInfo* frame_buffer;
    jint frame_count;
} jvmtiStackInfo;

jvmtiStackInfo - Stack information structure
Field	Type	Description
thread	jthread	On return, the thread traced.
state	jint	On return, the thread state. See GetThreadState.
frame_buffer	jvmtiFrameInfo *	On return, this agent allocated buffer is filled with stack frame information.
frame_count	jint	On return, the number of records filled into frame_buffer. This will be min(max_frame_count, stackDepth).

Get Stack Trace

jvmtiError
GetStackTrace(jvmtiEnv* env,
            jthread thread,
            jint start_depth,
            jint max_frame_count,
            jvmtiFrameInfo* frame_buffer,
            jint* count_ptr)

Get information about the stack of a thread. If max_frame_count is less than the depth of the stack, the max_frame_count topmost frames are returned, otherwise the entire stack is returned. The topmost frames, those most recently invoked, are at the beginning of the returned buffer. The following example causes up to five of the topmost frames to be returned and (if there are any frames) the currently executing method name to be printed.

jvmtiFrameInfo frames[5];
jint count;
jvmtiError err;

err = (*jvmti)->GetStackTrace(jvmti, aThread, 0, 5,
                                frames, &count);
if (err == JVMTI_ERROR_NONE && count >= 1) {
   char *methodName;
   err = (*jvmti)->GetMethodName(jvmti, frames[0].method,
                        &methodName, NULL, NULL);
   if (err == JVMTI_ERROR_NONE) {
      printf("Executing method: %s", methodName);
   }
}
        

The thread need not be suspended to call this function. The GetLineNumberTable function can be used to map locations to line numbers. Note that this mapping can be done lazily.

Get All Stack Traces

jvmtiError
GetAllStackTraces(jvmtiEnv* env,
            jint max_frame_count,
            jvmtiStackInfo** stack_info_ptr,
            jint* thread_count_ptr)

Get information about the stacks of all live threads (including agent threads). If max_frame_count is less than the depth of a stack, the max_frame_count topmost frames are returned for that thread, otherwise the entire stack is returned. The topmost frames, those most recently invoked, are at the beginning of the returned buffer. All stacks are collected simultaneously, that is, no changes will occur to the thread state or stacks between the sampling of one thread and the next. The threads need not be suspended.

jvmtiStackInfo *stack_info;
jint thread_count;
int ti;
jvmtiError err;

err = (*jvmti)->GetAllStackTraces(jvmti, MAX_FRAMES, &stack_info, &thread_count);

if (err != JVMTI_ERROR_NONE) {
   ...
  
}
for (ti = 0; ti < thread_count; ++ti) {
   jvmtiStackInfo *infop = &stack_info[ti];
   jthread thread = infop->thread;
   jint state = infop->state;
   jvmtiFrameInfo *frames = infop->frame_buffer;
   int fi;

   myThreadAndStatePrinter(thread, state);
   for (fi = 0; fi < infop->frame_count; fi++) {
      myFramePrinter(frames[fi].method, frames[fi].location);
   }
}
/* this one Deallocate call frees all data allocated by GetAllStackTraces */
err = (*jvmti)->Deallocate(jvmti, stack_info);
         

Get Thread List Stack Traces

jvmtiError
GetThreadListStackTraces(jvmtiEnv* env,
            jint thread_count,
            const jthread* thread_list,
            jint max_frame_count,
            jvmtiStackInfo** stack_info_ptr)

Get information about the stacks of the supplied threads. If max_frame_count is less than the depth of a stack, the max_frame_count topmost frames are returned for that thread, otherwise the entire stack is returned. The topmost frames, those most recently invoked, are at the beginning of the returned buffer. All stacks are collected simultaneously, that is, no changes will occur to the thread state or stacks between the sampling one thread and the next. The threads need not be suspended. If a thread has not yet started or terminates before the stack information is collected, a zero length stack (jvmtiStackInfo.frame_count will be zero) will be returned and the thread jvmtiStackInfo.state can be checked. See the example for the similar function GetAllStackTraces.

Get Frame Count

jvmtiError
GetFrameCount(jvmtiEnv* env,
            jthread thread,
            jint* count_ptr)

Get the number of frames currently in the specified thread's call stack. If this function is called for a thread actively executing bytecodes (for example, not the current thread and not suspended), the information returned is transient.

Pop Frame

jvmtiError
PopFrame(jvmtiEnv* env,
            jthread thread)

Pop the current frame of thread's stack. Popping a frame takes you to the previous frame. When the thread is resumed, the execution state of the thread is reset to the state immediately before the called method was invoked. That is (using The Javaâ„¢ Virtual Machine Specification terminology):

• the current frame is discarded as the previous frame becomes the current one
• the operand stack is restored--the argument values are added back and if the invoke was not invokestatic, objectref is added back as well
• the Java virtual machine PC is restored to the opcode of the invoke instruction

Note however, that any changes to the arguments, which occurred in the called method, remain; when execution continues, the first instruction to execute will be the invoke. Between calling PopFrame and resuming the thread the state of the stack is undefined. To pop frames beyond the first, these three steps must be repeated:

• suspend the thread via an event (step, breakpoint, ...)
• call PopFrame
• resume the thread

A lock acquired by calling the called method (if it is a synchronized method) and locks acquired by entering synchronized blocks within the called method are released. Note: this does not apply to native locks or java.util.concurrent.locks locks. Finally blocks are not executed. Changes to global state are not addressed and thus remain changed. The specified thread must be suspended (which implies it cannot be the current thread). Both the called method and calling method must be non-native Java programming language methods. No JVM TI events are generated by this function.

Get Frame Location

jvmtiError
GetFrameLocation(jvmtiEnv* env,
            jthread thread,
            jint depth,
            jmethodID* method_ptr,
            jlocation* location_ptr)

For a Java programming language frame, return the location of the instruction currently executing.

Notify Frame Pop

jvmtiError
NotifyFramePop(jvmtiEnv* env,
            jthread thread,
            jint depth)

When the frame that is currently at depth is popped from the stack, generate a FramePop event. See the FramePop event for details. Only frames corresponding to non-native Java programming language methods can receive notification. The specified thread must either be the current thread or the thread must be suspended.

Force Early Return

Force Early Return functions:

• Force Early Return - Object
• Force Early Return - Int
• Force Early Return - Long
• Force Early Return - Float
• Force Early Return - Double
• Force Early Return - Void

These functions allow an agent to force a method to return at any point during its execution. The method which will return early is referred to as the called method. The called method is the current method (as defined by The Javaâ„¢ Virtual Machine Specification, Chapter 3.6) for the specified thread at the time the function is called. The specified thread must be suspended or must be the current thread. The return occurs when execution of Java programming language code is resumed on this thread. Between calling one of these functions and resumption of thread execution, the state of the stack is undefined. No further instructions are executed in the called method. Specifically, finally blocks are not executed. Note: this can cause inconsistent states in the application. A lock acquired by calling the called method (if it is a synchronized method) and locks acquired by entering synchronized blocks within the called method are released. Note: this does not apply to native locks or java.util.concurrent.locks locks. Events, such as MethodExit, are generated as they would be in a normal return. The called method must be a non-native Java programming language method. Forcing return on a thread with only one frame on the stack causes the thread to exit when resumed.

Force Early Return - Object

jvmtiError
ForceEarlyReturnObject(jvmtiEnv* env,
            jthread thread,
            jobject value)

This function can be used to return from a method whose result type is Object or a subclass of Object.

Force Early Return - Int

jvmtiError
ForceEarlyReturnInt(jvmtiEnv* env,
            jthread thread,
            jint value)

This function can be used to return from a method whose result type is int, short, char, byte, or boolean.

Force Early Return - Long

jvmtiError
ForceEarlyReturnLong(jvmtiEnv* env,
            jthread thread,
            jlong value)

This function can be used to return from a method whose result type is long.

Force Early Return - Float

jvmtiError
ForceEarlyReturnFloat(jvmtiEnv* env,
            jthread thread,
            jfloat value)

This function can be used to return from a method whose result type is float.

Force Early Return - Double

jvmtiError
ForceEarlyReturnDouble(jvmtiEnv* env,
            jthread thread,
            jdouble value)

This function can be used to return from a method whose result type is double.

Force Early Return - Void

jvmtiError
ForceEarlyReturnVoid(jvmtiEnv* env,
            jthread thread)

This function can be used to return from a method with no result type. That is, the called method must be declared void.

Heap

Heap functions:

• Follow References
• Iterate Through Heap
• Get Tag
• Set Tag
• Get Objects With Tags
• Force Garbage Collection

Heap function types:

• Heap Iteration Callback
• Heap Reference Callback
• Primitive Field Callback
• Array Primitive Value Callback
• String Primitive Value Callback
• reserved for future use Callback

Heap types:

• jvmtiHeapReferenceKind - Heap Reference Enumeration
• jvmtiPrimitiveType - Primitive Type Enumeration
• jvmtiHeapReferenceInfoField - Reference information structure for Field references
• jvmtiHeapReferenceInfoArray - Reference information structure for Array references
• jvmtiHeapReferenceInfoConstantPool - Reference information structure for Constant Pool references
• jvmtiHeapReferenceInfoStackLocal - Reference information structure for Local Variable references
• jvmtiHeapReferenceInfoJniLocal - Reference information structure for JNI local references
• jvmtiHeapReferenceInfoReserved - Reference information structure for Other references
• jvmtiHeapReferenceInfo - Reference information structure
• jvmtiHeapCallbacks - Heap callback function structure

Heap flags and constants:

• Heap Filter Flags
• Heap Visit Control Flags

These functions are used to analyze the heap. Functionality includes the ability to view the objects in the heap and to tag these objects.

Object Tags

A tag is a value associated with an object. Tags are explicitly set by the agent using the SetTag function or by callback functions such as jvmtiHeapIterationCallback. Tags are local to the environment; that is, the tags of one environment are not visible in another. Tags are jlong values which can be used simply to mark an object or to store a pointer to more detailed information. Objects which have not been tagged have a tag of zero. Setting a tag to zero makes the object untagged.

Heap Callback Functions

Heap functions which iterate through the heap and recursively follow object references use agent supplied callback functions to deliver the information. These heap callback functions must adhere to the following restrictions -- These callbacks must not use JNI functions. These callbacks must not use JVM TI functions except callback safe functions which specifically allow such use (see the raw monitor, memory management, and environment local storage functions). An implementation may invoke a callback on an internal thread or the thread which called the iteration function. Heap callbacks are single threaded -- no more than one callback will be invoked at a time. The Heap Filter Flags can be used to prevent reporting based on the tag status of an object or its class. If no flags are set (the jint is zero), objects will not be filtered out.

Heap Filter Flags
Constant	Value	Description
JVMTI_HEAP_FILTER_TAGGED	0x4	Filter out tagged objects. Objects which are tagged are not included.
JVMTI_HEAP_FILTER_UNTAGGED	0x8	Filter out untagged objects. Objects which are not tagged are not included.
JVMTI_HEAP_FILTER_CLASS_TAGGED	0x10	Filter out objects with tagged classes. Objects whose class is tagged are not included.
JVMTI_HEAP_FILTER_CLASS_UNTAGGED	0x20	Filter out objects with untagged classes. Objects whose class is not tagged are not included.

The Heap Visit Control Flags are returned by the heap callbacks and can be used to abort the iteration. For the Heap Reference Callback, it can also be used to prune the graph of traversed references (JVMTI_VISIT_OBJECTS is not set).

Heap Visit Control Flags
Constant	Value	Description
JVMTI_VISIT_OBJECTS	0x100	If we are visiting an object and if this callback was initiated by FollowReferences, traverse the references of this object. Otherwise ignored.
JVMTI_VISIT_ABORT	0x8000	Abort the iteration. Ignore all other bits.

The Heap Reference Enumeration is provided by the Heap Reference Callback and Primitive Field Callback to describe the kind of reference being reported.

Heap Reference Enumeration (jvmtiHeapReferenceKind)
Constant	Value	Description
JVMTI_HEAP_REFERENCE_CLASS	1	Reference from an object to its class.
JVMTI_HEAP_REFERENCE_FIELD	2	Reference from an object to the value of one of its instance fields.
JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT	3	Reference from an array to one of its elements.
JVMTI_HEAP_REFERENCE_CLASS_LOADER	4	Reference from a class to its class loader.
JVMTI_HEAP_REFERENCE_SIGNERS	5	Reference from a class to its signers array.
JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN	6	Reference from a class to its protection domain.
JVMTI_HEAP_REFERENCE_INTERFACE	7	Reference from a class to one of its interfaces. Note: interfaces are defined via a constant pool reference, so the referenced interfaces may also be reported with a JVMTI_HEAP_REFERENCE_CONSTANT_POOL reference kind.
JVMTI_HEAP_REFERENCE_STATIC_FIELD	8	Reference from a class to the value of one of its static fields.
JVMTI_HEAP_REFERENCE_CONSTANT_POOL	9	Reference from a class to a resolved entry in the constant pool.
JVMTI_HEAP_REFERENCE_SUPERCLASS	10	Reference from a class to its superclass. A callback is bot not sent if the superclass is java.lang.Object. Note: loaded classes define superclasses via a constant pool reference, so the referenced superclass may also be reported with a JVMTI_HEAP_REFERENCE_CONSTANT_POOL reference kind.
JVMTI_HEAP_REFERENCE_JNI_GLOBAL	21	Heap root reference: JNI global reference.
JVMTI_HEAP_REFERENCE_SYSTEM_CLASS	22	Heap root reference: System class.
JVMTI_HEAP_REFERENCE_MONITOR	23	Heap root reference: monitor.
JVMTI_HEAP_REFERENCE_STACK_LOCAL	24	Heap root reference: local variable on the stack.
JVMTI_HEAP_REFERENCE_JNI_LOCAL	25	Heap root reference: JNI local reference.
JVMTI_HEAP_REFERENCE_THREAD	26	Heap root reference: Thread.
JVMTI_HEAP_REFERENCE_OTHER	27	Heap root reference: other heap root reference.

Definitions for the single character type descriptors of primitive types.

Primitive Type Enumeration (jvmtiPrimitiveType)
Constant	Value	Description
JVMTI_PRIMITIVE_TYPE_BOOLEAN	90	'Z' - Java programming language boolean - JNI jboolean
JVMTI_PRIMITIVE_TYPE_BYTE	66	'B' - Java programming language byte - JNI jbyte
JVMTI_PRIMITIVE_TYPE_CHAR	67	'C' - Java programming language char - JNI jchar
JVMTI_PRIMITIVE_TYPE_SHORT	83	'S' - Java programming language short - JNI jshort
JVMTI_PRIMITIVE_TYPE_INT	73	'I' - Java programming language int - JNI jint
JVMTI_PRIMITIVE_TYPE_LONG	74	'J' - Java programming language long - JNI jlong
JVMTI_PRIMITIVE_TYPE_FLOAT	70	'F' - Java programming language float - JNI jfloat
JVMTI_PRIMITIVE_TYPE_DOUBLE	68	'D' - Java programming language double - JNI jdouble

Reference information structure for Field references

Reference information returned for JVMTI_HEAP_REFERENCE_FIELD and JVMTI_HEAP_REFERENCE_STATIC_FIELD references.

typedef struct {
    jint index;
} jvmtiHeapReferenceInfoField;

jvmtiHeapReferenceInfoField - Reference information structure for Field references
Field	Type	Description
index	jint	For JVMTI_HEAP_REFERENCE_FIELD, the referrer object is not a class or an inteface. In this case, index is the index of the field in the class of the referrer object. This class is referred to below as C. For JVMTI_HEAP_REFERENCE_STATIC_FIELD, the referrer object is a class (referred to below as C) or an interface (referred to below as I). In this case, index is the index of the field in that class or interface. If the referrer object is not an interface, then the field indices are determined as follows: make a list of all the fields in C and its superclasses, starting with all the fields in java.lang.Object and ending with all the fields in C. Within this list, put the fields for a given class in the order returned by GetClassFields. Assign the fields in this list indices n, n+1, ..., in order, where n is the count of the fields in all the interfaces implemented by C. Note that C implements all interfaces directly implemented by its superclasses; as well as all superinterfaces of these interfaces. If the referrer object is an interface, then the field indices are determined as follows: make a list of the fields directly declared in I. Within this list, put the fields in the order returned by GetClassFields. Assign the fields in this list indices n, n+1, ..., in order, where n is the count of the fields in all the superinterfaces of I. All fields are included in this computation, regardless of field modifier (static, public, private, etc). For example, given the following classes and interfaces: interface I0 { int p = 0; } interface I1 extends I0 { int x = 1; } interface I2 extends I0 { int y = 2; } class C1 implements I1 { public static int a = 3; private int b = 4; } class C2 extends C1 implements I2 { static int q = 5; final int r = 6; } Assume that GetClassFields called on C1 returns the fields of C1 in the order: a, b; and that the fields of C2 are returned in the order: q, r. An instance of class C1 will have the following field indices: a 2 The count of the fields in the interfaces implemented by C1 is two (n=2): p of I0 and x of I1. b 3 the subsequent index. The class C1 will have the same field indices. An instance of class C2 will have the following field indices: a 3 The count of the fields in the interfaces implemented by C2 is three (n=3): p of I0, x of I1 and y of I2 (an interface of C2). Note that the field p of I0 is only included once. b 4 the subsequent index to "a". q 5 the subsequent index to "b". r 6 the subsequent index to "q". The class C2 will have the same field indices. Note that a field may have a different index depending on the object that is viewing it -- for example field "a" above. Note also: not all field indices may be visible from the callbacks, but all indices are shown for illustrative purposes. The interface I1 will have the following field indices: x 1 The count of the fields in the superinterfaces of I1 is one (n=1): p of I0.

Reference information structure for Array references

Reference information returned for JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT references.

typedef struct {
    jint index;
} jvmtiHeapReferenceInfoArray;

jvmtiHeapReferenceInfoArray - Reference information structure for Array references
Field	Type	Description
index	jint	The array index.

Reference information structure for Constant Pool references

Reference information returned for JVMTI_HEAP_REFERENCE_CONSTANT_POOL references.

typedef struct {
    jint index;
} jvmtiHeapReferenceInfoConstantPool;

jvmtiHeapReferenceInfoConstantPool - Reference information structure for Constant Pool references
Field	Type	Description
index	jint	The index into the constant pool of the class. See the description in The Javaâ„¢ Virtual Machine Specification, Chapter 4.4.

Reference information structure for Local Variable references

Reference information returned for JVMTI_HEAP_REFERENCE_STACK_LOCAL references.

typedef struct {
    jlong thread_tag;
    jlong thread_id;
    jint depth;
    jmethodID method;
    jlocation location;
    jint slot;
} jvmtiHeapReferenceInfoStackLocal;

jvmtiHeapReferenceInfoStackLocal - Reference information structure for Local Variable references
Field	Type	Description
thread_tag	jlong	The tag of the thread corresponding to this stack, zero if not tagged.
thread_id	jlong	The unique thread ID of the thread corresponding to this stack.
depth	jint	The depth of the frame.
method	jmethodID	The method executing in this frame.
location	jlocation	The currently executing location in this frame.
slot	jint	The slot number of the local variable.

Reference information structure for JNI local references

Reference information returned for JVMTI_HEAP_REFERENCE_JNI_LOCAL references.

typedef struct {
    jlong thread_tag;
    jlong thread_id;
    jint depth;
    jmethodID method;
} jvmtiHeapReferenceInfoJniLocal;

jvmtiHeapReferenceInfoJniLocal - Reference information structure for JNI local references
Field	Type	Description
thread_tag	jlong	The tag of the thread corresponding to this stack, zero if not tagged.
thread_id	jlong	The unique thread ID of the thread corresponding to this stack.
depth	jint	The depth of the frame.
method	jmethodID	The method executing in this frame.

Reference information structure for Other references

Reference information returned for other references.

typedef struct {
    jlong reserved1;
    jlong reserved2;
    jlong reserved3;
    jlong reserved4;
    jlong reserved5;
    jlong reserved6;
    jlong reserved7;
    jlong reserved8;
} jvmtiHeapReferenceInfoReserved;

jvmtiHeapReferenceInfoReserved - Reference information structure for Other references
Field	Type	Description
reserved1	jlong	reserved for future use.
reserved2	jlong	reserved for future use.
reserved3	jlong	reserved for future use.
reserved4	jlong	reserved for future use.
reserved5	jlong	reserved for future use.
reserved6	jlong	reserved for future use.
reserved7	jlong	reserved for future use.
reserved8	jlong	reserved for future use.

Reference information structure

The information returned about referrers. Represented as a union of the various kinds of reference information.

typedef union {
    jvmtiHeapReferenceInfoField field;
    jvmtiHeapReferenceInfoArray array;
    jvmtiHeapReferenceInfoConstantPool constant_pool;
    jvmtiHeapReferenceInfoStackLocal stack_local;
    jvmtiHeapReferenceInfoJniLocal jni_local;
    jvmtiHeapReferenceInfoReserved other;
} jvmtiHeapReferenceInfo;

jvmtiHeapReferenceInfo - Reference information structure
Field	Type	Description
field	jvmtiHeapReferenceInfoField	The referrer information for JVMTI_HEAP_REFERENCE_FIELD and JVMTI_HEAP_REFERENCE_STATIC_FIELD references.
array	jvmtiHeapReferenceInfoArray	The referrer information for For JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT references.
constant_pool	jvmtiHeapReferenceInfoConstantPool	The referrer information for For JVMTI_HEAP_REFERENCE_CONSTANT_POOL references.
stack_local	jvmtiHeapReferenceInfoStackLocal	The referrer information for For JVMTI_HEAP_REFERENCE_STACK_LOCAL references.
jni_local	jvmtiHeapReferenceInfoJniLocal	The referrer information for For JVMTI_HEAP_REFERENCE_JNI_LOCAL references.
other	jvmtiHeapReferenceInfoReserved	reserved for future use.

Heap callback function structure

typedef struct {
    jvmtiHeapIterationCallback heap_iteration_callback;
    jvmtiHeapReferenceCallback heap_reference_callback;
    jvmtiPrimitiveFieldCallback primitive_field_callback;
    jvmtiArrayPrimitiveValueCallback array_primitive_value_callback;
    jvmtiStringPrimitiveValueCallback string_primitive_value_callback;
    jvmtiReservedCallback reserved5;
    jvmtiReservedCallback reserved6;
    jvmtiReservedCallback reserved7;
    jvmtiReservedCallback reserved8;
    jvmtiReservedCallback reserved9;
    jvmtiReservedCallback reserved10;
    jvmtiReservedCallback reserved11;
    jvmtiReservedCallback reserved12;
    jvmtiReservedCallback reserved13;
    jvmtiReservedCallback reserved14;
    jvmtiReservedCallback reserved15;
} jvmtiHeapCallbacks;

jvmtiHeapCallbacks - Heap callback function structure
Field	Type	Description
heap_iteration_callback	jvmtiHeapIterationCallback	The callback to be called to describe an object in the heap. Used by the IterateThroughHeap function, ignored by the FollowReferences function.
heap_reference_callback	jvmtiHeapReferenceCallback	The callback to be called to describe an object reference. Used by the FollowReferences function, ignored by the IterateThroughHeap function.
primitive_field_callback	jvmtiPrimitiveFieldCallback	The callback to be called to describe a primitive field.
array_primitive_value_callback	jvmtiArrayPrimitiveValueCallback	The callback to be called to describe an array of primitive values.
string_primitive_value_callback	jvmtiStringPrimitiveValueCallback	The callback to be called to describe a String value.
reserved5	jvmtiReservedCallback	Reserved for future use..
reserved6	jvmtiReservedCallback	Reserved for future use..
reserved7	jvmtiReservedCallback	Reserved for future use..
reserved8	jvmtiReservedCallback	Reserved for future use..
reserved9	jvmtiReservedCallback	Reserved for future use..
reserved10	jvmtiReservedCallback	Reserved for future use..
reserved11	jvmtiReservedCallback	Reserved for future use..
reserved12	jvmtiReservedCallback	Reserved for future use..
reserved13	jvmtiReservedCallback	Reserved for future use..
reserved14	jvmtiReservedCallback	Reserved for future use..
reserved15	jvmtiReservedCallback	Reserved for future use..

Rationale: The heap dumping functionality (below) uses a callback for each object. While it would seem that a buffered approach would provide better throughput, tests do not show this to be the case--possibly due to locality of memory reference or array access overhead.

Heap Iteration Callback

Heap Reference Callback

Primitive Field Callback

Array Primitive Value Callback

String Primitive Value Callback

reserved for future use Callback

Follow References

jvmtiError
FollowReferences(jvmtiEnv* env,
            jint heap_filter,
            jclass klass,
            jobject initial_object,
            const jvmtiHeapCallbacks* callbacks,
            const void* user_data)

This function initiates a traversal over the objects that are directly and indirectly reachable from the specified object or, if initial_object is not specified, all objects reachable from the heap roots. The heap root are the set of system classes, JNI globals, references from thread stacks, and other objects used as roots for the purposes of garbage collection. This function operates by traversing the reference graph. Let A, B, ... represent objects. When a reference from A to B is traversed, when a reference from a heap root to B is traversed, or when B is specified as the initial_object, then B is said to be visited. A reference from A to B is not traversed until A is visited. References are reported in the same order that the references are traversed. Object references are reported by invoking the agent supplied callback function jvmtiHeapReferenceCallback. In a reference from A to B, A is known as the referrer and B as the referree. The callback is invoked exactly once for each reference from a referrer; this is true even if there are reference cycles or multiple paths to the referrer. There may be more than one reference between a referrer and a referree, each reference is reported. These references may be distinguished by examining the reference_kind and reference_info parameters of the jvmtiHeapReferenceCallback callback. This function reports a Java programming language view of object references, not a virtual machine implementation view. The following object references are reported when they are non-null:

• Instance objects report references to each non-primitive instance fields (including inherited fields).
• Instance objects report a reference to the object type (class).
• Classes report a reference to the superclass and directly implemented/extended interfaces.
• Classes report a reference to the class loader, protection domain, signers, and resolved entries in the constant pool.
• Classes report a reference to each directly declared non-primitive static field.
• Arrays report a reference to the array type (class) and each array element.
• Primitive arrays report a reference to the array type.

This function can also be used to examine primitive (non-object) values. The primitive value of an array or String is reported after the object has been visited; it is reported by invoking the agent supplied callback function jvmtiArrayPrimitiveValueCallback or jvmtiStringPrimitiveValueCallback. A primitive field is reported after the object with that field is visited; it is reported by invoking the agent supplied callback function jvmtiPrimitiveFieldCallback. Whether a callback is provided or is NULL only determines whether the callback will be invoked, it does not influence which objects are visited nor does it influence whether other callbacks will be invoked. However, the visit control flags returned by jvmtiHeapReferenceCallback do determine if the objects referenced by the current object as visited. The heap filter flags and klass provided as parameters to this function do not control which objects are visited but they do control which objects and primitive values are reported by the callbacks. For example, if the only callback that was set is array_primitive_value_callback and klass is set to the array of bytes class, then only arrays of byte will be reported. The table below summarizes this:

During the execution of this function the state of the heap does not change: no objects are allocated, no objects are garbage collected, and the state of objects (including held values) does not change. As a result, threads executing Java programming language code, threads attempting to resume the execution of Java programming language code, and threads attempting to execute JNI functions are typically stalled.

Iterate Through Heap

jvmtiError
IterateThroughHeap(jvmtiEnv* env,
            jint heap_filter,
            jclass klass,
            const jvmtiHeapCallbacks* callbacks,
            const void* user_data)

Initiate an iteration over all objects in the heap. This includes both reachable and unreachable objects. Objects are visited in no particular order. Heap objects are reported by invoking the agent supplied callback function jvmtiHeapIterationCallback. References between objects are not reported. If only reachable objects are desired, or if object reference information is needed, use FollowReferences. This function can also be used to examine primitive (non-object) values. The primitive value of an array or String is reported after the object has been visited; it is reported by invoking the agent supplied callback function jvmtiArrayPrimitiveValueCallback or jvmtiStringPrimitiveValueCallback. A primitive field is reported after the object with that field is visited; it is reported by invoking the agent supplied callback function jvmtiPrimitiveFieldCallback. Unless the iteration is aborted by the Heap Visit Control Flags returned by a callback, all objects in the heap are visited. Whether a callback is provided or is NULL only determines whether the callback will be invoked, it does not influence which objects are visited nor does it influence whether other callbacks will be invoked. The heap filter flags and klass provided as parameters to this function do not control which objects are visited but they do control which objects and primitive values are reported by the callbacks. For example, if the only callback that was set is array_primitive_value_callback and klass is set to the array of bytes class, then only arrays of byte will be reported. The table below summarizes this (contrast this with FollowReferences):

During the execution of this function the state of the heap does not change: no objects are allocated, no objects are garbage collected, and the state of objects (including held values) does not change. As a result, threads executing Java programming language code, threads attempting to resume the execution of Java programming language code, and threads attempting to execute JNI functions are typically stalled.

Get Tag

jvmtiError
GetTag(jvmtiEnv* env,
            jobject object,
            jlong* tag_ptr)

Retrieve the tag associated with an object. The tag is a long value typically used to store a unique identifier or pointer to object information. The tag is set with SetTag. Objects for which no tags have been set return a tag value of zero.

Set Tag

jvmtiError
SetTag(jvmtiEnv* env,
            jobject object,
            jlong tag)

Set the tag associated with an object. The tag is a long value typically used to store a unique identifier or pointer to object information. The tag is visible with GetTag.

Get Objects With Tags

jvmtiError
GetObjectsWithTags(jvmtiEnv* env,
            jint tag_count,
            const jlong* tags,
            jint* count_ptr,
            jobject** object_result_ptr,
            jlong** tag_result_ptr)

Return objects in the heap with the specified tags. The format is parallel arrays of objects and tags.

Force Garbage Collection

jvmtiError
ForceGarbageCollection(jvmtiEnv* env)

Force the VM to perform a garbage collection. The garbage collection is as complete as possible. This function does not cause finalizers to be run. This function does not return until the garbage collection is finished. Although garbage collection is as complete as possible there is no guarantee that all ObjectFree events will have been sent by the time that this function returns. In particular, an object may be prevented from being freed because it is awaiting finalization.

Heap (1.0)

Heap (1.0) functions:

• Iterate Over Objects Reachable From Object
• Iterate Over Reachable Objects
• Iterate Over Heap
• Iterate Over Instances Of Class

Heap (1.0) function types:

• Heap Object Callback
• Heap Root Object Callback
• Stack Reference Object Callback
• Object Reference Callback

Heap (1.0) types:

• jvmtiHeapObjectFilter - Heap Object Filter Enumeration
• jvmtiHeapRootKind - Heap Root Kind Enumeration
• jvmtiObjectReferenceKind - Object Reference Enumeration
• jvmtiIterationControl - Iteration Control Enumeration

These functions and data types were introduced in the original JVM TI version 1.0 and have been superseded by more powerful and flexible versions which:

• Allow access to primitive values (the value of Strings, arrays, and primitive fields)
• Allow the tag of the referrer to be set, thus enabling more efficient localized reference graph building
• Provide more extensive filtering abilities
• Are extensible, allowing their abilities to grow in future versions of JVM TI

Please use the current Heap functions.

Heap Object Filter Enumeration (jvmtiHeapObjectFilter)
Constant	Value	Description
JVMTI_HEAP_OBJECT_TAGGED	1	Tagged objects only.
JVMTI_HEAP_OBJECT_UNTAGGED	2	Untagged objects only.
JVMTI_HEAP_OBJECT_EITHER	3	Either tagged or untagged objects.

Heap Root Kind Enumeration (jvmtiHeapRootKind)
Constant	Value	Description
JVMTI_HEAP_ROOT_JNI_GLOBAL	1	JNI global reference.
JVMTI_HEAP_ROOT_SYSTEM_CLASS	2	System class.
JVMTI_HEAP_ROOT_MONITOR	3	Monitor.
JVMTI_HEAP_ROOT_STACK_LOCAL	4	Stack local.
JVMTI_HEAP_ROOT_JNI_LOCAL	5	JNI local reference.
JVMTI_HEAP_ROOT_THREAD	6	Thread.
JVMTI_HEAP_ROOT_OTHER	7	Other.

Object Reference Enumeration (jvmtiObjectReferenceKind)
Constant	Value	Description
JVMTI_REFERENCE_CLASS	1	Reference from an object to its class.
JVMTI_REFERENCE_FIELD	2	Reference from an object to the value of one of its instance fields. For references of this kind the referrer_index parameter to the jvmtiObjectReferenceCallback is the index of the the instance field. The index is based on the order of all the object's fields. This includes all fields of the directly declared static and instance fields in the class, and includes all fields (both public and private) fields declared in superclasses and superinterfaces. The index is thus calculated by summing the index of the field in the directly declared class (see GetClassFields), with the total number of fields (both public and private) declared in all superclasses and superinterfaces. The index starts at zero.
JVMTI_REFERENCE_ARRAY_ELEMENT	3	Reference from an array to one of its elements. For references of this kind the referrer_index parameter to the jvmtiObjectReferenceCallback is the array index.
JVMTI_REFERENCE_CLASS_LOADER	4	Reference from a class to its class loader.
JVMTI_REFERENCE_SIGNERS	5	Reference from a class to its signers array.
JVMTI_REFERENCE_PROTECTION_DOMAIN	6	Reference from a class to its protection domain.
JVMTI_REFERENCE_INTERFACE	7	Reference from a class to one of its interfaces.
JVMTI_REFERENCE_STATIC_FIELD	8	Reference from a class to the value of one of its static fields. For references of this kind the referrer_index parameter to the jvmtiObjectReferenceCallback is the index of the the static field. The index is based on the order of all the object's fields. This includes all fields of the directly declared static and instance fields in the class, and includes all fields (both public and private) fields declared in superclasses and superinterfaces. The index is thus calculated by summing the index of the field in the directly declared class (see GetClassFields), with the total number of fields (both public and private) declared in all superclasses and superinterfaces. The index starts at zero. Note: this definition differs from that in the JVM TI 1.0 Specification. Rationale: No known implementations used the 1.0 definition.
JVMTI_REFERENCE_CONSTANT_POOL	9	Reference from a class to a resolved entry in the constant pool. For references of this kind the referrer_index parameter to the jvmtiObjectReferenceCallback is the index into constant pool table of the class, starting at 1. See The Javaâ„¢ Virtual Machine Specification, Chapter 4.4.

Iteration Control Enumeration (jvmtiIterationControl)
Constant	Value	Description
JVMTI_ITERATION_CONTINUE	1	Continue the iteration. If this is a reference iteration, follow the references of this object.
JVMTI_ITERATION_IGNORE	2	Continue the iteration. If this is a reference iteration, ignore the references of this object.
JVMTI_ITERATION_ABORT	0	Abort the iteration.

Heap Object Callback

Heap Root Object Callback

Stack Reference Object Callback

Object Reference Callback