--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/hotspot/src/share/vm/prims/jvmti.xml Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,14267 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
+<!--
+ Copyright 2002-2006 Sun Microsystems, Inc. All Rights Reserved.
+ DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+ This code is free software; you can redistribute it and/or modify it
+ under the terms of the GNU General Public License version 2 only, as
+ published by the Free Software Foundation.
+
+ This code is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ version 2 for more details (a copy is included in the LICENSE file that
+ accompanied this code).
+
+ You should have received a copy of the GNU General Public License version
+ 2 along with this work; if not, write to the Free Software Foundation,
+ Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+ Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ CA 95054 USA or visit www.sun.com if you need additional information or
+ have any questions.
+
+-->
+
+<!DOCTYPE specification [
+ <!ELEMENT specification (title, intro*, functionsection, errorsection,
+ eventsection, datasection, issuessection, changehistory)>
+ <!ATTLIST specification label CDATA #REQUIRED
+ majorversion CDATA #REQUIRED
+ minorversion CDATA #REQUIRED
+ microversion CDATA #REQUIRED>
+
+ <!ELEMENT title (#PCDATA|jvmti|tm)*>
+ <!ATTLIST title subtitle CDATA #REQUIRED>
+
+ <!ELEMENT intro ANY>
+ <!ATTLIST intro id CDATA #IMPLIED
+ label CDATA "">
+
+ <!ELEMENT functionsection (intro*, category*)>
+ <!ATTLIST functionsection label CDATA #REQUIRED>
+
+ <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*,
+ (function|callback|elide)*)>
+ <!ATTLIST category id CDATA #REQUIRED
+ label CDATA #REQUIRED>
+
+ <!ELEMENT function (synopsis, typedef*, description?, origin,
+ (capabilities|eventcapabilities),
+ parameters, errors)>
+ <!ATTLIST function id CDATA #REQUIRED
+ num CDATA #REQUIRED
+ phase (onload|onloadOnly|start|live|any) #IMPLIED
+ callbacksafe (safe|unsafe) #IMPLIED
+ impl CDATA #IMPLIED
+ hide CDATA #IMPLIED
+ jkernel (yes|no) #IMPLIED
+ since CDATA "1.0">
+
+ <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
+ jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void),
+ synopsis, description?, parameters)>
+ <!ATTLIST callback id CDATA #REQUIRED
+ since CDATA "1.0">
+
+ <!ELEMENT synopsis (#PCDATA|jvmti)*>
+
+ <!ELEMENT typedef (description?, field*)>
+ <!ATTLIST typedef id CDATA #REQUIRED
+ label CDATA #REQUIRED
+ since CDATA "1.0">
+
+ <!ELEMENT uniontypedef (description?, field*)>
+ <!ATTLIST uniontypedef id CDATA #REQUIRED
+ label CDATA #REQUIRED
+ since CDATA "1.0">
+
+ <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
+ jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct),
+ description)>
+ <!ATTLIST field id CDATA #REQUIRED>
+
+ <!ELEMENT capabilitiestypedef (description?, capabilityfield*)>
+ <!ATTLIST capabilitiestypedef id CDATA #REQUIRED
+ label CDATA #REQUIRED>
+
+ <!ELEMENT capabilityfield (description)>
+ <!ATTLIST capabilityfield id CDATA #REQUIRED
+ disp1 CDATA ""
+ disp2 CDATA ""
+ since CDATA "1.0">
+
+ <!ELEMENT description ANY>
+
+ <!ELEMENT capabilities (required*, capability*)>
+
+ <!ELEMENT eventcapabilities EMPTY>
+
+ <!ELEMENT required ANY>
+ <!ATTLIST required id CDATA #REQUIRED>
+
+ <!ELEMENT capability ANY>
+ <!ATTLIST capability id CDATA #REQUIRED>
+
+ <!ELEMENT parameters (param*)>
+
+ <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
+ jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype|
+ outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf),
+ description)>
+ <!ATTLIST param id CDATA #REQUIRED>
+
+ <!ELEMENT jmethodID EMPTY>
+ <!ATTLIST jmethodID class CDATA #IMPLIED
+ native CDATA #IMPLIED>
+
+ <!ELEMENT jfieldID EMPTY>
+ <!ATTLIST jfieldID class CDATA #IMPLIED>
+
+ <!ELEMENT jclass EMPTY>
+ <!ATTLIST jclass method CDATA #IMPLIED
+ field CDATA #IMPLIED>
+
+ <!ELEMENT jframeID EMPTY>
+ <!ATTLIST jframeID thread CDATA #IMPLIED>
+
+ <!ELEMENT jrawMonitorID EMPTY>
+
+ <!ELEMENT jthread EMPTY>
+ <!ATTLIST jthread started CDATA #IMPLIED
+ null CDATA #IMPLIED
+ frame CDATA #IMPLIED
+ impl CDATA #IMPLIED>
+
+ <!ELEMENT varargs EMPTY>
+
+ <!ELEMENT jthreadGroup EMPTY>
+ <!ELEMENT jobject EMPTY>
+ <!ELEMENT jvalue EMPTY>
+ <!ELEMENT jchar EMPTY>
+ <!ELEMENT jint EMPTY>
+ <!ATTLIST jint min CDATA #IMPLIED>
+ <!ELEMENT jlong EMPTY>
+ <!ELEMENT jfloat EMPTY>
+ <!ELEMENT jdouble EMPTY>
+ <!ELEMENT jlocation EMPTY>
+ <!ELEMENT jboolean EMPTY>
+ <!ELEMENT char EMPTY>
+ <!ELEMENT uchar EMPTY>
+ <!ELEMENT size_t EMPTY>
+ <!ELEMENT void EMPTY>
+ <!ELEMENT enum (#PCDATA)*>
+ <!ELEMENT struct (#PCDATA)*>
+
+ <!ELEMENT nullok ANY>
+
+ <!ELEMENT ptrtype ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
+ jthreadGroup|jobject|jvalue), nullok?)>
+
+ <!ELEMENT outptr ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
+ jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
+ jlocation|jboolean|char|uchar|size_t|void), nullok?)>
+
+ <!ELEMENT allocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
+ jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
+ jlocation|jboolean|char|uchar|size_t|void), nullok?)>
+ <!ATTLIST allocbuf incount CDATA #IMPLIED
+ outcount CDATA #IMPLIED>
+
+ <!ELEMENT allocallocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
+ jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
+ jlocation|jboolean|char|uchar|size_t|void), nullok?)>
+ <!ATTLIST allocallocbuf incount CDATA #IMPLIED
+ outcount CDATA #IMPLIED>
+
+ <!ELEMENT inptr (struct, nullok?)>
+
+ <!ELEMENT inbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
+ jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
+ jlocation|jboolean|char|uchar|size_t|void), nullok?)>
+ <!ATTLIST inbuf incount CDATA #IMPLIED>
+
+ <!ELEMENT outbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
+ jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
+ jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)>
+ <!ATTLIST outbuf incount CDATA #IMPLIED
+ outcount CDATA #IMPLIED>
+
+ <!ELEMENT vmbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
+ jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
+ jlocation|jboolean|char|uchar|size_t|void), nullok?)>
+ <!ATTLIST vmbuf incount CDATA #IMPLIED
+ outcount CDATA #IMPLIED>
+
+ <!ELEMENT agentbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
+ jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
+ jlocation|jboolean|char|uchar|size_t|void), nullok?)>
+ <!ATTLIST agentbuf incount CDATA #IMPLIED
+ outcount CDATA #IMPLIED>
+
+ <!ELEMENT allocfieldbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
+ jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
+ jlocation|jboolean|char|uchar|size_t|void))>
+ <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED>
+
+ <!ELEMENT errors (error*)>
+
+ <!ELEMENT error ANY>
+ <!ATTLIST error id CDATA #REQUIRED>
+
+ <!ELEMENT errorsection (intro*, errorcategory*)>
+ <!ATTLIST errorsection label CDATA #REQUIRED>
+
+ <!ELEMENT errorcategory (intro*, errorid*)>
+ <!ATTLIST errorcategory id CDATA #REQUIRED
+ label CDATA #REQUIRED>
+
+ <!ELEMENT errorid ANY>
+ <!ATTLIST errorid id CDATA #REQUIRED
+ num CDATA #REQUIRED>
+
+ <!ELEMENT datasection (intro*, basetypes*)>
+
+ <!ELEMENT basetypes (intro*, basetype*)>
+ <!ATTLIST basetypes id CDATA #REQUIRED
+ label CDATA #REQUIRED>
+
+ <!ELEMENT basetype (definition?,description)>
+ <!ATTLIST basetype id CDATA #REQUIRED>
+
+ <!ELEMENT definition (#PCDATA|jvmti)*>
+
+ <!ELEMENT eventsection (intro*, (event|elide)*)>
+ <!ATTLIST eventsection label CDATA #REQUIRED>
+
+ <!ELEMENT event (description, origin, typedef*, capabilities, parameters)>
+ <!ATTLIST event id CDATA #REQUIRED
+ label CDATA #REQUIRED
+ const CDATA #REQUIRED
+ num CDATA #REQUIRED
+ phase (onload|start|live|any) #IMPLIED
+ filtered (thread|global) #IMPLIED
+ since CDATA "1.0">
+
+ <!ELEMENT issuessection (intro*)>
+ <!ATTLIST issuessection label CDATA #REQUIRED>
+
+ <!ELEMENT changehistory (intro*, change*)>
+ <!ATTLIST changehistory update CDATA #REQUIRED
+ id CDATA #REQUIRED>
+
+ <!ELEMENT change ANY>
+ <!ATTLIST change date CDATA #REQUIRED
+ version CDATA #IMPLIED>
+
+ <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*>
+ <!ATTLIST functionlink id CDATA #REQUIRED>
+
+ <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*>
+ <!ATTLIST datalink id CDATA #REQUIRED>
+
+ <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*>
+ <!ATTLIST typelink id CDATA #REQUIRED>
+
+ <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*>
+ <!ATTLIST fieldlink id CDATA #REQUIRED
+ struct CDATA #REQUIRED>
+
+ <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*>
+ <!ATTLIST paramlink id CDATA #REQUIRED>
+
+ <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*>
+ <!ATTLIST eventlink id CDATA #REQUIRED>
+
+ <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*>
+ <!ATTLIST errorlink id CDATA #REQUIRED>
+
+ <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*>
+ <!ATTLIST externallink id CDATA #REQUIRED>
+
+ <!ELEMENT vmspeclink EMPTY>
+ <!ATTLIST vmspeclink id CDATA #IMPLIED>
+ <!ATTLIST vmspeclink name CDATA #IMPLIED>
+ <!ATTLIST vmspeclink preposition CDATA #IMPLIED>
+
+ <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*>
+ <!ATTLIST internallink id CDATA #REQUIRED>
+
+ <!ELEMENT functionphaselist EMPTY>
+ <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED>
+
+ <!ELEMENT eventphaselist EMPTY>
+ <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED>
+
+ <!ELEMENT issue ANY>
+
+ <!ELEMENT rationale ANY>
+
+ <!ELEMENT todo ANY>
+
+ <!ELEMENT origin (#PCDATA)*>
+
+ <!ELEMENT elide (intro|function|callback|event)*>
+ <!ATTLIST elide why CDATA #IMPLIED>
+
+ <!ELEMENT constants (constant*)>
+ <!ATTLIST constants id CDATA #REQUIRED
+ label CDATA #REQUIRED
+ kind (enum|bits|const) #REQUIRED
+ since CDATA "1.0">
+
+ <!ELEMENT constant ANY>
+ <!ATTLIST constant id CDATA #REQUIRED
+ num CDATA #REQUIRED>
+
+ <!ELEMENT tm (#PCDATA)>
+
+ <!ELEMENT i (#PCDATA|jvmti|tm)*>
+
+ <!ELEMENT b (#PCDATA|jvmti|code)*>
+
+ <!ELEMENT code (#PCDATA|space)*>
+
+ <!ELEMENT pre ANY>
+
+ <!ELEMENT space EMPTY>
+
+ <!ELEMENT jvmti EMPTY>
+
+ <!ELEMENT example (#PCDATA|i)*>
+
+ <!ELEMENT br EMPTY>
+
+ <!ELEMENT p EMPTY>
+
+ <!ELEMENT dl (dt|dd)+>
+
+ <!ELEMENT dd ANY>
+
+ <!ELEMENT dt (#PCDATA|jvmti|code|i|b)*>
+
+ <!ELEMENT table (tr)+>
+
+ <!ELEMENT tr (td|th)*>
+
+ <!ELEMENT td ANY>
+ <!ATTLIST td align (left|right|center) "center">
+
+ <!ELEMENT th ANY>
+ <!ATTLIST th align (left|right|center) "center">
+
+ <!ELEMENT ul (li)+>
+ <!ATTLIST ul type (disc|circle|square) "disc">
+
+ <!ELEMENT li ANY>
+ ]>
+
+<specification label="JVM(TM) Tool Interface"
+ majorversion="1"
+ minorversion="1"
+ microversion="109">
+ <title subtitle="Version">
+ <tm>JVM</tm> Tool Interface
+ </title>
+
+ <intro id="whatIs" label="What is the JVM Tool Interface?">
+ The <tm>JVM</tm> Tool Interface (<jvmti/>)
+ 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
+ <tm>Java</tm> virtual machine (VM).
+ <p/>
+ <jvmti/> 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.
+ <p/>
+ <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual
+ machine.
+ <p/>
+ <jvmti/> is a two-way interface.
+ A client of <jvmti/>, hereafter called an <i>agent</i>,
+ can be notified of
+ interesting occurrences through <internallink id="EventSection">events</internallink>.
+ <jvmti/>
+ can query and control the application through many
+ <internallink id="FunctionSection">functions</internallink>,
+ either in response to events or
+ independent of them.
+ <p/>
+ 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 (<jvmti/>). 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.
+ </intro>
+
+ <intro id="architecture" label="Architecture">
+ Tools can be written directly to <jvmti/> or indirectly
+ through higher level interfaces.
+ The Java Platform Debugger Architecture includes <jvmti/>, but also
+ contains higher-level, out-of-process debugger interfaces. The higher-level
+ interfaces are more appropriate than <jvmti/> for many tools.
+ For more information on the Java Platform Debugger Architecture,
+ see the
+ <externallink id="http://java.sun.com/products/jpda/">Java
+ Platform Debugger Architecture website</externallink>.
+ </intro>
+
+ <intro id="writingAgents" label="Writing Agents">
+ Agents can be written in any native language that supports C
+ language calling conventions and C or C++
+ definitions.
+ <p/>
+ The function, event, data type, and constant definitions needed for
+ using <jvmti/> are defined in the include file <code>jvmti.h</code>.
+ To use these definitions add the <tm>J2SE</tm> include directory
+ to your include path and add
+ <example>
+#include <jvmti.h>
+ </example>
+ to your source code.
+ </intro>
+
+ <intro id="deployingAgents" label="Deploying Agents">
+ An agent is deployed in a platform specific manner but is typically the
+ platform equivalent of a dynamic library. On the <tm>Windows</tm> operating
+ system, for example, an agent library is a "Dynamic Linked Library" (DLL).
+ On the <tm>Solaris</tm> Operating Environment, an agent library is a shared
+ object (<code>.so</code> file).
+ <p/>
+ An agent may be started at VM startup by specifying the agent library
+ name using a <internallink id="starting">command line option</internallink>.
+ Some implementations may support a mechanism to <internallink id="onattach">
+ start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.
+ The details of how this is initiated are implementation specific.
+ </intro>
+
+ <intro id="starting" label="Agent Command Line Options">
+ The term "command-line option" is used below to
+ mean options supplied in the <code>JavaVMInitArgs</code> argument
+ to the <code>JNI_CreateJavaVM</code> function of the JNI
+ Invocation API.
+ <p/>
+ 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.
+ <dl>
+ <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt>
+ <dd>
+ The name following <code>-agentlib:</code> 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 <i><agent-lib-name></i> is expanded to an
+ operating system specific file name.
+ The <i><options></i> will be passed to the agent on start-up.
+ For example, if the option
+ <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to
+ load the shared library <code>foo.dll</code> from the system <code>PATH</code>
+ under <tm>Windows</tm> or <code>libfoo.so</code> from the
+ <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment.
+ </dd>
+ <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt>
+ <dd>
+ The path following <code>-agentpath:</code> is the absolute path from which
+ to load the library.
+ No library name expansion will occur.
+ The <i><options></i> will be passed to the agent on start-up.
+ For example, if the option
+ <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to
+ load the shared library <code>c:\myLibs\foo.dll</code>.
+ </dd>
+ </dl>
+ The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink>
+ in the library will be invoked.
+ <p/>
+ Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
+ will be searched for JNI native method implementations to facilitate the
+ use of Java programming language code in tools, as is needed for
+ <internallink id="bci">bytecode instrumentation</internallink>.
+ <p/>
+ 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
+ <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
+ <p/>
+ These switches do the above and nothing more - they do not change the
+ state of the VM or <jvmti/>. No command line options are needed
+ to enable <jvmti/>
+ or aspects of <jvmti/>, this is handled programmatically
+ by the use of
+ <internallink id="capability">capabilities</internallink>.
+ </intro>
+
+ <intro id="startup" label="Agent Start-Up">
+ The VM starts each agent by invoking a start-up function.
+ If the agent is started in the <code>OnLoad</code>
+ <functionlink id="GetPhase">phase</functionlink> the function
+ <internallink id="onload"><code>Agent_OnLoad</code></internallink>
+ will be invoked.
+ If the agent is started in the live
+ <functionlink id="GetPhase">phase</functionlink> the function
+ <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
+ will be invoked.
+ Exactly one call to a start-up function is made per agent.
+ </intro>
+
+ <intro id="onload" label="Agent Start-Up (OnLoad phase)">
+ If an agent is started during the <code>OnLoad</code> phase then its
+ agent library must export a start-up function with the following prototype:
+ <example>
+JNIEXPORT jint JNICALL
+Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>
+ The VM will start the agent by calling this function.
+ It will be called early enough in VM initialization that:
+ <ul>
+ <li><functionlink id="SetSystemProperty">system properties</functionlink>
+ may be set before they have been used in the start-up of the VM</li>
+ <li>the full set of
+ <internallink id="capability">capabilities</internallink>
+ is still available (note that capabilities that configure the VM
+ may only be available at this time--see the
+ <internallink id="capability">Capability function section</internallink>)</li>
+ <li>no bytecodes have executed</li>
+ <li>no classes have been loaded</li>
+ <li>no objects have been created</li>
+ </ul>
+ <p/>
+ The VM will call the <code>Agent_OnLoad</code> function with
+ <i><options></i> as the second argument -
+ that is, using the command-line option examples,
+ <code>"opt1,opt2"</code> will be passed to the <code>char *options</code>
+ argument of <code>Agent_OnLoad</code>.
+ The <code>options</code> argument is encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ If <i>=<options></i> is not specified,
+ a zero length string is passed to <code>options</code>.
+ The lifespan of the <code>options</code> string is the <code>Agent_OnLoad</code>
+ call. If needed beyond this time the string or parts of the string must
+ be copied.
+ The period between when <code>Agent_OnLoad</code> is called and when it
+ returns is called the <i>OnLoad phase</i>.
+ Since the VM is not initialized during the OnLoad
+ <functionlink id="GetPhase">phase</functionlink>,
+ the set of allowed operations
+ inside <code>Agent_OnLoad</code> 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 <functionlink id="SetEventCallbacks"></functionlink>. Once
+ the VM initialization event is received
+ (that is, the <eventlink id="VMInit">VMInit</eventlink>
+ 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.
+ </rationale>
+ <p/>
+ The return value from <code>Agent_OnLoad</code> is used to indicate an error.
+ Any value other than zero indicates an error and causes termination of the VM.
+ </intro>
+
+ <intro id="onattach" label="Agent Start-Up (Live phase)">
+ A VM may support a mechanism that allows agents to be started in the VM during the live
+ <functionlink id="GetPhase">phase</functionlink>. 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.
+ <p/>
+ If an agent is started during the live phase then its agent library
+ must export a start-up function
+ with the following prototype:
+ <example>
+JNIEXPORT jint JNICALL
+Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>
+ <p/>
+ 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 <i><vm></i> is the Java VM.
+ The <i><options></i> argument is the startup options provided to the agent.
+ <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8
+ </internallink> string.
+ If startup options were not provided, a zero length string is passed to
+ <code>options</code>. The lifespan of the <code>options</code> string is the
+ <code>Agent_OnAttach</code> call. If needed beyond this time the string or parts of
+ the string must be copied.
+ <p/>
+ Note that some <internallink id="capability">capabilities</internallink>
+ may not be available in the live phase.
+ <p/>
+ The <code>Agent_OnAttach</code> 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.
+ </intro>
+
+ <intro id="onunload" label="Agent Shutdown">
+ The library may optionally export a
+ shutdown function with the following prototype:
+ <example>
+JNIEXPORT void JNICALL
+Agent_OnUnload(JavaVM *vm)</example>
+ This function will be called by the VM when the library is about to be unloaded.
+ The library will be unloaded 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
+ <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
+ to be sent, the VM must have run at least to the point of initialization and a valid
+ <jvmti/> environment must exist which has set a callback for VMDeath
+ and enabled the event
+ None of these are required for <code>Agent_OnUnload</code> 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.
+ </intro>
+
+ <intro id="tooloptions" label="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 <code>JAVA_TOOL_OPTIONS</code> variable is
+ provided so that agents may be launched in these cases.
+ <p/>
+ Platforms which support environment variables or other named strings, may support the
+ <code>JAVA_TOOL_OPTIONS</code> 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:
+ <ul>
+ <li>All characters enclosed between a pair of single quote marks (''), except a single
+ quote, are quoted.</li>
+ <li>Double quote characters have no special meaning inside a pair of single quote marks.</li>
+ <li>All characters enclosed between a pair of double quote marks (""), except a double
+ quote, are quoted.</li>
+ <li>Single quote characters have no special meaning inside a pair of double quote marks.</li>
+ <li>A quoted part can start or end anywhere in the variable.</li>
+ <li>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.</li>
+ <li>The pair of quote marks is not included in the option.</li>
+ </ul>
+ <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied
+ in its <code>JavaVMInitArgs</code> 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.
+ </intro>
+
+ <intro id="environments" label="Environments">
+ The <jvmti/> specification supports the use of multiple simultaneous
+ <jvmti/> agents.
+ Each agent has its own <jvmti/> environment.
+ That is, the <jvmti/> state is
+ separate for each agent - changes to one environment do not affect the
+ others. The state of a <jvmti/>
+ environment includes:
+ <ul>
+ <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>
+ <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>
+ <li><internallink id="capability">the capabilities</internallink></li>
+ <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>
+ </ul>
+ Although their <jvmti/> 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. <jvmti/> 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.
+ <p/>
+ An agent creates a <jvmti/> environment
+ by passing a <jvmti/> version
+ as the interface ID to the JNI Invocation API function
+ <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><code>GetEnv</code></externallink>.
+ See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink>
+ for more details on the creation and use of
+ <jvmti/> environments.
+ Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from
+ <internallink id="onload"><code>Agent_OnLoad</code></internallink>.
+ </intro>
+
+ <intro id="bci" label="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
+ <i>bytecode instrumentation</i>, 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 <code>MyProfiler.methodEntered()</code>.
+ 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.
+ <p/>
+ Instrumentation can be inserted in one of three ways:
+ <ul>
+ <li>
+ Static Instrumentation: The class file is instrumented before it
+ is loaded into the VM - for example, by creating a duplicate directory of
+ <code>*.class</code> 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.
+ </li>
+ <li>
+ 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 <eventlink id="ClassFileLoadHook"/>
+ event, triggered by the class load,
+ provides this functionality. This mechanism provides efficient
+ and complete access to one-time instrumentation.
+ </li>
+ <li>
+ Dynamic Instrumentation: A class which is already loaded (and possibly
+ even running) is modified. This optional feature is provided by the
+ <eventlink id="ClassFileLoadHook"/> event, triggered by calling the
+ <functionlink id="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.
+ </li>
+ </ul>
+ <p/>
+ The class modification functionality provided in this interface
+ is intended to provide a mechanism for instrumentation
+ (the <eventlink id="ClassFileLoadHook"/> event
+ and the <functionlink id="RetransformClasses"/> function)
+ and, during development, for fix-and-continue debugging
+ (the <functionlink id="RedefineClasses"/> function).
+ <p/>
+ 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
+ <code>Object</code>. Assuming that the constructor is initially
+ empty, the constructor could be changed to:
+ <example>
+ public Object() {
+ MyProfiler.allocationTracker(this);
+ }
+ </example>
+ However, if this change was made using the
+ <eventlink id="ClassFileLoadHook"/>
+ event then this might impact a typical VM as follows:
+ the first created object will call the constructor causing a class load of
+ <code>MyProfiler</code>; which will then cause
+ object creation, and since <code>MyProfiler</code> 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, <code>trackAllocations</code> could be set in the
+ handler for the <code>VMInit</code> event.
+ <example>
+ static boolean trackAllocations = false;
+
+ public Object() {
+ if (trackAllocations) {
+ MyProfiler.allocationTracker(this);
+ }
+ }
+ </example>
+ <p/>
+ The <functionlink id="SetNativeMethodPrefix"/> allows native methods
+ to be instrumented by the use of wrapper methods.
+ </intro>
+
+ <intro id="mUTF" label="Modified UTF-8 String Encoding">
+ <jvmti/> 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
+ <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/types.html#wp16542">
+ Modified UTF-8 Strings</externallink>
+ section of the JNI specification for details.
+ </intro>
+
+ <intro id="context" label="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:
+ <ul>
+ <li>"thread" means Java programming language thread.</li>
+ <li>"stack frame" means Java virtual machine stack frame.</li>
+ <li>"class" means Java programming language class.</li>
+ <li>"heap" means Java virtual machine heap.</li>
+ <li>"monitor" means Java programming language object monitor.</li>
+ </ul>
+ <p/>
+ Sun, Sun Microsystems, the Sun logo, Java, and JVM
+ are trademarks or registered trademarks of Sun
+ Microsystems, Inc. in the U.S. and other countries.
+ </intro>
+
+
+<functionsection label="Functions">
+ <intro id="jvmtiEnvAccess" label="Accessing Functions">
+ Native code accesses <jvmti/> features
+ by calling <jvmti/> functions.
+ Access to <jvmti/> functions is by use of an interface pointer
+ in the same manner as
+ <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html">Java
+ Native Interface (JNI) functions</externallink> are accessed.
+ The <jvmti/> interface pointer is called the
+ <i>environment pointer</i>.
+ <p/>
+ An environment pointer is a pointer to an environment and has
+ the type <code>jvmtiEnv*</code>.
+ An environment has information about its <jvmti/> connection.
+ The first value in the environment is a pointer to the function table.
+ The function table is an array of pointers to <jvmti/> functions.
+ Every function pointer is at a predefined offset inside the
+ array.
+ <p/>
+ 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:
+ <example>
+jvmtiEnv *jvmti;
+...
+jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &class_count, &classes);
+ </example>
+ <p/>
+ When used from the C++ language:
+ functions are accessed as member functions of <code>jvmtiEnv</code>;
+ the environment pointer is not passed to the function call; for example:
+ <example>
+jvmtiEnv *jvmti;
+...
+jvmtiError err = jvmti->GetLoadedClasses(&class_count, &classes);
+ </example>
+ Unless otherwise stated, all examples and declarations in this
+ specification use the C language.
+ <p/>
+ A <jvmti/> environment can be obtained through the JNI Invocation API
+ <code>GetEnv</code> function:
+ <example>
+jvmtiEnv *jvmti;
+...
+(*jvm)->GetEnv(jvm, &jvmti, JVMTI_VERSION_1_0);
+ </example>
+ Each call to <code>GetEnv</code>
+ creates a new <jvmti/> connection and thus
+ a new <jvmti/> environment.
+ The <code>version</code> argument of <code>GetEnv</code> must be
+ a <jvmti/> version.
+ The returned environment may have a different version than the
+ requested version but the returned environment must be compatible.
+ <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a
+ compatible version is not available, if <jvmti/> is not supported or
+ <jvmti/> is not supported in the current VM configuration.
+ Other interfaces may be added for creating <jvmti/> environments
+ in specific contexts.
+ Each environment has its own state (for example,
+ <functionlink id="SetEventNotificationMode">desired events</functionlink>,
+ <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and
+ <functionlink id="AddCapabilities">capabilities</functionlink>).
+ An environment is released with
+ <functionlink id="DisposeEnvironment"></functionlink>.
+ Thus, unlike JNI which has one environment per thread, <jvmti/> environments work
+ across threads and are created dynamically.
+ </intro>
+
+ <intro id="functionReturn" label="Function Return Values">
+ <jvmti/> functions always return an
+ <internallink id="ErrorSection">error code</internallink> via the
+ <datalink id="jvmtiError"/> function return value.
+ Some functions can return additional
+ values through pointers provided by the calling function.
+ In some cases, <jvmti/> functions allocate memory that your program must
+ explicitly deallocate. This is indicated in the individual <jvmti/>
+ function descriptions. Empty lists, arrays, sequences, etc are
+ returned as <code>NULL</code>.
+ <p/>
+ In the event that the <jvmti/> function encounters
+ an error (any return value other than <code>JVMTI_ERROR_NONE</code>) 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.
+ </intro>
+
+<intro id="refs" label="Managing JNI Object References">
+ <jvmti/> functions identify objects with JNI references
+ (<datalink id="jobject"/> and <datalink id="jclass"/>)
+ and their derivatives
+ (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).
+ References passed to
+ <jvmti/> functions can be either global or local, but they must be
+ strong references. All references returned by <jvmti/> functions are
+ local references--these local references are created
+ during the <jvmti/> call.
+ Local references are a resource that must be managed (see the
+ <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html#wp18654">JNI Documentation</externallink>).
+ 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 <jvmti/> 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
+ <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.
+ Conversely, to preserve references beyond the
+ return from native code, they must be converted to global references.
+ These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/>
+ as they are not <datalink id="jobject"/>s.
+</intro>
+
+ <intro id="prereqState" label="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 <jvmti/> implementation is responsible for bringing the VM to a
+ safe and consistent state for performing the function.
+ </intro>
+
+ <intro id="functionsExceptions" label="Exceptions and Functions">
+ <jvmti/> functions never throw exceptions; error conditions are
+ communicated via the
+ <internallink id="functionReturn">function return value</internallink>.
+ Any existing exception state is preserved across a call to a
+ <jvmti/> function.
+ See the
+ <externallink
+ id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html#wp770"
+ >Java Exceptions</externallink>
+ section of the JNI specification for information on handling exceptions.
+ </intro>
+
+ <category id="memory" label="Memory Management">
+ <intro>
+ These functions provide for the allocation and deallocation of
+ memory used by <jvmti/> functionality and can be used to provide
+ working memory for agents.
+ Memory managed by <jvmti/> is not compatible with other memory
+ allocation libraries and mechanisms.
+ </intro>
+
+ <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">
+ <synopsis>Allocate</synopsis>
+ <description>
+ Allocate an area of memory through the <jvmti/> allocator.
+ The allocated
+ memory should be freed with <functionlink id="Deallocate"></functionlink>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="size">
+ <jlong/>
+ <description>
+ The number of bytes to allocate.
+ <rationale>
+ <code>jlong</code> is used for compatibility with JVMDI.
+ </rationale>
+ </description>
+ </param>
+ <param id="mem_ptr">
+ <allocbuf incount="size"><uchar/></allocbuf>
+ <description>
+ On return, a pointer to the beginning of the allocated memory.
+ If <code>size</code> is zero, <code>NULL</code> is returned.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_OUT_OF_MEMORY">
+ Memory request cannot be honored.
+ </error>
+ <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
+ <paramlink id="size"></paramlink> is less than zero.
+ </error>
+ </errors>
+ </function>
+
+ <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47">
+ <synopsis>Deallocate</synopsis>
+ <description>
+ Deallocate <code>mem</code> using the <jvmti/> allocator.
+ This function should
+ be used to deallocate any memory allocated and returned
+ by a <jvmti/> function
+ (including memory allocated with <functionlink id="Allocate"></functionlink>).
+ All allocated memory must be deallocated
+ or the memory cannot be reclaimed.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="mem">
+ <outbuf>
+ <uchar/>
+ <nullok>the call is ignored</nullok>
+ </outbuf>
+ <description>
+ A pointer to the beginning of the allocated memory.
+ Please ignore "On return, the elements are set."
+ <todo>keep it from generating "On return, the elements are set"</todo>
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+ </category>
+
+ <category id="threadCategory" label="Thread">
+ <intro>
+ </intro>
+
+ <function id="GetThreadState" num="17">
+ <synopsis>Get Thread State</synopsis>
+ <description>
+ Get the state of a thread. The state of the thread is represented by the
+ answers to the hierarchical set of questions below:
+ <ul type="circle">
+ <li><i>Alive?</i>
+ <ul>
+ <li>Not alive.
+ <ul type="circle">
+ <li><i>Why not alive?</i>
+ <ul>
+ <li>New.</li>
+ <li>Terminated (<datalink
+ id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>Alive (<datalink
+ id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>)
+ <ul type="circle">
+ <li><i>Suspended?</i>
+ <ul>
+ <li>Suspended (<datalink
+ id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li>
+ <li>Not suspended</li>
+ </ul>
+ </li>
+ <li><i>Interrupted?</i>
+ <ul>
+ <li>Interrupted (<datalink
+ id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li>
+ <li>Not interrupted.</li>
+ </ul>
+ </li>
+ <li><i>In native?</i>
+ <ul>
+ <li>In native code (<datalink
+ id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li>
+ <li>In Java programming language code</li>
+ </ul>
+ </li>
+ <li><i>What alive state?</i>
+ <ul>
+ <li>Runnable (<datalink
+ id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li>
+ <li>Blocked (<datalink
+ id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li>
+ <li>Waiting (<datalink
+ id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>)
+ <ul type="circle">
+ <li><i>Timed wait?</i>
+ <ul>
+ <li>Indefinite (<datalink
+ id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li>
+ <li>Timed (<datalink
+ id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li>
+ </ul>
+ </li>
+ <li><i>Why waiting?</i>
+ <ul>
+ <li>Object.wait (<datalink
+ id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li>
+ <li>LockSupport.park (<datalink
+ id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li>
+ <li>Sleeping (<datalink
+ id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p/>
+ The answers are represented by the following bit vector.
+ <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">
+ <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">
+ Thread is alive. Zero if thread is new (not started) or terminated.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">
+ Thread has completed execution.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">
+ Thread is runnable.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">
+ Thread is waiting to enter a synchronization block/method or,
+ after an <code>Object.wait()</code>, waiting to re-enter a
+ synchronization block/method.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">
+ Thread is waiting.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">
+ Thread is waiting without a timeout.
+ For example, <code>Object.wait()</code>.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">
+ Thread is waiting with a maximum time to wait specified.
+ For example, <code>Object.wait(long)</code>.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">
+ Thread is sleeping -- <code>Thread.sleep(long)</code>.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">
+ Thread is waiting on an object monitor -- <code>Object.wait</code>.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">
+ Thread is parked, for example: <code>LockSupport.park</code>,
+ <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
+ Thread suspended.
+ <code>java.lang.Thread.suspend()</code>
+ or a <jvmti/> suspend function
+ (such as <functionlink id="SuspendThread"></functionlink>)
+ has been called on the thread. If this bit
+ is set, the other bits refer to the thread state before suspension.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">
+ Thread has been interrupted.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="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.
+ <p/>
+ 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
+ <jvmti/> functions, may be implemented as VM code.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000">
+ Defined by VM vendor.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000">
+ Defined by VM vendor.
+ </constant>
+ <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000">
+ Defined by VM vendor.
+ </constant>
+ </constants>
+ The following definitions are used to convert <jvmti/> thread state
+ to <code>java.lang.Thread.State</code> style states.
+ <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits">
+ <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK"
+ num="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
+ </constant>
+ <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW"
+ num="0">
+ <code>java.lang.Thread.State.NEW</code>
+ </constant>
+ <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED"
+ num="JVMTI_THREAD_STATE_TERMINATED">
+ <code>java.lang.Thread.State.TERMINATED</code>
+ </constant>
+ <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE"
+ num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE">
+ <code>java.lang.Thread.State.RUNNABLE</code>
+ </constant>
+ <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED"
+ num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER">
+ <code>java.lang.Thread.State.BLOCKED</code>
+ </constant>
+ <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING"
+ num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY">
+ <code>java.lang.Thread.State.WAITING</code>
+ </constant>
+ <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING"
+ num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT">
+ <code>java.lang.Thread.State.TIMED_WAITING</code>
+ </constant>
+ </constants>
+ <b>Rules</b>
+ <p/>
+ 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
+ <ul type="circle">
+ <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li>
+ <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li>
+ <li><code>JVMTI_THREAD_STATE_WAITING</code></li>
+ </ul>
+ can be set (a <tm>J2SE</tm> compliant implementation will always set
+ one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set).
+ And if any of these are set, the enclosing answer
+ <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
+ No more than one of
+ <ul type="circle">
+ <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li>
+ <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li>
+ </ul>
+ can be set (a <tm>J2SE</tm> compliant implementation will always set
+ one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set).
+ And if either is set, the enclosing answers
+ <code>JVMTI_THREAD_STATE_ALIVE</code> and
+ <code>JVMTI_THREAD_STATE_WAITING</code> are set.
+ No more than one of
+ <ul type="circle">
+ <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li>
+ <li><code>JVMTI_THREAD_STATE_PARKED</code></li>
+ <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li>
+ </ul>
+ can be set. And if any of these is set, the enclosing answers
+ <code>JVMTI_THREAD_STATE_ALIVE</code> and
+ <code>JVMTI_THREAD_STATE_WAITING</code> are set.
+ Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set,
+ then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set.
+ If a state <i>A</i> is implemented using the mechanism of
+ state <i>B</i> then it is state <i>A</i> which
+ is returned by this function.
+ For example, if <code>Thread.sleep(long)</code>
+ is implemented using <code>Object.wait(long)</code>
+ then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code>
+ which is returned.
+ More than one of
+ <ul type="circle">
+ <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li>
+ <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li>
+ <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li>
+ </ul>
+ can be set, but if any is set,
+ <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
+ <p/>
+ And finally,
+ <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless
+ <code>JVMTI_THREAD_STATE_ALIVE</code> is not set.
+ <p/>
+ 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.
+ <p/>
+ <b>Examples</b>
+ <p/>
+ Note that the values below exclude reserved and vendor bits.
+ <p/>
+ The state of a thread blocked at a <code>synchronized</code>-statement would be:
+ <example>
+ JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
+ </example>
+ The state of a thread which hasn't started yet would be:
+ <example>
+ 0
+ </example>
+ The state of a thread at a <code>Object.wait(3000)</code> would be:
+ <example>
+ JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING +
+ JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT +
+ JVMTI_THREAD_STATE_MONITOR_WAITING
+ </example>
+ The state of a thread suspended while runnable would be:
+ <example>
+ JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED
+ </example>
+ <p/>
+ <b>Testing the State</b>
+ <p/>
+ 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:
+ <example>
+ jint state;
+ jvmtiError err;
+
+ err = (*jvmti)->GetThreadState(jvmti, thread, &state);
+ if (err == JVMTI_ERROR_NONE) {
+ if (state & JVMTI_THREAD_STATE_SLEEPING) { ...
+ </example>
+ <p/>
+ For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be:
+ <example>
+ if (state & JVMTI_THREAD_STATE_WAITING) { ...
+ </example>
+ 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:
+ <example>
+ if ((state & (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0) { ...
+ </example>
+ To distinguish timed from untimed <code>Object.wait</code>:
+ <example>
+ 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");
+ }
+ }
+ </example>
+ <p/>
+ <b>Relationship to <code>java.lang.Thread.State</code></b>
+ <p/>
+ The thread state represented by <code>java.lang.Thread.State</code>
+ returned from <code>java.lang.Thread.getState()</code> is a subset of the
+ information returned from this function.
+ The corresponding <code>java.lang.Thread.State</code> can be determined
+ by using the provided conversion masks.
+ For example, this returns the name of the <code>java.lang.Thread.State</code> thread state:
+ <example>
+ 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";
+ }
+ </example>
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" started="maybe" impl="noconvert"/>
+ <description>
+ The thread to query.
+ </description>
+ </param>
+ <param id="thread_state_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to state flags,
+ as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetCurrentThread" phase="start" num="18" since="1.1">
+ <synopsis>Get Current Thread</synopsis>
+ <description>
+ Get the current thread.
+ The current thread is the Java programming language thread which has called the function.
+ <p/>
+ Note that most <jvmti/> functions that take a thread
+ as an argument will accept <code>NULL</code> to mean
+ the current thread.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="thread_ptr">
+ <outptr><jthread/></outptr>
+ <description>
+ On return, points to the current thread.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetAllThreads" num="4">
+ <synopsis>Get All Threads</synopsis>
+ <description>
+ 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 <code>java.lang.Thread.isAlive()</code>
+ would return <code>true</code>, that is, the thread has
+ been started and has not yet died.
+ The universe of threads is determined by the context of the <jvmti/>
+ environment, which typically is all threads attached to the VM.
+ Note that this includes <jvmti/> agent threads
+ (see <functionlink id="RunAgentThread"/>).
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="threads_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of running threads.
+ </description>
+ </param>
+ <param id="threads_ptr">
+ <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
+ <description>
+ On return, points to an array of references, one
+ for each running thread.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="SuspendThread" num="5">
+ <synopsis>Suspend Thread</synopsis>
+ <description>
+ Suspend the specified thread. If the calling thread is specified,
+ this function will not return until some other thread calls
+ <functionlink id="ResumeThread"></functionlink>.
+ If the thread is currently suspended, this function
+ does nothing and returns an error.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_suspend"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ The thread to suspend.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_THREAD_SUSPENDED">
+ Thread already suspended.
+ </error>
+ </errors>
+ </function>
+
+ <elide>
+ <function id="SuspendAllThreads" num="101">
+ <synopsis>Suspend All Threads</synopsis>
+ <description>
+ <issue>
+ There has been no explicit call for this function, and it will
+ thus be removed if there is no interest.
+ </issue>
+ Suspend all live threads except:
+ <ul>
+ <li>already suspended threads</li>
+ <li>those listed in <paramlink id="except_list"></paramlink></li>
+ <li>certain system (non application) threads, as determined
+ by the VM implementation</li>
+ </ul>
+ The threads are Java programming language threads;
+ native threads which are not attached to the VM are not
+ Java programming language threads.
+ A thread is live if <code>java.lang.Thread.isAlive()</code>
+ would return <code>true</code>, that is, the thread has
+ been started and has not yet died.
+ The universe of threads is determined
+ by the context of the <jvmti/>
+ environment, which, typically, is all threads attached to the VM,
+ except critical VM internal threads and <jvmti/> agent threads
+ (see <functionlink id="RunAgentThread"/>).
+ <p/>
+ If the calling thread is specified,
+ all other threads are suspended first then the caller thread is suspended -
+ this function will not return until some other thread calls
+ <functionlink id="ResumeThread"></functionlink>.
+ <p/>
+ The list of actually
+ suspended threads is returned in
+ <paramlink id="suspended_list_ptr"></paramlink>.
+ Suspension is as defined in <functionlink id="SuspendThread"></functionlink>.
+ <functionlink id="ResumeThreadList"></functionlink>
+ can be used to resume the suspended threads.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_suspend"></required>
+ </capabilities>
+ <parameters>
+ <param id="except_count">
+ <jint min="0"/>
+ <description>
+ The number of threads in the list of threads not to be suspended.
+ </description>
+ </param>
+ <param id="except_list">
+ <inbuf incount="except_count">
+ <jthread/>
+ <nullok>not an error if <code>except_count == 0</code></nullok>
+ </inbuf>
+ <description>
+ The list of threads not to be suspended.
+ </description>
+ </param>
+ <param id="suspended_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of threads suspended by this call.
+ </description>
+ </param>
+ <param id="suspended_list_ptr">
+ <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf>
+ <description>
+ On return, points to an array of references, one
+ for each thread suspended.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_THREAD">
+ A thread in <paramlink id="except_list"></paramlink> was invalid.
+ </error>
+ <error id="JVMTI_ERROR_NULL_POINTER">
+ Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
+ and <paramlink id="except_count"></paramlink> was non-zero.
+ </error>
+ </errors>
+ </function>
+ </elide>
+
+ <function id="SuspendThreadList" num="92">
+ <synopsis>Suspend Thread List</synopsis>
+ <description>
+ Suspend the <paramlink id="request_count"></paramlink>
+ threads specified in the
+ <paramlink id="request_list"></paramlink> array.
+ Threads may be resumed with
+ <functionlink id="ResumeThreadList"></functionlink> or
+ <functionlink id="ResumeThread"></functionlink>.
+ If the calling thread is specified in the
+ <paramlink id="request_list"></paramlink> array, this function will
+ not return until some other thread resumes it.
+ Errors encountered in the suspension of a thread
+ are returned in the <paramlink id="results"></paramlink>
+ array, <b>not</b> in the return value of this function.
+ Threads that are currently suspended do not change state.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_suspend"></required>
+ </capabilities>
+ <parameters>
+ <param id="request_count">
+ <jint min="0"/>
+ <description>
+ The number of threads to suspend.
+ </description>
+ </param>
+ <param id="request_list">
+ <inbuf incount="request_count"><jthread/></inbuf>
+ <description>
+ The list of threads to suspend.
+ </description>
+ </param>
+ <param id="results">
+ <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
+ <description>
+ An agent supplied array of
+ <paramlink id="request_count"></paramlink> elements.
+ On return, filled with the error code for
+ the suspend of the corresponding thread.
+ The error code will be
+ <errorlink id="JVMTI_ERROR_NONE"></errorlink>
+ if the thread was suspended by this call.
+ Possible error codes are those specified
+ for <functionlink id="SuspendThread"></functionlink>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="ResumeThread" num="6">
+ <synopsis>Resume Thread</synopsis>
+ <description>
+ Resume a suspended thread.
+ Any threads currently suspended through
+ a <jvmti/> suspend function (eg.
+ <functionlink id="SuspendThread"></functionlink>)
+ or <code>java.lang.Thread.suspend()</code>
+ will resume execution;
+ all other threads are unaffected.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_suspend"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread/>
+ <description>
+ The thread to resume.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
+ Thread was not suspended.
+ </error>
+ <error id="JVMTI_ERROR_INVALID_TYPESTATE">
+ The state of the thread has been modified, and is now inconsistent.
+ </error>
+ </errors>
+ </function>
+
+ <function id="ResumeThreadList" num="93">
+ <synopsis>Resume Thread List</synopsis>
+ <description>
+ Resume the <paramlink id="request_count"></paramlink>
+ threads specified in the
+ <paramlink id="request_list"></paramlink> array.
+ Any thread suspended through
+ a <jvmti/> suspend function (eg.
+ <functionlink id="SuspendThreadList"></functionlink>)
+ or <code>java.lang.Thread.suspend()</code>
+ will resume execution.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_suspend"></required>
+ </capabilities>
+ <parameters>
+ <param id="request_count">
+ <jint min="0"/>
+ <description>
+ The number of threads to resume.
+ </description>
+ </param>
+ <param id="request_list">
+ <inbuf incount="request_count"><jthread/></inbuf>
+ <description>
+ The threads to resume.
+ </description>
+ </param>
+ <param id="results">
+ <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
+ <description>
+ An agent supplied array of
+ <paramlink id="request_count"></paramlink> elements.
+ On return, filled with the error code for
+ the resume of the corresponding thread.
+ The error code will be
+ <errorlink id="JVMTI_ERROR_NONE"></errorlink>
+ if the thread was suspended by this call.
+ Possible error codes are those specified
+ for <functionlink id="ResumeThread"></functionlink>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="StopThread" num="7">
+ <synopsis>Stop Thread</synopsis>
+ <description>
+ Send the specified asynchronous exception to the specified thread
+ (similar to <code>java.lang.Thread.stop</code>).
+ Normally, this function is used to kill the specified thread with an
+ instance of the exception <code>ThreadDeath</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_signal_thread"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread/>
+ <description>
+ The thread to stop.
+ </description>
+ </param>
+ <param id="exception">
+ <jobject/>
+ <description>
+ The asynchronous exception object.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="InterruptThread" num="8">
+ <synopsis>Interrupt Thread</synopsis>
+ <description>
+ Interrupt the specified thread
+ (similar to <code>java.lang.Thread.interrupt</code>).
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_signal_thread"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread impl="noconvert"/>
+ <description>
+ The thread to interrupt.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetThreadInfo" num="9">
+ <synopsis>Get Thread Info</synopsis>
+ <typedef id="jvmtiThreadInfo" label="Thread information structure">
+ <field id="name">
+ <allocfieldbuf><char/></allocfieldbuf>
+ <description>
+ The thread name, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </field>
+ <field id="priority">
+ <jint/>
+ <description>
+ The thread priority. See the thread priority constants:
+ <datalink id="jvmtiThreadPriority"></datalink>.
+ </description>
+ </field>
+ <field id="is_daemon">
+ <jboolean/>
+ <description>
+ Is this a daemon thread?
+ </description>
+ </field>
+ <field id="thread_group">
+ <jthreadGroup/>
+ <description>
+ The thread group to which this thread belongs.
+ <code>NULL</code> if the thread has died.
+ </description>
+ </field>
+ <field id="context_class_loader">
+ <jobject/>
+ <description>
+ The context class loader associated with this thread.
+ </description>
+ </field>
+ </typedef>
+ <description>
+ Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure
+ are filled in with details of the specified thread.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" impl="noconvert" started="maybe"/>
+ <description>
+ The thread to query.
+ </description>
+ </param>
+ <param id="info_ptr">
+ <outptr><struct>jvmtiThreadInfo</struct></outptr>
+ <description>
+ On return, filled with information describing the specified thread.
+ <p/>
+ For JDK 1.1 implementations that don't
+ recognize context class loaders,
+ the <code>context_class_loader</code> field will be NULL.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetOwnedMonitorInfo" num="10">
+ <synopsis>Get Owned Monitor Info</synopsis>
+ <description>
+ Get information about the monitors owned by the
+ specified thread.
+ </description>
+ <origin>jvmdiClone</origin>
+ <capabilities>
+ <required id="can_get_owned_monitor_info"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ The thread to query.
+ </description>
+ </param>
+ <param id="owned_monitor_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ The number of monitors returned.
+ </description>
+ </param>
+ <param id="owned_monitors_ptr">
+ <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf>
+ <description>
+ The array of owned monitors.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1">
+ <synopsis>Get Owned Monitor Stack Depth Info</synopsis>
+ <typedef id="jvmtiMonitorStackDepthInfo"
+ label="Monitor stack depth information structure">
+ <field id="monitor">
+ <jobject/>
+ <description>
+ The owned monitor.
+ </description>
+ </field>
+ <field id="stack_depth">
+ <jint/>
+ <description>
+ The stack depth. Corresponds to the stack depth used in the
+ <internallink id="stack">Stack Frame functions</internallink>.
+ That is, zero is the current frame, one is the frame which
+ called the current frame. And it is negative one if the
+ implementation cannot determine the stack depth (e.g., for
+ monitors acquired by JNI <code>MonitorEnter</code>).
+ </description>
+ </field>
+ </typedef>
+ <description>
+ Get information about the monitors owned by the
+ specified thread and the depth of the stack frame which locked them.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_get_owned_monitor_stack_depth_info"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ The thread to query.
+ </description>
+ </param>
+ <param id="monitor_info_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ The number of monitors returned.
+ </description>
+ </param>
+ <param id="monitor_info_ptr">
+ <allocbuf outcount="owned_monitor_depth_count_ptr">
+ <struct>jvmtiMonitorStackDepthInfo</struct>
+ </allocbuf>
+ <description>
+ The array of owned monitor depth information.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetCurrentContendedMonitor" num="11">
+ <synopsis>Get Current Contended Monitor</synopsis>
+ <description>
+ Get the object, if any, whose monitor the specified thread is waiting to
+ enter or waiting to regain through <code>java.lang.Object.wait</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_get_current_contended_monitor"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ The thread to query.
+ </description>
+ </param>
+ <param id="monitor_ptr">
+ <outptr><jobject/></outptr>
+ <description>
+ On return, filled with the current contended monitor, or
+ NULL if there is none.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <callback id="jvmtiStartFunction">
+ <void/>
+ <synopsis>Agent Start Function</synopsis>
+ <description>
+ Agent supplied callback function.
+ This function is the entry point for an agent thread
+ started with
+ <functionlink id="RunAgentThread"></functionlink>.
+ </description>
+ <parameters>
+ <param id="jvmti_env">
+ <outptr>
+ <struct>jvmtiEnv</struct>
+ </outptr>
+ <description>
+ The <jvmti/> environment.
+ </description>
+ </param>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment.
+ </description>
+ </param>
+ <param id="arg">
+ <outptr>
+ <void/>
+ </outptr>
+ <description>
+ The <code>arg</code> parameter passed to
+ <functionlink id="RunAgentThread"></functionlink>.
+ </description>
+ </param>
+ </parameters>
+ </callback>
+
+ <function id="RunAgentThread" num="12">
+ <synopsis>Run Agent Thread</synopsis>
+ <description>
+ Starts the execution of an agent thread. with the specified native function.
+ The parameter <paramlink id="arg"></paramlink> is forwarded on to the
+ <functionlink id="jvmtiStartFunction">start function</functionlink>
+ (specified with <paramlink id="proc"></paramlink>) 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 <code>java.lang.Thread</code> or
+ implementer of <code>java.lang.Runnable</code>.
+ Instead, the created thread can run entirely in native code.
+ However, the created thread does require a newly created instance
+ of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to
+ which it will be associated.
+ The thread object can be created with JNI calls.
+ <p/>
+ The following common thread priorities are provided for your convenience:
+ <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const">
+ <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1">
+ Minimum possible thread priority
+ </constant>
+ <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5">
+ Normal thread priority
+ </constant>
+ <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10">
+ Maximum possible thread priority
+ </constant>
+ </constants>
+ <p/>
+ The new thread is started as a daemon thread with the specified
+ <paramlink id="priority"></paramlink>.
+ If enabled, a <eventlink id="ThreadStart"/> event will be sent.
+ <p/>
+ Since the thread has been started, the thread will be live when this function
+ returns, unless the thread has died immediately.
+ <p/>
+ 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 <jvmti/> levels.
+ <p/>
+ The thread is not visible to Java programming language queries but is
+ included in <jvmti/> queries (for example,
+ <functionlink id="GetAllThreads"/> and
+ <functionlink id="GetAllStackTraces"/>).
+ <p/>
+ Upon execution of <code>proc</code>, the new thread will be attached to the
+ VM--see the JNI documentation on
+ <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/invocation.html#wp1060"
+ >Attaching to the VM</externallink>.
+ </description>
+ <origin>jvmdiClone</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread impl="noconvert" started="no"/>
+ <description>
+ The thread to run.
+ </description>
+ </param>
+ <param id="proc">
+ <ptrtype>
+ <struct>jvmtiStartFunction</struct>
+ </ptrtype>
+ <description>
+ The start function.
+ </description>
+ </param>
+ <param id="arg">
+ <inbuf>
+ <void/>
+ <nullok><code>NULL</code> is passed to the start function</nullok>
+ </inbuf>
+ <description>
+ The argument to the start function.
+ </description>
+ </param>
+ <param id="priority">
+ <jint/>
+ <description>
+ The priority of the started thread. Any thread
+ priority allowed by <code>java.lang.Thread.setPriority</code> can be used including
+ those in <datalink id="jvmtiThreadPriority"></datalink>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_PRIORITY">
+ <paramlink id="priority"/> is less than
+ <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>
+ or greater than
+ <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>
+ </error>
+ </errors>
+ </function>
+
+ <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">
+ <synopsis>Set Thread Local Storage</synopsis>
+ <description>
+ The VM stores a pointer value associated with each environment-thread
+ pair. This pointer value is called <i>thread-local storage</i>.
+ This value is <code>NULL</code> 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
+ <functionlink id="GetThreadLocalStorage"></functionlink>.
+ <p/>
+ This function is called by the agent to set the value of the <jvmti/>
+ thread-local storage. <jvmti/> supplies to the agent a pointer-size
+ thread-local storage that can be used to record per-thread
+ information.
+ </description>
+ <origin>jvmpi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ Store to this thread.
+ </description>
+ </param>
+ <param id="data">
+ <inbuf>
+ <void/>
+ <nullok>value is set to <code>NULL</code></nullok>
+ </inbuf>
+ <description>
+ The value to be entered into the thread-local storage.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102">
+ <synopsis>Get Thread Local Storage</synopsis>
+ <description>
+ Called by the agent to get the value of the <jvmti/> thread-local
+ storage.
+ </description>
+ <origin>jvmpi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" impl="noconvert"/>
+ <description>
+ Retrieve from this thread.
+ </description>
+ </param>
+ <param id="data_ptr">
+ <agentbuf><void/></agentbuf>
+ <description>
+ Pointer through which the value of the thread local
+ storage is returned.
+ If thread-local storage has not been set with
+ <functionlink id="SetThreadLocalStorage"></functionlink> the returned
+ pointer is <code>NULL</code>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ </category>
+
+ <category id="thread_groups" label="Thread Group">
+ <intro>
+ </intro>
+
+ <function id="GetTopThreadGroups" num="13">
+ <synopsis>Get Top Thread Groups</synopsis>
+ <description>
+ Return all top-level (parentless) thread groups in the VM.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="group_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of top-level thread groups.
+ </description>
+ </param>
+ <param id="groups_ptr">
+ <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
+ <description>
+ On return, refers to a pointer to the top-level thread group array.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetThreadGroupInfo" num="14">
+ <synopsis>Get Thread Group Info</synopsis>
+ <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure">
+ <field id="parent">
+ <jthreadGroup/>
+ <description>
+ The parent thread group.
+ </description>
+ </field>
+ <field id="name">
+ <allocfieldbuf><char/></allocfieldbuf>
+ <description>
+ The thread group's name, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </field>
+ <field id="max_priority">
+ <jint/>
+ <description>
+ The maximum priority for this thread group.
+ </description>
+ </field>
+ <field id="is_daemon">
+ <jboolean/>
+ <description>
+ Is this a daemon thread group?
+ </description>
+ </field>
+ </typedef>
+ <description>
+ Get information about the thread group. The fields of the
+ <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure
+ are filled in with details of the specified thread group.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="group">
+ <jthreadGroup/>
+ <description>
+ The thread group to query.
+ </description>
+ </param>
+ <param id="info_ptr">
+ <outptr><struct>jvmtiThreadGroupInfo</struct></outptr>
+ <description>
+ On return, filled with information describing the specified
+ thread group.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetThreadGroupChildren" num="15">
+ <synopsis>Get Thread Group Children</synopsis>
+ <description>
+ Get the live threads and active subgroups in this thread group.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="group">
+ <jthreadGroup/>
+ <description>
+ The group to query.
+ </description>
+ </param>
+ <param id="thread_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of live threads in this thread group.
+ </description>
+ </param>
+ <param id="threads_ptr">
+ <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf>
+ <description>
+ On return, points to an array of the live threads in this thread group.
+ </description>
+ </param>
+ <param id="group_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of active child thread groups
+ </description>
+ </param>
+ <param id="groups_ptr">
+ <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
+ <description>
+ On return, points to an array of the active child thread groups.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+ </category>
+
+ <category id="stack" label="Stack Frame">
+ <intro>
+ 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.
+ <p/>
+ Stack frames are as described in the
+ <vmspeclink id="Overview.doc.html#17257"
+ name="Frames section"/>.
+ That is, they correspond to method
+ invocations (including native methods) but do not correspond to platform native or
+ VM internal frames.
+ <p/>
+ A <jvmti/> 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 <code>main()</code> and <code>run()</code>.
+ However this presentation must be consistent across all <jvmti/> functionality which
+ uses stack frames or stack depth.
+ </intro>
+
+ <typedef id="jvmtiFrameInfo" label="Stack frame information structure">
+ <description>
+ Information about a stack frame is returned in this structure.
+ </description>
+ <field id="method">
+ <jmethodID/>
+ <description>
+ The method executing in this frame.
+ </description>
+ </field>
+ <field id="location">
+ <jlocation/>
+ <description>
+ The index of the instruction executing in this frame.
+ <code>-1</code> if the frame is executing a native method.
+ </description>
+ </field>
+ </typedef>
+
+ <typedef id="jvmtiStackInfo" label="Stack information structure">
+ <description>
+ Information about a set of stack frames is returned in this structure.
+ </description>
+ <field id="thread">
+ <jthread/>
+ <description>
+ On return, the thread traced.
+ </description>
+ </field>
+ <field id="state">
+ <jint/>
+ <description>
+ On return, the thread state. See <functionlink id="GetThreadState"></functionlink>.
+ </description>
+ </field>
+ <field id="frame_buffer">
+ <outbuf incount="max_frame_count">
+ <struct>jvmtiFrameInfo</struct>
+ </outbuf>
+ <description>
+ On return, this agent allocated buffer is filled
+ with stack frame information.
+ </description>
+ </field>
+ <field id="frame_count">
+ <jint/>
+ <description>
+ On return, the number of records filled into
+ <code>frame_buffer</code>.
+ This will be
+ min(<code>max_frame_count</code>, <i>stackDepth</i>).
+ </description>
+ </field>
+ </typedef>
+
+ <function id="GetStackTrace" num="104">
+ <synopsis>Get Stack Trace</synopsis>
+ <description>
+ Get information about the stack of a thread.
+ If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack,
+ the <paramlink id="max_frame_count"></paramlink> 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.
+ <p/>
+ 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.
+ <example>
+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);
+ if (err == JVMTI_ERROR_NONE) {
+ printf("Executing method: %s", methodName);
+ }
+}
+ </example>
+ <todo>
+ check example code.
+ </todo>
+ <p/>
+ The <paramlink id="thread"></paramlink> need not be suspended
+ to call this function.
+ <p/>
+ The <functionlink id="GetLineNumberTable"></functionlink>
+ function can be used to map locations to line numbers. Note that
+ this mapping can be done lazily.
+ </description>
+ <origin>jvmpi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ Fetch the stack trace of this thread.
+ </description>
+ </param>
+ <param id="start_depth">
+ <jint/>
+ <description>
+ Begin retrieving frames at this depth.
+ If non-negative, count from the current frame,
+ the first frame retrieved is at depth <code>start_depth</code>.
+ For example, if zero, start from the current frame; if one, start from the
+ caller of the current frame; if two, start from the caller of the
+ caller of the current frame; and so on.
+ If negative, count from below the oldest frame,
+ the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>,
+ where <i>stackDepth</i> is the count of frames on the stack.
+ For example, if negative one, only the oldest frame is retrieved;
+ if negative two, start from the frame called by the oldest frame.
+ </description>
+ </param>
+ <param id="max_frame_count">
+ <jint min="0"/>
+ <description>
+ The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
+ </description>
+ </param>
+ <param id="frame_buffer">
+ <outbuf incount="max_frame_count" outcount="count_ptr">
+ <struct>jvmtiFrameInfo</struct>
+ </outbuf>
+ <description>
+ On return, this agent allocated buffer is filled
+ with stack frame information.
+ </description>
+ </param>
+ <param id="count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of records filled in.
+ For non-negative <code>start_depth</code>, this will be
+ min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>).
+ For negative <code>start_depth</code>, this will be
+ min(<code>max_frame_count</code>, <code>-start_depth</code>).
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
+ <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>.
+ Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>.
+ </error>
+ </errors>
+ </function>
+
+
+ <function id="GetAllStackTraces" num="100">
+ <synopsis>Get All Stack Traces</synopsis>
+ <description>
+ Get information about the stacks of all live threads
+ (including <internallink id="RunAgentThread">agent threads</internallink>).
+ If <paramlink id="max_frame_count"/> is less than the depth of a stack,
+ the <paramlink id="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.
+ <p/>
+ 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.
+
+ <example>
+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);
+ </example>
+ <todo>
+ check example code.
+ </todo>
+
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="max_frame_count">
+ <jint min="0"/>
+ <description>
+ The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
+ </description>
+ </param>
+ <param id="stack_info_ptr">
+ <allocbuf>
+ <struct>jvmtiStackInfo</struct>
+ </allocbuf>
+ <description>
+ On return, this buffer is filled
+ with stack information for each thread.
+ The number of <datalink id="jvmtiStackInfo"/> records is determined
+ by <paramlink id="thread_count_ptr"/>.
+ <p/>
+ Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/>
+ buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
+ These buffers must not be separately deallocated.
+ </description>
+ </param>
+ <param id="thread_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ The number of threads traced.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetThreadListStackTraces" num="101">
+ <synopsis>Get Thread List Stack Traces</synopsis>
+ <description>
+ Get information about the stacks of the supplied threads.
+ If <paramlink id="max_frame_count"/> is less than the depth of a stack,
+ the <paramlink id="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.
+ <p/>
+ 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.
+ <p/>
+ If a thread has not yet started or terminates before the stack information is collected,
+ a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero)
+ will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked.
+ <p/>
+ See the example for the similar function
+ <functionlink id="GetAllStackTraces"/>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="thread_count">
+ <jint min="0"/>
+ <description>
+ The number of threads to trace.
+ </description>
+ </param>
+ <param id="thread_list">
+ <inbuf incount="thread_count"><jthread/></inbuf>
+ <description>
+ The list of threads to trace.
+ </description>
+ </param>
+ <param id="max_frame_count">
+ <jint min="0"/>
+ <description>
+ The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
+ </description>
+ </param>
+ <param id="stack_info_ptr">
+ <allocbuf outcount="thread_count">
+ <struct>jvmtiStackInfo</struct>
+ </allocbuf>
+ <description>
+ On return, this buffer is filled
+ with stack information for each thread.
+ The number of <datalink id="jvmtiStackInfo"/> records is determined
+ by <paramlink id="thread_count"/>.
+ <p/>
+ Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/>
+ buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
+ These buffers must not be separately deallocated.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_THREAD">
+ An element in <paramlink id="thread_list"/> is not a thread object.
+ </error>
+ </errors>
+ </function>
+
+ <elide>
+ <function id="AsyncGetStackTrace" num="1000">
+ <synopsis>Get Stack Trace--Asynchronous</synopsis>
+ <description>
+ Get information about the entire stack of a thread (or a sub-section of it).
+ This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink>
+ and is reentrant and safe to call
+ from asynchronous signal handlers.
+ The stack trace is returned only for the calling thread.
+ <p/>
+ The <functionlink id="GetLineNumberTable"></functionlink>
+ function can be used to map locations to line numbers. Note that
+ this mapping can be done lazily.
+ </description>
+ <origin>jvmpi</origin>
+ <capabilities>
+ <required id="can_get_async_stack_trace"></required>
+ <capability id="can_show_JVM_spec_async_frames">
+ If <code>false</code>,
+ <paramlink id="use_java_stack"></paramlink>
+ must be <code>false</code>.
+ </capability>
+ </capabilities>
+ <parameters>
+ <param id="use_java_stack">
+ <jboolean/>
+ <description>
+ Return the stack showing the <vmspeclink/>
+ model of the stack;
+ otherwise, show the internal representation of the stack with
+ inlined and optimized methods missing. If the virtual machine
+ is using the <i>Java Virtual Machine Specification</i> stack model
+ internally, this flag is ignored.
+ </description>
+ </param>
+ <param id="max_count">
+ <jint min="0"/>
+ <description>
+ The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
+ Retrieve this many unless the stack depth is less than <code>max_count</code>.
+ </description>
+ </param>
+ <param id="frame_buffer">
+ <outbuf incount="max_count" outcount="count_ptr">
+ <struct>jvmtiFrameInfo</struct>
+ <nullok>this information is not returned</nullok>
+ </outbuf>
+ <description>
+ The agent passes in a buffer
+ large enough to hold <code>max_count</code> records of
+ <datalink id="jvmtiFrameInfo"></datalink>. This buffer must be
+ pre-allocated by the agent.
+ </description>
+ </param>
+ <param id="count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of records filled in..
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_UNATTACHED_THREAD">
+ The thread being used to call this function is not attached
+ to the virtual machine. Calls must be made from attached threads.
+ </error>
+ </errors>
+ </function>
+ </elide>
+
+ <function id="GetFrameCount" num="16">
+ <synopsis>Get Frame Count</synopsis>
+ <description>
+ Get the number of frames currently in the specified thread's call stack.
+ <p/>
+ 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.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ The thread to query.
+ </description>
+ </param>
+ <param id="count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of frames in the call stack.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="PopFrame" num="80">
+ <synopsis>Pop Frame</synopsis>
+ <description>
+ Pop the current frame of <code>thread</code>'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 <vmspeclink/> terminology):
+ <ul>
+ <li>the current frame is discarded as the previous frame becomes the current one</li>
+ <li>the operand stack is restored--the argument values are added back
+ and if the invoke was not <code>invokestatic</code>,
+ <code>objectref</code> is added back as well</li>
+ <li>the Java virtual machine PC is restored to the opcode
+ of the invoke instruction</li>
+ </ul>
+ 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.
+ <p/>
+ Between calling <code>PopFrame</code> and resuming the
+ thread the state of the stack is undefined.
+ To pop frames beyond the first,
+ these three steps must be repeated:
+ <ul>
+ <li>suspend the thread via an event (step, breakpoint, ...)</li>
+ <li>call <code>PopFrame</code></li>
+ <li>resume the thread</li>
+ </ul>
+ <p/>
+ A lock acquired by calling the called method
+ (if it is a <code>synchronized</code> method)
+ and locks acquired by entering <code>synchronized</code>
+ blocks within the called method are released.
+ Note: this does not apply to native locks or
+ <code>java.util.concurrent.locks</code> locks.
+ <p/>
+ Finally blocks are not executed.
+ <p/>
+ Changes to global state are not addressed and thus remain changed.
+ <p/>
+ The specified thread must be suspended (which implies it cannot be the current thread).
+ <p/>
+ Both the called method and calling method must be non-native Java programming
+ language methods.
+ <p/>
+ No <jvmti/> events are generated by this function.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_pop_frame"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread/>
+ <description>
+ The thread whose current frame is to be popped.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Called or calling method is a native method.
+ The implementation is unable to pop this frame.
+ </error>
+ <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
+ Thread was not suspended.
+ </error>
+ <error id="JVMTI_ERROR_NO_MORE_FRAMES">
+ There are less than two stack frames on the call stack.
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetFrameLocation" num="19">
+ <synopsis>Get Frame Location</synopsis>
+ <description>
+ <p/>
+ For a Java programming language frame, return the location of the instruction
+ currently executing.
+ </description>
+ <origin>jvmdiClone</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" frame="frame"/>
+ <description>
+ The thread of the frame to query.
+ </description>
+ </param>
+ <param id="depth">
+ <jframeID thread="thread"/>
+ <description>
+ The depth of the frame to query.
+ </description>
+ </param>
+ <param id="method_ptr">
+ <outptr><jmethodID/></outptr>
+ <description>
+ On return, points to the method for the current location.
+ </description>
+ </param>
+ <param id="location_ptr">
+ <outptr><jlocation/></outptr>
+ <description>
+ On return, points to the index of the currently
+ executing instruction.
+ Is set to <code>-1</code> if the frame is executing
+ a native method.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="NotifyFramePop" num="20">
+ <synopsis>Notify Frame Pop</synopsis>
+ <description>
+ When the frame that is currently at <paramlink id="depth"></paramlink>
+ is popped from the stack, generate a
+ <eventlink id="FramePop"></eventlink> event. See the
+ <eventlink id="FramePop"></eventlink> event for details.
+ Only frames corresponding to non-native Java programming language
+ methods can receive notification.
+ <p/>
+ The specified thread must either be the current thread
+ or the thread must be suspended.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_frame_pop_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" frame="depth"/>
+ <description>
+ The thread of the frame for which the frame pop event will be generated.
+ </description>
+ </param>
+ <param id="depth">
+ <jframeID thread="thread"/>
+ <description>
+ The depth of the frame for which the frame pop event will be generated.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ The frame at <code>depth</code> is executing a
+ native method.
+ </error>
+ <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
+ Thread was not suspended and was not the current thread.
+ </error>
+ </errors>
+ </function>
+
+ </category>
+
+ <category id="ForceEarlyReturn" label="Force Early Return">
+ <intro>
+ 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 <i>called method</i>.
+ The called method is the current method
+ (as defined by the
+ <vmspeclink id="Overview.doc.html#17257"
+ name="Frames section"/>)
+ for the specified thread at
+ the time the function is called.
+ <p/>
+ 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.
+ <p/>
+ No further instructions are executed in the called method.
+ Specifically, finally blocks are not executed.
+ Note: this can cause inconsistent states in the application.
+ <p/>
+ A lock acquired by calling the called method
+ (if it is a <code>synchronized</code> method)
+ and locks acquired by entering <code>synchronized</code>
+ blocks within the called method are released.
+ Note: this does not apply to native locks or
+ <code>java.util.concurrent.locks</code> locks.
+ <p/>
+ Events, such as <eventlink id="MethodExit"></eventlink>,
+ are generated as they would be in a normal return.
+ <p/>
+ 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.
+ </intro>
+
+ <function id="ForceEarlyReturnObject" num="81" since="1.1">
+ <synopsis>Force Early Return - Object</synopsis>
+ <description>
+ This function can be used to return from a method whose
+ result type is <code>Object</code>
+ or a subclass of <code>Object</code>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_force_early_return"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ The thread whose current frame is to return early.
+ </description>
+ </param>
+ <param id="value">
+ <jobject/>
+ <description>
+ The return value for the called frame.
+ An object or <code>NULL</code>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Attempted to return early from a frame
+ corresponding to a native method.
+ Or the implementation is unable to provide
+ this functionality on this frame.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The result type of the called method is not
+ <code>Object</code> or a subclass of <code>Object</code>.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The supplied <paramlink id="value"/> is not compatible with the
+ result type of the called method.
+ </error>
+ <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
+ Thread was not the current thread and was not suspended.
+ </error>
+ <error id="JVMTI_ERROR_NO_MORE_FRAMES">
+ There are no more frames on the call stack.
+ </error>
+ </errors>
+ </function>
+
+ <function id="ForceEarlyReturnInt" num="82" since="1.1">
+ <synopsis>Force Early Return - Int</synopsis>
+ <description>
+ This function can be used to return from a method whose
+ result type is <code>int</code>, <code>short</code>,
+ <code>char</code>, <code>byte</code>, or
+ <code>boolean</code>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_force_early_return"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ The thread whose current frame is to return early.
+ </description>
+ </param>
+ <param id="value">
+ <jint/>
+ <description>
+ The return value for the called frame.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Attempted to return early from a frame
+ corresponding to a native method.
+ Or the implementation is unable to provide
+ this functionality on this frame.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The result type of the called method is not
+ <code>int</code>, <code>short</code>,
+ <code>char</code>, <code>byte</code>, or
+ <code>boolean</code>.
+ </error>
+ <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
+ Thread was not the current thread and was not suspended.
+ </error>
+ <error id="JVMTI_ERROR_NO_MORE_FRAMES">
+ There are no frames on the call stack.
+ </error>
+ </errors>
+ </function>
+
+ <function id="ForceEarlyReturnLong" num="83" since="1.1">
+ <synopsis>Force Early Return - Long</synopsis>
+ <description>
+ This function can be used to return from a method whose
+ result type is <code>long</code>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_force_early_return"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ The thread whose current frame is to return early.
+ </description>
+ </param>
+ <param id="value">
+ <jlong/>
+ <description>
+ The return value for the called frame.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Attempted to return early from a frame
+ corresponding to a native method.
+ Or the implementation is unable to provide
+ this functionality on this frame.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The result type of the called method is not <code>long</code>.
+ </error>
+ <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
+ Thread was not the current thread and was not suspended.
+ </error>
+ <error id="JVMTI_ERROR_NO_MORE_FRAMES">
+ There are no frames on the call stack.
+ </error>
+ </errors>
+ </function>
+
+ <function id="ForceEarlyReturnFloat" num="84" since="1.1">
+ <synopsis>Force Early Return - Float</synopsis>
+ <description>
+ This function can be used to return from a method whose
+ result type is <code>float</code>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_force_early_return"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ The thread whose current frame is to return early.
+ </description>
+ </param>
+ <param id="value">
+ <jfloat/>
+ <description>
+ The return value for the called frame.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Attempted to return early from a frame
+ corresponding to a native method.
+ Or the implementation is unable to provide
+ this functionality on this frame.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The result type of the called method is not <code>float</code>.
+ </error>
+ <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
+ Thread was not the current thread and was not suspended.
+ </error>
+ <error id="JVMTI_ERROR_NO_MORE_FRAMES">
+ There are no frames on the call stack.
+ </error>
+ </errors>
+ </function>
+
+ <function id="ForceEarlyReturnDouble" num="85" since="1.1">
+ <synopsis>Force Early Return - Double</synopsis>
+ <description>
+ This function can be used to return from a method whose
+ result type is <code>double</code>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_force_early_return"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ The thread whose current frame is to return early.
+ </description>
+ </param>
+ <param id="value">
+ <jdouble/>
+ <description>
+ The return value for the called frame.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Attempted to return early from a frame corresponding to a native method.
+ Or the implementation is unable to provide this functionality on this frame.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The result type of the called method is not <code>double</code>.
+ </error>
+ <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
+ Thread was not the current thread and was not suspended.
+ </error>
+ <error id="JVMTI_ERROR_NO_MORE_FRAMES">
+ There are no frames on the call stack.
+ </error>
+ </errors>
+ </function>
+
+ <function id="ForceEarlyReturnVoid" num="86" since="1.1">
+ <synopsis>Force Early Return - Void</synopsis>
+ <description>
+ This function can be used to return from a method with no result type.
+ That is, the called method must be declared <code>void</code>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_force_early_return"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ The thread whose current frame is to return early.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Attempted to return early from a frame
+ corresponding to a native method.
+ Or the implementation is unable to provide
+ this functionality on this frame.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The called method has a result type.
+ </error>
+ <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
+ Thread was not the current thread and was not suspended.
+ </error>
+ <error id="JVMTI_ERROR_NO_MORE_FRAMES">
+ There are no frames on the call stack.
+ </error>
+ </errors>
+ </function>
+
+ </category>
+
+ <category id="Heap" label="Heap">
+ <intro>
+ These functions are used to analyze the heap.
+ Functionality includes the ability to view the objects in the
+ heap and to tag these objects.
+ </intro>
+
+ <intro id="objectTags" label="Object Tags">
+ A <i>tag</i> is a value associated with an object.
+ Tags are explicitly set by the agent using the
+ <functionlink id="SetTag"></functionlink> function or by
+ callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>.
+ <p/>
+ Tags are local to the environment; that is, the tags of one
+ environment are not visible in another.
+ <p/>
+ Tags are <code>jlong</code> 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.
+ </intro>
+
+ <intro id="heapCallbacks" label="Heap Callback Functions">
+ Heap functions which iterate through the heap and recursively
+ follow object references use agent supplied callback functions
+ to deliver the information.
+ <p/>
+ These heap callback functions must adhere to the following restrictions --
+ These callbacks must not use JNI functions.
+ These callbacks must not use <jvmti/> functions except
+ <i>callback safe</i> functions which
+ specifically allow such use (see the raw monitor, memory management,
+ and environment local storage functions).
+ <p/>
+ 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.
+ <p/>
+ 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 <code>jint</code> is zero), objects
+ will not be filtered out.
+
+ <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits">
+ <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4">
+ Filter out tagged objects. Objects which are tagged are not included.
+ </constant>
+ <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8">
+ Filter out untagged objects. Objects which are not tagged are not included.
+ </constant>
+ <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10">
+ Filter out objects with tagged classes. Objects whose class is tagged are not included.
+ </constant>
+ <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20">
+ Filter out objects with untagged classes. Objects whose class is not tagged are not included.
+ </constant>
+ </constants>
+
+ <p/>
+ The Heap Visit Control Flags are returned by the heap callbacks
+ and can be used to abort the iteration. For the
+ <functionlink id="jvmtiHeapReferenceCallback">Heap
+ Reference Callback</functionlink>, it can also be used
+ to prune the graph of traversed references
+ (<code>JVMTI_VISIT_OBJECTS</code> is not set).
+
+ <constants id="jvmtiHeapVisitControl"
+ label="Heap Visit Control Flags"
+ kind="bits"
+ since="1.1">
+ <constant id="JVMTI_VISIT_OBJECTS" num="0x100">
+ If we are visiting an object and if this callback
+ was initiated by <functionlink id="FollowReferences"/>,
+ traverse the references of this object.
+ Otherwise ignored.
+ </constant>
+ <constant id="JVMTI_VISIT_ABORT" num="0x8000">
+ Abort the iteration. Ignore all other bits.
+ </constant>
+ </constants>
+
+ <p/>
+ The Heap Reference Enumeration is provided by the
+ <functionlink id="jvmtiHeapReferenceCallback">Heap
+ Reference Callback</functionlink> and
+ <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field
+ Callback</functionlink> to
+ describe the kind of reference
+ being reported.
+
+ <constants id="jvmtiHeapReferenceKind"
+ label="Heap Reference Enumeration"
+ kind="enum"
+ since="1.1">
+ <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1">
+ Reference from an object to its class.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2">
+ Reference from an object to the value of one of its instance fields.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3">
+ Reference from an array to one of its elements.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4">
+ Reference from a class to its class loader.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5">
+ Reference from a class to its signers array.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6">
+ Reference from a class to its protection domain.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="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
+ <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8">
+ Reference from a class to the value of one of its static fields.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9">
+ Reference from a class to a resolved entry in the constant pool.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10">
+ Reference from a class to its superclass.
+ A callback is bot sent if the superclass is <code>java.lang.Object</code>.
+ Note: loaded classes define superclasses via a constant pool
+ reference, so the referenced superclass may also be reported with
+ a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21">
+ Heap root reference: JNI global reference.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22">
+ Heap root reference: System class.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23">
+ Heap root reference: monitor.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24">
+ Heap root reference: local variable on the stack.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25">
+ Heap root reference: JNI local reference.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26">
+ Heap root reference: Thread.
+ </constant>
+ <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27">
+ Heap root reference: other heap root reference.
+ </constant>
+ </constants>
+
+ <p/>
+ Definitions for the single character type descriptors of
+ primitive types.
+
+ <constants id="jvmtiPrimitiveType"
+ label="Primitive Type Enumeration"
+ kind="enum"
+ since="1.1">
+ <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90">
+ 'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code>
+ </constant>
+ <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66">
+ 'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code>
+ </constant>
+ <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67">
+ 'C' - Java programming language <code>char</code> - JNI <code>jchar</code>
+ </constant>
+ <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83">
+ 'S' - Java programming language <code>short</code> - JNI <code>jshort</code>
+ </constant>
+ <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73">
+ 'I' - Java programming language <code>int</code> - JNI <code>jint</code>
+ </constant>
+ <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74">
+ 'J' - Java programming language <code>long</code> - JNI <code>jlong</code>
+ </constant>
+ <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70">
+ 'F' - Java programming language <code>float</code> - JNI <code>jfloat</code>
+ </constant>
+ <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68">
+ 'D' - Java programming language <code>double</code> - JNI <code>jdouble</code>
+ </constant>
+ </constants>
+ </intro>
+
+ <typedef id="jvmtiHeapReferenceInfoField"
+ label="Reference information structure for Field references"
+ since="1.1">
+ <description>
+ Reference information returned for
+ <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and
+ <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
+ </description>
+ <field id="index">
+ <jint/>
+ <description>
+ For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the
+ referrer object is not a class or an inteface.
+ In this case, <code>index</code> is the index of the field
+ in the class of the referrer object.
+ This class is referred to below as <i>C</i>.
+ <p/>
+ For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
+ the referrer object is a class (referred to below as <i>C</i>)
+ or an interface (referred to below as <i>I</i>).
+ In this case, <code>index</code> is the index of the field in
+ that class or interface.
+ <p/>
+ If the referrer object is not an interface, then the field
+ indices are determined as follows:
+ <ul>
+ <li>make a list of all the fields in <i>C</i> and its
+ superclasses, starting with all the fields in
+ <code>java.lang.Object</code> and ending with all the
+ fields in <i>C</i>.</li>
+ <li>Within this list, put
+ the fields for a given class in the order returned by
+ <functionlink id="GetClassFields"/>.</li>
+ <li>Assign the fields in this list indices
+ <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i>
+ is the count of the fields in all the interfaces
+ implemented by <i>C</i>.
+ Note that <i>C</i> implements all interfaces
+ directly implemented by its superclasses; as well
+ as all superinterfaces of these interfaces.</li>
+ </ul>
+ If the referrer object is an interface, then the field
+ indices are determined as follows:
+ <ul>
+ <li>make a list of the fields directly declared in
+ <i>I</i>.</li>
+ <li>Within this list, put
+ the fields in the order returned by
+ <functionlink id="GetClassFields"/>.</li>
+ <li>Assign the fields in this list indices
+ <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i>
+ is the count of the fields in all the superinterfaces
+ of <i>I</i>.</li>
+ </ul>
+ All fields are included in this computation, regardless of
+ field modifier (static, public, private, etc).
+ <p/>
+ For example, given the following classes and interfaces:
+ <example>
+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;
+}
+ </example>
+ Assume that <functionlink id="GetClassFields"/> called on
+ <code>C1</code> returns the fields of <code>C1</code> in the
+ order: a, b; and that the fields of <code>C2</code> are
+ returned in the order: q, r.
+ An instance of class <code>C1</code> will have the
+ following field indices:
+ <dl><dd><table>
+ <tr>
+ <td>
+ a
+ </td>
+ <td>
+ 2
+ </td>
+ <td align="left">
+ The count of the fields in the interfaces
+ implemented by <code>C1</code> is two (<i>n</i>=2):
+ <code>p</code> of <code>I0</code>
+ and <code>x</code> of <code>I1</code>.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ b
+ </td>
+ <td>
+ 3
+ </td>
+ <td align="left">
+ the subsequent index.
+ </td>
+ </tr>
+ </table></dd></dl>
+ The class <code>C1</code> will have the same field indices.
+ <p/>
+ An instance of class <code>C2</code> will have the
+ following field indices:
+ <dl><dd><table>
+ <tr>
+ <td>
+ a
+ </td>
+ <td>
+ 3
+ </td>
+ <td align="left">
+ The count of the fields in the interfaces
+ implemented by <code>C2</code> is three (<i>n</i>=3):
+ <code>p</code> of <code>I0</code>,
+ <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code>
+ (an interface of <code>C2</code>). Note that the field <code>p</code>
+ of <code>I0</code> is only included once.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ b
+ </td>
+ <td>
+ 4
+ </td>
+ <td align="left">
+ the subsequent index to "a".
+ </td>
+ </tr>
+ <tr>
+ <td>
+ q
+ </td>
+ <td>
+ 5
+ </td>
+ <td align="left">
+ the subsequent index to "b".
+ </td>
+ </tr>
+ <tr>
+ <td>
+ r
+ </td>
+ <td>
+ 6
+ </td>
+ <td align="left">
+ the subsequent index to "q".
+ </td>
+ </tr>
+ </table></dd></dl>
+ The class <code>C2</code> 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.
+ <p/>
+ The interface <code>I1</code> will have the
+ following field indices:
+ <dl><dd><table>
+ <tr>
+ <td>
+ x
+ </td>
+ <td>
+ 1
+ </td>
+ <td align="left">
+ The count of the fields in the superinterfaces
+ of <code>I1</code> is one (<i>n</i>=1):
+ <code>p</code> of <code>I0</code>.
+ </td>
+ </tr>
+ </table></dd></dl>
+ </description>
+ </field>
+ </typedef>
+
+ <typedef id="jvmtiHeapReferenceInfoArray"
+ label="Reference information structure for Array references"
+ since="1.1">
+ <description>
+ Reference information returned for
+ <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
+ </description>
+ <field id="index">
+ <jint/>
+ <description>
+ The array index.
+ </description>
+ </field>
+ </typedef>
+
+ <typedef id="jvmtiHeapReferenceInfoConstantPool"
+ label="Reference information structure for Constant Pool references"
+ since="1.1">
+ <description>
+ Reference information returned for
+ <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
+ </description>
+ <field id="index">
+ <jint/>
+ <description>
+ The index into the constant pool of the class. See the
+ <vmspeclink id="ClassFile.doc.html#20080"
+ name="Constant Pool section"/>
+ description.
+ </description>
+ </field>
+ </typedef>
+
+ <typedef id="jvmtiHeapReferenceInfoStackLocal"
+ label="Reference information structure for Local Variable references"
+ since="1.1">
+ <description>
+ Reference information returned for
+ <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
+ </description>
+ <field id="thread_tag">
+ <jlong/>
+ <description>
+ The tag of the thread corresponding to this stack, zero if not tagged.
+ </description>
+ </field>
+ <field id="thread_id">
+ <jlong/>
+ <description>
+ The unique thread ID of the thread corresponding to this stack.
+ </description>
+ </field>
+ <field id="depth">
+ <jint/>
+ <description>
+ The depth of the frame.
+ </description>
+ </field>
+ <field id="method">
+ <jmethodID/>
+ <description>
+ The method executing in this frame.
+ </description>
+ </field>
+ <field id="location">
+ <jlocation/>
+ <description>
+ The currently executing location in this frame.
+ </description>
+ </field>
+ <field id="slot">
+ <jint/>
+ <description>
+ The slot number of the local variable.
+ </description>
+ </field>
+ </typedef>
+
+ <typedef id="jvmtiHeapReferenceInfoJniLocal"
+ label="Reference information structure for JNI local references"
+ since="1.1">
+ <description>
+ Reference information returned for
+ <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
+ </description>
+ <field id="thread_tag">
+ <jlong/>
+ <description>
+ The tag of the thread corresponding to this stack, zero if not tagged.
+ </description>
+ </field>
+ <field id="thread_id">
+ <jlong/>
+ <description>
+ The unique thread ID of the thread corresponding to this stack.
+ </description>
+ </field>
+ <field id="depth">
+ <jint/>
+ <description>
+ The depth of the frame.
+ </description>
+ </field>
+ <field id="method">
+ <jmethodID/>
+ <description>
+ The method executing in this frame.
+ </description>
+ </field>
+ </typedef>
+
+ <typedef id="jvmtiHeapReferenceInfoReserved"
+ label="Reference information structure for Other references"
+ since="1.1">
+ <description>
+ Reference information returned for other references.
+ </description>
+ <field id="reserved1">
+ <jlong/>
+ <description>
+ reserved for future use.
+ </description>
+ </field>
+ <field id="reserved2">
+ <jlong/>
+ <description>
+ reserved for future use.
+ </description>
+ </field>
+ <field id="reserved3">
+ <jlong/>
+ <description>
+ reserved for future use.
+ </description>
+ </field>
+ <field id="reserved4">
+ <jlong/>
+ <description>
+ reserved for future use.
+ </description>
+ </field>
+ <field id="reserved5">
+ <jlong/>
+ <description>
+ reserved for future use.
+ </description>
+ </field>
+ <field id="reserved6">
+ <jlong/>
+ <description>
+ reserved for future use.
+ </description>
+ </field>
+ <field id="reserved7">
+ <jlong/>
+ <description>
+ reserved for future use.
+ </description>
+ </field>
+ <field id="reserved8">
+ <jlong/>
+ <description>
+ reserved for future use.
+ </description>
+ </field>
+ </typedef>
+
+ <uniontypedef id="jvmtiHeapReferenceInfo"
+ label="Reference information structure"
+ since="1.1">
+ <description>
+ The information returned about referrers.
+ Represented as a union of the various kinds of reference information.
+ </description>
+ <field id="field">
+ <struct>jvmtiHeapReferenceInfoField</struct>
+ <description>
+ The referrer information for
+ <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>
+ and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
+ </description>
+ </field>
+ <field id="array">
+ <struct>jvmtiHeapReferenceInfoArray</struct>
+ <description>
+ The referrer information for
+ For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
+ </description>
+ </field>
+ <field id="constant_pool">
+ <struct>jvmtiHeapReferenceInfoConstantPool</struct>
+ <description>
+ The referrer information for
+ For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
+ </description>
+ </field>
+ <field id="stack_local">
+ <struct>jvmtiHeapReferenceInfoStackLocal</struct>
+ <description>
+ The referrer information for
+ For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
+ </description>
+ </field>
+ <field id="jni_local">
+ <struct>jvmtiHeapReferenceInfoJniLocal</struct>
+ <description>
+ The referrer information for
+ For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
+ </description>
+ </field>
+ <field id="other">
+ <struct>jvmtiHeapReferenceInfoReserved</struct>
+ <description>
+ reserved for future use.
+ </description>
+ </field>
+ </uniontypedef>
+
+ <typedef id="jvmtiHeapCallbacks"
+ label="Heap callback function structure"
+ since="1.1">
+ <field id="heap_iteration_callback">
+ <ptrtype>
+ <struct>jvmtiHeapIterationCallback</struct>
+ </ptrtype>
+ <description>
+ The callback to be called to describe an
+ object in the heap. Used by the
+ <functionlink id="IterateThroughHeap"/> function, ignored by the
+ <functionlink id="FollowReferences"/> function.
+ </description>
+ </field>
+ <field id="heap_reference_callback">
+ <ptrtype>
+ <struct>jvmtiHeapReferenceCallback</struct>
+ </ptrtype>
+ <description>
+ The callback to be called to describe an
+ object reference. Used by the
+ <functionlink id="FollowReferences"/> function, ignored by the
+ <functionlink id="IterateThroughHeap"/> function.
+ </description>
+ </field>
+ <field id="primitive_field_callback">
+ <ptrtype>
+ <struct>jvmtiPrimitiveFieldCallback</struct>
+ </ptrtype>
+ <description>
+ The callback to be called to describe a
+ primitive field.
+ </description>
+ </field>
+ <field id="array_primitive_value_callback">
+ <ptrtype>
+ <struct>jvmtiArrayPrimitiveValueCallback</struct>
+ </ptrtype>
+ <description>
+ The callback to be called to describe an
+ array of primitive values.
+ </description>
+ </field>
+ <field id="string_primitive_value_callback">
+ <ptrtype>
+ <struct>jvmtiStringPrimitiveValueCallback</struct>
+ </ptrtype>
+ <description>
+ The callback to be called to describe a String value.
+ </description>
+ </field>
+ <field id="reserved5">
+ <ptrtype>
+ <struct>jvmtiReservedCallback</struct>
+ </ptrtype>
+ <description>
+ Reserved for future use..
+ </description>
+ </field>
+ <field id="reserved6">
+ <ptrtype>
+ <struct>jvmtiReservedCallback</struct>
+ </ptrtype>
+ <description>
+ Reserved for future use..
+ </description>
+ </field>
+ <field id="reserved7">
+ <ptrtype>
+ <struct>jvmtiReservedCallback</struct>
+ </ptrtype>
+ <description>
+ Reserved for future use..
+ </description>
+ </field>
+ <field id="reserved8">
+ <ptrtype>
+ <struct>jvmtiReservedCallback</struct>
+ </ptrtype>
+ <description>
+ Reserved for future use..
+ </description>
+ </field>
+ <field id="reserved9">
+ <ptrtype>
+ <struct>jvmtiReservedCallback</struct>
+ </ptrtype>
+ <description>
+ Reserved for future use..
+ </description>
+ </field>
+ <field id="reserved10">
+ <ptrtype>
+ <struct>jvmtiReservedCallback</struct>
+ </ptrtype>
+ <description>
+ Reserved for future use..
+ </description>
+ </field>
+ <field id="reserved11">
+ <ptrtype>
+ <struct>jvmtiReservedCallback</struct>
+ </ptrtype>
+ <description>
+ Reserved for future use..
+ </description>
+ </field>
+ <field id="reserved12">
+ <ptrtype>
+ <struct>jvmtiReservedCallback</struct>
+ </ptrtype>
+ <description>
+ Reserved for future use..
+ </description>
+ </field>
+ <field id="reserved13">
+ <ptrtype>
+ <struct>jvmtiReservedCallback</struct>
+ </ptrtype>
+ <description>
+ Reserved for future use..
+ </description>
+ </field>
+ <field id="reserved14">
+ <ptrtype>
+ <struct>jvmtiReservedCallback</struct>
+ </ptrtype>
+ <description>
+ Reserved for future use..
+ </description>
+ </field>
+ <field id="reserved15">
+ <ptrtype>
+ <struct>jvmtiReservedCallback</struct>
+ </ptrtype>
+ <description>
+ Reserved for future use..
+ </description>
+ </field>
+ </typedef>
+
+
+ <intro>
+ <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.
+ </rationale>
+
+ <issue>
+ Still under investigation as to if java.lang.ref references
+ are reported as a different type of reference.
+ </issue>
+
+ <issue>
+ Should or can an indication of the cost or relative cost of
+ these operations be included?
+ </issue>
+
+ </intro>
+
+ <callback id="jvmtiHeapIterationCallback" since="1.1">
+ <jint/>
+ <synopsis>Heap Iteration Callback</synopsis>
+ <description>
+ Agent supplied callback function.
+ Describes (but does not pass in) an object in the heap.
+ <p/>
+ This function should return a bit vector of the desired
+ <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
+ This will determine if the entire iteration should be aborted
+ (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
+ <p/>
+ See the <internallink id="heapCallbacks">heap callback
+ function restrictions</internallink>.
+ </description>
+ <parameters>
+ <param id="class_tag">
+ <jlong/>
+ <description>
+ The tag of the class of object (zero if the class is not tagged).
+ If the object represents a runtime class,
+ the <code>class_tag</code> is the tag
+ associated with <code>java.lang.Class</code>
+ (zero if <code>java.lang.Class</code> is not tagged).
+ </description>
+ </param>
+ <param id="size">
+ <jlong/>
+ <description>
+ Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
+ </description>
+ </param>
+ <param id="tag_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ The object tag value, or zero if the object is not tagged.
+ To set the tag value to be associated with the object
+ the agent sets the <code>jlong</code> pointed to by the parameter.
+ </description>
+ </param>
+ <param id="length">
+ <jint/>
+ <description>
+ If this object is an array, the length of the array. Otherwise negative one (-1).
+ </description>
+ </param>
+ <param id="user_data">
+ <outptr><void/></outptr>
+ <description>
+ The user supplied data that was passed into the iteration function.
+ </description>
+ </param>
+ </parameters>
+ </callback>
+
+ <callback id="jvmtiHeapReferenceCallback" since="1.1">
+ <jint/>
+ <synopsis>Heap Reference Callback</synopsis>
+ <description>
+ Agent supplied callback function.
+ Describes a reference from an object or the VM (the referrer) to another object
+ (the referree) or a heap root to a referree.
+ <p/>
+ This function should return a bit vector of the desired
+ <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
+ This will determine if the objects referenced by the referree
+ should be visited or if the entire iteration should be aborted.
+ <p/>
+ See the <internallink id="heapCallbacks">heap callback
+ function restrictions</internallink>.
+ </description>
+ <parameters>
+ <param id="reference_kind">
+ <enum>jvmtiHeapReferenceKind</enum>
+ <description>
+ The kind of reference.
+ </description>
+ </param>
+ <param id="reference_info">
+ <inptr>
+ <struct>jvmtiHeapReferenceInfo</struct>
+ </inptr>
+ <description>
+ Details about the reference.
+ Set when the <paramlink id="reference_kind"/> is
+ <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>,
+ <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
+ <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>,
+ <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>,
+ <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>,
+ or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>.
+ Otherwise <code>NULL</code>.
+ </description>
+ </param>
+ <param id="class_tag">
+ <jlong/>
+ <description>
+ The tag of the class of referree object (zero if the class is not tagged).
+ If the referree object represents a runtime class,
+ the <code>class_tag</code> is the tag
+ associated with <code>java.lang.Class</code>
+ (zero if <code>java.lang.Class</code> is not tagged).
+ </description>
+ </param>
+ <param id="referrer_class_tag">
+ <jlong/>
+ <description>
+ The tag of the class of the referrer object (zero if the class is not tagged
+ or the referree is a heap root). If the referrer object represents a runtime
+ class, the <code>referrer_class_tag</code> is the tag associated with
+ the <code>java.lang.Class</code>
+ (zero if <code>java.lang.Class</code> is not tagged).
+ </description>
+ </param>
+ <param id="size">
+ <jlong/>
+ <description>
+ Size of the referree object (in bytes).
+ See <functionlink id="GetObjectSize"/>.
+ </description>
+ </param>
+ <param id="tag_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ Points to the referree object tag value, or zero if the object is not
+ tagged.
+ To set the tag value to be associated with the object
+ the agent sets the <code>jlong</code> pointed to by the parameter.
+ </description>
+ </param>
+ <param id="referrer_tag_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ Points to the tag of the referrer object, or
+ points to the zero if the referrer
+ object is not tagged.
+ <code>NULL</code> if the referrer in not an object (that is,
+ this callback is reporting a heap root).
+ To set the tag value to be associated with the referrer object
+ the agent sets the <code>jlong</code> pointed to by the parameter.
+ If this callback is reporting a reference from an object to itself,
+ <code>referrer_tag_ptr == tag_ptr</code>.
+ </description>
+ </param>
+ <param id="length">
+ <jint/>
+ <description>
+ If this object is an array, the length of the array. Otherwise negative one (-1).
+ </description>
+ </param>
+ <param id="user_data">
+ <outptr><void/></outptr>
+ <description>
+ The user supplied data that was passed into the iteration function.
+ </description>
+ </param>
+ </parameters>
+ </callback>
+
+ <callback id="jvmtiPrimitiveFieldCallback" since="1.1">
+ <jint/>
+ <synopsis>Primitive Field Callback</synopsis>
+ <description>
+ Agent supplied callback function which
+ describes a primitive field of an object (<i>the object</i>).
+ A primitive field is a field whose type is a primitive type.
+ This callback will describe a static field if the object is a class,
+ and otherwise will describe an instance field.
+ <p/>
+ This function should return a bit vector of the desired
+ <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
+ This will determine if the entire iteration should be aborted
+ (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
+ <p/>
+ See the <internallink id="heapCallbacks">heap callback
+ function restrictions</internallink>.
+ </description>
+ <parameters>
+ <param id="kind">
+ <enum>jvmtiHeapReferenceKind</enum>
+ <description>
+ The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or
+ <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>).
+ </description>
+ </param>
+ <param id="info">
+ <inptr>
+ <struct>jvmtiHeapReferenceInfo</struct>
+ </inptr>
+ <description>
+ Which field (the field index).
+ </description>
+ </param>
+ <param id="object_class_tag">
+ <jlong/>
+ <description>
+ The tag of the class of the object (zero if the class is not tagged).
+ If the object represents a runtime class, the
+ <code>object_class_tag</code> is the tag
+ associated with <code>java.lang.Class</code>
+ (zero if <code>java.lang.Class</code> is not tagged).
+ </description>
+ </param>
+ <param id="object_tag_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ Points to the tag of the object, or zero if the object is not
+ tagged.
+ To set the tag value to be associated with the object
+ the agent sets the <code>jlong</code> pointed to by the parameter.
+ </description>
+ </param>
+ <param id="value">
+ <jvalue/>
+ <description>
+ The value of the field.
+ </description>
+ </param>
+ <param id="value_type">
+ <enum>jvmtiPrimitiveType</enum>
+ <description>
+ The type of the field.
+ </description>
+ </param>
+ <param id="user_data">
+ <outptr><void/></outptr>
+ <description>
+ The user supplied data that was passed into the iteration function.
+ </description>
+ </param>
+ </parameters>
+ </callback>
+
+ <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1">
+ <jint/>
+ <synopsis>Array Primitive Value Callback</synopsis>
+ <description>
+ Agent supplied callback function.
+ Describes the values in an array of a primitive type.
+ <p/>
+ This function should return a bit vector of the desired
+ <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
+ This will determine if the entire iteration should be aborted
+ (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
+ <p/>
+ See the <internallink id="heapCallbacks">heap callback
+ function restrictions</internallink>.
+ </description>
+ <parameters>
+ <param id="class_tag">
+ <jlong/>
+ <description>
+ The tag of the class of the array object (zero if the class is not tagged).
+ </description>
+ </param>
+ <param id="size">
+ <jlong/>
+ <description>
+ Size of the array (in bytes).
+ See <functionlink id="GetObjectSize"/>.
+ </description>
+ </param>
+ <param id="tag_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ Points to the tag of the array object, or zero if the object is not
+ tagged.
+ To set the tag value to be associated with the object
+ the agent sets the <code>jlong</code> pointed to by the parameter.
+ </description>
+ </param>
+ <param id="element_count">
+ <jint/>
+ <description>
+ The length of the primitive array.
+ </description>
+ </param>
+ <param id="element_type">
+ <enum>jvmtiPrimitiveType</enum>
+ <description>
+ The type of the elements of the array.
+ </description>
+ </param>
+ <param id="elements">
+ <vmbuf><void/></vmbuf>
+ <description>
+ The elements of the array in a packed array of <code>element_count</code>
+ items of <code>element_type</code> size each.
+ </description>
+ </param>
+ <param id="user_data">
+ <outptr><void/></outptr>
+ <description>
+ The user supplied data that was passed into the iteration function.
+ </description>
+ </param>
+ </parameters>
+ </callback>
+
+ <callback id="jvmtiStringPrimitiveValueCallback" since="1.1">
+ <jint/>
+ <synopsis>String Primitive Value Callback</synopsis>
+ <description>
+ Agent supplied callback function.
+ Describes the value of a java.lang.String.
+ <p/>
+ This function should return a bit vector of the desired
+ <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
+ This will determine if the entire iteration should be aborted
+ (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
+ <p/>
+ See the <internallink id="heapCallbacks">heap callback
+ function restrictions</internallink>.
+ </description>
+ <parameters>
+ <param id="class_tag">
+ <jlong/>
+ <description>
+ The tag of the class of the String class (zero if the class is not tagged).
+ <issue>Is this needed?</issue>
+ </description>
+ </param>
+ <param id="size">
+ <jlong/>
+ <description>
+ Size of the string (in bytes).
+ See <functionlink id="GetObjectSize"/>.
+ </description>
+ </param>
+ <param id="tag_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ Points to the tag of the String object, or zero if the object is not
+ tagged.
+ To set the tag value to be associated with the object
+ the agent sets the <code>jlong</code> pointed to by the parameter.
+ </description>
+ </param>
+ <param id="value">
+ <vmbuf><jchar/></vmbuf>
+ <description>
+ The value of the String, encoded as a Unicode string.
+ </description>
+ </param>
+ <param id="value_length">
+ <jint/>
+ <description>
+ The length of the string.
+ The length is equal to the number of 16-bit Unicode
+ characters in the string.
+ </description>
+ </param>
+ <param id="user_data">
+ <outptr><void/></outptr>
+ <description>
+ The user supplied data that was passed into the iteration function.
+ </description>
+ </param>
+ </parameters>
+ </callback>
+
+
+ <callback id="jvmtiReservedCallback" since="1.1">
+ <jint/>
+ <synopsis>reserved for future use Callback</synopsis>
+ <description>
+ Placeholder -- reserved for future use.
+ </description>
+ <parameters>
+ </parameters>
+ </callback>
+
+ <function id="FollowReferences" num="115" since="1.1">
+ <synopsis>Follow References</synopsis>
+ <description>
+ This function initiates a traversal over the objects that are
+ directly and indirectly reachable from the specified object or,
+ if <code>initial_object</code> 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.
+ <p/>
+ This function operates by traversing the reference graph.
+ Let <i>A</i>, <i>B</i>, ... represent objects.
+ When a reference from <i>A</i> to <i>B</i> is traversed,
+ when a reference from a heap root to <i>B</i> is traversed,
+ or when <i>B</i> is specified as the <paramlink id="initial_object"/>,
+ then <i>B</i> is said to be <i>visited</i>.
+ A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i>
+ 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 <functionlink id="jvmtiHeapReferenceCallback"/>.
+ In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known
+ as the <i>referrer</i> and <i>B</i> as the <i>referree</i>.
+ 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
+ <datalink
+ id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink>
+ and
+ <datalink
+ id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink>
+ parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback.
+ <p/>
+ 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:
+ <ul>
+ <li>Instance objects report references to each non-primitive instance fields
+ (including inherited fields).</li>
+ <li>Instance objects report a reference to the object type (class).</li>
+ <li>Classes report a reference to the superclass and directly
+ implemented/extended interfaces.</li>
+ <li>Classes report a reference to the class loader, protection domain,
+ signers, and resolved entries in the constant pool.</li>
+ <li>Classes report a reference to each directly declared non-primitive
+ static field.</li>
+ <li>Arrays report a reference to the array type (class) and each
+ array element.</li>
+ <li>Primitive arrays report a reference to the array type.</li>
+ </ul>
+ <p/>
+ 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
+ <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
+ <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
+ A primitive field
+ is reported after the object with that field is visited;
+ it is reported by invoking the agent supplied callback function
+ <functionlink id="jvmtiPrimitiveFieldCallback"/>.
+ <p/>
+ Whether a callback is provided or is <code>NULL</code> 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
+ <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>
+ returned by <functionlink id="jvmtiHeapReferenceCallback"/>
+ do determine if the objects referenced by the
+ current object as visited.
+ The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
+ and <paramlink id="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
+ <paramlink id="array_primitive_value_callback"/> and <code>klass</code>
+ is set to the array of bytes class, then only arrays of byte will be
+ reported.
+ The table below summarizes this:
+ <p/>
+ <table>
+ <tr>
+ <th/>
+ <th>
+ Controls objects visited
+ </th>
+ <th>
+ Controls objects reported
+ </th>
+ <th>
+ Controls primitives reported
+ </th>
+ </tr>
+ <tr>
+ <th align="left">
+ the
+ <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
+ returned by <functionlink id="jvmtiHeapReferenceCallback"/>
+ </th>
+ <td>
+ <b>Yes</b>
+ </td>
+ <td>
+ <b>Yes</b>, since visits are controlled
+ </td>
+ <td>
+ <b>Yes</b>, since visits are controlled
+ </td>
+ </tr>
+ <tr>
+ <th align="left">
+ <fieldlink id="object_reference_callback" struct="jvmtiHeapCallbacks"/>
+ in <paramlink id="callbacks"/> set
+ </th>
+ <td>
+ No
+ </td>
+ <td>
+ <b>Yes</b>
+ </td>
+ <td>
+ No
+ </td>
+ </tr>
+ <tr>
+ <th align="left">
+ <paramlink id="heap_filter"/>
+ </th>
+ <td>
+ No
+ </td>
+ <td>
+ <b>Yes</b>
+ </td>
+ <td>
+ <b>Yes</b>
+ </td>
+ </tr>
+ <tr>
+ <th align="left">
+ <paramlink id="klass"/>
+ </th>
+ <td>
+ No
+ </td>
+ <td>
+ <b>Yes</b>
+ </td>
+ <td>
+ <b>Yes</b>
+ </td>
+ </tr>
+ </table>
+ <p/>
+ 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.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_tag_objects"></required>
+ </capabilities>
+ <parameters>
+ <param id="heap_filter">
+ <jint/>
+ <description>
+ This bit vector of
+ <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
+ restricts the objects for which the callback function is called.
+ This applies to both the object and primitive callbacks.
+ </description>
+ </param>
+ <param id="klass">
+ <ptrtype>
+ <jclass/>
+ <nullok>callbacks are not limited to instances of a particular
+ class</nullok>
+ </ptrtype>
+ <description>
+ Callbacks are only reported when the object is an instance of
+ this class.
+ Objects which are instances of a subclass of <code>klass</code>
+ are not reported.
+ If <code>klass</code> is an interface, no objects are reported.
+ This applies to both the object and primitive callbacks.
+ </description>
+ </param>
+ <param id="initial_object">
+ <ptrtype>
+ <jobject/>
+ <nullok>references are followed from the heap roots</nullok>
+ </ptrtype>
+ <description>
+ The object to follow
+ </description>
+ </param>
+ <param id="callbacks">
+ <inptr>
+ <struct>jvmtiHeapCallbacks</struct>
+ </inptr>
+ <description>
+ Structure defining the set of callback functions.
+ </description>
+ </param>
+ <param id="user_data">
+ <inbuf>
+ <void/>
+ <nullok><code>NULL</code> is passed as the user supplied data</nullok>
+ </inbuf>
+ <description>
+ User supplied data to be passed to the callback.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_CLASS">
+ <paramlink id="klass"/> is not a valid class.
+ </error>
+ <error id="JVMTI_ERROR_INVALID_OBJECT">
+ <paramlink id="initial_object"/> is not a valid object.
+ </error>
+ </errors>
+ </function>
+
+
+ <function id="IterateThroughHeap" num="116" since="1.1">
+ <synopsis>Iterate Through Heap</synopsis>
+ <description>
+ Initiate an iteration over all objects in the heap.
+ This includes both reachable and
+ unreachable objects. Objects are visited in no particular order.
+ <p/>
+ Heap objects are reported by invoking the agent supplied
+ callback function <functionlink id="jvmtiHeapIterationCallback"/>.
+ References between objects are not reported.
+ If only reachable objects are desired, or if object reference information
+ is needed, use <functionlink id="FollowReferences"/>.
+ <p/>
+ 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
+ <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
+ <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
+ A primitive field
+ is reported after the object with that field is visited;
+ it is reported by invoking the agent supplied
+ callback function
+ <functionlink id="jvmtiPrimitiveFieldCallback"/>.
+ <p/>
+ Unless the iteration is aborted by the
+ <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
+ returned by a callback, all objects in the heap are visited.
+ Whether a callback is provided or is <code>NULL</code> 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 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
+ and <paramlink id="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
+ <paramlink id="array_primitive_value_callback"/> and <code>klass</code>
+ is set to the array of bytes class, then only arrays of byte will be
+ reported. The table below summarizes this (contrast this with
+ <functionlink id="FollowReferences"/>):
+ <p/>
+ <table>
+ <tr>
+ <th/>
+ <th>
+ Controls objects visited
+ </th>
+ <th>
+ Controls objects reported
+ </th>
+ <th>
+ Controls primitives reported
+ </th>
+ </tr>
+ <tr>
+ <th align="left">
+ the
+ <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
+ returned by <functionlink id="jvmtiHeapIterationCallback"/>
+ </th>
+ <td>
+ No<br/>(unless they abort the iteration)
+ </td>
+ <td>
+ No<br/>(unless they abort the iteration)
+ </td>
+ <td>
+ No<br/>(unless they abort the iteration)
+ </td>
+ </tr>
+ <tr>
+ <th align="left">
+ <fieldlink id="object_callback" struct="jvmtiHeapCallbacks"/>
+ in <paramlink id="callbacks"/> set
+ </th>
+ <td>
+ No
+ </td>
+ <td>
+ <b>Yes</b>
+ </td>
+ <td>
+ No
+ </td>
+ </tr>
+ <tr>
+ <th align="left">
+ <paramlink id="heap_filter"/>
+ </th>
+ <td>
+ No
+ </td>
+ <td>
+ <b>Yes</b>
+ </td>
+ <td>
+ <b>Yes</b>
+ </td>
+ </tr>
+ <tr>
+ <th align="left">
+ <paramlink id="klass"/>
+ </th>
+ <td>
+ No
+ </td>
+ <td>
+ <b>Yes</b>
+ </td>
+ <td>
+ <b>Yes</b>
+ </td>
+ </tr>
+ </table>
+ <p/>
+ 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.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_tag_objects"></required>
+ </capabilities>
+ <parameters>
+ <param id="heap_filter">
+ <jint/>
+ <description>
+ This bit vector of
+ <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
+ restricts the objects for which the callback function is called.
+ This applies to both the object and primitive callbacks.
+ </description>
+ </param>
+ <param id="klass">
+ <ptrtype>
+ <jclass/>
+ <nullok>callbacks are not limited to instances of a particular class</nullok>
+ </ptrtype>
+ <description>
+ Callbacks are only reported when the object is an instance of
+ this class.
+ Objects which are instances of a subclass of <code>klass</code>
+ are not reported.
+ If <code>klass</code> is an interface, no objects are reported.
+ This applies to both the object and primitive callbacks.
+ </description>
+ </param>
+ <param id="callbacks">
+ <inptr>
+ <struct>jvmtiHeapCallbacks</struct>
+ </inptr>
+ <description>
+ Structure defining the set callback functions.
+ </description>
+ </param>
+ <param id="user_data">
+ <inbuf>
+ <void/>
+ <nullok><code>NULL</code> is passed as the user supplied data</nullok>
+ </inbuf>
+ <description>
+ User supplied data to be passed to the callback.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_CLASS">
+ <paramlink id="klass"/> is not a valid class.
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetTag" phase="start" num="106">
+ <synopsis>Get Tag</synopsis>
+ <description>
+ 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
+ <functionlink id="SetTag"></functionlink>.
+ Objects for which no tags have been set return a
+ tag value of zero.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_tag_objects"></required>
+ </capabilities>
+ <parameters>
+ <param id="object">
+ <jobject/>
+ <description>
+ The object whose tag is to be retrieved.
+ </description>
+ </param>
+ <param id="tag_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ On return, the referenced long is set to the value
+ of the tag.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="SetTag" phase="start" num="107">
+ <synopsis>Set Tag</synopsis>
+ <description>
+ 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
+ <functionlink id="GetTag"></functionlink>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_tag_objects"></required>
+ </capabilities>
+ <parameters>
+ <param id="object">
+ <jobject/>
+ <description>
+ The object whose tag is to be set.
+ </description>
+ </param>
+ <param id="tag">
+ <jlong/>
+ <description>
+ The new value of the tag.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetObjectsWithTags" num="114">
+ <synopsis>Get Objects With Tags</synopsis>
+ <description>
+ Return objects in the heap with the specified tags.
+ The format is parallel arrays of objects and tags.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_tag_objects"></required>
+ </capabilities>
+ <parameters>
+ <param id="tag_count">
+ <jint min="0"/>
+ <description>
+ Number of tags to scan for.
+ </description>
+ </param>
+ <param id="tags">
+ <inbuf incount="tag_count">
+ <jlong/>
+ </inbuf>
+ <description>
+ Scan for objects with these tags.
+ Zero is not permitted in this array.
+ </description>
+ </param>
+ <param id="count_ptr">
+ <outptr>
+ <jint/>
+ </outptr>
+ <description>
+ Return the number of objects with any of the tags
+ in <paramlink id="tags"/>.
+ </description>
+ </param>
+ <param id="object_result_ptr">
+ <allocbuf outcount="count_ptr">
+ <jobject/>
+ <nullok>this information is not returned</nullok>
+ </allocbuf>
+ <description>
+ Returns the array of objects with any of the tags
+ in <paramlink id="tags"/>.
+ </description>
+ </param>
+ <param id="tag_result_ptr">
+ <allocbuf outcount="count_ptr">
+ <jlong/>
+ <nullok>this information is not returned</nullok>
+ </allocbuf>
+ <description>
+ For each object in <paramlink id="object_result_ptr"/>,
+ return the tag at the corresponding index.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
+ Zero is present in <paramlink id="tags"></paramlink>.
+ </error>
+ </errors>
+ </function>
+
+ <function id="ForceGarbageCollection" num="108">
+ <synopsis>Force Garbage Collection</synopsis>
+ <description>
+ 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.
+ <p/>
+ Although garbage collection is as complete
+ as possible there is no guarantee that all
+ <eventlink id="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.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+
+ </category>
+
+ <category id="Heap_1_0" label="Heap (1.0)">
+ <intro>
+ <b>
+ These functions and data types were introduced in the original
+ <jvmti/> version 1.0 and have been superseded by more
+ </b>
+ <internallink id="Heap"><b>powerful and flexible versions</b></internallink>
+ <b>
+ which:
+ </b>
+ <ul>
+ <li>
+ <b>
+ Allow access to primitive values (the value of Strings, arrays,
+ and primitive fields)
+ </b>
+ </li>
+ <li>
+ <b>
+ Allow the tag of the referrer to be set, thus enabling more
+ efficient localized reference graph building
+ </b>
+ </li>
+ <li>
+ <b>
+ Provide more extensive filtering abilities
+ </b>
+ </li>
+ <li>
+ <b>
+ Are extensible, allowing their abilities to grow in future versions of <jvmti/>
+ </b>
+ </li>
+ </ul>
+ <p/>
+ <b>Please use the </b>
+ <internallink id="Heap"><b>current Heap functions</b></internallink>.
+ <p/>
+ <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum">
+ <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1">
+ Tagged objects only.
+ </constant>
+ <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2">
+ Untagged objects only.
+ </constant>
+ <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3">
+ Either tagged or untagged objects.
+ </constant>
+ </constants>
+
+ <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum">
+ <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1">
+ JNI global reference.
+ </constant>
+ <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2">
+ System class.
+ </constant>
+ <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3">
+ Monitor.
+ </constant>
+ <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4">
+ Stack local.
+ </constant>
+ <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5">
+ JNI local reference.
+ </constant>
+ <constant id="JVMTI_HEAP_ROOT_THREAD" num="6">
+ Thread.
+ </constant>
+ <constant id="JVMTI_HEAP_ROOT_OTHER" num="7">
+ Other.
+ </constant>
+ </constants>
+
+ <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum">
+ <constant id="JVMTI_REFERENCE_CLASS" num="1">
+ Reference from an object to its class.
+ </constant>
+ <constant id="JVMTI_REFERENCE_FIELD" num="2">
+ Reference from an object to the value of one of its instance fields.
+ For references of this kind the <code>referrer_index</code>
+ parameter to the <internallink id="jvmtiObjectReferenceCallback">
+ jvmtiObjectReferenceCallback</internallink> 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 <functionlink id="GetClassFields"/>), with the total
+ number of fields (both public and private) declared in all superclasses
+ and superinterfaces. The index starts at zero.
+ </constant>
+ <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3">
+ Reference from an array to one of its elements.
+ For references of this kind the <code>referrer_index</code>
+ parameter to the <internallink id="jvmtiObjectReferenceCallback">
+ jvmtiObjectReferenceCallback</internallink> is the array index.
+ </constant>
+ <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4">
+ Reference from a class to its class loader.
+ </constant>
+ <constant id="JVMTI_REFERENCE_SIGNERS" num="5">
+ Reference from a class to its signers array.
+ </constant>
+ <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6">
+ Reference from a class to its protection domain.
+ </constant>
+ <constant id="JVMTI_REFERENCE_INTERFACE" num="7">
+ Reference from a class to one of its interfaces.
+ </constant>
+ <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8">
+ Reference from a class to the value of one of its static fields.
+ For references of this kind the <code>referrer_index</code>
+ parameter to the <internallink id="jvmtiObjectReferenceCallback">
+ jvmtiObjectReferenceCallback</internallink> 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 <functionlink id="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 <jvmti/> 1.0 Specification.
+ <rationale>No known implementations used the 1.0 definition.</rationale>
+ </constant>
+ <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9">
+ Reference from a class to a resolved entry in the constant pool.
+ For references of this kind the <code>referrer_index</code>
+ parameter to the <internallink id="jvmtiObjectReferenceCallback">
+ jvmtiObjectReferenceCallback</internallink> is the index into
+ constant pool table of the class, starting at 1. See the
+ <vmspeclink id="ClassFile.doc.html#20080"
+ name="Constant Pool section"/>
+ </constant>
+ </constants>
+
+ <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum">
+ <constant id="JVMTI_ITERATION_CONTINUE" num="1">
+ Continue the iteration.
+ If this is a reference iteration, follow the references of this object.
+ </constant>
+ <constant id="JVMTI_ITERATION_IGNORE" num="2">
+ Continue the iteration.
+ If this is a reference iteration, ignore the references of this object.
+ </constant>
+ <constant id="JVMTI_ITERATION_ABORT" num="0">
+ Abort the iteration.
+ </constant>
+ </constants>
+ </intro>
+
+ <callback id="jvmtiHeapObjectCallback">
+ <enum>jvmtiIterationControl</enum>
+ <synopsis>Heap Object Callback</synopsis>
+ <description>
+ Agent supplied callback function.
+ Describes (but does not pass in) an object in the heap.
+ <p/>
+ Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
+ or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
+ <p/>
+ See the <internallink id="heapCallbacks">heap callback
+ function restrictions</internallink>.
+ </description>
+ <parameters>
+ <param id="class_tag">
+ <jlong/>
+ <description>
+ The tag of the class of object (zero if the class is not tagged).
+ If the object represents a runtime class,
+ the <code>class_tag</code> is the tag
+ associated with <code>java.lang.Class</code>
+ (zero if <code>java.lang.Class</code> is not tagged).
+ </description>
+ </param>
+ <param id="size">
+ <jlong/>
+ <description>
+ Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
+ </description>
+ </param>
+ <param id="tag_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ The object tag value, or zero if the object is not tagged.
+ To set the tag value to be associated with the object
+ the agent sets the <code>jlong</code> pointed to by the parameter.
+ </description>
+ </param>
+ <param id="user_data">
+ <outptr><void/></outptr>
+ <description>
+ The user supplied data that was passed into the iteration function.
+ </description>
+ </param>
+ </parameters>
+ </callback>
+
+ <callback id="jvmtiHeapRootCallback">
+ <enum>jvmtiIterationControl</enum>
+ <synopsis>Heap Root Object Callback</synopsis>
+ <description>
+ Agent supplied callback function.
+ Describes (but does not pass in) an object that is a root for the purposes
+ of garbage collection.
+ <p/>
+ Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
+ <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
+ references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
+ <p/>
+ See the <internallink id="heapCallbacks">heap callback
+ function restrictions</internallink>.
+ </description>
+ <parameters>
+ <param id="root_kind">
+ <enum>jvmtiHeapRootKind</enum>
+ <description>
+ The kind of heap root.
+ </description>
+ </param>
+ <param id="class_tag">
+ <jlong/>
+ <description>
+ The tag of the class of object (zero if the class is not tagged).
+ If the object represents a runtime class, the <code>class_tag</code> is the tag
+ associated with <code>java.lang.Class</code>
+ (zero if <code>java.lang.Class</code> is not tagged).
+ </description>
+ </param>
+ <param id="size">
+ <jlong/>
+ <description>
+ Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
+ </description>
+ </param>
+ <param id="tag_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ The object tag value, or zero if the object is not tagged.
+ To set the tag value to be associated with the object
+ the agent sets the <code>jlong</code> pointed to by the parameter.
+ </description>
+ </param>
+ <param id="user_data">
+ <outptr><void/></outptr>
+ <description>
+ The user supplied data that was passed into the iteration function.
+ </description>
+ </param>
+ </parameters>
+ </callback>
+
+ <callback id="jvmtiStackReferenceCallback">
+ <enum>jvmtiIterationControl</enum>
+ <synopsis>Stack Reference Object Callback</synopsis>
+ <description>
+ Agent supplied callback function.
+ Describes (but does not pass in) an object on the stack that is a root for
+ the purposes of garbage collection.
+ <p/>
+ Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
+ <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
+ references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
+ <p/>
+ See the <internallink id="heapCallbacks">heap callback
+ function restrictions</internallink>.
+ </description>
+ <parameters>
+ <param id="root_kind">
+ <enum>jvmtiHeapRootKind</enum>
+ <description>
+ The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
+ <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>).
+ </description>
+ </param>
+ <param id="class_tag">
+ <jlong/>
+ <description>
+ The tag of the class of object (zero if the class is not tagged).
+ If the object represents a runtime class, the <code>class_tag</code> is the tag
+ associated with <code>java.lang.Class</code>
+ (zero if <code>java.lang.Class</code> is not tagged).
+ </description>
+ </param>
+ <param id="size">
+ <jlong/>
+ <description>
+ Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
+ </description>
+ </param>
+ <param id="tag_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ The object tag value, or zero if the object is not tagged.
+ To set the tag value to be associated with the object
+ the agent sets the <code>jlong</code> pointed to by the parameter.
+ </description>
+ </param>
+ <param id="thread_tag">
+ <jlong/>
+ <description>
+ The tag of the thread corresponding to this stack, zero if not tagged.
+ </description>
+ </param>
+ <param id="depth">
+ <jint/>
+ <description>
+ The depth of the frame.
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID/>
+ <description>
+ The method executing in this frame.
+ </description>
+ </param>
+ <param id="slot">
+ <jint/>
+ <description>
+ The slot number.
+ </description>
+ </param>
+ <param id="user_data">
+ <outptr><void/></outptr>
+ <description>
+ The user supplied data that was passed into the iteration function.
+ </description>
+ </param>
+ </parameters>
+ </callback>
+
+ <callback id="jvmtiObjectReferenceCallback">
+ <enum>jvmtiIterationControl</enum>
+ <synopsis>Object Reference Callback</synopsis>
+ <description>
+ Agent supplied callback function.
+ Describes a reference from an object (the referrer) to another object
+ (the referree).
+ <p/>
+ Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
+ <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
+ references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
+ <p/>
+ See the <internallink id="heapCallbacks">heap callback
+ function restrictions</internallink>.
+ </description>
+ <parameters>
+ <param id="reference_kind">
+ <enum>jvmtiObjectReferenceKind</enum>
+ <description>
+ The type of reference.
+ </description>
+ </param>
+ <param id="class_tag">
+ <jlong/>
+ <description>
+ The tag of the class of referree object (zero if the class is not tagged).
+ If the referree object represents a runtime class,
+ the <code>class_tag</code> is the tag
+ associated with <code>java.lang.Class</code>
+ (zero if <code>java.lang.Class</code> is not tagged).
+ </description>
+ </param>
+ <param id="size">
+ <jlong/>
+ <description>
+ Size of the referree object (in bytes).
+ See <functionlink id="GetObjectSize"/>.
+ </description>
+ </param>
+ <param id="tag_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ The referree object tag value, or zero if the object is not
+ tagged.
+ To set the tag value to be associated with the object
+ the agent sets the <code>jlong</code> pointed to by the parameter.
+ </description>
+ </param>
+ <param id="referrer_tag">
+ <jlong/>
+ <description>
+ The tag of the referrer object, or zero if the referrer
+ object is not tagged.
+ </description>
+ </param>
+ <param id="referrer_index">
+ <jint/>
+ <description>
+ For references of type <code>JVMTI_REFERENCE_FIELD</code> or
+ <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index
+ of the field in the referrer object. The index is based on the
+ order of all the object's fields - see <internallink
+ id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink>
+ or <internallink
+ id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD
+ </internallink> for further description.
+ <p/>
+ For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code>
+ the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT">
+ JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description.
+ <p/>
+ For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code>
+ the index into the constant pool of the class - see
+ <internallink id="JVMTI_REFERENCE_CONSTANT_POOL">
+ JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further
+ description.
+ <p/>
+ For references of other kinds the <code>referrer_index</code> is
+ <code>-1</code>.
+ </description>
+ </param>
+ <param id="user_data">
+ <outptr><void/></outptr>
+ <description>
+ The user supplied data that was passed into the iteration function.
+ </description>
+ </param>
+ </parameters>
+ </callback>
+
+ <function id="IterateOverObjectsReachableFromObject" num="109">
+ <synopsis>Iterate Over Objects Reachable From Object</synopsis>
+ <description>
+ This function iterates over all objects that are directly
+ and indirectly reachable from the specified object.
+ For each object <i>A</i> (known
+ as the referrer) with a reference to object <i>B</i> the specified
+ callback function is called to describe the object reference.
+ The callback is called 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,
+ These may be distinguished by the
+ <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
+ <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
+ The callback for an object will always occur after the callback for
+ its referrer.
+ <p/>
+ See <functionlink id="FollowReferences"/> for the object
+ references which are reported.
+ <p/>
+ 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.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_tag_objects"></required>
+ </capabilities>
+ <parameters>
+ <param id="object">
+ <jobject/>
+ <description>
+ The object
+ </description>
+ </param>
+ <param id="object_reference_callback">
+ <ptrtype>
+ <struct>jvmtiObjectReferenceCallback</struct>
+ </ptrtype>
+ <description>
+ The callback to be called to describe each
+ object reference.
+ </description>
+ </param>
+ <param id="user_data">
+ <inbuf>
+ <void/>
+ <nullok><code>NULL</code> is passed as the user supplied data</nullok>
+ </inbuf>
+ <description>
+ User supplied data to be passed to the callback.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="IterateOverReachableObjects" num="110">
+ <synopsis>Iterate Over Reachable Objects</synopsis>
+ <description>
+ This function iterates over the root objects and all objects that
+ are directly and indirectly reachable from the root objects.
+ The root objects comprise the set of system classes,
+ JNI globals, references from thread stacks, and other objects used as roots
+ for the purposes of garbage collection.
+ <p/>
+ For each root the <paramlink id="heap_root_callback"></paramlink>
+ or <paramlink id="stack_ref_callback"></paramlink> callback is called.
+ An object can be a root object for more than one reason and in that case
+ the appropriate callback is called for each reason.
+ <p/>
+ For each object reference the <paramlink id="object_ref_callback"></paramlink>
+ callback function is called to describe the object reference.
+ The callback is called 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,
+ These may be distinguished by the
+ <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
+ <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
+ The callback for an object will always occur after the callback for
+ its referrer.
+ <p/>
+ See <functionlink id="FollowReferences"/> for the object
+ references which are reported.
+ <p/>
+ Roots are always reported to the profiler before any object references
+ are reported. In other words, the <paramlink id="object_ref_callback"></paramlink>
+ callback will not be called until the appropriate callback has been called
+ for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is
+ specified as <code>NULL</code> then this function returns after
+ reporting the root objects to the profiler.
+ <p/>
+ 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.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_tag_objects"></required>
+ </capabilities>
+ <parameters>
+ <param id="heap_root_callback">
+ <ptrtype>
+ <struct>jvmtiHeapRootCallback</struct>
+ <nullok>do not report heap roots</nullok>
+ </ptrtype>
+ <description>
+ The callback function to be called for each heap root of type
+ <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>,
+ <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>,
+ <code>JVMTI_HEAP_ROOT_MONITOR</code>,
+ <code>JVMTI_HEAP_ROOT_THREAD</code>, or
+ <code>JVMTI_HEAP_ROOT_OTHER</code>.
+ </description>
+ </param>
+ <param id="stack_ref_callback">
+ <ptrtype>
+ <struct>jvmtiStackReferenceCallback</struct>
+ <nullok>do not report stack references</nullok>
+ </ptrtype>
+ <description>
+ The callback function to be called for each heap root of
+ <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
+ <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>.
+ </description>
+ </param>
+ <param id="object_ref_callback">
+ <ptrtype>
+ <struct>jvmtiObjectReferenceCallback</struct>
+ <nullok>do not follow references from the root objects</nullok>
+ </ptrtype>
+ <description>
+ The callback function to be called for each object reference.
+ </description>
+ </param>
+ <param id="user_data">
+ <inbuf>
+ <void/>
+ <nullok><code>NULL</code> is passed as the user supplied data</nullok>
+ </inbuf>
+ <description>
+ User supplied data to be passed to the callback.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="IterateOverHeap" num="111">
+ <synopsis>Iterate Over Heap</synopsis>
+ <description>
+ Iterate over all objects in the heap. This includes both reachable and
+ unreachable objects.
+ <p/>
+ The <paramlink id="object_filter"></paramlink> parameter indicates the
+ objects for which the callback function is called. If this parameter
+ is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be
+ called for every object that is tagged. If the parameter is
+ <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
+ for objects that are not tagged. If the parameter
+ is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
+ called for every object in the heap, irrespective of whether it is
+ tagged or not.
+ <p/>
+ 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.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_tag_objects"></required>
+ </capabilities>
+ <parameters>
+ <param id="object_filter">
+ <enum>jvmtiHeapObjectFilter</enum>
+ <description>
+ Indicates the objects for which the callback function is called.
+ </description>
+ </param>
+ <param id="heap_object_callback">
+ <ptrtype>
+ <struct>jvmtiHeapObjectCallback</struct>
+ </ptrtype>
+ <description>
+ The iterator function to be called for each
+ object matching the <paramlink id="object_filter"/>.
+ </description>
+ </param>
+ <param id="user_data">
+ <inbuf>
+ <void/>
+ <nullok><code>NULL</code> is passed as the user supplied data</nullok>
+ </inbuf>
+ <description>
+ User supplied data to be passed to the callback.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="IterateOverInstancesOfClass" num="112">
+ <synopsis>Iterate Over Instances Of Class</synopsis>
+ <description>
+ Iterate over all objects in the heap that are instances of the specified class.
+ This includes direct instances of the specified class and
+ instances of all subclasses of the specified class.
+ This includes both reachable and unreachable objects.
+ <p/>
+ The <paramlink id="object_filter"></paramlink> parameter indicates the
+ objects for which the callback function is called. If this parameter
+ is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be
+ called for every object that is tagged. If the parameter is
+ <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
+ called for objects that are not tagged. If the parameter
+ is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
+ called for every object in the heap, irrespective of whether it is
+ tagged or not.
+ <p/>
+ 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.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_tag_objects"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ Iterate over objects of this class only.
+ </description>
+ </param>
+ <param id="object_filter">
+ <enum>jvmtiHeapObjectFilter</enum>
+ <description>
+ Indicates the objects for which the callback function is called.
+ </description>
+ </param>
+ <param id="heap_object_callback">
+ <ptrtype>
+ <struct>jvmtiHeapObjectCallback</struct>
+ </ptrtype>
+ <description>
+ The iterator function to be called for each
+ <paramlink id="klass"/> instance matching
+ the <paramlink id="object_filter"/>.
+ </description>
+ </param>
+ <param id="user_data">
+ <inbuf>
+ <void/>
+ <nullok><code>NULL</code> is passed as the user supplied data</nullok>
+ </inbuf>
+ <description>
+ User supplied data to be passed to the callback.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ </category>
+
+ <category id="local" label="Local Variable">
+
+ <intro>
+ These functions are used to retrieve or set the value of a local variable.
+ The variable is identified by the depth of the frame containing its
+ value and the variable's slot number within that frame.
+ The mapping of variables to
+ slot numbers can be obtained with the function
+ <functionlink id="GetLocalVariableTable"></functionlink>.
+ </intro>
+
+ <function id="GetLocalObject" num="21">
+ <synopsis>Get Local Variable - Object</synopsis>
+ <description>
+ This function can be used to retrieve the value of a local
+ variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_access_local_variables"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" frame="frame"/>
+ <description>
+ The thread of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="depth">
+ <jframeID thread="thread"/>
+ <description>
+ The depth of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="slot">
+ <jint/>
+ <description>
+ The variable's slot number.
+ </description>
+ </param>
+ <param id="value_ptr">
+ <outptr><jobject/></outptr>
+ <description>
+ On return, points to the variable's value.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_SLOT">
+ Invalid <code>slot</code>.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The variable type is not
+ <code>Object</code> or a subclass of <code>Object</code>.
+ </error>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Not a visible frame
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetLocalInt" num="22">
+ <synopsis>Get Local Variable - Int</synopsis>
+ <description>
+ This function can be used to retrieve the value of a local
+ variable whose type is <code>int</code>,
+ <code>short</code>, <code>char</code>, <code>byte</code>, or
+ <code>boolean</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_access_local_variables"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" frame="frame"/>
+ <description>
+ The thread of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="depth">
+ <jframeID thread="thread"/>
+ <description>
+ The depth of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="slot">
+ <jint/>
+ <description>
+ The variable's slot number.
+ </description>
+ </param>
+ <param id="value_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the variable's value.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_SLOT">
+ Invalid <code>slot</code>.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The variable type is not
+ <code>int</code>, <code>short</code>,
+ <code>char</code>, <code>byte</code>, or
+ <code>boolean</code>.
+ </error>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Not a visible frame
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetLocalLong" num="23">
+ <synopsis>Get Local Variable - Long</synopsis>
+ <description>
+ This function can be used to retrieve the value of a local
+ variable whose type is <code>long</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_access_local_variables"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" frame="frame"/>
+ <description>
+ The thread of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="depth">
+ <jframeID thread="thread"/>
+ <description>
+ The depth of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="slot">
+ <jint/>
+ <description>
+ The variable's slot number.
+ </description>
+ </param>
+ <param id="value_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ On return, points to the variable's value.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_SLOT">
+ Invalid <code>slot</code>.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The variable type is not <code>long</code>.
+ </error>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Not a visible frame
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetLocalFloat" num="24">
+ <synopsis>Get Local Variable - Float</synopsis>
+ <description>
+ This function can be used to retrieve the value of a local
+ variable whose type is <code>float</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_access_local_variables"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" frame="frame"/>
+ <description>
+ The thread of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="depth">
+ <jframeID thread="thread"/>
+ <description>
+ The depth of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="slot">
+ <jint/>
+ <description>
+ The variable's slot number.
+ </description>
+ </param>
+ <param id="value_ptr">
+ <outptr><jfloat/></outptr>
+ <description>
+ On return, points to the variable's value.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_SLOT">
+ Invalid <code>slot</code>.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The variable type is not <code>float</code>.
+ </error>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Not a visible frame
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetLocalDouble" num="25">
+ <synopsis>Get Local Variable - Double</synopsis>
+ <description>
+ This function can be used to retrieve the value of a local
+ variable whose type is <code>long</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_access_local_variables"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" frame="frame"/>
+ <description>
+ The thread of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="depth">
+ <jframeID thread="thread"/>
+ <description>
+ The depth of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="slot">
+ <jint/>
+ <description>
+ The variable's slot number.
+ </description>
+ </param>
+ <param id="value_ptr">
+ <outptr><jdouble/></outptr>
+ <description>
+ On return, points to the variable's value.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_SLOT">
+ Invalid <code>slot</code>.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The variable type is not <code>double</code>.
+ </error>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Not a visible frame
+ </error>
+ </errors>
+ </function>
+
+ <function id="SetLocalObject" num="26">
+ <synopsis>Set Local Variable - Object</synopsis>
+ <description>
+ This function can be used to set the value of a local
+ variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_access_local_variables"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" frame="frame"/>
+ <description>
+ The thread of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="depth">
+ <jframeID thread="thread"/>
+ <description>
+ The depth of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="slot">
+ <jint/>
+ <description>
+ The variable's slot number.
+ </description>
+ </param>
+ <param id="value">
+ <jobject/>
+ <description>
+ The new value for the variable.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_SLOT">
+ Invalid <code>slot</code>.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The variable type is not
+ <code>Object</code> or a subclass of <code>Object</code>.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The supplied <paramlink id="value"/> is not compatible
+ with the variable type.
+ </error>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Not a visible frame
+ </error>
+ </errors>
+ </function>
+
+ <function id="SetLocalInt" num="27">
+ <synopsis>Set Local Variable - Int</synopsis>
+ <description>
+ This function can be used to set the value of a local
+ variable whose type is <code>int</code>,
+ <code>short</code>, <code>char</code>, <code>byte</code>, or
+ <code>boolean</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_access_local_variables"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" frame="frame"/>
+ <description>
+ The thread of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="depth">
+ <jframeID thread="thread"/>
+ <description>
+ The depth of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="slot">
+ <jint/>
+ <description>
+ The variable's slot number.
+ </description>
+ </param>
+ <param id="value">
+ <jint/>
+ <description>
+ The new value for the variable.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_SLOT">
+ Invalid <code>slot</code>.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The variable type is not
+ <code>int</code>, <code>short</code>,
+ <code>char</code>, <code>byte</code>, or
+ <code>boolean</code>.
+ </error>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Not a visible frame
+ </error>
+ </errors>
+ </function>
+
+ <function id="SetLocalLong" num="28">
+ <synopsis>Set Local Variable - Long</synopsis>
+ <description>
+ This function can be used to set the value of a local
+ variable whose type is <code>long</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_access_local_variables"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" frame="frame"/>
+ <description>
+ The thread of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="depth">
+ <jframeID thread="thread"/>
+ <description>
+ The depth of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="slot">
+ <jint/>
+ <description>
+ The variable's slot number.
+ </description>
+ </param>
+ <param id="value">
+ <jlong/>
+ <description>
+ The new value for the variable.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_SLOT">
+ Invalid <code>slot</code>.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The variable type is not <code>long</code>.
+ </error>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Not a visible frame
+ </error>
+ </errors>
+ </function>
+
+ <function id="SetLocalFloat" num="29">
+ <synopsis>Set Local Variable - Float</synopsis>
+ <description>
+ This function can be used to set the value of a local
+ variable whose type is <code>float</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_access_local_variables"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" frame="frame"/>
+ <description>
+ The thread of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="depth">
+ <jframeID thread="thread"/>
+ <description>
+ The depth of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="slot">
+ <jint/>
+ <description>
+ The variable's slot number.
+ </description>
+ </param>
+ <param id="value">
+ <jfloat/>
+ <description>
+ The new value for the variable.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_SLOT">
+ Invalid <code>slot</code>.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The variable type is not <code>float</code>.
+ </error>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Not a visible frame
+ </error>
+ </errors>
+ </function>
+
+ <function id="SetLocalDouble" num="30">
+ <synopsis>Set Local Variable - Double</synopsis>
+ <description>
+ This function can be used to set the value of a local
+ variable whose type is <code>double</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_access_local_variables"></required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current" frame="frame"/>
+ <description>
+ The thread of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="depth">
+ <jframeID thread="thread"/>
+ <description>
+ The depth of the frame containing the variable's value.
+ </description>
+ </param>
+ <param id="slot">
+ <jint/>
+ <description>
+ The variable's slot number.
+ </description>
+ </param>
+ <param id="value">
+ <jdouble/>
+ <description>
+ The new value for the variable.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_SLOT">
+ Invalid <code>slot</code>.
+ </error>
+ <error id="JVMTI_ERROR_TYPE_MISMATCH">
+ The variable type is not <code>double</code>.
+ </error>
+ <error id="JVMTI_ERROR_OPAQUE_FRAME">
+ Not a visible frame
+ </error>
+ </errors>
+ </function>
+ </category>
+
+ <category id="breakpointCategory" label="Breakpoint">
+
+ <intro>
+ </intro>
+
+ <function id="SetBreakpoint" num="38">
+ <synopsis>Set Breakpoint</synopsis>
+ <description>
+ Set a breakpoint at the instruction indicated by
+ <code>method</code> and <code>location</code>.
+ An instruction can only have one breakpoint.
+ <p/>
+ Whenever the designated instruction is about to be executed, a
+ <eventlink id="Breakpoint"></eventlink> event is generated.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_breakpoint_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ The class in which to set the breakpoint
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ The method in which to set the breakpoint
+ </description>
+ </param>
+ <param id="location">
+ <jlocation/>
+ <description>
+ the index of the instruction at which to set the breakpoint
+
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_DUPLICATE">
+ The designated bytecode already has a breakpoint.
+ </error>
+ </errors>
+ </function>
+
+ <function id="ClearBreakpoint" num="39">
+ <synopsis>Clear Breakpoint</synopsis>
+ <description>
+ Clear the breakpoint at the bytecode indicated by
+ <code>method</code> and <code>location</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_breakpoint_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ The class in which to clear the breakpoint
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ The method in which to clear the breakpoint
+ </description>
+ </param>
+ <param id="location">
+ <jlocation/>
+ <description>
+ the index of the instruction at which to clear the breakpoint
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_NOT_FOUND">
+ There's no breakpoint at the designated bytecode.
+ </error>
+ </errors>
+ </function>
+
+ </category>
+
+ <category id="fieldWatch" label="Watched Field">
+
+ <intro>
+ </intro>
+
+ <function id="SetFieldAccessWatch" num="41">
+ <synopsis>Set Field Access Watch</synopsis>
+ <description>
+ Generate a <eventlink id="FieldAccess"></eventlink> event
+ when the field specified
+ by <code>klass</code> and
+ <code>field</code> is about to be accessed.
+ An event will be generated for each access of the field
+ until it is canceled with
+ <functionlink id="ClearFieldAccessWatch"></functionlink>.
+ Field accesses from Java programming language code or from JNI code are watched,
+ fields modified by other means are not watched.
+ Note that <jvmti/> users should be aware that their own field accesses
+ will trigger the watch.
+ A field can only have one field access watch set.
+ Modification of a field is not considered an access--use
+ <functionlink id="SetFieldModificationWatch"></functionlink>
+ to monitor modifications.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_field_access_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass field="field"/>
+ <description>
+ The class containing the field to watch
+ </description>
+ </param>
+ <param id="field">
+ <jfieldID class="klass"/>
+ <description>
+ The field to watch
+
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_DUPLICATE">
+ The designated field is already being watched for accesses.
+ </error>
+ </errors>
+ </function>
+
+ <function id="ClearFieldAccessWatch" num="42">
+ <synopsis>Clear Field Access Watch</synopsis>
+ <description>
+ Cancel a field access watch previously set by
+ <functionlink id="SetFieldAccessWatch"></functionlink>, on the
+ field specified
+ by <code>klass</code> and
+ <code>field</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_field_access_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass field="field"/>
+ <description>
+ The class containing the field to watch
+ </description>
+ </param>
+ <param id="field">
+ <jfieldID class="klass"/>
+ <description>
+ The field to watch
+
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_NOT_FOUND">
+ The designated field is not being watched for accesses.
+ </error>
+ </errors>
+ </function>
+
+ <function id="SetFieldModificationWatch" num="43">
+ <synopsis>Set Field Modification Watch</synopsis>
+ <description>
+ Generate a <eventlink id="FieldModification"></eventlink> event
+ when the field specified
+ by <code>klass</code> and
+ <code>field</code> is about to be modified.
+ An event will be generated for each modification of the field
+ until it is canceled with
+ <functionlink id="ClearFieldModificationWatch"></functionlink>.
+ Field modifications from Java programming language code or from JNI code are watched,
+ fields modified by other means are not watched.
+ Note that <jvmti/> users should be aware that their own field modifications
+ will trigger the watch.
+ A field can only have one field modification watch set.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_field_modification_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass field="field"/>
+ <description>
+ The class containing the field to watch
+ </description>
+ </param>
+ <param id="field">
+ <jfieldID class="klass"/>
+ <description>
+ The field to watch
+
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_DUPLICATE">
+ The designated field is already being watched for modifications.
+ </error>
+ </errors>
+ </function>
+
+ <function id="ClearFieldModificationWatch" num="44">
+ <synopsis>Clear Field Modification Watch</synopsis>
+ <description>
+
+ Cancel a field modification watch previously set by
+ <functionlink id="SetFieldModificationWatch"></functionlink>, on the
+ field specified
+ by <code>klass</code> and
+ <code>field</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_field_modification_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass field="field"/>
+ <description>
+ The class containing the field to watch
+ </description>
+ </param>
+ <param id="field">
+ <jfieldID class="klass"/>
+ <description>
+ The field to watch
+
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_NOT_FOUND">
+ The designated field is not being watched for modifications.
+ </error>
+ </errors>
+ </function>
+ </category>
+
+ <category id="class" label="Class">
+
+ <intro>
+ </intro>
+
+ <function id="GetLoadedClasses" jkernel="yes" num="78">
+ <synopsis>Get Loaded Classes</synopsis>
+ <description>
+ Return an array of all classes loaded in the virtual machine.
+ The number of classes in the array is returned via
+ <code>class_count_ptr</code>, and the array itself via
+ <code>classes_ptr</code>.
+ <p/>
+ Array classes of all types (including arrays of primitive types) are
+ included in the returned list. Primitive classes (for example,
+ <code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="class_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of classes.
+ </description>
+ </param>
+ <param id="classes_ptr">
+ <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
+ <description>
+ On return, points to an array of references, one
+ for each class.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetClassLoaderClasses" jkernel="yes" num="79">
+ <synopsis>Get Classloader Classes</synopsis>
+ <description>
+ Returns an array of those classes for which this class loader has
+ been recorded as an initiating loader. Each
+ class in the returned array was created by this class loader,
+ either by defining it directly or by delegation to another class loader.
+ See the
+ <vmspeclink id="ConstantPool.doc.html#72007"
+ name="Creation and Loading section"/>.
+ <p/>
+ For JDK version 1.1 implementations that don't
+ recognize the distinction between initiating and defining class loaders,
+ this function should return all classes loaded in the virtual machine.
+ The number of classes in the array is returned via
+ <code>class_count_ptr</code>, and the array itself via
+ <code>classes_ptr</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="initiating_loader">
+ <ptrtype>
+ <jobject/>
+ <nullok>the classes initiated by the bootstrap loader will be returned</nullok>
+ </ptrtype>
+ <description>
+ An initiating class loader.
+ </description>
+ </param>
+ <param id="class_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of classes.
+ </description>
+ </param>
+ <param id="classes_ptr">
+ <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
+ <description>
+ On return, points to an array of references, one
+ for each class.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetClassSignature" phase="start" num="48">
+ <synopsis>Get Class Signature</synopsis>
+ <description>
+ For the class indicated by <code>klass</code>, return the
+ <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/types.html#wp16432">JNI
+ type signature</externallink>
+ and the generic signature of the class.
+ For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code>
+ and <code>int[]</code> is <code>"[I"</code>
+ The returned name for primitive classes
+ is the type signature character of the corresponding primitive type.
+ For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>.
+ </description>
+ <origin>jvmdiClone</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="signature_ptr">
+ <allocbuf>
+ <char/>
+ <nullok>the signature is not returned</nullok>
+ </allocbuf>
+ <description>
+ On return, points to the JNI type signature of the class, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ <param id="generic_ptr">
+ <allocbuf>
+ <char/>
+ <nullok>the generic signature is not returned</nullok>
+ </allocbuf>
+ <description>
+ On return, points to the generic signature of the class, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ If there is no generic signature attribute for the class, then,
+ on return, points to <code>NULL</code>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetClassStatus" phase="start" num="49">
+ <synopsis>Get Class Status</synopsis>
+ <description>
+ Get the status of the class. Zero or more of the following bits can be
+ set.
+ <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits">
+ <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1">
+ Class bytecodes have been verified
+ </constant>
+ <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2">
+ Class preparation is complete
+ </constant>
+ <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4">
+ Class initialization is complete. Static initializer has been run.
+ </constant>
+ <constant id="JVMTI_CLASS_STATUS_ERROR" num="8">
+ Error during initialization makes class unusable
+ </constant>
+ <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16">
+ Class is an array. If set, all other bits are zero.
+ </constant>
+ <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32">
+ Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>).
+ If set, all other bits are zero.
+ </constant>
+ </constants>
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="status_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the current state of this class as one or
+ more of the <internallink id="jvmtiClassStatus">class status flags</internallink>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetSourceFileName" phase="start" num="50">
+ <synopsis>Get Source File Name</synopsis>
+ <description>
+ For the class indicated by <code>klass</code>, return the source file
+ name via <code>source_name_ptr</code>. The returned string
+ is a file name only and never contains a directory name.
+ <p/>
+ For primitive classes (for example, <code>java.lang.Integer.TYPE</code>)
+ and for arrays this function returns
+ <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_get_source_file_name"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="source_name_ptr">
+ <allocbuf><char/></allocbuf>
+ <description>
+ On return, points to the class's source file name, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_ABSENT_INFORMATION">
+ Class information does not include a source file name. This includes
+ cases where the class is an array class or primitive class.
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetClassModifiers" phase="start" num="51">
+ <synopsis>Get Class Modifiers</synopsis>
+ <description>
+ For the class indicated by <code>klass</code>, return the access
+ flags
+ via <code>modifiers_ptr</code>.
+ Access flags are defined in the
+ <vmspeclink id="ClassFile.doc.html"
+ name="Class File Format chapter"/>.
+ <p/>
+ If the class is an array class, then its public, private, and protected
+ modifiers are the same as those of its component type. For arrays of
+ primitives, this component type is represented by one of the primitive
+ classes (for example, <code>java.lang.Integer.TYPE</code>).
+ <p/>
+ If the class is a primitive class, its public modifier is always true,
+ and its protected and private modifiers are always false.
+ <p/>
+ If the class is an array class or a primitive class then its final
+ modifier is always true and its interface modifier is always false.
+ The values of its other modifiers are not determined by this specification.
+
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="modifiers_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the current access flags of this class.
+
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetClassMethods" phase="start" num="52">
+ <synopsis>Get Class Methods</synopsis>
+ <description>
+ For the class indicated by <code>klass</code>, return a count of
+ methods via <code>method_count_ptr</code> and a list of
+ method IDs via <code>methods_ptr</code>. The method list contains
+ constructors and static initializers as well as true methods.
+ Only directly declared methods are returned (not inherited methods).
+ An empty method list is returned for array classes and primitive classes
+ (for example, <code>java.lang.Integer.TYPE</code>).
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <capability id="can_maintain_original_method_order"/>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="method_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of methods declared in this class.
+ </description>
+ </param>
+ <param id="methods_ptr">
+ <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf>
+ <description>
+ On return, points to the method ID array.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
+ <paramlink id="klass"></paramlink> is not prepared.
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetClassFields" phase="start" num="53">
+ <synopsis>Get Class Fields</synopsis>
+ <description>
+ For the class indicated by <code>klass</code>, return a count of fields
+ via <code>field_count_ptr</code> and a list of field IDs via
+ <code>fields_ptr</code>.
+ Only directly declared fields are returned (not inherited fields).
+ Fields are returned in the order they occur in the class file.
+ An empty field list is returned for array classes and primitive classes
+ (for example, <code>java.lang.Integer.TYPE</code>).
+ Use JNI to determine the length of an array.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="field_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of fields declared in this class.
+ </description>
+ </param>
+ <param id="fields_ptr">
+ <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf>
+ <description>
+ On return, points to the field ID array.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
+ <paramlink id="klass"></paramlink> is not prepared.
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetImplementedInterfaces" phase="start" num="54">
+ <synopsis>Get Implemented Interfaces</synopsis>
+ <description>
+ Return the direct super-interfaces of this class. For a class, this
+ function returns the interfaces declared in its <code>implements</code>
+ clause. For an interface, this function returns the interfaces declared in
+ its <code>extends</code> clause.
+ An empty interface list is returned for array classes and primitive classes
+ (for example, <code>java.lang.Integer.TYPE</code>).
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="interface_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of interfaces.
+ </description>
+ </param>
+ <param id="interfaces_ptr">
+ <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf>
+ <description>
+ On return, points to the interface array.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
+ <paramlink id="klass"></paramlink> is not prepared.
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1">
+ <synopsis>Get Class Version Numbers</synopsis>
+ <description>
+ For the class indicated by <code>klass</code>,
+ return the minor and major version numbers,
+ as defined in the
+ <vmspeclink id="ClassFile.doc.html"
+ name="Class File Format chapter"/>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="minor_version_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the value of the
+ <code>minor_version</code> item of the
+ Class File Format.
+ Note: to be consistent with the Class File Format,
+ the minor version number is the first parameter.
+ </description>
+ </param>
+ <param id="major_version_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the value of the
+ <code>major_version</code> item of the
+ Class File Format.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_ABSENT_INFORMATION">
+ The class is a primitive or array class.
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetConstantPool" phase="start" num="146" since="1.1">
+ <synopsis>Get Constant Pool</synopsis>
+ <description>
+ For the class indicated by <code>klass</code>,
+ return the raw bytes of the constant pool in the format of the
+ <code>constant_pool</code> item of the
+ <vmspeclink id="ClassFile.doc.html"
+ name="Class File Format"
+ preposition="in"/>.
+ The format of the constant pool may differ between versions
+ of the Class File Format, so, the
+ <functionlink id="GetClassVersionNumbers">minor and major
+ class version numbers</functionlink> should be checked for
+ compatibility.
+ <p/>
+ The returned constant pool might not have the same layout or
+ contents as the constant pool in the defining class file.
+ The constant pool returned by GetConstantPool() may have
+ more or fewer entries than the defining constant pool.
+ Entries may be in a different order.
+ The constant pool returned by GetConstantPool() will match the
+ constant pool used by
+ <functionlink id="GetBytecodes">GetBytecodes()</functionlink>.
+ That is, the bytecodes returned by GetBytecodes() will have
+ constant pool indices which refer to constant pool entries returned
+ by GetConstantPool().
+ Note that since <functionlink id="RetransformClasses"/>
+ and <functionlink id="RedefineClasses"/> can change
+ the constant pool, the constant pool returned by this function
+ can change accordingly. Thus, the correspondence between
+ GetConstantPool() and GetBytecodes() does not hold if there
+ is an intervening class retransformation or redefinition.
+ The value of a constant pool entry used by a given bytecode will
+ match that of the defining class file (even if the indices don't match).
+ Constant pool entries which are not used directly or indirectly by
+ bytecodes (for example, UTF-8 strings associated with annotations) are
+ not required to exist in the returned constant pool.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_get_constant_pool"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="constant_pool_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of entries
+ in the constant pool table plus one.
+ This corresponds to the <code>constant_pool_count</code>
+ item of the Class File Format.
+ </description>
+ </param>
+ <param id="constant_pool_byte_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of bytes
+ in the returned raw constant pool.
+ </description>
+ </param>
+ <param id="constant_pool_bytes_ptr">
+ <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf>
+ <description>
+ On return, points to the raw constant pool, that is the bytes
+ defined by the <code>constant_pool</code> item of the
+ Class File Format
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_ABSENT_INFORMATION">
+ The class is a primitive or array class.
+ </error>
+ </errors>
+ </function>
+
+ <function id="IsInterface" phase="start" num="55">
+ <synopsis>Is Interface</synopsis>
+ <description>
+ Determines whether a class object reference represents an interface.
+ The <code>jboolean</code> result is
+ <code>JNI_TRUE</code> if the "class" is actually an interface,
+ <code>JNI_FALSE</code> otherwise.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="is_interface_ptr">
+ <outptr><jboolean/></outptr>
+ <description>
+ On return, points to the boolean result of this function.
+
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="IsArrayClass" phase="start" num="56">
+ <synopsis>Is Array Class</synopsis>
+ <description>
+ Determines whether a class object reference represents an array.
+ The <code>jboolean</code> result is
+ <code>JNI_TRUE</code> if the class is an array,
+ <code>JNI_FALSE</code> otherwise.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="is_array_class_ptr">
+ <outptr><jboolean/></outptr>
+ <description>
+ On return, points to the boolean result of this function.
+
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1">
+ <synopsis>Is Modifiable Class</synopsis>
+ <description>
+ Determines whether a class is modifiable.
+ If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/>
+ returns <code>JNI_TRUE</code>) the class can be
+ redefined with <functionlink id="RedefineClasses"/> (assuming
+ the agent possesses the
+ <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/>
+ capability) or
+ retransformed with <functionlink id="RetransformClasses"/> (assuming
+ the agent possesses the
+ <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
+ capability).
+ If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/>
+ returns <code>JNI_FALSE</code>) the class can be neither
+ redefined nor retransformed.
+ <p/>
+ Primitive classes (for example, <code>java.lang.Integer.TYPE</code>)
+ and array classes are never modifiable.
+ <p/>
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <capability id="can_redefine_any_class">
+ If possessed then all classes (except primitive and array classes)
+ are modifiable.
+ </capability>
+ <capability id="can_redefine_classes">
+ No effect on the result of the function.
+ But must additionally be possessed to modify the class with
+ <functionlink id="RedefineClasses"/>.
+ </capability>
+ <capability id="can_retransform_classes">
+ No effect on the result of the function.
+ But must additionally be possessed to modify the class with
+ <functionlink id="RetransformClasses"/>.
+ </capability>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="is_modifiable_class_ptr">
+ <outptr><jboolean/></outptr>
+ <description>
+ On return, points to the boolean result of this function.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetClassLoader" phase="start" num="57">
+ <synopsis>Get Class Loader</synopsis>
+ <description>
+ For the class indicated by <code>klass</code>, return via
+ <code>classloader_ptr</code> a reference to the class loader for the
+ class.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="classloader_ptr">
+ <outptr><jobject/></outptr>
+ <description>
+ On return, points to the class loader that loaded
+ this class.
+ If the class was not created by a class loader
+ or if the class loader is the bootstrap class loader,
+ points to <code>NULL</code>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+
+ </function>
+
+ <function id="GetSourceDebugExtension" phase="start" num="90">
+ <synopsis>Get Source Debug Extension</synopsis>
+ <description>
+ For the class indicated by <code>klass</code>, return the debug
+ extension via <code>source_debug_extension_ptr</code>.
+ The returned string
+ contains exactly the debug extension information present in the
+ class file of <code>klass</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_get_source_debug_extension"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="source_debug_extension_ptr">
+ <allocbuf><char/></allocbuf>
+ <description>
+ On return, points to the class's debug extension, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_ABSENT_INFORMATION">
+ Class information does not include a debug extension.
+ </error>
+ </errors>
+ </function>
+
+ <function id="RetransformClasses" jkernel="yes" num="152" since="1.1">
+ <synopsis>Retransform Classes</synopsis>
+ <description>
+ This function facilitates the
+ <internallink id="bci">bytecode instrumentation</internallink>
+ of already loaded classes.
+ To replace the class definition without reference to the existing
+ bytecodes, as one might do when recompiling from source for
+ fix-and-continue debugging, <functionlink id="RedefineClasses"/>
+ function should be used instead.
+ <p/>
+ When classes are initially loaded or when they are
+ <functionlink id="RedefineClasses">redefined</functionlink>,
+ the initial class file bytes can be transformed with the
+ <eventlink id="ClassFileLoadHook"/> event.
+ This function reruns the transformation process
+ (whether or not a transformation has previously occurred).
+ This retransformation follows these steps:
+ <ul>
+ <li>starting from the initial class file bytes
+ </li>
+ <li>for each <fieldlink id="can_retransform_classes"
+ struct="jvmtiCapabilities">retransformation
+ incapable</fieldlink>
+ agent which received a
+ <code>ClassFileLoadHook</code> event during the previous
+ load or redefine, the bytes it returned
+ (via the <code>new_class_data</code> parameter)
+ are reused as the output of the transformation;
+ note that this is equivalent to reapplying
+ the previous transformation, unaltered. except that
+ the <code>ClassFileLoadHook</code> event
+ is <b>not</b> sent to these agents
+ </li>
+ <li>for each <fieldlink id="can_retransform_classes"
+ struct="jvmtiCapabilities">retransformation
+ capable</fieldlink>
+ agent, the <code>ClassFileLoadHook</code> event is sent,
+ allowing a new transformation to be applied
+ </li>
+ <li>the transformed class file bytes are installed as the new
+ definition of the class
+ </li>
+ </ul>
+ See the <eventlink id="ClassFileLoadHook"/> event for more details.
+ <p/>
+ The initial class file bytes represent the bytes passed to
+ <code>ClassLoader.defineClass</code>
+ or <code>RedefineClasses</code> (before any transformations
+ were applied), however they may not exactly match them.
+ The constant pool may differ in ways described in
+ <functionlink id="GetConstantPool"/>.
+ Constant pool indices in the bytecodes of methods will correspond.
+ Some attributes may not be present.
+ Where order is not meaningful, for example the order of methods,
+ order may not be preserved.
+ <p/>
+ Retransformation can cause new versions of methods to be installed.
+ Old method versions may become
+ <internallink id="obsoleteMethods">obsolete</internallink>
+ The new method version will be used on new invokes.
+ If a method has active stack frames, those active frames continue to
+ run the bytecodes of the original method version.
+ <p/>
+ This function does not cause any initialization except that which
+ would occur under the customary JVM semantics.
+ In other words, retransforming a class does not cause its initializers to be
+ run. The values of static fields will remain as they were
+ prior to the call.
+ <p/>
+ Threads need not be suspended.
+ <p/>
+ All breakpoints in the class are cleared.
+ <p/>
+ All attributes are updated.
+ <p/>
+ Instances of the retransformed class are not affected -- fields retain their
+ previous values.
+ <functionlink id="GetTag">Tags</functionlink> on the instances are
+ also unaffected.
+ <p/>
+ In response to this call, no events other than the
+ <eventlink id="ClassFileLoadHook"/> event
+ will be sent.
+ <p/>
+ The retransformation may change method bodies, the constant pool and attributes.
+ The retransformation must not add, remove or rename fields or methods, change the
+ signatures of methods, change modifiers, or change inheritance.
+ These restrictions may be lifted in future versions.
+ See the error return description below for information on error codes
+ returned if an unsupported retransformation is attempted.
+ The class file bytes are not verified or installed until they have passed
+ through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
+ returned error code reflects the result of the transformations.
+ If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
+ none of the classes to be retransformed will have a new definition installed.
+ When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
+ all of the classes to be retransformed will have their new definitions installed.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_retransform_classes"></required>
+ <capability id="can_retransform_any_class"></capability>
+ </capabilities>
+ <parameters>
+ <param id="class_count">
+ <jint min="0"/>
+ <description>
+ The number of classes to be retransformed.
+ </description>
+ </param>
+ <param id="classes">
+ <inbuf incount="class_count"><jclass/></inbuf>
+ <description>
+ The array of classes to be retransformed.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
+ One of the <paramlink id="classes"/> cannot be modified.
+ See <functionlink id="IsModifiableClass"/>.
+ </error>
+ <error id="JVMTI_ERROR_INVALID_CLASS">
+ One of the <paramlink id="classes"/> is not a valid class.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
+ A retransformed class file has a version number not supported by this VM.
+ </error>
+ <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
+ A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>).
+ </error>
+ <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
+ The retransformed class file definitions would lead to a circular definition
+ (the VM would return a <code>ClassCircularityError</code>).
+ </error>
+ <error id="JVMTI_ERROR_FAILS_VERIFICATION">
+ The retransformed class file bytes fail verification.
+ </error>
+ <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
+ The class name defined in a retransformed class file is
+ different from the name in the old class object.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
+ A retransformed class file would require adding a method.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
+ A retransformed class file changes a field.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
+ A direct superclass is different for a retransformed class file,
+ or the set of directly implemented
+ interfaces is different.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
+ A retransformed class file does not declare a method
+ declared in the old class version.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
+ A retransformed class file has different class modifiers.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
+ A method in the retransformed class file has different modifiers
+ than its counterpart in the old class version.
+ </error>
+ </errors>
+ </function>
+
+ <function id="RedefineClasses" jkernel="yes" num="87">
+ <synopsis>Redefine Classes</synopsis>
+ <typedef id="jvmtiClassDefinition" label="Class redefinition description">
+ <field id="klass">
+ <jclass/>
+ <description>
+ Class object for this class
+ </description>
+ </field>
+ <field id="class_byte_count">
+ <jint/>
+ <description>
+ Number of bytes defining class (below)
+ </description>
+ </field>
+ <field id="class_bytes">
+ <inbuf incount="class_byte_count"><uchar/></inbuf>
+ <description>
+ Bytes defining class (in the
+ <vmspeclink id="ClassFile.doc.html"
+ name="Class File Format"/>)
+ </description>
+ </field>
+ </typedef>
+ <description>
+ All classes given are redefined according to the definitions
+ supplied.
+ This function is used to replace the definition of a class
+ with a new definition, as might be needed in fix-and-continue
+ debugging.
+ Where the existing class file bytes are to be transformed, for
+ example in
+ <internallink id="bci">bytecode instrumentation</internallink>,
+ <functionlink id="RetransformClasses"/> should be used.
+ <p/>
+ Redefinition can cause new versions of methods to be installed.
+ Old method versions may become
+ <internallink id="obsoleteMethods">obsolete</internallink>
+ The new method version will be used on new invokes.
+ If a method has active stack frames, those active frames continue to
+ run the bytecodes of the original method version.
+ If resetting of stack frames is desired, use
+ <functionlink id="PopFrame"></functionlink>
+ to pop frames with obsolete method versions.
+ <p/>
+ This function does not cause any initialization except that which
+ would occur under the customary JVM semantics.
+ In other words, redefining a class does not cause its initializers to be
+ run. The values of static fields will remain as they were
+ prior to the call.
+ <p/>
+ Threads need not be suspended.
+ <p/>
+ All breakpoints in the class are cleared.
+ <p/>
+ All attributes are updated.
+ <p/>
+ Instances of the redefined class are not affected -- fields retain their
+ previous values.
+ <functionlink id="GetTag">Tags</functionlink> on the instances are
+ also unaffected.
+ <p/>
+ In response to this call, the <jvmti/> event
+ <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink>
+ will be sent (if enabled), but no other <jvmti/> events will be sent.
+ <p/>
+ The redefinition may change method bodies, the constant pool and attributes.
+ The redefinition must not add, remove or rename fields or methods, change the
+ signatures of methods, change modifiers, or change inheritance.
+ These restrictions may be lifted in future versions.
+ See the error return description below for information on error codes
+ returned if an unsupported redefinition is attempted.
+ The class file bytes are not verified or installed until they have passed
+ through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
+ returned error code reflects the result of the transformations applied
+ to the bytes passed into <paramlink id="class_definitions"/>.
+ If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
+ none of the classes to be redefined will have a new definition installed.
+ When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
+ all of the classes to be redefined will have their new definitions installed.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_redefine_classes"></required>
+ <capability id="can_redefine_any_class"></capability>
+ </capabilities>
+ <parameters>
+ <param id="class_count">
+ <jint min="0"/>
+ <description>
+ The number of classes specified in <code>class_definitions</code>
+ </description>
+ </param>
+ <param id="class_definitions">
+ <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf>
+ <description>
+ The array of new class definitions
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_NULL_POINTER">
+ One of <code>class_bytes</code> is <code>NULL</code>.
+ </error>
+ <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
+ An element of <code>class_definitions</code> cannot be modified.
+ See <functionlink id="IsModifiableClass"/>.
+ </error>
+ <error id="JVMTI_ERROR_INVALID_CLASS">
+ An element of <code>class_definitions</code> is not a valid class.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
+ A new class file has a version number not supported by this VM.
+ </error>
+ <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
+ A new class file is malformed (The VM would return a <code>ClassFormatError</code>).
+ </error>
+ <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
+ The new class file definitions would lead to a circular definition
+ (the VM would return a <code>ClassCircularityError</code>).
+ </error>
+ <error id="JVMTI_ERROR_FAILS_VERIFICATION">
+ The class bytes fail verification.
+ </error>
+ <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
+ The class name defined in a new class file is
+ different from the name in the old class object.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
+ A new class file would require adding a method.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
+ A new class version changes a field.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
+ A direct superclass is different for a new class
+ version, or the set of directly implemented
+ interfaces is different.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
+ A new class version does not declare a method
+ declared in the old class version.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
+ A new class version has different modifiers.
+ </error>
+ <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
+ A method in the new class version has different modifiers
+ than its counterpart in the old class version.
+ </error>
+ </errors>
+ </function>
+
+ </category>
+
+ <category id="object" label="Object">
+
+ <function id="GetObjectSize" jkernel="yes" phase="start" num="154">
+ <synopsis>Get Object Size</synopsis>
+ <description>
+ For the object indicated by <code>object</code>,
+ return via <code>size_ptr</code> the size of the object.
+ This size is an implementation-specific approximation of
+ the amount of storage consumed by this object.
+ It may include some or all of the object's overhead, and thus
+ is useful for comparison within an implementation but not
+ between implementations.
+ The estimate may change during a single invocation of the JVM.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="object">
+ <jobject/>
+ <description>
+ The object to query.
+ </description>
+ </param>
+ <param id="size_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ On return, points to the object's size in bytes.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetObjectHashCode" phase="start" num="58">
+ <synopsis>Get Object Hash Code</synopsis>
+ <description>
+ For the object indicated by <code>object</code>,
+ return via <code>hash_code_ptr</code> a hash code.
+ This hash code could be used to maintain a hash table of object references,
+ however, on some implementations this can cause significant performance
+ impacts--in most cases
+ <internallink id="Heap">tags</internallink>
+ will be a more efficient means of associating information with objects.
+ This function guarantees
+ the same hash code value for a particular object throughout its life
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="object">
+ <jobject/>
+ <description>
+ The object to query.
+ </description>
+ </param>
+ <param id="hash_code_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the object's hash code.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetObjectMonitorUsage" num="59">
+ <synopsis>Get Object Monitor Usage</synopsis>
+ <typedef id="jvmtiMonitorUsage" label="Object monitor usage information">
+ <field id="owner">
+ <jthread/>
+ <description>
+ The thread owning this monitor, or <code>NULL</code> if unused
+ </description>
+ </field>
+ <field id="entry_count">
+ <jint/>
+ <description>
+ The number of times the owning thread has entered the monitor
+ </description>
+ </field>
+ <field id="waiter_count">
+ <jint/>
+ <description>
+ The number of threads waiting to own this monitor
+ </description>
+ </field>
+ <field id="waiters">
+ <allocfieldbuf><jthread/></allocfieldbuf>
+ <description>
+ The <code>waiter_count</code> waiting threads
+ </description>
+ </field>
+ <field id="notify_waiter_count">
+ <jint/>
+ <description>
+ The number of threads waiting to be notified by this monitor
+ </description>
+ </field>
+ <field id="notify_waiters">
+ <allocfieldbuf><jthread/></allocfieldbuf>
+ <description>
+ The <code>notify_waiter_count</code> threads waiting to be notified
+ </description>
+ </field>
+ </typedef>
+ <description>
+ Get information about the object's monitor.
+ The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure
+ are filled in with information about usage of the monitor.
+ <todo>
+ Decide and then clarify suspend requirements.
+ </todo>
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_get_monitor_info"></required>
+ </capabilities>
+ <parameters>
+ <param id="object">
+ <jobject/>
+ <description>
+ The object to query.
+ </description>
+ </param>
+ <param id="info_ptr">
+ <outptr><struct>jvmtiMonitorUsage</struct></outptr>
+ <description>
+ On return, filled with monitor information for the
+ specified object.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <elide>
+ <function id="GetObjectMonitors" num="116">
+ <synopsis>Get Object Monitors</synopsis>
+ <description>
+ Return the list of object monitors.
+ <p/>
+ Note: details about each monitor can be examined with
+ <functionlink id="GetObjectMonitorUsage"></functionlink>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_get_monitor_info"></required>
+ </capabilities>
+ <parameters>
+ <param id="monitorCnt">
+ <outptr><jint/></outptr>
+ <description>
+ On return, pointer to the number
+ of monitors returned in <code>monitors_ptr</code>.
+ </description>
+ </param>
+ <param id="monitors_ptr">
+ <allocbuf outcount="monitorCnt"><jobject/></allocbuf>
+ <description>
+ On return, pointer to the monitor list.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+ </elide>
+
+ </category>
+
+ <category id="fieldCategory" label="Field">
+
+ <intro>
+ </intro>
+
+ <function id="GetFieldName" phase="start" num="60">
+ <synopsis>Get Field Name (and Signature)</synopsis>
+ <description>
+ For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>,
+ return the field name via <paramlink id="name_ptr"/> and field signature via
+ <paramlink id="signature_ptr"/>.
+ <p/>
+ Field signatures are defined in the JNI Specification and
+ are referred to as
+ <vmspeclink id="ClassFile.doc.html#14152"
+ name="field descriptors"
+ preposition="in"/>.
+ </description>
+ <origin>jvmdiClone</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass field="field"/>
+ <description>
+ The class of the field to query.
+ </description>
+ </param>
+ <param id="field">
+ <jfieldID class="klass"/>
+ <description>
+ The field to query.
+ </description>
+ </param>
+ <param id="name_ptr">
+ <allocbuf>
+ <char/>
+ <nullok>the name is not returned</nullok>
+ </allocbuf>
+ <description>
+ On return, points to the field name, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ <param id="signature_ptr">
+ <allocbuf>
+ <char/>
+ <nullok>the signature is not returned</nullok>
+ </allocbuf>
+ <description>
+ On return, points to the field signature, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ <param id="generic_ptr">
+ <allocbuf>
+ <char/>
+ <nullok>the generic signature is not returned</nullok>
+ </allocbuf>
+ <description>
+ On return, points to the generic signature of the field, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ If there is no generic signature attribute for the field, then,
+ on return, points to <code>NULL</code>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetFieldDeclaringClass" phase="start" num="61">
+ <synopsis>Get Field Declaring Class</synopsis>
+ <description>
+ For the field indicated by <code>klass</code> and <code>field</code>
+ return the class that defined it via <code>declaring_class_ptr</code>.
+ The declaring class will either be <code>klass</code>, a superclass, or
+ an implemented interface.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass field="field"/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="field">
+ <jfieldID class="klass"/>
+ <description>
+ The field to query.
+ </description>
+ </param>
+ <param id="declaring_class_ptr">
+ <outptr><jclass/></outptr>
+ <description>
+ On return, points to the declaring class
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetFieldModifiers" phase="start" num="62">
+ <synopsis>Get Field Modifiers</synopsis>
+ <description>
+ For the field indicated by <code>klass</code> and <code>field</code>
+ return the access flags via <code>modifiers_ptr</code>.
+ Access flags are defined in the
+ <vmspeclink id="ClassFile.doc.html"
+ name="Class File Format chapter"/>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass field="field"/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="field">
+ <jfieldID class="klass"/>
+ <description>
+ The field to query.
+ </description>
+ </param>
+ <param id="modifiers_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the access flags.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="IsFieldSynthetic" phase="start" num="63">
+ <synopsis>Is Field Synthetic</synopsis>
+ <description>
+ For the field indicated by <code>klass</code> and <code>field</code>, return a
+ value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>.
+ Synthetic fields are generated by the compiler but not present in the
+ original source code.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_get_synthetic_attribute"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass field="field"/>
+ <description>
+ The class of the field to query.
+ </description>
+ </param>
+ <param id="field">
+ <jfieldID class="klass"/>
+ <description>
+ The field to query.
+ </description>
+ </param>
+ <param id="is_synthetic_ptr">
+ <outptr><jboolean/></outptr>
+ <description>
+ On return, points to the boolean result of this function.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ </category>
+
+ <category id="method" label="Method">
+
+ <intro>
+ These functions provide information about a method (represented as a
+ <typelink id="jmethodID"/>) and set how methods are processed.
+ </intro>
+
+ <intro id="obsoleteMethods" label="Obsolete Methods">
+ The functions <functionlink id="RetransformClasses"/> and
+ <functionlink id="RedefineClasses"/> can cause new versions
+ of methods to be installed.
+ An original version of a method is considered equivalent
+ to the new version if:
+ <ul>
+ <li>their bytecodes are the same except for indices into the
+ constant pool and </li>
+ <li>the referenced constants are equal.</li>
+ </ul>
+ An original method version which is not equivalent to the
+ new method version is called obsolete and is assigned a new method ID;
+ the original method ID now refers to the new method version.
+ A method ID can be tested for obsolescence with
+ <functionlink id="IsMethodObsolete"/>.
+ </intro>
+
+ <function id="GetMethodName" phase="start" num="64">
+ <synopsis>Get Method Name (and Signature)</synopsis>
+ <description>
+ For the method indicated by <code>method</code>,
+ return the method name via <code>name_ptr</code> and method signature via
+ <code>signature_ptr</code>.
+ <p/>
+ Method signatures are defined in the JNI Specification and are referred to as
+ <vmspeclink id="ClassFile.doc.html#7035"
+ name="method descriptors"
+ preposition="in"/>.
+ Note this is different
+ than method signatures as defined in the <i>Java Language Specification</i>.
+ </description>
+ <origin>jvmdiClone</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="method">
+ <jmethodID/>
+ <description>
+ The method to query.
+ </description>
+ </param>
+ <param id="name_ptr">
+ <allocbuf>
+ <char/>
+ <nullok>the name is not returned</nullok>
+ </allocbuf>
+ <description>
+ On return, points to the method name, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ <param id="signature_ptr">
+ <allocbuf>
+ <char/>
+ <nullok>the signature is not returned</nullok>
+ </allocbuf>
+ <description>
+ On return, points to the method signature, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ <param id="generic_ptr">
+ <allocbuf>
+ <char/>
+ <nullok>the generic signature is not returned</nullok>
+ </allocbuf>
+ <description>
+ On return, points to the generic signature of the method, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ If there is no generic signature attribute for the method, then,
+ on return, points to <code>NULL</code>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetMethodDeclaringClass" phase="start" num="65">
+ <synopsis>Get Method Declaring Class</synopsis>
+ <description>
+ For the method indicated by <code>method</code>,
+ return the class that defined it via <code>declaring_class_ptr</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ The method to query.
+ </description>
+ </param>
+ <param id="declaring_class_ptr">
+ <outptr><jclass/></outptr>
+ <description>
+ On return, points to the declaring class
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetMethodModifiers" phase="start" num="66">
+ <synopsis>Get Method Modifiers</synopsis>
+ <description>
+ For the method indicated by <code>method</code>,
+ return the access flags via <code>modifiers_ptr</code>.
+ Access flags are defined in the
+ <vmspeclink id="ClassFile.doc.html"
+ name="Class File Format chapter"/>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ The method to query.
+ </description>
+ </param>
+ <param id="modifiers_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the access flags.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetMaxLocals" phase="start" num="68">
+ <synopsis>Get Max Locals</synopsis>
+ <description>
+ For the method indicated by <code>method</code>,
+ return the number of local variable slots used by the method,
+ including the local variables used to pass parameters to the
+ method on its invocation.
+ <p/>
+ See <code>max_locals</code> in the
+ <vmspeclink id="ClassFile.doc.html#1546"
+ name="Code Attribute section"/>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass" native="error"/>
+ <description>
+ The method to query.
+ </description>
+ </param>
+ <param id="max_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the maximum number of local slots
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetArgumentsSize" phase="start" num="69">
+ <synopsis>Get Arguments Size</synopsis>
+ <description>
+ For the method indicated by <code>method</code>,
+ return via <code>max_ptr</code> the number of local variable slots used
+ by the method's arguments.
+ Note that two-word arguments use two slots.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass" native="error"/>
+ <description>
+ The method to query.
+ </description>
+ </param>
+ <param id="size_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of argument slots
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetLineNumberTable" phase="start" num="70">
+ <synopsis>Get Line Number Table</synopsis>
+ <typedef id="jvmtiLineNumberEntry" label="Line number table entry">
+ <field id="start_location">
+ <jlocation/>
+ <description>
+ the <datalink id="jlocation"></datalink> where the line begins
+ </description>
+ </field>
+ <field id="line_number">
+ <jint/>
+ <description>
+ the line number
+ </description>
+ </field>
+ </typedef>
+ <description>
+ For the method indicated by <code>method</code>,
+ return a table of source line number entries. The size of the table is
+ returned via <code>entry_count_ptr</code> and the table itself is
+ returned via <code>table_ptr</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_get_line_numbers"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass" native="error"/>
+ <description>
+ The method to query.
+ </description>
+ </param>
+ <param id="entry_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of entries in the table
+ </description>
+ </param>
+ <param id="table_ptr">
+ <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf>
+ <description>
+ On return, points to the line number table pointer.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_ABSENT_INFORMATION">
+ Class information does not include line numbers.
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetMethodLocation" phase="start" num="71">
+ <synopsis>Get Method Location</synopsis>
+ <description>
+ For the method indicated by <code>method</code>,
+ return the beginning and ending addresses through
+ <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a
+ conventional byte code indexing scheme,
+ <code>start_location_ptr</code> will always point to zero
+ and <code>end_location_ptr</code>
+ will always point to the byte code count minus one.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass" native="error"/>
+ <description>
+ The method to query.
+ </description>
+ </param>
+ <param id="start_location_ptr">
+ <outptr><jlocation/></outptr>
+ <description>
+ On return, points to the first location, or
+ <code>-1</code> if location information is not available.
+ If the information is available and
+ <functionlink id="GetJLocationFormat"></functionlink>
+ returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>
+ then this will always be zero.
+ </description>
+ </param>
+ <param id="end_location_ptr">
+ <outptr><jlocation/></outptr>
+ <description>
+ On return, points to the last location,
+ or <code>-1</code> if location information is not available.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_ABSENT_INFORMATION">
+ Class information does not include method sizes.
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetLocalVariableTable" num="72">
+ <synopsis>Get Local Variable Table</synopsis>
+ <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry">
+ <field id="start_location">
+ <jlocation/>
+ <description>
+ The code array index where the local variable is first valid
+ (that is, where it must have a value).
+ </description>
+ </field>
+ <field id="length">
+ <jint/>
+ <description>
+ The length of the valid section for this local variable.
+ The last code array index where the local variable is valid
+ is <code>start_location + length</code>.
+ </description>
+ </field>
+ <field id="name">
+ <allocfieldbuf><char/></allocfieldbuf>
+ <description>
+ The local variable name, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </field>
+ <field id="signature">
+ <allocfieldbuf><char/></allocfieldbuf>
+ <description>
+ The local variable's type signature, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ The signature format is the same as that defined in
+ <vmspeclink id="ClassFile.doc.html#14152"
+ name="Field Descriptors section"/>
+ </description>
+ </field>
+ <field id="generic_signature">
+ <allocfieldbuf><char/></allocfieldbuf>
+ <description>
+ The local variable's generic signature, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ The value of this field will be <code>NULL</code> for any local
+ variable which does not have a generic type.
+ </description>
+ </field>
+ <field id="slot">
+ <jint/>
+ <description>
+ The local variable's slot. See <internallink id="local">Local Variables</internallink>.
+ </description>
+ </field>
+ </typedef>
+ <description>
+ Return local variable information.
+ </description>
+ <origin>jvmdiClone</origin>
+ <capabilities>
+ <required id="can_access_local_variables"></required>
+ </capabilities>
+ <parameters>
+ <param id="method">
+ <jmethodID native="error"/>
+ <description>
+ The method to query.
+ </description>
+ </param>
+ <param id="entry_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of entries in the table
+ </description>
+ </param>
+ <param id="table_ptr">
+ <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf>
+ <description>
+ On return, points to an array of local variable table entries.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_ABSENT_INFORMATION">
+ Class information does not include local variable
+ information.
+ </error>
+ </errors>
+ </function>
+
+ <function id="GetBytecodes" phase="start" num="75">
+ <synopsis>Get Bytecodes</synopsis>
+ <description>
+ For the method indicated by <code>method</code>,
+ return the byte codes that implement the method. The number of
+ bytecodes is returned via <code>bytecode_count_ptr</code>. The byte codes
+ themselves are returned via <code>bytecodes_ptr</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_get_bytecodes"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass" native="error"/>
+ <description>
+ The method to query.
+ </description>
+ </param>
+ <param id="bytecode_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the length of the byte code array
+ </description>
+ </param>
+ <param id="bytecodes_ptr">
+ <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf>
+ <description>
+ On return, points to the pointer to the byte code array
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="IsMethodNative" phase="start" num="76">
+ <synopsis>Is Method Native</synopsis>
+ <description>
+ For the method indicated by <code>method</code>, return a
+ value indicating whether the method is native via <code>is_native_ptr</code>
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ The method to query.
+ </description>
+ </param>
+ <param id="is_native_ptr">
+ <outptr><jboolean/></outptr>
+ <description>
+ On return, points to the boolean result of this function.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="IsMethodSynthetic" phase="start" num="77">
+ <synopsis>Is Method Synthetic</synopsis>
+ <description>
+ For the method indicated by <code>method</code>, return a
+ value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>.
+ Synthetic methods are generated by the compiler but not present in the
+ original source code.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_get_synthetic_attribute"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ The method to query.
+ </description>
+ </param>
+ <param id="is_synthetic_ptr">
+ <outptr><jboolean/></outptr>
+ <description>
+ On return, points to the boolean result of this function.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="IsMethodObsolete" phase="start" num="91">
+ <synopsis>Is Method Obsolete</synopsis>
+ <description>
+ Determine if a method ID refers to an
+ <internallink id="obsoleteMethods">obsolete</internallink>
+ method version.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ The class to query.
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ The method ID to query.
+ </description>
+ </param>
+ <param id="is_obsolete_ptr">
+ <outptr><jboolean/></outptr>
+ <description>
+ On return, points to the boolean result of this function.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1">
+ <synopsis>Set Native Method Prefix</synopsis>
+ <description>
+ This function modifies the failure handling of
+ native method resolution by allowing retry
+ with a prefix applied to the name.
+ When used with the
+ <eventlink id="ClassFileLoadHook">ClassFileLoadHook
+ event</eventlink>, it enables native methods to be
+ <internallink id="bci">instrumented</internallink>.
+ <p/>
+ Since native methods cannot be directly instrumented
+ (they have no bytecodes), they must be wrapped with
+ a non-native method which can be instrumented.
+ For example, if we had:
+ <example>
+native boolean foo(int x);</example>
+ <p/>
+ We could transform the class file (with the
+ ClassFileLoadHook event) so that this becomes:
+ <example>
+boolean foo(int x) {
+ <i>... record entry to foo ...</i>
+ return wrapped_foo(x);
+}
+
+native boolean wrapped_foo(int x);</example>
+ <p/>
+ Where foo becomes a wrapper for the actual native method
+ with the appended prefix "wrapped_". Note that
+ "wrapped_" would be a poor choice of prefix since it
+ might conceivably form the name of an existing method
+ thus something like "$$$MyAgentWrapped$$$_" would be
+ better but would make these examples less readable.
+ <p/>
+ The wrapper will allow data to be collected on the native
+ method call, but now the problem becomes linking up the
+ wrapped method with the native implementation.
+ That is, the method <code>wrapped_foo</code> needs to be
+ resolved to the native implementation of <code>foo</code>,
+ which might be:
+ <example>
+Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example>
+ <p/>
+ This function allows the prefix to be specified and the
+ proper resolution to occur.
+ Specifically, when the standard resolution fails, the
+ resolution is retried taking the prefix into consideration.
+ There are two ways that resolution occurs, explicit
+ resolution with the JNI function <code>RegisterNatives</code>
+ and the normal automatic resolution. For
+ <code>RegisterNatives</code>, the VM will attempt this
+ association:
+ <example>
+method(foo) -> nativeImplementation(foo)</example>
+ <p/>
+ When this fails, the resolution will be retried with
+ the specified prefix prepended to the method name,
+ yielding the correct resolution:
+ <example>
+method(wrapped_foo) -> nativeImplementation(foo)</example>
+ <p/>
+ For automatic resolution, the VM will attempt:
+ <example>
+method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example>
+ <p/>
+ When this fails, the resolution will be retried with
+ the specified prefix deleted from the implementation name,
+ yielding the correct resolution:
+ <example>
+method(wrapped_foo) -> nativeImplementation(foo)</example>
+ <p/>
+ Note that since the prefix is only used when standard
+ resolution fails, native methods can be wrapped selectively.
+ <p/>
+ Since each <jvmti/> environment is independent and
+ can do its own transformation of the bytecodes, more
+ than one layer of wrappers may be applied. Thus each
+ environment needs its own prefix. Since transformations
+ are applied in order, the prefixes, if applied, will
+ be applied in the same order.
+ The order of transformation application is described in
+ the <eventlink id="ClassFileLoadHook"/> event.
+ Thus if three environments applied
+ wrappers, <code>foo</code> might become
+ <code>$env3_$env2_$env1_foo</code>. But if, say,
+ the second environment did not apply a wrapper to
+ <code>foo</code> it would be just
+ <code>$env3_$env1_foo</code>. To be able to
+ efficiently determine the sequence of prefixes,
+ an intermediate prefix is only applied if its non-native
+ wrapper exists. Thus, in the last example, even though
+ <code>$env1_foo</code> is not a native method, the
+ <code>$env1_</code> prefix is applied since
+ <code>$env1_foo</code> exists.
+ <p/>
+ Since the prefixes are used at resolution time
+ and since resolution may be arbitrarily delayed, a
+ native method prefix must remain set as long as there
+ are corresponding prefixed native methods.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_set_native_method_prefix"></required>
+ </capabilities>
+ <parameters>
+ <param id="prefix">
+ <inbuf>
+ <char/>
+ <nullok>
+ any existing prefix in this environment is cancelled
+ </nullok>
+ </inbuf>
+ <description>
+ The prefix to apply, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1">
+ <synopsis>Set Native Method Prefixes</synopsis>
+ <description>
+ For a normal agent, <functionlink id="SetNativeMethodPrefix"/>
+ will provide all needed native method prefixing.
+ For a meta-agent that performs multiple independent class
+ file transformations (for example as a proxy for another
+ layer of agents) this function allows each transformation
+ to have its own prefix.
+ The prefixes are applied in the order supplied and are
+ processed in the same manor as described for the
+ application of prefixes from multiple <jvmti/> environments
+ in <functionlink id="SetNativeMethodPrefix"/>.
+ <p/>
+ Any previous prefixes are replaced. Thus, calling this
+ function with a <paramlink id="prefix_count"/> of <code>0</code>
+ disables prefixing in this environment.
+ <p/>
+ <functionlink id="SetNativeMethodPrefix"/> and this function
+ are the two ways to set the prefixes.
+ Calling <code>SetNativeMethodPrefix</code> with
+ a prefix is the same as calling this function with
+ <paramlink id="prefix_count"/> of <code>1</code>.
+ Calling <code>SetNativeMethodPrefix</code> with
+ <code>NULL</code> is the same as calling this function with
+ <paramlink id="prefix_count"/> of <code>0</code>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_set_native_method_prefix"></required>
+ </capabilities>
+ <parameters>
+ <param id="prefix_count">
+ <jint min="0"/>
+ <description>
+ The number of prefixes to apply.
+ </description>
+ </param>
+ <param id="prefixes">
+ <agentbuf>
+ <char/>
+ </agentbuf>
+ <description>
+ The prefixes to apply for this environment, each encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ </category>
+
+ <category id="RawMonitors" label="Raw Monitor">
+
+ <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31">
+ <synopsis>Create Raw Monitor</synopsis>
+ <description>
+ Create a raw monitor.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="name">
+ <inbuf><char/></inbuf>
+ <description>
+ A name to identify the monitor, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ <param id="monitor_ptr">
+ <outptr><jrawMonitorID/></outptr>
+ <description>
+ On return, points to the created monitor.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32">
+ <synopsis>Destroy Raw Monitor</synopsis>
+ <description>
+ Destroy the raw monitor.
+ If the monitor being destroyed has been entered by this thread, it will be
+ exited before it is destroyed.
+ If the monitor being destroyed has been entered by another thread,
+ an error will be returned and the monitor will not be destroyed.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="monitor">
+ <jrawMonitorID/>
+ <description>
+ The monitor
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
+ Not monitor owner
+ </error>
+ </errors>
+ </function>
+
+ <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33">
+ <synopsis>Raw Monitor Enter</synopsis>
+ <description>
+ Gain exclusive ownership of a raw monitor.
+ The same thread may enter a monitor more then once.
+ The thread must
+ <functionlink id="RawMonitorExit">exit</functionlink>
+ the monitor the same number of times as it is entered.
+ If a monitor is entered during <code>OnLoad</code> (before attached threads exist)
+ and has not exited when attached threads come into existence, the enter
+ is considered to have occurred on the main thread.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="monitor">
+ <jrawMonitorID/>
+ <description>
+ The monitor
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34">
+ <synopsis>Raw Monitor Exit</synopsis>
+ <description>
+ Release exclusive ownership of a raw monitor.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="monitor">
+ <jrawMonitorID/>
+ <description>
+ The monitor
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
+ Not monitor owner
+ </error>
+ </errors>
+ </function>
+
+ <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35">
+ <synopsis>Raw Monitor Wait</synopsis>
+ <description>
+ Wait for notification of the raw monitor.
+ <p/>
+ Causes the current thread to wait until either another thread calls
+ <functionlink id="RawMonitorNotify"/> or
+ <functionlink id="RawMonitorNotifyAll"/>
+ for the specified raw monitor, or the specified
+ <paramlink id="millis">timeout</paramlink>
+ has elapsed.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="monitor">
+ <jrawMonitorID/>
+ <description>
+ The monitor
+ </description>
+ </param>
+ <param id="millis">
+ <jlong/>
+ <description>
+ The timeout, in milliseconds. If the timeout is
+ zero, then real time is not taken into consideration
+ and the thread simply waits until notified.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
+ Not monitor owner
+ </error>
+ <error id="JVMTI_ERROR_INTERRUPT">
+ Wait was interrupted, try again
+ </error>
+ </errors>
+ </function>
+
+ <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36">
+ <synopsis>Raw Monitor Notify</synopsis>
+ <description>
+ Notify a single thread waiting on the raw monitor.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="monitor">
+ <jrawMonitorID/>
+ <description>
+ The monitor
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
+ Not monitor owner
+ </error>
+ </errors>
+ </function>
+
+ <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37">
+ <synopsis>Raw Monitor Notify All</synopsis>
+ <description>
+ Notify all threads waiting on the raw monitor.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="monitor">
+ <jrawMonitorID/>
+ <description>
+ The monitor
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
+ Not monitor owner
+ </error>
+ </errors>
+ </function>
+
+ <elide>
+ <function id="GetRawMonitorUse" num="118">
+ <synopsis>Get Raw Monitor Use</synopsis>
+ <description>
+ The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure
+ are filled in with information about usage of the raw monitor.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_get_raw_monitor_usage"></required>
+ </capabilities>
+ <parameters>
+ <param id="monitor">
+ <jrawMonitorID/>
+ <description>
+ the raw monitor to query.
+ </description>
+ </param>
+ <param id="info_ptr">
+ <outptr><struct>jvmtiMonitorUsage</struct></outptr>
+ <description>
+ On return, filled with monitor information for the
+ specified raw monitor.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetRawMonitors" num="119">
+ <synopsis>Get Raw Monitors</synopsis>
+ <description>
+ Return the list of raw monitors.
+ <p/>
+ Note: details about each monitor can be examined with
+ <functionlink id="GetRawMonitorUse"></functionlink>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_get_raw_monitor_usage"></required>
+ </capabilities>
+ <parameters>
+ <param id="monitorCnt">
+ <outptr><jint/></outptr>
+ <description>
+ On return, pointer to the number
+ of monitors returned in <code>monitors_ptr</code>.
+ </description>
+ </param>
+ <param id="monitors_ptr">
+ <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf>
+ <description>
+ On return, pointer to the monitor list.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+ </elide>
+ </category>
+
+ <category id="jniIntercept" label="JNI Function Interception">
+
+ <intro>
+ Provides the ability to intercept and resend
+ Java Native Interface (JNI) function calls
+ by manipulating the JNI function table.
+ See <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html">JNI
+ Functions</externallink> in the <i>Java Native Interface Specification</i>.
+ <p/>
+ The following example illustrates intercepting the
+ <code>NewGlobalRef</code> JNI call in order to count reference
+ creation.
+ <example>
+JNIEnv original_jni_Functions;
+JNIEnv redirected_jni_Functions;
+int my_global_ref_count = 0;
+
+jobject
+MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) {
+ ++my_global_ref_count;
+ return originalJNIFunctions->NewGlobalRef(env, lobj);
+}
+
+void
+myInit() {
+ jvmtiError err;
+
+ err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &original_jni_Functions);
+ if (err != JVMTI_ERROR_NONE) {
+ die();
+ }
+ err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &redirected_jni_Functions);
+ if (err != JVMTI_ERROR_NONE) {
+ die();
+ }
+ redirectedJNIFunctions->NewGlobalRef = MyNewGlobalRef;
+ err = (*jvmti_env)->SetJNIFunctionTable(jvmti_env, redirected_jni_Functions);
+ if (err != JVMTI_ERROR_NONE) {
+ die();
+ }
+}
+ </example>
+ Sometime after <code>myInit</code> is called the user's JNI
+ code is executed which makes the call to create a new global
+ reference. Instead of going to the normal JNI implementation
+ the call goes to <code>myNewGlobalRef</code>. Note that a
+ copy of the original function table is kept so that the normal
+ JNI function can be called after the data is collected.
+ Note also that any JNI functions which are not overwritten
+ will behave normally.
+ <todo>
+ check that the example compiles and executes.
+ </todo>
+ </intro>
+
+ <function id="SetJNIFunctionTable" phase="start" num="120">
+ <synopsis>Set JNI Function Table</synopsis>
+ <description>
+ Set the JNI function table
+ in all current and future JNI environments.
+ As a result, all future JNI calls are directed to the specified functions.
+ Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the
+ function table to pass to this function.
+ For this function to take effect the the updated table entries must be
+ used by the JNI clients.
+ Since the table is defined <code>const</code> some compilers may optimize
+ away the access to the table, thus preventing this function from taking
+ effect.
+ The table is copied--changes to the local copy of the
+ table have no effect.
+ This function affects only the function table, all other aspects of the environment are
+ unaffected.
+ See the examples <internallink id="jniIntercept">above</internallink>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="function_table">
+ <inptr>
+ <struct>jniNativeInterface</struct>
+ </inptr>
+ <description>
+ Points to the new JNI function table.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetJNIFunctionTable" phase="start" num="121">
+ <synopsis>Get JNI Function Table</synopsis>
+ <description>
+ Get the JNI function table.
+ The JNI function table is copied into allocated memory.
+ If <functionlink id="SetJNIFunctionTable"></functionlink>
+ has been called, the modified (not the original) function
+ table is returned.
+ Only the function table is copied, no other aspects of the environment
+ are copied.
+ See the examples <internallink id="jniIntercept">above</internallink>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="function_table">
+ <allocbuf>
+ <struct>jniNativeInterface</struct>
+ </allocbuf>
+ <description>
+ On return, <code>*function_table</code>
+ points a newly allocated copy of the JNI function table.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ </category>
+
+ <category id="eventManagement" label="Event Management">
+
+ <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122">
+ <synopsis>Set Event Callbacks</synopsis>
+ <description>
+ Set the functions to be called for each event.
+ The callbacks are specified by supplying a replacement function table.
+ The function table is copied--changes to the local copy of the
+ table have no effect.
+ This is an atomic action, all callbacks are set at once.
+ No events are sent before this function is called.
+ When an entry is <code>NULL</code> or when the event is beyond
+ <paramlink id="size_of_callbacks"></paramlink> no event is sent.
+ Details on events are
+ described <internallink id="EventSection">later</internallink> in this document.
+ An event must be enabled and have a callback in order to be
+ sent--the order in which this function and
+ <functionlink id="SetEventNotificationMode"></functionlink>
+ are called does not affect the result.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="callbacks">
+ <inptr>
+ <struct>jvmtiEventCallbacks</struct>
+ <nullok>remove the existing callbacks</nullok>
+ </inptr>
+ <description>
+ The new event callbacks.
+ </description>
+ </param>
+ <param id="size_of_callbacks">
+ <jint min="0"/>
+ <description>
+ <code>sizeof(jvmtiEventCallbacks)</code>--for version
+ compatibility.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2">
+ <synopsis>Set Event Notification Mode</synopsis>
+ <description>
+ Control the generation of events.
+ <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum">
+ <constant id="JVMTI_ENABLE" num="1">
+ If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>,
+ the event <paramlink id="event_type"></paramlink> will be enabled
+ </constant>
+ <constant id="JVMTI_DISABLE" num="0">
+ If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>,
+ the event <paramlink id="event_type"></paramlink> will be disabled
+ </constant>
+ </constants>
+ If <code>thread</code> is <code>NULL</code>,
+ the event is enabled or disabled globally; otherwise, it is
+ enabled or disabled for a particular thread.
+ An event is generated for
+ a particular thread if it is enabled either at the thread or global
+ levels.
+ <p/>
+ See <internallink id="EventIndex">below</internallink> for information on specific events.
+ <p/>
+ The following events cannot be controlled at the thread
+ level through this function.
+ <ul>
+ <li><eventlink id="VMInit"></eventlink></li>
+ <li><eventlink id="VMStart"></eventlink></li>
+ <li><eventlink id="VMDeath"></eventlink></li>
+ <li><eventlink id="ThreadStart"></eventlink></li>
+ <li><eventlink id="CompiledMethodLoad"></eventlink></li>
+ <li><eventlink id="CompiledMethodUnload"></eventlink></li>
+ <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
+ <li><eventlink id="DataDumpRequest"></eventlink></li>
+ </ul>
+ <p/>
+ Initially, no events are enabled at either the thread level
+ or the global level.
+ <p/>
+ Any needed capabilities (see Event Enabling Capabilities below) must be possessed
+ before calling this function.
+ <p/>
+ Details on events are
+ described <internallink id="EventSection">below</internallink>.
+ </description>
+ <origin>jvmdiClone</origin>
+ <eventcapabilities></eventcapabilities>
+ <parameters>
+ <param id="mode">
+ <enum>jvmtiEventMode</enum>
+ <description>
+ <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code>
+ </description>
+ </param>
+ <param id="event_type">
+ <enum>jvmtiEvent</enum>
+ <description>
+ the event to control
+ </description>
+ </param>
+ <param id="event_thread">
+ <ptrtype>
+ <jthread impl="noconvert"/>
+ <nullok>event is controlled at the global level</nullok>
+ </ptrtype>
+ <description>
+ The thread to control
+ </description>
+ </param>
+ <param id="...">
+ <varargs/>
+ <description>
+ for future expansion
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_INVALID_THREAD">
+ <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread.
+ </error>
+ <error id="JVMTI_ERROR_THREAD_NOT_ALIVE">
+ <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead).
+ </error>
+ <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
+ thread level control was attempted on events which do not
+ permit thread level control.
+ </error>
+ <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY">
+ The Required Event Enabling Capability is not possessed.
+ </error>
+ </errors>
+ </function>
+
+ <function id="GenerateEvents" num="123">
+ <synopsis>Generate Events</synopsis>
+ <description>
+ Generate events to represent the current state of the VM.
+ For example, if <paramlink id="event_type"/> is
+ <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>,
+ a <eventlink id="CompiledMethodLoad"></eventlink> event will be
+ sent for each currently compiled method.
+ Methods that were loaded and now have been unloaded are not sent.
+ The history of what events have previously been sent does not
+ effect what events are sent by this function--for example,
+ all currently compiled methods
+ will be sent each time this function is called.
+ <p/>
+ This function is useful when
+ events may have been missed due to the agent attaching after program
+ execution begins; this function generates the missed events.
+ <p/>
+ Attempts to execute Java programming language code or
+ JNI functions may be paused until this function returns -
+ so neither should be called from the thread sending the event.
+ This function returns only after the missed events have been
+ sent, processed and have returned.
+ The event may be sent on a different thread than the thread
+ on which the event occurred.
+ The callback for the event must be set with
+ <functionlink id="SetEventCallbacks"></functionlink>
+ and the event must be enabled with
+ <functionlink id="SetEventNotificationMode"></functionlink>
+ or the events will not occur.
+ If the VM no longer has the information to generate some or
+ all of the requested events, the events are simply not sent -
+ no error is returned.
+ <p/>
+ Only the following events are supported:
+ <ul>
+ <li><eventlink id="CompiledMethodLoad"></eventlink></li>
+ <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
+ </ul>
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <capability id="can_generate_compiled_method_load_events"></capability>
+ </capabilities>
+ <parameters>
+ <param id="event_type">
+ <enum>jvmtiEvent</enum>
+ <description>
+ The type of event to generate. Must be one of these:
+ <ul>
+ <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li>
+ <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li>
+ </ul>
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY">
+ <paramlink id="event_type"/> is
+ <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
+ and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink>
+ is <code>false</code>.
+ </error>
+ <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
+ <paramlink id="event_type"/> is other than
+ <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
+ or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>.
+ </error>
+ </errors>
+ </function>
+
+ </category>
+
+ <category id="extension" label="Extension Mechanism">
+
+ <intro>
+ These functions
+ allow a <jvmti/> implementation to provide functions and events
+ beyond those defined in this specification.
+ <p/>
+ Both extension functions and extension events have parameters
+ each of which has a 'type' and 'kind' chosen from the following tables:
+
+ <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum">
+ <constant id="JVMTI_TYPE_JBYTE" num="101">
+ Java programming language primitive type - <code>byte</code>.
+ JNI type <code>jbyte</code>.
+ </constant>
+ <constant id="JVMTI_TYPE_JCHAR" num="102">
+ Java programming language primitive type - <code>char</code>.
+ JNI type <code>jchar</code>.
+ </constant>
+ <constant id="JVMTI_TYPE_JSHORT" num="103">
+ Java programming language primitive type - <code>short</code>.
+ JNI type <code>jshort</code>.
+ </constant>
+ <constant id="JVMTI_TYPE_JINT" num="104">
+ Java programming language primitive type - <code>int</code>.
+ JNI type <datalink id="jint"></datalink>.
+ </constant>
+ <constant id="JVMTI_TYPE_JLONG" num="105">
+ Java programming language primitive type - <code>long</code>.
+ JNI type <datalink id="jlong"></datalink>.
+ </constant>
+ <constant id="JVMTI_TYPE_JFLOAT" num="106">
+ Java programming language primitive type - <code>float</code>.
+ JNI type <datalink id="jfloat"></datalink>.
+ </constant>
+ <constant id="JVMTI_TYPE_JDOUBLE" num="107">
+ Java programming language primitive type - <code>double</code>.
+ JNI type <datalink id="jdouble"></datalink>.
+ </constant>
+ <constant id="JVMTI_TYPE_JBOOLEAN" num="108">
+ Java programming language primitive type - <code>boolean</code>.
+ JNI type <datalink id="jboolean"></datalink>.
+ </constant>
+ <constant id="JVMTI_TYPE_JOBJECT" num="109">
+ Java programming language object type - <code>java.lang.Object</code>.
+ JNI type <datalink id="jobject"></datalink>.
+ Returned values are JNI local references and must be managed.
+ </constant>
+ <constant id="JVMTI_TYPE_JTHREAD" num="110">
+ Java programming language object type - <code>java.lang.Thread</code>.
+ <jvmti/> type <datalink id="jthread"></datalink>.
+ Returned values are JNI local references and must be managed.
+ </constant>
+ <constant id="JVMTI_TYPE_JCLASS" num="111">
+ Java programming language object type - <code>java.lang.Class</code>.
+ JNI type <datalink id="jclass"></datalink>.
+ Returned values are JNI local references and must be managed.
+ </constant>
+ <constant id="JVMTI_TYPE_JVALUE" num="112">
+ Union of all Java programming language primitive and object types -
+ JNI type <datalink id="jvalue"></datalink>.
+ Returned values which represent object types are JNI local references and must be managed.
+ </constant>
+ <constant id="JVMTI_TYPE_JFIELDID" num="113">
+ Java programming language field identifier -
+ JNI type <datalink id="jfieldID"></datalink>.
+ </constant>
+ <constant id="JVMTI_TYPE_JMETHODID" num="114">
+ Java programming language method identifier -
+ JNI type <datalink id="jmethodID"></datalink>.
+ </constant>
+ <constant id="JVMTI_TYPE_CCHAR" num="115">
+ C programming language type - <code>char</code>.
+ </constant>
+ <constant id="JVMTI_TYPE_CVOID" num="116">
+ C programming language type - <code>void</code>.
+ </constant>
+ <constant id="JVMTI_TYPE_JNIENV" num="117">
+ JNI environment - <code>JNIEnv</code>.
+ Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type.
+ </constant>
+ </constants>
+
+ <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum">
+ <constant id="JVMTI_KIND_IN" num="91">
+ Ingoing argument - <code>foo</code>.
+ </constant>
+ <constant id="JVMTI_KIND_IN_PTR" num="92">
+ Ingoing pointer argument - <code>const foo*</code>.
+ </constant>
+ <constant id="JVMTI_KIND_IN_BUF" num="93">
+ Ingoing array argument - <code>const foo*</code>.
+ </constant>
+ <constant id="JVMTI_KIND_ALLOC_BUF" num="94">
+ Outgoing allocated array argument - <code>foo**</code>.
+ Free with <code>Deallocate</code>.
+ </constant>
+ <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95">
+ Outgoing allocated array of allocated arrays argument - <code>foo***</code>.
+ Free with <code>Deallocate</code>.
+ </constant>
+ <constant id="JVMTI_KIND_OUT" num="96">
+ Outgoing argument - <code>foo*</code>.
+ </constant>
+ <constant id="JVMTI_KIND_OUT_BUF" num="97">
+ Outgoing array argument (pre-allocated by agent) - <code>foo*</code>.
+ Do not <code>Deallocate</code>.
+ </constant>
+ </constants>
+
+ </intro>
+
+ <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info">
+ <field id="name">
+ <allocfieldbuf><char/></allocfieldbuf>
+ <description>
+ The parameter name, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string
+ </description>
+ </field>
+ <field id="kind">
+ <enum>jvmtiParamKind</enum>
+ <description>
+ The kind of the parameter - type modifiers
+ </description>
+ </field>
+ <field id="base_type">
+ <enum>jvmtiParamTypes</enum>
+ <description>
+ The base type of the parameter - modified by <code>kind</code>
+ </description>
+ </field>
+ <field id="null_ok">
+ <jboolean/>
+ <description>
+ Is a <code>NULL</code> argument permitted? Applies only to pointer and object types.
+ </description>
+ </field>
+ </typedef>
+
+ <callback id="jvmtiExtensionFunction">
+ <enum>jvmtiError</enum>
+ <synopsis>Extension Function</synopsis>
+ <description>
+ This is the implementation-specific extension function.
+ </description>
+ <parameters>
+ <param id="jvmti_env">
+ <outptr>
+ <struct>jvmtiEnv</struct>
+ </outptr>
+ <description>
+ The <jvmti/> environment is the only fixed parameter for extension functions.
+ </description>
+ </param>
+ <param id="...">
+ <varargs/>
+ <description>
+ The extension function-specific parameters
+ </description>
+ </param>
+ </parameters>
+ </callback>
+
+ <function id="GetExtensionFunctions" phase="onload" num="124">
+ <synopsis>Get Extension Functions</synopsis>
+
+ <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info">
+ <field id="func">
+ <ptrtype>
+ <struct>jvmtiExtensionFunction</struct>
+ </ptrtype>
+ <description>
+ The actual function to call
+ </description>
+ </field>
+ <field id="id">
+ <allocfieldbuf><char/></allocfieldbuf>
+ <description>
+ The identifier for the extension function, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ Uses package name conventions.
+ For example, <code>com.sun.hotspot.bar</code>
+ </description>
+ </field>
+ <field id="short_description">
+ <allocfieldbuf><char/></allocfieldbuf>
+ <description>
+ A one sentence description of the function, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </field>
+ <field id="param_count">
+ <jint/>
+ <description>
+ The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
+ </description>
+ </field>
+ <field id="params">
+ <allocfieldbuf outcount="param_count">
+ <struct>jvmtiParamInfo</struct>
+ </allocfieldbuf>
+ <description>
+ Array of
+ <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
+ parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
+ </description>
+ </field>
+ <field id="error_count">
+ <jint/>
+ <description>
+ The number of possible error returns (excluding universal errors)
+ </description>
+ </field>
+ <field id="errors">
+ <allocfieldbuf outcount="error_count">
+ <enum>jvmtiError</enum>
+ </allocfieldbuf>
+ <description>
+ Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
+ possible errors
+ </description>
+ </field>
+ </typedef>
+
+ <description>
+ Returns the set of extension functions.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="extension_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of extension functions
+ </description>
+ </param>
+ <param id="extensions">
+ <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf>
+ <description>
+ Returns an array of extension function info, one per function
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetExtensionEvents" phase="onload" num="125">
+ <synopsis>Get Extension Events</synopsis>
+
+ <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info">
+ <field id="extension_event_index">
+ <jint/>
+ <description>
+ The identifying index of the event
+ </description>
+ </field>
+ <field id="id">
+ <allocfieldbuf><char/></allocfieldbuf>
+ <description>
+ The identifier for the extension event, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ Uses package name conventions.
+ For example, <code>com.sun.hotspot.bar</code>
+ </description>
+ </field>
+ <field id="short_description">
+ <allocfieldbuf><char/></allocfieldbuf>
+ <description>
+ A one sentence description of the event, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </field>
+ <field id="param_count">
+ <jint/>
+ <description>
+ The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
+ </description>
+ </field>
+ <field id="params">
+ <allocfieldbuf outcount="param_count">
+ <struct>jvmtiParamInfo</struct>
+ </allocfieldbuf>
+ <description>
+ Array of
+ <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink>
+ parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
+ </description>
+ </field>
+ </typedef>
+
+ <description>
+ Returns the set of extension events.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="extension_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of extension events
+ </description>
+ </param>
+ <param id="extensions">
+ <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf>
+ <description>
+ Returns an array of extension event info, one per event
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <callback id="jvmtiExtensionEvent">
+ <void/>
+ <synopsis>Extension Event</synopsis>
+ <description>
+ This is the implementation-specific event.
+ The event handler is set with
+ <functionlink id="SetExtensionEventCallback"/>.
+ <p/>
+ Event handlers for extension events must be declared varargs to match this definition.
+ Failure to do so could result in calling convention mismatch and undefined behavior
+ on some platforms.
+ <p/>
+ For example, if the <code>jvmtiParamInfo</code>
+ returned by <functionlink id="GetExtensionEvents"/> indicates that
+ there is a <code>jint</code> parameter, the event handler should be
+ declared:
+<example>
+ void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...)
+</example>
+ Note the terminal "<code>...</code>" which indicates varargs.
+ </description>
+ <parameters>
+ <param id="jvmti_env">
+ <outptr>
+ <struct>jvmtiEnv</struct>
+ </outptr>
+ <description>
+ The <jvmti/> environment is the only fixed parameter for extension events.
+ </description>
+ </param>
+ <param id="...">
+ <varargs/>
+ <description>
+ The extension event-specific parameters
+ </description>
+ </param>
+ </parameters>
+ </callback>
+
+ <function id="SetExtensionEventCallback" phase="onload" num="126">
+ <synopsis>Set Extension Event Callback</synopsis>
+
+ <description>
+ Sets the callback function for an extension event and
+ enables the event. Or, if the callback is <code>NULL</code>, disables
+ the event. Note that unlike standard events, setting
+ the callback and enabling the event are a single operation.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="extension_event_index">
+ <jint/>
+ <description>
+ Identifies which callback to set.
+ This index is the
+ <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink>
+ field of
+ <datalink id="jvmtiExtensionEventInfo"/>.
+ </description>
+ </param>
+ <param id="callback">
+ <ptrtype>
+ <struct>jvmtiExtensionEvent</struct>
+ <nullok>disable the event</nullok>
+ </ptrtype>
+ <description>
+ If <code>callback</code> is non-<code>NULL</code>,
+ set <code>callback</code> to be the event callback function
+ and enable the event.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
+ <paramlink id="extension_event_index"/> is not an
+ <fieldlink id="extension_event_index"
+ struct="jvmtiExtensionEventInfo"/>
+ returned by
+ <functionlink id="GetExtensionEvents"/>
+ </error>
+ </errors>
+ </function>
+
+ </category>
+
+ <category id="capability" label="Capability">
+
+ <intro>
+ The capabilities functions allow you to change the
+ functionality available to <jvmti/>--that is,
+ which <jvmti/>
+ functions can be called, what events can be generated,
+ and what functionality these events and functions can
+ provide.
+ <p/>
+ The "Capabilities" section of each function and event describe which
+ capabilities, if any, they are associated with. "Required Functionality"
+ means it is available for use and no capabilities must be added to use it.
+ "Optional Functionality" means the agent must possess the capability
+ before it can be used.
+ To possess a capability, the agent must
+ <functionlink id="AddCapabilities">add the capability</functionlink>.
+ "Optional Features" describe capabilities which,
+ if added, extend the feature set.
+ <p/>
+ The potentially available capabilities of each <jvmti/> implementation are different.
+ Depending on the implementation, a capability:
+ <ul>
+ <li>may never be added</li>
+ <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li>
+ <li>may be added only during the <code>OnLoad</code> phase</li>
+ <li>may be possessed by only one environment at a time</li>
+ <li>may be possessed by only one environment at a time,
+ and only during the <code>OnLoad</code> phase</li>
+ <li>and so on ...</li>
+ </ul>
+ Frequently, the addition of a capability may incur a cost in execution speed, start up
+ time, and/or memory footprint. Note that the overhead of using a capability
+ is completely different than the overhead of possessing a capability.
+ Take single stepping as an example. When single stepping is on (that
+ is, when the event is enabled and thus actively sending events)
+ the overhead of sending and processing an event
+ on each instruction is huge in any implementation.
+ However, the overhead of possessing the capability may be small or large,
+ depending on the implementation. Also, when and if a capability is potentially
+ available depends on the implementation. Some examples:
+ <ul>
+ <li>One VM might perform all execution by compiling bytecodes into
+ native code and be unable to generate single step instructions.
+ In this implementation the capability can not be added.</li>
+ <li>Another VM may be able to switch execution to a single stepping
+ interpreter at any time. In this implementation, having the capability has no
+ overhead and could be added at any time.</li>
+ <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted
+ execution engine at start up, but be unable to switch between them.
+ In this implementation the capability would need to be added
+ during the <code>OnLoad</code> phase (before bytecode
+ execution begins) and would have a large impact on execution speed
+ even if single stepping was never used.</li>
+ <li>Still another VM might be able to add an "is single stepping on" check
+ into compiled bytecodes or a generated interpreter. Again in this implementation
+ the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test
+ and branch on each instruction) would be considerably less.</li>
+ </ul>
+ <p/>
+ Each <jvmti/> <internallink id="environments">environment</internallink>
+ has its own set of capabilities.
+ Initially, that set is empty.
+ Any desired capability must be added.
+ If possible, capabilities should be added during the <code>OnLoad</code> phase. For most
+ virtual machines certain capabilities require special set up for
+ the virtual machine and this set up must happen
+ during the <code>OnLoad</code> phase, before the virtual machine begins execution.
+ Once a capability is added, it can
+ only be removed if explicitly relinquished by the environment.
+ <p/>
+ The agent can,
+ <functionlink id="GetPotentialCapabilities">determine what
+ capabilities this VM can potentially provide</functionlink>,
+ <functionlink id="AddCapabilities">add the capabilities
+ to be used</functionlink>,
+ <functionlink id="RelinquishCapabilities">release capabilities
+ which are no longer needed</functionlink>, and
+ <functionlink id="GetCapabilities">examine the currently available
+ capabilities</functionlink>.
+ </intro>
+
+ <intro id="capabilityExamples" label="Capability Examples">
+ For example, a freshly started agent (in the <code>OnLoad</code> function)
+ wants to enable all possible capabilities.
+ Note that, in general, this is not advisable as the agent may suffer
+ a performance penalty for functionality it is not using.
+ The code might look like this in C:
+ <example>
+ jvmtiCapabilities capa;
+ jvmtiError err;
+
+ err = (*jvmti)->GetPotentialCapabilities(jvmti, &capa);
+ if (err == JVMTI_ERROR_NONE) {
+ err = (*jvmti)->AddCapabilities(jvmti, &capa);
+ </example>
+ For example, if an agent wants to check if it can get
+ the bytecodes of a method (that is, it wants to check
+ if it previously added this capability and has not
+ relinquished it), the code might
+ look like this in C:
+ <example>
+ jvmtiCapabilities capa;
+ jvmtiError err;
+
+ err = (*jvmti)->GetCapabilities(jvmti, &capa);
+ if (err == JVMTI_ERROR_NONE) {
+ if (capa.can_get_bytecodes) { ... } }
+ </example>
+ </intro>
+
+ <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure">
+ <description>
+ The functions in this category use this capabilities structure
+ which contains boolean flags corresponding to each capability:
+ </description>
+ <capabilityfield id="can_tag_objects">
+ <description>
+ Can set and get tags, as described in the
+ <internallink id="Heap">Heap category</internallink>.
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_field_modification_events">
+ <description>
+ Can set watchpoints on field modification -
+ <functionlink id="SetFieldModificationWatch"></functionlink>
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_field_access_events">
+ <description>
+ Can set watchpoints on field access -
+ <functionlink id="SetFieldAccessWatch"></functionlink>
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_get_bytecodes">
+ <description>
+ Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink>
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_get_synthetic_attribute">
+ <description>
+ Can test if a field or method is synthetic -
+ <functionlink id="IsFieldSynthetic"></functionlink> and
+ <functionlink id="IsMethodSynthetic"></functionlink>
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_get_owned_monitor_info">
+ <description>
+ Can get information about ownership of monitors -
+ <functionlink id="GetOwnedMonitorInfo"></functionlink>
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_get_current_contended_monitor">
+ <description>
+ Can <functionlink id="GetCurrentContendedMonitor"></functionlink>
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_get_monitor_info">
+ <description>
+ Can <functionlink id="GetObjectMonitorUsage"></functionlink>
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_pop_frame">
+ <description>
+ Can pop frames off the stack - <functionlink id="PopFrame"></functionlink>
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_redefine_classes">
+ <description>
+ Can redefine classes with <functionlink id="RedefineClasses"/>.
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_signal_thread">
+ <description>
+ Can send stop or interrupt to threads
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_get_source_file_name">
+ <description>
+ Can get the source file name of a class
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_get_line_numbers">
+ <description>
+ Can get the line number table of a method
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_get_source_debug_extension">
+ <description>
+ Can get the source debug extension of a class
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_access_local_variables">
+ <description>
+ Can set and get local variables
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_maintain_original_method_order">
+ <description>
+ Can return methods in the order they occur in the class file
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_single_step_events">
+ <description>
+ Can get <eventlink id="SingleStep">single step</eventlink> events
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_exception_events">
+ <description>
+ Can get <eventlink id="Exception">exception thrown</eventlink> and
+ <eventlink id="ExceptionCatch">exception catch</eventlink> events
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_frame_pop_events">
+ <description>
+ Can <functionlink id="NotifyFramePop">set</functionlink> and thus get
+ <eventlink id="FramePop"></eventlink> events
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_breakpoint_events">
+ <description>
+ Can <functionlink id="SetBreakpoint">set</functionlink> and thus get
+ <eventlink id="Breakpoint"></eventlink> events
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_suspend">
+ <description>
+ Can suspend and resume threads
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_redefine_any_class">
+ <description>
+ Can modify (retransform or redefine) any non-primitive non-array class.
+ See <functionlink id="IsModifiableClass"/>.
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_get_current_thread_cpu_time">
+ <description>
+ Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink>
+ current thread CPU time
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_get_thread_cpu_time">
+ <description>
+ Can <functionlink id="GetThreadCpuTime">get</functionlink>
+ thread CPU time
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_method_entry_events"
+ disp1="can_generate" disp2="_method_entry_events"
+ >
+ <description>
+ Can generate method entry events on entering a method
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_method_exit_events"
+ disp1="can_generate" disp2="_method_exit_events"
+ >
+ <description>
+ Can generate method exit events on leaving a method
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_all_class_hook_events"
+ disp1="can_generate" disp2="_all_class_hook_events"
+ >
+ <description>
+ Can generate ClassFileLoadHook events for every loaded class.
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_compiled_method_load_events"
+ disp1="can_generate" disp2="_compiled_method_load_events"
+ >
+ <description>
+ Can generate events when a method is compiled or unloaded
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_monitor_events"
+ disp1="can_generate" disp2="_monitor_events"
+ >
+ <description>
+ Can generate events on monitor activity
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_vm_object_alloc_events"
+ disp1="can_generate" disp2="_vm_object_alloc_events"
+ >
+ <description>
+ Can generate events on VM allocation of an object
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_native_method_bind_events"
+ disp1="can_generate" disp2="_native_method_bind_events"
+ >
+ <description>
+ Can generate events when a native method is bound to its
+ implementation
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_garbage_collection_events"
+ disp1="can_generate" disp2="_garbage_collection_events"
+ >
+ <description>
+ Can generate events when garbage collection begins or ends
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_object_free_events"
+ disp1="can_generate" disp2="_object_free_events"
+ >
+ <description>
+ Can generate events when the garbage collector frees an object
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_force_early_return" since="1.1">
+ <description>
+ Can return early from a method, as described in the
+ <internallink id="ForceEarlyReturn">Force Early Return category</internallink>.
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1">
+ <description>
+ Can get information about owned monitors with stack depth -
+ <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink>
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_get_constant_pool" since="1.1">
+ <description>
+ Can get the constant pool of a class -
+ <functionlink id="GetConstantPool"></functionlink>
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_set_native_method_prefix" since="1.1">
+ <description>
+ Can set prefix to be applied when native method cannot be resolved -
+ <functionlink id="SetNativeMethodPrefix"/> and
+ <functionlink id="SetNativeMethodPrefixes"/>
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_retransform_classes" since="1.1">
+ <description>
+ Can retransform classes with <functionlink id="RetransformClasses"/>.
+ In addition to the restrictions imposed by the specific
+ implementation on this capability (see the
+ <internallink id="capability">Capability</internallink> section),
+ this capability must be set before the
+ <eventlink id="ClassFileLoadHook"/> event is enabled for the
+ first time in this environment.
+ An environment that possesses this capability at the time that
+ <code>ClassFileLoadHook</code> is enabled for the first time is
+ said to be <i>retransformation capable</i>.
+ An environment that does not possess this capability at the time that
+ <code>ClassFileLoadHook</code> is enabled for the first time is
+ said to be <i>retransformation incapable</i>.
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_retransform_any_class" since="1.1">
+ <description>
+ <functionlink id="RetransformClasses"/> can be called on any class
+ (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
+ must also be set)
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1">
+ <description>
+ Can generate events when the VM is unable to allocate memory from
+ the <tm>Java</tm> platform heap.
+ See <eventlink id="ResourceExhausted"/>.
+ </description>
+ </capabilityfield>
+ <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1">
+ <description>
+ Can generate events when the VM is unable to create a thread.
+ See <eventlink id="ResourceExhausted"/>.
+ </description>
+ </capabilityfield>
+ </capabilitiestypedef>
+
+ <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
+ <synopsis>Get Potential Capabilities</synopsis>
+ <description>
+ Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
+ features that can potentially be possessed by this environment
+ at this time.
+ The returned capabilities differ from the complete set of capabilities
+ implemented by the VM in two cases: another environment possesses
+ capabilities that can only be possessed by one environment, or the
+ current <functionlink id="GetPhase">phase</functionlink> is live,
+ and certain capabilities can only be added during the <code>OnLoad</code> phase.
+ The <functionlink id="AddCapabilities"></functionlink> function
+ may be used to set any or all or these capabilities.
+ Currently possessed capabilities are included.
+ <p/>
+ Typically this function is used in the <code>OnLoad</code> function.
+ Some virtual machines may allow a limited set of capabilities to be
+ added in the live phase.
+ In this case, the set of potentially available capabilities
+ will likely differ from the <code>OnLoad</code> phase set.
+ <p/>
+ See the
+ <internallink id="capabilityExamples">Capability Examples</internallink>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="capabilities_ptr">
+ <outptr><struct>jvmtiCapabilities</struct></outptr>
+ <description>
+ On return, points to the <jvmti/> capabilities that may be added.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <elide>
+ <function id="EstimateCostOfCapabilities" phase="onload" num="141">
+ <synopsis>Estimate Cost Of Capabilities</synopsis>
+ <description>
+ <issue>There is strong opposition to this function. The concern is
+ that it would be difficult or impossible to provide meaningful
+ numbers, as the amount of impact is conditional on many factors
+ that a single number could not represent. There is doubt that
+ conditional implementations would be used or are even a good idea.
+ The thought is that release documentation for the implementation
+ would be the best means of exposing this information.
+ Unless new arguments are presented, I intend to remove this
+ function in the next revision.
+ </issue>
+ <p/>
+ Return via the <paramlink id="time_impact_ptr"></paramlink> and
+ <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact
+ of adding the capabilities pointed to by
+ <paramlink id="capabilities_ptr"></paramlink>.
+ The returned estimates are in percentage of additional overhead, thus
+ a time impact of 100 mean the application might run
+ at half the speed.
+ The estimates are very rough approximations and are not guaranteed.
+ Note also, that the estimates are of the impact of having the
+ capability available--when and if it is used the impact may be
+ much greater.
+ Estimates can be for a single capability or for a set of
+ capabilities. Note that the costs are not necessarily additive,
+ adding support for one capability might make another available
+ for free or conversely having two capabilities at once may
+ have multiplicative impact.
+ Estimates are relative to the current set of capabilities -
+ that is, how much more impact given the currently possessed capabilities.
+ <p/>
+ Typically this function is used in the OnLoad function,
+ some virtual machines may allow a limited set of capabilities to be
+ added in the live phase.
+ In this case, the set of potentially available capabilities
+ will likely differ from the OnLoad phase set.
+ <p/>
+ See the
+ <internallink id="capabilityExamples">Capability Examples</internallink>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="capabilities_ptr">
+ <inptr><struct>jvmtiCapabilities</struct></inptr>
+ <description>
+ points to the <jvmti/> capabilities to evaluate.
+ </description>
+ </param>
+ <param id="time_impact_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the estimated percentage increase in
+ run time if this capability was added.
+ </description>
+ </param>
+ <param id="space_impact_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the estimated percentage increase in
+ memory space used if this capability was added.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_NOT_AVAILABLE">
+ The desired capabilities are not even potentially available.
+ </error>
+ </errors>
+ </function>
+ </elide>
+
+ <function id="AddCapabilities" jkernel="yes" phase="onload" num="142">
+ <synopsis>Add Capabilities</synopsis>
+ <description>
+ Set new capabilities by adding the capabilities
+ whose values are set to one (<code>1</code>) in
+ <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
+ All previous capabilities are retained.
+ Typically this function is used in the <code>OnLoad</code> function.
+ Some virtual machines may allow a limited set of capabilities to be
+ added in the live phase.
+ <p/>
+ See the
+ <internallink id="capabilityExamples">Capability Examples</internallink>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="capabilities_ptr">
+ <inptr><struct>jvmtiCapabilities</struct></inptr>
+ <description>
+ Points to the <jvmti/> capabilities to add.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_NOT_AVAILABLE">
+ The desired capabilities are not even potentially available.
+ </error>
+ </errors>
+ </function>
+
+
+ <function id="RelinquishCapabilities" phase="onload" num="143">
+ <synopsis>Relinquish Capabilities</synopsis>
+ <description>
+ Relinquish the capabilities
+ whose values are set to one (<code>1</code>) in
+ <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
+ Some implementations may allow only one environment to have a capability
+ (see the <internallink id="capability">capability introduction</internallink>).
+ This function releases capabilities
+ so that they may be used by other agents.
+ All other capabilities are retained.
+ The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>.
+ Attempting to relinquish a capability that the agent does not possess is not an error.
+ <issue>
+ It is possible for the agent to be actively using capabilities
+ which are being relinquished. For example, a thread is currently
+ suspended and can_suspend is being relinquished or an event is currently
+ enabled and can_generate_whatever is being relinquished.
+ There are three possible ways we could spec this:
+ <ul>
+ <li>relinquish automatically releases them</li>
+ <li>relinquish checks and returns some error code if held</li>
+ <li>it is the agent's responsibility and it is not checked</li>
+ </ul>
+ One of these should be chosen.
+ </issue>
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="capabilities_ptr">
+ <inptr><struct>jvmtiCapabilities</struct></inptr>
+ <description>
+ Points to the <jvmti/> capabilities to relinquish.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+
+
+ <function id="GetCapabilities" jkernel="yes" phase="any" num="89">
+ <synopsis>Get Capabilities</synopsis>
+ <description>
+ Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/>
+ features which this environment currently possesses.
+ Each possessed capability is indicated by a one (<code>1</code>) in the
+ corresponding field of the <internallink id="jvmtiCapabilities">capabilities
+ structure</internallink>.
+ An environment does not possess a capability unless it has been successfully added with
+ <functionlink id="AddCapabilities"/>.
+ An environment only loses possession of a capability if it has been relinquished with
+ <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result
+ of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which
+ have been made.
+ <p/>
+ See the
+ <internallink id="capabilityExamples">Capability Examples</internallink>.
+ </description>
+ <origin>jvmdiClone</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="capabilities_ptr">
+ <outptr><struct>jvmtiCapabilities</struct></outptr>
+ <description>
+ On return, points to the <jvmti/> capabilities.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ </category>
+
+
+ <category id="timers" label="Timers">
+
+ <intro>
+ These functions provide timing information.
+ The resolution at which the time is updated is not specified.
+ They provides nanosecond precision, but not necessarily nanosecond accuracy.
+ Details about the timers, such as their maximum values, can be accessed with
+ the timer information functions.
+ </intro>
+
+ <typedef id="jvmtiTimerInfo" label="Timer Info">
+ <description>
+ The information function for each timer returns this data structure.
+ </description>
+ <field id="max_value">
+ <jlong/>
+ <description>
+ The maximum value the timer can reach.
+ After this value is reached the timer wraps back to zero.
+ This is an unsigned value. If tested or printed as a jlong (signed value)
+ it may appear to be a negative number.
+ </description>
+ </field>
+ <field id="may_skip_forward">
+ <jboolean/>
+ <description>
+ If true, the timer can be externally adjusted and as a result skip forward.
+ If false, the timer value will never increase faster than real time.
+ </description>
+ </field>
+ <field id="may_skip_backward">
+ <jboolean/>
+ <description>
+ If true, the timer can be externally adjusted and as a result skip backward.
+ If false, the timer value will be monotonically increasing.
+ </description>
+ </field>
+ <field id="kind">
+ <enum>jvmtiTimerKind</enum>
+ <description>
+ The kind of timer.
+ On a platform that does not distinguish between user and system time, <datalink
+ id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink>
+ is returned.
+ </description>
+ </field>
+ <field id="reserved1">
+ <jlong/>
+ <description>
+ Reserved for future use.
+ </description>
+ </field>
+ <field id="reserved2">
+ <jlong/>
+ <description>
+ Reserved for future use.
+ </description>
+ </field>
+ </typedef>
+
+ <intro>
+ Where the timer kind is --
+
+ <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum">
+ <constant id="JVMTI_TIMER_USER_CPU" num="30">
+ CPU time that a thread is in user mode.
+ </constant>
+ <constant id="JVMTI_TIMER_TOTAL_CPU" num="31">
+ CPU time that a thread is in user or system mode.
+ </constant>
+ <constant id="JVMTI_TIMER_ELAPSED" num="32">
+ Elapsed time.
+ </constant>
+ </constants>
+ </intro>
+
+ <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe" impl="innative notrace" phase="start" num="134">
+ <synopsis>Get Current Thread CPU Timer Information</synopsis>
+ <description>
+ Get information about the
+ <functionlink id="GetCurrentThreadCpuTime"/> timer.
+ The fields of the <datalink id="jvmtiTimerInfo"/> structure
+ are filled in with details about the timer.
+ This information is specific to the platform and the implementation of
+ <functionlink id="GetCurrentThreadCpuTime"/> and thus
+ does not vary by thread nor does it vary
+ during a particular invocation of the VM.
+ <p/>
+ Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
+ and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
+ returned by <code>GetCurrentThreadCpuTimerInfo</code>
+ and <functionlink id="GetThreadCpuTimerInfo"/>
+ may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_get_current_thread_cpu_time">
+ Can get current thread CPU time.
+ </required>
+ </capabilities>
+ <parameters>
+ <param id="info_ptr">
+ <outptr><struct>jvmtiTimerInfo</struct></outptr>
+ <description>
+ On return, filled with information describing the time
+ returned by <functionlink id="GetCurrentThreadCpuTime"/>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135">
+ <synopsis>Get Current Thread CPU Time</synopsis>
+ <description>
+ Return the CPU time utilized by the current thread.
+ <p/>
+ Note that the <functionlink id="GetThreadCpuTime"/>
+ function provides CPU time for any thread, including
+ the current thread. <code>GetCurrentThreadCpuTime</code>
+ exists to support platforms which cannot
+ supply CPU time for threads other than the current
+ thread or which have more accurate information for
+ the current thread (see
+ <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs
+ <functionlink id="GetThreadCpuTimerInfo"/>).
+ On many platforms this call will be equivalent to:
+<example>
+ GetThreadCpuTime(env, NULL, nanos_ptr)
+</example>
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_get_current_thread_cpu_time">
+ Can get current thread CPU time.
+ <p/>
+ If this capability is enabled after threads have started,
+ the implementation may choose any time up
+ to and including the time that the capability is enabled
+ as the point where CPU time collection starts.
+ <p/>
+ This capability must be potentially available on any
+ platform where
+ <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink>
+ is potentially available.
+ </required>
+ </capabilities>
+ <parameters>
+ <param id="nanos_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ On return, points to the CPU time used by this thread
+ in nanoseconds.
+ This is an unsigned value. If tested or printed as a jlong (signed value)
+ it may appear to be a negative number.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetThreadCpuTimerInfo" num="136">
+ <synopsis>Get Thread CPU Timer Information</synopsis>
+ <description>
+ Get information about the
+ <functionlink id="GetThreadCpuTime"/> timer.
+ The fields of the <datalink id="jvmtiTimerInfo"/> structure
+ are filled in with details about the timer.
+ This information is specific to the platform and the implementation of
+ <functionlink id="GetThreadCpuTime"/> and thus
+ does not vary by thread nor does it vary
+ during a particular invocation of the VM.
+ <p/>
+ Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
+ and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
+ returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/>
+ and <code>GetThreadCpuTimerInfo</code>
+ may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_get_thread_cpu_time">
+ Can get thread CPU time.
+ </required>
+ </capabilities>
+ <parameters>
+ <param id="info_ptr">
+ <outptr><struct>jvmtiTimerInfo</struct></outptr>
+ <description>
+ On return, filled with information describing the time
+ returned by <functionlink id="GetThreadCpuTime"/>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetThreadCpuTime" num="137">
+ <synopsis>Get Thread CPU Time</synopsis>
+ <description>
+ Return the CPU time utilized by the specified thread.
+ <p/>
+ Get information about this timer with
+ <functionlink id="GetThreadCpuTimerInfo"/>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_get_thread_cpu_time">
+ Can get thread CPU time.
+ <p/>
+ If this capability is enabled after threads have started,
+ the implementation may choose any time up
+ to and including the time that the capability is enabled
+ as the point where CPU time collection starts.
+ </required>
+ </capabilities>
+ <parameters>
+ <param id="thread">
+ <jthread null="current"/>
+ <description>
+ The thread to query.
+ </description>
+ </param>
+ <param id="nanos_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ On return, points to the CPU time used by the specified thread
+ in nanoseconds.
+ This is an unsigned value. If tested or printed as a jlong (signed value)
+ it may appear to be a negative number.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138">
+ <synopsis>Get Timer Information</synopsis>
+ <description>
+ Get information about the
+ <functionlink id="GetTime"/> timer.
+ The fields of the <datalink id="jvmtiTimerInfo"/> structure
+ are filled in with details about the timer.
+ This information will not change during a particular invocation of the VM.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="info_ptr">
+ <outptr><struct>jvmtiTimerInfo</struct></outptr>
+ <description>
+ On return, filled with information describing the time
+ returned by <functionlink id="GetTime"/>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetTime" phase="any" callbacksafe="safe" num="139">
+ <synopsis>Get Time</synopsis>
+ <description>
+ Return the current value of the system timer, in nanoseconds.
+ <p/>
+ The value returned represents nanoseconds since some fixed but
+ arbitrary time (perhaps in the future, so values may be
+ negative). This function provides nanosecond precision, but not
+ necessarily nanosecond accuracy. No guarantees are made about
+ how frequently values change.
+ <p/>
+ Get information about this timer with
+ <functionlink id="GetTimerInfo"/>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="nanos_ptr">
+ <outptr><jlong/></outptr>
+ <description>
+ On return, points to the time in nanoseconds.
+ This is an unsigned value. If tested or printed as a jlong (signed value)
+ it may appear to be a negative number.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetAvailableProcessors" phase="any" num="144">
+ <synopsis>Get Available Processors</synopsis>
+ <description>
+ Returns the number of processors available to the Java virtual machine.
+ <p/>
+ This value may change during a particular invocation of the virtual machine.
+ Applications that are sensitive to the number of available processors should
+ therefore occasionally poll this property.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="processor_count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the maximum number of processors available to the
+ virtual machine; never smaller than one.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ </category>
+
+
+ <category id="classLoaderSearch" label="Class Loader Search">
+
+ <intro>
+ These functions allow the agent to add to the locations that a class loader searches for a class.
+ This is useful for installing instrumentation under the correct class loader.
+ </intro>
+
+ <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149">
+ <synopsis>Add To Bootstrap Class Loader Search</synopsis>
+ <description>
+ This function can be used to cause instrumentation classes to be defined by the
+ bootstrap class loader. See
+ <vmspeclink id="ConstantPool.doc.html#79383"
+ name="Loading Using the Bootstrap Class Loader"
+ preposition="in"/>.
+ After the bootstrap
+ class loader unsuccessfully searches for a class, the specified platform-dependent
+ search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in
+ the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments,
+ the segments will be searched in the order that this function was called.
+ <p/>
+ In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent
+ search path segment to be searched after the bootstrap class loader unsuccessfully searches
+ for a class. The segment is typically a directory or JAR file.
+ <p/>
+ In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent
+ path to a <externallink id="http://java.sun.com/javase/6/docs/guide/jar/jar.html">
+ JAR file</externallink>. The agent should take care that the JAR file does not
+ contain any classes or resources other than those to be defined by the bootstrap
+ class loader for the purposes of instrumentation.
+ <p/>
+ The <vmspeclink/> specifies that a subsequent attempt to resolve a symbolic
+ reference that the Java virtual machine has previously unsuccessfully attempted
+ to resolve always fails with the same error that was thrown as a result of the
+ initial resolution attempt. Consequently, if the JAR file contains an entry
+ that corresponds to a class for which the Java virtual machine has
+ unsuccessfully attempted to resolve a reference, then subsequent attempts to
+ resolve that reference will fail with the same error as the initial attempt.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="segment">
+ <inbuf><char/></inbuf>
+ <description>
+ The platform-dependent search path segment, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
+ <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
+ existing JAR file is an invalid path.
+ </error>
+ </errors>
+ </function>
+
+ <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1">
+ <synopsis>Add To System Class Loader Search</synopsis>
+ <description>
+ This function can be used to cause instrumentation classes to be
+ defined by the system class loader. See
+ <vmspeclink id="ConstantPool.doc.html#79441"
+ name="Loading Using a User-defined Class Loader"
+ preposition="in"/>.
+ After the class loader unsuccessfully searches for a class, the specified platform-dependent search
+ path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the
+ <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the
+ segments will be searched in the order that this function was called.
+ <p/>
+ In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent
+ search path segment to be searched after the system class loader unsuccessfully searches
+ for a class. The segment is typically a directory or JAR file.
+ <p/>
+ In the live phase the <paramlink id="segment"/> is a platform-dependent path to a <externallink
+ id="http://java.sun.com/javase/6/docs/guide/jar/jar.html">JAR file</externallink> to be
+ searched after the system class loader unsuccessfully searches for a class. The agent should
+ take care that the JAR file does not contain any classes or resources other than those to be
+ defined by the system class loader for the purposes of instrumentation.
+ <p/>
+ In the live phase the system class loader supports adding a JAR file to be searched if
+ the system class loader implements a method name <code>appendToClassPathForInstrumentation</code>
+ which takes a single parameter of type <code>java.lang.String</code>. The method is not required
+ to have <code>public</code> access.
+ <p/>
+ The <vmspeclink/> specifies that a subsequent attempt to resolve a symbolic
+ reference that the Java virtual machine has previously unsuccessfully attempted
+ to resolve always fails with the same error that was thrown as a result of the
+ initial resolution attempt. Consequently, if the JAR file contains an entry
+ that corresponds to a class for which the Java virtual machine has
+ unsuccessfully attempted to resolve a reference, then subsequent attempts to
+ resolve that reference will fail with the same error as the initial attempt.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="segment">
+ <inbuf><char/></inbuf>
+ <description>
+ The platform-dependent search path segment, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
+ <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
+ existing JAR file is an invalid path.
+ </error>
+ <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED">
+ Operation not supported by the system class loader.
+ </error>
+ </errors>
+ </function>
+
+ </category>
+
+
+ <category id="props" label="System Properties">
+
+ <intro>
+ These functions get and set system properties.
+ </intro>
+
+ <function id="GetSystemProperties" phase="onload" num="130">
+ <synopsis>Get System Properties</synopsis>
+ <description>
+ The list of VM system property keys which may be used with
+ <functionlink id="GetSystemProperty"/> is returned.
+ It is strongly recommended that virtual machines provide the
+ following property keys:
+ <ul>
+ <li><code>java.vm.vendor</code></li>
+ <li><code>java.vm.version</code></li>
+ <li><code>java.vm.name</code></li>
+ <li><code>java.vm.info</code></li>
+ <li><code>java.library.path</code></li>
+ <li><code>java.class.path</code></li>
+ </ul>
+ Provides access to system properties defined by and used
+ by the VM.
+ Properties set on the command-line are included.
+ This allows getting and setting of these properties
+ before the VM even begins executing bytecodes.
+ Since this is a VM view of system properties, the set of available
+ properties will usually be different than that
+ in <code>java.lang.System.getProperties</code>.
+ JNI method invocation may be used to access
+ <code>java.lang.System.getProperties</code>.
+ <p/>
+ The set of properties may grow during execution.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="count_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the number of property keys returned.
+ </description>
+ </param>
+ <param id="property_ptr">
+ <allocallocbuf outcount="count_ptr"><char/></allocallocbuf>
+ <description>
+ On return, points to an array of property keys, encoded as
+ <internallink id="mUTF">modified UTF-8</internallink> strings.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetSystemProperty" phase="onload" num="131">
+ <synopsis>Get System Property</synopsis>
+ <description>
+ Return a VM system property value given the property key.
+ <p/>
+ The function <functionlink id="GetSystemProperties"/>
+ returns the set of property keys which may be used.
+ The properties which can be retrieved may grow during
+ execution.
+ <p/>
+ Since this is a VM view of system properties, the values
+ of properties may differ from that returned by
+ <code>java.lang.System.getProperty(String)</code>.
+ A typical VM might copy the values of the VM system
+ properties into the <code>Properties</code> held by
+ <code>java.lang.System</code> during the initialization
+ of that class. Thereafter any changes to the VM system
+ properties (with <functionlink id="SetSystemProperty"/>)
+ or the <code>java.lang.System</code> system properties
+ (with <code>java.lang.System.setProperty(String,String)</code>)
+ would cause the values to diverge.
+ JNI method invocation may be used to access
+ <code>java.lang.System.getProperty(String)</code>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="property">
+ <inbuf><char/></inbuf>
+ <description>
+ The key of the property to retrieve, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ <param id="value_ptr">
+ <allocbuf><char/></allocbuf>
+ <description>
+ On return, points to the property value, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_NOT_AVAILABLE">
+ This property is not available.
+ Use <functionlink id="GetSystemProperties"/> to find available properties.
+ </error>
+ </errors>
+ </function>
+
+ <function id="SetSystemProperty" phase="onloadOnly" num="132">
+ <synopsis>Set System Property</synopsis>
+ <description>
+ Set a VM system property value.
+ <p/>
+ The function <functionlink id="GetSystemProperties"/>
+ returns the set of property keys, some of these may be settable.
+ See <functionlink id="GetSystemProperty"/>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="property">
+ <inbuf><char/></inbuf>
+ <description>
+ The key of the property, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ <param id="value">
+ <inbuf>
+ <char/>
+ <nullok>
+ do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/>
+ if the property is not writeable
+ </nullok>
+ </inbuf>
+ <description>
+ The property value to set, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_NOT_AVAILABLE">
+ This property is not available or is not writeable.
+ </error>
+ </errors>
+ </function>
+
+ </category>
+
+ <category id="general" label="General">
+
+ <intro>
+ </intro>
+
+ <function id="GetPhase" jkernel="yes" phase="any" num="133">
+ <synopsis>Get Phase</synopsis>
+ <description>
+ Return the current phase of VM execution.
+ The phases proceed in sequence:
+ <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
+ <constant id="JVMTI_PHASE_ONLOAD" num="1">
+ <code>OnLoad</code> phase: while in the
+ <internallink id="onload"><code>Agent_OnLoad</code></internallink> function.
+ </constant>
+ <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
+ Primordial phase: between return from <code>Agent_OnLoad</code> and the
+ <code>VMStart</code> event.
+ </constant>
+ <constant id="JVMTI_PHASE_START" num="6">
+ Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event
+ is sent and until the <code>VMInit</code> event is sent.
+ </constant>
+ <constant id="JVMTI_PHASE_LIVE" num="4">
+ Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent
+ and until the <eventlink id="VMDeath"></eventlink> event returns.
+ </constant>
+ <constant id="JVMTI_PHASE_DEAD" num="8">
+ Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after
+ start-up failure.
+ </constant>
+ </constants>
+ In the case of start-up failure the VM will proceed directly to the dead
+ phase skipping intermediate phases and neither a <code>VMInit</code> nor
+ <code>VMDeath</code> event will be sent.
+ <p/>
+ Most <jvmti/> functions operate only in the live phase.
+ The following functions operate in either the <code>OnLoad</code> or live phases:
+ <functionphaselist phase="onload"/>
+ The following functions operate in only the <code>OnLoad</code> phase:
+ <functionphaselist phase="onloadOnly"/>
+ The following functions operate in the start or live phases:
+ <functionphaselist phase="start"/>
+ The following functions operate in any phase:
+ <functionphaselist phase="any"/>
+ JNI functions (except the Invocation API) must only be used in the start or live phases.
+ <p/>
+ Most <jvmti/> events are sent only in the live phase.
+ The following events operate in others phases:
+ <eventphaselist phase="start"/>
+ <eventphaselist phase="any"/>
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="phase_ptr">
+ <outptr><enum>jvmtiPhase</enum></outptr>
+ <description>
+ On return, points to the phase.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127">
+ <synopsis>Dispose Environment</synopsis>
+ <description>
+ Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code>
+ (see <internallink id="environments"><jvmti/> Environments</internallink>).
+ Dispose of any resources held by the environment.
+ <issue>
+ What resources are reclaimed? What is undone?
+ Breakpoints,watchpoints removed?
+ </issue>
+ Threads suspended by this environment are not resumed by this call,
+ this must be done explicitly by the agent.
+ Memory allocated by this environment via calls to <jvmti/> functions
+ is not released, this can be done explicitly by the agent
+ by calling <functionlink id="Deallocate"/>.
+ Raw monitors created by this environment are not destroyed,
+ this can be done explicitly by the agent
+ by calling <functionlink id="DestroyRawMonitor"/>.
+ The state of threads waiting on raw monitors created by this environment
+ are not affected.
+ <p/>
+ Any <functionlink id="SetNativeMethodPrefix">native method
+ prefixes</functionlink> for this environment will be unset;
+ the agent must remove any prefixed native methods before
+ dispose is called.
+ <p/>
+ Any <internallink id="capability">capabilities</internallink>
+ held by this environment are relinquished.
+ <p/>
+ Events enabled by this environment will no longer be sent, however
+ event handlers currently running will continue to run. Caution must
+ be exercised in the design of event handlers whose environment may
+ be disposed and thus become invalid during their execution.
+ <p/>
+ This environment may not be used after this call.
+ This call returns to the caller.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148">
+ <synopsis>Set Environment Local Storage</synopsis>
+ <description>
+ The VM stores a pointer value associated with each environment.
+ This pointer value is called <i>environment-local storage</i>.
+ This value is <code>NULL</code> unless set with this function.
+ Agents can allocate memory in which they store environment specific
+ information. By setting environment-local storage it can then be
+ accessed with
+ <functionlink id="GetEnvironmentLocalStorage"></functionlink>.
+ <p/>
+ Called by the agent to set the value of the <jvmti/>
+ environment-local storage. <jvmti/> supplies to the agent a pointer-size
+ environment-local storage that can be used to record per-environment
+ information.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="data">
+ <inbuf>
+ <void/>
+ <nullok>value is set to <code>NULL</code></nullok>
+ </inbuf>
+ <description>
+ The value to be entered into the environment-local storage.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147">
+ <synopsis>Get Environment Local Storage</synopsis>
+ <description>
+ Called by the agent to get the value of the <jvmti/> environment-local
+ storage.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="data_ptr">
+ <agentbuf><void/></agentbuf>
+ <description>
+ Pointer through which the value of the environment local
+ storage is returned.
+ If environment-local storage has not been set with
+ <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned
+ pointer is <code>NULL</code>.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetVersionNumber" jkernel="yes" phase="any" num="88">
+ <synopsis>Get Version Number</synopsis>
+ <description>
+ Return the <jvmti/> version via <code>version_ptr</code>.
+ The return value is the version identifier.
+ The version identifier includes major, minor and micro
+ version as well as the interface type.
+ <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits">
+ <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000">
+ Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI.
+ </constant>
+ <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000">
+ Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>.
+ </constant>
+ </constants>
+ <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits">
+ <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000">
+ Mask to extract interface type.
+ The value of the version returned by this function masked with
+ <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always
+ <code>JVMTI_VERSION_INTERFACE_JVMTI</code>
+ since this is a <jvmti/> function.
+ </constant>
+ <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000">
+ Mask to extract major version number.
+ </constant>
+ <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00">
+ Mask to extract minor version number.
+ </constant>
+ <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF">
+ Mask to extract micro version number.
+ </constant>
+ </constants>
+ <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits">
+ <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16">
+ Shift to extract major version number.
+ </constant>
+ <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8">
+ Shift to extract minor version number.
+ </constant>
+ <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0">
+ Shift to extract micro version number.
+ </constant>
+ </constants>
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="version_ptr">
+ <outptr><jint/></outptr>
+ <description>
+ On return, points to the <jvmti/> version.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+
+ <function id="GetErrorName" phase="any" num="128">
+ <synopsis>Get Error Name</synopsis>
+ <description>
+ Return the symbolic name for an
+ <internallink id="ErrorSection">error code</internallink>.
+ <p/>
+ For example
+ <code>GetErrorName(env, JVMTI_ERROR_NONE, &err_name)</code>
+ would return in <code>err_name</code> the string
+ <code>"JVMTI_ERROR_NONE"</code>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="error">
+ <enum>jvmtiError</enum>
+ <description>
+ The error code.
+ </description>
+ </param>
+ <param id="name_ptr">
+ <allocbuf><char/></allocbuf>
+ <description>
+ On return, points to the error name.
+ The name is encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string,
+ but is restricted to the ASCII subset.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="SetVerboseFlag" phase="any" num="150">
+ <synopsis>Set Verbose Flag</synopsis>
+ <description>
+ <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum">
+ <constant id="JVMTI_VERBOSE_OTHER" num="0">
+ Verbose output other than the below.
+ </constant>
+ <constant id="JVMTI_VERBOSE_GC" num="1">
+ Verbose garbage collector output, like that specified with <code>-verbose:gc</code>.
+ </constant>
+ <constant id="JVMTI_VERBOSE_CLASS" num="2">
+ Verbose class loading output, like that specified with <code>-verbose:class</code>.
+ </constant>
+ <constant id="JVMTI_VERBOSE_JNI" num="4">
+ Verbose JNI output, like that specified with <code>-verbose:jni</code>.
+ </constant>
+ </constants>
+ Control verbose output.
+ This is the output which typically is sent to <code>stderr</code>.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="flag">
+ <enum>jvmtiVerboseFlag</enum>
+ <description>
+ Which verbose flag to set.
+ </description>
+ </param>
+ <param id="value">
+ <jboolean/>
+ <description>
+ New value of the flag.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+
+ <function id="GetJLocationFormat" phase="any" num="129">
+ <synopsis>Get JLocation Format</synopsis>
+ <description>
+ Although the greatest functionality is achieved with location information
+ referencing the virtual machine bytecode index, the definition of
+ <code>jlocation</code> has intentionally been left unconstrained to allow VM
+ implementations that do not have this information.
+ <p/>
+ This function describes the representation of <code>jlocation</code> used in this VM.
+ If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>,
+ <code>jlocation</code>s can
+ be used as in indices into the array returned by
+ <functionlink id="GetBytecodes"></functionlink>.
+ <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum">
+ <constant id="JVMTI_JLOCATION_JVMBCI" num="1">
+ <code>jlocation</code> values represent virtual machine
+ bytecode indices--that is, offsets into the
+ virtual machine code for a method.
+ </constant>
+ <constant id="JVMTI_JLOCATION_MACHINEPC" num="2">
+ <code>jlocation</code> values represent native machine
+ program counter values.
+ </constant>
+ <constant id="JVMTI_JLOCATION_OTHER" num="0">
+ <code>jlocation</code> values have some other representation.
+ </constant>
+ </constants>
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="format_ptr">
+ <outptr><enum>jvmtiJlocationFormat</enum></outptr>
+ <description>
+ On return, points to the format identifier for <code>jlocation</code> values.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ </category>
+
+</functionsection>
+
+<errorsection label="Error Reference">
+ <intro>
+ Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
+ <p/>
+ It is the responsibility of the agent to call <jvmti/> functions with
+ valid parameters and in the proper context (calling thread is attached,
+ phase is correct, etc.).
+ Detecting some error conditions may be difficult, inefficient, or
+ impossible for an implementation.
+ The errors listed in
+ <internallink id="reqerrors">Function Specific Required Errors</internallink>
+ must be detected by the implementation.
+ All other errors represent the recommended response to the error
+ condition.
+ </intro>
+
+ <errorcategory id="universal-error" label="Universal Errors">
+ <intro>
+ The following errors may be returned by any function
+ </intro>
+
+ <errorid id="JVMTI_ERROR_NONE" num="0">
+ No error has occurred. This is the error code that is returned
+ on successful completion of the function.
+ </errorid>
+ <errorid id="JVMTI_ERROR_NULL_POINTER" num="100">
+ Pointer is unexpectedly <code>NULL</code>.
+ </errorid>
+ <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110">
+ The function attempted to allocate memory and no more memory was
+ available for allocation.
+ </errorid>
+ <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111">
+ The desired functionality has not been enabled in this virtual machine.
+ </errorid>
+ <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115">
+ The thread being used to call this function is not attached
+ to the virtual machine. Calls must be made from attached threads.
+ See <code>AttachCurrentThread</code> in the JNI invocation API.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116">
+ The <jvmti/> environment provided is no longer connected or is
+ not an environment.
+ </errorid>
+ <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112">
+ The desired functionality is not available in the current
+ <functionlink id="GetPhase">phase</functionlink>.
+ Always returned if the virtual machine has completed running.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INTERNAL" num="113">
+ An unexpected internal error has occurred.
+ </errorid>
+ </errorcategory>
+
+ <errorcategory id="reqerrors" label="Function Specific Required Errors">
+ <intro>
+ The following errors are returned by some <jvmti/> functions and must
+ be returned by the implementation when the condition occurs.
+ </intro>
+
+ <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12">
+ Invalid priority.
+ </errorid>
+ <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13">
+ Thread was not suspended.
+ </errorid>
+ <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14">
+ Thread already suspended.
+ </errorid>
+ <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15">
+ This operation requires the thread to be alive--that is,
+ it must be started and not yet have died.
+ </errorid>
+ <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22">
+ The class has been loaded but not yet prepared.
+ </errorid>
+ <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31">
+ There are no Java programming language or JNI stack frames at the specified depth.
+ </errorid>
+ <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32">
+ Information about the frame is not available (e.g. for native frames).
+ </errorid>
+ <errorid id="JVMTI_ERROR_DUPLICATE" num="40">
+ Item already set.
+ </errorid>
+ <errorid id="JVMTI_ERROR_NOT_FOUND" num="41">
+ Desired element (e.g. field or breakpoint) not found
+ </errorid>
+ <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51">
+ This thread doesn't own the raw monitor.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INTERRUPT" num="52">
+ The call has been interrupted before completion.
+ </errorid>
+ <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79">
+ The class cannot be modified.
+ </errorid>
+ <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98">
+ The functionality is not available in this virtual machine.
+ </errorid>
+ <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101">
+ The requested information is not available.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102">
+ The specified event type ID is not recognized.
+ </errorid>
+ <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104">
+ The requested information is not available for native method.
+ </errorid>
+ <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106">
+ The class loader does not support this operation.
+ </errorid>
+ </errorcategory>
+
+ <errorcategory id="function-specific-errors" label="Function Specific Agent Errors">
+ <intro>
+ The following errors are returned by some <jvmti/> functions.
+ They are returned in the event of invalid parameters passed by the
+ agent or usage in an invalid context.
+ An implementation is not required to detect these errors.
+ </intro>
+
+ <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10">
+ The passed thread is not a valid thread.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25">
+ Invalid field.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23">
+ Invalid method.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24">
+ Invalid location.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20">
+ Invalid object.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21">
+ Invalid class.
+ </errorid>
+ <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34">
+ The variable is not an appropriate type for the function used.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35">
+ Invalid slot.
+ </errorid>
+ <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99">
+ The capability being used is false in this environment.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11">
+ Thread group invalid.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50">
+ Invalid raw monitor.
+ </errorid>
+ <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103">
+ Illegal argument.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65">
+ The state of the thread has been modified, and is now inconsistent.
+ </errorid>
+ <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68">
+ A new class file has a version number not supported by this VM.
+ </errorid>
+ <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60">
+ A new class file is malformed (the VM would return a <code>ClassFormatError</code>).
+ </errorid>
+ <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61">
+ The new class file definitions would lead to a circular
+ definition (the VM would return a <code>ClassCircularityError</code>).
+ </errorid>
+ <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63">
+ A new class file would require adding a method.
+ </errorid>
+ <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64">
+ A new class version changes a field.
+ </errorid>
+ <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62">
+ The class bytes fail verification.
+ </errorid>
+ <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66">
+ A direct superclass is different for the new class
+ version, or the set of directly implemented
+ interfaces is different.
+ </errorid>
+ <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67">
+ A new class version does not declare a method
+ declared in the old class version.
+ </errorid>
+ <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69">
+ The class name defined in the new class file is
+ different from the name in the old class object.
+ </errorid>
+ <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70">
+ A new class version has different modifiers.
+ </errorid>
+ <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71">
+ A method in the new class version has different modifiers
+ than its counterpart in the old class version.
+ </errorid>
+ </errorcategory>
+</errorsection>
+
+<eventsection label="Events">
+ <intro label="Handling Events" id="eventIntro">
+ Agents can be informed of many events that occur in application
+ programs.
+ <p/>
+ To handle events, designate a set of callback functions with
+ <functionlink id="SetEventCallbacks"></functionlink>.
+ For each event the corresponding callback function will be
+ called.
+ Arguments to the callback function provide additional
+ information about the event.
+ <p/>
+ The callback function is usually called from within an application
+ thread. The <jvmti/> implementation does not
+ queue events in any way. This means
+ that event callback functions must be written
+ carefully. Here are some general guidelines. See
+ the individual event descriptions for further
+ suggestions.
+ <p/>
+ <ul>
+ <li>Any exception thrown during the execution of an event callback can
+ overwrite any current pending exception in the current application thread.
+ Care must be taken to preserve a pending exception
+ when an event callback makes a JNI call that might generate an exception.
+ </li>
+ <li>Event callback functions must be re-entrant. The <jvmti/> implementation does
+ not queue events. If an agent needs to process events one at a time, it
+ can use a raw monitor inside the
+ event callback functions to serialize event processing.
+ </li>
+ <li>Event callback functions that execute JNI's FindClass function to load
+ classes need to note that FindClass locates the class loader associated
+ with the current native method. For the purposes of class loading, an
+ event callback that includes a JNI environment as a parameter to the
+ callback will treated as if it is a native call, where the native method
+ is in the class of the event thread's current frame.
+ </li>
+ </ul>
+ <p/>
+ Some <jvmti/> events identify objects with JNI references.
+ All references
+ in <jvmti/> events are JNI local references and will become invalid
+ after the event callback returns.
+ Unless stated otherwise, memory referenced by pointers sent in event
+ callbacks may not be referenced after the event callback returns.
+ <p/>
+ Except where stated otherwise, events are delivered on the thread
+ that caused the event.
+ Events are sent at the time they occur.
+ The specification for each event includes the set of
+ <functionlink id="GetPhase">phases</functionlink> in which it can be sent;
+ if an event triggering activity occurs during another phase, no event
+ is sent.
+ <p/>
+ A thread that generates an event does not change its execution status
+ (for example, the event does not cause the thread to be suspended).
+ If an agent wishes the event to result in suspension, then the agent
+ is responsible for explicitly suspending the thread with
+ <functionlink id="SuspendThread"></functionlink>.
+ <p/>
+ If an event is enabled in multiple environments, the event will be sent
+ to each agent in the order that the environments were created.
+ </intro>
+
+ <intro label="Enabling Events" id="enablingevents">
+ All events are initially disabled. In order to receive any
+ event:
+ <ul>
+ <li>
+ If the event requires a capability, that capability must
+ be added with
+ <functionlink id="AddCapabilities"></functionlink>.
+ </li>
+ <li>
+ A callback for the event must be set with
+ <functionlink id="SetEventCallbacks"></functionlink>.
+ </li>
+ <li>
+ The event must be enabled with
+ <functionlink id="SetEventNotificationMode"></functionlink>.
+ </li>
+ </ul>
+ </intro>
+
+ <intro label="Multiple Co-located Events" id="eventorder">
+ In many situations it is possible for multiple events to occur
+ at the same location in one thread. When this happens, all the events
+ are reported through the event callbacks in the order specified in this section.
+ <p/>
+ If the current location is at the entry point of a method, the
+ <eventlink id="MethodEntry"></eventlink> event is reported before
+ any other event at the current location in the same thread.
+ <p/>
+ If an exception catch has been detected at the current location,
+ either because it is the beginning of a catch clause or a native method
+ that cleared a pending exception has returned, the
+ <code>exceptionCatch</code> event is reported before
+ any other event at the current location in the same thread.
+ <p/>
+ If a <code>singleStep</code> event or
+ <code>breakpoint</code> event is triggered at the
+ current location, the event is defined to occur
+ immediately before the code at the current location is executed.
+ These events are reported before any events which are triggered
+ by the execution of code at the current location in the same
+ thread (specifically:
+ <code>exception</code>,
+ <code>fieldAccess</code>, and
+ <code>fieldModification</code>).
+ If both a step and breakpoint event are triggered for the same thread and
+ location, the step event is reported before the breakpoint event.
+ <p/>
+ If the current location is the exit point of a method (that is, the last
+ location before returning to the caller), the
+ <eventlink id="MethodExit"></eventlink> event and
+ the <eventlink id="FramePop"></eventlink> event (if requested)
+ are reported after all other events at the current location in the same
+ thread. There is no specified ordering of these two events
+ with respect to each other.
+ <p/>
+ Co-located events can be triggered during the processing of some other
+ event by the agent at the same location in the same thread.
+ If such an event, of type <i>y</i>, is triggered during the processing of
+ an event of type <i>x</i>, and if <i>x</i>
+ precedes <i>y</i> in the ordering specified above, the co-located event
+ <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede
+ <i>y</i>, <i>y</i> is not reported for the current thread and location.
+ For example, if a breakpoint is set at the current location
+ during the processing of <eventlink id="SingleStep"></eventlink>,
+ that breakpoint will be reported before the thread moves off the current
+ location.
+ <p/>The following events are never considered to be co-located with
+ other events.
+ <ul>
+ <li><eventlink id="VMStart"></eventlink></li>
+ <li><eventlink id="VMInit"></eventlink></li>
+ <li><eventlink id="VMDeath"></eventlink></li>
+ <li><eventlink id="ThreadStart"></eventlink></li>
+ <li><eventlink id="ThreadEnd"></eventlink></li>
+ <li><eventlink id="ClassLoad"></eventlink></li>
+ <li><eventlink id="ClassPrepare"></eventlink></li>
+ </ul>
+ </intro>
+
+ <intro label="Event Callbacks" id="jvmtiEventCallbacks">
+ The event callback structure below is used to specify the handler function
+ for events. It is set with the
+ <functionlink id="SetEventCallbacks"></functionlink> function.
+ </intro>
+
+ <event label="Single Step"
+ id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60">
+ <description>
+ Single step events allow the agent to trace thread execution
+ at the finest granularity allowed by the VM. A single step event is
+ generated whenever a thread reaches a new location.
+ Typically, single step events represent the completion of one VM
+ instruction as defined in the <vmspeclink/>. However, some implementations
+ may define locations differently. In any case the
+ <code>method</code> and <code>location</code>
+ parameters uniquely identify the current location and allow
+ the mapping to source file and line number when that information is
+ available.
+ <p/>
+ No single step events are generated from within native methods.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_single_step_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread about to execution a new instruction
+ </description>
+ </param>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ Class of the method about to execute a new instruction
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ Method about to execute a new instruction
+ </description>
+ </param>
+ <param id="location">
+ <jlocation/>
+ <description>
+ Location of the new instruction
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Breakpoint"
+ id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62">
+ <description>
+ Breakpoint events are generated whenever a thread reaches a location
+ designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>.
+ The <code>method</code> and <code>location</code>
+ parameters uniquely identify the current location and allow
+ the mapping to source file and line number when that information is
+ available.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_breakpoint_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread.
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread that hit the breakpoint
+ </description>
+ </param>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ Class of the method that hit the breakpoint
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ Method that hit the breakpoint
+ </description>
+ </param>
+ <param id="location">
+ <jlocation/>
+ <description>
+ location of the breakpoint
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Field Access"
+ id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63">
+ <description>
+ Field access events are generated whenever a thread accesses
+ a field that was designated as a watchpoint
+ with <functionlink id="SetFieldAccessWatch"></functionlink>.
+ The <code>method</code> and <code>location</code>
+ parameters uniquely identify the current location and allow
+ the mapping to source file and line number when that information is
+ available.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_field_access_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread accessing the field
+ </description>
+ </param>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ Class of the method where the access is occurring
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ Method where the access is occurring
+ </description>
+ </param>
+ <param id="location">
+ <jlocation/>
+ <description>
+ Location where the access is occurring
+ </description>
+ </param>
+ <param id="field_klass">
+ <jclass field="field"/>
+ <description>
+ Class of the field being accessed
+ </description>
+ </param>
+ <param id="object">
+ <jobject/>
+ <description>
+ Object with the field being accessed if the field is an
+ instance field; <code>NULL</code> otherwise
+ </description>
+ </param>
+ <param id="field">
+ <jfieldID class="field_klass"/>
+ <description>
+ Field being accessed
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Field Modification"
+ id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64">
+ <description>
+ Field modification events are generated whenever a thread modifies
+ a field that was designated as a watchpoint
+ with <functionlink id="SetFieldModificationWatch"></functionlink>.
+ The <code>method</code> and <code>location</code>
+ parameters uniquely identify the current location and allow
+ the mapping to source file and line number when that information is
+ available.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_field_modification_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread modifying the field
+ </description>
+ </param>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ Class of the method where the modification is occurring
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ Method where the modification is occurring
+ </description>
+ </param>
+ <param id="location">
+ <jlocation/>
+ <description>
+ Location where the modification is occurring
+ </description>
+ </param>
+ <param id="field_klass">
+ <jclass field="field"/>
+ <description>
+ Class of the field being modified
+ </description>
+ </param>
+ <param id="object">
+ <jobject/>
+ <description>
+ Object with the field being modified if the field is an
+ instance field; <code>NULL</code> otherwise
+ </description>
+ </param>
+ <param id="field">
+ <jfieldID class="field_klass"/>
+ <description>
+ Field being modified
+ </description>
+ </param>
+ <param id="signature_type">
+ <char/>
+ <description>
+ Signature type of the new value
+ </description>
+ </param>
+ <param id="new_value">
+ <jvalue/>
+ <description>
+ The new value
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Frame Pop"
+ id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61">
+ <description>
+ Frame pop events are generated upon exit from a single method
+ in a single frame as specified
+ in a call to <functionlink id="NotifyFramePop"></functionlink>.
+ This is true whether termination is caused by
+ executing its return instruction
+ or by throwing an exception to its caller
+ (see <paramlink id="was_popped_by_exception"></paramlink>).
+ However, frame pops caused by the <functionlink id="PopFrame"/>
+ function are not reported.
+ <p/>
+ The location reported by <functionlink id="GetFrameLocation"></functionlink>
+ identifies the executable location in the returning method,
+ immediately prior to the return.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_frame_pop_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread that is popping the frame
+ </description>
+ </param>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ Class of the method being popped
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ Method being popped
+ </description>
+ </param>
+ <param id="was_popped_by_exception">
+ <jboolean/>
+ <description>
+ True if frame was popped by a thrown exception.
+ False if method exited through its return instruction.
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Method Entry"
+ id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65">
+ <description>
+ Method entry events are generated upon entry of Java
+ programming language methods (including native methods).
+ <p/>
+ The location reported by <functionlink id="GetFrameLocation"></functionlink>
+ identifies the initial executable location in
+ the method.
+ <p/>
+ Enabling method
+ entry or exit events will significantly degrade performance on many platforms and is thus
+ not advised for performance critical usage (such as profiling).
+ <internallink id="bci">Bytecode instrumentation</internallink> should be
+ used in these cases.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_method_entry_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread entering the method
+ </description>
+ </param>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ Class of the method being entered
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ Method being entered
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Method Exit"
+ id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66">
+ <description>
+ Method exit events are generated upon exit from Java
+ programming language methods (including native methods).
+ This is true whether termination is caused by
+ executing its return instruction
+ or by throwing an exception to its caller
+ (see <paramlink id="was_popped_by_exception"></paramlink>).
+ <p/>
+ The <code>method</code> field uniquely identifies the
+ method being entered or exited. The <code>frame</code> field provides
+ access to the stack frame for the method.
+ <p/>
+ The location reported by <functionlink id="GetFrameLocation"></functionlink>
+ identifies the executable location in the returning method
+ immediately prior to the return.
+ <p/>
+ Enabling method
+ entry or exit events will significantly degrade performance on many platforms and is thus
+ not advised for performance critical usage (such as profiling).
+ <internallink id="bci">Bytecode instrumentation</internallink> should be
+ used in these cases.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_method_exit_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread exiting the method
+ </description>
+ </param>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ Class of the method being exited
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ Method being exited
+ </description>
+ </param>
+ <param id="was_popped_by_exception">
+ <jboolean/>
+ <description>
+ True if frame was popped by a thrown exception.
+ False if method exited through its return instruction.
+ </description>
+ </param>
+ <param id="return_value">
+ <jvalue/>
+ <description>
+ The return value of the method being exited.
+ Undefined and should not be used if
+ <paramlink id="was_popped_by_exception"></paramlink>
+ is true.
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Native Method Bind" phase="any"
+ id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67">
+ <description>
+ A Native Method Bind event is sent when a VM binds a
+ Java programming language native method
+ to the address of a function that implements the native method.
+ This will occur when the native method is called for the first time
+ and also occurs when the JNI function <code>RegisterNatives</code> is called.
+ This event allows the bind to be redirected to an agent-specified
+ proxy function.
+ This event is not sent when the native method is unbound.
+ Typically, this proxy function will need to be specific to a
+ particular method or, to handle the general case, automatically
+ generated assembly code, since after instrumentation code is
+ executed the function at the original binding
+ address will usually be invoked.
+ The original binding can be restored or the redirection changed
+ by use of the JNI function <code>RegisterNatives</code>.
+ Some events may be sent during the primordial phase, JNI and
+ most of <jvmti/> cannot be used at this time but the method and
+ address can be saved for use later.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_generate_native_method_bind_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ Will be <code>NULL</code> if sent during the primordial
+ <functionlink id="GetPhase">phase</functionlink>.
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread requesting the bind
+ </description>
+ </param>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ Class of the method being bound
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ Native method being bound
+ </description>
+ </param>
+ <param id="address">
+ <outptr><void/></outptr>
+ <description>
+ The address the VM is about to bind to--that is, the
+ address of the implementation of the native method
+ </description>
+ </param>
+ <param id="new_address_ptr">
+ <agentbuf><void/></agentbuf>
+ <description>
+ if the referenced address is changed (that is, if
+ <code>*new_address_ptr</code> is set), the binding
+ will instead be made to the supplied address.
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Exception"
+ id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58">
+ <description>
+ Exception events are generated whenever an exception is first detected
+ in a Java programming language method.
+ Where "exception" means any <code>java.lang.Throwable</code>.
+ The exception may have been thrown by a Java programming language or native
+ method, but in the case of native methods, the event is not generated
+ until the exception is first seen by a Java programming language method. If an exception is
+ set and cleared in a native method (and thus is never visible to Java programming language code),
+ no exception event is generated.
+ <p/>
+ The <code>method</code> and <code>location</code>
+ parameters uniquely identify the current location
+ (where the exception was detected) and allow
+ the mapping to source file and line number when that information is
+ available. The <code>exception</code> field identifies the thrown
+ exception object. The <code>catch_method</code>
+ and <code>catch_location</code> identify the location of the catch clause,
+ if any, that handles the thrown exception. If there is no such catch clause,
+ each field is set to 0. There is no guarantee that the thread will ever
+ reach this catch clause. If there are native methods on the call stack
+ between the throw location and the catch clause, the exception may
+ be reset by one of those native methods.
+ Similarly, exceptions that are reported as uncaught (<code>catch_klass</code>
+ et al. set to 0) may in fact be caught by native code.
+ Agents can check for these occurrences by monitoring
+ <eventlink id="ExceptionCatch"></eventlink> events.
+ Note that finally clauses are implemented as catch and re-throw. Therefore they
+ will be reported in the catch location.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_exception_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread generating the exception
+ </description>
+ </param>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ Class generating the exception
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ Method generating the exception
+ </description>
+ </param>
+ <param id="location">
+ <jlocation/>
+ <description>
+ Location where exception occurred
+ </description>
+ </param>
+ <param id="exception">
+ <jobject/>
+ <description>
+ The exception being thrown
+ </description>
+ </param>
+ <param id="catch_klass">
+ <jclass method="catch_method"/>
+ <description>
+ Class that will catch the exception, or <code>NULL</code> if no known catch
+ </description>
+ </param>
+ <param id="catch_method">
+ <jmethodID class="catch_klass"/>
+ <description>
+ Method that will catch the exception, or <code>NULL</code> if no known catch
+ </description>
+ </param>
+ <param id="catch_location">
+ <jlocation/>
+ <description>
+ location which will catch the exception or zero if no known catch
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Exception Catch"
+ id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59">
+ <description>
+ Exception catch events are generated whenever a thrown exception is caught.
+ Where "exception" means any <code>java.lang.Throwable</code>.
+ If the exception is caught in a Java programming language method, the event is generated
+ when the catch clause is reached. If the exception is caught in a native
+ method, the event is generated as soon as control is returned to a Java programming language
+ method. Exception catch events are generated for any exception for which
+ a throw was detected in a Java programming language method.
+ Note that finally clauses are implemented as catch and re-throw. Therefore they
+ will generate exception catch events.
+ <p/>
+ The <code>method</code> and <code>location</code>
+ parameters uniquely identify the current location
+ and allow the mapping to source file and line number when that information is
+ available. For exceptions caught in a Java programming language method, the
+ <code>exception</code> object identifies the exception object. Exceptions
+ caught in native methods are not necessarily available by the time the
+ exception catch is reported, so the <code>exception</code> field is set
+ to <code>NULL</code>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ <required id="can_generate_exception_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread catching the exception
+ </description>
+ </param>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ Class catching the exception
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ Method catching the exception
+ </description>
+ </param>
+ <param id="location">
+ <jlocation/>
+ <description>
+ Location where exception is being caught
+ </description>
+ </param>
+ <param id="exception">
+ <jobject/>
+ <description>
+ Exception being caught
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Thread Start"
+ id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start">
+ <description>
+ Thread start events are generated by a new thread before its initial
+ method executes.
+ <p/>
+ A thread may be listed in the array returned by
+ <functionlink id="GetAllThreads"></functionlink>
+ before its thread start event is generated.
+ It is possible for other events to be generated
+ on a thread before its thread start event.
+ <p/>
+ The event is sent on the newly started <paramlink id="thread"></paramlink>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread.
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread starting
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Thread End"
+ id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start">
+ <description>
+ Thread end events are generated by a terminating thread
+ after its initial method has finished execution.
+ <p/>
+ A thread may be listed in the array returned by
+ <functionlink id="GetAllThreads"></functionlink>
+ after its thread end event is generated.
+ No events are generated on a thread
+ after its thread end event.
+ <p/>
+ The event is sent on the dying <paramlink id="thread"></paramlink>.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread.
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread ending
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Class Load"
+ id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55">
+ <description>
+ A class load event is generated when a class is first loaded. The order
+ of class load events generated by a particular thread are guaranteed
+ to match the order of class loading within that thread.
+ Array class creation does not generate a class load event.
+ The creation of a primitive class (for example, java.lang.Integer.TYPE)
+ does not generate a class load event.
+ <p/>
+ This event is sent at an early stage in loading the class. As
+ a result the class should be used carefully. Note, for example,
+ that methods and fields are not yet loaded, so queries for methods,
+ fields, subclasses, and so on will not give correct results.
+ See "Loading of Classes and Interfaces" in the <i>Java Language
+ Specification</i>. For most
+ purposes the <eventlink id="ClassPrepare"></eventlink> event will
+ be more useful.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread loading the class
+ </description>
+ </param>
+ <param id="klass">
+ <jclass/>
+ <description>
+ Class being loaded
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <elide>
+ <event label="Class Unload"
+ id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57">
+ <description>
+ A class unload event is generated when the class is about to be unloaded.
+ Class unload events take place during garbage collection and must be
+ handled extremely carefully. The garbage collector holds many locks
+ and has suspended all other threads, so the event handler cannot depend
+ on the ability to acquire any locks. The class unload event handler should
+ do as little as possible, perhaps by queuing information to be processed
+ later. In particular, the <code>jclass</code> should be used only in
+ the JNI function <code>isSameObject</code> or in the following <jvmti/> functions:
+ <ul>
+ <li><functionlink id="GetClassSignature"></functionlink></li>
+ <li><functionlink id="GetSourceFileName"></functionlink></li>
+ <li><functionlink id="IsInterface"></functionlink></li>
+ <li><functionlink id="IsArrayClass"></functionlink></li>
+ </ul>
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread generating the class unload
+ </description>
+ </param>
+ <param id="klass">
+ <jclass/>
+ <description>
+ Class being unloaded
+ </description>
+ </param>
+ </parameters>
+ </event>
+ </elide>
+
+ <event label="Class Prepare"
+ id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56">
+ <description>
+ A class prepare event is generated when class preparation is complete.
+ At this point, class fields, methods, and implemented interfaces are
+ available, and no code from the class has been executed. Since array
+ classes never have fields or methods, class prepare events are not
+ generated for them. Class prepare events are not generated for
+ primitive classes (for example, <code>java.lang.Integer.TYPE</code>).
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread generating the class prepare
+ </description>
+ </param>
+ <param id="klass">
+ <jclass/>
+ <description>
+ Class being prepared
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Class File Load Hook" phase="any"
+ id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54">
+ <description>
+ This event is sent when the VM obtains class file data,
+ but before it constructs
+ the in-memory representation for that class.
+ This event is also sent when the class is being modified by the
+ <functionlink id="RetransformClasses"/> function or
+ the <functionlink id="RedefineClasses"/> function,
+ called in any <jvmti/> environment.
+ The agent can instrument
+ the existing class file data sent by the VM to include profiling/debugging hooks.
+ See the description of
+ <internallink id="bci">bytecode instrumentation</internallink>
+ for usage information.
+ <p/>
+ This event may be sent before the VM is initialized (the primordial
+ <functionlink id="GetPhase">phase</functionlink>). During this time
+ no VM resources should be created. Some classes might not be compatible
+ with the function (eg. ROMized classes) and this event will not be
+ generated for these classes.
+ <p/>
+ The agent must allocate the space for the modified
+ class file data buffer
+ using the memory allocation function
+ <functionlink id="Allocate"></functionlink> because the
+ VM is responsible for freeing the new class file data buffer
+ using <functionlink id="Deallocate"></functionlink>.
+ Note that <functionlink id="Allocate"></functionlink>
+ is permitted during the primordial phase.
+ <p/>
+ If the agent wishes to modify the class file, it must set
+ <code>new_class_data</code> to point
+ to the newly instrumented class file data buffer and set
+ <code>new_class_data_len</code> to the length of that
+ buffer before returning
+ from this call. If no modification is desired, the agent simply
+ does not set <code>new_class_data</code>. If multiple agents
+ have enabled this event the results are chained. That is, if
+ <code>new_class_data</code> has been set, it becomes the
+ <code>class_data</code> for the next agent.
+ <p/>
+ The order that this event is sent to each environment differs
+ from other events.
+ This event is sent to environments in the following order:
+ <ul>
+ <li><fieldlink id="can_retransform_classes"
+ struct="jvmtiCapabilities">retransformation
+ incapable</fieldlink>
+ environments, in the
+ order in which they were created
+ </li>
+ <li><fieldlink id="can_retransform_classes"
+ struct="jvmtiCapabilities">retransformation
+ capable</fieldlink>
+ environments, in the
+ order in which they were created
+ </li>
+ </ul>
+ When triggered by <functionlink id="RetransformClasses"/>,
+ this event is sent only to <fieldlink id="can_retransform_classes"
+ struct="jvmtiCapabilities">retransformation
+ capable</fieldlink>
+ environments.
+ </description>
+ <origin>jvmpi</origin>
+ <capabilities>
+ <capability id="can_generate_all_class_hook_events"></capability>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread.
+ Will be <code>NULL</code> if sent during the primordial
+ <functionlink id="GetPhase">phase</functionlink>.
+ </description>
+ </param>
+ <param id="class_being_redefined">
+ <jclass/>
+ <description>
+ The class being
+ <functionlink id="RedefineClasses">redefined</functionlink> or
+ <functionlink id="RetransformClasses">retransformed</functionlink>.
+ <code>NULL</code> if sent by class load.
+ </description>
+ </param>
+ <param id="loader">
+ <jobject/>
+ <description>
+ The class loader loading the class.
+ <code>NULL</code> if the bootstrap class loader.
+ </description>
+ </param>
+ <param id="name">
+ <vmbuf><char/></vmbuf>
+ <description>
+ Name of class being loaded as a VM internal qualified name
+ (for example, "java/util/List"), encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ Note: if the class is defined with a <code>NULL</code> name or
+ without a name specified, <code>name</code> will be <code>NULL</code>.
+ </description>
+ </param>
+ <param id="protection_domain">
+ <jobject/>
+ <description>
+ The <code>ProtectionDomain</code> of the class.
+ </description>
+ </param>
+ <param id="class_data_len">
+ <jint/>
+ <description>
+ Length of current class file data buffer.
+ </description>
+ </param>
+ <param id="class_data">
+ <vmbuf><uchar/></vmbuf>
+ <description>
+ Pointer to the current class file data buffer.
+ </description>
+ </param>
+ <param id="new_class_data_len">
+ <outptr><jint/></outptr>
+ <description>
+ Pointer to the length of the new class file data buffer.
+ </description>
+ </param>
+ <param id="new_class_data">
+ <agentbuf incount="new_class_data_len"><uchar/></agentbuf>
+ <description>
+ Pointer to the pointer to the instrumented class file data buffer.
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="VM Start Event"
+ id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start">
+ <description>
+ The VM initialization event signals the start of the VM.
+ At this time JNI is live but the VM is not yet fully initialized.
+ Once this event is generated, the agent is free to call any JNI function.
+ This event signals the beginning of the start phase,
+ <jvmti/> functions permitted in the start phase may be called.
+ <p/>
+ In the case of VM start-up failure, this event will not be sent.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread.
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="VM Initialization Event"
+ id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50">
+ <description>
+ The VM initialization event signals the completion of VM initialization. Once
+ this event is generated, the agent is free to call any JNI or <jvmti/>
+ function. The VM initialization event can be preceded by or can be concurrent
+ with other events, but
+ the preceding events should be handled carefully, if at all, because the
+ VM has not completed its initialization. The thread start event for the
+ main application thread is guaranteed not to occur until after the
+ handler for the VM initialization event returns.
+ <p/>
+ In the case of VM start-up failure, this event will not be sent.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread.
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ The initial thread
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="VM Death Event"
+ id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51">
+ <description>
+ The VM death event notifies the agent of the termination of the VM.
+ No events will occur after the VMDeath event.
+ <p/>
+ In the case of VM start-up failure, this event will not be sent.
+ Note that <internallink id="onunload">Agent_OnUnload</internallink>
+ will still be called in these cases.
+ </description>
+ <origin>jvmdi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Compiled Method Load"
+ id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68">
+ <description>
+ Sent when a method is compiled and loaded into memory by the VM.
+ If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent.
+ If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent,
+ followed by a new <code>CompiledMethodLoad</code> event.
+ Note that a single method may have multiple compiled forms, and that
+ this event will be sent for each form.
+ Note also that several methods may be inlined into a single
+ address range, and that this event will be sent for each method.
+ <p/>
+ These events can be sent after their initial occurrence with
+ <functionlink id="GenerateEvents"></functionlink>.
+ </description>
+ <origin>jvmpi</origin>
+ <typedef id="jvmtiAddrLocationMap" label="Native address to location entry">
+ <field id="start_address">
+ <vmbuf><void/></vmbuf>
+ <description>
+ Starting native address of code corresponding to a location
+ </description>
+ </field>
+ <field id="location">
+ <jlocation/>
+ <description>
+ Corresponding location. See
+ <functionlink id="GetJLocationFormat"></functionlink>
+ for the meaning of location.
+ </description>
+ </field>
+ </typedef>
+ <capabilities>
+ <required id="can_generate_compiled_method_load_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ Class of the method being compiled and loaded
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ Method being compiled and loaded
+ </description>
+ </param>
+ <param id="code_size">
+ <jint/>
+ <description>
+ Size of compiled code
+ </description>
+ </param>
+ <param id="code_addr">
+ <vmbuf><void/></vmbuf>
+ <description>
+ Address where compiled method code is loaded
+ </description>
+ </param>
+ <param id="map_length">
+ <jint/>
+ <description>
+ Number of <typelink id="jvmtiAddrLocationMap"></typelink>
+ entries in the address map.
+ Zero if mapping information cannot be supplied.
+ </description>
+ </param>
+ <param id="map">
+ <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf>
+ <description>
+ Map from native addresses to location.
+ The native address range of each entry is from
+ <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink>
+ to <code>start_address-1</code> of the next entry.
+ <code>NULL</code> if mapping information cannot be supplied.
+ </description>
+ </param>
+ <param id="compile_info">
+ <vmbuf><void/></vmbuf>
+ <description>
+ VM-specific compilation information.
+ The referenced compile information is managed by the VM
+ and must not depend on the agent for collection.
+ A VM implementation defines the content and lifetime
+ of the information.
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Compiled Method Unload"
+ id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69">
+ <description>
+ Sent when a compiled method is unloaded from memory.
+ This event might not be sent on the thread which performed the unload.
+ This event may be sent sometime after the unload occurs, but
+ will be sent before the memory is reused
+ by a newly generated compiled method. This event may be sent after
+ the class is unloaded.
+ </description>
+ <origin>jvmpi</origin>
+ <capabilities>
+ <required id="can_generate_compiled_method_load_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="klass">
+ <jclass method="method"/>
+ <description>
+ Class of the compiled method being unloaded.
+ </description>
+ </param>
+ <param id="method">
+ <jmethodID class="klass"/>
+ <description>
+ Compiled method being unloaded.
+ For identification of the compiled method only -- the class
+ may be unloaded and therefore the method should not be used
+ as an argument to further JNI or <jvmti/> functions.
+ </description>
+ </param>
+ <param id="code_addr">
+ <vmbuf><void/></vmbuf>
+ <description>
+ Address where compiled method code was loaded.
+ For identification of the compiled method only --
+ the space may have been reclaimed.
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Dynamic Code Generated" phase="any"
+ id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70">
+ <description>
+ Sent when a component of the virtual machine is generated dynamically.
+ This does not correspond to Java programming language code that is
+ compiled--see <eventlink id="CompiledMethodLoad"></eventlink>.
+ This is for native code--for example, an interpreter that is generated
+ differently depending on command-line options.
+ <p/>
+ Note that this event has no controlling capability.
+ If a VM cannot generate these events, it simply does not send any.
+ <p/>
+ These events can be sent after their initial occurrence with
+ <functionlink id="GenerateEvents"></functionlink>.
+ </description>
+ <origin>jvmpi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="name">
+ <vmbuf><char/></vmbuf>
+ <description>
+ Name of the code, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ Intended for display to an end-user.
+ The name might not be unique.
+ </description>
+ </param>
+ <param id="address">
+ <vmbuf><void/></vmbuf>
+ <description>
+ Native address of the code
+ </description>
+ </param>
+ <param id="length">
+ <jint/>
+ <description>
+ Length in bytes of the code
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Data Dump Request"
+ id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71">
+ <description>
+ Sent by the VM to request the agent to dump its data. This
+ is just a hint and the agent need not react to this event.
+ This is useful for processing command-line signals from users. For
+ example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris
+ causes the VM to send this event to the agent.
+ </description>
+ <origin>jvmpi</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ </parameters>
+ </event>
+
+ <event label="Monitor Contended Enter"
+ id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75">
+ <description>
+ Sent when a thread is attempting to enter a Java programming language
+ monitor already acquired by another thread.
+ </description>
+ <origin>jvmpi</origin>
+ <capabilities>
+ <required id="can_generate_monitor_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ JNI local reference to the thread
+ attempting to enter the monitor
+ </description>
+ </param>
+ <param id="object">
+ <jobject/>
+ <description>
+ JNI local reference to the monitor
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Monitor Contended Entered"
+ id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76">
+ <description>
+ Sent when a thread enters a Java programming language
+ monitor after waiting for it to be released by another thread.
+ </description>
+ <origin>jvmpi</origin>
+ <capabilities>
+ <required id="can_generate_monitor_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ JNI local reference to the thread entering
+ the monitor
+ </description>
+ </param>
+ <param id="object">
+ <jobject/>
+ <description>
+ JNI local reference to the monitor
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Monitor Wait"
+ id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73">
+ <description>
+ Sent when a thread is about to wait on an object.
+ </description>
+ <origin>jvmpi</origin>
+ <capabilities>
+ <required id="can_generate_monitor_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ JNI local reference to the thread about to wait
+ </description>
+ </param>
+ <param id="object">
+ <jobject/>
+ <description>
+ JNI local reference to the monitor
+ </description>
+ </param>
+ <param id="timeout">
+ <jlong/>
+ <description>
+ The number of milliseconds the thread will wait
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Monitor Waited"
+ id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74">
+ <description>
+ Sent when a thread finishes waiting on an object.
+ </description>
+ <origin>jvmpi</origin>
+ <capabilities>
+ <required id="can_generate_monitor_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ JNI local reference to the thread that was finished waiting
+ </description>
+ </param>
+ <param id="object">
+ <jobject/>
+ <description>
+ JNI local reference to the monitor.
+ </description>
+ </param>
+ <param id="timed_out">
+ <jboolean/>
+ <description>
+ True if the monitor timed out
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Resource Exhausted"
+ id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80"
+ since="1.1">
+ <description>
+ Sent when a VM resource needed by a running application has been exhausted.
+ Except as required by the optional capabilities, the set of resources
+ which report exhaustion is implementation dependent.
+ <p/>
+ The following bit flags define the properties of the resource exhaustion:
+ <constants id="jvmtiResourceExhaustionFlags"
+ label="Resource Exhaustion Flags"
+ kind="bits"
+ since="1.1">
+ <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001">
+ After this event returns, the VM will throw a
+ <code>java.lang.OutOfMemoryError</code>.
+ </constant>
+ <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002">
+ The VM was unable to allocate memory from the <tm>Java</tm>
+ platform <i>heap</i>.
+ The <i>heap</i> is the runtime
+ data area from which memory for all class instances and
+ arrays are allocated.
+ </constant>
+ <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004">
+ The VM was unable to create a thread.
+ </constant>
+ </constants>
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <capability id="can_generate_resource_exhaustion_heap_events">
+ Can generate events when the VM is unable to allocate memory from the
+ <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>.
+ </capability>
+ <capability id="can_generate_resource_exhaustion_threads_events">
+ Can generate events when the VM is unable to
+ <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create
+ a thread</internallink>.
+ </capability>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="flags">
+ <jint/>
+ <description>
+ Flags defining the properties of the of resource exhaustion
+ as specified by the
+ <internallink id="jvmtiResourceExhaustionFlags">Resource
+ Exhaustion Flags</internallink>.
+ </description>
+ </param>
+ <param id="reserved">
+ <vmbuf><void/></vmbuf>
+ <description>
+ Reserved.
+ </description>
+ </param>
+ <param id="description">
+ <vmbuf><char/></vmbuf>
+ <description>
+ Description of the resource exhaustion, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="VM Object Allocation"
+ id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84">
+ <description>
+ Sent when a method causes the virtual machine to allocate an
+ Object visible to Java programming language code and the
+ allocation is not detectable by other intrumentation mechanisms.
+ Generally object allocation should be detected by instrumenting
+ the bytecodes of allocating methods.
+ Object allocation generated in native code by JNI function
+ calls should be detected using
+ <internallink id="jniIntercept">JNI function interception</internallink>.
+ Some methods might not have associated bytecodes and are not
+ native methods, they instead are executed directly by the
+ VM. These methods should send this event.
+ Virtual machines which are incapable of bytecode instrumentation
+ for some or all of their methods can send this event.
+ <p/>
+ Typical examples where this event might be sent:
+ <ul>
+ <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li>
+ <li>Methods not represented by bytecodes -- for example, VM intrinsics and
+ J2ME preloaded classes</li>
+ </ul>
+ Cases where this event would not be generated:
+ <ul>
+ <li>Allocation due to bytecodes -- for example, the <code>new</code>
+ and <code>newarray</code> VM instructions</li>
+ <li>Allocation due to JNI function calls -- for example,
+ <code>AllocObject</code></li>
+ <li>Allocations during VM initialization</li>
+ <li>VM internal objects</li>
+ </ul>
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_generate_vm_object_alloc_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="jni_env">
+ <outptr>
+ <struct>JNIEnv</struct>
+ </outptr>
+ <description>
+ The JNI environment of the event (current) thread
+ </description>
+ </param>
+ <param id="thread">
+ <jthread/>
+ <description>
+ Thread allocating the object.
+ </description>
+ </param>
+ <param id="object">
+ <jobject/>
+ <description>
+ JNI local reference to the object that was allocated
+ </description>
+ </param>
+ <param id="object_klass">
+ <jclass/>
+ <description>
+ JNI local reference to the class of the object
+ </description>
+ </param>
+ <param id="size">
+ <jlong/>
+ <description>
+ Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Object Free"
+ id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
+ <description>
+ An Object Free event is sent when the garbage collector frees an object.
+ Events are only sent for tagged objects--see
+ <internallink id="Heap">heap functions</internallink>.
+ <p/>
+ The event handler must not use JNI functions and
+ must not use <jvmti/> functions except those which
+ specifically allow such use (see the raw monitor, memory management,
+ and environment local storage functions).
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_generate_object_free_events"></required>
+ </capabilities>
+ <parameters>
+ <param id="tag">
+ <jlong/>
+ <description>
+ The freed object's tag
+ </description>
+ </param>
+ </parameters>
+ </event>
+
+ <event label="Garbage Collection Start"
+ id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81">
+ <description>
+ A Garbage Collection Start event is sent when a full cycle
+ garbage collection begins.
+ Only stop-the-world collections are reported--that is, collections during
+ which all threads cease to modify the state of the Java virtual machine.
+ This means that some collectors will never generate these events.
+ This event is sent while the VM is still stopped, thus
+ the event handler must not use JNI functions and
+ must not use <jvmti/> functions except those which
+ specifically allow such use (see the raw monitor, memory management,
+ and environment local storage functions).
+ <p/>
+ This event is always sent as a matched pair with
+ <eventlink id="GarbageCollectionFinish"/>
+ (assuming both events are enabled) and no garbage collection
+ events will occur between them.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_generate_garbage_collection_events"></required>
+ </capabilities>
+ <parameters>
+ </parameters>
+ </event>
+
+ <event label="Garbage Collection Finish"
+ id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82">
+ <description>
+ A Garbage Collection Finish event is sent when a full
+ garbage collection cycle ends.
+ This event is sent while the VM is still stopped, thus
+ the event handler must not use JNI functions and
+ must not use <jvmti/> functions except those which
+ specifically allow such use (see the raw monitor, memory management,
+ and environment local storage functions).
+ <p/>
+ Some agents may need to do post garbage collection operations that
+ require the use of the disallowed <jvmti/> or JNI functions. For these
+ cases an agent thread can be created which waits on a raw monitor,
+ and the handler for the Garbage Collection Finish event simply
+ notifies the raw monitor
+ <p/>
+ This event is always sent as a matched pair with
+ <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled).
+ <issue>
+ The most important use of this event is to provide timing information,
+ and thus additional information is not required. However,
+ information about the collection which is "free" should be included -
+ what that information is needs to be determined.
+ </issue>
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_generate_garbage_collection_events"></required>
+ </capabilities>
+ <parameters>
+ </parameters>
+ </event>
+
+ <elide>
+ <event label="Verbose Output" phase="any"
+ id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85">
+ <description>
+ Send verbose messages as strings.
+ <issue>
+ This format is extremely fragile, as it can change with each
+ platform, collector and version. Alternatives include:
+ <ul>
+ <li>building off Java programming language M and M APIs</li>
+ <li>XML</li>
+ <li>key/value pairs</li>
+ <li>removing it</li>
+ </ul>
+ </issue>
+ <issue>
+ Though this seemed trivial to implement.
+ In the RI it appears this will be quite complex.
+ </issue>
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ </capabilities>
+ <parameters>
+ <param id="flag">
+ <enum>jvmtiVerboseFlag</enum>
+ <description>
+ Which verbose output is being sent.
+ </description>
+ </param>
+ <param id="message">
+ <vmbuf><char/></vmbuf>
+ <description>
+ Message text, encoded as a
+ <internallink id="mUTF">modified UTF-8</internallink> string.
+ </description>
+ </param>
+ </parameters>
+ </event>
+ </elide>
+
+</eventsection>
+
+<datasection>
+ <intro>
+ <jvmti/> extends the data types defined by JNI.
+ </intro>
+ <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface">
+ <basetype id="jboolean">
+ <description>
+ Holds a Java programming language <code>boolean</code>.
+ Unsigned 8 bits.
+ </description>
+ </basetype>
+ <basetype id="jint">
+ <description>
+ Holds a Java programming language <code>int</code>.
+ Signed 32 bits.
+ </description>
+ </basetype>
+ <basetype id="jlong">
+ <description>
+ Holds a Java programming language <code>long</code>.
+ Signed 64 bits.
+ </description>
+ </basetype>
+ <basetype id="jfloat">
+ <description>
+ Holds a Java programming language <code>float</code>.
+ 32 bits.
+ </description>
+ </basetype>
+ <basetype id="jdouble">
+ <description>
+ Holds a Java programming language <code>double</code>.
+ 64 bits.
+ </description>
+ </basetype>
+ <basetype id="jobject">
+ <description>
+ Holds a Java programming language object.
+ </description>
+ </basetype>
+ <basetype id="jclass">
+ <description>
+ Holds a Java programming language class.
+ </description>
+ </basetype>
+ <basetype id="jvalue">
+ <description>
+ Is a union of all primitive types and <code>jobject</code>. Thus, holds any Java
+ programming language value.
+ </description>
+ </basetype>
+ <basetype id="jfieldID">
+ <description>
+ Identifies a Java programming language field.
+ <code>jfieldID</code>s returned by <jvmti/> functions and events may be
+ safely stored.
+ </description>
+ </basetype>
+ <basetype id="jmethodID">
+ <description>
+ Identifies a Java programming language method, initializer, or constructor.
+ <code>jmethodID</code>s returned by <jvmti/> functions and events may be
+ safely stored. However, if the class is unloaded, they become invalid
+ and must not be used.
+ </description>
+ </basetype>
+ <basetype id="JNIEnv">
+ <description>
+ Pointer to the JNI function table. Pointer to this (<code>JNIEnv *</code>)
+ is a JNI environment.
+ </description>
+ </basetype>
+ </basetypes>
+
+ <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types">
+ <basetype id="jvmtiEnv">
+ <description>
+ The <jvmti/> <internallink id="environments">environment</internallink> pointer.
+ See the <internallink id="FunctionSection">Function Section</internallink>.
+ <code>jvmtiEnv</code> points to the
+ <internallink id="FunctionTable">function table</internallink> pointer.
+ </description>
+ </basetype>
+ <basetype id="jthread">
+ <definition>typedef jobject jthread;</definition>
+ <description>
+ Subtype of <datalink id="jobject"></datalink> that holds a thread.
+ </description>
+ </basetype>
+ <basetype id="jthreadGroup">
+ <definition>typedef jobject jthreadGroup;</definition>
+ <description>
+ Subtype of <datalink id="jobject"></datalink> that holds a thread group.
+ </description>
+ </basetype>
+ <basetype id="jlocation">
+ <definition>typedef jlong jlocation;</definition>
+ <description>
+ A 64 bit value, representing a monotonically increasing
+ executable position within a method.
+ <code>-1</code> indicates a native method.
+ See <functionlink id="GetJLocationFormat"></functionlink> for the format on a
+ given VM.
+ </description>
+ </basetype>
+ <basetype id="jrawMonitorID">
+ <definition>struct _jrawMonitorID;
+typedef struct _jrawMonitorID *jrawMonitorID;</definition>
+ <description>
+ A raw monitor.
+ </description>
+ </basetype>
+ <basetype id="jvmtiError">
+ <description>
+ Holds an error return code.
+ See the <internallink id="ErrorSection">Error section</internallink> for possible values.
+ <example>
+typedef enum {
+ JVMTI_ERROR_NONE = 0,
+ JVMTI_ERROR_INVALID_THREAD = 10,
+ ...
+} jvmtiError;
+</example>
+ </description>
+ </basetype>
+ <basetype id="jvmtiEvent">
+ <description>
+ An identifier for an event type.
+ See the <internallink id="EventSection">Event section</internallink> for possible values.
+ It is guaranteed that future versions of this specification will
+ never assign zero as an event type identifier.
+<example>
+typedef enum {
+ JVMTI_EVENT_SINGLE_STEP = 1,
+ JVMTI_EVENT_BREAKPOINT = 2,
+ ...
+} jvmtiEvent;
+</example>
+ </description>
+ </basetype>
+ <basetype id="jvmtiEventCallbacks">
+ <description>
+ The callbacks used for events.
+<example>
+typedef struct {
+ jvmtiEventVMInit VMInit;
+ jvmtiEventVMDeath VMDeath;
+ ...
+} jvmtiEventCallbacks;
+</example>
+ See <internallink id="jvmtiEventCallbacks">event callbacks</internallink>
+ for the complete structure.
+ <p/>
+ Where, for example, the VM initialization callback is defined:
+<example>
+typedef void (JNICALL *jvmtiEventVMInit)
+ (jvmtiEnv *jvmti_env,
+ JNIEnv* jni_env,
+ jthread thread);
+</example>
+ See the individual events for the callback function definition.
+ </description>
+ </basetype>
+ <basetype id="jniNativeInterface">
+ <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition>
+ <description>
+ Typedef for the JNI function table <code>JNINativeInterface</code>
+ defined in the
+ <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html#wp23720">JNI Specification</externallink>.
+ The JNI reference implementation defines this with an underscore.
+ </description>
+ </basetype>
+ </basetypes>
+
+</datasection>
+
+<issuessection label="Issues">
+ <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic">
+ JVMDI requires that the agent suspend threads before calling
+ certain sensitive functions. JVMPI requires garbage collection to be
+ disabled before calling certain sensitive functions.
+ It was suggested that rather than have this requirement, that
+ VM place itself in a suitable state before performing an
+ operation. This makes considerable sense since each VM
+ knows its requirements and can most easily arrange a
+ safe state.
+ <p/>
+ The ability to externally suspend/resume threads will, of
+ course, remain. The ability to enable/disable garbage collection will not.
+ <p/>
+ This issue is resolved--suspend will not
+ be required. The spec has been updated to reflect this.
+ </intro>
+
+ <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling">
+ There are a variety of approaches to sampling call stacks.
+ The biggest bifurcation is between VM controlled and agent
+ controlled.
+ <p/>
+ This issue is resolved--agent controlled
+ sampling will be the approach.
+ </intro>
+
+ <intro id="threadRepresentation" label="Resolved Issue: Thread Representation">
+ JVMDI represents threads as jthread. JVMPI primarily
+ uses JNIEnv* to represent threads.
+ <p/>
+ The Expert Group has chosen jthread as the representation
+ for threads in <jvmti/>.
+ JNIEnv* is sent by
+ events since it is needed to JNI functions. JNIEnv, per the
+ JNI spec, are not supposed to be used outside their thread.
+ </intro>
+
+ <intro id="design" label="Resolved Issue: Method Representation">
+ The JNI spec allows an implementation to depend on jclass/jmethodID
+ pairs, rather than simply a jmethodID, to reference a method.
+ JVMDI, for consistency, choose the same representation.
+ JVMPI, however, specifies that a jmethodID alone maps to a
+ method. Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store
+ pointers in jmethodIDs, and as a result, a jmethodID is sufficient.
+ In fact, any JVM implementation that supports JVMPI must have
+ such a representation.
+ <jvmti/> will use jmethodID as a unique representation of a method
+ (no jclass is used).
+ There should be efficiency gains, particularly in
+ functionality like stack dumping, to this representation.
+ <p/>
+ Note that fields were not used in JVMPI and that the access profile
+ of fields differs from methods--for implementation efficiency
+ reasons, a jclass/jfieldID pair will still be needed for field
+ reference.
+ </intro>
+
+ <intro id="localReferenceIssue" label="Resolved Issue: Local References">
+ Functions return local references.
+ </intro>
+
+ <intro id="frameRep" label="Resolved Issue: Representation of frames">
+ In JVMDI, a frame ID is used to represent a frame. Problem with this
+ is that a VM must track when a frame becomes invalid, a far better
+ approach, and the one used in <jvmti/>, is to reference frames by depth.
+ </intro>
+
+ <intro id="requiredCapabilities" label="Issue: Required Capabilities">
+ Currently, having a required capabilities means that the functionality
+ is optional. Capabilities are useful even for required functionality
+ since they can inform the VM is needed set-up. Thus, there should be
+ a set of capabilities that a conformant implementation must provide
+ (if requested during Agent_OnLoad).
+ </intro>
+
+ <intro id="taghint" label="Proposal: add tag hint function">
+ A hint of the percentage of objects that will be tagged would
+ help the VM pick a good implementation.
+ </intro>
+
+ <intro id="moreMonitorQueries" label="Request: More Monitor Quires">
+ How difficult or easy would be to extend the monitor_info category to include
+ <pre>
+ - current number of monitors
+ - enumeration of monitors
+ - enumeration of threads waiting on a given monitor
+ </pre>
+ The reason for my question is the fact that current get_monitor_info support
+ requires the agent to specify a given thread to get the info which is probably
+ OK in the profiling/debugging space, while in the monitoring space the agent
+ could be watching the monitor list and then decide which thread to ask for
+ the info. You might ask why is this important for monitoring .... I think it
+ can aid in the detection/prediction of application contention caused by hot-locks.
+ </intro>
+</issuessection>
+
+<changehistory id="ChangeHistory" update="09/05/07">
+ <intro>
+ The <jvmti/> specification is an evolving document with major, minor,
+ and micro version numbers.
+ A released version of the specification is uniquely identified
+ by its major and minor version.
+ The functions, events, and capabilities in this specification
+ indicate a "Since" value which is the major and minor version in
+ which it was introduced.
+ The version of the specification implemented by the VM can
+ be retrieved at runtime with the <functionlink id="GetVersionNumber"/>
+ function.
+ </intro>
+ <change date="14 Nov 2002">
+ Converted to XML document.
+ </change>
+ <change date="14 Nov 2002">
+ Elided heap dump functions (for now) since what was there
+ was wrong.
+ </change>
+ <change date="18 Nov 2002">
+ Added detail throughout.
+ </change>
+ <change date="18 Nov 2002">
+ Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE.
+ </change>
+ <change date="19 Nov 2002">
+ Added AsyncGetStackTrace.
+ </change>
+ <change date="19 Nov 2002">
+ Added jframeID return to GetStackTrace.
+ </change>
+ <change date="19 Nov 2002">
+ Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there
+ since they are redundant with GetStackTrace.
+ </change>
+ <change date="19 Nov 2002">
+ Elided ClearAllBreakpoints since it has always been redundant.
+ </change>
+ <change date="19 Nov 2002">
+ Added GetSystemProperties.
+ </change>
+ <change date="19 Nov 2002">
+ Changed the thread local storage functions to use jthread.
+ </change>
+ <change date="20 Nov 2002">
+ Added GetJLocationFormat.
+ </change>
+ <change date="22 Nov 2002">
+ Added events and introductory text.
+ </change>
+ <change date="22 Nov 2002">
+ Cross reference type and constant definitions.
+ </change>
+ <change date="24 Nov 2002">
+ Added DTD.
+ </change>
+ <change date="24 Nov 2002">
+ Added capabilities function section.
+ </change>
+ <change date="29 Nov 2002">
+ Assign capabilities to each function and event.
+ </change>
+ <change date="29 Nov 2002">
+ Add <internallink id="jniIntercept">JNI interception functions</internallink>.
+ </change>
+ <change date="30 Nov 2002">
+ Auto generate SetEventNotificationMode capabilities.
+ </change>
+ <change date="30 Nov 2002">
+ Add <eventlink id="VMObjectAlloc"></eventlink> event.
+ </change>
+ <change date="30 Nov 2002">
+ Add <eventlink id="DynamicCodeGenerated"></eventlink> event.
+ </change>
+ <change date="30 Nov 2002">
+ Add const to declarations.
+ </change>
+ <change date="30 Nov 2002">
+ Change method exit and frame pop to send on exception.
+ </change>
+ <change date="1 Dec 2002">
+ Add ForceGarbageCollection.
+ </change>
+ <change date="2 Dec 2002">
+ Redo Xrun section; clarify GetStackTrace and add example;
+ Fix width problems; use "agent" consistently.
+ </change>
+ <change date="8 Dec 2002">
+ Remove previous start-up intro.
+ Add <internallink id="environments"><jvmti/> Environments</internallink>
+ section.
+ </change>
+ <change date="8 Dec 2002">
+ Add <functionlink id="DisposeEnvironment"></functionlink>.
+ </change>
+ <change date="9 Dec 2002">
+ Numerous minor updates.
+ </change>
+ <change date="15 Dec 2002">
+ Add heap profiling functions added:
+ get/set annotation, iterate live objects/heap.
+ Add heap profiling functions place holder added:
+ heap roots.
+ Heap profiling event added: object free.
+ Heap profiling event redesigned: vm object allocation.
+ Heap profiling event placeholders added: garbage collection start/finish.
+ Native method bind event added.
+ </change>
+ <change date="19 Dec 2002">
+ Revamp suspend/resume functions.
+ Add origin information with jvmdi tag.
+ Misc fixes.
+ </change>
+ <change date="24 Dec 2002">
+ Add semantics to types.
+ </change>
+ <change date="27 Dec 2002">
+ Add local reference section.
+ Autogenerate parameter descriptions from types.
+ </change>
+ <change date="28 Dec 2002">
+ Document that RunAgentThread sends threadStart.
+ </change>
+ <change date="29 Dec 2002">
+ Remove redundant local ref and dealloc warning.
+ Convert GetRawMonitorName to allocated buffer.
+ Add GenerateEvents.
+ </change>
+ <change date="30 Dec 2002">
+ Make raw monitors a type and rename to "jrawMonitorID".
+ </change>
+ <change date="1 Jan 2003">
+ Include origin information.
+ Clean-up JVMDI issue references.
+ Remove Deallocate warnings which are now automatically generated.
+ </change>
+ <change date="2 Jan 2003">
+ Fix representation issues for jthread.
+ </change>
+ <change date="3 Jan 2003">
+ Make capabilities buffered out to 64 bits - and do it automatically.
+ </change>
+ <change date="4 Jan 2003">
+ Make constants which are enumeration into enum types.
+ Parameters now of enum type.
+ Clean-up and index type section.
+ Replace remaining datadef entities with callback.
+ </change>
+ <change date="7 Jan 2003">
+ Correct GenerateEvents description.
+ More internal semantics work.
+ </change>
+ <change date="9 Jan 2003">
+ Replace previous GetSystemProperties with two functions
+ which use allocated information instead fixed.
+ Add SetSystemProperty.
+ More internal semantics work.
+ </change>
+ <change date="12 Jan 2003">
+ Add varargs to end of SetEventNotificationMode.
+ </change>
+ <change date="20 Jan 2003">
+ Finish fixing spec to reflect that alloc sizes are jlong.
+ </change>
+ <change date="22 Jan 2003">
+ Allow NULL as RunAgentThread arg.
+ </change>
+ <change date="22 Jan 2003">
+ Fixed names to standardized naming convention
+ Removed AsyncGetStackTrace.
+ </change>
+ <change date="29 Jan 2003">
+ Since we are using jthread, removed GetThread.
+ </change>
+ <change date="31 Jan 2003">
+ Change GetFieldName to allow NULLs like GetMethodName.
+ </change>
+ <change date="29 Feb 2003" version="v40">
+ Rewrite the introductory text, adding sections on
+ start-up, environments and bytecode instrumentation.
+ Change the command line arguments per EG discussions.
+ Add an introduction to the capabilities section.
+ Add the extension mechanism category and functions.
+ Mark for deletion, but clarified anyhow, SuspendAllThreads.
+ Rename IterateOverLiveObjects to IterateOverReachableObjects and
+ change the text accordingly.
+ Clarify IterateOverHeap.
+ Clarify CompiledMethodLoad.
+ Discuss prerequisite state for Calling Functions.
+ Clarify SetAllocationHooks.
+ Added issues ("To be resolved:") through-out.
+ And so on...
+ </change>
+ <change date="6 Mar 2003" version="v41">
+ Remove struct from the call to GetOwnedMonitorInfo.
+ Automatically generate most error documentation, remove
+ (rather broken) hand written error doc.
+ Better describe capability use (empty initial set).
+ Add min value to jint params.
+ Remove the capability can_access_thread_local_storage.
+ Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY;
+ same for *NOT_IMPLEMENTED.
+ Description fixes.
+ </change>
+ <change date="8 Mar 2003" version="v42">
+ Rename GetClassSignature to GetClassName.
+ Rename IterateOverClassObjects to IterateOverInstancesOfClass.
+ Remove GetMaxStack (operand stack isn't used in <jvmti/>).
+ Description fixes: define launch-time, remove native frame pop
+ from PopFrame, and assorted clarifications.
+ </change>
+ <change date="8 Mar 2003" version="v43">
+ Fix minor editing problem.
+ </change>
+ <change date="10 Mar 2003" version="v44">
+ Add phase information.
+ Remap (compact) event numbers.
+ </change>
+ <change date="11 Mar 2003" version="v45">
+ More phase information - allow "any".
+ Elide raw monitor queries and events.
+ Minor description fixes.
+ </change>
+ <change date="12 Mar 2003" version="v46">
+ Add GetPhase.
+ Use "phase" through document.
+ Elide GetRawMonitorName.
+ Elide GetObjectMonitors.
+ </change>
+ <change date="12 Mar 2003" version="v47">
+ Fixes from link, XML, and spell checking.
+ Auto-generate the callback structure.
+ </change>
+ <change date="13 Mar 2003" version="v48">
+ One character XML fix.
+ </change>
+ <change date="13 Mar 2003" version="v49">
+ Change function parameter names to be consistent with
+ event parameters (fooBarBaz becomes foo_bar_baz).
+ </change>
+ <change date="14 Mar 2003" version="v50">
+ Fix broken link. Fix thread markers.
+ </change>
+ <change date="14 Mar 2003" version="v51">
+ Change constants so they are under 128 to workaround
+ compiler problems.
+ </change>
+ <change date="23 Mar 2003" version="v52">
+ Overhaul capabilities. Separate GetStackTrace into
+ GetStackTrace and GetStackFrames.
+ </change>
+ <change date="8 Apr 2003" version="v54">
+ Use depth instead of jframeID to reference frames.
+ Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames.
+ Remove frame arg from events.
+ </change>
+ <change date="9 Apr 2003" version="v55">
+ Remove GetObjectWithAnnotation since tests show bufferred approach more efficient.
+ Add missing annotation_count to GetObjectsWithAnnotations
+ </change>
+ <change date="10 Apr 2003" version="v56">
+ Remove confusing parenthetical statement in GetObjectsWithAnnotations
+ </change>
+ <change date="13 Apr 2003" version="v58">
+ Replace jclass/jmethodID representation of method with simply jmethodID;
+ Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate.
+ Replace can_access_frames with can_access_local_variables; remove from purely stack access.
+ Use can_get_synthetic_attribute; fix description.
+ Clarify that zero length arrays must be deallocated.
+ Clarify RelinquishCapabilities.
+ Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE.
+ </change>
+ <change date="27 Apr 2003" version="v59">
+ Remove lingering indirect references to OBSOLETE_METHOD_ID.
+ </change>
+ <change date="4 May 2003" version="v60">
+ Allow DestroyRawMonitor during OnLoad.
+ </change>
+ <change date="7 May 2003" version="v61">
+ Added not monitor owner error return to DestroyRawMonitor.
+ </change>
+ <change date="13 May 2003" version="v62">
+ Clarify semantics of raw monitors.
+ Change flags on <code>GetThreadStatus</code>.
+ <code>GetClassLoader</code> return NULL for the bootstrap class loader.
+ Add <code>GetClassName</code> issue.
+ Define local variable signature.
+ Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>.
+ Remove over specification in <code>GetObjectsWithAnnotations</code>.
+ Elide <code>SetAllocationHooks</code>.
+ Elide <code>SuspendAllThreads</code>.
+ </change>
+ <change date="14 May 2003" version="v63">
+ Define the data type <code>jvmtiEventCallbacks</code>.
+ Zero length allocations return NULL.
+ Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>.
+ Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED.
+ </change>
+ <change date="15 May 2003" version="v64">
+ Better wording, per review.
+ </change>
+ <change date="15 May 2003" version="v65">
+ First Alpha.
+ Make jmethodID and jfieldID unique, jclass not used.
+ </change>
+ <change date="27 May 2003" version="v66">
+ Fix minor XSLT errors.
+ </change>
+ <change date="13 June 2003" version="v67">
+ Undo making jfieldID unique (jmethodID still is).
+ </change>
+ <change date="17 June 2003" version="v68">
+ Changes per June 11th Expert Group meeting --
+ Overhaul Heap functionality: single callback,
+ remove GetHeapRoots, add reachable iterators,
+ and rename "annotation" to "tag".
+ NULL thread parameter on most functions is current
+ thread.
+ Add timers.
+ Remove ForceExit.
+ Add GetEnvironmentLocalStorage.
+ Add verbose flag and event.
+ Add AddToBootstrapClassLoaderSearch.
+ Update ClassFileLoadHook.
+ </change>
+ <change date="18 June 2003" version="v69">
+ Clean up issues sections.
+ Rename GetClassName back to GetClassSignature and
+ fix description.
+ Add generic signature to GetClassSignature,
+ GetFieldSignature, GetMethodSignature, and
+ GetLocalVariableTable.
+ Elide EstimateCostOfCapabilities.
+ Clarify that the system property functions operate
+ on the VM view of system properties.
+ Clarify Agent_OnLoad.
+ Remove "const" from JNIEnv* in events.
+ Add metadata accessors.
+ </change>
+ <change date="18 June 2003" version="v70">
+ Add start_depth to GetStackTrace.
+ Move system properties to a new category.
+ Add GetObjectSize.
+ Remove "X" from command line flags.
+ XML, HTML, and spell check corrections.
+ </change>
+ <change date="19 June 2003" version="v71">
+ Fix JVMTI_HEAP_ROOT_THREAD to be 6.
+ Make each synopsis match the function name.
+ Fix unclear wording.
+ </change>
+ <change date="26 June 2003" version="v72">
+ SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value
+ to be set to NULL.
+ NotifyFramePop, GetFrameLocationm and all the local variable operations
+ needed to have their wording about frames fixed.
+ Grammar and clarity need to be fixed throughout.
+ Capitalization and puntuation need to be consistent.
+ Need micro version number and masks for accessing major, minor, and micro.
+ The error code lists should indicate which must be returned by
+ an implementation.
+ The command line properties should be visible in the properties functions.
+ Disallow popping from the current thread.
+ Allow implementations to return opaque frame error when they cannot pop.
+ The NativeMethodBind event should be sent during any phase.
+ The DynamicCodeGenerated event should be sent during any phase.
+ The following functions should be allowed to operate before VMInit:
+ Set/GetEnvironmentLocalStorage
+ GetMethodDeclaringClass
+ GetClassSignature
+ GetClassModifiers
+ IsInterface
+ IsArrayClass
+ GetMethodName
+ GetMethodModifiers
+ GetMaxLocals
+ GetArgumentsSize
+ GetLineNumberTable
+ GetMethodLocation
+ IsMethodNative
+ IsMethodSynthetic.
+ Other changes (to XSL):
+ Argument description should show asterisk after not before pointers.
+ NotifyFramePop, GetFrameLocationm and all the local variable operations
+ should hsve the NO_MORE_FRAMES error added.
+ Not alive threads should have a different error return than invalid thread.
+ </change>
+ <change date="7 July 2003" version="v73">
+ VerboseOutput event was missing message parameter.
+ Minor fix-ups.
+ </change>
+ <change date="14 July 2003" version="v74">
+ Technical Publications Department corrections.
+ Allow thread and environment local storage to be set to NULL.
+ </change>
+ <change date="23 July 2003" version="v75">
+ Use new Agent_OnLoad rather than overloaded JVM_OnLoad.
+ Add JNICALL to callbacks (XSL).
+ Document JNICALL requirement for both events and callbacks (XSL).
+ Restrict RedefineClasses to methods and attributes.
+ Elide the VerboseOutput event.
+ VMObjectAlloc: restrict when event is sent and remove method parameter.
+ Finish loose ends from Tech Pubs edit.
+ </change>
+ <change date="24 July 2003" version="v76">
+ Change ClassFileLoadHook event to send the class instead of a boolean of redefine.
+ </change>
+ <change date="24 July 2003" version="v77">
+ XML fixes.
+ Minor text clarifications and corrections.
+ </change>
+ <change date="24 July 2003" version="v78">
+ Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>.
+ Clarify that stack frames are JVM Spec frames.
+ Split can_get_source_info into can_get_source_file_name, can_get_line_numbers,
+ and can_get_source_debug_extension.
+ PopFrame cannot have a native calling method.
+ Removed incorrect statement in GetClassloaderClasses
+ (see http://java.sun.com/docs/books/vmspec/2nd-edition/html/ConstantPool.doc.html#79383).
+ </change>
+ <change date="24 July 2003" version="v79">
+ XML and text fixes.
+ Move stack frame description into Stack Frame category.
+ </change>
+ <change date="26 July 2003" version="v80">
+ Allow NULL (means bootstrap loader) for GetClassloaderClasses.
+ Add new heap reference kinds for references from classes.
+ Add timer information struct and query functions.
+ Add AvailableProcessors.
+ Rename GetOtherThreadCpuTime to GetThreadCpuTime.
+ Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE
+ to SetEventNotification mode.
+ Add initial thread to the VM_INIT event.
+ Remove platform assumptions from AddToBootstrapClassLoaderSearch.
+ </change>
+ <change date="26 July 2003" version="v81">
+ Grammar and clarity changes per review.
+ </change>
+ <change date="27 July 2003" version="v82">
+ More grammar and clarity changes per review.
+ Add Agent_OnUnload.
+ </change>
+ <change date="28 July 2003" version="v83">
+ Change return type of Agent_OnUnload to void.
+ </change>
+ <change date="28 July 2003" version="v84">
+ Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT.
+ </change>
+ <change date="28 July 2003" version="v85">
+ Steal java.lang.Runtime.availableProcessors() wording for
+ AvailableProcessors().
+ Guarantee that zero will never be an event ID.
+ Remove some issues which are no longer issues.
+ Per review, rename and more completely document the timer
+ information functions.
+ </change>
+ <change date="29 July 2003" version="v86">
+ Non-spec visible change to XML controlled implementation:
+ SetThreadLocalStorage must run in VM mode.
+ </change>
+ <change date="5 August 2003" version="0.1.87">
+ Add GetErrorName.
+ Add varargs warning to jvmtiExtensionEvent.
+ Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent.
+ Remove unused can_get_exception_info capability.
+ Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction.
+ Fix jvmtiExtensionFunctionInfo.func declared type.
+ Extension function returns error code.
+ Use new version numbering.
+ </change>
+ <change date="5 August 2003" version="0.2.88">
+ Remove the ClassUnload event.
+ </change>
+ <change date="8 August 2003" version="0.2.89">
+ Heap reference iterator callbacks return an enum that
+ allows outgoing object references to be ignored.
+ Allow JNIEnv as a param type to extension events/functions.
+ </change>
+ <change date="15 August 2003" version="0.2.90">
+ Fix a typo.
+ </change>
+ <change date="2 September 2003" version="0.2.91">
+ Remove all metadata functions: GetClassMetadata,
+ GetFieldMetadata, and GetMethodMetadata.
+ </change>
+ <change date="1 October 2003" version="0.2.92">
+ Mark the functions Allocate. Deallocate, RawMonitor*,
+ SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage
+ as safe for use in heap callbacks and GC events.
+ </change>
+ <change date="24 November 2003" version="0.2.93">
+ Add pass through opaque user data pointer to heap iterate
+ functions and callbacks.
+ In the CompiledMethodUnload event, send the code address.
+ Add GarbageCollectionOccurred event.
+ Add constant pool reference kind.
+ Mark the functions CreateRawMonitor and DestroyRawMonitor
+ as safe for use in heap callbacks and GC events.
+ Clarify: VMDeath, GetCurrentThreadCpuTimerInfo,
+ GetThreadCpuTimerInfo, IterateOverReachableObjects,
+ IterateOverObjectsReachableFromObject, GetTime and
+ JVMTI_ERROR_NULL_POINTER.
+ Add missing errors to: GenerateEvents and
+ AddToBootstrapClassLoaderSearch.
+ Fix description of ClassFileLoadHook name parameter.
+ In heap callbacks and GC/ObjectFree events, specify
+ that only explicitly allowed functions can be called.
+ Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime,
+ GetTimerInfo, and GetTime during callback.
+ Allow calling SetTag/GetTag during the onload phase.
+ SetEventNotificationMode, add: error attempted inappropriate
+ thread level control.
+ Remove jvmtiExceptionHandlerEntry.
+ Fix handling of native methods on the stack --
+ location_ptr param of GetFrameLocation, remove
+ JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation,
+ jvmtiFrameInfo.location, and jlocation.
+ Remove typo (from JVMPI) implying that the MonitorWaited
+ event is sent on sleep.
+ </change>
+ <change date="25 November 2003" version="0.2.94">
+ Clarifications and typos.
+ </change>
+ <change date="3 December 2003" version="0.2.95">
+ Allow NULL user_data in heap iterators.
+ </change>
+ <change date="28 January 2004" version="0.2.97">
+ Add GetThreadState, deprecate GetThreadStatus.
+ </change>
+ <change date="29 January 2004" version="0.2.98">
+ INVALID_SLOT and TYPE_MISMATCH errors should be optional.
+ </change>
+ <change date="12 February 2004" version="0.2.102">
+ Remove MonitorContendedExit.
+ Added JNIEnv parameter to VMObjectAlloc.
+ Clarified definition of class_tag and referrer_index
+ parameters to heap callbacks.
+ </change>
+ <change date="16 Febuary 2004" version="0.2.103">
+ Document JAVA_TOOL_OPTIONS.
+ </change>
+ <change date="17 Febuary 2004" version="0.2.105">
+ Divide start phase into primordial and start.
+ Add VMStart event
+ Change phase associations of functions and events.
+ </change>
+ <change date="18 Febuary 2004" version="0.3.6">
+ Elide deprecated GetThreadStatus.
+ Bump minor version, subtract 100 from micro version
+ </change>
+ <change date="18 Febuary 2004" version="0.3.7">
+ Document that timer nanosecond values are unsigned.
+ Clarify text having to do with native methods.
+ </change>
+ <change date="19 Febuary 2004" version="0.3.8">
+ Fix typos.
+ Remove elided deprecated GetThreadStatus.
+ </change>
+ <change date="23 Febuary 2004" version="0.3.9">
+ Require NotifyFramePop to act on suspended threads.
+ </change>
+ <change date="24 Febuary 2004" version="0.3.10">
+ Add capabilities
+ (<internallink id="jvmtiCapabilities.can_redefine_any_class"
+ ><code>can_redefine_any_class</code></internallink>
+ and
+ <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events"
+ ><code>can_generate_all_class_hook_events</code></internallink>)
+ and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>)
+ which allow some classes to be unmodifiable.
+ </change>
+ <change date="28 Febuary 2004" version="0.3.11">
+ Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode.
+ </change>
+ <change date="8 March 2004" version="0.3.12">
+ Clarified CompiledMethodUnload so that it is clear the event
+ may be posted after the class has been unloaded.
+ </change>
+ <change date="5 March 2004" version="0.3.13">
+ Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize.
+ </change>
+ <change date="13 March 2004" version="0.3.14">
+ Added guideline for the use of the JNI FindClass function in event
+ callback functions.
+ </change>
+ <change date="15 March 2004" version="0.3.15">
+ Add GetAllStackTraces and GetThreadListStackTraces.
+ </change>
+ <change date="19 March 2004" version="0.3.16">
+ ClassLoad and ClassPrepare events can be posted during start phase.
+ </change>
+ <change date="25 March 2004" version="0.3.17">
+ Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable,
+ GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes.
+ </change>
+ <change date="29 March 2004" version="0.3.18">
+ Return the timer kind in the timer information structure.
+ </change>
+ <change date="31 March 2004" version="0.3.19">
+ Spec clarifications:
+ JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>.
+ ForceGarbageCollection does not run finalizers.
+ The context of the specification is the Java platform.
+ Warn about early instrumentation.
+ </change>
+ <change date="1 April 2004" version="0.3.20">
+ Refinements to the above clarifications and
+ Clarify that an error returned by Agent_OnLoad terminates the VM.
+ </change>
+ <change date="1 April 2004" version="0.3.21">
+ Array class creation does not generate a class load event.
+ </change>
+ <change date="7 April 2004" version="0.3.22">
+ Align thread state hierarchy more closely with java.lang.Thread.State.
+ </change>
+ <change date="12 April 2004" version="0.3.23">
+ Clarify the documentation of thread state.
+ </change>
+ <change date="19 April 2004" version="0.3.24">
+ Remove GarbageCollectionOccurred event -- can be done by agent.
+ </change>
+ <change date="22 April 2004" version="0.3.25">
+ Define "command-line option".
+ </change>
+ <change date="29 April 2004" version="0.3.26">
+ Describe the intended use of bytecode instrumentation.
+ Fix description of extension event first parameter.
+ </change>
+ <change date="30 April 2004" version="0.3.27">
+ Clarification and typos.
+ </change>
+ <change date="18 May 2004" version="0.3.28">
+ Remove DataDumpRequest event.
+ </change>
+ <change date="18 May 2004" version="0.3.29">
+ Clarify RawMonitorWait with zero timeout.
+ Clarify thread state after RunAgentThread.
+ </change>
+ <change date="24 May 2004" version="0.3.30">
+ Clean-up: fix bad/old links, etc.
+ </change>
+ <change date="30 May 2004" version="0.3.31">
+ Clarifications including:
+ All character strings are modified UTF-8.
+ Agent thread visibiity.
+ Meaning of obsolete method version.
+ Thread invoking heap callbacks,
+ </change>
+ <change date="1 June 2004" version="1.0.32">
+ Bump major.minor version numbers to "1.0".
+ </change>
+ <change date="2 June 2004" version="1.0.33">
+ Clarify interaction between ForceGarbageCollection
+ and ObjectFree.
+ </change>
+ <change date="6 June 2004" version="1.0.34">
+ Restrict AddToBootstrapClassLoaderSearch and
+ SetSystemProperty to the OnLoad phase only.
+ </change>
+ <change date="11 June 2004" version="1.0.35">
+ Fix typo in SetTag.
+ </change>
+ <change date="18 June 2004" version="1.0.36">
+ Fix trademarks.
+ Add missing parameter in example GetThreadState usage.
+ </change>
+ <change date="4 August 2004" version="1.0.37">
+ Copyright updates.
+ </change>
+ <change date="5 November 2004" version="1.0.38">
+ Add missing function table layout.
+ Add missing description of C++ member function format of functions.
+ Clarify that name in CFLH can be NULL.
+ Released as part of <tm>J2SE</tm> 5.0.
+ </change>
+ <change date="24 April 2005" version="1.1.47">
+ Bump major.minor version numbers to "1.1".
+ Add ForceEarlyReturn* functions.
+ Add GetOwnedMonitorStackDepthInfo function.
+ Add GetCurrentThread function.
+ Add "since" version marker.
+ Add AddToSystemClassLoaderSearch.
+ Allow AddToBootstrapClassLoaderSearch be used in live phase.
+ Fix historic rubbish in the descriptions of the heap_object_callback
+ parameter of IterateOverHeap and IterateOverInstancesOfClass functions;
+ disallow NULL for this parameter.
+ Clarify, correct and make consistent: wording about current thread,
+ opaque frames and insufficient number of frames in PopFrame.
+ Consistently use "current frame" rather than "topmost".
+ Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal*
+ by making them compatible with those in ForceEarlyReturn*.
+ Many other clarifications and wording clean ups.
+ </change>
+ <change date="25 April 2005" version="1.1.48">
+ Add GetConstantPool.
+ Switch references to the first edition of the VM Spec, to the seconds edition.
+ </change>
+ <change date="26 April 2005" version="1.1.49">
+ Clarify minor/major version order in GetConstantPool.
+ </change>
+ <change date="26 April 2005" version="1.1.50">
+ Add SetNativeMethodPrefix and SetNativeMethodPrefixes.
+ Reassign GetOwnedMonitorStackDepthInfo to position 153.
+ Break out Class Loader Search in its own documentation category.
+ Deal with overly long lines in XML source.
+ </change>
+ <change date="29 April 2005" version="1.1.51">
+ Allow agents be started in the live phase.
+ Added paragraph about deploying agents.
+ </change>
+ <change date="30 April 2005" version="1.1.52">
+ Add specification description to SetNativeMethodPrefix(es).
+ Better define the conditions on GetConstantPool.
+ </change>
+ <change date="30 April 2005" version="1.1.53">
+ Break out the GetClassVersionNumber function from GetConstantPool.
+ Clean-up the references to the VM Spec.
+ </change>
+ <change date="1 May 2005" version="1.1.54">
+ Allow SetNativeMethodPrefix(es) in any phase.
+ Add clarifications about the impact of redefinition on GetConstantPool.
+ </change>
+ <change date="2 May 2005" version="1.1.56">
+ Various clarifications to SetNativeMethodPrefix(es).
+ </change>
+ <change date="2 May 2005" version="1.1.57">
+ Add missing performance warning to the method entry event.
+ </change>
+ <change date="5 May 2005" version="1.1.58">
+ Remove internal JVMDI support.
+ </change>
+ <change date="8 May 2005" version="1.1.59">
+ Add <functionlink id="RetransformClasses"/>.
+ Revamp the bytecode instrumentation documentation.
+ Change <functionlink id="IsMethodObsolete"/> to no longer
+ require the can_redefine_classes capability.
+ </change>
+ <change date="11 May 2005" version="1.1.63">
+ Clarifications for retransformation.
+ </change>
+ <change date="11 May 2005" version="1.1.64">
+ Clarifications for retransformation, per review.
+ Lock "retransformation (in)capable" at class load enable time.
+ </change>
+ <change date="4 June 2005" version="1.1.67">
+ Add new heap functionity which supports reporting primitive values,
+ allows setting the referrer tag, and has more powerful filtering:
+ FollowReferences, IterateThroughHeap, and their associated
+ callbacks, structs, enums, and constants.
+ </change>
+ <change date="4 June 2005" version="1.1.68">
+ Clarification.
+ </change>
+ <change date="6 June 2005" version="1.1.69">
+ FollowReferences, IterateThroughHeap: Put callbacks in a struct;
+ Add missing error codes; reduce bits in the visit control flags.
+ </change>
+ <change date="14 June 2005" version="1.1.70">
+ More on new heap functionity: spec clean-up per review.
+ </change>
+ <change date="15 June 2005" version="1.1.71">
+ More on new heap functionity: Rename old heap section to Heap (1.0).
+ </change>
+ <change date="21 June 2005" version="1.1.72">
+ Fix typos.
+ </change>
+ <change date="27 June 2005" version="1.1.73">
+ Make referrer info structure a union.
+ </change>
+ <change date="9 September 2005" version="1.1.74">
+ In new heap functions:
+ Add missing superclass reference kind.
+ Use a single scheme for computing field indexes.
+ Remove outdated references to struct based referrer info.
+ </change>
+ <change date="12 September 2005" version="1.1.75">
+ Don't callback during FollowReferences on frivolous java.lang.Object superclass.
+ </change>
+ <change date="13 September 2005" version="1.1.76">
+ In string primitive callback, length now Unicode length.
+ In array and string primitive callbacks, value now "const".
+ Note possible compiler impacts on setting JNI function table.
+ </change>
+ <change date="13 September 2005" version="1.1.77">
+ GetClassVersionNumbers() and GetConstantPool() should return
+ error on array or primitive class.
+ </change>
+ <change date="14 September 2005" version="1.1.78">
+ Grammar fixes.
+ </change>
+ <change date="26 September 2005" version="1.1.79">
+ Add IsModifiableClass query.
+ </change>
+ <change date="9 February 2006" version="1.1.81">
+ Add referrer_class_tag parameter to jvmtiHeapReferenceCallback.
+ </change>
+ <change date="13 February 2006" version="1.1.82">
+ Doc fixes: update can_redefine_any_class to include retransform.
+ Clarify that exception events cover all Throwables.
+ In GetStackTrace, no test is done for start_depth too big if start_depth is zero,
+ Clarify fields reported in Primitive Field Callback -- static vs instance.
+ Repair confusing names of heap types, including callback names.
+ Require consistent usage of stack depth in the face of thread launch methods.
+ Note incompatibility of <jvmti/> memory management with other systems.
+ </change>
+ <change date="14 February 2006" version="1.1.85">
+ Fix typos and missing renames.
+ </change>
+ <change date="13 March 2006" version="1.1.86">
+ Clarify that jmethodIDs and jfieldIDs can be saved.
+ Clarify that Iterate Over Instances Of Class includes subclasses.
+ </change>
+ <change date="14 March 2006" version="1.1.87">
+ Better phrasing.
+ </change>
+ <change date="16 March 2006" version="1.1.88">
+ Match the referrer_index for static fields in Object Reference Callback
+ with the Reference Implementation (and all other known implementations);
+ that is, make it match the definition for instance fields.
+ In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover
+ an invalid thread in the list; and specify that not started threads
+ return empty stacks.
+ </change>
+ <change date="17 March 2006" version="1.1.89">
+ Typo.
+ </change>
+ <change date="25 March 2006" version="1.1.90">
+ Typo.
+ </change>
+ <change date="6 April 2006" version="1.1.91">
+ Remove restrictions on AddToBootstrapClassLoaderSearch and
+ AddToSystemClassLoaderSearch.
+ </change>
+ <change date="1 May 2006" version="1.1.93">
+ Changed spec to return -1 for monitor stack depth for the
+ implementation which can not determine stack depth.
+ </change>
+ <change date="3 May 2006" version="1.1.94">
+ Corrections for readability and accuracy courtesy of Alan Pratt of IBM.
+ List the object relationships reported in FollowReferences.
+ </change>
+ <change date="5 May 2006" version="1.1.95">
+ Clarify the object relationships reported in FollowReferences.
+ </change>
+ <change date="28 June 2006" version="1.1.98">
+ Clarify DisposeEnvironment; add warning.
+ Fix typos in SetLocalXXX "retrieve" => "set".
+ Clarify that native method prefixes must remain set while used.
+ Clarify that exactly one Agent_OnXXX is called per agent.
+ Clarify that library loading is independent from start-up.
+ Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
+ </change>
+ <change date="31 July 2006" version="1.1.99">
+ Clarify the interaction between functions and exceptions.
+ Clarify and give examples of field indices.
+ Remove confusing "That is" sentence from MonitorWait and MonitorWaited events.
+ Update links to point to Java 6.
+ </change>
+ <change date="6 August 2006" version="1.1.102">
+ Add ResourceExhaustedEvent.
+ </change>
+</changehistory>
+
+</specification>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
+sgml-general-insert-case:lower
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->