Mercurial > hg > truffle
annotate src/share/vm/prims/jvmti.xml @ 2100:b1a2afa37ec4
7003271: Hotspot should track cumulative Java heap bytes allocated on a per-thread basis
Summary: Track allocated bytes in Thread's, update on TLAB retirement and direct allocation in Eden and tenured, add JNI methods for ThreadMXBean.
Reviewed-by: coleenp, kvn, dholmes, ysr
| author | phh |
|---|---|
| date | Fri, 07 Jan 2011 10:42:32 -0500 |
| parents | 09b4dd4f152b |
| children | 7246a374a9f2 |
| rev | line source |
|---|---|
| 0 | 1 <?xml version="1.0" encoding="ISO-8859-1"?> |
| 2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?> | |
| 3 <!-- | |
|
2100
b1a2afa37ec4
7003271: Hotspot should track cumulative Java heap bytes allocated on a per-thread basis
phh
parents:
2019
diff
changeset
|
4 Copyright (c) 2002, 2011, Oracle and/or its affiliates. All rights reserved. |
| 0 | 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 | |
|
1552
c18cbe5936b8
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
0
diff
changeset
|
21 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
c18cbe5936b8
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
0
diff
changeset
|
22 or visit www.oracle.com if you need additional information or have any |
|
c18cbe5936b8
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
0
diff
changeset
|
23 questions. |
| 0 | 24 |
| 25 --> | |
| 26 | |
| 27 <!DOCTYPE specification [ | |
| 28 <!ELEMENT specification (title, intro*, functionsection, errorsection, | |
| 29 eventsection, datasection, issuessection, changehistory)> | |
| 30 <!ATTLIST specification label CDATA #REQUIRED | |
| 31 majorversion CDATA #REQUIRED | |
| 32 minorversion CDATA #REQUIRED | |
| 33 microversion CDATA #REQUIRED> | |
| 34 | |
| 35 <!ELEMENT title (#PCDATA|jvmti|tm)*> | |
| 36 <!ATTLIST title subtitle CDATA #REQUIRED> | |
| 37 | |
| 38 <!ELEMENT intro ANY> | |
| 39 <!ATTLIST intro id CDATA #IMPLIED | |
| 40 label CDATA ""> | |
| 41 | |
| 42 <!ELEMENT functionsection (intro*, category*)> | |
| 43 <!ATTLIST functionsection label CDATA #REQUIRED> | |
| 44 | |
| 45 <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*, | |
| 46 (function|callback|elide)*)> | |
| 47 <!ATTLIST category id CDATA #REQUIRED | |
| 48 label CDATA #REQUIRED> | |
| 49 | |
| 50 <!ELEMENT function (synopsis, typedef*, description?, origin, | |
| 51 (capabilities|eventcapabilities), | |
| 52 parameters, errors)> | |
| 53 <!ATTLIST function id CDATA #REQUIRED | |
| 54 num CDATA #REQUIRED | |
| 55 phase (onload|onloadOnly|start|live|any) #IMPLIED | |
| 56 callbacksafe (safe|unsafe) #IMPLIED | |
| 57 impl CDATA #IMPLIED | |
| 58 hide CDATA #IMPLIED | |
| 59 jkernel (yes|no) #IMPLIED | |
| 60 since CDATA "1.0"> | |
| 61 | |
| 62 <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject| | |
| 63 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void), | |
| 64 synopsis, description?, parameters)> | |
| 65 <!ATTLIST callback id CDATA #REQUIRED | |
| 66 since CDATA "1.0"> | |
| 67 | |
| 68 <!ELEMENT synopsis (#PCDATA|jvmti)*> | |
| 69 | |
| 70 <!ELEMENT typedef (description?, field*)> | |
| 71 <!ATTLIST typedef id CDATA #REQUIRED | |
| 72 label CDATA #REQUIRED | |
| 73 since CDATA "1.0"> | |
| 74 | |
| 75 <!ELEMENT uniontypedef (description?, field*)> | |
| 76 <!ATTLIST uniontypedef id CDATA #REQUIRED | |
| 77 label CDATA #REQUIRED | |
| 78 since CDATA "1.0"> | |
| 79 | |
| 80 <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject| | |
| 81 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct), | |
| 82 description)> | |
| 83 <!ATTLIST field id CDATA #REQUIRED> | |
| 84 | |
| 85 <!ELEMENT capabilitiestypedef (description?, capabilityfield*)> | |
| 86 <!ATTLIST capabilitiestypedef id CDATA #REQUIRED | |
| 87 label CDATA #REQUIRED> | |
| 88 | |
| 89 <!ELEMENT capabilityfield (description)> | |
| 90 <!ATTLIST capabilityfield id CDATA #REQUIRED | |
| 91 disp1 CDATA "" | |
| 92 disp2 CDATA "" | |
| 93 since CDATA "1.0"> | |
| 94 | |
| 95 <!ELEMENT description ANY> | |
| 96 | |
| 97 <!ELEMENT capabilities (required*, capability*)> | |
| 98 | |
| 99 <!ELEMENT eventcapabilities EMPTY> | |
| 100 | |
| 101 <!ELEMENT required ANY> | |
| 102 <!ATTLIST required id CDATA #REQUIRED> | |
| 103 | |
| 104 <!ELEMENT capability ANY> | |
| 105 <!ATTLIST capability id CDATA #REQUIRED> | |
| 106 | |
| 107 <!ELEMENT parameters (param*)> | |
| 108 | |
| 109 <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject| | |
| 110 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype| | |
| 111 outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf), | |
| 112 description)> | |
| 113 <!ATTLIST param id CDATA #REQUIRED> | |
| 114 | |
| 115 <!ELEMENT jmethodID EMPTY> | |
| 116 <!ATTLIST jmethodID class CDATA #IMPLIED | |
| 117 native CDATA #IMPLIED> | |
| 118 | |
| 119 <!ELEMENT jfieldID EMPTY> | |
| 120 <!ATTLIST jfieldID class CDATA #IMPLIED> | |
| 121 | |
| 122 <!ELEMENT jclass EMPTY> | |
| 123 <!ATTLIST jclass method CDATA #IMPLIED | |
| 124 field CDATA #IMPLIED> | |
| 125 | |
| 126 <!ELEMENT jframeID EMPTY> | |
| 127 <!ATTLIST jframeID thread CDATA #IMPLIED> | |
| 128 | |
| 129 <!ELEMENT jrawMonitorID EMPTY> | |
| 130 | |
| 131 <!ELEMENT jthread EMPTY> | |
| 132 <!ATTLIST jthread started CDATA #IMPLIED | |
| 133 null CDATA #IMPLIED | |
| 134 frame CDATA #IMPLIED | |
| 135 impl CDATA #IMPLIED> | |
| 136 | |
| 137 <!ELEMENT varargs EMPTY> | |
| 138 | |
| 139 <!ELEMENT jthreadGroup EMPTY> | |
| 140 <!ELEMENT jobject EMPTY> | |
| 141 <!ELEMENT jvalue EMPTY> | |
| 142 <!ELEMENT jchar EMPTY> | |
| 143 <!ELEMENT jint EMPTY> | |
| 144 <!ATTLIST jint min CDATA #IMPLIED> | |
| 145 <!ELEMENT jlong EMPTY> | |
| 146 <!ELEMENT jfloat EMPTY> | |
| 147 <!ELEMENT jdouble EMPTY> | |
| 148 <!ELEMENT jlocation EMPTY> | |
| 149 <!ELEMENT jboolean EMPTY> | |
| 150 <!ELEMENT char EMPTY> | |
| 151 <!ELEMENT uchar EMPTY> | |
| 152 <!ELEMENT size_t EMPTY> | |
| 153 <!ELEMENT void EMPTY> | |
| 154 <!ELEMENT enum (#PCDATA)*> | |
| 155 <!ELEMENT struct (#PCDATA)*> | |
| 156 | |
| 157 <!ELEMENT nullok ANY> | |
| 158 | |
| 159 <!ELEMENT ptrtype ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
| 160 jthreadGroup|jobject|jvalue), nullok?)> | |
| 161 | |
| 162 <!ELEMENT outptr ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
| 163 jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble| | |
| 164 jlocation|jboolean|char|uchar|size_t|void), nullok?)> | |
| 165 | |
| 166 <!ELEMENT allocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
| 167 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| | |
| 168 jlocation|jboolean|char|uchar|size_t|void), nullok?)> | |
| 169 <!ATTLIST allocbuf incount CDATA #IMPLIED | |
| 170 outcount CDATA #IMPLIED> | |
| 171 | |
| 172 <!ELEMENT allocallocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
| 173 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| | |
| 174 jlocation|jboolean|char|uchar|size_t|void), nullok?)> | |
| 175 <!ATTLIST allocallocbuf incount CDATA #IMPLIED | |
| 176 outcount CDATA #IMPLIED> | |
| 177 | |
| 178 <!ELEMENT inptr (struct, nullok?)> | |
| 179 | |
| 180 <!ELEMENT inbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
| 181 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| | |
| 182 jlocation|jboolean|char|uchar|size_t|void), nullok?)> | |
| 183 <!ATTLIST inbuf incount CDATA #IMPLIED> | |
| 184 | |
| 185 <!ELEMENT outbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
| 186 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| | |
| 187 jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)> | |
| 188 <!ATTLIST outbuf incount CDATA #IMPLIED | |
| 189 outcount CDATA #IMPLIED> | |
| 190 | |
| 191 <!ELEMENT vmbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
| 192 jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble| | |
| 193 jlocation|jboolean|char|uchar|size_t|void), nullok?)> | |
| 194 <!ATTLIST vmbuf incount CDATA #IMPLIED | |
| 195 outcount CDATA #IMPLIED> | |
| 196 | |
| 197 <!ELEMENT agentbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
| 198 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| | |
| 199 jlocation|jboolean|char|uchar|size_t|void), nullok?)> | |
| 200 <!ATTLIST agentbuf incount CDATA #IMPLIED | |
| 201 outcount CDATA #IMPLIED> | |
| 202 | |
| 203 <!ELEMENT allocfieldbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
| 204 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| | |
| 205 jlocation|jboolean|char|uchar|size_t|void))> | |
| 206 <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED> | |
| 207 | |
| 208 <!ELEMENT errors (error*)> | |
| 209 | |
| 210 <!ELEMENT error ANY> | |
| 211 <!ATTLIST error id CDATA #REQUIRED> | |
| 212 | |
| 213 <!ELEMENT errorsection (intro*, errorcategory*)> | |
| 214 <!ATTLIST errorsection label CDATA #REQUIRED> | |
| 215 | |
| 216 <!ELEMENT errorcategory (intro*, errorid*)> | |
| 217 <!ATTLIST errorcategory id CDATA #REQUIRED | |
| 218 label CDATA #REQUIRED> | |
| 219 | |
| 220 <!ELEMENT errorid ANY> | |
| 221 <!ATTLIST errorid id CDATA #REQUIRED | |
| 222 num CDATA #REQUIRED> | |
| 223 | |
| 224 <!ELEMENT datasection (intro*, basetypes*)> | |
| 225 | |
| 226 <!ELEMENT basetypes (intro*, basetype*)> | |
| 227 <!ATTLIST basetypes id CDATA #REQUIRED | |
| 228 label CDATA #REQUIRED> | |
| 229 | |
| 230 <!ELEMENT basetype (definition?,description)> | |
| 231 <!ATTLIST basetype id CDATA #REQUIRED> | |
| 232 | |
| 233 <!ELEMENT definition (#PCDATA|jvmti)*> | |
| 234 | |
| 235 <!ELEMENT eventsection (intro*, (event|elide)*)> | |
| 236 <!ATTLIST eventsection label CDATA #REQUIRED> | |
| 237 | |
| 238 <!ELEMENT event (description, origin, typedef*, capabilities, parameters)> | |
| 239 <!ATTLIST event id CDATA #REQUIRED | |
| 240 label CDATA #REQUIRED | |
| 241 const CDATA #REQUIRED | |
| 242 num CDATA #REQUIRED | |
| 243 phase (onload|start|live|any) #IMPLIED | |
| 244 filtered (thread|global) #IMPLIED | |
| 245 since CDATA "1.0"> | |
| 246 | |
| 247 <!ELEMENT issuessection (intro*)> | |
| 248 <!ATTLIST issuessection label CDATA #REQUIRED> | |
| 249 | |
| 250 <!ELEMENT changehistory (intro*, change*)> | |
| 251 <!ATTLIST changehistory update CDATA #REQUIRED | |
| 252 id CDATA #REQUIRED> | |
| 253 | |
| 254 <!ELEMENT change ANY> | |
| 255 <!ATTLIST change date CDATA #REQUIRED | |
| 256 version CDATA #IMPLIED> | |
| 257 | |
| 258 <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*> | |
| 259 <!ATTLIST functionlink id CDATA #REQUIRED> | |
| 260 | |
| 261 <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*> | |
| 262 <!ATTLIST datalink id CDATA #REQUIRED> | |
| 263 | |
| 264 <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*> | |
| 265 <!ATTLIST typelink id CDATA #REQUIRED> | |
| 266 | |
| 267 <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*> | |
| 268 <!ATTLIST fieldlink id CDATA #REQUIRED | |
| 269 struct CDATA #REQUIRED> | |
| 270 | |
| 271 <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*> | |
| 272 <!ATTLIST paramlink id CDATA #REQUIRED> | |
| 273 | |
| 274 <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*> | |
| 275 <!ATTLIST eventlink id CDATA #REQUIRED> | |
| 276 | |
| 277 <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*> | |
| 278 <!ATTLIST errorlink id CDATA #REQUIRED> | |
| 279 | |
| 280 <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*> | |
| 281 <!ATTLIST externallink id CDATA #REQUIRED> | |
| 282 | |
| 283 <!ELEMENT vmspeclink EMPTY> | |
| 284 <!ATTLIST vmspeclink id CDATA #IMPLIED> | |
| 285 <!ATTLIST vmspeclink name CDATA #IMPLIED> | |
| 286 <!ATTLIST vmspeclink preposition CDATA #IMPLIED> | |
| 287 | |
| 288 <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*> | |
| 289 <!ATTLIST internallink id CDATA #REQUIRED> | |
| 290 | |
| 291 <!ELEMENT functionphaselist EMPTY> | |
| 292 <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED> | |
| 293 | |
| 294 <!ELEMENT eventphaselist EMPTY> | |
| 295 <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED> | |
| 296 | |
| 297 <!ELEMENT issue ANY> | |
| 298 | |
| 299 <!ELEMENT rationale ANY> | |
| 300 | |
| 301 <!ELEMENT todo ANY> | |
| 302 | |
| 303 <!ELEMENT origin (#PCDATA)*> | |
| 304 | |
| 305 <!ELEMENT elide (intro|function|callback|event)*> | |
| 306 <!ATTLIST elide why CDATA #IMPLIED> | |
| 307 | |
| 308 <!ELEMENT constants (constant*)> | |
| 309 <!ATTLIST constants id CDATA #REQUIRED | |
| 310 label CDATA #REQUIRED | |
| 311 kind (enum|bits|const) #REQUIRED | |
| 312 since CDATA "1.0"> | |
| 313 | |
| 314 <!ELEMENT constant ANY> | |
| 315 <!ATTLIST constant id CDATA #REQUIRED | |
| 316 num CDATA #REQUIRED> | |
| 317 | |
| 318 <!ELEMENT tm (#PCDATA)> | |
| 319 | |
| 320 <!ELEMENT i (#PCDATA|jvmti|tm)*> | |
| 321 | |
| 322 <!ELEMENT b (#PCDATA|jvmti|code)*> | |
| 323 | |
| 324 <!ELEMENT code (#PCDATA|space)*> | |
| 325 | |
| 326 <!ELEMENT pre ANY> | |
| 327 | |
| 328 <!ELEMENT space EMPTY> | |
| 329 | |
| 330 <!ELEMENT jvmti EMPTY> | |
| 331 | |
| 332 <!ELEMENT example (#PCDATA|i)*> | |
| 333 | |
| 334 <!ELEMENT br EMPTY> | |
| 335 | |
| 336 <!ELEMENT p EMPTY> | |
| 337 | |
| 338 <!ELEMENT dl (dt|dd)+> | |
| 339 | |
| 340 <!ELEMENT dd ANY> | |
| 341 | |
| 342 <!ELEMENT dt (#PCDATA|jvmti|code|i|b)*> | |
| 343 | |
| 344 <!ELEMENT table (tr)+> | |
| 345 | |
| 346 <!ELEMENT tr (td|th)*> | |
| 347 | |
| 348 <!ELEMENT td ANY> | |
| 349 <!ATTLIST td align (left|right|center) "center"> | |
| 350 | |
| 351 <!ELEMENT th ANY> | |
| 352 <!ATTLIST th align (left|right|center) "center"> | |
| 353 | |
| 354 <!ELEMENT ul (li)+> | |
| 355 <!ATTLIST ul type (disc|circle|square) "disc"> | |
| 356 | |
| 357 <!ELEMENT li ANY> | |
| 358 ]> | |
| 359 | |
| 360 <specification label="JVM(TM) Tool Interface" | |
| 361 majorversion="1" | |
| 1988 | 362 minorversion="2" |
| 363 microversion="1"> | |
| 0 | 364 <title subtitle="Version"> |
| 365 <tm>JVM</tm> Tool Interface | |
| 366 </title> | |
| 367 | |
| 368 <intro id="whatIs" label="What is the JVM Tool Interface?"> | |
| 369 The <tm>JVM</tm> Tool Interface (<jvmti/>) | |
| 370 is a programming interface used by development and monitoring tools. | |
| 371 It provides both a way to inspect the state and | |
| 372 to control the execution of applications running in the | |
| 373 <tm>Java</tm> virtual machine (VM). | |
| 374 <p/> | |
| 375 <jvmti/> is intended to provide a VM interface for the full breadth of tools | |
| 376 that need access to VM state, including but not limited to: profiling, | |
| 377 debugging, monitoring, thread analysis, and coverage analysis tools. | |
| 378 <p/> | |
| 379 <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual | |
| 380 machine. | |
| 381 <p/> | |
| 382 <jvmti/> is a two-way interface. | |
| 383 A client of <jvmti/>, hereafter called an <i>agent</i>, | |
| 384 can be notified of | |
| 385 interesting occurrences through <internallink id="EventSection">events</internallink>. | |
| 386 <jvmti/> | |
| 387 can query and control the application through many | |
| 388 <internallink id="FunctionSection">functions</internallink>, | |
| 389 either in response to events or | |
| 390 independent of them. | |
| 391 <p/> | |
| 392 Agents run in the same process with and communicate directly with | |
| 393 the virtual machine executing | |
| 394 the application being examined. This communication is | |
| 395 through a native interface (<jvmti/>). The native in-process interface allows | |
| 396 maximal control with minimal intrusion on the part of a tool. | |
| 397 Typically, agents are relatively compact. They can be controlled | |
| 398 by a separate process which implements the bulk of a tool's | |
| 399 function without interfering with the target application's normal execution. | |
| 400 </intro> | |
| 401 | |
| 402 <intro id="architecture" label="Architecture"> | |
| 403 Tools can be written directly to <jvmti/> or indirectly | |
| 404 through higher level interfaces. | |
| 405 The Java Platform Debugger Architecture includes <jvmti/>, but also | |
| 406 contains higher-level, out-of-process debugger interfaces. The higher-level | |
| 407 interfaces are more appropriate than <jvmti/> for many tools. | |
| 408 For more information on the Java Platform Debugger Architecture, | |
| 409 see the | |
| 410 <externallink id="http://java.sun.com/products/jpda/">Java | |
| 411 Platform Debugger Architecture website</externallink>. | |
| 412 </intro> | |
| 413 | |
| 414 <intro id="writingAgents" label="Writing Agents"> | |
| 415 Agents can be written in any native language that supports C | |
| 416 language calling conventions and C or C++ | |
| 417 definitions. | |
| 418 <p/> | |
| 419 The function, event, data type, and constant definitions needed for | |
| 420 using <jvmti/> are defined in the include file <code>jvmti.h</code>. | |
| 421 To use these definitions add the <tm>J2SE</tm> include directory | |
| 422 to your include path and add | |
| 423 <example> | |
| 424 #include <jvmti.h> | |
| 425 </example> | |
| 426 to your source code. | |
| 427 </intro> | |
| 428 | |
| 429 <intro id="deployingAgents" label="Deploying Agents"> | |
| 430 An agent is deployed in a platform specific manner but is typically the | |
| 431 platform equivalent of a dynamic library. On the <tm>Windows</tm> operating | |
| 432 system, for example, an agent library is a "Dynamic Linked Library" (DLL). | |
| 433 On the <tm>Solaris</tm> Operating Environment, an agent library is a shared | |
| 434 object (<code>.so</code> file). | |
| 435 <p/> | |
| 436 An agent may be started at VM startup by specifying the agent library | |
| 437 name using a <internallink id="starting">command line option</internallink>. | |
| 438 Some implementations may support a mechanism to <internallink id="onattach"> | |
| 439 start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>. | |
| 440 The details of how this is initiated are implementation specific. | |
| 441 </intro> | |
| 442 | |
| 443 <intro id="starting" label="Agent Command Line Options"> | |
| 444 The term "command-line option" is used below to | |
| 445 mean options supplied in the <code>JavaVMInitArgs</code> argument | |
| 446 to the <code>JNI_CreateJavaVM</code> function of the JNI | |
| 447 Invocation API. | |
| 448 <p/> | |
| 449 One of the two following | |
| 450 command-line options is used on VM startup to | |
| 451 properly load and run agents. | |
| 452 These arguments identify the library containing | |
| 453 the agent as well as an options | |
| 454 string to be passed in at startup. | |
| 455 <dl> | |
| 456 <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt> | |
| 457 <dd> | |
| 458 The name following <code>-agentlib:</code> is the name of the | |
| 459 library to load. Lookup of the library, both its full name and location, | |
| 460 proceeds in a platform-specific manner. | |
| 461 Typically, the <i><agent-lib-name></i> is expanded to an | |
| 462 operating system specific file name. | |
| 463 The <i><options></i> will be passed to the agent on start-up. | |
| 464 For example, if the option | |
| 465 <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to | |
| 466 load the shared library <code>foo.dll</code> from the system <code>PATH</code> | |
| 467 under <tm>Windows</tm> or <code>libfoo.so</code> from the | |
| 468 <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment. | |
| 469 </dd> | |
| 470 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt> | |
| 471 <dd> | |
| 472 The path following <code>-agentpath:</code> is the absolute path from which | |
| 473 to load the library. | |
| 474 No library name expansion will occur. | |
| 475 The <i><options></i> will be passed to the agent on start-up. | |
| 476 For example, if the option | |
| 477 <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to | |
| 478 load the shared library <code>c:\myLibs\foo.dll</code>. | |
| 479 </dd> | |
| 480 </dl> | |
| 481 The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink> | |
| 482 in the library will be invoked. | |
| 483 <p/> | |
| 484 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code> | |
| 485 will be searched for JNI native method implementations to facilitate the | |
| 486 use of Java programming language code in tools, as is needed for | |
| 487 <internallink id="bci">bytecode instrumentation</internallink>. | |
| 488 <p/> | |
| 489 The agent libraries will be searched after all other libraries have been | |
| 490 searched (agents wishing to override or intercept the native method | |
| 491 implementations of non-agent methods can use the | |
| 492 <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>). | |
| 493 <p/> | |
| 494 These switches do the above and nothing more - they do not change the | |
| 495 state of the VM or <jvmti/>. No command line options are needed | |
| 496 to enable <jvmti/> | |
| 497 or aspects of <jvmti/>, this is handled programmatically | |
| 498 by the use of | |
| 499 <internallink id="capability">capabilities</internallink>. | |
| 500 </intro> | |
| 501 | |
| 502 <intro id="startup" label="Agent Start-Up"> | |
| 503 The VM starts each agent by invoking a start-up function. | |
| 504 If the agent is started in the <code>OnLoad</code> | |
| 505 <functionlink id="GetPhase">phase</functionlink> the function | |
| 506 <internallink id="onload"><code>Agent_OnLoad</code></internallink> | |
| 507 will be invoked. | |
| 508 If the agent is started in the live | |
| 509 <functionlink id="GetPhase">phase</functionlink> the function | |
| 510 <internallink id="onattach"><code>Agent_OnAttach</code></internallink> | |
| 511 will be invoked. | |
| 512 Exactly one call to a start-up function is made per agent. | |
| 513 </intro> | |
| 514 | |
| 515 <intro id="onload" label="Agent Start-Up (OnLoad phase)"> | |
| 516 If an agent is started during the <code>OnLoad</code> phase then its | |
| 517 agent library must export a start-up function with the following prototype: | |
| 518 <example> | |
| 519 JNIEXPORT jint JNICALL | |
| 520 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example> | |
| 521 The VM will start the agent by calling this function. | |
| 522 It will be called early enough in VM initialization that: | |
| 523 <ul> | |
| 524 <li><functionlink id="SetSystemProperty">system properties</functionlink> | |
| 525 may be set before they have been used in the start-up of the VM</li> | |
| 526 <li>the full set of | |
| 527 <internallink id="capability">capabilities</internallink> | |
| 528 is still available (note that capabilities that configure the VM | |
| 529 may only be available at this time--see the | |
| 530 <internallink id="capability">Capability function section</internallink>)</li> | |
| 531 <li>no bytecodes have executed</li> | |
| 532 <li>no classes have been loaded</li> | |
| 533 <li>no objects have been created</li> | |
| 534 </ul> | |
| 535 <p/> | |
| 536 The VM will call the <code>Agent_OnLoad</code> function with | |
| 537 <i><options></i> as the second argument - | |
| 538 that is, using the command-line option examples, | |
| 539 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> | |
| 540 argument of <code>Agent_OnLoad</code>. | |
| 541 The <code>options</code> argument is encoded as a | |
| 542 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 543 If <i>=<options></i> is not specified, | |
| 544 a zero length string is passed to <code>options</code>. | |
| 545 The lifespan of the <code>options</code> string is the <code>Agent_OnLoad</code> | |
| 546 call. If needed beyond this time the string or parts of the string must | |
| 547 be copied. | |
| 548 The period between when <code>Agent_OnLoad</code> is called and when it | |
| 549 returns is called the <i>OnLoad phase</i>. | |
| 550 Since the VM is not initialized during the OnLoad | |
| 551 <functionlink id="GetPhase">phase</functionlink>, | |
| 552 the set of allowed operations | |
| 553 inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the | |
| 554 functionality available at this time). | |
| 555 The agent can safely process the options and set | |
| 556 event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once | |
| 557 the VM initialization event is received | |
| 558 (that is, the <eventlink id="VMInit">VMInit</eventlink> | |
| 559 callback is invoked), the agent | |
| 560 can complete its initialization. | |
| 561 <rationale> | |
| 562 Early startup is required so that agents can set the desired capabilities, | |
| 563 many of which must be set before the VM is initialized. | |
| 564 In JVMDI, the -Xdebug command-line option provided | |
| 565 very coarse-grain control of capabilities. | |
| 566 JVMPI implementations use various tricks to provide a single "JVMPI on" switch. | |
| 567 No reasonable command-line | |
| 568 option could provide the fine-grain of control required to balance needed capabilities vs | |
| 569 performance impact. | |
| 570 Early startup is also needed so that agents can control the execution | |
| 571 environment - modifying the file system and system properties to install | |
| 572 their functionality. | |
| 573 </rationale> | |
| 574 <p/> | |
| 575 The return value from <code>Agent_OnLoad</code> is used to indicate an error. | |
| 576 Any value other than zero indicates an error and causes termination of the VM. | |
| 577 </intro> | |
| 578 | |
| 579 <intro id="onattach" label="Agent Start-Up (Live phase)"> | |
| 580 A VM may support a mechanism that allows agents to be started in the VM during the live | |
| 581 <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported, | |
| 582 are implementation specific. For example, a tool may use some platform specific mechanism, | |
| 583 or implementation specific API, to attach to the running VM, and request it start a given | |
| 584 agent. | |
| 585 <p/> | |
| 586 If an agent is started during the live phase then its agent library | |
| 587 must export a start-up function | |
| 588 with the following prototype: | |
| 589 <example> | |
| 590 JNIEXPORT jint JNICALL | |
| 591 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example> | |
| 592 <p/> | |
| 593 The VM will start the agent by calling this function. | |
| 594 It will be called in the context of a thread | |
| 595 that is attached to the VM. The first argument <i><vm></i> is the Java VM. | |
| 596 The <i><options></i> argument is the startup options provided to the agent. | |
| 597 <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8 | |
| 598 </internallink> string. | |
| 599 If startup options were not provided, a zero length string is passed to | |
| 600 <code>options</code>. The lifespan of the <code>options</code> string is the | |
| 601 <code>Agent_OnAttach</code> call. If needed beyond this time the string or parts of | |
| 602 the string must be copied. | |
| 603 <p/> | |
| 604 Note that some <internallink id="capability">capabilities</internallink> | |
| 605 may not be available in the live phase. | |
| 606 <p/> | |
| 607 The <code>Agent_OnAttach</code> function initializes the agent and returns a value | |
| 608 to the VM to indicate if an error occurred. Any value other than zero indicates an error. | |
| 609 An error does not cause the VM to terminate. Instead the VM ignores the error, or takes | |
| 610 some implementation specific action -- for example it might print an error to standard error, | |
| 611 or record the error in a system log. | |
| 612 </intro> | |
| 613 | |
| 614 <intro id="onunload" label="Agent Shutdown"> | |
| 615 The library may optionally export a | |
| 616 shutdown function with the following prototype: | |
| 617 <example> | |
| 618 JNIEXPORT void JNICALL | |
| 619 Agent_OnUnload(JavaVM *vm)</example> | |
| 620 This function will be called by the VM when the library is about to be unloaded. | |
| 621 The library will be unloaded and this function will be called if some platform specific | |
| 622 mechanism causes the unload (an unload mechanism is not specified in this document) | |
| 623 or the library is (in effect) unloaded by the termination of the VM whether through | |
| 624 normal termination or VM failure, including start-up failure. | |
| 625 Uncontrolled shutdown is, of couse, an exception to this rule. | |
| 626 Note the distinction between this function and the | |
| 627 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event | |
| 628 to be sent, the VM must have run at least to the point of initialization and a valid | |
| 629 <jvmti/> environment must exist which has set a callback for VMDeath | |
| 630 and enabled the event | |
| 631 None of these are required for <code>Agent_OnUnload</code> and this function | |
| 632 is also called if the library is unloaded for other reasons. | |
| 633 In the case that a VM Death event is sent, it will be sent before this | |
| 634 function is called (assuming this function is called due to VM termination). | |
| 635 This function can be used to clean-up resources allocated by the agent. | |
| 636 </intro> | |
| 637 | |
| 638 <intro id="tooloptions" label="JAVA_TOOL_OPTIONS"> | |
| 639 Since the command-line cannot always be accessed or modified, for example in embedded VMs | |
| 640 or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is | |
| 641 provided so that agents may be launched in these cases. | |
| 642 <p/> | |
| 643 Platforms which support environment variables or other named strings, may support the | |
| 644 <code>JAVA_TOOL_OPTIONS</code> variable. This variable will be broken into options at white-space | |
| 645 boundaries. White-space characters include space, tab, carriage-return, new-line, | |
| 646 vertical-tab, and form-feed. Sequences of white-space characters are considered | |
| 647 equivalent to a single white-space character. No white-space is included in the options | |
| 648 unless quoted. Quoting is as follows: | |
| 649 <ul> | |
| 650 <li>All characters enclosed between a pair of single quote marks (''), except a single | |
| 651 quote, are quoted.</li> | |
| 652 <li>Double quote characters have no special meaning inside a pair of single quote marks.</li> | |
| 653 <li>All characters enclosed between a pair of double quote marks (""), except a double | |
| 654 quote, are quoted.</li> | |
| 655 <li>Single quote characters have no special meaning inside a pair of double quote marks.</li> | |
| 656 <li>A quoted part can start or end anywhere in the variable.</li> | |
| 657 <li>White-space characters have no special meaning when quoted -- they are included in | |
| 658 the option like any other character and do not mark white-space boundaries.</li> | |
| 659 <li>The pair of quote marks is not included in the option.</li> | |
| 660 </ul> | |
| 661 <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied | |
| 662 in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is | |
| 663 a concern; for example, the Reference Implementation disables this feature on Unix systems when | |
| 664 the effective user or group ID differs from the real ID. | |
| 665 This feature is intended to support the initialization of tools -- specifically including the | |
| 666 launching of native or Java programming language agents. Multiple tools may wish to use this | |
| 667 feature, so the variable should not be overwritten, instead, options should be appended to | |
| 668 the variable. Note that since the variable is processed at the time of the JNI Invocation | |
| 669 API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled. | |
| 670 </intro> | |
| 671 | |
| 672 <intro id="environments" label="Environments"> | |
| 673 The <jvmti/> specification supports the use of multiple simultaneous | |
| 674 <jvmti/> agents. | |
| 675 Each agent has its own <jvmti/> environment. | |
| 676 That is, the <jvmti/> state is | |
| 677 separate for each agent - changes to one environment do not affect the | |
| 678 others. The state of a <jvmti/> | |
| 679 environment includes: | |
| 680 <ul> | |
| 681 <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li> | |
| 682 <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li> | |
| 683 <li><internallink id="capability">the capabilities</internallink></li> | |
| 684 <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li> | |
| 685 </ul> | |
| 686 Although their <jvmti/> state | |
| 687 is separate, agents inspect and modify the shared state | |
| 688 of the VM, they also share the native environment in which they execute. | |
| 689 As such, an agent can perturb the results of other agents or cause them | |
| 690 to fail. It is the responsibility of the agent writer to specify the level | |
| 691 of compatibility with other agents. <jvmti/> implementations are not capable | |
| 692 of preventing destructive interactions between agents. Techniques to reduce | |
| 693 the likelihood of these occurrences are beyond the scope of this document. | |
| 694 <p/> | |
| 695 An agent creates a <jvmti/> environment | |
| 696 by passing a <jvmti/> version | |
| 697 as the interface ID to the JNI Invocation API function | |
| 698 <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><code>GetEnv</code></externallink>. | |
| 699 See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink> | |
| 700 for more details on the creation and use of | |
| 701 <jvmti/> environments. | |
| 702 Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from | |
| 703 <internallink id="onload"><code>Agent_OnLoad</code></internallink>. | |
| 704 </intro> | |
| 705 | |
| 706 <intro id="bci" label="Bytecode Instrumentation"> | |
| 707 This interface does not include some events that one might expect in an interface with | |
| 708 profiling support. Some examples include object allocation events and full speed | |
| 709 method enter and exit events. The interface instead provides support for | |
| 710 <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine | |
| 711 bytecode instructions which comprise the target program. Typically, these alterations | |
| 712 are to add "events" to the code of a method - for example, to add, at the beginning of a method, | |
| 713 a call to <code>MyProfiler.methodEntered()</code>. | |
| 714 Since the changes are purely additive, they do not modify application | |
| 715 state or behavior. | |
| 716 Because the inserted agent code is standard bytecodes, the VM can run at full speed, | |
| 717 optimizing not only the target program but also the instrumentation. If the | |
| 718 instrumentation does not involve switching from bytecode execution, no expensive | |
| 719 state transitions are needed. The result is high performance events. | |
| 720 This approach also provides complete control to the agent: instrumentation can be | |
| 721 restricted to "interesting" portions of the code (e.g., the end user's code) and | |
| 722 can be conditional. Instrumentation can run entirely in Java programming language | |
| 723 code or can call into the native agent. Instrumentation can simply maintain | |
| 724 counters or can statistically sample events. | |
| 725 <p/> | |
| 726 Instrumentation can be inserted in one of three ways: | |
| 727 <ul> | |
| 728 <li> | |
| 729 Static Instrumentation: The class file is instrumented before it | |
| 730 is loaded into the VM - for example, by creating a duplicate directory of | |
| 731 <code>*.class</code> files which have been modified to add the instrumentation. | |
| 732 This method is extremely awkward and, in general, an agent cannot know | |
| 733 the origin of the class files which will be loaded. | |
| 734 </li> | |
| 735 <li> | |
| 736 Load-Time Instrumentation: When a class file is loaded by the VM, the raw | |
| 737 bytes of the class file are sent for instrumentation to the agent. | |
| 738 The <eventlink id="ClassFileLoadHook"/> | |
| 739 event, triggered by the class load, | |
| 740 provides this functionality. This mechanism provides efficient | |
| 741 and complete access to one-time instrumentation. | |
| 742 </li> | |
| 743 <li> | |
| 744 Dynamic Instrumentation: A class which is already loaded (and possibly | |
| 745 even running) is modified. This optional feature is provided by the | |
| 746 <eventlink id="ClassFileLoadHook"/> event, triggered by calling the | |
| 747 <functionlink id="RetransformClasses"/> function. | |
| 748 Classes can be modified multiple times and can be returned to their | |
| 749 original state. | |
| 750 The mechanism allows instrumentation which changes during the | |
| 751 course of execution. | |
| 752 </li> | |
| 753 </ul> | |
| 754 <p/> | |
| 755 The class modification functionality provided in this interface | |
| 756 is intended to provide a mechanism for instrumentation | |
| 757 (the <eventlink id="ClassFileLoadHook"/> event | |
| 758 and the <functionlink id="RetransformClasses"/> function) | |
| 759 and, during development, for fix-and-continue debugging | |
| 760 (the <functionlink id="RedefineClasses"/> function). | |
| 761 <p/> | |
| 762 Care must be taken to avoid perturbing dependencies, especially when | |
| 763 instrumenting core classes. For example, an approach to getting notification | |
| 764 of every object allocation is to instrument the constructor on | |
| 765 <code>Object</code>. Assuming that the constructor is initially | |
| 766 empty, the constructor could be changed to: | |
| 767 <example> | |
| 768 public Object() { | |
| 769 MyProfiler.allocationTracker(this); | |
| 770 } | |
| 771 </example> | |
| 772 However, if this change was made using the | |
| 773 <eventlink id="ClassFileLoadHook"/> | |
| 774 event then this might impact a typical VM as follows: | |
| 775 the first created object will call the constructor causing a class load of | |
| 776 <code>MyProfiler</code>; which will then cause | |
| 777 object creation, and since <code>MyProfiler</code> isn't loaded yet, | |
| 778 infinite recursion; resulting in a stack overflow. A refinement of this | |
| 779 would be to delay invoking the tracking method until a safe time. For | |
| 780 example, <code>trackAllocations</code> could be set in the | |
| 781 handler for the <code>VMInit</code> event. | |
| 782 <example> | |
| 783 static boolean trackAllocations = false; | |
| 784 | |
| 785 public Object() { | |
| 786 if (trackAllocations) { | |
| 787 MyProfiler.allocationTracker(this); | |
| 788 } | |
| 789 } | |
| 790 </example> | |
| 791 <p/> | |
| 792 The <functionlink id="SetNativeMethodPrefix"/> allows native methods | |
| 793 to be instrumented by the use of wrapper methods. | |
| 794 </intro> | |
| 795 | |
| 796 <intro id="mUTF" label="Modified UTF-8 String Encoding"> | |
| 797 <jvmti/> uses modified UTF-8 to encode character strings. | |
| 798 This is the same encoding used by JNI. | |
| 799 Modified UTF-8 differs | |
| 800 from standard UTF-8 in the representation of supplementary characters | |
| 801 and of the null character. See the | |
| 802 <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/types.html#wp16542"> | |
| 803 Modified UTF-8 Strings</externallink> | |
| 804 section of the JNI specification for details. | |
| 805 </intro> | |
| 806 | |
| 807 <intro id="context" label="Specification Context"> | |
| 808 Since this interface provides access to the state of applications running in the | |
| 809 Java virtual machine; | |
| 810 terminology refers to the Java platform and not the native | |
| 811 platform (unless stated otherwise). For example: | |
| 812 <ul> | |
| 813 <li>"thread" means Java programming language thread.</li> | |
| 814 <li>"stack frame" means Java virtual machine stack frame.</li> | |
| 815 <li>"class" means Java programming language class.</li> | |
| 816 <li>"heap" means Java virtual machine heap.</li> | |
| 817 <li>"monitor" means Java programming language object monitor.</li> | |
| 818 </ul> | |
| 819 <p/> | |
| 820 Sun, Sun Microsystems, the Sun logo, Java, and JVM | |
|
1552
c18cbe5936b8
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
0
diff
changeset
|
821 are trademarks or registered trademarks of Oracle |
|
c18cbe5936b8
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
0
diff
changeset
|
822 and/or its affiliates, in the U.S. and other countries. |
| 0 | 823 </intro> |
| 824 | |
| 825 | |
| 826 <functionsection label="Functions"> | |
| 827 <intro id="jvmtiEnvAccess" label="Accessing Functions"> | |
| 828 Native code accesses <jvmti/> features | |
| 829 by calling <jvmti/> functions. | |
| 830 Access to <jvmti/> functions is by use of an interface pointer | |
| 831 in the same manner as | |
| 832 <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html">Java | |
| 833 Native Interface (JNI) functions</externallink> are accessed. | |
| 834 The <jvmti/> interface pointer is called the | |
| 835 <i>environment pointer</i>. | |
| 836 <p/> | |
| 837 An environment pointer is a pointer to an environment and has | |
| 838 the type <code>jvmtiEnv*</code>. | |
| 839 An environment has information about its <jvmti/> connection. | |
| 840 The first value in the environment is a pointer to the function table. | |
| 841 The function table is an array of pointers to <jvmti/> functions. | |
| 842 Every function pointer is at a predefined offset inside the | |
| 843 array. | |
| 844 <p/> | |
| 845 When used from the C language: | |
| 846 double indirection is used to access the functions; | |
| 847 the environment pointer provides context and is the first | |
| 848 parameter of each function call; for example: | |
| 849 <example> | |
| 850 jvmtiEnv *jvmti; | |
| 851 ... | |
| 852 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &class_count, &classes); | |
| 853 </example> | |
| 854 <p/> | |
| 855 When used from the C++ language: | |
| 856 functions are accessed as member functions of <code>jvmtiEnv</code>; | |
| 857 the environment pointer is not passed to the function call; for example: | |
| 858 <example> | |
| 859 jvmtiEnv *jvmti; | |
| 860 ... | |
| 861 jvmtiError err = jvmti->GetLoadedClasses(&class_count, &classes); | |
| 862 </example> | |
| 863 Unless otherwise stated, all examples and declarations in this | |
| 864 specification use the C language. | |
| 865 <p/> | |
| 866 A <jvmti/> environment can be obtained through the JNI Invocation API | |
| 867 <code>GetEnv</code> function: | |
| 868 <example> | |
| 869 jvmtiEnv *jvmti; | |
| 870 ... | |
| 871 (*jvm)->GetEnv(jvm, &jvmti, JVMTI_VERSION_1_0); | |
| 872 </example> | |
| 873 Each call to <code>GetEnv</code> | |
| 874 creates a new <jvmti/> connection and thus | |
| 875 a new <jvmti/> environment. | |
| 876 The <code>version</code> argument of <code>GetEnv</code> must be | |
| 877 a <jvmti/> version. | |
| 878 The returned environment may have a different version than the | |
| 879 requested version but the returned environment must be compatible. | |
| 880 <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a | |
| 881 compatible version is not available, if <jvmti/> is not supported or | |
| 882 <jvmti/> is not supported in the current VM configuration. | |
| 883 Other interfaces may be added for creating <jvmti/> environments | |
| 884 in specific contexts. | |
| 885 Each environment has its own state (for example, | |
| 886 <functionlink id="SetEventNotificationMode">desired events</functionlink>, | |
| 887 <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and | |
| 888 <functionlink id="AddCapabilities">capabilities</functionlink>). | |
| 889 An environment is released with | |
| 890 <functionlink id="DisposeEnvironment"></functionlink>. | |
| 891 Thus, unlike JNI which has one environment per thread, <jvmti/> environments work | |
| 892 across threads and are created dynamically. | |
| 893 </intro> | |
| 894 | |
| 895 <intro id="functionReturn" label="Function Return Values"> | |
| 896 <jvmti/> functions always return an | |
| 897 <internallink id="ErrorSection">error code</internallink> via the | |
| 898 <datalink id="jvmtiError"/> function return value. | |
| 899 Some functions can return additional | |
| 900 values through pointers provided by the calling function. | |
| 901 In some cases, <jvmti/> functions allocate memory that your program must | |
| 902 explicitly deallocate. This is indicated in the individual <jvmti/> | |
| 903 function descriptions. Empty lists, arrays, sequences, etc are | |
| 904 returned as <code>NULL</code>. | |
| 905 <p/> | |
| 906 In the event that the <jvmti/> function encounters | |
| 907 an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values | |
| 908 of memory referenced by argument pointers is undefined, but no memory | |
| 909 will have been allocated and no global references will have been allocated. | |
| 910 If the error occurs because of invalid input, no action will have occurred. | |
| 911 </intro> | |
| 912 | |
| 913 <intro id="refs" label="Managing JNI Object References"> | |
| 914 <jvmti/> functions identify objects with JNI references | |
| 915 (<datalink id="jobject"/> and <datalink id="jclass"/>) | |
| 916 and their derivatives | |
| 917 (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>). | |
| 918 References passed to | |
| 919 <jvmti/> functions can be either global or local, but they must be | |
| 920 strong references. All references returned by <jvmti/> functions are | |
| 921 local references--these local references are created | |
| 922 during the <jvmti/> call. | |
| 923 Local references are a resource that must be managed (see the | |
| 924 <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html#wp18654">JNI Documentation</externallink>). | |
| 925 When threads return from native code all local references | |
| 926 are freed. Note that some threads, including typical | |
| 927 agent threads, will never return from native code. | |
| 928 A thread is ensured the ability to create sixteen local | |
| 929 references without the need for any explicit management. | |
| 930 For threads executing a limited number of <jvmti/> calls before | |
| 931 returning from native code | |
| 932 (for example, threads processing events), | |
| 933 it may be determined that no explicit management | |
| 934 is needed. | |
| 935 However, long running agent threads will need explicit | |
| 936 local reference management--usually with the JNI functions | |
| 937 <code>PushLocalFrame</code> and <code>PopLocalFrame</code>. | |
| 938 Conversely, to preserve references beyond the | |
| 939 return from native code, they must be converted to global references. | |
| 940 These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> | |
| 941 as they are not <datalink id="jobject"/>s. | |
| 942 </intro> | |
| 943 | |
| 944 <intro id="prereqState" label="Prerequisite State for Calling Functions"> | |
| 945 Unless the function explicitly states that the agent must bring | |
| 946 a thread or the VM to a particular state (for example, suspended), | |
| 947 the <jvmti/> implementation is responsible for bringing the VM to a | |
| 948 safe and consistent state for performing the function. | |
| 949 </intro> | |
| 950 | |
| 951 <intro id="functionsExceptions" label="Exceptions and Functions"> | |
| 952 <jvmti/> functions never throw exceptions; error conditions are | |
| 953 communicated via the | |
| 954 <internallink id="functionReturn">function return value</internallink>. | |
| 955 Any existing exception state is preserved across a call to a | |
| 956 <jvmti/> function. | |
| 957 See the | |
| 958 <externallink | |
| 959 id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html#wp770" | |
| 960 >Java Exceptions</externallink> | |
| 961 section of the JNI specification for information on handling exceptions. | |
| 962 </intro> | |
| 963 | |
| 964 <category id="memory" label="Memory Management"> | |
| 965 <intro> | |
| 966 These functions provide for the allocation and deallocation of | |
| 967 memory used by <jvmti/> functionality and can be used to provide | |
| 968 working memory for agents. | |
| 969 Memory managed by <jvmti/> is not compatible with other memory | |
| 970 allocation libraries and mechanisms. | |
| 971 </intro> | |
| 972 | |
| 973 <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46"> | |
| 974 <synopsis>Allocate</synopsis> | |
| 975 <description> | |
| 976 Allocate an area of memory through the <jvmti/> allocator. | |
| 977 The allocated | |
| 978 memory should be freed with <functionlink id="Deallocate"></functionlink>. | |
| 979 </description> | |
| 980 <origin>jvmdi</origin> | |
| 981 <capabilities> | |
| 982 </capabilities> | |
| 983 <parameters> | |
| 984 <param id="size"> | |
| 985 <jlong/> | |
| 986 <description> | |
| 987 The number of bytes to allocate. | |
| 988 <rationale> | |
| 989 <code>jlong</code> is used for compatibility with JVMDI. | |
| 990 </rationale> | |
| 991 </description> | |
| 992 </param> | |
| 993 <param id="mem_ptr"> | |
| 994 <allocbuf incount="size"><uchar/></allocbuf> | |
| 995 <description> | |
| 996 On return, a pointer to the beginning of the allocated memory. | |
| 997 If <code>size</code> is zero, <code>NULL</code> is returned. | |
| 998 </description> | |
| 999 </param> | |
| 1000 </parameters> | |
| 1001 <errors> | |
| 1002 <error id="JVMTI_ERROR_OUT_OF_MEMORY"> | |
| 1003 Memory request cannot be honored. | |
| 1004 </error> | |
| 1005 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 1006 <paramlink id="size"></paramlink> is less than zero. | |
| 1007 </error> | |
| 1008 </errors> | |
| 1009 </function> | |
| 1010 | |
| 1011 <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47"> | |
| 1012 <synopsis>Deallocate</synopsis> | |
| 1013 <description> | |
| 1014 Deallocate <code>mem</code> using the <jvmti/> allocator. | |
| 1015 This function should | |
| 1016 be used to deallocate any memory allocated and returned | |
| 1017 by a <jvmti/> function | |
| 1018 (including memory allocated with <functionlink id="Allocate"></functionlink>). | |
| 1019 All allocated memory must be deallocated | |
| 1020 or the memory cannot be reclaimed. | |
| 1021 </description> | |
| 1022 <origin>jvmdi</origin> | |
| 1023 <capabilities> | |
| 1024 </capabilities> | |
| 1025 <parameters> | |
| 1026 <param id="mem"> | |
| 1027 <outbuf> | |
| 1028 <uchar/> | |
| 1029 <nullok>the call is ignored</nullok> | |
| 1030 </outbuf> | |
| 1031 <description> | |
| 1032 A pointer to the beginning of the allocated memory. | |
| 1033 Please ignore "On return, the elements are set." | |
| 1034 <todo>keep it from generating "On return, the elements are set"</todo> | |
| 1035 </description> | |
| 1036 </param> | |
| 1037 </parameters> | |
| 1038 <errors> | |
| 1039 </errors> | |
| 1040 </function> | |
| 1041 </category> | |
| 1042 | |
| 1043 <category id="threadCategory" label="Thread"> | |
| 1044 <intro> | |
| 1045 </intro> | |
| 1046 | |
| 1047 <function id="GetThreadState" num="17"> | |
| 1048 <synopsis>Get Thread State</synopsis> | |
| 1049 <description> | |
| 1050 Get the state of a thread. The state of the thread is represented by the | |
| 1051 answers to the hierarchical set of questions below: | |
| 1052 <ul type="circle"> | |
| 1053 <li><i>Alive?</i> | |
| 1054 <ul> | |
| 1055 <li>Not alive. | |
| 1056 <ul type="circle"> | |
| 1057 <li><i>Why not alive?</i> | |
| 1058 <ul> | |
| 1059 <li>New.</li> | |
| 1060 <li>Terminated (<datalink | |
| 1061 id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li> | |
| 1062 </ul> | |
| 1063 </li> | |
| 1064 </ul> | |
| 1065 </li> | |
| 1066 <li>Alive (<datalink | |
| 1067 id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>) | |
| 1068 <ul type="circle"> | |
| 1069 <li><i>Suspended?</i> | |
| 1070 <ul> | |
| 1071 <li>Suspended (<datalink | |
| 1072 id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li> | |
| 1073 <li>Not suspended</li> | |
| 1074 </ul> | |
| 1075 </li> | |
| 1076 <li><i>Interrupted?</i> | |
| 1077 <ul> | |
| 1078 <li>Interrupted (<datalink | |
| 1079 id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li> | |
| 1080 <li>Not interrupted.</li> | |
| 1081 </ul> | |
| 1082 </li> | |
| 1083 <li><i>In native?</i> | |
| 1084 <ul> | |
| 1085 <li>In native code (<datalink | |
| 1086 id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li> | |
| 1087 <li>In Java programming language code</li> | |
| 1088 </ul> | |
| 1089 </li> | |
| 1090 <li><i>What alive state?</i> | |
| 1091 <ul> | |
| 1092 <li>Runnable (<datalink | |
| 1093 id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li> | |
| 1094 <li>Blocked (<datalink | |
| 1095 id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li> | |
| 1096 <li>Waiting (<datalink | |
| 1097 id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>) | |
| 1098 <ul type="circle"> | |
| 1099 <li><i>Timed wait?</i> | |
| 1100 <ul> | |
| 1101 <li>Indefinite (<datalink | |
| 1102 id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li> | |
| 1103 <li>Timed (<datalink | |
| 1104 id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li> | |
| 1105 </ul> | |
| 1106 </li> | |
| 1107 <li><i>Why waiting?</i> | |
| 1108 <ul> | |
| 1109 <li>Object.wait (<datalink | |
| 1110 id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li> | |
| 1111 <li>LockSupport.park (<datalink | |
| 1112 id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li> | |
| 1113 <li>Sleeping (<datalink | |
| 1114 id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li> | |
| 1115 </ul> | |
| 1116 </li> | |
| 1117 </ul> | |
| 1118 </li> | |
| 1119 </ul> | |
| 1120 </li> | |
| 1121 </ul> | |
| 1122 </li> | |
| 1123 </ul> | |
| 1124 </li> | |
| 1125 </ul> | |
| 1126 <p/> | |
| 1127 The answers are represented by the following bit vector. | |
| 1128 <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits"> | |
| 1129 <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001"> | |
| 1130 Thread is alive. Zero if thread is new (not started) or terminated. | |
| 1131 </constant> | |
| 1132 <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002"> | |
| 1133 Thread has completed execution. | |
| 1134 </constant> | |
| 1135 <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004"> | |
| 1136 Thread is runnable. | |
| 1137 </constant> | |
| 1138 <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400"> | |
| 1139 Thread is waiting to enter a synchronization block/method or, | |
| 1140 after an <code>Object.wait()</code>, waiting to re-enter a | |
| 1141 synchronization block/method. | |
| 1142 </constant> | |
| 1143 <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080"> | |
| 1144 Thread is waiting. | |
| 1145 </constant> | |
| 1146 <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010"> | |
| 1147 Thread is waiting without a timeout. | |
| 1148 For example, <code>Object.wait()</code>. | |
| 1149 </constant> | |
| 1150 <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020"> | |
| 1151 Thread is waiting with a maximum time to wait specified. | |
| 1152 For example, <code>Object.wait(long)</code>. | |
| 1153 </constant> | |
| 1154 <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040"> | |
| 1155 Thread is sleeping -- <code>Thread.sleep(long)</code>. | |
| 1156 </constant> | |
| 1157 <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100"> | |
| 1158 Thread is waiting on an object monitor -- <code>Object.wait</code>. | |
| 1159 </constant> | |
| 1160 <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200"> | |
| 1161 Thread is parked, for example: <code>LockSupport.park</code>, | |
| 1162 <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>. | |
| 1163 </constant> | |
| 1164 <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000"> | |
| 1165 Thread suspended. | |
| 1166 <code>java.lang.Thread.suspend()</code> | |
| 1167 or a <jvmti/> suspend function | |
| 1168 (such as <functionlink id="SuspendThread"></functionlink>) | |
| 1169 has been called on the thread. If this bit | |
| 1170 is set, the other bits refer to the thread state before suspension. | |
| 1171 </constant> | |
| 1172 <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000"> | |
| 1173 Thread has been interrupted. | |
| 1174 </constant> | |
| 1175 <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000"> | |
| 1176 Thread is in native code--that is, a native method is running | |
| 1177 which has not called back into the VM or Java programming | |
| 1178 language code. | |
| 1179 <p/> | |
| 1180 This flag is not set when running VM compiled Java programming | |
| 1181 language code nor is it set when running VM code or | |
| 1182 VM support code. Native VM interface functions, such as JNI and | |
| 1183 <jvmti/> functions, may be implemented as VM code. | |
| 1184 </constant> | |
| 1185 <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000"> | |
| 1186 Defined by VM vendor. | |
| 1187 </constant> | |
| 1188 <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000"> | |
| 1189 Defined by VM vendor. | |
| 1190 </constant> | |
| 1191 <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000"> | |
| 1192 Defined by VM vendor. | |
| 1193 </constant> | |
| 1194 </constants> | |
| 1195 The following definitions are used to convert <jvmti/> thread state | |
| 1196 to <code>java.lang.Thread.State</code> style states. | |
| 1197 <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits"> | |
| 1198 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK" | |
| 1199 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"> | |
| 1200 Mask the state with this before comparison | |
| 1201 </constant> | |
| 1202 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW" | |
| 1203 num="0"> | |
| 1204 <code>java.lang.Thread.State.NEW</code> | |
| 1205 </constant> | |
| 1206 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED" | |
| 1207 num="JVMTI_THREAD_STATE_TERMINATED"> | |
| 1208 <code>java.lang.Thread.State.TERMINATED</code> | |
| 1209 </constant> | |
| 1210 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE" | |
| 1211 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE"> | |
| 1212 <code>java.lang.Thread.State.RUNNABLE</code> | |
| 1213 </constant> | |
| 1214 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED" | |
| 1215 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"> | |
| 1216 <code>java.lang.Thread.State.BLOCKED</code> | |
| 1217 </constant> | |
| 1218 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING" | |
| 1219 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY"> | |
| 1220 <code>java.lang.Thread.State.WAITING</code> | |
| 1221 </constant> | |
| 1222 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING" | |
| 1223 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"> | |
| 1224 <code>java.lang.Thread.State.TIMED_WAITING</code> | |
| 1225 </constant> | |
| 1226 </constants> | |
| 1227 <b>Rules</b> | |
| 1228 <p/> | |
| 1229 There can be no more than one answer to a question, although there can be no | |
| 1230 answer (because the answer is unknown, does not apply, or none of the answers is | |
| 1231 correct). An answer is set only when the enclosing answers match. | |
| 1232 That is, no more than one of | |
| 1233 <ul type="circle"> | |
| 1234 <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li> | |
| 1235 <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li> | |
| 1236 <li><code>JVMTI_THREAD_STATE_WAITING</code></li> | |
| 1237 </ul> | |
| 1238 can be set (a <tm>J2SE</tm> compliant implementation will always set | |
| 1239 one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set). | |
| 1240 And if any of these are set, the enclosing answer | |
| 1241 <code>JVMTI_THREAD_STATE_ALIVE</code> is set. | |
| 1242 No more than one of | |
| 1243 <ul type="circle"> | |
| 1244 <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li> | |
| 1245 <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li> | |
| 1246 </ul> | |
| 1247 can be set (a <tm>J2SE</tm> compliant implementation will always set | |
| 1248 one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set). | |
| 1249 And if either is set, the enclosing answers | |
| 1250 <code>JVMTI_THREAD_STATE_ALIVE</code> and | |
| 1251 <code>JVMTI_THREAD_STATE_WAITING</code> are set. | |
| 1252 No more than one of | |
| 1253 <ul type="circle"> | |
| 1254 <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li> | |
| 1255 <li><code>JVMTI_THREAD_STATE_PARKED</code></li> | |
| 1256 <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li> | |
| 1257 </ul> | |
| 1258 can be set. And if any of these is set, the enclosing answers | |
| 1259 <code>JVMTI_THREAD_STATE_ALIVE</code> and | |
| 1260 <code>JVMTI_THREAD_STATE_WAITING</code> are set. | |
| 1261 Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set, | |
| 1262 then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set. | |
| 1263 If a state <i>A</i> is implemented using the mechanism of | |
| 1264 state <i>B</i> then it is state <i>A</i> which | |
| 1265 is returned by this function. | |
| 1266 For example, if <code>Thread.sleep(long)</code> | |
| 1267 is implemented using <code>Object.wait(long)</code> | |
| 1268 then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code> | |
| 1269 which is returned. | |
| 1270 More than one of | |
| 1271 <ul type="circle"> | |
| 1272 <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li> | |
| 1273 <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li> | |
| 1274 <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li> | |
| 1275 </ul> | |
| 1276 can be set, but if any is set, | |
| 1277 <code>JVMTI_THREAD_STATE_ALIVE</code> is set. | |
| 1278 <p/> | |
| 1279 And finally, | |
| 1280 <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless | |
| 1281 <code>JVMTI_THREAD_STATE_ALIVE</code> is not set. | |
| 1282 <p/> | |
| 1283 The thread state representation is designed for extension in future versions | |
| 1284 of the specification; thread state values should be used accordingly, that is | |
| 1285 they should not be used as ordinals. | |
| 1286 Most queries can be made by testing a single bit, if use in a switch statement is desired, | |
| 1287 the state bits should be masked with the interesting bits. | |
| 1288 All bits not defined above are reserved for future use. | |
| 1289 A VM, compliant to the current specification, must set reserved bits to zero. | |
| 1290 An agent should ignore reserved bits -- | |
| 1291 they should not be assumed to be zero and thus should not be included in comparisons. | |
| 1292 <p/> | |
| 1293 <b>Examples</b> | |
| 1294 <p/> | |
| 1295 Note that the values below exclude reserved and vendor bits. | |
| 1296 <p/> | |
| 1297 The state of a thread blocked at a <code>synchronized</code>-statement would be: | |
| 1298 <example> | |
| 1299 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | |
| 1300 </example> | |
| 1301 The state of a thread which hasn't started yet would be: | |
| 1302 <example> | |
| 1303 0 | |
| 1304 </example> | |
| 1305 The state of a thread at a <code>Object.wait(3000)</code> would be: | |
| 1306 <example> | |
| 1307 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING + | |
| 1308 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT + | |
| 1309 JVMTI_THREAD_STATE_MONITOR_WAITING | |
| 1310 </example> | |
| 1311 The state of a thread suspended while runnable would be: | |
| 1312 <example> | |
| 1313 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED | |
| 1314 </example> | |
| 1315 <p/> | |
| 1316 <b>Testing the State</b> | |
| 1317 <p/> | |
| 1318 In most cases, the thread state can be determined by testing the one bit corresponding | |
| 1319 to that question. For example, the code to test if a thread is sleeping: | |
| 1320 <example> | |
| 1321 jint state; | |
| 1322 jvmtiError err; | |
| 1323 | |
| 1324 err = (*jvmti)->GetThreadState(jvmti, thread, &state); | |
| 1325 if (err == JVMTI_ERROR_NONE) { | |
| 1326 if (state & JVMTI_THREAD_STATE_SLEEPING) { ... | |
| 1327 </example> | |
| 1328 <p/> | |
| 1329 For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be: | |
| 1330 <example> | |
| 1331 if (state & JVMTI_THREAD_STATE_WAITING) { ... | |
| 1332 </example> | |
| 1333 For some states, more than one bit will need to be tested as is the case | |
| 1334 when testing if a thread has not yet been started: | |
| 1335 <example> | |
| 1336 if ((state & (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0) { ... | |
| 1337 </example> | |
| 1338 To distinguish timed from untimed <code>Object.wait</code>: | |
| 1339 <example> | |
| 1340 if (state & JVMTI_THREAD_STATE_IN_OBJECT_WAIT) { | |
| 1341 if (state & JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT) { | |
| 1342 printf("in Object.wait(long timeout)\n"); | |
| 1343 } else { | |
| 1344 printf("in Object.wait()\n"); | |
| 1345 } | |
| 1346 } | |
| 1347 </example> | |
| 1348 <p/> | |
| 1349 <b>Relationship to <code>java.lang.Thread.State</code></b> | |
| 1350 <p/> | |
| 1351 The thread state represented by <code>java.lang.Thread.State</code> | |
| 1352 returned from <code>java.lang.Thread.getState()</code> is a subset of the | |
| 1353 information returned from this function. | |
| 1354 The corresponding <code>java.lang.Thread.State</code> can be determined | |
| 1355 by using the provided conversion masks. | |
| 1356 For example, this returns the name of the <code>java.lang.Thread.State</code> thread state: | |
| 1357 <example> | |
| 1358 err = (*jvmti)->GetThreadState(jvmti, thread, &state); | |
| 1359 abortOnError(err); | |
| 1360 switch (state & JVMTI_JAVA_LANG_THREAD_STATE_MASK) { | |
| 1361 case JVMTI_JAVA_LANG_THREAD_STATE_NEW: | |
| 1362 return "NEW"; | |
| 1363 case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED: | |
| 1364 return "TERMINATED"; | |
| 1365 case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE: | |
| 1366 return "RUNNABLE"; | |
| 1367 case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED: | |
| 1368 return "BLOCKED"; | |
| 1369 case JVMTI_JAVA_LANG_THREAD_STATE_WAITING: | |
| 1370 return "WAITING"; | |
| 1371 case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING: | |
| 1372 return "TIMED_WAITING"; | |
| 1373 } | |
| 1374 </example> | |
| 1375 </description> | |
| 1376 <origin>new</origin> | |
| 1377 <capabilities> | |
| 1378 </capabilities> | |
| 1379 <parameters> | |
| 1380 <param id="thread"> | |
| 1381 <jthread null="current" started="maybe" impl="noconvert"/> | |
| 1382 <description> | |
| 1383 The thread to query. | |
| 1384 </description> | |
| 1385 </param> | |
| 1386 <param id="thread_state_ptr"> | |
| 1387 <outptr><jint/></outptr> | |
| 1388 <description> | |
| 1389 On return, points to state flags, | |
| 1390 as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>. | |
| 1391 </description> | |
| 1392 </param> | |
| 1393 </parameters> | |
| 1394 <errors> | |
| 1395 </errors> | |
| 1396 </function> | |
| 1397 | |
| 1398 <function id="GetCurrentThread" phase="start" num="18" since="1.1"> | |
| 1399 <synopsis>Get Current Thread</synopsis> | |
| 1400 <description> | |
| 1401 Get the current thread. | |
| 1402 The current thread is the Java programming language thread which has called the function. | |
| 1403 <p/> | |
| 1404 Note that most <jvmti/> functions that take a thread | |
| 1405 as an argument will accept <code>NULL</code> to mean | |
| 1406 the current thread. | |
| 1407 </description> | |
| 1408 <origin>new</origin> | |
| 1409 <capabilities> | |
| 1410 </capabilities> | |
| 1411 <parameters> | |
| 1412 <param id="thread_ptr"> | |
| 1413 <outptr><jthread/></outptr> | |
| 1414 <description> | |
| 1415 On return, points to the current thread. | |
| 1416 </description> | |
| 1417 </param> | |
| 1418 </parameters> | |
| 1419 <errors> | |
| 1420 </errors> | |
| 1421 </function> | |
| 1422 | |
| 1423 <function id="GetAllThreads" num="4"> | |
| 1424 <synopsis>Get All Threads</synopsis> | |
| 1425 <description> | |
| 1426 Get all live threads. | |
| 1427 The threads are Java programming language threads; | |
| 1428 that is, threads that are attached to the VM. | |
| 1429 A thread is live if <code>java.lang.Thread.isAlive()</code> | |
| 1430 would return <code>true</code>, that is, the thread has | |
| 1431 been started and has not yet died. | |
| 1432 The universe of threads is determined by the context of the <jvmti/> | |
| 1433 environment, which typically is all threads attached to the VM. | |
| 1434 Note that this includes <jvmti/> agent threads | |
| 1435 (see <functionlink id="RunAgentThread"/>). | |
| 1436 </description> | |
| 1437 <origin>jvmdi</origin> | |
| 1438 <capabilities> | |
| 1439 </capabilities> | |
| 1440 <parameters> | |
| 1441 <param id="threads_count_ptr"> | |
| 1442 <outptr><jint/></outptr> | |
| 1443 <description> | |
| 1444 On return, points to the number of running threads. | |
| 1445 </description> | |
| 1446 </param> | |
| 1447 <param id="threads_ptr"> | |
| 1448 <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf> | |
| 1449 <description> | |
| 1450 On return, points to an array of references, one | |
| 1451 for each running thread. | |
| 1452 </description> | |
| 1453 </param> | |
| 1454 </parameters> | |
| 1455 <errors> | |
| 1456 </errors> | |
| 1457 </function> | |
| 1458 | |
| 1459 <function id="SuspendThread" num="5"> | |
| 1460 <synopsis>Suspend Thread</synopsis> | |
| 1461 <description> | |
| 1462 Suspend the specified thread. If the calling thread is specified, | |
| 1463 this function will not return until some other thread calls | |
| 1464 <functionlink id="ResumeThread"></functionlink>. | |
| 1465 If the thread is currently suspended, this function | |
| 1466 does nothing and returns an error. | |
| 1467 </description> | |
| 1468 <origin>jvmdi</origin> | |
| 1469 <capabilities> | |
| 1470 <required id="can_suspend"></required> | |
| 1471 </capabilities> | |
| 1472 <parameters> | |
| 1473 <param id="thread"> | |
| 1474 <jthread null="current"/> | |
| 1475 <description> | |
| 1476 The thread to suspend. | |
| 1477 </description> | |
| 1478 </param> | |
| 1479 </parameters> | |
| 1480 <errors> | |
| 1481 <error id="JVMTI_ERROR_THREAD_SUSPENDED"> | |
| 1482 Thread already suspended. | |
| 1483 </error> | |
| 1484 </errors> | |
| 1485 </function> | |
| 1486 | |
| 1487 <elide> | |
| 1488 <function id="SuspendAllThreads" num="101"> | |
| 1489 <synopsis>Suspend All Threads</synopsis> | |
| 1490 <description> | |
| 1491 <issue> | |
| 1492 There has been no explicit call for this function, and it will | |
| 1493 thus be removed if there is no interest. | |
| 1494 </issue> | |
| 1495 Suspend all live threads except: | |
| 1496 <ul> | |
| 1497 <li>already suspended threads</li> | |
| 1498 <li>those listed in <paramlink id="except_list"></paramlink></li> | |
| 1499 <li>certain system (non application) threads, as determined | |
| 1500 by the VM implementation</li> | |
| 1501 </ul> | |
| 1502 The threads are Java programming language threads; | |
| 1503 native threads which are not attached to the VM are not | |
| 1504 Java programming language threads. | |
| 1505 A thread is live if <code>java.lang.Thread.isAlive()</code> | |
| 1506 would return <code>true</code>, that is, the thread has | |
| 1507 been started and has not yet died. | |
| 1508 The universe of threads is determined | |
| 1509 by the context of the <jvmti/> | |
| 1510 environment, which, typically, is all threads attached to the VM, | |
| 1511 except critical VM internal threads and <jvmti/> agent threads | |
| 1512 (see <functionlink id="RunAgentThread"/>). | |
| 1513 <p/> | |
| 1514 If the calling thread is specified, | |
| 1515 all other threads are suspended first then the caller thread is suspended - | |
| 1516 this function will not return until some other thread calls | |
| 1517 <functionlink id="ResumeThread"></functionlink>. | |
| 1518 <p/> | |
| 1519 The list of actually | |
| 1520 suspended threads is returned in | |
| 1521 <paramlink id="suspended_list_ptr"></paramlink>. | |
| 1522 Suspension is as defined in <functionlink id="SuspendThread"></functionlink>. | |
| 1523 <functionlink id="ResumeThreadList"></functionlink> | |
| 1524 can be used to resume the suspended threads. | |
| 1525 </description> | |
| 1526 <origin>new</origin> | |
| 1527 <capabilities> | |
| 1528 <required id="can_suspend"></required> | |
| 1529 </capabilities> | |
| 1530 <parameters> | |
| 1531 <param id="except_count"> | |
| 1532 <jint min="0"/> | |
| 1533 <description> | |
| 1534 The number of threads in the list of threads not to be suspended. | |
| 1535 </description> | |
| 1536 </param> | |
| 1537 <param id="except_list"> | |
| 1538 <inbuf incount="except_count"> | |
| 1539 <jthread/> | |
| 1540 <nullok>not an error if <code>except_count == 0</code></nullok> | |
| 1541 </inbuf> | |
| 1542 <description> | |
| 1543 The list of threads not to be suspended. | |
| 1544 </description> | |
| 1545 </param> | |
| 1546 <param id="suspended_count_ptr"> | |
| 1547 <outptr><jint/></outptr> | |
| 1548 <description> | |
| 1549 On return, points to the number of threads suspended by this call. | |
| 1550 </description> | |
| 1551 </param> | |
| 1552 <param id="suspended_list_ptr"> | |
| 1553 <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf> | |
| 1554 <description> | |
| 1555 On return, points to an array of references, one | |
| 1556 for each thread suspended. | |
| 1557 </description> | |
| 1558 </param> | |
| 1559 </parameters> | |
| 1560 <errors> | |
| 1561 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
| 1562 A thread in <paramlink id="except_list"></paramlink> was invalid. | |
| 1563 </error> | |
| 1564 <error id="JVMTI_ERROR_NULL_POINTER"> | |
| 1565 Both <paramlink id="except_list"></paramlink> was <code>NULL</code> | |
| 1566 and <paramlink id="except_count"></paramlink> was non-zero. | |
| 1567 </error> | |
| 1568 </errors> | |
| 1569 </function> | |
| 1570 </elide> | |
| 1571 | |
| 1572 <function id="SuspendThreadList" num="92"> | |
| 1573 <synopsis>Suspend Thread List</synopsis> | |
| 1574 <description> | |
| 1575 Suspend the <paramlink id="request_count"></paramlink> | |
| 1576 threads specified in the | |
| 1577 <paramlink id="request_list"></paramlink> array. | |
| 1578 Threads may be resumed with | |
| 1579 <functionlink id="ResumeThreadList"></functionlink> or | |
| 1580 <functionlink id="ResumeThread"></functionlink>. | |
| 1581 If the calling thread is specified in the | |
| 1582 <paramlink id="request_list"></paramlink> array, this function will | |
| 1583 not return until some other thread resumes it. | |
| 1584 Errors encountered in the suspension of a thread | |
| 1585 are returned in the <paramlink id="results"></paramlink> | |
| 1586 array, <b>not</b> in the return value of this function. | |
| 1587 Threads that are currently suspended do not change state. | |
| 1588 </description> | |
| 1589 <origin>jvmdi</origin> | |
| 1590 <capabilities> | |
| 1591 <required id="can_suspend"></required> | |
| 1592 </capabilities> | |
| 1593 <parameters> | |
| 1594 <param id="request_count"> | |
| 1595 <jint min="0"/> | |
| 1596 <description> | |
| 1597 The number of threads to suspend. | |
| 1598 </description> | |
| 1599 </param> | |
| 1600 <param id="request_list"> | |
| 1601 <inbuf incount="request_count"><jthread/></inbuf> | |
| 1602 <description> | |
| 1603 The list of threads to suspend. | |
| 1604 </description> | |
| 1605 </param> | |
| 1606 <param id="results"> | |
| 1607 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> | |
| 1608 <description> | |
| 1609 An agent supplied array of | |
| 1610 <paramlink id="request_count"></paramlink> elements. | |
| 1611 On return, filled with the error code for | |
| 1612 the suspend of the corresponding thread. | |
| 1613 The error code will be | |
| 1614 <errorlink id="JVMTI_ERROR_NONE"></errorlink> | |
| 1615 if the thread was suspended by this call. | |
| 1616 Possible error codes are those specified | |
| 1617 for <functionlink id="SuspendThread"></functionlink>. | |
| 1618 </description> | |
| 1619 </param> | |
| 1620 </parameters> | |
| 1621 <errors> | |
| 1622 </errors> | |
| 1623 </function> | |
| 1624 | |
| 1625 <function id="ResumeThread" num="6"> | |
| 1626 <synopsis>Resume Thread</synopsis> | |
| 1627 <description> | |
| 1628 Resume a suspended thread. | |
| 1629 Any threads currently suspended through | |
| 1630 a <jvmti/> suspend function (eg. | |
| 1631 <functionlink id="SuspendThread"></functionlink>) | |
| 1632 or <code>java.lang.Thread.suspend()</code> | |
| 1633 will resume execution; | |
| 1634 all other threads are unaffected. | |
| 1635 </description> | |
| 1636 <origin>jvmdi</origin> | |
| 1637 <capabilities> | |
| 1638 <required id="can_suspend"></required> | |
| 1639 </capabilities> | |
| 1640 <parameters> | |
| 1641 <param id="thread"> | |
| 1642 <jthread/> | |
| 1643 <description> | |
| 1644 The thread to resume. | |
| 1645 </description> | |
| 1646 </param> | |
| 1647 </parameters> | |
| 1648 <errors> | |
| 1649 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 1650 Thread was not suspended. | |
| 1651 </error> | |
| 1652 <error id="JVMTI_ERROR_INVALID_TYPESTATE"> | |
| 1653 The state of the thread has been modified, and is now inconsistent. | |
| 1654 </error> | |
| 1655 </errors> | |
| 1656 </function> | |
| 1657 | |
| 1658 <function id="ResumeThreadList" num="93"> | |
| 1659 <synopsis>Resume Thread List</synopsis> | |
| 1660 <description> | |
| 1661 Resume the <paramlink id="request_count"></paramlink> | |
| 1662 threads specified in the | |
| 1663 <paramlink id="request_list"></paramlink> array. | |
| 1664 Any thread suspended through | |
| 1665 a <jvmti/> suspend function (eg. | |
| 1666 <functionlink id="SuspendThreadList"></functionlink>) | |
| 1667 or <code>java.lang.Thread.suspend()</code> | |
| 1668 will resume execution. | |
| 1669 </description> | |
| 1670 <origin>jvmdi</origin> | |
| 1671 <capabilities> | |
| 1672 <required id="can_suspend"></required> | |
| 1673 </capabilities> | |
| 1674 <parameters> | |
| 1675 <param id="request_count"> | |
| 1676 <jint min="0"/> | |
| 1677 <description> | |
| 1678 The number of threads to resume. | |
| 1679 </description> | |
| 1680 </param> | |
| 1681 <param id="request_list"> | |
| 1682 <inbuf incount="request_count"><jthread/></inbuf> | |
| 1683 <description> | |
| 1684 The threads to resume. | |
| 1685 </description> | |
| 1686 </param> | |
| 1687 <param id="results"> | |
| 1688 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> | |
| 1689 <description> | |
| 1690 An agent supplied array of | |
| 1691 <paramlink id="request_count"></paramlink> elements. | |
| 1692 On return, filled with the error code for | |
| 1693 the resume of the corresponding thread. | |
| 1694 The error code will be | |
| 1695 <errorlink id="JVMTI_ERROR_NONE"></errorlink> | |
| 1696 if the thread was suspended by this call. | |
| 1697 Possible error codes are those specified | |
| 1698 for <functionlink id="ResumeThread"></functionlink>. | |
| 1699 </description> | |
| 1700 </param> | |
| 1701 </parameters> | |
| 1702 <errors> | |
| 1703 </errors> | |
| 1704 </function> | |
| 1705 | |
| 1706 <function id="StopThread" num="7"> | |
| 1707 <synopsis>Stop Thread</synopsis> | |
| 1708 <description> | |
| 1709 Send the specified asynchronous exception to the specified thread | |
| 1710 (similar to <code>java.lang.Thread.stop</code>). | |
| 1711 Normally, this function is used to kill the specified thread with an | |
| 1712 instance of the exception <code>ThreadDeath</code>. | |
| 1713 </description> | |
| 1714 <origin>jvmdi</origin> | |
| 1715 <capabilities> | |
| 1716 <required id="can_signal_thread"></required> | |
| 1717 </capabilities> | |
| 1718 <parameters> | |
| 1719 <param id="thread"> | |
| 1720 <jthread/> | |
| 1721 <description> | |
| 1722 The thread to stop. | |
| 1723 </description> | |
| 1724 </param> | |
| 1725 <param id="exception"> | |
| 1726 <jobject/> | |
| 1727 <description> | |
| 1728 The asynchronous exception object. | |
| 1729 </description> | |
| 1730 </param> | |
| 1731 </parameters> | |
| 1732 <errors> | |
| 1733 </errors> | |
| 1734 </function> | |
| 1735 | |
| 1736 <function id="InterruptThread" num="8"> | |
| 1737 <synopsis>Interrupt Thread</synopsis> | |
| 1738 <description> | |
| 1739 Interrupt the specified thread | |
| 1740 (similar to <code>java.lang.Thread.interrupt</code>). | |
| 1741 </description> | |
| 1742 <origin>jvmdi</origin> | |
| 1743 <capabilities> | |
| 1744 <required id="can_signal_thread"></required> | |
| 1745 </capabilities> | |
| 1746 <parameters> | |
| 1747 <param id="thread"> | |
| 1748 <jthread impl="noconvert"/> | |
| 1749 <description> | |
| 1750 The thread to interrupt. | |
| 1751 </description> | |
| 1752 </param> | |
| 1753 </parameters> | |
| 1754 <errors> | |
| 1755 </errors> | |
| 1756 </function> | |
| 1757 | |
| 1758 <function id="GetThreadInfo" num="9"> | |
| 1759 <synopsis>Get Thread Info</synopsis> | |
| 1760 <typedef id="jvmtiThreadInfo" label="Thread information structure"> | |
| 1761 <field id="name"> | |
| 1762 <allocfieldbuf><char/></allocfieldbuf> | |
| 1763 <description> | |
| 1764 The thread name, encoded as a | |
| 1765 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 1766 </description> | |
| 1767 </field> | |
| 1768 <field id="priority"> | |
| 1769 <jint/> | |
| 1770 <description> | |
| 1771 The thread priority. See the thread priority constants: | |
| 1772 <datalink id="jvmtiThreadPriority"></datalink>. | |
| 1773 </description> | |
| 1774 </field> | |
| 1775 <field id="is_daemon"> | |
| 1776 <jboolean/> | |
| 1777 <description> | |
| 1778 Is this a daemon thread? | |
| 1779 </description> | |
| 1780 </field> | |
| 1781 <field id="thread_group"> | |
| 1782 <jthreadGroup/> | |
| 1783 <description> | |
| 1784 The thread group to which this thread belongs. | |
| 1785 <code>NULL</code> if the thread has died. | |
| 1786 </description> | |
| 1787 </field> | |
| 1788 <field id="context_class_loader"> | |
| 1789 <jobject/> | |
| 1790 <description> | |
| 1791 The context class loader associated with this thread. | |
| 1792 </description> | |
| 1793 </field> | |
| 1794 </typedef> | |
| 1795 <description> | |
| 1796 Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure | |
| 1797 are filled in with details of the specified thread. | |
| 1798 </description> | |
| 1799 <origin>jvmdi</origin> | |
| 1800 <capabilities> | |
| 1801 </capabilities> | |
| 1802 <parameters> | |
| 1803 <param id="thread"> | |
| 1804 <jthread null="current" impl="noconvert" started="maybe"/> | |
| 1805 <description> | |
| 1806 The thread to query. | |
| 1807 </description> | |
| 1808 </param> | |
| 1809 <param id="info_ptr"> | |
| 1810 <outptr><struct>jvmtiThreadInfo</struct></outptr> | |
| 1811 <description> | |
| 1812 On return, filled with information describing the specified thread. | |
| 1813 <p/> | |
| 1814 For JDK 1.1 implementations that don't | |
| 1815 recognize context class loaders, | |
| 1816 the <code>context_class_loader</code> field will be NULL. | |
| 1817 </description> | |
| 1818 </param> | |
| 1819 </parameters> | |
| 1820 <errors> | |
| 1821 </errors> | |
| 1822 </function> | |
| 1823 | |
| 1824 <function id="GetOwnedMonitorInfo" num="10"> | |
| 1825 <synopsis>Get Owned Monitor Info</synopsis> | |
| 1826 <description> | |
| 1827 Get information about the monitors owned by the | |
| 1828 specified thread. | |
| 1829 </description> | |
| 1830 <origin>jvmdiClone</origin> | |
| 1831 <capabilities> | |
| 1832 <required id="can_get_owned_monitor_info"></required> | |
| 1833 </capabilities> | |
| 1834 <parameters> | |
| 1835 <param id="thread"> | |
| 1836 <jthread null="current"/> | |
| 1837 <description> | |
| 1838 The thread to query. | |
| 1839 </description> | |
| 1840 </param> | |
| 1841 <param id="owned_monitor_count_ptr"> | |
| 1842 <outptr><jint/></outptr> | |
| 1843 <description> | |
| 1844 The number of monitors returned. | |
| 1845 </description> | |
| 1846 </param> | |
| 1847 <param id="owned_monitors_ptr"> | |
| 1848 <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf> | |
| 1849 <description> | |
| 1850 The array of owned monitors. | |
| 1851 </description> | |
| 1852 </param> | |
| 1853 </parameters> | |
| 1854 <errors> | |
| 1855 </errors> | |
| 1856 </function> | |
| 1857 | |
| 1858 <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1"> | |
| 1859 <synopsis>Get Owned Monitor Stack Depth Info</synopsis> | |
| 1860 <typedef id="jvmtiMonitorStackDepthInfo" | |
| 1861 label="Monitor stack depth information structure"> | |
| 1862 <field id="monitor"> | |
| 1863 <jobject/> | |
| 1864 <description> | |
| 1865 The owned monitor. | |
| 1866 </description> | |
| 1867 </field> | |
| 1868 <field id="stack_depth"> | |
| 1869 <jint/> | |
| 1870 <description> | |
| 1871 The stack depth. Corresponds to the stack depth used in the | |
| 1872 <internallink id="stack">Stack Frame functions</internallink>. | |
| 1873 That is, zero is the current frame, one is the frame which | |
| 1874 called the current frame. And it is negative one if the | |
| 1875 implementation cannot determine the stack depth (e.g., for | |
| 1876 monitors acquired by JNI <code>MonitorEnter</code>). | |
| 1877 </description> | |
| 1878 </field> | |
| 1879 </typedef> | |
| 1880 <description> | |
| 1881 Get information about the monitors owned by the | |
| 1882 specified thread and the depth of the stack frame which locked them. | |
| 1883 </description> | |
| 1884 <origin>new</origin> | |
| 1885 <capabilities> | |
| 1886 <required id="can_get_owned_monitor_stack_depth_info"></required> | |
| 1887 </capabilities> | |
| 1888 <parameters> | |
| 1889 <param id="thread"> | |
| 1890 <jthread null="current"/> | |
| 1891 <description> | |
| 1892 The thread to query. | |
| 1893 </description> | |
| 1894 </param> | |
| 1895 <param id="monitor_info_count_ptr"> | |
| 1896 <outptr><jint/></outptr> | |
| 1897 <description> | |
| 1898 The number of monitors returned. | |
| 1899 </description> | |
| 1900 </param> | |
| 1901 <param id="monitor_info_ptr"> | |
| 1902 <allocbuf outcount="owned_monitor_depth_count_ptr"> | |
| 1903 <struct>jvmtiMonitorStackDepthInfo</struct> | |
| 1904 </allocbuf> | |
| 1905 <description> | |
| 1906 The array of owned monitor depth information. | |
| 1907 </description> | |
| 1908 </param> | |
| 1909 </parameters> | |
| 1910 <errors> | |
| 1911 </errors> | |
| 1912 </function> | |
| 1913 | |
| 1914 <function id="GetCurrentContendedMonitor" num="11"> | |
| 1915 <synopsis>Get Current Contended Monitor</synopsis> | |
| 1916 <description> | |
| 1917 Get the object, if any, whose monitor the specified thread is waiting to | |
| 1918 enter or waiting to regain through <code>java.lang.Object.wait</code>. | |
| 1919 </description> | |
| 1920 <origin>jvmdi</origin> | |
| 1921 <capabilities> | |
| 1922 <required id="can_get_current_contended_monitor"></required> | |
| 1923 </capabilities> | |
| 1924 <parameters> | |
| 1925 <param id="thread"> | |
| 1926 <jthread null="current"/> | |
| 1927 <description> | |
| 1928 The thread to query. | |
| 1929 </description> | |
| 1930 </param> | |
| 1931 <param id="monitor_ptr"> | |
| 1932 <outptr><jobject/></outptr> | |
| 1933 <description> | |
| 1934 On return, filled with the current contended monitor, or | |
| 1935 NULL if there is none. | |
| 1936 </description> | |
| 1937 </param> | |
| 1938 </parameters> | |
| 1939 <errors> | |
| 1940 </errors> | |
| 1941 </function> | |
| 1942 | |
| 1943 <callback id="jvmtiStartFunction"> | |
| 1944 <void/> | |
| 1945 <synopsis>Agent Start Function</synopsis> | |
| 1946 <description> | |
| 1947 Agent supplied callback function. | |
| 1948 This function is the entry point for an agent thread | |
| 1949 started with | |
| 1950 <functionlink id="RunAgentThread"></functionlink>. | |
| 1951 </description> | |
| 1952 <parameters> | |
| 1953 <param id="jvmti_env"> | |
| 1954 <outptr> | |
| 1955 <struct>jvmtiEnv</struct> | |
| 1956 </outptr> | |
| 1957 <description> | |
| 1958 The <jvmti/> environment. | |
| 1959 </description> | |
| 1960 </param> | |
| 1961 <param id="jni_env"> | |
| 1962 <outptr> | |
| 1963 <struct>JNIEnv</struct> | |
| 1964 </outptr> | |
| 1965 <description> | |
| 1966 The JNI environment. | |
| 1967 </description> | |
| 1968 </param> | |
| 1969 <param id="arg"> | |
| 1970 <outptr> | |
| 1971 <void/> | |
| 1972 </outptr> | |
| 1973 <description> | |
| 1974 The <code>arg</code> parameter passed to | |
| 1975 <functionlink id="RunAgentThread"></functionlink>. | |
| 1976 </description> | |
| 1977 </param> | |
| 1978 </parameters> | |
| 1979 </callback> | |
| 1980 | |
| 1981 <function id="RunAgentThread" num="12"> | |
| 1982 <synopsis>Run Agent Thread</synopsis> | |
| 1983 <description> | |
| 1984 Starts the execution of an agent thread. with the specified native function. | |
| 1985 The parameter <paramlink id="arg"></paramlink> is forwarded on to the | |
| 1986 <functionlink id="jvmtiStartFunction">start function</functionlink> | |
| 1987 (specified with <paramlink id="proc"></paramlink>) as its single argument. | |
| 1988 This function allows the creation of agent threads | |
| 1989 for handling communication with another process or for handling events | |
| 1990 without the need to load a special subclass of <code>java.lang.Thread</code> or | |
| 1991 implementer of <code>java.lang.Runnable</code>. | |
| 1992 Instead, the created thread can run entirely in native code. | |
| 1993 However, the created thread does require a newly created instance | |
| 1994 of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to | |
| 1995 which it will be associated. | |
| 1996 The thread object can be created with JNI calls. | |
| 1997 <p/> | |
| 1998 The following common thread priorities are provided for your convenience: | |
| 1999 <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const"> | |
| 2000 <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1"> | |
| 2001 Minimum possible thread priority | |
| 2002 </constant> | |
| 2003 <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5"> | |
| 2004 Normal thread priority | |
| 2005 </constant> | |
| 2006 <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10"> | |
| 2007 Maximum possible thread priority | |
| 2008 </constant> | |
| 2009 </constants> | |
| 2010 <p/> | |
| 2011 The new thread is started as a daemon thread with the specified | |
| 2012 <paramlink id="priority"></paramlink>. | |
| 2013 If enabled, a <eventlink id="ThreadStart"/> event will be sent. | |
| 2014 <p/> | |
| 2015 Since the thread has been started, the thread will be live when this function | |
| 2016 returns, unless the thread has died immediately. | |
| 2017 <p/> | |
| 2018 The thread group of the thread is ignored -- specifically, the thread is not | |
| 2019 added to the thread group and the thread is not seen on queries of the thread | |
| 2020 group at either the Java programming language or <jvmti/> levels. | |
| 2021 <p/> | |
| 2022 The thread is not visible to Java programming language queries but is | |
| 2023 included in <jvmti/> queries (for example, | |
| 2024 <functionlink id="GetAllThreads"/> and | |
| 2025 <functionlink id="GetAllStackTraces"/>). | |
| 2026 <p/> | |
| 2027 Upon execution of <code>proc</code>, the new thread will be attached to the | |
| 2028 VM--see the JNI documentation on | |
| 2029 <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/invocation.html#wp1060" | |
| 2030 >Attaching to the VM</externallink>. | |
| 2031 </description> | |
| 2032 <origin>jvmdiClone</origin> | |
| 2033 <capabilities> | |
| 2034 </capabilities> | |
| 2035 <parameters> | |
| 2036 <param id="thread"> | |
| 2037 <jthread impl="noconvert" started="no"/> | |
| 2038 <description> | |
| 2039 The thread to run. | |
| 2040 </description> | |
| 2041 </param> | |
| 2042 <param id="proc"> | |
| 2043 <ptrtype> | |
| 2044 <struct>jvmtiStartFunction</struct> | |
| 2045 </ptrtype> | |
| 2046 <description> | |
| 2047 The start function. | |
| 2048 </description> | |
| 2049 </param> | |
| 2050 <param id="arg"> | |
| 2051 <inbuf> | |
| 2052 <void/> | |
| 2053 <nullok><code>NULL</code> is passed to the start function</nullok> | |
| 2054 </inbuf> | |
| 2055 <description> | |
| 2056 The argument to the start function. | |
| 2057 </description> | |
| 2058 </param> | |
| 2059 <param id="priority"> | |
| 2060 <jint/> | |
| 2061 <description> | |
| 2062 The priority of the started thread. Any thread | |
| 2063 priority allowed by <code>java.lang.Thread.setPriority</code> can be used including | |
| 2064 those in <datalink id="jvmtiThreadPriority"></datalink>. | |
| 2065 </description> | |
| 2066 </param> | |
| 2067 </parameters> | |
| 2068 <errors> | |
| 2069 <error id="JVMTI_ERROR_INVALID_PRIORITY"> | |
| 2070 <paramlink id="priority"/> is less than | |
| 2071 <datalink id="JVMTI_THREAD_MIN_PRIORITY"/> | |
| 2072 or greater than | |
| 2073 <datalink id="JVMTI_THREAD_MAX_PRIORITY"/> | |
| 2074 </error> | |
| 2075 </errors> | |
| 2076 </function> | |
| 2077 | |
| 2078 <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103"> | |
| 2079 <synopsis>Set Thread Local Storage</synopsis> | |
| 2080 <description> | |
| 2081 The VM stores a pointer value associated with each environment-thread | |
| 2082 pair. This pointer value is called <i>thread-local storage</i>. | |
| 2083 This value is <code>NULL</code> unless set with this function. | |
| 2084 Agents can allocate memory in which they store thread specific | |
| 2085 information. By setting thread-local storage it can then be | |
| 2086 accessed with | |
| 2087 <functionlink id="GetThreadLocalStorage"></functionlink>. | |
| 2088 <p/> | |
| 2089 This function is called by the agent to set the value of the <jvmti/> | |
| 2090 thread-local storage. <jvmti/> supplies to the agent a pointer-size | |
| 2091 thread-local storage that can be used to record per-thread | |
| 2092 information. | |
| 2093 </description> | |
| 2094 <origin>jvmpi</origin> | |
| 2095 <capabilities> | |
| 2096 </capabilities> | |
| 2097 <parameters> | |
| 2098 <param id="thread"> | |
| 2099 <jthread null="current"/> | |
| 2100 <description> | |
| 2101 Store to this thread. | |
| 2102 </description> | |
| 2103 </param> | |
| 2104 <param id="data"> | |
| 2105 <inbuf> | |
| 2106 <void/> | |
| 2107 <nullok>value is set to <code>NULL</code></nullok> | |
| 2108 </inbuf> | |
| 2109 <description> | |
| 2110 The value to be entered into the thread-local storage. | |
| 2111 </description> | |
| 2112 </param> | |
| 2113 </parameters> | |
| 2114 <errors> | |
| 2115 </errors> | |
| 2116 </function> | |
| 2117 | |
| 2118 <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102"> | |
| 2119 <synopsis>Get Thread Local Storage</synopsis> | |
| 2120 <description> | |
| 2121 Called by the agent to get the value of the <jvmti/> thread-local | |
| 2122 storage. | |
| 2123 </description> | |
| 2124 <origin>jvmpi</origin> | |
| 2125 <capabilities> | |
| 2126 </capabilities> | |
| 2127 <parameters> | |
| 2128 <param id="thread"> | |
| 2129 <jthread null="current" impl="noconvert"/> | |
| 2130 <description> | |
| 2131 Retrieve from this thread. | |
| 2132 </description> | |
| 2133 </param> | |
| 2134 <param id="data_ptr"> | |
| 2135 <agentbuf><void/></agentbuf> | |
| 2136 <description> | |
| 2137 Pointer through which the value of the thread local | |
| 2138 storage is returned. | |
| 2139 If thread-local storage has not been set with | |
| 2140 <functionlink id="SetThreadLocalStorage"></functionlink> the returned | |
| 2141 pointer is <code>NULL</code>. | |
| 2142 </description> | |
| 2143 </param> | |
| 2144 </parameters> | |
| 2145 <errors> | |
| 2146 </errors> | |
| 2147 </function> | |
| 2148 | |
| 2149 </category> | |
| 2150 | |
| 2151 <category id="thread_groups" label="Thread Group"> | |
| 2152 <intro> | |
| 2153 </intro> | |
| 2154 | |
| 2155 <function id="GetTopThreadGroups" num="13"> | |
| 2156 <synopsis>Get Top Thread Groups</synopsis> | |
| 2157 <description> | |
| 2158 Return all top-level (parentless) thread groups in the VM. | |
| 2159 </description> | |
| 2160 <origin>jvmdi</origin> | |
| 2161 <capabilities> | |
| 2162 </capabilities> | |
| 2163 <parameters> | |
| 2164 <param id="group_count_ptr"> | |
| 2165 <outptr><jint/></outptr> | |
| 2166 <description> | |
| 2167 On return, points to the number of top-level thread groups. | |
| 2168 </description> | |
| 2169 </param> | |
| 2170 <param id="groups_ptr"> | |
| 2171 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> | |
| 2172 <description> | |
| 2173 On return, refers to a pointer to the top-level thread group array. | |
| 2174 </description> | |
| 2175 </param> | |
| 2176 </parameters> | |
| 2177 <errors> | |
| 2178 </errors> | |
| 2179 </function> | |
| 2180 | |
| 2181 <function id="GetThreadGroupInfo" num="14"> | |
| 2182 <synopsis>Get Thread Group Info</synopsis> | |
| 2183 <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure"> | |
| 2184 <field id="parent"> | |
| 2185 <jthreadGroup/> | |
| 2186 <description> | |
| 2187 The parent thread group. | |
| 2188 </description> | |
| 2189 </field> | |
| 2190 <field id="name"> | |
| 2191 <allocfieldbuf><char/></allocfieldbuf> | |
| 2192 <description> | |
| 2193 The thread group's name, encoded as a | |
| 2194 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 2195 </description> | |
| 2196 </field> | |
| 2197 <field id="max_priority"> | |
| 2198 <jint/> | |
| 2199 <description> | |
| 2200 The maximum priority for this thread group. | |
| 2201 </description> | |
| 2202 </field> | |
| 2203 <field id="is_daemon"> | |
| 2204 <jboolean/> | |
| 2205 <description> | |
| 2206 Is this a daemon thread group? | |
| 2207 </description> | |
| 2208 </field> | |
| 2209 </typedef> | |
| 2210 <description> | |
| 2211 Get information about the thread group. The fields of the | |
| 2212 <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure | |
| 2213 are filled in with details of the specified thread group. | |
| 2214 </description> | |
| 2215 <origin>jvmdi</origin> | |
| 2216 <capabilities> | |
| 2217 </capabilities> | |
| 2218 <parameters> | |
| 2219 <param id="group"> | |
| 2220 <jthreadGroup/> | |
| 2221 <description> | |
| 2222 The thread group to query. | |
| 2223 </description> | |
| 2224 </param> | |
| 2225 <param id="info_ptr"> | |
| 2226 <outptr><struct>jvmtiThreadGroupInfo</struct></outptr> | |
| 2227 <description> | |
| 2228 On return, filled with information describing the specified | |
| 2229 thread group. | |
| 2230 </description> | |
| 2231 </param> | |
| 2232 </parameters> | |
| 2233 <errors> | |
| 2234 </errors> | |
| 2235 </function> | |
| 2236 | |
| 2237 <function id="GetThreadGroupChildren" num="15"> | |
| 2238 <synopsis>Get Thread Group Children</synopsis> | |
| 2239 <description> | |
| 2240 Get the live threads and active subgroups in this thread group. | |
| 2241 </description> | |
| 2242 <origin>jvmdi</origin> | |
| 2243 <capabilities> | |
| 2244 </capabilities> | |
| 2245 <parameters> | |
| 2246 <param id="group"> | |
| 2247 <jthreadGroup/> | |
| 2248 <description> | |
| 2249 The group to query. | |
| 2250 </description> | |
| 2251 </param> | |
| 2252 <param id="thread_count_ptr"> | |
| 2253 <outptr><jint/></outptr> | |
| 2254 <description> | |
| 2255 On return, points to the number of live threads in this thread group. | |
| 2256 </description> | |
| 2257 </param> | |
| 2258 <param id="threads_ptr"> | |
| 2259 <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf> | |
| 2260 <description> | |
| 2261 On return, points to an array of the live threads in this thread group. | |
| 2262 </description> | |
| 2263 </param> | |
| 2264 <param id="group_count_ptr"> | |
| 2265 <outptr><jint/></outptr> | |
| 2266 <description> | |
| 2267 On return, points to the number of active child thread groups | |
| 2268 </description> | |
| 2269 </param> | |
| 2270 <param id="groups_ptr"> | |
| 2271 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> | |
| 2272 <description> | |
| 2273 On return, points to an array of the active child thread groups. | |
| 2274 </description> | |
| 2275 </param> | |
| 2276 </parameters> | |
| 2277 <errors> | |
| 2278 </errors> | |
| 2279 </function> | |
| 2280 </category> | |
| 2281 | |
| 2282 <category id="stack" label="Stack Frame"> | |
| 2283 <intro> | |
| 2284 These functions provide information about the stack of a thread. | |
| 2285 Stack frames are referenced by depth. | |
| 2286 The frame at depth zero is the current frame. | |
| 2287 <p/> | |
| 2288 Stack frames are as described in the | |
| 2289 <vmspeclink id="Overview.doc.html#17257" | |
| 2290 name="Frames section"/>. | |
| 2291 That is, they correspond to method | |
| 2292 invocations (including native methods) but do not correspond to platform native or | |
| 2293 VM internal frames. | |
| 2294 <p/> | |
| 2295 A <jvmti/> implementation may use method invocations to launch a thread and | |
| 2296 the corresponding frames may be included in the stack as presented by these functions -- | |
| 2297 that is, there may be frames shown | |
| 2298 deeper than <code>main()</code> and <code>run()</code>. | |
| 2299 However this presentation must be consistent across all <jvmti/> functionality which | |
| 2300 uses stack frames or stack depth. | |
| 2301 </intro> | |
| 2302 | |
| 2303 <typedef id="jvmtiFrameInfo" label="Stack frame information structure"> | |
| 2304 <description> | |
| 2305 Information about a stack frame is returned in this structure. | |
| 2306 </description> | |
| 2307 <field id="method"> | |
| 2308 <jmethodID/> | |
| 2309 <description> | |
| 2310 The method executing in this frame. | |
| 2311 </description> | |
| 2312 </field> | |
| 2313 <field id="location"> | |
| 2314 <jlocation/> | |
| 2315 <description> | |
| 2316 The index of the instruction executing in this frame. | |
| 2317 <code>-1</code> if the frame is executing a native method. | |
| 2318 </description> | |
| 2319 </field> | |
| 2320 </typedef> | |
| 2321 | |
| 2322 <typedef id="jvmtiStackInfo" label="Stack information structure"> | |
| 2323 <description> | |
| 2324 Information about a set of stack frames is returned in this structure. | |
| 2325 </description> | |
| 2326 <field id="thread"> | |
| 2327 <jthread/> | |
| 2328 <description> | |
| 2329 On return, the thread traced. | |
| 2330 </description> | |
| 2331 </field> | |
| 2332 <field id="state"> | |
| 2333 <jint/> | |
| 2334 <description> | |
| 2335 On return, the thread state. See <functionlink id="GetThreadState"></functionlink>. | |
| 2336 </description> | |
| 2337 </field> | |
| 2338 <field id="frame_buffer"> | |
| 2339 <outbuf incount="max_frame_count"> | |
| 2340 <struct>jvmtiFrameInfo</struct> | |
| 2341 </outbuf> | |
| 2342 <description> | |
| 2343 On return, this agent allocated buffer is filled | |
| 2344 with stack frame information. | |
| 2345 </description> | |
| 2346 </field> | |
| 2347 <field id="frame_count"> | |
| 2348 <jint/> | |
| 2349 <description> | |
| 2350 On return, the number of records filled into | |
| 2351 <code>frame_buffer</code>. | |
| 2352 This will be | |
| 2353 min(<code>max_frame_count</code>, <i>stackDepth</i>). | |
| 2354 </description> | |
| 2355 </field> | |
| 2356 </typedef> | |
| 2357 | |
| 2358 <function id="GetStackTrace" num="104"> | |
| 2359 <synopsis>Get Stack Trace</synopsis> | |
| 2360 <description> | |
| 2361 Get information about the stack of a thread. | |
| 2362 If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack, | |
| 2363 the <paramlink id="max_frame_count"></paramlink> topmost frames are returned, | |
| 2364 otherwise the entire stack is returned. | |
| 2365 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
| 2366 <p/> | |
| 2367 The following example causes up to five of the topmost frames | |
| 2368 to be returned and (if there are any frames) the currently | |
| 2369 executing method name to be printed. | |
| 2370 <example> | |
| 2371 jvmtiFrameInfo frames[5]; | |
| 2372 jint count; | |
| 2373 jvmtiError err; | |
| 2374 | |
| 2375 err = (*jvmti)->GetStackTrace(jvmti, aThread, 0, 5, | |
| 2376 &frames, &count); | |
| 2377 if (err == JVMTI_ERROR_NONE && count >= 1) { | |
| 2378 char *methodName; | |
| 2379 err = (*jvmti)->GetMethodName(jvmti, frames[0].method, | |
| 2380 &methodName, NULL); | |
| 2381 if (err == JVMTI_ERROR_NONE) { | |
| 2382 printf("Executing method: %s", methodName); | |
| 2383 } | |
| 2384 } | |
| 2385 </example> | |
| 2386 <todo> | |
| 2387 check example code. | |
| 2388 </todo> | |
| 2389 <p/> | |
| 2390 The <paramlink id="thread"></paramlink> need not be suspended | |
| 2391 to call this function. | |
| 2392 <p/> | |
| 2393 The <functionlink id="GetLineNumberTable"></functionlink> | |
| 2394 function can be used to map locations to line numbers. Note that | |
| 2395 this mapping can be done lazily. | |
| 2396 </description> | |
| 2397 <origin>jvmpi</origin> | |
| 2398 <capabilities> | |
| 2399 </capabilities> | |
| 2400 <parameters> | |
| 2401 <param id="thread"> | |
| 2402 <jthread null="current"/> | |
| 2403 <description> | |
| 2404 Fetch the stack trace of this thread. | |
| 2405 </description> | |
| 2406 </param> | |
| 2407 <param id="start_depth"> | |
| 2408 <jint/> | |
| 2409 <description> | |
| 2410 Begin retrieving frames at this depth. | |
| 2411 If non-negative, count from the current frame, | |
| 2412 the first frame retrieved is at depth <code>start_depth</code>. | |
| 2413 For example, if zero, start from the current frame; if one, start from the | |
| 2414 caller of the current frame; if two, start from the caller of the | |
| 2415 caller of the current frame; and so on. | |
| 2416 If negative, count from below the oldest frame, | |
| 2417 the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>, | |
| 2418 where <i>stackDepth</i> is the count of frames on the stack. | |
| 2419 For example, if negative one, only the oldest frame is retrieved; | |
| 2420 if negative two, start from the frame called by the oldest frame. | |
| 2421 </description> | |
| 2422 </param> | |
| 2423 <param id="max_frame_count"> | |
| 2424 <jint min="0"/> | |
| 2425 <description> | |
| 2426 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. | |
| 2427 </description> | |
| 2428 </param> | |
| 2429 <param id="frame_buffer"> | |
| 2430 <outbuf incount="max_frame_count" outcount="count_ptr"> | |
| 2431 <struct>jvmtiFrameInfo</struct> | |
| 2432 </outbuf> | |
| 2433 <description> | |
| 2434 On return, this agent allocated buffer is filled | |
| 2435 with stack frame information. | |
| 2436 </description> | |
| 2437 </param> | |
| 2438 <param id="count_ptr"> | |
| 2439 <outptr><jint/></outptr> | |
| 2440 <description> | |
| 2441 On return, points to the number of records filled in. | |
| 2442 For non-negative <code>start_depth</code>, this will be | |
| 2443 min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>). | |
| 2444 For negative <code>start_depth</code>, this will be | |
| 2445 min(<code>max_frame_count</code>, <code>-start_depth</code>). | |
| 2446 </description> | |
| 2447 </param> | |
| 2448 </parameters> | |
| 2449 <errors> | |
| 2450 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 2451 <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>. | |
| 2452 Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>. | |
| 2453 </error> | |
| 2454 </errors> | |
| 2455 </function> | |
| 2456 | |
| 2457 | |
| 2458 <function id="GetAllStackTraces" num="100"> | |
| 2459 <synopsis>Get All Stack Traces</synopsis> | |
| 2460 <description> | |
| 2461 Get information about the stacks of all live threads | |
| 2462 (including <internallink id="RunAgentThread">agent threads</internallink>). | |
| 2463 If <paramlink id="max_frame_count"/> is less than the depth of a stack, | |
| 2464 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, | |
| 2465 otherwise the entire stack is returned. | |
| 2466 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
| 2467 <p/> | |
| 2468 All stacks are collected simultaneously, that is, no changes will occur to the | |
| 2469 thread state or stacks between the sampling of one thread and the next. | |
| 2470 The threads need not be suspended. | |
| 2471 | |
| 2472 <example> | |
| 2473 jvmtiStackInfo *stack_info; | |
| 2474 jint thread_count; | |
| 2475 int ti; | |
| 2476 jvmtiError err; | |
| 2477 | |
| 2478 err = (*jvmti)->GetAllStackTraces(jvmti, MAX_FRAMES, &stack_info, &thread_count); | |
| 2479 if (err != JVMTI_ERROR_NONE) { | |
| 2480 ... | |
| 2481 } | |
| 2482 for (ti = 0; ti < thread_count; ++ti) { | |
| 2483 jvmtiStackInfo *infop = &stack_info[ti]; | |
| 2484 jthread thread = infop->thread; | |
| 2485 jint state = infop->state; | |
| 2486 jvmtiFrameInfo *frames = infop->frame_buffer; | |
| 2487 int fi; | |
| 2488 | |
| 2489 myThreadAndStatePrinter(thread, state); | |
| 2490 for (fi = 0; fi < infop->frame_count; fi++) { | |
| 2491 myFramePrinter(frames[fi].method, frames[fi].location); | |
| 2492 } | |
| 2493 } | |
| 2494 /* this one Deallocate call frees all data allocated by GetAllStackTraces */ | |
| 2495 err = (*jvmti)->Deallocate(jvmti, stack_info); | |
| 2496 </example> | |
| 2497 <todo> | |
| 2498 check example code. | |
| 2499 </todo> | |
| 2500 | |
| 2501 </description> | |
| 2502 <origin>new</origin> | |
| 2503 <capabilities> | |
| 2504 </capabilities> | |
| 2505 <parameters> | |
| 2506 <param id="max_frame_count"> | |
| 2507 <jint min="0"/> | |
| 2508 <description> | |
| 2509 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. | |
| 2510 </description> | |
| 2511 </param> | |
| 2512 <param id="stack_info_ptr"> | |
| 2513 <allocbuf> | |
| 2514 <struct>jvmtiStackInfo</struct> | |
| 2515 </allocbuf> | |
| 2516 <description> | |
| 2517 On return, this buffer is filled | |
| 2518 with stack information for each thread. | |
| 2519 The number of <datalink id="jvmtiStackInfo"/> records is determined | |
| 2520 by <paramlink id="thread_count_ptr"/>. | |
| 2521 <p/> | |
| 2522 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> | |
| 2523 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. | |
| 2524 These buffers must not be separately deallocated. | |
| 2525 </description> | |
| 2526 </param> | |
| 2527 <param id="thread_count_ptr"> | |
| 2528 <outptr><jint/></outptr> | |
| 2529 <description> | |
| 2530 The number of threads traced. | |
| 2531 </description> | |
| 2532 </param> | |
| 2533 </parameters> | |
| 2534 <errors> | |
| 2535 </errors> | |
| 2536 </function> | |
| 2537 | |
| 2538 <function id="GetThreadListStackTraces" num="101"> | |
| 2539 <synopsis>Get Thread List Stack Traces</synopsis> | |
| 2540 <description> | |
| 2541 Get information about the stacks of the supplied threads. | |
| 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 one thread and the next. | |
| 2549 The threads need not be suspended. | |
| 2550 <p/> | |
| 2551 If a thread has not yet started or terminates before the stack information is collected, | |
| 2552 a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero) | |
| 2553 will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked. | |
| 2554 <p/> | |
| 2555 See the example for the similar function | |
| 2556 <functionlink id="GetAllStackTraces"/>. | |
| 2557 </description> | |
| 2558 <origin>new</origin> | |
| 2559 <capabilities> | |
| 2560 </capabilities> | |
| 2561 <parameters> | |
| 2562 <param id="thread_count"> | |
| 2563 <jint min="0"/> | |
| 2564 <description> | |
| 2565 The number of threads to trace. | |
| 2566 </description> | |
| 2567 </param> | |
| 2568 <param id="thread_list"> | |
| 2569 <inbuf incount="thread_count"><jthread/></inbuf> | |
| 2570 <description> | |
| 2571 The list of threads to trace. | |
| 2572 </description> | |
| 2573 </param> | |
| 2574 <param id="max_frame_count"> | |
| 2575 <jint min="0"/> | |
| 2576 <description> | |
| 2577 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. | |
| 2578 </description> | |
| 2579 </param> | |
| 2580 <param id="stack_info_ptr"> | |
| 2581 <allocbuf outcount="thread_count"> | |
| 2582 <struct>jvmtiStackInfo</struct> | |
| 2583 </allocbuf> | |
| 2584 <description> | |
| 2585 On return, this buffer is filled | |
| 2586 with stack information for each thread. | |
| 2587 The number of <datalink id="jvmtiStackInfo"/> records is determined | |
| 2588 by <paramlink id="thread_count"/>. | |
| 2589 <p/> | |
| 2590 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> | |
| 2591 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. | |
| 2592 These buffers must not be separately deallocated. | |
| 2593 </description> | |
| 2594 </param> | |
| 2595 </parameters> | |
| 2596 <errors> | |
| 2597 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
| 2598 An element in <paramlink id="thread_list"/> is not a thread object. | |
| 2599 </error> | |
| 2600 </errors> | |
| 2601 </function> | |
| 2602 | |
| 2603 <elide> | |
| 2604 <function id="AsyncGetStackTrace" num="1000"> | |
| 2605 <synopsis>Get Stack Trace--Asynchronous</synopsis> | |
| 2606 <description> | |
| 2607 Get information about the entire stack of a thread (or a sub-section of it). | |
| 2608 This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink> | |
| 2609 and is reentrant and safe to call | |
| 2610 from asynchronous signal handlers. | |
| 2611 The stack trace is returned only for the calling thread. | |
| 2612 <p/> | |
| 2613 The <functionlink id="GetLineNumberTable"></functionlink> | |
| 2614 function can be used to map locations to line numbers. Note that | |
| 2615 this mapping can be done lazily. | |
| 2616 </description> | |
| 2617 <origin>jvmpi</origin> | |
| 2618 <capabilities> | |
| 2619 <required id="can_get_async_stack_trace"></required> | |
| 2620 <capability id="can_show_JVM_spec_async_frames"> | |
| 2621 If <code>false</code>, | |
| 2622 <paramlink id="use_java_stack"></paramlink> | |
| 2623 must be <code>false</code>. | |
| 2624 </capability> | |
| 2625 </capabilities> | |
| 2626 <parameters> | |
| 2627 <param id="use_java_stack"> | |
| 2628 <jboolean/> | |
| 2629 <description> | |
| 2630 Return the stack showing the <vmspeclink/> | |
| 2631 model of the stack; | |
| 2632 otherwise, show the internal representation of the stack with | |
| 2633 inlined and optimized methods missing. If the virtual machine | |
| 2634 is using the <i>Java Virtual Machine Specification</i> stack model | |
| 2635 internally, this flag is ignored. | |
| 2636 </description> | |
| 2637 </param> | |
| 2638 <param id="max_count"> | |
| 2639 <jint min="0"/> | |
| 2640 <description> | |
| 2641 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. | |
| 2642 Retrieve this many unless the stack depth is less than <code>max_count</code>. | |
| 2643 </description> | |
| 2644 </param> | |
| 2645 <param id="frame_buffer"> | |
| 2646 <outbuf incount="max_count" outcount="count_ptr"> | |
| 2647 <struct>jvmtiFrameInfo</struct> | |
| 2648 <nullok>this information is not returned</nullok> | |
| 2649 </outbuf> | |
| 2650 <description> | |
| 2651 The agent passes in a buffer | |
| 2652 large enough to hold <code>max_count</code> records of | |
| 2653 <datalink id="jvmtiFrameInfo"></datalink>. This buffer must be | |
| 2654 pre-allocated by the agent. | |
| 2655 </description> | |
| 2656 </param> | |
| 2657 <param id="count_ptr"> | |
| 2658 <outptr><jint/></outptr> | |
| 2659 <description> | |
| 2660 On return, points to the number of records filled in.. | |
| 2661 </description> | |
| 2662 </param> | |
| 2663 </parameters> | |
| 2664 <errors> | |
| 2665 <error id="JVMTI_ERROR_UNATTACHED_THREAD"> | |
| 2666 The thread being used to call this function is not attached | |
| 2667 to the virtual machine. Calls must be made from attached threads. | |
| 2668 </error> | |
| 2669 </errors> | |
| 2670 </function> | |
| 2671 </elide> | |
| 2672 | |
| 2673 <function id="GetFrameCount" num="16"> | |
| 2674 <synopsis>Get Frame Count</synopsis> | |
| 2675 <description> | |
| 2676 Get the number of frames currently in the specified thread's call stack. | |
| 2677 <p/> | |
| 2678 If this function is called for a thread actively executing bytecodes (for example, | |
| 2679 not the current thread and not suspended), the information returned is transient. | |
| 2680 </description> | |
| 2681 <origin>jvmdi</origin> | |
| 2682 <capabilities> | |
| 2683 </capabilities> | |
| 2684 <parameters> | |
| 2685 <param id="thread"> | |
| 2686 <jthread null="current"/> | |
| 2687 <description> | |
| 2688 The thread to query. | |
| 2689 </description> | |
| 2690 </param> | |
| 2691 <param id="count_ptr"> | |
| 2692 <outptr><jint/></outptr> | |
| 2693 <description> | |
| 2694 On return, points to the number of frames in the call stack. | |
| 2695 </description> | |
| 2696 </param> | |
| 2697 </parameters> | |
| 2698 <errors> | |
| 2699 </errors> | |
| 2700 </function> | |
| 2701 | |
| 2702 <function id="PopFrame" num="80"> | |
| 2703 <synopsis>Pop Frame</synopsis> | |
| 2704 <description> | |
| 2705 Pop the current frame of <code>thread</code>'s stack. | |
| 2706 Popping a frame takes you to the previous frame. | |
| 2707 When the thread is resumed, the execution | |
| 2708 state of the thread is reset to the state | |
| 2709 immediately before the called method was invoked. | |
| 2710 That is (using the <vmspeclink/> terminology): | |
| 2711 <ul> | |
| 2712 <li>the current frame is discarded as the previous frame becomes the current one</li> | |
| 2713 <li>the operand stack is restored--the argument values are added back | |
| 2714 and if the invoke was not <code>invokestatic</code>, | |
| 2715 <code>objectref</code> is added back as well</li> | |
| 2716 <li>the Java virtual machine PC is restored to the opcode | |
| 2717 of the invoke instruction</li> | |
| 2718 </ul> | |
| 2719 Note however, that any changes to the arguments, which | |
| 2720 occurred in the called method, remain; | |
| 2721 when execution continues, the first instruction to | |
| 2722 execute will be the invoke. | |
| 2723 <p/> | |
| 2724 Between calling <code>PopFrame</code> and resuming the | |
| 2725 thread the state of the stack is undefined. | |
| 2726 To pop frames beyond the first, | |
| 2727 these three steps must be repeated: | |
| 2728 <ul> | |
| 2729 <li>suspend the thread via an event (step, breakpoint, ...)</li> | |
| 2730 <li>call <code>PopFrame</code></li> | |
| 2731 <li>resume the thread</li> | |
| 2732 </ul> | |
| 2733 <p/> | |
| 2734 A lock acquired by calling the called method | |
| 2735 (if it is a <code>synchronized</code> method) | |
| 2736 and locks acquired by entering <code>synchronized</code> | |
| 2737 blocks within the called method are released. | |
| 2738 Note: this does not apply to native locks or | |
| 2739 <code>java.util.concurrent.locks</code> locks. | |
| 2740 <p/> | |
| 2741 Finally blocks are not executed. | |
| 2742 <p/> | |
| 2743 Changes to global state are not addressed and thus remain changed. | |
| 2744 <p/> | |
| 2745 The specified thread must be suspended (which implies it cannot be the current thread). | |
| 2746 <p/> | |
| 2747 Both the called method and calling method must be non-native Java programming | |
| 2748 language methods. | |
| 2749 <p/> | |
| 2750 No <jvmti/> events are generated by this function. | |
| 2751 </description> | |
| 2752 <origin>jvmdi</origin> | |
| 2753 <capabilities> | |
| 2754 <required id="can_pop_frame"></required> | |
| 2755 </capabilities> | |
| 2756 <parameters> | |
| 2757 <param id="thread"> | |
| 2758 <jthread/> | |
| 2759 <description> | |
| 2760 The thread whose current frame is to be popped. | |
| 2761 </description> | |
| 2762 </param> | |
| 2763 </parameters> | |
| 2764 <errors> | |
| 2765 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2766 Called or calling method is a native method. | |
| 2767 The implementation is unable to pop this frame. | |
| 2768 </error> | |
| 2769 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 2770 Thread was not suspended. | |
| 2771 </error> | |
| 2772 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 2773 There are less than two stack frames on the call stack. | |
| 2774 </error> | |
| 2775 </errors> | |
| 2776 </function> | |
| 2777 | |
| 2778 <function id="GetFrameLocation" num="19"> | |
| 2779 <synopsis>Get Frame Location</synopsis> | |
| 2780 <description> | |
| 2781 <p/> | |
| 2782 For a Java programming language frame, return the location of the instruction | |
| 2783 currently executing. | |
| 2784 </description> | |
| 2785 <origin>jvmdiClone</origin> | |
| 2786 <capabilities> | |
| 2787 </capabilities> | |
| 2788 <parameters> | |
| 2789 <param id="thread"> | |
| 2790 <jthread null="current" frame="frame"/> | |
| 2791 <description> | |
| 2792 The thread of the frame to query. | |
| 2793 </description> | |
| 2794 </param> | |
| 2795 <param id="depth"> | |
| 2796 <jframeID thread="thread"/> | |
| 2797 <description> | |
| 2798 The depth of the frame to query. | |
| 2799 </description> | |
| 2800 </param> | |
| 2801 <param id="method_ptr"> | |
| 2802 <outptr><jmethodID/></outptr> | |
| 2803 <description> | |
| 2804 On return, points to the method for the current location. | |
| 2805 </description> | |
| 2806 </param> | |
| 2807 <param id="location_ptr"> | |
| 2808 <outptr><jlocation/></outptr> | |
| 2809 <description> | |
| 2810 On return, points to the index of the currently | |
| 2811 executing instruction. | |
| 2812 Is set to <code>-1</code> if the frame is executing | |
| 2813 a native method. | |
| 2814 </description> | |
| 2815 </param> | |
| 2816 </parameters> | |
| 2817 <errors> | |
| 2818 </errors> | |
| 2819 </function> | |
| 2820 | |
| 2821 <function id="NotifyFramePop" num="20"> | |
| 2822 <synopsis>Notify Frame Pop</synopsis> | |
| 2823 <description> | |
| 2824 When the frame that is currently at <paramlink id="depth"></paramlink> | |
| 2825 is popped from the stack, generate a | |
| 2826 <eventlink id="FramePop"></eventlink> event. See the | |
| 2827 <eventlink id="FramePop"></eventlink> event for details. | |
| 2828 Only frames corresponding to non-native Java programming language | |
| 2829 methods can receive notification. | |
| 2830 <p/> | |
| 2831 The specified thread must either be the current thread | |
| 2832 or the thread must be suspended. | |
| 2833 </description> | |
| 2834 <origin>jvmdi</origin> | |
| 2835 <capabilities> | |
| 2836 <required id="can_generate_frame_pop_events"></required> | |
| 2837 </capabilities> | |
| 2838 <parameters> | |
| 2839 <param id="thread"> | |
| 2840 <jthread null="current" frame="depth"/> | |
| 2841 <description> | |
| 2842 The thread of the frame for which the frame pop event will be generated. | |
| 2843 </description> | |
| 2844 </param> | |
| 2845 <param id="depth"> | |
| 2846 <jframeID thread="thread"/> | |
| 2847 <description> | |
| 2848 The depth of the frame for which the frame pop event will be generated. | |
| 2849 </description> | |
| 2850 </param> | |
| 2851 </parameters> | |
| 2852 <errors> | |
| 2853 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2854 The frame at <code>depth</code> is executing a | |
| 2855 native method. | |
| 2856 </error> | |
| 2857 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 2858 Thread was not suspended and was not the current thread. | |
| 2859 </error> | |
| 2860 </errors> | |
| 2861 </function> | |
| 2862 | |
| 2863 </category> | |
| 2864 | |
| 2865 <category id="ForceEarlyReturn" label="Force Early Return"> | |
| 2866 <intro> | |
| 2867 These functions allow an agent to force a method | |
| 2868 to return at any point during its execution. | |
| 2869 The method which will return early is referred to as the <i>called method</i>. | |
| 2870 The called method is the current method | |
| 2871 (as defined by the | |
| 2872 <vmspeclink id="Overview.doc.html#17257" | |
| 2873 name="Frames section"/>) | |
| 2874 for the specified thread at | |
| 2875 the time the function is called. | |
| 2876 <p/> | |
| 2877 The specified thread must be suspended or must be the current thread. | |
| 2878 The return occurs when execution of Java programming | |
| 2879 language code is resumed on this thread. | |
| 2880 Between calling one of these functions and resumption | |
| 2881 of thread execution, the state of the stack is undefined. | |
| 2882 <p/> | |
| 2883 No further instructions are executed in the called method. | |
| 2884 Specifically, finally blocks are not executed. | |
| 2885 Note: this can cause inconsistent states in the application. | |
| 2886 <p/> | |
| 2887 A lock acquired by calling the called method | |
| 2888 (if it is a <code>synchronized</code> method) | |
| 2889 and locks acquired by entering <code>synchronized</code> | |
| 2890 blocks within the called method are released. | |
| 2891 Note: this does not apply to native locks or | |
| 2892 <code>java.util.concurrent.locks</code> locks. | |
| 2893 <p/> | |
| 2894 Events, such as <eventlink id="MethodExit"></eventlink>, | |
| 2895 are generated as they would be in a normal return. | |
| 2896 <p/> | |
| 2897 The called method must be a non-native Java programming | |
| 2898 language method. | |
| 2899 Forcing return on a thread with only one frame on the | |
| 2900 stack causes the thread to exit when resumed. | |
| 2901 </intro> | |
| 2902 | |
| 2903 <function id="ForceEarlyReturnObject" num="81" since="1.1"> | |
| 2904 <synopsis>Force Early Return - Object</synopsis> | |
| 2905 <description> | |
| 2906 This function can be used to return from a method whose | |
| 2907 result type is <code>Object</code> | |
| 2908 or a subclass of <code>Object</code>. | |
| 2909 </description> | |
| 2910 <origin>new</origin> | |
| 2911 <capabilities> | |
| 2912 <required id="can_force_early_return"></required> | |
| 2913 </capabilities> | |
| 2914 <parameters> | |
| 2915 <param id="thread"> | |
| 2916 <jthread null="current"/> | |
| 2917 <description> | |
| 2918 The thread whose current frame is to return early. | |
| 2919 </description> | |
| 2920 </param> | |
| 2921 <param id="value"> | |
| 2922 <jobject/> | |
| 2923 <description> | |
| 2924 The return value for the called frame. | |
| 2925 An object or <code>NULL</code>. | |
| 2926 </description> | |
| 2927 </param> | |
| 2928 </parameters> | |
| 2929 <errors> | |
| 2930 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2931 Attempted to return early from a frame | |
| 2932 corresponding to a native method. | |
| 2933 Or the implementation is unable to provide | |
| 2934 this functionality on this frame. | |
| 2935 </error> | |
| 2936 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 2937 The result type of the called method is not | |
| 2938 <code>Object</code> or a subclass of <code>Object</code>. | |
| 2939 </error> | |
| 2940 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 2941 The supplied <paramlink id="value"/> is not compatible with the | |
| 2942 result type of the called method. | |
| 2943 </error> | |
| 2944 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 2945 Thread was not the current thread and was not suspended. | |
| 2946 </error> | |
| 2947 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 2948 There are no more frames on the call stack. | |
| 2949 </error> | |
| 2950 </errors> | |
| 2951 </function> | |
| 2952 | |
| 2953 <function id="ForceEarlyReturnInt" num="82" since="1.1"> | |
| 2954 <synopsis>Force Early Return - Int</synopsis> | |
| 2955 <description> | |
| 2956 This function can be used to return from a method whose | |
| 2957 result type is <code>int</code>, <code>short</code>, | |
| 2958 <code>char</code>, <code>byte</code>, or | |
| 2959 <code>boolean</code>. | |
| 2960 </description> | |
| 2961 <origin>new</origin> | |
| 2962 <capabilities> | |
| 2963 <required id="can_force_early_return"></required> | |
| 2964 </capabilities> | |
| 2965 <parameters> | |
| 2966 <param id="thread"> | |
| 2967 <jthread null="current"/> | |
| 2968 <description> | |
| 2969 The thread whose current frame is to return early. | |
| 2970 </description> | |
| 2971 </param> | |
| 2972 <param id="value"> | |
| 2973 <jint/> | |
| 2974 <description> | |
| 2975 The return value for the called frame. | |
| 2976 </description> | |
| 2977 </param> | |
| 2978 </parameters> | |
| 2979 <errors> | |
| 2980 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2981 Attempted to return early from a frame | |
| 2982 corresponding to a native method. | |
| 2983 Or the implementation is unable to provide | |
| 2984 this functionality on this frame. | |
| 2985 </error> | |
| 2986 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 2987 The result type of the called method is not | |
| 2988 <code>int</code>, <code>short</code>, | |
| 2989 <code>char</code>, <code>byte</code>, or | |
| 2990 <code>boolean</code>. | |
| 2991 </error> | |
| 2992 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 2993 Thread was not the current thread and was not suspended. | |
| 2994 </error> | |
| 2995 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 2996 There are no frames on the call stack. | |
| 2997 </error> | |
| 2998 </errors> | |
| 2999 </function> | |
| 3000 | |
| 3001 <function id="ForceEarlyReturnLong" num="83" since="1.1"> | |
| 3002 <synopsis>Force Early Return - Long</synopsis> | |
| 3003 <description> | |
| 3004 This function can be used to return from a method whose | |
| 3005 result type is <code>long</code>. | |
| 3006 </description> | |
| 3007 <origin>new</origin> | |
| 3008 <capabilities> | |
| 3009 <required id="can_force_early_return"></required> | |
| 3010 </capabilities> | |
| 3011 <parameters> | |
| 3012 <param id="thread"> | |
| 3013 <jthread null="current"/> | |
| 3014 <description> | |
| 3015 The thread whose current frame is to return early. | |
| 3016 </description> | |
| 3017 </param> | |
| 3018 <param id="value"> | |
| 3019 <jlong/> | |
| 3020 <description> | |
| 3021 The return value for the called frame. | |
| 3022 </description> | |
| 3023 </param> | |
| 3024 </parameters> | |
| 3025 <errors> | |
| 3026 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3027 Attempted to return early from a frame | |
| 3028 corresponding to a native method. | |
| 3029 Or the implementation is unable to provide | |
| 3030 this functionality on this frame. | |
| 3031 </error> | |
| 3032 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3033 The result type of the called method is not <code>long</code>. | |
| 3034 </error> | |
| 3035 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3036 Thread was not the current thread and was not suspended. | |
| 3037 </error> | |
| 3038 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3039 There are no frames on the call stack. | |
| 3040 </error> | |
| 3041 </errors> | |
| 3042 </function> | |
| 3043 | |
| 3044 <function id="ForceEarlyReturnFloat" num="84" since="1.1"> | |
| 3045 <synopsis>Force Early Return - Float</synopsis> | |
| 3046 <description> | |
| 3047 This function can be used to return from a method whose | |
| 3048 result type is <code>float</code>. | |
| 3049 </description> | |
| 3050 <origin>new</origin> | |
| 3051 <capabilities> | |
| 3052 <required id="can_force_early_return"></required> | |
| 3053 </capabilities> | |
| 3054 <parameters> | |
| 3055 <param id="thread"> | |
| 3056 <jthread null="current"/> | |
| 3057 <description> | |
| 3058 The thread whose current frame is to return early. | |
| 3059 </description> | |
| 3060 </param> | |
| 3061 <param id="value"> | |
| 3062 <jfloat/> | |
| 3063 <description> | |
| 3064 The return value for the called frame. | |
| 3065 </description> | |
| 3066 </param> | |
| 3067 </parameters> | |
| 3068 <errors> | |
| 3069 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3070 Attempted to return early from a frame | |
| 3071 corresponding to a native method. | |
| 3072 Or the implementation is unable to provide | |
| 3073 this functionality on this frame. | |
| 3074 </error> | |
| 3075 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3076 The result type of the called method is not <code>float</code>. | |
| 3077 </error> | |
| 3078 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3079 Thread was not the current thread and was not suspended. | |
| 3080 </error> | |
| 3081 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3082 There are no frames on the call stack. | |
| 3083 </error> | |
| 3084 </errors> | |
| 3085 </function> | |
| 3086 | |
| 3087 <function id="ForceEarlyReturnDouble" num="85" since="1.1"> | |
| 3088 <synopsis>Force Early Return - Double</synopsis> | |
| 3089 <description> | |
| 3090 This function can be used to return from a method whose | |
| 3091 result type is <code>double</code>. | |
| 3092 </description> | |
| 3093 <origin>new</origin> | |
| 3094 <capabilities> | |
| 3095 <required id="can_force_early_return"></required> | |
| 3096 </capabilities> | |
| 3097 <parameters> | |
| 3098 <param id="thread"> | |
| 3099 <jthread null="current"/> | |
| 3100 <description> | |
| 3101 The thread whose current frame is to return early. | |
| 3102 </description> | |
| 3103 </param> | |
| 3104 <param id="value"> | |
| 3105 <jdouble/> | |
| 3106 <description> | |
| 3107 The return value for the called frame. | |
| 3108 </description> | |
| 3109 </param> | |
| 3110 </parameters> | |
| 3111 <errors> | |
| 3112 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3113 Attempted to return early from a frame corresponding to a native method. | |
| 3114 Or the implementation is unable to provide this functionality on this frame. | |
| 3115 </error> | |
| 3116 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3117 The result type of the called method is not <code>double</code>. | |
| 3118 </error> | |
| 3119 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3120 Thread was not the current thread and was not suspended. | |
| 3121 </error> | |
| 3122 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3123 There are no frames on the call stack. | |
| 3124 </error> | |
| 3125 </errors> | |
| 3126 </function> | |
| 3127 | |
| 3128 <function id="ForceEarlyReturnVoid" num="86" since="1.1"> | |
| 3129 <synopsis>Force Early Return - Void</synopsis> | |
| 3130 <description> | |
| 3131 This function can be used to return from a method with no result type. | |
| 3132 That is, the called method must be declared <code>void</code>. | |
| 3133 </description> | |
| 3134 <origin>new</origin> | |
| 3135 <capabilities> | |
| 3136 <required id="can_force_early_return"></required> | |
| 3137 </capabilities> | |
| 3138 <parameters> | |
| 3139 <param id="thread"> | |
| 3140 <jthread null="current"/> | |
| 3141 <description> | |
| 3142 The thread whose current frame is to return early. | |
| 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 called method has a result type. | |
| 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 </category> | |
| 3166 | |
| 3167 <category id="Heap" label="Heap"> | |
| 3168 <intro> | |
| 3169 These functions are used to analyze the heap. | |
| 3170 Functionality includes the ability to view the objects in the | |
| 3171 heap and to tag these objects. | |
| 3172 </intro> | |
| 3173 | |
| 3174 <intro id="objectTags" label="Object Tags"> | |
| 3175 A <i>tag</i> is a value associated with an object. | |
| 3176 Tags are explicitly set by the agent using the | |
| 3177 <functionlink id="SetTag"></functionlink> function or by | |
| 3178 callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>. | |
| 3179 <p/> | |
| 3180 Tags are local to the environment; that is, the tags of one | |
| 3181 environment are not visible in another. | |
| 3182 <p/> | |
| 3183 Tags are <code>jlong</code> values which can be used | |
| 3184 simply to mark an object or to store a pointer to more detailed | |
| 3185 information. Objects which have not been tagged have a | |
| 3186 tag of zero. | |
| 3187 Setting a tag to zero makes the object untagged. | |
| 3188 </intro> | |
| 3189 | |
| 3190 <intro id="heapCallbacks" label="Heap Callback Functions"> | |
| 3191 Heap functions which iterate through the heap and recursively | |
| 3192 follow object references use agent supplied callback functions | |
| 3193 to deliver the information. | |
| 3194 <p/> | |
| 3195 These heap callback functions must adhere to the following restrictions -- | |
| 3196 These callbacks must not use JNI functions. | |
| 3197 These callbacks must not use <jvmti/> functions except | |
| 3198 <i>callback safe</i> functions which | |
| 3199 specifically allow such use (see the raw monitor, memory management, | |
| 3200 and environment local storage functions). | |
| 3201 <p/> | |
| 3202 An implementation may invoke a callback on an internal thread or | |
| 3203 the thread which called the iteration function. | |
| 3204 Heap callbacks are single threaded -- no more than one callback will | |
| 3205 be invoked at a time. | |
| 3206 <p/> | |
| 3207 The Heap Filter Flags can be used to prevent reporting | |
| 3208 based on the tag status of an object or its class. | |
| 3209 If no flags are set (the <code>jint</code> is zero), objects | |
| 3210 will not be filtered out. | |
| 3211 | |
| 3212 <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits"> | |
| 3213 <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4"> | |
| 3214 Filter out tagged objects. Objects which are tagged are not included. | |
| 3215 </constant> | |
| 3216 <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8"> | |
| 3217 Filter out untagged objects. Objects which are not tagged are not included. | |
| 3218 </constant> | |
| 3219 <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10"> | |
| 3220 Filter out objects with tagged classes. Objects whose class is tagged are not included. | |
| 3221 </constant> | |
| 3222 <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20"> | |
| 3223 Filter out objects with untagged classes. Objects whose class is not tagged are not included. | |
| 3224 </constant> | |
| 3225 </constants> | |
| 3226 | |
| 3227 <p/> | |
| 3228 The Heap Visit Control Flags are returned by the heap callbacks | |
| 3229 and can be used to abort the iteration. For the | |
| 3230 <functionlink id="jvmtiHeapReferenceCallback">Heap | |
| 3231 Reference Callback</functionlink>, it can also be used | |
| 3232 to prune the graph of traversed references | |
| 3233 (<code>JVMTI_VISIT_OBJECTS</code> is not set). | |
| 3234 | |
| 3235 <constants id="jvmtiHeapVisitControl" | |
| 3236 label="Heap Visit Control Flags" | |
| 3237 kind="bits" | |
| 3238 since="1.1"> | |
| 3239 <constant id="JVMTI_VISIT_OBJECTS" num="0x100"> | |
| 3240 If we are visiting an object and if this callback | |
| 3241 was initiated by <functionlink id="FollowReferences"/>, | |
| 3242 traverse the references of this object. | |
| 3243 Otherwise ignored. | |
| 3244 </constant> | |
| 3245 <constant id="JVMTI_VISIT_ABORT" num="0x8000"> | |
| 3246 Abort the iteration. Ignore all other bits. | |
| 3247 </constant> | |
| 3248 </constants> | |
| 3249 | |
| 3250 <p/> | |
| 3251 The Heap Reference Enumeration is provided by the | |
| 3252 <functionlink id="jvmtiHeapReferenceCallback">Heap | |
| 3253 Reference Callback</functionlink> and | |
| 3254 <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field | |
| 3255 Callback</functionlink> to | |
| 3256 describe the kind of reference | |
| 3257 being reported. | |
| 3258 | |
| 3259 <constants id="jvmtiHeapReferenceKind" | |
| 3260 label="Heap Reference Enumeration" | |
| 3261 kind="enum" | |
| 3262 since="1.1"> | |
| 3263 <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1"> | |
| 3264 Reference from an object to its class. | |
| 3265 </constant> | |
| 3266 <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2"> | |
| 3267 Reference from an object to the value of one of its instance fields. | |
| 3268 </constant> | |
| 3269 <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3"> | |
| 3270 Reference from an array to one of its elements. | |
| 3271 </constant> | |
| 3272 <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4"> | |
| 3273 Reference from a class to its class loader. | |
| 3274 </constant> | |
| 3275 <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5"> | |
| 3276 Reference from a class to its signers array. | |
| 3277 </constant> | |
| 3278 <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6"> | |
| 3279 Reference from a class to its protection domain. | |
| 3280 </constant> | |
| 3281 <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7"> | |
| 3282 Reference from a class to one of its interfaces. | |
| 3283 Note: interfaces are defined via a constant pool reference, | |
| 3284 so the referenced interfaces may also be reported with a | |
| 3285 <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. | |
| 3286 </constant> | |
| 3287 <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8"> | |
| 3288 Reference from a class to the value of one of its static fields. | |
| 3289 </constant> | |
| 3290 <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9"> | |
| 3291 Reference from a class to a resolved entry in the constant pool. | |
| 3292 </constant> | |
| 3293 <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10"> | |
| 3294 Reference from a class to its superclass. | |
| 3295 A callback is bot sent if the superclass is <code>java.lang.Object</code>. | |
| 3296 Note: loaded classes define superclasses via a constant pool | |
| 3297 reference, so the referenced superclass may also be reported with | |
| 3298 a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. | |
| 3299 </constant> | |
| 3300 <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21"> | |
| 3301 Heap root reference: JNI global reference. | |
| 3302 </constant> | |
| 3303 <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22"> | |
| 3304 Heap root reference: System class. | |
| 3305 </constant> | |
| 3306 <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23"> | |
| 3307 Heap root reference: monitor. | |
| 3308 </constant> | |
| 3309 <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24"> | |
| 3310 Heap root reference: local variable on the stack. | |
| 3311 </constant> | |
| 3312 <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25"> | |
| 3313 Heap root reference: JNI local reference. | |
| 3314 </constant> | |
| 3315 <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26"> | |
| 3316 Heap root reference: Thread. | |
| 3317 </constant> | |
| 3318 <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27"> | |
| 3319 Heap root reference: other heap root reference. | |
| 3320 </constant> | |
| 3321 </constants> | |
| 3322 | |
| 3323 <p/> | |
| 3324 Definitions for the single character type descriptors of | |
| 3325 primitive types. | |
| 3326 | |
| 3327 <constants id="jvmtiPrimitiveType" | |
| 3328 label="Primitive Type Enumeration" | |
| 3329 kind="enum" | |
| 3330 since="1.1"> | |
| 3331 <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90"> | |
| 3332 'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code> | |
| 3333 </constant> | |
| 3334 <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66"> | |
| 3335 'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code> | |
| 3336 </constant> | |
| 3337 <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67"> | |
| 3338 'C' - Java programming language <code>char</code> - JNI <code>jchar</code> | |
| 3339 </constant> | |
| 3340 <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83"> | |
| 3341 'S' - Java programming language <code>short</code> - JNI <code>jshort</code> | |
| 3342 </constant> | |
| 3343 <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73"> | |
| 3344 'I' - Java programming language <code>int</code> - JNI <code>jint</code> | |
| 3345 </constant> | |
| 3346 <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74"> | |
| 3347 'J' - Java programming language <code>long</code> - JNI <code>jlong</code> | |
| 3348 </constant> | |
| 3349 <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70"> | |
| 3350 'F' - Java programming language <code>float</code> - JNI <code>jfloat</code> | |
| 3351 </constant> | |
| 3352 <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68"> | |
| 3353 'D' - Java programming language <code>double</code> - JNI <code>jdouble</code> | |
| 3354 </constant> | |
| 3355 </constants> | |
| 3356 </intro> | |
| 3357 | |
| 3358 <typedef id="jvmtiHeapReferenceInfoField" | |
| 3359 label="Reference information structure for Field references" | |
| 3360 since="1.1"> | |
| 3361 <description> | |
| 3362 Reference information returned for | |
| 3363 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and | |
| 3364 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. | |
| 3365 </description> | |
| 3366 <field id="index"> | |
| 3367 <jint/> | |
| 3368 <description> | |
| 3369 For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the | |
| 3370 referrer object is not a class or an inteface. | |
| 3371 In this case, <code>index</code> is the index of the field | |
| 3372 in the class of the referrer object. | |
| 3373 This class is referred to below as <i>C</i>. | |
| 3374 <p/> | |
| 3375 For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, | |
| 3376 the referrer object is a class (referred to below as <i>C</i>) | |
| 3377 or an interface (referred to below as <i>I</i>). | |
| 3378 In this case, <code>index</code> is the index of the field in | |
| 3379 that class or interface. | |
| 3380 <p/> | |
| 3381 If the referrer object is not an interface, then the field | |
| 3382 indices are determined as follows: | |
| 3383 <ul> | |
| 3384 <li>make a list of all the fields in <i>C</i> and its | |
| 3385 superclasses, starting with all the fields in | |
| 3386 <code>java.lang.Object</code> and ending with all the | |
| 3387 fields in <i>C</i>.</li> | |
| 3388 <li>Within this list, put | |
| 3389 the fields for a given class in the order returned by | |
| 3390 <functionlink id="GetClassFields"/>.</li> | |
| 3391 <li>Assign the fields in this list indices | |
| 3392 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> | |
| 3393 is the count of the fields in all the interfaces | |
| 3394 implemented by <i>C</i>. | |
| 3395 Note that <i>C</i> implements all interfaces | |
| 3396 directly implemented by its superclasses; as well | |
| 3397 as all superinterfaces of these interfaces.</li> | |
| 3398 </ul> | |
| 3399 If the referrer object is an interface, then the field | |
| 3400 indices are determined as follows: | |
| 3401 <ul> | |
| 3402 <li>make a list of the fields directly declared in | |
| 3403 <i>I</i>.</li> | |
| 3404 <li>Within this list, put | |
| 3405 the fields in the order returned by | |
| 3406 <functionlink id="GetClassFields"/>.</li> | |
| 3407 <li>Assign the fields in this list indices | |
| 3408 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> | |
| 3409 is the count of the fields in all the superinterfaces | |
| 3410 of <i>I</i>.</li> | |
| 3411 </ul> | |
| 3412 All fields are included in this computation, regardless of | |
| 3413 field modifier (static, public, private, etc). | |
| 3414 <p/> | |
| 3415 For example, given the following classes and interfaces: | |
| 3416 <example> | |
| 3417 interface I0 { | |
| 3418 int p = 0; | |
| 3419 } | |
| 3420 | |
| 3421 interface I1 extends I0 { | |
| 3422 int x = 1; | |
| 3423 } | |
| 3424 | |
| 3425 interface I2 extends I0 { | |
| 3426 int y = 2; | |
| 3427 } | |
| 3428 | |
| 3429 class C1 implements I1 { | |
| 3430 public static int a = 3; | |
| 3431 private int b = 4; | |
| 3432 } | |
| 3433 | |
| 3434 class C2 extends C1 implements I2 { | |
| 3435 static int q = 5; | |
| 3436 final int r = 6; | |
| 3437 } | |
| 3438 </example> | |
| 3439 Assume that <functionlink id="GetClassFields"/> called on | |
| 3440 <code>C1</code> returns the fields of <code>C1</code> in the | |
| 3441 order: a, b; and that the fields of <code>C2</code> are | |
| 3442 returned in the order: q, r. | |
| 3443 An instance of class <code>C1</code> will have the | |
| 3444 following field indices: | |
| 3445 <dl><dd><table> | |
| 3446 <tr> | |
| 3447 <td> | |
| 3448 a | |
| 3449 </td> | |
| 3450 <td> | |
| 3451 2 | |
| 3452 </td> | |
| 3453 <td align="left"> | |
| 3454 The count of the fields in the interfaces | |
| 3455 implemented by <code>C1</code> is two (<i>n</i>=2): | |
| 3456 <code>p</code> of <code>I0</code> | |
| 3457 and <code>x</code> of <code>I1</code>. | |
| 3458 </td> | |
| 3459 </tr> | |
| 3460 <tr> | |
| 3461 <td> | |
| 3462 b | |
| 3463 </td> | |
| 3464 <td> | |
| 3465 3 | |
| 3466 </td> | |
| 3467 <td align="left"> | |
| 3468 the subsequent index. | |
| 3469 </td> | |
| 3470 </tr> | |
| 3471 </table></dd></dl> | |
| 3472 The class <code>C1</code> will have the same field indices. | |
| 3473 <p/> | |
| 3474 An instance of class <code>C2</code> will have the | |
| 3475 following field indices: | |
| 3476 <dl><dd><table> | |
| 3477 <tr> | |
| 3478 <td> | |
| 3479 a | |
| 3480 </td> | |
| 3481 <td> | |
| 3482 3 | |
| 3483 </td> | |
| 3484 <td align="left"> | |
| 3485 The count of the fields in the interfaces | |
| 3486 implemented by <code>C2</code> is three (<i>n</i>=3): | |
| 3487 <code>p</code> of <code>I0</code>, | |
| 3488 <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code> | |
| 3489 (an interface of <code>C2</code>). Note that the field <code>p</code> | |
| 3490 of <code>I0</code> is only included once. | |
| 3491 </td> | |
| 3492 </tr> | |
| 3493 <tr> | |
| 3494 <td> | |
| 3495 b | |
| 3496 </td> | |
| 3497 <td> | |
| 3498 4 | |
| 3499 </td> | |
| 3500 <td align="left"> | |
| 3501 the subsequent index to "a". | |
| 3502 </td> | |
| 3503 </tr> | |
| 3504 <tr> | |
| 3505 <td> | |
| 3506 q | |
| 3507 </td> | |
| 3508 <td> | |
| 3509 5 | |
| 3510 </td> | |
| 3511 <td align="left"> | |
| 3512 the subsequent index to "b". | |
| 3513 </td> | |
| 3514 </tr> | |
| 3515 <tr> | |
| 3516 <td> | |
| 3517 r | |
| 3518 </td> | |
| 3519 <td> | |
| 3520 6 | |
| 3521 </td> | |
| 3522 <td align="left"> | |
| 3523 the subsequent index to "q". | |
| 3524 </td> | |
| 3525 </tr> | |
| 3526 </table></dd></dl> | |
| 3527 The class <code>C2</code> will have the same field indices. | |
| 3528 Note that a field may have a different index depending on the | |
| 3529 object that is viewing it -- for example field "a" above. | |
| 3530 Note also: not all field indices may be visible from the | |
| 3531 callbacks, but all indices are shown for illustrative purposes. | |
| 3532 <p/> | |
| 3533 The interface <code>I1</code> will have the | |
| 3534 following field indices: | |
| 3535 <dl><dd><table> | |
| 3536 <tr> | |
| 3537 <td> | |
| 3538 x | |
| 3539 </td> | |
| 3540 <td> | |
| 3541 1 | |
| 3542 </td> | |
| 3543 <td align="left"> | |
| 3544 The count of the fields in the superinterfaces | |
| 3545 of <code>I1</code> is one (<i>n</i>=1): | |
| 3546 <code>p</code> of <code>I0</code>. | |
| 3547 </td> | |
| 3548 </tr> | |
| 3549 </table></dd></dl> | |
| 3550 </description> | |
| 3551 </field> | |
| 3552 </typedef> | |
| 3553 | |
| 3554 <typedef id="jvmtiHeapReferenceInfoArray" | |
| 3555 label="Reference information structure for Array references" | |
| 3556 since="1.1"> | |
| 3557 <description> | |
| 3558 Reference information returned for | |
| 3559 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. | |
| 3560 </description> | |
| 3561 <field id="index"> | |
| 3562 <jint/> | |
| 3563 <description> | |
| 3564 The array index. | |
| 3565 </description> | |
| 3566 </field> | |
| 3567 </typedef> | |
| 3568 | |
| 3569 <typedef id="jvmtiHeapReferenceInfoConstantPool" | |
| 3570 label="Reference information structure for Constant Pool references" | |
| 3571 since="1.1"> | |
| 3572 <description> | |
| 3573 Reference information returned for | |
| 3574 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. | |
| 3575 </description> | |
| 3576 <field id="index"> | |
| 3577 <jint/> | |
| 3578 <description> | |
| 3579 The index into the constant pool of the class. See the | |
| 3580 <vmspeclink id="ClassFile.doc.html#20080" | |
| 3581 name="Constant Pool section"/> | |
| 3582 description. | |
| 3583 </description> | |
| 3584 </field> | |
| 3585 </typedef> | |
| 3586 | |
| 3587 <typedef id="jvmtiHeapReferenceInfoStackLocal" | |
| 3588 label="Reference information structure for Local Variable references" | |
| 3589 since="1.1"> | |
| 3590 <description> | |
| 3591 Reference information returned for | |
| 3592 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. | |
| 3593 </description> | |
| 3594 <field id="thread_tag"> | |
| 3595 <jlong/> | |
| 3596 <description> | |
| 3597 The tag of the thread corresponding to this stack, zero if not tagged. | |
| 3598 </description> | |
| 3599 </field> | |
| 3600 <field id="thread_id"> | |
| 3601 <jlong/> | |
| 3602 <description> | |
| 3603 The unique thread ID of the thread corresponding to this stack. | |
| 3604 </description> | |
| 3605 </field> | |
| 3606 <field id="depth"> | |
| 3607 <jint/> | |
| 3608 <description> | |
| 3609 The depth of the frame. | |
| 3610 </description> | |
| 3611 </field> | |
| 3612 <field id="method"> | |
| 3613 <jmethodID/> | |
| 3614 <description> | |
| 3615 The method executing in this frame. | |
| 3616 </description> | |
| 3617 </field> | |
| 3618 <field id="location"> | |
| 3619 <jlocation/> | |
| 3620 <description> | |
| 3621 The currently executing location in this frame. | |
| 3622 </description> | |
| 3623 </field> | |
| 3624 <field id="slot"> | |
| 3625 <jint/> | |
| 3626 <description> | |
| 3627 The slot number of the local variable. | |
| 3628 </description> | |
| 3629 </field> | |
| 3630 </typedef> | |
| 3631 | |
| 3632 <typedef id="jvmtiHeapReferenceInfoJniLocal" | |
| 3633 label="Reference information structure for JNI local references" | |
| 3634 since="1.1"> | |
| 3635 <description> | |
| 3636 Reference information returned for | |
| 3637 <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. | |
| 3638 </description> | |
| 3639 <field id="thread_tag"> | |
| 3640 <jlong/> | |
| 3641 <description> | |
| 3642 The tag of the thread corresponding to this stack, zero if not tagged. | |
| 3643 </description> | |
| 3644 </field> | |
| 3645 <field id="thread_id"> | |
| 3646 <jlong/> | |
| 3647 <description> | |
| 3648 The unique thread ID of the thread corresponding to this stack. | |
| 3649 </description> | |
| 3650 </field> | |
| 3651 <field id="depth"> | |
| 3652 <jint/> | |
| 3653 <description> | |
| 3654 The depth of the frame. | |
| 3655 </description> | |
| 3656 </field> | |
| 3657 <field id="method"> | |
| 3658 <jmethodID/> | |
| 3659 <description> | |
| 3660 The method executing in this frame. | |
| 3661 </description> | |
| 3662 </field> | |
| 3663 </typedef> | |
| 3664 | |
| 3665 <typedef id="jvmtiHeapReferenceInfoReserved" | |
| 3666 label="Reference information structure for Other references" | |
| 3667 since="1.1"> | |
| 3668 <description> | |
| 3669 Reference information returned for other references. | |
| 3670 </description> | |
| 3671 <field id="reserved1"> | |
| 3672 <jlong/> | |
| 3673 <description> | |
| 3674 reserved for future use. | |
| 3675 </description> | |
| 3676 </field> | |
| 3677 <field id="reserved2"> | |
| 3678 <jlong/> | |
| 3679 <description> | |
| 3680 reserved for future use. | |
| 3681 </description> | |
| 3682 </field> | |
| 3683 <field id="reserved3"> | |
| 3684 <jlong/> | |
| 3685 <description> | |
| 3686 reserved for future use. | |
| 3687 </description> | |
| 3688 </field> | |
| 3689 <field id="reserved4"> | |
| 3690 <jlong/> | |
| 3691 <description> | |
| 3692 reserved for future use. | |
| 3693 </description> | |
| 3694 </field> | |
| 3695 <field id="reserved5"> | |
| 3696 <jlong/> | |
| 3697 <description> | |
| 3698 reserved for future use. | |
| 3699 </description> | |
| 3700 </field> | |
| 3701 <field id="reserved6"> | |
| 3702 <jlong/> | |
| 3703 <description> | |
| 3704 reserved for future use. | |
| 3705 </description> | |
| 3706 </field> | |
| 3707 <field id="reserved7"> | |
| 3708 <jlong/> | |
| 3709 <description> | |
| 3710 reserved for future use. | |
| 3711 </description> | |
| 3712 </field> | |
| 3713 <field id="reserved8"> | |
| 3714 <jlong/> | |
| 3715 <description> | |
| 3716 reserved for future use. | |
| 3717 </description> | |
| 3718 </field> | |
| 3719 </typedef> | |
| 3720 | |
| 3721 <uniontypedef id="jvmtiHeapReferenceInfo" | |
| 3722 label="Reference information structure" | |
| 3723 since="1.1"> | |
| 3724 <description> | |
| 3725 The information returned about referrers. | |
| 3726 Represented as a union of the various kinds of reference information. | |
| 3727 </description> | |
| 3728 <field id="field"> | |
| 3729 <struct>jvmtiHeapReferenceInfoField</struct> | |
| 3730 <description> | |
| 3731 The referrer information for | |
| 3732 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> | |
| 3733 and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. | |
| 3734 </description> | |
| 3735 </field> | |
| 3736 <field id="array"> | |
| 3737 <struct>jvmtiHeapReferenceInfoArray</struct> | |
| 3738 <description> | |
| 3739 The referrer information for | |
| 3740 For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. | |
| 3741 </description> | |
| 3742 </field> | |
| 3743 <field id="constant_pool"> | |
| 3744 <struct>jvmtiHeapReferenceInfoConstantPool</struct> | |
| 3745 <description> | |
| 3746 The referrer information for | |
| 3747 For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. | |
| 3748 </description> | |
| 3749 </field> | |
| 3750 <field id="stack_local"> | |
| 3751 <struct>jvmtiHeapReferenceInfoStackLocal</struct> | |
| 3752 <description> | |
| 3753 The referrer information for | |
| 3754 For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. | |
| 3755 </description> | |
| 3756 </field> | |
| 3757 <field id="jni_local"> | |
| 3758 <struct>jvmtiHeapReferenceInfoJniLocal</struct> | |
| 3759 <description> | |
| 3760 The referrer information for | |
| 3761 For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. | |
| 3762 </description> | |
| 3763 </field> | |
| 3764 <field id="other"> | |
| 3765 <struct>jvmtiHeapReferenceInfoReserved</struct> | |
| 3766 <description> | |
| 3767 reserved for future use. | |
| 3768 </description> | |
| 3769 </field> | |
| 3770 </uniontypedef> | |
| 3771 | |
| 3772 <typedef id="jvmtiHeapCallbacks" | |
| 3773 label="Heap callback function structure" | |
| 3774 since="1.1"> | |
| 3775 <field id="heap_iteration_callback"> | |
| 3776 <ptrtype> | |
| 3777 <struct>jvmtiHeapIterationCallback</struct> | |
| 3778 </ptrtype> | |
| 3779 <description> | |
| 3780 The callback to be called to describe an | |
| 3781 object in the heap. Used by the | |
| 3782 <functionlink id="IterateThroughHeap"/> function, ignored by the | |
| 3783 <functionlink id="FollowReferences"/> function. | |
| 3784 </description> | |
| 3785 </field> | |
| 3786 <field id="heap_reference_callback"> | |
| 3787 <ptrtype> | |
| 3788 <struct>jvmtiHeapReferenceCallback</struct> | |
| 3789 </ptrtype> | |
| 3790 <description> | |
| 3791 The callback to be called to describe an | |
| 3792 object reference. Used by the | |
| 3793 <functionlink id="FollowReferences"/> function, ignored by the | |
| 3794 <functionlink id="IterateThroughHeap"/> function. | |
| 3795 </description> | |
| 3796 </field> | |
| 3797 <field id="primitive_field_callback"> | |
| 3798 <ptrtype> | |
| 3799 <struct>jvmtiPrimitiveFieldCallback</struct> | |
| 3800 </ptrtype> | |
| 3801 <description> | |
| 3802 The callback to be called to describe a | |
| 3803 primitive field. | |
| 3804 </description> | |
| 3805 </field> | |
| 3806 <field id="array_primitive_value_callback"> | |
| 3807 <ptrtype> | |
| 3808 <struct>jvmtiArrayPrimitiveValueCallback</struct> | |
| 3809 </ptrtype> | |
| 3810 <description> | |
| 3811 The callback to be called to describe an | |
| 3812 array of primitive values. | |
| 3813 </description> | |
| 3814 </field> | |
| 3815 <field id="string_primitive_value_callback"> | |
| 3816 <ptrtype> | |
| 3817 <struct>jvmtiStringPrimitiveValueCallback</struct> | |
| 3818 </ptrtype> | |
| 3819 <description> | |
| 3820 The callback to be called to describe a String value. | |
| 3821 </description> | |
| 3822 </field> | |
| 3823 <field id="reserved5"> | |
| 3824 <ptrtype> | |
| 3825 <struct>jvmtiReservedCallback</struct> | |
| 3826 </ptrtype> | |
| 3827 <description> | |
| 3828 Reserved for future use.. | |
| 3829 </description> | |
| 3830 </field> | |
| 3831 <field id="reserved6"> | |
| 3832 <ptrtype> | |
| 3833 <struct>jvmtiReservedCallback</struct> | |
| 3834 </ptrtype> | |
| 3835 <description> | |
| 3836 Reserved for future use.. | |
| 3837 </description> | |
| 3838 </field> | |
| 3839 <field id="reserved7"> | |
| 3840 <ptrtype> | |
| 3841 <struct>jvmtiReservedCallback</struct> | |
| 3842 </ptrtype> | |
| 3843 <description> | |
| 3844 Reserved for future use.. | |
| 3845 </description> | |
| 3846 </field> | |
| 3847 <field id="reserved8"> | |
| 3848 <ptrtype> | |
| 3849 <struct>jvmtiReservedCallback</struct> | |
| 3850 </ptrtype> | |
| 3851 <description> | |
| 3852 Reserved for future use.. | |
| 3853 </description> | |
| 3854 </field> | |
| 3855 <field id="reserved9"> | |
| 3856 <ptrtype> | |
| 3857 <struct>jvmtiReservedCallback</struct> | |
| 3858 </ptrtype> | |
| 3859 <description> | |
| 3860 Reserved for future use.. | |
| 3861 </description> | |
| 3862 </field> | |
| 3863 <field id="reserved10"> | |
| 3864 <ptrtype> | |
| 3865 <struct>jvmtiReservedCallback</struct> | |
| 3866 </ptrtype> | |
| 3867 <description> | |
| 3868 Reserved for future use.. | |
| 3869 </description> | |
| 3870 </field> | |
| 3871 <field id="reserved11"> | |
| 3872 <ptrtype> | |
| 3873 <struct>jvmtiReservedCallback</struct> | |
| 3874 </ptrtype> | |
| 3875 <description> | |
| 3876 Reserved for future use.. | |
| 3877 </description> | |
| 3878 </field> | |
| 3879 <field id="reserved12"> | |
| 3880 <ptrtype> | |
| 3881 <struct>jvmtiReservedCallback</struct> | |
| 3882 </ptrtype> | |
| 3883 <description> | |
| 3884 Reserved for future use.. | |
| 3885 </description> | |
| 3886 </field> | |
| 3887 <field id="reserved13"> | |
| 3888 <ptrtype> | |
| 3889 <struct>jvmtiReservedCallback</struct> | |
| 3890 </ptrtype> | |
| 3891 <description> | |
| 3892 Reserved for future use.. | |
| 3893 </description> | |
| 3894 </field> | |
| 3895 <field id="reserved14"> | |
| 3896 <ptrtype> | |
| 3897 <struct>jvmtiReservedCallback</struct> | |
| 3898 </ptrtype> | |
| 3899 <description> | |
| 3900 Reserved for future use.. | |
| 3901 </description> | |
| 3902 </field> | |
| 3903 <field id="reserved15"> | |
| 3904 <ptrtype> | |
| 3905 <struct>jvmtiReservedCallback</struct> | |
| 3906 </ptrtype> | |
| 3907 <description> | |
| 3908 Reserved for future use.. | |
| 3909 </description> | |
| 3910 </field> | |
| 3911 </typedef> | |
| 3912 | |
| 3913 | |
| 3914 <intro> | |
| 3915 <rationale> | |
| 3916 The heap dumping functionality (below) uses a callback | |
| 3917 for each object. While it would seem that a buffered approach | |
| 3918 would provide better throughput, tests do | |
| 3919 not show this to be the case--possibly due to locality of | |
| 3920 memory reference or array access overhead. | |
| 3921 </rationale> | |
| 3922 | |
| 3923 <issue> | |
| 3924 Still under investigation as to if java.lang.ref references | |
| 3925 are reported as a different type of reference. | |
| 3926 </issue> | |
| 3927 | |
| 3928 <issue> | |
| 3929 Should or can an indication of the cost or relative cost of | |
| 3930 these operations be included? | |
| 3931 </issue> | |
| 3932 | |
| 3933 </intro> | |
| 3934 | |
| 3935 <callback id="jvmtiHeapIterationCallback" since="1.1"> | |
| 3936 <jint/> | |
| 3937 <synopsis>Heap Iteration Callback</synopsis> | |
| 3938 <description> | |
| 3939 Agent supplied callback function. | |
| 3940 Describes (but does not pass in) an object in the heap. | |
| 3941 <p/> | |
| 3942 This function should return a bit vector of the desired | |
| 3943 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 3944 This will determine if the entire iteration should be aborted | |
| 3945 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 3946 <p/> | |
| 3947 See the <internallink id="heapCallbacks">heap callback | |
| 3948 function restrictions</internallink>. | |
| 3949 </description> | |
| 3950 <parameters> | |
| 3951 <param id="class_tag"> | |
| 3952 <jlong/> | |
| 3953 <description> | |
| 3954 The tag of the class of object (zero if the class is not tagged). | |
| 3955 If the object represents a runtime class, | |
| 3956 the <code>class_tag</code> is the tag | |
| 3957 associated with <code>java.lang.Class</code> | |
| 3958 (zero if <code>java.lang.Class</code> is not tagged). | |
| 3959 </description> | |
| 3960 </param> | |
| 3961 <param id="size"> | |
| 3962 <jlong/> | |
| 3963 <description> | |
| 3964 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 3965 </description> | |
| 3966 </param> | |
| 3967 <param id="tag_ptr"> | |
| 3968 <outptr><jlong/></outptr> | |
| 3969 <description> | |
| 3970 The object tag value, or zero if the object is not tagged. | |
| 3971 To set the tag value to be associated with the object | |
| 3972 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 3973 </description> | |
| 3974 </param> | |
| 3975 <param id="length"> | |
| 3976 <jint/> | |
| 3977 <description> | |
| 3978 If this object is an array, the length of the array. Otherwise negative one (-1). | |
| 3979 </description> | |
| 3980 </param> | |
| 3981 <param id="user_data"> | |
| 3982 <outptr><void/></outptr> | |
| 3983 <description> | |
| 3984 The user supplied data that was passed into the iteration function. | |
| 3985 </description> | |
| 3986 </param> | |
| 3987 </parameters> | |
| 3988 </callback> | |
| 3989 | |
| 3990 <callback id="jvmtiHeapReferenceCallback" since="1.1"> | |
| 3991 <jint/> | |
| 3992 <synopsis>Heap Reference Callback</synopsis> | |
| 3993 <description> | |
| 3994 Agent supplied callback function. | |
| 3995 Describes a reference from an object or the VM (the referrer) to another object | |
| 3996 (the referree) or a heap root to a referree. | |
| 3997 <p/> | |
| 3998 This function should return a bit vector of the desired | |
| 3999 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4000 This will determine if the objects referenced by the referree | |
| 4001 should be visited or if the entire iteration should be aborted. | |
| 4002 <p/> | |
| 4003 See the <internallink id="heapCallbacks">heap callback | |
| 4004 function restrictions</internallink>. | |
| 4005 </description> | |
| 4006 <parameters> | |
| 4007 <param id="reference_kind"> | |
| 4008 <enum>jvmtiHeapReferenceKind</enum> | |
| 4009 <description> | |
| 4010 The kind of reference. | |
| 4011 </description> | |
| 4012 </param> | |
| 4013 <param id="reference_info"> | |
| 4014 <inptr> | |
| 4015 <struct>jvmtiHeapReferenceInfo</struct> | |
| 4016 </inptr> | |
| 4017 <description> | |
| 4018 Details about the reference. | |
| 4019 Set when the <paramlink id="reference_kind"/> is | |
| 4020 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, | |
| 4021 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, | |
| 4022 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>, | |
| 4023 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>, | |
| 4024 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>, | |
| 4025 or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>. | |
| 4026 Otherwise <code>NULL</code>. | |
| 4027 </description> | |
| 4028 </param> | |
| 4029 <param id="class_tag"> | |
| 4030 <jlong/> | |
| 4031 <description> | |
| 4032 The tag of the class of referree object (zero if the class is not tagged). | |
| 4033 If the referree object represents a runtime class, | |
| 4034 the <code>class_tag</code> is the tag | |
| 4035 associated with <code>java.lang.Class</code> | |
| 4036 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4037 </description> | |
| 4038 </param> | |
| 4039 <param id="referrer_class_tag"> | |
| 4040 <jlong/> | |
| 4041 <description> | |
| 4042 The tag of the class of the referrer object (zero if the class is not tagged | |
| 4043 or the referree is a heap root). If the referrer object represents a runtime | |
| 4044 class, the <code>referrer_class_tag</code> is the tag associated with | |
| 4045 the <code>java.lang.Class</code> | |
| 4046 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4047 </description> | |
| 4048 </param> | |
| 4049 <param id="size"> | |
| 4050 <jlong/> | |
| 4051 <description> | |
| 4052 Size of the referree object (in bytes). | |
| 4053 See <functionlink id="GetObjectSize"/>. | |
| 4054 </description> | |
| 4055 </param> | |
| 4056 <param id="tag_ptr"> | |
| 4057 <outptr><jlong/></outptr> | |
| 4058 <description> | |
| 4059 Points to the referree object tag value, or zero if the object is not | |
| 4060 tagged. | |
| 4061 To set the tag value to be associated with the object | |
| 4062 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4063 </description> | |
| 4064 </param> | |
| 4065 <param id="referrer_tag_ptr"> | |
| 4066 <outptr><jlong/></outptr> | |
| 4067 <description> | |
| 4068 Points to the tag of the referrer object, or | |
| 4069 points to the zero if the referrer | |
| 4070 object is not tagged. | |
| 4071 <code>NULL</code> if the referrer in not an object (that is, | |
| 4072 this callback is reporting a heap root). | |
| 4073 To set the tag value to be associated with the referrer object | |
| 4074 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4075 If this callback is reporting a reference from an object to itself, | |
| 4076 <code>referrer_tag_ptr == tag_ptr</code>. | |
| 4077 </description> | |
| 4078 </param> | |
| 4079 <param id="length"> | |
| 4080 <jint/> | |
| 4081 <description> | |
| 4082 If this object is an array, the length of the array. Otherwise negative one (-1). | |
| 4083 </description> | |
| 4084 </param> | |
| 4085 <param id="user_data"> | |
| 4086 <outptr><void/></outptr> | |
| 4087 <description> | |
| 4088 The user supplied data that was passed into the iteration function. | |
| 4089 </description> | |
| 4090 </param> | |
| 4091 </parameters> | |
| 4092 </callback> | |
| 4093 | |
| 4094 <callback id="jvmtiPrimitiveFieldCallback" since="1.1"> | |
| 4095 <jint/> | |
| 4096 <synopsis>Primitive Field Callback</synopsis> | |
| 4097 <description> | |
| 4098 Agent supplied callback function which | |
| 4099 describes a primitive field of an object (<i>the object</i>). | |
| 4100 A primitive field is a field whose type is a primitive type. | |
| 4101 This callback will describe a static field if the object is a class, | |
| 4102 and otherwise will describe an instance field. | |
| 4103 <p/> | |
| 4104 This function should return a bit vector of the desired | |
| 4105 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4106 This will determine if the entire iteration should be aborted | |
| 4107 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4108 <p/> | |
| 4109 See the <internallink id="heapCallbacks">heap callback | |
| 4110 function restrictions</internallink>. | |
| 4111 </description> | |
| 4112 <parameters> | |
| 4113 <param id="kind"> | |
| 4114 <enum>jvmtiHeapReferenceKind</enum> | |
| 4115 <description> | |
| 4116 The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or | |
| 4117 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>). | |
| 4118 </description> | |
| 4119 </param> | |
| 4120 <param id="info"> | |
| 4121 <inptr> | |
| 4122 <struct>jvmtiHeapReferenceInfo</struct> | |
| 4123 </inptr> | |
| 4124 <description> | |
| 4125 Which field (the field index). | |
| 4126 </description> | |
| 4127 </param> | |
| 4128 <param id="object_class_tag"> | |
| 4129 <jlong/> | |
| 4130 <description> | |
| 4131 The tag of the class of the object (zero if the class is not tagged). | |
| 4132 If the object represents a runtime class, the | |
| 4133 <code>object_class_tag</code> is the tag | |
| 4134 associated with <code>java.lang.Class</code> | |
| 4135 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4136 </description> | |
| 4137 </param> | |
| 4138 <param id="object_tag_ptr"> | |
| 4139 <outptr><jlong/></outptr> | |
| 4140 <description> | |
| 4141 Points to the tag of the object, or zero if the object is not | |
| 4142 tagged. | |
| 4143 To set the tag value to be associated with the object | |
| 4144 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4145 </description> | |
| 4146 </param> | |
| 4147 <param id="value"> | |
| 4148 <jvalue/> | |
| 4149 <description> | |
| 4150 The value of the field. | |
| 4151 </description> | |
| 4152 </param> | |
| 4153 <param id="value_type"> | |
| 4154 <enum>jvmtiPrimitiveType</enum> | |
| 4155 <description> | |
| 4156 The type of the field. | |
| 4157 </description> | |
| 4158 </param> | |
| 4159 <param id="user_data"> | |
| 4160 <outptr><void/></outptr> | |
| 4161 <description> | |
| 4162 The user supplied data that was passed into the iteration function. | |
| 4163 </description> | |
| 4164 </param> | |
| 4165 </parameters> | |
| 4166 </callback> | |
| 4167 | |
| 4168 <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1"> | |
| 4169 <jint/> | |
| 4170 <synopsis>Array Primitive Value Callback</synopsis> | |
| 4171 <description> | |
| 4172 Agent supplied callback function. | |
| 4173 Describes the values in an array of a primitive type. | |
| 4174 <p/> | |
| 4175 This function should return a bit vector of the desired | |
| 4176 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4177 This will determine if the entire iteration should be aborted | |
| 4178 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4179 <p/> | |
| 4180 See the <internallink id="heapCallbacks">heap callback | |
| 4181 function restrictions</internallink>. | |
| 4182 </description> | |
| 4183 <parameters> | |
| 4184 <param id="class_tag"> | |
| 4185 <jlong/> | |
| 4186 <description> | |
| 4187 The tag of the class of the array object (zero if the class is not tagged). | |
| 4188 </description> | |
| 4189 </param> | |
| 4190 <param id="size"> | |
| 4191 <jlong/> | |
| 4192 <description> | |
| 4193 Size of the array (in bytes). | |
| 4194 See <functionlink id="GetObjectSize"/>. | |
| 4195 </description> | |
| 4196 </param> | |
| 4197 <param id="tag_ptr"> | |
| 4198 <outptr><jlong/></outptr> | |
| 4199 <description> | |
| 4200 Points to the tag of the array object, or zero if the object is not | |
| 4201 tagged. | |
| 4202 To set the tag value to be associated with the object | |
| 4203 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4204 </description> | |
| 4205 </param> | |
| 4206 <param id="element_count"> | |
| 4207 <jint/> | |
| 4208 <description> | |
| 4209 The length of the primitive array. | |
| 4210 </description> | |
| 4211 </param> | |
| 4212 <param id="element_type"> | |
| 4213 <enum>jvmtiPrimitiveType</enum> | |
| 4214 <description> | |
| 4215 The type of the elements of the array. | |
| 4216 </description> | |
| 4217 </param> | |
| 4218 <param id="elements"> | |
| 4219 <vmbuf><void/></vmbuf> | |
| 4220 <description> | |
| 4221 The elements of the array in a packed array of <code>element_count</code> | |
| 4222 items of <code>element_type</code> size each. | |
| 4223 </description> | |
| 4224 </param> | |
| 4225 <param id="user_data"> | |
| 4226 <outptr><void/></outptr> | |
| 4227 <description> | |
| 4228 The user supplied data that was passed into the iteration function. | |
| 4229 </description> | |
| 4230 </param> | |
| 4231 </parameters> | |
| 4232 </callback> | |
| 4233 | |
| 4234 <callback id="jvmtiStringPrimitiveValueCallback" since="1.1"> | |
| 4235 <jint/> | |
| 4236 <synopsis>String Primitive Value Callback</synopsis> | |
| 4237 <description> | |
| 4238 Agent supplied callback function. | |
| 4239 Describes the value of a java.lang.String. | |
| 4240 <p/> | |
| 4241 This function should return a bit vector of the desired | |
| 4242 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4243 This will determine if the entire iteration should be aborted | |
| 4244 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4245 <p/> | |
| 4246 See the <internallink id="heapCallbacks">heap callback | |
| 4247 function restrictions</internallink>. | |
| 4248 </description> | |
| 4249 <parameters> | |
| 4250 <param id="class_tag"> | |
| 4251 <jlong/> | |
| 4252 <description> | |
| 4253 The tag of the class of the String class (zero if the class is not tagged). | |
| 4254 <issue>Is this needed?</issue> | |
| 4255 </description> | |
| 4256 </param> | |
| 4257 <param id="size"> | |
| 4258 <jlong/> | |
| 4259 <description> | |
| 4260 Size of the string (in bytes). | |
| 4261 See <functionlink id="GetObjectSize"/>. | |
| 4262 </description> | |
| 4263 </param> | |
| 4264 <param id="tag_ptr"> | |
| 4265 <outptr><jlong/></outptr> | |
| 4266 <description> | |
| 4267 Points to the tag of the String object, or zero if the object is not | |
| 4268 tagged. | |
| 4269 To set the tag value to be associated with the object | |
| 4270 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4271 </description> | |
| 4272 </param> | |
| 4273 <param id="value"> | |
| 4274 <vmbuf><jchar/></vmbuf> | |
| 4275 <description> | |
| 4276 The value of the String, encoded as a Unicode string. | |
| 4277 </description> | |
| 4278 </param> | |
| 4279 <param id="value_length"> | |
| 4280 <jint/> | |
| 4281 <description> | |
| 4282 The length of the string. | |
| 4283 The length is equal to the number of 16-bit Unicode | |
| 4284 characters in the string. | |
| 4285 </description> | |
| 4286 </param> | |
| 4287 <param id="user_data"> | |
| 4288 <outptr><void/></outptr> | |
| 4289 <description> | |
| 4290 The user supplied data that was passed into the iteration function. | |
| 4291 </description> | |
| 4292 </param> | |
| 4293 </parameters> | |
| 4294 </callback> | |
| 4295 | |
| 4296 | |
| 4297 <callback id="jvmtiReservedCallback" since="1.1"> | |
| 4298 <jint/> | |
| 4299 <synopsis>reserved for future use Callback</synopsis> | |
| 4300 <description> | |
| 4301 Placeholder -- reserved for future use. | |
| 4302 </description> | |
| 4303 <parameters> | |
| 4304 </parameters> | |
| 4305 </callback> | |
| 4306 | |
| 4307 <function id="FollowReferences" num="115" since="1.1"> | |
| 4308 <synopsis>Follow References</synopsis> | |
| 4309 <description> | |
| 4310 This function initiates a traversal over the objects that are | |
| 4311 directly and indirectly reachable from the specified object or, | |
| 4312 if <code>initial_object</code> is not specified, all objects | |
| 4313 reachable from the heap roots. | |
| 4314 The heap root are the set of system classes, | |
| 4315 JNI globals, references from thread stacks, and other objects used as roots | |
| 4316 for the purposes of garbage collection. | |
| 4317 <p/> | |
| 4318 This function operates by traversing the reference graph. | |
| 4319 Let <i>A</i>, <i>B</i>, ... represent objects. | |
| 4320 When a reference from <i>A</i> to <i>B</i> is traversed, | |
| 4321 when a reference from a heap root to <i>B</i> is traversed, | |
| 4322 or when <i>B</i> is specified as the <paramlink id="initial_object"/>, | |
| 4323 then <i>B</i> is said to be <i>visited</i>. | |
| 4324 A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i> | |
| 4325 is visited. | |
| 4326 References are reported in the same order that the references are traversed. | |
| 4327 Object references are reported by invoking the agent supplied | |
| 4328 callback function <functionlink id="jvmtiHeapReferenceCallback"/>. | |
| 4329 In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known | |
| 4330 as the <i>referrer</i> and <i>B</i> as the <i>referree</i>. | |
| 4331 The callback is invoked exactly once for each reference from a referrer; | |
| 4332 this is true even if there are reference cycles or multiple paths to | |
| 4333 the referrer. | |
| 4334 There may be more than one reference between a referrer and a referree, | |
| 4335 each reference is reported. | |
| 4336 These references may be distinguished by examining the | |
| 4337 <datalink | |
| 4338 id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink> | |
| 4339 and | |
| 4340 <datalink | |
| 4341 id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink> | |
| 4342 parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback. | |
| 4343 <p/> | |
| 4344 This function reports a Java programming language view of object references, | |
| 4345 not a virtual machine implementation view. The following object references | |
| 4346 are reported when they are non-null: | |
| 4347 <ul> | |
| 4348 <li>Instance objects report references to each non-primitive instance fields | |
| 4349 (including inherited fields).</li> | |
| 4350 <li>Instance objects report a reference to the object type (class).</li> | |
| 4351 <li>Classes report a reference to the superclass and directly | |
| 4352 implemented/extended interfaces.</li> | |
| 4353 <li>Classes report a reference to the class loader, protection domain, | |
| 4354 signers, and resolved entries in the constant pool.</li> | |
| 4355 <li>Classes report a reference to each directly declared non-primitive | |
| 4356 static field.</li> | |
| 4357 <li>Arrays report a reference to the array type (class) and each | |
| 4358 array element.</li> | |
| 4359 <li>Primitive arrays report a reference to the array type.</li> | |
| 4360 </ul> | |
| 4361 <p/> | |
| 4362 This function can also be used to examine primitive (non-object) values. | |
| 4363 The primitive value of an array or String | |
| 4364 is reported after the object has been visited; | |
| 4365 it is reported by invoking the agent supplied callback function | |
| 4366 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or | |
| 4367 <functionlink id="jvmtiStringPrimitiveValueCallback"/>. | |
| 4368 A primitive field | |
| 4369 is reported after the object with that field is visited; | |
| 4370 it is reported by invoking the agent supplied callback function | |
| 4371 <functionlink id="jvmtiPrimitiveFieldCallback"/>. | |
| 4372 <p/> | |
| 4373 Whether a callback is provided or is <code>NULL</code> only determines | |
| 4374 whether the callback will be invoked, it does not influence | |
| 4375 which objects are visited nor does it influence whether other callbacks | |
| 4376 will be invoked. | |
| 4377 However, the | |
| 4378 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink> | |
| 4379 returned by <functionlink id="jvmtiHeapReferenceCallback"/> | |
| 4380 do determine if the objects referenced by the | |
| 4381 current object as visited. | |
| 4382 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> | |
| 4383 and <paramlink id="klass"/> provided as parameters to this function | |
| 4384 do not control which objects are visited but they do control which | |
| 4385 objects and primitive values are reported by the callbacks. | |
| 4386 For example, if the only callback that was set is | |
| 4387 <paramlink id="array_primitive_value_callback"/> and <code>klass</code> | |
| 4388 is set to the array of bytes class, then only arrays of byte will be | |
| 4389 reported. | |
| 4390 The table below summarizes this: | |
| 4391 <p/> | |
| 4392 <table> | |
| 4393 <tr> | |
| 4394 <th/> | |
| 4395 <th> | |
| 4396 Controls objects visited | |
| 4397 </th> | |
| 4398 <th> | |
| 4399 Controls objects reported | |
| 4400 </th> | |
| 4401 <th> | |
| 4402 Controls primitives reported | |
| 4403 </th> | |
| 4404 </tr> | |
| 4405 <tr> | |
| 4406 <th align="left"> | |
| 4407 the | |
| 4408 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
| 4409 returned by <functionlink id="jvmtiHeapReferenceCallback"/> | |
| 4410 </th> | |
| 4411 <td> | |
| 4412 <b>Yes</b> | |
| 4413 </td> | |
| 4414 <td> | |
| 4415 <b>Yes</b>, since visits are controlled | |
| 4416 </td> | |
| 4417 <td> | |
| 4418 <b>Yes</b>, since visits are controlled | |
| 4419 </td> | |
| 4420 </tr> | |
| 4421 <tr> | |
| 4422 <th align="left"> | |
| 4423 <fieldlink id="object_reference_callback" struct="jvmtiHeapCallbacks"/> | |
| 4424 in <paramlink id="callbacks"/> set | |
| 4425 </th> | |
| 4426 <td> | |
| 4427 No | |
| 4428 </td> | |
| 4429 <td> | |
| 4430 <b>Yes</b> | |
| 4431 </td> | |
| 4432 <td> | |
| 4433 No | |
| 4434 </td> | |
| 4435 </tr> | |
| 4436 <tr> | |
| 4437 <th align="left"> | |
| 4438 <paramlink id="heap_filter"/> | |
| 4439 </th> | |
| 4440 <td> | |
| 4441 No | |
| 4442 </td> | |
| 4443 <td> | |
| 4444 <b>Yes</b> | |
| 4445 </td> | |
| 4446 <td> | |
| 4447 <b>Yes</b> | |
| 4448 </td> | |
| 4449 </tr> | |
| 4450 <tr> | |
| 4451 <th align="left"> | |
| 4452 <paramlink id="klass"/> | |
| 4453 </th> | |
| 4454 <td> | |
| 4455 No | |
| 4456 </td> | |
| 4457 <td> | |
| 4458 <b>Yes</b> | |
| 4459 </td> | |
| 4460 <td> | |
| 4461 <b>Yes</b> | |
| 4462 </td> | |
| 4463 </tr> | |
| 4464 </table> | |
| 4465 <p/> | |
| 4466 During the execution of this function the state of the heap | |
| 4467 does not change: no objects are allocated, no objects are | |
| 4468 garbage collected, and the state of objects (including | |
| 4469 held values) does not change. | |
| 4470 As a result, threads executing Java | |
| 4471 programming language code, threads attempting to resume the | |
| 4472 execution of Java programming language code, and threads | |
| 4473 attempting to execute JNI functions are typically stalled. | |
| 4474 </description> | |
| 4475 <origin>new</origin> | |
| 4476 <capabilities> | |
| 4477 <required id="can_tag_objects"></required> | |
| 4478 </capabilities> | |
| 4479 <parameters> | |
| 4480 <param id="heap_filter"> | |
| 4481 <jint/> | |
| 4482 <description> | |
| 4483 This bit vector of | |
| 4484 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>. | |
| 4485 restricts the objects for which the callback function is called. | |
| 4486 This applies to both the object and primitive callbacks. | |
| 4487 </description> | |
| 4488 </param> | |
| 4489 <param id="klass"> | |
| 4490 <ptrtype> | |
| 4491 <jclass/> | |
| 4492 <nullok>callbacks are not limited to instances of a particular | |
| 4493 class</nullok> | |
| 4494 </ptrtype> | |
| 4495 <description> | |
| 4496 Callbacks are only reported when the object is an instance of | |
| 4497 this class. | |
| 4498 Objects which are instances of a subclass of <code>klass</code> | |
| 4499 are not reported. | |
| 4500 If <code>klass</code> is an interface, no objects are reported. | |
| 4501 This applies to both the object and primitive callbacks. | |
| 4502 </description> | |
| 4503 </param> | |
| 4504 <param id="initial_object"> | |
| 4505 <ptrtype> | |
| 4506 <jobject/> | |
| 4507 <nullok>references are followed from the heap roots</nullok> | |
| 4508 </ptrtype> | |
| 4509 <description> | |
| 4510 The object to follow | |
| 4511 </description> | |
| 4512 </param> | |
| 4513 <param id="callbacks"> | |
| 4514 <inptr> | |
| 4515 <struct>jvmtiHeapCallbacks</struct> | |
| 4516 </inptr> | |
| 4517 <description> | |
| 4518 Structure defining the set of callback functions. | |
| 4519 </description> | |
| 4520 </param> | |
| 4521 <param id="user_data"> | |
| 4522 <inbuf> | |
| 4523 <void/> | |
| 4524 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 4525 </inbuf> | |
| 4526 <description> | |
| 4527 User supplied data to be passed to the callback. | |
| 4528 </description> | |
| 4529 </param> | |
| 4530 </parameters> | |
| 4531 <errors> | |
| 4532 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 4533 <paramlink id="klass"/> is not a valid class. | |
| 4534 </error> | |
| 4535 <error id="JVMTI_ERROR_INVALID_OBJECT"> | |
| 4536 <paramlink id="initial_object"/> is not a valid object. | |
| 4537 </error> | |
| 4538 </errors> | |
| 4539 </function> | |
| 4540 | |
| 4541 | |
| 4542 <function id="IterateThroughHeap" num="116" since="1.1"> | |
| 4543 <synopsis>Iterate Through Heap</synopsis> | |
| 4544 <description> | |
| 4545 Initiate an iteration over all objects in the heap. | |
| 4546 This includes both reachable and | |
| 4547 unreachable objects. Objects are visited in no particular order. | |
| 4548 <p/> | |
| 4549 Heap objects are reported by invoking the agent supplied | |
| 4550 callback function <functionlink id="jvmtiHeapIterationCallback"/>. | |
| 4551 References between objects are not reported. | |
| 4552 If only reachable objects are desired, or if object reference information | |
| 4553 is needed, use <functionlink id="FollowReferences"/>. | |
| 4554 <p/> | |
| 4555 This function can also be used to examine primitive (non-object) values. | |
| 4556 The primitive value of an array or String | |
| 4557 is reported after the object has been visited; | |
| 4558 it is reported by invoking the agent supplied callback function | |
| 4559 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or | |
| 4560 <functionlink id="jvmtiStringPrimitiveValueCallback"/>. | |
| 4561 A primitive field | |
| 4562 is reported after the object with that field is visited; | |
| 4563 it is reported by invoking the agent supplied | |
| 4564 callback function | |
| 4565 <functionlink id="jvmtiPrimitiveFieldCallback"/>. | |
| 4566 <p/> | |
| 4567 Unless the iteration is aborted by the | |
| 4568 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
| 4569 returned by a callback, all objects in the heap are visited. | |
| 4570 Whether a callback is provided or is <code>NULL</code> only determines | |
| 4571 whether the callback will be invoked, it does not influence | |
| 4572 which objects are visited nor does it influence whether other callbacks | |
| 4573 will be invoked. | |
| 4574 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> | |
| 4575 and <paramlink id="klass"/> provided as parameters to this function | |
| 4576 do not control which objects are visited but they do control which | |
| 4577 objects and primitive values are reported by the callbacks. | |
| 4578 For example, if the only callback that was set is | |
| 4579 <paramlink id="array_primitive_value_callback"/> and <code>klass</code> | |
| 4580 is set to the array of bytes class, then only arrays of byte will be | |
| 4581 reported. The table below summarizes this (contrast this with | |
| 4582 <functionlink id="FollowReferences"/>): | |
| 4583 <p/> | |
| 4584 <table> | |
| 4585 <tr> | |
| 4586 <th/> | |
| 4587 <th> | |
| 4588 Controls objects visited | |
| 4589 </th> | |
| 4590 <th> | |
| 4591 Controls objects reported | |
| 4592 </th> | |
| 4593 <th> | |
| 4594 Controls primitives reported | |
| 4595 </th> | |
| 4596 </tr> | |
| 4597 <tr> | |
| 4598 <th align="left"> | |
| 4599 the | |
| 4600 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
| 4601 returned by <functionlink id="jvmtiHeapIterationCallback"/> | |
| 4602 </th> | |
| 4603 <td> | |
| 4604 No<br/>(unless they abort the iteration) | |
| 4605 </td> | |
| 4606 <td> | |
| 4607 No<br/>(unless they abort the iteration) | |
| 4608 </td> | |
| 4609 <td> | |
| 4610 No<br/>(unless they abort the iteration) | |
| 4611 </td> | |
| 4612 </tr> | |
| 4613 <tr> | |
| 4614 <th align="left"> | |
| 4615 <fieldlink id="object_callback" struct="jvmtiHeapCallbacks"/> | |
| 4616 in <paramlink id="callbacks"/> set | |
| 4617 </th> | |
| 4618 <td> | |
| 4619 No | |
| 4620 </td> | |
| 4621 <td> | |
| 4622 <b>Yes</b> | |
| 4623 </td> | |
| 4624 <td> | |
| 4625 No | |
| 4626 </td> | |
| 4627 </tr> | |
| 4628 <tr> | |
| 4629 <th align="left"> | |
| 4630 <paramlink id="heap_filter"/> | |
| 4631 </th> | |
| 4632 <td> | |
| 4633 No | |
| 4634 </td> | |
| 4635 <td> | |
| 4636 <b>Yes</b> | |
| 4637 </td> | |
| 4638 <td> | |
| 4639 <b>Yes</b> | |
| 4640 </td> | |
| 4641 </tr> | |
| 4642 <tr> | |
| 4643 <th align="left"> | |
| 4644 <paramlink id="klass"/> | |
| 4645 </th> | |
| 4646 <td> | |
| 4647 No | |
| 4648 </td> | |
| 4649 <td> | |
| 4650 <b>Yes</b> | |
| 4651 </td> | |
| 4652 <td> | |
| 4653 <b>Yes</b> | |
| 4654 </td> | |
| 4655 </tr> | |
| 4656 </table> | |
| 4657 <p/> | |
| 4658 During the execution of this function the state of the heap | |
| 4659 does not change: no objects are allocated, no objects are | |
| 4660 garbage collected, and the state of objects (including | |
| 4661 held values) does not change. | |
| 4662 As a result, threads executing Java | |
| 4663 programming language code, threads attempting to resume the | |
| 4664 execution of Java programming language code, and threads | |
| 4665 attempting to execute JNI functions are typically stalled. | |
| 4666 </description> | |
| 4667 <origin>new</origin> | |
| 4668 <capabilities> | |
| 4669 <required id="can_tag_objects"></required> | |
| 4670 </capabilities> | |
| 4671 <parameters> | |
| 4672 <param id="heap_filter"> | |
| 4673 <jint/> | |
| 4674 <description> | |
| 4675 This bit vector of | |
| 4676 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>. | |
| 4677 restricts the objects for which the callback function is called. | |
| 4678 This applies to both the object and primitive callbacks. | |
| 4679 </description> | |
| 4680 </param> | |
| 4681 <param id="klass"> | |
| 4682 <ptrtype> | |
| 4683 <jclass/> | |
| 4684 <nullok>callbacks are not limited to instances of a particular class</nullok> | |
| 4685 </ptrtype> | |
| 4686 <description> | |
| 4687 Callbacks are only reported when the object is an instance of | |
| 4688 this class. | |
| 4689 Objects which are instances of a subclass of <code>klass</code> | |
| 4690 are not reported. | |
| 4691 If <code>klass</code> is an interface, no objects are reported. | |
| 4692 This applies to both the object and primitive callbacks. | |
| 4693 </description> | |
| 4694 </param> | |
| 4695 <param id="callbacks"> | |
| 4696 <inptr> | |
| 4697 <struct>jvmtiHeapCallbacks</struct> | |
| 4698 </inptr> | |
| 4699 <description> | |
| 4700 Structure defining the set callback functions. | |
| 4701 </description> | |
| 4702 </param> | |
| 4703 <param id="user_data"> | |
| 4704 <inbuf> | |
| 4705 <void/> | |
| 4706 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 4707 </inbuf> | |
| 4708 <description> | |
| 4709 User supplied data to be passed to the callback. | |
| 4710 </description> | |
| 4711 </param> | |
| 4712 </parameters> | |
| 4713 <errors> | |
| 4714 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 4715 <paramlink id="klass"/> is not a valid class. | |
| 4716 </error> | |
| 4717 </errors> | |
| 4718 </function> | |
| 4719 | |
| 4720 <function id="GetTag" phase="start" num="106"> | |
| 4721 <synopsis>Get Tag</synopsis> | |
| 4722 <description> | |
| 4723 Retrieve the tag associated with an object. | |
| 4724 The tag is a long value typically used to store a | |
| 4725 unique identifier or pointer to object information. | |
| 4726 The tag is set with | |
| 4727 <functionlink id="SetTag"></functionlink>. | |
| 4728 Objects for which no tags have been set return a | |
| 4729 tag value of zero. | |
| 4730 </description> | |
| 4731 <origin>new</origin> | |
| 4732 <capabilities> | |
| 4733 <required id="can_tag_objects"></required> | |
| 4734 </capabilities> | |
| 4735 <parameters> | |
| 4736 <param id="object"> | |
| 4737 <jobject/> | |
| 4738 <description> | |
| 4739 The object whose tag is to be retrieved. | |
| 4740 </description> | |
| 4741 </param> | |
| 4742 <param id="tag_ptr"> | |
| 4743 <outptr><jlong/></outptr> | |
| 4744 <description> | |
| 4745 On return, the referenced long is set to the value | |
| 4746 of the tag. | |
| 4747 </description> | |
| 4748 </param> | |
| 4749 </parameters> | |
| 4750 <errors> | |
| 4751 </errors> | |
| 4752 </function> | |
| 4753 | |
| 4754 <function id="SetTag" phase="start" num="107"> | |
| 4755 <synopsis>Set Tag</synopsis> | |
| 4756 <description> | |
| 4757 Set the tag associated with an object. | |
| 4758 The tag is a long value typically used to store a | |
| 4759 unique identifier or pointer to object information. | |
| 4760 The tag is visible with | |
| 4761 <functionlink id="GetTag"></functionlink>. | |
| 4762 </description> | |
| 4763 <origin>new</origin> | |
| 4764 <capabilities> | |
| 4765 <required id="can_tag_objects"></required> | |
| 4766 </capabilities> | |
| 4767 <parameters> | |
| 4768 <param id="object"> | |
| 4769 <jobject/> | |
| 4770 <description> | |
| 4771 The object whose tag is to be set. | |
| 4772 </description> | |
| 4773 </param> | |
| 4774 <param id="tag"> | |
| 4775 <jlong/> | |
| 4776 <description> | |
| 4777 The new value of the tag. | |
| 4778 </description> | |
| 4779 </param> | |
| 4780 </parameters> | |
| 4781 <errors> | |
| 4782 </errors> | |
| 4783 </function> | |
| 4784 | |
| 4785 <function id="GetObjectsWithTags" num="114"> | |
| 4786 <synopsis>Get Objects With Tags</synopsis> | |
| 4787 <description> | |
| 4788 Return objects in the heap with the specified tags. | |
| 4789 The format is parallel arrays of objects and tags. | |
| 4790 </description> | |
| 4791 <origin>new</origin> | |
| 4792 <capabilities> | |
| 4793 <required id="can_tag_objects"></required> | |
| 4794 </capabilities> | |
| 4795 <parameters> | |
| 4796 <param id="tag_count"> | |
| 4797 <jint min="0"/> | |
| 4798 <description> | |
| 4799 Number of tags to scan for. | |
| 4800 </description> | |
| 4801 </param> | |
| 4802 <param id="tags"> | |
| 4803 <inbuf incount="tag_count"> | |
| 4804 <jlong/> | |
| 4805 </inbuf> | |
| 4806 <description> | |
| 4807 Scan for objects with these tags. | |
| 4808 Zero is not permitted in this array. | |
| 4809 </description> | |
| 4810 </param> | |
| 4811 <param id="count_ptr"> | |
| 4812 <outptr> | |
| 4813 <jint/> | |
| 4814 </outptr> | |
| 4815 <description> | |
| 4816 Return the number of objects with any of the tags | |
| 4817 in <paramlink id="tags"/>. | |
| 4818 </description> | |
| 4819 </param> | |
| 4820 <param id="object_result_ptr"> | |
| 4821 <allocbuf outcount="count_ptr"> | |
| 4822 <jobject/> | |
| 4823 <nullok>this information is not returned</nullok> | |
| 4824 </allocbuf> | |
| 4825 <description> | |
| 4826 Returns the array of objects with any of the tags | |
| 4827 in <paramlink id="tags"/>. | |
| 4828 </description> | |
| 4829 </param> | |
| 4830 <param id="tag_result_ptr"> | |
| 4831 <allocbuf outcount="count_ptr"> | |
| 4832 <jlong/> | |
| 4833 <nullok>this information is not returned</nullok> | |
| 4834 </allocbuf> | |
| 4835 <description> | |
| 4836 For each object in <paramlink id="object_result_ptr"/>, | |
| 4837 return the tag at the corresponding index. | |
| 4838 </description> | |
| 4839 </param> | |
| 4840 </parameters> | |
| 4841 <errors> | |
| 4842 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 4843 Zero is present in <paramlink id="tags"></paramlink>. | |
| 4844 </error> | |
| 4845 </errors> | |
| 4846 </function> | |
| 4847 | |
| 4848 <function id="ForceGarbageCollection" num="108"> | |
| 4849 <synopsis>Force Garbage Collection</synopsis> | |
| 4850 <description> | |
| 4851 Force the VM to perform a garbage collection. | |
| 4852 The garbage collection is as complete as possible. | |
| 4853 This function does not cause finalizers to be run. | |
| 4854 This function does not return until the garbage collection | |
| 4855 is finished. | |
| 4856 <p/> | |
| 4857 Although garbage collection is as complete | |
| 4858 as possible there is no guarantee that all | |
| 4859 <eventlink id="ObjectFree"/> | |
| 4860 events will have been | |
| 4861 sent by the time that this function | |
| 4862 returns. In particular, an object may be | |
| 4863 prevented from being freed because it | |
| 4864 is awaiting finalization. | |
| 4865 </description> | |
| 4866 <origin>new</origin> | |
| 4867 <capabilities> | |
| 4868 </capabilities> | |
| 4869 <parameters> | |
| 4870 </parameters> | |
| 4871 <errors> | |
| 4872 </errors> | |
| 4873 </function> | |
| 4874 | |
| 4875 | |
| 4876 </category> | |
| 4877 | |
| 4878 <category id="Heap_1_0" label="Heap (1.0)"> | |
| 4879 <intro> | |
| 4880 <b> | |
| 4881 These functions and data types were introduced in the original | |
| 4882 <jvmti/> version 1.0 and have been superseded by more | |
| 4883 </b> | |
| 4884 <internallink id="Heap"><b>powerful and flexible versions</b></internallink> | |
| 4885 <b> | |
| 4886 which: | |
| 4887 </b> | |
| 4888 <ul> | |
| 4889 <li> | |
| 4890 <b> | |
| 4891 Allow access to primitive values (the value of Strings, arrays, | |
| 4892 and primitive fields) | |
| 4893 </b> | |
| 4894 </li> | |
| 4895 <li> | |
| 4896 <b> | |
| 4897 Allow the tag of the referrer to be set, thus enabling more | |
| 4898 efficient localized reference graph building | |
| 4899 </b> | |
| 4900 </li> | |
| 4901 <li> | |
| 4902 <b> | |
| 4903 Provide more extensive filtering abilities | |
| 4904 </b> | |
| 4905 </li> | |
| 4906 <li> | |
| 4907 <b> | |
| 4908 Are extensible, allowing their abilities to grow in future versions of <jvmti/> | |
| 4909 </b> | |
| 4910 </li> | |
| 4911 </ul> | |
| 4912 <p/> | |
| 4913 <b>Please use the </b> | |
| 4914 <internallink id="Heap"><b>current Heap functions</b></internallink>. | |
| 4915 <p/> | |
| 4916 <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum"> | |
| 4917 <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1"> | |
| 4918 Tagged objects only. | |
| 4919 </constant> | |
| 4920 <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2"> | |
| 4921 Untagged objects only. | |
| 4922 </constant> | |
| 4923 <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3"> | |
| 4924 Either tagged or untagged objects. | |
| 4925 </constant> | |
| 4926 </constants> | |
| 4927 | |
| 4928 <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum"> | |
| 4929 <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1"> | |
| 4930 JNI global reference. | |
| 4931 </constant> | |
| 4932 <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2"> | |
| 4933 System class. | |
| 4934 </constant> | |
| 4935 <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3"> | |
| 4936 Monitor. | |
| 4937 </constant> | |
| 4938 <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4"> | |
| 4939 Stack local. | |
| 4940 </constant> | |
| 4941 <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5"> | |
| 4942 JNI local reference. | |
| 4943 </constant> | |
| 4944 <constant id="JVMTI_HEAP_ROOT_THREAD" num="6"> | |
| 4945 Thread. | |
| 4946 </constant> | |
| 4947 <constant id="JVMTI_HEAP_ROOT_OTHER" num="7"> | |
| 4948 Other. | |
| 4949 </constant> | |
| 4950 </constants> | |
| 4951 | |
| 4952 <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum"> | |
| 4953 <constant id="JVMTI_REFERENCE_CLASS" num="1"> | |
| 4954 Reference from an object to its class. | |
| 4955 </constant> | |
| 4956 <constant id="JVMTI_REFERENCE_FIELD" num="2"> | |
| 4957 Reference from an object to the value of one of its instance fields. | |
| 4958 For references of this kind the <code>referrer_index</code> | |
| 4959 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 4960 jvmtiObjectReferenceCallback</internallink> is the index of the | |
| 4961 the instance field. The index is based on the order of all the | |
| 4962 object's fields. This includes all fields of the directly declared | |
| 4963 static and instance fields in the class, and includes all fields (both | |
| 4964 public and private) fields declared in superclasses and superinterfaces. | |
| 4965 The index is thus calculated by summing the index of the field in the directly | |
| 4966 declared class (see <functionlink id="GetClassFields"/>), with the total | |
| 4967 number of fields (both public and private) declared in all superclasses | |
| 4968 and superinterfaces. The index starts at zero. | |
| 4969 </constant> | |
| 4970 <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3"> | |
| 4971 Reference from an array to one of its elements. | |
| 4972 For references of this kind the <code>referrer_index</code> | |
| 4973 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 4974 jvmtiObjectReferenceCallback</internallink> is the array index. | |
| 4975 </constant> | |
| 4976 <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4"> | |
| 4977 Reference from a class to its class loader. | |
| 4978 </constant> | |
| 4979 <constant id="JVMTI_REFERENCE_SIGNERS" num="5"> | |
| 4980 Reference from a class to its signers array. | |
| 4981 </constant> | |
| 4982 <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6"> | |
| 4983 Reference from a class to its protection domain. | |
| 4984 </constant> | |
| 4985 <constant id="JVMTI_REFERENCE_INTERFACE" num="7"> | |
| 4986 Reference from a class to one of its interfaces. | |
| 4987 </constant> | |
| 4988 <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8"> | |
| 4989 Reference from a class to the value of one of its static fields. | |
| 4990 For references of this kind the <code>referrer_index</code> | |
| 4991 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 4992 jvmtiObjectReferenceCallback</internallink> is the index of the | |
| 4993 the static field. The index is based on the order of all the | |
| 4994 object's fields. This includes all fields of the directly declared | |
| 4995 static and instance fields in the class, and includes all fields (both | |
| 4996 public and private) fields declared in superclasses and superinterfaces. | |
| 4997 The index is thus calculated by summing the index of the field in the directly | |
| 4998 declared class (see <functionlink id="GetClassFields"/>), with the total | |
| 4999 number of fields (both public and private) declared in all superclasses | |
| 5000 and superinterfaces. The index starts at zero. | |
| 5001 Note: this definition differs from that in the <jvmti/> 1.0 Specification. | |
| 5002 <rationale>No known implementations used the 1.0 definition.</rationale> | |
| 5003 </constant> | |
| 5004 <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9"> | |
| 5005 Reference from a class to a resolved entry in the constant pool. | |
| 5006 For references of this kind the <code>referrer_index</code> | |
| 5007 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 5008 jvmtiObjectReferenceCallback</internallink> is the index into | |
| 5009 constant pool table of the class, starting at 1. See the | |
| 5010 <vmspeclink id="ClassFile.doc.html#20080" | |
| 5011 name="Constant Pool section"/> | |
| 5012 </constant> | |
| 5013 </constants> | |
| 5014 | |
| 5015 <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum"> | |
| 5016 <constant id="JVMTI_ITERATION_CONTINUE" num="1"> | |
| 5017 Continue the iteration. | |
| 5018 If this is a reference iteration, follow the references of this object. | |
| 5019 </constant> | |
| 5020 <constant id="JVMTI_ITERATION_IGNORE" num="2"> | |
| 5021 Continue the iteration. | |
| 5022 If this is a reference iteration, ignore the references of this object. | |
| 5023 </constant> | |
| 5024 <constant id="JVMTI_ITERATION_ABORT" num="0"> | |
| 5025 Abort the iteration. | |
| 5026 </constant> | |
| 5027 </constants> | |
| 5028 </intro> | |
| 5029 | |
| 5030 <callback id="jvmtiHeapObjectCallback"> | |
| 5031 <enum>jvmtiIterationControl</enum> | |
| 5032 <synopsis>Heap Object Callback</synopsis> | |
| 5033 <description> | |
| 5034 Agent supplied callback function. | |
| 5035 Describes (but does not pass in) an object in the heap. | |
| 5036 <p/> | |
| 5037 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5038 or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5039 <p/> | |
| 5040 See the <internallink id="heapCallbacks">heap callback | |
| 5041 function restrictions</internallink>. | |
| 5042 </description> | |
| 5043 <parameters> | |
| 5044 <param id="class_tag"> | |
| 5045 <jlong/> | |
| 5046 <description> | |
| 5047 The tag of the class of object (zero if the class is not tagged). | |
| 5048 If the object represents a runtime class, | |
| 5049 the <code>class_tag</code> is the tag | |
| 5050 associated with <code>java.lang.Class</code> | |
| 5051 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5052 </description> | |
| 5053 </param> | |
| 5054 <param id="size"> | |
| 5055 <jlong/> | |
| 5056 <description> | |
| 5057 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 5058 </description> | |
| 5059 </param> | |
| 5060 <param id="tag_ptr"> | |
| 5061 <outptr><jlong/></outptr> | |
| 5062 <description> | |
| 5063 The object tag value, or zero if the object is not tagged. | |
| 5064 To set the tag value to be associated with the object | |
| 5065 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5066 </description> | |
| 5067 </param> | |
| 5068 <param id="user_data"> | |
| 5069 <outptr><void/></outptr> | |
| 5070 <description> | |
| 5071 The user supplied data that was passed into the iteration function. | |
| 5072 </description> | |
| 5073 </param> | |
| 5074 </parameters> | |
| 5075 </callback> | |
| 5076 | |
| 5077 <callback id="jvmtiHeapRootCallback"> | |
| 5078 <enum>jvmtiIterationControl</enum> | |
| 5079 <synopsis>Heap Root Object Callback</synopsis> | |
| 5080 <description> | |
| 5081 Agent supplied callback function. | |
| 5082 Describes (but does not pass in) an object that is a root for the purposes | |
| 5083 of garbage collection. | |
| 5084 <p/> | |
| 5085 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5086 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
| 5087 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5088 <p/> | |
| 5089 See the <internallink id="heapCallbacks">heap callback | |
| 5090 function restrictions</internallink>. | |
| 5091 </description> | |
| 5092 <parameters> | |
| 5093 <param id="root_kind"> | |
| 5094 <enum>jvmtiHeapRootKind</enum> | |
| 5095 <description> | |
| 5096 The kind of heap root. | |
| 5097 </description> | |
| 5098 </param> | |
| 5099 <param id="class_tag"> | |
| 5100 <jlong/> | |
| 5101 <description> | |
| 5102 The tag of the class of object (zero if the class is not tagged). | |
| 5103 If the object represents a runtime class, the <code>class_tag</code> is the tag | |
| 5104 associated with <code>java.lang.Class</code> | |
| 5105 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5106 </description> | |
| 5107 </param> | |
| 5108 <param id="size"> | |
| 5109 <jlong/> | |
| 5110 <description> | |
| 5111 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 5112 </description> | |
| 5113 </param> | |
| 5114 <param id="tag_ptr"> | |
| 5115 <outptr><jlong/></outptr> | |
| 5116 <description> | |
| 5117 The object tag value, or zero if the object is not tagged. | |
| 5118 To set the tag value to be associated with the object | |
| 5119 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5120 </description> | |
| 5121 </param> | |
| 5122 <param id="user_data"> | |
| 5123 <outptr><void/></outptr> | |
| 5124 <description> | |
| 5125 The user supplied data that was passed into the iteration function. | |
| 5126 </description> | |
| 5127 </param> | |
| 5128 </parameters> | |
| 5129 </callback> | |
| 5130 | |
| 5131 <callback id="jvmtiStackReferenceCallback"> | |
| 5132 <enum>jvmtiIterationControl</enum> | |
| 5133 <synopsis>Stack Reference Object Callback</synopsis> | |
| 5134 <description> | |
| 5135 Agent supplied callback function. | |
| 5136 Describes (but does not pass in) an object on the stack that is a root for | |
| 5137 the purposes of garbage collection. | |
| 5138 <p/> | |
| 5139 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5140 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
| 5141 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5142 <p/> | |
| 5143 See the <internallink id="heapCallbacks">heap callback | |
| 5144 function restrictions</internallink>. | |
| 5145 </description> | |
| 5146 <parameters> | |
| 5147 <param id="root_kind"> | |
| 5148 <enum>jvmtiHeapRootKind</enum> | |
| 5149 <description> | |
| 5150 The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or | |
| 5151 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>). | |
| 5152 </description> | |
| 5153 </param> | |
| 5154 <param id="class_tag"> | |
| 5155 <jlong/> | |
| 5156 <description> | |
| 5157 The tag of the class of object (zero if the class is not tagged). | |
| 5158 If the object represents a runtime class, the <code>class_tag</code> is the tag | |
| 5159 associated with <code>java.lang.Class</code> | |
| 5160 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5161 </description> | |
| 5162 </param> | |
| 5163 <param id="size"> | |
| 5164 <jlong/> | |
| 5165 <description> | |
| 5166 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 5167 </description> | |
| 5168 </param> | |
| 5169 <param id="tag_ptr"> | |
| 5170 <outptr><jlong/></outptr> | |
| 5171 <description> | |
| 5172 The object tag value, or zero if the object is not tagged. | |
| 5173 To set the tag value to be associated with the object | |
| 5174 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5175 </description> | |
| 5176 </param> | |
| 5177 <param id="thread_tag"> | |
| 5178 <jlong/> | |
| 5179 <description> | |
| 5180 The tag of the thread corresponding to this stack, zero if not tagged. | |
| 5181 </description> | |
| 5182 </param> | |
| 5183 <param id="depth"> | |
| 5184 <jint/> | |
| 5185 <description> | |
| 5186 The depth of the frame. | |
| 5187 </description> | |
| 5188 </param> | |
| 5189 <param id="method"> | |
| 5190 <jmethodID/> | |
| 5191 <description> | |
| 5192 The method executing in this frame. | |
| 5193 </description> | |
| 5194 </param> | |
| 5195 <param id="slot"> | |
| 5196 <jint/> | |
| 5197 <description> | |
| 5198 The slot number. | |
| 5199 </description> | |
| 5200 </param> | |
| 5201 <param id="user_data"> | |
| 5202 <outptr><void/></outptr> | |
| 5203 <description> | |
| 5204 The user supplied data that was passed into the iteration function. | |
| 5205 </description> | |
| 5206 </param> | |
| 5207 </parameters> | |
| 5208 </callback> | |
| 5209 | |
| 5210 <callback id="jvmtiObjectReferenceCallback"> | |
| 5211 <enum>jvmtiIterationControl</enum> | |
| 5212 <synopsis>Object Reference Callback</synopsis> | |
| 5213 <description> | |
| 5214 Agent supplied callback function. | |
| 5215 Describes a reference from an object (the referrer) to another object | |
| 5216 (the referree). | |
| 5217 <p/> | |
| 5218 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5219 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
| 5220 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5221 <p/> | |
| 5222 See the <internallink id="heapCallbacks">heap callback | |
| 5223 function restrictions</internallink>. | |
| 5224 </description> | |
| 5225 <parameters> | |
| 5226 <param id="reference_kind"> | |
| 5227 <enum>jvmtiObjectReferenceKind</enum> | |
| 5228 <description> | |
| 5229 The type of reference. | |
| 5230 </description> | |
| 5231 </param> | |
| 5232 <param id="class_tag"> | |
| 5233 <jlong/> | |
| 5234 <description> | |
| 5235 The tag of the class of referree object (zero if the class is not tagged). | |
| 5236 If the referree object represents a runtime class, | |
| 5237 the <code>class_tag</code> is the tag | |
| 5238 associated with <code>java.lang.Class</code> | |
| 5239 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5240 </description> | |
| 5241 </param> | |
| 5242 <param id="size"> | |
| 5243 <jlong/> | |
| 5244 <description> | |
| 5245 Size of the referree object (in bytes). | |
| 5246 See <functionlink id="GetObjectSize"/>. | |
| 5247 </description> | |
| 5248 </param> | |
| 5249 <param id="tag_ptr"> | |
| 5250 <outptr><jlong/></outptr> | |
| 5251 <description> | |
| 5252 The referree object tag value, or zero if the object is not | |
| 5253 tagged. | |
| 5254 To set the tag value to be associated with the object | |
| 5255 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5256 </description> | |
| 5257 </param> | |
| 5258 <param id="referrer_tag"> | |
| 5259 <jlong/> | |
| 5260 <description> | |
| 5261 The tag of the referrer object, or zero if the referrer | |
| 5262 object is not tagged. | |
| 5263 </description> | |
| 5264 </param> | |
| 5265 <param id="referrer_index"> | |
| 5266 <jint/> | |
| 5267 <description> | |
| 5268 For references of type <code>JVMTI_REFERENCE_FIELD</code> or | |
| 5269 <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index | |
| 5270 of the field in the referrer object. The index is based on the | |
| 5271 order of all the object's fields - see <internallink | |
| 5272 id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink> | |
| 5273 or <internallink | |
| 5274 id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD | |
| 5275 </internallink> for further description. | |
| 5276 <p/> | |
| 5277 For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code> | |
| 5278 the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT"> | |
| 5279 JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description. | |
| 5280 <p/> | |
| 5281 For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code> | |
| 5282 the index into the constant pool of the class - see | |
| 5283 <internallink id="JVMTI_REFERENCE_CONSTANT_POOL"> | |
| 5284 JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further | |
| 5285 description. | |
| 5286 <p/> | |
| 5287 For references of other kinds the <code>referrer_index</code> is | |
| 5288 <code>-1</code>. | |
| 5289 </description> | |
| 5290 </param> | |
| 5291 <param id="user_data"> | |
| 5292 <outptr><void/></outptr> | |
| 5293 <description> | |
| 5294 The user supplied data that was passed into the iteration function. | |
| 5295 </description> | |
| 5296 </param> | |
| 5297 </parameters> | |
| 5298 </callback> | |
| 5299 | |
| 5300 <function id="IterateOverObjectsReachableFromObject" num="109"> | |
| 5301 <synopsis>Iterate Over Objects Reachable From Object</synopsis> | |
| 5302 <description> | |
| 5303 This function iterates over all objects that are directly | |
| 5304 and indirectly reachable from the specified object. | |
| 5305 For each object <i>A</i> (known | |
| 5306 as the referrer) with a reference to object <i>B</i> the specified | |
| 5307 callback function is called to describe the object reference. | |
| 5308 The callback is called exactly once for each reference from a referrer; | |
| 5309 this is true even if there are reference cycles or multiple paths to | |
| 5310 the referrer. | |
| 5311 There may be more than one reference between a referrer and a referree, | |
| 5312 These may be distinguished by the | |
| 5313 <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and | |
| 5314 <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>. | |
| 5315 The callback for an object will always occur after the callback for | |
| 5316 its referrer. | |
| 5317 <p/> | |
| 5318 See <functionlink id="FollowReferences"/> for the object | |
| 5319 references which are reported. | |
| 5320 <p/> | |
| 5321 During the execution of this function the state of the heap | |
| 5322 does not change: no objects are allocated, no objects are | |
| 5323 garbage collected, and the state of objects (including | |
| 5324 held values) does not change. | |
| 5325 As a result, threads executing Java | |
| 5326 programming language code, threads attempting to resume the | |
| 5327 execution of Java programming language code, and threads | |
| 5328 attempting to execute JNI functions are typically stalled. | |
| 5329 </description> | |
| 5330 <origin>new</origin> | |
| 5331 <capabilities> | |
| 5332 <required id="can_tag_objects"></required> | |
| 5333 </capabilities> | |
| 5334 <parameters> | |
| 5335 <param id="object"> | |
| 5336 <jobject/> | |
| 5337 <description> | |
| 5338 The object | |
| 5339 </description> | |
| 5340 </param> | |
| 5341 <param id="object_reference_callback"> | |
| 5342 <ptrtype> | |
| 5343 <struct>jvmtiObjectReferenceCallback</struct> | |
| 5344 </ptrtype> | |
| 5345 <description> | |
| 5346 The callback to be called to describe each | |
| 5347 object reference. | |
| 5348 </description> | |
| 5349 </param> | |
| 5350 <param id="user_data"> | |
| 5351 <inbuf> | |
| 5352 <void/> | |
| 5353 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5354 </inbuf> | |
| 5355 <description> | |
| 5356 User supplied data to be passed to the callback. | |
| 5357 </description> | |
| 5358 </param> | |
| 5359 </parameters> | |
| 5360 <errors> | |
| 5361 </errors> | |
| 5362 </function> | |
| 5363 | |
| 5364 <function id="IterateOverReachableObjects" num="110"> | |
| 5365 <synopsis>Iterate Over Reachable Objects</synopsis> | |
| 5366 <description> | |
| 5367 This function iterates over the root objects and all objects that | |
| 5368 are directly and indirectly reachable from the root objects. | |
| 5369 The root objects comprise the set of system classes, | |
| 5370 JNI globals, references from thread stacks, and other objects used as roots | |
| 5371 for the purposes of garbage collection. | |
| 5372 <p/> | |
| 5373 For each root the <paramlink id="heap_root_callback"></paramlink> | |
| 5374 or <paramlink id="stack_ref_callback"></paramlink> callback is called. | |
| 5375 An object can be a root object for more than one reason and in that case | |
| 5376 the appropriate callback is called for each reason. | |
| 5377 <p/> | |
| 5378 For each object reference the <paramlink id="object_ref_callback"></paramlink> | |
| 5379 callback function is called to describe the object reference. | |
| 5380 The callback is called exactly once for each reference from a referrer; | |
| 5381 this is true even if there are reference cycles or multiple paths to | |
| 5382 the referrer. | |
| 5383 There may be more than one reference between a referrer and a referree, | |
| 5384 These may be distinguished by the | |
| 5385 <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and | |
| 5386 <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>. | |
| 5387 The callback for an object will always occur after the callback for | |
| 5388 its referrer. | |
| 5389 <p/> | |
| 5390 See <functionlink id="FollowReferences"/> for the object | |
| 5391 references which are reported. | |
| 5392 <p/> | |
| 5393 Roots are always reported to the profiler before any object references | |
| 5394 are reported. In other words, the <paramlink id="object_ref_callback"></paramlink> | |
| 5395 callback will not be called until the appropriate callback has been called | |
| 5396 for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is | |
| 5397 specified as <code>NULL</code> then this function returns after | |
| 5398 reporting the root objects to the profiler. | |
| 5399 <p/> | |
| 5400 During the execution of this function the state of the heap | |
| 5401 does not change: no objects are allocated, no objects are | |
| 5402 garbage collected, and the state of objects (including | |
| 5403 held values) does not change. | |
| 5404 As a result, threads executing Java | |
| 5405 programming language code, threads attempting to resume the | |
| 5406 execution of Java programming language code, and threads | |
| 5407 attempting to execute JNI functions are typically stalled. | |
| 5408 </description> | |
| 5409 <origin>new</origin> | |
| 5410 <capabilities> | |
| 5411 <required id="can_tag_objects"></required> | |
| 5412 </capabilities> | |
| 5413 <parameters> | |
| 5414 <param id="heap_root_callback"> | |
| 5415 <ptrtype> | |
| 5416 <struct>jvmtiHeapRootCallback</struct> | |
| 5417 <nullok>do not report heap roots</nullok> | |
| 5418 </ptrtype> | |
| 5419 <description> | |
| 5420 The callback function to be called for each heap root of type | |
| 5421 <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>, | |
| 5422 <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>, | |
| 5423 <code>JVMTI_HEAP_ROOT_MONITOR</code>, | |
| 5424 <code>JVMTI_HEAP_ROOT_THREAD</code>, or | |
| 5425 <code>JVMTI_HEAP_ROOT_OTHER</code>. | |
| 5426 </description> | |
| 5427 </param> | |
| 5428 <param id="stack_ref_callback"> | |
| 5429 <ptrtype> | |
| 5430 <struct>jvmtiStackReferenceCallback</struct> | |
| 5431 <nullok>do not report stack references</nullok> | |
| 5432 </ptrtype> | |
| 5433 <description> | |
| 5434 The callback function to be called for each heap root of | |
| 5435 <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or | |
| 5436 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>. | |
| 5437 </description> | |
| 5438 </param> | |
| 5439 <param id="object_ref_callback"> | |
| 5440 <ptrtype> | |
| 5441 <struct>jvmtiObjectReferenceCallback</struct> | |
| 5442 <nullok>do not follow references from the root objects</nullok> | |
| 5443 </ptrtype> | |
| 5444 <description> | |
| 5445 The callback function to be called for each object reference. | |
| 5446 </description> | |
| 5447 </param> | |
| 5448 <param id="user_data"> | |
| 5449 <inbuf> | |
| 5450 <void/> | |
| 5451 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5452 </inbuf> | |
| 5453 <description> | |
| 5454 User supplied data to be passed to the callback. | |
| 5455 </description> | |
| 5456 </param> | |
| 5457 </parameters> | |
| 5458 <errors> | |
| 5459 </errors> | |
| 5460 </function> | |
| 5461 | |
| 5462 <function id="IterateOverHeap" num="111"> | |
| 5463 <synopsis>Iterate Over Heap</synopsis> | |
| 5464 <description> | |
| 5465 Iterate over all objects in the heap. This includes both reachable and | |
| 5466 unreachable objects. | |
| 5467 <p/> | |
| 5468 The <paramlink id="object_filter"></paramlink> parameter indicates the | |
| 5469 objects for which the callback function is called. If this parameter | |
| 5470 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be | |
| 5471 called for every object that is tagged. If the parameter is | |
| 5472 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be | |
| 5473 for objects that are not tagged. If the parameter | |
| 5474 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be | |
| 5475 called for every object in the heap, irrespective of whether it is | |
| 5476 tagged or not. | |
| 5477 <p/> | |
| 5478 During the execution of this function the state of the heap | |
| 5479 does not change: no objects are allocated, no objects are | |
| 5480 garbage collected, and the state of objects (including | |
| 5481 held values) does not change. | |
| 5482 As a result, threads executing Java | |
| 5483 programming language code, threads attempting to resume the | |
| 5484 execution of Java programming language code, and threads | |
| 5485 attempting to execute JNI functions are typically stalled. | |
| 5486 </description> | |
| 5487 <origin>new</origin> | |
| 5488 <capabilities> | |
| 5489 <required id="can_tag_objects"></required> | |
| 5490 </capabilities> | |
| 5491 <parameters> | |
| 5492 <param id="object_filter"> | |
| 5493 <enum>jvmtiHeapObjectFilter</enum> | |
| 5494 <description> | |
| 5495 Indicates the objects for which the callback function is called. | |
| 5496 </description> | |
| 5497 </param> | |
| 5498 <param id="heap_object_callback"> | |
| 5499 <ptrtype> | |
| 5500 <struct>jvmtiHeapObjectCallback</struct> | |
| 5501 </ptrtype> | |
| 5502 <description> | |
| 5503 The iterator function to be called for each | |
| 5504 object matching the <paramlink id="object_filter"/>. | |
| 5505 </description> | |
| 5506 </param> | |
| 5507 <param id="user_data"> | |
| 5508 <inbuf> | |
| 5509 <void/> | |
| 5510 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5511 </inbuf> | |
| 5512 <description> | |
| 5513 User supplied data to be passed to the callback. | |
| 5514 </description> | |
| 5515 </param> | |
| 5516 </parameters> | |
| 5517 <errors> | |
| 5518 </errors> | |
| 5519 </function> | |
| 5520 | |
| 5521 <function id="IterateOverInstancesOfClass" num="112"> | |
| 5522 <synopsis>Iterate Over Instances Of Class</synopsis> | |
| 5523 <description> | |
| 5524 Iterate over all objects in the heap that are instances of the specified class. | |
| 5525 This includes direct instances of the specified class and | |
| 5526 instances of all subclasses of the specified class. | |
| 5527 This includes both reachable and unreachable objects. | |
| 5528 <p/> | |
| 5529 The <paramlink id="object_filter"></paramlink> parameter indicates the | |
| 5530 objects for which the callback function is called. If this parameter | |
| 5531 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be | |
| 5532 called for every object that is tagged. If the parameter is | |
| 5533 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be | |
| 5534 called for objects that are not tagged. If the parameter | |
| 5535 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be | |
| 5536 called for every object in the heap, irrespective of whether it is | |
| 5537 tagged or not. | |
| 5538 <p/> | |
| 5539 During the execution of this function the state of the heap | |
| 5540 does not change: no objects are allocated, no objects are | |
| 5541 garbage collected, and the state of objects (including | |
| 5542 held values) does not change. | |
| 5543 As a result, threads executing Java | |
| 5544 programming language code, threads attempting to resume the | |
| 5545 execution of Java programming language code, and threads | |
| 5546 attempting to execute JNI functions are typically stalled. | |
| 5547 </description> | |
| 5548 <origin>new</origin> | |
| 5549 <capabilities> | |
| 5550 <required id="can_tag_objects"></required> | |
| 5551 </capabilities> | |
| 5552 <parameters> | |
| 5553 <param id="klass"> | |
| 5554 <jclass/> | |
| 5555 <description> | |
| 5556 Iterate over objects of this class only. | |
| 5557 </description> | |
| 5558 </param> | |
| 5559 <param id="object_filter"> | |
| 5560 <enum>jvmtiHeapObjectFilter</enum> | |
| 5561 <description> | |
| 5562 Indicates the objects for which the callback function is called. | |
| 5563 </description> | |
| 5564 </param> | |
| 5565 <param id="heap_object_callback"> | |
| 5566 <ptrtype> | |
| 5567 <struct>jvmtiHeapObjectCallback</struct> | |
| 5568 </ptrtype> | |
| 5569 <description> | |
| 5570 The iterator function to be called for each | |
| 5571 <paramlink id="klass"/> instance matching | |
| 5572 the <paramlink id="object_filter"/>. | |
| 5573 </description> | |
| 5574 </param> | |
| 5575 <param id="user_data"> | |
| 5576 <inbuf> | |
| 5577 <void/> | |
| 5578 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5579 </inbuf> | |
| 5580 <description> | |
| 5581 User supplied data to be passed to the callback. | |
| 5582 </description> | |
| 5583 </param> | |
| 5584 </parameters> | |
| 5585 <errors> | |
| 5586 </errors> | |
| 5587 </function> | |
| 5588 | |
| 5589 </category> | |
| 5590 | |
| 5591 <category id="local" label="Local Variable"> | |
| 5592 | |
| 5593 <intro> | |
| 5594 These functions are used to retrieve or set the value of a local variable. | |
| 5595 The variable is identified by the depth of the frame containing its | |
| 5596 value and the variable's slot number within that frame. | |
| 5597 The mapping of variables to | |
| 5598 slot numbers can be obtained with the function | |
| 5599 <functionlink id="GetLocalVariableTable"></functionlink>. | |
| 5600 </intro> | |
| 5601 | |
| 5602 <function id="GetLocalObject" num="21"> | |
| 5603 <synopsis>Get Local Variable - Object</synopsis> | |
| 5604 <description> | |
| 5605 This function can be used to retrieve the value of a local | |
| 5606 variable whose type is <code>Object</code> or a subclass of <code>Object</code>. | |
| 5607 </description> | |
| 5608 <origin>jvmdi</origin> | |
| 5609 <capabilities> | |
| 5610 <required id="can_access_local_variables"></required> | |
| 5611 </capabilities> | |
| 5612 <parameters> | |
| 5613 <param id="thread"> | |
| 5614 <jthread null="current" frame="frame"/> | |
| 5615 <description> | |
| 5616 The thread of the frame containing the variable's value. | |
| 5617 </description> | |
| 5618 </param> | |
| 5619 <param id="depth"> | |
| 5620 <jframeID thread="thread"/> | |
| 5621 <description> | |
| 5622 The depth of the frame containing the variable's value. | |
| 5623 </description> | |
| 5624 </param> | |
| 5625 <param id="slot"> | |
| 5626 <jint/> | |
| 5627 <description> | |
| 5628 The variable's slot number. | |
| 5629 </description> | |
| 5630 </param> | |
| 5631 <param id="value_ptr"> | |
| 5632 <outptr><jobject/></outptr> | |
| 5633 <description> | |
| 5634 On return, points to the variable's value. | |
| 5635 </description> | |
| 5636 </param> | |
| 5637 </parameters> | |
| 5638 <errors> | |
| 5639 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5640 Invalid <code>slot</code>. | |
| 5641 </error> | |
| 5642 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5643 The variable type is not | |
| 5644 <code>Object</code> or a subclass of <code>Object</code>. | |
| 5645 </error> | |
| 5646 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5647 Not a visible frame | |
| 5648 </error> | |
| 5649 </errors> | |
| 5650 </function> | |
| 5651 | |
| 2019 | 5652 <function id="GetLocalInstance" num="155" since="1.2"> |
| 5653 <synopsis>Get Local Instance</synopsis> | |
| 5654 <description> | |
| 5655 This function can be used to retrieve the value of the local object | |
| 5656 variable at slot 0 (the "<code>this</code>" object) from non-static | |
| 5657 frames. This function can retrieve the "<code>this</code>" object from | |
| 5658 native method frames, whereas <code>GetLocalObject()</code> would | |
| 5659 return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases. | |
| 5660 </description> | |
| 5661 <origin>new</origin> | |
| 5662 <capabilities> | |
| 5663 <required id="can_access_local_variables"></required> | |
| 5664 </capabilities> | |
| 5665 <parameters> | |
| 5666 <param id="thread"> | |
| 5667 <jthread null="current" frame="frame"/> | |
| 5668 <description> | |
| 5669 The thread of the frame containing the variable's value. | |
| 5670 </description> | |
| 5671 </param> | |
| 5672 <param id="depth"> | |
| 5673 <jframeID thread="thread"/> | |
| 5674 <description> | |
| 5675 The depth of the frame containing the variable's value. | |
| 5676 </description> | |
| 5677 </param> | |
| 5678 <param id="value_ptr"> | |
| 5679 <outptr><jobject/></outptr> | |
| 5680 <description> | |
| 5681 On return, points to the variable's value. | |
| 5682 </description> | |
| 5683 </param> | |
| 5684 </parameters> | |
| 5685 <errors> | |
| 5686 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5687 If the specified frame is a static method frame. | |
| 5688 </error> | |
| 5689 </errors> | |
| 5690 </function> | |
| 0 | 5691 <function id="GetLocalInt" num="22"> |
| 5692 <synopsis>Get Local Variable - Int</synopsis> | |
| 5693 <description> | |
| 5694 This function can be used to retrieve the value of a local | |
| 5695 variable whose type is <code>int</code>, | |
| 5696 <code>short</code>, <code>char</code>, <code>byte</code>, or | |
| 5697 <code>boolean</code>. | |
| 5698 </description> | |
| 5699 <origin>jvmdi</origin> | |
| 5700 <capabilities> | |
| 5701 <required id="can_access_local_variables"></required> | |
| 5702 </capabilities> | |
| 5703 <parameters> | |
| 5704 <param id="thread"> | |
| 5705 <jthread null="current" frame="frame"/> | |
| 5706 <description> | |
| 5707 The thread of the frame containing the variable's value. | |
| 5708 </description> | |
| 5709 </param> | |
| 5710 <param id="depth"> | |
| 5711 <jframeID thread="thread"/> | |
| 5712 <description> | |
| 5713 The depth of the frame containing the variable's value. | |
| 5714 </description> | |
| 5715 </param> | |
| 5716 <param id="slot"> | |
| 5717 <jint/> | |
| 5718 <description> | |
| 5719 The variable's slot number. | |
| 5720 </description> | |
| 5721 </param> | |
| 5722 <param id="value_ptr"> | |
| 5723 <outptr><jint/></outptr> | |
| 5724 <description> | |
| 5725 On return, points to the variable's value. | |
| 5726 </description> | |
| 5727 </param> | |
| 5728 </parameters> | |
| 5729 <errors> | |
| 5730 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5731 Invalid <code>slot</code>. | |
| 5732 </error> | |
| 5733 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5734 The variable type is not | |
| 5735 <code>int</code>, <code>short</code>, | |
| 5736 <code>char</code>, <code>byte</code>, or | |
| 5737 <code>boolean</code>. | |
| 5738 </error> | |
| 5739 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5740 Not a visible frame | |
| 5741 </error> | |
| 5742 </errors> | |
| 5743 </function> | |
| 5744 | |
| 5745 <function id="GetLocalLong" num="23"> | |
| 5746 <synopsis>Get Local Variable - Long</synopsis> | |
| 5747 <description> | |
| 5748 This function can be used to retrieve the value of a local | |
| 5749 variable whose type is <code>long</code>. | |
| 5750 </description> | |
| 5751 <origin>jvmdi</origin> | |
| 5752 <capabilities> | |
| 5753 <required id="can_access_local_variables"></required> | |
| 5754 </capabilities> | |
| 5755 <parameters> | |
| 5756 <param id="thread"> | |
| 5757 <jthread null="current" frame="frame"/> | |
| 5758 <description> | |
| 5759 The thread of the frame containing the variable's value. | |
| 5760 </description> | |
| 5761 </param> | |
| 5762 <param id="depth"> | |
| 5763 <jframeID thread="thread"/> | |
| 5764 <description> | |
| 5765 The depth of the frame containing the variable's value. | |
| 5766 </description> | |
| 5767 </param> | |
| 5768 <param id="slot"> | |
| 5769 <jint/> | |
| 5770 <description> | |
| 5771 The variable's slot number. | |
| 5772 </description> | |
| 5773 </param> | |
| 5774 <param id="value_ptr"> | |
| 5775 <outptr><jlong/></outptr> | |
| 5776 <description> | |
| 5777 On return, points to the variable's value. | |
| 5778 </description> | |
| 5779 </param> | |
| 5780 </parameters> | |
| 5781 <errors> | |
| 5782 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5783 Invalid <code>slot</code>. | |
| 5784 </error> | |
| 5785 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5786 The variable type is not <code>long</code>. | |
| 5787 </error> | |
| 5788 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5789 Not a visible frame | |
| 5790 </error> | |
| 5791 </errors> | |
| 5792 </function> | |
| 5793 | |
| 5794 <function id="GetLocalFloat" num="24"> | |
| 5795 <synopsis>Get Local Variable - Float</synopsis> | |
| 5796 <description> | |
| 5797 This function can be used to retrieve the value of a local | |
| 5798 variable whose type is <code>float</code>. | |
| 5799 </description> | |
| 5800 <origin>jvmdi</origin> | |
| 5801 <capabilities> | |
| 5802 <required id="can_access_local_variables"></required> | |
| 5803 </capabilities> | |
| 5804 <parameters> | |
| 5805 <param id="thread"> | |
| 5806 <jthread null="current" frame="frame"/> | |
| 5807 <description> | |
| 5808 The thread of the frame containing the variable's value. | |
| 5809 </description> | |
| 5810 </param> | |
| 5811 <param id="depth"> | |
| 5812 <jframeID thread="thread"/> | |
| 5813 <description> | |
| 5814 The depth of the frame containing the variable's value. | |
| 5815 </description> | |
| 5816 </param> | |
| 5817 <param id="slot"> | |
| 5818 <jint/> | |
| 5819 <description> | |
| 5820 The variable's slot number. | |
| 5821 </description> | |
| 5822 </param> | |
| 5823 <param id="value_ptr"> | |
| 5824 <outptr><jfloat/></outptr> | |
| 5825 <description> | |
| 5826 On return, points to the variable's value. | |
| 5827 </description> | |
| 5828 </param> | |
| 5829 </parameters> | |
| 5830 <errors> | |
| 5831 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5832 Invalid <code>slot</code>. | |
| 5833 </error> | |
| 5834 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5835 The variable type is not <code>float</code>. | |
| 5836 </error> | |
| 5837 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5838 Not a visible frame | |
| 5839 </error> | |
| 5840 </errors> | |
| 5841 </function> | |
| 5842 | |
| 5843 <function id="GetLocalDouble" num="25"> | |
| 5844 <synopsis>Get Local Variable - Double</synopsis> | |
| 5845 <description> | |
| 5846 This function can be used to retrieve the value of a local | |
| 5847 variable whose type is <code>long</code>. | |
| 5848 </description> | |
| 5849 <origin>jvmdi</origin> | |
| 5850 <capabilities> | |
| 5851 <required id="can_access_local_variables"></required> | |
| 5852 </capabilities> | |
| 5853 <parameters> | |
| 5854 <param id="thread"> | |
| 5855 <jthread null="current" frame="frame"/> | |
| 5856 <description> | |
| 5857 The thread of the frame containing the variable's value. | |
| 5858 </description> | |
| 5859 </param> | |
| 5860 <param id="depth"> | |
| 5861 <jframeID thread="thread"/> | |
| 5862 <description> | |
| 5863 The depth of the frame containing the variable's value. | |
| 5864 </description> | |
| 5865 </param> | |
| 5866 <param id="slot"> | |
| 5867 <jint/> | |
| 5868 <description> | |
| 5869 The variable's slot number. | |
| 5870 </description> | |
| 5871 </param> | |
| 5872 <param id="value_ptr"> | |
| 5873 <outptr><jdouble/></outptr> | |
| 5874 <description> | |
| 5875 On return, points to the variable's value. | |
| 5876 </description> | |
| 5877 </param> | |
| 5878 </parameters> | |
| 5879 <errors> | |
| 5880 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5881 Invalid <code>slot</code>. | |
| 5882 </error> | |
| 5883 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5884 The variable type is not <code>double</code>. | |
| 5885 </error> | |
| 5886 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5887 Not a visible frame | |
| 5888 </error> | |
| 5889 </errors> | |
| 5890 </function> | |
| 5891 | |
| 5892 <function id="SetLocalObject" num="26"> | |
| 5893 <synopsis>Set Local Variable - Object</synopsis> | |
| 5894 <description> | |
| 5895 This function can be used to set the value of a local | |
| 5896 variable whose type is <code>Object</code> or a subclass of <code>Object</code>. | |
| 5897 </description> | |
| 5898 <origin>jvmdi</origin> | |
| 5899 <capabilities> | |
| 5900 <required id="can_access_local_variables"></required> | |
| 5901 </capabilities> | |
| 5902 <parameters> | |
| 5903 <param id="thread"> | |
| 5904 <jthread null="current" frame="frame"/> | |
| 5905 <description> | |
| 5906 The thread of the frame containing the variable's value. | |
| 5907 </description> | |
| 5908 </param> | |
| 5909 <param id="depth"> | |
| 5910 <jframeID thread="thread"/> | |
| 5911 <description> | |
| 5912 The depth of the frame containing the variable's value. | |
| 5913 </description> | |
| 5914 </param> | |
| 5915 <param id="slot"> | |
| 5916 <jint/> | |
| 5917 <description> | |
| 5918 The variable's slot number. | |
| 5919 </description> | |
| 5920 </param> | |
| 5921 <param id="value"> | |
| 5922 <jobject/> | |
| 5923 <description> | |
| 5924 The new value for the variable. | |
| 5925 </description> | |
| 5926 </param> | |
| 5927 </parameters> | |
| 5928 <errors> | |
| 5929 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5930 Invalid <code>slot</code>. | |
| 5931 </error> | |
| 5932 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5933 The variable type is not | |
| 5934 <code>Object</code> or a subclass of <code>Object</code>. | |
| 5935 </error> | |
| 5936 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5937 The supplied <paramlink id="value"/> is not compatible | |
| 5938 with the variable type. | |
| 5939 </error> | |
| 5940 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5941 Not a visible frame | |
| 5942 </error> | |
| 5943 </errors> | |
| 5944 </function> | |
| 5945 | |
| 5946 <function id="SetLocalInt" num="27"> | |
| 5947 <synopsis>Set Local Variable - Int</synopsis> | |
| 5948 <description> | |
| 5949 This function can be used to set the value of a local | |
| 5950 variable whose type is <code>int</code>, | |
| 5951 <code>short</code>, <code>char</code>, <code>byte</code>, or | |
| 5952 <code>boolean</code>. | |
| 5953 </description> | |
| 5954 <origin>jvmdi</origin> | |
| 5955 <capabilities> | |
| 5956 <required id="can_access_local_variables"></required> | |
| 5957 </capabilities> | |
| 5958 <parameters> | |
| 5959 <param id="thread"> | |
| 5960 <jthread null="current" frame="frame"/> | |
| 5961 <description> | |
| 5962 The thread of the frame containing the variable's value. | |
| 5963 </description> | |
| 5964 </param> | |
| 5965 <param id="depth"> | |
| 5966 <jframeID thread="thread"/> | |
| 5967 <description> | |
| 5968 The depth of the frame containing the variable's value. | |
| 5969 </description> | |
| 5970 </param> | |
| 5971 <param id="slot"> | |
| 5972 <jint/> | |
| 5973 <description> | |
| 5974 The variable's slot number. | |
| 5975 </description> | |
| 5976 </param> | |
| 5977 <param id="value"> | |
| 5978 <jint/> | |
| 5979 <description> | |
| 5980 The new value for the variable. | |
| 5981 </description> | |
| 5982 </param> | |
| 5983 </parameters> | |
| 5984 <errors> | |
| 5985 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5986 Invalid <code>slot</code>. | |
| 5987 </error> | |
| 5988 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5989 The variable type is not | |
| 5990 <code>int</code>, <code>short</code>, | |
| 5991 <code>char</code>, <code>byte</code>, or | |
| 5992 <code>boolean</code>. | |
| 5993 </error> | |
| 5994 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5995 Not a visible frame | |
| 5996 </error> | |
| 5997 </errors> | |
| 5998 </function> | |
| 5999 | |
| 6000 <function id="SetLocalLong" num="28"> | |
| 6001 <synopsis>Set Local Variable - Long</synopsis> | |
| 6002 <description> | |
| 6003 This function can be used to set the value of a local | |
| 6004 variable whose type is <code>long</code>. | |
| 6005 </description> | |
| 6006 <origin>jvmdi</origin> | |
| 6007 <capabilities> | |
| 6008 <required id="can_access_local_variables"></required> | |
| 6009 </capabilities> | |
| 6010 <parameters> | |
| 6011 <param id="thread"> | |
| 6012 <jthread null="current" frame="frame"/> | |
| 6013 <description> | |
| 6014 The thread of the frame containing the variable's value. | |
| 6015 </description> | |
| 6016 </param> | |
| 6017 <param id="depth"> | |
| 6018 <jframeID thread="thread"/> | |
| 6019 <description> | |
| 6020 The depth of the frame containing the variable's value. | |
| 6021 </description> | |
| 6022 </param> | |
| 6023 <param id="slot"> | |
| 6024 <jint/> | |
| 6025 <description> | |
| 6026 The variable's slot number. | |
| 6027 </description> | |
| 6028 </param> | |
| 6029 <param id="value"> | |
| 6030 <jlong/> | |
| 6031 <description> | |
| 6032 The new value for the variable. | |
| 6033 </description> | |
| 6034 </param> | |
| 6035 </parameters> | |
| 6036 <errors> | |
| 6037 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6038 Invalid <code>slot</code>. | |
| 6039 </error> | |
| 6040 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6041 The variable type is not <code>long</code>. | |
| 6042 </error> | |
| 6043 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6044 Not a visible frame | |
| 6045 </error> | |
| 6046 </errors> | |
| 6047 </function> | |
| 6048 | |
| 6049 <function id="SetLocalFloat" num="29"> | |
| 6050 <synopsis>Set Local Variable - Float</synopsis> | |
| 6051 <description> | |
| 6052 This function can be used to set the value of a local | |
| 6053 variable whose type is <code>float</code>. | |
| 6054 </description> | |
| 6055 <origin>jvmdi</origin> | |
| 6056 <capabilities> | |
| 6057 <required id="can_access_local_variables"></required> | |
| 6058 </capabilities> | |
| 6059 <parameters> | |
| 6060 <param id="thread"> | |
| 6061 <jthread null="current" frame="frame"/> | |
| 6062 <description> | |
| 6063 The thread of the frame containing the variable's value. | |
| 6064 </description> | |
| 6065 </param> | |
| 6066 <param id="depth"> | |
| 6067 <jframeID thread="thread"/> | |
| 6068 <description> | |
| 6069 The depth of the frame containing the variable's value. | |
| 6070 </description> | |
| 6071 </param> | |
| 6072 <param id="slot"> | |
| 6073 <jint/> | |
| 6074 <description> | |
| 6075 The variable's slot number. | |
| 6076 </description> | |
| 6077 </param> | |
| 6078 <param id="value"> | |
| 6079 <jfloat/> | |
| 6080 <description> | |
| 6081 The new value for the variable. | |
| 6082 </description> | |
| 6083 </param> | |
| 6084 </parameters> | |
| 6085 <errors> | |
| 6086 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6087 Invalid <code>slot</code>. | |
| 6088 </error> | |
| 6089 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6090 The variable type is not <code>float</code>. | |
| 6091 </error> | |
| 6092 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6093 Not a visible frame | |
| 6094 </error> | |
| 6095 </errors> | |
| 6096 </function> | |
| 6097 | |
| 6098 <function id="SetLocalDouble" num="30"> | |
| 6099 <synopsis>Set Local Variable - Double</synopsis> | |
| 6100 <description> | |
| 6101 This function can be used to set the value of a local | |
| 6102 variable whose type is <code>double</code>. | |
| 6103 </description> | |
| 6104 <origin>jvmdi</origin> | |
| 6105 <capabilities> | |
| 6106 <required id="can_access_local_variables"></required> | |
| 6107 </capabilities> | |
| 6108 <parameters> | |
| 6109 <param id="thread"> | |
| 6110 <jthread null="current" frame="frame"/> | |
| 6111 <description> | |
| 6112 The thread of the frame containing the variable's value. | |
| 6113 </description> | |
| 6114 </param> | |
| 6115 <param id="depth"> | |
| 6116 <jframeID thread="thread"/> | |
| 6117 <description> | |
| 6118 The depth of the frame containing the variable's value. | |
| 6119 </description> | |
| 6120 </param> | |
| 6121 <param id="slot"> | |
| 6122 <jint/> | |
| 6123 <description> | |
| 6124 The variable's slot number. | |
| 6125 </description> | |
| 6126 </param> | |
| 6127 <param id="value"> | |
| 6128 <jdouble/> | |
| 6129 <description> | |
| 6130 The new value for the variable. | |
| 6131 </description> | |
| 6132 </param> | |
| 6133 </parameters> | |
| 6134 <errors> | |
| 6135 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6136 Invalid <code>slot</code>. | |
| 6137 </error> | |
| 6138 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6139 The variable type is not <code>double</code>. | |
| 6140 </error> | |
| 6141 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6142 Not a visible frame | |
| 6143 </error> | |
| 6144 </errors> | |
| 6145 </function> | |
| 6146 </category> | |
| 6147 | |
| 6148 <category id="breakpointCategory" label="Breakpoint"> | |
| 6149 | |
| 6150 <intro> | |
| 6151 </intro> | |
| 6152 | |
| 6153 <function id="SetBreakpoint" num="38"> | |
| 6154 <synopsis>Set Breakpoint</synopsis> | |
| 6155 <description> | |
| 6156 Set a breakpoint at the instruction indicated by | |
| 6157 <code>method</code> and <code>location</code>. | |
| 6158 An instruction can only have one breakpoint. | |
| 6159 <p/> | |
| 6160 Whenever the designated instruction is about to be executed, a | |
| 6161 <eventlink id="Breakpoint"></eventlink> event is generated. | |
| 6162 </description> | |
| 6163 <origin>jvmdi</origin> | |
| 6164 <capabilities> | |
| 6165 <required id="can_generate_breakpoint_events"></required> | |
| 6166 </capabilities> | |
| 6167 <parameters> | |
| 6168 <param id="klass"> | |
| 6169 <jclass method="method"/> | |
| 6170 <description> | |
| 6171 The class in which to set the breakpoint | |
| 6172 </description> | |
| 6173 </param> | |
| 6174 <param id="method"> | |
| 6175 <jmethodID class="klass"/> | |
| 6176 <description> | |
| 6177 The method in which to set the breakpoint | |
| 6178 </description> | |
| 6179 </param> | |
| 6180 <param id="location"> | |
| 6181 <jlocation/> | |
| 6182 <description> | |
| 6183 the index of the instruction at which to set the breakpoint | |
| 6184 | |
| 6185 </description> | |
| 6186 </param> | |
| 6187 </parameters> | |
| 6188 <errors> | |
| 6189 <error id="JVMTI_ERROR_DUPLICATE"> | |
| 6190 The designated bytecode already has a breakpoint. | |
| 6191 </error> | |
| 6192 </errors> | |
| 6193 </function> | |
| 6194 | |
| 6195 <function id="ClearBreakpoint" num="39"> | |
| 6196 <synopsis>Clear Breakpoint</synopsis> | |
| 6197 <description> | |
| 6198 Clear the breakpoint at the bytecode indicated by | |
| 6199 <code>method</code> and <code>location</code>. | |
| 6200 </description> | |
| 6201 <origin>jvmdi</origin> | |
| 6202 <capabilities> | |
| 6203 <required id="can_generate_breakpoint_events"></required> | |
| 6204 </capabilities> | |
| 6205 <parameters> | |
| 6206 <param id="klass"> | |
| 6207 <jclass method="method"/> | |
| 6208 <description> | |
| 6209 The class in which to clear the breakpoint | |
| 6210 </description> | |
| 6211 </param> | |
| 6212 <param id="method"> | |
| 6213 <jmethodID class="klass"/> | |
| 6214 <description> | |
| 6215 The method in which to clear the breakpoint | |
| 6216 </description> | |
| 6217 </param> | |
| 6218 <param id="location"> | |
| 6219 <jlocation/> | |
| 6220 <description> | |
| 6221 the index of the instruction at which to clear the breakpoint | |
| 6222 </description> | |
| 6223 </param> | |
| 6224 </parameters> | |
| 6225 <errors> | |
| 6226 <error id="JVMTI_ERROR_NOT_FOUND"> | |
| 6227 There's no breakpoint at the designated bytecode. | |
| 6228 </error> | |
| 6229 </errors> | |
| 6230 </function> | |
| 6231 | |
| 6232 </category> | |
| 6233 | |
| 6234 <category id="fieldWatch" label="Watched Field"> | |
| 6235 | |
| 6236 <intro> | |
| 6237 </intro> | |
| 6238 | |
| 6239 <function id="SetFieldAccessWatch" num="41"> | |
| 6240 <synopsis>Set Field Access Watch</synopsis> | |
| 6241 <description> | |
| 6242 Generate a <eventlink id="FieldAccess"></eventlink> event | |
| 6243 when the field specified | |
| 6244 by <code>klass</code> and | |
| 6245 <code>field</code> is about to be accessed. | |
| 6246 An event will be generated for each access of the field | |
| 6247 until it is canceled with | |
| 6248 <functionlink id="ClearFieldAccessWatch"></functionlink>. | |
| 6249 Field accesses from Java programming language code or from JNI code are watched, | |
| 6250 fields modified by other means are not watched. | |
| 6251 Note that <jvmti/> users should be aware that their own field accesses | |
| 6252 will trigger the watch. | |
| 6253 A field can only have one field access watch set. | |
| 6254 Modification of a field is not considered an access--use | |
| 6255 <functionlink id="SetFieldModificationWatch"></functionlink> | |
| 6256 to monitor modifications. | |
| 6257 </description> | |
| 6258 <origin>jvmdi</origin> | |
| 6259 <capabilities> | |
| 6260 <required id="can_generate_field_access_events"></required> | |
| 6261 </capabilities> | |
| 6262 <parameters> | |
| 6263 <param id="klass"> | |
| 6264 <jclass field="field"/> | |
| 6265 <description> | |
| 6266 The class containing the field to watch | |
| 6267 </description> | |
| 6268 </param> | |
| 6269 <param id="field"> | |
| 6270 <jfieldID class="klass"/> | |
| 6271 <description> | |
| 6272 The field to watch | |
| 6273 | |
| 6274 </description> | |
| 6275 </param> | |
| 6276 </parameters> | |
| 6277 <errors> | |
| 6278 <error id="JVMTI_ERROR_DUPLICATE"> | |
| 6279 The designated field is already being watched for accesses. | |
| 6280 </error> | |
| 6281 </errors> | |
| 6282 </function> | |
| 6283 | |
| 6284 <function id="ClearFieldAccessWatch" num="42"> | |
| 6285 <synopsis>Clear Field Access Watch</synopsis> | |
| 6286 <description> | |
| 6287 Cancel a field access watch previously set by | |
| 6288 <functionlink id="SetFieldAccessWatch"></functionlink>, on the | |
| 6289 field specified | |
| 6290 by <code>klass</code> and | |
| 6291 <code>field</code>. | |
| 6292 </description> | |
| 6293 <origin>jvmdi</origin> | |
| 6294 <capabilities> | |
| 6295 <required id="can_generate_field_access_events"></required> | |
| 6296 </capabilities> | |
| 6297 <parameters> | |
| 6298 <param id="klass"> | |
| 6299 <jclass field="field"/> | |
| 6300 <description> | |
| 6301 The class containing the field to watch | |
| 6302 </description> | |
| 6303 </param> | |
| 6304 <param id="field"> | |
| 6305 <jfieldID class="klass"/> | |
| 6306 <description> | |
| 6307 The field to watch | |
| 6308 | |
| 6309 </description> | |
| 6310 </param> | |
| 6311 </parameters> | |
| 6312 <errors> | |
| 6313 <error id="JVMTI_ERROR_NOT_FOUND"> | |
| 6314 The designated field is not being watched for accesses. | |
| 6315 </error> | |
| 6316 </errors> | |
| 6317 </function> | |
| 6318 | |
| 6319 <function id="SetFieldModificationWatch" num="43"> | |
| 6320 <synopsis>Set Field Modification Watch</synopsis> | |
| 6321 <description> | |
| 6322 Generate a <eventlink id="FieldModification"></eventlink> event | |
| 6323 when the field specified | |
| 6324 by <code>klass</code> and | |
| 6325 <code>field</code> is about to be modified. | |
| 6326 An event will be generated for each modification of the field | |
| 6327 until it is canceled with | |
| 6328 <functionlink id="ClearFieldModificationWatch"></functionlink>. | |
| 6329 Field modifications from Java programming language code or from JNI code are watched, | |
| 6330 fields modified by other means are not watched. | |
| 6331 Note that <jvmti/> users should be aware that their own field modifications | |
| 6332 will trigger the watch. | |
| 6333 A field can only have one field modification watch set. | |
| 6334 </description> | |
| 6335 <origin>jvmdi</origin> | |
| 6336 <capabilities> | |
| 6337 <required id="can_generate_field_modification_events"></required> | |
| 6338 </capabilities> | |
| 6339 <parameters> | |
| 6340 <param id="klass"> | |
| 6341 <jclass field="field"/> | |
| 6342 <description> | |
| 6343 The class containing the field to watch | |
| 6344 </description> | |
| 6345 </param> | |
| 6346 <param id="field"> | |
| 6347 <jfieldID class="klass"/> | |
| 6348 <description> | |
| 6349 The field to watch | |
| 6350 | |
| 6351 </description> | |
| 6352 </param> | |
| 6353 </parameters> | |
| 6354 <errors> | |
| 6355 <error id="JVMTI_ERROR_DUPLICATE"> | |
| 6356 The designated field is already being watched for modifications. | |
| 6357 </error> | |
| 6358 </errors> | |
| 6359 </function> | |
| 6360 | |
| 6361 <function id="ClearFieldModificationWatch" num="44"> | |
| 6362 <synopsis>Clear Field Modification Watch</synopsis> | |
| 6363 <description> | |
| 6364 | |
| 6365 Cancel a field modification watch previously set by | |
| 6366 <functionlink id="SetFieldModificationWatch"></functionlink>, on the | |
| 6367 field specified | |
| 6368 by <code>klass</code> and | |
| 6369 <code>field</code>. | |
| 6370 </description> | |
| 6371 <origin>jvmdi</origin> | |
| 6372 <capabilities> | |
| 6373 <required id="can_generate_field_modification_events"></required> | |
| 6374 </capabilities> | |
| 6375 <parameters> | |
| 6376 <param id="klass"> | |
| 6377 <jclass field="field"/> | |
| 6378 <description> | |
| 6379 The class containing the field to watch | |
| 6380 </description> | |
| 6381 </param> | |
| 6382 <param id="field"> | |
| 6383 <jfieldID class="klass"/> | |
| 6384 <description> | |
| 6385 The field to watch | |
| 6386 | |
| 6387 </description> | |
| 6388 </param> | |
| 6389 </parameters> | |
| 6390 <errors> | |
| 6391 <error id="JVMTI_ERROR_NOT_FOUND"> | |
| 6392 The designated field is not being watched for modifications. | |
| 6393 </error> | |
| 6394 </errors> | |
| 6395 </function> | |
| 6396 </category> | |
| 6397 | |
| 6398 <category id="class" label="Class"> | |
| 6399 | |
| 6400 <intro> | |
| 6401 </intro> | |
| 6402 | |
| 6403 <function id="GetLoadedClasses" jkernel="yes" num="78"> | |
| 6404 <synopsis>Get Loaded Classes</synopsis> | |
| 6405 <description> | |
| 6406 Return an array of all classes loaded in the virtual machine. | |
| 6407 The number of classes in the array is returned via | |
| 6408 <code>class_count_ptr</code>, and the array itself via | |
| 6409 <code>classes_ptr</code>. | |
| 6410 <p/> | |
| 6411 Array classes of all types (including arrays of primitive types) are | |
| 6412 included in the returned list. Primitive classes (for example, | |
| 6413 <code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list. | |
| 6414 </description> | |
| 6415 <origin>jvmdi</origin> | |
| 6416 <capabilities> | |
| 6417 </capabilities> | |
| 6418 <parameters> | |
| 6419 <param id="class_count_ptr"> | |
| 6420 <outptr><jint/></outptr> | |
| 6421 <description> | |
| 6422 On return, points to the number of classes. | |
| 6423 </description> | |
| 6424 </param> | |
| 6425 <param id="classes_ptr"> | |
| 6426 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf> | |
| 6427 <description> | |
| 6428 On return, points to an array of references, one | |
| 6429 for each class. | |
| 6430 </description> | |
| 6431 </param> | |
| 6432 </parameters> | |
| 6433 <errors> | |
| 6434 </errors> | |
| 6435 </function> | |
| 6436 | |
| 6437 <function id="GetClassLoaderClasses" jkernel="yes" num="79"> | |
| 6438 <synopsis>Get Classloader Classes</synopsis> | |
| 6439 <description> | |
| 6440 Returns an array of those classes for which this class loader has | |
| 6441 been recorded as an initiating loader. Each | |
| 6442 class in the returned array was created by this class loader, | |
| 6443 either by defining it directly or by delegation to another class loader. | |
| 6444 See the | |
| 6445 <vmspeclink id="ConstantPool.doc.html#72007" | |
| 6446 name="Creation and Loading section"/>. | |
| 6447 <p/> | |
| 6448 For JDK version 1.1 implementations that don't | |
| 6449 recognize the distinction between initiating and defining class loaders, | |
| 6450 this function should return all classes loaded in the virtual machine. | |
| 6451 The number of classes in the array is returned via | |
| 6452 <code>class_count_ptr</code>, and the array itself via | |
| 6453 <code>classes_ptr</code>. | |
| 6454 </description> | |
| 6455 <origin>jvmdi</origin> | |
| 6456 <capabilities> | |
| 6457 </capabilities> | |
| 6458 <parameters> | |
| 6459 <param id="initiating_loader"> | |
| 6460 <ptrtype> | |
| 6461 <jobject/> | |
| 6462 <nullok>the classes initiated by the bootstrap loader will be returned</nullok> | |
| 6463 </ptrtype> | |
| 6464 <description> | |
| 6465 An initiating class loader. | |
| 6466 </description> | |
| 6467 </param> | |
| 6468 <param id="class_count_ptr"> | |
| 6469 <outptr><jint/></outptr> | |
| 6470 <description> | |
| 6471 On return, points to the number of classes. | |
| 6472 </description> | |
| 6473 </param> | |
| 6474 <param id="classes_ptr"> | |
| 6475 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf> | |
| 6476 <description> | |
| 6477 On return, points to an array of references, one | |
| 6478 for each class. | |
| 6479 </description> | |
| 6480 </param> | |
| 6481 </parameters> | |
| 6482 <errors> | |
| 6483 </errors> | |
| 6484 </function> | |
| 6485 | |
| 6486 <function id="GetClassSignature" phase="start" num="48"> | |
| 6487 <synopsis>Get Class Signature</synopsis> | |
| 6488 <description> | |
| 6489 For the class indicated by <code>klass</code>, return the | |
| 6490 <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/types.html#wp16432">JNI | |
| 6491 type signature</externallink> | |
| 6492 and the generic signature of the class. | |
| 6493 For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code> | |
| 6494 and <code>int[]</code> is <code>"[I"</code> | |
| 6495 The returned name for primitive classes | |
| 6496 is the type signature character of the corresponding primitive type. | |
| 6497 For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>. | |
| 6498 </description> | |
| 6499 <origin>jvmdiClone</origin> | |
| 6500 <capabilities> | |
| 6501 </capabilities> | |
| 6502 <parameters> | |
| 6503 <param id="klass"> | |
| 6504 <jclass/> | |
| 6505 <description> | |
| 6506 The class to query. | |
| 6507 </description> | |
| 6508 </param> | |
| 6509 <param id="signature_ptr"> | |
| 6510 <allocbuf> | |
| 6511 <char/> | |
| 6512 <nullok>the signature is not returned</nullok> | |
| 6513 </allocbuf> | |
| 6514 <description> | |
| 6515 On return, points to the JNI type signature of the class, encoded as a | |
| 6516 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 6517 </description> | |
| 6518 </param> | |
| 6519 <param id="generic_ptr"> | |
| 6520 <allocbuf> | |
| 6521 <char/> | |
| 6522 <nullok>the generic signature is not returned</nullok> | |
| 6523 </allocbuf> | |
| 6524 <description> | |
| 6525 On return, points to the generic signature of the class, encoded as a | |
| 6526 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 6527 If there is no generic signature attribute for the class, then, | |
| 6528 on return, points to <code>NULL</code>. | |
| 6529 </description> | |
| 6530 </param> | |
| 6531 </parameters> | |
| 6532 <errors> | |
| 6533 </errors> | |
| 6534 </function> | |
| 6535 | |
| 6536 <function id="GetClassStatus" phase="start" num="49"> | |
| 6537 <synopsis>Get Class Status</synopsis> | |
| 6538 <description> | |
| 6539 Get the status of the class. Zero or more of the following bits can be | |
| 6540 set. | |
| 6541 <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits"> | |
| 6542 <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1"> | |
| 6543 Class bytecodes have been verified | |
| 6544 </constant> | |
| 6545 <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2"> | |
| 6546 Class preparation is complete | |
| 6547 </constant> | |
| 6548 <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4"> | |
| 6549 Class initialization is complete. Static initializer has been run. | |
| 6550 </constant> | |
| 6551 <constant id="JVMTI_CLASS_STATUS_ERROR" num="8"> | |
| 6552 Error during initialization makes class unusable | |
| 6553 </constant> | |
| 6554 <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16"> | |
| 6555 Class is an array. If set, all other bits are zero. | |
| 6556 </constant> | |
| 6557 <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32"> | |
| 6558 Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6559 If set, all other bits are zero. | |
| 6560 </constant> | |
| 6561 </constants> | |
| 6562 </description> | |
| 6563 <origin>jvmdi</origin> | |
| 6564 <capabilities> | |
| 6565 </capabilities> | |
| 6566 <parameters> | |
| 6567 <param id="klass"> | |
| 6568 <jclass/> | |
| 6569 <description> | |
| 6570 The class to query. | |
| 6571 </description> | |
| 6572 </param> | |
| 6573 <param id="status_ptr"> | |
| 6574 <outptr><jint/></outptr> | |
| 6575 <description> | |
| 6576 On return, points to the current state of this class as one or | |
| 6577 more of the <internallink id="jvmtiClassStatus">class status flags</internallink>. | |
| 6578 </description> | |
| 6579 </param> | |
| 6580 </parameters> | |
| 6581 <errors> | |
| 6582 </errors> | |
| 6583 </function> | |
| 6584 | |
| 6585 <function id="GetSourceFileName" phase="start" num="50"> | |
| 6586 <synopsis>Get Source File Name</synopsis> | |
| 6587 <description> | |
| 6588 For the class indicated by <code>klass</code>, return the source file | |
| 6589 name via <code>source_name_ptr</code>. The returned string | |
| 6590 is a file name only and never contains a directory name. | |
| 6591 <p/> | |
| 6592 For primitive classes (for example, <code>java.lang.Integer.TYPE</code>) | |
| 6593 and for arrays this function returns | |
| 6594 <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>. | |
| 6595 </description> | |
| 6596 <origin>jvmdi</origin> | |
| 6597 <capabilities> | |
| 6598 <required id="can_get_source_file_name"></required> | |
| 6599 </capabilities> | |
| 6600 <parameters> | |
| 6601 <param id="klass"> | |
| 6602 <jclass/> | |
| 6603 <description> | |
| 6604 The class to query. | |
| 6605 </description> | |
| 6606 </param> | |
| 6607 <param id="source_name_ptr"> | |
| 6608 <allocbuf><char/></allocbuf> | |
| 6609 <description> | |
| 6610 On return, points to the class's source file name, encoded as a | |
| 6611 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 6612 </description> | |
| 6613 </param> | |
| 6614 </parameters> | |
| 6615 <errors> | |
| 6616 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 6617 Class information does not include a source file name. This includes | |
| 6618 cases where the class is an array class or primitive class. | |
| 6619 </error> | |
| 6620 </errors> | |
| 6621 </function> | |
| 6622 | |
| 6623 <function id="GetClassModifiers" phase="start" num="51"> | |
| 6624 <synopsis>Get Class Modifiers</synopsis> | |
| 6625 <description> | |
| 6626 For the class indicated by <code>klass</code>, return the access | |
| 6627 flags | |
| 6628 via <code>modifiers_ptr</code>. | |
| 6629 Access flags are defined in the | |
| 6630 <vmspeclink id="ClassFile.doc.html" | |
| 6631 name="Class File Format chapter"/>. | |
| 6632 <p/> | |
| 6633 If the class is an array class, then its public, private, and protected | |
| 6634 modifiers are the same as those of its component type. For arrays of | |
| 6635 primitives, this component type is represented by one of the primitive | |
| 6636 classes (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6637 <p/> | |
| 6638 If the class is a primitive class, its public modifier is always true, | |
| 6639 and its protected and private modifiers are always false. | |
| 6640 <p/> | |
| 6641 If the class is an array class or a primitive class then its final | |
| 6642 modifier is always true and its interface modifier is always false. | |
| 6643 The values of its other modifiers are not determined by this specification. | |
| 6644 | |
| 6645 </description> | |
| 6646 <origin>jvmdi</origin> | |
| 6647 <capabilities> | |
| 6648 </capabilities> | |
| 6649 <parameters> | |
| 6650 <param id="klass"> | |
| 6651 <jclass/> | |
| 6652 <description> | |
| 6653 The class to query. | |
| 6654 </description> | |
| 6655 </param> | |
| 6656 <param id="modifiers_ptr"> | |
| 6657 <outptr><jint/></outptr> | |
| 6658 <description> | |
| 6659 On return, points to the current access flags of this class. | |
| 6660 | |
| 6661 </description> | |
| 6662 </param> | |
| 6663 </parameters> | |
| 6664 <errors> | |
| 6665 </errors> | |
| 6666 </function> | |
| 6667 | |
| 6668 <function id="GetClassMethods" phase="start" num="52"> | |
| 6669 <synopsis>Get Class Methods</synopsis> | |
| 6670 <description> | |
| 6671 For the class indicated by <code>klass</code>, return a count of | |
| 6672 methods via <code>method_count_ptr</code> and a list of | |
| 6673 method IDs via <code>methods_ptr</code>. The method list contains | |
| 6674 constructors and static initializers as well as true methods. | |
| 6675 Only directly declared methods are returned (not inherited methods). | |
| 6676 An empty method list is returned for array classes and primitive classes | |
| 6677 (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6678 </description> | |
| 6679 <origin>jvmdi</origin> | |
| 6680 <capabilities> | |
| 6681 <capability id="can_maintain_original_method_order"/> | |
| 6682 </capabilities> | |
| 6683 <parameters> | |
| 6684 <param id="klass"> | |
| 6685 <jclass/> | |
| 6686 <description> | |
| 6687 The class to query. | |
| 6688 </description> | |
| 6689 </param> | |
| 6690 <param id="method_count_ptr"> | |
| 6691 <outptr><jint/></outptr> | |
| 6692 <description> | |
| 6693 On return, points to the number of methods declared in this class. | |
| 6694 </description> | |
| 6695 </param> | |
| 6696 <param id="methods_ptr"> | |
| 6697 <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf> | |
| 6698 <description> | |
| 6699 On return, points to the method ID array. | |
| 6700 </description> | |
| 6701 </param> | |
| 6702 </parameters> | |
| 6703 <errors> | |
| 6704 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
| 6705 <paramlink id="klass"></paramlink> is not prepared. | |
| 6706 </error> | |
| 6707 </errors> | |
| 6708 </function> | |
| 6709 | |
| 6710 <function id="GetClassFields" phase="start" num="53"> | |
| 6711 <synopsis>Get Class Fields</synopsis> | |
| 6712 <description> | |
| 6713 For the class indicated by <code>klass</code>, return a count of fields | |
| 6714 via <code>field_count_ptr</code> and a list of field IDs via | |
| 6715 <code>fields_ptr</code>. | |
| 6716 Only directly declared fields are returned (not inherited fields). | |
| 6717 Fields are returned in the order they occur in the class file. | |
| 6718 An empty field list is returned for array classes and primitive classes | |
| 6719 (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6720 Use JNI to determine the length of an array. | |
| 6721 </description> | |
| 6722 <origin>jvmdi</origin> | |
| 6723 <capabilities> | |
| 6724 </capabilities> | |
| 6725 <parameters> | |
| 6726 <param id="klass"> | |
| 6727 <jclass/> | |
| 6728 <description> | |
| 6729 The class to query. | |
| 6730 </description> | |
| 6731 </param> | |
| 6732 <param id="field_count_ptr"> | |
| 6733 <outptr><jint/></outptr> | |
| 6734 <description> | |
| 6735 On return, points to the number of fields declared in this class. | |
| 6736 </description> | |
| 6737 </param> | |
| 6738 <param id="fields_ptr"> | |
| 6739 <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf> | |
| 6740 <description> | |
| 6741 On return, points to the field ID array. | |
| 6742 </description> | |
| 6743 </param> | |
| 6744 </parameters> | |
| 6745 <errors> | |
| 6746 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
| 6747 <paramlink id="klass"></paramlink> is not prepared. | |
| 6748 </error> | |
| 6749 </errors> | |
| 6750 </function> | |
| 6751 | |
| 6752 <function id="GetImplementedInterfaces" phase="start" num="54"> | |
| 6753 <synopsis>Get Implemented Interfaces</synopsis> | |
| 6754 <description> | |
| 6755 Return the direct super-interfaces of this class. For a class, this | |
| 6756 function returns the interfaces declared in its <code>implements</code> | |
| 6757 clause. For an interface, this function returns the interfaces declared in | |
| 6758 its <code>extends</code> clause. | |
| 6759 An empty interface list is returned for array classes and primitive classes | |
| 6760 (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6761 </description> | |
| 6762 <origin>jvmdi</origin> | |
| 6763 <capabilities> | |
| 6764 </capabilities> | |
| 6765 <parameters> | |
| 6766 <param id="klass"> | |
| 6767 <jclass/> | |
| 6768 <description> | |
| 6769 The class to query. | |
| 6770 </description> | |
| 6771 </param> | |
| 6772 <param id="interface_count_ptr"> | |
| 6773 <outptr><jint/></outptr> | |
| 6774 <description> | |
| 6775 On return, points to the number of interfaces. | |
| 6776 </description> | |
| 6777 </param> | |
| 6778 <param id="interfaces_ptr"> | |
| 6779 <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf> | |
| 6780 <description> | |
| 6781 On return, points to the interface array. | |
| 6782 </description> | |
| 6783 </param> | |
| 6784 </parameters> | |
| 6785 <errors> | |
| 6786 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
| 6787 <paramlink id="klass"></paramlink> is not prepared. | |
| 6788 </error> | |
| 6789 </errors> | |
| 6790 </function> | |
| 6791 | |
| 6792 <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1"> | |
| 6793 <synopsis>Get Class Version Numbers</synopsis> | |
| 6794 <description> | |
| 6795 For the class indicated by <code>klass</code>, | |
| 6796 return the minor and major version numbers, | |
| 6797 as defined in the | |
| 6798 <vmspeclink id="ClassFile.doc.html" | |
| 6799 name="Class File Format chapter"/>. | |
| 6800 </description> | |
| 6801 <origin>new</origin> | |
| 6802 <capabilities> | |
| 6803 </capabilities> | |
| 6804 <parameters> | |
| 6805 <param id="klass"> | |
| 6806 <jclass/> | |
| 6807 <description> | |
| 6808 The class to query. | |
| 6809 </description> | |
| 6810 </param> | |
| 6811 <param id="minor_version_ptr"> | |
| 6812 <outptr><jint/></outptr> | |
| 6813 <description> | |
| 6814 On return, points to the value of the | |
| 6815 <code>minor_version</code> item of the | |
| 6816 Class File Format. | |
| 6817 Note: to be consistent with the Class File Format, | |
| 6818 the minor version number is the first parameter. | |
| 6819 </description> | |
| 6820 </param> | |
| 6821 <param id="major_version_ptr"> | |
| 6822 <outptr><jint/></outptr> | |
| 6823 <description> | |
| 6824 On return, points to the value of the | |
| 6825 <code>major_version</code> item of the | |
| 6826 Class File Format. | |
| 6827 </description> | |
| 6828 </param> | |
| 6829 </parameters> | |
| 6830 <errors> | |
| 6831 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 6832 The class is a primitive or array class. | |
| 6833 </error> | |
| 6834 </errors> | |
| 6835 </function> | |
| 6836 | |
| 6837 <function id="GetConstantPool" phase="start" num="146" since="1.1"> | |
| 6838 <synopsis>Get Constant Pool</synopsis> | |
| 6839 <description> | |
| 6840 For the class indicated by <code>klass</code>, | |
| 6841 return the raw bytes of the constant pool in the format of the | |
| 6842 <code>constant_pool</code> item of the | |
| 6843 <vmspeclink id="ClassFile.doc.html" | |
| 6844 name="Class File Format" | |
| 6845 preposition="in"/>. | |
| 6846 The format of the constant pool may differ between versions | |
| 6847 of the Class File Format, so, the | |
| 6848 <functionlink id="GetClassVersionNumbers">minor and major | |
| 6849 class version numbers</functionlink> should be checked for | |
| 6850 compatibility. | |
| 6851 <p/> | |
| 6852 The returned constant pool might not have the same layout or | |
| 6853 contents as the constant pool in the defining class file. | |
| 6854 The constant pool returned by GetConstantPool() may have | |
| 6855 more or fewer entries than the defining constant pool. | |
| 6856 Entries may be in a different order. | |
| 6857 The constant pool returned by GetConstantPool() will match the | |
| 6858 constant pool used by | |
| 6859 <functionlink id="GetBytecodes">GetBytecodes()</functionlink>. | |
| 6860 That is, the bytecodes returned by GetBytecodes() will have | |
| 6861 constant pool indices which refer to constant pool entries returned | |
| 6862 by GetConstantPool(). | |
| 6863 Note that since <functionlink id="RetransformClasses"/> | |
| 6864 and <functionlink id="RedefineClasses"/> can change | |
| 6865 the constant pool, the constant pool returned by this function | |
| 6866 can change accordingly. Thus, the correspondence between | |
| 6867 GetConstantPool() and GetBytecodes() does not hold if there | |
| 6868 is an intervening class retransformation or redefinition. | |
| 6869 The value of a constant pool entry used by a given bytecode will | |
| 6870 match that of the defining class file (even if the indices don't match). | |
| 6871 Constant pool entries which are not used directly or indirectly by | |
| 6872 bytecodes (for example, UTF-8 strings associated with annotations) are | |
| 6873 not required to exist in the returned constant pool. | |
| 6874 </description> | |
| 6875 <origin>new</origin> | |
| 6876 <capabilities> | |
| 6877 <required id="can_get_constant_pool"></required> | |
| 6878 </capabilities> | |
| 6879 <parameters> | |
| 6880 <param id="klass"> | |
| 6881 <jclass/> | |
| 6882 <description> | |
| 6883 The class to query. | |
| 6884 </description> | |
| 6885 </param> | |
| 6886 <param id="constant_pool_count_ptr"> | |
| 6887 <outptr><jint/></outptr> | |
| 6888 <description> | |
| 6889 On return, points to the number of entries | |
| 6890 in the constant pool table plus one. | |
| 6891 This corresponds to the <code>constant_pool_count</code> | |
| 6892 item of the Class File Format. | |
| 6893 </description> | |
| 6894 </param> | |
| 6895 <param id="constant_pool_byte_count_ptr"> | |
| 6896 <outptr><jint/></outptr> | |
| 6897 <description> | |
| 6898 On return, points to the number of bytes | |
| 6899 in the returned raw constant pool. | |
| 6900 </description> | |
| 6901 </param> | |
| 6902 <param id="constant_pool_bytes_ptr"> | |
| 6903 <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf> | |
| 6904 <description> | |
| 6905 On return, points to the raw constant pool, that is the bytes | |
| 6906 defined by the <code>constant_pool</code> item of the | |
| 6907 Class File Format | |
| 6908 </description> | |
| 6909 </param> | |
| 6910 </parameters> | |
| 6911 <errors> | |
| 6912 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 6913 The class is a primitive or array class. | |
| 6914 </error> | |
| 6915 </errors> | |
| 6916 </function> | |
| 6917 | |
| 6918 <function id="IsInterface" phase="start" num="55"> | |
| 6919 <synopsis>Is Interface</synopsis> | |
| 6920 <description> | |
| 6921 Determines whether a class object reference represents an interface. | |
| 6922 The <code>jboolean</code> result is | |
| 6923 <code>JNI_TRUE</code> if the "class" is actually an interface, | |
| 6924 <code>JNI_FALSE</code> otherwise. | |
| 6925 </description> | |
| 6926 <origin>jvmdi</origin> | |
| 6927 <capabilities> | |
| 6928 </capabilities> | |
| 6929 <parameters> | |
| 6930 <param id="klass"> | |
| 6931 <jclass/> | |
| 6932 <description> | |
| 6933 The class to query. | |
| 6934 </description> | |
| 6935 </param> | |
| 6936 <param id="is_interface_ptr"> | |
| 6937 <outptr><jboolean/></outptr> | |
| 6938 <description> | |
| 6939 On return, points to the boolean result of this function. | |
| 6940 | |
| 6941 </description> | |
| 6942 </param> | |
| 6943 </parameters> | |
| 6944 <errors> | |
| 6945 </errors> | |
| 6946 </function> | |
| 6947 | |
| 6948 <function id="IsArrayClass" phase="start" num="56"> | |
| 6949 <synopsis>Is Array Class</synopsis> | |
| 6950 <description> | |
| 6951 Determines whether a class object reference represents an array. | |
| 6952 The <code>jboolean</code> result is | |
| 6953 <code>JNI_TRUE</code> if the class is an array, | |
| 6954 <code>JNI_FALSE</code> otherwise. | |
| 6955 </description> | |
| 6956 <origin>jvmdi</origin> | |
| 6957 <capabilities> | |
| 6958 </capabilities> | |
| 6959 <parameters> | |
| 6960 <param id="klass"> | |
| 6961 <jclass/> | |
| 6962 <description> | |
| 6963 The class to query. | |
| 6964 </description> | |
| 6965 </param> | |
| 6966 <param id="is_array_class_ptr"> | |
| 6967 <outptr><jboolean/></outptr> | |
| 6968 <description> | |
| 6969 On return, points to the boolean result of this function. | |
| 6970 | |
| 6971 </description> | |
| 6972 </param> | |
| 6973 </parameters> | |
| 6974 <errors> | |
| 6975 </errors> | |
| 6976 </function> | |
| 6977 | |
| 6978 <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1"> | |
| 6979 <synopsis>Is Modifiable Class</synopsis> | |
| 6980 <description> | |
| 6981 Determines whether a class is modifiable. | |
| 6982 If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/> | |
| 6983 returns <code>JNI_TRUE</code>) the class can be | |
| 6984 redefined with <functionlink id="RedefineClasses"/> (assuming | |
| 6985 the agent possesses the | |
| 6986 <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/> | |
| 6987 capability) or | |
| 6988 retransformed with <functionlink id="RetransformClasses"/> (assuming | |
| 6989 the agent possesses the | |
| 6990 <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> | |
| 6991 capability). | |
| 6992 If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/> | |
| 6993 returns <code>JNI_FALSE</code>) the class can be neither | |
| 6994 redefined nor retransformed. | |
| 6995 <p/> | |
| 6996 Primitive classes (for example, <code>java.lang.Integer.TYPE</code>) | |
| 6997 and array classes are never modifiable. | |
| 6998 <p/> | |
| 6999 </description> | |
| 7000 <origin>new</origin> | |
| 7001 <capabilities> | |
| 7002 <capability id="can_redefine_any_class"> | |
| 7003 If possessed then all classes (except primitive and array classes) | |
| 7004 are modifiable. | |
| 7005 </capability> | |
| 7006 <capability id="can_redefine_classes"> | |
| 7007 No effect on the result of the function. | |
| 7008 But must additionally be possessed to modify the class with | |
| 7009 <functionlink id="RedefineClasses"/>. | |
| 7010 </capability> | |
| 7011 <capability id="can_retransform_classes"> | |
| 7012 No effect on the result of the function. | |
| 7013 But must additionally be possessed to modify the class with | |
| 7014 <functionlink id="RetransformClasses"/>. | |
| 7015 </capability> | |
| 7016 </capabilities> | |
| 7017 <parameters> | |
| 7018 <param id="klass"> | |
| 7019 <jclass/> | |
| 7020 <description> | |
| 7021 The class to query. | |
| 7022 </description> | |
| 7023 </param> | |
| 7024 <param id="is_modifiable_class_ptr"> | |
| 7025 <outptr><jboolean/></outptr> | |
| 7026 <description> | |
| 7027 On return, points to the boolean result of this function. | |
| 7028 </description> | |
| 7029 </param> | |
| 7030 </parameters> | |
| 7031 <errors> | |
| 7032 </errors> | |
| 7033 </function> | |
| 7034 | |
| 7035 <function id="GetClassLoader" phase="start" num="57"> | |
| 7036 <synopsis>Get Class Loader</synopsis> | |
| 7037 <description> | |
| 7038 For the class indicated by <code>klass</code>, return via | |
| 7039 <code>classloader_ptr</code> a reference to the class loader for the | |
| 7040 class. | |
| 7041 </description> | |
| 7042 <origin>jvmdi</origin> | |
| 7043 <capabilities> | |
| 7044 </capabilities> | |
| 7045 <parameters> | |
| 7046 <param id="klass"> | |
| 7047 <jclass/> | |
| 7048 <description> | |
| 7049 The class to query. | |
| 7050 </description> | |
| 7051 </param> | |
| 7052 <param id="classloader_ptr"> | |
| 7053 <outptr><jobject/></outptr> | |
| 7054 <description> | |
| 7055 On return, points to the class loader that loaded | |
| 7056 this class. | |
| 7057 If the class was not created by a class loader | |
| 7058 or if the class loader is the bootstrap class loader, | |
| 7059 points to <code>NULL</code>. | |
| 7060 </description> | |
| 7061 </param> | |
| 7062 </parameters> | |
| 7063 <errors> | |
| 7064 </errors> | |
| 7065 | |
| 7066 </function> | |
| 7067 | |
| 7068 <function id="GetSourceDebugExtension" phase="start" num="90"> | |
| 7069 <synopsis>Get Source Debug Extension</synopsis> | |
| 7070 <description> | |
| 7071 For the class indicated by <code>klass</code>, return the debug | |
| 7072 extension via <code>source_debug_extension_ptr</code>. | |
| 7073 The returned string | |
| 7074 contains exactly the debug extension information present in the | |
| 7075 class file of <code>klass</code>. | |
| 7076 </description> | |
| 7077 <origin>jvmdi</origin> | |
| 7078 <capabilities> | |
| 7079 <required id="can_get_source_debug_extension"></required> | |
| 7080 </capabilities> | |
| 7081 <parameters> | |
| 7082 <param id="klass"> | |
| 7083 <jclass/> | |
| 7084 <description> | |
| 7085 The class to query. | |
| 7086 </description> | |
| 7087 </param> | |
| 7088 <param id="source_debug_extension_ptr"> | |
| 7089 <allocbuf><char/></allocbuf> | |
| 7090 <description> | |
| 7091 On return, points to the class's debug extension, encoded as a | |
| 7092 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7093 </description> | |
| 7094 </param> | |
| 7095 </parameters> | |
| 7096 <errors> | |
| 7097 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 7098 Class information does not include a debug extension. | |
| 7099 </error> | |
| 7100 </errors> | |
| 7101 </function> | |
| 7102 | |
| 7103 <function id="RetransformClasses" jkernel="yes" num="152" since="1.1"> | |
| 7104 <synopsis>Retransform Classes</synopsis> | |
| 7105 <description> | |
| 7106 This function facilitates the | |
| 7107 <internallink id="bci">bytecode instrumentation</internallink> | |
| 7108 of already loaded classes. | |
| 7109 To replace the class definition without reference to the existing | |
| 7110 bytecodes, as one might do when recompiling from source for | |
| 7111 fix-and-continue debugging, <functionlink id="RedefineClasses"/> | |
| 7112 function should be used instead. | |
| 7113 <p/> | |
| 7114 When classes are initially loaded or when they are | |
| 7115 <functionlink id="RedefineClasses">redefined</functionlink>, | |
| 7116 the initial class file bytes can be transformed with the | |
| 7117 <eventlink id="ClassFileLoadHook"/> event. | |
| 7118 This function reruns the transformation process | |
| 7119 (whether or not a transformation has previously occurred). | |
| 7120 This retransformation follows these steps: | |
| 7121 <ul> | |
| 7122 <li>starting from the initial class file bytes | |
| 7123 </li> | |
| 7124 <li>for each <fieldlink id="can_retransform_classes" | |
| 7125 struct="jvmtiCapabilities">retransformation | |
| 7126 incapable</fieldlink> | |
| 7127 agent which received a | |
| 7128 <code>ClassFileLoadHook</code> event during the previous | |
| 7129 load or redefine, the bytes it returned | |
| 7130 (via the <code>new_class_data</code> parameter) | |
| 7131 are reused as the output of the transformation; | |
| 7132 note that this is equivalent to reapplying | |
| 7133 the previous transformation, unaltered. except that | |
| 7134 the <code>ClassFileLoadHook</code> event | |
| 7135 is <b>not</b> sent to these agents | |
| 7136 </li> | |
| 7137 <li>for each <fieldlink id="can_retransform_classes" | |
| 7138 struct="jvmtiCapabilities">retransformation | |
| 7139 capable</fieldlink> | |
| 7140 agent, the <code>ClassFileLoadHook</code> event is sent, | |
| 7141 allowing a new transformation to be applied | |
| 7142 </li> | |
| 7143 <li>the transformed class file bytes are installed as the new | |
| 7144 definition of the class | |
| 7145 </li> | |
| 7146 </ul> | |
| 7147 See the <eventlink id="ClassFileLoadHook"/> event for more details. | |
| 7148 <p/> | |
| 7149 The initial class file bytes represent the bytes passed to | |
| 7150 <code>ClassLoader.defineClass</code> | |
| 7151 or <code>RedefineClasses</code> (before any transformations | |
| 7152 were applied), however they may not exactly match them. | |
| 7153 The constant pool may differ in ways described in | |
| 7154 <functionlink id="GetConstantPool"/>. | |
| 7155 Constant pool indices in the bytecodes of methods will correspond. | |
| 7156 Some attributes may not be present. | |
| 7157 Where order is not meaningful, for example the order of methods, | |
| 7158 order may not be preserved. | |
| 7159 <p/> | |
| 7160 Retransformation can cause new versions of methods to be installed. | |
| 7161 Old method versions may become | |
| 7162 <internallink id="obsoleteMethods">obsolete</internallink> | |
| 7163 The new method version will be used on new invokes. | |
| 7164 If a method has active stack frames, those active frames continue to | |
| 7165 run the bytecodes of the original method version. | |
| 7166 <p/> | |
| 7167 This function does not cause any initialization except that which | |
| 7168 would occur under the customary JVM semantics. | |
| 7169 In other words, retransforming a class does not cause its initializers to be | |
| 7170 run. The values of static fields will remain as they were | |
| 7171 prior to the call. | |
| 7172 <p/> | |
| 7173 Threads need not be suspended. | |
| 7174 <p/> | |
| 7175 All breakpoints in the class are cleared. | |
| 7176 <p/> | |
| 7177 All attributes are updated. | |
| 7178 <p/> | |
| 7179 Instances of the retransformed class are not affected -- fields retain their | |
| 7180 previous values. | |
| 7181 <functionlink id="GetTag">Tags</functionlink> on the instances are | |
| 7182 also unaffected. | |
| 7183 <p/> | |
| 7184 In response to this call, no events other than the | |
| 7185 <eventlink id="ClassFileLoadHook"/> event | |
| 7186 will be sent. | |
| 7187 <p/> | |
| 7188 The retransformation may change method bodies, the constant pool and attributes. | |
| 7189 The retransformation must not add, remove or rename fields or methods, change the | |
| 7190 signatures of methods, change modifiers, or change inheritance. | |
| 7191 These restrictions may be lifted in future versions. | |
| 7192 See the error return description below for information on error codes | |
| 7193 returned if an unsupported retransformation is attempted. | |
| 7194 The class file bytes are not verified or installed until they have passed | |
| 7195 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the | |
| 7196 returned error code reflects the result of the transformations. | |
| 7197 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, | |
| 7198 none of the classes to be retransformed will have a new definition installed. | |
| 7199 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) | |
| 7200 all of the classes to be retransformed will have their new definitions installed. | |
| 7201 </description> | |
| 7202 <origin>new</origin> | |
| 7203 <capabilities> | |
| 7204 <required id="can_retransform_classes"></required> | |
| 7205 <capability id="can_retransform_any_class"></capability> | |
| 7206 </capabilities> | |
| 7207 <parameters> | |
| 7208 <param id="class_count"> | |
| 7209 <jint min="0"/> | |
| 7210 <description> | |
| 7211 The number of classes to be retransformed. | |
| 7212 </description> | |
| 7213 </param> | |
| 7214 <param id="classes"> | |
| 7215 <inbuf incount="class_count"><jclass/></inbuf> | |
| 7216 <description> | |
| 7217 The array of classes to be retransformed. | |
| 7218 </description> | |
| 7219 </param> | |
| 7220 </parameters> | |
| 7221 <errors> | |
| 7222 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> | |
| 7223 One of the <paramlink id="classes"/> cannot be modified. | |
| 7224 See <functionlink id="IsModifiableClass"/>. | |
| 7225 </error> | |
| 7226 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 7227 One of the <paramlink id="classes"/> is not a valid class. | |
| 7228 </error> | |
| 7229 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> | |
| 7230 A retransformed class file has a version number not supported by this VM. | |
| 7231 </error> | |
| 7232 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> | |
| 7233 A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>). | |
| 7234 </error> | |
| 7235 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> | |
| 7236 The retransformed class file definitions would lead to a circular definition | |
| 7237 (the VM would return a <code>ClassCircularityError</code>). | |
| 7238 </error> | |
| 7239 <error id="JVMTI_ERROR_FAILS_VERIFICATION"> | |
| 7240 The retransformed class file bytes fail verification. | |
| 7241 </error> | |
| 7242 <error id="JVMTI_ERROR_NAMES_DONT_MATCH"> | |
| 7243 The class name defined in a retransformed class file is | |
| 7244 different from the name in the old class object. | |
| 7245 </error> | |
| 7246 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> | |
| 7247 A retransformed class file would require adding a method. | |
| 7248 </error> | |
| 7249 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> | |
| 7250 A retransformed class file changes a field. | |
| 7251 </error> | |
| 7252 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> | |
| 7253 A direct superclass is different for a retransformed class file, | |
| 7254 or the set of directly implemented | |
| 7255 interfaces is different. | |
| 7256 </error> | |
| 7257 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> | |
| 7258 A retransformed class file does not declare a method | |
| 7259 declared in the old class version. | |
| 7260 </error> | |
| 7261 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> | |
| 7262 A retransformed class file has different class modifiers. | |
| 7263 </error> | |
| 7264 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> | |
| 7265 A method in the retransformed class file has different modifiers | |
| 7266 than its counterpart in the old class version. | |
| 7267 </error> | |
| 7268 </errors> | |
| 7269 </function> | |
| 7270 | |
| 7271 <function id="RedefineClasses" jkernel="yes" num="87"> | |
| 7272 <synopsis>Redefine Classes</synopsis> | |
| 7273 <typedef id="jvmtiClassDefinition" label="Class redefinition description"> | |
| 7274 <field id="klass"> | |
| 7275 <jclass/> | |
| 7276 <description> | |
| 7277 Class object for this class | |
| 7278 </description> | |
| 7279 </field> | |
| 7280 <field id="class_byte_count"> | |
| 7281 <jint/> | |
| 7282 <description> | |
| 7283 Number of bytes defining class (below) | |
| 7284 </description> | |
| 7285 </field> | |
| 7286 <field id="class_bytes"> | |
| 7287 <inbuf incount="class_byte_count"><uchar/></inbuf> | |
| 7288 <description> | |
| 7289 Bytes defining class (in the | |
| 7290 <vmspeclink id="ClassFile.doc.html" | |
| 7291 name="Class File Format"/>) | |
| 7292 </description> | |
| 7293 </field> | |
| 7294 </typedef> | |
| 7295 <description> | |
| 7296 All classes given are redefined according to the definitions | |
| 7297 supplied. | |
| 7298 This function is used to replace the definition of a class | |
| 7299 with a new definition, as might be needed in fix-and-continue | |
| 7300 debugging. | |
| 7301 Where the existing class file bytes are to be transformed, for | |
| 7302 example in | |
| 7303 <internallink id="bci">bytecode instrumentation</internallink>, | |
| 7304 <functionlink id="RetransformClasses"/> should be used. | |
| 7305 <p/> | |
| 7306 Redefinition can cause new versions of methods to be installed. | |
| 7307 Old method versions may become | |
| 7308 <internallink id="obsoleteMethods">obsolete</internallink> | |
| 7309 The new method version will be used on new invokes. | |
| 7310 If a method has active stack frames, those active frames continue to | |
| 7311 run the bytecodes of the original method version. | |
| 7312 If resetting of stack frames is desired, use | |
| 7313 <functionlink id="PopFrame"></functionlink> | |
| 7314 to pop frames with obsolete method versions. | |
| 7315 <p/> | |
| 7316 This function does not cause any initialization except that which | |
| 7317 would occur under the customary JVM semantics. | |
| 7318 In other words, redefining a class does not cause its initializers to be | |
| 7319 run. The values of static fields will remain as they were | |
| 7320 prior to the call. | |
| 7321 <p/> | |
| 7322 Threads need not be suspended. | |
| 7323 <p/> | |
| 7324 All breakpoints in the class are cleared. | |
| 7325 <p/> | |
| 7326 All attributes are updated. | |
| 7327 <p/> | |
| 7328 Instances of the redefined class are not affected -- fields retain their | |
| 7329 previous values. | |
| 7330 <functionlink id="GetTag">Tags</functionlink> on the instances are | |
| 7331 also unaffected. | |
| 7332 <p/> | |
| 7333 In response to this call, the <jvmti/> event | |
| 7334 <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink> | |
| 7335 will be sent (if enabled), but no other <jvmti/> events will be sent. | |
| 7336 <p/> | |
| 7337 The redefinition may change method bodies, the constant pool and attributes. | |
| 7338 The redefinition must not add, remove or rename fields or methods, change the | |
| 7339 signatures of methods, change modifiers, or change inheritance. | |
| 7340 These restrictions may be lifted in future versions. | |
| 7341 See the error return description below for information on error codes | |
| 7342 returned if an unsupported redefinition is attempted. | |
| 7343 The class file bytes are not verified or installed until they have passed | |
| 7344 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the | |
| 7345 returned error code reflects the result of the transformations applied | |
| 7346 to the bytes passed into <paramlink id="class_definitions"/>. | |
| 7347 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, | |
| 7348 none of the classes to be redefined will have a new definition installed. | |
| 7349 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) | |
| 7350 all of the classes to be redefined will have their new definitions installed. | |
| 7351 </description> | |
| 7352 <origin>jvmdi</origin> | |
| 7353 <capabilities> | |
| 7354 <required id="can_redefine_classes"></required> | |
| 7355 <capability id="can_redefine_any_class"></capability> | |
| 7356 </capabilities> | |
| 7357 <parameters> | |
| 7358 <param id="class_count"> | |
| 7359 <jint min="0"/> | |
| 7360 <description> | |
| 7361 The number of classes specified in <code>class_definitions</code> | |
| 7362 </description> | |
| 7363 </param> | |
| 7364 <param id="class_definitions"> | |
| 7365 <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf> | |
| 7366 <description> | |
| 7367 The array of new class definitions | |
| 7368 </description> | |
| 7369 </param> | |
| 7370 </parameters> | |
| 7371 <errors> | |
| 7372 <error id="JVMTI_ERROR_NULL_POINTER"> | |
| 7373 One of <code>class_bytes</code> is <code>NULL</code>. | |
| 7374 </error> | |
| 7375 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> | |
| 7376 An element of <code>class_definitions</code> cannot be modified. | |
| 7377 See <functionlink id="IsModifiableClass"/>. | |
| 7378 </error> | |
| 7379 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 7380 An element of <code>class_definitions</code> is not a valid class. | |
| 7381 </error> | |
| 7382 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> | |
| 7383 A new class file has a version number not supported by this VM. | |
| 7384 </error> | |
| 7385 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> | |
| 7386 A new class file is malformed (The VM would return a <code>ClassFormatError</code>). | |
| 7387 </error> | |
| 7388 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> | |
| 7389 The new class file definitions would lead to a circular definition | |
| 7390 (the VM would return a <code>ClassCircularityError</code>). | |
| 7391 </error> | |
| 7392 <error id="JVMTI_ERROR_FAILS_VERIFICATION"> | |
| 7393 The class bytes fail verification. | |
| 7394 </error> | |
| 7395 <error id="JVMTI_ERROR_NAMES_DONT_MATCH"> | |
| 7396 The class name defined in a new class file is | |
| 7397 different from the name in the old class object. | |
| 7398 </error> | |
| 7399 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> | |
| 7400 A new class file would require adding a method. | |
| 7401 </error> | |
| 7402 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> | |
| 7403 A new class version changes a field. | |
| 7404 </error> | |
| 7405 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> | |
| 7406 A direct superclass is different for a new class | |
| 7407 version, or the set of directly implemented | |
| 7408 interfaces is different. | |
| 7409 </error> | |
| 7410 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> | |
| 7411 A new class version does not declare a method | |
| 7412 declared in the old class version. | |
| 7413 </error> | |
| 7414 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> | |
| 7415 A new class version has different modifiers. | |
| 7416 </error> | |
| 7417 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> | |
| 7418 A method in the new class version has different modifiers | |
| 7419 than its counterpart in the old class version. | |
| 7420 </error> | |
| 7421 </errors> | |
| 7422 </function> | |
| 7423 | |
| 7424 </category> | |
| 7425 | |
| 7426 <category id="object" label="Object"> | |
| 7427 | |
| 7428 <function id="GetObjectSize" jkernel="yes" phase="start" num="154"> | |
| 7429 <synopsis>Get Object Size</synopsis> | |
| 7430 <description> | |
| 7431 For the object indicated by <code>object</code>, | |
| 7432 return via <code>size_ptr</code> the size of the object. | |
| 7433 This size is an implementation-specific approximation of | |
| 7434 the amount of storage consumed by this object. | |
| 7435 It may include some or all of the object's overhead, and thus | |
| 7436 is useful for comparison within an implementation but not | |
| 7437 between implementations. | |
| 7438 The estimate may change during a single invocation of the JVM. | |
| 7439 </description> | |
| 7440 <origin>new</origin> | |
| 7441 <capabilities> | |
| 7442 </capabilities> | |
| 7443 <parameters> | |
| 7444 <param id="object"> | |
| 7445 <jobject/> | |
| 7446 <description> | |
| 7447 The object to query. | |
| 7448 </description> | |
| 7449 </param> | |
| 7450 <param id="size_ptr"> | |
| 7451 <outptr><jlong/></outptr> | |
| 7452 <description> | |
| 7453 On return, points to the object's size in bytes. | |
| 7454 </description> | |
| 7455 </param> | |
| 7456 </parameters> | |
| 7457 <errors> | |
| 7458 </errors> | |
| 7459 </function> | |
| 7460 | |
| 7461 <function id="GetObjectHashCode" phase="start" num="58"> | |
| 7462 <synopsis>Get Object Hash Code</synopsis> | |
| 7463 <description> | |
| 7464 For the object indicated by <code>object</code>, | |
| 7465 return via <code>hash_code_ptr</code> a hash code. | |
| 7466 This hash code could be used to maintain a hash table of object references, | |
| 7467 however, on some implementations this can cause significant performance | |
| 7468 impacts--in most cases | |
| 7469 <internallink id="Heap">tags</internallink> | |
| 7470 will be a more efficient means of associating information with objects. | |
| 7471 This function guarantees | |
| 7472 the same hash code value for a particular object throughout its life | |
| 7473 </description> | |
| 7474 <origin>jvmdi</origin> | |
| 7475 <capabilities> | |
| 7476 </capabilities> | |
| 7477 <parameters> | |
| 7478 <param id="object"> | |
| 7479 <jobject/> | |
| 7480 <description> | |
| 7481 The object to query. | |
| 7482 </description> | |
| 7483 </param> | |
| 7484 <param id="hash_code_ptr"> | |
| 7485 <outptr><jint/></outptr> | |
| 7486 <description> | |
| 7487 On return, points to the object's hash code. | |
| 7488 </description> | |
| 7489 </param> | |
| 7490 </parameters> | |
| 7491 <errors> | |
| 7492 </errors> | |
| 7493 </function> | |
| 7494 | |
| 7495 <function id="GetObjectMonitorUsage" num="59"> | |
| 7496 <synopsis>Get Object Monitor Usage</synopsis> | |
| 7497 <typedef id="jvmtiMonitorUsage" label="Object monitor usage information"> | |
| 7498 <field id="owner"> | |
| 7499 <jthread/> | |
| 7500 <description> | |
| 7501 The thread owning this monitor, or <code>NULL</code> if unused | |
| 7502 </description> | |
| 7503 </field> | |
| 7504 <field id="entry_count"> | |
| 7505 <jint/> | |
| 7506 <description> | |
| 7507 The number of times the owning thread has entered the monitor | |
| 7508 </description> | |
| 7509 </field> | |
| 7510 <field id="waiter_count"> | |
| 7511 <jint/> | |
| 7512 <description> | |
| 7513 The number of threads waiting to own this monitor | |
| 7514 </description> | |
| 7515 </field> | |
| 7516 <field id="waiters"> | |
| 7517 <allocfieldbuf><jthread/></allocfieldbuf> | |
| 7518 <description> | |
| 7519 The <code>waiter_count</code> waiting threads | |
| 7520 </description> | |
| 7521 </field> | |
| 7522 <field id="notify_waiter_count"> | |
| 7523 <jint/> | |
| 7524 <description> | |
| 7525 The number of threads waiting to be notified by this monitor | |
| 7526 </description> | |
| 7527 </field> | |
| 7528 <field id="notify_waiters"> | |
| 7529 <allocfieldbuf><jthread/></allocfieldbuf> | |
| 7530 <description> | |
| 7531 The <code>notify_waiter_count</code> threads waiting to be notified | |
| 7532 </description> | |
| 7533 </field> | |
| 7534 </typedef> | |
| 7535 <description> | |
| 7536 Get information about the object's monitor. | |
| 7537 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure | |
| 7538 are filled in with information about usage of the monitor. | |
| 7539 <todo> | |
| 7540 Decide and then clarify suspend requirements. | |
| 7541 </todo> | |
| 7542 </description> | |
| 7543 <origin>jvmdi</origin> | |
| 7544 <capabilities> | |
| 7545 <required id="can_get_monitor_info"></required> | |
| 7546 </capabilities> | |
| 7547 <parameters> | |
| 7548 <param id="object"> | |
| 7549 <jobject/> | |
| 7550 <description> | |
| 7551 The object to query. | |
| 7552 </description> | |
| 7553 </param> | |
| 7554 <param id="info_ptr"> | |
| 7555 <outptr><struct>jvmtiMonitorUsage</struct></outptr> | |
| 7556 <description> | |
| 7557 On return, filled with monitor information for the | |
| 7558 specified object. | |
| 7559 </description> | |
| 7560 </param> | |
| 7561 </parameters> | |
| 7562 <errors> | |
| 7563 </errors> | |
| 7564 </function> | |
| 7565 | |
| 7566 <elide> | |
| 7567 <function id="GetObjectMonitors" num="116"> | |
| 7568 <synopsis>Get Object Monitors</synopsis> | |
| 7569 <description> | |
| 7570 Return the list of object monitors. | |
| 7571 <p/> | |
| 7572 Note: details about each monitor can be examined with | |
| 7573 <functionlink id="GetObjectMonitorUsage"></functionlink>. | |
| 7574 </description> | |
| 7575 <origin>new</origin> | |
| 7576 <capabilities> | |
| 7577 <required id="can_get_monitor_info"></required> | |
| 7578 </capabilities> | |
| 7579 <parameters> | |
| 7580 <param id="monitorCnt"> | |
| 7581 <outptr><jint/></outptr> | |
| 7582 <description> | |
| 7583 On return, pointer to the number | |
| 7584 of monitors returned in <code>monitors_ptr</code>. | |
| 7585 </description> | |
| 7586 </param> | |
| 7587 <param id="monitors_ptr"> | |
| 7588 <allocbuf outcount="monitorCnt"><jobject/></allocbuf> | |
| 7589 <description> | |
| 7590 On return, pointer to the monitor list. | |
| 7591 </description> | |
| 7592 </param> | |
| 7593 </parameters> | |
| 7594 <errors> | |
| 7595 </errors> | |
| 7596 </function> | |
| 7597 </elide> | |
| 7598 | |
| 7599 </category> | |
| 7600 | |
| 7601 <category id="fieldCategory" label="Field"> | |
| 7602 | |
| 7603 <intro> | |
| 7604 </intro> | |
| 7605 | |
| 7606 <function id="GetFieldName" phase="start" num="60"> | |
| 7607 <synopsis>Get Field Name (and Signature)</synopsis> | |
| 7608 <description> | |
| 7609 For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>, | |
| 7610 return the field name via <paramlink id="name_ptr"/> and field signature via | |
| 7611 <paramlink id="signature_ptr"/>. | |
| 7612 <p/> | |
| 7613 Field signatures are defined in the JNI Specification and | |
| 7614 are referred to as | |
| 7615 <vmspeclink id="ClassFile.doc.html#14152" | |
| 7616 name="field descriptors" | |
| 7617 preposition="in"/>. | |
| 7618 </description> | |
| 7619 <origin>jvmdiClone</origin> | |
| 7620 <capabilities> | |
| 7621 </capabilities> | |
| 7622 <parameters> | |
| 7623 <param id="klass"> | |
| 7624 <jclass field="field"/> | |
| 7625 <description> | |
| 7626 The class of the field to query. | |
| 7627 </description> | |
| 7628 </param> | |
| 7629 <param id="field"> | |
| 7630 <jfieldID class="klass"/> | |
| 7631 <description> | |
| 7632 The field to query. | |
| 7633 </description> | |
| 7634 </param> | |
| 7635 <param id="name_ptr"> | |
| 7636 <allocbuf> | |
| 7637 <char/> | |
| 7638 <nullok>the name is not returned</nullok> | |
| 7639 </allocbuf> | |
| 7640 <description> | |
| 7641 On return, points to the field name, encoded as a | |
| 7642 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7643 </description> | |
| 7644 </param> | |
| 7645 <param id="signature_ptr"> | |
| 7646 <allocbuf> | |
| 7647 <char/> | |
| 7648 <nullok>the signature is not returned</nullok> | |
| 7649 </allocbuf> | |
| 7650 <description> | |
| 7651 On return, points to the field signature, encoded as a | |
| 7652 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7653 </description> | |
| 7654 </param> | |
| 7655 <param id="generic_ptr"> | |
| 7656 <allocbuf> | |
| 7657 <char/> | |
| 7658 <nullok>the generic signature is not returned</nullok> | |
| 7659 </allocbuf> | |
| 7660 <description> | |
| 7661 On return, points to the generic signature of the field, encoded as a | |
| 7662 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7663 If there is no generic signature attribute for the field, then, | |
| 7664 on return, points to <code>NULL</code>. | |
| 7665 </description> | |
| 7666 </param> | |
| 7667 </parameters> | |
| 7668 <errors> | |
| 7669 </errors> | |
| 7670 </function> | |
| 7671 | |
| 7672 <function id="GetFieldDeclaringClass" phase="start" num="61"> | |
| 7673 <synopsis>Get Field Declaring Class</synopsis> | |
| 7674 <description> | |
| 7675 For the field indicated by <code>klass</code> and <code>field</code> | |
| 7676 return the class that defined it via <code>declaring_class_ptr</code>. | |
| 7677 The declaring class will either be <code>klass</code>, a superclass, or | |
| 7678 an implemented interface. | |
| 7679 </description> | |
| 7680 <origin>jvmdi</origin> | |
| 7681 <capabilities> | |
| 7682 </capabilities> | |
| 7683 <parameters> | |
| 7684 <param id="klass"> | |
| 7685 <jclass field="field"/> | |
| 7686 <description> | |
| 7687 The class to query. | |
| 7688 </description> | |
| 7689 </param> | |
| 7690 <param id="field"> | |
| 7691 <jfieldID class="klass"/> | |
| 7692 <description> | |
| 7693 The field to query. | |
| 7694 </description> | |
| 7695 </param> | |
| 7696 <param id="declaring_class_ptr"> | |
| 7697 <outptr><jclass/></outptr> | |
| 7698 <description> | |
| 7699 On return, points to the declaring class | |
| 7700 </description> | |
| 7701 </param> | |
| 7702 </parameters> | |
| 7703 <errors> | |
| 7704 </errors> | |
| 7705 </function> | |
| 7706 | |
| 7707 <function id="GetFieldModifiers" phase="start" num="62"> | |
| 7708 <synopsis>Get Field Modifiers</synopsis> | |
| 7709 <description> | |
| 7710 For the field indicated by <code>klass</code> and <code>field</code> | |
| 7711 return the access flags via <code>modifiers_ptr</code>. | |
| 7712 Access flags are defined in the | |
| 7713 <vmspeclink id="ClassFile.doc.html" | |
| 7714 name="Class File Format chapter"/>. | |
| 7715 </description> | |
| 7716 <origin>jvmdi</origin> | |
| 7717 <capabilities> | |
| 7718 </capabilities> | |
| 7719 <parameters> | |
| 7720 <param id="klass"> | |
| 7721 <jclass field="field"/> | |
| 7722 <description> | |
| 7723 The class to query. | |
| 7724 </description> | |
| 7725 </param> | |
| 7726 <param id="field"> | |
| 7727 <jfieldID class="klass"/> | |
| 7728 <description> | |
| 7729 The field to query. | |
| 7730 </description> | |
| 7731 </param> | |
| 7732 <param id="modifiers_ptr"> | |
| 7733 <outptr><jint/></outptr> | |
| 7734 <description> | |
| 7735 On return, points to the access flags. | |
| 7736 </description> | |
| 7737 </param> | |
| 7738 </parameters> | |
| 7739 <errors> | |
| 7740 </errors> | |
| 7741 </function> | |
| 7742 | |
| 7743 <function id="IsFieldSynthetic" phase="start" num="63"> | |
| 7744 <synopsis>Is Field Synthetic</synopsis> | |
| 7745 <description> | |
| 7746 For the field indicated by <code>klass</code> and <code>field</code>, return a | |
| 7747 value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>. | |
| 7748 Synthetic fields are generated by the compiler but not present in the | |
| 7749 original source code. | |
| 7750 </description> | |
| 7751 <origin>jvmdi</origin> | |
| 7752 <capabilities> | |
| 7753 <required id="can_get_synthetic_attribute"></required> | |
| 7754 </capabilities> | |
| 7755 <parameters> | |
| 7756 <param id="klass"> | |
| 7757 <jclass field="field"/> | |
| 7758 <description> | |
| 7759 The class of the field to query. | |
| 7760 </description> | |
| 7761 </param> | |
| 7762 <param id="field"> | |
| 7763 <jfieldID class="klass"/> | |
| 7764 <description> | |
| 7765 The field to query. | |
| 7766 </description> | |
| 7767 </param> | |
| 7768 <param id="is_synthetic_ptr"> | |
| 7769 <outptr><jboolean/></outptr> | |
| 7770 <description> | |
| 7771 On return, points to the boolean result of this function. | |
| 7772 </description> | |
| 7773 </param> | |
| 7774 </parameters> | |
| 7775 <errors> | |
| 7776 </errors> | |
| 7777 </function> | |
| 7778 | |
| 7779 </category> | |
| 7780 | |
| 7781 <category id="method" label="Method"> | |
| 7782 | |
| 7783 <intro> | |
| 7784 These functions provide information about a method (represented as a | |
| 7785 <typelink id="jmethodID"/>) and set how methods are processed. | |
| 7786 </intro> | |
| 7787 | |
| 7788 <intro id="obsoleteMethods" label="Obsolete Methods"> | |
| 7789 The functions <functionlink id="RetransformClasses"/> and | |
| 7790 <functionlink id="RedefineClasses"/> can cause new versions | |
| 7791 of methods to be installed. | |
| 7792 An original version of a method is considered equivalent | |
| 7793 to the new version if: | |
| 7794 <ul> | |
| 7795 <li>their bytecodes are the same except for indices into the | |
| 7796 constant pool and </li> | |
| 7797 <li>the referenced constants are equal.</li> | |
| 7798 </ul> | |
| 7799 An original method version which is not equivalent to the | |
| 7800 new method version is called obsolete and is assigned a new method ID; | |
| 7801 the original method ID now refers to the new method version. | |
| 7802 A method ID can be tested for obsolescence with | |
| 7803 <functionlink id="IsMethodObsolete"/>. | |
| 7804 </intro> | |
| 7805 | |
| 7806 <function id="GetMethodName" phase="start" num="64"> | |
| 7807 <synopsis>Get Method Name (and Signature)</synopsis> | |
| 7808 <description> | |
| 7809 For the method indicated by <code>method</code>, | |
| 7810 return the method name via <code>name_ptr</code> and method signature via | |
| 7811 <code>signature_ptr</code>. | |
| 7812 <p/> | |
| 7813 Method signatures are defined in the JNI Specification and are referred to as | |
| 7814 <vmspeclink id="ClassFile.doc.html#7035" | |
| 7815 name="method descriptors" | |
| 7816 preposition="in"/>. | |
| 7817 Note this is different | |
| 7818 than method signatures as defined in the <i>Java Language Specification</i>. | |
| 7819 </description> | |
| 7820 <origin>jvmdiClone</origin> | |
| 7821 <capabilities> | |
| 7822 </capabilities> | |
| 7823 <parameters> | |
| 7824 <param id="method"> | |
| 7825 <jmethodID/> | |
| 7826 <description> | |
| 7827 The method to query. | |
| 7828 </description> | |
| 7829 </param> | |
| 7830 <param id="name_ptr"> | |
| 7831 <allocbuf> | |
| 7832 <char/> | |
| 7833 <nullok>the name is not returned</nullok> | |
| 7834 </allocbuf> | |
| 7835 <description> | |
| 7836 On return, points to the method name, encoded as a | |
| 7837 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7838 </description> | |
| 7839 </param> | |
| 7840 <param id="signature_ptr"> | |
| 7841 <allocbuf> | |
| 7842 <char/> | |
| 7843 <nullok>the signature is not returned</nullok> | |
| 7844 </allocbuf> | |
| 7845 <description> | |
| 7846 On return, points to the method signature, encoded as a | |
| 7847 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7848 </description> | |
| 7849 </param> | |
| 7850 <param id="generic_ptr"> | |
| 7851 <allocbuf> | |
| 7852 <char/> | |
| 7853 <nullok>the generic signature is not returned</nullok> | |
| 7854 </allocbuf> | |
| 7855 <description> | |
| 7856 On return, points to the generic signature of the method, encoded as a | |
| 7857 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7858 If there is no generic signature attribute for the method, then, | |
| 7859 on return, points to <code>NULL</code>. | |
| 7860 </description> | |
| 7861 </param> | |
| 7862 </parameters> | |
| 7863 <errors> | |
| 7864 </errors> | |
| 7865 </function> | |
| 7866 | |
| 7867 <function id="GetMethodDeclaringClass" phase="start" num="65"> | |
| 7868 <synopsis>Get Method Declaring Class</synopsis> | |
| 7869 <description> | |
| 7870 For the method indicated by <code>method</code>, | |
| 7871 return the class that defined it via <code>declaring_class_ptr</code>. | |
| 7872 </description> | |
| 7873 <origin>jvmdi</origin> | |
| 7874 <capabilities> | |
| 7875 </capabilities> | |
| 7876 <parameters> | |
| 7877 <param id="klass"> | |
| 7878 <jclass method="method"/> | |
| 7879 <description> | |
| 7880 The class to query. | |
| 7881 </description> | |
| 7882 </param> | |
| 7883 <param id="method"> | |
| 7884 <jmethodID class="klass"/> | |
| 7885 <description> | |
| 7886 The method to query. | |
| 7887 </description> | |
| 7888 </param> | |
| 7889 <param id="declaring_class_ptr"> | |
| 7890 <outptr><jclass/></outptr> | |
| 7891 <description> | |
| 7892 On return, points to the declaring class | |
| 7893 </description> | |
| 7894 </param> | |
| 7895 </parameters> | |
| 7896 <errors> | |
| 7897 </errors> | |
| 7898 </function> | |
| 7899 | |
| 7900 <function id="GetMethodModifiers" phase="start" num="66"> | |
| 7901 <synopsis>Get Method Modifiers</synopsis> | |
| 7902 <description> | |
| 7903 For the method indicated by <code>method</code>, | |
| 7904 return the access flags via <code>modifiers_ptr</code>. | |
| 7905 Access flags are defined in the | |
| 7906 <vmspeclink id="ClassFile.doc.html" | |
| 7907 name="Class File Format chapter"/>. | |
| 7908 </description> | |
| 7909 <origin>jvmdi</origin> | |
| 7910 <capabilities> | |
| 7911 </capabilities> | |
| 7912 <parameters> | |
| 7913 <param id="klass"> | |
| 7914 <jclass method="method"/> | |
| 7915 <description> | |
| 7916 The class to query. | |
| 7917 </description> | |
| 7918 </param> | |
| 7919 <param id="method"> | |
| 7920 <jmethodID class="klass"/> | |
| 7921 <description> | |
| 7922 The method to query. | |
| 7923 </description> | |
| 7924 </param> | |
| 7925 <param id="modifiers_ptr"> | |
| 7926 <outptr><jint/></outptr> | |
| 7927 <description> | |
| 7928 On return, points to the access flags. | |
| 7929 </description> | |
| 7930 </param> | |
| 7931 </parameters> | |
| 7932 <errors> | |
| 7933 </errors> | |
| 7934 </function> | |
| 7935 | |
| 7936 <function id="GetMaxLocals" phase="start" num="68"> | |
| 7937 <synopsis>Get Max Locals</synopsis> | |
| 7938 <description> | |
| 7939 For the method indicated by <code>method</code>, | |
| 7940 return the number of local variable slots used by the method, | |
| 7941 including the local variables used to pass parameters to the | |
| 7942 method on its invocation. | |
| 7943 <p/> | |
| 7944 See <code>max_locals</code> in the | |
| 7945 <vmspeclink id="ClassFile.doc.html#1546" | |
| 7946 name="Code Attribute section"/>. | |
| 7947 </description> | |
| 7948 <origin>jvmdi</origin> | |
| 7949 <capabilities> | |
| 7950 </capabilities> | |
| 7951 <parameters> | |
| 7952 <param id="klass"> | |
| 7953 <jclass method="method"/> | |
| 7954 <description> | |
| 7955 The class to query. | |
| 7956 </description> | |
| 7957 </param> | |
| 7958 <param id="method"> | |
| 7959 <jmethodID class="klass" native="error"/> | |
| 7960 <description> | |
| 7961 The method to query. | |
| 7962 </description> | |
| 7963 </param> | |
| 7964 <param id="max_ptr"> | |
| 7965 <outptr><jint/></outptr> | |
| 7966 <description> | |
| 7967 On return, points to the maximum number of local slots | |
| 7968 </description> | |
| 7969 </param> | |
| 7970 </parameters> | |
| 7971 <errors> | |
| 7972 </errors> | |
| 7973 </function> | |
| 7974 | |
| 7975 <function id="GetArgumentsSize" phase="start" num="69"> | |
| 7976 <synopsis>Get Arguments Size</synopsis> | |
| 7977 <description> | |
| 7978 For the method indicated by <code>method</code>, | |
| 7979 return via <code>max_ptr</code> the number of local variable slots used | |
| 7980 by the method's arguments. | |
| 7981 Note that two-word arguments use two slots. | |
| 7982 </description> | |
| 7983 <origin>jvmdi</origin> | |
| 7984 <capabilities> | |
| 7985 </capabilities> | |
| 7986 <parameters> | |
| 7987 <param id="klass"> | |
| 7988 <jclass method="method"/> | |
| 7989 <description> | |
| 7990 The class to query. | |
| 7991 </description> | |
| 7992 </param> | |
| 7993 <param id="method"> | |
| 7994 <jmethodID class="klass" native="error"/> | |
| 7995 <description> | |
| 7996 The method to query. | |
| 7997 </description> | |
| 7998 </param> | |
| 7999 <param id="size_ptr"> | |
| 8000 <outptr><jint/></outptr> | |
| 8001 <description> | |
| 8002 On return, points to the number of argument slots | |
| 8003 </description> | |
| 8004 </param> | |
| 8005 </parameters> | |
| 8006 <errors> | |
| 8007 </errors> | |
| 8008 </function> | |
| 8009 | |
| 8010 <function id="GetLineNumberTable" phase="start" num="70"> | |
| 8011 <synopsis>Get Line Number Table</synopsis> | |
| 8012 <typedef id="jvmtiLineNumberEntry" label="Line number table entry"> | |
| 8013 <field id="start_location"> | |
| 8014 <jlocation/> | |
| 8015 <description> | |
| 8016 the <datalink id="jlocation"></datalink> where the line begins | |
| 8017 </description> | |
| 8018 </field> | |
| 8019 <field id="line_number"> | |
| 8020 <jint/> | |
| 8021 <description> | |
| 8022 the line number | |
| 8023 </description> | |
| 8024 </field> | |
| 8025 </typedef> | |
| 8026 <description> | |
| 8027 For the method indicated by <code>method</code>, | |
| 8028 return a table of source line number entries. The size of the table is | |
| 8029 returned via <code>entry_count_ptr</code> and the table itself is | |
| 8030 returned via <code>table_ptr</code>. | |
| 8031 </description> | |
| 8032 <origin>jvmdi</origin> | |
| 8033 <capabilities> | |
| 8034 <required id="can_get_line_numbers"></required> | |
| 8035 </capabilities> | |
| 8036 <parameters> | |
| 8037 <param id="klass"> | |
| 8038 <jclass method="method"/> | |
| 8039 <description> | |
| 8040 The class to query. | |
| 8041 </description> | |
| 8042 </param> | |
| 8043 <param id="method"> | |
| 8044 <jmethodID class="klass" native="error"/> | |
| 8045 <description> | |
| 8046 The method to query. | |
| 8047 </description> | |
| 8048 </param> | |
| 8049 <param id="entry_count_ptr"> | |
| 8050 <outptr><jint/></outptr> | |
| 8051 <description> | |
| 8052 On return, points to the number of entries in the table | |
| 8053 </description> | |
| 8054 </param> | |
| 8055 <param id="table_ptr"> | |
| 8056 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf> | |
| 8057 <description> | |
| 8058 On return, points to the line number table pointer. | |
| 8059 </description> | |
| 8060 </param> | |
| 8061 </parameters> | |
| 8062 <errors> | |
| 8063 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 8064 Class information does not include line numbers. | |
| 8065 </error> | |
| 8066 </errors> | |
| 8067 </function> | |
| 8068 | |
| 8069 <function id="GetMethodLocation" phase="start" num="71"> | |
| 8070 <synopsis>Get Method Location</synopsis> | |
| 8071 <description> | |
| 8072 For the method indicated by <code>method</code>, | |
| 8073 return the beginning and ending addresses through | |
| 8074 <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a | |
| 8075 conventional byte code indexing scheme, | |
| 8076 <code>start_location_ptr</code> will always point to zero | |
| 8077 and <code>end_location_ptr</code> | |
| 8078 will always point to the byte code count minus one. | |
| 8079 </description> | |
| 8080 <origin>jvmdi</origin> | |
| 8081 <capabilities> | |
| 8082 </capabilities> | |
| 8083 <parameters> | |
| 8084 <param id="klass"> | |
| 8085 <jclass method="method"/> | |
| 8086 <description> | |
| 8087 The class to query. | |
| 8088 </description> | |
| 8089 </param> | |
| 8090 <param id="method"> | |
| 8091 <jmethodID class="klass" native="error"/> | |
| 8092 <description> | |
| 8093 The method to query. | |
| 8094 </description> | |
| 8095 </param> | |
| 8096 <param id="start_location_ptr"> | |
| 8097 <outptr><jlocation/></outptr> | |
| 8098 <description> | |
| 8099 On return, points to the first location, or | |
| 8100 <code>-1</code> if location information is not available. | |
| 8101 If the information is available and | |
| 8102 <functionlink id="GetJLocationFormat"></functionlink> | |
| 8103 returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink> | |
| 8104 then this will always be zero. | |
| 8105 </description> | |
| 8106 </param> | |
| 8107 <param id="end_location_ptr"> | |
| 8108 <outptr><jlocation/></outptr> | |
| 8109 <description> | |
| 8110 On return, points to the last location, | |
| 8111 or <code>-1</code> if location information is not available. | |
| 8112 </description> | |
| 8113 </param> | |
| 8114 </parameters> | |
| 8115 <errors> | |
| 8116 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 8117 Class information does not include method sizes. | |
| 8118 </error> | |
| 8119 </errors> | |
| 8120 </function> | |
| 8121 | |
| 8122 <function id="GetLocalVariableTable" num="72"> | |
| 8123 <synopsis>Get Local Variable Table</synopsis> | |
| 8124 <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry"> | |
| 8125 <field id="start_location"> | |
| 8126 <jlocation/> | |
| 8127 <description> | |
| 8128 The code array index where the local variable is first valid | |
| 8129 (that is, where it must have a value). | |
| 8130 </description> | |
| 8131 </field> | |
| 8132 <field id="length"> | |
| 8133 <jint/> | |
| 8134 <description> | |
| 8135 The length of the valid section for this local variable. | |
| 8136 The last code array index where the local variable is valid | |
| 8137 is <code>start_location + length</code>. | |
| 8138 </description> | |
| 8139 </field> | |
| 8140 <field id="name"> | |
| 8141 <allocfieldbuf><char/></allocfieldbuf> | |
| 8142 <description> | |
| 8143 The local variable name, encoded as a | |
| 8144 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8145 </description> | |
| 8146 </field> | |
| 8147 <field id="signature"> | |
| 8148 <allocfieldbuf><char/></allocfieldbuf> | |
| 8149 <description> | |
| 8150 The local variable's type signature, encoded as a | |
| 8151 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8152 The signature format is the same as that defined in | |
| 8153 <vmspeclink id="ClassFile.doc.html#14152" | |
| 8154 name="Field Descriptors section"/> | |
| 8155 </description> | |
| 8156 </field> | |
| 8157 <field id="generic_signature"> | |
| 8158 <allocfieldbuf><char/></allocfieldbuf> | |
| 8159 <description> | |
| 8160 The local variable's generic signature, encoded as a | |
| 8161 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8162 The value of this field will be <code>NULL</code> for any local | |
| 8163 variable which does not have a generic type. | |
| 8164 </description> | |
| 8165 </field> | |
| 8166 <field id="slot"> | |
| 8167 <jint/> | |
| 8168 <description> | |
| 8169 The local variable's slot. See <internallink id="local">Local Variables</internallink>. | |
| 8170 </description> | |
| 8171 </field> | |
| 8172 </typedef> | |
| 8173 <description> | |
| 8174 Return local variable information. | |
| 8175 </description> | |
| 8176 <origin>jvmdiClone</origin> | |
| 8177 <capabilities> | |
| 8178 <required id="can_access_local_variables"></required> | |
| 8179 </capabilities> | |
| 8180 <parameters> | |
| 8181 <param id="method"> | |
| 8182 <jmethodID native="error"/> | |
| 8183 <description> | |
| 8184 The method to query. | |
| 8185 </description> | |
| 8186 </param> | |
| 8187 <param id="entry_count_ptr"> | |
| 8188 <outptr><jint/></outptr> | |
| 8189 <description> | |
| 8190 On return, points to the number of entries in the table | |
| 8191 </description> | |
| 8192 </param> | |
| 8193 <param id="table_ptr"> | |
| 8194 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf> | |
| 8195 <description> | |
| 8196 On return, points to an array of local variable table entries. | |
| 8197 </description> | |
| 8198 </param> | |
| 8199 </parameters> | |
| 8200 <errors> | |
| 8201 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 8202 Class information does not include local variable | |
| 8203 information. | |
| 8204 </error> | |
| 8205 </errors> | |
| 8206 </function> | |
| 8207 | |
| 8208 <function id="GetBytecodes" phase="start" num="75"> | |
| 8209 <synopsis>Get Bytecodes</synopsis> | |
| 8210 <description> | |
| 8211 For the method indicated by <code>method</code>, | |
| 8212 return the byte codes that implement the method. The number of | |
| 8213 bytecodes is returned via <code>bytecode_count_ptr</code>. The byte codes | |
| 8214 themselves are returned via <code>bytecodes_ptr</code>. | |
| 8215 </description> | |
| 8216 <origin>jvmdi</origin> | |
| 8217 <capabilities> | |
| 8218 <required id="can_get_bytecodes"></required> | |
| 8219 </capabilities> | |
| 8220 <parameters> | |
| 8221 <param id="klass"> | |
| 8222 <jclass method="method"/> | |
| 8223 <description> | |
| 8224 The class to query. | |
| 8225 </description> | |
| 8226 </param> | |
| 8227 <param id="method"> | |
| 8228 <jmethodID class="klass" native="error"/> | |
| 8229 <description> | |
| 8230 The method to query. | |
| 8231 </description> | |
| 8232 </param> | |
| 8233 <param id="bytecode_count_ptr"> | |
| 8234 <outptr><jint/></outptr> | |
| 8235 <description> | |
| 8236 On return, points to the length of the byte code array | |
| 8237 </description> | |
| 8238 </param> | |
| 8239 <param id="bytecodes_ptr"> | |
| 8240 <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf> | |
| 8241 <description> | |
| 8242 On return, points to the pointer to the byte code array | |
| 8243 </description> | |
| 8244 </param> | |
| 8245 </parameters> | |
| 8246 <errors> | |
| 8247 </errors> | |
| 8248 </function> | |
| 8249 | |
| 8250 <function id="IsMethodNative" phase="start" num="76"> | |
| 8251 <synopsis>Is Method Native</synopsis> | |
| 8252 <description> | |
| 8253 For the method indicated by <code>method</code>, return a | |
| 8254 value indicating whether the method is native via <code>is_native_ptr</code> | |
| 8255 </description> | |
| 8256 <origin>jvmdi</origin> | |
| 8257 <capabilities> | |
| 8258 </capabilities> | |
| 8259 <parameters> | |
| 8260 <param id="klass"> | |
| 8261 <jclass method="method"/> | |
| 8262 <description> | |
| 8263 The class to query. | |
| 8264 </description> | |
| 8265 </param> | |
| 8266 <param id="method"> | |
| 8267 <jmethodID class="klass"/> | |
| 8268 <description> | |
| 8269 The method to query. | |
| 8270 </description> | |
| 8271 </param> | |
| 8272 <param id="is_native_ptr"> | |
| 8273 <outptr><jboolean/></outptr> | |
| 8274 <description> | |
| 8275 On return, points to the boolean result of this function. | |
| 8276 </description> | |
| 8277 </param> | |
| 8278 </parameters> | |
| 8279 <errors> | |
| 8280 </errors> | |
| 8281 </function> | |
| 8282 | |
| 8283 <function id="IsMethodSynthetic" phase="start" num="77"> | |
| 8284 <synopsis>Is Method Synthetic</synopsis> | |
| 8285 <description> | |
| 8286 For the method indicated by <code>method</code>, return a | |
| 8287 value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>. | |
| 8288 Synthetic methods are generated by the compiler but not present in the | |
| 8289 original source code. | |
| 8290 </description> | |
| 8291 <origin>jvmdi</origin> | |
| 8292 <capabilities> | |
| 8293 <required id="can_get_synthetic_attribute"></required> | |
| 8294 </capabilities> | |
| 8295 <parameters> | |
| 8296 <param id="klass"> | |
| 8297 <jclass method="method"/> | |
| 8298 <description> | |
| 8299 The class to query. | |
| 8300 </description> | |
| 8301 </param> | |
| 8302 <param id="method"> | |
| 8303 <jmethodID class="klass"/> | |
| 8304 <description> | |
| 8305 The method to query. | |
| 8306 </description> | |
| 8307 </param> | |
| 8308 <param id="is_synthetic_ptr"> | |
| 8309 <outptr><jboolean/></outptr> | |
| 8310 <description> | |
| 8311 On return, points to the boolean result of this function. | |
| 8312 </description> | |
| 8313 </param> | |
| 8314 </parameters> | |
| 8315 <errors> | |
| 8316 </errors> | |
| 8317 </function> | |
| 8318 | |
| 8319 <function id="IsMethodObsolete" phase="start" num="91"> | |
| 8320 <synopsis>Is Method Obsolete</synopsis> | |
| 8321 <description> | |
| 8322 Determine if a method ID refers to an | |
| 8323 <internallink id="obsoleteMethods">obsolete</internallink> | |
| 8324 method version. | |
| 8325 </description> | |
| 8326 <origin>jvmdi</origin> | |
| 8327 <capabilities> | |
| 8328 </capabilities> | |
| 8329 <parameters> | |
| 8330 <param id="klass"> | |
| 8331 <jclass method="method"/> | |
| 8332 <description> | |
| 8333 The class to query. | |
| 8334 </description> | |
| 8335 </param> | |
| 8336 <param id="method"> | |
| 8337 <jmethodID class="klass"/> | |
| 8338 <description> | |
| 8339 The method ID to query. | |
| 8340 </description> | |
| 8341 </param> | |
| 8342 <param id="is_obsolete_ptr"> | |
| 8343 <outptr><jboolean/></outptr> | |
| 8344 <description> | |
| 8345 On return, points to the boolean result of this function. | |
| 8346 </description> | |
| 8347 </param> | |
| 8348 </parameters> | |
| 8349 <errors> | |
| 8350 </errors> | |
| 8351 </function> | |
| 8352 | |
| 8353 <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1"> | |
| 8354 <synopsis>Set Native Method Prefix</synopsis> | |
| 8355 <description> | |
| 8356 This function modifies the failure handling of | |
| 8357 native method resolution by allowing retry | |
| 8358 with a prefix applied to the name. | |
| 8359 When used with the | |
| 8360 <eventlink id="ClassFileLoadHook">ClassFileLoadHook | |
| 8361 event</eventlink>, it enables native methods to be | |
| 8362 <internallink id="bci">instrumented</internallink>. | |
| 8363 <p/> | |
| 8364 Since native methods cannot be directly instrumented | |
| 8365 (they have no bytecodes), they must be wrapped with | |
| 8366 a non-native method which can be instrumented. | |
| 8367 For example, if we had: | |
| 8368 <example> | |
| 8369 native boolean foo(int x);</example> | |
| 8370 <p/> | |
| 8371 We could transform the class file (with the | |
| 8372 ClassFileLoadHook event) so that this becomes: | |
| 8373 <example> | |
| 8374 boolean foo(int x) { | |
| 8375 <i>... record entry to foo ...</i> | |
| 8376 return wrapped_foo(x); | |
| 8377 } | |
| 8378 | |
| 8379 native boolean wrapped_foo(int x);</example> | |
| 8380 <p/> | |
| 8381 Where foo becomes a wrapper for the actual native method | |
| 8382 with the appended prefix "wrapped_". Note that | |
| 8383 "wrapped_" would be a poor choice of prefix since it | |
| 8384 might conceivably form the name of an existing method | |
| 8385 thus something like "$$$MyAgentWrapped$$$_" would be | |
| 8386 better but would make these examples less readable. | |
| 8387 <p/> | |
| 8388 The wrapper will allow data to be collected on the native | |
| 8389 method call, but now the problem becomes linking up the | |
| 8390 wrapped method with the native implementation. | |
| 8391 That is, the method <code>wrapped_foo</code> needs to be | |
| 8392 resolved to the native implementation of <code>foo</code>, | |
| 8393 which might be: | |
| 8394 <example> | |
| 8395 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example> | |
| 8396 <p/> | |
| 8397 This function allows the prefix to be specified and the | |
| 8398 proper resolution to occur. | |
| 8399 Specifically, when the standard resolution fails, the | |
| 8400 resolution is retried taking the prefix into consideration. | |
| 8401 There are two ways that resolution occurs, explicit | |
| 8402 resolution with the JNI function <code>RegisterNatives</code> | |
| 8403 and the normal automatic resolution. For | |
| 8404 <code>RegisterNatives</code>, the VM will attempt this | |
| 8405 association: | |
| 8406 <example> | |
| 8407 method(foo) -> nativeImplementation(foo)</example> | |
| 8408 <p/> | |
| 8409 When this fails, the resolution will be retried with | |
| 8410 the specified prefix prepended to the method name, | |
| 8411 yielding the correct resolution: | |
| 8412 <example> | |
| 8413 method(wrapped_foo) -> nativeImplementation(foo)</example> | |
| 8414 <p/> | |
| 8415 For automatic resolution, the VM will attempt: | |
| 8416 <example> | |
| 8417 method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example> | |
| 8418 <p/> | |
| 8419 When this fails, the resolution will be retried with | |
| 8420 the specified prefix deleted from the implementation name, | |
| 8421 yielding the correct resolution: | |
| 8422 <example> | |
| 8423 method(wrapped_foo) -> nativeImplementation(foo)</example> | |
| 8424 <p/> | |
| 8425 Note that since the prefix is only used when standard | |
| 8426 resolution fails, native methods can be wrapped selectively. | |
| 8427 <p/> | |
| 8428 Since each <jvmti/> environment is independent and | |
| 8429 can do its own transformation of the bytecodes, more | |
| 8430 than one layer of wrappers may be applied. Thus each | |
| 8431 environment needs its own prefix. Since transformations | |
| 8432 are applied in order, the prefixes, if applied, will | |
| 8433 be applied in the same order. | |
| 8434 The order of transformation application is described in | |
| 8435 the <eventlink id="ClassFileLoadHook"/> event. | |
| 8436 Thus if three environments applied | |
| 8437 wrappers, <code>foo</code> might become | |
| 8438 <code>$env3_$env2_$env1_foo</code>. But if, say, | |
| 8439 the second environment did not apply a wrapper to | |
| 8440 <code>foo</code> it would be just | |
| 8441 <code>$env3_$env1_foo</code>. To be able to | |
| 8442 efficiently determine the sequence of prefixes, | |
| 8443 an intermediate prefix is only applied if its non-native | |
| 8444 wrapper exists. Thus, in the last example, even though | |
| 8445 <code>$env1_foo</code> is not a native method, the | |
| 8446 <code>$env1_</code> prefix is applied since | |
| 8447 <code>$env1_foo</code> exists. | |
| 8448 <p/> | |
| 8449 Since the prefixes are used at resolution time | |
| 8450 and since resolution may be arbitrarily delayed, a | |
| 8451 native method prefix must remain set as long as there | |
| 8452 are corresponding prefixed native methods. | |
| 8453 </description> | |
| 8454 <origin>new</origin> | |
| 8455 <capabilities> | |
| 8456 <required id="can_set_native_method_prefix"></required> | |
| 8457 </capabilities> | |
| 8458 <parameters> | |
| 8459 <param id="prefix"> | |
| 8460 <inbuf> | |
| 8461 <char/> | |
| 8462 <nullok> | |
| 8463 any existing prefix in this environment is cancelled | |
| 8464 </nullok> | |
| 8465 </inbuf> | |
| 8466 <description> | |
| 8467 The prefix to apply, encoded as a | |
| 8468 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8469 </description> | |
| 8470 </param> | |
| 8471 </parameters> | |
| 8472 <errors> | |
| 8473 </errors> | |
| 8474 </function> | |
| 8475 | |
| 8476 <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1"> | |
| 8477 <synopsis>Set Native Method Prefixes</synopsis> | |
| 8478 <description> | |
| 8479 For a normal agent, <functionlink id="SetNativeMethodPrefix"/> | |
| 8480 will provide all needed native method prefixing. | |
| 8481 For a meta-agent that performs multiple independent class | |
| 8482 file transformations (for example as a proxy for another | |
| 8483 layer of agents) this function allows each transformation | |
| 8484 to have its own prefix. | |
| 8485 The prefixes are applied in the order supplied and are | |
| 8486 processed in the same manor as described for the | |
| 8487 application of prefixes from multiple <jvmti/> environments | |
| 8488 in <functionlink id="SetNativeMethodPrefix"/>. | |
| 8489 <p/> | |
| 8490 Any previous prefixes are replaced. Thus, calling this | |
| 8491 function with a <paramlink id="prefix_count"/> of <code>0</code> | |
| 8492 disables prefixing in this environment. | |
| 8493 <p/> | |
| 8494 <functionlink id="SetNativeMethodPrefix"/> and this function | |
| 8495 are the two ways to set the prefixes. | |
| 8496 Calling <code>SetNativeMethodPrefix</code> with | |
| 8497 a prefix is the same as calling this function with | |
| 8498 <paramlink id="prefix_count"/> of <code>1</code>. | |
| 8499 Calling <code>SetNativeMethodPrefix</code> with | |
| 8500 <code>NULL</code> is the same as calling this function with | |
| 8501 <paramlink id="prefix_count"/> of <code>0</code>. | |
| 8502 </description> | |
| 8503 <origin>new</origin> | |
| 8504 <capabilities> | |
| 8505 <required id="can_set_native_method_prefix"></required> | |
| 8506 </capabilities> | |
| 8507 <parameters> | |
| 8508 <param id="prefix_count"> | |
| 8509 <jint min="0"/> | |
| 8510 <description> | |
| 8511 The number of prefixes to apply. | |
| 8512 </description> | |
| 8513 </param> | |
| 8514 <param id="prefixes"> | |
| 8515 <agentbuf> | |
| 8516 <char/> | |
| 8517 </agentbuf> | |
| 8518 <description> | |
| 8519 The prefixes to apply for this environment, each encoded as a | |
| 8520 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8521 </description> | |
| 8522 </param> | |
| 8523 </parameters> | |
| 8524 <errors> | |
| 8525 </errors> | |
| 8526 </function> | |
| 8527 | |
| 8528 </category> | |
| 8529 | |
| 8530 <category id="RawMonitors" label="Raw Monitor"> | |
| 8531 | |
| 8532 <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31"> | |
| 8533 <synopsis>Create Raw Monitor</synopsis> | |
| 8534 <description> | |
| 8535 Create a raw monitor. | |
| 8536 </description> | |
| 8537 <origin>jvmdi</origin> | |
| 8538 <capabilities> | |
| 8539 </capabilities> | |
| 8540 <parameters> | |
| 8541 <param id="name"> | |
| 8542 <inbuf><char/></inbuf> | |
| 8543 <description> | |
| 8544 A name to identify the monitor, encoded as a | |
| 8545 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8546 </description> | |
| 8547 </param> | |
| 8548 <param id="monitor_ptr"> | |
| 8549 <outptr><jrawMonitorID/></outptr> | |
| 8550 <description> | |
| 8551 On return, points to the created monitor. | |
| 8552 </description> | |
| 8553 </param> | |
| 8554 </parameters> | |
| 8555 <errors> | |
| 8556 </errors> | |
| 8557 </function> | |
| 8558 | |
| 8559 <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32"> | |
| 8560 <synopsis>Destroy Raw Monitor</synopsis> | |
| 8561 <description> | |
| 8562 Destroy the raw monitor. | |
| 8563 If the monitor being destroyed has been entered by this thread, it will be | |
| 8564 exited before it is destroyed. | |
| 8565 If the monitor being destroyed has been entered by another thread, | |
| 8566 an error will be returned and the monitor will not be destroyed. | |
| 8567 </description> | |
| 8568 <origin>jvmdi</origin> | |
| 8569 <capabilities> | |
| 8570 </capabilities> | |
| 8571 <parameters> | |
| 8572 <param id="monitor"> | |
| 8573 <jrawMonitorID/> | |
| 8574 <description> | |
| 8575 The monitor | |
| 8576 </description> | |
| 8577 </param> | |
| 8578 </parameters> | |
| 8579 <errors> | |
| 8580 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8581 Not monitor owner | |
| 8582 </error> | |
| 8583 </errors> | |
| 8584 </function> | |
| 8585 | |
| 8586 <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33"> | |
| 8587 <synopsis>Raw Monitor Enter</synopsis> | |
| 8588 <description> | |
| 8589 Gain exclusive ownership of a raw monitor. | |
| 8590 The same thread may enter a monitor more then once. | |
| 8591 The thread must | |
| 8592 <functionlink id="RawMonitorExit">exit</functionlink> | |
| 8593 the monitor the same number of times as it is entered. | |
| 8594 If a monitor is entered during <code>OnLoad</code> (before attached threads exist) | |
| 8595 and has not exited when attached threads come into existence, the enter | |
| 8596 is considered to have occurred on the main thread. | |
| 8597 </description> | |
| 8598 <origin>jvmdi</origin> | |
| 8599 <capabilities> | |
| 8600 </capabilities> | |
| 8601 <parameters> | |
| 8602 <param id="monitor"> | |
| 8603 <jrawMonitorID/> | |
| 8604 <description> | |
| 8605 The monitor | |
| 8606 </description> | |
| 8607 </param> | |
| 8608 </parameters> | |
| 8609 <errors> | |
| 8610 </errors> | |
| 8611 </function> | |
| 8612 | |
| 8613 <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34"> | |
| 8614 <synopsis>Raw Monitor Exit</synopsis> | |
| 8615 <description> | |
| 8616 Release exclusive ownership of a raw monitor. | |
| 8617 </description> | |
| 8618 <origin>jvmdi</origin> | |
| 8619 <capabilities> | |
| 8620 </capabilities> | |
| 8621 <parameters> | |
| 8622 <param id="monitor"> | |
| 8623 <jrawMonitorID/> | |
| 8624 <description> | |
| 8625 The monitor | |
| 8626 </description> | |
| 8627 </param> | |
| 8628 </parameters> | |
| 8629 <errors> | |
| 8630 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8631 Not monitor owner | |
| 8632 </error> | |
| 8633 </errors> | |
| 8634 </function> | |
| 8635 | |
| 8636 <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35"> | |
| 8637 <synopsis>Raw Monitor Wait</synopsis> | |
| 8638 <description> | |
| 8639 Wait for notification of the raw monitor. | |
| 8640 <p/> | |
| 8641 Causes the current thread to wait until either another thread calls | |
| 8642 <functionlink id="RawMonitorNotify"/> or | |
| 8643 <functionlink id="RawMonitorNotifyAll"/> | |
| 8644 for the specified raw monitor, or the specified | |
| 8645 <paramlink id="millis">timeout</paramlink> | |
| 8646 has elapsed. | |
| 8647 </description> | |
| 8648 <origin>jvmdi</origin> | |
| 8649 <capabilities> | |
| 8650 </capabilities> | |
| 8651 <parameters> | |
| 8652 <param id="monitor"> | |
| 8653 <jrawMonitorID/> | |
| 8654 <description> | |
| 8655 The monitor | |
| 8656 </description> | |
| 8657 </param> | |
| 8658 <param id="millis"> | |
| 8659 <jlong/> | |
| 8660 <description> | |
| 8661 The timeout, in milliseconds. If the timeout is | |
| 8662 zero, then real time is not taken into consideration | |
| 8663 and the thread simply waits until notified. | |
| 8664 </description> | |
| 8665 </param> | |
| 8666 </parameters> | |
| 8667 <errors> | |
| 8668 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8669 Not monitor owner | |
| 8670 </error> | |
| 8671 <error id="JVMTI_ERROR_INTERRUPT"> | |
| 8672 Wait was interrupted, try again | |
| 8673 </error> | |
| 8674 </errors> | |
| 8675 </function> | |
| 8676 | |
| 8677 <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36"> | |
| 8678 <synopsis>Raw Monitor Notify</synopsis> | |
| 8679 <description> | |
| 8680 Notify a single thread waiting on the raw monitor. | |
| 8681 </description> | |
| 8682 <origin>jvmdi</origin> | |
| 8683 <capabilities> | |
| 8684 </capabilities> | |
| 8685 <parameters> | |
| 8686 <param id="monitor"> | |
| 8687 <jrawMonitorID/> | |
| 8688 <description> | |
| 8689 The monitor | |
| 8690 </description> | |
| 8691 </param> | |
| 8692 </parameters> | |
| 8693 <errors> | |
| 8694 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8695 Not monitor owner | |
| 8696 </error> | |
| 8697 </errors> | |
| 8698 </function> | |
| 8699 | |
| 8700 <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37"> | |
| 8701 <synopsis>Raw Monitor Notify All</synopsis> | |
| 8702 <description> | |
| 8703 Notify all threads waiting on the raw monitor. | |
| 8704 </description> | |
| 8705 <origin>jvmdi</origin> | |
| 8706 <capabilities> | |
| 8707 </capabilities> | |
| 8708 <parameters> | |
| 8709 <param id="monitor"> | |
| 8710 <jrawMonitorID/> | |
| 8711 <description> | |
| 8712 The monitor | |
| 8713 </description> | |
| 8714 </param> | |
| 8715 </parameters> | |
| 8716 <errors> | |
| 8717 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8718 Not monitor owner | |
| 8719 </error> | |
| 8720 </errors> | |
| 8721 </function> | |
| 8722 | |
| 8723 <elide> | |
| 8724 <function id="GetRawMonitorUse" num="118"> | |
| 8725 <synopsis>Get Raw Monitor Use</synopsis> | |
| 8726 <description> | |
| 8727 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure | |
| 8728 are filled in with information about usage of the raw monitor. | |
| 8729 </description> | |
| 8730 <origin>new</origin> | |
| 8731 <capabilities> | |
| 8732 <required id="can_get_raw_monitor_usage"></required> | |
| 8733 </capabilities> | |
| 8734 <parameters> | |
| 8735 <param id="monitor"> | |
| 8736 <jrawMonitorID/> | |
| 8737 <description> | |
| 8738 the raw monitor to query. | |
| 8739 </description> | |
| 8740 </param> | |
| 8741 <param id="info_ptr"> | |
| 8742 <outptr><struct>jvmtiMonitorUsage</struct></outptr> | |
| 8743 <description> | |
| 8744 On return, filled with monitor information for the | |
| 8745 specified raw monitor. | |
| 8746 </description> | |
| 8747 </param> | |
| 8748 </parameters> | |
| 8749 <errors> | |
| 8750 </errors> | |
| 8751 </function> | |
| 8752 | |
| 8753 <function id="GetRawMonitors" num="119"> | |
| 8754 <synopsis>Get Raw Monitors</synopsis> | |
| 8755 <description> | |
| 8756 Return the list of raw monitors. | |
| 8757 <p/> | |
| 8758 Note: details about each monitor can be examined with | |
| 8759 <functionlink id="GetRawMonitorUse"></functionlink>. | |
| 8760 </description> | |
| 8761 <origin>new</origin> | |
| 8762 <capabilities> | |
| 8763 <required id="can_get_raw_monitor_usage"></required> | |
| 8764 </capabilities> | |
| 8765 <parameters> | |
| 8766 <param id="monitorCnt"> | |
| 8767 <outptr><jint/></outptr> | |
| 8768 <description> | |
| 8769 On return, pointer to the number | |
| 8770 of monitors returned in <code>monitors_ptr</code>. | |
| 8771 </description> | |
| 8772 </param> | |
| 8773 <param id="monitors_ptr"> | |
| 8774 <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf> | |
| 8775 <description> | |
| 8776 On return, pointer to the monitor list. | |
| 8777 </description> | |
| 8778 </param> | |
| 8779 </parameters> | |
| 8780 <errors> | |
| 8781 </errors> | |
| 8782 </function> | |
| 8783 </elide> | |
| 8784 </category> | |
| 8785 | |
| 8786 <category id="jniIntercept" label="JNI Function Interception"> | |
| 8787 | |
| 8788 <intro> | |
| 8789 Provides the ability to intercept and resend | |
| 8790 Java Native Interface (JNI) function calls | |
| 8791 by manipulating the JNI function table. | |
| 8792 See <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html">JNI | |
| 8793 Functions</externallink> in the <i>Java Native Interface Specification</i>. | |
| 8794 <p/> | |
| 8795 The following example illustrates intercepting the | |
| 8796 <code>NewGlobalRef</code> JNI call in order to count reference | |
| 8797 creation. | |
| 8798 <example> | |
| 8799 JNIEnv original_jni_Functions; | |
| 8800 JNIEnv redirected_jni_Functions; | |
| 8801 int my_global_ref_count = 0; | |
| 8802 | |
| 8803 jobject | |
| 8804 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) { | |
| 8805 ++my_global_ref_count; | |
| 8806 return originalJNIFunctions->NewGlobalRef(env, lobj); | |
| 8807 } | |
| 8808 | |
| 8809 void | |
| 8810 myInit() { | |
| 8811 jvmtiError err; | |
| 8812 | |
| 8813 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &original_jni_Functions); | |
| 8814 if (err != JVMTI_ERROR_NONE) { | |
| 8815 die(); | |
| 8816 } | |
| 8817 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &redirected_jni_Functions); | |
| 8818 if (err != JVMTI_ERROR_NONE) { | |
| 8819 die(); | |
| 8820 } | |
| 8821 redirectedJNIFunctions->NewGlobalRef = MyNewGlobalRef; | |
| 8822 err = (*jvmti_env)->SetJNIFunctionTable(jvmti_env, redirected_jni_Functions); | |
| 8823 if (err != JVMTI_ERROR_NONE) { | |
| 8824 die(); | |
| 8825 } | |
| 8826 } | |
| 8827 </example> | |
| 8828 Sometime after <code>myInit</code> is called the user's JNI | |
| 8829 code is executed which makes the call to create a new global | |
| 8830 reference. Instead of going to the normal JNI implementation | |
| 8831 the call goes to <code>myNewGlobalRef</code>. Note that a | |
| 8832 copy of the original function table is kept so that the normal | |
| 8833 JNI function can be called after the data is collected. | |
| 8834 Note also that any JNI functions which are not overwritten | |
| 8835 will behave normally. | |
| 8836 <todo> | |
| 8837 check that the example compiles and executes. | |
| 8838 </todo> | |
| 8839 </intro> | |
| 8840 | |
| 8841 <function id="SetJNIFunctionTable" phase="start" num="120"> | |
| 8842 <synopsis>Set JNI Function Table</synopsis> | |
| 8843 <description> | |
| 8844 Set the JNI function table | |
| 8845 in all current and future JNI environments. | |
| 8846 As a result, all future JNI calls are directed to the specified functions. | |
| 8847 Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the | |
| 8848 function table to pass to this function. | |
| 8849 For this function to take effect the the updated table entries must be | |
| 8850 used by the JNI clients. | |
| 8851 Since the table is defined <code>const</code> some compilers may optimize | |
| 8852 away the access to the table, thus preventing this function from taking | |
| 8853 effect. | |
| 8854 The table is copied--changes to the local copy of the | |
| 8855 table have no effect. | |
| 8856 This function affects only the function table, all other aspects of the environment are | |
| 8857 unaffected. | |
| 8858 See the examples <internallink id="jniIntercept">above</internallink>. | |
| 8859 </description> | |
| 8860 <origin>new</origin> | |
| 8861 <capabilities> | |
| 8862 </capabilities> | |
| 8863 <parameters> | |
| 8864 <param id="function_table"> | |
| 8865 <inptr> | |
| 8866 <struct>jniNativeInterface</struct> | |
| 8867 </inptr> | |
| 8868 <description> | |
| 8869 Points to the new JNI function table. | |
| 8870 </description> | |
| 8871 </param> | |
| 8872 </parameters> | |
| 8873 <errors> | |
| 8874 </errors> | |
| 8875 </function> | |
| 8876 | |
| 8877 <function id="GetJNIFunctionTable" phase="start" num="121"> | |
| 8878 <synopsis>Get JNI Function Table</synopsis> | |
| 8879 <description> | |
| 8880 Get the JNI function table. | |
| 8881 The JNI function table is copied into allocated memory. | |
| 8882 If <functionlink id="SetJNIFunctionTable"></functionlink> | |
| 8883 has been called, the modified (not the original) function | |
| 8884 table is returned. | |
| 8885 Only the function table is copied, no other aspects of the environment | |
| 8886 are copied. | |
| 8887 See the examples <internallink id="jniIntercept">above</internallink>. | |
| 8888 </description> | |
| 8889 <origin>new</origin> | |
| 8890 <capabilities> | |
| 8891 </capabilities> | |
| 8892 <parameters> | |
| 8893 <param id="function_table"> | |
| 8894 <allocbuf> | |
| 8895 <struct>jniNativeInterface</struct> | |
| 8896 </allocbuf> | |
| 8897 <description> | |
| 8898 On return, <code>*function_table</code> | |
| 8899 points a newly allocated copy of the JNI function table. | |
| 8900 </description> | |
| 8901 </param> | |
| 8902 </parameters> | |
| 8903 <errors> | |
| 8904 </errors> | |
| 8905 </function> | |
| 8906 | |
| 8907 </category> | |
| 8908 | |
| 8909 <category id="eventManagement" label="Event Management"> | |
| 8910 | |
| 8911 <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122"> | |
| 8912 <synopsis>Set Event Callbacks</synopsis> | |
| 8913 <description> | |
| 8914 Set the functions to be called for each event. | |
| 8915 The callbacks are specified by supplying a replacement function table. | |
| 8916 The function table is copied--changes to the local copy of the | |
| 8917 table have no effect. | |
| 8918 This is an atomic action, all callbacks are set at once. | |
| 8919 No events are sent before this function is called. | |
| 8920 When an entry is <code>NULL</code> or when the event is beyond | |
| 8921 <paramlink id="size_of_callbacks"></paramlink> no event is sent. | |
| 8922 Details on events are | |
| 8923 described <internallink id="EventSection">later</internallink> in this document. | |
| 8924 An event must be enabled and have a callback in order to be | |
| 8925 sent--the order in which this function and | |
| 8926 <functionlink id="SetEventNotificationMode"></functionlink> | |
| 8927 are called does not affect the result. | |
| 8928 </description> | |
| 8929 <origin>new</origin> | |
| 8930 <capabilities> | |
| 8931 </capabilities> | |
| 8932 <parameters> | |
| 8933 <param id="callbacks"> | |
| 8934 <inptr> | |
| 8935 <struct>jvmtiEventCallbacks</struct> | |
| 8936 <nullok>remove the existing callbacks</nullok> | |
| 8937 </inptr> | |
| 8938 <description> | |
| 8939 The new event callbacks. | |
| 8940 </description> | |
| 8941 </param> | |
| 8942 <param id="size_of_callbacks"> | |
| 8943 <jint min="0"/> | |
| 8944 <description> | |
| 8945 <code>sizeof(jvmtiEventCallbacks)</code>--for version | |
| 8946 compatibility. | |
| 8947 </description> | |
| 8948 </param> | |
| 8949 </parameters> | |
| 8950 <errors> | |
| 8951 </errors> | |
| 8952 </function> | |
| 8953 | |
| 8954 <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2"> | |
| 8955 <synopsis>Set Event Notification Mode</synopsis> | |
| 8956 <description> | |
| 8957 Control the generation of events. | |
| 8958 <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum"> | |
| 8959 <constant id="JVMTI_ENABLE" num="1"> | |
| 8960 If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>, | |
| 8961 the event <paramlink id="event_type"></paramlink> will be enabled | |
| 8962 </constant> | |
| 8963 <constant id="JVMTI_DISABLE" num="0"> | |
| 8964 If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>, | |
| 8965 the event <paramlink id="event_type"></paramlink> will be disabled | |
| 8966 </constant> | |
| 8967 </constants> | |
| 8968 If <code>thread</code> is <code>NULL</code>, | |
| 8969 the event is enabled or disabled globally; otherwise, it is | |
| 8970 enabled or disabled for a particular thread. | |
| 8971 An event is generated for | |
| 8972 a particular thread if it is enabled either at the thread or global | |
| 8973 levels. | |
| 8974 <p/> | |
| 8975 See <internallink id="EventIndex">below</internallink> for information on specific events. | |
| 8976 <p/> | |
| 8977 The following events cannot be controlled at the thread | |
| 8978 level through this function. | |
| 8979 <ul> | |
| 8980 <li><eventlink id="VMInit"></eventlink></li> | |
| 8981 <li><eventlink id="VMStart"></eventlink></li> | |
| 8982 <li><eventlink id="VMDeath"></eventlink></li> | |
| 8983 <li><eventlink id="ThreadStart"></eventlink></li> | |
| 8984 <li><eventlink id="CompiledMethodLoad"></eventlink></li> | |
| 8985 <li><eventlink id="CompiledMethodUnload"></eventlink></li> | |
| 8986 <li><eventlink id="DynamicCodeGenerated"></eventlink></li> | |
| 8987 <li><eventlink id="DataDumpRequest"></eventlink></li> | |
| 8988 </ul> | |
| 8989 <p/> | |
| 8990 Initially, no events are enabled at either the thread level | |
| 8991 or the global level. | |
| 8992 <p/> | |
| 8993 Any needed capabilities (see Event Enabling Capabilities below) must be possessed | |
| 8994 before calling this function. | |
| 8995 <p/> | |
| 8996 Details on events are | |
| 8997 described <internallink id="EventSection">below</internallink>. | |
| 8998 </description> | |
| 8999 <origin>jvmdiClone</origin> | |
| 9000 <eventcapabilities></eventcapabilities> | |
| 9001 <parameters> | |
| 9002 <param id="mode"> | |
| 9003 <enum>jvmtiEventMode</enum> | |
| 9004 <description> | |
| 9005 <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code> | |
| 9006 </description> | |
| 9007 </param> | |
| 9008 <param id="event_type"> | |
| 9009 <enum>jvmtiEvent</enum> | |
| 9010 <description> | |
| 9011 the event to control | |
| 9012 </description> | |
| 9013 </param> | |
| 9014 <param id="event_thread"> | |
| 9015 <ptrtype> | |
| 9016 <jthread impl="noconvert"/> | |
| 9017 <nullok>event is controlled at the global level</nullok> | |
| 9018 </ptrtype> | |
| 9019 <description> | |
| 9020 The thread to control | |
| 9021 </description> | |
| 9022 </param> | |
| 9023 <param id="..."> | |
| 9024 <varargs/> | |
| 9025 <description> | |
| 9026 for future expansion | |
| 9027 </description> | |
| 9028 </param> | |
| 9029 </parameters> | |
| 9030 <errors> | |
| 9031 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
| 9032 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread. | |
| 9033 </error> | |
| 9034 <error id="JVMTI_ERROR_THREAD_NOT_ALIVE"> | |
| 9035 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead). | |
| 9036 </error> | |
| 9037 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 9038 thread level control was attempted on events which do not | |
| 9039 permit thread level control. | |
| 9040 </error> | |
| 9041 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> | |
| 9042 The Required Event Enabling Capability is not possessed. | |
| 9043 </error> | |
| 9044 </errors> | |
| 9045 </function> | |
| 9046 | |
| 9047 <function id="GenerateEvents" num="123"> | |
| 9048 <synopsis>Generate Events</synopsis> | |
| 9049 <description> | |
| 9050 Generate events to represent the current state of the VM. | |
| 9051 For example, if <paramlink id="event_type"/> is | |
| 9052 <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>, | |
| 9053 a <eventlink id="CompiledMethodLoad"></eventlink> event will be | |
| 9054 sent for each currently compiled method. | |
| 9055 Methods that were loaded and now have been unloaded are not sent. | |
| 9056 The history of what events have previously been sent does not | |
| 9057 effect what events are sent by this function--for example, | |
| 9058 all currently compiled methods | |
| 9059 will be sent each time this function is called. | |
| 9060 <p/> | |
| 9061 This function is useful when | |
| 9062 events may have been missed due to the agent attaching after program | |
| 9063 execution begins; this function generates the missed events. | |
| 9064 <p/> | |
| 9065 Attempts to execute Java programming language code or | |
| 9066 JNI functions may be paused until this function returns - | |
| 9067 so neither should be called from the thread sending the event. | |
| 9068 This function returns only after the missed events have been | |
| 9069 sent, processed and have returned. | |
| 9070 The event may be sent on a different thread than the thread | |
| 9071 on which the event occurred. | |
| 9072 The callback for the event must be set with | |
| 9073 <functionlink id="SetEventCallbacks"></functionlink> | |
| 9074 and the event must be enabled with | |
| 9075 <functionlink id="SetEventNotificationMode"></functionlink> | |
| 9076 or the events will not occur. | |
| 9077 If the VM no longer has the information to generate some or | |
| 9078 all of the requested events, the events are simply not sent - | |
| 9079 no error is returned. | |
| 9080 <p/> | |
| 9081 Only the following events are supported: | |
| 9082 <ul> | |
| 9083 <li><eventlink id="CompiledMethodLoad"></eventlink></li> | |
| 9084 <li><eventlink id="DynamicCodeGenerated"></eventlink></li> | |
| 9085 </ul> | |
| 9086 </description> | |
| 9087 <origin>new</origin> | |
| 9088 <capabilities> | |
| 9089 <capability id="can_generate_compiled_method_load_events"></capability> | |
| 9090 </capabilities> | |
| 9091 <parameters> | |
| 9092 <param id="event_type"> | |
| 9093 <enum>jvmtiEvent</enum> | |
| 9094 <description> | |
| 9095 The type of event to generate. Must be one of these: | |
| 9096 <ul> | |
| 9097 <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li> | |
| 9098 <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li> | |
| 9099 </ul> | |
| 9100 </description> | |
| 9101 </param> | |
| 9102 </parameters> | |
| 9103 <errors> | |
| 9104 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> | |
| 9105 <paramlink id="event_type"/> is | |
| 9106 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> | |
| 9107 and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink> | |
| 9108 is <code>false</code>. | |
| 9109 </error> | |
| 9110 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 9111 <paramlink id="event_type"/> is other than | |
| 9112 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> | |
| 9113 or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>. | |
| 9114 </error> | |
| 9115 </errors> | |
| 9116 </function> | |
| 9117 | |
| 9118 </category> | |
| 9119 | |
| 9120 <category id="extension" label="Extension Mechanism"> | |
| 9121 | |
| 9122 <intro> | |
| 9123 These functions | |
| 9124 allow a <jvmti/> implementation to provide functions and events | |
| 9125 beyond those defined in this specification. | |
| 9126 <p/> | |
| 9127 Both extension functions and extension events have parameters | |
| 9128 each of which has a 'type' and 'kind' chosen from the following tables: | |
| 9129 | |
| 9130 <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum"> | |
| 9131 <constant id="JVMTI_TYPE_JBYTE" num="101"> | |
| 9132 Java programming language primitive type - <code>byte</code>. | |
| 9133 JNI type <code>jbyte</code>. | |
| 9134 </constant> | |
| 9135 <constant id="JVMTI_TYPE_JCHAR" num="102"> | |
| 9136 Java programming language primitive type - <code>char</code>. | |
| 9137 JNI type <code>jchar</code>. | |
| 9138 </constant> | |
| 9139 <constant id="JVMTI_TYPE_JSHORT" num="103"> | |
| 9140 Java programming language primitive type - <code>short</code>. | |
| 9141 JNI type <code>jshort</code>. | |
| 9142 </constant> | |
| 9143 <constant id="JVMTI_TYPE_JINT" num="104"> | |
| 9144 Java programming language primitive type - <code>int</code>. | |
| 9145 JNI type <datalink id="jint"></datalink>. | |
| 9146 </constant> | |
| 9147 <constant id="JVMTI_TYPE_JLONG" num="105"> | |
| 9148 Java programming language primitive type - <code>long</code>. | |
| 9149 JNI type <datalink id="jlong"></datalink>. | |
| 9150 </constant> | |
| 9151 <constant id="JVMTI_TYPE_JFLOAT" num="106"> | |
| 9152 Java programming language primitive type - <code>float</code>. | |
| 9153 JNI type <datalink id="jfloat"></datalink>. | |
| 9154 </constant> | |
| 9155 <constant id="JVMTI_TYPE_JDOUBLE" num="107"> | |
| 9156 Java programming language primitive type - <code>double</code>. | |
| 9157 JNI type <datalink id="jdouble"></datalink>. | |
| 9158 </constant> | |
| 9159 <constant id="JVMTI_TYPE_JBOOLEAN" num="108"> | |
| 9160 Java programming language primitive type - <code>boolean</code>. | |
| 9161 JNI type <datalink id="jboolean"></datalink>. | |
| 9162 </constant> | |
| 9163 <constant id="JVMTI_TYPE_JOBJECT" num="109"> | |
| 9164 Java programming language object type - <code>java.lang.Object</code>. | |
| 9165 JNI type <datalink id="jobject"></datalink>. | |
| 9166 Returned values are JNI local references and must be managed. | |
| 9167 </constant> | |
| 9168 <constant id="JVMTI_TYPE_JTHREAD" num="110"> | |
| 9169 Java programming language object type - <code>java.lang.Thread</code>. | |
| 9170 <jvmti/> type <datalink id="jthread"></datalink>. | |
| 9171 Returned values are JNI local references and must be managed. | |
| 9172 </constant> | |
| 9173 <constant id="JVMTI_TYPE_JCLASS" num="111"> | |
| 9174 Java programming language object type - <code>java.lang.Class</code>. | |
| 9175 JNI type <datalink id="jclass"></datalink>. | |
| 9176 Returned values are JNI local references and must be managed. | |
| 9177 </constant> | |
| 9178 <constant id="JVMTI_TYPE_JVALUE" num="112"> | |
| 9179 Union of all Java programming language primitive and object types - | |
| 9180 JNI type <datalink id="jvalue"></datalink>. | |
| 9181 Returned values which represent object types are JNI local references and must be managed. | |
| 9182 </constant> | |
| 9183 <constant id="JVMTI_TYPE_JFIELDID" num="113"> | |
| 9184 Java programming language field identifier - | |
| 9185 JNI type <datalink id="jfieldID"></datalink>. | |
| 9186 </constant> | |
| 9187 <constant id="JVMTI_TYPE_JMETHODID" num="114"> | |
| 9188 Java programming language method identifier - | |
| 9189 JNI type <datalink id="jmethodID"></datalink>. | |
| 9190 </constant> | |
| 9191 <constant id="JVMTI_TYPE_CCHAR" num="115"> | |
| 9192 C programming language type - <code>char</code>. | |
| 9193 </constant> | |
| 9194 <constant id="JVMTI_TYPE_CVOID" num="116"> | |
| 9195 C programming language type - <code>void</code>. | |
| 9196 </constant> | |
| 9197 <constant id="JVMTI_TYPE_JNIENV" num="117"> | |
| 9198 JNI environment - <code>JNIEnv</code>. | |
| 9199 Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type. | |
| 9200 </constant> | |
| 9201 </constants> | |
| 9202 | |
| 9203 <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum"> | |
| 9204 <constant id="JVMTI_KIND_IN" num="91"> | |
| 9205 Ingoing argument - <code>foo</code>. | |
| 9206 </constant> | |
| 9207 <constant id="JVMTI_KIND_IN_PTR" num="92"> | |
| 9208 Ingoing pointer argument - <code>const foo*</code>. | |
| 9209 </constant> | |
| 9210 <constant id="JVMTI_KIND_IN_BUF" num="93"> | |
| 9211 Ingoing array argument - <code>const foo*</code>. | |
| 9212 </constant> | |
| 9213 <constant id="JVMTI_KIND_ALLOC_BUF" num="94"> | |
| 9214 Outgoing allocated array argument - <code>foo**</code>. | |
| 9215 Free with <code>Deallocate</code>. | |
| 9216 </constant> | |
| 9217 <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95"> | |
| 9218 Outgoing allocated array of allocated arrays argument - <code>foo***</code>. | |
| 9219 Free with <code>Deallocate</code>. | |
| 9220 </constant> | |
| 9221 <constant id="JVMTI_KIND_OUT" num="96"> | |
| 9222 Outgoing argument - <code>foo*</code>. | |
| 9223 </constant> | |
| 9224 <constant id="JVMTI_KIND_OUT_BUF" num="97"> | |
| 9225 Outgoing array argument (pre-allocated by agent) - <code>foo*</code>. | |
| 9226 Do not <code>Deallocate</code>. | |
| 9227 </constant> | |
| 9228 </constants> | |
| 9229 | |
| 9230 </intro> | |
| 9231 | |
| 9232 <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info"> | |
| 9233 <field id="name"> | |
| 9234 <allocfieldbuf><char/></allocfieldbuf> | |
| 9235 <description> | |
| 9236 The parameter name, encoded as a | |
| 9237 <internallink id="mUTF">modified UTF-8</internallink> string | |
| 9238 </description> | |
| 9239 </field> | |
| 9240 <field id="kind"> | |
| 9241 <enum>jvmtiParamKind</enum> | |
| 9242 <description> | |
| 9243 The kind of the parameter - type modifiers | |
| 9244 </description> | |
| 9245 </field> | |
| 9246 <field id="base_type"> | |
| 9247 <enum>jvmtiParamTypes</enum> | |
| 9248 <description> | |
| 9249 The base type of the parameter - modified by <code>kind</code> | |
| 9250 </description> | |
| 9251 </field> | |
| 9252 <field id="null_ok"> | |
| 9253 <jboolean/> | |
| 9254 <description> | |
| 9255 Is a <code>NULL</code> argument permitted? Applies only to pointer and object types. | |
| 9256 </description> | |
| 9257 </field> | |
| 9258 </typedef> | |
| 9259 | |
| 9260 <callback id="jvmtiExtensionFunction"> | |
| 9261 <enum>jvmtiError</enum> | |
| 9262 <synopsis>Extension Function</synopsis> | |
| 9263 <description> | |
| 9264 This is the implementation-specific extension function. | |
| 9265 </description> | |
| 9266 <parameters> | |
| 9267 <param id="jvmti_env"> | |
| 9268 <outptr> | |
| 9269 <struct>jvmtiEnv</struct> | |
| 9270 </outptr> | |
| 9271 <description> | |
| 9272 The <jvmti/> environment is the only fixed parameter for extension functions. | |
| 9273 </description> | |
| 9274 </param> | |
| 9275 <param id="..."> | |
| 9276 <varargs/> | |
| 9277 <description> | |
| 9278 The extension function-specific parameters | |
| 9279 </description> | |
| 9280 </param> | |
| 9281 </parameters> | |
| 9282 </callback> | |
| 9283 | |
| 9284 <function id="GetExtensionFunctions" phase="onload" num="124"> | |
| 9285 <synopsis>Get Extension Functions</synopsis> | |
| 9286 | |
| 9287 <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info"> | |
| 9288 <field id="func"> | |
| 9289 <ptrtype> | |
| 9290 <struct>jvmtiExtensionFunction</struct> | |
| 9291 </ptrtype> | |
| 9292 <description> | |
| 9293 The actual function to call | |
| 9294 </description> | |
| 9295 </field> | |
| 9296 <field id="id"> | |
| 9297 <allocfieldbuf><char/></allocfieldbuf> | |
| 9298 <description> | |
| 9299 The identifier for the extension function, encoded as a | |
| 9300 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9301 Uses package name conventions. | |
| 9302 For example, <code>com.sun.hotspot.bar</code> | |
| 9303 </description> | |
| 9304 </field> | |
| 9305 <field id="short_description"> | |
| 9306 <allocfieldbuf><char/></allocfieldbuf> | |
| 9307 <description> | |
| 9308 A one sentence description of the function, encoded as a | |
| 9309 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9310 </description> | |
| 9311 </field> | |
| 9312 <field id="param_count"> | |
| 9313 <jint/> | |
| 9314 <description> | |
| 9315 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code> | |
| 9316 </description> | |
| 9317 </field> | |
| 9318 <field id="params"> | |
| 9319 <allocfieldbuf outcount="param_count"> | |
| 9320 <struct>jvmtiParamInfo</struct> | |
| 9321 </allocfieldbuf> | |
| 9322 <description> | |
| 9323 Array of | |
| 9324 <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> | |
| 9325 parameters (<code>jvmtiEnv *jvmti_env</code> excluded) | |
| 9326 </description> | |
| 9327 </field> | |
| 9328 <field id="error_count"> | |
| 9329 <jint/> | |
| 9330 <description> | |
| 9331 The number of possible error returns (excluding universal errors) | |
| 9332 </description> | |
| 9333 </field> | |
| 9334 <field id="errors"> | |
| 9335 <allocfieldbuf outcount="error_count"> | |
| 9336 <enum>jvmtiError</enum> | |
| 9337 </allocfieldbuf> | |
| 9338 <description> | |
| 9339 Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> | |
| 9340 possible errors | |
| 9341 </description> | |
| 9342 </field> | |
| 9343 </typedef> | |
| 9344 | |
| 9345 <description> | |
| 9346 Returns the set of extension functions. | |
| 9347 </description> | |
| 9348 <origin>new</origin> | |
| 9349 <capabilities> | |
| 9350 </capabilities> | |
| 9351 <parameters> | |
| 9352 <param id="extension_count_ptr"> | |
| 9353 <outptr><jint/></outptr> | |
| 9354 <description> | |
| 9355 On return, points to the number of extension functions | |
| 9356 </description> | |
| 9357 </param> | |
| 9358 <param id="extensions"> | |
| 9359 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf> | |
| 9360 <description> | |
| 9361 Returns an array of extension function info, one per function | |
| 9362 </description> | |
| 9363 </param> | |
| 9364 </parameters> | |
| 9365 <errors> | |
| 9366 </errors> | |
| 9367 </function> | |
| 9368 | |
| 9369 <function id="GetExtensionEvents" phase="onload" num="125"> | |
| 9370 <synopsis>Get Extension Events</synopsis> | |
| 9371 | |
| 9372 <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info"> | |
| 9373 <field id="extension_event_index"> | |
| 9374 <jint/> | |
| 9375 <description> | |
| 9376 The identifying index of the event | |
| 9377 </description> | |
| 9378 </field> | |
| 9379 <field id="id"> | |
| 9380 <allocfieldbuf><char/></allocfieldbuf> | |
| 9381 <description> | |
| 9382 The identifier for the extension event, encoded as a | |
| 9383 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9384 Uses package name conventions. | |
| 9385 For example, <code>com.sun.hotspot.bar</code> | |
| 9386 </description> | |
| 9387 </field> | |
| 9388 <field id="short_description"> | |
| 9389 <allocfieldbuf><char/></allocfieldbuf> | |
| 9390 <description> | |
| 9391 A one sentence description of the event, encoded as a | |
| 9392 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9393 </description> | |
| 9394 </field> | |
| 9395 <field id="param_count"> | |
| 9396 <jint/> | |
| 9397 <description> | |
| 9398 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code> | |
| 9399 </description> | |
| 9400 </field> | |
| 9401 <field id="params"> | |
| 9402 <allocfieldbuf outcount="param_count"> | |
| 9403 <struct>jvmtiParamInfo</struct> | |
| 9404 </allocfieldbuf> | |
| 9405 <description> | |
| 9406 Array of | |
| 9407 <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink> | |
| 9408 parameters (<code>jvmtiEnv *jvmti_env</code> excluded) | |
| 9409 </description> | |
| 9410 </field> | |
| 9411 </typedef> | |
| 9412 | |
| 9413 <description> | |
| 9414 Returns the set of extension events. | |
| 9415 </description> | |
| 9416 <origin>new</origin> | |
| 9417 <capabilities> | |
| 9418 </capabilities> | |
| 9419 <parameters> | |
| 9420 <param id="extension_count_ptr"> | |
| 9421 <outptr><jint/></outptr> | |
| 9422 <description> | |
| 9423 On return, points to the number of extension events | |
| 9424 </description> | |
| 9425 </param> | |
| 9426 <param id="extensions"> | |
| 9427 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf> | |
| 9428 <description> | |
| 9429 Returns an array of extension event info, one per event | |
| 9430 </description> | |
| 9431 </param> | |
| 9432 </parameters> | |
| 9433 <errors> | |
| 9434 </errors> | |
| 9435 </function> | |
| 9436 | |
| 9437 <callback id="jvmtiExtensionEvent"> | |
| 9438 <void/> | |
| 9439 <synopsis>Extension Event</synopsis> | |
| 9440 <description> | |
| 9441 This is the implementation-specific event. | |
| 9442 The event handler is set with | |
| 9443 <functionlink id="SetExtensionEventCallback"/>. | |
| 9444 <p/> | |
| 9445 Event handlers for extension events must be declared varargs to match this definition. | |
| 9446 Failure to do so could result in calling convention mismatch and undefined behavior | |
| 9447 on some platforms. | |
| 9448 <p/> | |
| 9449 For example, if the <code>jvmtiParamInfo</code> | |
| 9450 returned by <functionlink id="GetExtensionEvents"/> indicates that | |
| 9451 there is a <code>jint</code> parameter, the event handler should be | |
| 9452 declared: | |
| 9453 <example> | |
| 9454 void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...) | |
| 9455 </example> | |
| 9456 Note the terminal "<code>...</code>" which indicates varargs. | |
| 9457 </description> | |
| 9458 <parameters> | |
| 9459 <param id="jvmti_env"> | |
| 9460 <outptr> | |
| 9461 <struct>jvmtiEnv</struct> | |
| 9462 </outptr> | |
| 9463 <description> | |
| 9464 The <jvmti/> environment is the only fixed parameter for extension events. | |
| 9465 </description> | |
| 9466 </param> | |
| 9467 <param id="..."> | |
| 9468 <varargs/> | |
| 9469 <description> | |
| 9470 The extension event-specific parameters | |
| 9471 </description> | |
| 9472 </param> | |
| 9473 </parameters> | |
| 9474 </callback> | |
| 9475 | |
| 9476 <function id="SetExtensionEventCallback" phase="onload" num="126"> | |
| 9477 <synopsis>Set Extension Event Callback</synopsis> | |
| 9478 | |
| 9479 <description> | |
| 9480 Sets the callback function for an extension event and | |
| 9481 enables the event. Or, if the callback is <code>NULL</code>, disables | |
| 9482 the event. Note that unlike standard events, setting | |
| 9483 the callback and enabling the event are a single operation. | |
| 9484 </description> | |
| 9485 <origin>new</origin> | |
| 9486 <capabilities> | |
| 9487 </capabilities> | |
| 9488 <parameters> | |
| 9489 <param id="extension_event_index"> | |
| 9490 <jint/> | |
| 9491 <description> | |
| 9492 Identifies which callback to set. | |
| 9493 This index is the | |
| 9494 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink> | |
| 9495 field of | |
| 9496 <datalink id="jvmtiExtensionEventInfo"/>. | |
| 9497 </description> | |
| 9498 </param> | |
| 9499 <param id="callback"> | |
| 9500 <ptrtype> | |
| 9501 <struct>jvmtiExtensionEvent</struct> | |
| 9502 <nullok>disable the event</nullok> | |
| 9503 </ptrtype> | |
| 9504 <description> | |
| 9505 If <code>callback</code> is non-<code>NULL</code>, | |
| 9506 set <code>callback</code> to be the event callback function | |
| 9507 and enable the event. | |
| 9508 </description> | |
| 9509 </param> | |
| 9510 </parameters> | |
| 9511 <errors> | |
| 9512 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 9513 <paramlink id="extension_event_index"/> is not an | |
| 9514 <fieldlink id="extension_event_index" | |
| 9515 struct="jvmtiExtensionEventInfo"/> | |
| 9516 returned by | |
| 9517 <functionlink id="GetExtensionEvents"/> | |
| 9518 </error> | |
| 9519 </errors> | |
| 9520 </function> | |
| 9521 | |
| 9522 </category> | |
| 9523 | |
| 9524 <category id="capability" label="Capability"> | |
| 9525 | |
| 9526 <intro> | |
| 9527 The capabilities functions allow you to change the | |
| 9528 functionality available to <jvmti/>--that is, | |
| 9529 which <jvmti/> | |
| 9530 functions can be called, what events can be generated, | |
| 9531 and what functionality these events and functions can | |
| 9532 provide. | |
| 9533 <p/> | |
| 9534 The "Capabilities" section of each function and event describe which | |
| 9535 capabilities, if any, they are associated with. "Required Functionality" | |
| 9536 means it is available for use and no capabilities must be added to use it. | |
| 9537 "Optional Functionality" means the agent must possess the capability | |
| 9538 before it can be used. | |
| 9539 To possess a capability, the agent must | |
| 9540 <functionlink id="AddCapabilities">add the capability</functionlink>. | |
| 9541 "Optional Features" describe capabilities which, | |
| 9542 if added, extend the feature set. | |
| 9543 <p/> | |
| 9544 The potentially available capabilities of each <jvmti/> implementation are different. | |
| 9545 Depending on the implementation, a capability: | |
| 9546 <ul> | |
| 9547 <li>may never be added</li> | |
| 9548 <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li> | |
| 9549 <li>may be added only during the <code>OnLoad</code> phase</li> | |
| 9550 <li>may be possessed by only one environment at a time</li> | |
| 9551 <li>may be possessed by only one environment at a time, | |
| 9552 and only during the <code>OnLoad</code> phase</li> | |
| 9553 <li>and so on ...</li> | |
| 9554 </ul> | |
| 9555 Frequently, the addition of a capability may incur a cost in execution speed, start up | |
| 9556 time, and/or memory footprint. Note that the overhead of using a capability | |
| 9557 is completely different than the overhead of possessing a capability. | |
| 9558 Take single stepping as an example. When single stepping is on (that | |
| 9559 is, when the event is enabled and thus actively sending events) | |
| 9560 the overhead of sending and processing an event | |
| 9561 on each instruction is huge in any implementation. | |
| 9562 However, the overhead of possessing the capability may be small or large, | |
| 9563 depending on the implementation. Also, when and if a capability is potentially | |
| 9564 available depends on the implementation. Some examples: | |
| 9565 <ul> | |
| 9566 <li>One VM might perform all execution by compiling bytecodes into | |
| 9567 native code and be unable to generate single step instructions. | |
| 9568 In this implementation the capability can not be added.</li> | |
| 9569 <li>Another VM may be able to switch execution to a single stepping | |
| 9570 interpreter at any time. In this implementation, having the capability has no | |
| 9571 overhead and could be added at any time.</li> | |
| 9572 <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted | |
| 9573 execution engine at start up, but be unable to switch between them. | |
| 9574 In this implementation the capability would need to be added | |
| 9575 during the <code>OnLoad</code> phase (before bytecode | |
| 9576 execution begins) and would have a large impact on execution speed | |
| 9577 even if single stepping was never used.</li> | |
| 9578 <li>Still another VM might be able to add an "is single stepping on" check | |
| 9579 into compiled bytecodes or a generated interpreter. Again in this implementation | |
| 9580 the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test | |
| 9581 and branch on each instruction) would be considerably less.</li> | |
| 9582 </ul> | |
| 9583 <p/> | |
| 9584 Each <jvmti/> <internallink id="environments">environment</internallink> | |
| 9585 has its own set of capabilities. | |
| 9586 Initially, that set is empty. | |
| 9587 Any desired capability must be added. | |
| 9588 If possible, capabilities should be added during the <code>OnLoad</code> phase. For most | |
| 9589 virtual machines certain capabilities require special set up for | |
| 9590 the virtual machine and this set up must happen | |
| 9591 during the <code>OnLoad</code> phase, before the virtual machine begins execution. | |
| 9592 Once a capability is added, it can | |
| 9593 only be removed if explicitly relinquished by the environment. | |
| 9594 <p/> | |
| 9595 The agent can, | |
| 9596 <functionlink id="GetPotentialCapabilities">determine what | |
| 9597 capabilities this VM can potentially provide</functionlink>, | |
| 9598 <functionlink id="AddCapabilities">add the capabilities | |
| 9599 to be used</functionlink>, | |
| 9600 <functionlink id="RelinquishCapabilities">release capabilities | |
| 9601 which are no longer needed</functionlink>, and | |
| 9602 <functionlink id="GetCapabilities">examine the currently available | |
| 9603 capabilities</functionlink>. | |
| 9604 </intro> | |
| 9605 | |
| 9606 <intro id="capabilityExamples" label="Capability Examples"> | |
| 9607 For example, a freshly started agent (in the <code>OnLoad</code> function) | |
| 9608 wants to enable all possible capabilities. | |
| 9609 Note that, in general, this is not advisable as the agent may suffer | |
| 9610 a performance penalty for functionality it is not using. | |
| 9611 The code might look like this in C: | |
| 9612 <example> | |
| 9613 jvmtiCapabilities capa; | |
| 9614 jvmtiError err; | |
| 9615 | |
| 9616 err = (*jvmti)->GetPotentialCapabilities(jvmti, &capa); | |
| 9617 if (err == JVMTI_ERROR_NONE) { | |
| 9618 err = (*jvmti)->AddCapabilities(jvmti, &capa); | |
| 9619 </example> | |
| 9620 For example, if an agent wants to check if it can get | |
| 9621 the bytecodes of a method (that is, it wants to check | |
| 9622 if it previously added this capability and has not | |
| 9623 relinquished it), the code might | |
| 9624 look like this in C: | |
| 9625 <example> | |
| 9626 jvmtiCapabilities capa; | |
| 9627 jvmtiError err; | |
| 9628 | |
| 9629 err = (*jvmti)->GetCapabilities(jvmti, &capa); | |
| 9630 if (err == JVMTI_ERROR_NONE) { | |
| 9631 if (capa.can_get_bytecodes) { ... } } | |
| 9632 </example> | |
| 9633 </intro> | |
| 9634 | |
| 9635 <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure"> | |
| 9636 <description> | |
| 9637 The functions in this category use this capabilities structure | |
| 9638 which contains boolean flags corresponding to each capability: | |
| 9639 </description> | |
| 9640 <capabilityfield id="can_tag_objects"> | |
| 9641 <description> | |
| 9642 Can set and get tags, as described in the | |
| 9643 <internallink id="Heap">Heap category</internallink>. | |
| 9644 </description> | |
| 9645 </capabilityfield> | |
| 9646 <capabilityfield id="can_generate_field_modification_events"> | |
| 9647 <description> | |
| 9648 Can set watchpoints on field modification - | |
| 9649 <functionlink id="SetFieldModificationWatch"></functionlink> | |
| 9650 </description> | |
| 9651 </capabilityfield> | |
| 9652 <capabilityfield id="can_generate_field_access_events"> | |
| 9653 <description> | |
| 9654 Can set watchpoints on field access - | |
| 9655 <functionlink id="SetFieldAccessWatch"></functionlink> | |
| 9656 </description> | |
| 9657 </capabilityfield> | |
| 9658 <capabilityfield id="can_get_bytecodes"> | |
| 9659 <description> | |
| 9660 Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink> | |
| 9661 </description> | |
| 9662 </capabilityfield> | |
| 9663 <capabilityfield id="can_get_synthetic_attribute"> | |
| 9664 <description> | |
| 9665 Can test if a field or method is synthetic - | |
| 9666 <functionlink id="IsFieldSynthetic"></functionlink> and | |
| 9667 <functionlink id="IsMethodSynthetic"></functionlink> | |
| 9668 </description> | |
| 9669 </capabilityfield> | |
| 9670 <capabilityfield id="can_get_owned_monitor_info"> | |
| 9671 <description> | |
| 9672 Can get information about ownership of monitors - | |
| 9673 <functionlink id="GetOwnedMonitorInfo"></functionlink> | |
| 9674 </description> | |
| 9675 </capabilityfield> | |
| 9676 <capabilityfield id="can_get_current_contended_monitor"> | |
| 9677 <description> | |
| 9678 Can <functionlink id="GetCurrentContendedMonitor"></functionlink> | |
| 9679 </description> | |
| 9680 </capabilityfield> | |
| 9681 <capabilityfield id="can_get_monitor_info"> | |
| 9682 <description> | |
| 9683 Can <functionlink id="GetObjectMonitorUsage"></functionlink> | |
| 9684 </description> | |
| 9685 </capabilityfield> | |
| 9686 <capabilityfield id="can_pop_frame"> | |
| 9687 <description> | |
| 9688 Can pop frames off the stack - <functionlink id="PopFrame"></functionlink> | |
| 9689 </description> | |
| 9690 </capabilityfield> | |
| 9691 <capabilityfield id="can_redefine_classes"> | |
| 9692 <description> | |
| 9693 Can redefine classes with <functionlink id="RedefineClasses"/>. | |
| 9694 </description> | |
| 9695 </capabilityfield> | |
| 9696 <capabilityfield id="can_signal_thread"> | |
| 9697 <description> | |
| 9698 Can send stop or interrupt to threads | |
| 9699 </description> | |
| 9700 </capabilityfield> | |
| 9701 <capabilityfield id="can_get_source_file_name"> | |
| 9702 <description> | |
| 9703 Can get the source file name of a class | |
| 9704 </description> | |
| 9705 </capabilityfield> | |
| 9706 <capabilityfield id="can_get_line_numbers"> | |
| 9707 <description> | |
| 9708 Can get the line number table of a method | |
| 9709 </description> | |
| 9710 </capabilityfield> | |
| 9711 <capabilityfield id="can_get_source_debug_extension"> | |
| 9712 <description> | |
| 9713 Can get the source debug extension of a class | |
| 9714 </description> | |
| 9715 </capabilityfield> | |
| 9716 <capabilityfield id="can_access_local_variables"> | |
| 9717 <description> | |
| 9718 Can set and get local variables | |
| 9719 </description> | |
| 9720 </capabilityfield> | |
| 9721 <capabilityfield id="can_maintain_original_method_order"> | |
| 9722 <description> | |
| 9723 Can return methods in the order they occur in the class file | |
| 9724 </description> | |
| 9725 </capabilityfield> | |
| 9726 <capabilityfield id="can_generate_single_step_events"> | |
| 9727 <description> | |
| 9728 Can get <eventlink id="SingleStep">single step</eventlink> events | |
| 9729 </description> | |
| 9730 </capabilityfield> | |
| 9731 <capabilityfield id="can_generate_exception_events"> | |
| 9732 <description> | |
| 9733 Can get <eventlink id="Exception">exception thrown</eventlink> and | |
| 9734 <eventlink id="ExceptionCatch">exception catch</eventlink> events | |
| 9735 </description> | |
| 9736 </capabilityfield> | |
| 9737 <capabilityfield id="can_generate_frame_pop_events"> | |
| 9738 <description> | |
| 9739 Can <functionlink id="NotifyFramePop">set</functionlink> and thus get | |
| 9740 <eventlink id="FramePop"></eventlink> events | |
| 9741 </description> | |
| 9742 </capabilityfield> | |
| 9743 <capabilityfield id="can_generate_breakpoint_events"> | |
| 9744 <description> | |
| 9745 Can <functionlink id="SetBreakpoint">set</functionlink> and thus get | |
| 9746 <eventlink id="Breakpoint"></eventlink> events | |
| 9747 </description> | |
| 9748 </capabilityfield> | |
| 9749 <capabilityfield id="can_suspend"> | |
| 9750 <description> | |
| 9751 Can suspend and resume threads | |
| 9752 </description> | |
| 9753 </capabilityfield> | |
| 9754 <capabilityfield id="can_redefine_any_class"> | |
| 9755 <description> | |
| 9756 Can modify (retransform or redefine) any non-primitive non-array class. | |
| 9757 See <functionlink id="IsModifiableClass"/>. | |
| 9758 </description> | |
| 9759 </capabilityfield> | |
| 9760 <capabilityfield id="can_get_current_thread_cpu_time"> | |
| 9761 <description> | |
| 9762 Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink> | |
| 9763 current thread CPU time | |
| 9764 </description> | |
| 9765 </capabilityfield> | |
| 9766 <capabilityfield id="can_get_thread_cpu_time"> | |
| 9767 <description> | |
| 9768 Can <functionlink id="GetThreadCpuTime">get</functionlink> | |
| 9769 thread CPU time | |
| 9770 </description> | |
| 9771 </capabilityfield> | |
| 9772 <capabilityfield id="can_generate_method_entry_events" | |
| 9773 disp1="can_generate" disp2="_method_entry_events" | |
| 9774 > | |
| 9775 <description> | |
| 9776 Can generate method entry events on entering a method | |
| 9777 </description> | |
| 9778 </capabilityfield> | |
| 9779 <capabilityfield id="can_generate_method_exit_events" | |
| 9780 disp1="can_generate" disp2="_method_exit_events" | |
| 9781 > | |
| 9782 <description> | |
| 9783 Can generate method exit events on leaving a method | |
| 9784 </description> | |
| 9785 </capabilityfield> | |
| 9786 <capabilityfield id="can_generate_all_class_hook_events" | |
| 9787 disp1="can_generate" disp2="_all_class_hook_events" | |
| 9788 > | |
| 9789 <description> | |
| 9790 Can generate ClassFileLoadHook events for every loaded class. | |
| 9791 </description> | |
| 9792 </capabilityfield> | |
| 9793 <capabilityfield id="can_generate_compiled_method_load_events" | |
| 9794 disp1="can_generate" disp2="_compiled_method_load_events" | |
| 9795 > | |
| 9796 <description> | |
| 9797 Can generate events when a method is compiled or unloaded | |
| 9798 </description> | |
| 9799 </capabilityfield> | |
| 9800 <capabilityfield id="can_generate_monitor_events" | |
| 9801 disp1="can_generate" disp2="_monitor_events" | |
| 9802 > | |
| 9803 <description> | |
| 9804 Can generate events on monitor activity | |
| 9805 </description> | |
| 9806 </capabilityfield> | |
| 9807 <capabilityfield id="can_generate_vm_object_alloc_events" | |
| 9808 disp1="can_generate" disp2="_vm_object_alloc_events" | |
| 9809 > | |
| 9810 <description> | |
| 9811 Can generate events on VM allocation of an object | |
| 9812 </description> | |
| 9813 </capabilityfield> | |
| 9814 <capabilityfield id="can_generate_native_method_bind_events" | |
| 9815 disp1="can_generate" disp2="_native_method_bind_events" | |
| 9816 > | |
| 9817 <description> | |
| 9818 Can generate events when a native method is bound to its | |
| 9819 implementation | |
| 9820 </description> | |
| 9821 </capabilityfield> | |
| 9822 <capabilityfield id="can_generate_garbage_collection_events" | |
| 9823 disp1="can_generate" disp2="_garbage_collection_events" | |
| 9824 > | |
| 9825 <description> | |
| 9826 Can generate events when garbage collection begins or ends | |
| 9827 </description> | |
| 9828 </capabilityfield> | |
| 9829 <capabilityfield id="can_generate_object_free_events" | |
| 9830 disp1="can_generate" disp2="_object_free_events" | |
| 9831 > | |
| 9832 <description> | |
| 9833 Can generate events when the garbage collector frees an object | |
| 9834 </description> | |
| 9835 </capabilityfield> | |
| 9836 <capabilityfield id="can_force_early_return" since="1.1"> | |
| 9837 <description> | |
| 9838 Can return early from a method, as described in the | |
| 9839 <internallink id="ForceEarlyReturn">Force Early Return category</internallink>. | |
| 9840 </description> | |
| 9841 </capabilityfield> | |
| 9842 <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1"> | |
| 9843 <description> | |
| 9844 Can get information about owned monitors with stack depth - | |
| 9845 <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink> | |
| 9846 </description> | |
| 9847 </capabilityfield> | |
| 9848 <capabilityfield id="can_get_constant_pool" since="1.1"> | |
| 9849 <description> | |
| 9850 Can get the constant pool of a class - | |
| 9851 <functionlink id="GetConstantPool"></functionlink> | |
| 9852 </description> | |
| 9853 </capabilityfield> | |
| 9854 <capabilityfield id="can_set_native_method_prefix" since="1.1"> | |
| 9855 <description> | |
| 9856 Can set prefix to be applied when native method cannot be resolved - | |
| 9857 <functionlink id="SetNativeMethodPrefix"/> and | |
| 9858 <functionlink id="SetNativeMethodPrefixes"/> | |
| 9859 </description> | |
| 9860 </capabilityfield> | |
| 9861 <capabilityfield id="can_retransform_classes" since="1.1"> | |
| 9862 <description> | |
| 9863 Can retransform classes with <functionlink id="RetransformClasses"/>. | |
| 9864 In addition to the restrictions imposed by the specific | |
| 9865 implementation on this capability (see the | |
| 9866 <internallink id="capability">Capability</internallink> section), | |
| 9867 this capability must be set before the | |
| 9868 <eventlink id="ClassFileLoadHook"/> event is enabled for the | |
| 9869 first time in this environment. | |
| 9870 An environment that possesses this capability at the time that | |
| 9871 <code>ClassFileLoadHook</code> is enabled for the first time is | |
| 9872 said to be <i>retransformation capable</i>. | |
| 9873 An environment that does not possess this capability at the time that | |
| 9874 <code>ClassFileLoadHook</code> is enabled for the first time is | |
| 9875 said to be <i>retransformation incapable</i>. | |
| 9876 </description> | |
| 9877 </capabilityfield> | |
| 9878 <capabilityfield id="can_retransform_any_class" since="1.1"> | |
| 9879 <description> | |
| 9880 <functionlink id="RetransformClasses"/> can be called on any class | |
| 9881 (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> | |
| 9882 must also be set) | |
| 9883 </description> | |
| 9884 </capabilityfield> | |
| 9885 <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1"> | |
| 9886 <description> | |
| 9887 Can generate events when the VM is unable to allocate memory from | |
| 9888 the <tm>Java</tm> platform heap. | |
| 9889 See <eventlink id="ResourceExhausted"/>. | |
| 9890 </description> | |
| 9891 </capabilityfield> | |
| 9892 <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1"> | |
| 9893 <description> | |
| 9894 Can generate events when the VM is unable to create a thread. | |
| 9895 See <eventlink id="ResourceExhausted"/>. | |
| 9896 </description> | |
| 9897 </capabilityfield> | |
| 9898 </capabilitiestypedef> | |
| 9899 | |
| 9900 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140"> | |
| 9901 <synopsis>Get Potential Capabilities</synopsis> | |
| 9902 <description> | |
| 9903 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/> | |
| 9904 features that can potentially be possessed by this environment | |
| 9905 at this time. | |
| 9906 The returned capabilities differ from the complete set of capabilities | |
| 9907 implemented by the VM in two cases: another environment possesses | |
| 9908 capabilities that can only be possessed by one environment, or the | |
| 9909 current <functionlink id="GetPhase">phase</functionlink> is live, | |
| 9910 and certain capabilities can only be added during the <code>OnLoad</code> phase. | |
| 9911 The <functionlink id="AddCapabilities"></functionlink> function | |
| 9912 may be used to set any or all or these capabilities. | |
| 9913 Currently possessed capabilities are included. | |
| 9914 <p/> | |
| 9915 Typically this function is used in the <code>OnLoad</code> function. | |
| 9916 Some virtual machines may allow a limited set of capabilities to be | |
| 9917 added in the live phase. | |
| 9918 In this case, the set of potentially available capabilities | |
| 9919 will likely differ from the <code>OnLoad</code> phase set. | |
| 9920 <p/> | |
| 9921 See the | |
| 9922 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 9923 </description> | |
| 9924 <origin>new</origin> | |
| 9925 <capabilities> | |
| 9926 </capabilities> | |
| 9927 <parameters> | |
| 9928 <param id="capabilities_ptr"> | |
| 9929 <outptr><struct>jvmtiCapabilities</struct></outptr> | |
| 9930 <description> | |
| 9931 On return, points to the <jvmti/> capabilities that may be added. | |
| 9932 </description> | |
| 9933 </param> | |
| 9934 </parameters> | |
| 9935 <errors> | |
| 9936 </errors> | |
| 9937 </function> | |
| 9938 | |
| 9939 <elide> | |
| 9940 <function id="EstimateCostOfCapabilities" phase="onload" num="141"> | |
| 9941 <synopsis>Estimate Cost Of Capabilities</synopsis> | |
| 9942 <description> | |
| 9943 <issue>There is strong opposition to this function. The concern is | |
| 9944 that it would be difficult or impossible to provide meaningful | |
| 9945 numbers, as the amount of impact is conditional on many factors | |
| 9946 that a single number could not represent. There is doubt that | |
| 9947 conditional implementations would be used or are even a good idea. | |
| 9948 The thought is that release documentation for the implementation | |
| 9949 would be the best means of exposing this information. | |
| 9950 Unless new arguments are presented, I intend to remove this | |
| 9951 function in the next revision. | |
| 9952 </issue> | |
| 9953 <p/> | |
| 9954 Return via the <paramlink id="time_impact_ptr"></paramlink> and | |
| 9955 <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact | |
| 9956 of adding the capabilities pointed to by | |
| 9957 <paramlink id="capabilities_ptr"></paramlink>. | |
| 9958 The returned estimates are in percentage of additional overhead, thus | |
| 9959 a time impact of 100 mean the application might run | |
| 9960 at half the speed. | |
| 9961 The estimates are very rough approximations and are not guaranteed. | |
| 9962 Note also, that the estimates are of the impact of having the | |
| 9963 capability available--when and if it is used the impact may be | |
| 9964 much greater. | |
| 9965 Estimates can be for a single capability or for a set of | |
| 9966 capabilities. Note that the costs are not necessarily additive, | |
| 9967 adding support for one capability might make another available | |
| 9968 for free or conversely having two capabilities at once may | |
| 9969 have multiplicative impact. | |
| 9970 Estimates are relative to the current set of capabilities - | |
| 9971 that is, how much more impact given the currently possessed capabilities. | |
| 9972 <p/> | |
| 9973 Typically this function is used in the OnLoad function, | |
| 9974 some virtual machines may allow a limited set of capabilities to be | |
| 9975 added in the live phase. | |
| 9976 In this case, the set of potentially available capabilities | |
| 9977 will likely differ from the OnLoad phase set. | |
| 9978 <p/> | |
| 9979 See the | |
| 9980 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 9981 </description> | |
| 9982 <origin>new</origin> | |
| 9983 <capabilities> | |
| 9984 </capabilities> | |
| 9985 <parameters> | |
| 9986 <param id="capabilities_ptr"> | |
| 9987 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
| 9988 <description> | |
| 9989 points to the <jvmti/> capabilities to evaluate. | |
| 9990 </description> | |
| 9991 </param> | |
| 9992 <param id="time_impact_ptr"> | |
| 9993 <outptr><jint/></outptr> | |
| 9994 <description> | |
| 9995 On return, points to the estimated percentage increase in | |
| 9996 run time if this capability was added. | |
| 9997 </description> | |
| 9998 </param> | |
| 9999 <param id="space_impact_ptr"> | |
| 10000 <outptr><jint/></outptr> | |
| 10001 <description> | |
| 10002 On return, points to the estimated percentage increase in | |
| 10003 memory space used if this capability was added. | |
| 10004 </description> | |
| 10005 </param> | |
| 10006 </parameters> | |
| 10007 <errors> | |
| 10008 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10009 The desired capabilities are not even potentially available. | |
| 10010 </error> | |
| 10011 </errors> | |
| 10012 </function> | |
| 10013 </elide> | |
| 10014 | |
| 10015 <function id="AddCapabilities" jkernel="yes" phase="onload" num="142"> | |
| 10016 <synopsis>Add Capabilities</synopsis> | |
| 10017 <description> | |
| 10018 Set new capabilities by adding the capabilities | |
| 10019 whose values are set to one (<code>1</code>) in | |
| 10020 <code>*</code><paramlink id="capabilities_ptr"></paramlink>. | |
| 10021 All previous capabilities are retained. | |
| 10022 Typically this function is used in the <code>OnLoad</code> function. | |
| 10023 Some virtual machines may allow a limited set of capabilities to be | |
| 10024 added in the live phase. | |
| 10025 <p/> | |
| 10026 See the | |
| 10027 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 10028 </description> | |
| 10029 <origin>new</origin> | |
| 10030 <capabilities> | |
| 10031 </capabilities> | |
| 10032 <parameters> | |
| 10033 <param id="capabilities_ptr"> | |
| 10034 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
| 10035 <description> | |
| 10036 Points to the <jvmti/> capabilities to add. | |
| 10037 </description> | |
| 10038 </param> | |
| 10039 </parameters> | |
| 10040 <errors> | |
| 10041 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10042 The desired capabilities are not even potentially available. | |
| 10043 </error> | |
| 10044 </errors> | |
| 10045 </function> | |
| 10046 | |
| 10047 | |
| 10048 <function id="RelinquishCapabilities" phase="onload" num="143"> | |
| 10049 <synopsis>Relinquish Capabilities</synopsis> | |
| 10050 <description> | |
| 10051 Relinquish the capabilities | |
| 10052 whose values are set to one (<code>1</code>) in | |
| 10053 <code>*</code><paramlink id="capabilities_ptr"></paramlink>. | |
| 10054 Some implementations may allow only one environment to have a capability | |
| 10055 (see the <internallink id="capability">capability introduction</internallink>). | |
| 10056 This function releases capabilities | |
| 10057 so that they may be used by other agents. | |
| 10058 All other capabilities are retained. | |
| 10059 The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>. | |
| 10060 Attempting to relinquish a capability that the agent does not possess is not an error. | |
| 10061 <issue> | |
| 10062 It is possible for the agent to be actively using capabilities | |
| 10063 which are being relinquished. For example, a thread is currently | |
| 10064 suspended and can_suspend is being relinquished or an event is currently | |
| 10065 enabled and can_generate_whatever is being relinquished. | |
| 10066 There are three possible ways we could spec this: | |
| 10067 <ul> | |
| 10068 <li>relinquish automatically releases them</li> | |
| 10069 <li>relinquish checks and returns some error code if held</li> | |
| 10070 <li>it is the agent's responsibility and it is not checked</li> | |
| 10071 </ul> | |
| 10072 One of these should be chosen. | |
| 10073 </issue> | |
| 10074 </description> | |
| 10075 <origin>new</origin> | |
| 10076 <capabilities> | |
| 10077 </capabilities> | |
| 10078 <parameters> | |
| 10079 <param id="capabilities_ptr"> | |
| 10080 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
| 10081 <description> | |
| 10082 Points to the <jvmti/> capabilities to relinquish. | |
| 10083 </description> | |
| 10084 </param> | |
| 10085 </parameters> | |
| 10086 <errors> | |
| 10087 </errors> | |
| 10088 </function> | |
| 10089 | |
| 10090 | |
| 10091 | |
| 10092 <function id="GetCapabilities" jkernel="yes" phase="any" num="89"> | |
| 10093 <synopsis>Get Capabilities</synopsis> | |
| 10094 <description> | |
| 10095 Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/> | |
| 10096 features which this environment currently possesses. | |
| 10097 Each possessed capability is indicated by a one (<code>1</code>) in the | |
| 10098 corresponding field of the <internallink id="jvmtiCapabilities">capabilities | |
| 10099 structure</internallink>. | |
| 10100 An environment does not possess a capability unless it has been successfully added with | |
| 10101 <functionlink id="AddCapabilities"/>. | |
| 10102 An environment only loses possession of a capability if it has been relinquished with | |
| 10103 <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result | |
| 10104 of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which | |
| 10105 have been made. | |
| 10106 <p/> | |
| 10107 See the | |
| 10108 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 10109 </description> | |
| 10110 <origin>jvmdiClone</origin> | |
| 10111 <capabilities> | |
| 10112 </capabilities> | |
| 10113 <parameters> | |
| 10114 <param id="capabilities_ptr"> | |
| 10115 <outptr><struct>jvmtiCapabilities</struct></outptr> | |
| 10116 <description> | |
| 10117 On return, points to the <jvmti/> capabilities. | |
| 10118 </description> | |
| 10119 </param> | |
| 10120 </parameters> | |
| 10121 <errors> | |
| 10122 </errors> | |
| 10123 </function> | |
| 10124 | |
| 10125 </category> | |
| 10126 | |
| 10127 | |
| 10128 <category id="timers" label="Timers"> | |
| 10129 | |
| 10130 <intro> | |
| 10131 These functions provide timing information. | |
| 10132 The resolution at which the time is updated is not specified. | |
| 10133 They provides nanosecond precision, but not necessarily nanosecond accuracy. | |
| 10134 Details about the timers, such as their maximum values, can be accessed with | |
| 10135 the timer information functions. | |
| 10136 </intro> | |
| 10137 | |
| 10138 <typedef id="jvmtiTimerInfo" label="Timer Info"> | |
| 10139 <description> | |
| 10140 The information function for each timer returns this data structure. | |
| 10141 </description> | |
| 10142 <field id="max_value"> | |
| 10143 <jlong/> | |
| 10144 <description> | |
| 10145 The maximum value the timer can reach. | |
| 10146 After this value is reached the timer wraps back to zero. | |
| 10147 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10148 it may appear to be a negative number. | |
| 10149 </description> | |
| 10150 </field> | |
| 10151 <field id="may_skip_forward"> | |
| 10152 <jboolean/> | |
| 10153 <description> | |
| 10154 If true, the timer can be externally adjusted and as a result skip forward. | |
| 10155 If false, the timer value will never increase faster than real time. | |
| 10156 </description> | |
| 10157 </field> | |
| 10158 <field id="may_skip_backward"> | |
| 10159 <jboolean/> | |
| 10160 <description> | |
| 10161 If true, the timer can be externally adjusted and as a result skip backward. | |
| 10162 If false, the timer value will be monotonically increasing. | |
| 10163 </description> | |
| 10164 </field> | |
| 10165 <field id="kind"> | |
| 10166 <enum>jvmtiTimerKind</enum> | |
| 10167 <description> | |
| 10168 The kind of timer. | |
| 10169 On a platform that does not distinguish between user and system time, <datalink | |
| 10170 id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink> | |
| 10171 is returned. | |
| 10172 </description> | |
| 10173 </field> | |
| 10174 <field id="reserved1"> | |
| 10175 <jlong/> | |
| 10176 <description> | |
| 10177 Reserved for future use. | |
| 10178 </description> | |
| 10179 </field> | |
| 10180 <field id="reserved2"> | |
| 10181 <jlong/> | |
| 10182 <description> | |
| 10183 Reserved for future use. | |
| 10184 </description> | |
| 10185 </field> | |
| 10186 </typedef> | |
| 10187 | |
| 10188 <intro> | |
| 10189 Where the timer kind is -- | |
| 10190 | |
| 10191 <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum"> | |
| 10192 <constant id="JVMTI_TIMER_USER_CPU" num="30"> | |
| 10193 CPU time that a thread is in user mode. | |
| 10194 </constant> | |
| 10195 <constant id="JVMTI_TIMER_TOTAL_CPU" num="31"> | |
| 10196 CPU time that a thread is in user or system mode. | |
| 10197 </constant> | |
| 10198 <constant id="JVMTI_TIMER_ELAPSED" num="32"> | |
| 10199 Elapsed time. | |
| 10200 </constant> | |
| 10201 </constants> | |
| 10202 </intro> | |
| 10203 | |
| 10204 <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe" impl="innative notrace" phase="start" num="134"> | |
| 10205 <synopsis>Get Current Thread CPU Timer Information</synopsis> | |
| 10206 <description> | |
| 10207 Get information about the | |
| 10208 <functionlink id="GetCurrentThreadCpuTime"/> timer. | |
| 10209 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
| 10210 are filled in with details about the timer. | |
| 10211 This information is specific to the platform and the implementation of | |
| 10212 <functionlink id="GetCurrentThreadCpuTime"/> and thus | |
| 10213 does not vary by thread nor does it vary | |
| 10214 during a particular invocation of the VM. | |
| 10215 <p/> | |
| 10216 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> | |
| 10217 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values | |
| 10218 returned by <code>GetCurrentThreadCpuTimerInfo</code> | |
| 10219 and <functionlink id="GetThreadCpuTimerInfo"/> | |
| 10220 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. | |
| 10221 </description> | |
| 10222 <origin>new</origin> | |
| 10223 <capabilities> | |
| 10224 <required id="can_get_current_thread_cpu_time"> | |
| 10225 Can get current thread CPU time. | |
| 10226 </required> | |
| 10227 </capabilities> | |
| 10228 <parameters> | |
| 10229 <param id="info_ptr"> | |
| 10230 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
| 10231 <description> | |
| 10232 On return, filled with information describing the time | |
| 10233 returned by <functionlink id="GetCurrentThreadCpuTime"/>. | |
| 10234 </description> | |
| 10235 </param> | |
| 10236 </parameters> | |
| 10237 <errors> | |
| 10238 </errors> | |
| 10239 </function> | |
| 10240 | |
| 10241 <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135"> | |
| 10242 <synopsis>Get Current Thread CPU Time</synopsis> | |
| 10243 <description> | |
| 10244 Return the CPU time utilized by the current thread. | |
| 10245 <p/> | |
| 10246 Note that the <functionlink id="GetThreadCpuTime"/> | |
| 10247 function provides CPU time for any thread, including | |
| 10248 the current thread. <code>GetCurrentThreadCpuTime</code> | |
| 10249 exists to support platforms which cannot | |
| 10250 supply CPU time for threads other than the current | |
| 10251 thread or which have more accurate information for | |
| 10252 the current thread (see | |
| 10253 <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs | |
| 10254 <functionlink id="GetThreadCpuTimerInfo"/>). | |
| 10255 On many platforms this call will be equivalent to: | |
| 10256 <example> | |
| 10257 GetThreadCpuTime(env, NULL, nanos_ptr) | |
| 10258 </example> | |
| 10259 </description> | |
| 10260 <origin>new</origin> | |
| 10261 <capabilities> | |
| 10262 <required id="can_get_current_thread_cpu_time"> | |
| 10263 Can get current thread CPU time. | |
| 10264 <p/> | |
| 10265 If this capability is enabled after threads have started, | |
| 10266 the implementation may choose any time up | |
| 10267 to and including the time that the capability is enabled | |
| 10268 as the point where CPU time collection starts. | |
| 10269 <p/> | |
| 10270 This capability must be potentially available on any | |
| 10271 platform where | |
| 10272 <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink> | |
| 10273 is potentially available. | |
| 10274 </required> | |
| 10275 </capabilities> | |
| 10276 <parameters> | |
| 10277 <param id="nanos_ptr"> | |
| 10278 <outptr><jlong/></outptr> | |
| 10279 <description> | |
| 10280 On return, points to the CPU time used by this thread | |
| 10281 in nanoseconds. | |
| 10282 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10283 it may appear to be a negative number. | |
| 10284 </description> | |
| 10285 </param> | |
| 10286 </parameters> | |
| 10287 <errors> | |
| 10288 </errors> | |
| 10289 </function> | |
| 10290 | |
| 10291 <function id="GetThreadCpuTimerInfo" num="136"> | |
| 10292 <synopsis>Get Thread CPU Timer Information</synopsis> | |
| 10293 <description> | |
| 10294 Get information about the | |
| 10295 <functionlink id="GetThreadCpuTime"/> timer. | |
| 10296 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
| 10297 are filled in with details about the timer. | |
| 10298 This information is specific to the platform and the implementation of | |
| 10299 <functionlink id="GetThreadCpuTime"/> and thus | |
| 10300 does not vary by thread nor does it vary | |
| 10301 during a particular invocation of the VM. | |
| 10302 <p/> | |
| 10303 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> | |
| 10304 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values | |
| 10305 returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/> | |
| 10306 and <code>GetThreadCpuTimerInfo</code> | |
| 10307 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. | |
| 10308 </description> | |
| 10309 <origin>new</origin> | |
| 10310 <capabilities> | |
| 10311 <required id="can_get_thread_cpu_time"> | |
| 10312 Can get thread CPU time. | |
| 10313 </required> | |
| 10314 </capabilities> | |
| 10315 <parameters> | |
| 10316 <param id="info_ptr"> | |
| 10317 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
| 10318 <description> | |
| 10319 On return, filled with information describing the time | |
| 10320 returned by <functionlink id="GetThreadCpuTime"/>. | |
| 10321 </description> | |
| 10322 </param> | |
| 10323 </parameters> | |
| 10324 <errors> | |
| 10325 </errors> | |
| 10326 </function> | |
| 10327 | |
| 10328 <function id="GetThreadCpuTime" num="137"> | |
| 10329 <synopsis>Get Thread CPU Time</synopsis> | |
| 10330 <description> | |
| 10331 Return the CPU time utilized by the specified thread. | |
| 10332 <p/> | |
| 10333 Get information about this timer with | |
| 10334 <functionlink id="GetThreadCpuTimerInfo"/>. | |
| 10335 </description> | |
| 10336 <origin>new</origin> | |
| 10337 <capabilities> | |
| 10338 <required id="can_get_thread_cpu_time"> | |
| 10339 Can get thread CPU time. | |
| 10340 <p/> | |
| 10341 If this capability is enabled after threads have started, | |
| 10342 the implementation may choose any time up | |
| 10343 to and including the time that the capability is enabled | |
| 10344 as the point where CPU time collection starts. | |
| 10345 </required> | |
| 10346 </capabilities> | |
| 10347 <parameters> | |
| 10348 <param id="thread"> | |
| 10349 <jthread null="current"/> | |
| 10350 <description> | |
| 10351 The thread to query. | |
| 10352 </description> | |
| 10353 </param> | |
| 10354 <param id="nanos_ptr"> | |
| 10355 <outptr><jlong/></outptr> | |
| 10356 <description> | |
| 10357 On return, points to the CPU time used by the specified thread | |
| 10358 in nanoseconds. | |
| 10359 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10360 it may appear to be a negative number. | |
| 10361 </description> | |
| 10362 </param> | |
| 10363 </parameters> | |
| 10364 <errors> | |
| 10365 </errors> | |
| 10366 </function> | |
| 10367 | |
| 10368 <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138"> | |
| 10369 <synopsis>Get Timer Information</synopsis> | |
| 10370 <description> | |
| 10371 Get information about the | |
| 10372 <functionlink id="GetTime"/> timer. | |
| 10373 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
| 10374 are filled in with details about the timer. | |
| 10375 This information will not change during a particular invocation of the VM. | |
| 10376 </description> | |
| 10377 <origin>new</origin> | |
| 10378 <capabilities> | |
| 10379 </capabilities> | |
| 10380 <parameters> | |
| 10381 <param id="info_ptr"> | |
| 10382 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
| 10383 <description> | |
| 10384 On return, filled with information describing the time | |
| 10385 returned by <functionlink id="GetTime"/>. | |
| 10386 </description> | |
| 10387 </param> | |
| 10388 </parameters> | |
| 10389 <errors> | |
| 10390 </errors> | |
| 10391 </function> | |
| 10392 | |
| 10393 <function id="GetTime" phase="any" callbacksafe="safe" num="139"> | |
| 10394 <synopsis>Get Time</synopsis> | |
| 10395 <description> | |
| 10396 Return the current value of the system timer, in nanoseconds. | |
| 10397 <p/> | |
| 10398 The value returned represents nanoseconds since some fixed but | |
| 10399 arbitrary time (perhaps in the future, so values may be | |
| 10400 negative). This function provides nanosecond precision, but not | |
| 10401 necessarily nanosecond accuracy. No guarantees are made about | |
| 10402 how frequently values change. | |
| 10403 <p/> | |
| 10404 Get information about this timer with | |
| 10405 <functionlink id="GetTimerInfo"/>. | |
| 10406 </description> | |
| 10407 <origin>new</origin> | |
| 10408 <capabilities> | |
| 10409 </capabilities> | |
| 10410 <parameters> | |
| 10411 <param id="nanos_ptr"> | |
| 10412 <outptr><jlong/></outptr> | |
| 10413 <description> | |
| 10414 On return, points to the time in nanoseconds. | |
| 10415 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10416 it may appear to be a negative number. | |
| 10417 </description> | |
| 10418 </param> | |
| 10419 </parameters> | |
| 10420 <errors> | |
| 10421 </errors> | |
| 10422 </function> | |
| 10423 | |
| 10424 <function id="GetAvailableProcessors" phase="any" num="144"> | |
| 10425 <synopsis>Get Available Processors</synopsis> | |
| 10426 <description> | |
| 10427 Returns the number of processors available to the Java virtual machine. | |
| 10428 <p/> | |
| 10429 This value may change during a particular invocation of the virtual machine. | |
| 10430 Applications that are sensitive to the number of available processors should | |
| 10431 therefore occasionally poll this property. | |
| 10432 </description> | |
| 10433 <origin>new</origin> | |
| 10434 <capabilities> | |
| 10435 </capabilities> | |
| 10436 <parameters> | |
| 10437 <param id="processor_count_ptr"> | |
| 10438 <outptr><jint/></outptr> | |
| 10439 <description> | |
| 10440 On return, points to the maximum number of processors available to the | |
| 10441 virtual machine; never smaller than one. | |
| 10442 </description> | |
| 10443 </param> | |
| 10444 </parameters> | |
| 10445 <errors> | |
| 10446 </errors> | |
| 10447 </function> | |
| 10448 | |
| 10449 </category> | |
| 10450 | |
| 10451 | |
| 10452 <category id="classLoaderSearch" label="Class Loader Search"> | |
| 10453 | |
| 10454 <intro> | |
| 10455 These functions allow the agent to add to the locations that a class loader searches for a class. | |
| 10456 This is useful for installing instrumentation under the correct class loader. | |
| 10457 </intro> | |
| 10458 | |
| 10459 <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149"> | |
| 10460 <synopsis>Add To Bootstrap Class Loader Search</synopsis> | |
| 10461 <description> | |
| 10462 This function can be used to cause instrumentation classes to be defined by the | |
| 10463 bootstrap class loader. See | |
| 10464 <vmspeclink id="ConstantPool.doc.html#79383" | |
| 10465 name="Loading Using the Bootstrap Class Loader" | |
| 10466 preposition="in"/>. | |
| 10467 After the bootstrap | |
| 10468 class loader unsuccessfully searches for a class, the specified platform-dependent | |
| 10469 search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in | |
| 10470 the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, | |
| 10471 the segments will be searched in the order that this function was called. | |
| 10472 <p/> | |
| 10473 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent | |
| 10474 search path segment to be searched after the bootstrap class loader unsuccessfully searches | |
| 10475 for a class. The segment is typically a directory or JAR file. | |
| 10476 <p/> | |
| 10477 In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent | |
| 10478 path to a <externallink id="http://java.sun.com/javase/6/docs/guide/jar/jar.html"> | |
| 10479 JAR file</externallink>. The agent should take care that the JAR file does not | |
| 10480 contain any classes or resources other than those to be defined by the bootstrap | |
| 10481 class loader for the purposes of instrumentation. | |
| 10482 <p/> | |
| 10483 The <vmspeclink/> specifies that a subsequent attempt to resolve a symbolic | |
| 10484 reference that the Java virtual machine has previously unsuccessfully attempted | |
| 10485 to resolve always fails with the same error that was thrown as a result of the | |
| 10486 initial resolution attempt. Consequently, if the JAR file contains an entry | |
| 10487 that corresponds to a class for which the Java virtual machine has | |
| 10488 unsuccessfully attempted to resolve a reference, then subsequent attempts to | |
| 10489 resolve that reference will fail with the same error as the initial attempt. | |
| 10490 </description> | |
| 10491 <origin>new</origin> | |
| 10492 <capabilities> | |
| 10493 </capabilities> | |
| 10494 <parameters> | |
| 10495 <param id="segment"> | |
| 10496 <inbuf><char/></inbuf> | |
| 10497 <description> | |
| 10498 The platform-dependent search path segment, encoded as a | |
| 10499 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10500 </description> | |
| 10501 </param> | |
| 10502 </parameters> | |
| 10503 <errors> | |
| 10504 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 10505 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an | |
| 10506 existing JAR file is an invalid path. | |
| 10507 </error> | |
| 10508 </errors> | |
| 10509 </function> | |
| 10510 | |
| 10511 <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1"> | |
| 10512 <synopsis>Add To System Class Loader Search</synopsis> | |
| 10513 <description> | |
| 10514 This function can be used to cause instrumentation classes to be | |
| 10515 defined by the system class loader. See | |
| 10516 <vmspeclink id="ConstantPool.doc.html#79441" | |
| 10517 name="Loading Using a User-defined Class Loader" | |
| 10518 preposition="in"/>. | |
| 10519 After the class loader unsuccessfully searches for a class, the specified platform-dependent search | |
| 10520 path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the | |
| 10521 <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the | |
| 10522 segments will be searched in the order that this function was called. | |
| 10523 <p/> | |
| 10524 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent | |
| 10525 search path segment to be searched after the system class loader unsuccessfully searches | |
| 10526 for a class. The segment is typically a directory or JAR file. | |
| 10527 <p/> | |
| 10528 In the live phase the <paramlink id="segment"/> is a platform-dependent path to a <externallink | |
| 10529 id="http://java.sun.com/javase/6/docs/guide/jar/jar.html">JAR file</externallink> to be | |
| 10530 searched after the system class loader unsuccessfully searches for a class. The agent should | |
| 10531 take care that the JAR file does not contain any classes or resources other than those to be | |
| 10532 defined by the system class loader for the purposes of instrumentation. | |
| 10533 <p/> | |
| 10534 In the live phase the system class loader supports adding a JAR file to be searched if | |
| 10535 the system class loader implements a method name <code>appendToClassPathForInstrumentation</code> | |
| 10536 which takes a single parameter of type <code>java.lang.String</code>. The method is not required | |
| 10537 to have <code>public</code> access. | |
| 10538 <p/> | |
| 10539 The <vmspeclink/> specifies that a subsequent attempt to resolve a symbolic | |
| 10540 reference that the Java virtual machine has previously unsuccessfully attempted | |
| 10541 to resolve always fails with the same error that was thrown as a result of the | |
| 10542 initial resolution attempt. Consequently, if the JAR file contains an entry | |
| 10543 that corresponds to a class for which the Java virtual machine has | |
| 10544 unsuccessfully attempted to resolve a reference, then subsequent attempts to | |
| 10545 resolve that reference will fail with the same error as the initial attempt. | |
| 10546 </description> | |
| 10547 <origin>new</origin> | |
| 10548 <capabilities> | |
| 10549 </capabilities> | |
| 10550 <parameters> | |
| 10551 <param id="segment"> | |
| 10552 <inbuf><char/></inbuf> | |
| 10553 <description> | |
| 10554 The platform-dependent search path segment, encoded as a | |
| 10555 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10556 </description> | |
| 10557 </param> | |
| 10558 </parameters> | |
| 10559 <errors> | |
| 10560 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 10561 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an | |
| 10562 existing JAR file is an invalid path. | |
| 10563 </error> | |
| 10564 <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED"> | |
| 10565 Operation not supported by the system class loader. | |
| 10566 </error> | |
| 10567 </errors> | |
| 10568 </function> | |
| 10569 | |
| 10570 </category> | |
| 10571 | |
| 10572 | |
| 10573 <category id="props" label="System Properties"> | |
| 10574 | |
| 10575 <intro> | |
| 10576 These functions get and set system properties. | |
| 10577 </intro> | |
| 10578 | |
| 10579 <function id="GetSystemProperties" phase="onload" num="130"> | |
| 10580 <synopsis>Get System Properties</synopsis> | |
| 10581 <description> | |
| 10582 The list of VM system property keys which may be used with | |
| 10583 <functionlink id="GetSystemProperty"/> is returned. | |
| 10584 It is strongly recommended that virtual machines provide the | |
| 10585 following property keys: | |
| 10586 <ul> | |
| 10587 <li><code>java.vm.vendor</code></li> | |
| 10588 <li><code>java.vm.version</code></li> | |
| 10589 <li><code>java.vm.name</code></li> | |
| 10590 <li><code>java.vm.info</code></li> | |
| 10591 <li><code>java.library.path</code></li> | |
| 10592 <li><code>java.class.path</code></li> | |
| 10593 </ul> | |
| 10594 Provides access to system properties defined by and used | |
| 10595 by the VM. | |
| 10596 Properties set on the command-line are included. | |
| 10597 This allows getting and setting of these properties | |
| 10598 before the VM even begins executing bytecodes. | |
| 10599 Since this is a VM view of system properties, the set of available | |
| 10600 properties will usually be different than that | |
| 10601 in <code>java.lang.System.getProperties</code>. | |
| 10602 JNI method invocation may be used to access | |
| 10603 <code>java.lang.System.getProperties</code>. | |
| 10604 <p/> | |
| 10605 The set of properties may grow during execution. | |
| 10606 </description> | |
| 10607 <origin>new</origin> | |
| 10608 <capabilities> | |
| 10609 </capabilities> | |
| 10610 <parameters> | |
| 10611 <param id="count_ptr"> | |
| 10612 <outptr><jint/></outptr> | |
| 10613 <description> | |
| 10614 On return, points to the number of property keys returned. | |
| 10615 </description> | |
| 10616 </param> | |
| 10617 <param id="property_ptr"> | |
| 10618 <allocallocbuf outcount="count_ptr"><char/></allocallocbuf> | |
| 10619 <description> | |
| 10620 On return, points to an array of property keys, encoded as | |
| 10621 <internallink id="mUTF">modified UTF-8</internallink> strings. | |
| 10622 </description> | |
| 10623 </param> | |
| 10624 </parameters> | |
| 10625 <errors> | |
| 10626 </errors> | |
| 10627 </function> | |
| 10628 | |
| 10629 <function id="GetSystemProperty" phase="onload" num="131"> | |
| 10630 <synopsis>Get System Property</synopsis> | |
| 10631 <description> | |
| 10632 Return a VM system property value given the property key. | |
| 10633 <p/> | |
| 10634 The function <functionlink id="GetSystemProperties"/> | |
| 10635 returns the set of property keys which may be used. | |
| 10636 The properties which can be retrieved may grow during | |
| 10637 execution. | |
| 10638 <p/> | |
| 10639 Since this is a VM view of system properties, the values | |
| 10640 of properties may differ from that returned by | |
| 10641 <code>java.lang.System.getProperty(String)</code>. | |
| 10642 A typical VM might copy the values of the VM system | |
| 10643 properties into the <code>Properties</code> held by | |
| 10644 <code>java.lang.System</code> during the initialization | |
| 10645 of that class. Thereafter any changes to the VM system | |
| 10646 properties (with <functionlink id="SetSystemProperty"/>) | |
| 10647 or the <code>java.lang.System</code> system properties | |
| 10648 (with <code>java.lang.System.setProperty(String,String)</code>) | |
| 10649 would cause the values to diverge. | |
| 10650 JNI method invocation may be used to access | |
| 10651 <code>java.lang.System.getProperty(String)</code>. | |
| 10652 </description> | |
| 10653 <origin>new</origin> | |
| 10654 <capabilities> | |
| 10655 </capabilities> | |
| 10656 <parameters> | |
| 10657 <param id="property"> | |
| 10658 <inbuf><char/></inbuf> | |
| 10659 <description> | |
| 10660 The key of the property to retrieve, encoded as a | |
| 10661 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10662 </description> | |
| 10663 </param> | |
| 10664 <param id="value_ptr"> | |
| 10665 <allocbuf><char/></allocbuf> | |
| 10666 <description> | |
| 10667 On return, points to the property value, encoded as a | |
| 10668 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10669 </description> | |
| 10670 </param> | |
| 10671 </parameters> | |
| 10672 <errors> | |
| 10673 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10674 This property is not available. | |
| 10675 Use <functionlink id="GetSystemProperties"/> to find available properties. | |
| 10676 </error> | |
| 10677 </errors> | |
| 10678 </function> | |
| 10679 | |
| 10680 <function id="SetSystemProperty" phase="onloadOnly" num="132"> | |
| 10681 <synopsis>Set System Property</synopsis> | |
| 10682 <description> | |
| 10683 Set a VM system property value. | |
| 10684 <p/> | |
| 10685 The function <functionlink id="GetSystemProperties"/> | |
| 10686 returns the set of property keys, some of these may be settable. | |
| 10687 See <functionlink id="GetSystemProperty"/>. | |
| 10688 </description> | |
| 10689 <origin>new</origin> | |
| 10690 <capabilities> | |
| 10691 </capabilities> | |
| 10692 <parameters> | |
| 10693 <param id="property"> | |
| 10694 <inbuf><char/></inbuf> | |
| 10695 <description> | |
| 10696 The key of the property, encoded as a | |
| 10697 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10698 </description> | |
| 10699 </param> | |
|
2100
b1a2afa37ec4
7003271: Hotspot should track cumulative Java heap bytes allocated on a per-thread basis
phh
parents:
2019
diff
changeset
|
10700 <param id="value_ptr"> |
| 0 | 10701 <inbuf> |
| 10702 <char/> | |
| 10703 <nullok> | |
| 10704 do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/> | |
| 10705 if the property is not writeable | |
| 10706 </nullok> | |
| 10707 </inbuf> | |
| 10708 <description> | |
| 10709 The property value to set, encoded as a | |
| 10710 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10711 </description> | |
| 10712 </param> | |
| 10713 </parameters> | |
| 10714 <errors> | |
| 10715 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10716 This property is not available or is not writeable. | |
| 10717 </error> | |
| 10718 </errors> | |
| 10719 </function> | |
| 10720 | |
| 10721 </category> | |
| 10722 | |
| 10723 <category id="general" label="General"> | |
| 10724 | |
| 10725 <intro> | |
| 10726 </intro> | |
| 10727 | |
| 10728 <function id="GetPhase" jkernel="yes" phase="any" num="133"> | |
| 10729 <synopsis>Get Phase</synopsis> | |
| 10730 <description> | |
| 10731 Return the current phase of VM execution. | |
| 10732 The phases proceed in sequence: | |
| 10733 <constants id="jvmtiPhase" label="Phases of execution" kind="enum"> | |
| 10734 <constant id="JVMTI_PHASE_ONLOAD" num="1"> | |
| 10735 <code>OnLoad</code> phase: while in the | |
| 10736 <internallink id="onload"><code>Agent_OnLoad</code></internallink> function. | |
| 10737 </constant> | |
| 10738 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2"> | |
| 10739 Primordial phase: between return from <code>Agent_OnLoad</code> and the | |
| 10740 <code>VMStart</code> event. | |
| 10741 </constant> | |
| 10742 <constant id="JVMTI_PHASE_START" num="6"> | |
| 10743 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event | |
| 10744 is sent and until the <code>VMInit</code> event is sent. | |
| 10745 </constant> | |
| 10746 <constant id="JVMTI_PHASE_LIVE" num="4"> | |
| 10747 Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent | |
| 10748 and until the <eventlink id="VMDeath"></eventlink> event returns. | |
| 10749 </constant> | |
| 10750 <constant id="JVMTI_PHASE_DEAD" num="8"> | |
| 10751 Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after | |
| 10752 start-up failure. | |
| 10753 </constant> | |
| 10754 </constants> | |
| 10755 In the case of start-up failure the VM will proceed directly to the dead | |
| 10756 phase skipping intermediate phases and neither a <code>VMInit</code> nor | |
| 10757 <code>VMDeath</code> event will be sent. | |
| 10758 <p/> | |
| 10759 Most <jvmti/> functions operate only in the live phase. | |
| 10760 The following functions operate in either the <code>OnLoad</code> or live phases: | |
| 10761 <functionphaselist phase="onload"/> | |
| 10762 The following functions operate in only the <code>OnLoad</code> phase: | |
| 10763 <functionphaselist phase="onloadOnly"/> | |
| 10764 The following functions operate in the start or live phases: | |
| 10765 <functionphaselist phase="start"/> | |
| 10766 The following functions operate in any phase: | |
| 10767 <functionphaselist phase="any"/> | |
| 10768 JNI functions (except the Invocation API) must only be used in the start or live phases. | |
| 10769 <p/> | |
| 10770 Most <jvmti/> events are sent only in the live phase. | |
| 10771 The following events operate in others phases: | |
| 10772 <eventphaselist phase="start"/> | |
| 10773 <eventphaselist phase="any"/> | |
| 10774 </description> | |
| 10775 <origin>new</origin> | |
| 10776 <capabilities> | |
| 10777 </capabilities> | |
| 10778 <parameters> | |
| 10779 <param id="phase_ptr"> | |
| 10780 <outptr><enum>jvmtiPhase</enum></outptr> | |
| 10781 <description> | |
| 10782 On return, points to the phase. | |
| 10783 </description> | |
| 10784 </param> | |
| 10785 </parameters> | |
| 10786 <errors> | |
| 10787 </errors> | |
| 10788 </function> | |
| 10789 | |
| 10790 <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127"> | |
| 10791 <synopsis>Dispose Environment</synopsis> | |
| 10792 <description> | |
| 10793 Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code> | |
| 10794 (see <internallink id="environments"><jvmti/> Environments</internallink>). | |
| 10795 Dispose of any resources held by the environment. | |
| 10796 <issue> | |
| 10797 What resources are reclaimed? What is undone? | |
| 10798 Breakpoints,watchpoints removed? | |
| 10799 </issue> | |
| 10800 Threads suspended by this environment are not resumed by this call, | |
| 10801 this must be done explicitly by the agent. | |
| 10802 Memory allocated by this environment via calls to <jvmti/> functions | |
| 10803 is not released, this can be done explicitly by the agent | |
| 10804 by calling <functionlink id="Deallocate"/>. | |
| 10805 Raw monitors created by this environment are not destroyed, | |
| 10806 this can be done explicitly by the agent | |
| 10807 by calling <functionlink id="DestroyRawMonitor"/>. | |
| 10808 The state of threads waiting on raw monitors created by this environment | |
| 10809 are not affected. | |
| 10810 <p/> | |
| 10811 Any <functionlink id="SetNativeMethodPrefix">native method | |
| 10812 prefixes</functionlink> for this environment will be unset; | |
| 10813 the agent must remove any prefixed native methods before | |
| 10814 dispose is called. | |
| 10815 <p/> | |
| 10816 Any <internallink id="capability">capabilities</internallink> | |
| 10817 held by this environment are relinquished. | |
| 10818 <p/> | |
| 10819 Events enabled by this environment will no longer be sent, however | |
| 10820 event handlers currently running will continue to run. Caution must | |
| 10821 be exercised in the design of event handlers whose environment may | |
| 10822 be disposed and thus become invalid during their execution. | |
| 10823 <p/> | |
| 10824 This environment may not be used after this call. | |
| 10825 This call returns to the caller. | |
| 10826 </description> | |
| 10827 <origin>new</origin> | |
| 10828 <capabilities> | |
| 10829 </capabilities> | |
| 10830 <parameters> | |
| 10831 </parameters> | |
| 10832 <errors> | |
| 10833 </errors> | |
| 10834 </function> | |
| 10835 | |
| 10836 <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148"> | |
| 10837 <synopsis>Set Environment Local Storage</synopsis> | |
| 10838 <description> | |
| 10839 The VM stores a pointer value associated with each environment. | |
| 10840 This pointer value is called <i>environment-local storage</i>. | |
| 10841 This value is <code>NULL</code> unless set with this function. | |
| 10842 Agents can allocate memory in which they store environment specific | |
| 10843 information. By setting environment-local storage it can then be | |
| 10844 accessed with | |
| 10845 <functionlink id="GetEnvironmentLocalStorage"></functionlink>. | |
| 10846 <p/> | |
| 10847 Called by the agent to set the value of the <jvmti/> | |
| 10848 environment-local storage. <jvmti/> supplies to the agent a pointer-size | |
| 10849 environment-local storage that can be used to record per-environment | |
| 10850 information. | |
| 10851 </description> | |
| 10852 <origin>new</origin> | |
| 10853 <capabilities> | |
| 10854 </capabilities> | |
| 10855 <parameters> | |
| 10856 <param id="data"> | |
| 10857 <inbuf> | |
| 10858 <void/> | |
| 10859 <nullok>value is set to <code>NULL</code></nullok> | |
| 10860 </inbuf> | |
| 10861 <description> | |
| 10862 The value to be entered into the environment-local storage. | |
| 10863 </description> | |
| 10864 </param> | |
| 10865 </parameters> | |
| 10866 <errors> | |
| 10867 </errors> | |
| 10868 </function> | |
| 10869 | |
| 10870 <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147"> | |
| 10871 <synopsis>Get Environment Local Storage</synopsis> | |
| 10872 <description> | |
| 10873 Called by the agent to get the value of the <jvmti/> environment-local | |
| 10874 storage. | |
| 10875 </description> | |
| 10876 <origin>new</origin> | |
| 10877 <capabilities> | |
| 10878 </capabilities> | |
| 10879 <parameters> | |
| 10880 <param id="data_ptr"> | |
| 10881 <agentbuf><void/></agentbuf> | |
| 10882 <description> | |
| 10883 Pointer through which the value of the environment local | |
| 10884 storage is returned. | |
| 10885 If environment-local storage has not been set with | |
| 10886 <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned | |
| 10887 pointer is <code>NULL</code>. | |
| 10888 </description> | |
| 10889 </param> | |
| 10890 </parameters> | |
| 10891 <errors> | |
| 10892 </errors> | |
| 10893 </function> | |
| 10894 | |
| 10895 <function id="GetVersionNumber" jkernel="yes" phase="any" num="88"> | |
| 10896 <synopsis>Get Version Number</synopsis> | |
| 10897 <description> | |
| 10898 Return the <jvmti/> version via <code>version_ptr</code>. | |
| 10899 The return value is the version identifier. | |
| 10900 The version identifier includes major, minor and micro | |
| 10901 version as well as the interface type. | |
| 10902 <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits"> | |
| 10903 <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000"> | |
| 10904 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI. | |
| 10905 </constant> | |
| 10906 <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000"> | |
| 10907 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>. | |
| 10908 </constant> | |
| 10909 </constants> | |
| 10910 <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits"> | |
| 10911 <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000"> | |
| 10912 Mask to extract interface type. | |
| 10913 The value of the version returned by this function masked with | |
| 10914 <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always | |
| 10915 <code>JVMTI_VERSION_INTERFACE_JVMTI</code> | |
| 10916 since this is a <jvmti/> function. | |
| 10917 </constant> | |
| 10918 <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000"> | |
| 10919 Mask to extract major version number. | |
| 10920 </constant> | |
| 10921 <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00"> | |
| 10922 Mask to extract minor version number. | |
| 10923 </constant> | |
| 10924 <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF"> | |
| 10925 Mask to extract micro version number. | |
| 10926 </constant> | |
| 10927 </constants> | |
| 10928 <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits"> | |
| 10929 <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16"> | |
| 10930 Shift to extract major version number. | |
| 10931 </constant> | |
| 10932 <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8"> | |
| 10933 Shift to extract minor version number. | |
| 10934 </constant> | |
| 10935 <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0"> | |
| 10936 Shift to extract micro version number. | |
| 10937 </constant> | |
| 10938 </constants> | |
| 10939 </description> | |
| 10940 <origin>jvmdi</origin> | |
| 10941 <capabilities> | |
| 10942 </capabilities> | |
| 10943 <parameters> | |
| 10944 <param id="version_ptr"> | |
| 10945 <outptr><jint/></outptr> | |
| 10946 <description> | |
| 10947 On return, points to the <jvmti/> version. | |
| 10948 </description> | |
| 10949 </param> | |
| 10950 </parameters> | |
| 10951 <errors> | |
| 10952 </errors> | |
| 10953 </function> | |
| 10954 | |
| 10955 | |
| 10956 <function id="GetErrorName" phase="any" num="128"> | |
| 10957 <synopsis>Get Error Name</synopsis> | |
| 10958 <description> | |
| 10959 Return the symbolic name for an | |
| 10960 <internallink id="ErrorSection">error code</internallink>. | |
| 10961 <p/> | |
| 10962 For example | |
| 10963 <code>GetErrorName(env, JVMTI_ERROR_NONE, &err_name)</code> | |
| 10964 would return in <code>err_name</code> the string | |
| 10965 <code>"JVMTI_ERROR_NONE"</code>. | |
| 10966 </description> | |
| 10967 <origin>new</origin> | |
| 10968 <capabilities> | |
| 10969 </capabilities> | |
| 10970 <parameters> | |
| 10971 <param id="error"> | |
| 10972 <enum>jvmtiError</enum> | |
| 10973 <description> | |
| 10974 The error code. | |
| 10975 </description> | |
| 10976 </param> | |
| 10977 <param id="name_ptr"> | |
| 10978 <allocbuf><char/></allocbuf> | |
| 10979 <description> | |
| 10980 On return, points to the error name. | |
| 10981 The name is encoded as a | |
| 10982 <internallink id="mUTF">modified UTF-8</internallink> string, | |
| 10983 but is restricted to the ASCII subset. | |
| 10984 </description> | |
| 10985 </param> | |
| 10986 </parameters> | |
| 10987 <errors> | |
| 10988 </errors> | |
| 10989 </function> | |
| 10990 | |
| 10991 <function id="SetVerboseFlag" phase="any" num="150"> | |
| 10992 <synopsis>Set Verbose Flag</synopsis> | |
| 10993 <description> | |
| 10994 <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum"> | |
| 10995 <constant id="JVMTI_VERBOSE_OTHER" num="0"> | |
| 10996 Verbose output other than the below. | |
| 10997 </constant> | |
| 10998 <constant id="JVMTI_VERBOSE_GC" num="1"> | |
| 10999 Verbose garbage collector output, like that specified with <code>-verbose:gc</code>. | |
| 11000 </constant> | |
| 11001 <constant id="JVMTI_VERBOSE_CLASS" num="2"> | |
| 11002 Verbose class loading output, like that specified with <code>-verbose:class</code>. | |
| 11003 </constant> | |
| 11004 <constant id="JVMTI_VERBOSE_JNI" num="4"> | |
| 11005 Verbose JNI output, like that specified with <code>-verbose:jni</code>. | |
| 11006 </constant> | |
| 11007 </constants> | |
| 11008 Control verbose output. | |
| 11009 This is the output which typically is sent to <code>stderr</code>. | |
| 11010 </description> | |
| 11011 <origin>new</origin> | |
| 11012 <capabilities> | |
| 11013 </capabilities> | |
| 11014 <parameters> | |
| 11015 <param id="flag"> | |
| 11016 <enum>jvmtiVerboseFlag</enum> | |
| 11017 <description> | |
| 11018 Which verbose flag to set. | |
| 11019 </description> | |
| 11020 </param> | |
| 11021 <param id="value"> | |
| 11022 <jboolean/> | |
| 11023 <description> | |
| 11024 New value of the flag. | |
| 11025 </description> | |
| 11026 </param> | |
| 11027 </parameters> | |
| 11028 <errors> | |
| 11029 </errors> | |
| 11030 </function> | |
| 11031 | |
| 11032 | |
| 11033 <function id="GetJLocationFormat" phase="any" num="129"> | |
| 11034 <synopsis>Get JLocation Format</synopsis> | |
| 11035 <description> | |
| 11036 Although the greatest functionality is achieved with location information | |
| 11037 referencing the virtual machine bytecode index, the definition of | |
| 11038 <code>jlocation</code> has intentionally been left unconstrained to allow VM | |
| 11039 implementations that do not have this information. | |
| 11040 <p/> | |
| 11041 This function describes the representation of <code>jlocation</code> used in this VM. | |
| 11042 If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>, | |
| 11043 <code>jlocation</code>s can | |
| 11044 be used as in indices into the array returned by | |
| 11045 <functionlink id="GetBytecodes"></functionlink>. | |
| 11046 <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum"> | |
| 11047 <constant id="JVMTI_JLOCATION_JVMBCI" num="1"> | |
| 11048 <code>jlocation</code> values represent virtual machine | |
| 11049 bytecode indices--that is, offsets into the | |
| 11050 virtual machine code for a method. | |
| 11051 </constant> | |
| 11052 <constant id="JVMTI_JLOCATION_MACHINEPC" num="2"> | |
| 11053 <code>jlocation</code> values represent native machine | |
| 11054 program counter values. | |
| 11055 </constant> | |
| 11056 <constant id="JVMTI_JLOCATION_OTHER" num="0"> | |
| 11057 <code>jlocation</code> values have some other representation. | |
| 11058 </constant> | |
| 11059 </constants> | |
| 11060 </description> | |
| 11061 <origin>new</origin> | |
| 11062 <capabilities> | |
| 11063 </capabilities> | |
| 11064 <parameters> | |
| 11065 <param id="format_ptr"> | |
| 11066 <outptr><enum>jvmtiJlocationFormat</enum></outptr> | |
| 11067 <description> | |
| 11068 On return, points to the format identifier for <code>jlocation</code> values. | |
| 11069 </description> | |
| 11070 </param> | |
| 11071 </parameters> | |
| 11072 <errors> | |
| 11073 </errors> | |
| 11074 </function> | |
| 11075 | |
| 11076 </category> | |
| 11077 | |
| 11078 </functionsection> | |
| 11079 | |
| 11080 <errorsection label="Error Reference"> | |
| 11081 <intro> | |
| 11082 Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code. | |
| 11083 <p/> | |
| 11084 It is the responsibility of the agent to call <jvmti/> functions with | |
| 11085 valid parameters and in the proper context (calling thread is attached, | |
| 11086 phase is correct, etc.). | |
| 11087 Detecting some error conditions may be difficult, inefficient, or | |
| 11088 impossible for an implementation. | |
| 11089 The errors listed in | |
| 11090 <internallink id="reqerrors">Function Specific Required Errors</internallink> | |
| 11091 must be detected by the implementation. | |
| 11092 All other errors represent the recommended response to the error | |
| 11093 condition. | |
| 11094 </intro> | |
| 11095 | |
| 11096 <errorcategory id="universal-error" label="Universal Errors"> | |
| 11097 <intro> | |
| 11098 The following errors may be returned by any function | |
| 11099 </intro> | |
| 11100 | |
| 11101 <errorid id="JVMTI_ERROR_NONE" num="0"> | |
| 11102 No error has occurred. This is the error code that is returned | |
| 11103 on successful completion of the function. | |
| 11104 </errorid> | |
| 11105 <errorid id="JVMTI_ERROR_NULL_POINTER" num="100"> | |
| 11106 Pointer is unexpectedly <code>NULL</code>. | |
| 11107 </errorid> | |
| 11108 <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110"> | |
| 11109 The function attempted to allocate memory and no more memory was | |
| 11110 available for allocation. | |
| 11111 </errorid> | |
| 11112 <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111"> | |
| 11113 The desired functionality has not been enabled in this virtual machine. | |
| 11114 </errorid> | |
| 11115 <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115"> | |
| 11116 The thread being used to call this function is not attached | |
| 11117 to the virtual machine. Calls must be made from attached threads. | |
| 11118 See <code>AttachCurrentThread</code> in the JNI invocation API. | |
| 11119 </errorid> | |
| 11120 <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116"> | |
| 11121 The <jvmti/> environment provided is no longer connected or is | |
| 11122 not an environment. | |
| 11123 </errorid> | |
| 11124 <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112"> | |
| 11125 The desired functionality is not available in the current | |
| 11126 <functionlink id="GetPhase">phase</functionlink>. | |
| 11127 Always returned if the virtual machine has completed running. | |
| 11128 </errorid> | |
| 11129 <errorid id="JVMTI_ERROR_INTERNAL" num="113"> | |
| 11130 An unexpected internal error has occurred. | |
| 11131 </errorid> | |
| 11132 </errorcategory> | |
| 11133 | |
| 11134 <errorcategory id="reqerrors" label="Function Specific Required Errors"> | |
| 11135 <intro> | |
| 11136 The following errors are returned by some <jvmti/> functions and must | |
| 11137 be returned by the implementation when the condition occurs. | |
| 11138 </intro> | |
| 11139 | |
| 11140 <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12"> | |
| 11141 Invalid priority. | |
| 11142 </errorid> | |
| 11143 <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13"> | |
| 11144 Thread was not suspended. | |
| 11145 </errorid> | |
| 11146 <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14"> | |
| 11147 Thread already suspended. | |
| 11148 </errorid> | |
| 11149 <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15"> | |
| 11150 This operation requires the thread to be alive--that is, | |
| 11151 it must be started and not yet have died. | |
| 11152 </errorid> | |
| 11153 <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22"> | |
| 11154 The class has been loaded but not yet prepared. | |
| 11155 </errorid> | |
| 11156 <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31"> | |
| 11157 There are no Java programming language or JNI stack frames at the specified depth. | |
| 11158 </errorid> | |
| 11159 <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32"> | |
| 11160 Information about the frame is not available (e.g. for native frames). | |
| 11161 </errorid> | |
| 11162 <errorid id="JVMTI_ERROR_DUPLICATE" num="40"> | |
| 11163 Item already set. | |
| 11164 </errorid> | |
| 11165 <errorid id="JVMTI_ERROR_NOT_FOUND" num="41"> | |
| 11166 Desired element (e.g. field or breakpoint) not found | |
| 11167 </errorid> | |
| 11168 <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51"> | |
| 11169 This thread doesn't own the raw monitor. | |
| 11170 </errorid> | |
| 11171 <errorid id="JVMTI_ERROR_INTERRUPT" num="52"> | |
| 11172 The call has been interrupted before completion. | |
| 11173 </errorid> | |
| 11174 <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79"> | |
| 11175 The class cannot be modified. | |
| 11176 </errorid> | |
| 11177 <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98"> | |
| 11178 The functionality is not available in this virtual machine. | |
| 11179 </errorid> | |
| 11180 <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101"> | |
| 11181 The requested information is not available. | |
| 11182 </errorid> | |
| 11183 <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102"> | |
| 11184 The specified event type ID is not recognized. | |
| 11185 </errorid> | |
| 11186 <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104"> | |
| 11187 The requested information is not available for native method. | |
| 11188 </errorid> | |
| 11189 <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106"> | |
| 11190 The class loader does not support this operation. | |
| 11191 </errorid> | |
| 11192 </errorcategory> | |
| 11193 | |
| 11194 <errorcategory id="function-specific-errors" label="Function Specific Agent Errors"> | |
| 11195 <intro> | |
| 11196 The following errors are returned by some <jvmti/> functions. | |
| 11197 They are returned in the event of invalid parameters passed by the | |
| 11198 agent or usage in an invalid context. | |
| 11199 An implementation is not required to detect these errors. | |
| 11200 </intro> | |
| 11201 | |
| 11202 <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10"> | |
| 11203 The passed thread is not a valid thread. | |
| 11204 </errorid> | |
| 11205 <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25"> | |
| 11206 Invalid field. | |
| 11207 </errorid> | |
| 11208 <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23"> | |
| 11209 Invalid method. | |
| 11210 </errorid> | |
| 11211 <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24"> | |
| 11212 Invalid location. | |
| 11213 </errorid> | |
| 11214 <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20"> | |
| 11215 Invalid object. | |
| 11216 </errorid> | |
| 11217 <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21"> | |
| 11218 Invalid class. | |
| 11219 </errorid> | |
| 11220 <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34"> | |
| 11221 The variable is not an appropriate type for the function used. | |
| 11222 </errorid> | |
| 11223 <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35"> | |
| 11224 Invalid slot. | |
| 11225 </errorid> | |
| 11226 <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99"> | |
| 11227 The capability being used is false in this environment. | |
| 11228 </errorid> | |
| 11229 <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11"> | |
| 11230 Thread group invalid. | |
| 11231 </errorid> | |
| 11232 <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50"> | |
| 11233 Invalid raw monitor. | |
| 11234 </errorid> | |
| 11235 <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103"> | |
| 11236 Illegal argument. | |
| 11237 </errorid> | |
| 11238 <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65"> | |
| 11239 The state of the thread has been modified, and is now inconsistent. | |
| 11240 </errorid> | |
| 11241 <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68"> | |
| 11242 A new class file has a version number not supported by this VM. | |
| 11243 </errorid> | |
| 11244 <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60"> | |
| 11245 A new class file is malformed (the VM would return a <code>ClassFormatError</code>). | |
| 11246 </errorid> | |
| 11247 <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61"> | |
| 11248 The new class file definitions would lead to a circular | |
| 11249 definition (the VM would return a <code>ClassCircularityError</code>). | |
| 11250 </errorid> | |
| 11251 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63"> | |
| 11252 A new class file would require adding a method. | |
| 11253 </errorid> | |
| 11254 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64"> | |
| 11255 A new class version changes a field. | |
| 11256 </errorid> | |
| 11257 <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62"> | |
| 11258 The class bytes fail verification. | |
| 11259 </errorid> | |
| 11260 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66"> | |
| 11261 A direct superclass is different for the new class | |
| 11262 version, or the set of directly implemented | |
| 11263 interfaces is different. | |
| 11264 </errorid> | |
| 11265 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67"> | |
| 11266 A new class version does not declare a method | |
| 11267 declared in the old class version. | |
| 11268 </errorid> | |
| 11269 <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69"> | |
| 11270 The class name defined in the new class file is | |
| 11271 different from the name in the old class object. | |
| 11272 </errorid> | |
| 11273 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70"> | |
| 11274 A new class version has different modifiers. | |
| 11275 </errorid> | |
| 11276 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71"> | |
| 11277 A method in the new class version has different modifiers | |
| 11278 than its counterpart in the old class version. | |
| 11279 </errorid> | |
| 11280 </errorcategory> | |
| 11281 </errorsection> | |
| 11282 | |
| 11283 <eventsection label="Events"> | |
| 11284 <intro label="Handling Events" id="eventIntro"> | |
| 11285 Agents can be informed of many events that occur in application | |
| 11286 programs. | |
| 11287 <p/> | |
| 11288 To handle events, designate a set of callback functions with | |
| 11289 <functionlink id="SetEventCallbacks"></functionlink>. | |
| 11290 For each event the corresponding callback function will be | |
| 11291 called. | |
| 11292 Arguments to the callback function provide additional | |
| 11293 information about the event. | |
| 11294 <p/> | |
| 11295 The callback function is usually called from within an application | |
| 11296 thread. The <jvmti/> implementation does not | |
| 11297 queue events in any way. This means | |
| 11298 that event callback functions must be written | |
| 11299 carefully. Here are some general guidelines. See | |
| 11300 the individual event descriptions for further | |
| 11301 suggestions. | |
| 11302 <p/> | |
| 11303 <ul> | |
| 11304 <li>Any exception thrown during the execution of an event callback can | |
| 11305 overwrite any current pending exception in the current application thread. | |
| 11306 Care must be taken to preserve a pending exception | |
| 11307 when an event callback makes a JNI call that might generate an exception. | |
| 11308 </li> | |
| 11309 <li>Event callback functions must be re-entrant. The <jvmti/> implementation does | |
| 11310 not queue events. If an agent needs to process events one at a time, it | |
| 11311 can use a raw monitor inside the | |
| 11312 event callback functions to serialize event processing. | |
| 11313 </li> | |
| 11314 <li>Event callback functions that execute JNI's FindClass function to load | |
| 11315 classes need to note that FindClass locates the class loader associated | |
| 11316 with the current native method. For the purposes of class loading, an | |
| 11317 event callback that includes a JNI environment as a parameter to the | |
| 11318 callback will treated as if it is a native call, where the native method | |
| 11319 is in the class of the event thread's current frame. | |
| 11320 </li> | |
| 11321 </ul> | |
| 11322 <p/> | |
| 11323 Some <jvmti/> events identify objects with JNI references. | |
| 11324 All references | |
| 11325 in <jvmti/> events are JNI local references and will become invalid | |
| 11326 after the event callback returns. | |
| 11327 Unless stated otherwise, memory referenced by pointers sent in event | |
| 11328 callbacks may not be referenced after the event callback returns. | |
| 11329 <p/> | |
| 11330 Except where stated otherwise, events are delivered on the thread | |
| 11331 that caused the event. | |
| 11332 Events are sent at the time they occur. | |
| 11333 The specification for each event includes the set of | |
| 11334 <functionlink id="GetPhase">phases</functionlink> in which it can be sent; | |
| 11335 if an event triggering activity occurs during another phase, no event | |
| 11336 is sent. | |
| 11337 <p/> | |
| 11338 A thread that generates an event does not change its execution status | |
| 11339 (for example, the event does not cause the thread to be suspended). | |
| 11340 If an agent wishes the event to result in suspension, then the agent | |
| 11341 is responsible for explicitly suspending the thread with | |
| 11342 <functionlink id="SuspendThread"></functionlink>. | |
| 11343 <p/> | |
| 11344 If an event is enabled in multiple environments, the event will be sent | |
| 11345 to each agent in the order that the environments were created. | |
| 11346 </intro> | |
| 11347 | |
| 11348 <intro label="Enabling Events" id="enablingevents"> | |
| 11349 All events are initially disabled. In order to receive any | |
| 11350 event: | |
| 11351 <ul> | |
| 11352 <li> | |
| 11353 If the event requires a capability, that capability must | |
| 11354 be added with | |
| 11355 <functionlink id="AddCapabilities"></functionlink>. | |
| 11356 </li> | |
| 11357 <li> | |
| 11358 A callback for the event must be set with | |
| 11359 <functionlink id="SetEventCallbacks"></functionlink>. | |
| 11360 </li> | |
| 11361 <li> | |
| 11362 The event must be enabled with | |
| 11363 <functionlink id="SetEventNotificationMode"></functionlink>. | |
| 11364 </li> | |
| 11365 </ul> | |
| 11366 </intro> | |
| 11367 | |
| 11368 <intro label="Multiple Co-located Events" id="eventorder"> | |
| 11369 In many situations it is possible for multiple events to occur | |
| 11370 at the same location in one thread. When this happens, all the events | |
| 11371 are reported through the event callbacks in the order specified in this section. | |
| 11372 <p/> | |
| 11373 If the current location is at the entry point of a method, the | |
| 11374 <eventlink id="MethodEntry"></eventlink> event is reported before | |
| 11375 any other event at the current location in the same thread. | |
| 11376 <p/> | |
| 11377 If an exception catch has been detected at the current location, | |
| 11378 either because it is the beginning of a catch clause or a native method | |
| 11379 that cleared a pending exception has returned, the | |
| 11380 <code>exceptionCatch</code> event is reported before | |
| 11381 any other event at the current location in the same thread. | |
| 11382 <p/> | |
| 11383 If a <code>singleStep</code> event or | |
| 11384 <code>breakpoint</code> event is triggered at the | |
| 11385 current location, the event is defined to occur | |
| 11386 immediately before the code at the current location is executed. | |
| 11387 These events are reported before any events which are triggered | |
| 11388 by the execution of code at the current location in the same | |
| 11389 thread (specifically: | |
| 11390 <code>exception</code>, | |
| 11391 <code>fieldAccess</code>, and | |
| 11392 <code>fieldModification</code>). | |
| 11393 If both a step and breakpoint event are triggered for the same thread and | |
| 11394 location, the step event is reported before the breakpoint event. | |
| 11395 <p/> | |
| 11396 If the current location is the exit point of a method (that is, the last | |
| 11397 location before returning to the caller), the | |
| 11398 <eventlink id="MethodExit"></eventlink> event and | |
| 11399 the <eventlink id="FramePop"></eventlink> event (if requested) | |
| 11400 are reported after all other events at the current location in the same | |
| 11401 thread. There is no specified ordering of these two events | |
| 11402 with respect to each other. | |
| 11403 <p/> | |
| 11404 Co-located events can be triggered during the processing of some other | |
| 11405 event by the agent at the same location in the same thread. | |
| 11406 If such an event, of type <i>y</i>, is triggered during the processing of | |
| 11407 an event of type <i>x</i>, and if <i>x</i> | |
| 11408 precedes <i>y</i> in the ordering specified above, the co-located event | |
| 11409 <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede | |
| 11410 <i>y</i>, <i>y</i> is not reported for the current thread and location. | |
| 11411 For example, if a breakpoint is set at the current location | |
| 11412 during the processing of <eventlink id="SingleStep"></eventlink>, | |
| 11413 that breakpoint will be reported before the thread moves off the current | |
| 11414 location. | |
| 11415 <p/>The following events are never considered to be co-located with | |
| 11416 other events. | |
| 11417 <ul> | |
| 11418 <li><eventlink id="VMStart"></eventlink></li> | |
| 11419 <li><eventlink id="VMInit"></eventlink></li> | |
| 11420 <li><eventlink id="VMDeath"></eventlink></li> | |
| 11421 <li><eventlink id="ThreadStart"></eventlink></li> | |
| 11422 <li><eventlink id="ThreadEnd"></eventlink></li> | |
| 11423 <li><eventlink id="ClassLoad"></eventlink></li> | |
| 11424 <li><eventlink id="ClassPrepare"></eventlink></li> | |
| 11425 </ul> | |
| 11426 </intro> | |
| 11427 | |
| 11428 <intro label="Event Callbacks" id="jvmtiEventCallbacks"> | |
| 11429 The event callback structure below is used to specify the handler function | |
| 11430 for events. It is set with the | |
| 11431 <functionlink id="SetEventCallbacks"></functionlink> function. | |
| 11432 </intro> | |
| 11433 | |
| 11434 <event label="Single Step" | |
| 11435 id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60"> | |
| 11436 <description> | |
| 11437 Single step events allow the agent to trace thread execution | |
| 11438 at the finest granularity allowed by the VM. A single step event is | |
| 11439 generated whenever a thread reaches a new location. | |
| 11440 Typically, single step events represent the completion of one VM | |
| 11441 instruction as defined in the <vmspeclink/>. However, some implementations | |
| 11442 may define locations differently. In any case the | |
| 11443 <code>method</code> and <code>location</code> | |
| 11444 parameters uniquely identify the current location and allow | |
| 11445 the mapping to source file and line number when that information is | |
| 11446 available. | |
| 11447 <p/> | |
| 11448 No single step events are generated from within native methods. | |
| 11449 </description> | |
| 11450 <origin>jvmdi</origin> | |
| 11451 <capabilities> | |
| 11452 <required id="can_generate_single_step_events"></required> | |
| 11453 </capabilities> | |
| 11454 <parameters> | |
| 11455 <param id="jni_env"> | |
| 11456 <outptr> | |
| 11457 <struct>JNIEnv</struct> | |
| 11458 </outptr> | |
| 11459 <description> | |
| 11460 The JNI environment of the event (current) thread | |
| 11461 </description> | |
| 11462 </param> | |
| 11463 <param id="thread"> | |
| 11464 <jthread/> | |
| 11465 <description> | |
| 11466 Thread about to execution a new instruction | |
| 11467 </description> | |
| 11468 </param> | |
| 11469 <param id="klass"> | |
| 11470 <jclass method="method"/> | |
| 11471 <description> | |
| 11472 Class of the method about to execute a new instruction | |
| 11473 </description> | |
| 11474 </param> | |
| 11475 <param id="method"> | |
| 11476 <jmethodID class="klass"/> | |
| 11477 <description> | |
| 11478 Method about to execute a new instruction | |
| 11479 </description> | |
| 11480 </param> | |
| 11481 <param id="location"> | |
| 11482 <jlocation/> | |
| 11483 <description> | |
| 11484 Location of the new instruction | |
| 11485 </description> | |
| 11486 </param> | |
| 11487 </parameters> | |
| 11488 </event> | |
| 11489 | |
| 11490 <event label="Breakpoint" | |
| 11491 id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62"> | |
| 11492 <description> | |
| 11493 Breakpoint events are generated whenever a thread reaches a location | |
| 11494 designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>. | |
| 11495 The <code>method</code> and <code>location</code> | |
| 11496 parameters uniquely identify the current location and allow | |
| 11497 the mapping to source file and line number when that information is | |
| 11498 available. | |
| 11499 </description> | |
| 11500 <origin>jvmdi</origin> | |
| 11501 <capabilities> | |
| 11502 <required id="can_generate_breakpoint_events"></required> | |
| 11503 </capabilities> | |
| 11504 <parameters> | |
| 11505 <param id="jni_env"> | |
| 11506 <outptr> | |
| 11507 <struct>JNIEnv</struct> | |
| 11508 </outptr> | |
| 11509 <description> | |
| 11510 The JNI environment of the event (current) thread. | |
| 11511 </description> | |
| 11512 </param> | |
| 11513 <param id="thread"> | |
| 11514 <jthread/> | |
| 11515 <description> | |
| 11516 Thread that hit the breakpoint | |
| 11517 </description> | |
| 11518 </param> | |
| 11519 <param id="klass"> | |
| 11520 <jclass method="method"/> | |
| 11521 <description> | |
| 11522 Class of the method that hit the breakpoint | |
| 11523 </description> | |
| 11524 </param> | |
| 11525 <param id="method"> | |
| 11526 <jmethodID class="klass"/> | |
| 11527 <description> | |
| 11528 Method that hit the breakpoint | |
| 11529 </description> | |
| 11530 </param> | |
| 11531 <param id="location"> | |
| 11532 <jlocation/> | |
| 11533 <description> | |
| 11534 location of the breakpoint | |
| 11535 </description> | |
| 11536 </param> | |
| 11537 </parameters> | |
| 11538 </event> | |
| 11539 | |
| 11540 <event label="Field Access" | |
| 11541 id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63"> | |
| 11542 <description> | |
| 11543 Field access events are generated whenever a thread accesses | |
| 11544 a field that was designated as a watchpoint | |
| 11545 with <functionlink id="SetFieldAccessWatch"></functionlink>. | |
| 11546 The <code>method</code> and <code>location</code> | |
| 11547 parameters uniquely identify the current location and allow | |
| 11548 the mapping to source file and line number when that information is | |
| 11549 available. | |
| 11550 </description> | |
| 11551 <origin>jvmdi</origin> | |
| 11552 <capabilities> | |
| 11553 <required id="can_generate_field_access_events"></required> | |
| 11554 </capabilities> | |
| 11555 <parameters> | |
| 11556 <param id="jni_env"> | |
| 11557 <outptr> | |
| 11558 <struct>JNIEnv</struct> | |
| 11559 </outptr> | |
| 11560 <description> | |
| 11561 The JNI environment of the event (current) thread | |
| 11562 </description> | |
| 11563 </param> | |
| 11564 <param id="thread"> | |
| 11565 <jthread/> | |
| 11566 <description> | |
| 11567 Thread accessing the field | |
| 11568 </description> | |
| 11569 </param> | |
| 11570 <param id="klass"> | |
| 11571 <jclass method="method"/> | |
| 11572 <description> | |
| 11573 Class of the method where the access is occurring | |
| 11574 </description> | |
| 11575 </param> | |
| 11576 <param id="method"> | |
| 11577 <jmethodID class="klass"/> | |
| 11578 <description> | |
| 11579 Method where the access is occurring | |
| 11580 </description> | |
| 11581 </param> | |
| 11582 <param id="location"> | |
| 11583 <jlocation/> | |
| 11584 <description> | |
| 11585 Location where the access is occurring | |
| 11586 </description> | |
| 11587 </param> | |
| 11588 <param id="field_klass"> | |
| 11589 <jclass field="field"/> | |
| 11590 <description> | |
| 11591 Class of the field being accessed | |
| 11592 </description> | |
| 11593 </param> | |
| 11594 <param id="object"> | |
| 11595 <jobject/> | |
| 11596 <description> | |
| 11597 Object with the field being accessed if the field is an | |
| 11598 instance field; <code>NULL</code> otherwise | |
| 11599 </description> | |
| 11600 </param> | |
| 11601 <param id="field"> | |
| 11602 <jfieldID class="field_klass"/> | |
| 11603 <description> | |
| 11604 Field being accessed | |
| 11605 </description> | |
| 11606 </param> | |
| 11607 </parameters> | |
| 11608 </event> | |
| 11609 | |
| 11610 <event label="Field Modification" | |
| 11611 id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64"> | |
| 11612 <description> | |
| 11613 Field modification events are generated whenever a thread modifies | |
| 11614 a field that was designated as a watchpoint | |
| 11615 with <functionlink id="SetFieldModificationWatch"></functionlink>. | |
| 11616 The <code>method</code> and <code>location</code> | |
| 11617 parameters uniquely identify the current location and allow | |
| 11618 the mapping to source file and line number when that information is | |
| 11619 available. | |
| 11620 </description> | |
| 11621 <origin>jvmdi</origin> | |
| 11622 <capabilities> | |
| 11623 <required id="can_generate_field_modification_events"></required> | |
| 11624 </capabilities> | |
| 11625 <parameters> | |
| 11626 <param id="jni_env"> | |
| 11627 <outptr> | |
| 11628 <struct>JNIEnv</struct> | |
| 11629 </outptr> | |
| 11630 <description> | |
| 11631 The JNI environment of the event (current) thread | |
| 11632 </description> | |
| 11633 </param> | |
| 11634 <param id="thread"> | |
| 11635 <jthread/> | |
| 11636 <description> | |
| 11637 Thread modifying the field | |
| 11638 </description> | |
| 11639 </param> | |
| 11640 <param id="klass"> | |
| 11641 <jclass method="method"/> | |
| 11642 <description> | |
| 11643 Class of the method where the modification is occurring | |
| 11644 </description> | |
| 11645 </param> | |
| 11646 <param id="method"> | |
| 11647 <jmethodID class="klass"/> | |
| 11648 <description> | |
| 11649 Method where the modification is occurring | |
| 11650 </description> | |
| 11651 </param> | |
| 11652 <param id="location"> | |
| 11653 <jlocation/> | |
| 11654 <description> | |
| 11655 Location where the modification is occurring | |
| 11656 </description> | |
| 11657 </param> | |
| 11658 <param id="field_klass"> | |
| 11659 <jclass field="field"/> | |
| 11660 <description> | |
| 11661 Class of the field being modified | |
| 11662 </description> | |
| 11663 </param> | |
| 11664 <param id="object"> | |
| 11665 <jobject/> | |
| 11666 <description> | |
| 11667 Object with the field being modified if the field is an | |
| 11668 instance field; <code>NULL</code> otherwise | |
| 11669 </description> | |
| 11670 </param> | |
| 11671 <param id="field"> | |
| 11672 <jfieldID class="field_klass"/> | |
| 11673 <description> | |
| 11674 Field being modified | |
| 11675 </description> | |
| 11676 </param> | |
| 11677 <param id="signature_type"> | |
| 11678 <char/> | |
| 11679 <description> | |
| 11680 Signature type of the new value | |
| 11681 </description> | |
| 11682 </param> | |
| 11683 <param id="new_value"> | |
| 11684 <jvalue/> | |
| 11685 <description> | |
| 11686 The new value | |
| 11687 </description> | |
| 11688 </param> | |
| 11689 </parameters> | |
| 11690 </event> | |
| 11691 | |
| 11692 <event label="Frame Pop" | |
| 11693 id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61"> | |
| 11694 <description> | |
| 11695 Frame pop events are generated upon exit from a single method | |
| 11696 in a single frame as specified | |
| 11697 in a call to <functionlink id="NotifyFramePop"></functionlink>. | |
| 11698 This is true whether termination is caused by | |
| 11699 executing its return instruction | |
| 11700 or by throwing an exception to its caller | |
| 11701 (see <paramlink id="was_popped_by_exception"></paramlink>). | |
| 11702 However, frame pops caused by the <functionlink id="PopFrame"/> | |
| 11703 function are not reported. | |
| 11704 <p/> | |
| 11705 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
| 11706 identifies the executable location in the returning method, | |
| 11707 immediately prior to the return. | |
| 11708 </description> | |
| 11709 <origin>jvmdi</origin> | |
| 11710 <capabilities> | |
| 11711 <required id="can_generate_frame_pop_events"></required> | |
| 11712 </capabilities> | |
| 11713 <parameters> | |
| 11714 <param id="jni_env"> | |
| 11715 <outptr> | |
| 11716 <struct>JNIEnv</struct> | |
| 11717 </outptr> | |
| 11718 <description> | |
| 11719 The JNI environment of the event (current) thread | |
| 11720 </description> | |
| 11721 </param> | |
| 11722 <param id="thread"> | |
| 11723 <jthread/> | |
| 11724 <description> | |
| 11725 Thread that is popping the frame | |
| 11726 </description> | |
| 11727 </param> | |
| 11728 <param id="klass"> | |
| 11729 <jclass method="method"/> | |
| 11730 <description> | |
| 11731 Class of the method being popped | |
| 11732 </description> | |
| 11733 </param> | |
| 11734 <param id="method"> | |
| 11735 <jmethodID class="klass"/> | |
| 11736 <description> | |
| 11737 Method being popped | |
| 11738 </description> | |
| 11739 </param> | |
| 11740 <param id="was_popped_by_exception"> | |
| 11741 <jboolean/> | |
| 11742 <description> | |
| 11743 True if frame was popped by a thrown exception. | |
| 11744 False if method exited through its return instruction. | |
| 11745 </description> | |
| 11746 </param> | |
| 11747 </parameters> | |
| 11748 </event> | |
| 11749 | |
| 11750 <event label="Method Entry" | |
| 11751 id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65"> | |
| 11752 <description> | |
| 11753 Method entry events are generated upon entry of Java | |
| 11754 programming language methods (including native methods). | |
| 11755 <p/> | |
| 11756 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
| 11757 identifies the initial executable location in | |
| 11758 the method. | |
| 11759 <p/> | |
| 11760 Enabling method | |
| 11761 entry or exit events will significantly degrade performance on many platforms and is thus | |
| 11762 not advised for performance critical usage (such as profiling). | |
| 11763 <internallink id="bci">Bytecode instrumentation</internallink> should be | |
| 11764 used in these cases. | |
| 11765 </description> | |
| 11766 <origin>jvmdi</origin> | |
| 11767 <capabilities> | |
| 11768 <required id="can_generate_method_entry_events"></required> | |
| 11769 </capabilities> | |
| 11770 <parameters> | |
| 11771 <param id="jni_env"> | |
| 11772 <outptr> | |
| 11773 <struct>JNIEnv</struct> | |
| 11774 </outptr> | |
| 11775 <description> | |
| 11776 The JNI environment of the event (current) thread | |
| 11777 </description> | |
| 11778 </param> | |
| 11779 <param id="thread"> | |
| 11780 <jthread/> | |
| 11781 <description> | |
| 11782 Thread entering the method | |
| 11783 </description> | |
| 11784 </param> | |
| 11785 <param id="klass"> | |
| 11786 <jclass method="method"/> | |
| 11787 <description> | |
| 11788 Class of the method being entered | |
| 11789 </description> | |
| 11790 </param> | |
| 11791 <param id="method"> | |
| 11792 <jmethodID class="klass"/> | |
| 11793 <description> | |
| 11794 Method being entered | |
| 11795 </description> | |
| 11796 </param> | |
| 11797 </parameters> | |
| 11798 </event> | |
| 11799 | |
| 11800 <event label="Method Exit" | |
| 11801 id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66"> | |
| 11802 <description> | |
| 11803 Method exit events are generated upon exit from Java | |
| 11804 programming language methods (including native methods). | |
| 11805 This is true whether termination is caused by | |
| 11806 executing its return instruction | |
| 11807 or by throwing an exception to its caller | |
| 11808 (see <paramlink id="was_popped_by_exception"></paramlink>). | |
| 11809 <p/> | |
| 11810 The <code>method</code> field uniquely identifies the | |
| 11811 method being entered or exited. The <code>frame</code> field provides | |
| 11812 access to the stack frame for the method. | |
| 11813 <p/> | |
| 11814 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
| 11815 identifies the executable location in the returning method | |
| 11816 immediately prior to the return. | |
| 11817 <p/> | |
| 11818 Enabling method | |
| 11819 entry or exit events will significantly degrade performance on many platforms and is thus | |
| 11820 not advised for performance critical usage (such as profiling). | |
| 11821 <internallink id="bci">Bytecode instrumentation</internallink> should be | |
| 11822 used in these cases. | |
| 11823 </description> | |
| 11824 <origin>jvmdi</origin> | |
| 11825 <capabilities> | |
| 11826 <required id="can_generate_method_exit_events"></required> | |
| 11827 </capabilities> | |
| 11828 <parameters> | |
| 11829 <param id="jni_env"> | |
| 11830 <outptr> | |
| 11831 <struct>JNIEnv</struct> | |
| 11832 </outptr> | |
| 11833 <description> | |
| 11834 The JNI environment of the event (current) thread | |
| 11835 </description> | |
| 11836 </param> | |
| 11837 <param id="thread"> | |
| 11838 <jthread/> | |
| 11839 <description> | |
| 11840 Thread exiting the method | |
| 11841 </description> | |
| 11842 </param> | |
| 11843 <param id="klass"> | |
| 11844 <jclass method="method"/> | |
| 11845 <description> | |
| 11846 Class of the method being exited | |
| 11847 </description> | |
| 11848 </param> | |
| 11849 <param id="method"> | |
| 11850 <jmethodID class="klass"/> | |
| 11851 <description> | |
| 11852 Method being exited | |
| 11853 </description> | |
| 11854 </param> | |
| 11855 <param id="was_popped_by_exception"> | |
| 11856 <jboolean/> | |
| 11857 <description> | |
| 11858 True if frame was popped by a thrown exception. | |
| 11859 False if method exited through its return instruction. | |
| 11860 </description> | |
| 11861 </param> | |
| 11862 <param id="return_value"> | |
| 11863 <jvalue/> | |
| 11864 <description> | |
| 11865 The return value of the method being exited. | |
| 11866 Undefined and should not be used if | |
| 11867 <paramlink id="was_popped_by_exception"></paramlink> | |
| 11868 is true. | |
| 11869 </description> | |
| 11870 </param> | |
| 11871 </parameters> | |
| 11872 </event> | |
| 11873 | |
| 11874 <event label="Native Method Bind" phase="any" | |
| 11875 id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67"> | |
| 11876 <description> | |
| 11877 A Native Method Bind event is sent when a VM binds a | |
| 11878 Java programming language native method | |
| 11879 to the address of a function that implements the native method. | |
| 11880 This will occur when the native method is called for the first time | |
| 11881 and also occurs when the JNI function <code>RegisterNatives</code> is called. | |
| 11882 This event allows the bind to be redirected to an agent-specified | |
| 11883 proxy function. | |
| 11884 This event is not sent when the native method is unbound. | |
| 11885 Typically, this proxy function will need to be specific to a | |
| 11886 particular method or, to handle the general case, automatically | |
| 11887 generated assembly code, since after instrumentation code is | |
| 11888 executed the function at the original binding | |
| 11889 address will usually be invoked. | |
| 11890 The original binding can be restored or the redirection changed | |
| 11891 by use of the JNI function <code>RegisterNatives</code>. | |
| 11892 Some events may be sent during the primordial phase, JNI and | |
| 11893 most of <jvmti/> cannot be used at this time but the method and | |
| 11894 address can be saved for use later. | |
| 11895 </description> | |
| 11896 <origin>new</origin> | |
| 11897 <capabilities> | |
| 11898 <required id="can_generate_native_method_bind_events"></required> | |
| 11899 </capabilities> | |
| 11900 <parameters> | |
| 11901 <param id="jni_env"> | |
| 11902 <outptr> | |
| 11903 <struct>JNIEnv</struct> | |
| 11904 </outptr> | |
| 11905 <description> | |
| 11906 The JNI environment of the event (current) thread | |
| 11907 Will be <code>NULL</code> if sent during the primordial | |
| 11908 <functionlink id="GetPhase">phase</functionlink>. | |
| 11909 </description> | |
| 11910 </param> | |
| 11911 <param id="thread"> | |
| 11912 <jthread/> | |
| 11913 <description> | |
| 11914 Thread requesting the bind | |
| 11915 </description> | |
| 11916 </param> | |
| 11917 <param id="klass"> | |
| 11918 <jclass method="method"/> | |
| 11919 <description> | |
| 11920 Class of the method being bound | |
| 11921 </description> | |
| 11922 </param> | |
| 11923 <param id="method"> | |
| 11924 <jmethodID class="klass"/> | |
| 11925 <description> | |
| 11926 Native method being bound | |
| 11927 </description> | |
| 11928 </param> | |
| 11929 <param id="address"> | |
| 11930 <outptr><void/></outptr> | |
| 11931 <description> | |
| 11932 The address the VM is about to bind to--that is, the | |
| 11933 address of the implementation of the native method | |
| 11934 </description> | |
| 11935 </param> | |
| 11936 <param id="new_address_ptr"> | |
| 11937 <agentbuf><void/></agentbuf> | |
| 11938 <description> | |
| 11939 if the referenced address is changed (that is, if | |
| 11940 <code>*new_address_ptr</code> is set), the binding | |
| 11941 will instead be made to the supplied address. | |
| 11942 </description> | |
| 11943 </param> | |
| 11944 </parameters> | |
| 11945 </event> | |
| 11946 | |
| 11947 <event label="Exception" | |
| 11948 id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58"> | |
| 11949 <description> | |
| 11950 Exception events are generated whenever an exception is first detected | |
| 11951 in a Java programming language method. | |
| 11952 Where "exception" means any <code>java.lang.Throwable</code>. | |
| 11953 The exception may have been thrown by a Java programming language or native | |
| 11954 method, but in the case of native methods, the event is not generated | |
| 11955 until the exception is first seen by a Java programming language method. If an exception is | |
| 11956 set and cleared in a native method (and thus is never visible to Java programming language code), | |
| 11957 no exception event is generated. | |
| 11958 <p/> | |
| 11959 The <code>method</code> and <code>location</code> | |
| 11960 parameters uniquely identify the current location | |
| 11961 (where the exception was detected) and allow | |
| 11962 the mapping to source file and line number when that information is | |
| 11963 available. The <code>exception</code> field identifies the thrown | |
| 11964 exception object. The <code>catch_method</code> | |
| 11965 and <code>catch_location</code> identify the location of the catch clause, | |
| 11966 if any, that handles the thrown exception. If there is no such catch clause, | |
| 11967 each field is set to 0. There is no guarantee that the thread will ever | |
| 11968 reach this catch clause. If there are native methods on the call stack | |
| 11969 between the throw location and the catch clause, the exception may | |
| 11970 be reset by one of those native methods. | |
| 11971 Similarly, exceptions that are reported as uncaught (<code>catch_klass</code> | |
| 11972 et al. set to 0) may in fact be caught by native code. | |
| 11973 Agents can check for these occurrences by monitoring | |
| 11974 <eventlink id="ExceptionCatch"></eventlink> events. | |
| 11975 Note that finally clauses are implemented as catch and re-throw. Therefore they | |
| 11976 will be reported in the catch location. | |
| 11977 </description> | |
| 11978 <origin>jvmdi</origin> | |
| 11979 <capabilities> | |
| 11980 <required id="can_generate_exception_events"></required> | |
| 11981 </capabilities> | |
| 11982 <parameters> | |
| 11983 <param id="jni_env"> | |
| 11984 <outptr> | |
| 11985 <struct>JNIEnv</struct> | |
| 11986 </outptr> | |
| 11987 <description> | |
| 11988 The JNI environment of the event (current) thread | |
| 11989 </description> | |
| 11990 </param> | |
| 11991 <param id="thread"> | |
| 11992 <jthread/> | |
| 11993 <description> | |
| 11994 Thread generating the exception | |
| 11995 </description> | |
| 11996 </param> | |
| 11997 <param id="klass"> | |
| 11998 <jclass method="method"/> | |
| 11999 <description> | |
| 12000 Class generating the exception | |
| 12001 </description> | |
| 12002 </param> | |
| 12003 <param id="method"> | |
| 12004 <jmethodID class="klass"/> | |
| 12005 <description> | |
| 12006 Method generating the exception | |
| 12007 </description> | |
| 12008 </param> | |
| 12009 <param id="location"> | |
| 12010 <jlocation/> | |
| 12011 <description> | |
| 12012 Location where exception occurred | |
| 12013 </description> | |
| 12014 </param> | |
| 12015 <param id="exception"> | |
| 12016 <jobject/> | |
| 12017 <description> | |
| 12018 The exception being thrown | |
| 12019 </description> | |
| 12020 </param> | |
| 12021 <param id="catch_klass"> | |
| 12022 <jclass method="catch_method"/> | |
| 12023 <description> | |
| 12024 Class that will catch the exception, or <code>NULL</code> if no known catch | |
| 12025 </description> | |
| 12026 </param> | |
| 12027 <param id="catch_method"> | |
| 12028 <jmethodID class="catch_klass"/> | |
| 12029 <description> | |
| 12030 Method that will catch the exception, or <code>NULL</code> if no known catch | |
| 12031 </description> | |
| 12032 </param> | |
| 12033 <param id="catch_location"> | |
| 12034 <jlocation/> | |
| 12035 <description> | |
| 12036 location which will catch the exception or zero if no known catch | |
| 12037 </description> | |
| 12038 </param> | |
| 12039 </parameters> | |
| 12040 </event> | |
| 12041 | |
| 12042 <event label="Exception Catch" | |
| 12043 id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59"> | |
| 12044 <description> | |
| 12045 Exception catch events are generated whenever a thrown exception is caught. | |
| 12046 Where "exception" means any <code>java.lang.Throwable</code>. | |
| 12047 If the exception is caught in a Java programming language method, the event is generated | |
| 12048 when the catch clause is reached. If the exception is caught in a native | |
| 12049 method, the event is generated as soon as control is returned to a Java programming language | |
| 12050 method. Exception catch events are generated for any exception for which | |
| 12051 a throw was detected in a Java programming language method. | |
| 12052 Note that finally clauses are implemented as catch and re-throw. Therefore they | |
| 12053 will generate exception catch events. | |
| 12054 <p/> | |
| 12055 The <code>method</code> and <code>location</code> | |
| 12056 parameters uniquely identify the current location | |
| 12057 and allow the mapping to source file and line number when that information is | |
| 12058 available. For exceptions caught in a Java programming language method, the | |
| 12059 <code>exception</code> object identifies the exception object. Exceptions | |
| 12060 caught in native methods are not necessarily available by the time the | |
| 12061 exception catch is reported, so the <code>exception</code> field is set | |
| 12062 to <code>NULL</code>. | |
| 12063 </description> | |
| 12064 <origin>jvmdi</origin> | |
| 12065 <capabilities> | |
| 12066 <required id="can_generate_exception_events"></required> | |
| 12067 </capabilities> | |
| 12068 <parameters> | |
| 12069 <param id="jni_env"> | |
| 12070 <outptr> | |
| 12071 <struct>JNIEnv</struct> | |
| 12072 </outptr> | |
| 12073 <description> | |
| 12074 The JNI environment of the event (current) thread | |
| 12075 </description> | |
| 12076 </param> | |
| 12077 <param id="thread"> | |
| 12078 <jthread/> | |
| 12079 <description> | |
| 12080 Thread catching the exception | |
| 12081 </description> | |
| 12082 </param> | |
| 12083 <param id="klass"> | |
| 12084 <jclass method="method"/> | |
| 12085 <description> | |
| 12086 Class catching the exception | |
| 12087 </description> | |
| 12088 </param> | |
| 12089 <param id="method"> | |
| 12090 <jmethodID class="klass"/> | |
| 12091 <description> | |
| 12092 Method catching the exception | |
| 12093 </description> | |
| 12094 </param> | |
| 12095 <param id="location"> | |
| 12096 <jlocation/> | |
| 12097 <description> | |
| 12098 Location where exception is being caught | |
| 12099 </description> | |
| 12100 </param> | |
| 12101 <param id="exception"> | |
| 12102 <jobject/> | |
| 12103 <description> | |
| 12104 Exception being caught | |
| 12105 </description> | |
| 12106 </param> | |
| 12107 </parameters> | |
| 12108 </event> | |
| 12109 | |
| 12110 <event label="Thread Start" | |
| 12111 id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start"> | |
| 12112 <description> | |
| 12113 Thread start events are generated by a new thread before its initial | |
| 12114 method executes. | |
| 12115 <p/> | |
| 12116 A thread may be listed in the array returned by | |
| 12117 <functionlink id="GetAllThreads"></functionlink> | |
| 12118 before its thread start event is generated. | |
| 12119 It is possible for other events to be generated | |
| 12120 on a thread before its thread start event. | |
| 12121 <p/> | |
| 12122 The event is sent on the newly started <paramlink id="thread"></paramlink>. | |
| 12123 </description> | |
| 12124 <origin>jvmdi</origin> | |
| 12125 <capabilities> | |
| 12126 </capabilities> | |
| 12127 <parameters> | |
| 12128 <param id="jni_env"> | |
| 12129 <outptr> | |
| 12130 <struct>JNIEnv</struct> | |
| 12131 </outptr> | |
| 12132 <description> | |
| 12133 The JNI environment of the event (current) thread. | |
| 12134 </description> | |
| 12135 </param> | |
| 12136 <param id="thread"> | |
| 12137 <jthread/> | |
| 12138 <description> | |
| 12139 Thread starting | |
| 12140 </description> | |
| 12141 </param> | |
| 12142 </parameters> | |
| 12143 </event> | |
| 12144 | |
| 12145 <event label="Thread End" | |
| 12146 id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start"> | |
| 12147 <description> | |
| 12148 Thread end events are generated by a terminating thread | |
| 12149 after its initial method has finished execution. | |
| 12150 <p/> | |
| 12151 A thread may be listed in the array returned by | |
| 12152 <functionlink id="GetAllThreads"></functionlink> | |
| 12153 after its thread end event is generated. | |
| 12154 No events are generated on a thread | |
| 12155 after its thread end event. | |
| 12156 <p/> | |
| 12157 The event is sent on the dying <paramlink id="thread"></paramlink>. | |
| 12158 </description> | |
| 12159 <origin>jvmdi</origin> | |
| 12160 <capabilities> | |
| 12161 </capabilities> | |
| 12162 <parameters> | |
| 12163 <param id="jni_env"> | |
| 12164 <outptr> | |
| 12165 <struct>JNIEnv</struct> | |
| 12166 </outptr> | |
| 12167 <description> | |
| 12168 The JNI environment of the event (current) thread. | |
| 12169 </description> | |
| 12170 </param> | |
| 12171 <param id="thread"> | |
| 12172 <jthread/> | |
| 12173 <description> | |
| 12174 Thread ending | |
| 12175 </description> | |
| 12176 </param> | |
| 12177 </parameters> | |
| 12178 </event> | |
| 12179 | |
| 12180 <event label="Class Load" | |
| 12181 id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55"> | |
| 12182 <description> | |
| 12183 A class load event is generated when a class is first loaded. The order | |
| 12184 of class load events generated by a particular thread are guaranteed | |
| 12185 to match the order of class loading within that thread. | |
| 12186 Array class creation does not generate a class load event. | |
| 12187 The creation of a primitive class (for example, java.lang.Integer.TYPE) | |
| 12188 does not generate a class load event. | |
| 12189 <p/> | |
| 12190 This event is sent at an early stage in loading the class. As | |
| 12191 a result the class should be used carefully. Note, for example, | |
| 12192 that methods and fields are not yet loaded, so queries for methods, | |
| 12193 fields, subclasses, and so on will not give correct results. | |
| 12194 See "Loading of Classes and Interfaces" in the <i>Java Language | |
| 12195 Specification</i>. For most | |
| 12196 purposes the <eventlink id="ClassPrepare"></eventlink> event will | |
| 12197 be more useful. | |
| 12198 </description> | |
| 12199 <origin>jvmdi</origin> | |
| 12200 <capabilities> | |
| 12201 </capabilities> | |
| 12202 <parameters> | |
| 12203 <param id="jni_env"> | |
| 12204 <outptr> | |
| 12205 <struct>JNIEnv</struct> | |
| 12206 </outptr> | |
| 12207 <description> | |
| 12208 The JNI environment of the event (current) thread | |
| 12209 </description> | |
| 12210 </param> | |
| 12211 <param id="thread"> | |
| 12212 <jthread/> | |
| 12213 <description> | |
| 12214 Thread loading the class | |
| 12215 </description> | |
| 12216 </param> | |
| 12217 <param id="klass"> | |
| 12218 <jclass/> | |
| 12219 <description> | |
| 12220 Class being loaded | |
| 12221 </description> | |
| 12222 </param> | |
| 12223 </parameters> | |
| 12224 </event> | |
| 12225 | |
| 12226 <elide> | |
| 12227 <event label="Class Unload" | |
| 12228 id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57"> | |
| 12229 <description> | |
| 12230 A class unload event is generated when the class is about to be unloaded. | |
| 12231 Class unload events take place during garbage collection and must be | |
| 12232 handled extremely carefully. The garbage collector holds many locks | |
| 12233 and has suspended all other threads, so the event handler cannot depend | |
| 12234 on the ability to acquire any locks. The class unload event handler should | |
| 12235 do as little as possible, perhaps by queuing information to be processed | |
| 12236 later. In particular, the <code>jclass</code> should be used only in | |
| 12237 the JNI function <code>isSameObject</code> or in the following <jvmti/> functions: | |
| 12238 <ul> | |
| 12239 <li><functionlink id="GetClassSignature"></functionlink></li> | |
| 12240 <li><functionlink id="GetSourceFileName"></functionlink></li> | |
| 12241 <li><functionlink id="IsInterface"></functionlink></li> | |
| 12242 <li><functionlink id="IsArrayClass"></functionlink></li> | |
| 12243 </ul> | |
| 12244 </description> | |
| 12245 <origin>jvmdi</origin> | |
| 12246 <capabilities> | |
| 12247 </capabilities> | |
| 12248 <parameters> | |
| 12249 <param id="jni_env"> | |
| 12250 <outptr> | |
| 12251 <struct>JNIEnv</struct> | |
| 12252 </outptr> | |
| 12253 <description> | |
| 12254 The JNI environment of the event (current) thread | |
| 12255 </description> | |
| 12256 </param> | |
| 12257 <param id="thread"> | |
| 12258 <jthread/> | |
| 12259 <description> | |
| 12260 Thread generating the class unload | |
| 12261 </description> | |
| 12262 </param> | |
| 12263 <param id="klass"> | |
| 12264 <jclass/> | |
| 12265 <description> | |
| 12266 Class being unloaded | |
| 12267 </description> | |
| 12268 </param> | |
| 12269 </parameters> | |
| 12270 </event> | |
| 12271 </elide> | |
| 12272 | |
| 12273 <event label="Class Prepare" | |
| 12274 id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56"> | |
| 12275 <description> | |
| 12276 A class prepare event is generated when class preparation is complete. | |
| 12277 At this point, class fields, methods, and implemented interfaces are | |
| 12278 available, and no code from the class has been executed. Since array | |
| 12279 classes never have fields or methods, class prepare events are not | |
| 12280 generated for them. Class prepare events are not generated for | |
| 12281 primitive classes (for example, <code>java.lang.Integer.TYPE</code>). | |
| 12282 </description> | |
| 12283 <origin>jvmdi</origin> | |
| 12284 <capabilities> | |
| 12285 </capabilities> | |
| 12286 <parameters> | |
| 12287 <param id="jni_env"> | |
| 12288 <outptr> | |
| 12289 <struct>JNIEnv</struct> | |
| 12290 </outptr> | |
| 12291 <description> | |
| 12292 The JNI environment of the event (current) thread | |
| 12293 </description> | |
| 12294 </param> | |
| 12295 <param id="thread"> | |
| 12296 <jthread/> | |
| 12297 <description> | |
| 12298 Thread generating the class prepare | |
| 12299 </description> | |
| 12300 </param> | |
| 12301 <param id="klass"> | |
| 12302 <jclass/> | |
| 12303 <description> | |
| 12304 Class being prepared | |
| 12305 </description> | |
| 12306 </param> | |
| 12307 </parameters> | |
| 12308 </event> | |
| 12309 | |
| 12310 <event label="Class File Load Hook" phase="any" | |
| 12311 id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54"> | |
| 12312 <description> | |
| 12313 This event is sent when the VM obtains class file data, | |
| 12314 but before it constructs | |
| 12315 the in-memory representation for that class. | |
| 12316 This event is also sent when the class is being modified by the | |
| 12317 <functionlink id="RetransformClasses"/> function or | |
| 12318 the <functionlink id="RedefineClasses"/> function, | |
| 12319 called in any <jvmti/> environment. | |
| 12320 The agent can instrument | |
| 12321 the existing class file data sent by the VM to include profiling/debugging hooks. | |
| 12322 See the description of | |
| 12323 <internallink id="bci">bytecode instrumentation</internallink> | |
| 12324 for usage information. | |
| 12325 <p/> | |
| 12326 This event may be sent before the VM is initialized (the primordial | |
| 12327 <functionlink id="GetPhase">phase</functionlink>). During this time | |
| 12328 no VM resources should be created. Some classes might not be compatible | |
| 12329 with the function (eg. ROMized classes) and this event will not be | |
| 12330 generated for these classes. | |
| 12331 <p/> | |
| 12332 The agent must allocate the space for the modified | |
| 12333 class file data buffer | |
| 12334 using the memory allocation function | |
| 12335 <functionlink id="Allocate"></functionlink> because the | |
| 12336 VM is responsible for freeing the new class file data buffer | |
| 12337 using <functionlink id="Deallocate"></functionlink>. | |
| 12338 Note that <functionlink id="Allocate"></functionlink> | |
| 12339 is permitted during the primordial phase. | |
| 12340 <p/> | |
| 12341 If the agent wishes to modify the class file, it must set | |
| 12342 <code>new_class_data</code> to point | |
| 12343 to the newly instrumented class file data buffer and set | |
| 12344 <code>new_class_data_len</code> to the length of that | |
| 12345 buffer before returning | |
| 12346 from this call. If no modification is desired, the agent simply | |
| 12347 does not set <code>new_class_data</code>. If multiple agents | |
| 12348 have enabled this event the results are chained. That is, if | |
| 12349 <code>new_class_data</code> has been set, it becomes the | |
| 12350 <code>class_data</code> for the next agent. | |
| 12351 <p/> | |
| 12352 The order that this event is sent to each environment differs | |
| 12353 from other events. | |
| 12354 This event is sent to environments in the following order: | |
| 12355 <ul> | |
| 12356 <li><fieldlink id="can_retransform_classes" | |
| 12357 struct="jvmtiCapabilities">retransformation | |
| 12358 incapable</fieldlink> | |
| 12359 environments, in the | |
| 12360 order in which they were created | |
| 12361 </li> | |
| 12362 <li><fieldlink id="can_retransform_classes" | |
| 12363 struct="jvmtiCapabilities">retransformation | |
| 12364 capable</fieldlink> | |
| 12365 environments, in the | |
| 12366 order in which they were created | |
| 12367 </li> | |
| 12368 </ul> | |
| 12369 When triggered by <functionlink id="RetransformClasses"/>, | |
| 12370 this event is sent only to <fieldlink id="can_retransform_classes" | |
| 12371 struct="jvmtiCapabilities">retransformation | |
| 12372 capable</fieldlink> | |
| 12373 environments. | |
| 12374 </description> | |
| 12375 <origin>jvmpi</origin> | |
| 12376 <capabilities> | |
| 12377 <capability id="can_generate_all_class_hook_events"></capability> | |
| 12378 </capabilities> | |
| 12379 <parameters> | |
| 12380 <param id="jni_env"> | |
| 12381 <outptr> | |
| 12382 <struct>JNIEnv</struct> | |
| 12383 </outptr> | |
| 12384 <description> | |
| 12385 The JNI environment of the event (current) thread. | |
| 12386 Will be <code>NULL</code> if sent during the primordial | |
| 12387 <functionlink id="GetPhase">phase</functionlink>. | |
| 12388 </description> | |
| 12389 </param> | |
| 12390 <param id="class_being_redefined"> | |
| 12391 <jclass/> | |
| 12392 <description> | |
| 12393 The class being | |
| 12394 <functionlink id="RedefineClasses">redefined</functionlink> or | |
| 12395 <functionlink id="RetransformClasses">retransformed</functionlink>. | |
| 12396 <code>NULL</code> if sent by class load. | |
| 12397 </description> | |
| 12398 </param> | |
| 12399 <param id="loader"> | |
| 12400 <jobject/> | |
| 12401 <description> | |
| 12402 The class loader loading the class. | |
| 12403 <code>NULL</code> if the bootstrap class loader. | |
| 12404 </description> | |
| 12405 </param> | |
| 12406 <param id="name"> | |
| 12407 <vmbuf><char/></vmbuf> | |
| 12408 <description> | |
| 12409 Name of class being loaded as a VM internal qualified name | |
| 12410 (for example, "java/util/List"), encoded as a | |
| 12411 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 12412 Note: if the class is defined with a <code>NULL</code> name or | |
| 12413 without a name specified, <code>name</code> will be <code>NULL</code>. | |
| 12414 </description> | |
| 12415 </param> | |
| 12416 <param id="protection_domain"> | |
| 12417 <jobject/> | |
| 12418 <description> | |
| 12419 The <code>ProtectionDomain</code> of the class. | |
| 12420 </description> | |
| 12421 </param> | |
| 12422 <param id="class_data_len"> | |
| 12423 <jint/> | |
| 12424 <description> | |
| 12425 Length of current class file data buffer. | |
| 12426 </description> | |
| 12427 </param> | |
| 12428 <param id="class_data"> | |
| 12429 <vmbuf><uchar/></vmbuf> | |
| 12430 <description> | |
| 12431 Pointer to the current class file data buffer. | |
| 12432 </description> | |
| 12433 </param> | |
| 12434 <param id="new_class_data_len"> | |
| 12435 <outptr><jint/></outptr> | |
| 12436 <description> | |
| 12437 Pointer to the length of the new class file data buffer. | |
| 12438 </description> | |
| 12439 </param> | |
| 12440 <param id="new_class_data"> | |
| 12441 <agentbuf incount="new_class_data_len"><uchar/></agentbuf> | |
| 12442 <description> | |
| 12443 Pointer to the pointer to the instrumented class file data buffer. | |
| 12444 </description> | |
| 12445 </param> | |
| 12446 </parameters> | |
| 12447 </event> | |
| 12448 | |
| 12449 <event label="VM Start Event" | |
| 12450 id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start"> | |
| 12451 <description> | |
| 12452 The VM initialization event signals the start of the VM. | |
| 12453 At this time JNI is live but the VM is not yet fully initialized. | |
| 12454 Once this event is generated, the agent is free to call any JNI function. | |
| 12455 This event signals the beginning of the start phase, | |
| 12456 <jvmti/> functions permitted in the start phase may be called. | |
| 12457 <p/> | |
| 12458 In the case of VM start-up failure, this event will not be sent. | |
| 12459 </description> | |
| 12460 <origin>jvmdi</origin> | |
| 12461 <capabilities> | |
| 12462 </capabilities> | |
| 12463 <parameters> | |
| 12464 <param id="jni_env"> | |
| 12465 <outptr> | |
| 12466 <struct>JNIEnv</struct> | |
| 12467 </outptr> | |
| 12468 <description> | |
| 12469 The JNI environment of the event (current) thread. | |
| 12470 </description> | |
| 12471 </param> | |
| 12472 </parameters> | |
| 12473 </event> | |
| 12474 | |
| 12475 <event label="VM Initialization Event" | |
| 12476 id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50"> | |
| 12477 <description> | |
| 12478 The VM initialization event signals the completion of VM initialization. Once | |
| 12479 this event is generated, the agent is free to call any JNI or <jvmti/> | |
| 12480 function. The VM initialization event can be preceded by or can be concurrent | |
| 12481 with other events, but | |
| 12482 the preceding events should be handled carefully, if at all, because the | |
| 12483 VM has not completed its initialization. The thread start event for the | |
| 12484 main application thread is guaranteed not to occur until after the | |
| 12485 handler for the VM initialization event returns. | |
| 12486 <p/> | |
| 12487 In the case of VM start-up failure, this event will not be sent. | |
| 12488 </description> | |
| 12489 <origin>jvmdi</origin> | |
| 12490 <capabilities> | |
| 12491 </capabilities> | |
| 12492 <parameters> | |
| 12493 <param id="jni_env"> | |
| 12494 <outptr> | |
| 12495 <struct>JNIEnv</struct> | |
| 12496 </outptr> | |
| 12497 <description> | |
| 12498 The JNI environment of the event (current) thread. | |
| 12499 </description> | |
| 12500 </param> | |
| 12501 <param id="thread"> | |
| 12502 <jthread/> | |
| 12503 <description> | |
| 12504 The initial thread | |
| 12505 </description> | |
| 12506 </param> | |
| 12507 </parameters> | |
| 12508 </event> | |
| 12509 | |
| 12510 <event label="VM Death Event" | |
| 12511 id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51"> | |
| 12512 <description> | |
| 12513 The VM death event notifies the agent of the termination of the VM. | |
| 12514 No events will occur after the VMDeath event. | |
| 12515 <p/> | |
| 12516 In the case of VM start-up failure, this event will not be sent. | |
| 12517 Note that <internallink id="onunload">Agent_OnUnload</internallink> | |
| 12518 will still be called in these cases. | |
| 12519 </description> | |
| 12520 <origin>jvmdi</origin> | |
| 12521 <capabilities> | |
| 12522 </capabilities> | |
| 12523 <parameters> | |
| 12524 <param id="jni_env"> | |
| 12525 <outptr> | |
| 12526 <struct>JNIEnv</struct> | |
| 12527 </outptr> | |
| 12528 <description> | |
| 12529 The JNI environment of the event (current) thread | |
| 12530 </description> | |
| 12531 </param> | |
| 12532 </parameters> | |
| 12533 </event> | |
| 12534 | |
| 12535 <event label="Compiled Method Load" | |
| 12536 id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68"> | |
| 12537 <description> | |
| 12538 Sent when a method is compiled and loaded into memory by the VM. | |
| 12539 If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent. | |
| 12540 If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent, | |
| 12541 followed by a new <code>CompiledMethodLoad</code> event. | |
| 12542 Note that a single method may have multiple compiled forms, and that | |
| 12543 this event will be sent for each form. | |
| 12544 Note also that several methods may be inlined into a single | |
| 12545 address range, and that this event will be sent for each method. | |
| 12546 <p/> | |
| 12547 These events can be sent after their initial occurrence with | |
| 12548 <functionlink id="GenerateEvents"></functionlink>. | |
| 12549 </description> | |
| 12550 <origin>jvmpi</origin> | |
| 12551 <typedef id="jvmtiAddrLocationMap" label="Native address to location entry"> | |
| 12552 <field id="start_address"> | |
| 12553 <vmbuf><void/></vmbuf> | |
| 12554 <description> | |
| 12555 Starting native address of code corresponding to a location | |
| 12556 </description> | |
| 12557 </field> | |
| 12558 <field id="location"> | |
| 12559 <jlocation/> | |
| 12560 <description> | |
| 12561 Corresponding location. See | |
| 12562 <functionlink id="GetJLocationFormat"></functionlink> | |
| 12563 for the meaning of location. | |
| 12564 </description> | |
| 12565 </field> | |
| 12566 </typedef> | |
| 12567 <capabilities> | |
| 12568 <required id="can_generate_compiled_method_load_events"></required> | |
| 12569 </capabilities> | |
| 12570 <parameters> | |
| 12571 <param id="klass"> | |
| 12572 <jclass method="method"/> | |
| 12573 <description> | |
| 12574 Class of the method being compiled and loaded | |
| 12575 </description> | |
| 12576 </param> | |
| 12577 <param id="method"> | |
| 12578 <jmethodID class="klass"/> | |
| 12579 <description> | |
| 12580 Method being compiled and loaded | |
| 12581 </description> | |
| 12582 </param> | |
| 12583 <param id="code_size"> | |
| 12584 <jint/> | |
| 12585 <description> | |
| 12586 Size of compiled code | |
| 12587 </description> | |
| 12588 </param> | |
| 12589 <param id="code_addr"> | |
| 12590 <vmbuf><void/></vmbuf> | |
| 12591 <description> | |
| 12592 Address where compiled method code is loaded | |
| 12593 </description> | |
| 12594 </param> | |
| 12595 <param id="map_length"> | |
| 12596 <jint/> | |
| 12597 <description> | |
| 12598 Number of <typelink id="jvmtiAddrLocationMap"></typelink> | |
| 12599 entries in the address map. | |
| 12600 Zero if mapping information cannot be supplied. | |
| 12601 </description> | |
| 12602 </param> | |
| 12603 <param id="map"> | |
| 12604 <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf> | |
| 12605 <description> | |
| 12606 Map from native addresses to location. | |
| 12607 The native address range of each entry is from | |
| 12608 <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink> | |
| 12609 to <code>start_address-1</code> of the next entry. | |
| 12610 <code>NULL</code> if mapping information cannot be supplied. | |
| 12611 </description> | |
| 12612 </param> | |
| 12613 <param id="compile_info"> | |
| 12614 <vmbuf><void/></vmbuf> | |
| 12615 <description> | |
| 12616 VM-specific compilation information. | |
| 12617 The referenced compile information is managed by the VM | |
| 12618 and must not depend on the agent for collection. | |
| 12619 A VM implementation defines the content and lifetime | |
| 12620 of the information. | |
| 12621 </description> | |
| 12622 </param> | |
| 12623 </parameters> | |
| 12624 </event> | |
| 12625 | |
| 12626 <event label="Compiled Method Unload" | |
| 12627 id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69"> | |
| 12628 <description> | |
| 12629 Sent when a compiled method is unloaded from memory. | |
| 12630 This event might not be sent on the thread which performed the unload. | |
| 12631 This event may be sent sometime after the unload occurs, but | |
| 12632 will be sent before the memory is reused | |
| 12633 by a newly generated compiled method. This event may be sent after | |
| 12634 the class is unloaded. | |
| 12635 </description> | |
| 12636 <origin>jvmpi</origin> | |
| 12637 <capabilities> | |
| 12638 <required id="can_generate_compiled_method_load_events"></required> | |
| 12639 </capabilities> | |
| 12640 <parameters> | |
| 12641 <param id="klass"> | |
| 12642 <jclass method="method"/> | |
| 12643 <description> | |
| 12644 Class of the compiled method being unloaded. | |
| 12645 </description> | |
| 12646 </param> | |
| 12647 <param id="method"> | |
| 12648 <jmethodID class="klass"/> | |
| 12649 <description> | |
| 12650 Compiled method being unloaded. | |
| 12651 For identification of the compiled method only -- the class | |
| 12652 may be unloaded and therefore the method should not be used | |
| 12653 as an argument to further JNI or <jvmti/> functions. | |
| 12654 </description> | |
| 12655 </param> | |
| 12656 <param id="code_addr"> | |
| 12657 <vmbuf><void/></vmbuf> | |
| 12658 <description> | |
| 12659 Address where compiled method code was loaded. | |
| 12660 For identification of the compiled method only -- | |
| 12661 the space may have been reclaimed. | |
| 12662 </description> | |
| 12663 </param> | |
| 12664 </parameters> | |
| 12665 </event> | |
| 12666 | |
| 12667 <event label="Dynamic Code Generated" phase="any" | |
| 12668 id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70"> | |
| 12669 <description> | |
| 12670 Sent when a component of the virtual machine is generated dynamically. | |
| 12671 This does not correspond to Java programming language code that is | |
| 12672 compiled--see <eventlink id="CompiledMethodLoad"></eventlink>. | |
| 12673 This is for native code--for example, an interpreter that is generated | |
| 12674 differently depending on command-line options. | |
| 12675 <p/> | |
| 12676 Note that this event has no controlling capability. | |
| 12677 If a VM cannot generate these events, it simply does not send any. | |
| 12678 <p/> | |
| 12679 These events can be sent after their initial occurrence with | |
| 12680 <functionlink id="GenerateEvents"></functionlink>. | |
| 12681 </description> | |
| 12682 <origin>jvmpi</origin> | |
| 12683 <capabilities> | |
| 12684 </capabilities> | |
| 12685 <parameters> | |
| 12686 <param id="name"> | |
| 12687 <vmbuf><char/></vmbuf> | |
| 12688 <description> | |
| 12689 Name of the code, encoded as a | |
| 12690 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 12691 Intended for display to an end-user. | |
| 12692 The name might not be unique. | |
| 12693 </description> | |
| 12694 </param> | |
| 12695 <param id="address"> | |
| 12696 <vmbuf><void/></vmbuf> | |
| 12697 <description> | |
| 12698 Native address of the code | |
| 12699 </description> | |
| 12700 </param> | |
| 12701 <param id="length"> | |
| 12702 <jint/> | |
| 12703 <description> | |
| 12704 Length in bytes of the code | |
| 12705 </description> | |
| 12706 </param> | |
| 12707 </parameters> | |
| 12708 </event> | |
| 12709 | |
| 12710 <event label="Data Dump Request" | |
| 12711 id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71"> | |
| 12712 <description> | |
| 12713 Sent by the VM to request the agent to dump its data. This | |
| 12714 is just a hint and the agent need not react to this event. | |
| 12715 This is useful for processing command-line signals from users. For | |
| 12716 example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris | |
| 12717 causes the VM to send this event to the agent. | |
| 12718 </description> | |
| 12719 <origin>jvmpi</origin> | |
| 12720 <capabilities> | |
| 12721 </capabilities> | |
| 12722 <parameters> | |
| 12723 </parameters> | |
| 12724 </event> | |
| 12725 | |
| 12726 <event label="Monitor Contended Enter" | |
| 12727 id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75"> | |
| 12728 <description> | |
| 12729 Sent when a thread is attempting to enter a Java programming language | |
| 12730 monitor already acquired by another thread. | |
| 12731 </description> | |
| 12732 <origin>jvmpi</origin> | |
| 12733 <capabilities> | |
| 12734 <required id="can_generate_monitor_events"></required> | |
| 12735 </capabilities> | |
| 12736 <parameters> | |
| 12737 <param id="jni_env"> | |
| 12738 <outptr> | |
| 12739 <struct>JNIEnv</struct> | |
| 12740 </outptr> | |
| 12741 <description> | |
| 12742 The JNI environment of the event (current) thread | |
| 12743 </description> | |
| 12744 </param> | |
| 12745 <param id="thread"> | |
| 12746 <jthread/> | |
| 12747 <description> | |
| 12748 JNI local reference to the thread | |
| 12749 attempting to enter the monitor | |
| 12750 </description> | |
| 12751 </param> | |
| 12752 <param id="object"> | |
| 12753 <jobject/> | |
| 12754 <description> | |
| 12755 JNI local reference to the monitor | |
| 12756 </description> | |
| 12757 </param> | |
| 12758 </parameters> | |
| 12759 </event> | |
| 12760 | |
| 12761 <event label="Monitor Contended Entered" | |
| 12762 id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76"> | |
| 12763 <description> | |
| 12764 Sent when a thread enters a Java programming language | |
| 12765 monitor after waiting for it to be released by another thread. | |
| 12766 </description> | |
| 12767 <origin>jvmpi</origin> | |
| 12768 <capabilities> | |
| 12769 <required id="can_generate_monitor_events"></required> | |
| 12770 </capabilities> | |
| 12771 <parameters> | |
| 12772 <param id="jni_env"> | |
| 12773 <outptr> | |
| 12774 <struct>JNIEnv</struct> | |
| 12775 </outptr> | |
| 12776 <description> | |
| 12777 The JNI environment of the event (current) thread | |
| 12778 </description> | |
| 12779 </param> | |
| 12780 <param id="thread"> | |
| 12781 <jthread/> | |
| 12782 <description> | |
| 12783 JNI local reference to the thread entering | |
| 12784 the monitor | |
| 12785 </description> | |
| 12786 </param> | |
| 12787 <param id="object"> | |
| 12788 <jobject/> | |
| 12789 <description> | |
| 12790 JNI local reference to the monitor | |
| 12791 </description> | |
| 12792 </param> | |
| 12793 </parameters> | |
| 12794 </event> | |
| 12795 | |
| 12796 <event label="Monitor Wait" | |
| 12797 id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73"> | |
| 12798 <description> | |
| 12799 Sent when a thread is about to wait on an object. | |
| 12800 </description> | |
| 12801 <origin>jvmpi</origin> | |
| 12802 <capabilities> | |
| 12803 <required id="can_generate_monitor_events"></required> | |
| 12804 </capabilities> | |
| 12805 <parameters> | |
| 12806 <param id="jni_env"> | |
| 12807 <outptr> | |
| 12808 <struct>JNIEnv</struct> | |
| 12809 </outptr> | |
| 12810 <description> | |
| 12811 The JNI environment of the event (current) thread | |
| 12812 </description> | |
| 12813 </param> | |
| 12814 <param id="thread"> | |
| 12815 <jthread/> | |
| 12816 <description> | |
| 12817 JNI local reference to the thread about to wait | |
| 12818 </description> | |
| 12819 </param> | |
| 12820 <param id="object"> | |
| 12821 <jobject/> | |
| 12822 <description> | |
| 12823 JNI local reference to the monitor | |
| 12824 </description> | |
| 12825 </param> | |
| 12826 <param id="timeout"> | |
| 12827 <jlong/> | |
| 12828 <description> | |
| 12829 The number of milliseconds the thread will wait | |
| 12830 </description> | |
| 12831 </param> | |
| 12832 </parameters> | |
| 12833 </event> | |
| 12834 | |
| 12835 <event label="Monitor Waited" | |
| 12836 id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74"> | |
| 12837 <description> | |
| 12838 Sent when a thread finishes waiting on an object. | |
| 12839 </description> | |
| 12840 <origin>jvmpi</origin> | |
| 12841 <capabilities> | |
| 12842 <required id="can_generate_monitor_events"></required> | |
| 12843 </capabilities> | |
| 12844 <parameters> | |
| 12845 <param id="jni_env"> | |
| 12846 <outptr> | |
| 12847 <struct>JNIEnv</struct> | |
| 12848 </outptr> | |
| 12849 <description> | |
| 12850 The JNI environment of the event (current) thread | |
| 12851 </description> | |
| 12852 </param> | |
| 12853 <param id="thread"> | |
| 12854 <jthread/> | |
| 12855 <description> | |
| 12856 JNI local reference to the thread that was finished waiting | |
| 12857 </description> | |
| 12858 </param> | |
| 12859 <param id="object"> | |
| 12860 <jobject/> | |
| 12861 <description> | |
| 12862 JNI local reference to the monitor. | |
| 12863 </description> | |
| 12864 </param> | |
| 12865 <param id="timed_out"> | |
| 12866 <jboolean/> | |
| 12867 <description> | |
| 12868 True if the monitor timed out | |
| 12869 </description> | |
| 12870 </param> | |
| 12871 </parameters> | |
| 12872 </event> | |
| 12873 | |
| 12874 <event label="Resource Exhausted" | |
| 12875 id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80" | |
| 12876 since="1.1"> | |
| 12877 <description> | |
| 12878 Sent when a VM resource needed by a running application has been exhausted. | |
| 12879 Except as required by the optional capabilities, the set of resources | |
| 12880 which report exhaustion is implementation dependent. | |
| 12881 <p/> | |
| 12882 The following bit flags define the properties of the resource exhaustion: | |
| 12883 <constants id="jvmtiResourceExhaustionFlags" | |
| 12884 label="Resource Exhaustion Flags" | |
| 12885 kind="bits" | |
| 12886 since="1.1"> | |
| 12887 <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001"> | |
| 12888 After this event returns, the VM will throw a | |
| 12889 <code>java.lang.OutOfMemoryError</code>. | |
| 12890 </constant> | |
| 12891 <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002"> | |
| 12892 The VM was unable to allocate memory from the <tm>Java</tm> | |
| 12893 platform <i>heap</i>. | |
| 12894 The <i>heap</i> is the runtime | |
| 12895 data area from which memory for all class instances and | |
| 12896 arrays are allocated. | |
| 12897 </constant> | |
| 12898 <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004"> | |
| 12899 The VM was unable to create a thread. | |
| 12900 </constant> | |
| 12901 </constants> | |
| 12902 </description> | |
| 12903 <origin>new</origin> | |
| 12904 <capabilities> | |
| 12905 <capability id="can_generate_resource_exhaustion_heap_events"> | |
| 12906 Can generate events when the VM is unable to allocate memory from the | |
| 12907 <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>. | |
| 12908 </capability> | |
| 12909 <capability id="can_generate_resource_exhaustion_threads_events"> | |
| 12910 Can generate events when the VM is unable to | |
| 12911 <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create | |
| 12912 a thread</internallink>. | |
| 12913 </capability> | |
| 12914 </capabilities> | |
| 12915 <parameters> | |
| 12916 <param id="jni_env"> | |
| 12917 <outptr> | |
| 12918 <struct>JNIEnv</struct> | |
| 12919 </outptr> | |
| 12920 <description> | |
| 12921 The JNI environment of the event (current) thread | |
| 12922 </description> | |
| 12923 </param> | |
| 12924 <param id="flags"> | |
| 12925 <jint/> | |
| 12926 <description> | |
| 12927 Flags defining the properties of the of resource exhaustion | |
| 12928 as specified by the | |
| 12929 <internallink id="jvmtiResourceExhaustionFlags">Resource | |
| 12930 Exhaustion Flags</internallink>. | |
| 12931 </description> | |
| 12932 </param> | |
| 12933 <param id="reserved"> | |
| 12934 <vmbuf><void/></vmbuf> | |
| 12935 <description> | |
| 12936 Reserved. | |
| 12937 </description> | |
| 12938 </param> | |
| 12939 <param id="description"> | |
| 12940 <vmbuf><char/></vmbuf> | |
| 12941 <description> | |
| 12942 Description of the resource exhaustion, encoded as a | |
| 12943 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 12944 </description> | |
| 12945 </param> | |
| 12946 </parameters> | |
| 12947 </event> | |
| 12948 | |
| 12949 <event label="VM Object Allocation" | |
| 12950 id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84"> | |
| 12951 <description> | |
| 12952 Sent when a method causes the virtual machine to allocate an | |
| 12953 Object visible to Java programming language code and the | |
| 12954 allocation is not detectable by other intrumentation mechanisms. | |
| 12955 Generally object allocation should be detected by instrumenting | |
| 12956 the bytecodes of allocating methods. | |
| 12957 Object allocation generated in native code by JNI function | |
| 12958 calls should be detected using | |
| 12959 <internallink id="jniIntercept">JNI function interception</internallink>. | |
| 12960 Some methods might not have associated bytecodes and are not | |
| 12961 native methods, they instead are executed directly by the | |
| 12962 VM. These methods should send this event. | |
| 12963 Virtual machines which are incapable of bytecode instrumentation | |
| 12964 for some or all of their methods can send this event. | |
| 12965 <p/> | |
| 12966 Typical examples where this event might be sent: | |
| 12967 <ul> | |
| 12968 <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li> | |
| 12969 <li>Methods not represented by bytecodes -- for example, VM intrinsics and | |
| 12970 J2ME preloaded classes</li> | |
| 12971 </ul> | |
| 12972 Cases where this event would not be generated: | |
| 12973 <ul> | |
| 12974 <li>Allocation due to bytecodes -- for example, the <code>new</code> | |
| 12975 and <code>newarray</code> VM instructions</li> | |
| 12976 <li>Allocation due to JNI function calls -- for example, | |
| 12977 <code>AllocObject</code></li> | |
| 12978 <li>Allocations during VM initialization</li> | |
| 12979 <li>VM internal objects</li> | |
| 12980 </ul> | |
| 12981 </description> | |
| 12982 <origin>new</origin> | |
| 12983 <capabilities> | |
| 12984 <required id="can_generate_vm_object_alloc_events"></required> | |
| 12985 </capabilities> | |
| 12986 <parameters> | |
| 12987 <param id="jni_env"> | |
| 12988 <outptr> | |
| 12989 <struct>JNIEnv</struct> | |
| 12990 </outptr> | |
| 12991 <description> | |
| 12992 The JNI environment of the event (current) thread | |
| 12993 </description> | |
| 12994 </param> | |
| 12995 <param id="thread"> | |
| 12996 <jthread/> | |
| 12997 <description> | |
| 12998 Thread allocating the object. | |
| 12999 </description> | |
| 13000 </param> | |
| 13001 <param id="object"> | |
| 13002 <jobject/> | |
| 13003 <description> | |
| 13004 JNI local reference to the object that was allocated | |
| 13005 </description> | |
| 13006 </param> | |
| 13007 <param id="object_klass"> | |
| 13008 <jclass/> | |
| 13009 <description> | |
| 13010 JNI local reference to the class of the object | |
| 13011 </description> | |
| 13012 </param> | |
| 13013 <param id="size"> | |
| 13014 <jlong/> | |
| 13015 <description> | |
| 13016 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 13017 </description> | |
| 13018 </param> | |
| 13019 </parameters> | |
| 13020 </event> | |
| 13021 | |
| 13022 <event label="Object Free" | |
| 13023 id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83"> | |
| 13024 <description> | |
| 13025 An Object Free event is sent when the garbage collector frees an object. | |
| 13026 Events are only sent for tagged objects--see | |
| 13027 <internallink id="Heap">heap functions</internallink>. | |
| 13028 <p/> | |
| 13029 The event handler must not use JNI functions and | |
| 13030 must not use <jvmti/> functions except those which | |
| 13031 specifically allow such use (see the raw monitor, memory management, | |
| 13032 and environment local storage functions). | |
| 13033 </description> | |
| 13034 <origin>new</origin> | |
| 13035 <capabilities> | |
| 13036 <required id="can_generate_object_free_events"></required> | |
| 13037 </capabilities> | |
| 13038 <parameters> | |
| 13039 <param id="tag"> | |
| 13040 <jlong/> | |
| 13041 <description> | |
| 13042 The freed object's tag | |
| 13043 </description> | |
| 13044 </param> | |
| 13045 </parameters> | |
| 13046 </event> | |
| 13047 | |
| 13048 <event label="Garbage Collection Start" | |
| 13049 id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81"> | |
| 13050 <description> | |
| 13051 A Garbage Collection Start event is sent when a full cycle | |
| 13052 garbage collection begins. | |
| 13053 Only stop-the-world collections are reported--that is, collections during | |
| 13054 which all threads cease to modify the state of the Java virtual machine. | |
| 13055 This means that some collectors will never generate these events. | |
| 13056 This event is sent while the VM is still stopped, thus | |
| 13057 the event handler must not use JNI functions and | |
| 13058 must not use <jvmti/> functions except those which | |
| 13059 specifically allow such use (see the raw monitor, memory management, | |
| 13060 and environment local storage functions). | |
| 13061 <p/> | |
| 13062 This event is always sent as a matched pair with | |
| 13063 <eventlink id="GarbageCollectionFinish"/> | |
| 13064 (assuming both events are enabled) and no garbage collection | |
| 13065 events will occur between them. | |
| 13066 </description> | |
| 13067 <origin>new</origin> | |
| 13068 <capabilities> | |
| 13069 <required id="can_generate_garbage_collection_events"></required> | |
| 13070 </capabilities> | |
| 13071 <parameters> | |
| 13072 </parameters> | |
| 13073 </event> | |
| 13074 | |
| 13075 <event label="Garbage Collection Finish" | |
| 13076 id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82"> | |
| 13077 <description> | |
| 13078 A Garbage Collection Finish event is sent when a full | |
| 13079 garbage collection cycle ends. | |
| 13080 This event is sent while the VM is still stopped, thus | |
| 13081 the event handler must not use JNI functions and | |
| 13082 must not use <jvmti/> functions except those which | |
| 13083 specifically allow such use (see the raw monitor, memory management, | |
| 13084 and environment local storage functions). | |
| 13085 <p/> | |
| 13086 Some agents may need to do post garbage collection operations that | |
| 13087 require the use of the disallowed <jvmti/> or JNI functions. For these | |
| 13088 cases an agent thread can be created which waits on a raw monitor, | |
| 13089 and the handler for the Garbage Collection Finish event simply | |
| 13090 notifies the raw monitor | |
| 13091 <p/> | |
| 13092 This event is always sent as a matched pair with | |
| 13093 <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled). | |
| 13094 <issue> | |
| 13095 The most important use of this event is to provide timing information, | |
| 13096 and thus additional information is not required. However, | |
| 13097 information about the collection which is "free" should be included - | |
| 13098 what that information is needs to be determined. | |
| 13099 </issue> | |
| 13100 </description> | |
| 13101 <origin>new</origin> | |
| 13102 <capabilities> | |
| 13103 <required id="can_generate_garbage_collection_events"></required> | |
| 13104 </capabilities> | |
| 13105 <parameters> | |
| 13106 </parameters> | |
| 13107 </event> | |
| 13108 | |
| 13109 <elide> | |
| 13110 <event label="Verbose Output" phase="any" | |
| 13111 id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85"> | |
| 13112 <description> | |
| 13113 Send verbose messages as strings. | |
| 13114 <issue> | |
| 13115 This format is extremely fragile, as it can change with each | |
| 13116 platform, collector and version. Alternatives include: | |
| 13117 <ul> | |
| 13118 <li>building off Java programming language M and M APIs</li> | |
| 13119 <li>XML</li> | |
| 13120 <li>key/value pairs</li> | |
| 13121 <li>removing it</li> | |
| 13122 </ul> | |
| 13123 </issue> | |
| 13124 <issue> | |
| 13125 Though this seemed trivial to implement. | |
| 13126 In the RI it appears this will be quite complex. | |
| 13127 </issue> | |
| 13128 </description> | |
| 13129 <origin>new</origin> | |
| 13130 <capabilities> | |
| 13131 </capabilities> | |
| 13132 <parameters> | |
| 13133 <param id="flag"> | |
| 13134 <enum>jvmtiVerboseFlag</enum> | |
| 13135 <description> | |
| 13136 Which verbose output is being sent. | |
| 13137 </description> | |
| 13138 </param> | |
| 13139 <param id="message"> | |
| 13140 <vmbuf><char/></vmbuf> | |
| 13141 <description> | |
| 13142 Message text, encoded as a | |
| 13143 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 13144 </description> | |
| 13145 </param> | |
| 13146 </parameters> | |
| 13147 </event> | |
| 13148 </elide> | |
| 13149 | |
| 13150 </eventsection> | |
| 13151 | |
| 13152 <datasection> | |
| 13153 <intro> | |
| 13154 <jvmti/> extends the data types defined by JNI. | |
| 13155 </intro> | |
| 13156 <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface"> | |
| 13157 <basetype id="jboolean"> | |
| 13158 <description> | |
| 13159 Holds a Java programming language <code>boolean</code>. | |
| 13160 Unsigned 8 bits. | |
| 13161 </description> | |
| 13162 </basetype> | |
| 13163 <basetype id="jint"> | |
| 13164 <description> | |
| 13165 Holds a Java programming language <code>int</code>. | |
| 13166 Signed 32 bits. | |
| 13167 </description> | |
| 13168 </basetype> | |
| 13169 <basetype id="jlong"> | |
| 13170 <description> | |
| 13171 Holds a Java programming language <code>long</code>. | |
| 13172 Signed 64 bits. | |
| 13173 </description> | |
| 13174 </basetype> | |
| 13175 <basetype id="jfloat"> | |
| 13176 <description> | |
| 13177 Holds a Java programming language <code>float</code>. | |
| 13178 32 bits. | |
| 13179 </description> | |
| 13180 </basetype> | |
| 13181 <basetype id="jdouble"> | |
| 13182 <description> | |
| 13183 Holds a Java programming language <code>double</code>. | |
| 13184 64 bits. | |
| 13185 </description> | |
| 13186 </basetype> | |
| 13187 <basetype id="jobject"> | |
| 13188 <description> | |
| 13189 Holds a Java programming language object. | |
| 13190 </description> | |
| 13191 </basetype> | |
| 13192 <basetype id="jclass"> | |
| 13193 <description> | |
| 13194 Holds a Java programming language class. | |
| 13195 </description> | |
| 13196 </basetype> | |
| 13197 <basetype id="jvalue"> | |
| 13198 <description> | |
| 13199 Is a union of all primitive types and <code>jobject</code>. Thus, holds any Java | |
| 13200 programming language value. | |
| 13201 </description> | |
| 13202 </basetype> | |
| 13203 <basetype id="jfieldID"> | |
| 13204 <description> | |
| 13205 Identifies a Java programming language field. | |
| 13206 <code>jfieldID</code>s returned by <jvmti/> functions and events may be | |
| 13207 safely stored. | |
| 13208 </description> | |
| 13209 </basetype> | |
| 13210 <basetype id="jmethodID"> | |
| 13211 <description> | |
| 13212 Identifies a Java programming language method, initializer, or constructor. | |
| 13213 <code>jmethodID</code>s returned by <jvmti/> functions and events may be | |
| 13214 safely stored. However, if the class is unloaded, they become invalid | |
| 13215 and must not be used. | |
| 13216 </description> | |
| 13217 </basetype> | |
| 13218 <basetype id="JNIEnv"> | |
| 13219 <description> | |
| 13220 Pointer to the JNI function table. Pointer to this (<code>JNIEnv *</code>) | |
| 13221 is a JNI environment. | |
| 13222 </description> | |
| 13223 </basetype> | |
| 13224 </basetypes> | |
| 13225 | |
| 13226 <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types"> | |
| 13227 <basetype id="jvmtiEnv"> | |
| 13228 <description> | |
| 13229 The <jvmti/> <internallink id="environments">environment</internallink> pointer. | |
| 13230 See the <internallink id="FunctionSection">Function Section</internallink>. | |
| 13231 <code>jvmtiEnv</code> points to the | |
| 13232 <internallink id="FunctionTable">function table</internallink> pointer. | |
| 13233 </description> | |
| 13234 </basetype> | |
| 13235 <basetype id="jthread"> | |
| 13236 <definition>typedef jobject jthread;</definition> | |
| 13237 <description> | |
| 13238 Subtype of <datalink id="jobject"></datalink> that holds a thread. | |
| 13239 </description> | |
| 13240 </basetype> | |
| 13241 <basetype id="jthreadGroup"> | |
| 13242 <definition>typedef jobject jthreadGroup;</definition> | |
| 13243 <description> | |
| 13244 Subtype of <datalink id="jobject"></datalink> that holds a thread group. | |
| 13245 </description> | |
| 13246 </basetype> | |
| 13247 <basetype id="jlocation"> | |
| 13248 <definition>typedef jlong jlocation;</definition> | |
| 13249 <description> | |
| 13250 A 64 bit value, representing a monotonically increasing | |
| 13251 executable position within a method. | |
| 13252 <code>-1</code> indicates a native method. | |
| 13253 See <functionlink id="GetJLocationFormat"></functionlink> for the format on a | |
| 13254 given VM. | |
| 13255 </description> | |
| 13256 </basetype> | |
| 13257 <basetype id="jrawMonitorID"> | |
| 13258 <definition>struct _jrawMonitorID; | |
| 13259 typedef struct _jrawMonitorID *jrawMonitorID;</definition> | |
| 13260 <description> | |
| 13261 A raw monitor. | |
| 13262 </description> | |
| 13263 </basetype> | |
| 13264 <basetype id="jvmtiError"> | |
| 13265 <description> | |
| 13266 Holds an error return code. | |
| 13267 See the <internallink id="ErrorSection">Error section</internallink> for possible values. | |
| 13268 <example> | |
| 13269 typedef enum { | |
| 13270 JVMTI_ERROR_NONE = 0, | |
| 13271 JVMTI_ERROR_INVALID_THREAD = 10, | |
| 13272 ... | |
| 13273 } jvmtiError; | |
| 13274 </example> | |
| 13275 </description> | |
| 13276 </basetype> | |
| 13277 <basetype id="jvmtiEvent"> | |
| 13278 <description> | |
| 13279 An identifier for an event type. | |
| 13280 See the <internallink id="EventSection">Event section</internallink> for possible values. | |
| 13281 It is guaranteed that future versions of this specification will | |
| 13282 never assign zero as an event type identifier. | |
| 13283 <example> | |
| 13284 typedef enum { | |
| 13285 JVMTI_EVENT_SINGLE_STEP = 1, | |
| 13286 JVMTI_EVENT_BREAKPOINT = 2, | |
| 13287 ... | |
| 13288 } jvmtiEvent; | |
| 13289 </example> | |
| 13290 </description> | |
| 13291 </basetype> | |
| 13292 <basetype id="jvmtiEventCallbacks"> | |
| 13293 <description> | |
| 13294 The callbacks used for events. | |
| 13295 <example> | |
| 13296 typedef struct { | |
| 13297 jvmtiEventVMInit VMInit; | |
| 13298 jvmtiEventVMDeath VMDeath; | |
| 13299 ... | |
| 13300 } jvmtiEventCallbacks; | |
| 13301 </example> | |
| 13302 See <internallink id="jvmtiEventCallbacks">event callbacks</internallink> | |
| 13303 for the complete structure. | |
| 13304 <p/> | |
| 13305 Where, for example, the VM initialization callback is defined: | |
| 13306 <example> | |
| 13307 typedef void (JNICALL *jvmtiEventVMInit) | |
| 13308 (jvmtiEnv *jvmti_env, | |
| 13309 JNIEnv* jni_env, | |
| 13310 jthread thread); | |
| 13311 </example> | |
| 13312 See the individual events for the callback function definition. | |
| 13313 </description> | |
| 13314 </basetype> | |
| 13315 <basetype id="jniNativeInterface"> | |
| 13316 <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition> | |
| 13317 <description> | |
| 13318 Typedef for the JNI function table <code>JNINativeInterface</code> | |
| 13319 defined in the | |
| 13320 <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html#wp23720">JNI Specification</externallink>. | |
| 13321 The JNI reference implementation defines this with an underscore. | |
| 13322 </description> | |
| 13323 </basetype> | |
| 13324 </basetypes> | |
| 13325 | |
| 13326 </datasection> | |
| 13327 | |
| 13328 <issuessection label="Issues"> | |
| 13329 <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic"> | |
| 13330 JVMDI requires that the agent suspend threads before calling | |
| 13331 certain sensitive functions. JVMPI requires garbage collection to be | |
| 13332 disabled before calling certain sensitive functions. | |
| 13333 It was suggested that rather than have this requirement, that | |
| 13334 VM place itself in a suitable state before performing an | |
| 13335 operation. This makes considerable sense since each VM | |
| 13336 knows its requirements and can most easily arrange a | |
| 13337 safe state. | |
| 13338 <p/> | |
| 13339 The ability to externally suspend/resume threads will, of | |
| 13340 course, remain. The ability to enable/disable garbage collection will not. | |
| 13341 <p/> | |
| 13342 This issue is resolved--suspend will not | |
| 13343 be required. The spec has been updated to reflect this. | |
| 13344 </intro> | |
| 13345 | |
| 13346 <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling"> | |
| 13347 There are a variety of approaches to sampling call stacks. | |
| 13348 The biggest bifurcation is between VM controlled and agent | |
| 13349 controlled. | |
| 13350 <p/> | |
| 13351 This issue is resolved--agent controlled | |
| 13352 sampling will be the approach. | |
| 13353 </intro> | |
| 13354 | |
| 13355 <intro id="threadRepresentation" label="Resolved Issue: Thread Representation"> | |
| 13356 JVMDI represents threads as jthread. JVMPI primarily | |
| 13357 uses JNIEnv* to represent threads. | |
| 13358 <p/> | |
| 13359 The Expert Group has chosen jthread as the representation | |
| 13360 for threads in <jvmti/>. | |
| 13361 JNIEnv* is sent by | |
| 13362 events since it is needed to JNI functions. JNIEnv, per the | |
| 13363 JNI spec, are not supposed to be used outside their thread. | |
| 13364 </intro> | |
| 13365 | |
| 13366 <intro id="design" label="Resolved Issue: Method Representation"> | |
| 13367 The JNI spec allows an implementation to depend on jclass/jmethodID | |
| 13368 pairs, rather than simply a jmethodID, to reference a method. | |
| 13369 JVMDI, for consistency, choose the same representation. | |
| 13370 JVMPI, however, specifies that a jmethodID alone maps to a | |
| 13371 method. Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store | |
| 13372 pointers in jmethodIDs, and as a result, a jmethodID is sufficient. | |
| 13373 In fact, any JVM implementation that supports JVMPI must have | |
| 13374 such a representation. | |
| 13375 <jvmti/> will use jmethodID as a unique representation of a method | |
| 13376 (no jclass is used). | |
| 13377 There should be efficiency gains, particularly in | |
| 13378 functionality like stack dumping, to this representation. | |
| 13379 <p/> | |
| 13380 Note that fields were not used in JVMPI and that the access profile | |
| 13381 of fields differs from methods--for implementation efficiency | |
| 13382 reasons, a jclass/jfieldID pair will still be needed for field | |
| 13383 reference. | |
| 13384 </intro> | |
| 13385 | |
| 13386 <intro id="localReferenceIssue" label="Resolved Issue: Local References"> | |
| 13387 Functions return local references. | |
| 13388 </intro> | |
| 13389 | |
| 13390 <intro id="frameRep" label="Resolved Issue: Representation of frames"> | |
| 13391 In JVMDI, a frame ID is used to represent a frame. Problem with this | |
| 13392 is that a VM must track when a frame becomes invalid, a far better | |
| 13393 approach, and the one used in <jvmti/>, is to reference frames by depth. | |
| 13394 </intro> | |
| 13395 | |
| 13396 <intro id="requiredCapabilities" label="Issue: Required Capabilities"> | |
| 13397 Currently, having a required capabilities means that the functionality | |
| 13398 is optional. Capabilities are useful even for required functionality | |
| 13399 since they can inform the VM is needed set-up. Thus, there should be | |
| 13400 a set of capabilities that a conformant implementation must provide | |
| 13401 (if requested during Agent_OnLoad). | |
| 13402 </intro> | |
| 13403 | |
| 13404 <intro id="taghint" label="Proposal: add tag hint function"> | |
| 13405 A hint of the percentage of objects that will be tagged would | |
| 13406 help the VM pick a good implementation. | |
| 13407 </intro> | |
| 13408 | |
| 13409 <intro id="moreMonitorQueries" label="Request: More Monitor Quires"> | |
| 13410 How difficult or easy would be to extend the monitor_info category to include | |
| 13411 <pre> | |
| 13412 - current number of monitors | |
| 13413 - enumeration of monitors | |
| 13414 - enumeration of threads waiting on a given monitor | |
| 13415 </pre> | |
| 13416 The reason for my question is the fact that current get_monitor_info support | |
| 13417 requires the agent to specify a given thread to get the info which is probably | |
| 13418 OK in the profiling/debugging space, while in the monitoring space the agent | |
| 13419 could be watching the monitor list and then decide which thread to ask for | |
| 13420 the info. You might ask why is this important for monitoring .... I think it | |
| 13421 can aid in the detection/prediction of application contention caused by hot-locks. | |
| 13422 </intro> | |
| 13423 </issuessection> | |
| 13424 | |
| 13425 <changehistory id="ChangeHistory" update="09/05/07"> | |
| 13426 <intro> | |
| 13427 The <jvmti/> specification is an evolving document with major, minor, | |
| 13428 and micro version numbers. | |
| 13429 A released version of the specification is uniquely identified | |
| 13430 by its major and minor version. | |
| 13431 The functions, events, and capabilities in this specification | |
| 13432 indicate a "Since" value which is the major and minor version in | |
| 13433 which it was introduced. | |
| 13434 The version of the specification implemented by the VM can | |
| 13435 be retrieved at runtime with the <functionlink id="GetVersionNumber"/> | |
| 13436 function. | |
| 13437 </intro> | |
| 13438 <change date="14 Nov 2002"> | |
| 13439 Converted to XML document. | |
| 13440 </change> | |
| 13441 <change date="14 Nov 2002"> | |
| 13442 Elided heap dump functions (for now) since what was there | |
| 13443 was wrong. | |
| 13444 </change> | |
| 13445 <change date="18 Nov 2002"> | |
| 13446 Added detail throughout. | |
| 13447 </change> | |
| 13448 <change date="18 Nov 2002"> | |
| 13449 Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE. | |
| 13450 </change> | |
| 13451 <change date="19 Nov 2002"> | |
| 13452 Added AsyncGetStackTrace. | |
| 13453 </change> | |
| 13454 <change date="19 Nov 2002"> | |
| 13455 Added jframeID return to GetStackTrace. | |
| 13456 </change> | |
| 13457 <change date="19 Nov 2002"> | |
| 13458 Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there | |
| 13459 since they are redundant with GetStackTrace. | |
| 13460 </change> | |
| 13461 <change date="19 Nov 2002"> | |
| 13462 Elided ClearAllBreakpoints since it has always been redundant. | |
| 13463 </change> | |
| 13464 <change date="19 Nov 2002"> | |
| 13465 Added GetSystemProperties. | |
| 13466 </change> | |
| 13467 <change date="19 Nov 2002"> | |
| 13468 Changed the thread local storage functions to use jthread. | |
| 13469 </change> | |
| 13470 <change date="20 Nov 2002"> | |
| 13471 Added GetJLocationFormat. | |
| 13472 </change> | |
| 13473 <change date="22 Nov 2002"> | |
| 13474 Added events and introductory text. | |
| 13475 </change> | |
| 13476 <change date="22 Nov 2002"> | |
| 13477 Cross reference type and constant definitions. | |
| 13478 </change> | |
| 13479 <change date="24 Nov 2002"> | |
| 13480 Added DTD. | |
| 13481 </change> | |
| 13482 <change date="24 Nov 2002"> | |
| 13483 Added capabilities function section. | |
| 13484 </change> | |
| 13485 <change date="29 Nov 2002"> | |
| 13486 Assign capabilities to each function and event. | |
| 13487 </change> | |
| 13488 <change date="29 Nov 2002"> | |
| 13489 Add <internallink id="jniIntercept">JNI interception functions</internallink>. | |
| 13490 </change> | |
| 13491 <change date="30 Nov 2002"> | |
| 13492 Auto generate SetEventNotificationMode capabilities. | |
| 13493 </change> | |
| 13494 <change date="30 Nov 2002"> | |
| 13495 Add <eventlink id="VMObjectAlloc"></eventlink> event. | |
| 13496 </change> | |
| 13497 <change date="30 Nov 2002"> | |
| 13498 Add <eventlink id="DynamicCodeGenerated"></eventlink> event. | |
| 13499 </change> | |
| 13500 <change date="30 Nov 2002"> | |
| 13501 Add const to declarations. | |
| 13502 </change> | |
| 13503 <change date="30 Nov 2002"> | |
| 13504 Change method exit and frame pop to send on exception. | |
| 13505 </change> | |
| 13506 <change date="1 Dec 2002"> | |
| 13507 Add ForceGarbageCollection. | |
| 13508 </change> | |
| 13509 <change date="2 Dec 2002"> | |
| 13510 Redo Xrun section; clarify GetStackTrace and add example; | |
| 13511 Fix width problems; use "agent" consistently. | |
| 13512 </change> | |
| 13513 <change date="8 Dec 2002"> | |
| 13514 Remove previous start-up intro. | |
| 13515 Add <internallink id="environments"><jvmti/> Environments</internallink> | |
| 13516 section. | |
| 13517 </change> | |
| 13518 <change date="8 Dec 2002"> | |
| 13519 Add <functionlink id="DisposeEnvironment"></functionlink>. | |
| 13520 </change> | |
| 13521 <change date="9 Dec 2002"> | |
| 13522 Numerous minor updates. | |
| 13523 </change> | |
| 13524 <change date="15 Dec 2002"> | |
| 13525 Add heap profiling functions added: | |
| 13526 get/set annotation, iterate live objects/heap. | |
| 13527 Add heap profiling functions place holder added: | |
| 13528 heap roots. | |
| 13529 Heap profiling event added: object free. | |
| 13530 Heap profiling event redesigned: vm object allocation. | |
| 13531 Heap profiling event placeholders added: garbage collection start/finish. | |
| 13532 Native method bind event added. | |
| 13533 </change> | |
| 13534 <change date="19 Dec 2002"> | |
| 13535 Revamp suspend/resume functions. | |
| 13536 Add origin information with jvmdi tag. | |
| 13537 Misc fixes. | |
| 13538 </change> | |
| 13539 <change date="24 Dec 2002"> | |
| 13540 Add semantics to types. | |
| 13541 </change> | |
| 13542 <change date="27 Dec 2002"> | |
| 13543 Add local reference section. | |
| 13544 Autogenerate parameter descriptions from types. | |
| 13545 </change> | |
| 13546 <change date="28 Dec 2002"> | |
| 13547 Document that RunAgentThread sends threadStart. | |
| 13548 </change> | |
| 13549 <change date="29 Dec 2002"> | |
| 13550 Remove redundant local ref and dealloc warning. | |
| 13551 Convert GetRawMonitorName to allocated buffer. | |
| 13552 Add GenerateEvents. | |
| 13553 </change> | |
| 13554 <change date="30 Dec 2002"> | |
| 13555 Make raw monitors a type and rename to "jrawMonitorID". | |
| 13556 </change> | |
| 13557 <change date="1 Jan 2003"> | |
| 13558 Include origin information. | |
| 13559 Clean-up JVMDI issue references. | |
| 13560 Remove Deallocate warnings which are now automatically generated. | |
| 13561 </change> | |
| 13562 <change date="2 Jan 2003"> | |
| 13563 Fix representation issues for jthread. | |
| 13564 </change> | |
| 13565 <change date="3 Jan 2003"> | |
| 13566 Make capabilities buffered out to 64 bits - and do it automatically. | |
| 13567 </change> | |
| 13568 <change date="4 Jan 2003"> | |
| 13569 Make constants which are enumeration into enum types. | |
| 13570 Parameters now of enum type. | |
| 13571 Clean-up and index type section. | |
| 13572 Replace remaining datadef entities with callback. | |
| 13573 </change> | |
| 13574 <change date="7 Jan 2003"> | |
| 13575 Correct GenerateEvents description. | |
| 13576 More internal semantics work. | |
| 13577 </change> | |
| 13578 <change date="9 Jan 2003"> | |
| 13579 Replace previous GetSystemProperties with two functions | |
| 13580 which use allocated information instead fixed. | |
| 13581 Add SetSystemProperty. | |
| 13582 More internal semantics work. | |
| 13583 </change> | |
| 13584 <change date="12 Jan 2003"> | |
| 13585 Add varargs to end of SetEventNotificationMode. | |
| 13586 </change> | |
| 13587 <change date="20 Jan 2003"> | |
| 13588 Finish fixing spec to reflect that alloc sizes are jlong. | |
| 13589 </change> | |
| 13590 <change date="22 Jan 2003"> | |
| 13591 Allow NULL as RunAgentThread arg. | |
| 13592 </change> | |
| 13593 <change date="22 Jan 2003"> | |
| 13594 Fixed names to standardized naming convention | |
| 13595 Removed AsyncGetStackTrace. | |
| 13596 </change> | |
| 13597 <change date="29 Jan 2003"> | |
| 13598 Since we are using jthread, removed GetThread. | |
| 13599 </change> | |
| 13600 <change date="31 Jan 2003"> | |
| 13601 Change GetFieldName to allow NULLs like GetMethodName. | |
| 13602 </change> | |
| 13603 <change date="29 Feb 2003" version="v40"> | |
| 13604 Rewrite the introductory text, adding sections on | |
| 13605 start-up, environments and bytecode instrumentation. | |
| 13606 Change the command line arguments per EG discussions. | |
| 13607 Add an introduction to the capabilities section. | |
| 13608 Add the extension mechanism category and functions. | |
| 13609 Mark for deletion, but clarified anyhow, SuspendAllThreads. | |
| 13610 Rename IterateOverLiveObjects to IterateOverReachableObjects and | |
| 13611 change the text accordingly. | |
| 13612 Clarify IterateOverHeap. | |
| 13613 Clarify CompiledMethodLoad. | |
| 13614 Discuss prerequisite state for Calling Functions. | |
| 13615 Clarify SetAllocationHooks. | |
| 13616 Added issues ("To be resolved:") through-out. | |
| 13617 And so on... | |
| 13618 </change> | |
| 13619 <change date="6 Mar 2003" version="v41"> | |
| 13620 Remove struct from the call to GetOwnedMonitorInfo. | |
| 13621 Automatically generate most error documentation, remove | |
| 13622 (rather broken) hand written error doc. | |
| 13623 Better describe capability use (empty initial set). | |
| 13624 Add min value to jint params. | |
| 13625 Remove the capability can_access_thread_local_storage. | |
| 13626 Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY; | |
| 13627 same for *NOT_IMPLEMENTED. | |
| 13628 Description fixes. | |
| 13629 </change> | |
| 13630 <change date="8 Mar 2003" version="v42"> | |
| 13631 Rename GetClassSignature to GetClassName. | |
| 13632 Rename IterateOverClassObjects to IterateOverInstancesOfClass. | |
| 13633 Remove GetMaxStack (operand stack isn't used in <jvmti/>). | |
| 13634 Description fixes: define launch-time, remove native frame pop | |
| 13635 from PopFrame, and assorted clarifications. | |
| 13636 </change> | |
| 13637 <change date="8 Mar 2003" version="v43"> | |
| 13638 Fix minor editing problem. | |
| 13639 </change> | |
| 13640 <change date="10 Mar 2003" version="v44"> | |
| 13641 Add phase information. | |
| 13642 Remap (compact) event numbers. | |
| 13643 </change> | |
| 13644 <change date="11 Mar 2003" version="v45"> | |
| 13645 More phase information - allow "any". | |
| 13646 Elide raw monitor queries and events. | |
| 13647 Minor description fixes. | |
| 13648 </change> | |
| 13649 <change date="12 Mar 2003" version="v46"> | |
| 13650 Add GetPhase. | |
| 13651 Use "phase" through document. | |
| 13652 Elide GetRawMonitorName. | |
| 13653 Elide GetObjectMonitors. | |
| 13654 </change> | |
| 13655 <change date="12 Mar 2003" version="v47"> | |
| 13656 Fixes from link, XML, and spell checking. | |
| 13657 Auto-generate the callback structure. | |
| 13658 </change> | |
| 13659 <change date="13 Mar 2003" version="v48"> | |
| 13660 One character XML fix. | |
| 13661 </change> | |
| 13662 <change date="13 Mar 2003" version="v49"> | |
| 13663 Change function parameter names to be consistent with | |
| 13664 event parameters (fooBarBaz becomes foo_bar_baz). | |
| 13665 </change> | |
| 13666 <change date="14 Mar 2003" version="v50"> | |
| 13667 Fix broken link. Fix thread markers. | |
| 13668 </change> | |
| 13669 <change date="14 Mar 2003" version="v51"> | |
| 13670 Change constants so they are under 128 to workaround | |
| 13671 compiler problems. | |
| 13672 </change> | |
| 13673 <change date="23 Mar 2003" version="v52"> | |
| 13674 Overhaul capabilities. Separate GetStackTrace into | |
| 13675 GetStackTrace and GetStackFrames. | |
| 13676 </change> | |
| 13677 <change date="8 Apr 2003" version="v54"> | |
| 13678 Use depth instead of jframeID to reference frames. | |
| 13679 Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames. | |
| 13680 Remove frame arg from events. | |
| 13681 </change> | |
| 13682 <change date="9 Apr 2003" version="v55"> | |
| 13683 Remove GetObjectWithAnnotation since tests show bufferred approach more efficient. | |
| 13684 Add missing annotation_count to GetObjectsWithAnnotations | |
| 13685 </change> | |
| 13686 <change date="10 Apr 2003" version="v56"> | |
| 13687 Remove confusing parenthetical statement in GetObjectsWithAnnotations | |
| 13688 </change> | |
| 13689 <change date="13 Apr 2003" version="v58"> | |
| 13690 Replace jclass/jmethodID representation of method with simply jmethodID; | |
| 13691 Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate. | |
| 13692 Replace can_access_frames with can_access_local_variables; remove from purely stack access. | |
| 13693 Use can_get_synthetic_attribute; fix description. | |
| 13694 Clarify that zero length arrays must be deallocated. | |
| 13695 Clarify RelinquishCapabilities. | |
| 13696 Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE. | |
| 13697 </change> | |
| 13698 <change date="27 Apr 2003" version="v59"> | |
| 13699 Remove lingering indirect references to OBSOLETE_METHOD_ID. | |
| 13700 </change> | |
| 13701 <change date="4 May 2003" version="v60"> | |
| 13702 Allow DestroyRawMonitor during OnLoad. | |
| 13703 </change> | |
| 13704 <change date="7 May 2003" version="v61"> | |
| 13705 Added not monitor owner error return to DestroyRawMonitor. | |
| 13706 </change> | |
| 13707 <change date="13 May 2003" version="v62"> | |
| 13708 Clarify semantics of raw monitors. | |
| 13709 Change flags on <code>GetThreadStatus</code>. | |
| 13710 <code>GetClassLoader</code> return NULL for the bootstrap class loader. | |
| 13711 Add <code>GetClassName</code> issue. | |
| 13712 Define local variable signature. | |
| 13713 Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>. | |
| 13714 Remove over specification in <code>GetObjectsWithAnnotations</code>. | |
| 13715 Elide <code>SetAllocationHooks</code>. | |
| 13716 Elide <code>SuspendAllThreads</code>. | |
| 13717 </change> | |
| 13718 <change date="14 May 2003" version="v63"> | |
| 13719 Define the data type <code>jvmtiEventCallbacks</code>. | |
| 13720 Zero length allocations return NULL. | |
| 13721 Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>. | |
| 13722 Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED. | |
| 13723 </change> | |
| 13724 <change date="15 May 2003" version="v64"> | |
| 13725 Better wording, per review. | |
| 13726 </change> | |
| 13727 <change date="15 May 2003" version="v65"> | |
| 13728 First Alpha. | |
| 13729 Make jmethodID and jfieldID unique, jclass not used. | |
| 13730 </change> | |
| 13731 <change date="27 May 2003" version="v66"> | |
| 13732 Fix minor XSLT errors. | |
| 13733 </change> | |
| 13734 <change date="13 June 2003" version="v67"> | |
| 13735 Undo making jfieldID unique (jmethodID still is). | |
| 13736 </change> | |
| 13737 <change date="17 June 2003" version="v68"> | |
| 13738 Changes per June 11th Expert Group meeting -- | |
| 13739 Overhaul Heap functionality: single callback, | |
| 13740 remove GetHeapRoots, add reachable iterators, | |
| 13741 and rename "annotation" to "tag". | |
| 13742 NULL thread parameter on most functions is current | |
| 13743 thread. | |
| 13744 Add timers. | |
| 13745 Remove ForceExit. | |
| 13746 Add GetEnvironmentLocalStorage. | |
| 13747 Add verbose flag and event. | |
| 13748 Add AddToBootstrapClassLoaderSearch. | |
| 13749 Update ClassFileLoadHook. | |
| 13750 </change> | |
| 13751 <change date="18 June 2003" version="v69"> | |
| 13752 Clean up issues sections. | |
| 13753 Rename GetClassName back to GetClassSignature and | |
| 13754 fix description. | |
| 13755 Add generic signature to GetClassSignature, | |
| 13756 GetFieldSignature, GetMethodSignature, and | |
| 13757 GetLocalVariableTable. | |
| 13758 Elide EstimateCostOfCapabilities. | |
| 13759 Clarify that the system property functions operate | |
| 13760 on the VM view of system properties. | |
| 13761 Clarify Agent_OnLoad. | |
| 13762 Remove "const" from JNIEnv* in events. | |
| 13763 Add metadata accessors. | |
| 13764 </change> | |
| 13765 <change date="18 June 2003" version="v70"> | |
| 13766 Add start_depth to GetStackTrace. | |
| 13767 Move system properties to a new category. | |
| 13768 Add GetObjectSize. | |
| 13769 Remove "X" from command line flags. | |
| 13770 XML, HTML, and spell check corrections. | |
| 13771 </change> | |
| 13772 <change date="19 June 2003" version="v71"> | |
| 13773 Fix JVMTI_HEAP_ROOT_THREAD to be 6. | |
| 13774 Make each synopsis match the function name. | |
| 13775 Fix unclear wording. | |
| 13776 </change> | |
| 13777 <change date="26 June 2003" version="v72"> | |
| 13778 SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value | |
| 13779 to be set to NULL. | |
| 13780 NotifyFramePop, GetFrameLocationm and all the local variable operations | |
| 13781 needed to have their wording about frames fixed. | |
| 13782 Grammar and clarity need to be fixed throughout. | |
| 13783 Capitalization and puntuation need to be consistent. | |
| 13784 Need micro version number and masks for accessing major, minor, and micro. | |
| 13785 The error code lists should indicate which must be returned by | |
| 13786 an implementation. | |
| 13787 The command line properties should be visible in the properties functions. | |
| 13788 Disallow popping from the current thread. | |
| 13789 Allow implementations to return opaque frame error when they cannot pop. | |
| 13790 The NativeMethodBind event should be sent during any phase. | |
| 13791 The DynamicCodeGenerated event should be sent during any phase. | |
| 13792 The following functions should be allowed to operate before VMInit: | |
| 13793 Set/GetEnvironmentLocalStorage | |
| 13794 GetMethodDeclaringClass | |
| 13795 GetClassSignature | |
| 13796 GetClassModifiers | |
| 13797 IsInterface | |
| 13798 IsArrayClass | |
| 13799 GetMethodName | |
| 13800 GetMethodModifiers | |
| 13801 GetMaxLocals | |
| 13802 GetArgumentsSize | |
| 13803 GetLineNumberTable | |
| 13804 GetMethodLocation | |
| 13805 IsMethodNative | |
| 13806 IsMethodSynthetic. | |
| 13807 Other changes (to XSL): | |
| 13808 Argument description should show asterisk after not before pointers. | |
| 13809 NotifyFramePop, GetFrameLocationm and all the local variable operations | |
| 13810 should hsve the NO_MORE_FRAMES error added. | |
| 13811 Not alive threads should have a different error return than invalid thread. | |
| 13812 </change> | |
| 13813 <change date="7 July 2003" version="v73"> | |
| 13814 VerboseOutput event was missing message parameter. | |
| 13815 Minor fix-ups. | |
| 13816 </change> | |
| 13817 <change date="14 July 2003" version="v74"> | |
| 13818 Technical Publications Department corrections. | |
| 13819 Allow thread and environment local storage to be set to NULL. | |
| 13820 </change> | |
| 13821 <change date="23 July 2003" version="v75"> | |
| 13822 Use new Agent_OnLoad rather than overloaded JVM_OnLoad. | |
| 13823 Add JNICALL to callbacks (XSL). | |
| 13824 Document JNICALL requirement for both events and callbacks (XSL). | |
| 13825 Restrict RedefineClasses to methods and attributes. | |
| 13826 Elide the VerboseOutput event. | |
| 13827 VMObjectAlloc: restrict when event is sent and remove method parameter. | |
| 13828 Finish loose ends from Tech Pubs edit. | |
| 13829 </change> | |
| 13830 <change date="24 July 2003" version="v76"> | |
| 13831 Change ClassFileLoadHook event to send the class instead of a boolean of redefine. | |
| 13832 </change> | |
| 13833 <change date="24 July 2003" version="v77"> | |
| 13834 XML fixes. | |
| 13835 Minor text clarifications and corrections. | |
| 13836 </change> | |
| 13837 <change date="24 July 2003" version="v78"> | |
| 13838 Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>. | |
| 13839 Clarify that stack frames are JVM Spec frames. | |
| 13840 Split can_get_source_info into can_get_source_file_name, can_get_line_numbers, | |
| 13841 and can_get_source_debug_extension. | |
| 13842 PopFrame cannot have a native calling method. | |
| 13843 Removed incorrect statement in GetClassloaderClasses | |
| 13844 (see http://java.sun.com/docs/books/vmspec/2nd-edition/html/ConstantPool.doc.html#79383). | |
| 13845 </change> | |
| 13846 <change date="24 July 2003" version="v79"> | |
| 13847 XML and text fixes. | |
| 13848 Move stack frame description into Stack Frame category. | |
| 13849 </change> | |
| 13850 <change date="26 July 2003" version="v80"> | |
| 13851 Allow NULL (means bootstrap loader) for GetClassloaderClasses. | |
| 13852 Add new heap reference kinds for references from classes. | |
| 13853 Add timer information struct and query functions. | |
| 13854 Add AvailableProcessors. | |
| 13855 Rename GetOtherThreadCpuTime to GetThreadCpuTime. | |
| 13856 Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE | |
| 13857 to SetEventNotification mode. | |
| 13858 Add initial thread to the VM_INIT event. | |
| 13859 Remove platform assumptions from AddToBootstrapClassLoaderSearch. | |
| 13860 </change> | |
| 13861 <change date="26 July 2003" version="v81"> | |
| 13862 Grammar and clarity changes per review. | |
| 13863 </change> | |
| 13864 <change date="27 July 2003" version="v82"> | |
| 13865 More grammar and clarity changes per review. | |
| 13866 Add Agent_OnUnload. | |
| 13867 </change> | |
| 13868 <change date="28 July 2003" version="v83"> | |
| 13869 Change return type of Agent_OnUnload to void. | |
| 13870 </change> | |
| 13871 <change date="28 July 2003" version="v84"> | |
| 13872 Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT. | |
| 13873 </change> | |
| 13874 <change date="28 July 2003" version="v85"> | |
| 13875 Steal java.lang.Runtime.availableProcessors() wording for | |
| 13876 AvailableProcessors(). | |
| 13877 Guarantee that zero will never be an event ID. | |
| 13878 Remove some issues which are no longer issues. | |
| 13879 Per review, rename and more completely document the timer | |
| 13880 information functions. | |
| 13881 </change> | |
| 13882 <change date="29 July 2003" version="v86"> | |
| 13883 Non-spec visible change to XML controlled implementation: | |
| 13884 SetThreadLocalStorage must run in VM mode. | |
| 13885 </change> | |
| 13886 <change date="5 August 2003" version="0.1.87"> | |
| 13887 Add GetErrorName. | |
| 13888 Add varargs warning to jvmtiExtensionEvent. | |
| 13889 Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent. | |
| 13890 Remove unused can_get_exception_info capability. | |
| 13891 Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction. | |
| 13892 Fix jvmtiExtensionFunctionInfo.func declared type. | |
| 13893 Extension function returns error code. | |
| 13894 Use new version numbering. | |
| 13895 </change> | |
| 13896 <change date="5 August 2003" version="0.2.88"> | |
| 13897 Remove the ClassUnload event. | |
| 13898 </change> | |
| 13899 <change date="8 August 2003" version="0.2.89"> | |
| 13900 Heap reference iterator callbacks return an enum that | |
| 13901 allows outgoing object references to be ignored. | |
| 13902 Allow JNIEnv as a param type to extension events/functions. | |
| 13903 </change> | |
| 13904 <change date="15 August 2003" version="0.2.90"> | |
| 13905 Fix a typo. | |
| 13906 </change> | |
| 13907 <change date="2 September 2003" version="0.2.91"> | |
| 13908 Remove all metadata functions: GetClassMetadata, | |
| 13909 GetFieldMetadata, and GetMethodMetadata. | |
| 13910 </change> | |
| 13911 <change date="1 October 2003" version="0.2.92"> | |
| 13912 Mark the functions Allocate. Deallocate, RawMonitor*, | |
| 13913 SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage | |
| 13914 as safe for use in heap callbacks and GC events. | |
| 13915 </change> | |
| 13916 <change date="24 November 2003" version="0.2.93"> | |
| 13917 Add pass through opaque user data pointer to heap iterate | |
| 13918 functions and callbacks. | |
| 13919 In the CompiledMethodUnload event, send the code address. | |
| 13920 Add GarbageCollectionOccurred event. | |
| 13921 Add constant pool reference kind. | |
| 13922 Mark the functions CreateRawMonitor and DestroyRawMonitor | |
| 13923 as safe for use in heap callbacks and GC events. | |
| 13924 Clarify: VMDeath, GetCurrentThreadCpuTimerInfo, | |
| 13925 GetThreadCpuTimerInfo, IterateOverReachableObjects, | |
| 13926 IterateOverObjectsReachableFromObject, GetTime and | |
| 13927 JVMTI_ERROR_NULL_POINTER. | |
| 13928 Add missing errors to: GenerateEvents and | |
| 13929 AddToBootstrapClassLoaderSearch. | |
| 13930 Fix description of ClassFileLoadHook name parameter. | |
| 13931 In heap callbacks and GC/ObjectFree events, specify | |
| 13932 that only explicitly allowed functions can be called. | |
| 13933 Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime, | |
| 13934 GetTimerInfo, and GetTime during callback. | |
| 13935 Allow calling SetTag/GetTag during the onload phase. | |
| 13936 SetEventNotificationMode, add: error attempted inappropriate | |
| 13937 thread level control. | |
| 13938 Remove jvmtiExceptionHandlerEntry. | |
| 13939 Fix handling of native methods on the stack -- | |
| 13940 location_ptr param of GetFrameLocation, remove | |
| 13941 JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation, | |
| 13942 jvmtiFrameInfo.location, and jlocation. | |
| 13943 Remove typo (from JVMPI) implying that the MonitorWaited | |
| 13944 event is sent on sleep. | |
| 13945 </change> | |
| 13946 <change date="25 November 2003" version="0.2.94"> | |
| 13947 Clarifications and typos. | |
| 13948 </change> | |
| 13949 <change date="3 December 2003" version="0.2.95"> | |
| 13950 Allow NULL user_data in heap iterators. | |
| 13951 </change> | |
| 13952 <change date="28 January 2004" version="0.2.97"> | |
| 13953 Add GetThreadState, deprecate GetThreadStatus. | |
| 13954 </change> | |
| 13955 <change date="29 January 2004" version="0.2.98"> | |
| 13956 INVALID_SLOT and TYPE_MISMATCH errors should be optional. | |
| 13957 </change> | |
| 13958 <change date="12 February 2004" version="0.2.102"> | |
| 13959 Remove MonitorContendedExit. | |
| 13960 Added JNIEnv parameter to VMObjectAlloc. | |
| 13961 Clarified definition of class_tag and referrer_index | |
| 13962 parameters to heap callbacks. | |
| 13963 </change> | |
| 13964 <change date="16 Febuary 2004" version="0.2.103"> | |
| 13965 Document JAVA_TOOL_OPTIONS. | |
| 13966 </change> | |
| 13967 <change date="17 Febuary 2004" version="0.2.105"> | |
| 13968 Divide start phase into primordial and start. | |
| 13969 Add VMStart event | |
| 13970 Change phase associations of functions and events. | |
| 13971 </change> | |
| 13972 <change date="18 Febuary 2004" version="0.3.6"> | |
| 13973 Elide deprecated GetThreadStatus. | |
| 13974 Bump minor version, subtract 100 from micro version | |
| 13975 </change> | |
| 13976 <change date="18 Febuary 2004" version="0.3.7"> | |
| 13977 Document that timer nanosecond values are unsigned. | |
| 13978 Clarify text having to do with native methods. | |
| 13979 </change> | |
| 13980 <change date="19 Febuary 2004" version="0.3.8"> | |
| 13981 Fix typos. | |
| 13982 Remove elided deprecated GetThreadStatus. | |
| 13983 </change> | |
| 13984 <change date="23 Febuary 2004" version="0.3.9"> | |
| 13985 Require NotifyFramePop to act on suspended threads. | |
| 13986 </change> | |
| 13987 <change date="24 Febuary 2004" version="0.3.10"> | |
| 13988 Add capabilities | |
| 13989 (<internallink id="jvmtiCapabilities.can_redefine_any_class" | |
| 13990 ><code>can_redefine_any_class</code></internallink> | |
| 13991 and | |
| 13992 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events" | |
| 13993 ><code>can_generate_all_class_hook_events</code></internallink>) | |
| 13994 and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>) | |
| 13995 which allow some classes to be unmodifiable. | |
| 13996 </change> | |
| 13997 <change date="28 Febuary 2004" version="0.3.11"> | |
| 13998 Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode. | |
| 13999 </change> | |
| 14000 <change date="8 March 2004" version="0.3.12"> | |
| 14001 Clarified CompiledMethodUnload so that it is clear the event | |
| 14002 may be posted after the class has been unloaded. | |
| 14003 </change> | |
| 14004 <change date="5 March 2004" version="0.3.13"> | |
| 14005 Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize. | |
| 14006 </change> | |
| 14007 <change date="13 March 2004" version="0.3.14"> | |
| 14008 Added guideline for the use of the JNI FindClass function in event | |
| 14009 callback functions. | |
| 14010 </change> | |
| 14011 <change date="15 March 2004" version="0.3.15"> | |
| 14012 Add GetAllStackTraces and GetThreadListStackTraces. | |
| 14013 </change> | |
| 14014 <change date="19 March 2004" version="0.3.16"> | |
| 14015 ClassLoad and ClassPrepare events can be posted during start phase. | |
| 14016 </change> | |
| 14017 <change date="25 March 2004" version="0.3.17"> | |
| 14018 Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable, | |
| 14019 GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes. | |
| 14020 </change> | |
| 14021 <change date="29 March 2004" version="0.3.18"> | |
| 14022 Return the timer kind in the timer information structure. | |
| 14023 </change> | |
| 14024 <change date="31 March 2004" version="0.3.19"> | |
| 14025 Spec clarifications: | |
| 14026 JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>. | |
| 14027 ForceGarbageCollection does not run finalizers. | |
| 14028 The context of the specification is the Java platform. | |
| 14029 Warn about early instrumentation. | |
| 14030 </change> | |
| 14031 <change date="1 April 2004" version="0.3.20"> | |
| 14032 Refinements to the above clarifications and | |
| 14033 Clarify that an error returned by Agent_OnLoad terminates the VM. | |
| 14034 </change> | |
| 14035 <change date="1 April 2004" version="0.3.21"> | |
| 14036 Array class creation does not generate a class load event. | |
| 14037 </change> | |
| 14038 <change date="7 April 2004" version="0.3.22"> | |
| 14039 Align thread state hierarchy more closely with java.lang.Thread.State. | |
| 14040 </change> | |
| 14041 <change date="12 April 2004" version="0.3.23"> | |
| 14042 Clarify the documentation of thread state. | |
| 14043 </change> | |
| 14044 <change date="19 April 2004" version="0.3.24"> | |
| 14045 Remove GarbageCollectionOccurred event -- can be done by agent. | |
| 14046 </change> | |
| 14047 <change date="22 April 2004" version="0.3.25"> | |
| 14048 Define "command-line option". | |
| 14049 </change> | |
| 14050 <change date="29 April 2004" version="0.3.26"> | |
| 14051 Describe the intended use of bytecode instrumentation. | |
| 14052 Fix description of extension event first parameter. | |
| 14053 </change> | |
| 14054 <change date="30 April 2004" version="0.3.27"> | |
| 14055 Clarification and typos. | |
| 14056 </change> | |
| 14057 <change date="18 May 2004" version="0.3.28"> | |
| 14058 Remove DataDumpRequest event. | |
| 14059 </change> | |
| 14060 <change date="18 May 2004" version="0.3.29"> | |
| 14061 Clarify RawMonitorWait with zero timeout. | |
| 14062 Clarify thread state after RunAgentThread. | |
| 14063 </change> | |
| 14064 <change date="24 May 2004" version="0.3.30"> | |
| 14065 Clean-up: fix bad/old links, etc. | |
| 14066 </change> | |
| 14067 <change date="30 May 2004" version="0.3.31"> | |
| 14068 Clarifications including: | |
| 14069 All character strings are modified UTF-8. | |
| 14070 Agent thread visibiity. | |
| 14071 Meaning of obsolete method version. | |
| 14072 Thread invoking heap callbacks, | |
| 14073 </change> | |
| 14074 <change date="1 June 2004" version="1.0.32"> | |
| 14075 Bump major.minor version numbers to "1.0". | |
| 14076 </change> | |
| 14077 <change date="2 June 2004" version="1.0.33"> | |
| 14078 Clarify interaction between ForceGarbageCollection | |
| 14079 and ObjectFree. | |
| 14080 </change> | |
| 14081 <change date="6 June 2004" version="1.0.34"> | |
| 14082 Restrict AddToBootstrapClassLoaderSearch and | |
| 14083 SetSystemProperty to the OnLoad phase only. | |
| 14084 </change> | |
| 14085 <change date="11 June 2004" version="1.0.35"> | |
| 14086 Fix typo in SetTag. | |
| 14087 </change> | |
| 14088 <change date="18 June 2004" version="1.0.36"> | |
| 14089 Fix trademarks. | |
| 14090 Add missing parameter in example GetThreadState usage. | |
| 14091 </change> | |
| 14092 <change date="4 August 2004" version="1.0.37"> | |
| 14093 Copyright updates. | |
| 14094 </change> | |
| 14095 <change date="5 November 2004" version="1.0.38"> | |
| 14096 Add missing function table layout. | |
| 14097 Add missing description of C++ member function format of functions. | |
| 14098 Clarify that name in CFLH can be NULL. | |
| 14099 Released as part of <tm>J2SE</tm> 5.0. | |
| 14100 </change> | |
| 14101 <change date="24 April 2005" version="1.1.47"> | |
| 14102 Bump major.minor version numbers to "1.1". | |
| 14103 Add ForceEarlyReturn* functions. | |
| 14104 Add GetOwnedMonitorStackDepthInfo function. | |
| 14105 Add GetCurrentThread function. | |
| 14106 Add "since" version marker. | |
| 14107 Add AddToSystemClassLoaderSearch. | |
| 14108 Allow AddToBootstrapClassLoaderSearch be used in live phase. | |
| 14109 Fix historic rubbish in the descriptions of the heap_object_callback | |
| 14110 parameter of IterateOverHeap and IterateOverInstancesOfClass functions; | |
| 14111 disallow NULL for this parameter. | |
| 14112 Clarify, correct and make consistent: wording about current thread, | |
| 14113 opaque frames and insufficient number of frames in PopFrame. | |
| 14114 Consistently use "current frame" rather than "topmost". | |
| 14115 Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal* | |
| 14116 by making them compatible with those in ForceEarlyReturn*. | |
| 14117 Many other clarifications and wording clean ups. | |
| 14118 </change> | |
| 14119 <change date="25 April 2005" version="1.1.48"> | |
| 14120 Add GetConstantPool. | |
| 14121 Switch references to the first edition of the VM Spec, to the seconds edition. | |
| 14122 </change> | |
| 14123 <change date="26 April 2005" version="1.1.49"> | |
| 14124 Clarify minor/major version order in GetConstantPool. | |
| 14125 </change> | |
| 14126 <change date="26 April 2005" version="1.1.50"> | |
| 14127 Add SetNativeMethodPrefix and SetNativeMethodPrefixes. | |
| 14128 Reassign GetOwnedMonitorStackDepthInfo to position 153. | |
| 14129 Break out Class Loader Search in its own documentation category. | |
| 14130 Deal with overly long lines in XML source. | |
| 14131 </change> | |
| 14132 <change date="29 April 2005" version="1.1.51"> | |
| 14133 Allow agents be started in the live phase. | |
| 14134 Added paragraph about deploying agents. | |
| 14135 </change> | |
| 14136 <change date="30 April 2005" version="1.1.52"> | |
| 14137 Add specification description to SetNativeMethodPrefix(es). | |
| 14138 Better define the conditions on GetConstantPool. | |
| 14139 </change> | |
| 14140 <change date="30 April 2005" version="1.1.53"> | |
| 14141 Break out the GetClassVersionNumber function from GetConstantPool. | |
| 14142 Clean-up the references to the VM Spec. | |
| 14143 </change> | |
| 14144 <change date="1 May 2005" version="1.1.54"> | |
| 14145 Allow SetNativeMethodPrefix(es) in any phase. | |
| 14146 Add clarifications about the impact of redefinition on GetConstantPool. | |
| 14147 </change> | |
| 14148 <change date="2 May 2005" version="1.1.56"> | |
| 14149 Various clarifications to SetNativeMethodPrefix(es). | |
| 14150 </change> | |
| 14151 <change date="2 May 2005" version="1.1.57"> | |
| 14152 Add missing performance warning to the method entry event. | |
| 14153 </change> | |
| 14154 <change date="5 May 2005" version="1.1.58"> | |
| 14155 Remove internal JVMDI support. | |
| 14156 </change> | |
| 14157 <change date="8 May 2005" version="1.1.59"> | |
| 14158 Add <functionlink id="RetransformClasses"/>. | |
| 14159 Revamp the bytecode instrumentation documentation. | |
| 14160 Change <functionlink id="IsMethodObsolete"/> to no longer | |
| 14161 require the can_redefine_classes capability. | |
| 14162 </change> | |
| 14163 <change date="11 May 2005" version="1.1.63"> | |
| 14164 Clarifications for retransformation. | |
| 14165 </change> | |
| 14166 <change date="11 May 2005" version="1.1.64"> | |
| 14167 Clarifications for retransformation, per review. | |
| 14168 Lock "retransformation (in)capable" at class load enable time. | |
| 14169 </change> | |
| 14170 <change date="4 June 2005" version="1.1.67"> | |
| 14171 Add new heap functionity which supports reporting primitive values, | |
| 14172 allows setting the referrer tag, and has more powerful filtering: | |
| 14173 FollowReferences, IterateThroughHeap, and their associated | |
| 14174 callbacks, structs, enums, and constants. | |
| 14175 </change> | |
| 14176 <change date="4 June 2005" version="1.1.68"> | |
| 14177 Clarification. | |
| 14178 </change> | |
| 14179 <change date="6 June 2005" version="1.1.69"> | |
| 14180 FollowReferences, IterateThroughHeap: Put callbacks in a struct; | |
| 14181 Add missing error codes; reduce bits in the visit control flags. | |
| 14182 </change> | |
| 14183 <change date="14 June 2005" version="1.1.70"> | |
| 14184 More on new heap functionity: spec clean-up per review. | |
| 14185 </change> | |
| 14186 <change date="15 June 2005" version="1.1.71"> | |
| 14187 More on new heap functionity: Rename old heap section to Heap (1.0). | |
| 14188 </change> | |
| 14189 <change date="21 June 2005" version="1.1.72"> | |
| 14190 Fix typos. | |
| 14191 </change> | |
| 14192 <change date="27 June 2005" version="1.1.73"> | |
| 14193 Make referrer info structure a union. | |
| 14194 </change> | |
| 14195 <change date="9 September 2005" version="1.1.74"> | |
| 14196 In new heap functions: | |
| 14197 Add missing superclass reference kind. | |
| 14198 Use a single scheme for computing field indexes. | |
| 14199 Remove outdated references to struct based referrer info. | |
| 14200 </change> | |
| 14201 <change date="12 September 2005" version="1.1.75"> | |
| 14202 Don't callback during FollowReferences on frivolous java.lang.Object superclass. | |
| 14203 </change> | |
| 14204 <change date="13 September 2005" version="1.1.76"> | |
| 14205 In string primitive callback, length now Unicode length. | |
| 14206 In array and string primitive callbacks, value now "const". | |
| 14207 Note possible compiler impacts on setting JNI function table. | |
| 14208 </change> | |
| 14209 <change date="13 September 2005" version="1.1.77"> | |
| 14210 GetClassVersionNumbers() and GetConstantPool() should return | |
| 14211 error on array or primitive class. | |
| 14212 </change> | |
| 14213 <change date="14 September 2005" version="1.1.78"> | |
| 14214 Grammar fixes. | |
| 14215 </change> | |
| 14216 <change date="26 September 2005" version="1.1.79"> | |
| 14217 Add IsModifiableClass query. | |
| 14218 </change> | |
| 14219 <change date="9 February 2006" version="1.1.81"> | |
| 14220 Add referrer_class_tag parameter to jvmtiHeapReferenceCallback. | |
| 14221 </change> | |
| 14222 <change date="13 February 2006" version="1.1.82"> | |
| 14223 Doc fixes: update can_redefine_any_class to include retransform. | |
| 14224 Clarify that exception events cover all Throwables. | |
| 14225 In GetStackTrace, no test is done for start_depth too big if start_depth is zero, | |
| 14226 Clarify fields reported in Primitive Field Callback -- static vs instance. | |
| 14227 Repair confusing names of heap types, including callback names. | |
| 14228 Require consistent usage of stack depth in the face of thread launch methods. | |
| 14229 Note incompatibility of <jvmti/> memory management with other systems. | |
| 14230 </change> | |
| 14231 <change date="14 February 2006" version="1.1.85"> | |
| 14232 Fix typos and missing renames. | |
| 14233 </change> | |
| 14234 <change date="13 March 2006" version="1.1.86"> | |
| 14235 Clarify that jmethodIDs and jfieldIDs can be saved. | |
| 14236 Clarify that Iterate Over Instances Of Class includes subclasses. | |
| 14237 </change> | |
| 14238 <change date="14 March 2006" version="1.1.87"> | |
| 14239 Better phrasing. | |
| 14240 </change> | |
| 14241 <change date="16 March 2006" version="1.1.88"> | |
| 14242 Match the referrer_index for static fields in Object Reference Callback | |
| 14243 with the Reference Implementation (and all other known implementations); | |
| 14244 that is, make it match the definition for instance fields. | |
| 14245 In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover | |
| 14246 an invalid thread in the list; and specify that not started threads | |
| 14247 return empty stacks. | |
| 14248 </change> | |
| 14249 <change date="17 March 2006" version="1.1.89"> | |
| 14250 Typo. | |
| 14251 </change> | |
| 14252 <change date="25 March 2006" version="1.1.90"> | |
| 14253 Typo. | |
| 14254 </change> | |
| 14255 <change date="6 April 2006" version="1.1.91"> | |
| 14256 Remove restrictions on AddToBootstrapClassLoaderSearch and | |
| 14257 AddToSystemClassLoaderSearch. | |
| 14258 </change> | |
| 14259 <change date="1 May 2006" version="1.1.93"> | |
| 14260 Changed spec to return -1 for monitor stack depth for the | |
| 14261 implementation which can not determine stack depth. | |
| 14262 </change> | |
| 14263 <change date="3 May 2006" version="1.1.94"> | |
| 14264 Corrections for readability and accuracy courtesy of Alan Pratt of IBM. | |
| 14265 List the object relationships reported in FollowReferences. | |
| 14266 </change> | |
| 14267 <change date="5 May 2006" version="1.1.95"> | |
| 14268 Clarify the object relationships reported in FollowReferences. | |
| 14269 </change> | |
| 14270 <change date="28 June 2006" version="1.1.98"> | |
| 14271 Clarify DisposeEnvironment; add warning. | |
| 14272 Fix typos in SetLocalXXX "retrieve" => "set". | |
| 14273 Clarify that native method prefixes must remain set while used. | |
| 14274 Clarify that exactly one Agent_OnXXX is called per agent. | |
| 14275 Clarify that library loading is independent from start-up. | |
| 14276 Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec. | |
| 14277 </change> | |
| 14278 <change date="31 July 2006" version="1.1.99"> | |
| 14279 Clarify the interaction between functions and exceptions. | |
| 14280 Clarify and give examples of field indices. | |
| 14281 Remove confusing "That is" sentence from MonitorWait and MonitorWaited events. | |
| 14282 Update links to point to Java 6. | |
| 14283 </change> | |
| 14284 <change date="6 August 2006" version="1.1.102"> | |
| 14285 Add ResourceExhaustedEvent. | |
| 14286 </change> | |
| 14287 </changehistory> | |
| 14288 | |
| 14289 </specification> | |
| 14290 <!-- Keep this comment at the end of the file | |
| 14291 Local variables: | |
| 14292 mode: sgml | |
| 14293 sgml-omittag:t | |
| 14294 sgml-shorttag:t | |
| 14295 sgml-namecase-general:t | |
| 14296 sgml-general-insert-case:lower | |
| 14297 sgml-minimize-attributes:nil | |
| 14298 sgml-always-quote-attributes:t | |
| 14299 sgml-indent-step:2 | |
| 14300 sgml-indent-data:t | |
| 14301 sgml-parent-document:nil | |
| 14302 sgml-exposed-tags:nil | |
| 14303 sgml-local-catalogs:nil | |
| 14304 sgml-local-ecat-files:nil | |
| 14305 End: | |
| 14306 --> |