jvmti.xml revision 12290:8953c0318163
1<?xml version="1.0" encoding="ISO-8859-1"?> 2<?xml-stylesheet type="text/xsl" href="jvmti.xsl"?> 3<!-- 4 Copyright (c) 2002, 2016, Oracle and/or its affiliates. All rights reserved. 5 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 6 7 This code is free software; you can redistribute it and/or modify it 8 under the terms of the GNU General Public License version 2 only, as 9 published by the Free Software Foundation. 10 11 This code is distributed in the hope that it will be useful, but WITHOUT 12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 version 2 for more details (a copy is included in the LICENSE file that 15 accompanied this code). 16 17 You should have received a copy of the GNU General Public License version 18 2 along with this work; if not, write to the Free Software Foundation, 19 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 21 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 or visit www.oracle.com if you need additional information or have any 23 questions. 24--> 25 26<!DOCTYPE specification [ 27 <!ELEMENT specification (title, intro*, functionsection, errorsection, 28 eventsection, datasection, issuessection, changehistory)> 29 <!ATTLIST specification label CDATA #REQUIRED 30 majorversion CDATA #REQUIRED 31 minorversion CDATA #REQUIRED 32 microversion CDATA #REQUIRED> 33 34 <!ELEMENT title (#PCDATA|jvmti|tm)*> 35 <!ATTLIST title subtitle CDATA #REQUIRED> 36 37 <!ELEMENT intro ANY> 38 <!ATTLIST intro id CDATA #IMPLIED 39 label CDATA ""> 40 41 <!ELEMENT functionsection (intro*, category*)> 42 <!ATTLIST functionsection label CDATA #REQUIRED> 43 44 <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*, 45 (function|callback|elide)*)> 46 <!ATTLIST category id CDATA #REQUIRED 47 label CDATA #REQUIRED> 48 49 <!ELEMENT function (synopsis, typedef*, description?, origin, 50 (capabilities|eventcapabilities), 51 parameters, errors)> 52 <!ATTLIST function id CDATA #REQUIRED 53 num CDATA #REQUIRED 54 phase (onload|onloadOnly|start|live|any) #IMPLIED 55 callbacksafe (safe|unsafe) #IMPLIED 56 impl CDATA #IMPLIED 57 hide CDATA #IMPLIED 58 jkernel (yes|no) #IMPLIED 59 since CDATA "1.0"> 60 61 <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject| 62 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void), 63 synopsis, description?, parameters)> 64 <!ATTLIST callback id CDATA #REQUIRED 65 since CDATA "1.0"> 66 67 <!ELEMENT synopsis (#PCDATA|jvmti)*> 68 69 <!ELEMENT typedef (description?, field*)> 70 <!ATTLIST typedef id CDATA #REQUIRED 71 label CDATA #REQUIRED 72 since CDATA "1.0"> 73 74 <!ELEMENT uniontypedef (description?, field*)> 75 <!ATTLIST uniontypedef id CDATA #REQUIRED 76 label CDATA #REQUIRED 77 since CDATA "1.0"> 78 79 <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject| 80 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct), 81 description)> 82 <!ATTLIST field id CDATA #REQUIRED> 83 84 <!ELEMENT capabilitiestypedef (description?, capabilityfield*)> 85 <!ATTLIST capabilitiestypedef id CDATA #REQUIRED 86 label CDATA #REQUIRED> 87 88 <!ELEMENT capabilityfield (description)> 89 <!ATTLIST capabilityfield id CDATA #REQUIRED 90 disp1 CDATA "" 91 disp2 CDATA "" 92 since CDATA "1.0"> 93 94 <!ELEMENT description ANY> 95 96 <!ELEMENT capabilities (required*, capability*)> 97 98 <!ELEMENT eventcapabilities EMPTY> 99 100 <!ELEMENT required ANY> 101 <!ATTLIST required id CDATA #REQUIRED> 102 103 <!ELEMENT capability ANY> 104 <!ATTLIST capability id CDATA #REQUIRED> 105 106 <!ELEMENT parameters (param*)> 107 108 <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject| 109 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype| 110 outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf), 111 description)> 112 <!ATTLIST param id CDATA #REQUIRED> 113 114 <!ELEMENT jmethodID EMPTY> 115 <!ATTLIST jmethodID class CDATA #IMPLIED 116 native CDATA #IMPLIED> 117 118 <!ELEMENT jfieldID EMPTY> 119 <!ATTLIST jfieldID class CDATA #IMPLIED> 120 121 <!ELEMENT jclass EMPTY> 122 <!ATTLIST jclass method CDATA #IMPLIED 123 field CDATA #IMPLIED> 124 125 <!ELEMENT jframeID EMPTY> 126 <!ATTLIST jframeID thread CDATA #IMPLIED> 127 128 <!ELEMENT jrawMonitorID EMPTY> 129 130 <!ELEMENT jthread EMPTY> 131 <!ATTLIST jthread started CDATA #IMPLIED 132 null CDATA #IMPLIED 133 frame CDATA #IMPLIED 134 impl CDATA #IMPLIED> 135 136 <!ELEMENT varargs EMPTY> 137 138 <!ELEMENT jthreadGroup EMPTY> 139 <!ELEMENT jobject EMPTY> 140 <!ELEMENT jvalue EMPTY> 141 <!ELEMENT jchar EMPTY> 142 <!ELEMENT jint EMPTY> 143 <!ATTLIST jint min CDATA #IMPLIED> 144 <!ELEMENT jlong EMPTY> 145 <!ELEMENT jfloat EMPTY> 146 <!ELEMENT jdouble EMPTY> 147 <!ELEMENT jlocation EMPTY> 148 <!ELEMENT jboolean EMPTY> 149 <!ELEMENT char EMPTY> 150 <!ELEMENT uchar EMPTY> 151 <!ELEMENT size_t EMPTY> 152 <!ELEMENT void EMPTY> 153 <!ELEMENT enum (#PCDATA)*> 154 <!ELEMENT struct (#PCDATA)*> 155 156 <!ELEMENT nullok ANY> 157 158 <!ELEMENT ptrtype ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| 159 jthreadGroup|jobject|jvalue), nullok?)> 160 161 <!ELEMENT outptr ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| 162 jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble| 163 jlocation|jboolean|char|uchar|size_t|void), nullok?)> 164 165 <!ELEMENT allocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| 166 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| 167 jlocation|jboolean|char|uchar|size_t|void), nullok?)> 168 <!ATTLIST allocbuf incount CDATA #IMPLIED 169 outcount CDATA #IMPLIED> 170 171 <!ELEMENT allocallocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| 172 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| 173 jlocation|jboolean|char|uchar|size_t|void), nullok?)> 174 <!ATTLIST allocallocbuf incount CDATA #IMPLIED 175 outcount CDATA #IMPLIED> 176 177 <!ELEMENT inptr (struct, nullok?)> 178 179 <!ELEMENT inbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| 180 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| 181 jlocation|jboolean|char|uchar|size_t|void), nullok?)> 182 <!ATTLIST inbuf incount CDATA #IMPLIED> 183 184 <!ELEMENT outbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| 185 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| 186 jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)> 187 <!ATTLIST outbuf incount CDATA #IMPLIED 188 outcount CDATA #IMPLIED> 189 190 <!ELEMENT vmbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| 191 jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble| 192 jlocation|jboolean|char|uchar|size_t|void), nullok?)> 193 <!ATTLIST vmbuf incount CDATA #IMPLIED 194 outcount CDATA #IMPLIED> 195 196 <!ELEMENT agentbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| 197 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| 198 jlocation|jboolean|char|uchar|size_t|void), nullok?)> 199 <!ATTLIST agentbuf incount CDATA #IMPLIED 200 outcount CDATA #IMPLIED> 201 202 <!ELEMENT allocfieldbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| 203 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| 204 jlocation|jboolean|char|uchar|size_t|void))> 205 <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED> 206 207 <!ELEMENT errors (error*)> 208 209 <!ELEMENT error ANY> 210 <!ATTLIST error id CDATA #REQUIRED> 211 212 <!ELEMENT errorsection (intro*, errorcategory*)> 213 <!ATTLIST errorsection label CDATA #REQUIRED> 214 215 <!ELEMENT errorcategory (intro*, errorid*)> 216 <!ATTLIST errorcategory id CDATA #REQUIRED 217 label CDATA #REQUIRED> 218 219 <!ELEMENT errorid ANY> 220 <!ATTLIST errorid id CDATA #REQUIRED 221 num CDATA #REQUIRED> 222 223 <!ELEMENT datasection (intro*, basetypes*)> 224 225 <!ELEMENT basetypes (intro*, basetype*)> 226 <!ATTLIST basetypes id CDATA #REQUIRED 227 label CDATA #REQUIRED> 228 229 <!ELEMENT basetype (definition?,description)> 230 <!ATTLIST basetype id CDATA #REQUIRED> 231 232 <!ELEMENT definition (#PCDATA|jvmti)*> 233 234 <!ELEMENT eventsection (intro*, (event|elide)*)> 235 <!ATTLIST eventsection label CDATA #REQUIRED> 236 237 <!ELEMENT event (description, origin, typedef*, capabilities, parameters)> 238 <!ATTLIST event id CDATA #REQUIRED 239 label CDATA #REQUIRED 240 const CDATA #REQUIRED 241 num CDATA #REQUIRED 242 phase (onload|start|live|any) #IMPLIED 243 filtered (thread|global) #IMPLIED 244 since CDATA "1.0"> 245 246 <!ELEMENT issuessection (intro*)> 247 <!ATTLIST issuessection label CDATA #REQUIRED> 248 249 <!ELEMENT changehistory (intro*, change*)> 250 <!ATTLIST changehistory update CDATA #REQUIRED 251 id CDATA #REQUIRED> 252 253 <!ELEMENT change ANY> 254 <!ATTLIST change date CDATA #REQUIRED 255 version CDATA #IMPLIED> 256 257 <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*> 258 <!ATTLIST functionlink id CDATA #REQUIRED> 259 260 <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*> 261 <!ATTLIST datalink id CDATA #REQUIRED> 262 263 <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*> 264 <!ATTLIST typelink id CDATA #REQUIRED> 265 266 <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*> 267 <!ATTLIST fieldlink id CDATA #REQUIRED 268 struct CDATA #REQUIRED> 269 270 <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*> 271 <!ATTLIST paramlink id CDATA #REQUIRED> 272 273 <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*> 274 <!ATTLIST eventlink id CDATA #REQUIRED> 275 276 <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*> 277 <!ATTLIST errorlink id CDATA #REQUIRED> 278 279 <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*> 280 <!ATTLIST externallink id CDATA #REQUIRED> 281 282 <!ELEMENT vmspec EMPTY> 283 <!ATTLIST vmspec chapter CDATA #IMPLIED> 284 285 <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*> 286 <!ATTLIST internallink id CDATA #REQUIRED> 287 288 <!ELEMENT functionphaselist EMPTY> 289 <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED> 290 291 <!ELEMENT eventphaselist EMPTY> 292 <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED> 293 294 <!ELEMENT issue ANY> 295 296 <!ELEMENT rationale ANY> 297 298 <!ELEMENT todo ANY> 299 300 <!ELEMENT origin (#PCDATA)*> 301 302 <!ELEMENT elide (intro|function|callback|event)*> 303 <!ATTLIST elide why CDATA #IMPLIED> 304 305 <!ELEMENT constants (constant*)> 306 <!ATTLIST constants id CDATA #REQUIRED 307 label CDATA #REQUIRED 308 kind (enum|bits|const) #REQUIRED 309 since CDATA "1.0"> 310 311 <!ELEMENT constant ANY> 312 <!ATTLIST constant id CDATA #REQUIRED 313 num CDATA #REQUIRED> 314 315 <!ELEMENT tm (#PCDATA)> 316 317 <!ELEMENT i (#PCDATA|jvmti|tm)*> 318 319 <!ELEMENT b (#PCDATA|jvmti|code)*> 320 321 <!ELEMENT code (#PCDATA|space)*> 322 323 <!ELEMENT pre ANY> 324 325 <!ELEMENT space EMPTY> 326 327 <!ELEMENT jvmti EMPTY> 328 329 <!ELEMENT example (#PCDATA|i)*> 330 331 <!ELEMENT br EMPTY> 332 333 <!ELEMENT p EMPTY> 334 335 <!ELEMENT dl (dt|dd)+> 336 337 <!ELEMENT dd ANY> 338 339 <!ELEMENT dt (#PCDATA|jvmti|code|i|b)*> 340 341 <!ELEMENT table (tr)+> 342 343 <!ELEMENT tr (td|th)*> 344 345 <!ELEMENT td ANY> 346 <!ATTLIST td align (left|right|center) "center"> 347 348 <!ELEMENT th ANY> 349 <!ATTLIST th align (left|right|center) "center"> 350 351 <!ELEMENT ul (li)+> 352 <!ATTLIST ul type (disc|circle|square) "disc"> 353 354 <!ELEMENT li ANY> 355 ]> 356 357<specification label="JVM(TM) Tool Interface" 358 majorversion="9" 359 minorversion="0" 360 microversion="0"> 361 <title subtitle="Version"> 362 <tm>JVM</tm> Tool Interface 363 </title> 364 365 <intro id="whatIs" label="What is the JVM Tool Interface?"> 366 The <tm>JVM</tm> Tool Interface (<jvmti/>) 367 is a programming interface used by development and monitoring tools. 368 It provides both a way to inspect the state and 369 to control the execution of applications running in the 370 <tm>Java</tm> virtual machine (VM). 371 <p/> 372 <jvmti/> is intended to provide a VM interface for the full breadth of tools 373 that need access to VM state, including but not limited to: profiling, 374 debugging, monitoring, thread analysis, and coverage analysis tools. 375 <p/> 376 <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual 377 machine. 378 <p/> 379 <jvmti/> is a two-way interface. 380 A client of <jvmti/>, hereafter called an <i>agent</i>, 381 can be notified of 382 interesting occurrences through <internallink id="EventSection">events</internallink>. 383 <jvmti/> 384 can query and control the application through many 385 <internallink id="FunctionSection">functions</internallink>, 386 either in response to events or 387 independent of them. 388 <p/> 389 Agents run in the same process with and communicate directly with 390 the virtual machine executing 391 the application being examined. This communication is 392 through a native interface (<jvmti/>). The native in-process interface allows 393 maximal control with minimal intrusion on the part of a tool. 394 Typically, agents are relatively compact. They can be controlled 395 by a separate process which implements the bulk of a tool's 396 function without interfering with the target application's normal execution. 397 </intro> 398 399 <intro id="architecture" label="Architecture"> 400 Tools can be written directly to <jvmti/> or indirectly 401 through higher level interfaces. 402 The Java Platform Debugger Architecture includes <jvmti/>, but also 403 contains higher-level, out-of-process debugger interfaces. The higher-level 404 interfaces are more appropriate than <jvmti/> for many tools. 405 For more information on the Java Platform Debugger Architecture, 406 see the 407 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/architecture.html">Java 408 Platform Debugger Architecture website</externallink>. 409 </intro> 410 411 <intro id="writingAgents" label="Writing Agents"> 412 Agents can be written in any native language that supports C 413 language calling conventions and C or C++ 414 definitions. 415 <p/> 416 The function, event, data type, and constant definitions needed for 417 using <jvmti/> are defined in the include file <code>jvmti.h</code>. 418 To use these definitions add the <tm>J2SE</tm> include directory 419 to your include path and add 420 <example> 421#include <jvmti.h> 422 </example> 423 to your source code. 424 </intro> 425 426 <intro id="deployingAgents" label="Deploying Agents"> 427 An agent is deployed in a platform specific manner but is typically the 428 platform equivalent of a dynamic library. On the <tm>Windows</tm> operating 429 system, for example, an agent library is a "Dynamic Linked Library" (DLL). 430 On the <tm>Solaris</tm> Operating Environment, an agent library is a shared 431 object (<code>.so</code> file). 432 <p/> 433 434 An agent may be started at VM startup by specifying the agent library 435 name using a <internallink id="starting">command line option</internallink>. 436 Some implementations may support a mechanism to <internallink id="onattach"> 437 start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>. 438 The details of how this is initiated are implementation specific. 439 </intro> 440 441 <intro id="entry point" label="Statically Linked Agents (since version 1.2.3)"> 442 443 A native JVMTI Agent may be <i>statically linked</i> with the VM. 444 The manner in which the library and VM image are combined is 445 implementation-dependent. 446 An agent L whose image has been combined with the VM is defined as 447 <i>statically linked</i> if and only if the agent exports a function 448 called Agent_OnLoad_L. 449<p/> 450 If a <i>statically linked</i> agent L exports a function called 451 Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad 452 function will be ignored. 453 If an agent L is <i>statically linked</i>, an Agent_OnLoad_L 454 function will be invoked with the same arguments and expected return 455 value as specified for the Agent_OnLoad function. 456 An agent L that is <i>statically linked</i> will prohibit an agent of 457 the same name from being loaded dynamically. 458<p/> 459 The VM will invoke the Agent_OnUnload_L function of the agent, if such 460 a function is exported, at the same point during VM execution as it would 461 have called the dynamic entry point Agent_OnUnLoad. A statically loaded 462 agent cannot be unloaded. The Agent_OnUnload_L function will still be 463 called to do any other agent shutdown related tasks. 464 If a <i>statically linked</i> agent L exports a function called 465 Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad 466 function will be ignored. 467<p/> 468 If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function 469 will be invoked with the same arguments and expected return value as 470 specified for the Agent_OnAttach function. 471 If a <i>statically linked</i> agent L exports a function called 472 Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach 473 function will be ignored. 474</intro> 475 476 <intro id="starting" label="Agent Command Line Options"> 477 The term "command-line option" is used below to 478 mean options supplied in the <code>JavaVMInitArgs</code> argument 479 to the <code>JNI_CreateJavaVM</code> function of the JNI 480 Invocation API. 481 <p/> 482 One of the two following 483 command-line options is used on VM startup to 484 properly load and run agents. 485 These arguments identify the library containing 486 the agent as well as an options 487 string to be passed in at startup. 488 <dl> 489 <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt> 490 <dd> 491 The name following <code>-agentlib:</code> is the name of the 492 library to load. Lookup of the library, both its full name and location, 493 proceeds in a platform-specific manner. 494 Typically, the <i><agent-lib-name></i> is expanded to an 495 operating system specific file name. 496 The <i><options></i> will be passed to the agent on start-up. 497 For example, if the option 498 <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to 499 load the shared library <code>foo.dll</code> from the system <code>PATH</code> 500 under <tm>Windows</tm> or <code>libfoo.so</code> from the 501 <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating 502 environment. 503 If the agent library is statically linked into the executable 504 then no actual loading takes place. 505 <p/> 506 </dd> 507 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt> 508 <dd> 509 The path following <code>-agentpath:</code> is the absolute path from which 510 to load the library. 511 No library name expansion will occur. 512 The <i><options></i> will be passed to the agent on start-up. 513 For example, if the option 514 <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to 515 load the shared library <code>c:\myLibs\foo.dll</code>. If the agent 516 library is statically linked into the executable 517 then no actual loading takes place. 518 <p/> 519 </dd> 520 </dl> 521 For a dynamic shared library agent, the start-up routine 522 <internallink id="onload"><code>Agent_OnLoad</code></internallink> 523 in the library will be invoked. If the agent library is statically linked 524 into the executable then the system will attempt to invoke the 525 <code>Agent_OnLoad_<agent-lib-name></code> entry point where 526 <agent-lib-name> is the basename of the 527 agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>, 528 the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine. 529 <p/> 530 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code> 531 will be searched for JNI native method implementations to facilitate the 532 use of Java programming language code in tools, as is needed for 533 <internallink id="bci">bytecode instrumentation</internallink>. 534 <p/> 535 The agent libraries will be searched after all other libraries have been 536 searched (agents wishing to override or intercept the native method 537 implementations of non-agent methods can use the 538 <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>). 539 <p/> 540 These switches do the above and nothing more - they do not change the 541 state of the VM or <jvmti/>. No command line options are needed 542 to enable <jvmti/> 543 or aspects of <jvmti/>, this is handled programmatically 544 by the use of 545 <internallink id="capability">capabilities</internallink>. 546 </intro> 547 548 <intro id="startup" label="Agent Start-Up"> 549 The VM starts each agent by invoking a start-up function. 550 If the agent is started in the <code>OnLoad</code> 551 <functionlink id="GetPhase">phase</functionlink> the function 552 <internallink id="onload"><code>Agent_OnLoad</code></internallink> 553 or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink> 554 for statically linked agents will be invoked. 555 If the agent is started in the live 556 <functionlink id="GetPhase">phase</functionlink> the function 557 <internallink id="onattach"><code>Agent_OnAttach</code></internallink> 558 or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink> 559 for statically linked agents will be invoked. 560 Exactly one call to a start-up function is made per agent. 561 </intro> 562 563 <intro id="onload" label="Agent Start-Up (OnLoad phase)"> 564 If an agent is started during the <code>OnLoad</code> phase then its 565 agent library must export a start-up function with the following prototype: 566 <example> 567JNIEXPORT jint JNICALL 568Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example> 569 Or for a statically linked agent named 'L': 570 <example> 571JNIEXPORT jint JNICALL 572Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example> 573 574 The VM will start the agent by calling this function. 575 It will be called early enough in VM initialization that: 576 <ul> 577 <li><functionlink id="SetSystemProperty">system properties</functionlink> 578 may be set before they have been used in the start-up of the VM</li> 579 <li>the full set of 580 <internallink id="capability">capabilities</internallink> 581 is still available (note that capabilities that configure the VM 582 may only be available at this time--see the 583 <internallink id="capability">Capability function section</internallink>)</li> 584 <li>no bytecodes have executed</li> 585 <li>no classes have been loaded</li> 586 <li>no objects have been created</li> 587 </ul> 588 <p/> 589 The VM will call the <code>Agent_OnLoad</code> or 590 <code>Agent_OnLoad_<agent-lib-name></code> function with 591 <i><options></i> as the second argument - 592 that is, using the command-line option examples, 593 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> 594 argument of <code>Agent_OnLoad</code>. 595 The <code>options</code> argument is encoded as a 596 <internallink id="mUTF">modified UTF-8</internallink> string. 597 If <i>=<options></i> is not specified, 598 a zero length string is passed to <code>options</code>. 599 The lifespan of the <code>options</code> string is the 600 <code>Agent_OnLoad</code> or <code>Agent_OnLoad_<agent-lib-name></code> 601 call. If needed beyond this time the string or parts of the string must 602 be copied. 603 The period between when <code>Agent_OnLoad</code> is called and when it 604 returns is called the <i>OnLoad phase</i>. 605 Since the VM is not initialized during the OnLoad 606 <functionlink id="GetPhase">phase</functionlink>, 607 the set of allowed operations 608 inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the 609 functionality available at this time). 610 The agent can safely process the options and set 611 event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once 612 the VM initialization event is received 613 (that is, the <eventlink id="VMInit">VMInit</eventlink> 614 callback is invoked), the agent 615 can complete its initialization. 616 <rationale> 617 Early startup is required so that agents can set the desired capabilities, 618 many of which must be set before the VM is initialized. 619 In JVMDI, the -Xdebug command-line option provided 620 very coarse-grain control of capabilities. 621 JVMPI implementations use various tricks to provide a single "JVMPI on" switch. 622 No reasonable command-line 623 option could provide the fine-grain of control required to balance needed capabilities vs 624 performance impact. 625 Early startup is also needed so that agents can control the execution 626 environment - modifying the file system and system properties to install 627 their functionality. 628 </rationale> 629 <p/> 630 The return value from <code>Agent_OnLoad</code> or 631 <code>Agent_OnLoad_<agent-lib-name></code> is used to indicate an error. 632 Any value other than zero indicates an error and causes termination of the VM. 633 </intro> 634 635 <intro id="onattach" label="Agent Start-Up (Live phase)"> 636 A VM may support a mechanism that allows agents to be started in the VM during the live 637 <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported, 638 are implementation specific. For example, a tool may use some platform specific mechanism, 639 or implementation specific API, to attach to the running VM, and request it start a given 640 agent. 641 <p/> 642 If an agent is started during the live phase then its agent library 643 must export a start-up function 644 with the following prototype: 645 <example> 646JNIEXPORT jint JNICALL 647Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example> 648Or for a statically linked agent named 'L': 649 <example> 650JNIEXPORT jint JNICALL 651Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example> 652 653 <p/> 654 The VM will start the agent by calling this function. 655 It will be called in the context of a thread 656 that is attached to the VM. The first argument <i><vm></i> is the Java VM. 657 The <i><options></i> argument is the startup options provided to the agent. 658 <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8 659 </internallink> string. 660 If startup options were not provided, a zero length string is passed to 661 <code>options</code>. The lifespan of the <code>options</code> string is the 662 <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name></code> call. 663 If needed beyond this time the string or parts of the string must be copied. 664 <p/> 665 Note that some <internallink id="capability">capabilities</internallink> 666 may not be available in the live phase. 667 <p/> 668 The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name 669 ></code> function initializes the agent and returns a value 670 to the VM to indicate if an error occurred. Any value other than zero indicates an error. 671 An error does not cause the VM to terminate. Instead the VM ignores the error, or takes 672 some implementation specific action -- for example it might print an error to standard error, 673 or record the error in a system log. 674 </intro> 675 676 <intro id="onunload" label="Agent Shutdown"> 677 The library may optionally export a 678 shutdown function with the following prototype: 679 <example> 680JNIEXPORT void JNICALL 681Agent_OnUnload(JavaVM *vm)</example> 682 Or for a statically linked agent named 'L': 683 <example> 684JNIEXPORT void JNICALL 685Agent_OnUnload_L(JavaVM *vm)</example> 686 687 This function will be called by the VM when the library is about to be unloaded. 688 The library will be unloaded (unless it is statically linked into the 689 executable) and this function will be called if some platform specific 690 mechanism causes the unload (an unload mechanism is not specified in this document) 691 or the library is (in effect) unloaded by the termination of the VM whether through 692 normal termination or VM failure, including start-up failure. 693 Uncontrolled shutdown is, of couse, an exception to this rule. 694 Note the distinction between this function and the 695 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event 696 to be sent, the VM must have run at least to the point of initialization and a valid 697 <jvmti/> environment must exist which has set a callback for VMDeath 698 and enabled the event. 699 None of these are required for <code>Agent_OnUnload</code> or 700 <code>Agent_OnUnload_<agent-lib-name></code> and this function 701 is also called if the library is unloaded for other reasons. 702 In the case that a VM Death event is sent, it will be sent before this 703 function is called (assuming this function is called due to VM termination). 704 This function can be used to clean-up resources allocated by the agent. 705 </intro> 706 707 <intro id="tooloptions" label="JAVA_TOOL_OPTIONS"> 708 Since the command-line cannot always be accessed or modified, for example in embedded VMs 709 or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is 710 provided so that agents may be launched in these cases. 711 <p/> 712 Platforms which support environment variables or other named strings, may support the 713 <code>JAVA_TOOL_OPTIONS</code> variable. This variable will be broken into options at white-space 714 boundaries. White-space characters include space, tab, carriage-return, new-line, 715 vertical-tab, and form-feed. Sequences of white-space characters are considered 716 equivalent to a single white-space character. No white-space is included in the options 717 unless quoted. Quoting is as follows: 718 <ul> 719 <li>All characters enclosed between a pair of single quote marks (''), except a single 720 quote, are quoted.</li> 721 <li>Double quote characters have no special meaning inside a pair of single quote marks.</li> 722 <li>All characters enclosed between a pair of double quote marks (""), except a double 723 quote, are quoted.</li> 724 <li>Single quote characters have no special meaning inside a pair of double quote marks.</li> 725 <li>A quoted part can start or end anywhere in the variable.</li> 726 <li>White-space characters have no special meaning when quoted -- they are included in 727 the option like any other character and do not mark white-space boundaries.</li> 728 <li>The pair of quote marks is not included in the option.</li> 729 </ul> 730 <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied 731 in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is 732 a concern; for example, the Reference Implementation disables this feature on Unix systems when 733 the effective user or group ID differs from the real ID. 734 This feature is intended to support the initialization of tools -- specifically including the 735 launching of native or Java programming language agents. Multiple tools may wish to use this 736 feature, so the variable should not be overwritten, instead, options should be appended to 737 the variable. Note that since the variable is processed at the time of the JNI Invocation 738 API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled. 739 </intro> 740 741 <intro id="environments" label="Environments"> 742 The <jvmti/> specification supports the use of multiple simultaneous 743 <jvmti/> agents. 744 Each agent has its own <jvmti/> environment. 745 That is, the <jvmti/> state is 746 separate for each agent - changes to one environment do not affect the 747 others. The state of a <jvmti/> 748 environment includes: 749 <ul> 750 <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li> 751 <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li> 752 <li><internallink id="capability">the capabilities</internallink></li> 753 <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li> 754 </ul> 755 Although their <jvmti/> state 756 is separate, agents inspect and modify the shared state 757 of the VM, they also share the native environment in which they execute. 758 As such, an agent can perturb the results of other agents or cause them 759 to fail. It is the responsibility of the agent writer to specify the level 760 of compatibility with other agents. <jvmti/> implementations are not capable 761 of preventing destructive interactions between agents. Techniques to reduce 762 the likelihood of these occurrences are beyond the scope of this document. 763 <p/> 764 An agent creates a <jvmti/> environment 765 by passing a <jvmti/> version 766 as the interface ID to the JNI Invocation API function 767 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><code>GetEnv</code></externallink>. 768 See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink> 769 for more details on the creation and use of 770 <jvmti/> environments. 771 Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from 772 <internallink id="onload"><code>Agent_OnLoad</code></internallink>. 773 </intro> 774 775 <intro id="bci" label="Bytecode Instrumentation"> 776 This interface does not include some events that one might expect in an interface with 777 profiling support. Some examples include object allocation events and full speed 778 method enter and exit events. The interface instead provides support for 779 <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine 780 bytecode instructions which comprise the target program. Typically, these alterations 781 are to add "events" to the code of a method - for example, to add, at the beginning of a method, 782 a call to <code>MyProfiler.methodEntered()</code>. 783 Since the changes are purely additive, they do not modify application 784 state or behavior. 785 Because the inserted agent code is standard bytecodes, the VM can run at full speed, 786 optimizing not only the target program but also the instrumentation. If the 787 instrumentation does not involve switching from bytecode execution, no expensive 788 state transitions are needed. The result is high performance events. 789 This approach also provides complete control to the agent: instrumentation can be 790 restricted to "interesting" portions of the code (e.g., the end user's code) and 791 can be conditional. Instrumentation can run entirely in Java programming language 792 code or can call into the native agent. Instrumentation can simply maintain 793 counters or can statistically sample events. 794 <p/> 795 Instrumentation can be inserted in one of three ways: 796 <ul> 797 <li> 798 Static Instrumentation: The class file is instrumented before it 799 is loaded into the VM - for example, by creating a duplicate directory of 800 <code>*.class</code> files which have been modified to add the instrumentation. 801 This method is extremely awkward and, in general, an agent cannot know 802 the origin of the class files which will be loaded. 803 </li> 804 <li> 805 Load-Time Instrumentation: When a class file is loaded by the VM, the raw 806 bytes of the class file are sent for instrumentation to the agent. 807 The <eventlink id="ClassFileLoadHook"/> 808 event, triggered by the class load, 809 provides this functionality. This mechanism provides efficient 810 and complete access to one-time instrumentation. 811 </li> 812 <li> 813 Dynamic Instrumentation: A class which is already loaded (and possibly 814 even running) is modified. This optional feature is provided by the 815 <eventlink id="ClassFileLoadHook"/> event, triggered by calling the 816 <functionlink id="RetransformClasses"/> function. 817 Classes can be modified multiple times and can be returned to their 818 original state. 819 The mechanism allows instrumentation which changes during the 820 course of execution. 821 </li> 822 </ul> 823 <p/> 824 The class modification functionality provided in this interface 825 is intended to provide a mechanism for instrumentation 826 (the <eventlink id="ClassFileLoadHook"/> event 827 and the <functionlink id="RetransformClasses"/> function) 828 and, during development, for fix-and-continue debugging 829 (the <functionlink id="RedefineClasses"/> function). 830 <p/> 831 Care must be taken to avoid perturbing dependencies, especially when 832 instrumenting core classes. For example, an approach to getting notification 833 of every object allocation is to instrument the constructor on 834 <code>Object</code>. Assuming that the constructor is initially 835 empty, the constructor could be changed to: 836 <example> 837 public Object() { 838 MyProfiler.allocationTracker(this); 839 } 840 </example> 841 However, if this change was made using the 842 <eventlink id="ClassFileLoadHook"/> 843 event then this might impact a typical VM as follows: 844 the first created object will call the constructor causing a class load of 845 <code>MyProfiler</code>; which will then cause 846 object creation, and since <code>MyProfiler</code> isn't loaded yet, 847 infinite recursion; resulting in a stack overflow. A refinement of this 848 would be to delay invoking the tracking method until a safe time. For 849 example, <code>trackAllocations</code> could be set in the 850 handler for the <code>VMInit</code> event. 851 <example> 852 static boolean trackAllocations = false; 853 854 public Object() { 855 if (trackAllocations) { 856 MyProfiler.allocationTracker(this); 857 } 858 } 859 </example> 860 <p/> 861 The <functionlink id="SetNativeMethodPrefix"/> allows native methods 862 to be instrumented by the use of wrapper methods. 863 </intro> 864 865<intro id="bcimodules" label="Bytecode Instrumentation of code in modules"> 866 Agents can use the functions <functionlink id="AddModuleReads"/>, 867 <functionlink id="AddModuleExports"/>, <functionlink id="AddModuleOpens"/>, 868 <functionlink id="AddModuleUses"/> and <functionlink id="AddModuleProvides"/> 869 to update a module to expand the set of modules that it reads, the set of 870 packages that it exports or opens to other modules, or the services that it 871 uses and provides. 872 <p/> 873 As an aid to agents that deploy supporting classes on the search path of 874 the bootstrap class loader, or the search path of the class loader that 875 loads the main class, the Java virtual machine arranges for the module 876 of classes transformed by the <eventlink id="ClassFileLoadHook"/> event to 877 read the unnamed module of both class loaders. 878</intro> 879 880 <intro id="mUTF" label="Modified UTF-8 String Encoding"> 881 <jvmti/> uses modified UTF-8 to encode character strings. 882 This is the same encoding used by JNI. 883 Modified UTF-8 differs 884 from standard UTF-8 in the representation of supplementary characters 885 and of the null character. See the 886 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16542"> 887 Modified UTF-8 Strings</externallink> 888 section of the JNI specification for details. 889 </intro> 890 891 <intro id="context" label="Specification Context"> 892 Since this interface provides access to the state of applications running in the 893 Java virtual machine; 894 terminology refers to the Java platform and not the native 895 platform (unless stated otherwise). For example: 896 <ul> 897 <li>"thread" means Java programming language thread.</li> 898 <li>"stack frame" means Java virtual machine stack frame.</li> 899 <li>"class" means Java programming language class.</li> 900 <li>"heap" means Java virtual machine heap.</li> 901 <li>"monitor" means Java programming language object monitor.</li> 902 </ul> 903 <p/> 904 Sun, Sun Microsystems, the Sun logo, Java, and JVM 905 are trademarks or registered trademarks of Oracle 906 and/or its affiliates, in the U.S. and other countries. 907 </intro> 908 909 910<functionsection label="Functions"> 911 <intro id="jvmtiEnvAccess" label="Accessing Functions"> 912 Native code accesses <jvmti/> features 913 by calling <jvmti/> functions. 914 Access to <jvmti/> functions is by use of an interface pointer 915 in the same manner as 916 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html">Java 917 Native Interface (JNI) functions</externallink> are accessed. 918 The <jvmti/> interface pointer is called the 919 <i>environment pointer</i>. 920 <p/> 921 An environment pointer is a pointer to an environment and has 922 the type <code>jvmtiEnv*</code>. 923 An environment has information about its <jvmti/> connection. 924 The first value in the environment is a pointer to the function table. 925 The function table is an array of pointers to <jvmti/> functions. 926 Every function pointer is at a predefined offset inside the 927 array. 928 <p/> 929 When used from the C language: 930 double indirection is used to access the functions; 931 the environment pointer provides context and is the first 932 parameter of each function call; for example: 933 <example> 934jvmtiEnv *jvmti; 935... 936jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &class_count, &classes); 937 </example> 938 <p/> 939 When used from the C++ language: 940 functions are accessed as member functions of <code>jvmtiEnv</code>; 941 the environment pointer is not passed to the function call; for example: 942 <example> 943jvmtiEnv *jvmti; 944... 945jvmtiError err = jvmti->GetLoadedClasses(&class_count, &classes); 946 </example> 947 Unless otherwise stated, all examples and declarations in this 948 specification use the C language. 949 <p/> 950 A <jvmti/> environment can be obtained through the JNI Invocation API 951 <code>GetEnv</code> function: 952 <example> 953jvmtiEnv *jvmti; 954... 955(*jvm)->GetEnv(jvm, &jvmti, JVMTI_VERSION_1_0); 956 </example> 957 Each call to <code>GetEnv</code> 958 creates a new <jvmti/> connection and thus 959 a new <jvmti/> environment. 960 The <code>version</code> argument of <code>GetEnv</code> must be 961 a <jvmti/> version. 962 The returned environment may have a different version than the 963 requested version but the returned environment must be compatible. 964 <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a 965 compatible version is not available, if <jvmti/> is not supported or 966 <jvmti/> is not supported in the current VM configuration. 967 Other interfaces may be added for creating <jvmti/> environments 968 in specific contexts. 969 Each environment has its own state (for example, 970 <functionlink id="SetEventNotificationMode">desired events</functionlink>, 971 <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and 972 <functionlink id="AddCapabilities">capabilities</functionlink>). 973 An environment is released with 974 <functionlink id="DisposeEnvironment"></functionlink>. 975 Thus, unlike JNI which has one environment per thread, <jvmti/> environments work 976 across threads and are created dynamically. 977 </intro> 978 979 <intro id="functionReturn" label="Function Return Values"> 980 <jvmti/> functions always return an 981 <internallink id="ErrorSection">error code</internallink> via the 982 <datalink id="jvmtiError"/> function return value. 983 Some functions can return additional 984 values through pointers provided by the calling function. 985 In some cases, <jvmti/> functions allocate memory that your program must 986 explicitly deallocate. This is indicated in the individual <jvmti/> 987 function descriptions. Empty lists, arrays, sequences, etc are 988 returned as <code>NULL</code>. 989 <p/> 990 In the event that the <jvmti/> function encounters 991 an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values 992 of memory referenced by argument pointers is undefined, but no memory 993 will have been allocated and no global references will have been allocated. 994 If the error occurs because of invalid input, no action will have occurred. 995 </intro> 996 997<intro id="refs" label="Managing JNI Object References"> 998 <jvmti/> functions identify objects with JNI references 999 (<datalink id="jobject"/> and <datalink id="jclass"/>) 1000 and their derivatives 1001 (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>). 1002 References passed to 1003 <jvmti/> functions can be either global or local, but they must be 1004 strong references. All references returned by <jvmti/> functions are 1005 local references--these local references are created 1006 during the <jvmti/> call. 1007 Local references are a resource that must be managed (see the 1008 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp18654">JNI Documentation</externallink>). 1009 When threads return from native code all local references 1010 are freed. Note that some threads, including typical 1011 agent threads, will never return from native code. 1012 A thread is ensured the ability to create sixteen local 1013 references without the need for any explicit management. 1014 For threads executing a limited number of <jvmti/> calls before 1015 returning from native code 1016 (for example, threads processing events), 1017 it may be determined that no explicit management 1018 is needed. 1019 However, long running agent threads will need explicit 1020 local reference management--usually with the JNI functions 1021 <code>PushLocalFrame</code> and <code>PopLocalFrame</code>. 1022 Conversely, to preserve references beyond the 1023 return from native code, they must be converted to global references. 1024 These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> 1025 as they are not <datalink id="jobject"/>s. 1026</intro> 1027 1028 <intro id="prereqState" label="Prerequisite State for Calling Functions"> 1029 Unless the function explicitly states that the agent must bring 1030 a thread or the VM to a particular state (for example, suspended), 1031 the <jvmti/> implementation is responsible for bringing the VM to a 1032 safe and consistent state for performing the function. 1033 </intro> 1034 1035 <intro id="functionsExceptions" label="Exceptions and Functions"> 1036 <jvmti/> functions never throw exceptions; error conditions are 1037 communicated via the 1038 <internallink id="functionReturn">function return value</internallink>. 1039 Any existing exception state is preserved across a call to a 1040 <jvmti/> function. 1041 See the 1042 <externallink 1043 id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html#wp770" 1044 >Java Exceptions</externallink> 1045 section of the JNI specification for information on handling exceptions. 1046 </intro> 1047 1048 <category id="memory" label="Memory Management"> 1049 <intro> 1050 These functions provide for the allocation and deallocation of 1051 memory used by <jvmti/> functionality and can be used to provide 1052 working memory for agents. 1053 Memory managed by <jvmti/> is not compatible with other memory 1054 allocation libraries and mechanisms. 1055 </intro> 1056 1057 <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46"> 1058 <synopsis>Allocate</synopsis> 1059 <description> 1060 Allocate an area of memory through the <jvmti/> allocator. 1061 The allocated 1062 memory should be freed with <functionlink id="Deallocate"></functionlink>. 1063 </description> 1064 <origin>jvmdi</origin> 1065 <capabilities> 1066 </capabilities> 1067 <parameters> 1068 <param id="size"> 1069 <jlong/> 1070 <description> 1071 The number of bytes to allocate. 1072 <rationale> 1073 <code>jlong</code> is used for compatibility with JVMDI. 1074 </rationale> 1075 </description> 1076 </param> 1077 <param id="mem_ptr"> 1078 <allocbuf incount="size"><uchar/></allocbuf> 1079 <description> 1080 On return, a pointer to the beginning of the allocated memory. 1081 If <code>size</code> is zero, <code>NULL</code> is returned. 1082 </description> 1083 </param> 1084 </parameters> 1085 <errors> 1086 <error id="JVMTI_ERROR_OUT_OF_MEMORY"> 1087 Memory request cannot be honored. 1088 </error> 1089 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 1090 <paramlink id="size"></paramlink> is less than zero. 1091 </error> 1092 </errors> 1093 </function> 1094 1095 <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47"> 1096 <synopsis>Deallocate</synopsis> 1097 <description> 1098 Deallocate <code>mem</code> using the <jvmti/> allocator. 1099 This function should 1100 be used to deallocate any memory allocated and returned 1101 by a <jvmti/> function 1102 (including memory allocated with <functionlink id="Allocate"></functionlink>). 1103 All allocated memory must be deallocated 1104 or the memory cannot be reclaimed. 1105 </description> 1106 <origin>jvmdi</origin> 1107 <capabilities> 1108 </capabilities> 1109 <parameters> 1110 <param id="mem"> 1111 <outbuf> 1112 <uchar/> 1113 <nullok>the call is ignored</nullok> 1114 </outbuf> 1115 <description> 1116 A pointer to the beginning of the allocated memory. 1117 Please ignore "On return, the elements are set." 1118 <todo>keep it from generating "On return, the elements are set"</todo> 1119 </description> 1120 </param> 1121 </parameters> 1122 <errors> 1123 </errors> 1124 </function> 1125 </category> 1126 1127 <category id="threadCategory" label="Thread"> 1128 <intro> 1129 </intro> 1130 1131 <function id="GetThreadState" num="17"> 1132 <synopsis>Get Thread State</synopsis> 1133 <description> 1134 Get the state of a thread. The state of the thread is represented by the 1135 answers to the hierarchical set of questions below: 1136 <ul type="circle"> 1137 <li><i>Alive?</i> 1138 <ul> 1139 <li>Not alive. 1140 <ul type="circle"> 1141 <li><i>Why not alive?</i> 1142 <ul> 1143 <li>New.</li> 1144 <li>Terminated (<datalink 1145 id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li> 1146 </ul> 1147 </li> 1148 </ul> 1149 </li> 1150 <li>Alive (<datalink 1151 id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>) 1152 <ul type="circle"> 1153 <li><i>Suspended?</i> 1154 <ul> 1155 <li>Suspended (<datalink 1156 id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li> 1157 <li>Not suspended</li> 1158 </ul> 1159 </li> 1160 <li><i>Interrupted?</i> 1161 <ul> 1162 <li>Interrupted (<datalink 1163 id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li> 1164 <li>Not interrupted.</li> 1165 </ul> 1166 </li> 1167 <li><i>In native?</i> 1168 <ul> 1169 <li>In native code (<datalink 1170 id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li> 1171 <li>In Java programming language code</li> 1172 </ul> 1173 </li> 1174 <li><i>What alive state?</i> 1175 <ul> 1176 <li>Runnable (<datalink 1177 id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li> 1178 <li>Blocked (<datalink 1179 id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li> 1180 <li>Waiting (<datalink 1181 id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>) 1182 <ul type="circle"> 1183 <li><i>Timed wait?</i> 1184 <ul> 1185 <li>Indefinite (<datalink 1186 id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li> 1187 <li>Timed (<datalink 1188 id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li> 1189 </ul> 1190 </li> 1191 <li><i>Why waiting?</i> 1192 <ul> 1193 <li>Object.wait (<datalink 1194 id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li> 1195 <li>LockSupport.park (<datalink 1196 id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li> 1197 <li>Sleeping (<datalink 1198 id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li> 1199 </ul> 1200 </li> 1201 </ul> 1202 </li> 1203 </ul> 1204 </li> 1205 </ul> 1206 </li> 1207 </ul> 1208 </li> 1209 </ul> 1210 <p/> 1211 The answers are represented by the following bit vector. 1212 <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits"> 1213 <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001"> 1214 Thread is alive. Zero if thread is new (not started) or terminated. 1215 </constant> 1216 <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002"> 1217 Thread has completed execution. 1218 </constant> 1219 <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004"> 1220 Thread is runnable. 1221 </constant> 1222 <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400"> 1223 Thread is waiting to enter a synchronization block/method or, 1224 after an <code>Object.wait()</code>, waiting to re-enter a 1225 synchronization block/method. 1226 </constant> 1227 <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080"> 1228 Thread is waiting. 1229 </constant> 1230 <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010"> 1231 Thread is waiting without a timeout. 1232 For example, <code>Object.wait()</code>. 1233 </constant> 1234 <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020"> 1235 Thread is waiting with a maximum time to wait specified. 1236 For example, <code>Object.wait(long)</code>. 1237 </constant> 1238 <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040"> 1239 Thread is sleeping -- <code>Thread.sleep(long)</code>. 1240 </constant> 1241 <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100"> 1242 Thread is waiting on an object monitor -- <code>Object.wait</code>. 1243 </constant> 1244 <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200"> 1245 Thread is parked, for example: <code>LockSupport.park</code>, 1246 <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>. 1247 </constant> 1248 <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000"> 1249 Thread suspended. 1250 <code>java.lang.Thread.suspend()</code> 1251 or a <jvmti/> suspend function 1252 (such as <functionlink id="SuspendThread"></functionlink>) 1253 has been called on the thread. If this bit 1254 is set, the other bits refer to the thread state before suspension. 1255 </constant> 1256 <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000"> 1257 Thread has been interrupted. 1258 </constant> 1259 <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000"> 1260 Thread is in native code--that is, a native method is running 1261 which has not called back into the VM or Java programming 1262 language code. 1263 <p/> 1264 This flag is not set when running VM compiled Java programming 1265 language code nor is it set when running VM code or 1266 VM support code. Native VM interface functions, such as JNI and 1267 <jvmti/> functions, may be implemented as VM code. 1268 </constant> 1269 <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000"> 1270 Defined by VM vendor. 1271 </constant> 1272 <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000"> 1273 Defined by VM vendor. 1274 </constant> 1275 <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000"> 1276 Defined by VM vendor. 1277 </constant> 1278 </constants> 1279 The following definitions are used to convert <jvmti/> thread state 1280 to <code>java.lang.Thread.State</code> style states. 1281 <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits"> 1282 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK" 1283 num="JVMTI_THREAD_STATE_TERMINATED | JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"> 1284 Mask the state with this before comparison 1285 </constant> 1286 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW" 1287 num="0"> 1288 <code>java.lang.Thread.State.NEW</code> 1289 </constant> 1290 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED" 1291 num="JVMTI_THREAD_STATE_TERMINATED"> 1292 <code>java.lang.Thread.State.TERMINATED</code> 1293 </constant> 1294 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE" 1295 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE"> 1296 <code>java.lang.Thread.State.RUNNABLE</code> 1297 </constant> 1298 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED" 1299 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"> 1300 <code>java.lang.Thread.State.BLOCKED</code> 1301 </constant> 1302 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING" 1303 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY"> 1304 <code>java.lang.Thread.State.WAITING</code> 1305 </constant> 1306 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING" 1307 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"> 1308 <code>java.lang.Thread.State.TIMED_WAITING</code> 1309 </constant> 1310 </constants> 1311 <b>Rules</b> 1312 <p/> 1313 There can be no more than one answer to a question, although there can be no 1314 answer (because the answer is unknown, does not apply, or none of the answers is 1315 correct). An answer is set only when the enclosing answers match. 1316 That is, no more than one of 1317 <ul type="circle"> 1318 <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li> 1319 <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li> 1320 <li><code>JVMTI_THREAD_STATE_WAITING</code></li> 1321 </ul> 1322 can be set (a <tm>J2SE</tm> compliant implementation will always set 1323 one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set). 1324 And if any of these are set, the enclosing answer 1325 <code>JVMTI_THREAD_STATE_ALIVE</code> is set. 1326 No more than one of 1327 <ul type="circle"> 1328 <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li> 1329 <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li> 1330 </ul> 1331 can be set (a <tm>J2SE</tm> compliant implementation will always set 1332 one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set). 1333 And if either is set, the enclosing answers 1334 <code>JVMTI_THREAD_STATE_ALIVE</code> and 1335 <code>JVMTI_THREAD_STATE_WAITING</code> are set. 1336 No more than one of 1337 <ul type="circle"> 1338 <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li> 1339 <li><code>JVMTI_THREAD_STATE_PARKED</code></li> 1340 <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li> 1341 </ul> 1342 can be set. And if any of these is set, the enclosing answers 1343 <code>JVMTI_THREAD_STATE_ALIVE</code> and 1344 <code>JVMTI_THREAD_STATE_WAITING</code> are set. 1345 Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set, 1346 then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set. 1347 If a state <i>A</i> is implemented using the mechanism of 1348 state <i>B</i> then it is state <i>A</i> which 1349 is returned by this function. 1350 For example, if <code>Thread.sleep(long)</code> 1351 is implemented using <code>Object.wait(long)</code> 1352 then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code> 1353 which is returned. 1354 More than one of 1355 <ul type="circle"> 1356 <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li> 1357 <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li> 1358 <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li> 1359 </ul> 1360 can be set, but if any is set, 1361 <code>JVMTI_THREAD_STATE_ALIVE</code> is set. 1362 <p/> 1363 And finally, 1364 <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless 1365 <code>JVMTI_THREAD_STATE_ALIVE</code> is not set. 1366 <p/> 1367 The thread state representation is designed for extension in future versions 1368 of the specification; thread state values should be used accordingly, that is 1369 they should not be used as ordinals. 1370 Most queries can be made by testing a single bit, if use in a switch statement is desired, 1371 the state bits should be masked with the interesting bits. 1372 All bits not defined above are reserved for future use. 1373 A VM, compliant to the current specification, must set reserved bits to zero. 1374 An agent should ignore reserved bits -- 1375 they should not be assumed to be zero and thus should not be included in comparisons. 1376 <p/> 1377 <b>Examples</b> 1378 <p/> 1379 Note that the values below exclude reserved and vendor bits. 1380 <p/> 1381 The state of a thread blocked at a <code>synchronized</code>-statement would be: 1382 <example> 1383 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER 1384 </example> 1385 The state of a thread which hasn't started yet would be: 1386 <example> 1387 0 1388 </example> 1389 The state of a thread at a <code>Object.wait(3000)</code> would be: 1390 <example> 1391 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING + 1392 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT + 1393 JVMTI_THREAD_STATE_MONITOR_WAITING 1394 </example> 1395 The state of a thread suspended while runnable would be: 1396 <example> 1397 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED 1398 </example> 1399 <p/> 1400 <b>Testing the State</b> 1401 <p/> 1402 In most cases, the thread state can be determined by testing the one bit corresponding 1403 to that question. For example, the code to test if a thread is sleeping: 1404 <example> 1405 jint state; 1406 jvmtiError err; 1407 1408 err = (*jvmti)->GetThreadState(jvmti, thread, &state); 1409 if (err == JVMTI_ERROR_NONE) { 1410 if (state & JVMTI_THREAD_STATE_SLEEPING) { ... 1411 </example> 1412 <p/> 1413 For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be: 1414 <example> 1415 if (state & JVMTI_THREAD_STATE_WAITING) { ... 1416 </example> 1417 For some states, more than one bit will need to be tested as is the case 1418 when testing if a thread has not yet been started: 1419 <example> 1420 if ((state & (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0) { ... 1421 </example> 1422 To distinguish timed from untimed <code>Object.wait</code>: 1423 <example> 1424 if (state & JVMTI_THREAD_STATE_IN_OBJECT_WAIT) { 1425 if (state & JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT) { 1426 printf("in Object.wait(long timeout)\n"); 1427 } else { 1428 printf("in Object.wait()\n"); 1429 } 1430 } 1431 </example> 1432 <p/> 1433 <b>Relationship to <code>java.lang.Thread.State</code></b> 1434 <p/> 1435 The thread state represented by <code>java.lang.Thread.State</code> 1436 returned from <code>java.lang.Thread.getState()</code> is a subset of the 1437 information returned from this function. 1438 The corresponding <code>java.lang.Thread.State</code> can be determined 1439 by using the provided conversion masks. 1440 For example, this returns the name of the <code>java.lang.Thread.State</code> thread state: 1441 <example> 1442 err = (*jvmti)->GetThreadState(jvmti, thread, &state); 1443 abortOnError(err); 1444 switch (state & JVMTI_JAVA_LANG_THREAD_STATE_MASK) { 1445 case JVMTI_JAVA_LANG_THREAD_STATE_NEW: 1446 return "NEW"; 1447 case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED: 1448 return "TERMINATED"; 1449 case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE: 1450 return "RUNNABLE"; 1451 case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED: 1452 return "BLOCKED"; 1453 case JVMTI_JAVA_LANG_THREAD_STATE_WAITING: 1454 return "WAITING"; 1455 case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING: 1456 return "TIMED_WAITING"; 1457 } 1458 </example> 1459 </description> 1460 <origin>new</origin> 1461 <capabilities> 1462 </capabilities> 1463 <parameters> 1464 <param id="thread"> 1465 <jthread null="current" started="maybe" impl="noconvert"/> 1466 <description> 1467 The thread to query. 1468 </description> 1469 </param> 1470 <param id="thread_state_ptr"> 1471 <outptr><jint/></outptr> 1472 <description> 1473 On return, points to state flags, 1474 as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>. 1475 </description> 1476 </param> 1477 </parameters> 1478 <errors> 1479 </errors> 1480 </function> 1481 1482 <function id="GetCurrentThread" phase="start" num="18" since="1.1"> 1483 <synopsis>Get Current Thread</synopsis> 1484 <description> 1485 Get the current thread. 1486 The current thread is the Java programming language thread which has called the function. 1487 <p/> 1488 Note that most <jvmti/> functions that take a thread 1489 as an argument will accept <code>NULL</code> to mean 1490 the current thread. 1491 </description> 1492 <origin>new</origin> 1493 <capabilities> 1494 </capabilities> 1495 <parameters> 1496 <param id="thread_ptr"> 1497 <outptr><jthread/></outptr> 1498 <description> 1499 On return, points to the current thread. 1500 </description> 1501 </param> 1502 </parameters> 1503 <errors> 1504 </errors> 1505 </function> 1506 1507 <function id="GetAllThreads" num="4"> 1508 <synopsis>Get All Threads</synopsis> 1509 <description> 1510 Get all live threads. 1511 The threads are Java programming language threads; 1512 that is, threads that are attached to the VM. 1513 A thread is live if <code>java.lang.Thread.isAlive()</code> 1514 would return <code>true</code>, that is, the thread has 1515 been started and has not yet died. 1516 The universe of threads is determined by the context of the <jvmti/> 1517 environment, which typically is all threads attached to the VM. 1518 Note that this includes <jvmti/> agent threads 1519 (see <functionlink id="RunAgentThread"/>). 1520 </description> 1521 <origin>jvmdi</origin> 1522 <capabilities> 1523 </capabilities> 1524 <parameters> 1525 <param id="threads_count_ptr"> 1526 <outptr><jint/></outptr> 1527 <description> 1528 On return, points to the number of running threads. 1529 </description> 1530 </param> 1531 <param id="threads_ptr"> 1532 <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf> 1533 <description> 1534 On return, points to an array of references, one 1535 for each running thread. 1536 </description> 1537 </param> 1538 </parameters> 1539 <errors> 1540 </errors> 1541 </function> 1542 1543 <function id="SuspendThread" num="5"> 1544 <synopsis>Suspend Thread</synopsis> 1545 <description> 1546 Suspend the specified thread. If the calling thread is specified, 1547 this function will not return until some other thread calls 1548 <functionlink id="ResumeThread"></functionlink>. 1549 If the thread is currently suspended, this function 1550 does nothing and returns an error. 1551 </description> 1552 <origin>jvmdi</origin> 1553 <capabilities> 1554 <required id="can_suspend"></required> 1555 </capabilities> 1556 <parameters> 1557 <param id="thread"> 1558 <jthread null="current"/> 1559 <description> 1560 The thread to suspend. 1561 </description> 1562 </param> 1563 </parameters> 1564 <errors> 1565 <error id="JVMTI_ERROR_THREAD_SUSPENDED"> 1566 Thread already suspended. 1567 </error> 1568 </errors> 1569 </function> 1570 1571 <elide> 1572 <function id="SuspendAllThreads" num="101"> 1573 <synopsis>Suspend All Threads</synopsis> 1574 <description> 1575 <issue> 1576 There has been no explicit call for this function, and it will 1577 thus be removed if there is no interest. 1578 </issue> 1579 Suspend all live threads except: 1580 <ul> 1581 <li>already suspended threads</li> 1582 <li>those listed in <paramlink id="except_list"></paramlink></li> 1583 <li>certain system (non application) threads, as determined 1584 by the VM implementation</li> 1585 </ul> 1586 The threads are Java programming language threads; 1587 native threads which are not attached to the VM are not 1588 Java programming language threads. 1589 A thread is live if <code>java.lang.Thread.isAlive()</code> 1590 would return <code>true</code>, that is, the thread has 1591 been started and has not yet died. 1592 The universe of threads is determined 1593 by the context of the <jvmti/> 1594 environment, which, typically, is all threads attached to the VM, 1595 except critical VM internal threads and <jvmti/> agent threads 1596 (see <functionlink id="RunAgentThread"/>). 1597 <p/> 1598 If the calling thread is specified, 1599 all other threads are suspended first then the caller thread is suspended - 1600 this function will not return until some other thread calls 1601 <functionlink id="ResumeThread"></functionlink>. 1602 <p/> 1603 The list of actually 1604 suspended threads is returned in 1605 <paramlink id="suspended_list_ptr"></paramlink>. 1606 Suspension is as defined in <functionlink id="SuspendThread"></functionlink>. 1607 <functionlink id="ResumeThreadList"></functionlink> 1608 can be used to resume the suspended threads. 1609 </description> 1610 <origin>new</origin> 1611 <capabilities> 1612 <required id="can_suspend"></required> 1613 </capabilities> 1614 <parameters> 1615 <param id="except_count"> 1616 <jint min="0"/> 1617 <description> 1618 The number of threads in the list of threads not to be suspended. 1619 </description> 1620 </param> 1621 <param id="except_list"> 1622 <inbuf incount="except_count"> 1623 <jthread/> 1624 <nullok>not an error if <code>except_count == 0</code></nullok> 1625 </inbuf> 1626 <description> 1627 The list of threads not to be suspended. 1628 </description> 1629 </param> 1630 <param id="suspended_count_ptr"> 1631 <outptr><jint/></outptr> 1632 <description> 1633 On return, points to the number of threads suspended by this call. 1634 </description> 1635 </param> 1636 <param id="suspended_list_ptr"> 1637 <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf> 1638 <description> 1639 On return, points to an array of references, one 1640 for each thread suspended. 1641 </description> 1642 </param> 1643 </parameters> 1644 <errors> 1645 <error id="JVMTI_ERROR_INVALID_THREAD"> 1646 A thread in <paramlink id="except_list"></paramlink> was invalid. 1647 </error> 1648 <error id="JVMTI_ERROR_NULL_POINTER"> 1649 Both <paramlink id="except_list"></paramlink> was <code>NULL</code> 1650 and <paramlink id="except_count"></paramlink> was non-zero. 1651 </error> 1652 </errors> 1653 </function> 1654 </elide> 1655 1656 <function id="SuspendThreadList" num="92"> 1657 <synopsis>Suspend Thread List</synopsis> 1658 <description> 1659 Suspend the <paramlink id="request_count"></paramlink> 1660 threads specified in the 1661 <paramlink id="request_list"></paramlink> array. 1662 Threads may be resumed with 1663 <functionlink id="ResumeThreadList"></functionlink> or 1664 <functionlink id="ResumeThread"></functionlink>. 1665 If the calling thread is specified in the 1666 <paramlink id="request_list"></paramlink> array, this function will 1667 not return until some other thread resumes it. 1668 Errors encountered in the suspension of a thread 1669 are returned in the <paramlink id="results"></paramlink> 1670 array, <b>not</b> in the return value of this function. 1671 Threads that are currently suspended do not change state. 1672 </description> 1673 <origin>jvmdi</origin> 1674 <capabilities> 1675 <required id="can_suspend"></required> 1676 </capabilities> 1677 <parameters> 1678 <param id="request_count"> 1679 <jint min="0"/> 1680 <description> 1681 The number of threads to suspend. 1682 </description> 1683 </param> 1684 <param id="request_list"> 1685 <inbuf incount="request_count"><jthread/></inbuf> 1686 <description> 1687 The list of threads to suspend. 1688 </description> 1689 </param> 1690 <param id="results"> 1691 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> 1692 <description> 1693 An agent supplied array of 1694 <paramlink id="request_count"></paramlink> elements. 1695 On return, filled with the error code for 1696 the suspend of the corresponding thread. 1697 The error code will be 1698 <errorlink id="JVMTI_ERROR_NONE"></errorlink> 1699 if the thread was suspended by this call. 1700 Possible error codes are those specified 1701 for <functionlink id="SuspendThread"></functionlink>. 1702 </description> 1703 </param> 1704 </parameters> 1705 <errors> 1706 </errors> 1707 </function> 1708 1709 <function id="ResumeThread" num="6"> 1710 <synopsis>Resume Thread</synopsis> 1711 <description> 1712 Resume a suspended thread. 1713 Any threads currently suspended through 1714 a <jvmti/> suspend function (eg. 1715 <functionlink id="SuspendThread"></functionlink>) 1716 or <code>java.lang.Thread.suspend()</code> 1717 will resume execution; 1718 all other threads are unaffected. 1719 </description> 1720 <origin>jvmdi</origin> 1721 <capabilities> 1722 <required id="can_suspend"></required> 1723 </capabilities> 1724 <parameters> 1725 <param id="thread"> 1726 <jthread/> 1727 <description> 1728 The thread to resume. 1729 </description> 1730 </param> 1731 </parameters> 1732 <errors> 1733 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> 1734 Thread was not suspended. 1735 </error> 1736 <error id="JVMTI_ERROR_INVALID_TYPESTATE"> 1737 The state of the thread has been modified, and is now inconsistent. 1738 </error> 1739 </errors> 1740 </function> 1741 1742 <function id="ResumeThreadList" num="93"> 1743 <synopsis>Resume Thread List</synopsis> 1744 <description> 1745 Resume the <paramlink id="request_count"></paramlink> 1746 threads specified in the 1747 <paramlink id="request_list"></paramlink> array. 1748 Any thread suspended through 1749 a <jvmti/> suspend function (eg. 1750 <functionlink id="SuspendThreadList"></functionlink>) 1751 or <code>java.lang.Thread.suspend()</code> 1752 will resume execution. 1753 </description> 1754 <origin>jvmdi</origin> 1755 <capabilities> 1756 <required id="can_suspend"></required> 1757 </capabilities> 1758 <parameters> 1759 <param id="request_count"> 1760 <jint min="0"/> 1761 <description> 1762 The number of threads to resume. 1763 </description> 1764 </param> 1765 <param id="request_list"> 1766 <inbuf incount="request_count"><jthread/></inbuf> 1767 <description> 1768 The threads to resume. 1769 </description> 1770 </param> 1771 <param id="results"> 1772 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> 1773 <description> 1774 An agent supplied array of 1775 <paramlink id="request_count"></paramlink> elements. 1776 On return, filled with the error code for 1777 the resume of the corresponding thread. 1778 The error code will be 1779 <errorlink id="JVMTI_ERROR_NONE"></errorlink> 1780 if the thread was suspended by this call. 1781 Possible error codes are those specified 1782 for <functionlink id="ResumeThread"></functionlink>. 1783 </description> 1784 </param> 1785 </parameters> 1786 <errors> 1787 </errors> 1788 </function> 1789 1790 <function id="StopThread" num="7"> 1791 <synopsis>Stop Thread</synopsis> 1792 <description> 1793 Send the specified asynchronous exception to the specified thread 1794 (similar to <code>java.lang.Thread.stop</code>). 1795 Normally, this function is used to kill the specified thread with an 1796 instance of the exception <code>ThreadDeath</code>. 1797 </description> 1798 <origin>jvmdi</origin> 1799 <capabilities> 1800 <required id="can_signal_thread"></required> 1801 </capabilities> 1802 <parameters> 1803 <param id="thread"> 1804 <jthread/> 1805 <description> 1806 The thread to stop. 1807 </description> 1808 </param> 1809 <param id="exception"> 1810 <jobject/> 1811 <description> 1812 The asynchronous exception object. 1813 </description> 1814 </param> 1815 </parameters> 1816 <errors> 1817 </errors> 1818 </function> 1819 1820 <function id="InterruptThread" num="8"> 1821 <synopsis>Interrupt Thread</synopsis> 1822 <description> 1823 Interrupt the specified thread 1824 (similar to <code>java.lang.Thread.interrupt</code>). 1825 </description> 1826 <origin>jvmdi</origin> 1827 <capabilities> 1828 <required id="can_signal_thread"></required> 1829 </capabilities> 1830 <parameters> 1831 <param id="thread"> 1832 <jthread impl="noconvert"/> 1833 <description> 1834 The thread to interrupt. 1835 </description> 1836 </param> 1837 </parameters> 1838 <errors> 1839 </errors> 1840 </function> 1841 1842 <function id="GetThreadInfo" num="9"> 1843 <synopsis>Get Thread Info</synopsis> 1844 <typedef id="jvmtiThreadInfo" label="Thread information structure"> 1845 <field id="name"> 1846 <allocfieldbuf><char/></allocfieldbuf> 1847 <description> 1848 The thread name, encoded as a 1849 <internallink id="mUTF">modified UTF-8</internallink> string. 1850 </description> 1851 </field> 1852 <field id="priority"> 1853 <jint/> 1854 <description> 1855 The thread priority. See the thread priority constants: 1856 <datalink id="jvmtiThreadPriority"></datalink>. 1857 </description> 1858 </field> 1859 <field id="is_daemon"> 1860 <jboolean/> 1861 <description> 1862 Is this a daemon thread? 1863 </description> 1864 </field> 1865 <field id="thread_group"> 1866 <jthreadGroup/> 1867 <description> 1868 The thread group to which this thread belongs. 1869 <code>NULL</code> if the thread has died. 1870 </description> 1871 </field> 1872 <field id="context_class_loader"> 1873 <jobject/> 1874 <description> 1875 The context class loader associated with this thread. 1876 </description> 1877 </field> 1878 </typedef> 1879 <description> 1880 Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure 1881 are filled in with details of the specified thread. 1882 </description> 1883 <origin>jvmdi</origin> 1884 <capabilities> 1885 </capabilities> 1886 <parameters> 1887 <param id="thread"> 1888 <jthread null="current" impl="noconvert" started="maybe"/> 1889 <description> 1890 The thread to query. 1891 </description> 1892 </param> 1893 <param id="info_ptr"> 1894 <outptr><struct>jvmtiThreadInfo</struct></outptr> 1895 <description> 1896 On return, filled with information describing the specified thread. 1897 </description> 1898 </param> 1899 </parameters> 1900 <errors> 1901 </errors> 1902 </function> 1903 1904 <function id="GetOwnedMonitorInfo" num="10"> 1905 <synopsis>Get Owned Monitor Info</synopsis> 1906 <description> 1907 Get information about the monitors owned by the 1908 specified thread. 1909 </description> 1910 <origin>jvmdiClone</origin> 1911 <capabilities> 1912 <required id="can_get_owned_monitor_info"></required> 1913 </capabilities> 1914 <parameters> 1915 <param id="thread"> 1916 <jthread null="current"/> 1917 <description> 1918 The thread to query. 1919 </description> 1920 </param> 1921 <param id="owned_monitor_count_ptr"> 1922 <outptr><jint/></outptr> 1923 <description> 1924 The number of monitors returned. 1925 </description> 1926 </param> 1927 <param id="owned_monitors_ptr"> 1928 <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf> 1929 <description> 1930 The array of owned monitors. 1931 </description> 1932 </param> 1933 </parameters> 1934 <errors> 1935 </errors> 1936 </function> 1937 1938 <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1"> 1939 <synopsis>Get Owned Monitor Stack Depth Info</synopsis> 1940 <typedef id="jvmtiMonitorStackDepthInfo" 1941 label="Monitor stack depth information structure"> 1942 <field id="monitor"> 1943 <jobject/> 1944 <description> 1945 The owned monitor. 1946 </description> 1947 </field> 1948 <field id="stack_depth"> 1949 <jint/> 1950 <description> 1951 The stack depth. Corresponds to the stack depth used in the 1952 <internallink id="stack">Stack Frame functions</internallink>. 1953 That is, zero is the current frame, one is the frame which 1954 called the current frame. And it is negative one if the 1955 implementation cannot determine the stack depth (e.g., for 1956 monitors acquired by JNI <code>MonitorEnter</code>). 1957 </description> 1958 </field> 1959 </typedef> 1960 <description> 1961 Get information about the monitors owned by the 1962 specified thread and the depth of the stack frame which locked them. 1963 </description> 1964 <origin>new</origin> 1965 <capabilities> 1966 <required id="can_get_owned_monitor_stack_depth_info"></required> 1967 </capabilities> 1968 <parameters> 1969 <param id="thread"> 1970 <jthread null="current"/> 1971 <description> 1972 The thread to query. 1973 </description> 1974 </param> 1975 <param id="monitor_info_count_ptr"> 1976 <outptr><jint/></outptr> 1977 <description> 1978 The number of monitors returned. 1979 </description> 1980 </param> 1981 <param id="monitor_info_ptr"> 1982 <allocbuf outcount="monitor_info_count_ptr"> 1983 <struct>jvmtiMonitorStackDepthInfo</struct> 1984 </allocbuf> 1985 <description> 1986 The array of owned monitor depth information. 1987 </description> 1988 </param> 1989 </parameters> 1990 <errors> 1991 </errors> 1992 </function> 1993 1994 <function id="GetCurrentContendedMonitor" num="11"> 1995 <synopsis>Get Current Contended Monitor</synopsis> 1996 <description> 1997 Get the object, if any, whose monitor the specified thread is waiting to 1998 enter or waiting to regain through <code>java.lang.Object.wait</code>. 1999 </description> 2000 <origin>jvmdi</origin> 2001 <capabilities> 2002 <required id="can_get_current_contended_monitor"></required> 2003 </capabilities> 2004 <parameters> 2005 <param id="thread"> 2006 <jthread null="current"/> 2007 <description> 2008 The thread to query. 2009 </description> 2010 </param> 2011 <param id="monitor_ptr"> 2012 <outptr><jobject/></outptr> 2013 <description> 2014 On return, filled with the current contended monitor, or 2015 NULL if there is none. 2016 </description> 2017 </param> 2018 </parameters> 2019 <errors> 2020 </errors> 2021 </function> 2022 2023 <callback id="jvmtiStartFunction"> 2024 <void/> 2025 <synopsis>Agent Start Function</synopsis> 2026 <description> 2027 Agent supplied callback function. 2028 This function is the entry point for an agent thread 2029 started with 2030 <functionlink id="RunAgentThread"></functionlink>. 2031 </description> 2032 <parameters> 2033 <param id="jvmti_env"> 2034 <outptr> 2035 <struct>jvmtiEnv</struct> 2036 </outptr> 2037 <description> 2038 The <jvmti/> environment. 2039 </description> 2040 </param> 2041 <param id="jni_env"> 2042 <outptr> 2043 <struct>JNIEnv</struct> 2044 </outptr> 2045 <description> 2046 The JNI environment. 2047 </description> 2048 </param> 2049 <param id="arg"> 2050 <outptr> 2051 <void/> 2052 </outptr> 2053 <description> 2054 The <code>arg</code> parameter passed to 2055 <functionlink id="RunAgentThread"></functionlink>. 2056 </description> 2057 </param> 2058 </parameters> 2059 </callback> 2060 2061 <function id="RunAgentThread" num="12"> 2062 <synopsis>Run Agent Thread</synopsis> 2063 <description> 2064 Starts the execution of an agent thread. with the specified native function. 2065 The parameter <paramlink id="arg"></paramlink> is forwarded on to the 2066 <functionlink id="jvmtiStartFunction">start function</functionlink> 2067 (specified with <paramlink id="proc"></paramlink>) as its single argument. 2068 This function allows the creation of agent threads 2069 for handling communication with another process or for handling events 2070 without the need to load a special subclass of <code>java.lang.Thread</code> or 2071 implementer of <code>java.lang.Runnable</code>. 2072 Instead, the created thread can run entirely in native code. 2073 However, the created thread does require a newly created instance 2074 of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to 2075 which it will be associated. 2076 The thread object can be created with JNI calls. 2077 <p/> 2078 The following common thread priorities are provided for your convenience: 2079 <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const"> 2080 <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1"> 2081 Minimum possible thread priority 2082 </constant> 2083 <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5"> 2084 Normal thread priority 2085 </constant> 2086 <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10"> 2087 Maximum possible thread priority 2088 </constant> 2089 </constants> 2090 <p/> 2091 The new thread is started as a daemon thread with the specified 2092 <paramlink id="priority"></paramlink>. 2093 If enabled, a <eventlink id="ThreadStart"/> event will be sent. 2094 <p/> 2095 Since the thread has been started, the thread will be live when this function 2096 returns, unless the thread has died immediately. 2097 <p/> 2098 The thread group of the thread is ignored -- specifically, the thread is not 2099 added to the thread group and the thread is not seen on queries of the thread 2100 group at either the Java programming language or <jvmti/> levels. 2101 <p/> 2102 The thread is not visible to Java programming language queries but is 2103 included in <jvmti/> queries (for example, 2104 <functionlink id="GetAllThreads"/> and 2105 <functionlink id="GetAllStackTraces"/>). 2106 <p/> 2107 Upon execution of <code>proc</code>, the new thread will be attached to the 2108 VM--see the JNI documentation on 2109 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#wp1060" 2110 >Attaching to the VM</externallink>. 2111 </description> 2112 <origin>jvmdiClone</origin> 2113 <capabilities> 2114 </capabilities> 2115 <parameters> 2116 <param id="thread"> 2117 <jthread impl="noconvert" started="no"/> 2118 <description> 2119 The thread to run. 2120 </description> 2121 </param> 2122 <param id="proc"> 2123 <ptrtype> 2124 <struct>jvmtiStartFunction</struct> 2125 </ptrtype> 2126 <description> 2127 The start function. 2128 </description> 2129 </param> 2130 <param id="arg"> 2131 <inbuf> 2132 <void/> 2133 <nullok><code>NULL</code> is passed to the start function</nullok> 2134 </inbuf> 2135 <description> 2136 The argument to the start function. 2137 </description> 2138 </param> 2139 <param id="priority"> 2140 <jint/> 2141 <description> 2142 The priority of the started thread. Any thread 2143 priority allowed by <code>java.lang.Thread.setPriority</code> can be used including 2144 those in <datalink id="jvmtiThreadPriority"></datalink>. 2145 </description> 2146 </param> 2147 </parameters> 2148 <errors> 2149 <error id="JVMTI_ERROR_INVALID_PRIORITY"> 2150 <paramlink id="priority"/> is less than 2151 <datalink id="JVMTI_THREAD_MIN_PRIORITY"/> 2152 or greater than 2153 <datalink id="JVMTI_THREAD_MAX_PRIORITY"/> 2154 </error> 2155 </errors> 2156 </function> 2157 2158 <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103"> 2159 <synopsis>Set Thread Local Storage</synopsis> 2160 <description> 2161 The VM stores a pointer value associated with each environment-thread 2162 pair. This pointer value is called <i>thread-local storage</i>. 2163 This value is <code>NULL</code> unless set with this function. 2164 Agents can allocate memory in which they store thread specific 2165 information. By setting thread-local storage it can then be 2166 accessed with 2167 <functionlink id="GetThreadLocalStorage"></functionlink>. 2168 <p/> 2169 This function is called by the agent to set the value of the <jvmti/> 2170 thread-local storage. <jvmti/> supplies to the agent a pointer-size 2171 thread-local storage that can be used to record per-thread 2172 information. 2173 </description> 2174 <origin>jvmpi</origin> 2175 <capabilities> 2176 </capabilities> 2177 <parameters> 2178 <param id="thread"> 2179 <jthread null="current"/> 2180 <description> 2181 Store to this thread. 2182 </description> 2183 </param> 2184 <param id="data"> 2185 <inbuf> 2186 <void/> 2187 <nullok>value is set to <code>NULL</code></nullok> 2188 </inbuf> 2189 <description> 2190 The value to be entered into the thread-local storage. 2191 </description> 2192 </param> 2193 </parameters> 2194 <errors> 2195 </errors> 2196 </function> 2197 2198 <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102"> 2199 <synopsis>Get Thread Local Storage</synopsis> 2200 <description> 2201 Called by the agent to get the value of the <jvmti/> thread-local 2202 storage. 2203 </description> 2204 <origin>jvmpi</origin> 2205 <capabilities> 2206 </capabilities> 2207 <parameters> 2208 <param id="thread"> 2209 <jthread null="current" impl="noconvert"/> 2210 <description> 2211 Retrieve from this thread. 2212 </description> 2213 </param> 2214 <param id="data_ptr"> 2215 <agentbuf><void/></agentbuf> 2216 <description> 2217 Pointer through which the value of the thread local 2218 storage is returned. 2219 If thread-local storage has not been set with 2220 <functionlink id="SetThreadLocalStorage"></functionlink> the returned 2221 pointer is <code>NULL</code>. 2222 </description> 2223 </param> 2224 </parameters> 2225 <errors> 2226 </errors> 2227 </function> 2228 2229 </category> 2230 2231 <category id="thread_groups" label="Thread Group"> 2232 <intro> 2233 </intro> 2234 2235 <function id="GetTopThreadGroups" num="13"> 2236 <synopsis>Get Top Thread Groups</synopsis> 2237 <description> 2238 Return all top-level (parentless) thread groups in the VM. 2239 </description> 2240 <origin>jvmdi</origin> 2241 <capabilities> 2242 </capabilities> 2243 <parameters> 2244 <param id="group_count_ptr"> 2245 <outptr><jint/></outptr> 2246 <description> 2247 On return, points to the number of top-level thread groups. 2248 </description> 2249 </param> 2250 <param id="groups_ptr"> 2251 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> 2252 <description> 2253 On return, refers to a pointer to the top-level thread group array. 2254 </description> 2255 </param> 2256 </parameters> 2257 <errors> 2258 </errors> 2259 </function> 2260 2261 <function id="GetThreadGroupInfo" num="14"> 2262 <synopsis>Get Thread Group Info</synopsis> 2263 <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure"> 2264 <field id="parent"> 2265 <jthreadGroup/> 2266 <description> 2267 The parent thread group. 2268 </description> 2269 </field> 2270 <field id="name"> 2271 <allocfieldbuf><char/></allocfieldbuf> 2272 <description> 2273 The thread group's name, encoded as a 2274 <internallink id="mUTF">modified UTF-8</internallink> string. 2275 </description> 2276 </field> 2277 <field id="max_priority"> 2278 <jint/> 2279 <description> 2280 The maximum priority for this thread group. 2281 </description> 2282 </field> 2283 <field id="is_daemon"> 2284 <jboolean/> 2285 <description> 2286 Is this a daemon thread group? 2287 </description> 2288 </field> 2289 </typedef> 2290 <description> 2291 Get information about the thread group. The fields of the 2292 <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure 2293 are filled in with details of the specified thread group. 2294 </description> 2295 <origin>jvmdi</origin> 2296 <capabilities> 2297 </capabilities> 2298 <parameters> 2299 <param id="group"> 2300 <jthreadGroup/> 2301 <description> 2302 The thread group to query. 2303 </description> 2304 </param> 2305 <param id="info_ptr"> 2306 <outptr><struct>jvmtiThreadGroupInfo</struct></outptr> 2307 <description> 2308 On return, filled with information describing the specified 2309 thread group. 2310 </description> 2311 </param> 2312 </parameters> 2313 <errors> 2314 </errors> 2315 </function> 2316 2317 <function id="GetThreadGroupChildren" num="15"> 2318 <synopsis>Get Thread Group Children</synopsis> 2319 <description> 2320 Get the live threads and active subgroups in this thread group. 2321 </description> 2322 <origin>jvmdi</origin> 2323 <capabilities> 2324 </capabilities> 2325 <parameters> 2326 <param id="group"> 2327 <jthreadGroup/> 2328 <description> 2329 The group to query. 2330 </description> 2331 </param> 2332 <param id="thread_count_ptr"> 2333 <outptr><jint/></outptr> 2334 <description> 2335 On return, points to the number of live threads in this thread group. 2336 </description> 2337 </param> 2338 <param id="threads_ptr"> 2339 <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf> 2340 <description> 2341 On return, points to an array of the live threads in this thread group. 2342 </description> 2343 </param> 2344 <param id="group_count_ptr"> 2345 <outptr><jint/></outptr> 2346 <description> 2347 On return, points to the number of active child thread groups 2348 </description> 2349 </param> 2350 <param id="groups_ptr"> 2351 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> 2352 <description> 2353 On return, points to an array of the active child thread groups. 2354 </description> 2355 </param> 2356 </parameters> 2357 <errors> 2358 </errors> 2359 </function> 2360 </category> 2361 2362 <category id="stack" label="Stack Frame"> 2363 <intro> 2364 These functions provide information about the stack of a thread. 2365 Stack frames are referenced by depth. 2366 The frame at depth zero is the current frame. 2367 <p/> 2368 Stack frames are as described in 2369 <vmspec chapter="3.6"/>, 2370 That is, they correspond to method 2371 invocations (including native methods) but do not correspond to platform native or 2372 VM internal frames. 2373 <p/> 2374 A <jvmti/> implementation may use method invocations to launch a thread and 2375 the corresponding frames may be included in the stack as presented by these functions -- 2376 that is, there may be frames shown 2377 deeper than <code>main()</code> and <code>run()</code>. 2378 However this presentation must be consistent across all <jvmti/> functionality which 2379 uses stack frames or stack depth. 2380 </intro> 2381 2382 <typedef id="jvmtiFrameInfo" label="Stack frame information structure"> 2383 <description> 2384 Information about a stack frame is returned in this structure. 2385 </description> 2386 <field id="method"> 2387 <jmethodID/> 2388 <description> 2389 The method executing in this frame. 2390 </description> 2391 </field> 2392 <field id="location"> 2393 <jlocation/> 2394 <description> 2395 The index of the instruction executing in this frame. 2396 <code>-1</code> if the frame is executing a native method. 2397 </description> 2398 </field> 2399 </typedef> 2400 2401 <typedef id="jvmtiStackInfo" label="Stack information structure"> 2402 <description> 2403 Information about a set of stack frames is returned in this structure. 2404 </description> 2405 <field id="thread"> 2406 <jthread/> 2407 <description> 2408 On return, the thread traced. 2409 </description> 2410 </field> 2411 <field id="state"> 2412 <jint/> 2413 <description> 2414 On return, the thread state. See <functionlink id="GetThreadState"></functionlink>. 2415 </description> 2416 </field> 2417 <field id="frame_buffer"> 2418 <outbuf incount="max_frame_count"> 2419 <struct>jvmtiFrameInfo</struct> 2420 </outbuf> 2421 <description> 2422 On return, this agent allocated buffer is filled 2423 with stack frame information. 2424 </description> 2425 </field> 2426 <field id="frame_count"> 2427 <jint/> 2428 <description> 2429 On return, the number of records filled into 2430 <code>frame_buffer</code>. 2431 This will be 2432 min(<code>max_frame_count</code>, <i>stackDepth</i>). 2433 </description> 2434 </field> 2435 </typedef> 2436 2437 <function id="GetStackTrace" num="104"> 2438 <synopsis>Get Stack Trace</synopsis> 2439 <description> 2440 Get information about the stack of a thread. 2441 If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack, 2442 the <paramlink id="max_frame_count"></paramlink> topmost frames are returned, 2443 otherwise the entire stack is returned. 2444 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. 2445 <p/> 2446 The following example causes up to five of the topmost frames 2447 to be returned and (if there are any frames) the currently 2448 executing method name to be printed. 2449 <example> 2450jvmtiFrameInfo frames[5]; 2451jint count; 2452jvmtiError err; 2453 2454err = (*jvmti)->GetStackTrace(jvmti, aThread, 0, 5, 2455 frames, &count); 2456if (err == JVMTI_ERROR_NONE && count >= 1) { 2457 char *methodName; 2458 err = (*jvmti)->GetMethodName(jvmti, frames[0].method, 2459 &methodName, NULL, NULL); 2460 if (err == JVMTI_ERROR_NONE) { 2461 printf("Executing method: %s", methodName); 2462 } 2463} 2464 </example> 2465 <todo> 2466 check example code. 2467 </todo> 2468 <p/> 2469 The <paramlink id="thread"></paramlink> need not be suspended 2470 to call this function. 2471 <p/> 2472 The <functionlink id="GetLineNumberTable"></functionlink> 2473 function can be used to map locations to line numbers. Note that 2474 this mapping can be done lazily. 2475 </description> 2476 <origin>jvmpi</origin> 2477 <capabilities> 2478 </capabilities> 2479 <parameters> 2480 <param id="thread"> 2481 <jthread null="current"/> 2482 <description> 2483 Fetch the stack trace of this thread. 2484 </description> 2485 </param> 2486 <param id="start_depth"> 2487 <jint/> 2488 <description> 2489 Begin retrieving frames at this depth. 2490 If non-negative, count from the current frame, 2491 the first frame retrieved is at depth <code>start_depth</code>. 2492 For example, if zero, start from the current frame; if one, start from the 2493 caller of the current frame; if two, start from the caller of the 2494 caller of the current frame; and so on. 2495 If negative, count from below the oldest frame, 2496 the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>, 2497 where <i>stackDepth</i> is the count of frames on the stack. 2498 For example, if negative one, only the oldest frame is retrieved; 2499 if negative two, start from the frame called by the oldest frame. 2500 </description> 2501 </param> 2502 <param id="max_frame_count"> 2503 <jint min="0"/> 2504 <description> 2505 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. 2506 </description> 2507 </param> 2508 <param id="frame_buffer"> 2509 <outbuf incount="max_frame_count" outcount="count_ptr"> 2510 <struct>jvmtiFrameInfo</struct> 2511 </outbuf> 2512 <description> 2513 On return, this agent allocated buffer is filled 2514 with stack frame information. 2515 </description> 2516 </param> 2517 <param id="count_ptr"> 2518 <outptr><jint/></outptr> 2519 <description> 2520 On return, points to the number of records filled in. 2521 For non-negative <code>start_depth</code>, this will be 2522 min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>). 2523 For negative <code>start_depth</code>, this will be 2524 min(<code>max_frame_count</code>, <code>-start_depth</code>). 2525 </description> 2526 </param> 2527 </parameters> 2528 <errors> 2529 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 2530 <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>. 2531 Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>. 2532 </error> 2533 </errors> 2534 </function> 2535 2536 2537 <function id="GetAllStackTraces" num="100"> 2538 <synopsis>Get All Stack Traces</synopsis> 2539 <description> 2540 Get information about the stacks of all live threads 2541 (including <internallink id="RunAgentThread">agent threads</internallink>). 2542 If <paramlink id="max_frame_count"/> is less than the depth of a stack, 2543 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, 2544 otherwise the entire stack is returned. 2545 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. 2546 <p/> 2547 All stacks are collected simultaneously, that is, no changes will occur to the 2548 thread state or stacks between the sampling of one thread and the next. 2549 The threads need not be suspended. 2550 2551 <example> 2552jvmtiStackInfo *stack_info; 2553jint thread_count; 2554int ti; 2555jvmtiError err; 2556 2557err = (*jvmti)->GetAllStackTraces(jvmti, MAX_FRAMES, &stack_info, &thread_count); 2558if (err != JVMTI_ERROR_NONE) { 2559 ... 2560} 2561for (ti = 0; ti < thread_count; ++ti) { 2562 jvmtiStackInfo *infop = &stack_info[ti]; 2563 jthread thread = infop->thread; 2564 jint state = infop->state; 2565 jvmtiFrameInfo *frames = infop->frame_buffer; 2566 int fi; 2567 2568 myThreadAndStatePrinter(thread, state); 2569 for (fi = 0; fi < infop->frame_count; fi++) { 2570 myFramePrinter(frames[fi].method, frames[fi].location); 2571 } 2572} 2573/* this one Deallocate call frees all data allocated by GetAllStackTraces */ 2574err = (*jvmti)->Deallocate(jvmti, stack_info); 2575 </example> 2576 <todo> 2577 check example code. 2578 </todo> 2579 2580 </description> 2581 <origin>new</origin> 2582 <capabilities> 2583 </capabilities> 2584 <parameters> 2585 <param id="max_frame_count"> 2586 <jint min="0"/> 2587 <description> 2588 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. 2589 </description> 2590 </param> 2591 <param id="stack_info_ptr"> 2592 <allocbuf> 2593 <struct>jvmtiStackInfo</struct> 2594 </allocbuf> 2595 <description> 2596 On return, this buffer is filled 2597 with stack information for each thread. 2598 The number of <datalink id="jvmtiStackInfo"/> records is determined 2599 by <paramlink id="thread_count_ptr"/>. 2600 <p/> 2601 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> 2602 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. 2603 These buffers must not be separately deallocated. 2604 </description> 2605 </param> 2606 <param id="thread_count_ptr"> 2607 <outptr><jint/></outptr> 2608 <description> 2609 The number of threads traced. 2610 </description> 2611 </param> 2612 </parameters> 2613 <errors> 2614 </errors> 2615 </function> 2616 2617 <function id="GetThreadListStackTraces" num="101"> 2618 <synopsis>Get Thread List Stack Traces</synopsis> 2619 <description> 2620 Get information about the stacks of the supplied threads. 2621 If <paramlink id="max_frame_count"/> is less than the depth of a stack, 2622 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, 2623 otherwise the entire stack is returned. 2624 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. 2625 <p/> 2626 All stacks are collected simultaneously, that is, no changes will occur to the 2627 thread state or stacks between the sampling one thread and the next. 2628 The threads need not be suspended. 2629 <p/> 2630 If a thread has not yet started or terminates before the stack information is collected, 2631 a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero) 2632 will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked. 2633 <p/> 2634 See the example for the similar function 2635 <functionlink id="GetAllStackTraces"/>. 2636 </description> 2637 <origin>new</origin> 2638 <capabilities> 2639 </capabilities> 2640 <parameters> 2641 <param id="thread_count"> 2642 <jint min="0"/> 2643 <description> 2644 The number of threads to trace. 2645 </description> 2646 </param> 2647 <param id="thread_list"> 2648 <inbuf incount="thread_count"><jthread/></inbuf> 2649 <description> 2650 The list of threads to trace. 2651 </description> 2652 </param> 2653 <param id="max_frame_count"> 2654 <jint min="0"/> 2655 <description> 2656 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. 2657 </description> 2658 </param> 2659 <param id="stack_info_ptr"> 2660 <allocbuf outcount="thread_count"> 2661 <struct>jvmtiStackInfo</struct> 2662 </allocbuf> 2663 <description> 2664 On return, this buffer is filled 2665 with stack information for each thread. 2666 The number of <datalink id="jvmtiStackInfo"/> records is determined 2667 by <paramlink id="thread_count"/>. 2668 <p/> 2669 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> 2670 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. 2671 These buffers must not be separately deallocated. 2672 </description> 2673 </param> 2674 </parameters> 2675 <errors> 2676 <error id="JVMTI_ERROR_INVALID_THREAD"> 2677 An element in <paramlink id="thread_list"/> is not a thread object. 2678 </error> 2679 </errors> 2680 </function> 2681 2682 <elide> 2683 <function id="AsyncGetStackTrace" num="1000"> 2684 <synopsis>Get Stack Trace--Asynchronous</synopsis> 2685 <description> 2686 Get information about the entire stack of a thread (or a sub-section of it). 2687 This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink> 2688 and is reentrant and safe to call 2689 from asynchronous signal handlers. 2690 The stack trace is returned only for the calling thread. 2691 <p/> 2692 The <functionlink id="GetLineNumberTable"></functionlink> 2693 function can be used to map locations to line numbers. Note that 2694 this mapping can be done lazily. 2695 </description> 2696 <origin>jvmpi</origin> 2697 <capabilities> 2698 <required id="can_get_async_stack_trace"></required> 2699 <capability id="can_show_JVM_spec_async_frames"> 2700 If <code>false</code>, 2701 <paramlink id="use_java_stack"></paramlink> 2702 must be <code>false</code>. 2703 </capability> 2704 </capabilities> 2705 <parameters> 2706 <param id="use_java_stack"> 2707 <jboolean/> 2708 <description> 2709 Return the stack showing <vmspec/> 2710 model of the stack; 2711 otherwise, show the internal representation of the stack with 2712 inlined and optimized methods missing. If the virtual machine 2713 is using the <i>Java Virtual Machine Specification</i> stack model 2714 internally, this flag is ignored. 2715 </description> 2716 </param> 2717 <param id="max_count"> 2718 <jint min="0"/> 2719 <description> 2720 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. 2721 Retrieve this many unless the stack depth is less than <code>max_count</code>. 2722 </description> 2723 </param> 2724 <param id="frame_buffer"> 2725 <outbuf incount="max_count" outcount="count_ptr"> 2726 <struct>jvmtiFrameInfo</struct> 2727 <nullok>this information is not returned</nullok> 2728 </outbuf> 2729 <description> 2730 The agent passes in a buffer 2731 large enough to hold <code>max_count</code> records of 2732 <datalink id="jvmtiFrameInfo"></datalink>. This buffer must be 2733 pre-allocated by the agent. 2734 </description> 2735 </param> 2736 <param id="count_ptr"> 2737 <outptr><jint/></outptr> 2738 <description> 2739 On return, points to the number of records filled in.. 2740 </description> 2741 </param> 2742 </parameters> 2743 <errors> 2744 <error id="JVMTI_ERROR_UNATTACHED_THREAD"> 2745 The thread being used to call this function is not attached 2746 to the virtual machine. Calls must be made from attached threads. 2747 </error> 2748 </errors> 2749 </function> 2750 </elide> 2751 2752 <function id="GetFrameCount" num="16"> 2753 <synopsis>Get Frame Count</synopsis> 2754 <description> 2755 Get the number of frames currently in the specified thread's call stack. 2756 <p/> 2757 If this function is called for a thread actively executing bytecodes (for example, 2758 not the current thread and not suspended), the information returned is transient. 2759 </description> 2760 <origin>jvmdi</origin> 2761 <capabilities> 2762 </capabilities> 2763 <parameters> 2764 <param id="thread"> 2765 <jthread null="current"/> 2766 <description> 2767 The thread to query. 2768 </description> 2769 </param> 2770 <param id="count_ptr"> 2771 <outptr><jint/></outptr> 2772 <description> 2773 On return, points to the number of frames in the call stack. 2774 </description> 2775 </param> 2776 </parameters> 2777 <errors> 2778 </errors> 2779 </function> 2780 2781 <function id="PopFrame" num="80"> 2782 <synopsis>Pop Frame</synopsis> 2783 <description> 2784 Pop the current frame of <code>thread</code>'s stack. 2785 Popping a frame takes you to the previous frame. 2786 When the thread is resumed, the execution 2787 state of the thread is reset to the state 2788 immediately before the called method was invoked. 2789 That is (using <vmspec/> terminology): 2790 <ul> 2791 <li>the current frame is discarded as the previous frame becomes the current one</li> 2792 <li>the operand stack is restored--the argument values are added back 2793 and if the invoke was not <code>invokestatic</code>, 2794 <code>objectref</code> is added back as well</li> 2795 <li>the Java virtual machine PC is restored to the opcode 2796 of the invoke instruction</li> 2797 </ul> 2798 Note however, that any changes to the arguments, which 2799 occurred in the called method, remain; 2800 when execution continues, the first instruction to 2801 execute will be the invoke. 2802 <p/> 2803 Between calling <code>PopFrame</code> and resuming the 2804 thread the state of the stack is undefined. 2805 To pop frames beyond the first, 2806 these three steps must be repeated: 2807 <ul> 2808 <li>suspend the thread via an event (step, breakpoint, ...)</li> 2809 <li>call <code>PopFrame</code></li> 2810 <li>resume the thread</li> 2811 </ul> 2812 <p/> 2813 A lock acquired by calling the called method 2814 (if it is a <code>synchronized</code> method) 2815 and locks acquired by entering <code>synchronized</code> 2816 blocks within the called method are released. 2817 Note: this does not apply to native locks or 2818 <code>java.util.concurrent.locks</code> locks. 2819 <p/> 2820 Finally blocks are not executed. 2821 <p/> 2822 Changes to global state are not addressed and thus remain changed. 2823 <p/> 2824 The specified thread must be suspended (which implies it cannot be the current thread). 2825 <p/> 2826 Both the called method and calling method must be non-native Java programming 2827 language methods. 2828 <p/> 2829 No <jvmti/> events are generated by this function. 2830 </description> 2831 <origin>jvmdi</origin> 2832 <capabilities> 2833 <required id="can_pop_frame"></required> 2834 </capabilities> 2835 <parameters> 2836 <param id="thread"> 2837 <jthread/> 2838 <description> 2839 The thread whose current frame is to be popped. 2840 </description> 2841 </param> 2842 </parameters> 2843 <errors> 2844 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 2845 Called or calling method is a native method. 2846 The implementation is unable to pop this frame. 2847 </error> 2848 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> 2849 Thread was not suspended. 2850 </error> 2851 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> 2852 There are less than two stack frames on the call stack. 2853 </error> 2854 </errors> 2855 </function> 2856 2857 <function id="GetFrameLocation" num="19"> 2858 <synopsis>Get Frame Location</synopsis> 2859 <description> 2860 <p/> 2861 For a Java programming language frame, return the location of the instruction 2862 currently executing. 2863 </description> 2864 <origin>jvmdiClone</origin> 2865 <capabilities> 2866 </capabilities> 2867 <parameters> 2868 <param id="thread"> 2869 <jthread null="current" frame="frame"/> 2870 <description> 2871 The thread of the frame to query. 2872 </description> 2873 </param> 2874 <param id="depth"> 2875 <jframeID thread="thread"/> 2876 <description> 2877 The depth of the frame to query. 2878 </description> 2879 </param> 2880 <param id="method_ptr"> 2881 <outptr><jmethodID/></outptr> 2882 <description> 2883 On return, points to the method for the current location. 2884 </description> 2885 </param> 2886 <param id="location_ptr"> 2887 <outptr><jlocation/></outptr> 2888 <description> 2889 On return, points to the index of the currently 2890 executing instruction. 2891 Is set to <code>-1</code> if the frame is executing 2892 a native method. 2893 </description> 2894 </param> 2895 </parameters> 2896 <errors> 2897 </errors> 2898 </function> 2899 2900 <function id="NotifyFramePop" num="20"> 2901 <synopsis>Notify Frame Pop</synopsis> 2902 <description> 2903 When the frame that is currently at <paramlink id="depth"></paramlink> 2904 is popped from the stack, generate a 2905 <eventlink id="FramePop"></eventlink> event. See the 2906 <eventlink id="FramePop"></eventlink> event for details. 2907 Only frames corresponding to non-native Java programming language 2908 methods can receive notification. 2909 <p/> 2910 The specified thread must either be the current thread 2911 or the thread must be suspended. 2912 </description> 2913 <origin>jvmdi</origin> 2914 <capabilities> 2915 <required id="can_generate_frame_pop_events"></required> 2916 </capabilities> 2917 <parameters> 2918 <param id="thread"> 2919 <jthread null="current" frame="depth"/> 2920 <description> 2921 The thread of the frame for which the frame pop event will be generated. 2922 </description> 2923 </param> 2924 <param id="depth"> 2925 <jframeID thread="thread"/> 2926 <description> 2927 The depth of the frame for which the frame pop event will be generated. 2928 </description> 2929 </param> 2930 </parameters> 2931 <errors> 2932 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 2933 The frame at <code>depth</code> is executing a 2934 native method. 2935 </error> 2936 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> 2937 Thread was not suspended and was not the current thread. 2938 </error> 2939 </errors> 2940 </function> 2941 2942 </category> 2943 2944 <category id="ForceEarlyReturn" label="Force Early Return"> 2945 <intro> 2946 These functions allow an agent to force a method 2947 to return at any point during its execution. 2948 The method which will return early is referred to as the <i>called method</i>. 2949 The called method is the current method 2950 (as defined by 2951 <vmspec chapter="3.6"/>) 2952 for the specified thread at 2953 the time the function is called. 2954 <p/> 2955 The specified thread must be suspended or must be the current thread. 2956 The return occurs when execution of Java programming 2957 language code is resumed on this thread. 2958 Between calling one of these functions and resumption 2959 of thread execution, the state of the stack is undefined. 2960 <p/> 2961 No further instructions are executed in the called method. 2962 Specifically, finally blocks are not executed. 2963 Note: this can cause inconsistent states in the application. 2964 <p/> 2965 A lock acquired by calling the called method 2966 (if it is a <code>synchronized</code> method) 2967 and locks acquired by entering <code>synchronized</code> 2968 blocks within the called method are released. 2969 Note: this does not apply to native locks or 2970 <code>java.util.concurrent.locks</code> locks. 2971 <p/> 2972 Events, such as <eventlink id="MethodExit"></eventlink>, 2973 are generated as they would be in a normal return. 2974 <p/> 2975 The called method must be a non-native Java programming 2976 language method. 2977 Forcing return on a thread with only one frame on the 2978 stack causes the thread to exit when resumed. 2979 </intro> 2980 2981 <function id="ForceEarlyReturnObject" num="81" since="1.1"> 2982 <synopsis>Force Early Return - Object</synopsis> 2983 <description> 2984 This function can be used to return from a method whose 2985 result type is <code>Object</code> 2986 or a subclass of <code>Object</code>. 2987 </description> 2988 <origin>new</origin> 2989 <capabilities> 2990 <required id="can_force_early_return"></required> 2991 </capabilities> 2992 <parameters> 2993 <param id="thread"> 2994 <jthread null="current"/> 2995 <description> 2996 The thread whose current frame is to return early. 2997 </description> 2998 </param> 2999 <param id="value"> 3000 <jobject/> 3001 <description> 3002 The return value for the called frame. 3003 An object or <code>NULL</code>. 3004 </description> 3005 </param> 3006 </parameters> 3007 <errors> 3008 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 3009 Attempted to return early from a frame 3010 corresponding to a native method. 3011 Or the implementation is unable to provide 3012 this functionality on this frame. 3013 </error> 3014 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 3015 The result type of the called method is not 3016 <code>Object</code> or a subclass of <code>Object</code>. 3017 </error> 3018 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 3019 The supplied <paramlink id="value"/> is not compatible with the 3020 result type of the called method. 3021 </error> 3022 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> 3023 Thread was not the current thread and was not suspended. 3024 </error> 3025 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> 3026 There are no more frames on the call stack. 3027 </error> 3028 </errors> 3029 </function> 3030 3031 <function id="ForceEarlyReturnInt" num="82" since="1.1"> 3032 <synopsis>Force Early Return - Int</synopsis> 3033 <description> 3034 This function can be used to return from a method whose 3035 result type is <code>int</code>, <code>short</code>, 3036 <code>char</code>, <code>byte</code>, or 3037 <code>boolean</code>. 3038 </description> 3039 <origin>new</origin> 3040 <capabilities> 3041 <required id="can_force_early_return"></required> 3042 </capabilities> 3043 <parameters> 3044 <param id="thread"> 3045 <jthread null="current"/> 3046 <description> 3047 The thread whose current frame is to return early. 3048 </description> 3049 </param> 3050 <param id="value"> 3051 <jint/> 3052 <description> 3053 The return value for the called frame. 3054 </description> 3055 </param> 3056 </parameters> 3057 <errors> 3058 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 3059 Attempted to return early from a frame 3060 corresponding to a native method. 3061 Or the implementation is unable to provide 3062 this functionality on this frame. 3063 </error> 3064 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 3065 The result type of the called method is not 3066 <code>int</code>, <code>short</code>, 3067 <code>char</code>, <code>byte</code>, or 3068 <code>boolean</code>. 3069 </error> 3070 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> 3071 Thread was not the current thread and was not suspended. 3072 </error> 3073 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> 3074 There are no frames on the call stack. 3075 </error> 3076 </errors> 3077 </function> 3078 3079 <function id="ForceEarlyReturnLong" num="83" since="1.1"> 3080 <synopsis>Force Early Return - Long</synopsis> 3081 <description> 3082 This function can be used to return from a method whose 3083 result type is <code>long</code>. 3084 </description> 3085 <origin>new</origin> 3086 <capabilities> 3087 <required id="can_force_early_return"></required> 3088 </capabilities> 3089 <parameters> 3090 <param id="thread"> 3091 <jthread null="current"/> 3092 <description> 3093 The thread whose current frame is to return early. 3094 </description> 3095 </param> 3096 <param id="value"> 3097 <jlong/> 3098 <description> 3099 The return value for the called frame. 3100 </description> 3101 </param> 3102 </parameters> 3103 <errors> 3104 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 3105 Attempted to return early from a frame 3106 corresponding to a native method. 3107 Or the implementation is unable to provide 3108 this functionality on this frame. 3109 </error> 3110 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 3111 The result type of the called method is not <code>long</code>. 3112 </error> 3113 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> 3114 Thread was not the current thread and was not suspended. 3115 </error> 3116 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> 3117 There are no frames on the call stack. 3118 </error> 3119 </errors> 3120 </function> 3121 3122 <function id="ForceEarlyReturnFloat" num="84" since="1.1"> 3123 <synopsis>Force Early Return - Float</synopsis> 3124 <description> 3125 This function can be used to return from a method whose 3126 result type is <code>float</code>. 3127 </description> 3128 <origin>new</origin> 3129 <capabilities> 3130 <required id="can_force_early_return"></required> 3131 </capabilities> 3132 <parameters> 3133 <param id="thread"> 3134 <jthread null="current"/> 3135 <description> 3136 The thread whose current frame is to return early. 3137 </description> 3138 </param> 3139 <param id="value"> 3140 <jfloat/> 3141 <description> 3142 The return value for the called frame. 3143 </description> 3144 </param> 3145 </parameters> 3146 <errors> 3147 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 3148 Attempted to return early from a frame 3149 corresponding to a native method. 3150 Or the implementation is unable to provide 3151 this functionality on this frame. 3152 </error> 3153 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 3154 The result type of the called method is not <code>float</code>. 3155 </error> 3156 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> 3157 Thread was not the current thread and was not suspended. 3158 </error> 3159 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> 3160 There are no frames on the call stack. 3161 </error> 3162 </errors> 3163 </function> 3164 3165 <function id="ForceEarlyReturnDouble" num="85" since="1.1"> 3166 <synopsis>Force Early Return - Double</synopsis> 3167 <description> 3168 This function can be used to return from a method whose 3169 result type is <code>double</code>. 3170 </description> 3171 <origin>new</origin> 3172 <capabilities> 3173 <required id="can_force_early_return"></required> 3174 </capabilities> 3175 <parameters> 3176 <param id="thread"> 3177 <jthread null="current"/> 3178 <description> 3179 The thread whose current frame is to return early. 3180 </description> 3181 </param> 3182 <param id="value"> 3183 <jdouble/> 3184 <description> 3185 The return value for the called frame. 3186 </description> 3187 </param> 3188 </parameters> 3189 <errors> 3190 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 3191 Attempted to return early from a frame corresponding to a native method. 3192 Or the implementation is unable to provide this functionality on this frame. 3193 </error> 3194 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 3195 The result type of the called method is not <code>double</code>. 3196 </error> 3197 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> 3198 Thread was not the current thread and was not suspended. 3199 </error> 3200 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> 3201 There are no frames on the call stack. 3202 </error> 3203 </errors> 3204 </function> 3205 3206 <function id="ForceEarlyReturnVoid" num="86" since="1.1"> 3207 <synopsis>Force Early Return - Void</synopsis> 3208 <description> 3209 This function can be used to return from a method with no result type. 3210 That is, the called method must be declared <code>void</code>. 3211 </description> 3212 <origin>new</origin> 3213 <capabilities> 3214 <required id="can_force_early_return"></required> 3215 </capabilities> 3216 <parameters> 3217 <param id="thread"> 3218 <jthread null="current"/> 3219 <description> 3220 The thread whose current frame is to return early. 3221 </description> 3222 </param> 3223 </parameters> 3224 <errors> 3225 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 3226 Attempted to return early from a frame 3227 corresponding to a native method. 3228 Or the implementation is unable to provide 3229 this functionality on this frame. 3230 </error> 3231 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 3232 The called method has a result type. 3233 </error> 3234 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> 3235 Thread was not the current thread and was not suspended. 3236 </error> 3237 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> 3238 There are no frames on the call stack. 3239 </error> 3240 </errors> 3241 </function> 3242 3243 </category> 3244 3245 <category id="Heap" label="Heap"> 3246 <intro> 3247 These functions are used to analyze the heap. 3248 Functionality includes the ability to view the objects in the 3249 heap and to tag these objects. 3250 </intro> 3251 3252 <intro id="objectTags" label="Object Tags"> 3253 A <i>tag</i> is a value associated with an object. 3254 Tags are explicitly set by the agent using the 3255 <functionlink id="SetTag"></functionlink> function or by 3256 callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>. 3257 <p/> 3258 Tags are local to the environment; that is, the tags of one 3259 environment are not visible in another. 3260 <p/> 3261 Tags are <code>jlong</code> values which can be used 3262 simply to mark an object or to store a pointer to more detailed 3263 information. Objects which have not been tagged have a 3264 tag of zero. 3265 Setting a tag to zero makes the object untagged. 3266 </intro> 3267 3268 <intro id="heapCallbacks" label="Heap Callback Functions"> 3269 Heap functions which iterate through the heap and recursively 3270 follow object references use agent supplied callback functions 3271 to deliver the information. 3272 <p/> 3273 These heap callback functions must adhere to the following restrictions -- 3274 These callbacks must not use JNI functions. 3275 These callbacks must not use <jvmti/> functions except 3276 <i>callback safe</i> functions which 3277 specifically allow such use (see the raw monitor, memory management, 3278 and environment local storage functions). 3279 <p/> 3280 An implementation may invoke a callback on an internal thread or 3281 the thread which called the iteration function. 3282 Heap callbacks are single threaded -- no more than one callback will 3283 be invoked at a time. 3284 <p/> 3285 The Heap Filter Flags can be used to prevent reporting 3286 based on the tag status of an object or its class. 3287 If no flags are set (the <code>jint</code> is zero), objects 3288 will not be filtered out. 3289 3290 <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits"> 3291 <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4"> 3292 Filter out tagged objects. Objects which are tagged are not included. 3293 </constant> 3294 <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8"> 3295 Filter out untagged objects. Objects which are not tagged are not included. 3296 </constant> 3297 <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10"> 3298 Filter out objects with tagged classes. Objects whose class is tagged are not included. 3299 </constant> 3300 <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20"> 3301 Filter out objects with untagged classes. Objects whose class is not tagged are not included. 3302 </constant> 3303 </constants> 3304 3305 <p/> 3306 The Heap Visit Control Flags are returned by the heap callbacks 3307 and can be used to abort the iteration. For the 3308 <functionlink id="jvmtiHeapReferenceCallback">Heap 3309 Reference Callback</functionlink>, it can also be used 3310 to prune the graph of traversed references 3311 (<code>JVMTI_VISIT_OBJECTS</code> is not set). 3312 3313 <constants id="jvmtiHeapVisitControl" 3314 label="Heap Visit Control Flags" 3315 kind="bits" 3316 since="1.1"> 3317 <constant id="JVMTI_VISIT_OBJECTS" num="0x100"> 3318 If we are visiting an object and if this callback 3319 was initiated by <functionlink id="FollowReferences"/>, 3320 traverse the references of this object. 3321 Otherwise ignored. 3322 </constant> 3323 <constant id="JVMTI_VISIT_ABORT" num="0x8000"> 3324 Abort the iteration. Ignore all other bits. 3325 </constant> 3326 </constants> 3327 3328 <p/> 3329 The Heap Reference Enumeration is provided by the 3330 <functionlink id="jvmtiHeapReferenceCallback">Heap 3331 Reference Callback</functionlink> and 3332 <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field 3333 Callback</functionlink> to 3334 describe the kind of reference 3335 being reported. 3336 3337 <constants id="jvmtiHeapReferenceKind" 3338 label="Heap Reference Enumeration" 3339 kind="enum" 3340 since="1.1"> 3341 <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1"> 3342 Reference from an object to its class. 3343 </constant> 3344 <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2"> 3345 Reference from an object to the value of one of its instance fields. 3346 </constant> 3347 <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3"> 3348 Reference from an array to one of its elements. 3349 </constant> 3350 <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4"> 3351 Reference from a class to its class loader. 3352 </constant> 3353 <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5"> 3354 Reference from a class to its signers array. 3355 </constant> 3356 <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6"> 3357 Reference from a class to its protection domain. 3358 </constant> 3359 <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7"> 3360 Reference from a class to one of its interfaces. 3361 Note: interfaces are defined via a constant pool reference, 3362 so the referenced interfaces may also be reported with a 3363 <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. 3364 </constant> 3365 <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8"> 3366 Reference from a class to the value of one of its static fields. 3367 </constant> 3368 <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9"> 3369 Reference from a class to a resolved entry in the constant pool. 3370 </constant> 3371 <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10"> 3372 Reference from a class to its superclass. 3373 A callback is bot sent if the superclass is <code>java.lang.Object</code>. 3374 Note: loaded classes define superclasses via a constant pool 3375 reference, so the referenced superclass may also be reported with 3376 a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. 3377 </constant> 3378 <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21"> 3379 Heap root reference: JNI global reference. 3380 </constant> 3381 <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22"> 3382 Heap root reference: System class. 3383 </constant> 3384 <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23"> 3385 Heap root reference: monitor. 3386 </constant> 3387 <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24"> 3388 Heap root reference: local variable on the stack. 3389 </constant> 3390 <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25"> 3391 Heap root reference: JNI local reference. 3392 </constant> 3393 <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26"> 3394 Heap root reference: Thread. 3395 </constant> 3396 <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27"> 3397 Heap root reference: other heap root reference. 3398 </constant> 3399 </constants> 3400 3401 <p/> 3402 Definitions for the single character type descriptors of 3403 primitive types. 3404 3405 <constants id="jvmtiPrimitiveType" 3406 label="Primitive Type Enumeration" 3407 kind="enum" 3408 since="1.1"> 3409 <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90"> 3410 'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code> 3411 </constant> 3412 <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66"> 3413 'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code> 3414 </constant> 3415 <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67"> 3416 'C' - Java programming language <code>char</code> - JNI <code>jchar</code> 3417 </constant> 3418 <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83"> 3419 'S' - Java programming language <code>short</code> - JNI <code>jshort</code> 3420 </constant> 3421 <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73"> 3422 'I' - Java programming language <code>int</code> - JNI <code>jint</code> 3423 </constant> 3424 <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74"> 3425 'J' - Java programming language <code>long</code> - JNI <code>jlong</code> 3426 </constant> 3427 <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70"> 3428 'F' - Java programming language <code>float</code> - JNI <code>jfloat</code> 3429 </constant> 3430 <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68"> 3431 'D' - Java programming language <code>double</code> - JNI <code>jdouble</code> 3432 </constant> 3433 </constants> 3434 </intro> 3435 3436 <typedef id="jvmtiHeapReferenceInfoField" 3437 label="Reference information structure for Field references" 3438 since="1.1"> 3439 <description> 3440 Reference information returned for 3441 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and 3442 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. 3443 </description> 3444 <field id="index"> 3445 <jint/> 3446 <description> 3447 For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the 3448 referrer object is not a class or an inteface. 3449 In this case, <code>index</code> is the index of the field 3450 in the class of the referrer object. 3451 This class is referred to below as <i>C</i>. 3452 <p/> 3453 For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, 3454 the referrer object is a class (referred to below as <i>C</i>) 3455 or an interface (referred to below as <i>I</i>). 3456 In this case, <code>index</code> is the index of the field in 3457 that class or interface. 3458 <p/> 3459 If the referrer object is not an interface, then the field 3460 indices are determined as follows: 3461 <ul> 3462 <li>make a list of all the fields in <i>C</i> and its 3463 superclasses, starting with all the fields in 3464 <code>java.lang.Object</code> and ending with all the 3465 fields in <i>C</i>.</li> 3466 <li>Within this list, put 3467 the fields for a given class in the order returned by 3468 <functionlink id="GetClassFields"/>.</li> 3469 <li>Assign the fields in this list indices 3470 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> 3471 is the count of the fields in all the interfaces 3472 implemented by <i>C</i>. 3473 Note that <i>C</i> implements all interfaces 3474 directly implemented by its superclasses; as well 3475 as all superinterfaces of these interfaces.</li> 3476 </ul> 3477 If the referrer object is an interface, then the field 3478 indices are determined as follows: 3479 <ul> 3480 <li>make a list of the fields directly declared in 3481 <i>I</i>.</li> 3482 <li>Within this list, put 3483 the fields in the order returned by 3484 <functionlink id="GetClassFields"/>.</li> 3485 <li>Assign the fields in this list indices 3486 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> 3487 is the count of the fields in all the superinterfaces 3488 of <i>I</i>.</li> 3489 </ul> 3490 All fields are included in this computation, regardless of 3491 field modifier (static, public, private, etc). 3492 <p/> 3493 For example, given the following classes and interfaces: 3494 <example> 3495interface I0 { 3496 int p = 0; 3497} 3498 3499interface I1 extends I0 { 3500 int x = 1; 3501} 3502 3503interface I2 extends I0 { 3504 int y = 2; 3505} 3506 3507class C1 implements I1 { 3508 public static int a = 3; 3509 private int b = 4; 3510} 3511 3512class C2 extends C1 implements I2 { 3513 static int q = 5; 3514 final int r = 6; 3515} 3516 </example> 3517 Assume that <functionlink id="GetClassFields"/> called on 3518 <code>C1</code> returns the fields of <code>C1</code> in the 3519 order: a, b; and that the fields of <code>C2</code> are 3520 returned in the order: q, r. 3521 An instance of class <code>C1</code> will have the 3522 following field indices: 3523 <dl><dd><table> 3524 <tr> 3525 <td> 3526 a 3527 </td> 3528 <td> 3529 2 3530 </td> 3531 <td align="left"> 3532 The count of the fields in the interfaces 3533 implemented by <code>C1</code> is two (<i>n</i>=2): 3534 <code>p</code> of <code>I0</code> 3535 and <code>x</code> of <code>I1</code>. 3536 </td> 3537 </tr> 3538 <tr> 3539 <td> 3540 b 3541 </td> 3542 <td> 3543 3 3544 </td> 3545 <td align="left"> 3546 the subsequent index. 3547 </td> 3548 </tr> 3549 </table></dd></dl> 3550 The class <code>C1</code> will have the same field indices. 3551 <p/> 3552 An instance of class <code>C2</code> will have the 3553 following field indices: 3554 <dl><dd><table> 3555 <tr> 3556 <td> 3557 a 3558 </td> 3559 <td> 3560 3 3561 </td> 3562 <td align="left"> 3563 The count of the fields in the interfaces 3564 implemented by <code>C2</code> is three (<i>n</i>=3): 3565 <code>p</code> of <code>I0</code>, 3566 <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code> 3567 (an interface of <code>C2</code>). Note that the field <code>p</code> 3568 of <code>I0</code> is only included once. 3569 </td> 3570 </tr> 3571 <tr> 3572 <td> 3573 b 3574 </td> 3575 <td> 3576 4 3577 </td> 3578 <td align="left"> 3579 the subsequent index to "a". 3580 </td> 3581 </tr> 3582 <tr> 3583 <td> 3584 q 3585 </td> 3586 <td> 3587 5 3588 </td> 3589 <td align="left"> 3590 the subsequent index to "b". 3591 </td> 3592 </tr> 3593 <tr> 3594 <td> 3595 r 3596 </td> 3597 <td> 3598 6 3599 </td> 3600 <td align="left"> 3601 the subsequent index to "q". 3602 </td> 3603 </tr> 3604 </table></dd></dl> 3605 The class <code>C2</code> will have the same field indices. 3606 Note that a field may have a different index depending on the 3607 object that is viewing it -- for example field "a" above. 3608 Note also: not all field indices may be visible from the 3609 callbacks, but all indices are shown for illustrative purposes. 3610 <p/> 3611 The interface <code>I1</code> will have the 3612 following field indices: 3613 <dl><dd><table> 3614 <tr> 3615 <td> 3616 x 3617 </td> 3618 <td> 3619 1 3620 </td> 3621 <td align="left"> 3622 The count of the fields in the superinterfaces 3623 of <code>I1</code> is one (<i>n</i>=1): 3624 <code>p</code> of <code>I0</code>. 3625 </td> 3626 </tr> 3627 </table></dd></dl> 3628 </description> 3629 </field> 3630 </typedef> 3631 3632 <typedef id="jvmtiHeapReferenceInfoArray" 3633 label="Reference information structure for Array references" 3634 since="1.1"> 3635 <description> 3636 Reference information returned for 3637 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. 3638 </description> 3639 <field id="index"> 3640 <jint/> 3641 <description> 3642 The array index. 3643 </description> 3644 </field> 3645 </typedef> 3646 3647 <typedef id="jvmtiHeapReferenceInfoConstantPool" 3648 label="Reference information structure for Constant Pool references" 3649 since="1.1"> 3650 <description> 3651 Reference information returned for 3652 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. 3653 </description> 3654 <field id="index"> 3655 <jint/> 3656 <description> 3657 The index into the constant pool of the class. See the description in 3658 <vmspec chapter="4.4"/>. 3659 </description> 3660 </field> 3661 </typedef> 3662 3663 <typedef id="jvmtiHeapReferenceInfoStackLocal" 3664 label="Reference information structure for Local Variable references" 3665 since="1.1"> 3666 <description> 3667 Reference information returned for 3668 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. 3669 </description> 3670 <field id="thread_tag"> 3671 <jlong/> 3672 <description> 3673 The tag of the thread corresponding to this stack, zero if not tagged. 3674 </description> 3675 </field> 3676 <field id="thread_id"> 3677 <jlong/> 3678 <description> 3679 The unique thread ID of the thread corresponding to this stack. 3680 </description> 3681 </field> 3682 <field id="depth"> 3683 <jint/> 3684 <description> 3685 The depth of the frame. 3686 </description> 3687 </field> 3688 <field id="method"> 3689 <jmethodID/> 3690 <description> 3691 The method executing in this frame. 3692 </description> 3693 </field> 3694 <field id="location"> 3695 <jlocation/> 3696 <description> 3697 The currently executing location in this frame. 3698 </description> 3699 </field> 3700 <field id="slot"> 3701 <jint/> 3702 <description> 3703 The slot number of the local variable. 3704 </description> 3705 </field> 3706 </typedef> 3707 3708 <typedef id="jvmtiHeapReferenceInfoJniLocal" 3709 label="Reference information structure for JNI local references" 3710 since="1.1"> 3711 <description> 3712 Reference information returned for 3713 <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. 3714 </description> 3715 <field id="thread_tag"> 3716 <jlong/> 3717 <description> 3718 The tag of the thread corresponding to this stack, zero if not tagged. 3719 </description> 3720 </field> 3721 <field id="thread_id"> 3722 <jlong/> 3723 <description> 3724 The unique thread ID of the thread corresponding to this stack. 3725 </description> 3726 </field> 3727 <field id="depth"> 3728 <jint/> 3729 <description> 3730 The depth of the frame. 3731 </description> 3732 </field> 3733 <field id="method"> 3734 <jmethodID/> 3735 <description> 3736 The method executing in this frame. 3737 </description> 3738 </field> 3739 </typedef> 3740 3741 <typedef id="jvmtiHeapReferenceInfoReserved" 3742 label="Reference information structure for Other references" 3743 since="1.1"> 3744 <description> 3745 Reference information returned for other references. 3746 </description> 3747 <field id="reserved1"> 3748 <jlong/> 3749 <description> 3750 reserved for future use. 3751 </description> 3752 </field> 3753 <field id="reserved2"> 3754 <jlong/> 3755 <description> 3756 reserved for future use. 3757 </description> 3758 </field> 3759 <field id="reserved3"> 3760 <jlong/> 3761 <description> 3762 reserved for future use. 3763 </description> 3764 </field> 3765 <field id="reserved4"> 3766 <jlong/> 3767 <description> 3768 reserved for future use. 3769 </description> 3770 </field> 3771 <field id="reserved5"> 3772 <jlong/> 3773 <description> 3774 reserved for future use. 3775 </description> 3776 </field> 3777 <field id="reserved6"> 3778 <jlong/> 3779 <description> 3780 reserved for future use. 3781 </description> 3782 </field> 3783 <field id="reserved7"> 3784 <jlong/> 3785 <description> 3786 reserved for future use. 3787 </description> 3788 </field> 3789 <field id="reserved8"> 3790 <jlong/> 3791 <description> 3792 reserved for future use. 3793 </description> 3794 </field> 3795 </typedef> 3796 3797 <uniontypedef id="jvmtiHeapReferenceInfo" 3798 label="Reference information structure" 3799 since="1.1"> 3800 <description> 3801 The information returned about referrers. 3802 Represented as a union of the various kinds of reference information. 3803 </description> 3804 <field id="field"> 3805 <struct>jvmtiHeapReferenceInfoField</struct> 3806 <description> 3807 The referrer information for 3808 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> 3809 and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. 3810 </description> 3811 </field> 3812 <field id="array"> 3813 <struct>jvmtiHeapReferenceInfoArray</struct> 3814 <description> 3815 The referrer information for 3816 For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. 3817 </description> 3818 </field> 3819 <field id="constant_pool"> 3820 <struct>jvmtiHeapReferenceInfoConstantPool</struct> 3821 <description> 3822 The referrer information for 3823 For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. 3824 </description> 3825 </field> 3826 <field id="stack_local"> 3827 <struct>jvmtiHeapReferenceInfoStackLocal</struct> 3828 <description> 3829 The referrer information for 3830 For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. 3831 </description> 3832 </field> 3833 <field id="jni_local"> 3834 <struct>jvmtiHeapReferenceInfoJniLocal</struct> 3835 <description> 3836 The referrer information for 3837 For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. 3838 </description> 3839 </field> 3840 <field id="other"> 3841 <struct>jvmtiHeapReferenceInfoReserved</struct> 3842 <description> 3843 reserved for future use. 3844 </description> 3845 </field> 3846 </uniontypedef> 3847 3848 <typedef id="jvmtiHeapCallbacks" 3849 label="Heap callback function structure" 3850 since="1.1"> 3851 <field id="heap_iteration_callback"> 3852 <ptrtype> 3853 <struct>jvmtiHeapIterationCallback</struct> 3854 </ptrtype> 3855 <description> 3856 The callback to be called to describe an 3857 object in the heap. Used by the 3858 <functionlink id="IterateThroughHeap"/> function, ignored by the 3859 <functionlink id="FollowReferences"/> function. 3860 </description> 3861 </field> 3862 <field id="heap_reference_callback"> 3863 <ptrtype> 3864 <struct>jvmtiHeapReferenceCallback</struct> 3865 </ptrtype> 3866 <description> 3867 The callback to be called to describe an 3868 object reference. Used by the 3869 <functionlink id="FollowReferences"/> function, ignored by the 3870 <functionlink id="IterateThroughHeap"/> function. 3871 </description> 3872 </field> 3873 <field id="primitive_field_callback"> 3874 <ptrtype> 3875 <struct>jvmtiPrimitiveFieldCallback</struct> 3876 </ptrtype> 3877 <description> 3878 The callback to be called to describe a 3879 primitive field. 3880 </description> 3881 </field> 3882 <field id="array_primitive_value_callback"> 3883 <ptrtype> 3884 <struct>jvmtiArrayPrimitiveValueCallback</struct> 3885 </ptrtype> 3886 <description> 3887 The callback to be called to describe an 3888 array of primitive values. 3889 </description> 3890 </field> 3891 <field id="string_primitive_value_callback"> 3892 <ptrtype> 3893 <struct>jvmtiStringPrimitiveValueCallback</struct> 3894 </ptrtype> 3895 <description> 3896 The callback to be called to describe a String value. 3897 </description> 3898 </field> 3899 <field id="reserved5"> 3900 <ptrtype> 3901 <struct>jvmtiReservedCallback</struct> 3902 </ptrtype> 3903 <description> 3904 Reserved for future use.. 3905 </description> 3906 </field> 3907 <field id="reserved6"> 3908 <ptrtype> 3909 <struct>jvmtiReservedCallback</struct> 3910 </ptrtype> 3911 <description> 3912 Reserved for future use.. 3913 </description> 3914 </field> 3915 <field id="reserved7"> 3916 <ptrtype> 3917 <struct>jvmtiReservedCallback</struct> 3918 </ptrtype> 3919 <description> 3920 Reserved for future use.. 3921 </description> 3922 </field> 3923 <field id="reserved8"> 3924 <ptrtype> 3925 <struct>jvmtiReservedCallback</struct> 3926 </ptrtype> 3927 <description> 3928 Reserved for future use.. 3929 </description> 3930 </field> 3931 <field id="reserved9"> 3932 <ptrtype> 3933 <struct>jvmtiReservedCallback</struct> 3934 </ptrtype> 3935 <description> 3936 Reserved for future use.. 3937 </description> 3938 </field> 3939 <field id="reserved10"> 3940 <ptrtype> 3941 <struct>jvmtiReservedCallback</struct> 3942 </ptrtype> 3943 <description> 3944 Reserved for future use.. 3945 </description> 3946 </field> 3947 <field id="reserved11"> 3948 <ptrtype> 3949 <struct>jvmtiReservedCallback</struct> 3950 </ptrtype> 3951 <description> 3952 Reserved for future use.. 3953 </description> 3954 </field> 3955 <field id="reserved12"> 3956 <ptrtype> 3957 <struct>jvmtiReservedCallback</struct> 3958 </ptrtype> 3959 <description> 3960 Reserved for future use.. 3961 </description> 3962 </field> 3963 <field id="reserved13"> 3964 <ptrtype> 3965 <struct>jvmtiReservedCallback</struct> 3966 </ptrtype> 3967 <description> 3968 Reserved for future use.. 3969 </description> 3970 </field> 3971 <field id="reserved14"> 3972 <ptrtype> 3973 <struct>jvmtiReservedCallback</struct> 3974 </ptrtype> 3975 <description> 3976 Reserved for future use.. 3977 </description> 3978 </field> 3979 <field id="reserved15"> 3980 <ptrtype> 3981 <struct>jvmtiReservedCallback</struct> 3982 </ptrtype> 3983 <description> 3984 Reserved for future use.. 3985 </description> 3986 </field> 3987 </typedef> 3988 3989 3990 <intro> 3991 <rationale> 3992 The heap dumping functionality (below) uses a callback 3993 for each object. While it would seem that a buffered approach 3994 would provide better throughput, tests do 3995 not show this to be the case--possibly due to locality of 3996 memory reference or array access overhead. 3997 </rationale> 3998 3999 <issue> 4000 Still under investigation as to if java.lang.ref references 4001 are reported as a different type of reference. 4002 </issue> 4003 4004 <issue> 4005 Should or can an indication of the cost or relative cost of 4006 these operations be included? 4007 </issue> 4008 4009 </intro> 4010 4011 <callback id="jvmtiHeapIterationCallback" since="1.1"> 4012 <jint/> 4013 <synopsis>Heap Iteration Callback</synopsis> 4014 <description> 4015 Agent supplied callback function. 4016 Describes (but does not pass in) an object in the heap. 4017 <p/> 4018 This function should return a bit vector of the desired 4019 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. 4020 This will determine if the entire iteration should be aborted 4021 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). 4022 <p/> 4023 See the <internallink id="heapCallbacks">heap callback 4024 function restrictions</internallink>. 4025 </description> 4026 <parameters> 4027 <param id="class_tag"> 4028 <jlong/> 4029 <description> 4030 The tag of the class of object (zero if the class is not tagged). 4031 If the object represents a runtime class, 4032 the <code>class_tag</code> is the tag 4033 associated with <code>java.lang.Class</code> 4034 (zero if <code>java.lang.Class</code> is not tagged). 4035 </description> 4036 </param> 4037 <param id="size"> 4038 <jlong/> 4039 <description> 4040 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. 4041 </description> 4042 </param> 4043 <param id="tag_ptr"> 4044 <outptr><jlong/></outptr> 4045 <description> 4046 The object tag value, or zero if the object is not tagged. 4047 To set the tag value to be associated with the object 4048 the agent sets the <code>jlong</code> pointed to by the parameter. 4049 </description> 4050 </param> 4051 <param id="length"> 4052 <jint/> 4053 <description> 4054 If this object is an array, the length of the array. Otherwise negative one (-1). 4055 </description> 4056 </param> 4057 <param id="user_data"> 4058 <outptr><void/></outptr> 4059 <description> 4060 The user supplied data that was passed into the iteration function. 4061 </description> 4062 </param> 4063 </parameters> 4064 </callback> 4065 4066 <callback id="jvmtiHeapReferenceCallback" since="1.1"> 4067 <jint/> 4068 <synopsis>Heap Reference Callback</synopsis> 4069 <description> 4070 Agent supplied callback function. 4071 Describes a reference from an object or the VM (the referrer) to another object 4072 (the referree) or a heap root to a referree. 4073 <p/> 4074 This function should return a bit vector of the desired 4075 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. 4076 This will determine if the objects referenced by the referree 4077 should be visited or if the entire iteration should be aborted. 4078 <p/> 4079 See the <internallink id="heapCallbacks">heap callback 4080 function restrictions</internallink>. 4081 </description> 4082 <parameters> 4083 <param id="reference_kind"> 4084 <enum>jvmtiHeapReferenceKind</enum> 4085 <description> 4086 The kind of reference. 4087 </description> 4088 </param> 4089 <param id="reference_info"> 4090 <inptr> 4091 <struct>jvmtiHeapReferenceInfo</struct> 4092 </inptr> 4093 <description> 4094 Details about the reference. 4095 Set when the <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> is 4096 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, 4097 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, 4098 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>, 4099 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>, 4100 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>, 4101 or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>. 4102 Otherwise <code>NULL</code>. 4103 </description> 4104 </param> 4105 <param id="class_tag"> 4106 <jlong/> 4107 <description> 4108 The tag of the class of referree object (zero if the class is not tagged). 4109 If the referree object represents a runtime class, 4110 the <code>class_tag</code> is the tag 4111 associated with <code>java.lang.Class</code> 4112 (zero if <code>java.lang.Class</code> is not tagged). 4113 </description> 4114 </param> 4115 <param id="referrer_class_tag"> 4116 <jlong/> 4117 <description> 4118 The tag of the class of the referrer object (zero if the class is not tagged 4119 or the referree is a heap root). If the referrer object represents a runtime 4120 class, the <code>referrer_class_tag</code> is the tag associated with 4121 the <code>java.lang.Class</code> 4122 (zero if <code>java.lang.Class</code> is not tagged). 4123 </description> 4124 </param> 4125 <param id="size"> 4126 <jlong/> 4127 <description> 4128 Size of the referree object (in bytes). 4129 See <functionlink id="GetObjectSize"/>. 4130 </description> 4131 </param> 4132 <param id="tag_ptr"> 4133 <outptr><jlong/></outptr> 4134 <description> 4135 Points to the referree object tag value, or zero if the object is not 4136 tagged. 4137 To set the tag value to be associated with the object 4138 the agent sets the <code>jlong</code> pointed to by the parameter. 4139 </description> 4140 </param> 4141 <param id="referrer_tag_ptr"> 4142 <outptr><jlong/></outptr> 4143 <description> 4144 Points to the tag of the referrer object, or 4145 points to the zero if the referrer 4146 object is not tagged. 4147 <code>NULL</code> if the referrer in not an object (that is, 4148 this callback is reporting a heap root). 4149 To set the tag value to be associated with the referrer object 4150 the agent sets the <code>jlong</code> pointed to by the parameter. 4151 If this callback is reporting a reference from an object to itself, 4152 <code>referrer_tag_ptr == tag_ptr</code>. 4153 </description> 4154 </param> 4155 <param id="length"> 4156 <jint/> 4157 <description> 4158 If this object is an array, the length of the array. Otherwise negative one (-1). 4159 </description> 4160 </param> 4161 <param id="user_data"> 4162 <outptr><void/></outptr> 4163 <description> 4164 The user supplied data that was passed into the iteration function. 4165 </description> 4166 </param> 4167 </parameters> 4168 </callback> 4169 4170 <callback id="jvmtiPrimitiveFieldCallback" since="1.1"> 4171 <jint/> 4172 <synopsis>Primitive Field Callback</synopsis> 4173 <description> 4174 Agent supplied callback function which 4175 describes a primitive field of an object (<i>the object</i>). 4176 A primitive field is a field whose type is a primitive type. 4177 This callback will describe a static field if the object is a class, 4178 and otherwise will describe an instance field. 4179 <p/> 4180 This function should return a bit vector of the desired 4181 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. 4182 This will determine if the entire iteration should be aborted 4183 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). 4184 <p/> 4185 See the <internallink id="heapCallbacks">heap callback 4186 function restrictions</internallink>. 4187 </description> 4188 <parameters> 4189 <param id="kind"> 4190 <enum>jvmtiHeapReferenceKind</enum> 4191 <description> 4192 The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or 4193 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>). 4194 </description> 4195 </param> 4196 <param id="info"> 4197 <inptr> 4198 <struct>jvmtiHeapReferenceInfo</struct> 4199 </inptr> 4200 <description> 4201 Which field (the field index). 4202 </description> 4203 </param> 4204 <param id="object_class_tag"> 4205 <jlong/> 4206 <description> 4207 The tag of the class of the object (zero if the class is not tagged). 4208 If the object represents a runtime class, the 4209 <code>object_class_tag</code> is the tag 4210 associated with <code>java.lang.Class</code> 4211 (zero if <code>java.lang.Class</code> is not tagged). 4212 </description> 4213 </param> 4214 <param id="object_tag_ptr"> 4215 <outptr><jlong/></outptr> 4216 <description> 4217 Points to the tag of the object, or zero if the object is not 4218 tagged. 4219 To set the tag value to be associated with the object 4220 the agent sets the <code>jlong</code> pointed to by the parameter. 4221 </description> 4222 </param> 4223 <param id="value"> 4224 <jvalue/> 4225 <description> 4226 The value of the field. 4227 </description> 4228 </param> 4229 <param id="value_type"> 4230 <enum>jvmtiPrimitiveType</enum> 4231 <description> 4232 The type of the field. 4233 </description> 4234 </param> 4235 <param id="user_data"> 4236 <outptr><void/></outptr> 4237 <description> 4238 The user supplied data that was passed into the iteration function. 4239 </description> 4240 </param> 4241 </parameters> 4242 </callback> 4243 4244 <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1"> 4245 <jint/> 4246 <synopsis>Array Primitive Value Callback</synopsis> 4247 <description> 4248 Agent supplied callback function. 4249 Describes the values in an array of a primitive type. 4250 <p/> 4251 This function should return a bit vector of the desired 4252 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. 4253 This will determine if the entire iteration should be aborted 4254 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). 4255 <p/> 4256 See the <internallink id="heapCallbacks">heap callback 4257 function restrictions</internallink>. 4258 </description> 4259 <parameters> 4260 <param id="class_tag"> 4261 <jlong/> 4262 <description> 4263 The tag of the class of the array object (zero if the class is not tagged). 4264 </description> 4265 </param> 4266 <param id="size"> 4267 <jlong/> 4268 <description> 4269 Size of the array (in bytes). 4270 See <functionlink id="GetObjectSize"/>. 4271 </description> 4272 </param> 4273 <param id="tag_ptr"> 4274 <outptr><jlong/></outptr> 4275 <description> 4276 Points to the tag of the array object, or zero if the object is not 4277 tagged. 4278 To set the tag value to be associated with the object 4279 the agent sets the <code>jlong</code> pointed to by the parameter. 4280 </description> 4281 </param> 4282 <param id="element_count"> 4283 <jint/> 4284 <description> 4285 The length of the primitive array. 4286 </description> 4287 </param> 4288 <param id="element_type"> 4289 <enum>jvmtiPrimitiveType</enum> 4290 <description> 4291 The type of the elements of the array. 4292 </description> 4293 </param> 4294 <param id="elements"> 4295 <vmbuf><void/></vmbuf> 4296 <description> 4297 The elements of the array in a packed array of <code>element_count</code> 4298 items of <code>element_type</code> size each. 4299 </description> 4300 </param> 4301 <param id="user_data"> 4302 <outptr><void/></outptr> 4303 <description> 4304 The user supplied data that was passed into the iteration function. 4305 </description> 4306 </param> 4307 </parameters> 4308 </callback> 4309 4310 <callback id="jvmtiStringPrimitiveValueCallback" since="1.1"> 4311 <jint/> 4312 <synopsis>String Primitive Value Callback</synopsis> 4313 <description> 4314 Agent supplied callback function. 4315 Describes the value of a java.lang.String. 4316 <p/> 4317 This function should return a bit vector of the desired 4318 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. 4319 This will determine if the entire iteration should be aborted 4320 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). 4321 <p/> 4322 See the <internallink id="heapCallbacks">heap callback 4323 function restrictions</internallink>. 4324 </description> 4325 <parameters> 4326 <param id="class_tag"> 4327 <jlong/> 4328 <description> 4329 The tag of the class of the String class (zero if the class is not tagged). 4330 <issue>Is this needed?</issue> 4331 </description> 4332 </param> 4333 <param id="size"> 4334 <jlong/> 4335 <description> 4336 Size of the string (in bytes). 4337 See <functionlink id="GetObjectSize"/>. 4338 </description> 4339 </param> 4340 <param id="tag_ptr"> 4341 <outptr><jlong/></outptr> 4342 <description> 4343 Points to the tag of the String object, or zero if the object is not 4344 tagged. 4345 To set the tag value to be associated with the object 4346 the agent sets the <code>jlong</code> pointed to by the parameter. 4347 </description> 4348 </param> 4349 <param id="value"> 4350 <vmbuf><jchar/></vmbuf> 4351 <description> 4352 The value of the String, encoded as a Unicode string. 4353 </description> 4354 </param> 4355 <param id="value_length"> 4356 <jint/> 4357 <description> 4358 The length of the string. 4359 The length is equal to the number of 16-bit Unicode 4360 characters in the string. 4361 </description> 4362 </param> 4363 <param id="user_data"> 4364 <outptr><void/></outptr> 4365 <description> 4366 The user supplied data that was passed into the iteration function. 4367 </description> 4368 </param> 4369 </parameters> 4370 </callback> 4371 4372 4373 <callback id="jvmtiReservedCallback" since="1.1"> 4374 <jint/> 4375 <synopsis>reserved for future use Callback</synopsis> 4376 <description> 4377 Placeholder -- reserved for future use. 4378 </description> 4379 <parameters> 4380 </parameters> 4381 </callback> 4382 4383 <function id="FollowReferences" num="115" since="1.1"> 4384 <synopsis>Follow References</synopsis> 4385 <description> 4386 This function initiates a traversal over the objects that are 4387 directly and indirectly reachable from the specified object or, 4388 if <code>initial_object</code> is not specified, all objects 4389 reachable from the heap roots. 4390 The heap root are the set of system classes, 4391 JNI globals, references from thread stacks, and other objects used as roots 4392 for the purposes of garbage collection. 4393 <p/> 4394 This function operates by traversing the reference graph. 4395 Let <i>A</i>, <i>B</i>, ... represent objects. 4396 When a reference from <i>A</i> to <i>B</i> is traversed, 4397 when a reference from a heap root to <i>B</i> is traversed, 4398 or when <i>B</i> is specified as the <paramlink id="initial_object"/>, 4399 then <i>B</i> is said to be <i>visited</i>. 4400 A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i> 4401 is visited. 4402 References are reported in the same order that the references are traversed. 4403 Object references are reported by invoking the agent supplied 4404 callback function <functionlink id="jvmtiHeapReferenceCallback"/>. 4405 In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known 4406 as the <i>referrer</i> and <i>B</i> as the <i>referree</i>. 4407 The callback is invoked exactly once for each reference from a referrer; 4408 this is true even if there are reference cycles or multiple paths to 4409 the referrer. 4410 There may be more than one reference between a referrer and a referree, 4411 each reference is reported. 4412 These references may be distinguished by examining the 4413 <datalink 4414 id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink> 4415 and 4416 <datalink 4417 id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink> 4418 parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback. 4419 <p/> 4420 This function reports a Java programming language view of object references, 4421 not a virtual machine implementation view. The following object references 4422 are reported when they are non-null: 4423 <ul> 4424 <li>Instance objects report references to each non-primitive instance fields 4425 (including inherited fields).</li> 4426 <li>Instance objects report a reference to the object type (class).</li> 4427 <li>Classes report a reference to the superclass and directly 4428 implemented/extended interfaces.</li> 4429 <li>Classes report a reference to the class loader, protection domain, 4430 signers, and resolved entries in the constant pool.</li> 4431 <li>Classes report a reference to each directly declared non-primitive 4432 static field.</li> 4433 <li>Arrays report a reference to the array type (class) and each 4434 array element.</li> 4435 <li>Primitive arrays report a reference to the array type.</li> 4436 </ul> 4437 <p/> 4438 This function can also be used to examine primitive (non-object) values. 4439 The primitive value of an array or String 4440 is reported after the object has been visited; 4441 it is reported by invoking the agent supplied callback function 4442 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or 4443 <functionlink id="jvmtiStringPrimitiveValueCallback"/>. 4444 A primitive field 4445 is reported after the object with that field is visited; 4446 it is reported by invoking the agent supplied callback function 4447 <functionlink id="jvmtiPrimitiveFieldCallback"/>. 4448 <p/> 4449 Whether a callback is provided or is <code>NULL</code> only determines 4450 whether the callback will be invoked, it does not influence 4451 which objects are visited nor does it influence whether other callbacks 4452 will be invoked. 4453 However, the 4454 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink> 4455 returned by <functionlink id="jvmtiHeapReferenceCallback"/> 4456 do determine if the objects referenced by the 4457 current object as visited. 4458 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> 4459 and <paramlink id="klass"/> provided as parameters to this function 4460 do not control which objects are visited but they do control which 4461 objects and primitive values are reported by the callbacks. 4462 For example, if the only callback that was set is 4463 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code> 4464 is set to the array of bytes class, then only arrays of byte will be 4465 reported. 4466 The table below summarizes this: 4467 <p/> 4468 <table> 4469 <tr> 4470 <th/> 4471 <th> 4472 Controls objects visited 4473 </th> 4474 <th> 4475 Controls objects reported 4476 </th> 4477 <th> 4478 Controls primitives reported 4479 </th> 4480 </tr> 4481 <tr> 4482 <th align="left"> 4483 the 4484 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> 4485 returned by <functionlink id="jvmtiHeapReferenceCallback"/> 4486 </th> 4487 <td> 4488 <b>Yes</b> 4489 </td> 4490 <td> 4491 <b>Yes</b>, since visits are controlled 4492 </td> 4493 <td> 4494 <b>Yes</b>, since visits are controlled 4495 </td> 4496 </tr> 4497 <tr> 4498 <th align="left"> 4499 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> 4500 in <paramlink id="callbacks"/> set 4501 </th> 4502 <td> 4503 No 4504 </td> 4505 <td> 4506 <b>Yes</b> 4507 </td> 4508 <td> 4509 No 4510 </td> 4511 </tr> 4512 <tr> 4513 <th align="left"> 4514 <paramlink id="heap_filter"/> 4515 </th> 4516 <td> 4517 No 4518 </td> 4519 <td> 4520 <b>Yes</b> 4521 </td> 4522 <td> 4523 <b>Yes</b> 4524 </td> 4525 </tr> 4526 <tr> 4527 <th align="left"> 4528 <paramlink id="klass"/> 4529 </th> 4530 <td> 4531 No 4532 </td> 4533 <td> 4534 <b>Yes</b> 4535 </td> 4536 <td> 4537 <b>Yes</b> 4538 </td> 4539 </tr> 4540 </table> 4541 <p/> 4542 During the execution of this function the state of the heap 4543 does not change: no objects are allocated, no objects are 4544 garbage collected, and the state of objects (including 4545 held values) does not change. 4546 As a result, threads executing Java 4547 programming language code, threads attempting to resume the 4548 execution of Java programming language code, and threads 4549 attempting to execute JNI functions are typically stalled. 4550 </description> 4551 <origin>new</origin> 4552 <capabilities> 4553 <required id="can_tag_objects"></required> 4554 </capabilities> 4555 <parameters> 4556 <param id="heap_filter"> 4557 <jint/> 4558 <description> 4559 This bit vector of 4560 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>. 4561 restricts the objects for which the callback function is called. 4562 This applies to both the object and primitive callbacks. 4563 </description> 4564 </param> 4565 <param id="klass"> 4566 <ptrtype> 4567 <jclass/> 4568 <nullok>callbacks are not limited to instances of a particular 4569 class</nullok> 4570 </ptrtype> 4571 <description> 4572 Callbacks are only reported when the object is an instance of 4573 this class. 4574 Objects which are instances of a subclass of <code>klass</code> 4575 are not reported. 4576 If <code>klass</code> is an interface, no objects are reported. 4577 This applies to both the object and primitive callbacks. 4578 </description> 4579 </param> 4580 <param id="initial_object"> 4581 <ptrtype> 4582 <jobject/> 4583 <nullok>references are followed from the heap roots</nullok> 4584 </ptrtype> 4585 <description> 4586 The object to follow 4587 </description> 4588 </param> 4589 <param id="callbacks"> 4590 <inptr> 4591 <struct>jvmtiHeapCallbacks</struct> 4592 </inptr> 4593 <description> 4594 Structure defining the set of callback functions. 4595 </description> 4596 </param> 4597 <param id="user_data"> 4598 <inbuf> 4599 <void/> 4600 <nullok><code>NULL</code> is passed as the user supplied data</nullok> 4601 </inbuf> 4602 <description> 4603 User supplied data to be passed to the callback. 4604 </description> 4605 </param> 4606 </parameters> 4607 <errors> 4608 <error id="JVMTI_ERROR_INVALID_CLASS"> 4609 <paramlink id="klass"/> is not a valid class. 4610 </error> 4611 <error id="JVMTI_ERROR_INVALID_OBJECT"> 4612 <paramlink id="initial_object"/> is not a valid object. 4613 </error> 4614 </errors> 4615 </function> 4616 4617 4618 <function id="IterateThroughHeap" num="116" since="1.1"> 4619 <synopsis>Iterate Through Heap</synopsis> 4620 <description> 4621 Initiate an iteration over all objects in the heap. 4622 This includes both reachable and 4623 unreachable objects. Objects are visited in no particular order. 4624 <p/> 4625 Heap objects are reported by invoking the agent supplied 4626 callback function <functionlink id="jvmtiHeapIterationCallback"/>. 4627 References between objects are not reported. 4628 If only reachable objects are desired, or if object reference information 4629 is needed, use <functionlink id="FollowReferences"/>. 4630 <p/> 4631 This function can also be used to examine primitive (non-object) values. 4632 The primitive value of an array or String 4633 is reported after the object has been visited; 4634 it is reported by invoking the agent supplied callback function 4635 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or 4636 <functionlink id="jvmtiStringPrimitiveValueCallback"/>. 4637 A primitive field 4638 is reported after the object with that field is visited; 4639 it is reported by invoking the agent supplied 4640 callback function 4641 <functionlink id="jvmtiPrimitiveFieldCallback"/>. 4642 <p/> 4643 Unless the iteration is aborted by the 4644 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> 4645 returned by a callback, all objects in the heap are visited. 4646 Whether a callback is provided or is <code>NULL</code> only determines 4647 whether the callback will be invoked, it does not influence 4648 which objects are visited nor does it influence whether other callbacks 4649 will be invoked. 4650 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> 4651 and <paramlink id="klass"/> provided as parameters to this function 4652 do not control which objects are visited but they do control which 4653 objects and primitive values are reported by the callbacks. 4654 For example, if the only callback that was set is 4655 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code> 4656 is set to the array of bytes class, then only arrays of byte will be 4657 reported. The table below summarizes this (contrast this with 4658 <functionlink id="FollowReferences"/>): 4659 <p/> 4660 <table> 4661 <tr> 4662 <th/> 4663 <th> 4664 Controls objects visited 4665 </th> 4666 <th> 4667 Controls objects reported 4668 </th> 4669 <th> 4670 Controls primitives reported 4671 </th> 4672 </tr> 4673 <tr> 4674 <th align="left"> 4675 the 4676 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> 4677 returned by <functionlink id="jvmtiHeapIterationCallback"/> 4678 </th> 4679 <td> 4680 No<br/>(unless they abort the iteration) 4681 </td> 4682 <td> 4683 No<br/>(unless they abort the iteration) 4684 </td> 4685 <td> 4686 No<br/>(unless they abort the iteration) 4687 </td> 4688 </tr> 4689 <tr> 4690 <th align="left"> 4691 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> 4692 in <paramlink id="callbacks"/> set 4693 </th> 4694 <td> 4695 No 4696 </td> 4697 <td> 4698 <b>Yes</b> 4699 </td> 4700 <td> 4701 No 4702 </td> 4703 </tr> 4704 <tr> 4705 <th align="left"> 4706 <paramlink id="heap_filter"/> 4707 </th> 4708 <td> 4709 No 4710 </td> 4711 <td> 4712 <b>Yes</b> 4713 </td> 4714 <td> 4715 <b>Yes</b> 4716 </td> 4717 </tr> 4718 <tr> 4719 <th align="left"> 4720 <paramlink id="klass"/> 4721 </th> 4722 <td> 4723 No 4724 </td> 4725 <td> 4726 <b>Yes</b> 4727 </td> 4728 <td> 4729 <b>Yes</b> 4730 </td> 4731 </tr> 4732 </table> 4733 <p/> 4734 During the execution of this function the state of the heap 4735 does not change: no objects are allocated, no objects are 4736 garbage collected, and the state of objects (including 4737 held values) does not change. 4738 As a result, threads executing Java 4739 programming language code, threads attempting to resume the 4740 execution of Java programming language code, and threads 4741 attempting to execute JNI functions are typically stalled. 4742 </description> 4743 <origin>new</origin> 4744 <capabilities> 4745 <required id="can_tag_objects"></required> 4746 </capabilities> 4747 <parameters> 4748 <param id="heap_filter"> 4749 <jint/> 4750 <description> 4751 This bit vector of 4752 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>. 4753 restricts the objects for which the callback function is called. 4754 This applies to both the object and primitive callbacks. 4755 </description> 4756 </param> 4757 <param id="klass"> 4758 <ptrtype> 4759 <jclass/> 4760 <nullok>callbacks are not limited to instances of a particular class</nullok> 4761 </ptrtype> 4762 <description> 4763 Callbacks are only reported when the object is an instance of 4764 this class. 4765 Objects which are instances of a subclass of <code>klass</code> 4766 are not reported. 4767 If <code>klass</code> is an interface, no objects are reported. 4768 This applies to both the object and primitive callbacks. 4769 </description> 4770 </param> 4771 <param id="callbacks"> 4772 <inptr> 4773 <struct>jvmtiHeapCallbacks</struct> 4774 </inptr> 4775 <description> 4776 Structure defining the set callback functions. 4777 </description> 4778 </param> 4779 <param id="user_data"> 4780 <inbuf> 4781 <void/> 4782 <nullok><code>NULL</code> is passed as the user supplied data</nullok> 4783 </inbuf> 4784 <description> 4785 User supplied data to be passed to the callback. 4786 </description> 4787 </param> 4788 </parameters> 4789 <errors> 4790 <error id="JVMTI_ERROR_INVALID_CLASS"> 4791 <paramlink id="klass"/> is not a valid class. 4792 </error> 4793 </errors> 4794 </function> 4795 4796 <function id="GetTag" phase="start" num="106"> 4797 <synopsis>Get Tag</synopsis> 4798 <description> 4799 Retrieve the tag associated with an object. 4800 The tag is a long value typically used to store a 4801 unique identifier or pointer to object information. 4802 The tag is set with 4803 <functionlink id="SetTag"></functionlink>. 4804 Objects for which no tags have been set return a 4805 tag value of zero. 4806 </description> 4807 <origin>new</origin> 4808 <capabilities> 4809 <required id="can_tag_objects"></required> 4810 </capabilities> 4811 <parameters> 4812 <param id="object"> 4813 <jobject/> 4814 <description> 4815 The object whose tag is to be retrieved. 4816 </description> 4817 </param> 4818 <param id="tag_ptr"> 4819 <outptr><jlong/></outptr> 4820 <description> 4821 On return, the referenced long is set to the value 4822 of the tag. 4823 </description> 4824 </param> 4825 </parameters> 4826 <errors> 4827 </errors> 4828 </function> 4829 4830 <function id="SetTag" phase="start" num="107"> 4831 <synopsis>Set Tag</synopsis> 4832 <description> 4833 Set the tag associated with an object. 4834 The tag is a long value typically used to store a 4835 unique identifier or pointer to object information. 4836 The tag is visible with 4837 <functionlink id="GetTag"></functionlink>. 4838 </description> 4839 <origin>new</origin> 4840 <capabilities> 4841 <required id="can_tag_objects"></required> 4842 </capabilities> 4843 <parameters> 4844 <param id="object"> 4845 <jobject/> 4846 <description> 4847 The object whose tag is to be set. 4848 </description> 4849 </param> 4850 <param id="tag"> 4851 <jlong/> 4852 <description> 4853 The new value of the tag. 4854 </description> 4855 </param> 4856 </parameters> 4857 <errors> 4858 </errors> 4859 </function> 4860 4861 <function id="GetObjectsWithTags" num="114"> 4862 <synopsis>Get Objects With Tags</synopsis> 4863 <description> 4864 Return objects in the heap with the specified tags. 4865 The format is parallel arrays of objects and tags. 4866 </description> 4867 <origin>new</origin> 4868 <capabilities> 4869 <required id="can_tag_objects"></required> 4870 </capabilities> 4871 <parameters> 4872 <param id="tag_count"> 4873 <jint min="0"/> 4874 <description> 4875 Number of tags to scan for. 4876 </description> 4877 </param> 4878 <param id="tags"> 4879 <inbuf incount="tag_count"> 4880 <jlong/> 4881 </inbuf> 4882 <description> 4883 Scan for objects with these tags. 4884 Zero is not permitted in this array. 4885 </description> 4886 </param> 4887 <param id="count_ptr"> 4888 <outptr> 4889 <jint/> 4890 </outptr> 4891 <description> 4892 Return the number of objects with any of the tags 4893 in <paramlink id="tags"/>. 4894 </description> 4895 </param> 4896 <param id="object_result_ptr"> 4897 <allocbuf outcount="count_ptr"> 4898 <jobject/> 4899 <nullok>this information is not returned</nullok> 4900 </allocbuf> 4901 <description> 4902 Returns the array of objects with any of the tags 4903 in <paramlink id="tags"/>. 4904 </description> 4905 </param> 4906 <param id="tag_result_ptr"> 4907 <allocbuf outcount="count_ptr"> 4908 <jlong/> 4909 <nullok>this information is not returned</nullok> 4910 </allocbuf> 4911 <description> 4912 For each object in <paramlink id="object_result_ptr"/>, 4913 return the tag at the corresponding index. 4914 </description> 4915 </param> 4916 </parameters> 4917 <errors> 4918 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 4919 Zero is present in <paramlink id="tags"></paramlink>. 4920 </error> 4921 </errors> 4922 </function> 4923 4924 <function id="ForceGarbageCollection" num="108"> 4925 <synopsis>Force Garbage Collection</synopsis> 4926 <description> 4927 Force the VM to perform a garbage collection. 4928 The garbage collection is as complete as possible. 4929 This function does not cause finalizers to be run. 4930 This function does not return until the garbage collection 4931 is finished. 4932 <p/> 4933 Although garbage collection is as complete 4934 as possible there is no guarantee that all 4935 <eventlink id="ObjectFree"/> 4936 events will have been 4937 sent by the time that this function 4938 returns. In particular, an object may be 4939 prevented from being freed because it 4940 is awaiting finalization. 4941 </description> 4942 <origin>new</origin> 4943 <capabilities> 4944 </capabilities> 4945 <parameters> 4946 </parameters> 4947 <errors> 4948 </errors> 4949 </function> 4950 4951 4952 </category> 4953 4954 <category id="Heap_1_0" label="Heap (1.0)"> 4955 <intro> 4956 <b> 4957 These functions and data types were introduced in the original 4958 <jvmti/> version 1.0 and have been superseded by more 4959 </b> 4960 <internallink id="Heap"><b>powerful and flexible versions</b></internallink> 4961 <b> 4962 which: 4963 </b> 4964 <ul> 4965 <li> 4966 <b> 4967 Allow access to primitive values (the value of Strings, arrays, 4968 and primitive fields) 4969 </b> 4970 </li> 4971 <li> 4972 <b> 4973 Allow the tag of the referrer to be set, thus enabling more 4974 efficient localized reference graph building 4975 </b> 4976 </li> 4977 <li> 4978 <b> 4979 Provide more extensive filtering abilities 4980 </b> 4981 </li> 4982 <li> 4983 <b> 4984 Are extensible, allowing their abilities to grow in future versions of <jvmti/> 4985 </b> 4986 </li> 4987 </ul> 4988 <p/> 4989 <b>Please use the </b> 4990 <internallink id="Heap"><b>current Heap functions</b></internallink>. 4991 <p/> 4992 <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum"> 4993 <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1"> 4994 Tagged objects only. 4995 </constant> 4996 <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2"> 4997 Untagged objects only. 4998 </constant> 4999 <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3"> 5000 Either tagged or untagged objects. 5001 </constant> 5002 </constants> 5003 5004 <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum"> 5005 <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1"> 5006 JNI global reference. 5007 </constant> 5008 <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2"> 5009 System class. 5010 </constant> 5011 <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3"> 5012 Monitor. 5013 </constant> 5014 <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4"> 5015 Stack local. 5016 </constant> 5017 <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5"> 5018 JNI local reference. 5019 </constant> 5020 <constant id="JVMTI_HEAP_ROOT_THREAD" num="6"> 5021 Thread. 5022 </constant> 5023 <constant id="JVMTI_HEAP_ROOT_OTHER" num="7"> 5024 Other. 5025 </constant> 5026 </constants> 5027 5028 <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum"> 5029 <constant id="JVMTI_REFERENCE_CLASS" num="1"> 5030 Reference from an object to its class. 5031 </constant> 5032 <constant id="JVMTI_REFERENCE_FIELD" num="2"> 5033 Reference from an object to the value of one of its instance fields. 5034 For references of this kind the <code>referrer_index</code> 5035 parameter to the <internallink id="jvmtiObjectReferenceCallback"> 5036 jvmtiObjectReferenceCallback</internallink> is the index of the 5037 the instance field. The index is based on the order of all the 5038 object's fields. This includes all fields of the directly declared 5039 static and instance fields in the class, and includes all fields (both 5040 public and private) fields declared in superclasses and superinterfaces. 5041 The index is thus calculated by summing the index of the field in the directly 5042 declared class (see <functionlink id="GetClassFields"/>), with the total 5043 number of fields (both public and private) declared in all superclasses 5044 and superinterfaces. The index starts at zero. 5045 </constant> 5046 <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3"> 5047 Reference from an array to one of its elements. 5048 For references of this kind the <code>referrer_index</code> 5049 parameter to the <internallink id="jvmtiObjectReferenceCallback"> 5050 jvmtiObjectReferenceCallback</internallink> is the array index. 5051 </constant> 5052 <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4"> 5053 Reference from a class to its class loader. 5054 </constant> 5055 <constant id="JVMTI_REFERENCE_SIGNERS" num="5"> 5056 Reference from a class to its signers array. 5057 </constant> 5058 <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6"> 5059 Reference from a class to its protection domain. 5060 </constant> 5061 <constant id="JVMTI_REFERENCE_INTERFACE" num="7"> 5062 Reference from a class to one of its interfaces. 5063 </constant> 5064 <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8"> 5065 Reference from a class to the value of one of its static fields. 5066 For references of this kind the <code>referrer_index</code> 5067 parameter to the <internallink id="jvmtiObjectReferenceCallback"> 5068 jvmtiObjectReferenceCallback</internallink> is the index of the 5069 the static field. The index is based on the order of all the 5070 object's fields. This includes all fields of the directly declared 5071 static and instance fields in the class, and includes all fields (both 5072 public and private) fields declared in superclasses and superinterfaces. 5073 The index is thus calculated by summing the index of the field in the directly 5074 declared class (see <functionlink id="GetClassFields"/>), with the total 5075 number of fields (both public and private) declared in all superclasses 5076 and superinterfaces. The index starts at zero. 5077 Note: this definition differs from that in the <jvmti/> 1.0 Specification. 5078 <rationale>No known implementations used the 1.0 definition.</rationale> 5079 </constant> 5080 <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9"> 5081 Reference from a class to a resolved entry in the constant pool. 5082 For references of this kind the <code>referrer_index</code> 5083 parameter to the <internallink id="jvmtiObjectReferenceCallback"> 5084 jvmtiObjectReferenceCallback</internallink> is the index into 5085 constant pool table of the class, starting at 1. See 5086 <vmspec chapter="4.4"/>. 5087 </constant> 5088 </constants> 5089 5090 <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum"> 5091 <constant id="JVMTI_ITERATION_CONTINUE" num="1"> 5092 Continue the iteration. 5093 If this is a reference iteration, follow the references of this object. 5094 </constant> 5095 <constant id="JVMTI_ITERATION_IGNORE" num="2"> 5096 Continue the iteration. 5097 If this is a reference iteration, ignore the references of this object. 5098 </constant> 5099 <constant id="JVMTI_ITERATION_ABORT" num="0"> 5100 Abort the iteration. 5101 </constant> 5102 </constants> 5103 </intro> 5104 5105 <callback id="jvmtiHeapObjectCallback"> 5106 <enum>jvmtiIterationControl</enum> 5107 <synopsis>Heap Object Callback</synopsis> 5108 <description> 5109 Agent supplied callback function. 5110 Describes (but does not pass in) an object in the heap. 5111 <p/> 5112 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, 5113 or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. 5114 <p/> 5115 See the <internallink id="heapCallbacks">heap callback 5116 function restrictions</internallink>. 5117 </description> 5118 <parameters> 5119 <param id="class_tag"> 5120 <jlong/> 5121 <description> 5122 The tag of the class of object (zero if the class is not tagged). 5123 If the object represents a runtime class, 5124 the <code>class_tag</code> is the tag 5125 associated with <code>java.lang.Class</code> 5126 (zero if <code>java.lang.Class</code> is not tagged). 5127 </description> 5128 </param> 5129 <param id="size"> 5130 <jlong/> 5131 <description> 5132 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. 5133 </description> 5134 </param> 5135 <param id="tag_ptr"> 5136 <outptr><jlong/></outptr> 5137 <description> 5138 The object tag value, or zero if the object is not tagged. 5139 To set the tag value to be associated with the object 5140 the agent sets the <code>jlong</code> pointed to by the parameter. 5141 </description> 5142 </param> 5143 <param id="user_data"> 5144 <outptr><void/></outptr> 5145 <description> 5146 The user supplied data that was passed into the iteration function. 5147 </description> 5148 </param> 5149 </parameters> 5150 </callback> 5151 5152 <callback id="jvmtiHeapRootCallback"> 5153 <enum>jvmtiIterationControl</enum> 5154 <synopsis>Heap Root Object Callback</synopsis> 5155 <description> 5156 Agent supplied callback function. 5157 Describes (but does not pass in) an object that is a root for the purposes 5158 of garbage collection. 5159 <p/> 5160 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, 5161 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 5162 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. 5163 <p/> 5164 See the <internallink id="heapCallbacks">heap callback 5165 function restrictions</internallink>. 5166 </description> 5167 <parameters> 5168 <param id="root_kind"> 5169 <enum>jvmtiHeapRootKind</enum> 5170 <description> 5171 The kind of heap root. 5172 </description> 5173 </param> 5174 <param id="class_tag"> 5175 <jlong/> 5176 <description> 5177 The tag of the class of object (zero if the class is not tagged). 5178 If the object represents a runtime class, the <code>class_tag</code> is the tag 5179 associated with <code>java.lang.Class</code> 5180 (zero if <code>java.lang.Class</code> is not tagged). 5181 </description> 5182 </param> 5183 <param id="size"> 5184 <jlong/> 5185 <description> 5186 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. 5187 </description> 5188 </param> 5189 <param id="tag_ptr"> 5190 <outptr><jlong/></outptr> 5191 <description> 5192 The object tag value, or zero if the object is not tagged. 5193 To set the tag value to be associated with the object 5194 the agent sets the <code>jlong</code> pointed to by the parameter. 5195 </description> 5196 </param> 5197 <param id="user_data"> 5198 <outptr><void/></outptr> 5199 <description> 5200 The user supplied data that was passed into the iteration function. 5201 </description> 5202 </param> 5203 </parameters> 5204 </callback> 5205 5206 <callback id="jvmtiStackReferenceCallback"> 5207 <enum>jvmtiIterationControl</enum> 5208 <synopsis>Stack Reference Object Callback</synopsis> 5209 <description> 5210 Agent supplied callback function. 5211 Describes (but does not pass in) an object on the stack that is a root for 5212 the purposes of garbage collection. 5213 <p/> 5214 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, 5215 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 5216 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. 5217 <p/> 5218 See the <internallink id="heapCallbacks">heap callback 5219 function restrictions</internallink>. 5220 </description> 5221 <parameters> 5222 <param id="root_kind"> 5223 <enum>jvmtiHeapRootKind</enum> 5224 <description> 5225 The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or 5226 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>). 5227 </description> 5228 </param> 5229 <param id="class_tag"> 5230 <jlong/> 5231 <description> 5232 The tag of the class of object (zero if the class is not tagged). 5233 If the object represents a runtime class, the <code>class_tag</code> is the tag 5234 associated with <code>java.lang.Class</code> 5235 (zero if <code>java.lang.Class</code> is not tagged). 5236 </description> 5237 </param> 5238 <param id="size"> 5239 <jlong/> 5240 <description> 5241 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. 5242 </description> 5243 </param> 5244 <param id="tag_ptr"> 5245 <outptr><jlong/></outptr> 5246 <description> 5247 The object tag value, or zero if the object is not tagged. 5248 To set the tag value to be associated with the object 5249 the agent sets the <code>jlong</code> pointed to by the parameter. 5250 </description> 5251 </param> 5252 <param id="thread_tag"> 5253 <jlong/> 5254 <description> 5255 The tag of the thread corresponding to this stack, zero if not tagged. 5256 </description> 5257 </param> 5258 <param id="depth"> 5259 <jint/> 5260 <description> 5261 The depth of the frame. 5262 </description> 5263 </param> 5264 <param id="method"> 5265 <jmethodID/> 5266 <description> 5267 The method executing in this frame. 5268 </description> 5269 </param> 5270 <param id="slot"> 5271 <jint/> 5272 <description> 5273 The slot number. 5274 </description> 5275 </param> 5276 <param id="user_data"> 5277 <outptr><void/></outptr> 5278 <description> 5279 The user supplied data that was passed into the iteration function. 5280 </description> 5281 </param> 5282 </parameters> 5283 </callback> 5284 5285 <callback id="jvmtiObjectReferenceCallback"> 5286 <enum>jvmtiIterationControl</enum> 5287 <synopsis>Object Reference Callback</synopsis> 5288 <description> 5289 Agent supplied callback function. 5290 Describes a reference from an object (the referrer) to another object 5291 (the referree). 5292 <p/> 5293 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, 5294 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 5295 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. 5296 <p/> 5297 See the <internallink id="heapCallbacks">heap callback 5298 function restrictions</internallink>. 5299 </description> 5300 <parameters> 5301 <param id="reference_kind"> 5302 <enum>jvmtiObjectReferenceKind</enum> 5303 <description> 5304 The type of reference. 5305 </description> 5306 </param> 5307 <param id="class_tag"> 5308 <jlong/> 5309 <description> 5310 The tag of the class of referree object (zero if the class is not tagged). 5311 If the referree object represents a runtime class, 5312 the <code>class_tag</code> is the tag 5313 associated with <code>java.lang.Class</code> 5314 (zero if <code>java.lang.Class</code> is not tagged). 5315 </description> 5316 </param> 5317 <param id="size"> 5318 <jlong/> 5319 <description> 5320 Size of the referree object (in bytes). 5321 See <functionlink id="GetObjectSize"/>. 5322 </description> 5323 </param> 5324 <param id="tag_ptr"> 5325 <outptr><jlong/></outptr> 5326 <description> 5327 The referree object tag value, or zero if the object is not 5328 tagged. 5329 To set the tag value to be associated with the object 5330 the agent sets the <code>jlong</code> pointed to by the parameter. 5331 </description> 5332 </param> 5333 <param id="referrer_tag"> 5334 <jlong/> 5335 <description> 5336 The tag of the referrer object, or zero if the referrer 5337 object is not tagged. 5338 </description> 5339 </param> 5340 <param id="referrer_index"> 5341 <jint/> 5342 <description> 5343 For references of type <code>JVMTI_REFERENCE_FIELD</code> or 5344 <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index 5345 of the field in the referrer object. The index is based on the 5346 order of all the object's fields - see <internallink 5347 id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink> 5348 or <internallink 5349 id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD 5350 </internallink> for further description. 5351 <p/> 5352 For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code> 5353 the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT"> 5354 JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description. 5355 <p/> 5356 For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code> 5357 the index into the constant pool of the class - see 5358 <internallink id="JVMTI_REFERENCE_CONSTANT_POOL"> 5359 JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further 5360 description. 5361 <p/> 5362 For references of other kinds the <code>referrer_index</code> is 5363 <code>-1</code>. 5364 </description> 5365 </param> 5366 <param id="user_data"> 5367 <outptr><void/></outptr> 5368 <description> 5369 The user supplied data that was passed into the iteration function. 5370 </description> 5371 </param> 5372 </parameters> 5373 </callback> 5374 5375 <function id="IterateOverObjectsReachableFromObject" num="109"> 5376 <synopsis>Iterate Over Objects Reachable From Object</synopsis> 5377 <description> 5378 This function iterates over all objects that are directly 5379 and indirectly reachable from the specified object. 5380 For each object <i>A</i> (known 5381 as the referrer) with a reference to object <i>B</i> the specified 5382 callback function is called to describe the object reference. 5383 The callback is called exactly once for each reference from a referrer; 5384 this is true even if there are reference cycles or multiple paths to 5385 the referrer. 5386 There may be more than one reference between a referrer and a referree, 5387 These may be distinguished by the 5388 <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and 5389 <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>. 5390 The callback for an object will always occur after the callback for 5391 its referrer. 5392 <p/> 5393 See <functionlink id="FollowReferences"/> for the object 5394 references which are reported. 5395 <p/> 5396 During the execution of this function the state of the heap 5397 does not change: no objects are allocated, no objects are 5398 garbage collected, and the state of objects (including 5399 held values) does not change. 5400 As a result, threads executing Java 5401 programming language code, threads attempting to resume the 5402 execution of Java programming language code, and threads 5403 attempting to execute JNI functions are typically stalled. 5404 </description> 5405 <origin>new</origin> 5406 <capabilities> 5407 <required id="can_tag_objects"></required> 5408 </capabilities> 5409 <parameters> 5410 <param id="object"> 5411 <jobject/> 5412 <description> 5413 The object 5414 </description> 5415 </param> 5416 <param id="object_reference_callback"> 5417 <ptrtype> 5418 <struct>jvmtiObjectReferenceCallback</struct> 5419 </ptrtype> 5420 <description> 5421 The callback to be called to describe each 5422 object reference. 5423 </description> 5424 </param> 5425 <param id="user_data"> 5426 <inbuf> 5427 <void/> 5428 <nullok><code>NULL</code> is passed as the user supplied data</nullok> 5429 </inbuf> 5430 <description> 5431 User supplied data to be passed to the callback. 5432 </description> 5433 </param> 5434 </parameters> 5435 <errors> 5436 </errors> 5437 </function> 5438 5439 <function id="IterateOverReachableObjects" num="110"> 5440 <synopsis>Iterate Over Reachable Objects</synopsis> 5441 <description> 5442 This function iterates over the root objects and all objects that 5443 are directly and indirectly reachable from the root objects. 5444 The root objects comprise the set of system classes, 5445 JNI globals, references from thread stacks, and other objects used as roots 5446 for the purposes of garbage collection. 5447 <p/> 5448 For each root the <paramlink id="heap_root_callback"></paramlink> 5449 or <paramlink id="stack_ref_callback"></paramlink> callback is called. 5450 An object can be a root object for more than one reason and in that case 5451 the appropriate callback is called for each reason. 5452 <p/> 5453 For each object reference the <paramlink id="object_ref_callback"></paramlink> 5454 callback function is called to describe the object reference. 5455 The callback is called exactly once for each reference from a referrer; 5456 this is true even if there are reference cycles or multiple paths to 5457 the referrer. 5458 There may be more than one reference between a referrer and a referree, 5459 These may be distinguished by the 5460 <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and 5461 <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>. 5462 The callback for an object will always occur after the callback for 5463 its referrer. 5464 <p/> 5465 See <functionlink id="FollowReferences"/> for the object 5466 references which are reported. 5467 <p/> 5468 Roots are always reported to the profiler before any object references 5469 are reported. In other words, the <paramlink id="object_ref_callback"></paramlink> 5470 callback will not be called until the appropriate callback has been called 5471 for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is 5472 specified as <code>NULL</code> then this function returns after 5473 reporting the root objects to the profiler. 5474 <p/> 5475 During the execution of this function the state of the heap 5476 does not change: no objects are allocated, no objects are 5477 garbage collected, and the state of objects (including 5478 held values) does not change. 5479 As a result, threads executing Java 5480 programming language code, threads attempting to resume the 5481 execution of Java programming language code, and threads 5482 attempting to execute JNI functions are typically stalled. 5483 </description> 5484 <origin>new</origin> 5485 <capabilities> 5486 <required id="can_tag_objects"></required> 5487 </capabilities> 5488 <parameters> 5489 <param id="heap_root_callback"> 5490 <ptrtype> 5491 <struct>jvmtiHeapRootCallback</struct> 5492 <nullok>do not report heap roots</nullok> 5493 </ptrtype> 5494 <description> 5495 The callback function to be called for each heap root of type 5496 <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>, 5497 <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>, 5498 <code>JVMTI_HEAP_ROOT_MONITOR</code>, 5499 <code>JVMTI_HEAP_ROOT_THREAD</code>, or 5500 <code>JVMTI_HEAP_ROOT_OTHER</code>. 5501 </description> 5502 </param> 5503 <param id="stack_ref_callback"> 5504 <ptrtype> 5505 <struct>jvmtiStackReferenceCallback</struct> 5506 <nullok>do not report stack references</nullok> 5507 </ptrtype> 5508 <description> 5509 The callback function to be called for each heap root of 5510 <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or 5511 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>. 5512 </description> 5513 </param> 5514 <param id="object_ref_callback"> 5515 <ptrtype> 5516 <struct>jvmtiObjectReferenceCallback</struct> 5517 <nullok>do not follow references from the root objects</nullok> 5518 </ptrtype> 5519 <description> 5520 The callback function to be called for each object reference. 5521 </description> 5522 </param> 5523 <param id="user_data"> 5524 <inbuf> 5525 <void/> 5526 <nullok><code>NULL</code> is passed as the user supplied data</nullok> 5527 </inbuf> 5528 <description> 5529 User supplied data to be passed to the callback. 5530 </description> 5531 </param> 5532 </parameters> 5533 <errors> 5534 </errors> 5535 </function> 5536 5537 <function id="IterateOverHeap" num="111"> 5538 <synopsis>Iterate Over Heap</synopsis> 5539 <description> 5540 Iterate over all objects in the heap. This includes both reachable and 5541 unreachable objects. 5542 <p/> 5543 The <paramlink id="object_filter"></paramlink> parameter indicates the 5544 objects for which the callback function is called. If this parameter 5545 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be 5546 called for every object that is tagged. If the parameter is 5547 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be 5548 for objects that are not tagged. If the parameter 5549 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be 5550 called for every object in the heap, irrespective of whether it is 5551 tagged or not. 5552 <p/> 5553 During the execution of this function the state of the heap 5554 does not change: no objects are allocated, no objects are 5555 garbage collected, and the state of objects (including 5556 held values) does not change. 5557 As a result, threads executing Java 5558 programming language code, threads attempting to resume the 5559 execution of Java programming language code, and threads 5560 attempting to execute JNI functions are typically stalled. 5561 </description> 5562 <origin>new</origin> 5563 <capabilities> 5564 <required id="can_tag_objects"></required> 5565 </capabilities> 5566 <parameters> 5567 <param id="object_filter"> 5568 <enum>jvmtiHeapObjectFilter</enum> 5569 <description> 5570 Indicates the objects for which the callback function is called. 5571 </description> 5572 </param> 5573 <param id="heap_object_callback"> 5574 <ptrtype> 5575 <struct>jvmtiHeapObjectCallback</struct> 5576 </ptrtype> 5577 <description> 5578 The iterator function to be called for each 5579 object matching the <paramlink id="object_filter"/>. 5580 </description> 5581 </param> 5582 <param id="user_data"> 5583 <inbuf> 5584 <void/> 5585 <nullok><code>NULL</code> is passed as the user supplied data</nullok> 5586 </inbuf> 5587 <description> 5588 User supplied data to be passed to the callback. 5589 </description> 5590 </param> 5591 </parameters> 5592 <errors> 5593 </errors> 5594 </function> 5595 5596 <function id="IterateOverInstancesOfClass" num="112"> 5597 <synopsis>Iterate Over Instances Of Class</synopsis> 5598 <description> 5599 Iterate over all objects in the heap that are instances of the specified class. 5600 This includes direct instances of the specified class and 5601 instances of all subclasses of the specified class. 5602 This includes both reachable and unreachable objects. 5603 <p/> 5604 The <paramlink id="object_filter"></paramlink> parameter indicates the 5605 objects for which the callback function is called. If this parameter 5606 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be 5607 called for every object that is tagged. If the parameter is 5608 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be 5609 called for objects that are not tagged. If the parameter 5610 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be 5611 called for every object in the heap, irrespective of whether it is 5612 tagged or not. 5613 <p/> 5614 During the execution of this function the state of the heap 5615 does not change: no objects are allocated, no objects are 5616 garbage collected, and the state of objects (including 5617 held values) does not change. 5618 As a result, threads executing Java 5619 programming language code, threads attempting to resume the 5620 execution of Java programming language code, and threads 5621 attempting to execute JNI functions are typically stalled. 5622 </description> 5623 <origin>new</origin> 5624 <capabilities> 5625 <required id="can_tag_objects"></required> 5626 </capabilities> 5627 <parameters> 5628 <param id="klass"> 5629 <jclass/> 5630 <description> 5631 Iterate over objects of this class only. 5632 </description> 5633 </param> 5634 <param id="object_filter"> 5635 <enum>jvmtiHeapObjectFilter</enum> 5636 <description> 5637 Indicates the objects for which the callback function is called. 5638 </description> 5639 </param> 5640 <param id="heap_object_callback"> 5641 <ptrtype> 5642 <struct>jvmtiHeapObjectCallback</struct> 5643 </ptrtype> 5644 <description> 5645 The iterator function to be called for each 5646 <paramlink id="klass"/> instance matching 5647 the <paramlink id="object_filter"/>. 5648 </description> 5649 </param> 5650 <param id="user_data"> 5651 <inbuf> 5652 <void/> 5653 <nullok><code>NULL</code> is passed as the user supplied data</nullok> 5654 </inbuf> 5655 <description> 5656 User supplied data to be passed to the callback. 5657 </description> 5658 </param> 5659 </parameters> 5660 <errors> 5661 </errors> 5662 </function> 5663 5664 </category> 5665 5666 <category id="local" label="Local Variable"> 5667 5668 <intro> 5669 These functions are used to retrieve or set the value of a local variable. 5670 The variable is identified by the depth of the frame containing its 5671 value and the variable's slot number within that frame. 5672 The mapping of variables to 5673 slot numbers can be obtained with the function 5674 <functionlink id="GetLocalVariableTable"></functionlink>. 5675 </intro> 5676 5677 <function id="GetLocalObject" num="21"> 5678 <synopsis>Get Local Variable - Object</synopsis> 5679 <description> 5680 This function can be used to retrieve the value of a local 5681 variable whose type is <code>Object</code> or a subclass of <code>Object</code>. 5682 </description> 5683 <origin>jvmdi</origin> 5684 <capabilities> 5685 <required id="can_access_local_variables"></required> 5686 </capabilities> 5687 <parameters> 5688 <param id="thread"> 5689 <jthread null="current" frame="frame"/> 5690 <description> 5691 The thread of the frame containing the variable's value. 5692 </description> 5693 </param> 5694 <param id="depth"> 5695 <jframeID thread="thread"/> 5696 <description> 5697 The depth of the frame containing the variable's value. 5698 </description> 5699 </param> 5700 <param id="slot"> 5701 <jint/> 5702 <description> 5703 The variable's slot number. 5704 </description> 5705 </param> 5706 <param id="value_ptr"> 5707 <outptr><jobject/></outptr> 5708 <description> 5709 On return, points to the variable's value. 5710 </description> 5711 </param> 5712 </parameters> 5713 <errors> 5714 <error id="JVMTI_ERROR_INVALID_SLOT"> 5715 Invalid <code>slot</code>. 5716 </error> 5717 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 5718 The variable type is not 5719 <code>Object</code> or a subclass of <code>Object</code>. 5720 </error> 5721 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 5722 Not a visible frame 5723 </error> 5724 </errors> 5725 </function> 5726 5727 <function id="GetLocalInstance" num="155" since="1.2"> 5728 <synopsis>Get Local Instance</synopsis> 5729 <description> 5730 This function can be used to retrieve the value of the local object 5731 variable at slot 0 (the "<code>this</code>" object) from non-static 5732 frames. This function can retrieve the "<code>this</code>" object from 5733 native method frames, whereas <code>GetLocalObject()</code> would 5734 return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases. 5735 </description> 5736 <origin>new</origin> 5737 <capabilities> 5738 <required id="can_access_local_variables"></required> 5739 </capabilities> 5740 <parameters> 5741 <param id="thread"> 5742 <jthread null="current" frame="frame"/> 5743 <description> 5744 The thread of the frame containing the variable's value. 5745 </description> 5746 </param> 5747 <param id="depth"> 5748 <jframeID thread="thread"/> 5749 <description> 5750 The depth of the frame containing the variable's value. 5751 </description> 5752 </param> 5753 <param id="value_ptr"> 5754 <outptr><jobject/></outptr> 5755 <description> 5756 On return, points to the variable's value. 5757 </description> 5758 </param> 5759 </parameters> 5760 <errors> 5761 <error id="JVMTI_ERROR_INVALID_SLOT"> 5762 If the specified frame is a static method frame. 5763 </error> 5764 </errors> 5765 </function> 5766 <function id="GetLocalInt" num="22"> 5767 <synopsis>Get Local Variable - Int</synopsis> 5768 <description> 5769 This function can be used to retrieve the value of a local 5770 variable whose type is <code>int</code>, 5771 <code>short</code>, <code>char</code>, <code>byte</code>, or 5772 <code>boolean</code>. 5773 </description> 5774 <origin>jvmdi</origin> 5775 <capabilities> 5776 <required id="can_access_local_variables"></required> 5777 </capabilities> 5778 <parameters> 5779 <param id="thread"> 5780 <jthread null="current" frame="frame"/> 5781 <description> 5782 The thread of the frame containing the variable's value. 5783 </description> 5784 </param> 5785 <param id="depth"> 5786 <jframeID thread="thread"/> 5787 <description> 5788 The depth of the frame containing the variable's value. 5789 </description> 5790 </param> 5791 <param id="slot"> 5792 <jint/> 5793 <description> 5794 The variable's slot number. 5795 </description> 5796 </param> 5797 <param id="value_ptr"> 5798 <outptr><jint/></outptr> 5799 <description> 5800 On return, points to the variable's value. 5801 </description> 5802 </param> 5803 </parameters> 5804 <errors> 5805 <error id="JVMTI_ERROR_INVALID_SLOT"> 5806 Invalid <code>slot</code>. 5807 </error> 5808 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 5809 The variable type is not 5810 <code>int</code>, <code>short</code>, 5811 <code>char</code>, <code>byte</code>, or 5812 <code>boolean</code>. 5813 </error> 5814 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 5815 Not a visible frame 5816 </error> 5817 </errors> 5818 </function> 5819 5820 <function id="GetLocalLong" num="23"> 5821 <synopsis>Get Local Variable - Long</synopsis> 5822 <description> 5823 This function can be used to retrieve the value of a local 5824 variable whose type is <code>long</code>. 5825 </description> 5826 <origin>jvmdi</origin> 5827 <capabilities> 5828 <required id="can_access_local_variables"></required> 5829 </capabilities> 5830 <parameters> 5831 <param id="thread"> 5832 <jthread null="current" frame="frame"/> 5833 <description> 5834 The thread of the frame containing the variable's value. 5835 </description> 5836 </param> 5837 <param id="depth"> 5838 <jframeID thread="thread"/> 5839 <description> 5840 The depth of the frame containing the variable's value. 5841 </description> 5842 </param> 5843 <param id="slot"> 5844 <jint/> 5845 <description> 5846 The variable's slot number. 5847 </description> 5848 </param> 5849 <param id="value_ptr"> 5850 <outptr><jlong/></outptr> 5851 <description> 5852 On return, points to the variable's value. 5853 </description> 5854 </param> 5855 </parameters> 5856 <errors> 5857 <error id="JVMTI_ERROR_INVALID_SLOT"> 5858 Invalid <code>slot</code>. 5859 </error> 5860 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 5861 The variable type is not <code>long</code>. 5862 </error> 5863 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 5864 Not a visible frame 5865 </error> 5866 </errors> 5867 </function> 5868 5869 <function id="GetLocalFloat" num="24"> 5870 <synopsis>Get Local Variable - Float</synopsis> 5871 <description> 5872 This function can be used to retrieve the value of a local 5873 variable whose type is <code>float</code>. 5874 </description> 5875 <origin>jvmdi</origin> 5876 <capabilities> 5877 <required id="can_access_local_variables"></required> 5878 </capabilities> 5879 <parameters> 5880 <param id="thread"> 5881 <jthread null="current" frame="frame"/> 5882 <description> 5883 The thread of the frame containing the variable's value. 5884 </description> 5885 </param> 5886 <param id="depth"> 5887 <jframeID thread="thread"/> 5888 <description> 5889 The depth of the frame containing the variable's value. 5890 </description> 5891 </param> 5892 <param id="slot"> 5893 <jint/> 5894 <description> 5895 The variable's slot number. 5896 </description> 5897 </param> 5898 <param id="value_ptr"> 5899 <outptr><jfloat/></outptr> 5900 <description> 5901 On return, points to the variable's value. 5902 </description> 5903 </param> 5904 </parameters> 5905 <errors> 5906 <error id="JVMTI_ERROR_INVALID_SLOT"> 5907 Invalid <code>slot</code>. 5908 </error> 5909 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 5910 The variable type is not <code>float</code>. 5911 </error> 5912 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 5913 Not a visible frame 5914 </error> 5915 </errors> 5916 </function> 5917 5918 <function id="GetLocalDouble" num="25"> 5919 <synopsis>Get Local Variable - Double</synopsis> 5920 <description> 5921 This function can be used to retrieve the value of a local 5922 variable whose type is <code>long</code>. 5923 </description> 5924 <origin>jvmdi</origin> 5925 <capabilities> 5926 <required id="can_access_local_variables"></required> 5927 </capabilities> 5928 <parameters> 5929 <param id="thread"> 5930 <jthread null="current" frame="frame"/> 5931 <description> 5932 The thread of the frame containing the variable's value. 5933 </description> 5934 </param> 5935 <param id="depth"> 5936 <jframeID thread="thread"/> 5937 <description> 5938 The depth of the frame containing the variable's value. 5939 </description> 5940 </param> 5941 <param id="slot"> 5942 <jint/> 5943 <description> 5944 The variable's slot number. 5945 </description> 5946 </param> 5947 <param id="value_ptr"> 5948 <outptr><jdouble/></outptr> 5949 <description> 5950 On return, points to the variable's value. 5951 </description> 5952 </param> 5953 </parameters> 5954 <errors> 5955 <error id="JVMTI_ERROR_INVALID_SLOT"> 5956 Invalid <code>slot</code>. 5957 </error> 5958 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 5959 The variable type is not <code>double</code>. 5960 </error> 5961 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 5962 Not a visible frame 5963 </error> 5964 </errors> 5965 </function> 5966 5967 <function id="SetLocalObject" num="26"> 5968 <synopsis>Set Local Variable - Object</synopsis> 5969 <description> 5970 This function can be used to set the value of a local 5971 variable whose type is <code>Object</code> or a subclass of <code>Object</code>. 5972 </description> 5973 <origin>jvmdi</origin> 5974 <capabilities> 5975 <required id="can_access_local_variables"></required> 5976 </capabilities> 5977 <parameters> 5978 <param id="thread"> 5979 <jthread null="current" frame="frame"/> 5980 <description> 5981 The thread of the frame containing the variable's value. 5982 </description> 5983 </param> 5984 <param id="depth"> 5985 <jframeID thread="thread"/> 5986 <description> 5987 The depth of the frame containing the variable's value. 5988 </description> 5989 </param> 5990 <param id="slot"> 5991 <jint/> 5992 <description> 5993 The variable's slot number. 5994 </description> 5995 </param> 5996 <param id="value"> 5997 <jobject/> 5998 <description> 5999 The new value for the variable. 6000 </description> 6001 </param> 6002 </parameters> 6003 <errors> 6004 <error id="JVMTI_ERROR_INVALID_SLOT"> 6005 Invalid <code>slot</code>. 6006 </error> 6007 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 6008 The variable type is not 6009 <code>Object</code> or a subclass of <code>Object</code>. 6010 </error> 6011 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 6012 The supplied <paramlink id="value"/> is not compatible 6013 with the variable type. 6014 </error> 6015 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 6016 Not a visible frame 6017 </error> 6018 </errors> 6019 </function> 6020 6021 <function id="SetLocalInt" num="27"> 6022 <synopsis>Set Local Variable - Int</synopsis> 6023 <description> 6024 This function can be used to set the value of a local 6025 variable whose type is <code>int</code>, 6026 <code>short</code>, <code>char</code>, <code>byte</code>, or 6027 <code>boolean</code>. 6028 </description> 6029 <origin>jvmdi</origin> 6030 <capabilities> 6031 <required id="can_access_local_variables"></required> 6032 </capabilities> 6033 <parameters> 6034 <param id="thread"> 6035 <jthread null="current" frame="frame"/> 6036 <description> 6037 The thread of the frame containing the variable's value. 6038 </description> 6039 </param> 6040 <param id="depth"> 6041 <jframeID thread="thread"/> 6042 <description> 6043 The depth of the frame containing the variable's value. 6044 </description> 6045 </param> 6046 <param id="slot"> 6047 <jint/> 6048 <description> 6049 The variable's slot number. 6050 </description> 6051 </param> 6052 <param id="value"> 6053 <jint/> 6054 <description> 6055 The new value for the variable. 6056 </description> 6057 </param> 6058 </parameters> 6059 <errors> 6060 <error id="JVMTI_ERROR_INVALID_SLOT"> 6061 Invalid <code>slot</code>. 6062 </error> 6063 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 6064 The variable type is not 6065 <code>int</code>, <code>short</code>, 6066 <code>char</code>, <code>byte</code>, or 6067 <code>boolean</code>. 6068 </error> 6069 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 6070 Not a visible frame 6071 </error> 6072 </errors> 6073 </function> 6074 6075 <function id="SetLocalLong" num="28"> 6076 <synopsis>Set Local Variable - Long</synopsis> 6077 <description> 6078 This function can be used to set the value of a local 6079 variable whose type is <code>long</code>. 6080 </description> 6081 <origin>jvmdi</origin> 6082 <capabilities> 6083 <required id="can_access_local_variables"></required> 6084 </capabilities> 6085 <parameters> 6086 <param id="thread"> 6087 <jthread null="current" frame="frame"/> 6088 <description> 6089 The thread of the frame containing the variable's value. 6090 </description> 6091 </param> 6092 <param id="depth"> 6093 <jframeID thread="thread"/> 6094 <description> 6095 The depth of the frame containing the variable's value. 6096 </description> 6097 </param> 6098 <param id="slot"> 6099 <jint/> 6100 <description> 6101 The variable's slot number. 6102 </description> 6103 </param> 6104 <param id="value"> 6105 <jlong/> 6106 <description> 6107 The new value for the variable. 6108 </description> 6109 </param> 6110 </parameters> 6111 <errors> 6112 <error id="JVMTI_ERROR_INVALID_SLOT"> 6113 Invalid <code>slot</code>. 6114 </error> 6115 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 6116 The variable type is not <code>long</code>. 6117 </error> 6118 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 6119 Not a visible frame 6120 </error> 6121 </errors> 6122 </function> 6123 6124 <function id="SetLocalFloat" num="29"> 6125 <synopsis>Set Local Variable - Float</synopsis> 6126 <description> 6127 This function can be used to set the value of a local 6128 variable whose type is <code>float</code>. 6129 </description> 6130 <origin>jvmdi</origin> 6131 <capabilities> 6132 <required id="can_access_local_variables"></required> 6133 </capabilities> 6134 <parameters> 6135 <param id="thread"> 6136 <jthread null="current" frame="frame"/> 6137 <description> 6138 The thread of the frame containing the variable's value. 6139 </description> 6140 </param> 6141 <param id="depth"> 6142 <jframeID thread="thread"/> 6143 <description> 6144 The depth of the frame containing the variable's value. 6145 </description> 6146 </param> 6147 <param id="slot"> 6148 <jint/> 6149 <description> 6150 The variable's slot number. 6151 </description> 6152 </param> 6153 <param id="value"> 6154 <jfloat/> 6155 <description> 6156 The new value for the variable. 6157 </description> 6158 </param> 6159 </parameters> 6160 <errors> 6161 <error id="JVMTI_ERROR_INVALID_SLOT"> 6162 Invalid <code>slot</code>. 6163 </error> 6164 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 6165 The variable type is not <code>float</code>. 6166 </error> 6167 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 6168 Not a visible frame 6169 </error> 6170 </errors> 6171 </function> 6172 6173 <function id="SetLocalDouble" num="30"> 6174 <synopsis>Set Local Variable - Double</synopsis> 6175 <description> 6176 This function can be used to set the value of a local 6177 variable whose type is <code>double</code>. 6178 </description> 6179 <origin>jvmdi</origin> 6180 <capabilities> 6181 <required id="can_access_local_variables"></required> 6182 </capabilities> 6183 <parameters> 6184 <param id="thread"> 6185 <jthread null="current" frame="frame"/> 6186 <description> 6187 The thread of the frame containing the variable's value. 6188 </description> 6189 </param> 6190 <param id="depth"> 6191 <jframeID thread="thread"/> 6192 <description> 6193 The depth of the frame containing the variable's value. 6194 </description> 6195 </param> 6196 <param id="slot"> 6197 <jint/> 6198 <description> 6199 The variable's slot number. 6200 </description> 6201 </param> 6202 <param id="value"> 6203 <jdouble/> 6204 <description> 6205 The new value for the variable. 6206 </description> 6207 </param> 6208 </parameters> 6209 <errors> 6210 <error id="JVMTI_ERROR_INVALID_SLOT"> 6211 Invalid <code>slot</code>. 6212 </error> 6213 <error id="JVMTI_ERROR_TYPE_MISMATCH"> 6214 The variable type is not <code>double</code>. 6215 </error> 6216 <error id="JVMTI_ERROR_OPAQUE_FRAME"> 6217 Not a visible frame 6218 </error> 6219 </errors> 6220 </function> 6221 </category> 6222 6223 <category id="breakpointCategory" label="Breakpoint"> 6224 6225 <intro> 6226 </intro> 6227 6228 <function id="SetBreakpoint" num="38"> 6229 <synopsis>Set Breakpoint</synopsis> 6230 <description> 6231 Set a breakpoint at the instruction indicated by 6232 <code>method</code> and <code>location</code>. 6233 An instruction can only have one breakpoint. 6234 <p/> 6235 Whenever the designated instruction is about to be executed, a 6236 <eventlink id="Breakpoint"></eventlink> event is generated. 6237 </description> 6238 <origin>jvmdi</origin> 6239 <capabilities> 6240 <required id="can_generate_breakpoint_events"></required> 6241 </capabilities> 6242 <parameters> 6243 <param id="klass"> 6244 <jclass method="method"/> 6245 <description> 6246 The class in which to set the breakpoint 6247 </description> 6248 </param> 6249 <param id="method"> 6250 <jmethodID class="klass"/> 6251 <description> 6252 The method in which to set the breakpoint 6253 </description> 6254 </param> 6255 <param id="location"> 6256 <jlocation/> 6257 <description> 6258 the index of the instruction at which to set the breakpoint 6259 6260 </description> 6261 </param> 6262 </parameters> 6263 <errors> 6264 <error id="JVMTI_ERROR_DUPLICATE"> 6265 The designated bytecode already has a breakpoint. 6266 </error> 6267 </errors> 6268 </function> 6269 6270 <function id="ClearBreakpoint" num="39"> 6271 <synopsis>Clear Breakpoint</synopsis> 6272 <description> 6273 Clear the breakpoint at the bytecode indicated by 6274 <code>method</code> and <code>location</code>. 6275 </description> 6276 <origin>jvmdi</origin> 6277 <capabilities> 6278 <required id="can_generate_breakpoint_events"></required> 6279 </capabilities> 6280 <parameters> 6281 <param id="klass"> 6282 <jclass method="method"/> 6283 <description> 6284 The class in which to clear the breakpoint 6285 </description> 6286 </param> 6287 <param id="method"> 6288 <jmethodID class="klass"/> 6289 <description> 6290 The method in which to clear the breakpoint 6291 </description> 6292 </param> 6293 <param id="location"> 6294 <jlocation/> 6295 <description> 6296 the index of the instruction at which to clear the breakpoint 6297 </description> 6298 </param> 6299 </parameters> 6300 <errors> 6301 <error id="JVMTI_ERROR_NOT_FOUND"> 6302 There's no breakpoint at the designated bytecode. 6303 </error> 6304 </errors> 6305 </function> 6306 6307 </category> 6308 6309 <category id="fieldWatch" label="Watched Field"> 6310 6311 <intro> 6312 </intro> 6313 6314 <function id="SetFieldAccessWatch" num="41"> 6315 <synopsis>Set Field Access Watch</synopsis> 6316 <description> 6317 Generate a <eventlink id="FieldAccess"></eventlink> event 6318 when the field specified 6319 by <code>klass</code> and 6320 <code>field</code> is about to be accessed. 6321 An event will be generated for each access of the field 6322 until it is canceled with 6323 <functionlink id="ClearFieldAccessWatch"></functionlink>. 6324 Field accesses from Java programming language code or from JNI code are watched, 6325 fields modified by other means are not watched. 6326 Note that <jvmti/> users should be aware that their own field accesses 6327 will trigger the watch. 6328 A field can only have one field access watch set. 6329 Modification of a field is not considered an access--use 6330 <functionlink id="SetFieldModificationWatch"></functionlink> 6331 to monitor modifications. 6332 </description> 6333 <origin>jvmdi</origin> 6334 <capabilities> 6335 <required id="can_generate_field_access_events"></required> 6336 </capabilities> 6337 <parameters> 6338 <param id="klass"> 6339 <jclass field="field"/> 6340 <description> 6341 The class containing the field to watch 6342 </description> 6343 </param> 6344 <param id="field"> 6345 <jfieldID class="klass"/> 6346 <description> 6347 The field to watch 6348 6349 </description> 6350 </param> 6351 </parameters> 6352 <errors> 6353 <error id="JVMTI_ERROR_DUPLICATE"> 6354 The designated field is already being watched for accesses. 6355 </error> 6356 </errors> 6357 </function> 6358 6359 <function id="ClearFieldAccessWatch" num="42"> 6360 <synopsis>Clear Field Access Watch</synopsis> 6361 <description> 6362 Cancel a field access watch previously set by 6363 <functionlink id="SetFieldAccessWatch"></functionlink>, on the 6364 field specified 6365 by <code>klass</code> and 6366 <code>field</code>. 6367 </description> 6368 <origin>jvmdi</origin> 6369 <capabilities> 6370 <required id="can_generate_field_access_events"></required> 6371 </capabilities> 6372 <parameters> 6373 <param id="klass"> 6374 <jclass field="field"/> 6375 <description> 6376 The class containing the field to watch 6377 </description> 6378 </param> 6379 <param id="field"> 6380 <jfieldID class="klass"/> 6381 <description> 6382 The field to watch 6383 6384 </description> 6385 </param> 6386 </parameters> 6387 <errors> 6388 <error id="JVMTI_ERROR_NOT_FOUND"> 6389 The designated field is not being watched for accesses. 6390 </error> 6391 </errors> 6392 </function> 6393 6394 <function id="SetFieldModificationWatch" num="43"> 6395 <synopsis>Set Field Modification Watch</synopsis> 6396 <description> 6397 Generate a <eventlink id="FieldModification"></eventlink> event 6398 when the field specified 6399 by <code>klass</code> and 6400 <code>field</code> is about to be modified. 6401 An event will be generated for each modification of the field 6402 until it is canceled with 6403 <functionlink id="ClearFieldModificationWatch"></functionlink>. 6404 Field modifications from Java programming language code or from JNI code are watched, 6405 fields modified by other means are not watched. 6406 Note that <jvmti/> users should be aware that their own field modifications 6407 will trigger the watch. 6408 A field can only have one field modification watch set. 6409 </description> 6410 <origin>jvmdi</origin> 6411 <capabilities> 6412 <required id="can_generate_field_modification_events"></required> 6413 </capabilities> 6414 <parameters> 6415 <param id="klass"> 6416 <jclass field="field"/> 6417 <description> 6418 The class containing the field to watch 6419 </description> 6420 </param> 6421 <param id="field"> 6422 <jfieldID class="klass"/> 6423 <description> 6424 The field to watch 6425 6426 </description> 6427 </param> 6428 </parameters> 6429 <errors> 6430 <error id="JVMTI_ERROR_DUPLICATE"> 6431 The designated field is already being watched for modifications. 6432 </error> 6433 </errors> 6434 </function> 6435 6436 <function id="ClearFieldModificationWatch" num="44"> 6437 <synopsis>Clear Field Modification Watch</synopsis> 6438 <description> 6439 6440 Cancel a field modification watch previously set by 6441 <functionlink id="SetFieldModificationWatch"></functionlink>, on the 6442 field specified 6443 by <code>klass</code> and 6444 <code>field</code>. 6445 </description> 6446 <origin>jvmdi</origin> 6447 <capabilities> 6448 <required id="can_generate_field_modification_events"></required> 6449 </capabilities> 6450 <parameters> 6451 <param id="klass"> 6452 <jclass field="field"/> 6453 <description> 6454 The class containing the field to watch 6455 </description> 6456 </param> 6457 <param id="field"> 6458 <jfieldID class="klass"/> 6459 <description> 6460 The field to watch 6461 6462 </description> 6463 </param> 6464 </parameters> 6465 <errors> 6466 <error id="JVMTI_ERROR_NOT_FOUND"> 6467 The designated field is not being watched for modifications. 6468 </error> 6469 </errors> 6470 </function> 6471 </category> 6472 6473 <category id="module" label="Module"> 6474 6475 <intro> 6476 </intro> 6477 6478 <function id="GetAllModules" num="3" since="9"> 6479 <synopsis>Get All Modules</synopsis> 6480 <description> 6481 Return an array of all modules loaded in the virtual machine. 6482 The array includes the unnamed module for each class loader. 6483 The number of modules in the array is returned via 6484 <code>module_count_ptr</code>, and the array itself via 6485 <code>modules_ptr</code>. 6486 <p/> 6487 </description> 6488 <origin>new</origin> 6489 <capabilities> 6490 </capabilities> 6491 <parameters> 6492 <param id="module_count_ptr"> 6493 <outptr><jint/></outptr> 6494 <description> 6495 On return, points to the number of returned modules. 6496 </description> 6497 </param> 6498 <param id="modules_ptr"> 6499 <allocbuf outcount="module_count_ptr"><jobject/></allocbuf> 6500 <description> 6501 On return, points to an array of references, one 6502 for each module. 6503 </description> 6504 </param> 6505 </parameters> 6506 <errors> 6507 </errors> 6508 </function> 6509 6510 <function id="GetNamedModule" num="40" since="9"> 6511 <synopsis>Get Named Module</synopsis> 6512 <description> 6513 Return the <code>java.lang.reflect.Module</code> object for a named 6514 module defined to a class loader that contains a given package. 6515 The module is returned via <code>module_ptr</code>. 6516 <p/> 6517 If a named module is defined to the class loader and it 6518 contains the package then that named module is returned, 6519 otherwise <code>NULL</code> is returned. 6520 <p/> 6521 </description> 6522 <origin>new</origin> 6523 <capabilities> 6524 </capabilities> 6525 <parameters> 6526 <param id="class_loader"> 6527 <ptrtype> 6528 <jobject/> 6529 <nullok>the bootstrap loader is assumed</nullok> 6530 </ptrtype> 6531 <description> 6532 A class loader. 6533 If the <code>class_loader</code> is not <code>NULL</code> 6534 or a subclass of <code>java.lang.ClassLoader</code> 6535 this function returns 6536 <errorlink id="JVMTI_ERROR_ILLEGAL_ARGUMENT"></errorlink>. 6537 </description> 6538 </param> 6539 <param id="package_name"> 6540 <inbuf><char/></inbuf> 6541 <description> 6542 The name of the package, encoded as a 6543 <internallink id="mUTF">modified UTF-8</internallink> string. 6544 The package name is in internal form (JVMS 4.2.1); 6545 identifiers are separated by forward slashes rather than periods. 6546 </description> 6547 </param> 6548 <param id="module_ptr"> 6549 <outptr><jobject/></outptr> 6550 <description> 6551 On return, points to a <code>java.lang.reflect.Module</code> object 6552 or points to <code>NULL</code>. 6553 </description> 6554 </param> 6555 </parameters> 6556 <errors> 6557 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 6558 If class loader is not <code>NULL</code> and is not a class loader object. 6559 </error> 6560 </errors> 6561 </function> 6562 6563 <function id="AddModuleReads" num="94" since="9"> 6564 <synopsis>Add Module Reads</synopsis> 6565 <description> 6566 Update a module to read another module. This function is a no-op 6567 when <paramlink id="module"></paramlink> is an unnamed module. 6568 This function facilitates the instrumentation of code 6569 in named modules where that instrumentation requires 6570 expanding the set of modules that a module reads. 6571 </description> 6572 <origin>new</origin> 6573 <capabilities> 6574 </capabilities> 6575 <parameters> 6576 <param id="module"> 6577 <ptrtype><jobject/></ptrtype> 6578 <description> 6579 The module to update. 6580 </description> 6581 </param> 6582 <param id="to_module"> 6583 <ptrtype><jobject/></ptrtype> 6584 <description> 6585 The additional module to read. 6586 </description> 6587 </param> 6588 </parameters> 6589 <errors> 6590 <error id="JVMTI_ERROR_INVALID_MODULE"> 6591 If <paramlink id="module"></paramlink> is not a module object. 6592 </error> 6593 <error id="JVMTI_ERROR_INVALID_MODULE"> 6594 If <paramlink id="to_module"></paramlink> is not a module object. 6595 </error> 6596 </errors> 6597 </function> 6598 6599 <function id="AddModuleExports" num="95" since="9"> 6600 <synopsis>Add Module Exports</synopsis> 6601 <description> 6602 Update a module to export a package to another module. 6603 This function is a no-op when <paramlink id="module"></paramlink> 6604 is an unnamed module or an open module. 6605 This function facilitates the instrumentation of code 6606 in named modules where that instrumentation requires 6607 expanding the set of packages that a module exports. 6608 </description> 6609 <origin>new</origin> 6610 <capabilities> 6611 </capabilities> 6612 <parameters> 6613 <param id="module"> 6614 <ptrtype><jobject/></ptrtype> 6615 <description> 6616 The module to update. 6617 </description> 6618 </param> 6619 <param id="pkg_name"> 6620 <inbuf><char/></inbuf> 6621 <description> 6622 The exported package name. 6623 </description> 6624 </param> 6625 <param id="to_module"> 6626 <ptrtype><jobject/></ptrtype> 6627 <description> 6628 The module the package is exported to. 6629 If the <code>to_module</code> is not a subclass of 6630 <code>java.lang.reflect.Module</code> this function returns 6631 <errorlink id="JVMTI_ERROR_INVALID_MODULE"></errorlink>. 6632 </description> 6633 </param> 6634 </parameters> 6635 <errors> 6636 <error id="JVMTI_ERROR_INVALID_MODULE"> 6637 If <paramlink id="module"></paramlink> is not a module object. 6638 </error> 6639 <error id="JVMTI_ERROR_INVALID_MODULE"> 6640 If <paramlink id="to_modules"></paramlink> is not a module object. 6641 </error> 6642 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 6643 If the package <paramlink id="pkg_name"></paramlink> 6644 does not belong to the module. 6645 </error> 6646 </errors> 6647 </function> 6648 6649 <function id="AddModuleOpens" num="96" since="9"> 6650 <synopsis>Add Module Opens</synopsis> 6651 <description> 6652 Update a module to open a package to another module. 6653 This function is a no-op when <paramlink id="module"></paramlink> 6654 is an unnamed module or an open module. 6655 This function facilitates the instrumentation of code 6656 in modules where that instrumentation requires 6657 expanding the set of packages that a module opens to 6658 other modules. 6659 </description> 6660 <origin>new</origin> 6661 <capabilities> 6662 </capabilities> 6663 <parameters> 6664 <param id="module"> 6665 <ptrtype><jobject/></ptrtype> 6666 <description> 6667 The module to update. 6668 </description> 6669 </param> 6670 <param id="pkg_name"> 6671 <inbuf><char/></inbuf> 6672 <description> 6673 The package name of the package to open. 6674 </description> 6675 </param> 6676 <param id="to_module"> 6677 <ptrtype><jobject/></ptrtype> 6678 <description> 6679 The module with the package to open. 6680 If the <code>to_module</code> is not a subclass of 6681 <code>java.lang.reflect.Module</code> this function returns 6682 <errorlink id="JVMTI_ERROR_INVALID_MODULE"></errorlink>. 6683 </description> 6684 </param> 6685 </parameters> 6686 <errors> 6687 <error id="JVMTI_ERROR_INVALID_MODULE"> 6688 If <paramlink id="module"></paramlink> is not a module object. 6689 </error> 6690 <error id="JVMTI_ERROR_INVALID_MODULE"> 6691 If <paramlink id="to_modules"></paramlink> is not a module object. 6692 </error> 6693 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 6694 If the package <paramlink id="pkg_name"></paramlink> 6695 does not belong to the module. 6696 </error> 6697 </errors> 6698 </function> 6699 6700 <function id="AddModuleUses" num="97" since="9"> 6701 <synopsis>Add Module Uses</synopsis> 6702 <description> 6703 Updates a module to add a service to the set of services that 6704 a module uses. This function is a no-op when the module 6705 is an unnamed module. 6706 This function facilitates the instrumentation of code 6707 in named modules where that instrumentation requires 6708 expanding the set of services that a module is using. 6709 </description> 6710 <origin>new</origin> 6711 <capabilities> 6712 </capabilities> 6713 <parameters> 6714 <param id="module"> 6715 <ptrtype><jobject/></ptrtype> 6716 <description> 6717 The module to update. 6718 </description> 6719 </param> 6720 <param id="service"> 6721 <ptrtype><jclass/></ptrtype> 6722 <description> 6723 The service to use. 6724 </description> 6725 </param> 6726 </parameters> 6727 <errors> 6728 <error id="JVMTI_ERROR_INVALID_MODULE"> 6729 If <paramlink id="module"></paramlink> is not a module object. 6730 </error> 6731 <error id="JVMTI_ERROR_INVALID_CLASS"> 6732 If <paramlink id="service"></paramlink> is not a class object. 6733 </error> 6734 </errors> 6735 </function> 6736 6737 <function id="AddModuleProvides" num="98" since="9"> 6738 <synopsis>Add Module Provides</synopsis> 6739 <description> 6740 Updates a module to add a service to the set of services that 6741 a module provides. This function is a no-op when the module 6742 is an unnamed module. 6743 This function facilitates the instrumentation of code 6744 in named modules where that instrumentation requires 6745 changes to the services that are provided. 6746 </description> 6747 <origin>new</origin> 6748 <capabilities> 6749 </capabilities> 6750 <parameters> 6751 <param id="module"> 6752 <ptrtype><jobject/></ptrtype> 6753 <description> 6754 The module to update. 6755 </description> 6756 </param> 6757 <param id="service"> 6758 <ptrtype><jclass/></ptrtype> 6759 <description> 6760 The service to provide. 6761 </description> 6762 </param> 6763 <param id="impl_class"> 6764 <ptrtype><jclass/></ptrtype> 6765 <description> 6766 The implementation class for the provided service. 6767 </description> 6768 </param> 6769 </parameters> 6770 <errors> 6771 <error id="JVMTI_ERROR_INVALID_MODULE"> 6772 If <paramlink id="module"></paramlink> is not a module object. 6773 </error> 6774 <error id="JVMTI_ERROR_INVALID_CLASS"> 6775 If <paramlink id="service"></paramlink> is not a class object. 6776 </error> 6777 <error id="JVMTI_ERROR_INVALID_CLASS"> 6778 If <paramlink id="impl_class"></paramlink> is not a class object. 6779 </error> 6780 </errors> 6781 </function> 6782 6783 </category> 6784 6785 <category id="class" label="Class"> 6786 6787 <intro> 6788 </intro> 6789 6790 <function id="GetLoadedClasses" jkernel="yes" num="78"> 6791 <synopsis>Get Loaded Classes</synopsis> 6792 <description> 6793 Return an array of all classes loaded in the virtual machine. 6794 The number of classes in the array is returned via 6795 <code>class_count_ptr</code>, and the array itself via 6796 <code>classes_ptr</code>. 6797 <p/> 6798 Array classes of all types (including arrays of primitive types) are 6799 included in the returned list. Primitive classes (for example, 6800 <code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list. 6801 </description> 6802 <origin>jvmdi</origin> 6803 <capabilities> 6804 </capabilities> 6805 <parameters> 6806 <param id="class_count_ptr"> 6807 <outptr><jint/></outptr> 6808 <description> 6809 On return, points to the number of classes. 6810 </description> 6811 </param> 6812 <param id="classes_ptr"> 6813 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf> 6814 <description> 6815 On return, points to an array of references, one 6816 for each class. 6817 </description> 6818 </param> 6819 </parameters> 6820 <errors> 6821 </errors> 6822 </function> 6823 6824 <function id="GetClassLoaderClasses" jkernel="yes" num="79"> 6825 <synopsis>Get Classloader Classes</synopsis> 6826 <description> 6827 Returns an array of those classes for which this class loader has 6828 been recorded as an initiating loader. Each 6829 class in the returned array was created by this class loader, 6830 either by defining it directly or by delegation to another class loader. 6831 See <vmspec chapter="5.3"/>. 6832 <p/> 6833 The number of classes in the array is returned via 6834 <code>class_count_ptr</code>, and the array itself via 6835 <code>classes_ptr</code>. 6836 </description> 6837 <origin>jvmdi</origin> 6838 <capabilities> 6839 </capabilities> 6840 <parameters> 6841 <param id="initiating_loader"> 6842 <ptrtype> 6843 <jobject/> 6844 <nullok>the classes initiated by the bootstrap loader will be returned</nullok> 6845 </ptrtype> 6846 <description> 6847 An initiating class loader. 6848 </description> 6849 </param> 6850 <param id="class_count_ptr"> 6851 <outptr><jint/></outptr> 6852 <description> 6853 On return, points to the number of classes. 6854 </description> 6855 </param> 6856 <param id="classes_ptr"> 6857 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf> 6858 <description> 6859 On return, points to an array of references, one 6860 for each class. 6861 </description> 6862 </param> 6863 </parameters> 6864 <errors> 6865 </errors> 6866 </function> 6867 6868 <function id="GetClassSignature" phase="start" num="48"> 6869 <synopsis>Get Class Signature</synopsis> 6870 <description> 6871 For the class indicated by <code>klass</code>, return the 6872 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16432">JNI 6873 type signature</externallink> 6874 and the generic signature of the class. 6875 For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code> 6876 and <code>int[]</code> is <code>"[I"</code> 6877 The returned name for primitive classes 6878 is the type signature character of the corresponding primitive type. 6879 For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>. 6880 </description> 6881 <origin>jvmdiClone</origin> 6882 <capabilities> 6883 </capabilities> 6884 <parameters> 6885 <param id="klass"> 6886 <jclass/> 6887 <description> 6888 The class to query. 6889 </description> 6890 </param> 6891 <param id="signature_ptr"> 6892 <allocbuf> 6893 <char/> 6894 <nullok>the signature is not returned</nullok> 6895 </allocbuf> 6896 <description> 6897 On return, points to the JNI type signature of the class, encoded as a 6898 <internallink id="mUTF">modified UTF-8</internallink> string. 6899 </description> 6900 </param> 6901 <param id="generic_ptr"> 6902 <allocbuf> 6903 <char/> 6904 <nullok>the generic signature is not returned</nullok> 6905 </allocbuf> 6906 <description> 6907 On return, points to the generic signature of the class, encoded as a 6908 <internallink id="mUTF">modified UTF-8</internallink> string. 6909 If there is no generic signature attribute for the class, then, 6910 on return, points to <code>NULL</code>. 6911 </description> 6912 </param> 6913 </parameters> 6914 <errors> 6915 </errors> 6916 </function> 6917 6918 <function id="GetClassStatus" phase="start" num="49"> 6919 <synopsis>Get Class Status</synopsis> 6920 <description> 6921 Get the status of the class. Zero or more of the following bits can be 6922 set. 6923 <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits"> 6924 <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1"> 6925 Class bytecodes have been verified 6926 </constant> 6927 <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2"> 6928 Class preparation is complete 6929 </constant> 6930 <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4"> 6931 Class initialization is complete. Static initializer has been run. 6932 </constant> 6933 <constant id="JVMTI_CLASS_STATUS_ERROR" num="8"> 6934 Error during initialization makes class unusable 6935 </constant> 6936 <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16"> 6937 Class is an array. If set, all other bits are zero. 6938 </constant> 6939 <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32"> 6940 Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>). 6941 If set, all other bits are zero. 6942 </constant> 6943 </constants> 6944 </description> 6945 <origin>jvmdi</origin> 6946 <capabilities> 6947 </capabilities> 6948 <parameters> 6949 <param id="klass"> 6950 <jclass/> 6951 <description> 6952 The class to query. 6953 </description> 6954 </param> 6955 <param id="status_ptr"> 6956 <outptr><jint/></outptr> 6957 <description> 6958 On return, points to the current state of this class as one or 6959 more of the <internallink id="jvmtiClassStatus">class status flags</internallink>. 6960 </description> 6961 </param> 6962 </parameters> 6963 <errors> 6964 </errors> 6965 </function> 6966 6967 <function id="GetSourceFileName" phase="start" num="50"> 6968 <synopsis>Get Source File Name</synopsis> 6969 <description> 6970 For the class indicated by <code>klass</code>, return the source file 6971 name via <code>source_name_ptr</code>. The returned string 6972 is a file name only and never contains a directory name. 6973 <p/> 6974 For primitive classes (for example, <code>java.lang.Integer.TYPE</code>) 6975 and for arrays this function returns 6976 <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>. 6977 </description> 6978 <origin>jvmdi</origin> 6979 <capabilities> 6980 <required id="can_get_source_file_name"></required> 6981 </capabilities> 6982 <parameters> 6983 <param id="klass"> 6984 <jclass/> 6985 <description> 6986 The class to query. 6987 </description> 6988 </param> 6989 <param id="source_name_ptr"> 6990 <allocbuf><char/></allocbuf> 6991 <description> 6992 On return, points to the class's source file name, encoded as a 6993 <internallink id="mUTF">modified UTF-8</internallink> string. 6994 </description> 6995 </param> 6996 </parameters> 6997 <errors> 6998 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 6999 Class information does not include a source file name. This includes 7000 cases where the class is an array class or primitive class. 7001 </error> 7002 </errors> 7003 </function> 7004 7005 <function id="GetClassModifiers" phase="start" num="51"> 7006 <synopsis>Get Class Modifiers</synopsis> 7007 <description> 7008 For the class indicated by <code>klass</code>, return the access 7009 flags 7010 via <code>modifiers_ptr</code>. 7011 Access flags are defined in <vmspec chapter="4"/>. 7012 <p/> 7013 If the class is an array class, then its public, private, and protected 7014 modifiers are the same as those of its component type. For arrays of 7015 primitives, this component type is represented by one of the primitive 7016 classes (for example, <code>java.lang.Integer.TYPE</code>). 7017 <p/> 7018 If the class is a primitive class, its public modifier is always true, 7019 and its protected and private modifiers are always false. 7020 <p/> 7021 If the class is an array class or a primitive class then its final 7022 modifier is always true and its interface modifier is always false. 7023 The values of its other modifiers are not determined by this specification. 7024 7025 </description> 7026 <origin>jvmdi</origin> 7027 <capabilities> 7028 </capabilities> 7029 <parameters> 7030 <param id="klass"> 7031 <jclass/> 7032 <description> 7033 The class to query. 7034 </description> 7035 </param> 7036 <param id="modifiers_ptr"> 7037 <outptr><jint/></outptr> 7038 <description> 7039 On return, points to the current access flags of this class. 7040 7041 </description> 7042 </param> 7043 </parameters> 7044 <errors> 7045 </errors> 7046 </function> 7047 7048 <function id="GetClassMethods" phase="start" num="52"> 7049 <synopsis>Get Class Methods</synopsis> 7050 <description> 7051 For the class indicated by <code>klass</code>, return a count of 7052 methods via <code>method_count_ptr</code> and a list of 7053 method IDs via <code>methods_ptr</code>. The method list contains 7054 constructors and static initializers as well as true methods. 7055 Only directly declared methods are returned (not inherited methods). 7056 An empty method list is returned for array classes and primitive classes 7057 (for example, <code>java.lang.Integer.TYPE</code>). 7058 </description> 7059 <origin>jvmdi</origin> 7060 <capabilities> 7061 <capability id="can_maintain_original_method_order"/> 7062 </capabilities> 7063 <parameters> 7064 <param id="klass"> 7065 <jclass/> 7066 <description> 7067 The class to query. 7068 </description> 7069 </param> 7070 <param id="method_count_ptr"> 7071 <outptr><jint/></outptr> 7072 <description> 7073 On return, points to the number of methods declared in this class. 7074 </description> 7075 </param> 7076 <param id="methods_ptr"> 7077 <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf> 7078 <description> 7079 On return, points to the method ID array. 7080 </description> 7081 </param> 7082 </parameters> 7083 <errors> 7084 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> 7085 <paramlink id="klass"></paramlink> is not prepared. 7086 </error> 7087 </errors> 7088 </function> 7089 7090 <function id="GetClassFields" phase="start" num="53"> 7091 <synopsis>Get Class Fields</synopsis> 7092 <description> 7093 For the class indicated by <code>klass</code>, return a count of fields 7094 via <code>field_count_ptr</code> and a list of field IDs via 7095 <code>fields_ptr</code>. 7096 Only directly declared fields are returned (not inherited fields). 7097 Fields are returned in the order they occur in the class file. 7098 An empty field list is returned for array classes and primitive classes 7099 (for example, <code>java.lang.Integer.TYPE</code>). 7100 Use JNI to determine the length of an array. 7101 </description> 7102 <origin>jvmdi</origin> 7103 <capabilities> 7104 </capabilities> 7105 <parameters> 7106 <param id="klass"> 7107 <jclass/> 7108 <description> 7109 The class to query. 7110 </description> 7111 </param> 7112 <param id="field_count_ptr"> 7113 <outptr><jint/></outptr> 7114 <description> 7115 On return, points to the number of fields declared in this class. 7116 </description> 7117 </param> 7118 <param id="fields_ptr"> 7119 <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf> 7120 <description> 7121 On return, points to the field ID array. 7122 </description> 7123 </param> 7124 </parameters> 7125 <errors> 7126 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> 7127 <paramlink id="klass"></paramlink> is not prepared. 7128 </error> 7129 </errors> 7130 </function> 7131 7132 <function id="GetImplementedInterfaces" phase="start" num="54"> 7133 <synopsis>Get Implemented Interfaces</synopsis> 7134 <description> 7135 Return the direct super-interfaces of this class. For a class, this 7136 function returns the interfaces declared in its <code>implements</code> 7137 clause. For an interface, this function returns the interfaces declared in 7138 its <code>extends</code> clause. 7139 An empty interface list is returned for array classes and primitive classes 7140 (for example, <code>java.lang.Integer.TYPE</code>). 7141 </description> 7142 <origin>jvmdi</origin> 7143 <capabilities> 7144 </capabilities> 7145 <parameters> 7146 <param id="klass"> 7147 <jclass/> 7148 <description> 7149 The class to query. 7150 </description> 7151 </param> 7152 <param id="interface_count_ptr"> 7153 <outptr><jint/></outptr> 7154 <description> 7155 On return, points to the number of interfaces. 7156 </description> 7157 </param> 7158 <param id="interfaces_ptr"> 7159 <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf> 7160 <description> 7161 On return, points to the interface array. 7162 </description> 7163 </param> 7164 </parameters> 7165 <errors> 7166 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> 7167 <paramlink id="klass"></paramlink> is not prepared. 7168 </error> 7169 </errors> 7170 </function> 7171 7172 <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1"> 7173 <synopsis>Get Class Version Numbers</synopsis> 7174 <description> 7175 For the class indicated by <code>klass</code>, 7176 return the minor and major version numbers, 7177 as defined in 7178 <vmspec chapter="4"/>. 7179 </description> 7180 <origin>new</origin> 7181 <capabilities> 7182 </capabilities> 7183 <parameters> 7184 <param id="klass"> 7185 <jclass/> 7186 <description> 7187 The class to query. 7188 </description> 7189 </param> 7190 <param id="minor_version_ptr"> 7191 <outptr><jint/></outptr> 7192 <description> 7193 On return, points to the value of the 7194 <code>minor_version</code> item of the 7195 Class File Format. 7196 Note: to be consistent with the Class File Format, 7197 the minor version number is the first parameter. 7198 </description> 7199 </param> 7200 <param id="major_version_ptr"> 7201 <outptr><jint/></outptr> 7202 <description> 7203 On return, points to the value of the 7204 <code>major_version</code> item of the 7205 Class File Format. 7206 </description> 7207 </param> 7208 </parameters> 7209 <errors> 7210 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 7211 The class is a primitive or array class. 7212 </error> 7213 </errors> 7214 </function> 7215 7216 <function id="GetConstantPool" phase="start" num="146" since="1.1"> 7217 <synopsis>Get Constant Pool</synopsis> 7218 <description> 7219 For the class indicated by <code>klass</code>, 7220 return the raw bytes of the constant pool in the format of the 7221 <code>constant_pool</code> item of 7222 <vmspec chapter="4"/>. 7223 The format of the constant pool may differ between versions 7224 of the Class File Format, so, the 7225 <functionlink id="GetClassVersionNumbers">minor and major 7226 class version numbers</functionlink> should be checked for 7227 compatibility. 7228 <p/> 7229 The returned constant pool might not have the same layout or 7230 contents as the constant pool in the defining class file. 7231 The constant pool returned by GetConstantPool() may have 7232 more or fewer entries than the defining constant pool. 7233 Entries may be in a different order. 7234 The constant pool returned by GetConstantPool() will match the 7235 constant pool used by 7236 <functionlink id="GetBytecodes">GetBytecodes()</functionlink>. 7237 That is, the bytecodes returned by GetBytecodes() will have 7238 constant pool indices which refer to constant pool entries returned 7239 by GetConstantPool(). 7240 Note that since <functionlink id="RetransformClasses"/> 7241 and <functionlink id="RedefineClasses"/> can change 7242 the constant pool, the constant pool returned by this function 7243 can change accordingly. Thus, the correspondence between 7244 GetConstantPool() and GetBytecodes() does not hold if there 7245 is an intervening class retransformation or redefinition. 7246 The value of a constant pool entry used by a given bytecode will 7247 match that of the defining class file (even if the indices don't match). 7248 Constant pool entries which are not used directly or indirectly by 7249 bytecodes (for example, UTF-8 strings associated with annotations) are 7250 not required to exist in the returned constant pool. 7251 </description> 7252 <origin>new</origin> 7253 <capabilities> 7254 <required id="can_get_constant_pool"></required> 7255 </capabilities> 7256 <parameters> 7257 <param id="klass"> 7258 <jclass/> 7259 <description> 7260 The class to query. 7261 </description> 7262 </param> 7263 <param id="constant_pool_count_ptr"> 7264 <outptr><jint/></outptr> 7265 <description> 7266 On return, points to the number of entries 7267 in the constant pool table plus one. 7268 This corresponds to the <code>constant_pool_count</code> 7269 item of the Class File Format. 7270 </description> 7271 </param> 7272 <param id="constant_pool_byte_count_ptr"> 7273 <outptr><jint/></outptr> 7274 <description> 7275 On return, points to the number of bytes 7276 in the returned raw constant pool. 7277 </description> 7278 </param> 7279 <param id="constant_pool_bytes_ptr"> 7280 <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf> 7281 <description> 7282 On return, points to the raw constant pool, that is the bytes 7283 defined by the <code>constant_pool</code> item of the 7284 Class File Format 7285 </description> 7286 </param> 7287 </parameters> 7288 <errors> 7289 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 7290 The class is a primitive or array class. 7291 </error> 7292 </errors> 7293 </function> 7294 7295 <function id="IsInterface" phase="start" num="55"> 7296 <synopsis>Is Interface</synopsis> 7297 <description> 7298 Determines whether a class object reference represents an interface. 7299 The <code>jboolean</code> result is 7300 <code>JNI_TRUE</code> if the "class" is actually an interface, 7301 <code>JNI_FALSE</code> otherwise. 7302 </description> 7303 <origin>jvmdi</origin> 7304 <capabilities> 7305 </capabilities> 7306 <parameters> 7307 <param id="klass"> 7308 <jclass/> 7309 <description> 7310 The class to query. 7311 </description> 7312 </param> 7313 <param id="is_interface_ptr"> 7314 <outptr><jboolean/></outptr> 7315 <description> 7316 On return, points to the boolean result of this function. 7317 7318 </description> 7319 </param> 7320 </parameters> 7321 <errors> 7322 </errors> 7323 </function> 7324 7325 <function id="IsArrayClass" phase="start" num="56"> 7326 <synopsis>Is Array Class</synopsis> 7327 <description> 7328 Determines whether a class object reference represents an array. 7329 The <code>jboolean</code> result is 7330 <code>JNI_TRUE</code> if the class is an array, 7331 <code>JNI_FALSE</code> otherwise. 7332 </description> 7333 <origin>jvmdi</origin> 7334 <capabilities> 7335 </capabilities> 7336 <parameters> 7337 <param id="klass"> 7338 <jclass/> 7339 <description> 7340 The class to query. 7341 </description> 7342 </param> 7343 <param id="is_array_class_ptr"> 7344 <outptr><jboolean/></outptr> 7345 <description> 7346 On return, points to the boolean result of this function. 7347 7348 </description> 7349 </param> 7350 </parameters> 7351 <errors> 7352 </errors> 7353 </function> 7354 7355 <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1"> 7356 <synopsis>Is Modifiable Class</synopsis> 7357 <description> 7358 Determines whether a class is modifiable. 7359 If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/> 7360 returns <code>JNI_TRUE</code>) the class can be 7361 redefined with <functionlink id="RedefineClasses"/> (assuming 7362 the agent possesses the 7363 <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/> 7364 capability) or 7365 retransformed with <functionlink id="RetransformClasses"/> (assuming 7366 the agent possesses the 7367 <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> 7368 capability). 7369 If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/> 7370 returns <code>JNI_FALSE</code>) the class can be neither 7371 redefined nor retransformed. 7372 <p/> 7373 Primitive classes (for example, <code>java.lang.Integer.TYPE</code>), 7374 array classes, and some implementation defined classes are never modifiable. 7375 <p/> 7376 </description> 7377 <origin>new</origin> 7378 <capabilities> 7379 <capability id="can_redefine_any_class"> 7380 If possessed then all classes (except primitive, array, and some implementation defined 7381 classes) are modifiable (redefine or retransform). 7382 </capability> 7383 <capability id="can_retransform_any_class"> 7384 If possessed then all classes (except primitive, array, and some implementation defined 7385 classes) are modifiable with <functionlink id="RetransformClasses"/>. 7386 </capability> 7387 <capability id="can_redefine_classes"> 7388 No effect on the result of the function. 7389 But must additionally be possessed to modify the class with 7390 <functionlink id="RedefineClasses"/>. 7391 </capability> 7392 <capability id="can_retransform_classes"> 7393 No effect on the result of the function. 7394 But must additionally be possessed to modify the class with 7395 <functionlink id="RetransformClasses"/>. 7396 </capability> 7397 </capabilities> 7398 <parameters> 7399 <param id="klass"> 7400 <jclass/> 7401 <description> 7402 The class to query. 7403 </description> 7404 </param> 7405 <param id="is_modifiable_class_ptr"> 7406 <outptr><jboolean/></outptr> 7407 <description> 7408 On return, points to the boolean result of this function. 7409 </description> 7410 </param> 7411 </parameters> 7412 <errors> 7413 </errors> 7414 </function> 7415 7416 <function id="GetClassLoader" phase="start" num="57"> 7417 <synopsis>Get Class Loader</synopsis> 7418 <description> 7419 For the class indicated by <code>klass</code>, return via 7420 <code>classloader_ptr</code> a reference to the class loader for the 7421 class. 7422 </description> 7423 <origin>jvmdi</origin> 7424 <capabilities> 7425 </capabilities> 7426 <parameters> 7427 <param id="klass"> 7428 <jclass/> 7429 <description> 7430 The class to query. 7431 </description> 7432 </param> 7433 <param id="classloader_ptr"> 7434 <outptr><jobject/></outptr> 7435 <description> 7436 On return, points to the class loader that loaded 7437 this class. 7438 If the class was not created by a class loader 7439 or if the class loader is the bootstrap class loader, 7440 points to <code>NULL</code>. 7441 </description> 7442 </param> 7443 </parameters> 7444 <errors> 7445 </errors> 7446 7447 </function> 7448 7449 <function id="GetSourceDebugExtension" phase="start" num="90"> 7450 <synopsis>Get Source Debug Extension</synopsis> 7451 <description> 7452 For the class indicated by <code>klass</code>, return the debug 7453 extension via <code>source_debug_extension_ptr</code>. 7454 The returned string 7455 contains exactly the debug extension information present in the 7456 class file of <code>klass</code>. 7457 </description> 7458 <origin>jvmdi</origin> 7459 <capabilities> 7460 <required id="can_get_source_debug_extension"></required> 7461 </capabilities> 7462 <parameters> 7463 <param id="klass"> 7464 <jclass/> 7465 <description> 7466 The class to query. 7467 </description> 7468 </param> 7469 <param id="source_debug_extension_ptr"> 7470 <allocbuf><char/></allocbuf> 7471 <description> 7472 On return, points to the class's debug extension, encoded as a 7473 <internallink id="mUTF">modified UTF-8</internallink> string. 7474 </description> 7475 </param> 7476 </parameters> 7477 <errors> 7478 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 7479 Class information does not include a debug extension. 7480 </error> 7481 </errors> 7482 </function> 7483 7484 <function id="RetransformClasses" jkernel="yes" num="152" since="1.1"> 7485 <synopsis>Retransform Classes</synopsis> 7486 <description> 7487 This function facilitates the 7488 <internallink id="bci">bytecode instrumentation</internallink> 7489 of already loaded classes. 7490 To replace the class definition without reference to the existing 7491 bytecodes, as one might do when recompiling from source for 7492 fix-and-continue debugging, <functionlink id="RedefineClasses"/> 7493 function should be used instead. 7494 <p/> 7495 When classes are initially loaded or when they are 7496 <functionlink id="RedefineClasses">redefined</functionlink>, 7497 the initial class file bytes can be transformed with the 7498 <eventlink id="ClassFileLoadHook"/> event. 7499 This function reruns the transformation process 7500 (whether or not a transformation has previously occurred). 7501 This retransformation follows these steps: 7502 <ul> 7503 <li>starting from the initial class file bytes 7504 </li> 7505 <li>for each <fieldlink id="can_retransform_classes" 7506 struct="jvmtiCapabilities">retransformation 7507 incapable</fieldlink> 7508 agent which received a 7509 <code>ClassFileLoadHook</code> event during the previous 7510 load or redefine, the bytes it returned 7511 (via the <code>new_class_data</code> parameter) 7512 are reused as the output of the transformation; 7513 note that this is equivalent to reapplying 7514 the previous transformation, unaltered. except that 7515 the <code>ClassFileLoadHook</code> event 7516 is <b>not</b> sent to these agents 7517 </li> 7518 <li>for each <fieldlink id="can_retransform_classes" 7519 struct="jvmtiCapabilities">retransformation 7520 capable</fieldlink> 7521 agent, the <code>ClassFileLoadHook</code> event is sent, 7522 allowing a new transformation to be applied 7523 </li> 7524 <li>the transformed class file bytes are installed as the new 7525 definition of the class 7526 </li> 7527 </ul> 7528 See the <eventlink id="ClassFileLoadHook"/> event for more details. 7529 <p/> 7530 The initial class file bytes represent the bytes passed to 7531 <code>ClassLoader.defineClass</code> 7532 or <code>RedefineClasses</code> (before any transformations 7533 were applied), however they may not exactly match them. 7534 The constant pool may differ in ways described in 7535 <functionlink id="GetConstantPool"/>. 7536 Constant pool indices in the bytecodes of methods will correspond. 7537 Some attributes may not be present. 7538 Where order is not meaningful, for example the order of methods, 7539 order may not be preserved. 7540 <p/> 7541 Retransformation can cause new versions of methods to be installed. 7542 Old method versions may become 7543 <internallink id="obsoleteMethods">obsolete</internallink> 7544 The new method version will be used on new invokes. 7545 If a method has active stack frames, those active frames continue to 7546 run the bytecodes of the original method version. 7547 <p/> 7548 This function does not cause any initialization except that which 7549 would occur under the customary JVM semantics. 7550 In other words, retransforming a class does not cause its initializers to be 7551 run. The values of static fields will remain as they were 7552 prior to the call. 7553 <p/> 7554 Threads need not be suspended. 7555 <p/> 7556 All breakpoints in the class are cleared. 7557 <p/> 7558 All attributes are updated. 7559 <p/> 7560 Instances of the retransformed class are not affected -- fields retain their 7561 previous values. 7562 <functionlink id="GetTag">Tags</functionlink> on the instances are 7563 also unaffected. 7564 <p/> 7565 In response to this call, no events other than the 7566 <eventlink id="ClassFileLoadHook"/> event 7567 will be sent. 7568 <p/> 7569 The retransformation may change method bodies, the constant pool and attributes. 7570 The retransformation must not add, remove or rename fields or methods, change the 7571 signatures of methods, change modifiers, or change inheritance. 7572 These restrictions may be lifted in future versions. 7573 See the error return description below for information on error codes 7574 returned if an unsupported retransformation is attempted. 7575 The class file bytes are not verified or installed until they have passed 7576 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the 7577 returned error code reflects the result of the transformations. 7578 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, 7579 none of the classes to be retransformed will have a new definition installed. 7580 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) 7581 all of the classes to be retransformed will have their new definitions installed. 7582 </description> 7583 <origin>new</origin> 7584 <capabilities> 7585 <required id="can_retransform_classes"></required> 7586 <capability id="can_retransform_any_class"></capability> 7587 </capabilities> 7588 <parameters> 7589 <param id="class_count"> 7590 <jint min="0"/> 7591 <description> 7592 The number of classes to be retransformed. 7593 </description> 7594 </param> 7595 <param id="classes"> 7596 <inbuf incount="class_count"><jclass/></inbuf> 7597 <description> 7598 The array of classes to be retransformed. 7599 </description> 7600 </param> 7601 </parameters> 7602 <errors> 7603 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> 7604 One of the <paramlink id="classes"/> cannot be modified. 7605 See <functionlink id="IsModifiableClass"/>. 7606 </error> 7607 <error id="JVMTI_ERROR_INVALID_CLASS"> 7608 One of the <paramlink id="classes"/> is not a valid class. 7609 </error> 7610 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> 7611 A retransformed class file has a version number not supported by this VM. 7612 </error> 7613 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> 7614 A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>). 7615 </error> 7616 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> 7617 The retransformed class file definitions would lead to a circular definition 7618 (the VM would return a <code>ClassCircularityError</code>). 7619 </error> 7620 <error id="JVMTI_ERROR_FAILS_VERIFICATION"> 7621 The retransformed class file bytes fail verification. 7622 </error> 7623 <error id="JVMTI_ERROR_NAMES_DONT_MATCH"> 7624 The class name defined in a retransformed class file is 7625 different from the name in the old class object. 7626 </error> 7627 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> 7628 A retransformed class file would require adding a method. 7629 </error> 7630 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> 7631 A retransformed class file changes a field. 7632 </error> 7633 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> 7634 A direct superclass is different for a retransformed class file, 7635 or the set of directly implemented 7636 interfaces is different. 7637 </error> 7638 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> 7639 A retransformed class file does not declare a method 7640 declared in the old class version. 7641 </error> 7642 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> 7643 A retransformed class file has different class modifiers. 7644 </error> 7645 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> 7646 A method in the retransformed class file has different modifiers 7647 than its counterpart in the old class version. 7648 </error> 7649 </errors> 7650 </function> 7651 7652 <function id="RedefineClasses" jkernel="yes" num="87"> 7653 <synopsis>Redefine Classes</synopsis> 7654 <typedef id="jvmtiClassDefinition" label="Class redefinition description"> 7655 <field id="klass"> 7656 <jclass/> 7657 <description> 7658 Class object for this class 7659 </description> 7660 </field> 7661 <field id="class_byte_count"> 7662 <jint/> 7663 <description> 7664 Number of bytes defining class (below) 7665 </description> 7666 </field> 7667 <field id="class_bytes"> 7668 <inbuf incount="class_byte_count"><uchar/></inbuf> 7669 <description> 7670 Bytes defining class (in <vmspec chapter="4"/>) 7671 </description> 7672 </field> 7673 </typedef> 7674 <description> 7675 All classes given are redefined according to the definitions 7676 supplied. 7677 This function is used to replace the definition of a class 7678 with a new definition, as might be needed in fix-and-continue 7679 debugging. 7680 Where the existing class file bytes are to be transformed, for 7681 example in 7682 <internallink id="bci">bytecode instrumentation</internallink>, 7683 <functionlink id="RetransformClasses"/> should be used. 7684 <p/> 7685 Redefinition can cause new versions of methods to be installed. 7686 Old method versions may become 7687 <internallink id="obsoleteMethods">obsolete</internallink> 7688 The new method version will be used on new invokes. 7689 If a method has active stack frames, those active frames continue to 7690 run the bytecodes of the original method version. 7691 If resetting of stack frames is desired, use 7692 <functionlink id="PopFrame"></functionlink> 7693 to pop frames with obsolete method versions. 7694 <p/> 7695 This function does not cause any initialization except that which 7696 would occur under the customary JVM semantics. 7697 In other words, redefining a class does not cause its initializers to be 7698 run. The values of static fields will remain as they were 7699 prior to the call. 7700 <p/> 7701 Threads need not be suspended. 7702 <p/> 7703 All breakpoints in the class are cleared. 7704 <p/> 7705 All attributes are updated. 7706 <p/> 7707 Instances of the redefined class are not affected -- fields retain their 7708 previous values. 7709 <functionlink id="GetTag">Tags</functionlink> on the instances are 7710 also unaffected. 7711 <p/> 7712 In response to this call, the <jvmti/> event 7713 <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink> 7714 will be sent (if enabled), but no other <jvmti/> events will be sent. 7715 <p/> 7716 The redefinition may change method bodies, the constant pool and attributes. 7717 The redefinition must not add, remove or rename fields or methods, change the 7718 signatures of methods, change modifiers, or change inheritance. 7719 These restrictions may be lifted in future versions. 7720 See the error return description below for information on error codes 7721 returned if an unsupported redefinition is attempted. 7722 The class file bytes are not verified or installed until they have passed 7723 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the 7724 returned error code reflects the result of the transformations applied 7725 to the bytes passed into <paramlink id="class_definitions"/>. 7726 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, 7727 none of the classes to be redefined will have a new definition installed. 7728 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) 7729 all of the classes to be redefined will have their new definitions installed. 7730 </description> 7731 <origin>jvmdi</origin> 7732 <capabilities> 7733 <required id="can_redefine_classes"></required> 7734 <capability id="can_redefine_any_class"></capability> 7735 </capabilities> 7736 <parameters> 7737 <param id="class_count"> 7738 <jint min="0"/> 7739 <description> 7740 The number of classes specified in <code>class_definitions</code> 7741 </description> 7742 </param> 7743 <param id="class_definitions"> 7744 <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf> 7745 <description> 7746 The array of new class definitions 7747 </description> 7748 </param> 7749 </parameters> 7750 <errors> 7751 <error id="JVMTI_ERROR_NULL_POINTER"> 7752 One of <code>class_bytes</code> is <code>NULL</code>. 7753 </error> 7754 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> 7755 An element of <code>class_definitions</code> cannot be modified. 7756 See <functionlink id="IsModifiableClass"/>. 7757 </error> 7758 <error id="JVMTI_ERROR_INVALID_CLASS"> 7759 An element of <code>class_definitions</code> is not a valid class. 7760 </error> 7761 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> 7762 A new class file has a version number not supported by this VM. 7763 </error> 7764 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> 7765 A new class file is malformed (The VM would return a <code>ClassFormatError</code>). 7766 </error> 7767 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> 7768 The new class file definitions would lead to a circular definition 7769 (the VM would return a <code>ClassCircularityError</code>). 7770 </error> 7771 <error id="JVMTI_ERROR_FAILS_VERIFICATION"> 7772 The class bytes fail verification. 7773 </error> 7774 <error id="JVMTI_ERROR_NAMES_DONT_MATCH"> 7775 The class name defined in a new class file is 7776 different from the name in the old class object. 7777 </error> 7778 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> 7779 A new class file would require adding a method. 7780 </error> 7781 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> 7782 A new class version changes a field. 7783 </error> 7784 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> 7785 A direct superclass is different for a new class 7786 version, or the set of directly implemented 7787 interfaces is different. 7788 </error> 7789 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> 7790 A new class version does not declare a method 7791 declared in the old class version. 7792 </error> 7793 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> 7794 A new class version has different modifiers. 7795 </error> 7796 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> 7797 A method in the new class version has different modifiers 7798 than its counterpart in the old class version. 7799 </error> 7800 </errors> 7801 </function> 7802 7803 </category> 7804 7805 <category id="object" label="Object"> 7806 7807 <function id="GetObjectSize" jkernel="yes" phase="start" num="154"> 7808 <synopsis>Get Object Size</synopsis> 7809 <description> 7810 For the object indicated by <code>object</code>, 7811 return via <code>size_ptr</code> the size of the object. 7812 This size is an implementation-specific approximation of 7813 the amount of storage consumed by this object. 7814 It may include some or all of the object's overhead, and thus 7815 is useful for comparison within an implementation but not 7816 between implementations. 7817 The estimate may change during a single invocation of the JVM. 7818 </description> 7819 <origin>new</origin> 7820 <capabilities> 7821 </capabilities> 7822 <parameters> 7823 <param id="object"> 7824 <jobject/> 7825 <description> 7826 The object to query. 7827 </description> 7828 </param> 7829 <param id="size_ptr"> 7830 <outptr><jlong/></outptr> 7831 <description> 7832 On return, points to the object's size in bytes. 7833 </description> 7834 </param> 7835 </parameters> 7836 <errors> 7837 </errors> 7838 </function> 7839 7840 <function id="GetObjectHashCode" phase="start" num="58"> 7841 <synopsis>Get Object Hash Code</synopsis> 7842 <description> 7843 For the object indicated by <code>object</code>, 7844 return via <code>hash_code_ptr</code> a hash code. 7845 This hash code could be used to maintain a hash table of object references, 7846 however, on some implementations this can cause significant performance 7847 impacts--in most cases 7848 <internallink id="Heap">tags</internallink> 7849 will be a more efficient means of associating information with objects. 7850 This function guarantees 7851 the same hash code value for a particular object throughout its life 7852 </description> 7853 <origin>jvmdi</origin> 7854 <capabilities> 7855 </capabilities> 7856 <parameters> 7857 <param id="object"> 7858 <jobject/> 7859 <description> 7860 The object to query. 7861 </description> 7862 </param> 7863 <param id="hash_code_ptr"> 7864 <outptr><jint/></outptr> 7865 <description> 7866 On return, points to the object's hash code. 7867 </description> 7868 </param> 7869 </parameters> 7870 <errors> 7871 </errors> 7872 </function> 7873 7874 <function id="GetObjectMonitorUsage" num="59"> 7875 <synopsis>Get Object Monitor Usage</synopsis> 7876 <typedef id="jvmtiMonitorUsage" label="Object monitor usage information"> 7877 <field id="owner"> 7878 <jthread/> 7879 <description> 7880 The thread owning this monitor, or <code>NULL</code> if unused 7881 </description> 7882 </field> 7883 <field id="entry_count"> 7884 <jint/> 7885 <description> 7886 The number of times the owning thread has entered the monitor 7887 </description> 7888 </field> 7889 <field id="waiter_count"> 7890 <jint/> 7891 <description> 7892 The number of threads waiting to own this monitor 7893 </description> 7894 </field> 7895 <field id="waiters"> 7896 <allocfieldbuf><jthread/></allocfieldbuf> 7897 <description> 7898 The <code>waiter_count</code> waiting threads 7899 </description> 7900 </field> 7901 <field id="notify_waiter_count"> 7902 <jint/> 7903 <description> 7904 The number of threads waiting to be notified by this monitor 7905 </description> 7906 </field> 7907 <field id="notify_waiters"> 7908 <allocfieldbuf><jthread/></allocfieldbuf> 7909 <description> 7910 The <code>notify_waiter_count</code> threads waiting to be notified 7911 </description> 7912 </field> 7913 </typedef> 7914 <description> 7915 Get information about the object's monitor. 7916 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure 7917 are filled in with information about usage of the monitor. 7918 <todo> 7919 Decide and then clarify suspend requirements. 7920 </todo> 7921 </description> 7922 <origin>jvmdi</origin> 7923 <capabilities> 7924 <required id="can_get_monitor_info"></required> 7925 </capabilities> 7926 <parameters> 7927 <param id="object"> 7928 <jobject/> 7929 <description> 7930 The object to query. 7931 </description> 7932 </param> 7933 <param id="info_ptr"> 7934 <outptr><struct>jvmtiMonitorUsage</struct></outptr> 7935 <description> 7936 On return, filled with monitor information for the 7937 specified object. 7938 </description> 7939 </param> 7940 </parameters> 7941 <errors> 7942 </errors> 7943 </function> 7944 7945 <elide> 7946 <function id="GetObjectMonitors" num="116"> 7947 <synopsis>Get Object Monitors</synopsis> 7948 <description> 7949 Return the list of object monitors. 7950 <p/> 7951 Note: details about each monitor can be examined with 7952 <functionlink id="GetObjectMonitorUsage"></functionlink>. 7953 </description> 7954 <origin>new</origin> 7955 <capabilities> 7956 <required id="can_get_monitor_info"></required> 7957 </capabilities> 7958 <parameters> 7959 <param id="monitorCnt"> 7960 <outptr><jint/></outptr> 7961 <description> 7962 On return, pointer to the number 7963 of monitors returned in <code>monitors_ptr</code>. 7964 </description> 7965 </param> 7966 <param id="monitors_ptr"> 7967 <allocbuf outcount="monitorCnt"><jobject/></allocbuf> 7968 <description> 7969 On return, pointer to the monitor list. 7970 </description> 7971 </param> 7972 </parameters> 7973 <errors> 7974 </errors> 7975 </function> 7976 </elide> 7977 7978 </category> 7979 7980 <category id="fieldCategory" label="Field"> 7981 7982 <intro> 7983 </intro> 7984 7985 <function id="GetFieldName" phase="start" num="60"> 7986 <synopsis>Get Field Name (and Signature)</synopsis> 7987 <description> 7988 For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>, 7989 return the field name via <paramlink id="name_ptr"/> and field signature via 7990 <paramlink id="signature_ptr"/>. 7991 <p/> 7992 Field signatures are defined in the JNI Specification and 7993 are referred to as <code>field descriptors</code> in 7994 <vmspec chapter="4.3.2"/>. 7995 </description> 7996 <origin>jvmdiClone</origin> 7997 <capabilities> 7998 </capabilities> 7999 <parameters> 8000 <param id="klass"> 8001 <jclass field="field"/> 8002 <description> 8003 The class of the field to query. 8004 </description> 8005 </param> 8006 <param id="field"> 8007 <jfieldID class="klass"/> 8008 <description> 8009 The field to query. 8010 </description> 8011 </param> 8012 <param id="name_ptr"> 8013 <allocbuf> 8014 <char/> 8015 <nullok>the name is not returned</nullok> 8016 </allocbuf> 8017 <description> 8018 On return, points to the field name, encoded as a 8019 <internallink id="mUTF">modified UTF-8</internallink> string. 8020 </description> 8021 </param> 8022 <param id="signature_ptr"> 8023 <allocbuf> 8024 <char/> 8025 <nullok>the signature is not returned</nullok> 8026 </allocbuf> 8027 <description> 8028 On return, points to the field signature, encoded as a 8029 <internallink id="mUTF">modified UTF-8</internallink> string. 8030 </description> 8031 </param> 8032 <param id="generic_ptr"> 8033 <allocbuf> 8034 <char/> 8035 <nullok>the generic signature is not returned</nullok> 8036 </allocbuf> 8037 <description> 8038 On return, points to the generic signature of the field, encoded as a 8039 <internallink id="mUTF">modified UTF-8</internallink> string. 8040 If there is no generic signature attribute for the field, then, 8041 on return, points to <code>NULL</code>. 8042 </description> 8043 </param> 8044 </parameters> 8045 <errors> 8046 </errors> 8047 </function> 8048 8049 <function id="GetFieldDeclaringClass" phase="start" num="61"> 8050 <synopsis>Get Field Declaring Class</synopsis> 8051 <description> 8052 For the field indicated by <code>klass</code> and <code>field</code> 8053 return the class that defined it via <code>declaring_class_ptr</code>. 8054 The declaring class will either be <code>klass</code>, a superclass, or 8055 an implemented interface. 8056 </description> 8057 <origin>jvmdi</origin> 8058 <capabilities> 8059 </capabilities> 8060 <parameters> 8061 <param id="klass"> 8062 <jclass field="field"/> 8063 <description> 8064 The class to query. 8065 </description> 8066 </param> 8067 <param id="field"> 8068 <jfieldID class="klass"/> 8069 <description> 8070 The field to query. 8071 </description> 8072 </param> 8073 <param id="declaring_class_ptr"> 8074 <outptr><jclass/></outptr> 8075 <description> 8076 On return, points to the declaring class 8077 </description> 8078 </param> 8079 </parameters> 8080 <errors> 8081 </errors> 8082 </function> 8083 8084 <function id="GetFieldModifiers" phase="start" num="62"> 8085 <synopsis>Get Field Modifiers</synopsis> 8086 <description> 8087 For the field indicated by <code>klass</code> and <code>field</code> 8088 return the access flags via <code>modifiers_ptr</code>. 8089 Access flags are defined in <vmspec chapter="4"/>. 8090 </description> 8091 <origin>jvmdi</origin> 8092 <capabilities> 8093 </capabilities> 8094 <parameters> 8095 <param id="klass"> 8096 <jclass field="field"/> 8097 <description> 8098 The class to query. 8099 </description> 8100 </param> 8101 <param id="field"> 8102 <jfieldID class="klass"/> 8103 <description> 8104 The field to query. 8105 </description> 8106 </param> 8107 <param id="modifiers_ptr"> 8108 <outptr><jint/></outptr> 8109 <description> 8110 On return, points to the access flags. 8111 </description> 8112 </param> 8113 </parameters> 8114 <errors> 8115 </errors> 8116 </function> 8117 8118 <function id="IsFieldSynthetic" phase="start" num="63"> 8119 <synopsis>Is Field Synthetic</synopsis> 8120 <description> 8121 For the field indicated by <code>klass</code> and <code>field</code>, return a 8122 value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>. 8123 Synthetic fields are generated by the compiler but not present in the 8124 original source code. 8125 </description> 8126 <origin>jvmdi</origin> 8127 <capabilities> 8128 <required id="can_get_synthetic_attribute"></required> 8129 </capabilities> 8130 <parameters> 8131 <param id="klass"> 8132 <jclass field="field"/> 8133 <description> 8134 The class of the field to query. 8135 </description> 8136 </param> 8137 <param id="field"> 8138 <jfieldID class="klass"/> 8139 <description> 8140 The field to query. 8141 </description> 8142 </param> 8143 <param id="is_synthetic_ptr"> 8144 <outptr><jboolean/></outptr> 8145 <description> 8146 On return, points to the boolean result of this function. 8147 </description> 8148 </param> 8149 </parameters> 8150 <errors> 8151 </errors> 8152 </function> 8153 8154 </category> 8155 8156 <category id="method" label="Method"> 8157 8158 <intro> 8159 These functions provide information about a method (represented as a 8160 <typelink id="jmethodID"/>) and set how methods are processed. 8161 </intro> 8162 8163 <intro id="obsoleteMethods" label="Obsolete Methods"> 8164 The functions <functionlink id="RetransformClasses"/> and 8165 <functionlink id="RedefineClasses"/> can cause new versions 8166 of methods to be installed. 8167 An original version of a method is considered equivalent 8168 to the new version if: 8169 <ul> 8170 <li>their bytecodes are the same except for indices into the 8171 constant pool and </li> 8172 <li>the referenced constants are equal.</li> 8173 </ul> 8174 An original method version which is not equivalent to the 8175 new method version is called obsolete and is assigned a new method ID; 8176 the original method ID now refers to the new method version. 8177 A method ID can be tested for obsolescence with 8178 <functionlink id="IsMethodObsolete"/>. 8179 </intro> 8180 8181 <function id="GetMethodName" phase="start" num="64"> 8182 <synopsis>Get Method Name (and Signature)</synopsis> 8183 <description> 8184 For the method indicated by <code>method</code>, 8185 return the method name via <code>name_ptr</code> and method signature via 8186 <code>signature_ptr</code>. 8187 <p/> 8188 Method signatures are defined in the JNI Specification and are 8189 referred to as <code>method descriptors</code> in 8190 <vmspec chapter="4.3.3"/>. 8191 Note this is different 8192 than method signatures as defined in the <i>Java Language Specification</i>. 8193 </description> 8194 <origin>jvmdiClone</origin> 8195 <capabilities> 8196 </capabilities> 8197 <parameters> 8198 <param id="method"> 8199 <jmethodID/> 8200 <description> 8201 The method to query. 8202 </description> 8203 </param> 8204 <param id="name_ptr"> 8205 <allocbuf> 8206 <char/> 8207 <nullok>the name is not returned</nullok> 8208 </allocbuf> 8209 <description> 8210 On return, points to the method name, encoded as a 8211 <internallink id="mUTF">modified UTF-8</internallink> string. 8212 </description> 8213 </param> 8214 <param id="signature_ptr"> 8215 <allocbuf> 8216 <char/> 8217 <nullok>the signature is not returned</nullok> 8218 </allocbuf> 8219 <description> 8220 On return, points to the method signature, encoded as a 8221 <internallink id="mUTF">modified UTF-8</internallink> string. 8222 </description> 8223 </param> 8224 <param id="generic_ptr"> 8225 <allocbuf> 8226 <char/> 8227 <nullok>the generic signature is not returned</nullok> 8228 </allocbuf> 8229 <description> 8230 On return, points to the generic signature of the method, encoded as a 8231 <internallink id="mUTF">modified UTF-8</internallink> string. 8232 If there is no generic signature attribute for the method, then, 8233 on return, points to <code>NULL</code>. 8234 </description> 8235 </param> 8236 </parameters> 8237 <errors> 8238 </errors> 8239 </function> 8240 8241 <function id="GetMethodDeclaringClass" phase="start" num="65"> 8242 <synopsis>Get Method Declaring Class</synopsis> 8243 <description> 8244 For the method indicated by <code>method</code>, 8245 return the class that defined it via <code>declaring_class_ptr</code>. 8246 </description> 8247 <origin>jvmdi</origin> 8248 <capabilities> 8249 </capabilities> 8250 <parameters> 8251 <param id="klass"> 8252 <jclass method="method"/> 8253 <description> 8254 The class to query. 8255 </description> 8256 </param> 8257 <param id="method"> 8258 <jmethodID class="klass"/> 8259 <description> 8260 The method to query. 8261 </description> 8262 </param> 8263 <param id="declaring_class_ptr"> 8264 <outptr><jclass/></outptr> 8265 <description> 8266 On return, points to the declaring class 8267 </description> 8268 </param> 8269 </parameters> 8270 <errors> 8271 </errors> 8272 </function> 8273 8274 <function id="GetMethodModifiers" phase="start" num="66"> 8275 <synopsis>Get Method Modifiers</synopsis> 8276 <description> 8277 For the method indicated by <code>method</code>, 8278 return the access flags via <code>modifiers_ptr</code>. 8279 Access flags are defined in <vmspec chapter="4"/>. 8280 </description> 8281 <origin>jvmdi</origin> 8282 <capabilities> 8283 </capabilities> 8284 <parameters> 8285 <param id="klass"> 8286 <jclass method="method"/> 8287 <description> 8288 The class to query. 8289 </description> 8290 </param> 8291 <param id="method"> 8292 <jmethodID class="klass"/> 8293 <description> 8294 The method to query. 8295 </description> 8296 </param> 8297 <param id="modifiers_ptr"> 8298 <outptr><jint/></outptr> 8299 <description> 8300 On return, points to the access flags. 8301 </description> 8302 </param> 8303 </parameters> 8304 <errors> 8305 </errors> 8306 </function> 8307 8308 <function id="GetMaxLocals" phase="start" num="68"> 8309 <synopsis>Get Max Locals</synopsis> 8310 <description> 8311 For the method indicated by <code>method</code>, 8312 return the number of local variable slots used by the method, 8313 including the local variables used to pass parameters to the 8314 method on its invocation. 8315 <p/> 8316 See <code>max_locals</code> in <vmspec chapter="4.7.3"/>. 8317 </description> 8318 <origin>jvmdi</origin> 8319 <capabilities> 8320 </capabilities> 8321 <parameters> 8322 <param id="klass"> 8323 <jclass method="method"/> 8324 <description> 8325 The class to query. 8326 </description> 8327 </param> 8328 <param id="method"> 8329 <jmethodID class="klass" native="error"/> 8330 <description> 8331 The method to query. 8332 </description> 8333 </param> 8334 <param id="max_ptr"> 8335 <outptr><jint/></outptr> 8336 <description> 8337 On return, points to the maximum number of local slots 8338 </description> 8339 </param> 8340 </parameters> 8341 <errors> 8342 </errors> 8343 </function> 8344 8345 <function id="GetArgumentsSize" phase="start" num="69"> 8346 <synopsis>Get Arguments Size</synopsis> 8347 <description> 8348 For the method indicated by <code>method</code>, 8349 return via <code>max_ptr</code> the number of local variable slots used 8350 by the method's arguments. 8351 Note that two-word arguments use two slots. 8352 </description> 8353 <origin>jvmdi</origin> 8354 <capabilities> 8355 </capabilities> 8356 <parameters> 8357 <param id="klass"> 8358 <jclass method="method"/> 8359 <description> 8360 The class to query. 8361 </description> 8362 </param> 8363 <param id="method"> 8364 <jmethodID class="klass" native="error"/> 8365 <description> 8366 The method to query. 8367 </description> 8368 </param> 8369 <param id="size_ptr"> 8370 <outptr><jint/></outptr> 8371 <description> 8372 On return, points to the number of argument slots 8373 </description> 8374 </param> 8375 </parameters> 8376 <errors> 8377 </errors> 8378 </function> 8379 8380 <function id="GetLineNumberTable" phase="start" num="70"> 8381 <synopsis>Get Line Number Table</synopsis> 8382 <typedef id="jvmtiLineNumberEntry" label="Line number table entry"> 8383 <field id="start_location"> 8384 <jlocation/> 8385 <description> 8386 the <datalink id="jlocation"></datalink> where the line begins 8387 </description> 8388 </field> 8389 <field id="line_number"> 8390 <jint/> 8391 <description> 8392 the line number 8393 </description> 8394 </field> 8395 </typedef> 8396 <description> 8397 For the method indicated by <code>method</code>, 8398 return a table of source line number entries. The size of the table is 8399 returned via <code>entry_count_ptr</code> and the table itself is 8400 returned via <code>table_ptr</code>. 8401 </description> 8402 <origin>jvmdi</origin> 8403 <capabilities> 8404 <required id="can_get_line_numbers"></required> 8405 </capabilities> 8406 <parameters> 8407 <param id="klass"> 8408 <jclass method="method"/> 8409 <description> 8410 The class to query. 8411 </description> 8412 </param> 8413 <param id="method"> 8414 <jmethodID class="klass" native="error"/> 8415 <description> 8416 The method to query. 8417 </description> 8418 </param> 8419 <param id="entry_count_ptr"> 8420 <outptr><jint/></outptr> 8421 <description> 8422 On return, points to the number of entries in the table 8423 </description> 8424 </param> 8425 <param id="table_ptr"> 8426 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf> 8427 <description> 8428 On return, points to the line number table pointer. 8429 </description> 8430 </param> 8431 </parameters> 8432 <errors> 8433 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 8434 Class information does not include line numbers. 8435 </error> 8436 </errors> 8437 </function> 8438 8439 <function id="GetMethodLocation" phase="start" num="71"> 8440 <synopsis>Get Method Location</synopsis> 8441 <description> 8442 For the method indicated by <code>method</code>, 8443 return the beginning and ending addresses through 8444 <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a 8445 conventional byte code indexing scheme, 8446 <code>start_location_ptr</code> will always point to zero 8447 and <code>end_location_ptr</code> 8448 will always point to the byte code count minus one. 8449 </description> 8450 <origin>jvmdi</origin> 8451 <capabilities> 8452 </capabilities> 8453 <parameters> 8454 <param id="klass"> 8455 <jclass method="method"/> 8456 <description> 8457 The class to query. 8458 </description> 8459 </param> 8460 <param id="method"> 8461 <jmethodID class="klass" native="error"/> 8462 <description> 8463 The method to query. 8464 </description> 8465 </param> 8466 <param id="start_location_ptr"> 8467 <outptr><jlocation/></outptr> 8468 <description> 8469 On return, points to the first location, or 8470 <code>-1</code> if location information is not available. 8471 If the information is available and 8472 <functionlink id="GetJLocationFormat"></functionlink> 8473 returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink> 8474 then this will always be zero. 8475 </description> 8476 </param> 8477 <param id="end_location_ptr"> 8478 <outptr><jlocation/></outptr> 8479 <description> 8480 On return, points to the last location, 8481 or <code>-1</code> if location information is not available. 8482 </description> 8483 </param> 8484 </parameters> 8485 <errors> 8486 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 8487 Class information does not include method sizes. 8488 </error> 8489 </errors> 8490 </function> 8491 8492 <function id="GetLocalVariableTable" num="72"> 8493 <synopsis>Get Local Variable Table</synopsis> 8494 <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry"> 8495 <field id="start_location"> 8496 <jlocation/> 8497 <description> 8498 The code array index where the local variable is first valid 8499 (that is, where it must have a value). 8500 </description> 8501 </field> 8502 <field id="length"> 8503 <jint/> 8504 <description> 8505 The length of the valid section for this local variable. 8506 The last code array index where the local variable is valid 8507 is <code>start_location + length</code>. 8508 </description> 8509 </field> 8510 <field id="name"> 8511 <allocfieldbuf><char/></allocfieldbuf> 8512 <description> 8513 The local variable name, encoded as a 8514 <internallink id="mUTF">modified UTF-8</internallink> string. 8515 </description> 8516 </field> 8517 <field id="signature"> 8518 <allocfieldbuf><char/></allocfieldbuf> 8519 <description> 8520 The local variable's type signature, encoded as a 8521 <internallink id="mUTF">modified UTF-8</internallink> string. 8522 The signature format is the same as that defined in 8523 <vmspec chapter="4.3.2"/>. 8524 </description> 8525 </field> 8526 <field id="generic_signature"> 8527 <allocfieldbuf><char/></allocfieldbuf> 8528 <description> 8529 The local variable's generic signature, encoded as a 8530 <internallink id="mUTF">modified UTF-8</internallink> string. 8531 The value of this field will be <code>NULL</code> for any local 8532 variable which does not have a generic type. 8533 </description> 8534 </field> 8535 <field id="slot"> 8536 <jint/> 8537 <description> 8538 The local variable's slot. See <internallink id="local">Local Variables</internallink>. 8539 </description> 8540 </field> 8541 </typedef> 8542 <description> 8543 Return local variable information. 8544 </description> 8545 <origin>jvmdiClone</origin> 8546 <capabilities> 8547 <required id="can_access_local_variables"></required> 8548 </capabilities> 8549 <parameters> 8550 <param id="method"> 8551 <jmethodID native="error"/> 8552 <description> 8553 The method to query. 8554 </description> 8555 </param> 8556 <param id="entry_count_ptr"> 8557 <outptr><jint/></outptr> 8558 <description> 8559 On return, points to the number of entries in the table 8560 </description> 8561 </param> 8562 <param id="table_ptr"> 8563 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf> 8564 <description> 8565 On return, points to an array of local variable table entries. 8566 </description> 8567 </param> 8568 </parameters> 8569 <errors> 8570 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 8571 Class information does not include local variable 8572 information. 8573 </error> 8574 </errors> 8575 </function> 8576 8577 <function id="GetBytecodes" phase="start" num="75"> 8578 <synopsis>Get Bytecodes</synopsis> 8579 <description> 8580 For the method indicated by <code>method</code>, 8581 return the byte codes that implement the method. The number of 8582 bytecodes is returned via <code>bytecode_count_ptr</code>. The byte codes 8583 themselves are returned via <code>bytecodes_ptr</code>. 8584 </description> 8585 <origin>jvmdi</origin> 8586 <capabilities> 8587 <required id="can_get_bytecodes"></required> 8588 </capabilities> 8589 <parameters> 8590 <param id="klass"> 8591 <jclass method="method"/> 8592 <description> 8593 The class to query. 8594 </description> 8595 </param> 8596 <param id="method"> 8597 <jmethodID class="klass" native="error"/> 8598 <description> 8599 The method to query. 8600 </description> 8601 </param> 8602 <param id="bytecode_count_ptr"> 8603 <outptr><jint/></outptr> 8604 <description> 8605 On return, points to the length of the byte code array 8606 </description> 8607 </param> 8608 <param id="bytecodes_ptr"> 8609 <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf> 8610 <description> 8611 On return, points to the pointer to the byte code array 8612 </description> 8613 </param> 8614 </parameters> 8615 <errors> 8616 </errors> 8617 </function> 8618 8619 <function id="IsMethodNative" phase="start" num="76"> 8620 <synopsis>Is Method Native</synopsis> 8621 <description> 8622 For the method indicated by <code>method</code>, return a 8623 value indicating whether the method is native via <code>is_native_ptr</code> 8624 </description> 8625 <origin>jvmdi</origin> 8626 <capabilities> 8627 </capabilities> 8628 <parameters> 8629 <param id="klass"> 8630 <jclass method="method"/> 8631 <description> 8632 The class to query. 8633 </description> 8634 </param> 8635 <param id="method"> 8636 <jmethodID class="klass"/> 8637 <description> 8638 The method to query. 8639 </description> 8640 </param> 8641 <param id="is_native_ptr"> 8642 <outptr><jboolean/></outptr> 8643 <description> 8644 On return, points to the boolean result of this function. 8645 </description> 8646 </param> 8647 </parameters> 8648 <errors> 8649 </errors> 8650 </function> 8651 8652 <function id="IsMethodSynthetic" phase="start" num="77"> 8653 <synopsis>Is Method Synthetic</synopsis> 8654 <description> 8655 For the method indicated by <code>method</code>, return a 8656 value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>. 8657 Synthetic methods are generated by the compiler but not present in the 8658 original source code. 8659 </description> 8660 <origin>jvmdi</origin> 8661 <capabilities> 8662 <required id="can_get_synthetic_attribute"></required> 8663 </capabilities> 8664 <parameters> 8665 <param id="klass"> 8666 <jclass method="method"/> 8667 <description> 8668 The class to query. 8669 </description> 8670 </param> 8671 <param id="method"> 8672 <jmethodID class="klass"/> 8673 <description> 8674 The method to query. 8675 </description> 8676 </param> 8677 <param id="is_synthetic_ptr"> 8678 <outptr><jboolean/></outptr> 8679 <description> 8680 On return, points to the boolean result of this function. 8681 </description> 8682 </param> 8683 </parameters> 8684 <errors> 8685 </errors> 8686 </function> 8687 8688 <function id="IsMethodObsolete" phase="start" num="91"> 8689 <synopsis>Is Method Obsolete</synopsis> 8690 <description> 8691 Determine if a method ID refers to an 8692 <internallink id="obsoleteMethods">obsolete</internallink> 8693 method version. 8694 </description> 8695 <origin>jvmdi</origin> 8696 <capabilities> 8697 </capabilities> 8698 <parameters> 8699 <param id="klass"> 8700 <jclass method="method"/> 8701 <description> 8702 The class to query. 8703 </description> 8704 </param> 8705 <param id="method"> 8706 <jmethodID class="klass"/> 8707 <description> 8708 The method ID to query. 8709 </description> 8710 </param> 8711 <param id="is_obsolete_ptr"> 8712 <outptr><jboolean/></outptr> 8713 <description> 8714 On return, points to the boolean result of this function. 8715 </description> 8716 </param> 8717 </parameters> 8718 <errors> 8719 </errors> 8720 </function> 8721 8722 <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1"> 8723 <synopsis>Set Native Method Prefix</synopsis> 8724 <description> 8725 This function modifies the failure handling of 8726 native method resolution by allowing retry 8727 with a prefix applied to the name. 8728 When used with the 8729 <eventlink id="ClassFileLoadHook">ClassFileLoadHook 8730 event</eventlink>, it enables native methods to be 8731 <internallink id="bci">instrumented</internallink>. 8732 <p/> 8733 Since native methods cannot be directly instrumented 8734 (they have no bytecodes), they must be wrapped with 8735 a non-native method which can be instrumented. 8736 For example, if we had: 8737 <example> 8738native boolean foo(int x);</example> 8739 <p/> 8740 We could transform the class file (with the 8741 ClassFileLoadHook event) so that this becomes: 8742 <example> 8743boolean foo(int x) { 8744 <i>... record entry to foo ...</i> 8745 return wrapped_foo(x); 8746} 8747 8748native boolean wrapped_foo(int x);</example> 8749 <p/> 8750 Where foo becomes a wrapper for the actual native method 8751 with the appended prefix "wrapped_". Note that 8752 "wrapped_" would be a poor choice of prefix since it 8753 might conceivably form the name of an existing method 8754 thus something like "$$$MyAgentWrapped$$$_" would be 8755 better but would make these examples less readable. 8756 <p/> 8757 The wrapper will allow data to be collected on the native 8758 method call, but now the problem becomes linking up the 8759 wrapped method with the native implementation. 8760 That is, the method <code>wrapped_foo</code> needs to be 8761 resolved to the native implementation of <code>foo</code>, 8762 which might be: 8763 <example> 8764Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example> 8765 <p/> 8766 This function allows the prefix to be specified and the 8767 proper resolution to occur. 8768 Specifically, when the standard resolution fails, the 8769 resolution is retried taking the prefix into consideration. 8770 There are two ways that resolution occurs, explicit 8771 resolution with the JNI function <code>RegisterNatives</code> 8772 and the normal automatic resolution. For 8773 <code>RegisterNatives</code>, the VM will attempt this 8774 association: 8775 <example> 8776method(foo) -> nativeImplementation(foo)</example> 8777 <p/> 8778 When this fails, the resolution will be retried with 8779 the specified prefix prepended to the method name, 8780 yielding the correct resolution: 8781 <example> 8782method(wrapped_foo) -> nativeImplementation(foo)</example> 8783 <p/> 8784 For automatic resolution, the VM will attempt: 8785 <example> 8786method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example> 8787 <p/> 8788 When this fails, the resolution will be retried with 8789 the specified prefix deleted from the implementation name, 8790 yielding the correct resolution: 8791 <example> 8792method(wrapped_foo) -> nativeImplementation(foo)</example> 8793 <p/> 8794 Note that since the prefix is only used when standard 8795 resolution fails, native methods can be wrapped selectively. 8796 <p/> 8797 Since each <jvmti/> environment is independent and 8798 can do its own transformation of the bytecodes, more 8799 than one layer of wrappers may be applied. Thus each 8800 environment needs its own prefix. Since transformations 8801 are applied in order, the prefixes, if applied, will 8802 be applied in the same order. 8803 The order of transformation application is described in 8804 the <eventlink id="ClassFileLoadHook"/> event. 8805 Thus if three environments applied 8806 wrappers, <code>foo</code> might become 8807 <code>$env3_$env2_$env1_foo</code>. But if, say, 8808 the second environment did not apply a wrapper to 8809 <code>foo</code> it would be just 8810 <code>$env3_$env1_foo</code>. To be able to 8811 efficiently determine the sequence of prefixes, 8812 an intermediate prefix is only applied if its non-native 8813 wrapper exists. Thus, in the last example, even though 8814 <code>$env1_foo</code> is not a native method, the 8815 <code>$env1_</code> prefix is applied since 8816 <code>$env1_foo</code> exists. 8817 <p/> 8818 Since the prefixes are used at resolution time 8819 and since resolution may be arbitrarily delayed, a 8820 native method prefix must remain set as long as there 8821 are corresponding prefixed native methods. 8822 </description> 8823 <origin>new</origin> 8824 <capabilities> 8825 <required id="can_set_native_method_prefix"></required> 8826 </capabilities> 8827 <parameters> 8828 <param id="prefix"> 8829 <inbuf> 8830 <char/> 8831 <nullok> 8832 any existing prefix in this environment is cancelled 8833 </nullok> 8834 </inbuf> 8835 <description> 8836 The prefix to apply, encoded as a 8837 <internallink id="mUTF">modified UTF-8</internallink> string. 8838 </description> 8839 </param> 8840 </parameters> 8841 <errors> 8842 </errors> 8843 </function> 8844 8845 <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1"> 8846 <synopsis>Set Native Method Prefixes</synopsis> 8847 <description> 8848 For a normal agent, <functionlink id="SetNativeMethodPrefix"/> 8849 will provide all needed native method prefixing. 8850 For a meta-agent that performs multiple independent class 8851 file transformations (for example as a proxy for another 8852 layer of agents) this function allows each transformation 8853 to have its own prefix. 8854 The prefixes are applied in the order supplied and are 8855 processed in the same manor as described for the 8856 application of prefixes from multiple <jvmti/> environments 8857 in <functionlink id="SetNativeMethodPrefix"/>. 8858 <p/> 8859 Any previous prefixes are replaced. Thus, calling this 8860 function with a <paramlink id="prefix_count"/> of <code>0</code> 8861 disables prefixing in this environment. 8862 <p/> 8863 <functionlink id="SetNativeMethodPrefix"/> and this function 8864 are the two ways to set the prefixes. 8865 Calling <code>SetNativeMethodPrefix</code> with 8866 a prefix is the same as calling this function with 8867 <paramlink id="prefix_count"/> of <code>1</code>. 8868 Calling <code>SetNativeMethodPrefix</code> with 8869 <code>NULL</code> is the same as calling this function with 8870 <paramlink id="prefix_count"/> of <code>0</code>. 8871 </description> 8872 <origin>new</origin> 8873 <capabilities> 8874 <required id="can_set_native_method_prefix"></required> 8875 </capabilities> 8876 <parameters> 8877 <param id="prefix_count"> 8878 <jint min="0"/> 8879 <description> 8880 The number of prefixes to apply. 8881 </description> 8882 </param> 8883 <param id="prefixes"> 8884 <agentbuf> 8885 <char/> 8886 </agentbuf> 8887 <description> 8888 The prefixes to apply for this environment, each encoded as a 8889 <internallink id="mUTF">modified UTF-8</internallink> string. 8890 </description> 8891 </param> 8892 </parameters> 8893 <errors> 8894 </errors> 8895 </function> 8896 8897 </category> 8898 8899 <category id="RawMonitors" label="Raw Monitor"> 8900 8901 <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31"> 8902 <synopsis>Create Raw Monitor</synopsis> 8903 <description> 8904 Create a raw monitor. 8905 </description> 8906 <origin>jvmdi</origin> 8907 <capabilities> 8908 </capabilities> 8909 <parameters> 8910 <param id="name"> 8911 <inbuf><char/></inbuf> 8912 <description> 8913 A name to identify the monitor, encoded as a 8914 <internallink id="mUTF">modified UTF-8</internallink> string. 8915 </description> 8916 </param> 8917 <param id="monitor_ptr"> 8918 <outptr><jrawMonitorID/></outptr> 8919 <description> 8920 On return, points to the created monitor. 8921 </description> 8922 </param> 8923 </parameters> 8924 <errors> 8925 </errors> 8926 </function> 8927 8928 <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32"> 8929 <synopsis>Destroy Raw Monitor</synopsis> 8930 <description> 8931 Destroy the raw monitor. 8932 If the monitor being destroyed has been entered by this thread, it will be 8933 exited before it is destroyed. 8934 If the monitor being destroyed has been entered by another thread, 8935 an error will be returned and the monitor will not be destroyed. 8936 </description> 8937 <origin>jvmdi</origin> 8938 <capabilities> 8939 </capabilities> 8940 <parameters> 8941 <param id="monitor"> 8942 <jrawMonitorID/> 8943 <description> 8944 The monitor 8945 </description> 8946 </param> 8947 </parameters> 8948 <errors> 8949 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 8950 Not monitor owner 8951 </error> 8952 </errors> 8953 </function> 8954 8955 <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33"> 8956 <synopsis>Raw Monitor Enter</synopsis> 8957 <description> 8958 Gain exclusive ownership of a raw monitor. 8959 The same thread may enter a monitor more then once. 8960 The thread must 8961 <functionlink id="RawMonitorExit">exit</functionlink> 8962 the monitor the same number of times as it is entered. 8963 If a monitor is entered during <code>OnLoad</code> (before attached threads exist) 8964 and has not exited when attached threads come into existence, the enter 8965 is considered to have occurred on the main thread. 8966 </description> 8967 <origin>jvmdi</origin> 8968 <capabilities> 8969 </capabilities> 8970 <parameters> 8971 <param id="monitor"> 8972 <jrawMonitorID/> 8973 <description> 8974 The monitor 8975 </description> 8976 </param> 8977 </parameters> 8978 <errors> 8979 </errors> 8980 </function> 8981 8982 <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34"> 8983 <synopsis>Raw Monitor Exit</synopsis> 8984 <description> 8985 Release exclusive ownership of a raw monitor. 8986 </description> 8987 <origin>jvmdi</origin> 8988 <capabilities> 8989 </capabilities> 8990 <parameters> 8991 <param id="monitor"> 8992 <jrawMonitorID/> 8993 <description> 8994 The monitor 8995 </description> 8996 </param> 8997 </parameters> 8998 <errors> 8999 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 9000 Not monitor owner 9001 </error> 9002 </errors> 9003 </function> 9004 9005 <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35"> 9006 <synopsis>Raw Monitor Wait</synopsis> 9007 <description> 9008 Wait for notification of the raw monitor. 9009 <p/> 9010 Causes the current thread to wait until either another thread calls 9011 <functionlink id="RawMonitorNotify"/> or 9012 <functionlink id="RawMonitorNotifyAll"/> 9013 for the specified raw monitor, or the specified 9014 <paramlink id="millis">timeout</paramlink> 9015 has elapsed. 9016 </description> 9017 <origin>jvmdi</origin> 9018 <capabilities> 9019 </capabilities> 9020 <parameters> 9021 <param id="monitor"> 9022 <jrawMonitorID/> 9023 <description> 9024 The monitor 9025 </description> 9026 </param> 9027 <param id="millis"> 9028 <jlong/> 9029 <description> 9030 The timeout, in milliseconds. If the timeout is 9031 zero, then real time is not taken into consideration 9032 and the thread simply waits until notified. 9033 </description> 9034 </param> 9035 </parameters> 9036 <errors> 9037 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 9038 Not monitor owner 9039 </error> 9040 <error id="JVMTI_ERROR_INTERRUPT"> 9041 Wait was interrupted, try again 9042 </error> 9043 </errors> 9044 </function> 9045 9046 <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36"> 9047 <synopsis>Raw Monitor Notify</synopsis> 9048 <description> 9049 Notify a single thread waiting on the raw monitor. 9050 </description> 9051 <origin>jvmdi</origin> 9052 <capabilities> 9053 </capabilities> 9054 <parameters> 9055 <param id="monitor"> 9056 <jrawMonitorID/> 9057 <description> 9058 The monitor 9059 </description> 9060 </param> 9061 </parameters> 9062 <errors> 9063 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 9064 Not monitor owner 9065 </error> 9066 </errors> 9067 </function> 9068 9069 <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37"> 9070 <synopsis>Raw Monitor Notify All</synopsis> 9071 <description> 9072 Notify all threads waiting on the raw monitor. 9073 </description> 9074 <origin>jvmdi</origin> 9075 <capabilities> 9076 </capabilities> 9077 <parameters> 9078 <param id="monitor"> 9079 <jrawMonitorID/> 9080 <description> 9081 The monitor 9082 </description> 9083 </param> 9084 </parameters> 9085 <errors> 9086 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 9087 Not monitor owner 9088 </error> 9089 </errors> 9090 </function> 9091 9092 <elide> 9093 <function id="GetRawMonitorUse" num="118"> 9094 <synopsis>Get Raw Monitor Use</synopsis> 9095 <description> 9096 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure 9097 are filled in with information about usage of the raw monitor. 9098 </description> 9099 <origin>new</origin> 9100 <capabilities> 9101 <required id="can_get_raw_monitor_usage"></required> 9102 </capabilities> 9103 <parameters> 9104 <param id="monitor"> 9105 <jrawMonitorID/> 9106 <description> 9107 the raw monitor to query. 9108 </description> 9109 </param> 9110 <param id="info_ptr"> 9111 <outptr><struct>jvmtiMonitorUsage</struct></outptr> 9112 <description> 9113 On return, filled with monitor information for the 9114 specified raw monitor. 9115 </description> 9116 </param> 9117 </parameters> 9118 <errors> 9119 </errors> 9120 </function> 9121 9122 <function id="GetRawMonitors" num="119"> 9123 <synopsis>Get Raw Monitors</synopsis> 9124 <description> 9125 Return the list of raw monitors. 9126 <p/> 9127 Note: details about each monitor can be examined with 9128 <functionlink id="GetRawMonitorUse"></functionlink>. 9129 </description> 9130 <origin>new</origin> 9131 <capabilities> 9132 <required id="can_get_raw_monitor_usage"></required> 9133 </capabilities> 9134 <parameters> 9135 <param id="monitorCnt"> 9136 <outptr><jint/></outptr> 9137 <description> 9138 On return, pointer to the number 9139 of monitors returned in <code>monitors_ptr</code>. 9140 </description> 9141 </param> 9142 <param id="monitors_ptr"> 9143 <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf> 9144 <description> 9145 On return, pointer to the monitor list. 9146 </description> 9147 </param> 9148 </parameters> 9149 <errors> 9150 </errors> 9151 </function> 9152 </elide> 9153 </category> 9154 9155 <category id="jniIntercept" label="JNI Function Interception"> 9156 9157 <intro> 9158 Provides the ability to intercept and resend 9159 Java Native Interface (JNI) function calls 9160 by manipulating the JNI function table. 9161 See <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html">JNI 9162 Functions</externallink> in the <i>Java Native Interface Specification</i>. 9163 <p/> 9164 The following example illustrates intercepting the 9165 <code>NewGlobalRef</code> JNI call in order to count reference 9166 creation. 9167 <example> 9168JNIEnv original_jni_Functions; 9169JNIEnv redirected_jni_Functions; 9170int my_global_ref_count = 0; 9171 9172jobject 9173MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) { 9174 ++my_global_ref_count; 9175 return originalJNIFunctions->NewGlobalRef(env, lobj); 9176} 9177 9178void 9179myInit() { 9180 jvmtiError err; 9181 9182 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &original_jni_Functions); 9183 if (err != JVMTI_ERROR_NONE) { 9184 die(); 9185 } 9186 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &redirected_jni_Functions); 9187 if (err != JVMTI_ERROR_NONE) { 9188 die(); 9189 } 9190 redirectedJNIFunctions->NewGlobalRef = MyNewGlobalRef; 9191 err = (*jvmti_env)->SetJNIFunctionTable(jvmti_env, redirected_jni_Functions); 9192 if (err != JVMTI_ERROR_NONE) { 9193 die(); 9194 } 9195} 9196 </example> 9197 Sometime after <code>myInit</code> is called the user's JNI 9198 code is executed which makes the call to create a new global 9199 reference. Instead of going to the normal JNI implementation 9200 the call goes to <code>myNewGlobalRef</code>. Note that a 9201 copy of the original function table is kept so that the normal 9202 JNI function can be called after the data is collected. 9203 Note also that any JNI functions which are not overwritten 9204 will behave normally. 9205 <todo> 9206 check that the example compiles and executes. 9207 </todo> 9208 </intro> 9209 9210 <function id="SetJNIFunctionTable" phase="start" num="120"> 9211 <synopsis>Set JNI Function Table</synopsis> 9212 <description> 9213 Set the JNI function table 9214 in all current and future JNI environments. 9215 As a result, all future JNI calls are directed to the specified functions. 9216 Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the 9217 function table to pass to this function. 9218 For this function to take effect the the updated table entries must be 9219 used by the JNI clients. 9220 Since the table is defined <code>const</code> some compilers may optimize 9221 away the access to the table, thus preventing this function from taking 9222 effect. 9223 The table is copied--changes to the local copy of the 9224 table have no effect. 9225 This function affects only the function table, all other aspects of the environment are 9226 unaffected. 9227 See the examples <internallink id="jniIntercept">above</internallink>. 9228 </description> 9229 <origin>new</origin> 9230 <capabilities> 9231 </capabilities> 9232 <parameters> 9233 <param id="function_table"> 9234 <inptr> 9235 <struct>jniNativeInterface</struct> 9236 </inptr> 9237 <description> 9238 Points to the new JNI function table. 9239 </description> 9240 </param> 9241 </parameters> 9242 <errors> 9243 </errors> 9244 </function> 9245 9246 <function id="GetJNIFunctionTable" phase="start" num="121"> 9247 <synopsis>Get JNI Function Table</synopsis> 9248 <description> 9249 Get the JNI function table. 9250 The JNI function table is copied into allocated memory. 9251 If <functionlink id="SetJNIFunctionTable"></functionlink> 9252 has been called, the modified (not the original) function 9253 table is returned. 9254 Only the function table is copied, no other aspects of the environment 9255 are copied. 9256 See the examples <internallink id="jniIntercept">above</internallink>. 9257 </description> 9258 <origin>new</origin> 9259 <capabilities> 9260 </capabilities> 9261 <parameters> 9262 <param id="function_table"> 9263 <allocbuf> 9264 <struct>jniNativeInterface</struct> 9265 </allocbuf> 9266 <description> 9267 On return, <code>*function_table</code> 9268 points a newly allocated copy of the JNI function table. 9269 </description> 9270 </param> 9271 </parameters> 9272 <errors> 9273 </errors> 9274 </function> 9275 9276 </category> 9277 9278 <category id="eventManagement" label="Event Management"> 9279 9280 <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122"> 9281 <synopsis>Set Event Callbacks</synopsis> 9282 <description> 9283 Set the functions to be called for each event. 9284 The callbacks are specified by supplying a replacement function table. 9285 The function table is copied--changes to the local copy of the 9286 table have no effect. 9287 This is an atomic action, all callbacks are set at once. 9288 No events are sent before this function is called. 9289 When an entry is <code>NULL</code> or when the event is beyond 9290 <paramlink id="size_of_callbacks"></paramlink> no event is sent. 9291 Details on events are 9292 described <internallink id="EventSection">later</internallink> in this document. 9293 An event must be enabled and have a callback in order to be 9294 sent--the order in which this function and 9295 <functionlink id="SetEventNotificationMode"></functionlink> 9296 are called does not affect the result. 9297 </description> 9298 <origin>new</origin> 9299 <capabilities> 9300 </capabilities> 9301 <parameters> 9302 <param id="callbacks"> 9303 <inptr> 9304 <struct>jvmtiEventCallbacks</struct> 9305 <nullok>remove the existing callbacks</nullok> 9306 </inptr> 9307 <description> 9308 The new event callbacks. 9309 </description> 9310 </param> 9311 <param id="size_of_callbacks"> 9312 <jint min="0"/> 9313 <description> 9314 <code>sizeof(jvmtiEventCallbacks)</code>--for version 9315 compatibility. 9316 </description> 9317 </param> 9318 </parameters> 9319 <errors> 9320 </errors> 9321 </function> 9322 9323 <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2"> 9324 <synopsis>Set Event Notification Mode</synopsis> 9325 <description> 9326 Control the generation of events. 9327 <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum"> 9328 <constant id="JVMTI_ENABLE" num="1"> 9329 If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>, 9330 the event <paramlink id="event_type"></paramlink> will be enabled 9331 </constant> 9332 <constant id="JVMTI_DISABLE" num="0"> 9333 If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>, 9334 the event <paramlink id="event_type"></paramlink> will be disabled 9335 </constant> 9336 </constants> 9337 If <code>thread</code> is <code>NULL</code>, 9338 the event is enabled or disabled globally; otherwise, it is 9339 enabled or disabled for a particular thread. 9340 An event is generated for 9341 a particular thread if it is enabled either at the thread or global 9342 levels. 9343 <p/> 9344 See <internallink id="EventIndex">below</internallink> for information on specific events. 9345 <p/> 9346 The following events cannot be controlled at the thread 9347 level through this function. 9348 <ul> 9349 <li><eventlink id="VMInit"></eventlink></li> 9350 <li><eventlink id="VMStart"></eventlink></li> 9351 <li><eventlink id="VMDeath"></eventlink></li> 9352 <li><eventlink id="ThreadStart"></eventlink></li> 9353 <li><eventlink id="CompiledMethodLoad"></eventlink></li> 9354 <li><eventlink id="CompiledMethodUnload"></eventlink></li> 9355 <li><eventlink id="DynamicCodeGenerated"></eventlink></li> 9356 <li><eventlink id="DataDumpRequest"></eventlink></li> 9357 </ul> 9358 <p/> 9359 Initially, no events are enabled at either the thread level 9360 or the global level. 9361 <p/> 9362 Any needed capabilities (see Event Enabling Capabilities below) must be possessed 9363 before calling this function. 9364 <p/> 9365 Details on events are 9366 described <internallink id="EventSection">below</internallink>. 9367 </description> 9368 <origin>jvmdiClone</origin> 9369 <eventcapabilities></eventcapabilities> 9370 <parameters> 9371 <param id="mode"> 9372 <enum>jvmtiEventMode</enum> 9373 <description> 9374 <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code> 9375 </description> 9376 </param> 9377 <param id="event_type"> 9378 <enum>jvmtiEvent</enum> 9379 <description> 9380 the event to control 9381 </description> 9382 </param> 9383 <param id="event_thread"> 9384 <ptrtype> 9385 <jthread impl="noconvert"/> 9386 <nullok>event is controlled at the global level</nullok> 9387 </ptrtype> 9388 <description> 9389 The thread to control 9390 </description> 9391 </param> 9392 <param id="..."> 9393 <varargs/> 9394 <description> 9395 for future expansion 9396 </description> 9397 </param> 9398 </parameters> 9399 <errors> 9400 <error id="JVMTI_ERROR_INVALID_THREAD"> 9401 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread. 9402 </error> 9403 <error id="JVMTI_ERROR_THREAD_NOT_ALIVE"> 9404 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead). 9405 </error> 9406 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 9407 thread level control was attempted on events which do not 9408 permit thread level control. 9409 </error> 9410 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> 9411 The Required Event Enabling Capability is not possessed. 9412 </error> 9413 </errors> 9414 </function> 9415 9416 <function id="GenerateEvents" num="123"> 9417 <synopsis>Generate Events</synopsis> 9418 <description> 9419 Generate events to represent the current state of the VM. 9420 For example, if <paramlink id="event_type"/> is 9421 <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>, 9422 a <eventlink id="CompiledMethodLoad"></eventlink> event will be 9423 sent for each currently compiled method. 9424 Methods that were loaded and now have been unloaded are not sent. 9425 The history of what events have previously been sent does not 9426 effect what events are sent by this function--for example, 9427 all currently compiled methods 9428 will be sent each time this function is called. 9429 <p/> 9430 This function is useful when 9431 events may have been missed due to the agent attaching after program 9432 execution begins; this function generates the missed events. 9433 <p/> 9434 Attempts to execute Java programming language code or 9435 JNI functions may be paused until this function returns - 9436 so neither should be called from the thread sending the event. 9437 This function returns only after the missed events have been 9438 sent, processed and have returned. 9439 The event may be sent on a different thread than the thread 9440 on which the event occurred. 9441 The callback for the event must be set with 9442 <functionlink id="SetEventCallbacks"></functionlink> 9443 and the event must be enabled with 9444 <functionlink id="SetEventNotificationMode"></functionlink> 9445 or the events will not occur. 9446 If the VM no longer has the information to generate some or 9447 all of the requested events, the events are simply not sent - 9448 no error is returned. 9449 <p/> 9450 Only the following events are supported: 9451 <ul> 9452 <li><eventlink id="CompiledMethodLoad"></eventlink></li> 9453 <li><eventlink id="DynamicCodeGenerated"></eventlink></li> 9454 </ul> 9455 </description> 9456 <origin>new</origin> 9457 <capabilities> 9458 <capability id="can_generate_compiled_method_load_events"></capability> 9459 </capabilities> 9460 <parameters> 9461 <param id="event_type"> 9462 <enum>jvmtiEvent</enum> 9463 <description> 9464 The type of event to generate. Must be one of these: 9465 <ul> 9466 <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li> 9467 <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li> 9468 </ul> 9469 </description> 9470 </param> 9471 </parameters> 9472 <errors> 9473 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> 9474 <paramlink id="event_type"/> is 9475 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> 9476 and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink> 9477 is <code>false</code>. 9478 </error> 9479 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 9480 <paramlink id="event_type"/> is other than 9481 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> 9482 or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>. 9483 </error> 9484 </errors> 9485 </function> 9486 9487 </category> 9488 9489 <category id="extension" label="Extension Mechanism"> 9490 9491 <intro> 9492 These functions 9493 allow a <jvmti/> implementation to provide functions and events 9494 beyond those defined in this specification. 9495 <p/> 9496 Both extension functions and extension events have parameters 9497 each of which has a 'type' and 'kind' chosen from the following tables: 9498 9499 <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum"> 9500 <constant id="JVMTI_TYPE_JBYTE" num="101"> 9501 Java programming language primitive type - <code>byte</code>. 9502 JNI type <code>jbyte</code>. 9503 </constant> 9504 <constant id="JVMTI_TYPE_JCHAR" num="102"> 9505 Java programming language primitive type - <code>char</code>. 9506 JNI type <code>jchar</code>. 9507 </constant> 9508 <constant id="JVMTI_TYPE_JSHORT" num="103"> 9509 Java programming language primitive type - <code>short</code>. 9510 JNI type <code>jshort</code>. 9511 </constant> 9512 <constant id="JVMTI_TYPE_JINT" num="104"> 9513 Java programming language primitive type - <code>int</code>. 9514 JNI type <datalink id="jint"></datalink>. 9515 </constant> 9516 <constant id="JVMTI_TYPE_JLONG" num="105"> 9517 Java programming language primitive type - <code>long</code>. 9518 JNI type <datalink id="jlong"></datalink>. 9519 </constant> 9520 <constant id="JVMTI_TYPE_JFLOAT" num="106"> 9521 Java programming language primitive type - <code>float</code>. 9522 JNI type <datalink id="jfloat"></datalink>. 9523 </constant> 9524 <constant id="JVMTI_TYPE_JDOUBLE" num="107"> 9525 Java programming language primitive type - <code>double</code>. 9526 JNI type <datalink id="jdouble"></datalink>. 9527 </constant> 9528 <constant id="JVMTI_TYPE_JBOOLEAN" num="108"> 9529 Java programming language primitive type - <code>boolean</code>. 9530 JNI type <datalink id="jboolean"></datalink>. 9531 </constant> 9532 <constant id="JVMTI_TYPE_JOBJECT" num="109"> 9533 Java programming language object type - <code>java.lang.Object</code>. 9534 JNI type <datalink id="jobject"></datalink>. 9535 Returned values are JNI local references and must be managed. 9536 </constant> 9537 <constant id="JVMTI_TYPE_JTHREAD" num="110"> 9538 Java programming language object type - <code>java.lang.Thread</code>. 9539 <jvmti/> type <datalink id="jthread"></datalink>. 9540 Returned values are JNI local references and must be managed. 9541 </constant> 9542 <constant id="JVMTI_TYPE_JCLASS" num="111"> 9543 Java programming language object type - <code>java.lang.Class</code>. 9544 JNI type <datalink id="jclass"></datalink>. 9545 Returned values are JNI local references and must be managed. 9546 </constant> 9547 <constant id="JVMTI_TYPE_JVALUE" num="112"> 9548 Union of all Java programming language primitive and object types - 9549 JNI type <datalink id="jvalue"></datalink>. 9550 Returned values which represent object types are JNI local references and must be managed. 9551 </constant> 9552 <constant id="JVMTI_TYPE_JFIELDID" num="113"> 9553 Java programming language field identifier - 9554 JNI type <datalink id="jfieldID"></datalink>. 9555 </constant> 9556 <constant id="JVMTI_TYPE_JMETHODID" num="114"> 9557 Java programming language method identifier - 9558 JNI type <datalink id="jmethodID"></datalink>. 9559 </constant> 9560 <constant id="JVMTI_TYPE_CCHAR" num="115"> 9561 C programming language type - <code>char</code>. 9562 </constant> 9563 <constant id="JVMTI_TYPE_CVOID" num="116"> 9564 C programming language type - <code>void</code>. 9565 </constant> 9566 <constant id="JVMTI_TYPE_JNIENV" num="117"> 9567 JNI environment - <code>JNIEnv</code>. 9568 Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type. 9569 </constant> 9570 </constants> 9571 9572 <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum"> 9573 <constant id="JVMTI_KIND_IN" num="91"> 9574 Ingoing argument - <code>foo</code>. 9575 </constant> 9576 <constant id="JVMTI_KIND_IN_PTR" num="92"> 9577 Ingoing pointer argument - <code>const foo*</code>. 9578 </constant> 9579 <constant id="JVMTI_KIND_IN_BUF" num="93"> 9580 Ingoing array argument - <code>const foo*</code>. 9581 </constant> 9582 <constant id="JVMTI_KIND_ALLOC_BUF" num="94"> 9583 Outgoing allocated array argument - <code>foo**</code>. 9584 Free with <code>Deallocate</code>. 9585 </constant> 9586 <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95"> 9587 Outgoing allocated array of allocated arrays argument - <code>foo***</code>. 9588 Free with <code>Deallocate</code>. 9589 </constant> 9590 <constant id="JVMTI_KIND_OUT" num="96"> 9591 Outgoing argument - <code>foo*</code>. 9592 </constant> 9593 <constant id="JVMTI_KIND_OUT_BUF" num="97"> 9594 Outgoing array argument (pre-allocated by agent) - <code>foo*</code>. 9595 Do not <code>Deallocate</code>. 9596 </constant> 9597 </constants> 9598 9599 </intro> 9600 9601 <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info"> 9602 <field id="name"> 9603 <allocfieldbuf><char/></allocfieldbuf> 9604 <description> 9605 The parameter name, encoded as a 9606 <internallink id="mUTF">modified UTF-8</internallink> string 9607 </description> 9608 </field> 9609 <field id="kind"> 9610 <enum>jvmtiParamKind</enum> 9611 <description> 9612 The kind of the parameter - type modifiers 9613 </description> 9614 </field> 9615 <field id="base_type"> 9616 <enum>jvmtiParamTypes</enum> 9617 <description> 9618 The base type of the parameter - modified by <code>kind</code> 9619 </description> 9620 </field> 9621 <field id="null_ok"> 9622 <jboolean/> 9623 <description> 9624 Is a <code>NULL</code> argument permitted? Applies only to pointer and object types. 9625 </description> 9626 </field> 9627 </typedef> 9628 9629 <callback id="jvmtiExtensionFunction"> 9630 <enum>jvmtiError</enum> 9631 <synopsis>Extension Function</synopsis> 9632 <description> 9633 This is the implementation-specific extension function. 9634 </description> 9635 <parameters> 9636 <param id="jvmti_env"> 9637 <outptr> 9638 <struct>jvmtiEnv</struct> 9639 </outptr> 9640 <description> 9641 The <jvmti/> environment is the only fixed parameter for extension functions. 9642 </description> 9643 </param> 9644 <param id="..."> 9645 <varargs/> 9646 <description> 9647 The extension function-specific parameters 9648 </description> 9649 </param> 9650 </parameters> 9651 </callback> 9652 9653 <function id="GetExtensionFunctions" phase="onload" num="124"> 9654 <synopsis>Get Extension Functions</synopsis> 9655 9656 <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info"> 9657 <field id="func"> 9658 <ptrtype> 9659 <struct>jvmtiExtensionFunction</struct> 9660 </ptrtype> 9661 <description> 9662 The actual function to call 9663 </description> 9664 </field> 9665 <field id="id"> 9666 <allocfieldbuf><char/></allocfieldbuf> 9667 <description> 9668 The identifier for the extension function, encoded as a 9669 <internallink id="mUTF">modified UTF-8</internallink> string. 9670 Uses package name conventions. 9671 For example, <code>com.sun.hotspot.bar</code> 9672 </description> 9673 </field> 9674 <field id="short_description"> 9675 <allocfieldbuf><char/></allocfieldbuf> 9676 <description> 9677 A one sentence description of the function, encoded as a 9678 <internallink id="mUTF">modified UTF-8</internallink> string. 9679 </description> 9680 </field> 9681 <field id="param_count"> 9682 <jint/> 9683 <description> 9684 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code> 9685 </description> 9686 </field> 9687 <field id="params"> 9688 <allocfieldbuf outcount="param_count"> 9689 <struct>jvmtiParamInfo</struct> 9690 </allocfieldbuf> 9691 <description> 9692 Array of 9693 <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> 9694 parameters (<code>jvmtiEnv *jvmti_env</code> excluded) 9695 </description> 9696 </field> 9697 <field id="error_count"> 9698 <jint/> 9699 <description> 9700 The number of possible error returns (excluding universal errors) 9701 </description> 9702 </field> 9703 <field id="errors"> 9704 <allocfieldbuf outcount="error_count"> 9705 <enum>jvmtiError</enum> 9706 </allocfieldbuf> 9707 <description> 9708 Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> 9709 possible errors 9710 </description> 9711 </field> 9712 </typedef> 9713 9714 <description> 9715 Returns the set of extension functions. 9716 </description> 9717 <origin>new</origin> 9718 <capabilities> 9719 </capabilities> 9720 <parameters> 9721 <param id="extension_count_ptr"> 9722 <outptr><jint/></outptr> 9723 <description> 9724 On return, points to the number of extension functions 9725 </description> 9726 </param> 9727 <param id="extensions"> 9728 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf> 9729 <description> 9730 Returns an array of extension function info, one per function 9731 </description> 9732 </param> 9733 </parameters> 9734 <errors> 9735 </errors> 9736 </function> 9737 9738 <function id="GetExtensionEvents" phase="onload" num="125"> 9739 <synopsis>Get Extension Events</synopsis> 9740 9741 <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info"> 9742 <field id="extension_event_index"> 9743 <jint/> 9744 <description> 9745 The identifying index of the event 9746 </description> 9747 </field> 9748 <field id="id"> 9749 <allocfieldbuf><char/></allocfieldbuf> 9750 <description> 9751 The identifier for the extension event, encoded as a 9752 <internallink id="mUTF">modified UTF-8</internallink> string. 9753 Uses package name conventions. 9754 For example, <code>com.sun.hotspot.bar</code> 9755 </description> 9756 </field> 9757 <field id="short_description"> 9758 <allocfieldbuf><char/></allocfieldbuf> 9759 <description> 9760 A one sentence description of the event, encoded as a 9761 <internallink id="mUTF">modified UTF-8</internallink> string. 9762 </description> 9763 </field> 9764 <field id="param_count"> 9765 <jint/> 9766 <description> 9767 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code> 9768 </description> 9769 </field> 9770 <field id="params"> 9771 <allocfieldbuf outcount="param_count"> 9772 <struct>jvmtiParamInfo</struct> 9773 </allocfieldbuf> 9774 <description> 9775 Array of 9776 <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink> 9777 parameters (<code>jvmtiEnv *jvmti_env</code> excluded) 9778 </description> 9779 </field> 9780 </typedef> 9781 9782 <description> 9783 Returns the set of extension events. 9784 </description> 9785 <origin>new</origin> 9786 <capabilities> 9787 </capabilities> 9788 <parameters> 9789 <param id="extension_count_ptr"> 9790 <outptr><jint/></outptr> 9791 <description> 9792 On return, points to the number of extension events 9793 </description> 9794 </param> 9795 <param id="extensions"> 9796 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf> 9797 <description> 9798 Returns an array of extension event info, one per event 9799 </description> 9800 </param> 9801 </parameters> 9802 <errors> 9803 </errors> 9804 </function> 9805 9806 <callback id="jvmtiExtensionEvent"> 9807 <void/> 9808 <synopsis>Extension Event</synopsis> 9809 <description> 9810 This is the implementation-specific event. 9811 The event handler is set with 9812 <functionlink id="SetExtensionEventCallback"/>. 9813 <p/> 9814 Event handlers for extension events must be declared varargs to match this definition. 9815 Failure to do so could result in calling convention mismatch and undefined behavior 9816 on some platforms. 9817 <p/> 9818 For example, if the <code>jvmtiParamInfo</code> 9819 returned by <functionlink id="GetExtensionEvents"/> indicates that 9820 there is a <code>jint</code> parameter, the event handler should be 9821 declared: 9822<example> 9823 void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...) 9824</example> 9825 Note the terminal "<code>...</code>" which indicates varargs. 9826 </description> 9827 <parameters> 9828 <param id="jvmti_env"> 9829 <outptr> 9830 <struct>jvmtiEnv</struct> 9831 </outptr> 9832 <description> 9833 The <jvmti/> environment is the only fixed parameter for extension events. 9834 </description> 9835 </param> 9836 <param id="..."> 9837 <varargs/> 9838 <description> 9839 The extension event-specific parameters 9840 </description> 9841 </param> 9842 </parameters> 9843 </callback> 9844 9845 <function id="SetExtensionEventCallback" phase="onload" num="126"> 9846 <synopsis>Set Extension Event Callback</synopsis> 9847 9848 <description> 9849 Sets the callback function for an extension event and 9850 enables the event. Or, if the callback is <code>NULL</code>, disables 9851 the event. Note that unlike standard events, setting 9852 the callback and enabling the event are a single operation. 9853 </description> 9854 <origin>new</origin> 9855 <capabilities> 9856 </capabilities> 9857 <parameters> 9858 <param id="extension_event_index"> 9859 <jint/> 9860 <description> 9861 Identifies which callback to set. 9862 This index is the 9863 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink> 9864 field of 9865 <datalink id="jvmtiExtensionEventInfo"/>. 9866 </description> 9867 </param> 9868 <param id="callback"> 9869 <ptrtype> 9870 <struct>jvmtiExtensionEvent</struct> 9871 <nullok>disable the event</nullok> 9872 </ptrtype> 9873 <description> 9874 If <code>callback</code> is non-<code>NULL</code>, 9875 set <code>callback</code> to be the event callback function 9876 and enable the event. 9877 </description> 9878 </param> 9879 </parameters> 9880 <errors> 9881 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 9882 <paramlink id="extension_event_index"/> is not an 9883 <fieldlink id="extension_event_index" 9884 struct="jvmtiExtensionEventInfo"/> 9885 returned by 9886 <functionlink id="GetExtensionEvents"/> 9887 </error> 9888 </errors> 9889 </function> 9890 9891 </category> 9892 9893 <category id="capability" label="Capability"> 9894 9895 <intro> 9896 The capabilities functions allow you to change the 9897 functionality available to <jvmti/>--that is, 9898 which <jvmti/> 9899 functions can be called, what events can be generated, 9900 and what functionality these events and functions can 9901 provide. 9902 <p/> 9903 The "Capabilities" section of each function and event describe which 9904 capabilities, if any, they are associated with. "Required Functionality" 9905 means it is available for use and no capabilities must be added to use it. 9906 "Optional Functionality" means the agent must possess the capability 9907 before it can be used. 9908 To possess a capability, the agent must 9909 <functionlink id="AddCapabilities">add the capability</functionlink>. 9910 "Optional Features" describe capabilities which, 9911 if added, extend the feature set. 9912 <p/> 9913 The potentially available capabilities of each <jvmti/> implementation are different. 9914 Depending on the implementation, a capability: 9915 <ul> 9916 <li>may never be added</li> 9917 <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li> 9918 <li>may be added only during the <code>OnLoad</code> phase</li> 9919 <li>may be possessed by only one environment at a time</li> 9920 <li>may be possessed by only one environment at a time, 9921 and only during the <code>OnLoad</code> phase</li> 9922 <li>and so on ...</li> 9923 </ul> 9924 Frequently, the addition of a capability may incur a cost in execution speed, start up 9925 time, and/or memory footprint. Note that the overhead of using a capability 9926 is completely different than the overhead of possessing a capability. 9927 Take single stepping as an example. When single stepping is on (that 9928 is, when the event is enabled and thus actively sending events) 9929 the overhead of sending and processing an event 9930 on each instruction is huge in any implementation. 9931 However, the overhead of possessing the capability may be small or large, 9932 depending on the implementation. Also, when and if a capability is potentially 9933 available depends on the implementation. Some examples: 9934 <ul> 9935 <li>One VM might perform all execution by compiling bytecodes into 9936 native code and be unable to generate single step instructions. 9937 In this implementation the capability can not be added.</li> 9938 <li>Another VM may be able to switch execution to a single stepping 9939 interpreter at any time. In this implementation, having the capability has no 9940 overhead and could be added at any time.</li> 9941 <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted 9942 execution engine at start up, but be unable to switch between them. 9943 In this implementation the capability would need to be added 9944 during the <code>OnLoad</code> phase (before bytecode 9945 execution begins) and would have a large impact on execution speed 9946 even if single stepping was never used.</li> 9947 <li>Still another VM might be able to add an "is single stepping on" check 9948 into compiled bytecodes or a generated interpreter. Again in this implementation 9949 the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test 9950 and branch on each instruction) would be considerably less.</li> 9951 </ul> 9952 <p/> 9953 Each <jvmti/> <internallink id="environments">environment</internallink> 9954 has its own set of capabilities. 9955 Initially, that set is empty. 9956 Any desired capability must be added. 9957 If possible, capabilities should be added during the <code>OnLoad</code> phase. For most 9958 virtual machines certain capabilities require special set up for 9959 the virtual machine and this set up must happen 9960 during the <code>OnLoad</code> phase, before the virtual machine begins execution. 9961 Once a capability is added, it can 9962 only be removed if explicitly relinquished by the environment. 9963 <p/> 9964 The agent can, 9965 <functionlink id="GetPotentialCapabilities">determine what 9966 capabilities this VM can potentially provide</functionlink>, 9967 <functionlink id="AddCapabilities">add the capabilities 9968 to be used</functionlink>, 9969 <functionlink id="RelinquishCapabilities">release capabilities 9970 which are no longer needed</functionlink>, and 9971 <functionlink id="GetCapabilities">examine the currently available 9972 capabilities</functionlink>. 9973 </intro> 9974 9975 <intro id="capabilityExamples" label="Capability Examples"> 9976 For example, a freshly started agent (in the <code>OnLoad</code> function) 9977 wants to enable all possible capabilities. 9978 Note that, in general, this is not advisable as the agent may suffer 9979 a performance penalty for functionality it is not using. 9980 The code might look like this in C: 9981 <example> 9982 jvmtiCapabilities capa; 9983 jvmtiError err; 9984 9985 err = (*jvmti)->GetPotentialCapabilities(jvmti, &capa); 9986 if (err == JVMTI_ERROR_NONE) { 9987 err = (*jvmti)->AddCapabilities(jvmti, &capa); 9988 </example> 9989 For example, if an agent wants to check if it can get 9990 the bytecodes of a method (that is, it wants to check 9991 if it previously added this capability and has not 9992 relinquished it), the code might 9993 look like this in C: 9994 <example> 9995 jvmtiCapabilities capa; 9996 jvmtiError err; 9997 9998 err = (*jvmti)->GetCapabilities(jvmti, &capa); 9999 if (err == JVMTI_ERROR_NONE) { 10000 if (capa.can_get_bytecodes) { ... } } 10001 </example> 10002 </intro> 10003 10004 <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure"> 10005 <description> 10006 The functions in this category use this capabilities structure 10007 which contains boolean flags corresponding to each capability: 10008 </description> 10009 <capabilityfield id="can_tag_objects"> 10010 <description> 10011 Can set and get tags, as described in the 10012 <internallink id="Heap">Heap category</internallink>. 10013 </description> 10014 </capabilityfield> 10015 <capabilityfield id="can_generate_field_modification_events"> 10016 <description> 10017 Can set watchpoints on field modification - 10018 <functionlink id="SetFieldModificationWatch"></functionlink> 10019 </description> 10020 </capabilityfield> 10021 <capabilityfield id="can_generate_field_access_events"> 10022 <description> 10023 Can set watchpoints on field access - 10024 <functionlink id="SetFieldAccessWatch"></functionlink> 10025 </description> 10026 </capabilityfield> 10027 <capabilityfield id="can_get_bytecodes"> 10028 <description> 10029 Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink> 10030 </description> 10031 </capabilityfield> 10032 <capabilityfield id="can_get_synthetic_attribute"> 10033 <description> 10034 Can test if a field or method is synthetic - 10035 <functionlink id="IsFieldSynthetic"></functionlink> and 10036 <functionlink id="IsMethodSynthetic"></functionlink> 10037 </description> 10038 </capabilityfield> 10039 <capabilityfield id="can_get_owned_monitor_info"> 10040 <description> 10041 Can get information about ownership of monitors - 10042 <functionlink id="GetOwnedMonitorInfo"></functionlink> 10043 </description> 10044 </capabilityfield> 10045 <capabilityfield id="can_get_current_contended_monitor"> 10046 <description> 10047 Can <functionlink id="GetCurrentContendedMonitor"></functionlink> 10048 </description> 10049 </capabilityfield> 10050 <capabilityfield id="can_get_monitor_info"> 10051 <description> 10052 Can <functionlink id="GetObjectMonitorUsage"></functionlink> 10053 </description> 10054 </capabilityfield> 10055 <capabilityfield id="can_pop_frame"> 10056 <description> 10057 Can pop frames off the stack - <functionlink id="PopFrame"></functionlink> 10058 </description> 10059 </capabilityfield> 10060 <capabilityfield id="can_redefine_classes"> 10061 <description> 10062 Can redefine classes with <functionlink id="RedefineClasses"/>. 10063 </description> 10064 </capabilityfield> 10065 <capabilityfield id="can_signal_thread"> 10066 <description> 10067 Can send stop or interrupt to threads 10068 </description> 10069 </capabilityfield> 10070 <capabilityfield id="can_get_source_file_name"> 10071 <description> 10072 Can get the source file name of a class 10073 </description> 10074 </capabilityfield> 10075 <capabilityfield id="can_get_line_numbers"> 10076 <description> 10077 Can get the line number table of a method 10078 </description> 10079 </capabilityfield> 10080 <capabilityfield id="can_get_source_debug_extension"> 10081 <description> 10082 Can get the source debug extension of a class 10083 </description> 10084 </capabilityfield> 10085 <capabilityfield id="can_access_local_variables"> 10086 <description> 10087 Can set and get local variables 10088 </description> 10089 </capabilityfield> 10090 <capabilityfield id="can_maintain_original_method_order"> 10091 <description> 10092 Can return methods in the order they occur in the class file 10093 </description> 10094 </capabilityfield> 10095 <capabilityfield id="can_generate_single_step_events"> 10096 <description> 10097 Can get <eventlink id="SingleStep">single step</eventlink> events 10098 </description> 10099 </capabilityfield> 10100 <capabilityfield id="can_generate_exception_events"> 10101 <description> 10102 Can get <eventlink id="Exception">exception thrown</eventlink> and 10103 <eventlink id="ExceptionCatch">exception catch</eventlink> events 10104 </description> 10105 </capabilityfield> 10106 <capabilityfield id="can_generate_frame_pop_events"> 10107 <description> 10108 Can <functionlink id="NotifyFramePop">set</functionlink> and thus get 10109 <eventlink id="FramePop"></eventlink> events 10110 </description> 10111 </capabilityfield> 10112 <capabilityfield id="can_generate_breakpoint_events"> 10113 <description> 10114 Can <functionlink id="SetBreakpoint">set</functionlink> and thus get 10115 <eventlink id="Breakpoint"></eventlink> events 10116 </description> 10117 </capabilityfield> 10118 <capabilityfield id="can_suspend"> 10119 <description> 10120 Can suspend and resume threads 10121 </description> 10122 </capabilityfield> 10123 <capabilityfield id="can_redefine_any_class"> 10124 <description> 10125 Can modify (retransform or redefine) any modifiable class. 10126 See <functionlink id="IsModifiableClass"/>. 10127 </description> 10128 </capabilityfield> 10129 <capabilityfield id="can_get_current_thread_cpu_time"> 10130 <description> 10131 Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink> 10132 current thread CPU time 10133 </description> 10134 </capabilityfield> 10135 <capabilityfield id="can_get_thread_cpu_time"> 10136 <description> 10137 Can <functionlink id="GetThreadCpuTime">get</functionlink> 10138 thread CPU time 10139 </description> 10140 </capabilityfield> 10141 <capabilityfield id="can_generate_method_entry_events" 10142 disp1="can_generate" disp2="_method_entry_events" 10143 > 10144 <description> 10145 Can generate method entry events on entering a method 10146 </description> 10147 </capabilityfield> 10148 <capabilityfield id="can_generate_method_exit_events" 10149 disp1="can_generate" disp2="_method_exit_events" 10150 > 10151 <description> 10152 Can generate method exit events on leaving a method 10153 </description> 10154 </capabilityfield> 10155 <capabilityfield id="can_generate_all_class_hook_events" 10156 disp1="can_generate" disp2="_all_class_hook_events" 10157 > 10158 <description> 10159 Can generate ClassFileLoadHook events for every loaded class. 10160 </description> 10161 </capabilityfield> 10162 <capabilityfield id="can_generate_compiled_method_load_events" 10163 disp1="can_generate" disp2="_compiled_method_load_events" 10164 > 10165 <description> 10166 Can generate events when a method is compiled or unloaded 10167 </description> 10168 </capabilityfield> 10169 <capabilityfield id="can_generate_monitor_events" 10170 disp1="can_generate" disp2="_monitor_events" 10171 > 10172 <description> 10173 Can generate events on monitor activity 10174 </description> 10175 </capabilityfield> 10176 <capabilityfield id="can_generate_vm_object_alloc_events" 10177 disp1="can_generate" disp2="_vm_object_alloc_events" 10178 > 10179 <description> 10180 Can generate events on VM allocation of an object 10181 </description> 10182 </capabilityfield> 10183 <capabilityfield id="can_generate_native_method_bind_events" 10184 disp1="can_generate" disp2="_native_method_bind_events" 10185 > 10186 <description> 10187 Can generate events when a native method is bound to its 10188 implementation 10189 </description> 10190 </capabilityfield> 10191 <capabilityfield id="can_generate_garbage_collection_events" 10192 disp1="can_generate" disp2="_garbage_collection_events" 10193 > 10194 <description> 10195 Can generate events when garbage collection begins or ends 10196 </description> 10197 </capabilityfield> 10198 <capabilityfield id="can_generate_object_free_events" 10199 disp1="can_generate" disp2="_object_free_events" 10200 > 10201 <description> 10202 Can generate events when the garbage collector frees an object 10203 </description> 10204 </capabilityfield> 10205 <capabilityfield id="can_force_early_return" since="1.1"> 10206 <description> 10207 Can return early from a method, as described in the 10208 <internallink id="ForceEarlyReturn">Force Early Return category</internallink>. 10209 </description> 10210 </capabilityfield> 10211 <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1"> 10212 <description> 10213 Can get information about owned monitors with stack depth - 10214 <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink> 10215 </description> 10216 </capabilityfield> 10217 <capabilityfield id="can_get_constant_pool" since="1.1"> 10218 <description> 10219 Can get the constant pool of a class - 10220 <functionlink id="GetConstantPool"></functionlink> 10221 </description> 10222 </capabilityfield> 10223 <capabilityfield id="can_set_native_method_prefix" since="1.1"> 10224 <description> 10225 Can set prefix to be applied when native method cannot be resolved - 10226 <functionlink id="SetNativeMethodPrefix"/> and 10227 <functionlink id="SetNativeMethodPrefixes"/> 10228 </description> 10229 </capabilityfield> 10230 <capabilityfield id="can_retransform_classes" since="1.1"> 10231 <description> 10232 Can retransform classes with <functionlink id="RetransformClasses"/>. 10233 In addition to the restrictions imposed by the specific 10234 implementation on this capability (see the 10235 <internallink id="capability">Capability</internallink> section), 10236 this capability must be set before the 10237 <eventlink id="ClassFileLoadHook"/> event is enabled for the 10238 first time in this environment. 10239 An environment that possesses this capability at the time that 10240 <code>ClassFileLoadHook</code> is enabled for the first time is 10241 said to be <i>retransformation capable</i>. 10242 An environment that does not possess this capability at the time that 10243 <code>ClassFileLoadHook</code> is enabled for the first time is 10244 said to be <i>retransformation incapable</i>. 10245 </description> 10246 </capabilityfield> 10247 <capabilityfield id="can_retransform_any_class" since="1.1"> 10248 <description> 10249 <functionlink id="RetransformClasses"/> can be called on any modifiable class. 10250 See <functionlink id="IsModifiableClass"/>. 10251 (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> 10252 must also be set) 10253 </description> 10254 </capabilityfield> 10255 <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1"> 10256 <description> 10257 Can generate events when the VM is unable to allocate memory from 10258 the <tm>Java</tm> platform heap. 10259 See <eventlink id="ResourceExhausted"/>. 10260 </description> 10261 </capabilityfield> 10262 <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1"> 10263 <description> 10264 Can generate events when the VM is unable to create a thread. 10265 See <eventlink id="ResourceExhausted"/>. 10266 </description> 10267 </capabilityfield> 10268 <capabilityfield id="can_generate_early_vmstart" since="9"> 10269 <description> 10270 Can generate the <code>VMStart</code> event early. 10271 See <eventlink id="VMStart"/>. 10272 </description> 10273 </capabilityfield> 10274 <capabilityfield id="can_generate_early_class_hook_events" since="9"> 10275 <description> 10276 Can generate the <eventlink id="ClassFileLoadHook"/> events 10277 in the primordial phase. If this capability and 10278 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events"> 10279 <code>can_generate_all_class_hook_events</code></internallink> 10280 are enabled then the <eventlink id="ClassFileLoadHook"/> events 10281 can be posted for classes loaded in the primordial phase. 10282 See <eventlink id="ClassFileLoadHook"/>. 10283 </description> 10284 </capabilityfield> 10285 </capabilitiestypedef> 10286 10287 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140"> 10288 <synopsis>Get Potential Capabilities</synopsis> 10289 <description> 10290 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/> 10291 features that can potentially be possessed by this environment 10292 at this time. 10293 The returned capabilities differ from the complete set of capabilities 10294 implemented by the VM in two cases: another environment possesses 10295 capabilities that can only be possessed by one environment, or the 10296 current <functionlink id="GetPhase">phase</functionlink> is live, 10297 and certain capabilities can only be added during the <code>OnLoad</code> phase. 10298 The <functionlink id="AddCapabilities"></functionlink> function 10299 may be used to set any or all or these capabilities. 10300 Currently possessed capabilities are included. 10301 <p/> 10302 Typically this function is used in the <code>OnLoad</code> function. 10303 Some virtual machines may allow a limited set of capabilities to be 10304 added in the live phase. 10305 In this case, the set of potentially available capabilities 10306 will likely differ from the <code>OnLoad</code> phase set. 10307 <p/> 10308 See the 10309 <internallink id="capabilityExamples">Capability Examples</internallink>. 10310 </description> 10311 <origin>new</origin> 10312 <capabilities> 10313 </capabilities> 10314 <parameters> 10315 <param id="capabilities_ptr"> 10316 <outptr><struct>jvmtiCapabilities</struct></outptr> 10317 <description> 10318 On return, points to the <jvmti/> capabilities that may be added. 10319 </description> 10320 </param> 10321 </parameters> 10322 <errors> 10323 </errors> 10324 </function> 10325 10326 <elide> 10327 <function id="EstimateCostOfCapabilities" phase="onload" num="141"> 10328 <synopsis>Estimate Cost Of Capabilities</synopsis> 10329 <description> 10330 <issue>There is strong opposition to this function. The concern is 10331 that it would be difficult or impossible to provide meaningful 10332 numbers, as the amount of impact is conditional on many factors 10333 that a single number could not represent. There is doubt that 10334 conditional implementations would be used or are even a good idea. 10335 The thought is that release documentation for the implementation 10336 would be the best means of exposing this information. 10337 Unless new arguments are presented, I intend to remove this 10338 function in the next revision. 10339 </issue> 10340 <p/> 10341 Return via the <paramlink id="time_impact_ptr"></paramlink> and 10342 <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact 10343 of adding the capabilities pointed to by 10344 <paramlink id="capabilities_ptr"></paramlink>. 10345 The returned estimates are in percentage of additional overhead, thus 10346 a time impact of 100 mean the application might run 10347 at half the speed. 10348 The estimates are very rough approximations and are not guaranteed. 10349 Note also, that the estimates are of the impact of having the 10350 capability available--when and if it is used the impact may be 10351 much greater. 10352 Estimates can be for a single capability or for a set of 10353 capabilities. Note that the costs are not necessarily additive, 10354 adding support for one capability might make another available 10355 for free or conversely having two capabilities at once may 10356 have multiplicative impact. 10357 Estimates are relative to the current set of capabilities - 10358 that is, how much more impact given the currently possessed capabilities. 10359 <p/> 10360 Typically this function is used in the OnLoad function, 10361 some virtual machines may allow a limited set of capabilities to be 10362 added in the live phase. 10363 In this case, the set of potentially available capabilities 10364 will likely differ from the OnLoad phase set. 10365 <p/> 10366 See the 10367 <internallink id="capabilityExamples">Capability Examples</internallink>. 10368 </description> 10369 <origin>new</origin> 10370 <capabilities> 10371 </capabilities> 10372 <parameters> 10373 <param id="capabilities_ptr"> 10374 <inptr><struct>jvmtiCapabilities</struct></inptr> 10375 <description> 10376 points to the <jvmti/> capabilities to evaluate. 10377 </description> 10378 </param> 10379 <param id="time_impact_ptr"> 10380 <outptr><jint/></outptr> 10381 <description> 10382 On return, points to the estimated percentage increase in 10383 run time if this capability was added. 10384 </description> 10385 </param> 10386 <param id="space_impact_ptr"> 10387 <outptr><jint/></outptr> 10388 <description> 10389 On return, points to the estimated percentage increase in 10390 memory space used if this capability was added. 10391 </description> 10392 </param> 10393 </parameters> 10394 <errors> 10395 <error id="JVMTI_ERROR_NOT_AVAILABLE"> 10396 The desired capabilities are not even potentially available. 10397 </error> 10398 </errors> 10399 </function> 10400 </elide> 10401 10402 <function id="AddCapabilities" jkernel="yes" phase="onload" num="142"> 10403 <synopsis>Add Capabilities</synopsis> 10404 <description> 10405 Set new capabilities by adding the capabilities 10406 whose values are set to one (<code>1</code>) in 10407 <code>*</code><paramlink id="capabilities_ptr"></paramlink>. 10408 All previous capabilities are retained. 10409 Typically this function is used in the <code>OnLoad</code> function. 10410 Some virtual machines may allow a limited set of capabilities to be 10411 added in the live phase. 10412 <p/> 10413 See the 10414 <internallink id="capabilityExamples">Capability Examples</internallink>. 10415 </description> 10416 <origin>new</origin> 10417 <capabilities> 10418 </capabilities> 10419 <parameters> 10420 <param id="capabilities_ptr"> 10421 <inptr><struct>jvmtiCapabilities</struct></inptr> 10422 <description> 10423 Points to the <jvmti/> capabilities to add. 10424 </description> 10425 </param> 10426 </parameters> 10427 <errors> 10428 <error id="JVMTI_ERROR_NOT_AVAILABLE"> 10429 The desired capabilities are not even potentially available. 10430 </error> 10431 </errors> 10432 </function> 10433 10434 10435 <function id="RelinquishCapabilities" phase="onload" num="143"> 10436 <synopsis>Relinquish Capabilities</synopsis> 10437 <description> 10438 Relinquish the capabilities 10439 whose values are set to one (<code>1</code>) in 10440 <code>*</code><paramlink id="capabilities_ptr"></paramlink>. 10441 Some implementations may allow only one environment to have a capability 10442 (see the <internallink id="capability">capability introduction</internallink>). 10443 This function releases capabilities 10444 so that they may be used by other agents. 10445 All other capabilities are retained. 10446 The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>. 10447 Attempting to relinquish a capability that the agent does not possess is not an error. 10448 <issue> 10449 It is possible for the agent to be actively using capabilities 10450 which are being relinquished. For example, a thread is currently 10451 suspended and can_suspend is being relinquished or an event is currently 10452 enabled and can_generate_whatever is being relinquished. 10453 There are three possible ways we could spec this: 10454 <ul> 10455 <li>relinquish automatically releases them</li> 10456 <li>relinquish checks and returns some error code if held</li> 10457 <li>it is the agent's responsibility and it is not checked</li> 10458 </ul> 10459 One of these should be chosen. 10460 </issue> 10461 </description> 10462 <origin>new</origin> 10463 <capabilities> 10464 </capabilities> 10465 <parameters> 10466 <param id="capabilities_ptr"> 10467 <inptr><struct>jvmtiCapabilities</struct></inptr> 10468 <description> 10469 Points to the <jvmti/> capabilities to relinquish. 10470 </description> 10471 </param> 10472 </parameters> 10473 <errors> 10474 </errors> 10475 </function> 10476 10477 10478 10479 <function id="GetCapabilities" jkernel="yes" phase="any" num="89"> 10480 <synopsis>Get Capabilities</synopsis> 10481 <description> 10482 Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/> 10483 features which this environment currently possesses. 10484 Each possessed capability is indicated by a one (<code>1</code>) in the 10485 corresponding field of the <internallink id="jvmtiCapabilities">capabilities 10486 structure</internallink>. 10487 An environment does not possess a capability unless it has been successfully added with 10488 <functionlink id="AddCapabilities"/>. 10489 An environment only loses possession of a capability if it has been relinquished with 10490 <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result 10491 of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which 10492 have been made. 10493 <p/> 10494 See the 10495 <internallink id="capabilityExamples">Capability Examples</internallink>. 10496 </description> 10497 <origin>jvmdiClone</origin> 10498 <capabilities> 10499 </capabilities> 10500 <parameters> 10501 <param id="capabilities_ptr"> 10502 <outptr><struct>jvmtiCapabilities</struct></outptr> 10503 <description> 10504 On return, points to the <jvmti/> capabilities. 10505 </description> 10506 </param> 10507 </parameters> 10508 <errors> 10509 </errors> 10510 </function> 10511 10512 </category> 10513 10514 10515 <category id="timers" label="Timers"> 10516 10517 <intro> 10518 These functions provide timing information. 10519 The resolution at which the time is updated is not specified. 10520 They provides nanosecond precision, but not necessarily nanosecond accuracy. 10521 Details about the timers, such as their maximum values, can be accessed with 10522 the timer information functions. 10523 </intro> 10524 10525 <typedef id="jvmtiTimerInfo" label="Timer Info"> 10526 <description> 10527 The information function for each timer returns this data structure. 10528 </description> 10529 <field id="max_value"> 10530 <jlong/> 10531 <description> 10532 The maximum value the timer can reach. 10533 After this value is reached the timer wraps back to zero. 10534 This is an unsigned value. If tested or printed as a jlong (signed value) 10535 it may appear to be a negative number. 10536 </description> 10537 </field> 10538 <field id="may_skip_forward"> 10539 <jboolean/> 10540 <description> 10541 If true, the timer can be externally adjusted and as a result skip forward. 10542 If false, the timer value will never increase faster than real time. 10543 </description> 10544 </field> 10545 <field id="may_skip_backward"> 10546 <jboolean/> 10547 <description> 10548 If true, the timer can be externally adjusted and as a result skip backward. 10549 If false, the timer value will be monotonically increasing. 10550 </description> 10551 </field> 10552 <field id="kind"> 10553 <enum>jvmtiTimerKind</enum> 10554 <description> 10555 The kind of timer. 10556 On a platform that does not distinguish between user and system time, <datalink 10557 id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink> 10558 is returned. 10559 </description> 10560 </field> 10561 <field id="reserved1"> 10562 <jlong/> 10563 <description> 10564 Reserved for future use. 10565 </description> 10566 </field> 10567 <field id="reserved2"> 10568 <jlong/> 10569 <description> 10570 Reserved for future use. 10571 </description> 10572 </field> 10573 </typedef> 10574 10575 <intro> 10576 Where the timer kind is -- 10577 10578 <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum"> 10579 <constant id="JVMTI_TIMER_USER_CPU" num="30"> 10580 CPU time that a thread is in user mode. 10581 </constant> 10582 <constant id="JVMTI_TIMER_TOTAL_CPU" num="31"> 10583 CPU time that a thread is in user or system mode. 10584 </constant> 10585 <constant id="JVMTI_TIMER_ELAPSED" num="32"> 10586 Elapsed time. 10587 </constant> 10588 </constants> 10589 </intro> 10590 10591 <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe" impl="innative notrace" phase="start" num="134"> 10592 <synopsis>Get Current Thread CPU Timer Information</synopsis> 10593 <description> 10594 Get information about the 10595 <functionlink id="GetCurrentThreadCpuTime"/> timer. 10596 The fields of the <datalink id="jvmtiTimerInfo"/> structure 10597 are filled in with details about the timer. 10598 This information is specific to the platform and the implementation of 10599 <functionlink id="GetCurrentThreadCpuTime"/> and thus 10600 does not vary by thread nor does it vary 10601 during a particular invocation of the VM. 10602 <p/> 10603 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> 10604 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values 10605 returned by <code>GetCurrentThreadCpuTimerInfo</code> 10606 and <functionlink id="GetThreadCpuTimerInfo"/> 10607 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. 10608 </description> 10609 <origin>new</origin> 10610 <capabilities> 10611 <required id="can_get_current_thread_cpu_time"> 10612 Can get current thread CPU time. 10613 </required> 10614 </capabilities> 10615 <parameters> 10616 <param id="info_ptr"> 10617 <outptr><struct>jvmtiTimerInfo</struct></outptr> 10618 <description> 10619 On return, filled with information describing the time 10620 returned by <functionlink id="GetCurrentThreadCpuTime"/>. 10621 </description> 10622 </param> 10623 </parameters> 10624 <errors> 10625 </errors> 10626 </function> 10627 10628 <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135"> 10629 <synopsis>Get Current Thread CPU Time</synopsis> 10630 <description> 10631 Return the CPU time utilized by the current thread. 10632 <p/> 10633 Note that the <functionlink id="GetThreadCpuTime"/> 10634 function provides CPU time for any thread, including 10635 the current thread. <code>GetCurrentThreadCpuTime</code> 10636 exists to support platforms which cannot 10637 supply CPU time for threads other than the current 10638 thread or which have more accurate information for 10639 the current thread (see 10640 <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs 10641 <functionlink id="GetThreadCpuTimerInfo"/>). 10642 On many platforms this call will be equivalent to: 10643<example> 10644 GetThreadCpuTime(env, NULL, nanos_ptr) 10645</example> 10646 </description> 10647 <origin>new</origin> 10648 <capabilities> 10649 <required id="can_get_current_thread_cpu_time"> 10650 Can get current thread CPU time. 10651 <p/> 10652 If this capability is enabled after threads have started, 10653 the implementation may choose any time up 10654 to and including the time that the capability is enabled 10655 as the point where CPU time collection starts. 10656 <p/> 10657 This capability must be potentially available on any 10658 platform where 10659 <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink> 10660 is potentially available. 10661 </required> 10662 </capabilities> 10663 <parameters> 10664 <param id="nanos_ptr"> 10665 <outptr><jlong/></outptr> 10666 <description> 10667 On return, points to the CPU time used by this thread 10668 in nanoseconds. 10669 This is an unsigned value. If tested or printed as a jlong (signed value) 10670 it may appear to be a negative number. 10671 </description> 10672 </param> 10673 </parameters> 10674 <errors> 10675 </errors> 10676 </function> 10677 10678 <function id="GetThreadCpuTimerInfo" num="136"> 10679 <synopsis>Get Thread CPU Timer Information</synopsis> 10680 <description> 10681 Get information about the 10682 <functionlink id="GetThreadCpuTime"/> timer. 10683 The fields of the <datalink id="jvmtiTimerInfo"/> structure 10684 are filled in with details about the timer. 10685 This information is specific to the platform and the implementation of 10686 <functionlink id="GetThreadCpuTime"/> and thus 10687 does not vary by thread nor does it vary 10688 during a particular invocation of the VM. 10689 <p/> 10690 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> 10691 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values 10692 returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/> 10693 and <code>GetThreadCpuTimerInfo</code> 10694 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. 10695 </description> 10696 <origin>new</origin> 10697 <capabilities> 10698 <required id="can_get_thread_cpu_time"> 10699 Can get thread CPU time. 10700 </required> 10701 </capabilities> 10702 <parameters> 10703 <param id="info_ptr"> 10704 <outptr><struct>jvmtiTimerInfo</struct></outptr> 10705 <description> 10706 On return, filled with information describing the time 10707 returned by <functionlink id="GetThreadCpuTime"/>. 10708 </description> 10709 </param> 10710 </parameters> 10711 <errors> 10712 </errors> 10713 </function> 10714 10715 <function id="GetThreadCpuTime" num="137"> 10716 <synopsis>Get Thread CPU Time</synopsis> 10717 <description> 10718 Return the CPU time utilized by the specified thread. 10719 <p/> 10720 Get information about this timer with 10721 <functionlink id="GetThreadCpuTimerInfo"/>. 10722 </description> 10723 <origin>new</origin> 10724 <capabilities> 10725 <required id="can_get_thread_cpu_time"> 10726 Can get thread CPU time. 10727 <p/> 10728 If this capability is enabled after threads have started, 10729 the implementation may choose any time up 10730 to and including the time that the capability is enabled 10731 as the point where CPU time collection starts. 10732 </required> 10733 </capabilities> 10734 <parameters> 10735 <param id="thread"> 10736 <jthread null="current"/> 10737 <description> 10738 The thread to query. 10739 </description> 10740 </param> 10741 <param id="nanos_ptr"> 10742 <outptr><jlong/></outptr> 10743 <description> 10744 On return, points to the CPU time used by the specified thread 10745 in nanoseconds. 10746 This is an unsigned value. If tested or printed as a jlong (signed value) 10747 it may appear to be a negative number. 10748 </description> 10749 </param> 10750 </parameters> 10751 <errors> 10752 </errors> 10753 </function> 10754 10755 <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138"> 10756 <synopsis>Get Timer Information</synopsis> 10757 <description> 10758 Get information about the 10759 <functionlink id="GetTime"/> timer. 10760 The fields of the <datalink id="jvmtiTimerInfo"/> structure 10761 are filled in with details about the timer. 10762 This information will not change during a particular invocation of the VM. 10763 </description> 10764 <origin>new</origin> 10765 <capabilities> 10766 </capabilities> 10767 <parameters> 10768 <param id="info_ptr"> 10769 <outptr><struct>jvmtiTimerInfo</struct></outptr> 10770 <description> 10771 On return, filled with information describing the time 10772 returned by <functionlink id="GetTime"/>. 10773 </description> 10774 </param> 10775 </parameters> 10776 <errors> 10777 </errors> 10778 </function> 10779 10780 <function id="GetTime" phase="any" callbacksafe="safe" num="139"> 10781 <synopsis>Get Time</synopsis> 10782 <description> 10783 Return the current value of the system timer, in nanoseconds. 10784 <p/> 10785 The value returned represents nanoseconds since some fixed but 10786 arbitrary time (perhaps in the future, so values may be 10787 negative). This function provides nanosecond precision, but not 10788 necessarily nanosecond accuracy. No guarantees are made about 10789 how frequently values change. 10790 <p/> 10791 Get information about this timer with 10792 <functionlink id="GetTimerInfo"/>. 10793 </description> 10794 <origin>new</origin> 10795 <capabilities> 10796 </capabilities> 10797 <parameters> 10798 <param id="nanos_ptr"> 10799 <outptr><jlong/></outptr> 10800 <description> 10801 On return, points to the time in nanoseconds. 10802 This is an unsigned value. If tested or printed as a jlong (signed value) 10803 it may appear to be a negative number. 10804 </description> 10805 </param> 10806 </parameters> 10807 <errors> 10808 </errors> 10809 </function> 10810 10811 <function id="GetAvailableProcessors" phase="any" num="144"> 10812 <synopsis>Get Available Processors</synopsis> 10813 <description> 10814 Returns the number of processors available to the Java virtual machine. 10815 <p/> 10816 This value may change during a particular invocation of the virtual machine. 10817 Applications that are sensitive to the number of available processors should 10818 therefore occasionally poll this property. 10819 </description> 10820 <origin>new</origin> 10821 <capabilities> 10822 </capabilities> 10823 <parameters> 10824 <param id="processor_count_ptr"> 10825 <outptr><jint/></outptr> 10826 <description> 10827 On return, points to the maximum number of processors available to the 10828 virtual machine; never smaller than one. 10829 </description> 10830 </param> 10831 </parameters> 10832 <errors> 10833 </errors> 10834 </function> 10835 10836 </category> 10837 10838 10839 <category id="classLoaderSearch" label="Class Loader Search"> 10840 10841 <intro> 10842 These functions allow the agent to add to the locations that a class loader searches for a class. 10843 This is useful for installing instrumentation under the correct class loader. 10844 </intro> 10845 10846 <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149"> 10847 <synopsis>Add To Bootstrap Class Loader Search</synopsis> 10848 <description> 10849 This function can be used to cause instrumentation classes to be defined by the 10850 bootstrap class loader. See <vmspec chapter="5.3.1"/>. 10851 After the bootstrap 10852 class loader unsuccessfully searches for a class, the specified platform-dependent 10853 search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in 10854 the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, 10855 the segments will be searched in the order that this function was called. 10856 <p/> 10857 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 10858 search path segment to be searched after the bootstrap class loader unsuccessfully searches 10859 for a class. The segment is typically a directory or JAR file. 10860 <p/> 10861 In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent 10862 path to a <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html"> 10863 JAR file</externallink>. The agent should take care that the JAR file does not 10864 contain any classes or resources other than those to be defined by the bootstrap 10865 class loader for the purposes of instrumentation. 10866 <p/> 10867 <vmspec/> specifies that a subsequent attempt to resolve a symbolic 10868 reference that the Java virtual machine has previously unsuccessfully attempted 10869 to resolve always fails with the same error that was thrown as a result of the 10870 initial resolution attempt. Consequently, if the JAR file contains an entry 10871 that corresponds to a class for which the Java virtual machine has 10872 unsuccessfully attempted to resolve a reference, then subsequent attempts to 10873 resolve that reference will fail with the same error as the initial attempt. 10874 </description> 10875 <origin>new</origin> 10876 <capabilities> 10877 </capabilities> 10878 <parameters> 10879 <param id="segment"> 10880 <inbuf><char/></inbuf> 10881 <description> 10882 The platform-dependent search path segment, encoded as a 10883 <internallink id="mUTF">modified UTF-8</internallink> string. 10884 </description> 10885 </param> 10886 </parameters> 10887 <errors> 10888 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 10889 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an 10890 existing JAR file is an invalid path. 10891 </error> 10892 </errors> 10893 </function> 10894 10895 <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1"> 10896 <synopsis>Add To System Class Loader Search</synopsis> 10897 <description> 10898 This function can be used to cause instrumentation classes to be 10899 defined by the system class loader. See <vmspec chapter="5.3.2"/>. 10900 After the class loader unsuccessfully searches for a class, the specified platform-dependent search 10901 path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the 10902 <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the 10903 segments will be searched in the order that this function was called. 10904 <p/> 10905 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 10906 search path segment to be searched after the system class loader unsuccessfully searches 10907 for a class. The segment is typically a directory or JAR file. 10908 <p/> 10909 In the live phase the <paramlink id="segment"/> is a platform-dependent path to a <externallink 10910 id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">JAR file</externallink> to be 10911 searched after the system class loader unsuccessfully searches for a class. The agent should 10912 take care that the JAR file does not contain any classes or resources other than those to be 10913 defined by the system class loader for the purposes of instrumentation. 10914 <p/> 10915 In the live phase the system class loader supports adding a JAR file to be searched if 10916 the system class loader implements a method name <code>appendToClassPathForInstrumentation</code> 10917 which takes a single parameter of type <code>java.lang.String</code>. The method is not required 10918 to have <code>public</code> access. 10919 <p/> 10920 <vmspec/> specifies that a subsequent attempt to resolve a symbolic 10921 reference that the Java virtual machine has previously unsuccessfully attempted 10922 to resolve always fails with the same error that was thrown as a result of the 10923 initial resolution attempt. Consequently, if the JAR file contains an entry 10924 that corresponds to a class for which the Java virtual machine has 10925 unsuccessfully attempted to resolve a reference, then subsequent attempts to 10926 resolve that reference will fail with the same error as the initial attempt. 10927 </description> 10928 <origin>new</origin> 10929 <capabilities> 10930 </capabilities> 10931 <parameters> 10932 <param id="segment"> 10933 <inbuf><char/></inbuf> 10934 <description> 10935 The platform-dependent search path segment, encoded as a 10936 <internallink id="mUTF">modified UTF-8</internallink> string. 10937 </description> 10938 </param> 10939 </parameters> 10940 <errors> 10941 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 10942 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an 10943 existing JAR file is an invalid path. 10944 </error> 10945 <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED"> 10946 Operation not supported by the system class loader. 10947 </error> 10948 </errors> 10949 </function> 10950 10951 </category> 10952 10953 10954 <category id="props" label="System Properties"> 10955 10956 <intro> 10957 These functions get and set system properties. 10958 </intro> 10959 10960 <function id="GetSystemProperties" phase="onload" num="130"> 10961 <synopsis>Get System Properties</synopsis> 10962 <description> 10963 The list of VM system property keys which may be used with 10964 <functionlink id="GetSystemProperty"/> is returned. 10965 It is strongly recommended that virtual machines provide the 10966 following property keys: 10967 <ul> 10968 <li><code>java.vm.vendor</code></li> 10969 <li><code>java.vm.version</code></li> 10970 <li><code>java.vm.name</code></li> 10971 <li><code>java.vm.info</code></li> 10972 <li><code>java.library.path</code></li> 10973 <li><code>java.class.path</code></li> 10974 </ul> 10975 Provides access to system properties defined by and used 10976 by the VM. 10977 Properties set on the command-line are included. 10978 This allows getting and setting of these properties 10979 before the VM even begins executing bytecodes. 10980 Since this is a VM view of system properties, the set of available 10981 properties will usually be different than that 10982 in <code>java.lang.System.getProperties</code>. 10983 JNI method invocation may be used to access 10984 <code>java.lang.System.getProperties</code>. 10985 <p/> 10986 The set of properties may grow during execution. 10987 </description> 10988 <origin>new</origin> 10989 <capabilities> 10990 </capabilities> 10991 <parameters> 10992 <param id="count_ptr"> 10993 <outptr><jint/></outptr> 10994 <description> 10995 On return, points to the number of property keys returned. 10996 </description> 10997 </param> 10998 <param id="property_ptr"> 10999 <allocallocbuf outcount="count_ptr"><char/></allocallocbuf> 11000 <description> 11001 On return, points to an array of property keys, encoded as 11002 <internallink id="mUTF">modified UTF-8</internallink> strings. 11003 </description> 11004 </param> 11005 </parameters> 11006 <errors> 11007 </errors> 11008 </function> 11009 11010 <function id="GetSystemProperty" phase="onload" num="131"> 11011 <synopsis>Get System Property</synopsis> 11012 <description> 11013 Return a VM system property value given the property key. 11014 <p/> 11015 The function <functionlink id="GetSystemProperties"/> 11016 returns the set of property keys which may be used. 11017 The properties which can be retrieved may grow during 11018 execution. 11019 <p/> 11020 Since this is a VM view of system properties, the values 11021 of properties may differ from that returned by 11022 <code>java.lang.System.getProperty(String)</code>. 11023 A typical VM might copy the values of the VM system 11024 properties into the <code>Properties</code> held by 11025 <code>java.lang.System</code> during the initialization 11026 of that class. Thereafter any changes to the VM system 11027 properties (with <functionlink id="SetSystemProperty"/>) 11028 or the <code>java.lang.System</code> system properties 11029 (with <code>java.lang.System.setProperty(String,String)</code>) 11030 would cause the values to diverge. 11031 JNI method invocation may be used to access 11032 <code>java.lang.System.getProperty(String)</code>. 11033 </description> 11034 <origin>new</origin> 11035 <capabilities> 11036 </capabilities> 11037 <parameters> 11038 <param id="property"> 11039 <inbuf><char/></inbuf> 11040 <description> 11041 The key of the property to retrieve, encoded as a 11042 <internallink id="mUTF">modified UTF-8</internallink> string. 11043 </description> 11044 </param> 11045 <param id="value_ptr"> 11046 <allocbuf><char/></allocbuf> 11047 <description> 11048 On return, points to the property value, encoded as a 11049 <internallink id="mUTF">modified UTF-8</internallink> string. 11050 </description> 11051 </param> 11052 </parameters> 11053 <errors> 11054 <error id="JVMTI_ERROR_NOT_AVAILABLE"> 11055 This property is not available. 11056 Use <functionlink id="GetSystemProperties"/> to find available properties. 11057 </error> 11058 </errors> 11059 </function> 11060 11061 <function id="SetSystemProperty" phase="onloadOnly" num="132"> 11062 <synopsis>Set System Property</synopsis> 11063 <description> 11064 Set a VM system property value. 11065 <p/> 11066 The function <functionlink id="GetSystemProperties"/> 11067 returns the set of property keys, some of these may be settable. 11068 See <functionlink id="GetSystemProperty"/>. 11069 </description> 11070 <origin>new</origin> 11071 <capabilities> 11072 </capabilities> 11073 <parameters> 11074 <param id="property"> 11075 <inbuf><char/></inbuf> 11076 <description> 11077 The key of the property, encoded as a 11078 <internallink id="mUTF">modified UTF-8</internallink> string. 11079 </description> 11080 </param> 11081 <param id="value_ptr"> 11082 <inbuf> 11083 <char/> 11084 <nullok> 11085 do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/> 11086 if the property is not writeable 11087 </nullok> 11088 </inbuf> 11089 <description> 11090 The property value to set, encoded as a 11091 <internallink id="mUTF">modified UTF-8</internallink> string. 11092 </description> 11093 </param> 11094 </parameters> 11095 <errors> 11096 <error id="JVMTI_ERROR_NOT_AVAILABLE"> 11097 This property is not available or is not writeable. 11098 </error> 11099 </errors> 11100 </function> 11101 11102 </category> 11103 11104 <category id="general" label="General"> 11105 11106 <intro> 11107 </intro> 11108 11109 <function id="GetPhase" jkernel="yes" phase="any" num="133"> 11110 <synopsis>Get Phase</synopsis> 11111 <description> 11112 Return the current phase of VM execution. 11113 The phases proceed in sequence: 11114 <constants id="jvmtiPhase" label="Phases of execution" kind="enum"> 11115 <constant id="JVMTI_PHASE_ONLOAD" num="1"> 11116 <code>OnLoad</code> phase: while in the 11117 <internallink id="onload"><code>Agent_OnLoad</code></internallink> 11118 or, for statically linked agents, the <internallink id="onload"> 11119 <code>Agent_OnLoad_<agent-lib-name> 11120 </code></internallink> function. 11121 </constant> 11122 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2"> 11123 Primordial phase: between return from <code>Agent_OnLoad</code> 11124 or <code>Agent_OnLoad_<agent-lib-name></code> and the 11125 <code>VMStart</code> event. 11126 </constant> 11127 <constant id="JVMTI_PHASE_START" num="6"> 11128 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event 11129 is sent and until the <code>VMInit</code> event is sent. 11130 </constant> 11131 <constant id="JVMTI_PHASE_LIVE" num="4"> 11132 Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent 11133 and until the <eventlink id="VMDeath"></eventlink> event returns. 11134 </constant> 11135 <constant id="JVMTI_PHASE_DEAD" num="8"> 11136 Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after 11137 start-up failure. 11138 </constant> 11139 </constants> 11140 In the case of start-up failure the VM will proceed directly to the dead 11141 phase skipping intermediate phases and neither a <code>VMInit</code> nor 11142 <code>VMDeath</code> event will be sent. 11143 <p/> 11144 Most <jvmti/> functions operate only in the live phase. 11145 The following functions operate in either the <code>OnLoad</code> or live phases: 11146 <functionphaselist phase="onload"/> 11147 The following functions operate in only the <code>OnLoad</code> phase: 11148 <functionphaselist phase="onloadOnly"/> 11149 The following functions operate in the start or live phases: 11150 <functionphaselist phase="start"/> 11151 The following functions operate in any phase: 11152 <functionphaselist phase="any"/> 11153 JNI functions (except the Invocation API) must only be used in the start or live phases. 11154 <p/> 11155 Most <jvmti/> events are sent only in the live phase. 11156 The following events operate in others phases: 11157 <eventphaselist phase="start"/> 11158 <eventphaselist phase="any"/> 11159 </description> 11160 <origin>new</origin> 11161 <capabilities> 11162 </capabilities> 11163 <parameters> 11164 <param id="phase_ptr"> 11165 <outptr><enum>jvmtiPhase</enum></outptr> 11166 <description> 11167 On return, points to the phase. 11168 </description> 11169 </param> 11170 </parameters> 11171 <errors> 11172 </errors> 11173 </function> 11174 11175 <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127"> 11176 <synopsis>Dispose Environment</synopsis> 11177 <description> 11178 Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code> 11179 (see <internallink id="environments"><jvmti/> Environments</internallink>). 11180 Dispose of any resources held by the environment. 11181 <issue> 11182 What resources are reclaimed? What is undone? 11183 Breakpoints,watchpoints removed? 11184 </issue> 11185 Threads suspended by this environment are not resumed by this call, 11186 this must be done explicitly by the agent. 11187 Memory allocated by this environment via calls to <jvmti/> functions 11188 is not released, this can be done explicitly by the agent 11189 by calling <functionlink id="Deallocate"/>. 11190 Raw monitors created by this environment are not destroyed, 11191 this can be done explicitly by the agent 11192 by calling <functionlink id="DestroyRawMonitor"/>. 11193 The state of threads waiting on raw monitors created by this environment 11194 are not affected. 11195 <p/> 11196 Any <functionlink id="SetNativeMethodPrefix">native method 11197 prefixes</functionlink> for this environment will be unset; 11198 the agent must remove any prefixed native methods before 11199 dispose is called. 11200 <p/> 11201 Any <internallink id="capability">capabilities</internallink> 11202 held by this environment are relinquished. 11203 <p/> 11204 Events enabled by this environment will no longer be sent, however 11205 event handlers currently running will continue to run. Caution must 11206 be exercised in the design of event handlers whose environment may 11207 be disposed and thus become invalid during their execution. 11208 <p/> 11209 This environment may not be used after this call. 11210 This call returns to the caller. 11211 </description> 11212 <origin>new</origin> 11213 <capabilities> 11214 </capabilities> 11215 <parameters> 11216 </parameters> 11217 <errors> 11218 </errors> 11219 </function> 11220 11221 <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148"> 11222 <synopsis>Set Environment Local Storage</synopsis> 11223 <description> 11224 The VM stores a pointer value associated with each environment. 11225 This pointer value is called <i>environment-local storage</i>. 11226 This value is <code>NULL</code> unless set with this function. 11227 Agents can allocate memory in which they store environment specific 11228 information. By setting environment-local storage it can then be 11229 accessed with 11230 <functionlink id="GetEnvironmentLocalStorage"></functionlink>. 11231 <p/> 11232 Called by the agent to set the value of the <jvmti/> 11233 environment-local storage. <jvmti/> supplies to the agent a pointer-size 11234 environment-local storage that can be used to record per-environment 11235 information. 11236 </description> 11237 <origin>new</origin> 11238 <capabilities> 11239 </capabilities> 11240 <parameters> 11241 <param id="data"> 11242 <inbuf> 11243 <void/> 11244 <nullok>value is set to <code>NULL</code></nullok> 11245 </inbuf> 11246 <description> 11247 The value to be entered into the environment-local storage. 11248 </description> 11249 </param> 11250 </parameters> 11251 <errors> 11252 </errors> 11253 </function> 11254 11255 <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147"> 11256 <synopsis>Get Environment Local Storage</synopsis> 11257 <description> 11258 Called by the agent to get the value of the <jvmti/> environment-local 11259 storage. 11260 </description> 11261 <origin>new</origin> 11262 <capabilities> 11263 </capabilities> 11264 <parameters> 11265 <param id="data_ptr"> 11266 <agentbuf><void/></agentbuf> 11267 <description> 11268 Pointer through which the value of the environment local 11269 storage is returned. 11270 If environment-local storage has not been set with 11271 <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned 11272 pointer is <code>NULL</code>. 11273 </description> 11274 </param> 11275 </parameters> 11276 <errors> 11277 </errors> 11278 </function> 11279 11280 <function id="GetVersionNumber" jkernel="yes" phase="any" num="88"> 11281 <synopsis>Get Version Number</synopsis> 11282 <description> 11283 Return the <jvmti/> version via <code>version_ptr</code>. 11284 The return value is the version identifier. 11285 The version identifier includes major, minor and micro 11286 version as well as the interface type. 11287 <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits"> 11288 <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000"> 11289 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI. 11290 </constant> 11291 <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000"> 11292 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>. 11293 </constant> 11294 </constants> 11295 <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits"> 11296 <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000"> 11297 Mask to extract interface type. 11298 The value of the version returned by this function masked with 11299 <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always 11300 <code>JVMTI_VERSION_INTERFACE_JVMTI</code> 11301 since this is a <jvmti/> function. 11302 </constant> 11303 <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000"> 11304 Mask to extract major version number. 11305 </constant> 11306 <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00"> 11307 Mask to extract minor version number. 11308 </constant> 11309 <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF"> 11310 Mask to extract micro version number. 11311 </constant> 11312 </constants> 11313 <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits"> 11314 <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16"> 11315 Shift to extract major version number. 11316 </constant> 11317 <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8"> 11318 Shift to extract minor version number. 11319 </constant> 11320 <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0"> 11321 Shift to extract micro version number. 11322 </constant> 11323 </constants> 11324 </description> 11325 <origin>jvmdi</origin> 11326 <capabilities> 11327 </capabilities> 11328 <parameters> 11329 <param id="version_ptr"> 11330 <outptr><jint/></outptr> 11331 <description> 11332 On return, points to the <jvmti/> version. 11333 </description> 11334 </param> 11335 </parameters> 11336 <errors> 11337 </errors> 11338 </function> 11339 11340 11341 <function id="GetErrorName" phase="any" num="128"> 11342 <synopsis>Get Error Name</synopsis> 11343 <description> 11344 Return the symbolic name for an 11345 <internallink id="ErrorSection">error code</internallink>. 11346 <p/> 11347 For example 11348 <code>GetErrorName(env, JVMTI_ERROR_NONE, &err_name)</code> 11349 would return in <code>err_name</code> the string 11350 <code>"JVMTI_ERROR_NONE"</code>. 11351 </description> 11352 <origin>new</origin> 11353 <capabilities> 11354 </capabilities> 11355 <parameters> 11356 <param id="error"> 11357 <enum>jvmtiError</enum> 11358 <description> 11359 The error code. 11360 </description> 11361 </param> 11362 <param id="name_ptr"> 11363 <allocbuf><char/></allocbuf> 11364 <description> 11365 On return, points to the error name. 11366 The name is encoded as a 11367 <internallink id="mUTF">modified UTF-8</internallink> string, 11368 but is restricted to the ASCII subset. 11369 </description> 11370 </param> 11371 </parameters> 11372 <errors> 11373 </errors> 11374 </function> 11375 11376 <function id="SetVerboseFlag" phase="any" num="150"> 11377 <synopsis>Set Verbose Flag</synopsis> 11378 <description> 11379 <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum"> 11380 <constant id="JVMTI_VERBOSE_OTHER" num="0"> 11381 Verbose output other than the below. 11382 </constant> 11383 <constant id="JVMTI_VERBOSE_GC" num="1"> 11384 Verbose garbage collector output, like that specified with <code>-verbose:gc</code>. 11385 </constant> 11386 <constant id="JVMTI_VERBOSE_CLASS" num="2"> 11387 Verbose class loading output, like that specified with <code>-verbose:class</code>. 11388 </constant> 11389 <constant id="JVMTI_VERBOSE_JNI" num="4"> 11390 Verbose JNI output, like that specified with <code>-verbose:jni</code>. 11391 </constant> 11392 </constants> 11393 Control verbose output. 11394 This is the output which typically is sent to <code>stderr</code>. 11395 </description> 11396 <origin>new</origin> 11397 <capabilities> 11398 </capabilities> 11399 <parameters> 11400 <param id="flag"> 11401 <enum>jvmtiVerboseFlag</enum> 11402 <description> 11403 Which verbose flag to set. 11404 </description> 11405 </param> 11406 <param id="value"> 11407 <jboolean/> 11408 <description> 11409 New value of the flag. 11410 </description> 11411 </param> 11412 </parameters> 11413 <errors> 11414 </errors> 11415 </function> 11416 11417 11418 <function id="GetJLocationFormat" phase="any" num="129"> 11419 <synopsis>Get JLocation Format</synopsis> 11420 <description> 11421 Although the greatest functionality is achieved with location information 11422 referencing the virtual machine bytecode index, the definition of 11423 <code>jlocation</code> has intentionally been left unconstrained to allow VM 11424 implementations that do not have this information. 11425 <p/> 11426 This function describes the representation of <code>jlocation</code> used in this VM. 11427 If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>, 11428 <code>jlocation</code>s can 11429 be used as in indices into the array returned by 11430 <functionlink id="GetBytecodes"></functionlink>. 11431 <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum"> 11432 <constant id="JVMTI_JLOCATION_JVMBCI" num="1"> 11433 <code>jlocation</code> values represent virtual machine 11434 bytecode indices--that is, offsets into the 11435 virtual machine code for a method. 11436 </constant> 11437 <constant id="JVMTI_JLOCATION_MACHINEPC" num="2"> 11438 <code>jlocation</code> values represent native machine 11439 program counter values. 11440 </constant> 11441 <constant id="JVMTI_JLOCATION_OTHER" num="0"> 11442 <code>jlocation</code> values have some other representation. 11443 </constant> 11444 </constants> 11445 </description> 11446 <origin>new</origin> 11447 <capabilities> 11448 </capabilities> 11449 <parameters> 11450 <param id="format_ptr"> 11451 <outptr><enum>jvmtiJlocationFormat</enum></outptr> 11452 <description> 11453 On return, points to the format identifier for <code>jlocation</code> values. 11454 </description> 11455 </param> 11456 </parameters> 11457 <errors> 11458 </errors> 11459 </function> 11460 11461 </category> 11462 11463</functionsection> 11464 11465<errorsection label="Error Reference"> 11466 <intro> 11467 Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code. 11468 <p/> 11469 It is the responsibility of the agent to call <jvmti/> functions with 11470 valid parameters and in the proper context (calling thread is attached, 11471 phase is correct, etc.). 11472 Detecting some error conditions may be difficult, inefficient, or 11473 impossible for an implementation. 11474 The errors listed in 11475 <internallink id="reqerrors">Function Specific Required Errors</internallink> 11476 must be detected by the implementation. 11477 All other errors represent the recommended response to the error 11478 condition. 11479 </intro> 11480 11481 <errorcategory id="universal-error" label="Universal Errors"> 11482 <intro> 11483 The following errors may be returned by any function 11484 </intro> 11485 11486 <errorid id="JVMTI_ERROR_NONE" num="0"> 11487 No error has occurred. This is the error code that is returned 11488 on successful completion of the function. 11489 </errorid> 11490 <errorid id="JVMTI_ERROR_NULL_POINTER" num="100"> 11491 Pointer is unexpectedly <code>NULL</code>. 11492 </errorid> 11493 <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110"> 11494 The function attempted to allocate memory and no more memory was 11495 available for allocation. 11496 </errorid> 11497 <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111"> 11498 The desired functionality has not been enabled in this virtual machine. 11499 </errorid> 11500 <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115"> 11501 The thread being used to call this function is not attached 11502 to the virtual machine. Calls must be made from attached threads. 11503 See <code>AttachCurrentThread</code> in the JNI invocation API. 11504 </errorid> 11505 <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116"> 11506 The <jvmti/> environment provided is no longer connected or is 11507 not an environment. 11508 </errorid> 11509 <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112"> 11510 The desired functionality is not available in the current 11511 <functionlink id="GetPhase">phase</functionlink>. 11512 Always returned if the virtual machine has completed running. 11513 </errorid> 11514 <errorid id="JVMTI_ERROR_INTERNAL" num="113"> 11515 An unexpected internal error has occurred. 11516 </errorid> 11517 </errorcategory> 11518 11519 <errorcategory id="reqerrors" label="Function Specific Required Errors"> 11520 <intro> 11521 The following errors are returned by some <jvmti/> functions and must 11522 be returned by the implementation when the condition occurs. 11523 </intro> 11524 11525 <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12"> 11526 Invalid priority. 11527 </errorid> 11528 <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13"> 11529 Thread was not suspended. 11530 </errorid> 11531 <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14"> 11532 Thread already suspended. 11533 </errorid> 11534 <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15"> 11535 This operation requires the thread to be alive--that is, 11536 it must be started and not yet have died. 11537 </errorid> 11538 <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22"> 11539 The class has been loaded but not yet prepared. 11540 </errorid> 11541 <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31"> 11542 There are no Java programming language or JNI stack frames at the specified depth. 11543 </errorid> 11544 <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32"> 11545 Information about the frame is not available (e.g. for native frames). 11546 </errorid> 11547 <errorid id="JVMTI_ERROR_DUPLICATE" num="40"> 11548 Item already set. 11549 </errorid> 11550 <errorid id="JVMTI_ERROR_NOT_FOUND" num="41"> 11551 Desired element (e.g. field or breakpoint) not found 11552 </errorid> 11553 <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51"> 11554 This thread doesn't own the raw monitor. 11555 </errorid> 11556 <errorid id="JVMTI_ERROR_INTERRUPT" num="52"> 11557 The call has been interrupted before completion. 11558 </errorid> 11559 <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79"> 11560 The class cannot be modified. 11561 </errorid> 11562 <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98"> 11563 The functionality is not available in this virtual machine. 11564 </errorid> 11565 <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101"> 11566 The requested information is not available. 11567 </errorid> 11568 <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102"> 11569 The specified event type ID is not recognized. 11570 </errorid> 11571 <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104"> 11572 The requested information is not available for native method. 11573 </errorid> 11574 <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106"> 11575 The class loader does not support this operation. 11576 </errorid> 11577 </errorcategory> 11578 11579 <errorcategory id="function-specific-errors" label="Function Specific Agent Errors"> 11580 <intro> 11581 The following errors are returned by some <jvmti/> functions. 11582 They are returned in the event of invalid parameters passed by the 11583 agent or usage in an invalid context. 11584 An implementation is not required to detect these errors. 11585 </intro> 11586 11587 <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10"> 11588 The passed thread is not a valid thread. 11589 </errorid> 11590 <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25"> 11591 Invalid field. 11592 </errorid> 11593 <errorid id="JVMTI_ERROR_INVALID_MODULE" num="26"> 11594 Invalid module. 11595 </errorid> 11596 <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23"> 11597 Invalid method. 11598 </errorid> 11599 <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24"> 11600 Invalid location. 11601 </errorid> 11602 <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20"> 11603 Invalid object. 11604 </errorid> 11605 <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21"> 11606 Invalid class. 11607 </errorid> 11608 <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34"> 11609 The variable is not an appropriate type for the function used. 11610 </errorid> 11611 <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35"> 11612 Invalid slot. 11613 </errorid> 11614 <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99"> 11615 The capability being used is false in this environment. 11616 </errorid> 11617 <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11"> 11618 Thread group invalid. 11619 </errorid> 11620 <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50"> 11621 Invalid raw monitor. 11622 </errorid> 11623 <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103"> 11624 Illegal argument. 11625 </errorid> 11626 <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65"> 11627 The state of the thread has been modified, and is now inconsistent. 11628 </errorid> 11629 <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68"> 11630 A new class file has a version number not supported by this VM. 11631 </errorid> 11632 <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60"> 11633 A new class file is malformed (the VM would return a <code>ClassFormatError</code>). 11634 </errorid> 11635 <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61"> 11636 The new class file definitions would lead to a circular 11637 definition (the VM would return a <code>ClassCircularityError</code>). 11638 </errorid> 11639 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63"> 11640 A new class file would require adding a method. 11641 </errorid> 11642 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64"> 11643 A new class version changes a field. 11644 </errorid> 11645 <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62"> 11646 The class bytes fail verification. 11647 </errorid> 11648 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66"> 11649 A direct superclass is different for the new class 11650 version, or the set of directly implemented 11651 interfaces is different. 11652 </errorid> 11653 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67"> 11654 A new class version does not declare a method 11655 declared in the old class version. 11656 </errorid> 11657 <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69"> 11658 The class name defined in the new class file is 11659 different from the name in the old class object. 11660 </errorid> 11661 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70"> 11662 A new class version has different modifiers. 11663 </errorid> 11664 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71"> 11665 A method in the new class version has different modifiers 11666 than its counterpart in the old class version. 11667 </errorid> 11668 </errorcategory> 11669</errorsection> 11670 11671<eventsection label="Events"> 11672 <intro label="Handling Events" id="eventIntro"> 11673 Agents can be informed of many events that occur in application 11674 programs. 11675 <p/> 11676 To handle events, designate a set of callback functions with 11677 <functionlink id="SetEventCallbacks"></functionlink>. 11678 For each event the corresponding callback function will be 11679 called. 11680 Arguments to the callback function provide additional 11681 information about the event. 11682 <p/> 11683 The callback function is usually called from within an application 11684 thread. The <jvmti/> implementation does not 11685 queue events in any way. This means 11686 that event callback functions must be written 11687 carefully. Here are some general guidelines. See 11688 the individual event descriptions for further 11689 suggestions. 11690 <p/> 11691 <ul> 11692 <li>Any exception thrown during the execution of an event callback can 11693 overwrite any current pending exception in the current application thread. 11694 Care must be taken to preserve a pending exception 11695 when an event callback makes a JNI call that might generate an exception. 11696 </li> 11697 <li>Event callback functions must be re-entrant. The <jvmti/> implementation does 11698 not queue events. If an agent needs to process events one at a time, it 11699 can use a raw monitor inside the 11700 event callback functions to serialize event processing. 11701 </li> 11702 <li>Event callback functions that execute JNI's FindClass function to load 11703 classes need to note that FindClass locates the class loader associated 11704 with the current native method. For the purposes of class loading, an 11705 event callback that includes a JNI environment as a parameter to the 11706 callback will treated as if it is a native call, where the native method 11707 is in the class of the event thread's current frame. 11708 </li> 11709 </ul> 11710 <p/> 11711 Some <jvmti/> events identify objects with JNI references. 11712 All references 11713 in <jvmti/> events are JNI local references and will become invalid 11714 after the event callback returns. 11715 Unless stated otherwise, memory referenced by pointers sent in event 11716 callbacks may not be referenced after the event callback returns. 11717 <p/> 11718 Except where stated otherwise, events are delivered on the thread 11719 that caused the event. 11720 Events are sent at the time they occur. 11721 The specification for each event includes the set of 11722 <functionlink id="GetPhase">phases</functionlink> in which it can be sent; 11723 if an event triggering activity occurs during another phase, no event 11724 is sent. 11725 <p/> 11726 A thread that generates an event does not change its execution status 11727 (for example, the event does not cause the thread to be suspended). 11728 If an agent wishes the event to result in suspension, then the agent 11729 is responsible for explicitly suspending the thread with 11730 <functionlink id="SuspendThread"></functionlink>. 11731 <p/> 11732 If an event is enabled in multiple environments, the event will be sent 11733 to each agent in the order that the environments were created. 11734 </intro> 11735 11736 <intro label="Enabling Events" id="enablingevents"> 11737 All events are initially disabled. In order to receive any 11738 event: 11739 <ul> 11740 <li> 11741 If the event requires a capability, that capability must 11742 be added with 11743 <functionlink id="AddCapabilities"></functionlink>. 11744 </li> 11745 <li> 11746 A callback for the event must be set with 11747 <functionlink id="SetEventCallbacks"></functionlink>. 11748 </li> 11749 <li> 11750 The event must be enabled with 11751 <functionlink id="SetEventNotificationMode"></functionlink>. 11752 </li> 11753 </ul> 11754 </intro> 11755 11756 <intro label="Multiple Co-located Events" id="eventorder"> 11757 In many situations it is possible for multiple events to occur 11758 at the same location in one thread. When this happens, all the events 11759 are reported through the event callbacks in the order specified in this section. 11760 <p/> 11761 If the current location is at the entry point of a method, the 11762 <eventlink id="MethodEntry"></eventlink> event is reported before 11763 any other event at the current location in the same thread. 11764 <p/> 11765 If an exception catch has been detected at the current location, 11766 either because it is the beginning of a catch clause or a native method 11767 that cleared a pending exception has returned, the 11768 <code>exceptionCatch</code> event is reported before 11769 any other event at the current location in the same thread. 11770 <p/> 11771 If a <code>singleStep</code> event or 11772 <code>breakpoint</code> event is triggered at the 11773 current location, the event is defined to occur 11774 immediately before the code at the current location is executed. 11775 These events are reported before any events which are triggered 11776 by the execution of code at the current location in the same 11777 thread (specifically: 11778 <code>exception</code>, 11779 <code>fieldAccess</code>, and 11780 <code>fieldModification</code>). 11781 If both a step and breakpoint event are triggered for the same thread and 11782 location, the step event is reported before the breakpoint event. 11783 <p/> 11784 If the current location is the exit point of a method (that is, the last 11785 location before returning to the caller), the 11786 <eventlink id="MethodExit"></eventlink> event and 11787 the <eventlink id="FramePop"></eventlink> event (if requested) 11788 are reported after all other events at the current location in the same 11789 thread. There is no specified ordering of these two events 11790 with respect to each other. 11791 <p/> 11792 Co-located events can be triggered during the processing of some other 11793 event by the agent at the same location in the same thread. 11794 If such an event, of type <i>y</i>, is triggered during the processing of 11795 an event of type <i>x</i>, and if <i>x</i> 11796 precedes <i>y</i> in the ordering specified above, the co-located event 11797 <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede 11798 <i>y</i>, <i>y</i> is not reported for the current thread and location. 11799 For example, if a breakpoint is set at the current location 11800 during the processing of <eventlink id="SingleStep"></eventlink>, 11801 that breakpoint will be reported before the thread moves off the current 11802 location. 11803 <p/>The following events are never considered to be co-located with 11804 other events. 11805 <ul> 11806 <li><eventlink id="VMStart"></eventlink></li> 11807 <li><eventlink id="VMInit"></eventlink></li> 11808 <li><eventlink id="VMDeath"></eventlink></li> 11809 <li><eventlink id="ThreadStart"></eventlink></li> 11810 <li><eventlink id="ThreadEnd"></eventlink></li> 11811 <li><eventlink id="ClassLoad"></eventlink></li> 11812 <li><eventlink id="ClassPrepare"></eventlink></li> 11813 </ul> 11814 </intro> 11815 11816 <intro label="Event Callbacks" id="jvmtiEventCallbacks"> 11817 The event callback structure below is used to specify the handler function 11818 for events. It is set with the 11819 <functionlink id="SetEventCallbacks"></functionlink> function. 11820 </intro> 11821 11822 <event label="Single Step" 11823 id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60"> 11824 <description> 11825 Single step events allow the agent to trace thread execution 11826 at the finest granularity allowed by the VM. A single step event is 11827 generated whenever a thread reaches a new location. 11828 Typically, single step events represent the completion of one VM 11829 instruction as defined in <vmspec/>. However, some implementations 11830 may define locations differently. In any case the 11831 <code>method</code> and <code>location</code> 11832 parameters uniquely identify the current location and allow 11833 the mapping to source file and line number when that information is 11834 available. 11835 <p/> 11836 No single step events are generated from within native methods. 11837 </description> 11838 <origin>jvmdi</origin> 11839 <capabilities> 11840 <required id="can_generate_single_step_events"></required> 11841 </capabilities> 11842 <parameters> 11843 <param id="jni_env"> 11844 <outptr> 11845 <struct>JNIEnv</struct> 11846 </outptr> 11847 <description> 11848 The JNI environment of the event (current) thread 11849 </description> 11850 </param> 11851 <param id="thread"> 11852 <jthread/> 11853 <description> 11854 Thread about to execution a new instruction 11855 </description> 11856 </param> 11857 <param id="klass"> 11858 <jclass method="method"/> 11859 <description> 11860 Class of the method about to execute a new instruction 11861 </description> 11862 </param> 11863 <param id="method"> 11864 <jmethodID class="klass"/> 11865 <description> 11866 Method about to execute a new instruction 11867 </description> 11868 </param> 11869 <param id="location"> 11870 <jlocation/> 11871 <description> 11872 Location of the new instruction 11873 </description> 11874 </param> 11875 </parameters> 11876 </event> 11877 11878 <event label="Breakpoint" 11879 id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62"> 11880 <description> 11881 Breakpoint events are generated whenever a thread reaches a location 11882 designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>. 11883 The <code>method</code> and <code>location</code> 11884 parameters uniquely identify the current location and allow 11885 the mapping to source file and line number when that information is 11886 available. 11887 </description> 11888 <origin>jvmdi</origin> 11889 <capabilities> 11890 <required id="can_generate_breakpoint_events"></required> 11891 </capabilities> 11892 <parameters> 11893 <param id="jni_env"> 11894 <outptr> 11895 <struct>JNIEnv</struct> 11896 </outptr> 11897 <description> 11898 The JNI environment of the event (current) thread. 11899 </description> 11900 </param> 11901 <param id="thread"> 11902 <jthread/> 11903 <description> 11904 Thread that hit the breakpoint 11905 </description> 11906 </param> 11907 <param id="klass"> 11908 <jclass method="method"/> 11909 <description> 11910 Class of the method that hit the breakpoint 11911 </description> 11912 </param> 11913 <param id="method"> 11914 <jmethodID class="klass"/> 11915 <description> 11916 Method that hit the breakpoint 11917 </description> 11918 </param> 11919 <param id="location"> 11920 <jlocation/> 11921 <description> 11922 location of the breakpoint 11923 </description> 11924 </param> 11925 </parameters> 11926 </event> 11927 11928 <event label="Field Access" 11929 id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63"> 11930 <description> 11931 Field access events are generated whenever a thread accesses 11932 a field that was designated as a watchpoint 11933 with <functionlink id="SetFieldAccessWatch"></functionlink>. 11934 The <code>method</code> and <code>location</code> 11935 parameters uniquely identify the current location and allow 11936 the mapping to source file and line number when that information is 11937 available. 11938 </description> 11939 <origin>jvmdi</origin> 11940 <capabilities> 11941 <required id="can_generate_field_access_events"></required> 11942 </capabilities> 11943 <parameters> 11944 <param id="jni_env"> 11945 <outptr> 11946 <struct>JNIEnv</struct> 11947 </outptr> 11948 <description> 11949 The JNI environment of the event (current) thread 11950 </description> 11951 </param> 11952 <param id="thread"> 11953 <jthread/> 11954 <description> 11955 Thread accessing the field 11956 </description> 11957 </param> 11958 <param id="klass"> 11959 <jclass method="method"/> 11960 <description> 11961 Class of the method where the access is occurring 11962 </description> 11963 </param> 11964 <param id="method"> 11965 <jmethodID class="klass"/> 11966 <description> 11967 Method where the access is occurring 11968 </description> 11969 </param> 11970 <param id="location"> 11971 <jlocation/> 11972 <description> 11973 Location where the access is occurring 11974 </description> 11975 </param> 11976 <param id="field_klass"> 11977 <jclass field="field"/> 11978 <description> 11979 Class of the field being accessed 11980 </description> 11981 </param> 11982 <param id="object"> 11983 <jobject/> 11984 <description> 11985 Object with the field being accessed if the field is an 11986 instance field; <code>NULL</code> otherwise 11987 </description> 11988 </param> 11989 <param id="field"> 11990 <jfieldID class="field_klass"/> 11991 <description> 11992 Field being accessed 11993 </description> 11994 </param> 11995 </parameters> 11996 </event> 11997 11998 <event label="Field Modification" 11999 id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64"> 12000 <description> 12001 Field modification events are generated whenever a thread modifies 12002 a field that was designated as a watchpoint 12003 with <functionlink id="SetFieldModificationWatch"></functionlink>. 12004 The <code>method</code> and <code>location</code> 12005 parameters uniquely identify the current location and allow 12006 the mapping to source file and line number when that information is 12007 available. 12008 </description> 12009 <origin>jvmdi</origin> 12010 <capabilities> 12011 <required id="can_generate_field_modification_events"></required> 12012 </capabilities> 12013 <parameters> 12014 <param id="jni_env"> 12015 <outptr> 12016 <struct>JNIEnv</struct> 12017 </outptr> 12018 <description> 12019 The JNI environment of the event (current) thread 12020 </description> 12021 </param> 12022 <param id="thread"> 12023 <jthread/> 12024 <description> 12025 Thread modifying the field 12026 </description> 12027 </param> 12028 <param id="klass"> 12029 <jclass method="method"/> 12030 <description> 12031 Class of the method where the modification is occurring 12032 </description> 12033 </param> 12034 <param id="method"> 12035 <jmethodID class="klass"/> 12036 <description> 12037 Method where the modification is occurring 12038 </description> 12039 </param> 12040 <param id="location"> 12041 <jlocation/> 12042 <description> 12043 Location where the modification is occurring 12044 </description> 12045 </param> 12046 <param id="field_klass"> 12047 <jclass field="field"/> 12048 <description> 12049 Class of the field being modified 12050 </description> 12051 </param> 12052 <param id="object"> 12053 <jobject/> 12054 <description> 12055 Object with the field being modified if the field is an 12056 instance field; <code>NULL</code> otherwise 12057 </description> 12058 </param> 12059 <param id="field"> 12060 <jfieldID class="field_klass"/> 12061 <description> 12062 Field being modified 12063 </description> 12064 </param> 12065 <param id="signature_type"> 12066 <char/> 12067 <description> 12068 Signature type of the new value 12069 </description> 12070 </param> 12071 <param id="new_value"> 12072 <jvalue/> 12073 <description> 12074 The new value 12075 </description> 12076 </param> 12077 </parameters> 12078 </event> 12079 12080 <event label="Frame Pop" 12081 id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61"> 12082 <description> 12083 Frame pop events are generated upon exit from a single method 12084 in a single frame as specified 12085 in a call to <functionlink id="NotifyFramePop"></functionlink>. 12086 This is true whether termination is caused by 12087 executing its return instruction 12088 or by throwing an exception to its caller 12089 (see <paramlink id="was_popped_by_exception"></paramlink>). 12090 However, frame pops caused by the <functionlink id="PopFrame"/> 12091 function are not reported. 12092 <p/> 12093 The location reported by <functionlink id="GetFrameLocation"></functionlink> 12094 identifies the executable location in the returning method, 12095 immediately prior to the return. 12096 </description> 12097 <origin>jvmdi</origin> 12098 <capabilities> 12099 <required id="can_generate_frame_pop_events"></required> 12100 </capabilities> 12101 <parameters> 12102 <param id="jni_env"> 12103 <outptr> 12104 <struct>JNIEnv</struct> 12105 </outptr> 12106 <description> 12107 The JNI environment of the event (current) thread 12108 </description> 12109 </param> 12110 <param id="thread"> 12111 <jthread/> 12112 <description> 12113 Thread that is popping the frame 12114 </description> 12115 </param> 12116 <param id="klass"> 12117 <jclass method="method"/> 12118 <description> 12119 Class of the method being popped 12120 </description> 12121 </param> 12122 <param id="method"> 12123 <jmethodID class="klass"/> 12124 <description> 12125 Method being popped 12126 </description> 12127 </param> 12128 <param id="was_popped_by_exception"> 12129 <jboolean/> 12130 <description> 12131 True if frame was popped by a thrown exception. 12132 False if method exited through its return instruction. 12133 </description> 12134 </param> 12135 </parameters> 12136 </event> 12137 12138 <event label="Method Entry" 12139 id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65"> 12140 <description> 12141 Method entry events are generated upon entry of Java 12142 programming language methods (including native methods). 12143 <p/> 12144 The location reported by <functionlink id="GetFrameLocation"></functionlink> 12145 identifies the initial executable location in 12146 the method. 12147 <p/> 12148 Enabling method 12149 entry or exit events will significantly degrade performance on many platforms and is thus 12150 not advised for performance critical usage (such as profiling). 12151 <internallink id="bci">Bytecode instrumentation</internallink> should be 12152 used in these cases. 12153 </description> 12154 <origin>jvmdi</origin> 12155 <capabilities> 12156 <required id="can_generate_method_entry_events"></required> 12157 </capabilities> 12158 <parameters> 12159 <param id="jni_env"> 12160 <outptr> 12161 <struct>JNIEnv</struct> 12162 </outptr> 12163 <description> 12164 The JNI environment of the event (current) thread 12165 </description> 12166 </param> 12167 <param id="thread"> 12168 <jthread/> 12169 <description> 12170 Thread entering the method 12171 </description> 12172 </param> 12173 <param id="klass"> 12174 <jclass method="method"/> 12175 <description> 12176 Class of the method being entered 12177 </description> 12178 </param> 12179 <param id="method"> 12180 <jmethodID class="klass"/> 12181 <description> 12182 Method being entered 12183 </description> 12184 </param> 12185 </parameters> 12186 </event> 12187 12188 <event label="Method Exit" 12189 id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66"> 12190 <description> 12191 Method exit events are generated upon exit from Java 12192 programming language methods (including native methods). 12193 This is true whether termination is caused by 12194 executing its return instruction 12195 or by throwing an exception to its caller 12196 (see <paramlink id="was_popped_by_exception"></paramlink>). 12197 <p/> 12198 The <code>method</code> field uniquely identifies the 12199 method being entered or exited. The <code>frame</code> field provides 12200 access to the stack frame for the method. 12201 <p/> 12202 The location reported by <functionlink id="GetFrameLocation"></functionlink> 12203 identifies the executable location in the returning method 12204 immediately prior to the return. 12205 <p/> 12206 Enabling method 12207 entry or exit events will significantly degrade performance on many platforms and is thus 12208 not advised for performance critical usage (such as profiling). 12209 <internallink id="bci">Bytecode instrumentation</internallink> should be 12210 used in these cases. 12211 </description> 12212 <origin>jvmdi</origin> 12213 <capabilities> 12214 <required id="can_generate_method_exit_events"></required> 12215 </capabilities> 12216 <parameters> 12217 <param id="jni_env"> 12218 <outptr> 12219 <struct>JNIEnv</struct> 12220 </outptr> 12221 <description> 12222 The JNI environment of the event (current) thread 12223 </description> 12224 </param> 12225 <param id="thread"> 12226 <jthread/> 12227 <description> 12228 Thread exiting the method 12229 </description> 12230 </param> 12231 <param id="klass"> 12232 <jclass method="method"/> 12233 <description> 12234 Class of the method being exited 12235 </description> 12236 </param> 12237 <param id="method"> 12238 <jmethodID class="klass"/> 12239 <description> 12240 Method being exited 12241 </description> 12242 </param> 12243 <param id="was_popped_by_exception"> 12244 <jboolean/> 12245 <description> 12246 True if frame was popped by a thrown exception. 12247 False if method exited through its return instruction. 12248 </description> 12249 </param> 12250 <param id="return_value"> 12251 <jvalue/> 12252 <description> 12253 The return value of the method being exited. 12254 Undefined and should not be used if 12255 <paramlink id="was_popped_by_exception"></paramlink> 12256 is true. 12257 </description> 12258 </param> 12259 </parameters> 12260 </event> 12261 12262 <event label="Native Method Bind" phase="any" 12263 id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67"> 12264 <description> 12265 A Native Method Bind event is sent when a VM binds a 12266 Java programming language native method 12267 to the address of a function that implements the native method. 12268 This will occur when the native method is called for the first time 12269 and also occurs when the JNI function <code>RegisterNatives</code> is called. 12270 This event allows the bind to be redirected to an agent-specified 12271 proxy function. 12272 This event is not sent when the native method is unbound. 12273 Typically, this proxy function will need to be specific to a 12274 particular method or, to handle the general case, automatically 12275 generated assembly code, since after instrumentation code is 12276 executed the function at the original binding 12277 address will usually be invoked. 12278 The original binding can be restored or the redirection changed 12279 by use of the JNI function <code>RegisterNatives</code>. 12280 Some events may be sent during the primordial phase, JNI and 12281 most of <jvmti/> cannot be used at this time but the method and 12282 address can be saved for use later. 12283 </description> 12284 <origin>new</origin> 12285 <capabilities> 12286 <required id="can_generate_native_method_bind_events"></required> 12287 </capabilities> 12288 <parameters> 12289 <param id="jni_env"> 12290 <outptr> 12291 <struct>JNIEnv</struct> 12292 </outptr> 12293 <description> 12294 The JNI environment of the event (current) thread 12295 Will be <code>NULL</code> if sent during the primordial 12296 <functionlink id="GetPhase">phase</functionlink>. 12297 </description> 12298 </param> 12299 <param id="thread"> 12300 <jthread/> 12301 <description> 12302 Thread requesting the bind 12303 </description> 12304 </param> 12305 <param id="klass"> 12306 <jclass method="method"/> 12307 <description> 12308 Class of the method being bound 12309 </description> 12310 </param> 12311 <param id="method"> 12312 <jmethodID class="klass"/> 12313 <description> 12314 Native method being bound 12315 </description> 12316 </param> 12317 <param id="address"> 12318 <outptr><void/></outptr> 12319 <description> 12320 The address the VM is about to bind to--that is, the 12321 address of the implementation of the native method 12322 </description> 12323 </param> 12324 <param id="new_address_ptr"> 12325 <agentbuf><void/></agentbuf> 12326 <description> 12327 if the referenced address is changed (that is, if 12328 <code>*new_address_ptr</code> is set), the binding 12329 will instead be made to the supplied address. 12330 </description> 12331 </param> 12332 </parameters> 12333 </event> 12334 12335 <event label="Exception" 12336 id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58"> 12337 <description> 12338 Exception events are generated whenever an exception is first detected 12339 in a Java programming language method. 12340 Where "exception" means any <code>java.lang.Throwable</code>. 12341 The exception may have been thrown by a Java programming language or native 12342 method, but in the case of native methods, the event is not generated 12343 until the exception is first seen by a Java programming language method. If an exception is 12344 set and cleared in a native method (and thus is never visible to Java programming language code), 12345 no exception event is generated. 12346 <p/> 12347 The <code>method</code> and <code>location</code> 12348 parameters uniquely identify the current location 12349 (where the exception was detected) and allow 12350 the mapping to source file and line number when that information is 12351 available. The <code>exception</code> field identifies the thrown 12352 exception object. The <code>catch_method</code> 12353 and <code>catch_location</code> identify the location of the catch clause, 12354 if any, that handles the thrown exception. If there is no such catch clause, 12355 each field is set to 0. There is no guarantee that the thread will ever 12356 reach this catch clause. If there are native methods on the call stack 12357 between the throw location and the catch clause, the exception may 12358 be reset by one of those native methods. 12359 Similarly, exceptions that are reported as uncaught (<code>catch_klass</code> 12360 et al. set to 0) may in fact be caught by native code. 12361 Agents can check for these occurrences by monitoring 12362 <eventlink id="ExceptionCatch"></eventlink> events. 12363 Note that finally clauses are implemented as catch and re-throw. Therefore they 12364 will be reported in the catch location. 12365 </description> 12366 <origin>jvmdi</origin> 12367 <capabilities> 12368 <required id="can_generate_exception_events"></required> 12369 </capabilities> 12370 <parameters> 12371 <param id="jni_env"> 12372 <outptr> 12373 <struct>JNIEnv</struct> 12374 </outptr> 12375 <description> 12376 The JNI environment of the event (current) thread 12377 </description> 12378 </param> 12379 <param id="thread"> 12380 <jthread/> 12381 <description> 12382 Thread generating the exception 12383 </description> 12384 </param> 12385 <param id="klass"> 12386 <jclass method="method"/> 12387 <description> 12388 Class generating the exception 12389 </description> 12390 </param> 12391 <param id="method"> 12392 <jmethodID class="klass"/> 12393 <description> 12394 Method generating the exception 12395 </description> 12396 </param> 12397 <param id="location"> 12398 <jlocation/> 12399 <description> 12400 Location where exception occurred 12401 </description> 12402 </param> 12403 <param id="exception"> 12404 <jobject/> 12405 <description> 12406 The exception being thrown 12407 </description> 12408 </param> 12409 <param id="catch_klass"> 12410 <jclass method="catch_method"/> 12411 <description> 12412 Class that will catch the exception, or <code>NULL</code> if no known catch 12413 </description> 12414 </param> 12415 <param id="catch_method"> 12416 <jmethodID class="catch_klass"/> 12417 <description> 12418 Method that will catch the exception, or <code>NULL</code> if no known catch 12419 </description> 12420 </param> 12421 <param id="catch_location"> 12422 <jlocation/> 12423 <description> 12424 location which will catch the exception or zero if no known catch 12425 </description> 12426 </param> 12427 </parameters> 12428 </event> 12429 12430 <event label="Exception Catch" 12431 id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59"> 12432 <description> 12433 Exception catch events are generated whenever a thrown exception is caught. 12434 Where "exception" means any <code>java.lang.Throwable</code>. 12435 If the exception is caught in a Java programming language method, the event is generated 12436 when the catch clause is reached. If the exception is caught in a native 12437 method, the event is generated as soon as control is returned to a Java programming language 12438 method. Exception catch events are generated for any exception for which 12439 a throw was detected in a Java programming language method. 12440 Note that finally clauses are implemented as catch and re-throw. Therefore they 12441 will generate exception catch events. 12442 <p/> 12443 The <code>method</code> and <code>location</code> 12444 parameters uniquely identify the current location 12445 and allow the mapping to source file and line number when that information is 12446 available. For exceptions caught in a Java programming language method, the 12447 <code>exception</code> object identifies the exception object. Exceptions 12448 caught in native methods are not necessarily available by the time the 12449 exception catch is reported, so the <code>exception</code> field is set 12450 to <code>NULL</code>. 12451 </description> 12452 <origin>jvmdi</origin> 12453 <capabilities> 12454 <required id="can_generate_exception_events"></required> 12455 </capabilities> 12456 <parameters> 12457 <param id="jni_env"> 12458 <outptr> 12459 <struct>JNIEnv</struct> 12460 </outptr> 12461 <description> 12462 The JNI environment of the event (current) thread 12463 </description> 12464 </param> 12465 <param id="thread"> 12466 <jthread/> 12467 <description> 12468 Thread catching the exception 12469 </description> 12470 </param> 12471 <param id="klass"> 12472 <jclass method="method"/> 12473 <description> 12474 Class catching the exception 12475 </description> 12476 </param> 12477 <param id="method"> 12478 <jmethodID class="klass"/> 12479 <description> 12480 Method catching the exception 12481 </description> 12482 </param> 12483 <param id="location"> 12484 <jlocation/> 12485 <description> 12486 Location where exception is being caught 12487 </description> 12488 </param> 12489 <param id="exception"> 12490 <jobject/> 12491 <description> 12492 Exception being caught 12493 </description> 12494 </param> 12495 </parameters> 12496 </event> 12497 12498 <event label="Thread Start" 12499 id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start"> 12500 <description> 12501 Thread start events are generated by a new thread before its initial 12502 method executes. 12503 <p/> 12504 A thread may be listed in the array returned by 12505 <functionlink id="GetAllThreads"></functionlink> 12506 before its thread start event is generated. 12507 It is possible for other events to be generated 12508 on a thread before its thread start event. 12509 <p/> 12510 The event is sent on the newly started <paramlink id="thread"></paramlink>. 12511 </description> 12512 <origin>jvmdi</origin> 12513 <capabilities> 12514 </capabilities> 12515 <parameters> 12516 <param id="jni_env"> 12517 <outptr> 12518 <struct>JNIEnv</struct> 12519 </outptr> 12520 <description> 12521 The JNI environment of the event (current) thread. 12522 </description> 12523 </param> 12524 <param id="thread"> 12525 <jthread/> 12526 <description> 12527 Thread starting 12528 </description> 12529 </param> 12530 </parameters> 12531 </event> 12532 12533 <event label="Thread End" 12534 id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start"> 12535 <description> 12536 Thread end events are generated by a terminating thread 12537 after its initial method has finished execution. 12538 <p/> 12539 A thread may be listed in the array returned by 12540 <functionlink id="GetAllThreads"></functionlink> 12541 after its thread end event is generated. 12542 No events are generated on a thread 12543 after its thread end event. 12544 <p/> 12545 The event is sent on the dying <paramlink id="thread"></paramlink>. 12546 </description> 12547 <origin>jvmdi</origin> 12548 <capabilities> 12549 </capabilities> 12550 <parameters> 12551 <param id="jni_env"> 12552 <outptr> 12553 <struct>JNIEnv</struct> 12554 </outptr> 12555 <description> 12556 The JNI environment of the event (current) thread. 12557 </description> 12558 </param> 12559 <param id="thread"> 12560 <jthread/> 12561 <description> 12562 Thread ending 12563 </description> 12564 </param> 12565 </parameters> 12566 </event> 12567 12568 <event label="Class Load" 12569 id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55"> 12570 <description> 12571 A class load event is generated when a class is first loaded. The order 12572 of class load events generated by a particular thread are guaranteed 12573 to match the order of class loading within that thread. 12574 Array class creation does not generate a class load event. 12575 The creation of a primitive class (for example, java.lang.Integer.TYPE) 12576 does not generate a class load event. 12577 <p/> 12578 This event is sent at an early stage in loading the class. As 12579 a result the class should be used carefully. Note, for example, 12580 that methods and fields are not yet loaded, so queries for methods, 12581 fields, subclasses, and so on will not give correct results. 12582 See "Loading of Classes and Interfaces" in the <i>Java Language 12583 Specification</i>. For most 12584 purposes the <eventlink id="ClassPrepare"></eventlink> event will 12585 be more useful. 12586 </description> 12587 <origin>jvmdi</origin> 12588 <capabilities> 12589 </capabilities> 12590 <parameters> 12591 <param id="jni_env"> 12592 <outptr> 12593 <struct>JNIEnv</struct> 12594 </outptr> 12595 <description> 12596 The JNI environment of the event (current) thread 12597 </description> 12598 </param> 12599 <param id="thread"> 12600 <jthread/> 12601 <description> 12602 Thread loading the class 12603 </description> 12604 </param> 12605 <param id="klass"> 12606 <jclass/> 12607 <description> 12608 Class being loaded 12609 </description> 12610 </param> 12611 </parameters> 12612 </event> 12613 12614 <elide> 12615 <event label="Class Unload" 12616 id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57"> 12617 <description> 12618 A class unload event is generated when the class is about to be unloaded. 12619 Class unload events take place during garbage collection and must be 12620 handled extremely carefully. The garbage collector holds many locks 12621 and has suspended all other threads, so the event handler cannot depend 12622 on the ability to acquire any locks. The class unload event handler should 12623 do as little as possible, perhaps by queuing information to be processed 12624 later. In particular, the <code>jclass</code> should be used only in 12625 the JNI function <code>isSameObject</code> or in the following <jvmti/> functions: 12626 <ul> 12627 <li><functionlink id="GetClassSignature"></functionlink></li> 12628 <li><functionlink id="GetSourceFileName"></functionlink></li> 12629 <li><functionlink id="IsInterface"></functionlink></li> 12630 <li><functionlink id="IsArrayClass"></functionlink></li> 12631 </ul> 12632 </description> 12633 <origin>jvmdi</origin> 12634 <capabilities> 12635 </capabilities> 12636 <parameters> 12637 <param id="jni_env"> 12638 <outptr> 12639 <struct>JNIEnv</struct> 12640 </outptr> 12641 <description> 12642 The JNI environment of the event (current) thread 12643 </description> 12644 </param> 12645 <param id="thread"> 12646 <jthread/> 12647 <description> 12648 Thread generating the class unload 12649 </description> 12650 </param> 12651 <param id="klass"> 12652 <jclass/> 12653 <description> 12654 Class being unloaded 12655 </description> 12656 </param> 12657 </parameters> 12658 </event> 12659 </elide> 12660 12661 <event label="Class Prepare" 12662 id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56"> 12663 <description> 12664 A class prepare event is generated when class preparation is complete. 12665 At this point, class fields, methods, and implemented interfaces are 12666 available, and no code from the class has been executed. Since array 12667 classes never have fields or methods, class prepare events are not 12668 generated for them. Class prepare events are not generated for 12669 primitive classes (for example, <code>java.lang.Integer.TYPE</code>). 12670 </description> 12671 <origin>jvmdi</origin> 12672 <capabilities> 12673 </capabilities> 12674 <parameters> 12675 <param id="jni_env"> 12676 <outptr> 12677 <struct>JNIEnv</struct> 12678 </outptr> 12679 <description> 12680 The JNI environment of the event (current) thread 12681 </description> 12682 </param> 12683 <param id="thread"> 12684 <jthread/> 12685 <description> 12686 Thread generating the class prepare 12687 </description> 12688 </param> 12689 <param id="klass"> 12690 <jclass/> 12691 <description> 12692 Class being prepared 12693 </description> 12694 </param> 12695 </parameters> 12696 </event> 12697 12698 <event label="Class File Load Hook" phase="any" 12699 id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54"> 12700 <description> 12701 This event is sent when the VM obtains class file data, 12702 but before it constructs 12703 the in-memory representation for that class. 12704 This event is also sent when the class is being modified by the 12705 <functionlink id="RetransformClasses"/> function or 12706 the <functionlink id="RedefineClasses"/> function, 12707 called in any <jvmti/> environment. 12708 The agent can instrument 12709 the existing class file data sent by the VM to include profiling/debugging hooks. 12710 See the description of 12711 <internallink id="bci">bytecode instrumentation</internallink> 12712 for usage information. 12713 <p/> 12714 When the capabilities 12715 <internallink id="jvmtiCapabilities.can_generate_early_class_hook_events"> 12716 <code>can_generate_early_class_hook_events</code></internallink> and 12717 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events"> 12718 <code>can_generate_all_class_hook_events</code></internallink> 12719 are enabled then this event may be sent in the primordial phase. 12720 Otherwise, this event may be sent before the VM is initialized (the start 12721 <functionlink id="GetPhase">phase</functionlink>). 12722 Some classes might not be compatible 12723 with the function (eg. ROMized classes or implementation defined classes) and this event will 12724 not be generated for these classes. 12725 <p/> 12726 The agent must allocate the space for the modified 12727 class file data buffer 12728 using the memory allocation function 12729 <functionlink id="Allocate"></functionlink> because the 12730 VM is responsible for freeing the new class file data buffer 12731 using <functionlink id="Deallocate"></functionlink>. 12732 <p/> 12733 If the agent wishes to modify the class file, it must set 12734 <code>new_class_data</code> to point 12735 to the newly instrumented class file data buffer and set 12736 <code>new_class_data_len</code> to the length of that 12737 buffer before returning 12738 from this call. If no modification is desired, the agent simply 12739 does not set <code>new_class_data</code>. If multiple agents 12740 have enabled this event the results are chained. That is, if 12741 <code>new_class_data</code> has been set, it becomes the 12742 <code>class_data</code> for the next agent. 12743 <p/> 12744 When handling a class load in the live phase, then the 12745 <functionlink id="GetNamedModule"></functionlink> 12746 function can be used to map class loader and a package name to a module. 12747 When a class is being redefined or retransformed then 12748 <code>class_being_redefined</code> is non <code>NULL</code> and so 12749 the JNI <code>GetModule</code> function can also be used 12750 to obtain the Module. 12751 <p/> 12752 The order that this event is sent to each environment differs 12753 from other events. 12754 This event is sent to environments in the following order: 12755 <ul> 12756 <li><fieldlink id="can_retransform_classes" 12757 struct="jvmtiCapabilities">retransformation 12758 incapable</fieldlink> 12759 environments, in the 12760 order in which they were created 12761 </li> 12762 <li><fieldlink id="can_retransform_classes" 12763 struct="jvmtiCapabilities">retransformation 12764 capable</fieldlink> 12765 environments, in the 12766 order in which they were created 12767 </li> 12768 </ul> 12769 When triggered by <functionlink id="RetransformClasses"/>, 12770 this event is sent only to <fieldlink id="can_retransform_classes" 12771 struct="jvmtiCapabilities">retransformation 12772 capable</fieldlink> 12773 environments. 12774 </description> 12775 <origin>jvmpi</origin> 12776 <capabilities> 12777 <capability id="can_generate_all_class_hook_events"></capability> 12778 <capability id="can_generate_early_class_hook_events"></capability> 12779 </capabilities> 12780 <parameters> 12781 <param id="jni_env"> 12782 <outptr> 12783 <struct>JNIEnv</struct> 12784 </outptr> 12785 <description> 12786 The JNI environment of the event (current) thread. 12787 </description> 12788 </param> 12789 <param id="class_being_redefined"> 12790 <jclass/> 12791 <description> 12792 The class being 12793 <functionlink id="RedefineClasses">redefined</functionlink> or 12794 <functionlink id="RetransformClasses">retransformed</functionlink>. 12795 <code>NULL</code> if sent by class load. 12796 </description> 12797 </param> 12798 <param id="loader"> 12799 <jobject/> 12800 <description> 12801 The class loader loading the class. 12802 <code>NULL</code> if the bootstrap class loader. 12803 </description> 12804 </param> 12805 <param id="name"> 12806 <vmbuf><char/></vmbuf> 12807 <description> 12808 Name of class being loaded as a VM internal qualified name 12809 (for example, "java/util/List"), encoded as a 12810 <internallink id="mUTF">modified UTF-8</internallink> string. 12811 Note: if the class is defined with a <code>NULL</code> name or 12812 without a name specified, <code>name</code> will be <code>NULL</code>. 12813 </description> 12814 </param> 12815 <param id="protection_domain"> 12816 <jobject/> 12817 <description> 12818 The <code>ProtectionDomain</code> of the class. 12819 </description> 12820 </param> 12821 <param id="class_data_len"> 12822 <jint/> 12823 <description> 12824 Length of current class file data buffer. 12825 </description> 12826 </param> 12827 <param id="class_data"> 12828 <vmbuf><uchar/></vmbuf> 12829 <description> 12830 Pointer to the current class file data buffer. 12831 </description> 12832 </param> 12833 <param id="new_class_data_len"> 12834 <outptr><jint/></outptr> 12835 <description> 12836 Pointer to the length of the new class file data buffer. 12837 </description> 12838 </param> 12839 <param id="new_class_data"> 12840 <agentbuf incount="new_class_data_len"><uchar/></agentbuf> 12841 <description> 12842 Pointer to the pointer to the instrumented class file data buffer. 12843 </description> 12844 </param> 12845 </parameters> 12846 </event> 12847 12848 <event label="VM Start Event" 12849 id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start"> 12850 <description> 12851 The VM start event signals the start of the VM. 12852 At this time JNI is live but the VM is not yet fully initialized. 12853 Once this event is generated, the agent is free to call any JNI function. 12854 This event signals the beginning of the start phase, 12855 <jvmti/> functions permitted in the start phase may be called. 12856 <p/> 12857 The timing of this event may depend on whether the agent has added the 12858 <internallink id="jvmtiCapabilities.can_generate_early_vmstart"> 12859 <code>can_generate_early_vmstart</code></internallink> capability or not. 12860 If the capability has been added then the VM posts the event as early 12861 as possible. The VM is capable of executing bytecode but it may not have 12862 initialized to the point where it can load classes in modules other than 12863 <code>java.base</code>. Agents that do load-time instrumentation in this 12864 phase must take great care when instrumenting code that potentially 12865 executes in this phase. Care should also be taken with JNI 12866 <code>FindClass</code> as it may not be possible to load classes that are 12867 not in the <code>java.base</code> module. 12868 If the capability has not been added then the VM delays posting this 12869 event until it is capable of loading classes in modules other than 12870 <code>java.base</code> or the VM has completed its initialization. 12871 Agents that create more than one JVM TI environment, where the 12872 capability is added to some but not all environments, may observe the 12873 start phase beginning earlier in the JVM TI environments that possess 12874 the capabilty. 12875 <p/> 12876 In the case of VM start-up failure, this event will not be sent. 12877 </description> 12878 <origin>jvmdi</origin> 12879 <capabilities> 12880 </capabilities> 12881 <parameters> 12882 <param id="jni_env"> 12883 <outptr> 12884 <struct>JNIEnv</struct> 12885 </outptr> 12886 <description> 12887 The JNI environment of the event (current) thread. 12888 </description> 12889 </param> 12890 </parameters> 12891 </event> 12892 12893 <event label="VM Initialization Event" 12894 id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50"> 12895 <description> 12896 The VM initialization event signals the completion of VM initialization. Once 12897 this event is generated, the agent is free to call any JNI or <jvmti/> 12898 function. The VM initialization event can be preceded by or can be concurrent 12899 with other events, but 12900 the preceding events should be handled carefully, if at all, because the 12901 VM has not completed its initialization. The thread start event for the 12902 main application thread is guaranteed not to occur until after the 12903 handler for the VM initialization event returns. 12904 <p/> 12905 In the case of VM start-up failure, this event will not be sent. 12906 </description> 12907 <origin>jvmdi</origin> 12908 <capabilities> 12909 </capabilities> 12910 <parameters> 12911 <param id="jni_env"> 12912 <outptr> 12913 <struct>JNIEnv</struct> 12914 </outptr> 12915 <description> 12916 The JNI environment of the event (current) thread. 12917 </description> 12918 </param> 12919 <param id="thread"> 12920 <jthread/> 12921 <description> 12922 The initial thread 12923 </description> 12924 </param> 12925 </parameters> 12926 </event> 12927 12928 <event label="VM Death Event" 12929 id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51"> 12930 <description> 12931 The VM death event notifies the agent of the termination of the VM. 12932 No events will occur after the VMDeath event. 12933 <p/> 12934 In the case of VM start-up failure, this event will not be sent. 12935 Note that <internallink id="onunload">Agent_OnUnload</internallink> 12936 will still be called in these cases. 12937 </description> 12938 <origin>jvmdi</origin> 12939 <capabilities> 12940 </capabilities> 12941 <parameters> 12942 <param id="jni_env"> 12943 <outptr> 12944 <struct>JNIEnv</struct> 12945 </outptr> 12946 <description> 12947 The JNI environment of the event (current) thread 12948 </description> 12949 </param> 12950 </parameters> 12951 </event> 12952 12953 <event label="Compiled Method Load" phase="start" 12954 id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68"> 12955 <description> 12956 Sent when a method is compiled and loaded into memory by the VM. 12957 If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent. 12958 If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent, 12959 followed by a new <code>CompiledMethodLoad</code> event. 12960 Note that a single method may have multiple compiled forms, and that 12961 this event will be sent for each form. 12962 Note also that several methods may be inlined into a single 12963 address range, and that this event will be sent for each method. 12964 <p/> 12965 These events can be sent after their initial occurrence with 12966 <functionlink id="GenerateEvents"></functionlink>. 12967 </description> 12968 <origin>jvmpi</origin> 12969 <typedef id="jvmtiAddrLocationMap" label="Native address to location entry"> 12970 <field id="start_address"> 12971 <vmbuf><void/></vmbuf> 12972 <description> 12973 Starting native address of code corresponding to a location 12974 </description> 12975 </field> 12976 <field id="location"> 12977 <jlocation/> 12978 <description> 12979 Corresponding location. See 12980 <functionlink id="GetJLocationFormat"></functionlink> 12981 for the meaning of location. 12982 </description> 12983 </field> 12984 </typedef> 12985 <capabilities> 12986 <required id="can_generate_compiled_method_load_events"></required> 12987 </capabilities> 12988 <parameters> 12989 <param id="klass"> 12990 <jclass method="method"/> 12991 <description> 12992 Class of the method being compiled and loaded 12993 </description> 12994 </param> 12995 <param id="method"> 12996 <jmethodID class="klass"/> 12997 <description> 12998 Method being compiled and loaded 12999 </description> 13000 </param> 13001 <param id="code_size"> 13002 <jint/> 13003 <description> 13004 Size of compiled code 13005 </description> 13006 </param> 13007 <param id="code_addr"> 13008 <vmbuf><void/></vmbuf> 13009 <description> 13010 Address where compiled method code is loaded 13011 </description> 13012 </param> 13013 <param id="map_length"> 13014 <jint/> 13015 <description> 13016 Number of <typelink id="jvmtiAddrLocationMap"></typelink> 13017 entries in the address map. 13018 Zero if mapping information cannot be supplied. 13019 </description> 13020 </param> 13021 <param id="map"> 13022 <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf> 13023 <description> 13024 Map from native addresses to location. 13025 The native address range of each entry is from 13026 <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink> 13027 to <code>start_address-1</code> of the next entry. 13028 <code>NULL</code> if mapping information cannot be supplied. 13029 </description> 13030 </param> 13031 <param id="compile_info"> 13032 <vmbuf><void/></vmbuf> 13033 <description> 13034 VM-specific compilation information. 13035 The referenced compile information is managed by the VM 13036 and must not depend on the agent for collection. 13037 A VM implementation defines the content and lifetime 13038 of the information. 13039 </description> 13040 </param> 13041 </parameters> 13042 </event> 13043 13044 <event label="Compiled Method Unload" phase="start" 13045 id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69"> 13046 <description> 13047 Sent when a compiled method is unloaded from memory. 13048 This event might not be sent on the thread which performed the unload. 13049 This event may be sent sometime after the unload occurs, but 13050 will be sent before the memory is reused 13051 by a newly generated compiled method. This event may be sent after 13052 the class is unloaded. 13053 </description> 13054 <origin>jvmpi</origin> 13055 <capabilities> 13056 <required id="can_generate_compiled_method_load_events"></required> 13057 </capabilities> 13058 <parameters> 13059 <param id="klass"> 13060 <jclass method="method"/> 13061 <description> 13062 Class of the compiled method being unloaded. 13063 </description> 13064 </param> 13065 <param id="method"> 13066 <jmethodID class="klass"/> 13067 <description> 13068 Compiled method being unloaded. 13069 For identification of the compiled method only -- the class 13070 may be unloaded and therefore the method should not be used 13071 as an argument to further JNI or <jvmti/> functions. 13072 </description> 13073 </param> 13074 <param id="code_addr"> 13075 <vmbuf><void/></vmbuf> 13076 <description> 13077 Address where compiled method code was loaded. 13078 For identification of the compiled method only -- 13079 the space may have been reclaimed. 13080 </description> 13081 </param> 13082 </parameters> 13083 </event> 13084 13085 <event label="Dynamic Code Generated" phase="any" 13086 id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70"> 13087 <description> 13088 Sent when a component of the virtual machine is generated dynamically. 13089 This does not correspond to Java programming language code that is 13090 compiled--see <eventlink id="CompiledMethodLoad"></eventlink>. 13091 This is for native code--for example, an interpreter that is generated 13092 differently depending on command-line options. 13093 <p/> 13094 Note that this event has no controlling capability. 13095 If a VM cannot generate these events, it simply does not send any. 13096 <p/> 13097 These events can be sent after their initial occurrence with 13098 <functionlink id="GenerateEvents"></functionlink>. 13099 </description> 13100 <origin>jvmpi</origin> 13101 <capabilities> 13102 </capabilities> 13103 <parameters> 13104 <param id="name"> 13105 <vmbuf><char/></vmbuf> 13106 <description> 13107 Name of the code, encoded as a 13108 <internallink id="mUTF">modified UTF-8</internallink> string. 13109 Intended for display to an end-user. 13110 The name might not be unique. 13111 </description> 13112 </param> 13113 <param id="address"> 13114 <vmbuf><void/></vmbuf> 13115 <description> 13116 Native address of the code 13117 </description> 13118 </param> 13119 <param id="length"> 13120 <jint/> 13121 <description> 13122 Length in bytes of the code 13123 </description> 13124 </param> 13125 </parameters> 13126 </event> 13127 13128 <event label="Data Dump Request" 13129 id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71"> 13130 <description> 13131 Sent by the VM to request the agent to dump its data. This 13132 is just a hint and the agent need not react to this event. 13133 This is useful for processing command-line signals from users. For 13134 example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris 13135 causes the VM to send this event to the agent. 13136 </description> 13137 <origin>jvmpi</origin> 13138 <capabilities> 13139 </capabilities> 13140 <parameters> 13141 </parameters> 13142 </event> 13143 13144 <event label="Monitor Contended Enter" 13145 id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75"> 13146 <description> 13147 Sent when a thread is attempting to enter a Java programming language 13148 monitor already acquired by another thread. 13149 </description> 13150 <origin>jvmpi</origin> 13151 <capabilities> 13152 <required id="can_generate_monitor_events"></required> 13153 </capabilities> 13154 <parameters> 13155 <param id="jni_env"> 13156 <outptr> 13157 <struct>JNIEnv</struct> 13158 </outptr> 13159 <description> 13160 The JNI environment of the event (current) thread 13161 </description> 13162 </param> 13163 <param id="thread"> 13164 <jthread/> 13165 <description> 13166 JNI local reference to the thread 13167 attempting to enter the monitor 13168 </description> 13169 </param> 13170 <param id="object"> 13171 <jobject/> 13172 <description> 13173 JNI local reference to the monitor 13174 </description> 13175 </param> 13176 </parameters> 13177 </event> 13178 13179 <event label="Monitor Contended Entered" 13180 id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76"> 13181 <description> 13182 Sent when a thread enters a Java programming language 13183 monitor after waiting for it to be released by another thread. 13184 </description> 13185 <origin>jvmpi</origin> 13186 <capabilities> 13187 <required id="can_generate_monitor_events"></required> 13188 </capabilities> 13189 <parameters> 13190 <param id="jni_env"> 13191 <outptr> 13192 <struct>JNIEnv</struct> 13193 </outptr> 13194 <description> 13195 The JNI environment of the event (current) thread 13196 </description> 13197 </param> 13198 <param id="thread"> 13199 <jthread/> 13200 <description> 13201 JNI local reference to the thread entering 13202 the monitor 13203 </description> 13204 </param> 13205 <param id="object"> 13206 <jobject/> 13207 <description> 13208 JNI local reference to the monitor 13209 </description> 13210 </param> 13211 </parameters> 13212 </event> 13213 13214 <event label="Monitor Wait" 13215 id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73"> 13216 <description> 13217 Sent when a thread is about to wait on an object. 13218 </description> 13219 <origin>jvmpi</origin> 13220 <capabilities> 13221 <required id="can_generate_monitor_events"></required> 13222 </capabilities> 13223 <parameters> 13224 <param id="jni_env"> 13225 <outptr> 13226 <struct>JNIEnv</struct> 13227 </outptr> 13228 <description> 13229 The JNI environment of the event (current) thread 13230 </description> 13231 </param> 13232 <param id="thread"> 13233 <jthread/> 13234 <description> 13235 JNI local reference to the thread about to wait 13236 </description> 13237 </param> 13238 <param id="object"> 13239 <jobject/> 13240 <description> 13241 JNI local reference to the monitor 13242 </description> 13243 </param> 13244 <param id="timeout"> 13245 <jlong/> 13246 <description> 13247 The number of milliseconds the thread will wait 13248 </description> 13249 </param> 13250 </parameters> 13251 </event> 13252 13253 <event label="Monitor Waited" 13254 id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74"> 13255 <description> 13256 Sent when a thread finishes waiting on an object. 13257 </description> 13258 <origin>jvmpi</origin> 13259 <capabilities> 13260 <required id="can_generate_monitor_events"></required> 13261 </capabilities> 13262 <parameters> 13263 <param id="jni_env"> 13264 <outptr> 13265 <struct>JNIEnv</struct> 13266 </outptr> 13267 <description> 13268 The JNI environment of the event (current) thread 13269 </description> 13270 </param> 13271 <param id="thread"> 13272 <jthread/> 13273 <description> 13274 JNI local reference to the thread that was finished waiting 13275 </description> 13276 </param> 13277 <param id="object"> 13278 <jobject/> 13279 <description> 13280 JNI local reference to the monitor. 13281 </description> 13282 </param> 13283 <param id="timed_out"> 13284 <jboolean/> 13285 <description> 13286 True if the monitor timed out 13287 </description> 13288 </param> 13289 </parameters> 13290 </event> 13291 13292 <event label="Resource Exhausted" 13293 id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80" 13294 since="1.1"> 13295 <description> 13296 Sent when a VM resource needed by a running application has been exhausted. 13297 Except as required by the optional capabilities, the set of resources 13298 which report exhaustion is implementation dependent. 13299 <p/> 13300 The following bit flags define the properties of the resource exhaustion: 13301 <constants id="jvmtiResourceExhaustionFlags" 13302 label="Resource Exhaustion Flags" 13303 kind="bits" 13304 since="1.1"> 13305 <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001"> 13306 After this event returns, the VM will throw a 13307 <code>java.lang.OutOfMemoryError</code>. 13308 </constant> 13309 <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002"> 13310 The VM was unable to allocate memory from the <tm>Java</tm> 13311 platform <i>heap</i>. 13312 The <i>heap</i> is the runtime 13313 data area from which memory for all class instances and 13314 arrays are allocated. 13315 </constant> 13316 <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004"> 13317 The VM was unable to create a thread. 13318 </constant> 13319 </constants> 13320 </description> 13321 <origin>new</origin> 13322 <capabilities> 13323 <capability id="can_generate_resource_exhaustion_heap_events"> 13324 Can generate events when the VM is unable to allocate memory from the 13325 <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>. 13326 </capability> 13327 <capability id="can_generate_resource_exhaustion_threads_events"> 13328 Can generate events when the VM is unable to 13329 <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create 13330 a thread</internallink>. 13331 </capability> 13332 </capabilities> 13333 <parameters> 13334 <param id="jni_env"> 13335 <outptr> 13336 <struct>JNIEnv</struct> 13337 </outptr> 13338 <description> 13339 The JNI environment of the event (current) thread 13340 </description> 13341 </param> 13342 <param id="flags"> 13343 <jint/> 13344 <description> 13345 Flags defining the properties of the of resource exhaustion 13346 as specified by the 13347 <internallink id="jvmtiResourceExhaustionFlags">Resource 13348 Exhaustion Flags</internallink>. 13349 </description> 13350 </param> 13351 <param id="reserved"> 13352 <vmbuf><void/></vmbuf> 13353 <description> 13354 Reserved. 13355 </description> 13356 </param> 13357 <param id="description"> 13358 <vmbuf><char/></vmbuf> 13359 <description> 13360 Description of the resource exhaustion, encoded as a 13361 <internallink id="mUTF">modified UTF-8</internallink> string. 13362 </description> 13363 </param> 13364 </parameters> 13365 </event> 13366 13367 <event label="VM Object Allocation" 13368 id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84"> 13369 <description> 13370 Sent when a method causes the virtual machine to allocate an 13371 Object visible to Java programming language code and the 13372 allocation is not detectable by other intrumentation mechanisms. 13373 Generally object allocation should be detected by instrumenting 13374 the bytecodes of allocating methods. 13375 Object allocation generated in native code by JNI function 13376 calls should be detected using 13377 <internallink id="jniIntercept">JNI function interception</internallink>. 13378 Some methods might not have associated bytecodes and are not 13379 native methods, they instead are executed directly by the 13380 VM. These methods should send this event. 13381 Virtual machines which are incapable of bytecode instrumentation 13382 for some or all of their methods can send this event. 13383 <p/> 13384 Typical examples where this event might be sent: 13385 <ul> 13386 <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li> 13387 <li>Methods not represented by bytecodes -- for example, VM intrinsics and 13388 J2ME preloaded classes</li> 13389 </ul> 13390 Cases where this event would not be generated: 13391 <ul> 13392 <li>Allocation due to bytecodes -- for example, the <code>new</code> 13393 and <code>newarray</code> VM instructions</li> 13394 <li>Allocation due to JNI function calls -- for example, 13395 <code>AllocObject</code></li> 13396 <li>Allocations during VM initialization</li> 13397 <li>VM internal objects</li> 13398 </ul> 13399 </description> 13400 <origin>new</origin> 13401 <capabilities> 13402 <required id="can_generate_vm_object_alloc_events"></required> 13403 </capabilities> 13404 <parameters> 13405 <param id="jni_env"> 13406 <outptr> 13407 <struct>JNIEnv</struct> 13408 </outptr> 13409 <description> 13410 The JNI environment of the event (current) thread 13411 </description> 13412 </param> 13413 <param id="thread"> 13414 <jthread/> 13415 <description> 13416 Thread allocating the object. 13417 </description> 13418 </param> 13419 <param id="object"> 13420 <jobject/> 13421 <description> 13422 JNI local reference to the object that was allocated 13423 </description> 13424 </param> 13425 <param id="object_klass"> 13426 <jclass/> 13427 <description> 13428 JNI local reference to the class of the object 13429 </description> 13430 </param> 13431 <param id="size"> 13432 <jlong/> 13433 <description> 13434 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. 13435 </description> 13436 </param> 13437 </parameters> 13438 </event> 13439 13440 <event label="Object Free" 13441 id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83"> 13442 <description> 13443 An Object Free event is sent when the garbage collector frees an object. 13444 Events are only sent for tagged objects--see 13445 <internallink id="Heap">heap functions</internallink>. 13446 <p/> 13447 The event handler must not use JNI functions and 13448 must not use <jvmti/> functions except those which 13449 specifically allow such use (see the raw monitor, memory management, 13450 and environment local storage functions). 13451 </description> 13452 <origin>new</origin> 13453 <capabilities> 13454 <required id="can_generate_object_free_events"></required> 13455 </capabilities> 13456 <parameters> 13457 <param id="tag"> 13458 <jlong/> 13459 <description> 13460 The freed object's tag 13461 </description> 13462 </param> 13463 </parameters> 13464 </event> 13465 13466 <event label="Garbage Collection Start" 13467 id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81"> 13468 <description> 13469 A Garbage Collection Start event is sent when a 13470 garbage collection pause begins. 13471 Only stop-the-world collections are reported--that is, collections during 13472 which all threads cease to modify the state of the Java virtual machine. 13473 This means that some collectors will never generate these events. 13474 This event is sent while the VM is still stopped, thus 13475 the event handler must not use JNI functions and 13476 must not use <jvmti/> functions except those which 13477 specifically allow such use (see the raw monitor, memory management, 13478 and environment local storage functions). 13479 <p/> 13480 This event is always sent as a matched pair with 13481 <eventlink id="GarbageCollectionFinish"/> 13482 (assuming both events are enabled) and no garbage collection 13483 events will occur between them. 13484 </description> 13485 <origin>new</origin> 13486 <capabilities> 13487 <required id="can_generate_garbage_collection_events"></required> 13488 </capabilities> 13489 <parameters> 13490 </parameters> 13491 </event> 13492 13493 <event label="Garbage Collection Finish" 13494 id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82"> 13495 <description> 13496 A Garbage Collection Finish event is sent when a 13497 garbage collection pause ends. 13498 This event is sent while the VM is still stopped, thus 13499 the event handler must not use JNI functions and 13500 must not use <jvmti/> functions except those which 13501 specifically allow such use (see the raw monitor, memory management, 13502 and environment local storage functions). 13503 <p/> 13504 Some agents may need to do post garbage collection operations that 13505 require the use of the disallowed <jvmti/> or JNI functions. For these 13506 cases an agent thread can be created which waits on a raw monitor, 13507 and the handler for the Garbage Collection Finish event simply 13508 notifies the raw monitor 13509 <p/> 13510 This event is always sent as a matched pair with 13511 <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled). 13512 <issue> 13513 The most important use of this event is to provide timing information, 13514 and thus additional information is not required. However, 13515 information about the collection which is "free" should be included - 13516 what that information is needs to be determined. 13517 </issue> 13518 </description> 13519 <origin>new</origin> 13520 <capabilities> 13521 <required id="can_generate_garbage_collection_events"></required> 13522 </capabilities> 13523 <parameters> 13524 </parameters> 13525 </event> 13526 13527 <elide> 13528 <event label="Verbose Output" phase="any" 13529 id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85"> 13530 <description> 13531 Send verbose messages as strings. 13532 <issue> 13533 This format is extremely fragile, as it can change with each 13534 platform, collector and version. Alternatives include: 13535 <ul> 13536 <li>building off Java programming language M and M APIs</li> 13537 <li>XML</li> 13538 <li>key/value pairs</li> 13539 <li>removing it</li> 13540 </ul> 13541 </issue> 13542 <issue> 13543 Though this seemed trivial to implement. 13544 In the RI it appears this will be quite complex. 13545 </issue> 13546 </description> 13547 <origin>new</origin> 13548 <capabilities> 13549 </capabilities> 13550 <parameters> 13551 <param id="flag"> 13552 <enum>jvmtiVerboseFlag</enum> 13553 <description> 13554 Which verbose output is being sent. 13555 </description> 13556 </param> 13557 <param id="message"> 13558 <vmbuf><char/></vmbuf> 13559 <description> 13560 Message text, encoded as a 13561 <internallink id="mUTF">modified UTF-8</internallink> string. 13562 </description> 13563 </param> 13564 </parameters> 13565 </event> 13566 </elide> 13567 13568</eventsection> 13569 13570<datasection> 13571 <intro> 13572 <jvmti/> extends the data types defined by JNI. 13573 </intro> 13574 <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface"> 13575 <basetype id="jboolean"> 13576 <description> 13577 Holds a Java programming language <code>boolean</code>. 13578 Unsigned 8 bits. 13579 </description> 13580 </basetype> 13581 <basetype id="jchar"> 13582 <description> 13583 Holds a Java programming language <code>char</code>. 13584 Unsigned 16 bits. 13585 </description> 13586 </basetype> 13587 <basetype id="jint"> 13588 <description> 13589 Holds a Java programming language <code>int</code>. 13590 Signed 32 bits. 13591 </description> 13592 </basetype> 13593 <basetype id="jlong"> 13594 <description> 13595 Holds a Java programming language <code>long</code>. 13596 Signed 64 bits. 13597 </description> 13598 </basetype> 13599 <basetype id="jfloat"> 13600 <description> 13601 Holds a Java programming language <code>float</code>. 13602 32 bits. 13603 </description> 13604 </basetype> 13605 <basetype id="jdouble"> 13606 <description> 13607 Holds a Java programming language <code>double</code>. 13608 64 bits. 13609 </description> 13610 </basetype> 13611 <basetype id="jobject"> 13612 <description> 13613 Holds a Java programming language object. 13614 </description> 13615 </basetype> 13616 <basetype id="jclass"> 13617 <description> 13618 Holds a Java programming language class. 13619 </description> 13620 </basetype> 13621 <basetype id="jvalue"> 13622 <description> 13623 Is a union of all primitive types and <code>jobject</code>. Thus, holds any Java 13624 programming language value. 13625 </description> 13626 </basetype> 13627 <basetype id="jfieldID"> 13628 <description> 13629 Identifies a Java programming language field. 13630 <code>jfieldID</code>s returned by <jvmti/> functions and events may be 13631 safely stored. 13632 </description> 13633 </basetype> 13634 <basetype id="jmethodID"> 13635 <description> 13636 Identifies a Java programming language method, initializer, or constructor. 13637 <code>jmethodID</code>s returned by <jvmti/> functions and events may be 13638 safely stored. However, if the class is unloaded, they become invalid 13639 and must not be used. 13640 </description> 13641 </basetype> 13642 <basetype id="JNIEnv"> 13643 <description> 13644 Pointer to the JNI function table. Pointer to this (<code>JNIEnv *</code>) 13645 is a JNI environment. 13646 </description> 13647 </basetype> 13648 </basetypes> 13649 13650 <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types"> 13651 <basetype id="jvmtiEnv"> 13652 <description> 13653 The <jvmti/> <internallink id="environments">environment</internallink> pointer. 13654 See the <internallink id="FunctionSection">Function Section</internallink>. 13655 <code>jvmtiEnv</code> points to the 13656 <internallink id="FunctionTable">function table</internallink> pointer. 13657 </description> 13658 </basetype> 13659 <basetype id="jthread"> 13660 <definition>typedef jobject jthread;</definition> 13661 <description> 13662 Subtype of <datalink id="jobject"></datalink> that holds a thread. 13663 </description> 13664 </basetype> 13665 <basetype id="jthreadGroup"> 13666 <definition>typedef jobject jthreadGroup;</definition> 13667 <description> 13668 Subtype of <datalink id="jobject"></datalink> that holds a thread group. 13669 </description> 13670 </basetype> 13671 <basetype id="jlocation"> 13672 <definition>typedef jlong jlocation;</definition> 13673 <description> 13674 A 64 bit value, representing a monotonically increasing 13675 executable position within a method. 13676 <code>-1</code> indicates a native method. 13677 See <functionlink id="GetJLocationFormat"></functionlink> for the format on a 13678 given VM. 13679 </description> 13680 </basetype> 13681 <basetype id="jrawMonitorID"> 13682 <definition>struct _jrawMonitorID; 13683typedef struct _jrawMonitorID *jrawMonitorID;</definition> 13684 <description> 13685 A raw monitor. 13686 </description> 13687 </basetype> 13688 <basetype id="jvmtiError"> 13689 <description> 13690 Holds an error return code. 13691 See the <internallink id="ErrorSection">Error section</internallink> for possible values. 13692 <example> 13693typedef enum { 13694 JVMTI_ERROR_NONE = 0, 13695 JVMTI_ERROR_INVALID_THREAD = 10, 13696 ... 13697} jvmtiError; 13698</example> 13699 </description> 13700 </basetype> 13701 <basetype id="jvmtiEvent"> 13702 <description> 13703 An identifier for an event type. 13704 See the <internallink id="EventSection">Event section</internallink> for possible values. 13705 It is guaranteed that future versions of this specification will 13706 never assign zero as an event type identifier. 13707<example> 13708typedef enum { 13709 JVMTI_EVENT_SINGLE_STEP = 1, 13710 JVMTI_EVENT_BREAKPOINT = 2, 13711 ... 13712} jvmtiEvent; 13713</example> 13714 </description> 13715 </basetype> 13716 <basetype id="jvmtiEventCallbacks"> 13717 <description> 13718 The callbacks used for events. 13719<example> 13720typedef struct { 13721 jvmtiEventVMInit VMInit; 13722 jvmtiEventVMDeath VMDeath; 13723 ... 13724} jvmtiEventCallbacks; 13725</example> 13726 See <internallink id="jvmtiEventCallbacks">event callbacks</internallink> 13727 for the complete structure. 13728 <p/> 13729 Where, for example, the VM initialization callback is defined: 13730<example> 13731typedef void (JNICALL *jvmtiEventVMInit) 13732 (jvmtiEnv *jvmti_env, 13733 JNIEnv* jni_env, 13734 jthread thread); 13735</example> 13736 See the individual events for the callback function definition. 13737 </description> 13738 </basetype> 13739 <basetype id="jniNativeInterface"> 13740 <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition> 13741 <description> 13742 Typedef for the JNI function table <code>JNINativeInterface</code> 13743 defined in the 13744 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp23720">JNI Specification</externallink>. 13745 The JNI reference implementation defines this with an underscore. 13746 </description> 13747 </basetype> 13748 </basetypes> 13749 13750</datasection> 13751 13752<issuessection label="Issues"> 13753 <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic"> 13754 JVMDI requires that the agent suspend threads before calling 13755 certain sensitive functions. JVMPI requires garbage collection to be 13756 disabled before calling certain sensitive functions. 13757 It was suggested that rather than have this requirement, that 13758 VM place itself in a suitable state before performing an 13759 operation. This makes considerable sense since each VM 13760 knows its requirements and can most easily arrange a 13761 safe state. 13762 <p/> 13763 The ability to externally suspend/resume threads will, of 13764 course, remain. The ability to enable/disable garbage collection will not. 13765 <p/> 13766 This issue is resolved--suspend will not 13767 be required. The spec has been updated to reflect this. 13768 </intro> 13769 13770 <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling"> 13771 There are a variety of approaches to sampling call stacks. 13772 The biggest bifurcation is between VM controlled and agent 13773 controlled. 13774 <p/> 13775 This issue is resolved--agent controlled 13776 sampling will be the approach. 13777 </intro> 13778 13779 <intro id="threadRepresentation" label="Resolved Issue: Thread Representation"> 13780 JVMDI represents threads as jthread. JVMPI primarily 13781 uses JNIEnv* to represent threads. 13782 <p/> 13783 The Expert Group has chosen jthread as the representation 13784 for threads in <jvmti/>. 13785 JNIEnv* is sent by 13786 events since it is needed to JNI functions. JNIEnv, per the 13787 JNI spec, are not supposed to be used outside their thread. 13788 </intro> 13789 13790 <intro id="design" label="Resolved Issue: Method Representation"> 13791 The JNI spec allows an implementation to depend on jclass/jmethodID 13792 pairs, rather than simply a jmethodID, to reference a method. 13793 JVMDI, for consistency, choose the same representation. 13794 JVMPI, however, specifies that a jmethodID alone maps to a 13795 method. Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store 13796 pointers in jmethodIDs, and as a result, a jmethodID is sufficient. 13797 In fact, any JVM implementation that supports JVMPI must have 13798 such a representation. 13799 <jvmti/> will use jmethodID as a unique representation of a method 13800 (no jclass is used). 13801 There should be efficiency gains, particularly in 13802 functionality like stack dumping, to this representation. 13803 <p/> 13804 Note that fields were not used in JVMPI and that the access profile 13805 of fields differs from methods--for implementation efficiency 13806 reasons, a jclass/jfieldID pair will still be needed for field 13807 reference. 13808 </intro> 13809 13810 <intro id="localReferenceIssue" label="Resolved Issue: Local References"> 13811 Functions return local references. 13812 </intro> 13813 13814 <intro id="frameRep" label="Resolved Issue: Representation of frames"> 13815 In JVMDI, a frame ID is used to represent a frame. Problem with this 13816 is that a VM must track when a frame becomes invalid, a far better 13817 approach, and the one used in <jvmti/>, is to reference frames by depth. 13818 </intro> 13819 13820 <intro id="requiredCapabilities" label="Issue: Required Capabilities"> 13821 Currently, having a required capabilities means that the functionality 13822 is optional. Capabilities are useful even for required functionality 13823 since they can inform the VM is needed set-up. Thus, there should be 13824 a set of capabilities that a conformant implementation must provide 13825 (if requested during Agent_OnLoad). 13826 </intro> 13827 13828 <intro id="taghint" label="Proposal: add tag hint function"> 13829 A hint of the percentage of objects that will be tagged would 13830 help the VM pick a good implementation. 13831 </intro> 13832 13833 <intro id="moreMonitorQueries" label="Request: More Monitor Quires"> 13834 How difficult or easy would be to extend the monitor_info category to include 13835 <pre> 13836 - current number of monitors 13837 - enumeration of monitors 13838 - enumeration of threads waiting on a given monitor 13839 </pre> 13840 The reason for my question is the fact that current get_monitor_info support 13841 requires the agent to specify a given thread to get the info which is probably 13842 OK in the profiling/debugging space, while in the monitoring space the agent 13843 could be watching the monitor list and then decide which thread to ask for 13844 the info. You might ask why is this important for monitoring .... I think it 13845 can aid in the detection/prediction of application contention caused by hot-locks. 13846 </intro> 13847</issuessection> 13848 13849<changehistory id="ChangeHistory" update="09/05/07"> 13850 <intro> 13851 The <jvmti/> specification is an evolving document with major, minor, 13852 and micro version numbers. 13853 A released version of the specification is uniquely identified 13854 by its major and minor version. 13855 The functions, events, and capabilities in this specification 13856 indicate a "Since" value which is the major and minor version in 13857 which it was introduced. 13858 The version of the specification implemented by the VM can 13859 be retrieved at runtime with the <functionlink id="GetVersionNumber"/> 13860 function. 13861 </intro> 13862 <change date="14 Nov 2002"> 13863 Converted to XML document. 13864 </change> 13865 <change date="14 Nov 2002"> 13866 Elided heap dump functions (for now) since what was there 13867 was wrong. 13868 </change> 13869 <change date="18 Nov 2002"> 13870 Added detail throughout. 13871 </change> 13872 <change date="18 Nov 2002"> 13873 Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE. 13874 </change> 13875 <change date="19 Nov 2002"> 13876 Added AsyncGetStackTrace. 13877 </change> 13878 <change date="19 Nov 2002"> 13879 Added jframeID return to GetStackTrace. 13880 </change> 13881 <change date="19 Nov 2002"> 13882 Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there 13883 since they are redundant with GetStackTrace. 13884 </change> 13885 <change date="19 Nov 2002"> 13886 Elided ClearAllBreakpoints since it has always been redundant. 13887 </change> 13888 <change date="19 Nov 2002"> 13889 Added GetSystemProperties. 13890 </change> 13891 <change date="19 Nov 2002"> 13892 Changed the thread local storage functions to use jthread. 13893 </change> 13894 <change date="20 Nov 2002"> 13895 Added GetJLocationFormat. 13896 </change> 13897 <change date="22 Nov 2002"> 13898 Added events and introductory text. 13899 </change> 13900 <change date="22 Nov 2002"> 13901 Cross reference type and constant definitions. 13902 </change> 13903 <change date="24 Nov 2002"> 13904 Added DTD. 13905 </change> 13906 <change date="24 Nov 2002"> 13907 Added capabilities function section. 13908 </change> 13909 <change date="29 Nov 2002"> 13910 Assign capabilities to each function and event. 13911 </change> 13912 <change date="29 Nov 2002"> 13913 Add <internallink id="jniIntercept">JNI interception functions</internallink>. 13914 </change> 13915 <change date="30 Nov 2002"> 13916 Auto generate SetEventNotificationMode capabilities. 13917 </change> 13918 <change date="30 Nov 2002"> 13919 Add <eventlink id="VMObjectAlloc"></eventlink> event. 13920 </change> 13921 <change date="30 Nov 2002"> 13922 Add <eventlink id="DynamicCodeGenerated"></eventlink> event. 13923 </change> 13924 <change date="30 Nov 2002"> 13925 Add const to declarations. 13926 </change> 13927 <change date="30 Nov 2002"> 13928 Change method exit and frame pop to send on exception. 13929 </change> 13930 <change date="1 Dec 2002"> 13931 Add ForceGarbageCollection. 13932 </change> 13933 <change date="2 Dec 2002"> 13934 Redo Xrun section; clarify GetStackTrace and add example; 13935 Fix width problems; use "agent" consistently. 13936 </change> 13937 <change date="8 Dec 2002"> 13938 Remove previous start-up intro. 13939 Add <internallink id="environments"><jvmti/> Environments</internallink> 13940 section. 13941 </change> 13942 <change date="8 Dec 2002"> 13943 Add <functionlink id="DisposeEnvironment"></functionlink>. 13944 </change> 13945 <change date="9 Dec 2002"> 13946 Numerous minor updates. 13947 </change> 13948 <change date="15 Dec 2002"> 13949 Add heap profiling functions added: 13950 get/set annotation, iterate live objects/heap. 13951 Add heap profiling functions place holder added: 13952 heap roots. 13953 Heap profiling event added: object free. 13954 Heap profiling event redesigned: vm object allocation. 13955 Heap profiling event placeholders added: garbage collection start/finish. 13956 Native method bind event added. 13957 </change> 13958 <change date="19 Dec 2002"> 13959 Revamp suspend/resume functions. 13960 Add origin information with jvmdi tag. 13961 Misc fixes. 13962 </change> 13963 <change date="24 Dec 2002"> 13964 Add semantics to types. 13965 </change> 13966 <change date="27 Dec 2002"> 13967 Add local reference section. 13968 Autogenerate parameter descriptions from types. 13969 </change> 13970 <change date="28 Dec 2002"> 13971 Document that RunAgentThread sends threadStart. 13972 </change> 13973 <change date="29 Dec 2002"> 13974 Remove redundant local ref and dealloc warning. 13975 Convert GetRawMonitorName to allocated buffer. 13976 Add GenerateEvents. 13977 </change> 13978 <change date="30 Dec 2002"> 13979 Make raw monitors a type and rename to "jrawMonitorID". 13980 </change> 13981 <change date="1 Jan 2003"> 13982 Include origin information. 13983 Clean-up JVMDI issue references. 13984 Remove Deallocate warnings which are now automatically generated. 13985 </change> 13986 <change date="2 Jan 2003"> 13987 Fix representation issues for jthread. 13988 </change> 13989 <change date="3 Jan 2003"> 13990 Make capabilities buffered out to 64 bits - and do it automatically. 13991 </change> 13992 <change date="4 Jan 2003"> 13993 Make constants which are enumeration into enum types. 13994 Parameters now of enum type. 13995 Clean-up and index type section. 13996 Replace remaining datadef entities with callback. 13997 </change> 13998 <change date="7 Jan 2003"> 13999 Correct GenerateEvents description. 14000 More internal semantics work. 14001 </change> 14002 <change date="9 Jan 2003"> 14003 Replace previous GetSystemProperties with two functions 14004 which use allocated information instead fixed. 14005 Add SetSystemProperty. 14006 More internal semantics work. 14007 </change> 14008 <change date="12 Jan 2003"> 14009 Add varargs to end of SetEventNotificationMode. 14010 </change> 14011 <change date="20 Jan 2003"> 14012 Finish fixing spec to reflect that alloc sizes are jlong. 14013 </change> 14014 <change date="22 Jan 2003"> 14015 Allow NULL as RunAgentThread arg. 14016 </change> 14017 <change date="22 Jan 2003"> 14018 Fixed names to standardized naming convention 14019 Removed AsyncGetStackTrace. 14020 </change> 14021 <change date="29 Jan 2003"> 14022 Since we are using jthread, removed GetThread. 14023 </change> 14024 <change date="31 Jan 2003"> 14025 Change GetFieldName to allow NULLs like GetMethodName. 14026 </change> 14027 <change date="29 Feb 2003" version="v40"> 14028 Rewrite the introductory text, adding sections on 14029 start-up, environments and bytecode instrumentation. 14030 Change the command line arguments per EG discussions. 14031 Add an introduction to the capabilities section. 14032 Add the extension mechanism category and functions. 14033 Mark for deletion, but clarified anyhow, SuspendAllThreads. 14034 Rename IterateOverLiveObjects to IterateOverReachableObjects and 14035 change the text accordingly. 14036 Clarify IterateOverHeap. 14037 Clarify CompiledMethodLoad. 14038 Discuss prerequisite state for Calling Functions. 14039 Clarify SetAllocationHooks. 14040 Added issues ("To be resolved:") through-out. 14041 And so on... 14042 </change> 14043 <change date="6 Mar 2003" version="v41"> 14044 Remove struct from the call to GetOwnedMonitorInfo. 14045 Automatically generate most error documentation, remove 14046 (rather broken) hand written error doc. 14047 Better describe capability use (empty initial set). 14048 Add min value to jint params. 14049 Remove the capability can_access_thread_local_storage. 14050 Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY; 14051 same for *NOT_IMPLEMENTED. 14052 Description fixes. 14053 </change> 14054 <change date="8 Mar 2003" version="v42"> 14055 Rename GetClassSignature to GetClassName. 14056 Rename IterateOverClassObjects to IterateOverInstancesOfClass. 14057 Remove GetMaxStack (operand stack isn't used in <jvmti/>). 14058 Description fixes: define launch-time, remove native frame pop 14059 from PopFrame, and assorted clarifications. 14060 </change> 14061 <change date="8 Mar 2003" version="v43"> 14062 Fix minor editing problem. 14063 </change> 14064 <change date="10 Mar 2003" version="v44"> 14065 Add phase information. 14066 Remap (compact) event numbers. 14067 </change> 14068 <change date="11 Mar 2003" version="v45"> 14069 More phase information - allow "any". 14070 Elide raw monitor queries and events. 14071 Minor description fixes. 14072 </change> 14073 <change date="12 Mar 2003" version="v46"> 14074 Add GetPhase. 14075 Use "phase" through document. 14076 Elide GetRawMonitorName. 14077 Elide GetObjectMonitors. 14078 </change> 14079 <change date="12 Mar 2003" version="v47"> 14080 Fixes from link, XML, and spell checking. 14081 Auto-generate the callback structure. 14082 </change> 14083 <change date="13 Mar 2003" version="v48"> 14084 One character XML fix. 14085 </change> 14086 <change date="13 Mar 2003" version="v49"> 14087 Change function parameter names to be consistent with 14088 event parameters (fooBarBaz becomes foo_bar_baz). 14089 </change> 14090 <change date="14 Mar 2003" version="v50"> 14091 Fix broken link. Fix thread markers. 14092 </change> 14093 <change date="14 Mar 2003" version="v51"> 14094 Change constants so they are under 128 to workaround 14095 compiler problems. 14096 </change> 14097 <change date="23 Mar 2003" version="v52"> 14098 Overhaul capabilities. Separate GetStackTrace into 14099 GetStackTrace and GetStackFrames. 14100 </change> 14101 <change date="8 Apr 2003" version="v54"> 14102 Use depth instead of jframeID to reference frames. 14103 Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames. 14104 Remove frame arg from events. 14105 </change> 14106 <change date="9 Apr 2003" version="v55"> 14107 Remove GetObjectWithAnnotation since tests show bufferred approach more efficient. 14108 Add missing annotation_count to GetObjectsWithAnnotations 14109 </change> 14110 <change date="10 Apr 2003" version="v56"> 14111 Remove confusing parenthetical statement in GetObjectsWithAnnotations 14112 </change> 14113 <change date="13 Apr 2003" version="v58"> 14114 Replace jclass/jmethodID representation of method with simply jmethodID; 14115 Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate. 14116 Replace can_access_frames with can_access_local_variables; remove from purely stack access. 14117 Use can_get_synthetic_attribute; fix description. 14118 Clarify that zero length arrays must be deallocated. 14119 Clarify RelinquishCapabilities. 14120 Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE. 14121 </change> 14122 <change date="27 Apr 2003" version="v59"> 14123 Remove lingering indirect references to OBSOLETE_METHOD_ID. 14124 </change> 14125 <change date="4 May 2003" version="v60"> 14126 Allow DestroyRawMonitor during OnLoad. 14127 </change> 14128 <change date="7 May 2003" version="v61"> 14129 Added not monitor owner error return to DestroyRawMonitor. 14130 </change> 14131 <change date="13 May 2003" version="v62"> 14132 Clarify semantics of raw monitors. 14133 Change flags on <code>GetThreadStatus</code>. 14134 <code>GetClassLoader</code> return NULL for the bootstrap class loader. 14135 Add <code>GetClassName</code> issue. 14136 Define local variable signature. 14137 Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>. 14138 Remove over specification in <code>GetObjectsWithAnnotations</code>. 14139 Elide <code>SetAllocationHooks</code>. 14140 Elide <code>SuspendAllThreads</code>. 14141 </change> 14142 <change date="14 May 2003" version="v63"> 14143 Define the data type <code>jvmtiEventCallbacks</code>. 14144 Zero length allocations return NULL. 14145 Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>. 14146 Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED. 14147 </change> 14148 <change date="15 May 2003" version="v64"> 14149 Better wording, per review. 14150 </change> 14151 <change date="15 May 2003" version="v65"> 14152 First Alpha. 14153 Make jmethodID and jfieldID unique, jclass not used. 14154 </change> 14155 <change date="27 May 2003" version="v66"> 14156 Fix minor XSLT errors. 14157 </change> 14158 <change date="13 June 2003" version="v67"> 14159 Undo making jfieldID unique (jmethodID still is). 14160 </change> 14161 <change date="17 June 2003" version="v68"> 14162 Changes per June 11th Expert Group meeting -- 14163 Overhaul Heap functionality: single callback, 14164 remove GetHeapRoots, add reachable iterators, 14165 and rename "annotation" to "tag". 14166 NULL thread parameter on most functions is current 14167 thread. 14168 Add timers. 14169 Remove ForceExit. 14170 Add GetEnvironmentLocalStorage. 14171 Add verbose flag and event. 14172 Add AddToBootstrapClassLoaderSearch. 14173 Update ClassFileLoadHook. 14174 </change> 14175 <change date="18 June 2003" version="v69"> 14176 Clean up issues sections. 14177 Rename GetClassName back to GetClassSignature and 14178 fix description. 14179 Add generic signature to GetClassSignature, 14180 GetFieldSignature, GetMethodSignature, and 14181 GetLocalVariableTable. 14182 Elide EstimateCostOfCapabilities. 14183 Clarify that the system property functions operate 14184 on the VM view of system properties. 14185 Clarify Agent_OnLoad. 14186 Remove "const" from JNIEnv* in events. 14187 Add metadata accessors. 14188 </change> 14189 <change date="18 June 2003" version="v70"> 14190 Add start_depth to GetStackTrace. 14191 Move system properties to a new category. 14192 Add GetObjectSize. 14193 Remove "X" from command line flags. 14194 XML, HTML, and spell check corrections. 14195 </change> 14196 <change date="19 June 2003" version="v71"> 14197 Fix JVMTI_HEAP_ROOT_THREAD to be 6. 14198 Make each synopsis match the function name. 14199 Fix unclear wording. 14200 </change> 14201 <change date="26 June 2003" version="v72"> 14202 SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value 14203 to be set to NULL. 14204 NotifyFramePop, GetFrameLocationm and all the local variable operations 14205 needed to have their wording about frames fixed. 14206 Grammar and clarity need to be fixed throughout. 14207 Capitalization and puntuation need to be consistent. 14208 Need micro version number and masks for accessing major, minor, and micro. 14209 The error code lists should indicate which must be returned by 14210 an implementation. 14211 The command line properties should be visible in the properties functions. 14212 Disallow popping from the current thread. 14213 Allow implementations to return opaque frame error when they cannot pop. 14214 The NativeMethodBind event should be sent during any phase. 14215 The DynamicCodeGenerated event should be sent during any phase. 14216 The following functions should be allowed to operate before VMInit: 14217 Set/GetEnvironmentLocalStorage 14218 GetMethodDeclaringClass 14219 GetClassSignature 14220 GetClassModifiers 14221 IsInterface 14222 IsArrayClass 14223 GetMethodName 14224 GetMethodModifiers 14225 GetMaxLocals 14226 GetArgumentsSize 14227 GetLineNumberTable 14228 GetMethodLocation 14229 IsMethodNative 14230 IsMethodSynthetic. 14231 Other changes (to XSL): 14232 Argument description should show asterisk after not before pointers. 14233 NotifyFramePop, GetFrameLocationm and all the local variable operations 14234 should hsve the NO_MORE_FRAMES error added. 14235 Not alive threads should have a different error return than invalid thread. 14236 </change> 14237 <change date="7 July 2003" version="v73"> 14238 VerboseOutput event was missing message parameter. 14239 Minor fix-ups. 14240 </change> 14241 <change date="14 July 2003" version="v74"> 14242 Technical Publications Department corrections. 14243 Allow thread and environment local storage to be set to NULL. 14244 </change> 14245 <change date="23 July 2003" version="v75"> 14246 Use new Agent_OnLoad rather than overloaded JVM_OnLoad. 14247 Add JNICALL to callbacks (XSL). 14248 Document JNICALL requirement for both events and callbacks (XSL). 14249 Restrict RedefineClasses to methods and attributes. 14250 Elide the VerboseOutput event. 14251 VMObjectAlloc: restrict when event is sent and remove method parameter. 14252 Finish loose ends from Tech Pubs edit. 14253 </change> 14254 <change date="24 July 2003" version="v76"> 14255 Change ClassFileLoadHook event to send the class instead of a boolean of redefine. 14256 </change> 14257 <change date="24 July 2003" version="v77"> 14258 XML fixes. 14259 Minor text clarifications and corrections. 14260 </change> 14261 <change date="24 July 2003" version="v78"> 14262 Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>. 14263 Clarify that stack frames are JVM Spec frames. 14264 Split can_get_source_info into can_get_source_file_name, can_get_line_numbers, 14265 and can_get_source_debug_extension. 14266 PopFrame cannot have a native calling method. 14267 Removed incorrect statement in GetClassloaderClasses 14268 (see <vmspec chapter="4.4"/>). 14269 </change> 14270 <change date="24 July 2003" version="v79"> 14271 XML and text fixes. 14272 Move stack frame description into Stack Frame category. 14273 </change> 14274 <change date="26 July 2003" version="v80"> 14275 Allow NULL (means bootstrap loader) for GetClassloaderClasses. 14276 Add new heap reference kinds for references from classes. 14277 Add timer information struct and query functions. 14278 Add AvailableProcessors. 14279 Rename GetOtherThreadCpuTime to GetThreadCpuTime. 14280 Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE 14281 to SetEventNotification mode. 14282 Add initial thread to the VM_INIT event. 14283 Remove platform assumptions from AddToBootstrapClassLoaderSearch. 14284 </change> 14285 <change date="26 July 2003" version="v81"> 14286 Grammar and clarity changes per review. 14287 </change> 14288 <change date="27 July 2003" version="v82"> 14289 More grammar and clarity changes per review. 14290 Add Agent_OnUnload. 14291 </change> 14292 <change date="28 July 2003" version="v83"> 14293 Change return type of Agent_OnUnload to void. 14294 </change> 14295 <change date="28 July 2003" version="v84"> 14296 Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT. 14297 </change> 14298 <change date="28 July 2003" version="v85"> 14299 Steal java.lang.Runtime.availableProcessors() wording for 14300 AvailableProcessors(). 14301 Guarantee that zero will never be an event ID. 14302 Remove some issues which are no longer issues. 14303 Per review, rename and more completely document the timer 14304 information functions. 14305 </change> 14306 <change date="29 July 2003" version="v86"> 14307 Non-spec visible change to XML controlled implementation: 14308 SetThreadLocalStorage must run in VM mode. 14309 </change> 14310 <change date="5 August 2003" version="0.1.87"> 14311 Add GetErrorName. 14312 Add varargs warning to jvmtiExtensionEvent. 14313 Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent. 14314 Remove unused can_get_exception_info capability. 14315 Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction. 14316 Fix jvmtiExtensionFunctionInfo.func declared type. 14317 Extension function returns error code. 14318 Use new version numbering. 14319 </change> 14320 <change date="5 August 2003" version="0.2.88"> 14321 Remove the ClassUnload event. 14322 </change> 14323 <change date="8 August 2003" version="0.2.89"> 14324 Heap reference iterator callbacks return an enum that 14325 allows outgoing object references to be ignored. 14326 Allow JNIEnv as a param type to extension events/functions. 14327 </change> 14328 <change date="15 August 2003" version="0.2.90"> 14329 Fix a typo. 14330 </change> 14331 <change date="2 September 2003" version="0.2.91"> 14332 Remove all metadata functions: GetClassMetadata, 14333 GetFieldMetadata, and GetMethodMetadata. 14334 </change> 14335 <change date="1 October 2003" version="0.2.92"> 14336 Mark the functions Allocate. Deallocate, RawMonitor*, 14337 SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage 14338 as safe for use in heap callbacks and GC events. 14339 </change> 14340 <change date="24 November 2003" version="0.2.93"> 14341 Add pass through opaque user data pointer to heap iterate 14342 functions and callbacks. 14343 In the CompiledMethodUnload event, send the code address. 14344 Add GarbageCollectionOccurred event. 14345 Add constant pool reference kind. 14346 Mark the functions CreateRawMonitor and DestroyRawMonitor 14347 as safe for use in heap callbacks and GC events. 14348 Clarify: VMDeath, GetCurrentThreadCpuTimerInfo, 14349 GetThreadCpuTimerInfo, IterateOverReachableObjects, 14350 IterateOverObjectsReachableFromObject, GetTime and 14351 JVMTI_ERROR_NULL_POINTER. 14352 Add missing errors to: GenerateEvents and 14353 AddToBootstrapClassLoaderSearch. 14354 Fix description of ClassFileLoadHook name parameter. 14355 In heap callbacks and GC/ObjectFree events, specify 14356 that only explicitly allowed functions can be called. 14357 Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime, 14358 GetTimerInfo, and GetTime during callback. 14359 Allow calling SetTag/GetTag during the onload phase. 14360 SetEventNotificationMode, add: error attempted inappropriate 14361 thread level control. 14362 Remove jvmtiExceptionHandlerEntry. 14363 Fix handling of native methods on the stack -- 14364 location_ptr param of GetFrameLocation, remove 14365 JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation, 14366 jvmtiFrameInfo.location, and jlocation. 14367 Remove typo (from JVMPI) implying that the MonitorWaited 14368 event is sent on sleep. 14369 </change> 14370 <change date="25 November 2003" version="0.2.94"> 14371 Clarifications and typos. 14372 </change> 14373 <change date="3 December 2003" version="0.2.95"> 14374 Allow NULL user_data in heap iterators. 14375 </change> 14376 <change date="28 January 2004" version="0.2.97"> 14377 Add GetThreadState, deprecate GetThreadStatus. 14378 </change> 14379 <change date="29 January 2004" version="0.2.98"> 14380 INVALID_SLOT and TYPE_MISMATCH errors should be optional. 14381 </change> 14382 <change date="12 February 2004" version="0.2.102"> 14383 Remove MonitorContendedExit. 14384 Added JNIEnv parameter to VMObjectAlloc. 14385 Clarified definition of class_tag and referrer_index 14386 parameters to heap callbacks. 14387 </change> 14388 <change date="16 Febuary 2004" version="0.2.103"> 14389 Document JAVA_TOOL_OPTIONS. 14390 </change> 14391 <change date="17 Febuary 2004" version="0.2.105"> 14392 Divide start phase into primordial and start. 14393 Add VMStart event 14394 Change phase associations of functions and events. 14395 </change> 14396 <change date="18 Febuary 2004" version="0.3.6"> 14397 Elide deprecated GetThreadStatus. 14398 Bump minor version, subtract 100 from micro version 14399 </change> 14400 <change date="18 Febuary 2004" version="0.3.7"> 14401 Document that timer nanosecond values are unsigned. 14402 Clarify text having to do with native methods. 14403 </change> 14404 <change date="19 Febuary 2004" version="0.3.8"> 14405 Fix typos. 14406 Remove elided deprecated GetThreadStatus. 14407 </change> 14408 <change date="23 Febuary 2004" version="0.3.9"> 14409 Require NotifyFramePop to act on suspended threads. 14410 </change> 14411 <change date="24 Febuary 2004" version="0.3.10"> 14412 Add capabilities 14413 (<internallink id="jvmtiCapabilities.can_redefine_any_class" 14414 ><code>can_redefine_any_class</code></internallink> 14415 and 14416 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events" 14417 ><code>can_generate_all_class_hook_events</code></internallink>) 14418 and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>) 14419 which allow some classes to be unmodifiable. 14420 </change> 14421 <change date="28 Febuary 2004" version="0.3.11"> 14422 Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode. 14423 </change> 14424 <change date="8 March 2004" version="0.3.12"> 14425 Clarified CompiledMethodUnload so that it is clear the event 14426 may be posted after the class has been unloaded. 14427 </change> 14428 <change date="5 March 2004" version="0.3.13"> 14429 Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize. 14430 </change> 14431 <change date="13 March 2004" version="0.3.14"> 14432 Added guideline for the use of the JNI FindClass function in event 14433 callback functions. 14434 </change> 14435 <change date="15 March 2004" version="0.3.15"> 14436 Add GetAllStackTraces and GetThreadListStackTraces. 14437 </change> 14438 <change date="19 March 2004" version="0.3.16"> 14439 ClassLoad and ClassPrepare events can be posted during start phase. 14440 </change> 14441 <change date="25 March 2004" version="0.3.17"> 14442 Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable, 14443 GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes. 14444 </change> 14445 <change date="29 March 2004" version="0.3.18"> 14446 Return the timer kind in the timer information structure. 14447 </change> 14448 <change date="31 March 2004" version="0.3.19"> 14449 Spec clarifications: 14450 JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>. 14451 ForceGarbageCollection does not run finalizers. 14452 The context of the specification is the Java platform. 14453 Warn about early instrumentation. 14454 </change> 14455 <change date="1 April 2004" version="0.3.20"> 14456 Refinements to the above clarifications and 14457 Clarify that an error returned by Agent_OnLoad terminates the VM. 14458 </change> 14459 <change date="1 April 2004" version="0.3.21"> 14460 Array class creation does not generate a class load event. 14461 </change> 14462 <change date="7 April 2004" version="0.3.22"> 14463 Align thread state hierarchy more closely with java.lang.Thread.State. 14464 </change> 14465 <change date="12 April 2004" version="0.3.23"> 14466 Clarify the documentation of thread state. 14467 </change> 14468 <change date="19 April 2004" version="0.3.24"> 14469 Remove GarbageCollectionOccurred event -- can be done by agent. 14470 </change> 14471 <change date="22 April 2004" version="0.3.25"> 14472 Define "command-line option". 14473 </change> 14474 <change date="29 April 2004" version="0.3.26"> 14475 Describe the intended use of bytecode instrumentation. 14476 Fix description of extension event first parameter. 14477 </change> 14478 <change date="30 April 2004" version="0.3.27"> 14479 Clarification and typos. 14480 </change> 14481 <change date="18 May 2004" version="0.3.28"> 14482 Remove DataDumpRequest event. 14483 </change> 14484 <change date="18 May 2004" version="0.3.29"> 14485 Clarify RawMonitorWait with zero timeout. 14486 Clarify thread state after RunAgentThread. 14487 </change> 14488 <change date="24 May 2004" version="0.3.30"> 14489 Clean-up: fix bad/old links, etc. 14490 </change> 14491 <change date="30 May 2004" version="0.3.31"> 14492 Clarifications including: 14493 All character strings are modified UTF-8. 14494 Agent thread visibiity. 14495 Meaning of obsolete method version. 14496 Thread invoking heap callbacks, 14497 </change> 14498 <change date="1 June 2004" version="1.0.32"> 14499 Bump major.minor version numbers to "1.0". 14500 </change> 14501 <change date="2 June 2004" version="1.0.33"> 14502 Clarify interaction between ForceGarbageCollection 14503 and ObjectFree. 14504 </change> 14505 <change date="6 June 2004" version="1.0.34"> 14506 Restrict AddToBootstrapClassLoaderSearch and 14507 SetSystemProperty to the OnLoad phase only. 14508 </change> 14509 <change date="11 June 2004" version="1.0.35"> 14510 Fix typo in SetTag. 14511 </change> 14512 <change date="18 June 2004" version="1.0.36"> 14513 Fix trademarks. 14514 Add missing parameter in example GetThreadState usage. 14515 </change> 14516 <change date="4 August 2004" version="1.0.37"> 14517 Copyright updates. 14518 </change> 14519 <change date="5 November 2004" version="1.0.38"> 14520 Add missing function table layout. 14521 Add missing description of C++ member function format of functions. 14522 Clarify that name in CFLH can be NULL. 14523 Released as part of <tm>J2SE</tm> 5.0. 14524 </change> 14525 <change date="24 April 2005" version="1.1.47"> 14526 Bump major.minor version numbers to "1.1". 14527 Add ForceEarlyReturn* functions. 14528 Add GetOwnedMonitorStackDepthInfo function. 14529 Add GetCurrentThread function. 14530 Add "since" version marker. 14531 Add AddToSystemClassLoaderSearch. 14532 Allow AddToBootstrapClassLoaderSearch be used in live phase. 14533 Fix historic rubbish in the descriptions of the heap_object_callback 14534 parameter of IterateOverHeap and IterateOverInstancesOfClass functions; 14535 disallow NULL for this parameter. 14536 Clarify, correct and make consistent: wording about current thread, 14537 opaque frames and insufficient number of frames in PopFrame. 14538 Consistently use "current frame" rather than "topmost". 14539 Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal* 14540 by making them compatible with those in ForceEarlyReturn*. 14541 Many other clarifications and wording clean ups. 14542 </change> 14543 <change date="25 April 2005" version="1.1.48"> 14544 Add GetConstantPool. 14545 Switch references to the first edition of the VM Spec, to the seconds edition. 14546 </change> 14547 <change date="26 April 2005" version="1.1.49"> 14548 Clarify minor/major version order in GetConstantPool. 14549 </change> 14550 <change date="26 April 2005" version="1.1.50"> 14551 Add SetNativeMethodPrefix and SetNativeMethodPrefixes. 14552 Reassign GetOwnedMonitorStackDepthInfo to position 153. 14553 Break out Class Loader Search in its own documentation category. 14554 Deal with overly long lines in XML source. 14555 </change> 14556 <change date="29 April 2005" version="1.1.51"> 14557 Allow agents be started in the live phase. 14558 Added paragraph about deploying agents. 14559 </change> 14560 <change date="30 April 2005" version="1.1.52"> 14561 Add specification description to SetNativeMethodPrefix(es). 14562 Better define the conditions on GetConstantPool. 14563 </change> 14564 <change date="30 April 2005" version="1.1.53"> 14565 Break out the GetClassVersionNumber function from GetConstantPool. 14566 Clean-up the references to the VM Spec. 14567 </change> 14568 <change date="1 May 2005" version="1.1.54"> 14569 Allow SetNativeMethodPrefix(es) in any phase. 14570 Add clarifications about the impact of redefinition on GetConstantPool. 14571 </change> 14572 <change date="2 May 2005" version="1.1.56"> 14573 Various clarifications to SetNativeMethodPrefix(es). 14574 </change> 14575 <change date="2 May 2005" version="1.1.57"> 14576 Add missing performance warning to the method entry event. 14577 </change> 14578 <change date="5 May 2005" version="1.1.58"> 14579 Remove internal JVMDI support. 14580 </change> 14581 <change date="8 May 2005" version="1.1.59"> 14582 Add <functionlink id="RetransformClasses"/>. 14583 Revamp the bytecode instrumentation documentation. 14584 Change <functionlink id="IsMethodObsolete"/> to no longer 14585 require the can_redefine_classes capability. 14586 </change> 14587 <change date="11 May 2005" version="1.1.63"> 14588 Clarifications for retransformation. 14589 </change> 14590 <change date="11 May 2005" version="1.1.64"> 14591 Clarifications for retransformation, per review. 14592 Lock "retransformation (in)capable" at class load enable time. 14593 </change> 14594 <change date="4 June 2005" version="1.1.67"> 14595 Add new heap functionity which supports reporting primitive values, 14596 allows setting the referrer tag, and has more powerful filtering: 14597 FollowReferences, IterateThroughHeap, and their associated 14598 callbacks, structs, enums, and constants. 14599 </change> 14600 <change date="4 June 2005" version="1.1.68"> 14601 Clarification. 14602 </change> 14603 <change date="6 June 2005" version="1.1.69"> 14604 FollowReferences, IterateThroughHeap: Put callbacks in a struct; 14605 Add missing error codes; reduce bits in the visit control flags. 14606 </change> 14607 <change date="14 June 2005" version="1.1.70"> 14608 More on new heap functionity: spec clean-up per review. 14609 </change> 14610 <change date="15 June 2005" version="1.1.71"> 14611 More on new heap functionity: Rename old heap section to Heap (1.0). 14612 </change> 14613 <change date="21 June 2005" version="1.1.72"> 14614 Fix typos. 14615 </change> 14616 <change date="27 June 2005" version="1.1.73"> 14617 Make referrer info structure a union. 14618 </change> 14619 <change date="9 September 2005" version="1.1.74"> 14620 In new heap functions: 14621 Add missing superclass reference kind. 14622 Use a single scheme for computing field indexes. 14623 Remove outdated references to struct based referrer info. 14624 </change> 14625 <change date="12 September 2005" version="1.1.75"> 14626 Don't callback during FollowReferences on frivolous java.lang.Object superclass. 14627 </change> 14628 <change date="13 September 2005" version="1.1.76"> 14629 In string primitive callback, length now Unicode length. 14630 In array and string primitive callbacks, value now "const". 14631 Note possible compiler impacts on setting JNI function table. 14632 </change> 14633 <change date="13 September 2005" version="1.1.77"> 14634 GetClassVersionNumbers() and GetConstantPool() should return 14635 error on array or primitive class. 14636 </change> 14637 <change date="14 September 2005" version="1.1.78"> 14638 Grammar fixes. 14639 </change> 14640 <change date="26 September 2005" version="1.1.79"> 14641 Add IsModifiableClass query. 14642 </change> 14643 <change date="9 February 2006" version="1.1.81"> 14644 Add referrer_class_tag parameter to jvmtiHeapReferenceCallback. 14645 </change> 14646 <change date="13 February 2006" version="1.1.82"> 14647 Doc fixes: update can_redefine_any_class to include retransform. 14648 Clarify that exception events cover all Throwables. 14649 In GetStackTrace, no test is done for start_depth too big if start_depth is zero, 14650 Clarify fields reported in Primitive Field Callback -- static vs instance. 14651 Repair confusing names of heap types, including callback names. 14652 Require consistent usage of stack depth in the face of thread launch methods. 14653 Note incompatibility of <jvmti/> memory management with other systems. 14654 </change> 14655 <change date="14 February 2006" version="1.1.85"> 14656 Fix typos and missing renames. 14657 </change> 14658 <change date="13 March 2006" version="1.1.86"> 14659 Clarify that jmethodIDs and jfieldIDs can be saved. 14660 Clarify that Iterate Over Instances Of Class includes subclasses. 14661 </change> 14662 <change date="14 March 2006" version="1.1.87"> 14663 Better phrasing. 14664 </change> 14665 <change date="16 March 2006" version="1.1.88"> 14666 Match the referrer_index for static fields in Object Reference Callback 14667 with the Reference Implementation (and all other known implementations); 14668 that is, make it match the definition for instance fields. 14669 In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover 14670 an invalid thread in the list; and specify that not started threads 14671 return empty stacks. 14672 </change> 14673 <change date="17 March 2006" version="1.1.89"> 14674 Typo. 14675 </change> 14676 <change date="25 March 2006" version="1.1.90"> 14677 Typo. 14678 </change> 14679 <change date="6 April 2006" version="1.1.91"> 14680 Remove restrictions on AddToBootstrapClassLoaderSearch and 14681 AddToSystemClassLoaderSearch. 14682 </change> 14683 <change date="1 May 2006" version="1.1.93"> 14684 Changed spec to return -1 for monitor stack depth for the 14685 implementation which can not determine stack depth. 14686 </change> 14687 <change date="3 May 2006" version="1.1.94"> 14688 Corrections for readability and accuracy courtesy of Alan Pratt of IBM. 14689 List the object relationships reported in FollowReferences. 14690 </change> 14691 <change date="5 May 2006" version="1.1.95"> 14692 Clarify the object relationships reported in FollowReferences. 14693 </change> 14694 <change date="28 June 2006" version="1.1.98"> 14695 Clarify DisposeEnvironment; add warning. 14696 Fix typos in SetLocalXXX "retrieve" => "set". 14697 Clarify that native method prefixes must remain set while used. 14698 Clarify that exactly one Agent_OnXXX is called per agent. 14699 Clarify that library loading is independent from start-up. 14700 Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec. 14701 </change> 14702 <change date="31 July 2006" version="1.1.99"> 14703 Clarify the interaction between functions and exceptions. 14704 Clarify and give examples of field indices. 14705 Remove confusing "That is" sentence from MonitorWait and MonitorWaited events. 14706 Update links to point to Java 6. 14707 </change> 14708 <change date="6 August 2006" version="1.1.102"> 14709 Add ResourceExhaustedEvent. 14710 </change> 14711 <change date="11 October 2012" version="1.2.2"> 14712 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool. 14713 </change> 14714 <change date="19 June 2013" version="1.2.3"> 14715 Added support for statically linked agents. 14716 </change> 14717 <change date="13 October 2016" version="9.0.0"> 14718 Support for modules: 14719 - The majorversion is 9 now 14720 - The ClassFileLoadHook events are not sent during the primordial phase anymore. 14721 - Allow CompiledMethodLoad events at start phase 14722 - Add new capabilities: 14723 - can_generate_early_vmstart 14724 - can_generate_early_class_hook_events 14725 - Add new functions: 14726 - GetAllModules 14727 - AddModuleReads, AddModuleExports, AddModuleOpens, AddModuleUses, AddModuleProvides 14728 Clarified can_redefine_any_classes, can_retransform_any_classes and IsModifiableClass API to 14729 disallow some implementation defined classes. 14730 </change> 14731</changehistory> 14732 14733</specification> 14734<!-- Keep this comment at the end of the file 14735Local variables: 14736mode: sgml 14737sgml-omittag:t 14738sgml-shorttag:t 14739sgml-namecase-general:t 14740sgml-general-insert-case:lower 14741sgml-minimize-attributes:nil 14742sgml-always-quote-attributes:t 14743sgml-indent-step:2 14744sgml-indent-data:t 14745sgml-parent-document:nil 14746sgml-exposed-tags:nil 14747sgml-local-catalogs:nil 14748sgml-local-ecat-files:nil 14749End: 14750--> 14751