0N/A<?xml version="1.0" encoding="ISO-8859-1"?>

0N/A<?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>

0N/A

0N/A<!DOCTYPE specification [

0N/A <!ELEMENT specification (title, intro*, functionsection, errorsection,

0N/A eventsection, datasection, issuessection, changehistory)>

0N/A <!ATTLIST specification label CDATA #REQUIRED

0N/A majorversion CDATA #REQUIRED

0N/A minorversion CDATA #REQUIRED

0N/A microversion CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT title (#PCDATA|jvmti|tm)*>

0N/A <!ATTLIST title subtitle CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT intro ANY>

0N/A <!ATTLIST intro id CDATA #IMPLIED

0N/A label CDATA "">

0N/A

0N/A <!ELEMENT functionsection (intro*, category*)>

0N/A <!ATTLIST functionsection label CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*,

0N/A (function|callback|elide)*)>

0N/A <!ATTLIST category id CDATA #REQUIRED

0N/A label CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT function (synopsis, typedef*, description?, origin,

0N/A (capabilities|eventcapabilities),

0N/A parameters, errors)>

0N/A <!ATTLIST function id CDATA #REQUIRED

0N/A num CDATA #REQUIRED

0N/A phase (onload|onloadOnly|start|live|any) #IMPLIED

0N/A callbacksafe (safe|unsafe) #IMPLIED

0N/A impl CDATA #IMPLIED

0N/A hide CDATA #IMPLIED

0N/A jkernel (yes|no) #IMPLIED

0N/A since CDATA "1.0">

0N/A

0N/A <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|

0N/A jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void),

0N/A synopsis, description?, parameters)>

0N/A <!ATTLIST callback id CDATA #REQUIRED

0N/A since CDATA "1.0">

0N/A

0N/A <!ELEMENT synopsis (#PCDATA|jvmti)*>

0N/A

0N/A <!ELEMENT typedef (description?, field*)>

0N/A <!ATTLIST typedef id CDATA #REQUIRED

0N/A label CDATA #REQUIRED

0N/A since CDATA "1.0">

0N/A

0N/A <!ELEMENT uniontypedef (description?, field*)>

0N/A <!ATTLIST uniontypedef id CDATA #REQUIRED

0N/A label CDATA #REQUIRED

0N/A since CDATA "1.0">

0N/A

0N/A <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|

0N/A jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct),

0N/A description)>

0N/A <!ATTLIST field id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT capabilitiestypedef (description?, capabilityfield*)>

0N/A <!ATTLIST capabilitiestypedef id CDATA #REQUIRED

0N/A label CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT capabilityfield (description)>

0N/A <!ATTLIST capabilityfield id CDATA #REQUIRED

0N/A disp1 CDATA ""

0N/A disp2 CDATA ""

0N/A since CDATA "1.0">

0N/A

0N/A <!ELEMENT description ANY>

0N/A

0N/A <!ELEMENT capabilities (required*, capability*)>

0N/A

0N/A <!ELEMENT eventcapabilities EMPTY>

0N/A

0N/A <!ELEMENT required ANY>

0N/A <!ATTLIST required id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT capability ANY>

0N/A <!ATTLIST capability id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT parameters (param*)>

0N/A

0N/A <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|

0N/A jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype|

0N/A outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf),

0N/A description)>

0N/A <!ATTLIST param id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT jmethodID EMPTY>

0N/A <!ATTLIST jmethodID class CDATA #IMPLIED

0N/A native CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT jfieldID EMPTY>

0N/A <!ATTLIST jfieldID class CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT jclass EMPTY>

0N/A <!ATTLIST jclass method CDATA #IMPLIED

0N/A field CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT jframeID EMPTY>

0N/A <!ATTLIST jframeID thread CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT jrawMonitorID EMPTY>

0N/A

0N/A <!ELEMENT jthread EMPTY>

0N/A <!ATTLIST jthread started CDATA #IMPLIED

0N/A null CDATA #IMPLIED

0N/A frame CDATA #IMPLIED

0N/A impl CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT varargs EMPTY>

0N/A

0N/A <!ELEMENT jthreadGroup EMPTY>

0N/A <!ELEMENT jobject EMPTY>

0N/A <!ELEMENT jvalue EMPTY>

0N/A <!ELEMENT jchar EMPTY>

0N/A <!ELEMENT jint EMPTY>

0N/A <!ATTLIST jint min CDATA #IMPLIED>

0N/A <!ELEMENT jlong EMPTY>

0N/A <!ELEMENT jfloat EMPTY>

0N/A <!ELEMENT jdouble EMPTY>

0N/A <!ELEMENT jlocation EMPTY>

0N/A <!ELEMENT jboolean EMPTY>

0N/A <!ELEMENT char EMPTY>

0N/A <!ELEMENT uchar EMPTY>

0N/A <!ELEMENT size_t EMPTY>

0N/A <!ELEMENT void EMPTY>

0N/A <!ELEMENT enum (#PCDATA)*>

0N/A <!ELEMENT struct (#PCDATA)*>

0N/A

0N/A <!ELEMENT nullok ANY>

0N/A

0N/A <!ELEMENT ptrtype ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

0N/A jthreadGroup|jobject|jvalue), nullok?)>

0N/A

0N/A <!ELEMENT outptr ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

0N/A jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|

0N/A jlocation|jboolean|char|uchar|size_t|void), nullok?)>

0N/A

0N/A <!ELEMENT allocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

0N/A jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|

0N/A jlocation|jboolean|char|uchar|size_t|void), nullok?)>

0N/A <!ATTLIST allocbuf incount CDATA #IMPLIED

0N/A outcount CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT allocallocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

0N/A jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|

0N/A jlocation|jboolean|char|uchar|size_t|void), nullok?)>

0N/A <!ATTLIST allocallocbuf incount CDATA #IMPLIED

0N/A outcount CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT inptr (struct, nullok?)>

0N/A

0N/A <!ELEMENT inbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

0N/A jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|

0N/A jlocation|jboolean|char|uchar|size_t|void), nullok?)>

0N/A <!ATTLIST inbuf incount CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT outbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

0N/A jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|

0N/A jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)>

0N/A <!ATTLIST outbuf incount CDATA #IMPLIED

0N/A outcount CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT vmbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

0N/A jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|

0N/A jlocation|jboolean|char|uchar|size_t|void), nullok?)>

0N/A <!ATTLIST vmbuf incount CDATA #IMPLIED

0N/A outcount CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT agentbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

0N/A jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|

0N/A jlocation|jboolean|char|uchar|size_t|void), nullok?)>

0N/A <!ATTLIST agentbuf incount CDATA #IMPLIED

0N/A outcount CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT allocfieldbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

0N/A jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|

