annotate src/share/vm/prims/jvmti.xml @ 1932:09b4dd4f152b

7004582: Add GetThisObject() function to JVMTI 1.2 Summary: Add 'GetThisObject' function Reviewed-by: never, coleenp
author kamg
date Thu, 09 Dec 2010 15:04:26 -0500
parents 684faacebf20
children b1a2afa37ec4
rev   line source
duke@0 1 <?xml version="1.0" encoding="ISO-8859-1"?>
duke@0 2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
duke@0 3 <!--
kamg@1901 4 Copyright (c) 2002, 2010, Oracle and/or its affiliates. All rights reserved.
duke@0 6
duke@0 7 This code is free software; you can redistribute it and/or modify it
duke@0 8 under the terms of the GNU General Public License version 2 only, as
duke@0 9 published by the Free Software Foundation.
duke@0 10
duke@0 11 This code is distributed in the hope that it will be useful, but WITHOUT
duke@0 12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@0 13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
duke@0 14 version 2 for more details (a copy is included in the LICENSE file that
duke@0 15 accompanied this code).
duke@0 16
duke@0 17 You should have received a copy of the GNU General Public License version
duke@0 18 2 along with this work; if not, write to the Free Software Foundation,
duke@0 19 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@0 20
trims@1472 21 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
trims@1472 22 or visit if you need additional information or have any
trims@1472 23 questions.
duke@0 24
duke@0 25 -->
duke@0 26
duke@0 27 <!DOCTYPE specification [
duke@0 28 <!ELEMENT specification (title, intro*, functionsection, errorsection,
duke@0 29 eventsection, datasection, issuessection, changehistory)>
duke@0 30 <!ATTLIST specification label CDATA #REQUIRED
duke@0 31 majorversion CDATA #REQUIRED
duke@0 32 minorversion CDATA #REQUIRED
duke@0 33 microversion CDATA #REQUIRED>
duke@0 34
duke@0 35 <!ELEMENT title (#PCDATA|jvmti|tm)*>
duke@0 36 <!ATTLIST title subtitle CDATA #REQUIRED>
duke@0 37
duke@0 38 <!ELEMENT intro ANY>
duke@0 39 <!ATTLIST intro id CDATA #IMPLIED
duke@0 40 label CDATA "">
duke@0 41
duke@0 42 <!ELEMENT functionsection (intro*, category*)>
duke@0 43 <!ATTLIST functionsection label CDATA #REQUIRED>
duke@0 44
duke@0 45 <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*,
duke@0 46 (function|callback|elide)*)>
duke@0 47 <!ATTLIST category id CDATA #REQUIRED
duke@0 48 label CDATA #REQUIRED>
duke@0 49
duke@0 50 <!ELEMENT function (synopsis, typedef*, description?, origin,
duke@0 51 (capabilities|eventcapabilities),
duke@0 52 parameters, errors)>
duke@0 53 <!ATTLIST function id CDATA #REQUIRED
duke@0 54 num CDATA #REQUIRED
duke@0 55 phase (onload|onloadOnly|start|live|any) #IMPLIED
duke@0 56 callbacksafe (safe|unsafe) #IMPLIED
duke@0 57 impl CDATA #IMPLIED
duke@0 58 hide CDATA #IMPLIED
duke@0 59 jkernel (yes|no) #IMPLIED
duke@0 60 since CDATA "1.0">
duke@0 61
duke@0 62 <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
duke@0 63 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void),
duke@0 64 synopsis, description?, parameters)>
duke@0 65 <!ATTLIST callback id CDATA #REQUIRED
duke@0 66 since CDATA "1.0">
duke@0 67
duke@0 68 <!ELEMENT synopsis (#PCDATA|jvmti)*>
duke@0 69
duke@0 70 <!ELEMENT typedef (description?, field*)>
duke@0 71 <!ATTLIST typedef id CDATA #REQUIRED
duke@0 72 label CDATA #REQUIRED
duke@0 73 since CDATA "1.0">
duke@0 74
duke@0 75 <!ELEMENT uniontypedef (description?, field*)>
duke@0 76 <!ATTLIST uniontypedef id CDATA #REQUIRED
duke@0 77 label CDATA #REQUIRED
duke@0 78 since CDATA "1.0">
duke@0 79
duke@0 80 <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
duke@0 81 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct),
duke@0 82 description)>
duke@0 83 <!ATTLIST field id CDATA #REQUIRED>
duke@0 84
duke@0 85 <!ELEMENT capabilitiestypedef (description?, capabilityfield*)>
duke@0 86 <!ATTLIST capabilitiestypedef id CDATA #REQUIRED
duke@0 87 label CDATA #REQUIRED>
duke@0 88
duke@0 89 <!ELEMENT capabilityfield (description)>
duke@0 90 <!ATTLIST capabilityfield id CDATA #REQUIRED
duke@0 91 disp1 CDATA ""
duke@0 92 disp2 CDATA ""
duke@0 93 since CDATA "1.0">
duke@0 94
duke@0 95 <!ELEMENT description ANY>
duke@0 96
duke@0 97 <!ELEMENT capabilities (required*, capability*)>
duke@0 98
duke@0 99 <!ELEMENT eventcapabilities EMPTY>
duke@0 100
duke@0 101 <!ELEMENT required ANY>
duke@0 102 <!ATTLIST required id CDATA #REQUIRED>
duke@0 103
duke@0 104 <!ELEMENT capability ANY>
duke@0 105 <!ATTLIST capability id CDATA #REQUIRED>
duke@0 106
duke@0 107 <!ELEMENT parameters (param*)>
duke@0 108
duke@0 109 <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
duke@0 110 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype|
duke@0 111 outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf),
duke@0 112 description)>
duke@0 113 <!ATTLIST param id CDATA #REQUIRED>
duke@0 114
duke@0 115 <!ELEMENT jmethodID EMPTY>
duke@0 116 <!ATTLIST jmethodID class CDATA #IMPLIED
duke@0 117 native CDATA #IMPLIED>
duke@0 118
duke@0 119 <!ELEMENT jfieldID EMPTY>
duke@0 120 <!ATTLIST jfieldID class CDATA #IMPLIED>
duke@0 121
duke@0 122 <!ELEMENT jclass EMPTY>
duke@0 123 <!ATTLIST jclass method CDATA #IMPLIED
duke@0 124 field CDATA #IMPLIED>
duke@0 125
duke@0 126 <!ELEMENT jframeID EMPTY>
duke@0 127 <!ATTLIST jframeID thread CDATA #IMPLIED>
duke@0 128
duke@0 129 <!ELEMENT jrawMonitorID EMPTY>
duke@0 130
duke@0 131 <!ELEMENT jthread EMPTY>
duke@0 132 <!ATTLIST jthread started CDATA #IMPLIED
duke@0 133 null CDATA #IMPLIED
duke@0 134 frame CDATA #IMPLIED
duke@0 135 impl CDATA #IMPLIED>
duke@0 136
duke@0 137 <!ELEMENT varargs EMPTY>
duke@0 138
duke@0 139 <!ELEMENT jthreadGroup EMPTY>
duke@0 140 <!ELEMENT jobject EMPTY>
duke@0 141 <!ELEMENT jvalue EMPTY>
duke@0 142 <!ELEMENT jchar EMPTY>
duke@0 143 <!ELEMENT jint EMPTY>
duke@0 144 <!ATTLIST jint min CDATA #IMPLIED>
duke@0 145 <!ELEMENT jlong EMPTY>
duke@0 146 <!ELEMENT jfloat EMPTY>
duke@0 147 <!ELEMENT jdouble EMPTY>
duke@0 148 <!ELEMENT jlocation EMPTY>
duke@0 149 <!ELEMENT jboolean EMPTY>
duke@0 150 <!ELEMENT char EMPTY>
duke@0 151 <!ELEMENT uchar EMPTY>
duke@0 152 <!ELEMENT size_t EMPTY>
duke@0 153 <!ELEMENT void EMPTY>
duke@0 154 <!ELEMENT enum (#PCDATA)*>
duke@0 155 <!ELEMENT struct (#PCDATA)*>
duke@0 156
duke@0 157 <!ELEMENT nullok ANY>
duke@0 158
duke@0 159 <!ELEMENT ptrtype ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
duke@0 160 jthreadGroup|jobject|jvalue), nullok?)>
duke@0 161
duke@0 162 <!ELEMENT outptr ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
duke@0 163 jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
duke@0 164 jlocation|jboolean|char|uchar|size_t|void), nullok?)>
duke@0 165
duke@0 166 <!ELEMENT allocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
duke@0 167 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
duke@0 168 jlocation|jboolean|char|uchar|size_t|void), nullok?)>
duke@0 169 <!ATTLIST allocbuf incount CDATA #IMPLIED
duke@0 170 outcount CDATA #IMPLIED>
duke@0 171
duke@0 172 <!ELEMENT allocallocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
duke@0 173 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
duke@0 174 jlocation|jboolean|char|uchar|size_t|void), nullok?)>
duke@0 175 <!ATTLIST allocallocbuf incount CDATA #IMPLIED
duke@0 176 outcount CDATA #IMPLIED>
duke@0 177
duke@0 178 <!ELEMENT inptr (struct, nullok?)>
duke@0 179
duke@0 180 <!ELEMENT inbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
duke@0 181 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
duke@0 182 jlocation|jboolean|char|uchar|size_t|void), nullok?)>
duke@0 183 <!ATTLIST inbuf incount CDATA #IMPLIED>
duke@0 184
duke@0 185 <!ELEMENT outbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
duke@0 186 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
duke@0 187 jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)>
duke@0 188 <!ATTLIST outbuf incount CDATA #IMPLIED
duke@0 189 outcount CDATA #IMPLIED>
duke@0 190
duke@0 191 <!ELEMENT vmbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
duke@0 192 jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
duke@0 193 jlocation|jboolean|char|uchar|size_t|void), nullok?)>
duke@0 194 <!ATTLIST vmbuf incount CDATA #IMPLIED
duke@0 195 outcount CDATA #IMPLIED>
duke@0 196
duke@0 197 <!ELEMENT agentbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
duke@0 198 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
duke@0 199 jlocation|jboolean|char|uchar|size_t|void), nullok?)>
duke@0 200 <!ATTLIST agentbuf incount CDATA #IMPLIED
duke@0 201 outcount CDATA #IMPLIED>
duke@0 202
duke@0 203 <!ELEMENT allocfieldbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
duke@0 204 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
duke@0 205 jlocation|jboolean|char|uchar|size_t|void))>
duke@0 206 <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED>
duke@0 207
duke@0 208 <!ELEMENT errors (error*)>
duke@0 209
duke@0 210 <!ELEMENT error ANY>
duke@0 211 <!ATTLIST error id CDATA #REQUIRED>
duke@0 212
duke@0 213 <!ELEMENT errorsection (intro*, errorcategory*)>
duke@0 214 <!ATTLIST errorsection label CDATA #REQUIRED>
duke@0 215
duke@0 216 <!ELEMENT errorcategory (intro*, errorid*)>
duke@0 217 <!ATTLIST errorcategory id CDATA #REQUIRED
duke@0 218 label CDATA #REQUIRED>
duke@0 219
duke@0 220 <!ELEMENT errorid ANY>
duke@0 221 <!ATTLIST errorid id CDATA #REQUIRED
duke@0 222 num CDATA #REQUIRED>
duke@0 223
duke@0 224 <!ELEMENT datasection (intro*, basetypes*)>
duke@0 225
duke@0 226 <!ELEMENT basetypes (intro*, basetype*)>
duke@0 227 <!ATTLIST basetypes id CDATA #REQUIRED
duke@0 228 label CDATA #REQUIRED>
duke@0 229
duke@0 230 <!ELEMENT basetype (definition?,description)>
duke@0 231 <!ATTLIST basetype id CDATA #REQUIRED>
duke@0 232
duke@0 233 <!ELEMENT definition (#PCDATA|jvmti)*>
duke@0 234
duke@0 235 <!ELEMENT eventsection (intro*, (event|elide)*)>
duke@0 236 <!ATTLIST eventsection label CDATA #REQUIRED>
duke@0 237
duke@0 238 <!ELEMENT event (description, origin, typedef*, capabilities, parameters)>
duke@0 239 <!ATTLIST event id CDATA #REQUIRED
duke@0 240 label CDATA #REQUIRED
duke@0 241 const CDATA #REQUIRED
duke@0 242 num CDATA #REQUIRED
duke@0 243 phase (onload|start|live|any) #IMPLIED
duke@0 244 filtered (thread|global) #IMPLIED
duke@0 245 since CDATA "1.0">
duke@0 246
duke@0 247 <!ELEMENT issuessection (intro*)>
duke@0 248 <!ATTLIST issuessection label CDATA #REQUIRED>
duke@0 249
duke@0 250 <!ELEMENT changehistory (intro*, change*)>
duke@0 251 <!ATTLIST changehistory update CDATA #REQUIRED
duke@0 252 id CDATA #REQUIRED>
duke@0 253
duke@0 254 <!ELEMENT change ANY>
duke@0 255 <!ATTLIST change date CDATA #REQUIRED
duke@0 256 version CDATA #IMPLIED>
duke@0 257
duke@0 258 <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*>
duke@0 259 <!ATTLIST functionlink id CDATA #REQUIRED>
duke@0 260
duke@0 261 <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*>
duke@0 262 <!ATTLIST datalink id CDATA #REQUIRED>
duke@0 263
duke@0 264 <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*>
duke@0 265 <!ATTLIST typelink id CDATA #REQUIRED>
duke@0 266
duke@0 267 <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*>
duke@0 268 <!ATTLIST fieldlink id CDATA #REQUIRED
duke@0 269 struct CDATA #REQUIRED>
duke@0 270
duke@0 271 <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*>
duke@0 272 <!ATTLIST paramlink id CDATA #REQUIRED>
duke@0 273
duke@0 274 <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*>
duke@0 275 <!ATTLIST eventlink id CDATA #REQUIRED>
duke@0 276
duke@0 277 <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*>
duke@0 278 <!ATTLIST errorlink id CDATA #REQUIRED>
duke@0 279
duke@0 280 <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*>
duke@0 281 <!ATTLIST externallink id CDATA #REQUIRED>
duke@0 282
duke@0 283 <!ELEMENT vmspeclink EMPTY>
duke@0 284 <!ATTLIST vmspeclink id CDATA #IMPLIED>
duke@0 285 <!ATTLIST vmspeclink name CDATA #IMPLIED>
duke@0 286 <!ATTLIST vmspeclink preposition CDATA #IMPLIED>
duke@0 287
duke@0 288 <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*>
duke@0 289 <!ATTLIST internallink id CDATA #REQUIRED>
duke@0 290
duke@0 291 <!ELEMENT functionphaselist EMPTY>
duke@0 292 <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED>
duke@0 293
duke@0 294 <!ELEMENT eventphaselist EMPTY>
duke@0 295 <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED>
duke@0 296
duke@0 297 <!ELEMENT issue ANY>
duke@0 298
duke@0 299 <!ELEMENT rationale ANY>
duke@0 300
duke@0 301 <!ELEMENT todo ANY>
duke@0 302
duke@0 303 <!ELEMENT origin (#PCDATA)*>
duke@0 304
duke@0 305 <!ELEMENT elide (intro|function|callback|event)*>
duke@0 306 <!ATTLIST elide why CDATA #IMPLIED>
duke@0 307
duke@0 308 <!ELEMENT constants (constant*)>
duke@0 309 <!ATTLIST constants id CDATA #REQUIRED
duke@0 310 label CDATA #REQUIRED
duke@0 311 kind (enum|bits|const) #REQUIRED
duke@0 312 since CDATA "1.0">
duke@0 313
duke@0 314 <!ELEMENT constant ANY>
duke@0 315 <!ATTLIST constant id CDATA #REQUIRED
duke@0 316 num CDATA #REQUIRED>
duke@0 317
duke@0 318 <!ELEMENT tm (#PCDATA)>
duke@0 319
duke@0 320 <!ELEMENT i (#PCDATA|jvmti|tm)*>
duke@0 321
duke@0 322 <!ELEMENT b (#PCDATA|jvmti|code)*>
duke@0 323
duke@0 324 <!ELEMENT code (#PCDATA|space)*>
duke@0 325
duke@0 326 <!ELEMENT pre ANY>
duke@0 327
duke@0 328 <!ELEMENT space EMPTY>
duke@0 329
duke@0 330 <!ELEMENT jvmti EMPTY>
duke@0 331
duke@0 332 <!ELEMENT example (#PCDATA|i)*>
duke@0 333
duke@0 334 <!ELEMENT br EMPTY>
duke@0 335
duke@0 336 <!ELEMENT p EMPTY>
duke@0 337
duke@0 338 <!ELEMENT dl (dt|dd)+>
duke@0 339
duke@0 340 <!ELEMENT dd ANY>
duke@0 341
duke@0 342 <!ELEMENT dt (#PCDATA|jvmti|code|i|b)*>
duke@0 343
duke@0 344 <!ELEMENT table (tr)+>
duke@0 345
duke@0 346 <!ELEMENT tr (td|th)*>
duke@0 347
duke@0 348 <!ELEMENT td ANY>
duke@0 349 <!ATTLIST td align (left|right|center) "center">
duke@0 350
duke@0 351 <!ELEMENT th ANY>
duke@0 352 <!ATTLIST th align (left|right|center) "center">
duke@0 353
duke@0 354 <!ELEMENT ul (li)+>
duke@0 355 <!ATTLIST ul type (disc|circle|square) "disc">
duke@0 356
duke@0 357 <!ELEMENT li ANY>
duke@0 358 ]>
duke@0 359
duke@0 360 <specification label="JVM(TM) Tool Interface"
duke@0 361 majorversion="1"
kamg@1901 362 minorversion="2"
kamg@1901 363 microversion="1">
duke@0 364 <title subtitle="Version">
duke@0 365 <tm>JVM</tm> Tool Interface
duke@0 366 </title>
duke@0 367
duke@0 368 <intro id="whatIs" label="What is the JVM Tool Interface?">
duke@0 369 The <tm>JVM</tm> Tool Interface (<jvmti/>)
duke@0 370 is a programming interface used by development and monitoring tools.
duke@0 371 It provides both a way to inspect the state and
duke@0 372 to control the execution of applications running in the
duke@0 373 <tm>Java</tm> virtual machine (VM).
duke@0 374 <p/>
duke@0 375 <jvmti/> is intended to provide a VM interface for the full breadth of tools
duke@0 376 that need access to VM state, including but not limited to: profiling,
duke@0 377 debugging, monitoring, thread analysis, and coverage analysis tools.
duke@0 378 <p/>
duke@0 379 <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual
duke@0 380 machine.
duke@0 381 <p/>
duke@0 382 <jvmti/> is a two-way interface.
duke@0 383 A client of <jvmti/>, hereafter called an <i>agent</i>,
duke@0 384 can be notified of
duke@0 385 interesting occurrences through <internallink id="EventSection">events</internallink>.
duke@0 386 <jvmti/>
duke@0 387 can query and control the application through many
duke@0 388 <internallink id="FunctionSection">functions</internallink>,
duke@0 389 either in response to events or
duke@0 390 independent of them.
duke@0 391 <p/>
duke@0 392 Agents run in the same process with and communicate directly with
duke@0 393 the virtual machine executing
duke@0 394 the application being examined. This communication is
duke@0 395 through a native interface (<jvmti/>). The native in-process interface allows
duke@0 396 maximal control with minimal intrusion on the part of a tool.
duke@0 397 Typically, agents are relatively compact. They can be controlled
duke@0 398 by a separate process which implements the bulk of a tool's
duke@0 399 function without interfering with the target application's normal execution.
duke@0 400 </intro>
duke@0 401
duke@0 402 <intro id="architecture" label="Architecture">
duke@0 403 Tools can be written directly to <jvmti/> or indirectly
duke@0 404 through higher level interfaces.
duke@0 405 The Java Platform Debugger Architecture includes <jvmti/>, but also
duke@0 406 contains higher-level, out-of-process debugger interfaces. The higher-level
duke@0 407 interfaces are more appropriate than <jvmti/> for many tools.
duke@0 408 For more information on the Java Platform Debugger Architecture,
duke@0 409 see the
duke@0 410 <externallink id="">Java
duke@0 411 Platform Debugger Architecture website</externallink>.
duke@0 412 </intro>
duke@0 413
duke@0 414 <intro id="writingAgents" label="Writing Agents">
duke@0 415 Agents can be written in any native language that supports C
duke@0 416 language calling conventions and C or C++
duke@0 417 definitions.
duke@0 418 <p/>
duke@0 419 The function, event, data type, and constant definitions needed for
duke@0 420 using <jvmti/> are defined in the include file <code>jvmti.h</code>.
duke@0 421 To use these definitions add the <tm>J2SE</tm> include directory
duke@0 422 to your include path and add
duke@0 423 <example>
duke@0 424 #include &lt;jvmti.h&gt;
duke@0 425 </example>
duke@0 426 to your source code.
duke@0 427 </intro>
duke@0 428
duke@0 429 <intro id="deployingAgents" label="Deploying Agents">
duke@0 430 An agent is deployed in a platform specific manner but is typically the
duke@0 431 platform equivalent of a dynamic library. On the <tm>Windows</tm> operating
duke@0 432 system, for example, an agent library is a "Dynamic Linked Library" (DLL).
duke@0 433 On the <tm>Solaris</tm> Operating Environment, an agent library is a shared
duke@0 434 object (<code>.so</code> file).
duke@0 435 <p/>
duke@0 436 An agent may be started at VM startup by specifying the agent library
duke@0 437 name using a <internallink id="starting">command line option</internallink>.
duke@0 438 Some implementations may support a mechanism to <internallink id="onattach">
duke@0 439 start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.
duke@0 440 The details of how this is initiated are implementation specific.
duke@0 441 </intro>
duke@0 442
duke@0 443 <intro id="starting" label="Agent Command Line Options">
duke@0 444 The term "command-line option" is used below to
duke@0 445 mean options supplied in the <code>JavaVMInitArgs</code> argument
duke@0 446 to the <code>JNI_CreateJavaVM</code> function of the JNI
duke@0 447 Invocation API.
duke@0 448 <p/>
duke@0 449 One of the two following
duke@0 450 command-line options is used on VM startup to
duke@0 451 properly load and run agents.
duke@0 452 These arguments identify the library containing
duke@0 453 the agent as well as an options
duke@0 454 string to be passed in at startup.
duke@0 455 <dl>
duke@0 456 <dt><code>-agentlib:</code><i>&lt;agent-lib-name&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
duke@0 457 <dd>
duke@0 458 The name following <code>-agentlib:</code> is the name of the
duke@0 459 library to load. Lookup of the library, both its full name and location,
duke@0 460 proceeds in a platform-specific manner.
duke@0 461 Typically, the <i>&lt;agent-lib-name&gt;</i> is expanded to an
duke@0 462 operating system specific file name.
duke@0 463 The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
duke@0 464 For example, if the option
duke@0 465 <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to
duke@0 466 load the shared library <code>foo.dll</code> from the system <code>PATH</code>
duke@0 467 under <tm>Windows</tm> or <code></code> from the
duke@0 468 <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment.
duke@0 469 </dd>
duke@0 470 <dt><code>-agentpath:</code><i>&lt;path-to-agent&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
duke@0 471 <dd>
duke@0 472 The path following <code>-agentpath:</code> is the absolute path from which
duke@0 473 to load the library.
duke@0 474 No library name expansion will occur.
duke@0 475 The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
duke@0 476 For example, if the option
duke@0 477 <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to
duke@0 478 load the shared library <code>c:\myLibs\foo.dll</code>.
duke@0 479 </dd>
duke@0 480 </dl>
duke@0 481 The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink>
duke@0 482 in the library will be invoked.
duke@0 483 <p/>
duke@0 484 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
duke@0 485 will be searched for JNI native method implementations to facilitate the
duke@0 486 use of Java programming language code in tools, as is needed for
duke@0 487 <internallink id="bci">bytecode instrumentation</internallink>.
duke@0 488 <p/>
duke@0 489 The agent libraries will be searched after all other libraries have been
duke@0 490 searched (agents wishing to override or intercept the native method
duke@0 491 implementations of non-agent methods can use the
duke@0 492 <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
duke@0 493 <p/>
duke@0 494 These switches do the above and nothing more - they do not change the
duke@0 495 state of the VM or <jvmti/>. No command line options are needed
duke@0 496 to enable <jvmti/>
duke@0 497 or aspects of <jvmti/>, this is handled programmatically
duke@0 498 by the use of
duke@0 499 <internallink id="capability">capabilities</internallink>.
duke@0 500 </intro>
duke@0 501
duke@0 502 <intro id="startup" label="Agent Start-Up">
duke@0 503 The VM starts each agent by invoking a start-up function.
duke@0 504 If the agent is started in the <code>OnLoad</code>
duke@0 505 <functionlink id="GetPhase">phase</functionlink> the function
duke@0 506 <internallink id="onload"><code>Agent_OnLoad</code></internallink>
duke@0 507 will be invoked.
duke@0 508 If the agent is started in the live
duke@0 509 <functionlink id="GetPhase">phase</functionlink> the function
duke@0 510 <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
duke@0 511 will be invoked.
duke@0 512 Exactly one call to a start-up function is made per agent.
duke@0 513 </intro>
duke@0 514
duke@0 515 <intro id="onload" label="Agent Start-Up (OnLoad phase)">
duke@0 516 If an agent is started during the <code>OnLoad</code> phase then its
duke@0 517 agent library must export a start-up function with the following prototype:
duke@0 518 <example>
duke@0 519 JNIEXPORT jint JNICALL
duke@0 520 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>
duke@0 521 The VM will start the agent by calling this function.
duke@0 522 It will be called early enough in VM initialization that:
duke@0 523 <ul>
duke@0 524 <li><functionlink id="SetSystemProperty">system properties</functionlink>
duke@0 525 may be set before they have been used in the start-up of the VM</li>
duke@0 526 <li>the full set of
duke@0 527 <internallink id="capability">capabilities</internallink>
duke@0 528 is still available (note that capabilities that configure the VM
duke@0 529 may only be available at this time--see the
duke@0 530 <internallink id="capability">Capability function section</internallink>)</li>
duke@0 531 <li>no bytecodes have executed</li>
duke@0 532 <li>no classes have been loaded</li>
duke@0 533 <li>no objects have been created</li>
duke@0 534 </ul>
duke@0 535 <p/>
duke@0 536 The VM will call the <code>Agent_OnLoad</code> function with
duke@0 537 <i>&lt;options&gt;</i> as the second argument -
duke@0 538 that is, using the command-line option examples,
duke@0 539 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code>
duke@0 540 argument of <code>Agent_OnLoad</code>.
duke@0 541 The <code>options</code> argument is encoded as a
duke@0 542 <internallink id="mUTF">modified UTF-8</internallink> string.
duke@0 543 If <i>=&lt;options&gt;</i> is not specified,
duke@0 544 a zero length string is passed to <code>options</code>.
duke@0 545 The lifespan of the <code>options</code> string is the <code>Agent_OnLoad</code>
duke@0 546 call. If needed beyond this time the string or parts of the string must
duke@0 547 be copied.
duke@0 548 The period between when <code>Agent_OnLoad</code> is called and when it
duke@0 549 returns is called the <i>OnLoad phase</i>.
duke@0 550 Since the VM is not initialized during the OnLoad
duke@0 551 <functionlink id="GetPhase">phase</functionlink>,
duke@0 552 the set of allowed operations
duke@0 553 inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the
duke@0 554 functionality available at this time).
duke@0 555 The agent can safely process the options and set
duke@0 556 event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once
duke@0 557 the VM initialization event is received
duke@0 558 (that is, the <eventlink id="VMInit">VMInit</eventlink>
duke@0 559 callback is invoked), the agent
duke@0 560 can complete its initialization.
duke@0 561 <rationale>
duke@0 562 Early startup is required so that agents can set the desired capabilities,
duke@0 563 many of which must be set before the VM is initialized.
duke@0 564 In JVMDI, the -Xdebug command-line option provided
duke@0 565 very coarse-grain control of capabilities.
duke@0 566 JVMPI implementations use various tricks to provide a single "JVMPI on" switch.
duke@0 567 No reasonable command-line
duke@0 568 option could provide the fine-grain of control required to balance needed capabilities vs
duke@0 569 performance impact.
duke@0 570 Early startup is also needed so that agents can control the execution
duke@0 571 environment - modifying the file system and system properties to install
duke@0 572 their functionality.
duke@0 573 </rationale>
duke@0 574 <p/>
duke@0 575 The return value from <code>Agent_OnLoad</code> is used to indicate an error.
duke@0 576 Any value other than zero indicates an error and causes termination of the VM.
duke@0 577 </intro>
duke@0 578
duke@0 579 <intro id="onattach" label="Agent Start-Up (Live phase)">
duke@0 580 A VM may support a mechanism that allows agents to be started in the VM during the live
duke@0 581 <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,
duke@0 582 are implementation specific. For example, a tool may use some platform specific mechanism,
duke@0 583 or implementation specific API, to attach to the running VM, and request it start a given
duke@0 584 agent.
duke@0 585 <p/>
duke@0 586 If an agent is started during the live phase then its agent library
duke@0 587 must export a start-up function
duke@0 588 with the following prototype:
duke@0 589 <example>
duke@0 590 JNIEXPORT jint JNICALL
duke@0 591 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>
duke@0 592 <p/>
duke@0 593 The VM will start the agent by calling this function.
duke@0 594 It will be called in the context of a thread
duke@0 595 that is attached to the VM. The first argument <i>&lt;vm&gt;</i> is the Java VM.
duke@0 596 The <i>&lt;options&gt;</i> argument is the startup options provided to the agent.
duke@0 597 <i>&lt;options&gt;</i> is encoded as a <internallink id="mUTF">modified UTF-8
duke@0 598 </internallink> string.
duke@0 599 If startup options were not provided, a zero length string is passed to
duke@0 600 <code>options</code>. The lifespan of the <code>options</code> string is the
duke@0 601 <code>Agent_OnAttach</code> call. If needed beyond this time the string or parts of
duke@0 602 the string must be copied.
duke@0 603 <p/>
duke@0 604 Note that some <internallink id="capability">capabilities</internallink>
duke@0 605 may not be available in the live phase.
duke@0 606 <p/>
duke@0 607 The <code>Agent_OnAttach</code> function initializes the agent and returns a value
duke@0 608 to the VM to indicate if an error occurred. Any value other than zero indicates an error.
duke@0 609 An error does not cause the VM to terminate. Instead the VM ignores the error, or takes
duke@0 610 some implementation specific action -- for example it might print an error to standard error,
duke@0 611 or record the error in a system log.
duke@0 612 </intro>
duke@0 613
duke@0 614 <intro id="onunload" label="Agent Shutdown">
duke@0 615 The library may optionally export a
duke@0 616 shutdown function with the following prototype:
duke@0 617 <example>
duke@0 618 JNIEXPORT void JNICALL
duke@0 619 Agent_OnUnload(JavaVM *vm)</example>
duke@0 620 This function will be called by the VM when the library is about to be unloaded.
duke@0 621 The library will be unloaded and this function will be called if some platform specific
duke@0 622 mechanism causes the unload (an unload mechanism is not specified in this document)
duke@0 623 or the library is (in effect) unloaded by the termination of the VM whether through
duke@0 624 normal termination or VM failure, including start-up failure.
duke@0 625 Uncontrolled shutdown is, of couse, an exception to this rule.
duke@0 626 Note the distinction between this function and the
duke@0 627 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
duke@0 628 to be sent, the VM must have run at least to the point of initialization and a valid
duke@0 629 <jvmti/> environment must exist which has set a callback for VMDeath
duke@0 630 and enabled the event
duke@0 631 None of these are required for <code>Agent_OnUnload</code> and this function
duke@0 632 is also called if the library is unloaded for other reasons.
duke@0 633 In the case that a VM Death event is sent, it will be sent before this
duke@0 634 function is called (assuming this function is called due to VM termination).
duke@0 635 This function can be used to clean-up resources allocated by the agent.
duke@0 636 </intro>
duke@0 637
duke@0 638 <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">
duke@0 639 Since the command-line cannot always be accessed or modified, for example in embedded VMs
duke@0 640 or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is
duke@0 641 provided so that agents may be launched in these cases.
duke@0 642 <p/>
duke@0 643 Platforms which support environment variables or other named strings, may support the
duke@0 644 <code>JAVA_TOOL_OPTIONS</code> variable. This variable will be broken into options at white-space
duke@0 645 boundaries. White-space characters include space, tab, carriage-return, new-line,
duke@0 646 vertical-tab, and form-feed. Sequences of white-space characters are considered
duke@0 647 equivalent to a single white-space character. No white-space is included in the options
duke@0 648 unless quoted. Quoting is as follows:
duke@0 649 <ul>
duke@0 650 <li>All characters enclosed between a pair of single quote marks (''), except a single
duke@0 651 quote, are quoted.</li>
duke@0 652 <li>Double quote characters have no special meaning inside a pair of single quote marks.</li>
duke@0 653 <li>All characters enclosed between a pair of double quote marks (""), except a double
duke@0 654 quote, are quoted.</li>
duke@0 655 <li>Single quote characters have no special meaning inside a pair of double quote marks.</li>
duke@0 656 <li>A quoted part can start or end anywhere in the variable.</li>
duke@0 657 <li>White-space characters have no special meaning when quoted -- they are included in
duke@0 658 the option like any other character and do not mark white-space boundaries.</li>
duke@0 659 <li>The pair of quote marks is not included in the option.</li>
duke@0 660 </ul>
duke@0 661 <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied
duke@0 662 in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is
duke@0 663 a concern; for example, the Reference Implementation disables this feature on Unix systems when
duke@0 664 the effective user or group ID differs from the real ID.
duke@0 665 This feature is intended to support the initialization of tools -- specifically including the
duke@0 666 launching of native or Java programming language agents. Multiple tools may wish to use this
duke@0 667 feature, so the variable should not be overwritten, instead, options should be appended to
duke@0 668 the variable. Note that since the variable is processed at the time of the JNI Invocation
duke@0 669 API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled.
duke@0 670 </intro>
duke@0 671
duke@0 672 <intro id="environments" label="Environments">
duke@0 673 The <jvmti/> specification supports the use of multiple simultaneous
duke@0 674 <jvmti/> agents.
duke@0 675 Each agent has its own <jvmti/> environment.
duke@0 676 That is, the <jvmti/> state is
duke@0 677 separate for each agent - changes to one environment do not affect the
duke@0 678 others. The state of a <jvmti/>
duke@0 679 environment includes:
duke@0 680 <ul>
duke@0 681 <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>
duke@0 682 <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>
duke@0 683 <li><internallink id="capability">the capabilities</internallink></li>
duke@0 684 <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>
duke@0 685 </ul>
duke@0 686 Although their <jvmti/> state
duke@0 687 is separate, agents inspect and modify the shared state
duke@0 688 of the VM, they also share the native environment in which they execute.
duke@0 689 As such, an agent can perturb the results of other agents or cause them
duke@0 690 to fail. It is the responsibility of the agent writer to specify the level
duke@0 691 of compatibility with other agents. <jvmti/> implementations are not capable
duke@0 692 of preventing destructive interactions between agents. Techniques to reduce
duke@0 693 the likelihood of these occurrences are beyond the scope of this document.
duke@0 694 <p/>
duke@0 695 An agent creates a <jvmti/> environment
duke@0 696 by passing a <jvmti/> version
duke@0 697 as the interface ID to the JNI Invocation API function
duke@0 698 <externallink id=""><code>GetEnv</code></externallink>.
duke@0 699 See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink>
duke@0 700 for more details on the creation and use of
duke@0 701 <jvmti/> environments.
duke@0 702 Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from
duke@0 703 <internallink id="onload"><code>Agent_OnLoad</code></internallink>.
duke@0 704 </intro>
duke@0 705
duke@0 706 <intro id="bci" label="Bytecode Instrumentation">
duke@0 707 This interface does not include some events that one might expect in an interface with
duke@0 708 profiling support. Some examples include object allocation events and full speed
duke@0 709 method enter and exit events. The interface instead provides support for
duke@0 710 <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine
duke@0 711 bytecode instructions which comprise the target program. Typically, these alterations
duke@0 712 are to add "events" to the code of a method - for example, to add, at the beginning of a method,
duke@0 713 a call to <code>MyProfiler.methodEntered()</code>.
duke@0 714 Since the changes are purely additive, they do not modify application
duke@0 715 state or behavior.
duke@0 716 Because the inserted agent code is standard bytecodes, the VM can run at full speed,
duke@0 717 optimizing not only the target program but also the instrumentation. If the
duke@0 718 instrumentation does not involve switching from bytecode execution, no expensive
duke@0 719 state transitions are needed. The result is high performance events.
duke@0 720 This approach also provides complete control to the agent: instrumentation can be
duke@0 721 restricted to "interesting" portions of the code (e.g., the end user's code) and
duke@0 722 can be conditional. Instrumentation can run entirely in Java programming language
duke@0 723 code or can call into the native agent. Instrumentation can simply maintain
duke@0 724 counters or can statistically sample events.
duke@0 725 <p/>
duke@0 726 Instrumentation can be inserted in one of three ways:
duke@0 727 <ul>
duke@0 728 <li>
duke@0 729 Static Instrumentation: The class file is instrumented before it
duke@0 730 is loaded into the VM - for example, by creating a duplicate directory of
duke@0 731 <code>*.class</code> files which have been modified to add the instrumentation.
duke@0 732 This method is extremely awkward and, in general, an agent cannot know
duke@0 733 the origin of the class files which will be loaded.
duke@0 734 </li>
duke@0 735 <li>
duke@0 736 Load-Time Instrumentation: When a class file is loaded by the VM, the raw
duke@0 737 bytes of the class file are sent for instrumentation to the agent.
duke@0 738 The <eventlink id="ClassFileLoadHook"/>
duke@0 739 event, triggered by the class load,
duke@0 740 provides this functionality. This mechanism provides efficient
duke@0 741 and complete access to one-time instrumentation.
duke@0 742 </li>
duke@0 743 <li>
duke@0 744 Dynamic Instrumentation: A class which is already loaded (and possibly
duke@0 745 even running) is modified. This optional feature is provided by the
duke@0 746 <eventlink id="ClassFileLoadHook"/> event, triggered by calling the
duke@0 747 <functionlink id="RetransformClasses"/> function.
duke@0 748 Classes can be modified multiple times and can be returned to their
duke@0 749 original state.
duke@0 750 The mechanism allows instrumentation which changes during the
duke@0 751 course of execution.
duke@0 752 </li>
duke@0 753 </ul>
duke@0 754 <p/>
duke@0 755 The class modification functionality provided in this interface
duke@0 756 is intended to provide a mechanism for instrumentation
duke@0 757 (the <eventlink id="ClassFileLoadHook"/> event
duke@0 758 and the <functionlink id="RetransformClasses"/> function)
duke@0 759 and, during development, for fix-and-continue debugging
duke@0 760 (the <functionlink id="RedefineClasses"/> function).
duke@0 761 <p/>
duke@0 762 Care must be taken to avoid perturbing dependencies, especially when
duke@0 763 instrumenting core classes. For example, an approach to getting notification
duke@0 764 of every object allocation is to instrument the constructor on
duke@0 765 <code>Object</code>. Assuming that the constructor is initially
duke@0 766 empty, the constructor could be changed to:
duke@0 767 <example>
duke@0 768 public Object() {
duke@0 769 MyProfiler.allocationTracker(this);
duke@0 770 }
duke@0 771 </example>
duke@0 772 However, if this change was made using the
duke@0 773 <eventlink id="ClassFileLoadHook"/>
duke@0 774 event then this might impact a typical VM as follows:
duke@0 775 the first created object will call the constructor causing a class load of
duke@0 776 <code>MyProfiler</code>; which will then cause
duke@0 777 object creation, and since <code>MyProfiler</code> isn't loaded yet,
duke@0 778 infinite recursion; resulting in a stack overflow. A refinement of this
duke@0 779 would be to delay invoking the tracking method until a safe time. For
duke@0 780 example, <code>trackAllocations</code> could be set in the
duke@0 781 handler for the <code>VMInit</code> event.
duke@0 782 <example>
duke@0 783 static boolean trackAllocations = false;
duke@0 784
duke@0 785 public Object() {
duke@0 786 if (trackAllocations) {
duke@0 787 MyProfiler.allocationTracker(this);
duke@0 788 }
duke@0 789 }
duke@0 790 </example>
duke@0 791 <p/>
duke@0 792 The <functionlink id="SetNativeMethodPrefix"/> allows native methods
duke@0 793 to be instrumented by the use of wrapper methods.
duke@0 794 </intro>
duke@0 795
duke@0 796 <intro id="mUTF" label="Modified UTF-8 String Encoding">
duke@0 797 <jvmti/> uses modified UTF-8 to encode character strings.
duke@0 798 This is the same encoding used by JNI.
duke@0 799 Modified UTF-8 differs
duke@0 800 from standard UTF-8 in the representation of supplementary characters
duke@0 801 and of the null character. See the
duke@0 802 <externallink id="">
duke@0 803 Modified UTF-8 Strings</externallink>
duke@0 804 section of the JNI specification for details.
duke@0 805 </intro>
duke@0 806
duke@0 807 <intro id="context" label="Specification Context">
duke@0 808 Since this interface provides access to the state of applications running in the
duke@0 809 Java virtual machine;
duke@0 810 terminology refers to the Java platform and not the native
duke@0 811 platform (unless stated otherwise). For example:
duke@0 812 <ul>
duke@0 813 <li>"thread" means Java programming language thread.</li>
duke@0 814 <li>"stack frame" means Java virtual machine stack frame.</li>
duke@0 815 <li>"class" means Java programming language class.</li>
duke@0 816 <li>"heap" means Java virtual machine heap.</li>
duke@0 817 <li>"monitor" means Java programming language object monitor.</li>
duke@0 818 </ul>
duke@0 819 <p/>
duke@0 820 Sun, Sun Microsystems, the Sun logo, Java, and JVM
trims@1472 821 are trademarks or registered trademarks of Oracle
trims@1472 822 and/or its affiliates, in the U.S. and other countries.
duke@0 823 </intro>
duke@0 824
duke@0 825
duke@0 826 <functionsection label="Functions">
duke@0 827 <intro id="jvmtiEnvAccess" label="Accessing Functions">
duke@0 828 Native code accesses <jvmti/> features
duke@0 829 by calling <jvmti/> functions.
duke@0 830 Access to <jvmti/> functions is by use of an interface pointer
duke@0 831 in the same manner as
duke@0 832 <externallink id="">Java
duke@0 833 Native Interface (JNI) functions</externallink> are accessed.
duke@0 834 The <jvmti/> interface pointer is called the
duke@0 835 <i>environment pointer</i>.
duke@0 836 <p/>
duke@0 837 An environment pointer is a pointer to an environment and has
duke@0 838 the type <code>jvmtiEnv*</code>.
duke@0 839 An environment has information about its <jvmti/> connection.
duke@0 840 The first value in the environment is a pointer to the function table.
duke@0 841 The function table is an array of pointers to <jvmti/> functions.
duke@0 842 Every function pointer is at a predefined offset inside the
duke@0 843 array.
duke@0 844 <p/>
duke@0 845 When used from the C language:
duke@0 846 double indirection is used to access the functions;
duke@0 847 the environment pointer provides context and is the first
duke@0 848 parameter of each function call; for example:
duke@0 849 <example>
duke@0 850 jvmtiEnv *jvmti;
duke@0 851 ...
duke@0 852 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &amp;class_count, &amp;classes);
duke@0 853 </example>
duke@0 854 <p/>
duke@0 855 When used from the C++ language:
duke@0 856 functions are accessed as member functions of <code>jvmtiEnv</code>;
duke@0 857 the environment pointer is not passed to the function call; for example:
duke@0 858 <example>
duke@0 859 jvmtiEnv *jvmti;
duke@0 860 ...
duke@0 861 jvmtiError err = jvmti->GetLoadedClasses(&amp;class_count, &amp;classes);
duke@0 862 </example>
duke@0 863 Unless otherwise stated, all examples and declarations in this
duke@0 864 specification use the C language.
duke@0 865 <p/>
duke@0 866 A <jvmti/> environment can be obtained through the JNI Invocation API
duke@0 867 <code>GetEnv</code> function:
duke@0 868 <example>
duke@0 869 jvmtiEnv *jvmti;
duke@0 870 ...
duke@0 871 (*jvm)->GetEnv(jvm, &amp;jvmti, JVMTI_VERSION_1_0);
duke@0 872 </example>
duke@0 873 Each call to <code>GetEnv</code>
duke@0 874 creates a new <jvmti/> connection and thus
duke@0 875 a new <jvmti/> environment.
duke@0 876 The <code>version</code> argument of <code>GetEnv</code> must be
duke@0 877 a <jvmti/> version.
duke@0 878 The returned environment may have a different version than the
duke@0 879 requested version but the returned environment must be compatible.
duke@0 880 <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a
duke@0 881 compatible version is not available, if <jvmti/> is not supported or
duke@0 882 <jvmti/> is not supported in the current VM configuration.
duke@0 883 Other interfaces may be added for creating <jvmti/> environments
duke@0 884 in specific contexts.
duke@0 885 Each environment has its own state (for example,
duke@0 886 <functionlink id="SetEventNotificationMode">desired events</functionlink>,
duke@0 887 <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and
duke@0 888 <functionlink id="AddCapabilities">capabilities</functionlink>).
duke@0 889 An environment is released with
duke@0 890 <functionlink id="DisposeEnvironment"></functionlink>.
duke@0 891 Thus, unlike JNI which has one environment per thread, <jvmti/> environments work
duke@0 892 across threads and are created dynamically.
duke@0 893 </intro>
duke@0 894
duke@0 895 <intro id="functionReturn" label="Function Return Values">
duke@0 896 <jvmti/> functions always return an
duke@0 897 <internallink id="ErrorSection">error code</internallink> via the
duke@0 898 <datalink id="jvmtiError"/> function return value.
duke@0 899 Some functions can return additional
duke@0 900 values through pointers provided by the calling function.
duke@0 901 In some cases, <jvmti/> functions allocate memory that your program must
duke@0 902 explicitly deallocate. This is indicated in the individual <jvmti/>
duke@0 903 function descriptions. Empty lists, arrays, sequences, etc are
duke@0 904 returned as <code>NULL</code>.
duke@0 905 <p/>
duke@0 906 In the event that the <jvmti/> function encounters
duke@0 907 an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values
duke@0 908 of memory referenced by argument pointers is undefined, but no memory
duke@0 909 will have been allocated and no global references will have been allocated.
duke@0 910 If the error occurs because of invalid input, no action will have occurred.
duke@0 911 </intro>
duke@0 912
duke@0 913 <intro id="refs" label="Managing JNI Object References">
duke@0 914 <jvmti/> functions identify objects with JNI references
duke@0 915 (<datalink id="jobject"/> and <datalink id="jclass"/>)
duke@0 916 and their derivatives
duke@0 917 (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).
duke@0 918 References passed to
duke@0 919 <jvmti/> functions can be either global or local, but they must be
duke@0 920 strong references. All references returned by <jvmti/> functions are
duke@0 921 local references--these local references are created
duke@0 922 during the <jvmti/> call.
duke@0 923 Local references are a resource that must be managed (see the
duke@0 924 <externallink id="">JNI Documentation</externallink>).
duke@0 925 When threads return from native code all local references
duke@0 926 are freed. Note that some threads, including typical
duke@0 927 agent threads, will never return from native code.
duke@0 928 A thread is ensured the ability to create sixteen local
duke@0 929 references without the need for any explicit management.
duke@0 930 For threads executing a limited number of <jvmti/> calls before
duke@0 931 returning from native code
duke@0 932 (for example, threads processing events),
duke@0 933 it may be determined that no explicit management
duke@0 934 is needed.
duke@0 935 However, long running agent threads will need explicit
duke@0 936 local reference management--usually with the JNI functions
duke@0 937 <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.
duke@0 938 Conversely, to preserve references beyond the
duke@0 939 return from native code, they must be converted to global references.
duke@0 940 These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/>
duke@0 941 as they are not <datalink id="jobject"/>s.
duke@0 942 </intro>
duke@0 943
duke@0 944 <intro id="prereqState" label="Prerequisite State for Calling Functions">
duke@0 945 Unless the function explicitly states that the agent must bring
duke@0 946 a thread or the VM to a particular state (for example, suspended),
duke@0 947 the <jvmti/> implementation is responsible for bringing the VM to a
duke@0 948 safe and consistent state for performing the function.
duke@0 949 </intro>
duke@0 950
duke@0 951 <intro id="functionsExceptions" label="Exceptions and Functions">
duke@0 952 <jvmti/> functions never throw exceptions; error conditions are
duke@0 953 communicated via the
duke@0 954 <internallink id="functionReturn">function return value</internallink>.
duke@0 955 Any existing exception state is preserved across a call to a
duke@0 956 <jvmti/> function.
duke@0 957 See the
duke@0 958 <externallink
duke@0 959 id=""
duke@0 960 >Java Exceptions</externallink>
duke@0 961 section of the JNI specification for information on handling exceptions.
duke@0 962 </intro>
duke@0 963
duke@0 964 <category id="memory" label="Memory Management">
duke@0 965 <intro>
duke@0 966 These functions provide for the allocation and deallocation of
duke@0 967 memory used by <jvmti/> functionality and can be used to provide
duke@0 968 working memory for agents.
duke@0 969 Memory managed by <jvmti/> is not compatible with other memory
duke@0 970 allocation libraries and mechanisms.
duke@0 971 </intro>
duke@0 972
duke@0 973 <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">
duke@0 974 <synopsis>Allocate</synopsis>
duke@0 975 <description>
duke@0 976 Allocate an area of memory through the <jvmti/> allocator.
duke@0 977 The allocated
duke@0 978 memory should be freed with <functionlink id="Deallocate"></functionlink>.
duke@0 979 </description>
duke@0 980 <origin>jvmdi</origin>
duke@0 981 <capabilities>
duke@0 982 </capabilities>
duke@0 983 <parameters>
duke@0 984 <param id="size">
duke@0 985 <jlong/>
duke@0 986 <description>
duke@0 987 The number of bytes to allocate.
duke@0 988 <rationale>
duke@0 989 <code>jlong</code> is used for compatibility with JVMDI.
duke@0 990 </rationale>
duke@0 991 </description>
duke@0 992 </param>
duke@0 993 <param id="mem_ptr">
duke@0 994 <allocbuf incount="size"><uchar/></allocbuf>
duke@0 995 <description>
duke@0 996 On return, a pointer to the beginning of the allocated memory.
duke@0 997 If <code>size</code> is zero, <code>NULL</code> is returned.
duke@0 998 </description>
duke@0 999 </param>
duke@0 1000 </parameters>
duke@0 1001 <errors>
duke@0 1002 <error id="JVMTI_ERROR_OUT_OF_MEMORY">
duke@0 1003 Memory request cannot be honored.
duke@0 1004 </error>
duke@0 1005 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
duke@0 1006 <paramlink id="size"></paramlink> is less than zero.
duke@0 1007 </error>
duke@0 1008 </errors>
duke@0 1009 </function>
duke@0 1010
duke@0 1011 <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47">
duke@0 1012 <synopsis>Deallocate</synopsis>
duke@0 1013 <description>
duke@0 1014 Deallocate <code>mem</code> using the <jvmti/> allocator.
duke@0 1015 This function should
duke@0 1016 be used to deallocate any memory allocated and returned
duke@0 1017 by a <jvmti/> function
duke@0 1018 (including memory allocated with <functionlink id="Allocate"></functionlink>).
duke@0 1019 All allocated memory must be deallocated
duke@0 1020 or the memory cannot be reclaimed.
duke@0 1021 </description>
duke@0 1022 <origin>jvmdi</origin>
duke@0 1023 <capabilities>
duke@0 1024 </capabilities>
duke@0 1025 <parameters>
duke@0 1026 <param id="mem">
duke@0 1027 <outbuf>
duke@0 1028 <uchar/>
duke@0 1029 <nullok>the call is ignored</nullok>
duke@0 1030 </outbuf>
duke@0 1031 <description>
duke@0 1032 A pointer to the beginning of the allocated memory.
duke@0 1033 Please ignore "On return, the elements are set."
duke@0 1034 <todo>keep it from generating "On return, the elements are set"</todo>
duke@0 1035 </description>
duke@0 1036 </param>
duke@0 1037 </parameters>
duke@0 1038 <errors>
duke@0 1039 </errors>
duke@0 1040 </function>
duke@0 1041 </category>
duke@0 1042
duke@0 1043 <category id="threadCategory" label="Thread">
duke@0 1044 <intro>
duke@0 1045 </intro>
duke@0 1046
duke@0 1047 <function id="GetThreadState" num="17">
duke@0 1048 <synopsis>Get Thread State</synopsis>
duke@0 1049 <description>
duke@0 1050 Get the state of a thread. The state of the thread is represented by the
duke@0 1051 answers to the hierarchical set of questions below:
duke@0 1052 <ul type="circle">
duke@0 1053 <li><i>Alive?</i>
duke@0 1054 <ul>
duke@0 1055 <li>Not alive.
duke@0 1056 <ul type="circle">
duke@0 1057 <li><i>Why not alive?</i>
duke@0 1058 <ul>
duke@0 1059 <li>New.</li>
duke@0 1060 <li>Terminated (<datalink
duke@0 1061 id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>
duke@0 1062 </ul>
duke@0 1063 </li>
duke@0 1064 </ul>
duke@0 1065 </li>
duke@0 1066 <li>Alive (<datalink
duke@0 1067 id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>)
duke@0 1068 <ul type="circle">
duke@0 1069 <li><i>Suspended?</i>
duke@0 1070 <ul>
duke@0 1071 <li>Suspended (<datalink
duke@0 1072 id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li>
duke@0 1073 <li>Not suspended</li>
duke@0 1074 </ul>
duke@0 1075 </li>
duke@0 1076 <li><i>Interrupted?</i>
duke@0 1077 <ul>
duke@0 1078 <li>Interrupted (<datalink
duke@0 1079 id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li>
duke@0 1080 <li>Not interrupted.</li>
duke@0 1081 </ul>
duke@0 1082 </li>
duke@0 1083 <li><i>In native?</i>
duke@0 1084 <ul>
duke@0 1085 <li>In native code (<datalink
duke@0 1086 id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li>
duke@0 1087 <li>In Java programming language code</li>
duke@0 1088 </ul>
duke@0 1089 </li>
duke@0 1090 <li><i>What alive state?</i>
duke@0 1091 <ul>
duke@0 1092 <li>Runnable (<datalink
duke@0 1093 id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li>
duke@0 1094 <li>Blocked (<datalink
duke@0 1096 <li>Waiting (<datalink
duke@0 1097 id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>)
duke@0 1098 <ul type="circle">
duke@0 1099 <li><i>Timed wait?</i>
duke@0 1100 <ul>
duke@0 1101 <li>Indefinite (<datalink
duke@0 1103 <li>Timed (<datalink
duke@0 1105 </ul>
duke@0 1106 </li>
duke@0 1107 <li><i>Why waiting?</i>
duke@0 1108 <ul>
duke@0 1109 <li>Object.wait (<datalink
duke@0 1110 id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li>
duke@0 1111 <li>LockSupport.park (<datalink
duke@0 1112 id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li>
duke@0 1113 <li>Sleeping (<datalink
duke@0 1114 id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li>
duke@0 1115 </ul>
duke@0 1116 </li>
duke@0 1117 </ul>
duke@0 1118 </li>
duke@0 1119 </ul>
duke@0 1120 </li>
duke@0 1121 </ul>
duke@0 1122 </li>
duke@0 1123 </ul>
duke@0 1124 </li>
duke@0 1125 </ul>
duke@0 1126 <p/>
duke@0 1127 The answers are represented by the following bit vector.
duke@0 1128 <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">
duke@0 1129 <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">
duke@0 1130 Thread is alive. Zero if thread is new (not started) or terminated.
duke@0 1131 </constant>
duke@0 1132 <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">
duke@0 1133 Thread has completed execution.
duke@0 1134 </constant>
duke@0 1135 <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">
duke@0 1136 Thread is runnable.
duke@0 1137 </constant>
duke@0 1138 <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">
duke@0 1139 Thread is waiting to enter a synchronization block/method or,
duke@0 1140 after an <code>Object.wait()</code>, waiting to re-enter a
duke@0 1141 synchronization block/method.
duke@0 1142 </constant>
duke@0 1143 <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">
duke@0 1144 Thread is waiting.
duke@0 1145 </constant>
duke@0 1146 <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">
duke@0 1147 Thread is waiting without a timeout.
duke@0 1148 For example, <code>Object.wait()</code>.
duke@0 1149 </constant>
duke@0 1150 <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">
duke@0 1151 Thread is waiting with a maximum time to wait specified.
duke@0 1152 For example, <code>Object.wait(long)</code>.
duke@0 1153 </constant>
duke@0 1154 <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">
duke@0 1155 Thread is sleeping -- <code>Thread.sleep(long)</code>.
duke@0 1156 </constant>
duke@0 1157 <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">
duke@0 1158 Thread is waiting on an object monitor -- <code>Object.wait</code>.
duke@0 1159 </constant>
duke@0 1160 <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">
duke@0 1161 Thread is parked, for example: <code>LockSupport.park</code>,
duke@0 1162 <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.
duke@0 1163 </constant>
duke@0 1164 <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
duke@0 1165 Thread suspended.
duke@0 1166 <code>java.lang.Thread.suspend()</code>
duke@0 1167 or a <jvmti/> suspend function
duke@0 1168 (such as <functionlink id="SuspendThread"></functionlink>)
duke@0 1169 has been called on the thread. If this bit
duke@0 1170 is set, the other bits refer to the thread state before suspension.
duke@0 1171 </constant>
duke@0 1172 <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">
duke@0 1173 Thread has been interrupted.
duke@0 1174 </constant>
duke@0 1175 <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000">
duke@0 1176 Thread is in native code--that is, a native method is running
duke@0 1177 which has not called back into the VM or Java programming
duke@0 1178 language code.
duke@0 1179 <p/>
duke@0 1180 This flag is not set when running VM compiled Java programming
duke@0 1181 language code nor is it set when running VM code or
duke@0 1182 VM support code. Native VM interface functions, such as JNI and
duke@0 1183 <jvmti/> functions, may be implemented as VM code.
duke@0 1184 </constant>
duke@0 1185 <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000">
duke@0 1186 Defined by VM vendor.
duke@0 1187 </constant>
duke@0 1188 <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000">
duke@0 1189 Defined by VM vendor.
duke@0 1190 </constant>
duke@0 1191 <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000">
duke@0 1192 Defined by VM vendor.
duke@0 1193 </constant>
duke@0 1194 </constants>
duke@0 1195 The following definitions are used to convert <jvmti/> thread state
duke@0 1196 to <code>java.lang.Thread.State</code> style states.
duke@0 1197 <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits">
duke@0 1198 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK"
duke@0 1200 Mask the state with this before comparison
duke@0 1201 </constant>
duke@0 1202 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW"
duke@0 1203 num="0">
duke@0 1204 <code>java.lang.Thread.State.NEW</code>
duke@0 1205 </constant>
duke@0 1208 <code>java.lang.Thread.State.TERMINATED</code>
duke@0 1209 </constant>
duke@0 1210 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE"
duke@0 1212 <code>java.lang.Thread.State.RUNNABLE</code>
duke@0 1213 </constant>
duke@0 1214 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED"
duke@0 1216 <code>java.lang.Thread.State.BLOCKED</code>
duke@0 1217 </constant>
duke@0 1218 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING"
duke@0 1220 <code>java.lang.Thread.State.WAITING</code>
duke@0 1221 </constant>
duke@0 1224 <code>java.lang.Thread.State.TIMED_WAITING</code>
duke@0 1225 </constant>
duke@0 1226 </constants>
duke@0 1227 <b>Rules</b>
duke@0 1228 <p/>
duke@0 1229 There can be no more than one answer to a question, although there can be no
duke@0 1230 answer (because the answer is unknown, does not apply, or none of the answers is
duke@0 1231 correct). An answer is set only when the enclosing answers match.
duke@0 1232 That is, no more than one of
duke@0 1233 <ul type="circle">
duke@0 1234 <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li>
duke@0 1235 <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li>
duke@0 1236 <li><code>JVMTI_THREAD_STATE_WAITING</code></li>
duke@0 1237 </ul>
duke@0 1238 can be set (a <tm>J2SE</tm> compliant implementation will always set
duke@0 1239 one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set).
duke@0 1240 And if any of these are set, the enclosing answer
duke@0 1241 <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
duke@0 1242 No more than one of
duke@0 1243 <ul type="circle">
duke@0 1244 <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li>
duke@0 1245 <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li>
duke@0 1246 </ul>
duke@0 1247 can be set (a <tm>J2SE</tm> compliant implementation will always set
duke@0 1248 one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set).
duke@0 1249 And if either is set, the enclosing answers
duke@0 1250 <code>JVMTI_THREAD_STATE_ALIVE</code> and
duke@0 1251 <code>JVMTI_THREAD_STATE_WAITING</code> are set.
duke@0 1252 No more than one of
duke@0 1253 <ul type="circle">
duke@0 1254 <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li>
duke@0 1255 <li><code>JVMTI_THREAD_STATE_PARKED</code></li>
duke@0 1256 <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li>
duke@0 1257 </ul>
duke@0 1258 can be set. And if any of these is set, the enclosing answers
duke@0 1259 <code>JVMTI_THREAD_STATE_ALIVE</code> and
duke@0 1260 <code>JVMTI_THREAD_STATE_WAITING</code> are set.
duke@0 1261 Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set,
duke@0 1262 then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set.
duke@0 1263 If a state <i>A</i> is implemented using the mechanism of
duke@0 1264 state <i>B</i> then it is state <i>A</i> which
duke@0 1265 is returned by this function.
duke@0 1266 For example, if <code>Thread.sleep(long)</code>
duke@0 1267 is implemented using <code>Object.wait(long)</code>
duke@0 1268 then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code>
duke@0 1269 which is returned.
duke@0 1270 More than one of
duke@0 1271 <ul type="circle">
duke@0 1272 <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li>
duke@0 1273 <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li>
duke@0 1274 <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li>
duke@0 1275 </ul>
duke@0 1276 can be set, but if any is set,
duke@0 1277 <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
duke@0 1278 <p/>
duke@0 1279 And finally,
duke@0 1280 <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless
duke@0 1281 <code>JVMTI_THREAD_STATE_ALIVE</code> is not set.
duke@0 1282 <p/>
duke@0 1283 The thread state representation is designed for extension in future versions
duke@0 1284 of the specification; thread state values should be used accordingly, that is
duke@0 1285 they should not be used as ordinals.
duke@0 1286 Most queries can be made by testing a single bit, if use in a switch statement is desired,
duke@0 1287 the state bits should be masked with the interesting bits.
duke@0 1288 All bits not defined above are reserved for future use.
duke@0 1289 A VM, compliant to the current specification, must set reserved bits to zero.
duke@0 1290 An agent should ignore reserved bits --
duke@0 1291 they should not be assumed to be zero and thus should not be included in comparisons.
duke@0 1292 <p/>
duke@0 1293 <b>Examples</b>
duke@0 1294 <p/>
duke@0 1295 Note that the values below exclude reserved and vendor bits.
duke@0 1296 <p/>
duke@0 1297 The state of a thread blocked at a <code>synchronized</code>-statement would be:
duke@0 1298 <example>
duke@0 1300 </example>
duke@0 1301 The state of a thread which hasn't started yet would be:
duke@0 1302 <example>
duke@0 1303 0
duke@0 1304 </example>
duke@0 1305 The state of a thread at a <code>Object.wait(3000)</code> would be:
duke@0 1306 <example>
duke@0 1310 </example>
duke@0 1311 The state of a thread suspended while runnable would be:
duke@0 1312 <example>
duke@0 1314 </example>
duke@0 1315 <p/>
duke@0 1316 <b>Testing the State</b>
duke@0 1317 <p/>
duke@0 1318 In most cases, the thread state can be determined by testing the one bit corresponding
duke@0 1319 to that question. For example, the code to test if a thread is sleeping:
duke@0 1320 <example>
duke@0 1321 jint state;
duke@0 1322 jvmtiError err;
duke@0 1323
duke@0 1324 err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
duke@0 1325 if (err == JVMTI_ERROR_NONE) {
duke@0 1326 if (state &amp; JVMTI_THREAD_STATE_SLEEPING) { ...
duke@0 1327 </example>
duke@0 1328 <p/>
duke@0 1329 For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be:
duke@0 1330 <example>
duke@0 1331 if (state &amp; JVMTI_THREAD_STATE_WAITING) { ...
duke@0 1332 </example>
duke@0 1333 For some states, more than one bit will need to be tested as is the case
duke@0 1334 when testing if a thread has not yet been started:
duke@0 1335 <example>
duke@0 1336 if ((state &amp; (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0) { ...
duke@0 1337 </example>
duke@0 1338 To distinguish timed from untimed <code>Object.wait</code>:
duke@0 1339 <example>
duke@0 1340 if (state &amp; JVMTI_THREAD_STATE_IN_OBJECT_WAIT) {
duke@0 1341 if (state &amp; JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT) {
duke@0 1342 printf("in Object.wait(long timeout)\n");
duke@0 1343 } else {
duke@0 1344 printf("in Object.wait()\n");
duke@0 1345 }
duke@0 1346 }
duke@0 1347 </example>
duke@0 1348 <p/>
duke@0 1349 <b>Relationship to <code>java.lang.Thread.State</code></b>
duke@0 1350 <p/>
duke@0 1351 The thread state represented by <code>java.lang.Thread.State</code>
duke@0 1352 returned from <code>java.lang.Thread.getState()</code> is a subset of the
duke@0 1353 information returned from this function.
duke@0 1354 The corresponding <code>java.lang.Thread.State</code> can be determined
duke@0 1355 by using the provided conversion masks.
duke@0 1356 For example, this returns the name of the <code>java.lang.Thread.State</code> thread state:
duke@0 1357 <example>
duke@0 1358 err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
duke@0 1359 abortOnError(err);
duke@0 1360 switch (state &amp; JVMTI_JAVA_LANG_THREAD_STATE_MASK) {
duke@0 1362 return "NEW";
duke@0 1364 return "TERMINATED";
duke@0 1366 return "RUNNABLE";
duke@0 1368 return "BLOCKED";
duke@0 1370 return "WAITING";
duke@0 1372 return "TIMED_WAITING";
duke@0 1373 }
duke@0 1374 </example>
duke@0 1375 </description>
duke@0 1376 <origin>new</origin>
duke@0 1377 <capabilities>
duke@0 1378 </capabilities>
duke@0 1379 <parameters>
duke@0 1380 <param id="thread">
duke@0 1381 <jthread null="current" started="maybe" impl="noconvert"/>
duke@0 1382 <description>
duke@0 1383 The thread to query.
duke@0 1384 </description>
duke@0 1385 </param>
duke@0 1386 <param id="thread_state_ptr">
duke@0 1387 <outptr><jint/></outptr>
duke@0 1388 <description>
duke@0 1389 On return, points to state flags,
duke@0 1390 as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>.
duke@0 1391 </description>
duke@0 1392 </param>
duke@0 1393 </parameters>
duke@0 1394 <errors>
duke@0 1395 </errors>
duke@0 1396 </function>
duke@0 1397
duke@0 1398 <function id="GetCurrentThread" phase="start" num="18" since="1.1">
duke@0 1399 <synopsis>Get Current Thread</synopsis>
duke@0 1400 <description>
duke@0 1401 Get the current thread.
duke@0 1402 The current thread is the Java programming language thread which has called the function.
duke@0 1403 <p/>
duke@0 1404 Note that most <jvmti/> functions that take a thread
duke@0 1405 as an argument will accept <code>NULL</code> to mean
duke@0 1406 the current thread.
duke@0 1407 </description>
duke@0 1408 <origin>new</origin>
duke@0 1409 <capabilities>
duke@0 1410 </capabilities>
duke@0 1411 <parameters>
duke@0 1412 <param id="thread_ptr">
duke@0 1413 <outptr><jthread/></outptr>
duke@0 1414 <description>
duke@0 1415 On return, points to the current thread.
duke@0 1416 </description>
duke@0 1417 </param>
duke@0 1418 </parameters>
duke@0 1419 <errors>
duke@0 1420 </errors>
duke@0 1421 </function>
duke@0 1422
duke@0 1423 <function id="GetAllThreads" num="4">
duke@0 1424 <synopsis>Get All Threads</synopsis>
duke@0 1425 <description>
duke@0 1426 Get all live threads.
duke@0 1427 The threads are Java programming language threads;
duke@0 1428 that is, threads that are attached to the VM.
duke@0 1429 A thread is live if <code>java.lang.Thread.isAlive()</code>
duke@0 1430 would return <code>true</code>, that is, the thread has
duke@0 1431 been started and has not yet died.
duke@0 1432 The universe of threads is determined by the context of the <jvmti/>
duke@0 1433 environment, which typically is all threads attached to the VM.
duke@0 1434 Note that this includes <jvmti/> agent threads
duke@0 1435 (see <functionlink id="RunAgentThread"/>).
duke@0 1436 </description>
duke@0 1437 <origin>jvmdi</origin>
duke@0 1438 <capabilities>
duke@0 1439 </capabilities>
duke@0 1440 <parameters>
duke@0 1441 <param id="threads_count_ptr">
duke@0 1442 <outptr><jint/></outptr>
duke@0 1443 <description>
duke@0 1444 On return, points to the number of running threads.
duke@0 1445 </description>
duke@0 1446 </param>
duke@0 1447 <param id="threads_ptr">
duke@0 1448 <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
duke@0 1449 <description>
duke@0 1450 On return, points to an array of references, one
duke@0 1451 for each running thread.
duke@0 1452 </description>
duke@0 1453 </param>
duke@0 1454 </parameters>
duke@0 1455 <errors>
duke@0 1456 </errors>
duke@0 1457 </function>
duke@0 1458
duke@0 1459 <function id="SuspendThread" num="5">
duke@0 1460 <synopsis>Suspend Thread</synopsis>
duke@0 1461 <description>
duke@0 1462 Suspend the specified thread. If the calling thread is specified,
duke@0 1463 this function will not return until some other thread calls
duke@0 1464 <functionlink id="ResumeThread"></functionlink>.
duke@0 1465 If the thread is currently suspended, this function
duke@0 1466 does nothing and returns an error.
duke@0 1467 </description>
duke@0 1468 <origin>jvmdi</origin>
duke@0 1469 <capabilities>
duke@0 1470 <required id="can_suspend"></required>
duke@0 1471 </capabilities>
duke@0 1472 <parameters>
duke@0 1473 <param id="thread">
duke@0 1474 <jthread null="current"/>
duke@0 1475 <description>
duke@0 1476 The thread to suspend.
duke@0 1477 </description>
duke@0 1478 </param>
duke@0 1479 </parameters>
duke@0 1480 <errors>
duke@0 1481 <error id="JVMTI_ERROR_THREAD_SUSPENDED">
duke@0 1482 Thread already suspended.
duke@0 1483 </error>
duke@0 1484 </errors>
duke@0 1485 </function>
duke@0 1486
duke@0 1487 <elide>
duke@0 1488 <function id="SuspendAllThreads" num="101">
duke@0 1489 <synopsis>Suspend All Threads</synopsis>
duke@0 1490 <description>
duke@0 1491 <issue>
duke@0 1492 There has been no explicit call for this function, and it will
duke@0 1493 thus be removed if there is no interest.
duke@0 1494 </issue>
duke@0 1495 Suspend all live threads except:
duke@0 1496 <ul>
duke@0 1497 <li>already suspended threads</li>
duke@0 1498 <li>those listed in <paramlink id="except_list"></paramlink></li>
duke@0 1499 <li>certain system (non application) threads, as determined
duke@0 1500 by the VM implementation</li>
duke@0 1501 </ul>
duke@0 1502 The threads are Java programming language threads;
duke@0 1503 native threads which are not attached to the VM are not
duke@0 1504 Java programming language threads.
duke@0 1505 A thread is live if <code>java.lang.Thread.isAlive()</code>
duke@0 1506 would return <code>true</code>, that is, the thread has
duke@0 1507 been started and has not yet died.
duke@0 1508 The universe of threads is determined
duke@0 1509 by the context of the <jvmti/>
duke@0 1510 environment, which, typically, is all threads attached to the VM,
duke@0 1511 except critical VM internal threads and <jvmti/> agent threads
duke@0 1512 (see <functionlink id="RunAgentThread"/>).
duke@0 1513 <p/>
duke@0 1514 If the calling thread is specified,
duke@0 1515 all other threads are suspended first then the caller thread is suspended -
duke@0 1516 this function will not return until some other thread calls
duke@0 1517 <functionlink id="ResumeThread"></functionlink>.
duke@0 1518 <p/>
duke@0 1519 The list of actually
duke@0 1520 suspended threads is returned in
duke@0 1521 <paramlink id="suspended_list_ptr"></paramlink>.
duke@0 1522 Suspension is as defined in <functionlink id="SuspendThread"></functionlink>.
duke@0 1523 <functionlink id="ResumeThreadList"></functionlink>
duke@0 1524 can be used to resume the suspended threads.
duke@0 1525 </description>
duke@0 1526 <origin>new</origin>
duke@0 1527 <capabilities>
duke@0 1528 <required id="can_suspend"></required>
duke@0 1529 </capabilities>
duke@0 1530 <parameters>
duke@0 1531 <param id="except_count">
duke@0 1532 <jint min="0"/>
duke@0 1533 <description>
duke@0 1534 The number of threads in the list of threads not to be suspended.
duke@0 1535 </description>
duke@0 1536 </param>
duke@0 1537 <param id="except_list">
duke@0 1538 <inbuf incount="except_count">
duke@0 1539 <jthread/>
duke@0 1540 <nullok>not an error if <code>except_count == 0</code></nullok>
duke@0 1541 </inbuf>
duke@0 1542 <description>
duke@0 1543 The list of threads not to be suspended.
duke@0 1544 </description>
duke@0 1545 </param>
duke@0 1546 <param id="suspended_count_ptr">
duke@0 1547 <outptr><jint/></outptr>
duke@0 1548 <description>
duke@0 1549 On return, points to the number of threads suspended by this call.
duke@0 1550 </description>
duke@0 1551 </param>
duke@0 1552 <param id="suspended_list_ptr">
duke@0 1553 <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf>
duke@0 1554 <description>
duke@0 1555 On return, points to an array of references, one
duke@0 1556 for each thread suspended.
duke@0 1557 </description>
duke@0 1558 </param>
duke@0 1559 </parameters>
duke@0 1560 <errors>
duke@0 1561 <error id="JVMTI_ERROR_INVALID_THREAD">
duke@0 1562 A thread in <paramlink id="except_list"></paramlink> was invalid.
duke@0 1563 </error>
duke@0 1564 <error id="JVMTI_ERROR_NULL_POINTER">
duke@0 1565 Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
duke@0 1566 and <paramlink id="except_count"></paramlink> was non-zero.
duke@0 1567 </error>
duke@0 1568 </errors>
duke@0 1569 </function>
duke@0 1570 </elide>
duke@0 1571
duke@0 1572 <function id="SuspendThreadList" num="92">
duke@0 1573 <synopsis>Suspend Thread List</synopsis>
duke@0 1574 <description>
duke@0 1575 Suspend the <paramlink id="request_count"></paramlink>
duke@0 1576 threads specified in the
duke@0 1577 <paramlink id="request_list"></paramlink> array.
duke@0 1578 Threads may be resumed with
duke@0 1579 <functionlink id="ResumeThreadList"></functionlink> or
duke@0 1580 <functionlink id="ResumeThread"></functionlink>.
duke@0 1581 If the calling thread is specified in the
duke@0 1582 <paramlink id="request_list"></paramlink> array, this function will
duke@0 1583 not return until some other thread resumes it.
duke@0 1584 Errors encountered in the suspension of a thread
duke@0 1585 are returned in the <paramlink id="results"></paramlink>
duke@0 1586 array, <b>not</b> in the return value of this function.
duke@0 1587 Threads that are currently suspended do not change state.
duke@0 1588 </description>
duke@0 1589 <origin>jvmdi</origin>
duke@0 1590 <capabilities>
duke@0 1591 <required id="can_suspend"></required>
duke@0 1592 </capabilities>
duke@0 1593 <parameters>
duke@0 1594 <param id="request_count">
duke@0 1595 <jint min="0"/>
duke@0 1596 <description>
duke@0 1597 The number of threads to suspend.
duke@0 1598 </description>
duke@0 1599 </param>
duke@0 1600 <param id="request_list">
duke@0 1601 <inbuf incount="request_count"><jthread/></inbuf>
duke@0 1602 <description>
duke@0 1603 The list of threads to suspend.
duke@0 1604 </description>
duke@0 1605 </param>
duke@0 1606 <param id="results">
duke@0 1607 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
duke@0 1608 <description>
duke@0 1609 An agent supplied array of
duke@0 1610 <paramlink id="request_count"></paramlink> elements.
duke@0 1611 On return, filled with the error code for
duke@0 1612 the suspend of the corresponding thread.
duke@0 1613 The error code will be
duke@0 1614 <errorlink id="JVMTI_ERROR_NONE"></errorlink>
duke@0 1615 if the thread was suspended by this call.
duke@0 1616 Possible error codes are those specified
duke@0 1617 for <functionlink id="SuspendThread"></functionlink>.
duke@0 1618 </description>
duke@0 1619 </param>
duke@0 1620 </parameters>
duke@0 1621 <errors>
duke@0 1622 </errors>
duke@0 1623 </function>
duke@0 1624
duke@0 1625 <function id="ResumeThread" num="6">
duke@0 1626 <synopsis>Resume Thread</synopsis>
duke@0 1627 <description>
duke@0 1628 Resume a suspended thread.
duke@0 1629 Any threads currently suspended through
duke@0 1630 a <jvmti/> suspend function (eg.
duke@0 1631 <functionlink id="SuspendThread"></functionlink>)
duke@0 1632 or <code>java.lang.Thread.suspend()</code>
duke@0 1633 will resume execution;
duke@0 1634 all other threads are unaffected.
duke@0 1635 </description>
duke@0 1636 <origin>jvmdi</origin>
duke@0 1637 <capabilities>
duke@0 1638 <required id="can_suspend"></required>
duke@0 1639 </capabilities>
duke@0 1640 <parameters>
duke@0 1641 <param id="thread">
duke@0 1642 <jthread/>
duke@0 1643 <description>
duke@0 1644 The thread to resume.
duke@0 1645 </description>
duke@0 1646 </param>
duke@0 1647 </parameters>
duke@0 1648 <errors>
duke@0 1649 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
duke@0 1650 Thread was not suspended.
duke@0 1651 </error>
duke@0 1652 <error id="JVMTI_ERROR_INVALID_TYPESTATE">
duke@0 1653 The state of the thread has been modified, and is now inconsistent.
duke@0 1654 </error>
duke@0 1655 </errors>
duke@0 1656 </function>
duke@0 1657
duke@0 1658 <function id="ResumeThreadList" num="93">
duke@0 1659 <synopsis>Resume Thread List</synopsis>
duke@0 1660 <description>
duke@0 1661 Resume the <paramlink id="request_count"></paramlink>
duke@0 1662 threads specified in the
duke@0 1663 <paramlink id="request_list"></paramlink> array.
duke@0 1664 Any thread suspended through
duke@0 1665 a <jvmti/> suspend function (eg.
duke@0 1666 <functionlink id="SuspendThreadList"></functionlink>)
duke@0 1667 or <code>java.lang.Thread.suspend()</code>
duke@0 1668 will resume execution.
duke@0 1669 </description>
duke@0 1670 <origin>jvmdi</origin>
duke@0 1671 <capabilities>
duke@0 1672 <required id="can_suspend"></required>
duke@0 1673 </capabilities>
duke@0 1674 <parameters>
duke@0 1675 <param id="request_count">
duke@0 1676 <jint min="0"/>
duke@0 1677 <description>
duke@0 1678 The number of threads to resume.
duke@0 1679 </description>
duke@0 1680 </param>
duke@0 1681 <param id="request_list">
duke@0 1682 <inbuf incount="request_count"><jthread/></inbuf>
duke@0 1683 <description>
duke@0 1684 The threads to resume.
duke@0 1685 </description>
duke@0 1686 </param>
duke@0 1687 <param id="results">
duke@0 1688 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
duke@0 1689 <description>
duke@0 1690 An agent supplied array of
duke@0 1691 <paramlink id="request_count"></paramlink> elements.
duke@0 1692 On return, filled with the error code for
duke@0 1693 the resume of the corresponding thread.
duke@0 1694 The error code will be
duke@0 1695 <errorlink id="JVMTI_ERROR_NONE"></errorlink>
duke@0 1696 if the thread was suspended by this call.
duke@0 1697 Possible error codes are those specified
duke@0 1698 for <functionlink id="ResumeThread"></functionlink>.
duke@0 1699 </description>
duke@0 1700 </param>
duke@0 1701 </parameters>
duke@0 1702 <errors>
duke@0 1703 </errors>
duke@0 1704 </function>
duke@0 1705
duke@0 1706 <function id="StopThread" num="7">
duke@0 1707 <synopsis>Stop Thread</synopsis>
duke@0 1708 <description>
duke@0 1709 Send the specified asynchronous exception to the specified thread
duke@0 1710 (similar to <code>java.lang.Thread.stop</code>).
duke@0 1711 Normally, this function is used to kill the specified thread with an
duke@0 1712 instance of the exception <code>ThreadDeath</code>.
duke@0 1713 </description>
duke@0 1714 <origin>jvmdi</origin>
duke@0 1715 <capabilities>
duke@0 1716 <required id="can_signal_thread"></required>
duke@0 1717 </capabilities>
duke@0 1718 <parameters>
duke@0 1719 <param id="thread">
duke@0 1720 <jthread/>
duke@0 1721 <description>
duke@0 1722 The thread to stop.
duke@0 1723 </description>
duke@0 1724 </param>
duke@0 1725 <param id="exception">
duke@0 1726 <jobject/>
duke@0 1727 <description>
duke@0 1728 The asynchronous exception object.
duke@0 1729 </description>
duke@0 1730 </param>
duke@0 1731 </parameters>
duke@0 1732 <errors>
duke@0 1733 </errors>
duke@0 1734 </function>
duke@0 1735
duke@0 1736 <function id="InterruptThread" num="8">
duke@0 1737 <synopsis>Interrupt Thread</synopsis>
duke@0 1738 <description>
duke@0 1739 Interrupt the specified thread
duke@0 1740 (similar to <code>java.lang.Thread.interrupt</code>).
duke@0 1741 </description>
duke@0 1742 <origin>jvmdi</origin>
duke@0 1743 <capabilities>
duke@0 1744 <required id="can_signal_thread"></required>
duke@0 1745 </capabilities>
duke@0 1746 <parameters>
duke@0 1747 <param id="thread">
duke@0 1748 <jthread impl="noconvert"/>
duke@0 1749 <description>
duke@0 1750 The thread to interrupt.
duke@0 1751 </description>
duke@0 1752 </param>
duke@0 1753 </parameters>
duke@0 1754 <errors>
duke@0 1755 </errors>
duke@0 1756 </function>
duke@0 1757
duke@0 1758 <function id="GetThreadInfo" num="9">
duke@0 1759 <synopsis>Get Thread Info</synopsis>
duke@0 1760 <typedef id="jvmtiThreadInfo" label="Thread information structure">
duke@0 1761 <field id="name">
duke@0 1762 <allocfieldbuf><char/></allocfieldbuf>
duke@0 1763 <description>
duke@0 1764 The thread name, encoded as a
duke@0 1765 <internallink id="mUTF">modified UTF-8</internallink> string.
duke@0 1766 </description>
duke@0 1767 </field>
duke@0 1768 <field id="priority">
duke@0 1769 <jint/>
duke@0 1770 <description>
duke@0 1771 The thread priority. See the thread priority constants:
duke@0 1772 <datalink id="jvmtiThreadPriority"></datalink>.
duke@0 1773 </description>
duke@0 1774 </field>
duke@0 1775 <field id="is_daemon">
duke@0 1776 <jboolean/>
duke@0 1777 <description>
duke@0 1778 Is this a daemon thread?
duke@0 1779 </description>
duke@0 1780 </field>
duke@0 1781 <field id="thread_group">
duke@0 1782 <jthreadGroup/>
duke@0 1783 <description>
duke@0 1784 The thread group to which this thread belongs.
duke@0 1785 <code>NULL</code> if the thread has died.
duke@0 1786 </description>
duke@0 1787 </field>
duke@0 1788 <field id="context_class_loader">
duke@0 1789 <jobject/>
duke@0 1790 <description>
duke@0 1791 The context class loader associated with this thread.
duke@0 1792 </description>
duke@0 1793 </field>
duke@0 1794 </typedef>
duke@0 1795 <description>
duke@0 1796 Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure
duke@0 1797 are filled in with details of the specified thread.
duke@0 1798 </description>
duke@0 1799 <origin>jvmdi</origin>
duke@0 1800 <capabilities>
duke@0 1801 </capabilities>
duke@0 1802 <parameters>
duke@0 1803 <param id="thread">
duke@0 1804 <jthread null="current" impl="noconvert" started="maybe"/>
duke@0 1805 <description>
duke@0 1806 The thread to query.
duke@0 1807 </description>
duke@0 1808 </param>
duke@0 1809 <param id="info_ptr">
duke@0 1810 <outptr><struct>jvmtiThreadInfo</struct></outptr>
duke@0 1811 <description>
duke@0 1812 On return, filled with information describing the specified thread.
duke@0 1813 <p/>
duke@0 1814 For JDK 1.1 implementations that don't
duke@0 1815 recognize context class loaders,
duke@0 1816 the <code>context_class_loader</code> field will be NULL.
duke@0 1817 </description>
duke@0 1818 </param>
duke@0 1819 </parameters>
duke@0 1820 <errors>
duke@0 1821 </errors>
duke@0 1822 </function>
duke@0 1823
duke@0 1824 <function id="GetOwnedMonitorInfo" num="10">
duke@0 1825 <synopsis>Get Owned Monitor Info</synopsis>
duke@0 1826 <description>
duke@0 1827 Get information about the monitors owned by the
duke@0 1828 specified thread.
duke@0 1829 </description>
duke@0 1830 <origin>jvmdiClone</origin>
duke@0 1831 <capabilities>
duke@0 1832 <required id="can_get_owned_monitor_info"></required>
duke@0 1833 </capabilities>
duke@0 1834 <parameters>
duke@0 1835 <param id="thread">
duke@0 1836 <jthread null="current"/>
duke@0 1837 <description>
duke@0 1838 The thread to query.
duke@0 1839 </description>
duke@0 1840 </param>
duke@0 1841 <param id="owned_monitor_count_ptr">
duke@0 1842 <outptr><jint/></outptr>
duke@0 1843 <description>
duke@0 1844 The number of monitors returned.
duke@0 1845 </description>
duke@0 1846 </param>
duke@0 1847 <param id="owned_monitors_ptr">
duke@0 1848 <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf>
duke@0 1849 <description>
duke@0 1850 The array of owned monitors.
duke@0 1851 </description>
duke@0 1852 </param>
duke@0 1853 </parameters>
duke@0 1854 <errors>
duke@0 1855 </errors>
duke@0 1856 </function>
duke@0 1857
duke@0 1858 <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1">
duke@0 1859 <synopsis>Get Owned Monitor Stack Depth Info</synopsis>
duke@0 1860 <typedef id="jvmtiMonitorStackDepthInfo"
duke@0 1861 label="Monitor stack depth information structure">
duke@0 1862 <field id="monitor">
duke@0 1863 <jobject/>
duke@0 1864 <description>
duke@0 1865 The owned monitor.
duke@0 1866 </description>
duke@0 1867 </field>
duke@0 1868 <field id="stack_depth">
duke@0 1869 <jint/>
duke@0 1870 <description>
duke@0 1871 The stack depth. Corresponds to the stack depth used in the
duke@0 1872 <internallink id="stack">Stack Frame functions</internallink>.
duke@0 1873 That is, zero is the current frame, one is the frame which
duke@0 1874 called the current frame. And it is negative one if the
duke@0 1875 implementation cannot determine the stack depth (e.g., for
duke@0 1876 monitors acquired by JNI <code>MonitorEnter</code>).
duke@0 1877 </description>
duke@0 1878 </field>
duke@0 1879 </typedef>
duke@0 1880 <description>
duke@0 1881 Get information about the monitors owned by the
duke@0 1882 specified thread and the depth of the stack frame which locked them.
duke@0 1883 </description>
duke@0 1884 <origin>new</origin>
duke@0 1885 <capabilities>
duke@0 1886 <required id="can_get_owned_monitor_stack_depth_info"></required>
duke@0 1887 </capabilities>
duke@0 1888 <parameters>
duke@0 1889 <param id="thread">
duke@0 1890 <jthread null="current"/>
duke@0 1891 <description>
duke@0 1892 The thread to query.
duke@0 1893 </description>
duke@0 1894 </param>
duke@0 1895 <param id="monitor_info_count_ptr">
duke@0 1896 <outptr><jint/></outptr>
duke@0 1897 <description>
duke@0 1898 The number of monitors returned.
duke@0 1899 </description>
duke@0 1900 </param>
duke@0 1901 <param id="monitor_info_ptr">
duke@0 1902 <allocbuf outcount="owned_monitor_depth_count_ptr">
duke@0 1903 <struct>jvmtiMonitorStackDepthInfo</struct>
duke@0 1904 </allocbuf>
duke@0 1905 <description>
duke@0 1906 The array of owned monitor depth information.
duke@0 1907 </description>
duke@0 1908 </param>
duke@0 1909 </parameters>
duke@0 1910 <errors>
duke@0 1911 </errors>
duke@0 1912 </function>
duke@0 1913
duke@0 1914 <function id="GetCurrentContendedMonitor" num="11">
duke@0 1915 <synopsis>Get Current Contended Monitor</synopsis>
duke@0 1916 <description>
duke@0 1917 Get the object, if any, whose monitor the specified thread is waiting to
duke@0 1918 enter or waiting to regain through <code>java.lang.Object.wait</code>.
duke@0 1919 </description>
duke@0 1920 <origin>jvmdi</origin>
duke@0 1921 <capabilities>
duke@0 1922 <required id="can_get_current_contended_monitor"></required>
duke@0 1923 </capabilities>
duke@0 1924 <parameters>
duke@0 1925 <param id="thread">
duke@0 1926 <jthread null="current"/>
duke@0 1927 <description>
duke@0 1928 The thread to query.
duke@0 1929 </description>
duke@0 1930 </param>
duke@0 1931 <param id="monitor_ptr">
duke@0 1932 <outptr><jobject/></outptr>
duke@0 1933 <description>
duke@0 1934 On return, filled with the current contended monitor, or
duke@0 1935 NULL if there is none.
duke@0 1936 </description>
duke@0 1937 </param>
duke@0 1938 </parameters>
duke@0 1939 <errors>
duke@0 1940 </errors>
duke@0 1941 </function>
duke@0 1942
duke@0 1943 <callback id="jvmtiStartFunction">
duke@0 1944 <void/>
duke@0 1945 <synopsis>Agent Start Function</synopsis>
duke@0 1946 <description>
duke@0 1947 Agent supplied callback function.
duke@0 1948 This function is the entry point for an agent thread
duke@0 1949 started with
duke@0 1950 <functionlink id="RunAgentThread"></functionlink>.
duke@0 1951 </description>
duke@0 1952 <parameters>
duke@0 1953 <param id="jvmti_env">
duke@0 1954 <outptr>
duke@0 1955 <struct>jvmtiEnv</struct>
duke@0 1956 </outptr>
duke@0 1957 <description>
duke@0 1958 The <jvmti/> environment.
duke@0 1959 </description>
duke@0 1960 </param>
duke@0 1961 <param id="jni_env">
duke@0 1962 <outptr>
duke@0 1963 <struct>JNIEnv</struct>
duke@0 1964 </outptr>
duke@0 1965 <description>
duke@0 1966 The JNI environment.
duke@0 1967 </description>
duke@0 1968 </param>
duke@0 1969 <param id="arg">
duke@0 1970 <outptr>
duke@0 1971 <void/>
duke@0 1972 </outptr>
duke@0 1973 <description>
duke@0 1974 The <code>arg</code> parameter passed to
duke@0 1975 <functionlink id="RunAgentThread"></functionlink>.
duke@0 1976 </description>
duke@0 1977 </param>
duke@0 1978 </parameters>
duke@0 1979 </callback>
duke@0 1980
duke@0 1981 <function id="RunAgentThread" num="12">
duke@0 1982 <synopsis>Run Agent Thread</synopsis>
duke@0 1983 <description>
duke@0 1984 Starts the execution of an agent thread. with the specified native function.
duke@0 1985 The parameter <paramlink id="arg"></paramlink> is forwarded on to the
duke@0 1986 <functionlink id="jvmtiStartFunction">start function</functionlink>
duke@0 1987 (specified with <paramlink id="proc"></paramlink>) as its single argument.
duke@0 1988 This function allows the creation of agent threads
duke@0 1989 for handling communication with another process or for handling events
duke@0 1990 without the need to load a special subclass of <code>java.lang.Thread</code> or
duke@0 1991 implementer of <code>java.lang.Runnable</code>.
duke@0 1992 Instead, the created thread can run entirely in native code.
duke@0 1993 However, the created thread does require a newly created instance
duke@0 1994 of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to
duke@0 1995 which it will be associated.
duke@0 1996 The thread object can be created with JNI calls.
duke@0 1997 <p/>
duke@0 1998 The following common thread priorities are provided for your convenience:
duke@0 1999 <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const">
duke@0 2000 <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1">
duke@0 2001 Minimum possible thread priority
duke@0 2002 </constant>
duke@0 2003 <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5">
duke@0 2004 Normal thread priority
duke@0 2005 </constant>
duke@0 2006 <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10">
duke@0 2007 Maximum possible thread priority
duke@0 2008 </constant>
duke@0 2009 </constants>
duke@0 2010 <p/>
duke@0 2011 The new thread is started as a daemon thread with the specified
duke@0 2012 <paramlink id="priority"></paramlink>.
duke@0 2013 If enabled, a <eventlink id="ThreadStart"/> event will be sent.
duke@0 2014 <p/>
duke@0 2015 Since the thread has been started, the thread will be live when this function
duke@0 2016 returns, unless the thread has died immediately.
duke@0 2017 <p/>
duke@0 2018 The thread group of the thread is ignored -- specifically, the thread is not
duke@0 2019 added to the thread group and the thread is not seen on queries of the thread
duke@0 2020 group at either the Java programming language or <jvmti/> levels.
duke@0 2021 <p/>
duke@0 2022 The thread is not visible to Java programming language queries but is
duke@0 2023 included in <jvmti/> queries (for example,
duke@0 2024 <functionlink id="GetAllThreads"/> and
duke@0 2025 <functionlink id="GetAllStackTraces"/>).
duke@0 2026 <p/>
duke@0 2027 Upon execution of <code>proc</code>, the new thread will be attached to the
duke@0 2028 VM--see the JNI documentation on
duke@0 2029 <externallink id=""
duke@0 2030 >Attaching to the VM</externallink>.
duke@0 2031 </description>
duke@0 2032 <origin>jvmdiClone</origin>
duke@0 2033 <capabilities>
duke@0 2034 </capabilities>
duke@0 2035 <parameters>
duke@0 2036 <param id="thread">
duke@0 2037 <jthread impl="noconvert" started="no"/>
duke@0 2038 <description>
duke@0 2039 The thread to run.
duke@0 2040 </description>
duke@0 2041 </param>
duke@0 2042 <param id="proc">
duke@0 2043 <ptrtype>
duke@0 2044 <struct>jvmtiStartFunction</struct>
duke@0 2045 </ptrtype>
duke@0 2046 <description>
duke@0 2047 The start function.
duke@0 2048 </description>
duke@0 2049 </param>
duke@0 2050 <param id="arg">
duke@0 2051 <inbuf>
duke@0 2052 <void/>
duke@0 2053 <nullok><code>NULL</code> is passed to the start function</nullok>
duke@0 2054 </inbuf>
duke@0 2055 <description>
duke@0 2056 The argument to the start function.
duke@0 2057 </description>
duke@0 2058 </param>
duke@0 2059 <param id="priority">
duke@0 2060 <jint/>
duke@0 2061 <description>
duke@0 2062 The priority of the started thread. Any thread
duke@0 2063 priority allowed by <code>java.lang.Thread.setPriority</code> can be used including
duke@0 2064 those in <datalink id="jvmtiThreadPriority"></datalink>.
duke@0 2065 </description>
duke@0 2066 </param>
duke@0 2067 </parameters>
duke@0 2068 <errors>
duke@0 2069 <error id="JVMTI_ERROR_INVALID_PRIORITY">
duke@0 2070 <paramlink id="priority"/> is less than
duke@0 2071 <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>
duke@0 2072 or greater than
duke@0 2073 <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>
duke@0 2074 </error>
duke@0 2075 </errors>
duke@0 2076 </function>
duke@0 2077
duke@0 2078 <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">
duke@0 2079 <synopsis>Set Thread Local Storage</synopsis>
duke@0 2080 <description>
duke@0 2081 The VM stores a pointer value associated with each environment-thread
duke@0 2082 pair. This pointer value is called <i>thread-local storage</i>.
duke@0 2083 This value is <code>NULL</code> unless set with this function.
duke@0 2084 Agents can allocate memory in which they store thread specific
duke@0 2085 information. By setting thread-local storage it can then be
duke@0 2086 accessed with
duke@0 2087 <functionlink id="GetThreadLocalStorage"></functionlink>.
duke@0 2088 <p/>
duke@0 2089 This function is called by the agent to set the value of the <jvmti/>
duke@0 2090 thread-local storage. <jvmti/> supplies to the agent a pointer-size
duke@0 2091 thread-local storage that can be used to record per-thread
duke@0 2092 information.
duke@0 2093 </description>
duke@0 2094 <origin>jvmpi</origin>
duke@0 2095 <capabilities>
duke@0 2096 </capabilities>
duke@0 2097 <parameters>
duke@0 2098 <param id="thread">
duke@0 2099 <jthread null="current"/>
duke@0 2100 <description>
duke@0 2101 Store to this thread.
duke@0 2102 </description>
duke@0 2103 </param>
duke@0 2104 <param id="data">
duke@0 2105 <inbuf>
duke@0 2106 <void/>
duke@0 2107 <nullok>value is set to <code>NULL</code></nullok>
duke@0 2108 </inbuf>
duke@0 2109 <description>
duke@0 2110 The value to be entered into the thread-local storage.
duke@0 2111 </description>
duke@0 2112 </param>
duke@0 2113 </parameters>
duke@0 2114 <errors>
duke@0 2115 </errors>
duke@0 2116 </function>
duke@0 2117
duke@0 2118 <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102">
duke@0 2119 <synopsis>Get Thread Local Storage</synopsis>
duke@0 2120 <description>
duke@0 2121 Called by the agent to get the value of the <jvmti/> thread-local
duke@0 2122 storage.
duke@0 2123 </description>
duke@0 2124 <origin>jvmpi</origin>
duke@0 2125 <capabilities>
duke@0 2126 </capabilities>
duke@0 2127 <parameters>
duke@0 2128 <param id="thread">
duke@0 2129 <jthread null="current" impl="noconvert"/>
duke@0 2130 <description>
duke@0 2131 Retrieve from this thread.
duke@0 2132 </description>
duke@0 2133 </param>
duke@0 2134 <param id="data_ptr">
duke@0 2135 <agentbuf><void/></agentbuf>
duke@0 2136 <description>
duke@0 2137 Pointer through which the value of the thread local
duke@0 2138 storage is returned.
duke@0 2139 If thread-local storage has not been set with
duke@0 2140 <functionlink id="SetThreadLocalStorage"></functionlink> the returned
duke@0 2141 pointer is <code>NULL</code>.
duke@0 2142 </description>
duke@0 2143 </param>
duke@0 2144 </parameters>
duke@0 2145 <errors>
duke@0 2146 </errors>
duke@0 2147 </function>
duke@0 2148
duke@0 2149 </category>
duke@0 2150
duke@0 2151 <category id="thread_groups" label="Thread Group">
duke@0 2152 <intro>
duke@0 2153 </intro>
duke@0 2154
duke@0 2155 <function id="GetTopThreadGroups" num="13">
duke@0 2156 <synopsis>Get Top Thread Groups</synopsis>
duke@0 2157 <description>
duke@0 2158 Return all top-level (parentless) thread groups in the VM.
duke@0 2159 </description>
duke@0 2160 <origin>jvmdi</origin>
duke@0 2161 <capabilities>
duke@0 2162 </capabilities>
duke@0 2163 <parameters>
duke@0 2164 <param id="group_count_ptr">
duke@0 2165 <outptr><jint/></outptr>
duke@0 2166 <description>
duke@0 2167 On return, points to the number of top-level thread groups.
duke@0 2168 </description>
duke@0 2169 </param>
duke@0 2170 <param id="groups_ptr">
duke@0 2171 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
duke@0 2172 <description>
duke@0 2173 On return, refers to a pointer to the top-level thread group array.
duke@0 2174 </description>
duke@0 2175 </param>
duke@0 2176 </parameters>
duke@0 2177 <errors>
duke@0 2178 </errors>
duke@0 2179 </function>
duke@0 2180
duke@0 2181 <function id="GetThreadGroupInfo" num="14">
duke@0 2182 <synopsis>Get Thread Group Info</synopsis>
duke@0 2183 <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure">
duke@0 2184 <field id="parent">
duke@0 2185 <jthreadGroup/>
duke@0 2186 <description>
duke@0 2187 The parent thread group.
duke@0 2188 </description>
duke@0 2189 </field>
duke@0 2190 <field id="name">
duke@0 2191 <allocfieldbuf><char/></allocfieldbuf>
duke@0 2192 <description>
duke@0 2193 The thread group's name, encoded as a
duke@0 2194 <internallink id="mUTF">modified UTF-8</internallink> string.
duke@0 2195 </description>
duke@0 2196 </field>
duke@0 2197 <field id="max_priority">
duke@0 2198 <jint/>
duke@0 2199 <description>
duke@0 2200 The maximum priority for this thread group.
duke@0 2201 </description>
duke@0 2202 </field>
duke@0 2203 <field id="is_daemon">
duke@0 2204 <jboolean/>
duke@0 2205 <description>
duke@0 2206 Is this a daemon thread group?
duke@0 2207 </description>
duke@0 2208 </field>
duke@0 2209 </typedef>
duke@0 2210 <description>
duke@0 2211 Get information about the thread group. The fields of the
duke@0 2212 <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure
duke@0 2213 are filled in with details of the specified thread group.
duke@0 2214 </description>
duke@0 2215 <origin>jvmdi</origin>
duke@0 2216 <capabilities>
duke@0 2217 </capabilities>
duke@0 2218 <parameters>
duke@0 2219 <param id="group">
duke@0 2220 <jthreadGroup/>
duke@0 2221 <description>
duke@0 2222 The thread group to query.
duke@0 2223 </description>
duke@0 2224 </param>
duke@0 2225 <param id="info_ptr">
duke@0 2226 <outptr><struct>jvmtiThreadGroupInfo</struct></outptr>
duke@0 2227 <description>
duke@0 2228 On return, filled with information describing the specified
duke@0 2229 thread group.
duke@0 2230 </description>
duke@0 2231 </param>
duke@0 2232 </parameters>
duke@0 2233 <errors>
duke@0 2234 </errors>
duke@0 2235 </function>
duke@0 2236
duke@0 2237 <function id="GetThreadGroupChildren" num="15">
duke@0 2238 <synopsis>Get Thread Group Children</synopsis>
duke@0 2239 <description>
duke@0 2240 Get the live threads and active subgroups in this thread group.
duke@0 2241 </description>
duke@0 2242 <origin>jvmdi</origin>
duke@0 2243 <capabilities>
duke@0 2244 </capabilities>
duke@0 2245 <parameters>
duke@0 2246 <param id="group">
duke@0 2247 <jthreadGroup/>
duke@0 2248 <description>
duke@0 2249 The group to query.
duke@0 2250 </description>
duke@0 2251 </param>
duke@0 2252 <param id="thread_count_ptr">
duke@0 2253 <outptr><jint/></outptr>
duke@0 2254 <description>
duke@0 2255 On return, points to the number of live threads in this thread group.
duke@0 2256 </description>
duke@0 2257 </param>
duke@0 2258 <param id="threads_ptr">
duke@0 2259 <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf>
duke@0 2260 <description>
duke@0 2261 On return, points to an array of the live threads in this thread group.
duke@0 2262 </description>
duke@0 2263 </param>
duke@0 2264 <param id="group_count_ptr">
duke@0 2265 <outptr><jint/></outptr>
duke@0 2266 <description>
duke@0 2267 On return, points to the number of active child thread groups
duke@0 2268 </description>
duke@0 2269 </param>
duke@0 2270 <param id="groups_ptr">
duke@0 2271 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
duke@0 2272 <description>
duke@0 2273 On return, points to an array of the active child thread groups.
duke@0 2274 </description>
duke@0 2275 </param>
duke@0 2276 </parameters>
duke@0 2277 <errors>
duke@0 2278 </errors>
duke@0 2279 </function>
duke@0 2280 </category>
duke@0 2281
duke@0 2282 <category id="stack" label="Stack Frame">
duke@0 2283 <intro>
duke@0 2284 These functions provide information about the stack of a thread.
duke@0 2285 Stack frames are referenced by depth.
duke@0 2286 The frame at depth zero is the current frame.
duke@0 2287 <p/>
duke@0 2288 Stack frames are as described in the
duke@0 2289 <vmspeclink id="Overview.doc.html#17257"
duke@0 2290 name="Frames section"/>.
duke@0 2291 That is, they correspond to method
duke@0 2292 invocations (including native methods) but do not correspond to platform native or
duke@0 2293 VM internal frames.
duke@0 2294 <p/>
duke@0 2295 A <jvmti/> implementation may use method invocations to launch a thread and
duke@0 2296 the corresponding frames may be included in the stack as presented by these functions --
duke@0 2297 that is, there may be frames shown
duke@0 2298 deeper than <code>main()</code> and <code>run()</code>.
duke@0 2299 However this presentation must be consistent across all <jvmti/> functionality which
duke@0 2300 uses stack frames or stack depth.
duke@0 2301 </intro>
duke@0 2302
duke@0 2303 <typedef id="jvmtiFrameInfo" label="Stack frame information structure">
duke@0 2304 <description>
duke@0 2305 Information about a stack frame is returned in this structure.
duke@0 2306 </description>
duke@0 2307 <field id="method">
duke@0 2308 <jmethodID/>
duke@0 2309 <description>
duke@0 2310 The method executing in this frame.
duke@0 2311 </description>
duke@0 2312 </field>
duke@0 2313 <field id="location">
duke@0 2314 <jlocation/>
duke@0 2315 <description>
duke@0 2316 The index of the instruction executing in this frame.
duke@0 2317 <code>-1</code> if the frame is executing a native method.
duke@0 2318 </description>
duke@0 2319 </field>
duke@0 2320 </typedef>
duke@0 2321
duke@0 2322 <typedef id="jvmtiStackInfo" label="Stack information structure">
duke@0 2323 <description>
duke@0 2324 Information about a set of stack frames is returned in this structure.
duke@0 2325 </description>
duke@0 2326 <field id="thread">
duke@0 2327 <jthread/>
duke@0 2328 <description>
duke@0 2329 On return, the thread traced.
duke@0 2330 </description>
duke@0 2331 </field>
duke@0 2332 <field id="state">
duke@0 2333 <jint/>
duke@0 2334 <description>
duke@0 2335 On return, the thread state. See <functionlink id="GetThreadState"></functionlink>.
duke@0 2336 </description>
duke@0 2337 </field>
duke@0 2338 <field id="frame_buffer">
duke@0 2339 <outbuf incount="max_frame_count">
duke@0 2340 <struct>jvmtiFrameInfo</struct>
duke@0 2341 </outbuf>
duke@0 2342 <description>
duke@0 2343 On return, this agent allocated buffer is filled
duke@0 2344 with stack frame information.
duke@0 2345 </description>
duke@0 2346 </field>
duke@0 2347 <field id="frame_count">
duke@0 2348 <jint/>
duke@0 2349 <description>
duke@0 2350 On return, the number of records filled into
duke@0 2351 <code>frame_buffer</code>.
duke@0 2352 This will be
duke@0 2353 min(<code>max_frame_count</code>, <i>stackDepth</i>).
duke@0 2354 </description>
duke@0 2355 </field>
duke@0 2356 </typedef>
duke@0 2357
duke@0 2358 <function id="GetStackTrace" num="104">
duke@0 2359 <synopsis>Get Stack Trace</synopsis>
duke@0 2360 <description>
duke@0 2361 Get information about the stack of a thread.
duke@0 2362 If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack,
duke@0 2363 the <paramlink id="max_frame_count"></paramlink> topmost frames are returned,
duke@0 2364 otherwise the entire stack is returned.
duke@0 2365 The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
duke@0 2366 <p/>
duke@0 2367 The following example causes up to five of the topmost frames
duke@0 2368 to be returned and (if there are any frames) the currently
duke@0 2369 executing method name to be printed.
duke@0 2370 <example>
duke@0 2371 jvmtiFrameInfo frames[5];
duke@0 2372 jint count;
duke@0 2373 jvmtiError err;
duke@0 2374
duke@0 2375 err = (*jvmti)-&gt;GetStackTrace(jvmti, aThread, 0, 5,
duke@0 2376 &amp;frames, &amp;count);
duke@0 2377 if (err == JVMTI_ERROR_NONE &amp;&amp; count &gt;= 1) {
duke@0 2378 char *methodName;
duke@0 2379 err = (*jvmti)-&gt;GetMethodName(jvmti, frames[0].method,
duke@0 2380 &amp;methodName, NULL);
duke@0 2381 if (err == JVMTI_ERROR_NONE) {
duke@0 2382 printf("Executing method: %s", methodName);
duke@0 2383 }
duke@0 2384 }
duke@0 2385 </example>
duke@0 2386 <todo>
duke@0 2387 check example code.
duke@0 2388 </todo>
duke@0 2389 <p/>
duke@0 2390 The <paramlink id="thread"></paramlink> need not be suspended
duke@0 2391 to call this function.
duke@0 2392 <p/>
duke@0 2393 The <functionlink id="GetLineNumberTable"></functionlink>
duke@0 2394 function can be used to map locations to line numbers. Note that
duke@0 2395 this mapping can be done lazily.
duke@0 2396 </description>
duke@0 2397 <origin>jvmpi</origin>
duke@0 2398 <capabilities>
duke@0 2399 </capabilities>
duke@0 2400 <parameters>
duke@0 2401 <param id="thread">
duke@0 2402 <jthread null="current"/>
duke@0 2403 <description>
duke@0 2404 Fetch the stack trace of this thread.
duke@0 2405 </description>
duke@0 2406 </param>
duke@0 2407 <param id="start_depth">
duke@0 2408 <jint/>
duke@0 2409 <description>
duke@0 2410 Begin retrieving frames at this depth.
duke@0 2411 If non-negative, count from the current frame,
duke@0 2412 the first frame retrieved is at depth <code>start_depth</code>.
duke@0 2413 For example, if zero, start from the current frame; if one, start from the
duke@0 2414 caller of the current frame; if two, start from the caller of the
duke@0 2415 caller of the current frame; and so on.
duke@0 2416 If negative, count from below the oldest frame,
duke@0 2417 the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>,
duke@0 2418 where <i>stackDepth</i> is the count of frames on the stack.
duke@0 2419 For example, if negative one, only the oldest frame is retrieved;
duke@0 2420 if negative two, start from the frame called by the oldest frame.
duke@0 2421 </description>
duke@0 2422 </param>
duke@0 2423 <param id="max_frame_count">
duke@0 2424 <jint min="0"/>
duke@0 2425 <description>
duke@0 2426 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
duke@0 2427 </description>
duke@0 2428 </param>
duke@0 2429 <param id="frame_buffer">
duke@0 2430 <outbuf incount="max_frame_count" outcount="count_ptr">
duke@0 2431 <struct>jvmtiFrameInfo</struct>
duke@0 2432 </outbuf>
duke@0 2433 <description>
duke@0 2434 On return, this agent allocated buffer is filled
duke@0 2435 with stack frame information.
duke@0 2436 </description>
duke@0 2437 </param>
duke@0 2438 <param id="count_ptr">
duke@0 2439 <outptr><jint/></outptr>
duke@0 2440 <description>
duke@0 2441 On return, points to the number of records filled in.
duke@0 2442 For non-negative <code>start_depth</code>, this will be
duke@0 2443 min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>).
duke@0 2444 For negative <code>start_depth</code>, this will be
duke@0 2445 min(<code>max_frame_count</code>, <code>-start_depth</code>).
duke@0 2446 </description>
duke@0 2447 </param>
duke@0 2448 </parameters>
duke@0 2449 <errors>
duke@0 2450 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
duke@0 2451 <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>.
duke@0 2452 Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>.
duke@0 2453 </error>
duke@0 2454 </errors>
duke@0 2455 </function>
duke@0 2456
duke@0 2457
duke@0 2458 <function id="GetAllStackTraces" num="100">
duke@0 2459 <synopsis>Get All Stack Traces</synopsis>
duke@0 2460 <description>
duke@0 2461 Get information about the stacks of all live threads
duke@0 2462 (including <internallink id="RunAgentThread">agent threads</internallink>).
duke@0 2463 If <paramlink id="max_frame_count"/> is less than the depth of a stack,
duke@0 2464 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
duke@0 2465 otherwise the entire stack is returned.
duke@0 2466 The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
duke@0 2467 <p/>
duke@0 2468 All stacks are collected simultaneously, that is, no changes will occur to the
duke@0 2469 thread state or stacks between the sampling of one thread and the next.
duke@0 2470 The threads need not be suspended.
duke@0 2471
duke@0 2472 <example>
duke@0 2473 jvmtiStackInfo *stack_info;
duke@0 2474 jint thread_count;
duke@0 2475 int ti;
duke@0 2476 jvmtiError err;
duke@0 2477
duke@0 2478 err = (*jvmti)-&gt;GetAllStackTraces(jvmti, MAX_FRAMES, &amp;stack_info, &amp;thread_count);
duke@0 2479 if (err != JVMTI_ERROR_NONE) {
duke@0 2480 ...
duke@0 2481 }
duke@0 2482 for (ti = 0; ti &lt; thread_count; ++ti) {
duke@0 2483 jvmtiStackInfo *infop = &amp;stack_info[ti];
duke@0 2484 jthread thread = infop-&gt;thread;
duke@0 2485 jint state = infop-&gt;state;
duke@0 2486 jvmtiFrameInfo *frames = infop-&gt;frame_buffer;
duke@0 2487 int fi;
duke@0 2488
duke@0 2489 myThreadAndStatePrinter(thread, state);
duke@0 2490 for (fi = 0; fi &lt; infop-&gt;frame_count; fi++) {
duke@0 2491 myFramePrinter(frames[fi].method, frames[fi].location);
duke@0 2492 }
duke@0 2493 }
duke@0 2494 /* this one Deallocate call frees all data allocated by GetAllStackTraces */
duke@0 2495 err = (*jvmti)-&gt;Deallocate(jvmti, stack_info);
duke@0 2496 </example>
duke@0 2497 <todo>
duke@0 2498 check example code.
duke@0 2499 </todo>
duke@0 2500
duke@0 2501 </description>
duke@0 2502 <origin>new</origin>
duke@0 2503 <capabilities>
duke@0 2504 </capabilities>
duke@0 2505 <parameters>
duke@0 2506 <param id="max_frame_count">
duke@0 2507 <jint min="0"/>
duke@0 2508 <description>
duke@0 2509 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
duke@0 2510 </description>
duke@0 2511 </param>
duke@0 2512 <param id="stack_info_ptr">
duke@0 2513 <allocbuf>
duke@0 2514 <struct>jvmtiStackInfo</struct>
duke@0 2515 </allocbuf>
duke@0 2516 <description>
duke@0 2517 On return, this buffer is filled
duke@0 2518 with stack information for each thread.
duke@0 2519 The number of <datalink id="jvmtiStackInfo"/> records is determined
duke@0 2520 by <paramlink id="thread_count_ptr"/>.
duke@0 2521 <p/>
duke@0 2522 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/>
duke@0 2523 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
duke@0 2524 These buffers must not be separately deallocated.
duke@0 2525 </description>
duke@0 2526 </param>
duke@0 2527 <param id="thread_count_ptr">
duke@0 2528 <outptr><jint/></outptr>
duke@0 2529 <description>
duke@0 2530 The number of threads traced.
duke@0 2531 </description>
duke@0 2532 </param>
duke@0 2533 </parameters>
duke@0 2534 <errors>
duke@0 2535 </errors>
duke@0 2536 </function>
duke@0 2537
duke@0 2538 <function id="GetThreadListStackTraces" num="101">
duke@0 2539 <synopsis>Get Thread List Stack Traces</synopsis>
duke@0 2540 <description>
duke@0 2541 Get information about the stacks of the supplied threads.
duke@0 2542 If <paramlink id="max_frame_count"/> is less than the depth of a stack,
duke@0 2543 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
duke@0 2544 otherwise the entire stack is returned.
duke@0 2545 The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
duke@0 2546 <p/>
duke@0 2547 All stacks are collected simultaneously, that is, no changes will occur to the
duke@0 2548 thread state or stacks between the sampling one thread and the next.
duke@0 2549 The threads need not be suspended.
duke@0 2550 <p/>
duke@0 2551 If a thread has not yet started or terminates before the stack information is collected,
duke@0 2552 a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero)
duke@0 2553 will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked.
duke@0 2554 <p/>
duke@0 2555 See the example for the similar function
duke@0 2556 <functionlink id="GetAllStackTraces"/>.
duke@0 2557 </description>
duke@0 2558 <origin>new</origin>
duke@0 2559 <capabilities>
duke@0 2560 </capabilities>
duke@0 2561 <parameters>
duke@0 2562 <param id="thread_count">
duke@0 2563 <jint min="0"/>
duke@0 2564 <description>
duke@0 2565 The number of threads to trace.
duke@0 2566 </description>
duke@0 2567 </param>
duke@0 2568 <param id="thread_list">
duke@0 2569 <inbuf incount="thread_count"><jthread/></inbuf>
duke@0 2570 <description>
duke@0 2571 The list of threads to trace.
duke@0 2572 </description>
duke@0 2573 </param>
duke@0 2574 <param id="max_frame_count">
duke@0 2575 <jint min="0"/>
duke@0 2576 <description>
duke@0 2577 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
duke@0 2578 </description>
duke@0 2579 </param>
duke@0 2580 <param id="stack_info_ptr">
duke@0 2581 <allocbuf outcount="thread_count">
duke@0 2582 <struct>jvmtiStackInfo</struct>
duke@0 2583 </allocbuf>
duke@0 2584 <description>
duke@0 2585 On return, this buffer is filled
duke@0 2586 with stack information for each thread.
duke@0 2587 The number of <datalink id="jvmtiStackInfo"/> records is determined
duke@0 2588 by <paramlink id="thread_count"/>.
duke@0 2589 <p/>
duke@0 2590 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/>
duke@0 2591 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
duke@0 2592 These buffers must not be separately deallocated.
duke@0 2593 </description>
duke@0 2594 </param>
duke@0 2595 </parameters>
duke@0 2596 <errors>
duke@0 2597 <error id="JVMTI_ERROR_INVALID_THREAD">
duke@0 2598 An element in <paramlink id="thread_list"/> is not a thread object.
duke@0 2599 </error>
duke@0 2600 </errors>
duke@0 2601 </function>
duke@0 2602
duke@0 2603 <elide>
duke@0 2604 <function id="AsyncGetStackTrace" num="1000">
duke@0 2605 <synopsis>Get Stack Trace--Asynchronous</synopsis>
duke@0 2606 <description>
duke@0 2607 Get information about the entire stack of a thread (or a sub-section of it).
duke@0 2608 This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink>
duke@0 2609 and is reentrant and safe to call
duke@0 2610 from asynchronous signal handlers.
duke@0 2611 The stack trace is returned only for the calling thread.
duke@0 2612 <p/>
duke@0 2613 The <functionlink id="GetLineNumberTable"></functionlink>
duke@0 2614 function can be used to map locations to line numbers. Note that
duke@0 2615 this mapping can be done lazily.
duke@0 2616 </description>
duke@0 2617 <origin>jvmpi</origin>
duke@0 2618 <capabilities>
duke@0 2619 <required id="can_get_async_stack_trace"></required>
duke@0 2620 <capability id="can_show_JVM_spec_async_frames">
duke@0 2621 If <code>false</code>,
duke@0 2622 <paramlink id="use_java_stack"></paramlink>
duke@0 2623 must be <code>false</code>.
duke@0 2624 </capability>
duke@0 2625 </capabilities>
duke@0 2626 <parameters>
duke@0 2627 <param id="use_java_stack">
duke@0 2628 <jboolean/>
duke@0 2629 <description>
duke@0 2630 Return the stack showing the <vmspeclink/>
duke@0 2631 model of the stack;
duke@0 2632 otherwise, show the internal representation of the stack with
duke@0 2633 inlined and optimized methods missing. If the virtual machine
duke@0 2634 is using the <i>Java Virtual Machine Specification</i> stack model
duke@0 2635 internally, this flag is ignored.
duke@0 2636 </description>
duke@0 2637 </param>
duke@0 2638 <param id="max_count">
duke@0 2639 <jint min="0"/>
duke@0 2640 <description>
duke@0 2641 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
duke@0 2642 Retrieve this many unless the stack depth is less than <code>max_count</code>.
duke@0 2643 </description>
duke@0 2644 </param>
duke@0 2645 <param id="frame_buffer">
duke@0 2646 <outbuf incount="max_count" outcount="count_ptr">
duke@0 2647 <struct>jvmtiFrameInfo</struct>
duke@0 2648 <nullok>this information is not returned</nullok>
duke@0 2649 </outbuf>
duke@0 2650 <description>
duke@0 2651 The agent passes in a buffer
duke@0 2652 large enough to hold <code>max_count</code> records of
duke@0 2653 <datalink id="jvmtiFrameInfo"></datalink>. This buffer must be
duke@0 2654 pre-allocated by the agent.
duke@0 2655 </description>
duke@0 2656 </param>
duke@0 2657 <param id="count_ptr">
duke@0 2658 <outptr><jint/></outptr>
duke@0 2659 <description>
duke@0 2660 On return, points to the number of records filled in..
duke@0 2661 </description>
duke@0 2662 </param>
duke@0 2663 </parameters>
duke@0 2664 <errors>
duke@0 2665 <error id="JVMTI_ERROR_UNATTACHED_THREAD">
duke@0 2666 The thread being used to call this function is not attached
duke@0 2667 to the virtual machine. Calls must be made from attached threads.
duke@0 2668 </error>
duke@0 2669 </errors>
duke@0 2670 </function>
duke@0 2671 </elide>
duke@0 2672
duke@0 2673 <function id="GetFrameCount" num="16">
duke@0 2674 <synopsis>Get Frame Count</synopsis>
duke@0 2675 <description>
duke@0 2676 Get the number of frames currently in the specified thread's call stack.
duke@0 2677 <p/>
duke@0 2678 If this function is called for a thread actively executing bytecodes (for example,
duke@0 2679 not the current thread and not suspended), the information returned is transient.
duke@0 2680 </description>
duke@0 2681 <origin>jvmdi</origin>
duke@0 2682 <capabilities>
duke@0 2683 </capabilities>
duke@0 2684 <parameters>
duke@0 2685 <param id="thread">
duke@0 2686 <jthread null="current"/>
duke@0 2687 <description>
duke@0 2688 The thread to query.
duke@0 2689 </description>
duke@0 2690 </param>
duke@0 2691 <param id="count_ptr">
duke@0 2692 <outptr><jint/></outptr>
duke@0 2693 <description>
duke@0 2694 On return, points to the number of frames in the call stack.
duke@0 2695 </description>
duke@0 2696 </param>
duke@0 2697 </parameters>
duke@0 2698 <errors>
duke@0 2699 </errors>
duke@0 2700 </function>
duke@0 2701
duke@0 2702 <function id="PopFrame" num="80">
duke@0 2703 <synopsis>Pop Frame</synopsis>
duke@0 2704 <description>
duke@0 2705 Pop the current frame of <code>thread</code>'s stack.
duke@0 2706 Popping a frame takes you to the previous frame.
duke@0 2707 When the thread is resumed, the execution
duke@0 2708 state of the thread is reset to the state
duke@0 2709 immediately before the called method was invoked.
duke@0 2710 That is (using the <vmspeclink/> terminology):
duke@0 2711 <ul>
duke@0 2712 <li>the current frame is discarded as the previous frame becomes the current one</li>
duke@0 2713 <li>the operand stack is restored--the argument values are added back
duke@0 2714 and if the invoke was not <code>invokestatic</code>,
duke@0 2715 <code>objectref</code> is added back as well</li>
duke@0 2716 <li>the Java virtual machine PC is restored to the opcode
duke@0 2717 of the invoke instruction</li>
duke@0 2718 </ul>
duke@0 2719 Note however, that any changes to the arguments, which
duke@0 2720 occurred in the called method, remain;
duke@0 2721 when execution continues, the first instruction to
duke@0 2722 execute will be the invoke.
duke@0 2723 <p/>
duke@0 2724 Between calling <code>PopFrame</code> and resuming the
duke@0 2725 thread the state of the stack is undefined.
duke@0 2726 To pop frames beyond the first,
duke@0 2727 these three steps must be repeated:
duke@0 2728 <ul>
duke@0 2729 <li>suspend the thread via an event (step, breakpoint, ...)</li>
duke@0 2730 <li>call <code>PopFrame</code></li>
duke@0 2731 <li>resume the thread</li>
duke@0 2732 </ul>
duke@0 2733 <p/>
duke@0 2734 A lock acquired by calling the called method
duke@0 2735 (if it is a <code>synchronized</code> method)
duke@0 2736 and locks acquired by entering <code>synchronized</code>
duke@0 2737 blocks within the called method are released.
duke@0 2738 Note: this does not apply to native locks or
duke@0 2739 <code>java.util.concurrent.locks</code> locks.
duke@0 2740 <p/>
duke@0 2741 Finally blocks are not executed.
duke@0 2742 <p/>
duke@0 2743 Changes to global state are not addressed and thus remain changed.
duke@0 2744 <p/>
duke@0 2745 The specified thread must be suspended (which implies it cannot be the current thread).
duke@0 2746 <p/>
duke@0 2747 Both the called method and calling method must be non-native Java programming
duke@0 2748 language methods.
duke@0 2749 <p/>
duke@0 2750 No <jvmti/> events are generated by this function.
duke@0 2751 </description>
duke@0 2752 <origin>jvmdi</origin>
duke@0 2753 <capabilities>
duke@0 2754 <required id="can_pop_frame"></required>
duke@0 2755 </capabilities>
duke@0 2756 <parameters>
duke@0 2757 <param id="thread">
duke@0 2758 <jthread/>
duke@0 2759 <description>
duke@0 2760 The thread whose current frame is to be popped.
duke@0 2761 </description>
duke@0 2762 </param>
duke@0 2763 </parameters>
duke@0 2764 <errors>
duke@0 2765 <error id="JVMTI_ERROR_OPAQUE_FRAME">
duke@0 2766 Called or calling method is a native method.
duke@0 2767 The implementation is unable to pop this frame.
duke@0 2768 </error>
duke@0 2769 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
duke@0 2770 Thread was not suspended.
duke@0 2771 </error>
duke@0 2772 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
duke@0 2773 There are less than two stack frames on the call stack.
duke@0 2774 </error>
duke@0 2775 </errors>
duke@0 2776 </function>
duke@0 2777
duke@0 2778 <function id="GetFrameLocation" num="19">
duke@0 2779 <synopsis>Get Frame Location</synopsis>
duke@0 2780 <description>
duke@0 2781 <p/>
duke@0 2782 For a Java programming language frame, return the location of the instruction
duke@0 2783 currently executing.
duke@0 2784 </description>
duke@0 2785 <origin>jvmdiClone</origin>
duke@0 2786 <capabilities>
duke@0 2787 </capabilities>
duke@0 2788 <parameters>
duke@0 2789 <param id="thread">
duke@0 2790 <jthread null="current" frame="frame"/>
duke@0 2791 <description>
duke@0 2792 The thread of the frame to query.
duke@0 2793 </description>
duke@0 2794 </param>
duke@0 2795 <param id="depth">
duke@0 2796 <jframeID thread="thread"/>
duke@0 2797 <description>
duke@0 2798 The depth of the frame to query.
duke@0 2799 </description>
duke@0 2800 </param>
duke@0 2801 <param id="method_ptr">
duke@0 2802 <outptr><jmethodID/></outptr>
duke@0 2803 <description>
duke@0 2804 On return, points to the method for the current location.
duke@0 2805 </description>
duke@0 2806 </param>
duke@0 2807 <param id="location_ptr">
duke@0 2808 <outptr><jlocation/></outptr>
duke@0 2809 <description>
duke@0 2810 On return, points to the index of the currently
duke@0 2811 executing instruction.
duke@0 2812 Is set to <code>-1</code> if the frame is executing
duke@0 2813 a native method.
duke@0 2814 </description>
duke@0 2815 </param>
duke@0 2816 </parameters>
duke@0 2817 <errors>
duke@0 2818 </errors>
duke@0 2819 </function>
duke@0 2820
duke@0 2821 <function id="NotifyFramePop" num="20">
duke@0 2822 <synopsis>Notify Frame Pop</synopsis>
duke@0 2823 <description>
duke@0 2824 When the frame that is currently at <paramlink id="depth"></paramlink>
duke@0 2825 is popped from the stack, generate a
duke@0 2826 <eventlink id="FramePop"></eventlink> event. See the
duke@0 2827 <eventlink id="FramePop"></eventlink> event for details.
duke@0 2828 Only frames corresponding to non-native Java programming language
duke@0 2829 methods can receive notification.
duke@0 2830 <p/>
duke@0 2831 The specified thread must either be the current thread
duke@0 2832 or the thread must be suspended.
duke@0 2833 </description>
duke@0 2834 <origin>jvmdi</origin>
duke@0 2835 <capabilities>
duke@0 2836 <required id="can_generate_frame_pop_events"></required>
duke@0 2837 </capabilities>
duke@0 2838 <parameters>
duke@0 2839 <param id="thread">
duke@0 2840 <jthread null="current" frame="depth"/>
duke@0 2841 <description>
duke@0 2842 The thread of the frame for which the frame pop event will be generated.
duke@0 2843 </description>
duke@0 2844 </param>
duke@0 2845 <param id="depth">
duke@0 2846 <jframeID thread="thread"/>
duke@0 2847 <description>
duke@0 2848 The depth of the frame for which the frame pop event will be generated.
duke@0 2849 </description>
duke@0 2850 </param>
duke@0 2851 </parameters>
duke@0 2852 <errors>
duke@0 2853 <error id="JVMTI_ERROR_OPAQUE_FRAME">
duke@0 2854 The frame at <code>depth</code> is executing a
duke@0 2855 native method.
duke@0 2856 </error>
duke@0 2857 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
duke@0 2858 Thread was not suspended and was not the current thread.
duke@0 2859 </error>
duke@0 2860 </errors>
duke@0 2861 </function>
duke@0 2862
duke@0 2863 </category>
duke@0 2864
duke@0 2865 <category id="ForceEarlyReturn" label="Force Early Return">
duke@0 2866 <intro>
duke@0 2867 These functions allow an agent to force a method
duke@0 2868 to return at any point during its execution.
duke@0 2869 The method which will return early is referred to as the <i>called method</i>.
duke@0 2870 The called method is the current method
duke@0 2871 (as defined by the
duke@0 2872 <vmspeclink id="Overview.doc.html#17257"
duke@0 2873 name="Frames section"/>)
duke@0 2874 for the specified thread at
duke@0 2875 the time the function is called.
duke@0 2876 <p/>
duke@0 2877 The specified thread must be suspended or must be the current thread.
duke@0 2878 The return occurs when execution of Java programming
duke@0 2879 language code is resumed on this thread.
duke@0 2880 Between calling one of these functions and resumption
duke@0 2881 of thread execution, the state of the stack is undefined.
duke@0 2882 <p/>
duke@0 2883 No further instructions are executed in the called method.
duke@0 2884 Specifically, finally blocks are not executed.
duke@0 2885 Note: this can cause inconsistent states in the application.
duke@0 2886 <p/>
duke@0 2887 A lock acquired by calling the called method
duke@0 2888 (if it is a <code>synchronized</code> method)
duke@0 2889 and locks acquired by entering <code>synchronized</code>
duke@0 2890 blocks within the called method are released.
duke@0 2891 Note: this does not apply to native locks or
duke@0 2892 <code>java.util.concurrent.locks</code> locks.
duke@0 2893 <p/>
duke@0 2894 Events, such as <eventlink id="MethodExit"></eventlink>,
duke@0 2895 are generated as they would be in a normal return.
duke@0 2896 <p/>
duke@0 2897 The called method must be a non-native Java programming
duke@0 2898 language method.
duke@0 2899 Forcing return on a thread with only one frame on the
duke@0 2900 stack causes the thread to exit when resumed.
duke@0 2901 </intro>
duke@0 2902
duke@0 2903 <function id="ForceEarlyReturnObject" num="81" since="1.1">
duke@0 2904 <synopsis>Force Early Return - Object</synopsis>
duke@0 2905 <description>
duke@0 2906 This function can be used to return from a method whose
duke@0 2907 result type is <code>Object</code>
duke@0 2908 or a subclass of <code>Object</code>.
duke@0 2909 </description>
duke@0 2910 <origin>new</origin>
duke@0 2911 <capabilities>
duke@0 2912 <required id="can_force_early_return"></required>
duke@0 2913 </capabilities>
duke@0 2914 <parameters>
duke@0 2915 <param id="thread">
duke@0 2916 <jthread null="current"/>
duke@0 2917 <description>
duke@0 2918 The thread whose current frame is to return early.
duke@0 2919 </description>
duke@0 2920 </param>
duke@0 2921 <param id="value">
duke@0 2922 <jobject/>
duke@0 2923 <description>
duke@0 2924 The return value for the called frame.
duke@0 2925 An object or <code>NULL</code>.
duke@0 2926 </description>
duke@0 2927 </param>
duke@0 2928 </parameters>
duke@0 2929 <errors>
duke@0 2930 <error id="JVMTI_ERROR_OPAQUE_FRAME">
duke@0 2931 Attempted to return early from a frame
duke@0 2932 corresponding to a native method.
duke@0 2933 Or the implementation is unable to provide
duke@0 2934 this functionality on this frame.
duke@0 2935 </error>
duke@0 2936 <error id="JVMTI_ERROR_TYPE_MISMATCH">
duke@0 2937 The result type of the called method is not
duke@0 2938 <code>Object</code> or a subclass of <code>Object</code>.
duke@0 2939 </error>
duke@0 2940 <error id="JVMTI_ERROR_TYPE_MISMATCH">
duke@0 2941 The supplied <paramlink id="value"/> is not compatible with the
duke@0 2942 result type of the called method.
duke@0 2943 </error>
duke@0 2944 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
duke@0 2945 Thread was not the current thread and was not suspended.
duke@0 2946 </error>
duke@0 2947 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
duke@0 2948 There are no more frames on the call stack.
duke@0 2949 </error>
duke@0 2950 </errors>
duke@0 2951 </function>
duke@0 2952
duke@0 2953 <function id="ForceEarlyReturnInt" num="82" since="1.1">
duke@0 2954 <synopsis>Force Early Return - Int</synopsis>
duke@0 2955 <description>
duke@0 2956 This function can be used to return from a method whose
duke@0 2957 result type is <code>int</code>, <code>short</code>,
duke@0 2958 <code>char</code>, <code>byte</code>, or
duke@0 2959 <code>boolean</code>.
duke@0 2960 </description>
duke@0 2961 <origin>new</origin>
duke@0 2962 <capabilities>
duke@0 2963 <required id="can_force_early_return"></required>
duke@0 2964 </capabilities>
duke@0 2965 <parameters>
duke@0 2966 <param id="thread">
duke@0 2967 <jthread null="current"/>
duke@0 2968 <description>
duke@0 2969 The thread whose current frame is to return early.
duke@0 2970 </description>
duke@0 2971 </param>
duke@0 2972 <param id="value">
duke@0 2973 <jint/>
duke@0 2974 <description>
duke@0 2975 The return value for the called frame.
duke@0 2976 </description>
duke@0 2977 </param>
duke@0 2978 </parameters>
duke@0 2979 <errors>
duke@0 2980 <error id="JVMTI_ERROR_OPAQUE_FRAME">
duke@0 2981 Attempted to return early from a frame
duke@0 2982 corresponding to a native method.
duke@0 2983 Or the implementation is unable to provide
duke@0 2984 this functionality on this frame.
duke@0 2985 </error>
duke@0 2986 <error id="JVMTI_ERROR_TYPE_MISMATCH">
duke@0 2987 The result type of the called method is not
duke@0 2988 <code>int</code>, <code>short</code>,
duke@0 2989 <code>char</code>, <code>byte</code>, or
duke@0 2990 <code>boolean</code>.
duke@0 2991 </error>
duke@0 2992 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
duke@0 2993 Thread was not the current thread and was not suspended.
duke@0 2994 </error>
duke@0 2995 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
duke@0 2996 There are no frames on the call stack.
duke@0 2997 </error>
duke@0 2998 </errors>
duke@0 2999 </function>
duke@0 3000
duke@0 3001 <function id="ForceEarlyReturnLong" num="83" since="1.1">
duke@0 3002 <synopsis>Force Early Return - Long</synopsis>
duke@0 3003 <description>
duke@0 3004 This function can be used to return from a method whose
duke@0 3005 result type is <code>long</code>.
duke@0 3006 </description>
duke@0 3007 <origin>new</origin>
duke@0 3008 <capabilities>
duke@0 3009 <required id="can_force_early_return"></required>
duke@0 3010 </capabilities>
duke@0 3011 <parameters>
duke@0 3012 <param id="thread">
duke@0 3013 <jthread null="current"/>
duke@0 3014 <description>
duke@0 3015 The thread whose current frame is to return early.
duke@0 3016 </description>
duke@0 3017 </param>
duke@0 3018 <param id="value">
duke@0 3019 <jlong/>
duke@0 3020 <description>
duke@0 3021 The return value for the called frame.
duke@0 3022 </description>
duke@0 3023 </param>
duke@0 3024 </parameters>
duke@0 3025 <errors>
duke@0 3026 <error id="JVMTI_ERROR_OPAQUE_FRAME">
duke@0 3027 Attempted to return early from a frame
duke@0 3028 corresponding to a native method.
duke@0 3029 Or the implementation is unable to provide
duke@0 3030 this functionality on this frame.
duke@0 3031 </error>
duke@0 3032 <error id="JVMTI_ERROR_TYPE_MISMATCH">
duke@0 3033 The result type of the called method is not <code>long</code>.
duke@0 3034 </error>
duke@0 3035 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
duke@0 3036 Thread was not the current thread and was not suspended.
duke@0 3037 </error>
duke@0 3038 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
duke@0 3039 There are no frames on the call stack.
duke@0 3040 </error>
duke@0 3041 </errors>
duke@0 3042 </function>
duke@0 3043
duke@0 3044 <function id="ForceEarlyReturnFloat" num="84" since="1.1">
duke@0 3045 <synopsis>Force Early Return - Float</synopsis>
duke@0 3046 <description>
duke@0 3047 This function can be used to return from a method whose
duke@0 3048 result type is <code>float</code>.
duke@0 3049 </description>
duke@0 3050 <origin>new</origin>
duke@0 3051 <capabilities>
duke@0 3052 <required id="can_force_early_return"></required>
duke@0 3053 </capabilities>
duke@0 3054 <parameters>
duke@0 3055 <param id="thread">
duke@0 3056 <jthread null="current"/>
duke@0 3057 <description>
duke@0 3058 The thread whose current frame is to return early.
duke@0 3059 </description>
duke@0 3060 </param>
duke@0 3061 <param id="value">
duke@0 3062 <jfloat/>
duke@0 3063 <description>
duke@0 3064 The return value for the called frame.
duke@0 3065 </description>
duke@0 3066 </param>
duke@0 3067 </parameters>
duke@0 3068 <errors>
duke@0 3069 <error id="JVMTI_ERROR_OPAQUE_FRAME">
duke@0 3070 Attempted to return early from a frame
duke@0 3071 corresponding to a native method.
duke@0 3072 Or the implementation is unable to provide
duke@0 3073 this functionality on this frame.
duke@0 3074 </error>
duke@0 3075 <error id="JVMTI_ERROR_TYPE_MISMATCH">
duke@0 3076 The result type of the called method is not <code>float</code>.
duke@0 3077 </error>
duke@0 3078 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
duke@0 3079 Thread was not the current thread and was not suspended.
duke@0 3080 </error>
duke@0 3081 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
duke@0 3082 There are no frames on the call stack.
duke@0 3083 </error>
duke@0 3084 </errors>
duke@0 3085 </function>
duke@0 3086
duke@0 3087 <function id="ForceEarlyReturnDouble" num="85" since="1.1">
duke@0 3088 <synopsis>Force Early Return - Double</synopsis>
duke@0 3089 <description>
duke@0 3090 This function can be used to return from a method whose
duke@0 3091 result type is <code>double</code>.
duke@0 3092 </description>
duke@0 3093 <origin>new</origin>
duke@0 3094 <capabilities>
duke@0 3095 <required id="can_force_early_return"></required>
duke@0 3096 </capabilities>
duke@0 3097 <parameters>
duke@0 3098 <param id="thread">
duke@0 3099 <jthread null="current"/>
duke@0 3100 <description>
duke@0 3101 The thread whose current frame is to return early.
duke@0 3102 </description>
duke@0 3103 </param>
duke@0 3104 <param id="value">
duke@0 3105 <jdouble/>
duke@0 3106 <description>
duke@0 3107 The return value for the called frame.
duke@0 3108 </description>
duke@0 3109 </param>
duke@0 3110 </parameters>
duke@0 3111 <errors>
duke@0 3112 <error id="JVMTI_ERROR_OPAQUE_FRAME">
duke@0 3113 Attempted to return early from a frame corresponding to a native method.
duke@0 3114 Or the implementation is unable to provide this functionality on this frame.
duke@0 3115 </error>
duke@0 3116 <error id="JVMTI_ERROR_TYPE_MISMATCH">
duke@0 3117 The result type of the called method is not <code>double</code>.
duke@0 3118 </error>
duke@0 3119 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
duke@0 3120 Thread was not the current thread and was not suspended.
duke@0 3121 </error>
duke@0 3122 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
duke@0 3123 There are no frames on the call stack.
duke@0 3124 </error>
duke@0 3125 </errors>
duke@0 3126 </function>
duke@0 3127
duke@0 3128 <function id="ForceEarlyReturnVoid" num="86" since="1.1">
duke@0 3129 <synopsis>Force Early Return - Void</synopsis>
duke@0 3130 <description>
duke@0 3131 This function can be used to return from a method with no result type.
duke@0 3132 That is, the called method must be declared <code>void</code>.
duke@0 3133 </description>
duke@0 3134 <origin>new</origin>
duke@0 3135 <capabilities>
duke@0 3136 <required id="can_force_early_return"></required>
duke@0 3137 </capabilities>
duke@0 3138 <parameters>
duke@0 3139 <param id="thread">
duke@0 3140 <jthread null="current"/>
duke@0 3141 <description>
duke@0 3142 The thread whose current frame is to return early.
duke@0 3143 </description>
duke@0 3144 </param>
duke@0 3145 </parameters>
duke@0 3146 <errors>
duke@0 3147 <error id="JVMTI_ERROR_OPAQUE_FRAME">
duke@0 3148 Attempted to return early from a frame
duke@0 3149 corresponding to a native method.
duke@0 3150 Or the implementation is unable to provide
duke@0 3151 this functionality on this frame.
duke@0 3152 </error>
duke@0 3153 <error id="JVMTI_ERROR_TYPE_MISMATCH">
duke@0 3154 The called method has a result type.
duke@0 3155 </error>
duke@0 3156 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
duke@0 3157 Thread was not the current thread and was not suspended.
duke@0 3158 </error>
duke@0 3159 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
duke@0 3160 There are no frames on the call stack.
duke@0 3161 </error>
duke@0 3162 </errors>
duke@0 3163 </function>
duke@0 3164
duke@0 3165 </category>
duke@0 3166
duke@0 3167 <category id="Heap" label="Heap">
duke@0 3168 <intro>
duke@0 3169 These functions are used to analyze the heap.
duke@0 3170 Functionality includes the ability to view the objects in the
duke@0 3171 heap and to tag these objects.
duke@0 3172 </intro>
duke@0 3173
duke@0 3174 <intro id="objectTags" label="Object Tags">
duke@0 3175 A <i>tag</i> is a value associated with an object.
duke@0 3176 Tags are explicitly set by the agent using the
duke@0 3177 <functionlink id="SetTag"></functionlink> function or by
duke@0 3178 callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>.
duke@0 3179 <p/>
duke@0 3180 Tags are local to the environment; that is, the tags of one
duke@0 3181 environment are not visible in another.
duke@0 3182 <p/>
duke@0 3183 Tags are <code>jlong</code> values which can be used
duke@0 3184 simply to mark an object or to store a pointer to more detailed
duke@0 3185 information. Objects which have not been tagged have a
duke@0 3186 tag of zero.
duke@0 3187 Setting a tag to zero makes the object untagged.
duke@0 3188 </intro>
duke@0 3189
duke@0 3190 <intro id="heapCallbacks" label="Heap Callback Functions">
duke@0 3191 Heap functions which iterate through the heap and recursively
duke@0 3192 follow object references use agent supplied callback functions
duke@0 3193 to deliver the information.
duke@0 3194 <p/>
duke@0 3195 These heap callback functions must adhere to the following restrictions --
duke@0 3196 These callbacks must not use JNI functions.
duke@0 3197 These callbacks must not use <jvmti/> functions except
duke@0 3198 <i>callback safe</i> functions which
duke@0 3199 specifically allow such use (see the raw monitor, memory management,
duke@0 3200 and environment local storage functions).
duke@0 3201 <p/>
duke@0 3202 An implementation may invoke a callback on an internal thread or
duke@0 3203 the thread which called the iteration function.
duke@0 3204 Heap callbacks are single threaded -- no more than one callback will
duke@0 3205 be invoked at a time.
duke@0 3206 <p/>
duke@0 3207 The Heap Filter Flags can be used to prevent reporting
duke@0 3208 based on the tag status of an object or its class.
duke@0 3209 If no flags are set (the <code>jint</code> is zero), objects
duke@0 3210 will not be filtered out.
duke@0 3211
duke@0 3212 <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits">
duke@0 3213 <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4">
duke@0 3214 Filter out tagged objects. Objects which are tagged are not included.
duke@0 3215 </constant>
duke@0 3216 <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8">
duke@0 3217 Filter out untagged objects. Objects which are not tagged are not included.
duke@0 3218 </constant>
duke@0 3219 <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10">
duke@0 3220 Filter out objects with tagged classes. Objects whose class is tagged are not included.
duke@0 3221 </constant>
duke@0 3222 <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20">
duke@0 3223 Filter out objects with untagged classes. Objects whose class is not tagged are not included.
duke@0 3224 </constant>
duke@0 3225 </constants>
duke@0 3226
duke@0 3227 <p/>
duke@0 3228 The Heap Visit Control Flags are returned by the heap callbacks
duke@0 3229 and can be used to abort the iteration. For the
duke@0 3230 <functionlink id="jvmtiHeapReferenceCallback">Heap
duke@0 3231 Reference Callback</functionlink>, it can also be used
duke@0 3232 to prune the graph of traversed references
duke@0 3233 (<code>JVMTI_VISIT_OBJECTS</code> is not set).
duke@0 3234
duke@0 3235 <constants id="jvmtiHeapVisitControl"
duke@0 3236 label="Heap Visit Control Flags"
duke@0 3237 kind="bits"
duke@0 3238 since="1.1">
duke@0 3239 <constant id="JVMTI_VISIT_OBJECTS" num="0x100">
duke@0 3240 If we are visiting an object and if this callback
duke@0 3241 was initiated by <functionlink id="FollowReferences"/>,
duke@0 3242 traverse the references of this object.
duke@0 3243 Otherwise ignored.
duke@0 3244 </constant>
duke@0 3245 <constant id="JVMTI_VISIT_ABORT" num="0x8000">
duke@0 3246 Abort the iteration. Ignore all other bits.
duke@0 3247 </constant>
duke@0 3248 </constants>
duke@0 3249
duke@0 3250 <p/>
duke@0 3251 The Heap Reference Enumeration is provided by the
duke@0 3252 <functionlink id="jvmtiHeapReferenceCallback">Heap
duke@0 3253 Reference Callback</functionlink> and
duke@0 3254 <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field
duke@0 3255 Callback</functionlink> to
duke@0 3256 describe the kind of reference
duke@0 3257 being reported.
duke@0 3258
duke@0 3259 <constants id="jvmtiHeapReferenceKind"
duke@0 3260 label="Heap Reference Enumeration"
duke@0 3261 kind="enum"
duke@0 3262 since="1.1">
duke@0 3263 <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1">
duke@0 3264 Reference from an object to its class.
duke@0 3265 </constant>
duke@0 3266 <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2">
duke@0 3267 Reference from an object to the value of one of its instance fields.
duke@0 3268 </constant>
duke@0 3269 <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3">
duke@0 3270 Reference from an array to one of its elements.
duke@0 3271 </constant>
duke@0 3272 <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4">
duke@0 3273 Reference from a class to its class loader.
duke@0 3274 </constant>
duke@0 3275 <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5">
duke@0 3276 Reference from a class to its signers array.
duke@0 3277 </constant>
duke@0 3278 <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6">
duke@0 3279 Reference from a class to its protection domain.
duke@0 3280 </constant>
duke@0 3281 <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7">
duke@0 3282 Reference from a class to one of its interfaces.
duke@0 3283 Note: interfaces are defined via a constant pool reference,
duke@0 3284 so the referenced interfaces may also be reported with a
duke@0 3285 <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
duke@0 3286 </constant>
duke@0 3287 <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8">
duke@0 3288 Reference from a class to the value of one of its static fields.
duke@0 3289 </constant>
duke@0 3290 <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9">
duke@0 3291 Reference from a class to a resolved entry in the constant pool.
duke@0 3292 </constant>
duke@0 3293 <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10">
duke@0 3294 Reference from a class to its superclass.
duke@0 3295 A callback is bot sent if the superclass is <code>java.lang.Object</code>.
duke@0 3296 Note: loaded classes define superclasses via a constant pool
duke@0 3297 reference, so the referenced superclass may also be reported with
duke@0 3298 a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
duke@0 3299 </constant>
duke@0 3300 <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21">
duke@0 3301 Heap root reference: JNI global reference.
duke@0 3302 </constant>
duke@0 3303 <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22">
duke@0 3304 Heap root reference: System class.
duke@0 3305 </constant>
duke@0 3306 <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23">
duke@0 3307 Heap root reference: monitor.
duke@0 3308 </constant>
duke@0 3309 <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24">
duke@0 3310 Heap root reference: local variable on the stack.
duke@0 3311 </constant>
duke@0 3312 <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25">
duke@0 3313 Heap root reference: JNI local reference.
duke@0 3314 </constant>
duke@0 3315 <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26">
duke@0 3316 Heap root reference: Thread.
duke@0 3317 </constant>
duke@0 3318 <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27">
duke@0 3319 Heap root reference: other heap root reference.
duke@0 3320 </constant>
duke@0 3321 </constants>
duke@0 3322
duke@0 3323 <p/>
duke@0 3324 Definitions for the single character type descriptors of
duke@0 3325 primitive types.
duke@0 3326
duke@0 3327 <constants id="jvmtiPrimitiveType"
duke@0 3328 label="Primitive Type Enumeration"
duke@0 3329 kind="enum"
duke@0 3330 since="1.1">
duke@0 3331 <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90">
duke@0 3332 'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code>
duke@0 3333 </constant>
duke@0 3334 <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66">
duke@0 3335 'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code>
duke@0 3336 </constant>
duke@0 3337 <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67">
duke@0 3338 'C' - Java programming language <code>char</code> - JNI <code>jchar</code>
duke@0 3339 </constant>
duke@0 3340 <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83">
duke@0 3341 'S' - Java programming language <code>short</code> - JNI <code>jshort</code>
duke@0 3342 </constant>
duke@0 3343 <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73">
duke@0 3344 'I' - Java programming language <code>int</code> - JNI <code>jint</code>
duke@0 3345 </constant>
duke@0 3346 <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74">
duke@0 3347 'J' - Java programming language <code>long</code> - JNI <code>jlong</code>
duke@0 3348 </constant>
duke@0 3349 <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70">
duke@0 3350 'F' - Java programming language <code>float</code> - JNI <code>jfloat</code>
duke@0 3351 </constant>
duke@0 3352 <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68">
duke@0 3353 'D' - Java programming language <code>double</code> - JNI <code>jdouble</code>
duke@0 3354 </constant>
duke@0 3355 </constants>
duke@0 3356 </intro>
duke@0 3357
duke@0 3358 <typedef id="jvmtiHeapReferenceInfoField"
duke@0 3359 label="Reference information structure for Field references"
duke@0 3360 since="1.1">
duke@0 3361 <description>
duke@0 3362 Reference information returned for
duke@0 3363 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and
duke@0 3364 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
duke@0 3365 </description>
duke@0 3366 <field id="index">
duke@0 3367 <jint/>
duke@0 3368 <description>
duke@0 3369 For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the
duke@0 3370 referrer object is not a class or an inteface.
duke@0 3371 In this case, <code>index</code> is the index of the field
duke@0 3372 in the class of the referrer object.
duke@0 3373 This class is referred to below as <i>C</i>.
duke@0 3374 <p/>
duke@0 3375 For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
duke@0 3376 the referrer object is a class (referred to below as <i>C</i>)
duke@0 3377 or an interface (referred to below as <i>I</i>).
duke@0 3378 In this case, <code>index</code> is the index of the field in
duke@0 3379 that class or interface.
duke@0 3380 <p/>
duke@0 3381 If the referrer object is not an interface, then the field
duke@0 3382 indices are determined as follows:
duke@0 3383 <ul>
duke@0 3384 <li>make a list of all the fields in <i>C</i> and its
duke@0 3385 superclasses, starting with all the fields in
duke@0 3386 <code>java.lang.Object</code> and ending with all the
duke@0 3387 fields in <i>C</i>.</li>
duke@0 3388 <li>Within this list, put
duke@0 3389 the fields for a given class in the order returned by
duke@0 3390 <functionlink id="GetClassFields"/>.</li>
duke@0 3391 <li>Assign the fields in this list indices
duke@0 3392 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i>
duke@0 3393 is the count of the fields in all the interfaces
duke@0 3394 implemented by <i>C</i>.
duke@0 3395 Note that <i>C</i> implements all interfaces
duke@0 3396 directly implemented by its superclasses; as well
duke@0 3397 as all superinterfaces of these interfaces.</li>
duke@0 3398 </ul>
duke@0 3399 If the referrer object is an interface, then the field
duke@0 3400 indices are determined as follows:
duke@0 3401 <ul>
duke@0 3402 <li>make a list of the fields directly declared in
duke@0 3403 <i>I</i>.</li>
duke@0 3404 <li>Within this list, put
duke@0 3405 the fields in the order returned by
duke@0 3406 <functionlink id="GetClassFields"/>.</li>
duke@0 3407 <li>Assign the fields in this list indices
duke@0 3408 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i>
duke@0 3409 is the count of the fields in all the superinterfaces
duke@0 3410 of <i>I</i>.</li>
duke@0 3411 </ul>
duke@0 3412 All fields are included in this computation, regardless of
duke@0 3413 field modifier (static, public, private, etc).
duke@0 3414 <p/>
duke@0 3415 For example, given the following classes and interfaces:
duke@0 3416 <example>
duke@0 3417 interface I0 {
duke@0 3418 int p = 0;
duke@0 3419 }
duke@0 3420
duke@0 3421 interface I1 extends I0 {
duke@0 3422 int x = 1;
duke@0 3423 }
duke@0 3424
duke@0 3425 interface I2 extends I0 {
duke@0 3426 int y = 2;
duke@0 3427 }
duke@0 3428
duke@0 3429 class C1 implements I1 {
duke@0 3430 public static int a = 3;
duke@0 3431 private int b = 4;
duke@0 3432 }
duke@0 3433
duke@0 3434 class C2 extends C1 implements I2 {
duke@0 3435 static int q = 5;
duke@0 3436 final int r = 6;
duke@0 3437 }
duke@0 3438 </example>
duke@0 3439 Assume that <functionlink id="GetClassFields"/> called on
duke@0 3440 <code>C1</code> returns the fields of <code>C1</code> in the
duke@0 3441 order: a, b; and that the fields of <code>C2</code> are
duke@0 3442 returned in the order: q, r.
duke@0 3443 An instance of class <code>C1</code> will have the
duke@0 3444 following field indices:
duke@0 3445 <dl><dd><table>
duke@0 3446 <tr>
duke@0 3447 <td>
duke@0 3448 a
duke@0 3449 </td>
duke@0 3450 <td>
duke@0 3451 2
duke@0 3452 </td>
duke@0 3453 <td align="left">
duke@0 3454 The count of the fields in the interfaces
duke@0 3455 implemented by <code>C1</code> is two (<i>n</i>=2):
duke@0 3456 <code>p</code> of <code>I0</code>
duke@0 3457 and <code>x</code> of <code>I1</code>.
duke@0 3458 </td>
duke@0 3459 </tr>
duke@0 3460 <tr>
duke@0 3461 <td>
duke@0 3462 b
duke@0 3463 </td>
duke@0 3464 <td>
duke@0 3465 3
duke@0 3466 </td>
duke@0 3467 <td align="left">
duke@0 3468 the subsequent index.
duke@0 3469 </td>
duke@0 3470 </tr>
duke@0 3471 </table></dd></dl>
duke@0 3472 The class <code>C1</code> will have the same field indices.
duke@0 3473 <p/>
duke@0 3474 An instance of class <code>C2</code> will have the
duke@0 3475 following field indices:
duke@0 3476 <dl><dd><table>
duke@0 3477 <tr>
duke@0 3478 <td>
duke@0 3479 a
duke@0 3480 </td>
duke@0 3481 <td>
duke@0 3482 3
duke@0 3483 </td>
duke@0 3484 <td align="left">
duke@0 3485 The count of the fields in the interfaces
duke@0 3486 implemented by <code>C2</code> is three (<i>n</i>=3):
duke@0 3487 <code>p</code> of <code>I0</code>,
duke@0 3488 <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code>
duke@0 3489 (an interface of <code>C2</code>). Note that the field <code>p</code>
duke@0 3490 of <code>I0</code> is only included once.
duke@0 3491 </td>
duke@0 3492 </tr>
duke@0 3493 <tr>
duke@0 3494 <td>
duke@0 3495 b
duke@0 3496 </td>
duke@0 3497 <td>
duke@0 3498 4
duke@0 3499 </td>
duke@0 3500 <td align="left">
duke@0 3501 the subsequent index to "a".
duke@0 3502 </td>
duke@0 3503 </tr>
duke@0 3504 <tr>
duke@0 3505 <td>
duke@0 3506 q
duke@0 3507 </td>
duke@0 3508 <td>
duke@0 3509 5
duke@0 3510 </td>
duke@0 3511 <td align="left">
duke@0 3512 the subsequent index to "b".
duke@0 3513 </td>
duke@0 3514 </tr>
duke@0 3515 <tr>
duke@0 3516 <td>
duke@0 3517 r
duke@0 3518 </td>
duke@0 3519 <td>
duke@0 3520 6
duke@0 3521 </td>
duke@0 3522 <td align="left">
duke@0 3523 the subsequent index to "q".
duke@0 3524 </td>
duke@0 3525 </tr>
duke@0 3526 </table></dd></dl>
duke@0 3527 The class <code>C2</code> will have the same field indices.
duke@0 3528 Note that a field may have a different index depending on the
duke@0 3529 object that is viewing it -- for example field "a" above.
duke@0 3530 Note also: not all field indices may be visible from the
duke@0 3531 callbacks, but all indices are shown for illustrative purposes.
duke@0 3532 <p/>
duke@0 3533 The interface <code>I1</code> will have the
duke@0 3534 following field indices:
duke@0 3535 <dl><dd><table>
duke@0 3536 <tr>
duke@0 3537 <td>
duke@0 3538 x
duke@0 3539 </td>
duke@0 3540 <td>
duke@0 3541 1
duke@0 3542 </td>
duke@0 3543 <td align="left">
duke@0 3544 The count of the fields in the superinterfaces
duke@0 3545 of <code>I1</code> is one (<i>n</i>=1):
duke@0 3546 <code>p</code> of <code>I0</code>.
duke@0 3547 </td>
duke@0 3548 </tr>
duke@0 3549 </table></dd></dl>
duke@0 3550 </description>
duke@0 3551 </field>
duke@0 3552 </typedef>
duke@0 3553
duke@0 3554 <typedef id="jvmtiHeapReferenceInfoArray"
duke@0 3555 label="Reference information structure for Array references"
duke@0 3556 since="1.1">
duke@0 3557 <description>
duke@0 3558 Reference information returned for
duke@0 3559 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
duke@0 3560 </description>
duke@0 3561 <field id="index">
duke@0 3562 <jint/>
duke@0 3563 <description>
duke@0 3564 The array index.
duke@0 3565 </description>
duke@0 3566 </field>
duke@0 3567 </typedef>
duke@0 3568
duke@0 3569 <typedef id="jvmtiHeapReferenceInfoConstantPool"
duke@0 3570 label="Reference information structure for Constant Pool references"
duke@0 3571 since="1.1">
duke@0 3572 <description>
duke@0 3573 Reference information returned for
duke@0 3574 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
duke@0 3575 </description>
duke@0 3576 <field id="index">
duke@0 3577 <jint/>
duke@0 3578 <description>
duke@0 3579 The index into the constant pool of the class. See the
duke@0 3580 <vmspeclink id="ClassFile.doc.html#20080"
duke@0 3581 name="Constant Pool section"/>
duke@0 3582 description.
duke@0 3583 </description>
duke@0 3584 </field>
duke@0 3585 </typedef>
duke@0 3586
duke@0 3587 <typedef id="jvmtiHeapReferenceInfoStackLocal"
duke@0 3588 label="Reference information structure for Local Variable references"
duke@0 3589 since="1.1">
duke@0 3590 <description>
duke@0 3591 Reference information returned for
duke@0 3592 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
duke@0 3593 </description>
duke@0 3594 <field id="thread_tag">
duke@0 3595 <jlong/>
duke@0 3596 <description>
duke@0 3597 The tag of the thread corresponding to this stack, zero if not tagged.
duke@0 3598 </description>
duke@0 3599 </field>
duke@0 3600 <field id="thread_id">
duke@0 3601 <jlong/>
duke@0 3602 <description>
duke@0 3603 The unique thread ID of the thread corresponding to this stack.
duke@0 3604 </description>
duke@0 3605 </field>
duke@0 3606 <field id="depth">
duke@0 3607 <jint/>
duke@0 3608 <description>
duke@0 3609 The depth of the frame.
duke@0 3610 </description>
duke@0 3611 </field>
duke@0 3612 <field id="method">
duke@0 3613 <jmethodID/>
duke@0 3614 <description>
duke@0 3615 The method executing in this frame.
duke@0 3616 </description>
duke@0 3617 </field>
duke@0 3618 <field id="location">
duke@0 3619 <jlocation/>
duke@0 3620 <description>
duke@0 3621 The currently executing location in this frame.
duke@0 3622 </description>
duke@0 3623 </field>
duke@0 3624 <field id="slot">
duke@0 3625 <jint/>
duke@0 3626 <description>
duke@0 3627 The slot number of the local variable.
duke@0 3628 </description>
duke@0 3629 </field>
duke@0 3630 </typedef>
duke@0 3631
duke@0 3632 <typedef id="jvmtiHeapReferenceInfoJniLocal"
duke@0 3633 label="Reference information structure for JNI local references"
duke@0 3634 since="1.1">
duke@0 3635 <description>
duke@0 3636 Reference information returned for
duke@0 3637 <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
duke@0 3638 </description>
duke@0 3639 <field id="thread_tag">
duke@0 3640 <jlong/>
duke@0 3641 <description>
duke@0 3642 The tag of the thread corresponding to this stack, zero if not tagged.
duke@0 3643 </description>
duke@0 3644 </field>
duke@0 3645 <field id="thread_id">
duke@0 3646 <jlong/>
duke@0 3647 <description>
duke@0 3648 The unique thread ID of the thread corresponding to this stack.
duke@0 3649 </description>
duke@0 3650 </field>
duke@0 3651 <field id="depth">
duke@0 3652 <jint/>
duke@0 3653 <description>
duke@0 3654 The depth of the frame.
duke@0 3655 </description>
duke@0 3656 </field>
duke@0 3657 <field id="method">
duke@0 3658 <jmethodID/>
duke@0 3659 <description>
duke@0 3660 The method executing in this frame.
duke@0 3661 </description>
duke@0 3662 </field>
duke@0 3663 </typedef>
duke@0 3664
duke@0 3665 <typedef id="jvmtiHeapReferenceInfoReserved"
duke@0 3666 label="Reference information structure for Other references"
duke@0 3667 since="1.1">
duke@0 3668 <description>
duke@0 3669 Reference information returned for other references.
duke@0 3670 </description>
duke@0 3671 <field id="reserved1">
duke@0 3672 <jlong/>
duke@0 3673 <description>
duke@0 3674 reserved for future use.
duke@0 3675 </description>
duke@0 3676 </field>