14363 lines
510 KiB
XML
14363 lines
510 KiB
XML
<?xml version="1.0" encoding="ISO-8859-1"?>
|
|
<?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
|
|
<!--
|
|
Copyright (c) 2002, 2013, Oracle and/or its affiliates. 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
or visit www.oracle.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 vmspec EMPTY>
|
|
<!ATTLIST vmspec chapter 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="2"
|
|
microversion="3">
|
|
<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://docs.oracle.com/javase/7/docs/technotes/guides/jpda/architecture.html">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="entry point" label="Statically Linked Agents (since version 1.2.3)">
|
|
|
|
A native JVMTI Agent may be <i>statically linked</i> with the VM.
|
|
The manner in which the library and VM image are combined is
|
|
implementation-dependent.
|
|
An agent L whose image has been combined with the VM is defined as
|
|
<i>statically linked</i> if and only if the agent exports a function
|
|
called Agent_OnLoad_L.
|
|
<p/>
|
|
If a <i>statically linked</i> agent L exports a function called
|
|
Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad
|
|
function will be ignored.
|
|
If an agent L is <i>statically linked</i>, an Agent_OnLoad_L
|
|
function will be invoked with the same arguments and expected return
|
|
value as specified for the Agent_OnLoad function.
|
|
An agent L that is <i>statically linked</i> will prohibit an agent of
|
|
the same name from being loaded dynamically.
|
|
<p/>
|
|
The VM will invoke the Agent_OnUnload_L function of the agent, if such
|
|
a function is exported, at the same point during VM execution as it would
|
|
have called the dynamic entry point Agent_OnUnLoad. A statically loaded
|
|
agent cannot be unloaded. The Agent_OnUnload_L function will still be
|
|
called to do any other agent shutdown related tasks.
|
|
If a <i>statically linked</i> agent L exports a function called
|
|
Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad
|
|
function will be ignored.
|
|
<p/>
|
|
If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function
|
|
will be invoked with the same arguments and expected return value as
|
|
specified for the Agent_OnAttach function.
|
|
If a <i>statically linked</i> agent L exports a function called
|
|
Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach
|
|
function will be ignored.
|
|
</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.
|
|
If the agent library is statically linked into the executable
|
|
then no actual loading takes place.
|
|
<p/>
|
|
</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>. If the agent
|
|
library is statically linked into the executable
|
|
then no actual loading takes place.
|
|
<p/>
|
|
</dd>
|
|
</dl>
|
|
For a dynamic shared library agent, the start-up routine
|
|
<internallink id="onload"><code>Agent_OnLoad</code></internallink>
|
|
in the library will be invoked. If the agent library is statically linked
|
|
into the executable then the system will attempt to invoke the
|
|
<code>Agent_OnLoad_<agent-lib-name></code> entry point where
|
|
<agent-lib-name> is the basename of the
|
|
agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>,
|
|
the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine.
|
|
<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>
|
|
or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink>
|
|
for statically linked agents 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>
|
|
or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink>
|
|
for statically linked agents 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>
|
|
Or for a statically linked agent named 'L':
|
|
<example>
|
|
JNIEXPORT jint JNICALL
|
|
Agent_OnLoad_L(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> or
|
|
<code>Agent_OnLoad_<agent-lib-name></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> or <code>Agent_OnLoad_<agent-lib-name></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> or
|
|
<code>Agent_OnLoad_<agent-lib-name></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>
|
|
Or for a statically linked agent named 'L':
|
|
<example>
|
|
JNIEXPORT jint JNICALL
|
|
Agent_OnAttach_L(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> or <code>Agent_OnAttach_<agent-lib-name></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> or <code>Agent_OnAttach_<agent-lib-name
|
|
></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>
|
|
Or for a statically linked agent named 'L':
|
|
<example>
|
|
JNIEXPORT void JNICALL
|
|
Agent_OnUnload_L(JavaVM *vm)</example>
|
|
|
|
This function will be called by the VM when the library is about to be unloaded.
|
|
The library will be unloaded (unless it is statically linked into the
|
|
executable) and this function will be called if some platform specific
|
|
mechanism causes the unload (an unload mechanism is not specified in this document)
|
|
or the library is (in effect) unloaded by the termination of the VM whether through
|
|
normal termination or VM failure, including start-up failure.
|
|
Uncontrolled shutdown is, of couse, an exception to this rule.
|
|
Note the distinction between this function and the
|
|
<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> or
|
|
<code>Agent_OnUnload_<agent-lib-name></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://docs.oracle.com/javase/7/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://docs.oracle.com/javase/7/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 Oracle
|
|
and/or its affiliates, 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://docs.oracle.com/javase/7/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://docs.oracle.com/javase/7/docs/technotes/guides/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://docs.oracle.com/javase/7/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="monitor_info_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://docs.oracle.com/javase/7/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
|
|
<vmspec chapter="3.6"/>,
|
|
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, 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 <vmspec/>
|
|
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 <vmspec/> 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
|
|
<vmspec chapter="3.6"/>)
|
|
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 description in
|
|
<vmspec chapter="4.4"/>.
|
|
</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 <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> 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
|
|
<fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> 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="array_primitive_value_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
|
|
<fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> 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="array_primitive_value_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
|
|
<vmspec chapter="4.4"/>.
|
|
</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="GetLocalInstance" num="155" since="1.2">
|
|
<synopsis>Get Local Instance</synopsis>
|
|
<description>
|
|
This function can be used to retrieve the value of the local object
|
|
variable at slot 0 (the "<code>this</code>" object) from non-static
|
|
frames. This function can retrieve the "<code>this</code>" object from
|
|
native method frames, whereas <code>GetLocalObject()</code> would
|
|
return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
|
|
</description>
|
|
<origin>new</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="value_ptr">
|
|
<outptr><jobject/></outptr>
|
|
<description>
|
|
On return, points to the variable's value.
|
|
</description>
|
|
</param>
|
|
</parameters>
|
|
<errors>
|
|
<error id="JVMTI_ERROR_INVALID_SLOT">
|
|
If the specified frame is a static method 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 <vmspec chapter="5.3"/>.
|
|
<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://docs.oracle.com/javase/7/docs/technotes/guides/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 <vmspec chapter="4"/>.
|
|
<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
|
|
<vmspec chapter="4"/>.
|
|
</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
|
|
<vmspec chapter="4"/>.
|
|
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 <vmspec chapter="4"/>)
|
|
</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 <code>field descriptors</code> in
|
|
<vmspec chapter="4.3.2"/>.
|
|
</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 <vmspec chapter="4"/>.
|
|
</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 <code>method descriptors</code> in
|
|
<vmspec chapter="4.3.3"/>.
|
|
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 <vmspec chapter="4"/>.
|
|
</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 <vmspec chapter="4.7.3"/>.
|
|
</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
|
|
<vmspec chapter="4.3.2"/>.
|
|
</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://docs.oracle.com/javase/7/docs/technotes/guides/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 <vmspec chapter="5.3.1"/>.
|
|
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://docs.oracle.com/javase/7/docs/technotes/guides/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/>
|
|
<vmspec/> 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 <vmspec chapter="5.3.2"/>.
|
|
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://docs.oracle.com/javase/7/docs/technotes/guides/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/>
|
|
<vmspec/> 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_ptr">
|
|
<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>
|
|
or, for statically linked agents, the <internallink id="onload">
|
|
<code>Agent_OnLoad_<agent-lib-name>
|
|
</code></internallink> function.
|
|
</constant>
|
|
<constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
|
|
Primordial phase: between return from <code>Agent_OnLoad</code>
|
|
or <code>Agent_OnLoad_<agent-lib-name></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 <vmspec/>. 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
|
|
garbage collection pause 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
|
|
garbage collection pause 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="jchar">
|
|
<description>
|
|
Holds a Java programming language <code>char</code>.
|
|
Unsigned 16 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://docs.oracle.com/javase/7/docs/technotes/guides/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 <vmspec chapter="4.4"/>).
|
|
</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>
|
|
<change date="11 October 2012" version="1.2.2">
|
|
Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
|
|
</change>
|
|
<change date="19 June 2013" version="1.2.3">
|
|
Added support for statically linked agents.
|
|
</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:
|
|
-->
|