0N/A jlocation|jboolean|char|uchar|size_t|void))>

0N/A <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT errors (error*)>

0N/A

0N/A <!ELEMENT error ANY>

0N/A <!ATTLIST error id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT errorsection (intro*, errorcategory*)>

0N/A <!ATTLIST errorsection label CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT errorcategory (intro*, errorid*)>

0N/A <!ATTLIST errorcategory id CDATA #REQUIRED

0N/A label CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT errorid ANY>

0N/A <!ATTLIST errorid id CDATA #REQUIRED

0N/A num CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT datasection (intro*, basetypes*)>

0N/A

0N/A <!ELEMENT basetypes (intro*, basetype*)>

0N/A <!ATTLIST basetypes id CDATA #REQUIRED

0N/A label CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT basetype (definition?,description)>

0N/A <!ATTLIST basetype id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT definition (#PCDATA|jvmti)*>

0N/A

0N/A <!ELEMENT eventsection (intro*, (event|elide)*)>

0N/A <!ATTLIST eventsection label CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT event (description, origin, typedef*, capabilities, parameters)>

0N/A <!ATTLIST event id CDATA #REQUIRED

0N/A label CDATA #REQUIRED

0N/A const CDATA #REQUIRED

0N/A num CDATA #REQUIRED

0N/A phase (onload|start|live|any) #IMPLIED

0N/A filtered (thread|global) #IMPLIED

0N/A since CDATA "1.0">

0N/A

0N/A <!ELEMENT issuessection (intro*)>

0N/A <!ATTLIST issuessection label CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT changehistory (intro*, change*)>

0N/A <!ATTLIST changehistory update CDATA #REQUIRED

0N/A id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT change ANY>

0N/A <!ATTLIST change date CDATA #REQUIRED

0N/A version CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*>

0N/A <!ATTLIST functionlink id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*>

0N/A <!ATTLIST datalink id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*>

0N/A <!ATTLIST typelink id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*>

0N/A <!ATTLIST fieldlink id CDATA #REQUIRED

0N/A struct CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*>

0N/A <!ATTLIST paramlink id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*>

0N/A <!ATTLIST eventlink id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*>

0N/A <!ATTLIST errorlink id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*>

0N/A <!ATTLIST externallink id CDATA #REQUIRED>

0N/A

2427N/A <!ELEMENT vmspec EMPTY>

2427N/A <!ATTLIST vmspec chapter CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*>

0N/A <!ATTLIST internallink id CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT functionphaselist EMPTY>

0N/A <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED>

0N/A

0N/A <!ELEMENT eventphaselist EMPTY>

0N/A <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED>

0N/A

0N/A <!ELEMENT issue ANY>

0N/A

0N/A <!ELEMENT rationale ANY>

0N/A

0N/A <!ELEMENT todo ANY>

0N/A

0N/A <!ELEMENT origin (#PCDATA)*>

0N/A

0N/A <!ELEMENT elide (intro|function|callback|event)*>

0N/A <!ATTLIST elide why CDATA #IMPLIED>

0N/A

0N/A <!ELEMENT constants (constant*)>

0N/A <!ATTLIST constants id CDATA #REQUIRED

0N/A label CDATA #REQUIRED

0N/A kind (enum|bits|const) #REQUIRED

0N/A since CDATA "1.0">

0N/A

0N/A <!ELEMENT constant ANY>

0N/A <!ATTLIST constant id CDATA #REQUIRED

0N/A num CDATA #REQUIRED>

0N/A

0N/A <!ELEMENT tm (#PCDATA)>

0N/A

0N/A <!ELEMENT i (#PCDATA|jvmti|tm)*>

0N/A

0N/A <!ELEMENT b (#PCDATA|jvmti|code)*>

0N/A

0N/A <!ELEMENT code (#PCDATA|space)*>

0N/A

0N/A <!ELEMENT pre ANY>

0N/A

0N/A <!ELEMENT space EMPTY>

0N/A

0N/A <!ELEMENT jvmti EMPTY>

0N/A

0N/A <!ELEMENT example (#PCDATA|i)*>

0N/A

0N/A <!ELEMENT br EMPTY>

0N/A

0N/A <!ELEMENT p EMPTY>

0N/A

0N/A <!ELEMENT dl (dt|dd)+>

0N/A

0N/A <!ELEMENT dd ANY>

0N/A

0N/A <!ELEMENT dt (#PCDATA|jvmti|code|i|b)*>

0N/A

0N/A <!ELEMENT table (tr)+>

0N/A

0N/A <!ELEMENT tr (td|th)*>

0N/A

0N/A <!ELEMENT td ANY>

0N/A <!ATTLIST td align (left|right|center) "center">

0N/A

0N/A <!ELEMENT th ANY>

0N/A <!ATTLIST th align (left|right|center) "center">

0N/A

0N/A <!ELEMENT ul (li)+>

0N/A <!ATTLIST ul type (disc|circle|square) "disc">

0N/A

0N/A <!ELEMENT li ANY>

0N/A ]>

0N/A

0N/A<specification label="JVM(TM) Tool Interface"

0N/A majorversion="1"

1895N/A minorversion="2"

1895N/A microversion="1">

0N/A <title subtitle="Version">

0N/A <tm>JVM</tm> Tool Interface

0N/A </title>

0N/A

0N/A <intro id="whatIs" label="What is the JVM Tool Interface?">

0N/A The <tm>JVM</tm> Tool Interface (<jvmti/>)

0N/A is a programming interface used by development and monitoring tools.

0N/A It provides both a way to inspect the state and

0N/A to control the execution of applications running in the

0N/A <tm>Java</tm> virtual machine (VM).

0N/A <p/>

0N/A <jvmti/> is intended to provide a VM interface for the full breadth of tools

0N/A that need access to VM state, including but not limited to: profiling,

0N/A debugging, monitoring, thread analysis, and coverage analysis tools.

0N/A <p/>

0N/A <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual

0N/A machine.

0N/A <p/>

0N/A <jvmti/> is a two-way interface.

0N/A A client of <jvmti/>, hereafter called an <i>agent</i>,

0N/A can be notified of

0N/A interesting occurrences through <internallink id="EventSection">events</internallink>.

0N/A <jvmti/>

0N/A can query and control the application through many

0N/A <internallink id="FunctionSection">functions</internallink>,

0N/A either in response to events or

0N/A independent of them.

0N/A <p/>

0N/A Agents run in the same process with and communicate directly with

0N/A the virtual machine executing

0N/A the application being examined. This communication is

0N/A through a native interface (<jvmti/>). The native in-process interface allows

0N/A maximal control with minimal intrusion on the part of a tool.

0N/A Typically, agents are relatively compact. They can be controlled

0N/A by a separate process which implements the bulk of a tool's

0N/A function without interfering with the target application's normal execution.

0N/A </intro>

0N/A

0N/A <intro id="architecture" label="Architecture">

0N/A Tools can be written directly to <jvmti/> or indirectly

0N/A through higher level interfaces.

0N/A The Java Platform Debugger Architecture includes <jvmti/>, but also

0N/A contains higher-level, out-of-process debugger interfaces. The higher-level

0N/A interfaces are more appropriate than <jvmti/> for many tools.

0N/A For more information on the Java Platform Debugger Architecture,

0N/A see the

0N/A <externallink id="http://java.sun.com/products/jpda/">Java

0N/A Platform Debugger Architecture website</externallink>.

0N/A </intro>

0N/A

0N/A <intro id="writingAgents" label="Writing Agents">

0N/A Agents can be written in any native language that supports C

0N/A language calling conventions and C or C++

0N/A definitions.

0N/A <p/>

0N/A The function, event, data type, and constant definitions needed for

0N/A using <jvmti/> are defined in the include file <code>jvmti.h</code>.

0N/A To use these definitions add the <tm>J2SE</tm> include directory

0N/A to your include path and add

0N/A <example>

0N/A#include &lt;jvmti.h&gt;

0N/A </example>

0N/A to your source code.

0N/A </intro>

0N/A

0N/A <intro id="deployingAgents" label="Deploying Agents">

0N/A An agent is deployed in a platform specific manner but is typically the

0N/A platform equivalent of a dynamic library. On the <tm>Windows</tm> operating

0N/A system, for example, an agent library is a "Dynamic Linked Library" (DLL).

0N/A On the <tm>Solaris</tm> Operating Environment, an agent library is a shared

0N/A object (<code>.so</code> file).

0N/A <p/>

0N/A An agent may be started at VM startup by specifying the agent library

0N/A name using a <internallink id="starting">command line option</internallink>.

0N/A Some implementations may support a mechanism to <internallink id="onattach">

0N/A start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.

0N/A The details of how this is initiated are implementation specific.

0N/A </intro>

0N/A

0N/A <intro id="starting" label="Agent Command Line Options">

0N/A The term "command-line option" is used below to

0N/A mean options supplied in the <code>JavaVMInitArgs</code> argument

0N/A to the <code>JNI_CreateJavaVM</code> function of the JNI

0N/A Invocation API.

0N/A <p/>

0N/A One of the two following

0N/A command-line options is used on VM startup to

0N/A properly load and run agents.

0N/A These arguments identify the library containing

0N/A the agent as well as an options

0N/A string to be passed in at startup.

0N/A <dl>

0N/A <dt><code>-agentlib:</code><i>&lt;agent-lib-name&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>

0N/A <dd>

0N/A The name following <code>-agentlib:</code> is the name of the

0N/A library to load. Lookup of the library, both its full name and location,

0N/A proceeds in a platform-specific manner.

0N/A Typically, the <i>&lt;agent-lib-name&gt;</i> is expanded to an

0N/A operating system specific file name.

0N/A The <i>&lt;options&gt;</i> will be passed to the agent on start-up.

0N/A For example, if the option

0N/A <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to

0N/A load the shared library <code>foo.dll</code> from the system <code>PATH</code>

0N/A under <tm>Windows</tm> or <code>libfoo.so</code> from the

0N/A <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment.

0N/A </dd>

0N/A <dt><code>-agentpath:</code><i>&lt;path-to-agent&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>

0N/A <dd>

0N/A The path following <code>-agentpath:</code> is the absolute path from which

0N/A to load the library.

0N/A No library name expansion will occur.

0N/A The <i>&lt;options&gt;</i> will be passed to the agent on start-up.

0N/A For example, if the option

0N/A <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to

0N/A load the shared library <code>c:\myLibs\foo.dll</code>.

0N/A </dd>

0N/A </dl>

0N/A The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink>

0N/A in the library will be invoked.

0N/A <p/>

0N/A Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>

0N/A will be searched for JNI native method implementations to facilitate the

0N/A use of Java programming language code in tools, as is needed for

0N/A <internallink id="bci">bytecode instrumentation</internallink>.

0N/A <p/>

0N/A The agent libraries will be searched after all other libraries have been

0N/A searched (agents wishing to override or intercept the native method

0N/A implementations of non-agent methods can use the

0N/A <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).

0N/A <p/>

0N/A These switches do the above and nothing more - they do not change the

0N/A state of the VM or <jvmti/>. No command line options are needed

0N/A to enable <jvmti/>

0N/A or aspects of <jvmti/>, this is handled programmatically

0N/A by the use of

0N/A <internallink id="capability">capabilities</internallink>.

0N/A </intro>

0N/A

0N/A <intro id="startup" label="Agent Start-Up">

0N/A The VM starts each agent by invoking a start-up function.

0N/A If the agent is started in the <code>OnLoad</code>

0N/A <functionlink id="GetPhase">phase</functionlink> the function

0N/A <internallink id="onload"><code>Agent_OnLoad</code></internallink>

0N/A will be invoked.

0N/A If the agent is started in the live

0N/A <functionlink id="GetPhase">phase</functionlink> the function

0N/A <internallink id="onattach"><code>Agent_OnAttach</code></internallink>

0N/A will be invoked.

0N/A Exactly one call to a start-up function is made per agent.

0N/A </intro>

0N/A

0N/A <intro id="onload" label="Agent Start-Up (OnLoad phase)">

0N/A If an agent is started during the <code>OnLoad</code> phase then its

0N/A agent library must export a start-up function with the following prototype:

0N/A <example>

0N/AJNIEXPORT jint JNICALL

0N/AAgent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>

0N/A The VM will start the agent by calling this function.

0N/A It will be called early enough in VM initialization that:

0N/A <ul>

0N/A <li><functionlink id="SetSystemProperty">system properties</functionlink>

0N/A may be set before they have been used in the start-up of the VM</li>

0N/A <li>the full set of

0N/A <internallink id="capability">capabilities</internallink>

0N/A is still available (note that capabilities that configure the VM

0N/A may only be available at this time--see the

0N/A <internallink id="capability">Capability function section</internallink>)</li>

0N/A <li>no bytecodes have executed</li>

0N/A <li>no classes have been loaded</li>

0N/A <li>no objects have been created</li>

0N/A </ul>

0N/A <p/>

0N/A The VM will call the <code>Agent_OnLoad</code> function with

0N/A <i>&lt;options&gt;</i> as the second argument -

0N/A that is, using the command-line option examples,

0N/A <code>"opt1,opt2"</code> will be passed to the <code>char *options</code>

0N/A argument of <code>Agent_OnLoad</code>.

0N/A The <code>options</code> argument is encoded as a

0N/A <internallink id="mUTF">modified UTF-8</internallink> string.

0N/A If <i>=&lt;options&gt;</i> is not specified,

0N/A a zero length string is passed to <code>options</code>.

0N/A The lifespan of the <code>options</code> string is the <code>Agent_OnLoad</code>

0N/A call. If needed beyond this time the string or parts of the string must

0N/A be copied.

0N/A The period between when <code>Agent_OnLoad</code> is called and when it

0N/A returns is called the <i>OnLoad phase</i>.

0N/A Since the VM is not initialized during the OnLoad

0N/A <functionlink id="GetPhase">phase</functionlink>,

0N/A the set of allowed operations

0N/A inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the

0N/A functionality available at this time).

0N/A The agent can safely process the options and set

0N/A event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once

0N/A the VM initialization event is received

0N/A (that is, the <eventlink id="VMInit">VMInit</eventlink>

0N/A callback is invoked), the agent

0N/A can complete its initialization.

0N/A <rationale>

0N/A Early startup is required so that agents can set the desired capabilities,

0N/A many of which must be set before the VM is initialized.

0N/A In JVMDI, the -Xdebug command-line option provided

0N/A very coarse-grain control of capabilities.

0N/A JVMPI implementations use various tricks to provide a single "JVMPI on" switch.

0N/A No reasonable command-line

0N/A option could provide the fine-grain of control required to balance needed capabilities vs

0N/A performance impact.

0N/A Early startup is also needed so that agents can control the execution

0N/A environment - modifying the file system and system properties to install

0N/A their functionality.

0N/A </rationale>

0N/A <p/>

0N/A The return value from <code>Agent_OnLoad</code> is used to indicate an error.

0N/A Any value other than zero indicates an error and causes termination of the VM.

0N/A </intro>

0N/A

0N/A <intro id="onattach" label="Agent Start-Up (Live phase)">

0N/A A VM may support a mechanism that allows agents to be started in the VM during the live

0N/A <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,

0N/A are implementation specific. For example, a tool may use some platform specific mechanism,

0N/A or implementation specific API, to attach to the running VM, and request it start a given

0N/A agent.

0N/A <p/>

0N/A If an agent is started during the live phase then its agent library

0N/A must export a start-up function

0N/A with the following prototype:

0N/A <example>

0N/AJNIEXPORT jint JNICALL

0N/AAgent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>

0N/A <p/>

0N/A The VM will start the agent by calling this function.

0N/A It will be called in the context of a thread

0N/A that is attached to the VM. The first argument <i>&lt;vm&gt;</i> is the Java VM.

0N/A The <i>&lt;options&gt;</i> argument is the startup options provided to the agent.

0N/A <i>&lt;options&gt;</i> is encoded as a <internallink id="mUTF">modified UTF-8

0N/A </internallink> string.

0N/A If startup options were not provided, a zero length string is passed to

0N/A <code>options</code>. The lifespan of the <code>options</code> string is the

0N/A <code>Agent_OnAttach</code> call. If needed beyond this time the string or parts of

0N/A the string must be copied.

0N/A <p/>

0N/A Note that some <internallink id="capability">capabilities</internallink>

0N/A may not be available in the live phase.

0N/A <p/>

0N/A The <code>Agent_OnAttach</code> function initializes the agent and returns a value

0N/A to the VM to indicate if an error occurred. Any value other than zero indicates an error.

0N/A An error does not cause the VM to terminate. Instead the VM ignores the error, or takes

0N/A some implementation specific action -- for example it might print an error to standard error,

0N/A or record the error in a system log.

0N/A </intro>

0N/A

0N/A <intro id="onunload" label="Agent Shutdown">

0N/A The library may optionally export a

0N/A shutdown function with the following prototype:

0N/A <example>

0N/AJNIEXPORT void JNICALL

0N/AAgent_OnUnload(JavaVM *vm)</example>

0N/A This function will be called by the VM when the library is about to be unloaded.

0N/A The library will be unloaded and this function will be called if some platform specific

0N/A mechanism causes the unload (an unload mechanism is not specified in this document)

0N/A or the library is (in effect) unloaded by the termination of the VM whether through

0N/A normal termination or VM failure, including start-up failure.

0N/A Uncontrolled shutdown is, of couse, an exception to this rule.

0N/A Note the distinction between this function and the

0N/A <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event

0N/A to be sent, the VM must have run at least to the point of initialization and a valid

0N/A <jvmti/> environment must exist which has set a callback for VMDeath

0N/A and enabled the event

0N/A None of these are required for <code>Agent_OnUnload</code> and this function

0N/A is also called if the library is unloaded for other reasons.

0N/A In the case that a VM Death event is sent, it will be sent before this

0N/A function is called (assuming this function is called due to VM termination).

0N/A This function can be used to clean-up resources allocated by the agent.

0N/A </intro>

0N/A

0N/A <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">

0N/A Since the command-line cannot always be accessed or modified, for example in embedded VMs

0N/A or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is

0N/A provided so that agents may be launched in these cases.

0N/A <p/>

0N/A Platforms which support environment variables or other named strings, may support the

0N/A <code>JAVA_TOOL_OPTIONS</code> variable. This variable will be broken into options at white-space

0N/A boundaries. White-space characters include space, tab, carriage-return, new-line,

0N/A vertical-tab, and form-feed. Sequences of white-space characters are considered

0N/A equivalent to a single white-space character. No white-space is included in the options

0N/A unless quoted. Quoting is as follows:

0N/A <ul>

0N/A <li>All characters enclosed between a pair of single quote marks (''), except a single

0N/A quote, are quoted.</li>

0N/A <li>Double quote characters have no special meaning inside a pair of single quote marks.</li>

0N/A <li>All characters enclosed between a pair of double quote marks (""), except a double

0N/A quote, are quoted.</li>

0N/A <li>Single quote characters have no special meaning inside a pair of double quote marks.</li>

0N/A <li>A quoted part can start or end anywhere in the variable.</li>

0N/A <li>White-space characters have no special meaning when quoted -- they are included in

0N/A the option like any other character and do not mark white-space boundaries.</li>

0N/A <li>The pair of quote marks is not included in the option.</li>

0N/A </ul>

0N/A <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied

0N/A in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is

0N/A a concern; for example, the Reference Implementation disables this feature on Unix systems when

0N/A the effective user or group ID differs from the real ID.

0N/A This feature is intended to support the initialization of tools -- specifically including the

0N/A launching of native or Java programming language agents. Multiple tools may wish to use this

0N/A feature, so the variable should not be overwritten, instead, options should be appended to

0N/A the variable. Note that since the variable is processed at the time of the JNI Invocation

0N/A API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled.

0N/A </intro>

0N/A

0N/A <intro id="environments" label="Environments">

0N/A The <jvmti/> specification supports the use of multiple simultaneous

0N/A <jvmti/> agents.

0N/A Each agent has its own <jvmti/> environment.

0N/A That is, the <jvmti/> state is

0N/A separate for each agent - changes to one environment do not affect the

0N/A others. The state of a <jvmti/>

0N/A environment includes:

0N/A <ul>

0N/A <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>

0N/A <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>

0N/A <li><internallink id="capability">the capabilities</internallink></li>

0N/A <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>

0N/A </ul>

0N/A Although their <jvmti/> state

0N/A is separate, agents inspect and modify the shared state

0N/A of the VM, they also share the native environment in which they execute.

0N/A As such, an agent can perturb the results of other agents or cause them

0N/A to fail. It is the responsibility of the agent writer to specify the level

0N/A of compatibility with other agents. <jvmti/> implementations are not capable

0N/A of preventing destructive interactions between agents. Techniques to reduce

0N/A the likelihood of these occurrences are beyond the scope of this document.

0N/A <p/>

0N/A An agent creates a <jvmti/> environment

0N/A by passing a <jvmti/> version

0N/A as the interface ID to the JNI Invocation API function

0N/A <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><code>GetEnv</code></externallink>.

0N/A See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink>

0N/A for more details on the creation and use of

0N/A <jvmti/> environments.

0N/A Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from

0N/A <internallink id="onload"><code>Agent_OnLoad</code></internallink>.

0N/A </intro>

0N/A

0N/A <intro id="bci" label="Bytecode Instrumentation">

0N/A This interface does not include some events that one might expect in an interface with

0N/A profiling support. Some examples include object allocation events and full speed

0N/A method enter and exit events. The interface instead provides support for

0N/A <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine

0N/A bytecode instructions which comprise the target program. Typically, these alterations

0N/A are to add "events" to the code of a method - for example, to add, at the beginning of a method,

0N/A a call to <code>MyProfiler.methodEntered()</code>.

0N/A Since the changes are purely additive, they do not modify application

0N/A state or behavior.

0N/A Because the inserted agent code is standard bytecodes, the VM can run at full speed,

0N/A optimizing not only the target program but also the instrumentation. If the

0N/A instrumentation does not involve switching from bytecode execution, no expensive

0N/A state transitions are needed. The result is high performance events.

0N/A This approach also provides complete control to the agent: instrumentation can be

0N/A restricted to "interesting" portions of the code (e.g., the end user's code) and

0N/A can be conditional. Instrumentation can run entirely in Java programming language

0N/A code or can call into the native agent. Instrumentation can simply maintain

0N/A counters or can statistically sample events.

0N/A <p/>

0N/A Instrumentation can be inserted in one of three ways:

0N/A <ul>

0N/A <li>

0N/A Static Instrumentation: The class file is instrumented before it

0N/A is loaded into the VM - for example, by creating a duplicate directory of

0N/A <code>*.class</code> files which have been modified to add the instrumentation.

0N/A This method is extremely awkward and, in general, an agent cannot know

0N/A the origin of the class files which will be loaded.

0N/A </li>

0N/A <li>

0N/A Load-Time Instrumentation: When a class file is loaded by the VM, the raw

0N/A bytes of the class file are sent for instrumentation to the agent.

0N/A The <eventlink id="ClassFileLoadHook"/>

0N/A event, triggered by the class load,

0N/A provides this functionality. This mechanism provides efficient

0N/A and complete access to one-time instrumentation.

0N/A </li>

0N/A <li>

0N/A Dynamic Instrumentation: A class which is already loaded (and possibly

0N/A even running) is modified. This optional feature is provided by the

0N/A <eventlink id="ClassFileLoadHook"/> event, triggered by calling the

0N/A <functionlink id="RetransformClasses"/> function.

0N/A Classes can be modified multiple times and can be returned to their

0N/A original state.

0N/A The mechanism allows instrumentation which changes during the

0N/A course of execution.

0N/A </li>

0N/A </ul>

0N/A <p/>

0N/A The class modification functionality provided in this interface

0N/A is intended to provide a mechanism for instrumentation

0N/A (the <eventlink id="ClassFileLoadHook"/> event

0N/A and the <functionlink id="RetransformClasses"/> function)

0N/A and, during development, for fix-and-continue debugging

0N/A (the <functionlink id="RedefineClasses"/> function).

0N/A <p/>

0N/A Care must be taken to avoid perturbing dependencies, especially when

0N/A instrumenting core classes. For example, an approach to getting notification

0N/A of every object allocation is to instrument the constructor on

0N/A <code>Object</code>. Assuming that the constructor is initially

0N/A empty, the constructor could be changed to:

0N/A <example>

0N/A public Object() {

0N/A MyProfiler.allocationTracker(this);

0N/A }

0N/A </example>

0N/A However, if this change was made using the

0N/A <eventlink id="ClassFileLoadHook"/>

0N/A event then this might impact a typical VM as follows:

0N/A the first created object will call the constructor causing a class load of

0N/A <code>MyProfiler</code>; which will then cause

0N/A object creation, and since <code>MyProfiler</code> isn't loaded yet,

0N/A infinite recursion; resulting in a stack overflow. A refinement of this

0N/A would be to delay invoking the tracking method until a safe time. For

0N/A example, <code>trackAllocations</code> could be set in the

0N/A handler for the <code>VMInit</code> event.

0N/A <example>

0N/A static boolean trackAllocations = false;

0N/A

0N/A public Object() {

0N/A if (trackAllocations) {

0N/A MyProfiler.allocationTracker(this);

0N/A }

0N/A }

0N/A </example>

0N/A <p/>

0N/A The <functionlink id="SetNativeMethodPrefix"/> allows native methods

0N/A to be instrumented by the use of wrapper methods.

0N/A </intro>

0N/A

0N/A <intro id="mUTF" label="Modified UTF-8 String Encoding">

0N/A <jvmti/> uses modified UTF-8 to encode character strings.

0N/A This is the same encoding used by JNI.

0N/A Modified UTF-8 differs

0N/A from standard UTF-8 in the representation of supplementary characters

0N/A and of the null character. See the

0N/A <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/types.html#wp16542">

0N/A Modified UTF-8 Strings</externallink>

0N/A section of the JNI specification for details.

0N/A </intro>

0N/A

0N/A <intro id="context" label="Specification Context">

0N/A Since this interface provides access to the state of applications running in the

0N/A Java virtual machine;

0N/A terminology refers to the Java platform and not the native

0N/A platform (unless stated otherwise). For example:

0N/A <ul>

0N/A <li>"thread" means Java programming language thread.</li>

0N/A <li>"stack frame" means Java virtual machine stack frame.</li>

0N/A <li>"class" means Java programming language class.</li>

0N/A <li>"heap" means Java virtual machine heap.</li>

0N/A <li>"monitor" means Java programming language object monitor.</li>

0N/A </ul>

0N/A <p/>

0N/A Sun, Sun Microsystems, the Sun logo, Java, and JVM

1472N/A are trademarks or registered trademarks of Oracle

1472N/A and/or its affiliates, in the U.S. and other countries.

0N/A </intro>

0N/A

0N/A

0N/A<functionsection label="Functions">

0N/A <intro id="jvmtiEnvAccess" label="Accessing Functions">

0N/A Native code accesses <jvmti/> features

0N/A by calling <jvmti/> functions.

0N/A Access to <jvmti/> functions is by use of an interface pointer

0N/A in the same manner as

0N/A <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html">Java

0N/A Native Interface (JNI) functions</externallink> are accessed.

0N/A The <jvmti/> interface pointer is called the

0N/A <i>environment pointer</i>.

0N/A <p/>

0N/A An environment pointer is a pointer to an environment and has

0N/A the type <code>jvmtiEnv*</code>.

0N/A An environment has information about its <jvmti/> connection.

0N/A The first value in the environment is a pointer to the function table.

0N/A The function table is an array of pointers to <jvmti/> functions.

0N/A Every function pointer is at a predefined offset inside the

0N/A array.

0N/A <p/>

0N/A When used from the C language:

0N/A double indirection is used to access the functions;

0N/A the environment pointer provides context and is the first

0N/A parameter of each function call; for example:

0N/A <example>

0N/AjvmtiEnv *jvmti;

0N/A...

0N/AjvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &amp;class_count, &amp;classes);

0N/A </example>

0N/A <p/>

0N/A When used from the C++ language:

0N/A functions are accessed as member functions of <code>jvmtiEnv</code>;

0N/A the environment pointer is not passed to the function call; for example:

0N/A <example>

0N/AjvmtiEnv *jvmti;

0N/A...

0N/AjvmtiError err = jvmti->GetLoadedClasses(&amp;class_count, &amp;classes);

0N/A </example>

0N/A Unless otherwise stated, all examples and declarations in this

0N/A specification use the C language.

0N/A <p/>

0N/A A <jvmti/> environment can be obtained through the JNI Invocation API

0N/A <code>GetEnv</code> function:

0N/A <example>

0N/AjvmtiEnv *jvmti;

0N/A...

0N/A(*jvm)->GetEnv(jvm, &amp;jvmti, JVMTI_VERSION_1_0);

0N/A </example>

0N/A Each call to <code>GetEnv</code>

0N/A creates a new <jvmti/> connection and thus

0N/A a new <jvmti/> environment.

0N/A The <code>version</code> argument of <code>GetEnv</code> must be

0N/A a <jvmti/> version.

0N/A The returned environment may have a different version than the

0N/A requested version but the returned environment must be compatible.

0N/A <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a

0N/A compatible version is not available, if <jvmti/> is not supported or

0N/A <jvmti/> is not supported in the current VM configuration.

0N/A Other interfaces may be added for creating <jvmti/> environments

0N/A in specific contexts.

0N/A Each environment has its own state (for example,

0N/A <functionlink id="SetEventNotificationMode">desired events</functionlink>,

0N/A <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and

0N/A <functionlink id="AddCapabilities">capabilities</functionlink>).

0N/A An environment is released with

0N/A <functionlink id="DisposeEnvironment"></functionlink>.

0N/A Thus, unlike JNI which has one environment per thread, <jvmti/> environments work

0N/A across threads and are created dynamically.

0N/A </intro>

0N/A

0N/A <intro id="functionReturn" label="Function Return Values">

0N/A <jvmti/> functions always return an

0N/A <internallink id="ErrorSection">error code</internallink> via the

0N/A <datalink id="jvmtiError"/> function return value.

0N/A Some functions can return additional

0N/A values through pointers provided by the calling function.

0N/A In some cases, <jvmti/> functions allocate memory that your program must

0N/A explicitly deallocate. This is indicated in the individual <jvmti/>

0N/A function descriptions. Empty lists, arrays, sequences, etc are

0N/A returned as <code>NULL</code>.

0N/A <p/>

0N/A In the event that the <jvmti/> function encounters

0N/A an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values

0N/A of memory referenced by argument pointers is undefined, but no memory

0N/A will have been allocated and no global references will have been allocated.

0N/A If the error occurs because of invalid input, no action will have occurred.

0N/A </intro>

0N/A

0N/A<intro id="refs" label="Managing JNI Object References">

0N/A <jvmti/> functions identify objects with JNI references

0N/A (<datalink id="jobject"/> and <datalink id="jclass"/>)

0N/A and their derivatives

0N/A (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).

0N/A References passed to

0N/A <jvmti/> functions can be either global or local, but they must be

0N/A strong references. All references returned by <jvmti/> functions are

0N/A local references--these local references are created

0N/A during the <jvmti/> call.

0N/A Local references are a resource that must be managed (see the

0N/A <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html#wp18654">JNI Documentation</externallink>).

0N/A When threads return from native code all local references

0N/A are freed. Note that some threads, including typical

0N/A agent threads, will never return from native code.

0N/A A thread is ensured the ability to create sixteen local

0N/A references without the need for any explicit management.

0N/A For threads executing a limited number of <jvmti/> calls before

0N/A returning from native code

0N/A (for example, threads processing events),

0N/A it may be determined that no explicit management

0N/A is needed.

0N/A However, long running agent threads will need explicit

0N/A local reference management--usually with the JNI functions

0N/A <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.

0N/A Conversely, to preserve references beyond the

0N/A return from native code, they must be converted to global references.

0N/A These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/>

0N/A as they are not <datalink id="jobject"/>s.

0N/A</intro>

0N/A

0N/A <intro id="prereqState" label="Prerequisite State for Calling Functions">

0N/A Unless the function explicitly states that the agent must bring

0N/A a thread or the VM to a particular state (for example, suspended),

0N/A the <jvmti/> implementation is responsible for bringing the VM to a

0N/A safe and consistent state for performing the function.

0N/A </intro>

0N/A

0N/A <intro id="functionsExceptions" label="Exceptions and Functions">

0N/A <jvmti/> functions never throw exceptions; error conditions are

0N/A communicated via the

0N/A <internallink id="functionReturn">function return value</internallink>.

0N/A Any existing exception state is preserved across a call to a

0N/A <jvmti/> function.

0N/A See the

0N/A <externallink

0N/A id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html#wp770"

0N/A >Java Exceptions</externallink>

0N/A section of the JNI specification for information on handling exceptions.

0N/A </intro>

0N/A

0N/A <category id="memory" label="Memory Management">

0N/A <intro>

0N/A These functions provide for the allocation and deallocation of

0N/A memory used by <jvmti/> functionality and can be used to provide

0N/A working memory for agents.

0N/A Memory managed by <jvmti/> is not compatible with other memory

0N/A allocation libraries and mechanisms.

0N/A </intro>

0N/A

0N/A <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">

0N/A <synopsis>Allocate</synopsis>

0N/A <description>

0N/A Allocate an area of memory through the <jvmti/> allocator.

0N/A The allocated

0N/A memory should be freed with <functionlink id="Deallocate"></functionlink>.

0N/A </description>

0N/A <origin>jvmdi</origin>

0N/A <capabilities>

0N/A </capabilities>

0N/A <parameters>

0N/A <param id="size">

0N/A <jlong/>

0N/A <description>

0N/A The number of bytes to allocate.

0N/A <rationale>

0N/A <code>jlong</code> is used for compatibility with JVMDI.

0N/A </rationale>

0N/A </description>

0N/A </param>

0N/A <param id="mem_ptr">

0N/A <allocbuf incount="size"><uchar/></allocbuf>

0N/A <description>

0N/A On return, a pointer to the beginning of the allocated memory.

0N/A If <code>size</code> is zero, <code>NULL</code> is returned.

0N/A </description>

0N/A </param>

0N/A </parameters>

0N/A <errors>

0N/A <error id="JVMTI_ERROR_OUT_OF_MEMORY">

0N/A Memory request cannot be honored.

0N/A </error>

0N/A <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">

0N/A <paramlink id="size"></paramlink> is less than zero.

0N/A </error>

0N/A </errors>

0N/A </function>

0N/A

0N/A <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47">

0N/A <synopsis>Deallocate</synopsis>

0N/A <description>

0N/A Deallocate <code>mem</code> using the <jvmti/> allocator.

0N/A This function should

0N/A be used to deallocate any memory allocated and returned

0N/A by a <jvmti/> function

0N/A (including memory allocated with <functionlink id="Allocate"></functionlink>).

0N/A All allocated memory must be deallocated

0N/A or the memory cannot be reclaimed.

0N/A </description>

0N/A <origin>jvmdi</origin>

0N/A <capabilities>

0N/A </capabilities>

0N/A <parameters>

0N/A <param id="mem">

0N/A <outbuf>

0N/A <uchar/>

0N/A <nullok>the call is ignored</nullok>

0N/A </outbuf>

0N/A <description>

0N/A A pointer to the beginning of the allocated memory.

0N/A Please ignore "On return, the elements are set."

0N/A <todo>keep it from generating "On return, the elements are set"</todo>

0N/A </description>

0N/A </param>

0N/A </parameters>

0N/A <errors>

0N/A </errors>

0N/A </function>

0N/A </category>

0N/A

0N/A <category id="threadCategory" label="Thread">

0N/A <intro>

0N/A </intro>

0N/A

0N/A <function id="GetThreadState" num="17">

0N/A <synopsis>Get Thread State</synopsis>

0N/A <description>

0N/A Get the state of a thread. The state of the thread is represented by the

0N/A answers to the hierarchical set of questions below:

0N/A <ul type="circle">

0N/A <li><i>Alive?</i>

0N/A <ul>

0N/A <li>Not alive.

0N/A <ul type="circle">

0N/A <li><i>Why not alive?</i>

0N/A <ul>

0N/A <li>New.</li>

0N/A <li>Terminated (<datalink

0N/A id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>

0N/A </ul>

0N/A </li>

0N/A </ul>

0N/A </li>

0N/A <li>Alive (<datalink

0N/A id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>)

0N/A <ul type="circle">

0N/A <li><i>Suspended?</i>

0N/A <ul>

0N/A <li>Suspended (<datalink

0N/A id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li>

0N/A <li>Not suspended</li>

0N/A </ul>

0N/A </li>

0N/A <li><i>Interrupted?</i>

0N/A <ul>

0N/A <li>Interrupted (<datalink

0N/A id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li>

0N/A <li>Not interrupted.</li>

0N/A </ul>

0N/A </li>

0N/A <li><i>In native?</i>

0N/A <ul>

0N/A <li>In native code (<datalink

0N/A id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li>

0N/A <li>In Java programming language code</li>

0N/A </ul>

0N/A </li>

0N/A <li><i>What alive state?</i>

0N/A <ul>

0N/A <li>Runnable (<datalink

0N/A id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li>

0N/A <li>Blocked (<datalink

0N/A id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li>

0N/A <li>Waiting (<datalink

0N/A id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>)

0N/A <ul type="circle">

0N/A <li><i>Timed wait?</i>

0N/A <ul>

0N/A <li>Indefinite (<datalink

0N/A id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li>

0N/A <li>Timed (<datalink

0N/A id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li>

0N/A </ul>

0N/A </li>

0N/A <li><i>Why waiting?</i>

0N/A <ul>

0N/A <li>Object.wait (<datalink

0N/A id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li>

0N/A <li>LockSupport.park (<datalink

0N/A id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li>

0N/A <li>Sleeping (<datalink

0N/A id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li>

0N/A </ul>

0N/A </li>

0N/A </ul>

0N/A </li>

0N/A </ul>

0N/A </li>

0N/A </ul>

0N/A </li>

0N/A </ul>

0N/A </li>

0N/A </ul>

0N/A <p/>

0N/A The answers are represented by the following bit vector.

0N/A <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">

0N/A <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">

0N/A Thread is alive. Zero if thread is new (not started) or terminated.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">

0N/A Thread has completed execution.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">

0N/A Thread is runnable.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">

0N/A Thread is waiting to enter a synchronization block/method or,

0N/A after an <code>Object.wait()</code>, waiting to re-enter a

0N/A synchronization block/method.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">

0N/A Thread is waiting.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">

0N/A Thread is waiting without a timeout.

0N/A For example, <code>Object.wait()</code>.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">

0N/A Thread is waiting with a maximum time to wait specified.

0N/A For example, <code>Object.wait(long)</code>.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">

0N/A Thread is sleeping -- <code>Thread.sleep(long)</code>.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">

0N/A Thread is waiting on an object monitor -- <code>Object.wait</code>.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">

0N/A Thread is parked, for example: <code>LockSupport.park</code>,

0N/A <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">

0N/A Thread suspended.

0N/A <code>java.lang.Thread.suspend()</code>

0N/A or a <jvmti/> suspend function

0N/A (such as <functionlink id="SuspendThread"></functionlink>)

0N/A has been called on the thread. If this bit

0N/A is set, the other bits refer to the thread state before suspension.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">

0N/A Thread has been interrupted.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000">

0N/A Thread is in native code--that is, a native method is running

0N/A which has not called back into the VM or Java programming

0N/A language code.

0N/A <p/>

0N/A This flag is not set when running VM compiled Java programming

0N/A language code nor is it set when running VM code or

0N/A VM support code. Native VM interface functions, such as JNI and

0N/A <jvmti/> functions, may be implemented as VM code.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000">

0N/A Defined by VM vendor.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000">

0N/A Defined by VM vendor.

0N/A </constant>

0N/A <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000">

0N/A Defined by VM vendor.

0N/A </constant>

0N/A </constants>

0N/A The following definitions are used to convert <jvmti/> thread state

0N/A to <code>java.lang.Thread.State</code> style states.

0N/A <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits">

0N/A <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK"

0N/A 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">

0N/A Mask the state with this before comparison

0N/A </constant>

0N/A <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW"

0N/A num="0">

0N/A <code>java.lang.Thread.State.NEW</code>

0N/A </constant>

0N/A <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED"

0N/A num="JVMTI_THREAD_STATE_TERMINATED">

0N/A <code>java.lang.Thread.State.TERMINATED</code>

0N/A </constant>

0N/A <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE"

0N/A num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE">

0N/A <code>java.lang.Thread.State.RUNNABLE</code>

0N/A </constant>

0N/A <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED"

0N/A num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER">

0N/A <code>java.lang.Thread.State.BLOCKED</code>

0N/A </constant>

0N/A <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING"

0N/A num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY">

0N/A <code>java.lang.Thread.State.WAITING</code>

0N/A </constant>

0N/A <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING"

0N/A num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT">

0N/A <code>java.lang.Thread.State.TIMED_WAITING</code>

0N/A </constant>

0N/A </constants>

0N/A <b>Rules</b>

0N/A <p/>

0N/A There can be no more than one answer to a question, although there can be no

0N/A answer (because the answer is unknown, does not apply, or none of the answers is

0N/A correct). An answer is set only when the enclosing answers match.

0N/A That is, no more than one of

0N/A <ul type="circle">

0N/A <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li>

0N/A <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li>

0N/A <li><code>JVMTI_THREAD_STATE_WAITING</code></li>

0N/A </ul>

0N/A can be set (a <tm>J2SE</tm> compliant implementation will always set

0N/A one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set).

0N/A And if any of these are set, the enclosing answer

0N/A <code>JVMTI_THREAD_STATE_ALIVE</code> is set.

0N/A No more than one of

0N/A <ul type="circle">

0N/A <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li>

0N/A <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li>

0N/A </ul>

0N/A can be set (a <tm>J2SE</tm> compliant implementation will always set

0N/A one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set).

0N/A And if either is set, the enclosing answers

0N/A <code>JVMTI_THREAD_STATE_ALIVE</code> and

0N/A <code>JVMTI_THREAD_STATE_WAITING</code> are set.

0N/A No more than one of

0N/A <ul type="circle">

0N/A <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li>

0N/A <li><code>JVMTI_THREAD_STATE_PARKED</code></li>

0N/A <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li>

0N/A </ul>

0N/A can be set. And if any of these is set, the enclosing answers

0N/A <code>JVMTI_THREAD_STATE_ALIVE</code> and

0N/A <code>JVMTI_THREAD_STATE_WAITING</code> are set.

0N/A Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set,

0N/A then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set.

0N/A If a state <i>A</i> is implemented using the mechanism of

0N/A state <i>B</i> then it is state <i>A</i> which

0N/A is returned by this function.

0N/A For example, if <code>Thread.sleep(long)</code>

0N/A is implemented using <code>Object.wait(long)</code>

0N/A then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code>

0N/A which is returned.

0N/A More than one of

0N/A <ul type="circle">

0N/A <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li>

0N/A <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li>

0N/A <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li>

0N/A </ul>

0N/A can be set, but if any is set,

0N/A <code>JVMTI_THREAD_STATE_ALIVE</code> is set.

0N/A <p/>

0N/A And finally,

0N/A <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless

0N/A <code>JVMTI_THREAD_STATE_ALIVE</code> is not set.

0N/A <p/>

0N/A The thread state representation is designed for extension in future versions

0N/A of the specification; thread state values should be used accordingly, that is

0N/A they should not be used as ordinals.

0N/A Most queries can be made by testing a single bit, if use in a switch statement is desired,

0N/A the state bits should be masked with the interesting bits.

0N/A All bits not defined above are reserved for future use.

0N/A A VM, compliant to the current specification, must set reserved bits to zero.

0N/A An agent should ignore reserved bits --

0N/A they should not be assumed to be zero and thus should not be included in comparisons.

0N/A <p/>

0N/A <b>Examples</b>

0N/A <p/>

0N/A Note that the values below exclude reserved and vendor bits.

0N/A <p/>

0N/A The state of a thread blocked at a <code>synchronized</code>-statement would be:

0N/A <example>

0N/A JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER

0N/A </example>

0N/A The state of a thread which hasn't started yet would be:

0N/A <example>

0N/A 0

0N/A </example>

0N/A The state of a thread at a <code>Object.wait(3000)</code> would be:

0N/A <example>

0N/A JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING +

0N/A JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT +

0N/A JVMTI_THREAD_STATE_MONITOR_WAITING

0N/A </example>

0N/A The state of a thread suspended while runnable would be:

0N/A <example>

0N/A JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED

0N/A </example>

0N/A <p/>

0N/A <b>Testing the State</b>

0N/A <p/>

0N/A In most cases, the thread state can be determined by testing the one bit corresponding

0N/A to that question. For example, the code to test if a thread is sleeping:

0N/A <example>

0N/A jint state;

0N/A jvmtiError err;

0N/A

0N/A err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);

0N/A if (err == JVMTI_ERROR_NONE) {

0N/A if (state &amp; JVMTI_THREAD_STATE_SLEEPING) { ...

0N/A </example>

0N/A <p/>

0N/A For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be:

0N/A <example>

0N/A if (state &amp; JVMTI_THREAD_STATE_WAITING) { ...

0N/A </example>

0N/A For some states, more than one bit will need to be tested as is the case

0N/A when testing if a thread has not yet been started:

0N/A <example>

0N/A if ((state &amp; (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0) { ...

0N/A </example>

0N/A To distinguish timed from untimed <code>Object.wait</code>:

0N/A <example>

0N/A if (state &amp; JVMTI_THREAD_STATE_IN_OBJECT_WAIT) {

0N/A if (state &amp; JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT) {

0N/A printf("in Object.wait(long timeout)\n");

0N/A } else {

0N/A printf("in Object.wait()\n");

0N/A }

0N/A }

0N/A </example>

0N/A <p/>

0N/A <b>Relationship to <code>java.lang.Thread.State</code></b>