Mercurial > hg > truffle
diff src/share/vm/prims/jvmti.xml @ 0:a61af66fc99e jdk7-b24
Initial load
author | duke |
---|---|
date | Sat, 01 Dec 2007 00:00:00 +0000 |
parents | |
children | c18cbe5936b8 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/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: +-->