|
<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
<!--
Copyright (c) 2002, 2022, 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>
<!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>
<!ATTLIST jobject frame CDATA #IMPLIED>
<!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?)>
<!ATTLIST outptr impl CDATA #IMPLIED>
<!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
name CDATA #IMPLIED>
<!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 blockquote ANY>
<!ELEMENT dl (dt|dd)+>
<!ELEMENT dd ANY>
<!ELEMENT dt (#PCDATA|jvmti|code|i|b)*>
<!ELEMENT table (tr)+>
<!ELEMENT tr (td|th)*>
<!ATTLIST tr class CDATA #IMPLIED>
<!ELEMENT td ANY>
<!ATTLIST td class CDATA #IMPLIED>
<!ELEMENT th ANY>
<!ATTLIST th class CDATA #IMPLIED
scope (col|row) #IMPLIED>
<!ELEMENT ul (li)+>
<!ATTLIST ul type (disc|circle|square) "disc">
<!ELEMENT li ANY>
]>
<specification label="JVM(TM) Tool Interface">
<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="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 <tm>Linux</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="entryPoint" 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 <tm>Linux</tm>.
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.
VM termination includes normal termination and VM failure, including start-up failure,
but not, of course, uncontrolled shutdown. An implementation may also
choose to not call this function if the <code>Agent_OnAttach</code>/
<code>Agent_OnAttach_L</code> function reported an error (returned a non-zero value).
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="jni/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 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="bcimodules" label="Bytecode Instrumentation of code in modules">
Agents can use the functions <functionlink id="AddModuleReads"/>,
<functionlink id="AddModuleExports"/>, <functionlink id="AddModuleOpens"/>,
<functionlink id="AddModuleUses"/> and <functionlink id="AddModuleProvides"/>
to update a module to expand the set of modules that it reads, the set of
packages that it exports or opens to other modules, or the services that it
uses and provides.
<p/>
As an aid to agents that deploy supporting classes on the search path of
the bootstrap class loader, or the search path of the class loader that
loads the main class, the Java virtual machine arranges for the module
of classes transformed by the <eventlink id="ClassFileLoadHook"/> event to
read the unnamed module of both class loaders.
</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="jni/types.html#modified-utf-8-strings">
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="jni/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="jni/functions.html#local-references">
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="jni/design.html#java-exceptions"
>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>
These functions provide information about threads and allow an agent to
suspend and resume threads.
<p/>
The <code>jthread</code> specified to these functions can be a JNI
reference to a
<externallink id="../api/java.base/java/lang/Thread.html#platform-threads">platform thread</externallink>
or <externallink id="../api/java.base/java/lang/Thread.html#virtual-threads">virtual thread</externallink>.
Some functions are not supported on virtual threads and return
<code>JVMTI_ERROR_UNSUPPORTED_OPERATION</code> when called with a reference
to a virtual thread.
</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 synchronized block/method or,
after an <code>Object.wait()</code>, waiting to re-enter a
synchronized 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</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>.
A virtual thread that is sleeping, in <code>Thread.sleep</code>, may
have this state flag set instead of <code>JVMTI_THREAD_STATE_SLEEPING</code>.
</constant>
<constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
Thread is suspended by a suspend function
(such as <functionlink id="SuspendThread"></functionlink>).
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>
--> --------------------
--> maximum size reached
--> --------------------
¤ Dauer der Verarbeitung: 0.73 Sekunden
(vorverarbeitet)
¤
|
Haftungshinweis
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
|
