Mercurial > hg > truffle
annotate src/share/vm/prims/jvmti.xml @ 10981:5c89346f2bdd
6493116: JVMTI Doc: GetOwnedMonitorStackDepthInfo has a typo in monitor_info_ptr parameter description
Summary: A typo in the parameter spelling, a bound update missed when the parameter was renamed
Reviewed-by: sla, minqi
Contributed-by: serguei.spitsyn@oracle.com
| author | sspitsyn |
|---|---|
| date | Fri, 14 Jun 2013 15:17:10 -0700 |
| parents | 73e64867adb7 |
| children | f92b82d454fa |
| rev | line source |
|---|---|
| 0 | 1 <?xml version="1.0" encoding="ISO-8859-1"?> |
| 2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?> | |
| 3 <!-- | |
| 6919 | 4 Copyright (c) 2002, 2012, 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 | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
283 <!ELEMENT vmspec EMPTY> |
|
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
284 <!ATTLIST vmspec chapter CDATA #IMPLIED> |
| 0 | 285 |
| 286 <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*> | |
| 287 <!ATTLIST internallink id CDATA #REQUIRED> | |
| 288 | |
| 289 <!ELEMENT functionphaselist EMPTY> | |
| 290 <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED> | |
| 291 | |
| 292 <!ELEMENT eventphaselist EMPTY> | |
| 293 <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED> | |
| 294 | |
| 295 <!ELEMENT issue ANY> | |
| 296 | |
| 297 <!ELEMENT rationale ANY> | |
| 298 | |
| 299 <!ELEMENT todo ANY> | |
| 300 | |
| 301 <!ELEMENT origin (#PCDATA)*> | |
| 302 | |
| 303 <!ELEMENT elide (intro|function|callback|event)*> | |
| 304 <!ATTLIST elide why CDATA #IMPLIED> | |
| 305 | |
| 306 <!ELEMENT constants (constant*)> | |
| 307 <!ATTLIST constants id CDATA #REQUIRED | |
| 308 label CDATA #REQUIRED | |
| 309 kind (enum|bits|const) #REQUIRED | |
| 310 since CDATA "1.0"> | |
| 311 | |
| 312 <!ELEMENT constant ANY> | |
| 313 <!ATTLIST constant id CDATA #REQUIRED | |
| 314 num CDATA #REQUIRED> | |
| 315 | |
| 316 <!ELEMENT tm (#PCDATA)> | |
| 317 | |
| 318 <!ELEMENT i (#PCDATA|jvmti|tm)*> | |
| 319 | |
| 320 <!ELEMENT b (#PCDATA|jvmti|code)*> | |
| 321 | |
| 322 <!ELEMENT code (#PCDATA|space)*> | |
| 323 | |
| 324 <!ELEMENT pre ANY> | |
| 325 | |
| 326 <!ELEMENT space EMPTY> | |
| 327 | |
| 328 <!ELEMENT jvmti EMPTY> | |
| 329 | |
| 330 <!ELEMENT example (#PCDATA|i)*> | |
| 331 | |
| 332 <!ELEMENT br EMPTY> | |
| 333 | |
| 334 <!ELEMENT p EMPTY> | |
| 335 | |
| 336 <!ELEMENT dl (dt|dd)+> | |
| 337 | |
| 338 <!ELEMENT dd ANY> | |
| 339 | |
| 340 <!ELEMENT dt (#PCDATA|jvmti|code|i|b)*> | |
| 341 | |
| 342 <!ELEMENT table (tr)+> | |
| 343 | |
| 344 <!ELEMENT tr (td|th)*> | |
| 345 | |
| 346 <!ELEMENT td ANY> | |
| 347 <!ATTLIST td align (left|right|center) "center"> | |
| 348 | |
| 349 <!ELEMENT th ANY> | |
| 350 <!ATTLIST th align (left|right|center) "center"> | |
| 351 | |
| 352 <!ELEMENT ul (li)+> | |
| 353 <!ATTLIST ul type (disc|circle|square) "disc"> | |
| 354 | |
| 355 <!ELEMENT li ANY> | |
| 356 ]> | |
| 357 | |
| 358 <specification label="JVM(TM) Tool Interface" | |
| 359 majorversion="1" | |
| 1988 | 360 minorversion="2" |
| 6919 | 361 microversion="2"> |
| 0 | 362 <title subtitle="Version"> |
| 363 <tm>JVM</tm> Tool Interface | |
| 364 </title> | |
| 365 | |
| 366 <intro id="whatIs" label="What is the JVM Tool Interface?"> | |
| 367 The <tm>JVM</tm> Tool Interface (<jvmti/>) | |
| 368 is a programming interface used by development and monitoring tools. | |
| 369 It provides both a way to inspect the state and | |
| 370 to control the execution of applications running in the | |
| 371 <tm>Java</tm> virtual machine (VM). | |
| 372 <p/> | |
| 373 <jvmti/> is intended to provide a VM interface for the full breadth of tools | |
| 374 that need access to VM state, including but not limited to: profiling, | |
| 375 debugging, monitoring, thread analysis, and coverage analysis tools. | |
| 376 <p/> | |
| 377 <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual | |
| 378 machine. | |
| 379 <p/> | |
| 380 <jvmti/> is a two-way interface. | |
| 381 A client of <jvmti/>, hereafter called an <i>agent</i>, | |
| 382 can be notified of | |
| 383 interesting occurrences through <internallink id="EventSection">events</internallink>. | |
| 384 <jvmti/> | |
| 385 can query and control the application through many | |
| 386 <internallink id="FunctionSection">functions</internallink>, | |
| 387 either in response to events or | |
| 388 independent of them. | |
| 389 <p/> | |
| 390 Agents run in the same process with and communicate directly with | |
| 391 the virtual machine executing | |
| 392 the application being examined. This communication is | |
| 393 through a native interface (<jvmti/>). The native in-process interface allows | |
| 394 maximal control with minimal intrusion on the part of a tool. | |
| 395 Typically, agents are relatively compact. They can be controlled | |
| 396 by a separate process which implements the bulk of a tool's | |
| 397 function without interfering with the target application's normal execution. | |
| 398 </intro> | |
| 399 | |
| 400 <intro id="architecture" label="Architecture"> | |
| 401 Tools can be written directly to <jvmti/> or indirectly | |
| 402 through higher level interfaces. | |
| 403 The Java Platform Debugger Architecture includes <jvmti/>, but also | |
| 404 contains higher-level, out-of-process debugger interfaces. The higher-level | |
| 405 interfaces are more appropriate than <jvmti/> for many tools. | |
| 406 For more information on the Java Platform Debugger Architecture, | |
| 407 see the | |
| 6919 | 408 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/architecture.html">Java |
| 0 | 409 Platform Debugger Architecture website</externallink>. |
| 410 </intro> | |
| 411 | |
| 412 <intro id="writingAgents" label="Writing Agents"> | |
| 413 Agents can be written in any native language that supports C | |
| 414 language calling conventions and C or C++ | |
| 415 definitions. | |
| 416 <p/> | |
| 417 The function, event, data type, and constant definitions needed for | |
| 418 using <jvmti/> are defined in the include file <code>jvmti.h</code>. | |
| 419 To use these definitions add the <tm>J2SE</tm> include directory | |
| 420 to your include path and add | |
| 421 <example> | |
| 422 #include <jvmti.h> | |
| 423 </example> | |
| 424 to your source code. | |
| 425 </intro> | |
| 426 | |
| 427 <intro id="deployingAgents" label="Deploying Agents"> | |
| 428 An agent is deployed in a platform specific manner but is typically the | |
| 429 platform equivalent of a dynamic library. On the <tm>Windows</tm> operating | |
| 430 system, for example, an agent library is a "Dynamic Linked Library" (DLL). | |
| 431 On the <tm>Solaris</tm> Operating Environment, an agent library is a shared | |
| 432 object (<code>.so</code> file). | |
| 433 <p/> | |
| 434 An agent may be started at VM startup by specifying the agent library | |
| 435 name using a <internallink id="starting">command line option</internallink>. | |
| 436 Some implementations may support a mechanism to <internallink id="onattach"> | |
| 437 start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>. | |
| 438 The details of how this is initiated are implementation specific. | |
| 439 </intro> | |
| 440 | |
| 441 <intro id="starting" label="Agent Command Line Options"> | |
| 442 The term "command-line option" is used below to | |
| 443 mean options supplied in the <code>JavaVMInitArgs</code> argument | |
| 444 to the <code>JNI_CreateJavaVM</code> function of the JNI | |
| 445 Invocation API. | |
| 446 <p/> | |
| 447 One of the two following | |
| 448 command-line options is used on VM startup to | |
| 449 properly load and run agents. | |
| 450 These arguments identify the library containing | |
| 451 the agent as well as an options | |
| 452 string to be passed in at startup. | |
| 453 <dl> | |
| 454 <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt> | |
| 455 <dd> | |
| 456 The name following <code>-agentlib:</code> is the name of the | |
| 457 library to load. Lookup of the library, both its full name and location, | |
| 458 proceeds in a platform-specific manner. | |
| 459 Typically, the <i><agent-lib-name></i> is expanded to an | |
| 460 operating system specific file name. | |
| 461 The <i><options></i> will be passed to the agent on start-up. | |
| 462 For example, if the option | |
| 463 <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to | |
| 464 load the shared library <code>foo.dll</code> from the system <code>PATH</code> | |
| 465 under <tm>Windows</tm> or <code>libfoo.so</code> from the | |
| 466 <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment. | |
| 467 </dd> | |
| 468 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt> | |
| 469 <dd> | |
| 470 The path following <code>-agentpath:</code> is the absolute path from which | |
| 471 to load the library. | |
| 472 No library name expansion will occur. | |
| 473 The <i><options></i> will be passed to the agent on start-up. | |
| 474 For example, if the option | |
| 475 <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to | |
| 476 load the shared library <code>c:\myLibs\foo.dll</code>. | |
| 477 </dd> | |
| 478 </dl> | |
| 479 The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink> | |
| 480 in the library will be invoked. | |
| 481 <p/> | |
| 482 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code> | |
| 483 will be searched for JNI native method implementations to facilitate the | |
| 484 use of Java programming language code in tools, as is needed for | |
| 485 <internallink id="bci">bytecode instrumentation</internallink>. | |
| 486 <p/> | |
| 487 The agent libraries will be searched after all other libraries have been | |
| 488 searched (agents wishing to override or intercept the native method | |
| 489 implementations of non-agent methods can use the | |
| 490 <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>). | |
| 491 <p/> | |
| 492 These switches do the above and nothing more - they do not change the | |
| 493 state of the VM or <jvmti/>. No command line options are needed | |
| 494 to enable <jvmti/> | |
| 495 or aspects of <jvmti/>, this is handled programmatically | |
| 496 by the use of | |
| 497 <internallink id="capability">capabilities</internallink>. | |
| 498 </intro> | |
| 499 | |
| 500 <intro id="startup" label="Agent Start-Up"> | |
| 501 The VM starts each agent by invoking a start-up function. | |
| 502 If the agent is started in the <code>OnLoad</code> | |
| 503 <functionlink id="GetPhase">phase</functionlink> the function | |
| 504 <internallink id="onload"><code>Agent_OnLoad</code></internallink> | |
| 505 will be invoked. | |
| 506 If the agent is started in the live | |
| 507 <functionlink id="GetPhase">phase</functionlink> the function | |
| 508 <internallink id="onattach"><code>Agent_OnAttach</code></internallink> | |
| 509 will be invoked. | |
| 510 Exactly one call to a start-up function is made per agent. | |
| 511 </intro> | |
| 512 | |
| 513 <intro id="onload" label="Agent Start-Up (OnLoad phase)"> | |
| 514 If an agent is started during the <code>OnLoad</code> phase then its | |
| 515 agent library must export a start-up function with the following prototype: | |
| 516 <example> | |
| 517 JNIEXPORT jint JNICALL | |
| 518 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example> | |
| 519 The VM will start the agent by calling this function. | |
| 520 It will be called early enough in VM initialization that: | |
| 521 <ul> | |
| 522 <li><functionlink id="SetSystemProperty">system properties</functionlink> | |
| 523 may be set before they have been used in the start-up of the VM</li> | |
| 524 <li>the full set of | |
| 525 <internallink id="capability">capabilities</internallink> | |
| 526 is still available (note that capabilities that configure the VM | |
| 527 may only be available at this time--see the | |
| 528 <internallink id="capability">Capability function section</internallink>)</li> | |
| 529 <li>no bytecodes have executed</li> | |
| 530 <li>no classes have been loaded</li> | |
| 531 <li>no objects have been created</li> | |
| 532 </ul> | |
| 533 <p/> | |
| 534 The VM will call the <code>Agent_OnLoad</code> function with | |
| 535 <i><options></i> as the second argument - | |
| 536 that is, using the command-line option examples, | |
| 537 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> | |
| 538 argument of <code>Agent_OnLoad</code>. | |
| 539 The <code>options</code> argument is encoded as a | |
| 540 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 541 If <i>=<options></i> is not specified, | |
| 542 a zero length string is passed to <code>options</code>. | |
| 543 The lifespan of the <code>options</code> string is the <code>Agent_OnLoad</code> | |
| 544 call. If needed beyond this time the string or parts of the string must | |
| 545 be copied. | |
| 546 The period between when <code>Agent_OnLoad</code> is called and when it | |
| 547 returns is called the <i>OnLoad phase</i>. | |
| 548 Since the VM is not initialized during the OnLoad | |
| 549 <functionlink id="GetPhase">phase</functionlink>, | |
| 550 the set of allowed operations | |
| 551 inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the | |
| 552 functionality available at this time). | |
| 553 The agent can safely process the options and set | |
| 554 event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once | |
| 555 the VM initialization event is received | |
| 556 (that is, the <eventlink id="VMInit">VMInit</eventlink> | |
| 557 callback is invoked), the agent | |
| 558 can complete its initialization. | |
| 559 <rationale> | |
| 560 Early startup is required so that agents can set the desired capabilities, | |
| 561 many of which must be set before the VM is initialized. | |
| 562 In JVMDI, the -Xdebug command-line option provided | |
| 563 very coarse-grain control of capabilities. | |
| 564 JVMPI implementations use various tricks to provide a single "JVMPI on" switch. | |
| 565 No reasonable command-line | |
| 566 option could provide the fine-grain of control required to balance needed capabilities vs | |
| 567 performance impact. | |
| 568 Early startup is also needed so that agents can control the execution | |
| 569 environment - modifying the file system and system properties to install | |
| 570 their functionality. | |
| 571 </rationale> | |
| 572 <p/> | |
| 573 The return value from <code>Agent_OnLoad</code> is used to indicate an error. | |
| 574 Any value other than zero indicates an error and causes termination of the VM. | |
| 575 </intro> | |
| 576 | |
| 577 <intro id="onattach" label="Agent Start-Up (Live phase)"> | |
| 578 A VM may support a mechanism that allows agents to be started in the VM during the live | |
| 579 <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported, | |
| 580 are implementation specific. For example, a tool may use some platform specific mechanism, | |
| 581 or implementation specific API, to attach to the running VM, and request it start a given | |
| 582 agent. | |
| 583 <p/> | |
| 584 If an agent is started during the live phase then its agent library | |
| 585 must export a start-up function | |
| 586 with the following prototype: | |
| 587 <example> | |
| 588 JNIEXPORT jint JNICALL | |
| 589 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example> | |
| 590 <p/> | |
| 591 The VM will start the agent by calling this function. | |
| 592 It will be called in the context of a thread | |
| 593 that is attached to the VM. The first argument <i><vm></i> is the Java VM. | |
| 594 The <i><options></i> argument is the startup options provided to the agent. | |
| 595 <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8 | |
| 596 </internallink> string. | |
| 597 If startup options were not provided, a zero length string is passed to | |
| 598 <code>options</code>. The lifespan of the <code>options</code> string is the | |
| 599 <code>Agent_OnAttach</code> call. If needed beyond this time the string or parts of | |
| 600 the string must be copied. | |
| 601 <p/> | |
| 602 Note that some <internallink id="capability">capabilities</internallink> | |
| 603 may not be available in the live phase. | |
| 604 <p/> | |
| 605 The <code>Agent_OnAttach</code> function initializes the agent and returns a value | |
| 606 to the VM to indicate if an error occurred. Any value other than zero indicates an error. | |
| 607 An error does not cause the VM to terminate. Instead the VM ignores the error, or takes | |
| 608 some implementation specific action -- for example it might print an error to standard error, | |
| 609 or record the error in a system log. | |
| 610 </intro> | |
| 611 | |
| 612 <intro id="onunload" label="Agent Shutdown"> | |
| 613 The library may optionally export a | |
| 614 shutdown function with the following prototype: | |
| 615 <example> | |
| 616 JNIEXPORT void JNICALL | |
| 617 Agent_OnUnload(JavaVM *vm)</example> | |
| 618 This function will be called by the VM when the library is about to be unloaded. | |
| 619 The library will be unloaded and this function will be called if some platform specific | |
| 620 mechanism causes the unload (an unload mechanism is not specified in this document) | |
| 621 or the library is (in effect) unloaded by the termination of the VM whether through | |
| 622 normal termination or VM failure, including start-up failure. | |
| 623 Uncontrolled shutdown is, of couse, an exception to this rule. | |
| 624 Note the distinction between this function and the | |
| 625 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event | |
| 626 to be sent, the VM must have run at least to the point of initialization and a valid | |
| 627 <jvmti/> environment must exist which has set a callback for VMDeath | |
| 628 and enabled the event | |
| 629 None of these are required for <code>Agent_OnUnload</code> and this function | |
| 630 is also called if the library is unloaded for other reasons. | |
| 631 In the case that a VM Death event is sent, it will be sent before this | |
| 632 function is called (assuming this function is called due to VM termination). | |
| 633 This function can be used to clean-up resources allocated by the agent. | |
| 634 </intro> | |
| 635 | |
| 636 <intro id="tooloptions" label="JAVA_TOOL_OPTIONS"> | |
| 637 Since the command-line cannot always be accessed or modified, for example in embedded VMs | |
| 638 or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is | |
| 639 provided so that agents may be launched in these cases. | |
| 640 <p/> | |
| 641 Platforms which support environment variables or other named strings, may support the | |
| 642 <code>JAVA_TOOL_OPTIONS</code> variable. This variable will be broken into options at white-space | |
| 643 boundaries. White-space characters include space, tab, carriage-return, new-line, | |
| 644 vertical-tab, and form-feed. Sequences of white-space characters are considered | |
| 645 equivalent to a single white-space character. No white-space is included in the options | |
| 646 unless quoted. Quoting is as follows: | |
| 647 <ul> | |
| 648 <li>All characters enclosed between a pair of single quote marks (''), except a single | |
| 649 quote, are quoted.</li> | |
| 650 <li>Double quote characters have no special meaning inside a pair of single quote marks.</li> | |
| 651 <li>All characters enclosed between a pair of double quote marks (""), except a double | |
| 652 quote, are quoted.</li> | |
| 653 <li>Single quote characters have no special meaning inside a pair of double quote marks.</li> | |
| 654 <li>A quoted part can start or end anywhere in the variable.</li> | |
| 655 <li>White-space characters have no special meaning when quoted -- they are included in | |
| 656 the option like any other character and do not mark white-space boundaries.</li> | |
| 657 <li>The pair of quote marks is not included in the option.</li> | |
| 658 </ul> | |
| 659 <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied | |
| 660 in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is | |
| 661 a concern; for example, the Reference Implementation disables this feature on Unix systems when | |
| 662 the effective user or group ID differs from the real ID. | |
| 663 This feature is intended to support the initialization of tools -- specifically including the | |
| 664 launching of native or Java programming language agents. Multiple tools may wish to use this | |
| 665 feature, so the variable should not be overwritten, instead, options should be appended to | |
| 666 the variable. Note that since the variable is processed at the time of the JNI Invocation | |
| 667 API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled. | |
| 668 </intro> | |
| 669 | |
| 670 <intro id="environments" label="Environments"> | |
| 671 The <jvmti/> specification supports the use of multiple simultaneous | |
| 672 <jvmti/> agents. | |
| 673 Each agent has its own <jvmti/> environment. | |
| 674 That is, the <jvmti/> state is | |
| 675 separate for each agent - changes to one environment do not affect the | |
| 676 others. The state of a <jvmti/> | |
| 677 environment includes: | |
| 678 <ul> | |
| 679 <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li> | |
| 680 <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li> | |
| 681 <li><internallink id="capability">the capabilities</internallink></li> | |
| 682 <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li> | |
| 683 </ul> | |
| 684 Although their <jvmti/> state | |
| 685 is separate, agents inspect and modify the shared state | |
| 686 of the VM, they also share the native environment in which they execute. | |
| 687 As such, an agent can perturb the results of other agents or cause them | |
| 688 to fail. It is the responsibility of the agent writer to specify the level | |
| 689 of compatibility with other agents. <jvmti/> implementations are not capable | |
| 690 of preventing destructive interactions between agents. Techniques to reduce | |
| 691 the likelihood of these occurrences are beyond the scope of this document. | |
| 692 <p/> | |
| 693 An agent creates a <jvmti/> environment | |
| 694 by passing a <jvmti/> version | |
| 695 as the interface ID to the JNI Invocation API function | |
| 6919 | 696 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><code>GetEnv</code></externallink>. |
| 0 | 697 See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink> |
| 698 for more details on the creation and use of | |
| 699 <jvmti/> environments. | |
| 700 Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from | |
| 701 <internallink id="onload"><code>Agent_OnLoad</code></internallink>. | |
| 702 </intro> | |
| 703 | |
| 704 <intro id="bci" label="Bytecode Instrumentation"> | |
| 705 This interface does not include some events that one might expect in an interface with | |
| 706 profiling support. Some examples include object allocation events and full speed | |
| 707 method enter and exit events. The interface instead provides support for | |
| 708 <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine | |
| 709 bytecode instructions which comprise the target program. Typically, these alterations | |
| 710 are to add "events" to the code of a method - for example, to add, at the beginning of a method, | |
| 711 a call to <code>MyProfiler.methodEntered()</code>. | |
| 712 Since the changes are purely additive, they do not modify application | |
| 713 state or behavior. | |
| 714 Because the inserted agent code is standard bytecodes, the VM can run at full speed, | |
| 715 optimizing not only the target program but also the instrumentation. If the | |
| 716 instrumentation does not involve switching from bytecode execution, no expensive | |
| 717 state transitions are needed. The result is high performance events. | |
| 718 This approach also provides complete control to the agent: instrumentation can be | |
| 719 restricted to "interesting" portions of the code (e.g., the end user's code) and | |
| 720 can be conditional. Instrumentation can run entirely in Java programming language | |
| 721 code or can call into the native agent. Instrumentation can simply maintain | |
| 722 counters or can statistically sample events. | |
| 723 <p/> | |
| 724 Instrumentation can be inserted in one of three ways: | |
| 725 <ul> | |
| 726 <li> | |
| 727 Static Instrumentation: The class file is instrumented before it | |
| 728 is loaded into the VM - for example, by creating a duplicate directory of | |
| 729 <code>*.class</code> files which have been modified to add the instrumentation. | |
| 730 This method is extremely awkward and, in general, an agent cannot know | |
| 731 the origin of the class files which will be loaded. | |
| 732 </li> | |
| 733 <li> | |
| 734 Load-Time Instrumentation: When a class file is loaded by the VM, the raw | |
| 735 bytes of the class file are sent for instrumentation to the agent. | |
| 736 The <eventlink id="ClassFileLoadHook"/> | |
| 737 event, triggered by the class load, | |
| 738 provides this functionality. This mechanism provides efficient | |
| 739 and complete access to one-time instrumentation. | |
| 740 </li> | |
| 741 <li> | |
| 742 Dynamic Instrumentation: A class which is already loaded (and possibly | |
| 743 even running) is modified. This optional feature is provided by the | |
| 744 <eventlink id="ClassFileLoadHook"/> event, triggered by calling the | |
| 745 <functionlink id="RetransformClasses"/> function. | |
| 746 Classes can be modified multiple times and can be returned to their | |
| 747 original state. | |
| 748 The mechanism allows instrumentation which changes during the | |
| 749 course of execution. | |
| 750 </li> | |
| 751 </ul> | |
| 752 <p/> | |
| 753 The class modification functionality provided in this interface | |
| 754 is intended to provide a mechanism for instrumentation | |
| 755 (the <eventlink id="ClassFileLoadHook"/> event | |
| 756 and the <functionlink id="RetransformClasses"/> function) | |
| 757 and, during development, for fix-and-continue debugging | |
| 758 (the <functionlink id="RedefineClasses"/> function). | |
| 759 <p/> | |
| 760 Care must be taken to avoid perturbing dependencies, especially when | |
| 761 instrumenting core classes. For example, an approach to getting notification | |
| 762 of every object allocation is to instrument the constructor on | |
| 763 <code>Object</code>. Assuming that the constructor is initially | |
| 764 empty, the constructor could be changed to: | |
| 765 <example> | |
| 766 public Object() { | |
| 767 MyProfiler.allocationTracker(this); | |
| 768 } | |
| 769 </example> | |
| 770 However, if this change was made using the | |
| 771 <eventlink id="ClassFileLoadHook"/> | |
| 772 event then this might impact a typical VM as follows: | |
| 773 the first created object will call the constructor causing a class load of | |
| 774 <code>MyProfiler</code>; which will then cause | |
| 775 object creation, and since <code>MyProfiler</code> isn't loaded yet, | |
| 776 infinite recursion; resulting in a stack overflow. A refinement of this | |
| 777 would be to delay invoking the tracking method until a safe time. For | |
| 778 example, <code>trackAllocations</code> could be set in the | |
| 779 handler for the <code>VMInit</code> event. | |
| 780 <example> | |
| 781 static boolean trackAllocations = false; | |
| 782 | |
| 783 public Object() { | |
| 784 if (trackAllocations) { | |
| 785 MyProfiler.allocationTracker(this); | |
| 786 } | |
| 787 } | |
| 788 </example> | |
| 789 <p/> | |
| 790 The <functionlink id="SetNativeMethodPrefix"/> allows native methods | |
| 791 to be instrumented by the use of wrapper methods. | |
| 792 </intro> | |
| 793 | |
| 794 <intro id="mUTF" label="Modified UTF-8 String Encoding"> | |
| 795 <jvmti/> uses modified UTF-8 to encode character strings. | |
| 796 This is the same encoding used by JNI. | |
| 797 Modified UTF-8 differs | |
| 798 from standard UTF-8 in the representation of supplementary characters | |
| 799 and of the null character. See the | |
| 6919 | 800 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16542"> |
| 0 | 801 Modified UTF-8 Strings</externallink> |
| 802 section of the JNI specification for details. | |
| 803 </intro> | |
| 804 | |
| 805 <intro id="context" label="Specification Context"> | |
| 806 Since this interface provides access to the state of applications running in the | |
| 807 Java virtual machine; | |
| 808 terminology refers to the Java platform and not the native | |
| 809 platform (unless stated otherwise). For example: | |
| 810 <ul> | |
| 811 <li>"thread" means Java programming language thread.</li> | |
| 812 <li>"stack frame" means Java virtual machine stack frame.</li> | |
| 813 <li>"class" means Java programming language class.</li> | |
| 814 <li>"heap" means Java virtual machine heap.</li> | |
| 815 <li>"monitor" means Java programming language object monitor.</li> | |
| 816 </ul> | |
| 817 <p/> | |
| 818 Sun, Sun Microsystems, the Sun logo, Java, and JVM | |
|
1552
c18cbe5936b8
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
0
diff
changeset
|
819 are trademarks or registered trademarks of Oracle |
|
c18cbe5936b8
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
0
diff
changeset
|
820 and/or its affiliates, in the U.S. and other countries. |
| 0 | 821 </intro> |
| 822 | |
| 823 | |
| 824 <functionsection label="Functions"> | |
| 825 <intro id="jvmtiEnvAccess" label="Accessing Functions"> | |
| 826 Native code accesses <jvmti/> features | |
| 827 by calling <jvmti/> functions. | |
| 828 Access to <jvmti/> functions is by use of an interface pointer | |
| 829 in the same manner as | |
| 6919 | 830 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html">Java |
| 0 | 831 Native Interface (JNI) functions</externallink> are accessed. |
| 832 The <jvmti/> interface pointer is called the | |
| 833 <i>environment pointer</i>. | |
| 834 <p/> | |
| 835 An environment pointer is a pointer to an environment and has | |
| 836 the type <code>jvmtiEnv*</code>. | |
| 837 An environment has information about its <jvmti/> connection. | |
| 838 The first value in the environment is a pointer to the function table. | |
| 839 The function table is an array of pointers to <jvmti/> functions. | |
| 840 Every function pointer is at a predefined offset inside the | |
| 841 array. | |
| 842 <p/> | |
| 843 When used from the C language: | |
| 844 double indirection is used to access the functions; | |
| 845 the environment pointer provides context and is the first | |
| 846 parameter of each function call; for example: | |
| 847 <example> | |
| 848 jvmtiEnv *jvmti; | |
| 849 ... | |
| 850 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &class_count, &classes); | |
| 851 </example> | |
| 852 <p/> | |
| 853 When used from the C++ language: | |
| 854 functions are accessed as member functions of <code>jvmtiEnv</code>; | |
| 855 the environment pointer is not passed to the function call; for example: | |
| 856 <example> | |
| 857 jvmtiEnv *jvmti; | |
| 858 ... | |
| 859 jvmtiError err = jvmti->GetLoadedClasses(&class_count, &classes); | |
| 860 </example> | |
| 861 Unless otherwise stated, all examples and declarations in this | |
| 862 specification use the C language. | |
| 863 <p/> | |
| 864 A <jvmti/> environment can be obtained through the JNI Invocation API | |
| 865 <code>GetEnv</code> function: | |
| 866 <example> | |
| 867 jvmtiEnv *jvmti; | |
| 868 ... | |
| 869 (*jvm)->GetEnv(jvm, &jvmti, JVMTI_VERSION_1_0); | |
| 870 </example> | |
| 871 Each call to <code>GetEnv</code> | |
| 872 creates a new <jvmti/> connection and thus | |
| 873 a new <jvmti/> environment. | |
| 874 The <code>version</code> argument of <code>GetEnv</code> must be | |
| 875 a <jvmti/> version. | |
| 876 The returned environment may have a different version than the | |
| 877 requested version but the returned environment must be compatible. | |
| 878 <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a | |
| 879 compatible version is not available, if <jvmti/> is not supported or | |
| 880 <jvmti/> is not supported in the current VM configuration. | |
| 881 Other interfaces may be added for creating <jvmti/> environments | |
| 882 in specific contexts. | |
| 883 Each environment has its own state (for example, | |
| 884 <functionlink id="SetEventNotificationMode">desired events</functionlink>, | |
| 885 <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and | |
| 886 <functionlink id="AddCapabilities">capabilities</functionlink>). | |
| 887 An environment is released with | |
| 888 <functionlink id="DisposeEnvironment"></functionlink>. | |
| 889 Thus, unlike JNI which has one environment per thread, <jvmti/> environments work | |
| 890 across threads and are created dynamically. | |
| 891 </intro> | |
| 892 | |
| 893 <intro id="functionReturn" label="Function Return Values"> | |
| 894 <jvmti/> functions always return an | |
| 895 <internallink id="ErrorSection">error code</internallink> via the | |
| 896 <datalink id="jvmtiError"/> function return value. | |
| 897 Some functions can return additional | |
| 898 values through pointers provided by the calling function. | |
| 899 In some cases, <jvmti/> functions allocate memory that your program must | |
| 900 explicitly deallocate. This is indicated in the individual <jvmti/> | |
| 901 function descriptions. Empty lists, arrays, sequences, etc are | |
| 902 returned as <code>NULL</code>. | |
| 903 <p/> | |
| 904 In the event that the <jvmti/> function encounters | |
| 905 an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values | |
| 906 of memory referenced by argument pointers is undefined, but no memory | |
| 907 will have been allocated and no global references will have been allocated. | |
| 908 If the error occurs because of invalid input, no action will have occurred. | |
| 909 </intro> | |
| 910 | |
| 911 <intro id="refs" label="Managing JNI Object References"> | |
| 912 <jvmti/> functions identify objects with JNI references | |
| 913 (<datalink id="jobject"/> and <datalink id="jclass"/>) | |
| 914 and their derivatives | |
| 915 (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>). | |
| 916 References passed to | |
| 917 <jvmti/> functions can be either global or local, but they must be | |
| 918 strong references. All references returned by <jvmti/> functions are | |
| 919 local references--these local references are created | |
| 920 during the <jvmti/> call. | |
| 921 Local references are a resource that must be managed (see the | |
| 6919 | 922 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp18654">JNI Documentation</externallink>). |
| 0 | 923 When threads return from native code all local references |
| 924 are freed. Note that some threads, including typical | |
| 925 agent threads, will never return from native code. | |
| 926 A thread is ensured the ability to create sixteen local | |
| 927 references without the need for any explicit management. | |
| 928 For threads executing a limited number of <jvmti/> calls before | |
| 929 returning from native code | |
| 930 (for example, threads processing events), | |
| 931 it may be determined that no explicit management | |
| 932 is needed. | |
| 933 However, long running agent threads will need explicit | |
| 934 local reference management--usually with the JNI functions | |
| 935 <code>PushLocalFrame</code> and <code>PopLocalFrame</code>. | |
| 936 Conversely, to preserve references beyond the | |
| 937 return from native code, they must be converted to global references. | |
| 938 These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> | |
| 939 as they are not <datalink id="jobject"/>s. | |
| 940 </intro> | |
| 941 | |
| 942 <intro id="prereqState" label="Prerequisite State for Calling Functions"> | |
| 943 Unless the function explicitly states that the agent must bring | |
| 944 a thread or the VM to a particular state (for example, suspended), | |
| 945 the <jvmti/> implementation is responsible for bringing the VM to a | |
| 946 safe and consistent state for performing the function. | |
| 947 </intro> | |
| 948 | |
| 949 <intro id="functionsExceptions" label="Exceptions and Functions"> | |
| 950 <jvmti/> functions never throw exceptions; error conditions are | |
| 951 communicated via the | |
| 952 <internallink id="functionReturn">function return value</internallink>. | |
| 953 Any existing exception state is preserved across a call to a | |
| 954 <jvmti/> function. | |
| 955 See the | |
| 956 <externallink | |
| 6919 | 957 id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html#wp770" |
| 0 | 958 >Java Exceptions</externallink> |
| 959 section of the JNI specification for information on handling exceptions. | |
| 960 </intro> | |
| 961 | |
| 962 <category id="memory" label="Memory Management"> | |
| 963 <intro> | |
| 964 These functions provide for the allocation and deallocation of | |
| 965 memory used by <jvmti/> functionality and can be used to provide | |
| 966 working memory for agents. | |
| 967 Memory managed by <jvmti/> is not compatible with other memory | |
| 968 allocation libraries and mechanisms. | |
| 969 </intro> | |
| 970 | |
| 971 <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46"> | |
| 972 <synopsis>Allocate</synopsis> | |
| 973 <description> | |
| 974 Allocate an area of memory through the <jvmti/> allocator. | |
| 975 The allocated | |
| 976 memory should be freed with <functionlink id="Deallocate"></functionlink>. | |
| 977 </description> | |
| 978 <origin>jvmdi</origin> | |
| 979 <capabilities> | |
| 980 </capabilities> | |
| 981 <parameters> | |
| 982 <param id="size"> | |
| 983 <jlong/> | |
| 984 <description> | |
| 985 The number of bytes to allocate. | |
| 986 <rationale> | |
| 987 <code>jlong</code> is used for compatibility with JVMDI. | |
| 988 </rationale> | |
| 989 </description> | |
| 990 </param> | |
| 991 <param id="mem_ptr"> | |
| 992 <allocbuf incount="size"><uchar/></allocbuf> | |
| 993 <description> | |
| 994 On return, a pointer to the beginning of the allocated memory. | |
| 995 If <code>size</code> is zero, <code>NULL</code> is returned. | |
| 996 </description> | |
| 997 </param> | |
| 998 </parameters> | |
| 999 <errors> | |
| 1000 <error id="JVMTI_ERROR_OUT_OF_MEMORY"> | |
| 1001 Memory request cannot be honored. | |
| 1002 </error> | |
| 1003 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 1004 <paramlink id="size"></paramlink> is less than zero. | |
| 1005 </error> | |
| 1006 </errors> | |
| 1007 </function> | |
| 1008 | |
| 1009 <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47"> | |
| 1010 <synopsis>Deallocate</synopsis> | |
| 1011 <description> | |
| 1012 Deallocate <code>mem</code> using the <jvmti/> allocator. | |
| 1013 This function should | |
| 1014 be used to deallocate any memory allocated and returned | |
| 1015 by a <jvmti/> function | |
| 1016 (including memory allocated with <functionlink id="Allocate"></functionlink>). | |
| 1017 All allocated memory must be deallocated | |
| 1018 or the memory cannot be reclaimed. | |
| 1019 </description> | |
| 1020 <origin>jvmdi</origin> | |
| 1021 <capabilities> | |
| 1022 </capabilities> | |
| 1023 <parameters> | |
| 1024 <param id="mem"> | |
| 1025 <outbuf> | |
| 1026 <uchar/> | |
| 1027 <nullok>the call is ignored</nullok> | |
| 1028 </outbuf> | |
| 1029 <description> | |
| 1030 A pointer to the beginning of the allocated memory. | |
| 1031 Please ignore "On return, the elements are set." | |
| 1032 <todo>keep it from generating "On return, the elements are set"</todo> | |
| 1033 </description> | |
| 1034 </param> | |
| 1035 </parameters> | |
| 1036 <errors> | |
| 1037 </errors> | |
| 1038 </function> | |
| 1039 </category> | |
| 1040 | |
| 1041 <category id="threadCategory" label="Thread"> | |
| 1042 <intro> | |
| 1043 </intro> | |
| 1044 | |
| 1045 <function id="GetThreadState" num="17"> | |
| 1046 <synopsis>Get Thread State</synopsis> | |
| 1047 <description> | |
| 1048 Get the state of a thread. The state of the thread is represented by the | |
| 1049 answers to the hierarchical set of questions below: | |
| 1050 <ul type="circle"> | |
| 1051 <li><i>Alive?</i> | |
| 1052 <ul> | |
| 1053 <li>Not alive. | |
| 1054 <ul type="circle"> | |
| 1055 <li><i>Why not alive?</i> | |
| 1056 <ul> | |
| 1057 <li>New.</li> | |
| 1058 <li>Terminated (<datalink | |
| 1059 id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li> | |
| 1060 </ul> | |
| 1061 </li> | |
| 1062 </ul> | |
| 1063 </li> | |
| 1064 <li>Alive (<datalink | |
| 1065 id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>) | |
| 1066 <ul type="circle"> | |
| 1067 <li><i>Suspended?</i> | |
| 1068 <ul> | |
| 1069 <li>Suspended (<datalink | |
| 1070 id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li> | |
| 1071 <li>Not suspended</li> | |
| 1072 </ul> | |
| 1073 </li> | |
| 1074 <li><i>Interrupted?</i> | |
| 1075 <ul> | |
| 1076 <li>Interrupted (<datalink | |
| 1077 id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li> | |
| 1078 <li>Not interrupted.</li> | |
| 1079 </ul> | |
| 1080 </li> | |
| 1081 <li><i>In native?</i> | |
| 1082 <ul> | |
| 1083 <li>In native code (<datalink | |
| 1084 id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li> | |
| 1085 <li>In Java programming language code</li> | |
| 1086 </ul> | |
| 1087 </li> | |
| 1088 <li><i>What alive state?</i> | |
| 1089 <ul> | |
| 1090 <li>Runnable (<datalink | |
| 1091 id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li> | |
| 1092 <li>Blocked (<datalink | |
| 1093 id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li> | |
| 1094 <li>Waiting (<datalink | |
| 1095 id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>) | |
| 1096 <ul type="circle"> | |
| 1097 <li><i>Timed wait?</i> | |
| 1098 <ul> | |
| 1099 <li>Indefinite (<datalink | |
| 1100 id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li> | |
| 1101 <li>Timed (<datalink | |
| 1102 id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li> | |
| 1103 </ul> | |
| 1104 </li> | |
| 1105 <li><i>Why waiting?</i> | |
| 1106 <ul> | |
| 1107 <li>Object.wait (<datalink | |
| 1108 id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li> | |
| 1109 <li>LockSupport.park (<datalink | |
| 1110 id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li> | |
| 1111 <li>Sleeping (<datalink | |
| 1112 id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li> | |
| 1113 </ul> | |
| 1114 </li> | |
| 1115 </ul> | |
| 1116 </li> | |
| 1117 </ul> | |
| 1118 </li> | |
| 1119 </ul> | |
| 1120 </li> | |
| 1121 </ul> | |
| 1122 </li> | |
| 1123 </ul> | |
| 1124 <p/> | |
| 1125 The answers are represented by the following bit vector. | |
| 1126 <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits"> | |
| 1127 <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001"> | |
| 1128 Thread is alive. Zero if thread is new (not started) or terminated. | |
| 1129 </constant> | |
| 1130 <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002"> | |
| 1131 Thread has completed execution. | |
| 1132 </constant> | |
| 1133 <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004"> | |
| 1134 Thread is runnable. | |
| 1135 </constant> | |
| 1136 <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400"> | |
| 1137 Thread is waiting to enter a synchronization block/method or, | |
| 1138 after an <code>Object.wait()</code>, waiting to re-enter a | |
| 1139 synchronization block/method. | |
| 1140 </constant> | |
| 1141 <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080"> | |
| 1142 Thread is waiting. | |
| 1143 </constant> | |
| 1144 <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010"> | |
| 1145 Thread is waiting without a timeout. | |
| 1146 For example, <code>Object.wait()</code>. | |
| 1147 </constant> | |
| 1148 <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020"> | |
| 1149 Thread is waiting with a maximum time to wait specified. | |
| 1150 For example, <code>Object.wait(long)</code>. | |
| 1151 </constant> | |
| 1152 <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040"> | |
| 1153 Thread is sleeping -- <code>Thread.sleep(long)</code>. | |
| 1154 </constant> | |
| 1155 <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100"> | |
| 1156 Thread is waiting on an object monitor -- <code>Object.wait</code>. | |
| 1157 </constant> | |
| 1158 <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200"> | |
| 1159 Thread is parked, for example: <code>LockSupport.park</code>, | |
| 1160 <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>. | |
| 1161 </constant> | |
| 1162 <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000"> | |
| 1163 Thread suspended. | |
| 1164 <code>java.lang.Thread.suspend()</code> | |
| 1165 or a <jvmti/> suspend function | |
| 1166 (such as <functionlink id="SuspendThread"></functionlink>) | |
| 1167 has been called on the thread. If this bit | |
| 1168 is set, the other bits refer to the thread state before suspension. | |
| 1169 </constant> | |
| 1170 <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000"> | |
| 1171 Thread has been interrupted. | |
| 1172 </constant> | |
| 1173 <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000"> | |
| 1174 Thread is in native code--that is, a native method is running | |
| 1175 which has not called back into the VM or Java programming | |
| 1176 language code. | |
| 1177 <p/> | |
| 1178 This flag is not set when running VM compiled Java programming | |
| 1179 language code nor is it set when running VM code or | |
| 1180 VM support code. Native VM interface functions, such as JNI and | |
| 1181 <jvmti/> functions, may be implemented as VM code. | |
| 1182 </constant> | |
| 1183 <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000"> | |
| 1184 Defined by VM vendor. | |
| 1185 </constant> | |
| 1186 <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000"> | |
| 1187 Defined by VM vendor. | |
| 1188 </constant> | |
| 1189 <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000"> | |
| 1190 Defined by VM vendor. | |
| 1191 </constant> | |
| 1192 </constants> | |
| 1193 The following definitions are used to convert <jvmti/> thread state | |
| 1194 to <code>java.lang.Thread.State</code> style states. | |
| 1195 <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits"> | |
| 1196 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK" | |
| 1197 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"> | |
| 1198 Mask the state with this before comparison | |
| 1199 </constant> | |
| 1200 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW" | |
| 1201 num="0"> | |
| 1202 <code>java.lang.Thread.State.NEW</code> | |
| 1203 </constant> | |
| 1204 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED" | |
| 1205 num="JVMTI_THREAD_STATE_TERMINATED"> | |
| 1206 <code>java.lang.Thread.State.TERMINATED</code> | |
| 1207 </constant> | |
| 1208 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE" | |
| 1209 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE"> | |
| 1210 <code>java.lang.Thread.State.RUNNABLE</code> | |
| 1211 </constant> | |
| 1212 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED" | |
| 1213 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"> | |
| 1214 <code>java.lang.Thread.State.BLOCKED</code> | |
| 1215 </constant> | |
| 1216 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING" | |
| 1217 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY"> | |
| 1218 <code>java.lang.Thread.State.WAITING</code> | |
| 1219 </constant> | |
| 1220 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING" | |
| 1221 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"> | |
| 1222 <code>java.lang.Thread.State.TIMED_WAITING</code> | |
| 1223 </constant> | |
| 1224 </constants> | |
| 1225 <b>Rules</b> | |
| 1226 <p/> | |
| 1227 There can be no more than one answer to a question, although there can be no | |
| 1228 answer (because the answer is unknown, does not apply, or none of the answers is | |
| 1229 correct). An answer is set only when the enclosing answers match. | |
| 1230 That is, no more than one of | |
| 1231 <ul type="circle"> | |
| 1232 <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li> | |
| 1233 <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li> | |
| 1234 <li><code>JVMTI_THREAD_STATE_WAITING</code></li> | |
| 1235 </ul> | |
| 1236 can be set (a <tm>J2SE</tm> compliant implementation will always set | |
| 1237 one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set). | |
| 1238 And if any of these are set, the enclosing answer | |
| 1239 <code>JVMTI_THREAD_STATE_ALIVE</code> is set. | |
| 1240 No more than one of | |
| 1241 <ul type="circle"> | |
| 1242 <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li> | |
| 1243 <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li> | |
| 1244 </ul> | |
| 1245 can be set (a <tm>J2SE</tm> compliant implementation will always set | |
| 1246 one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set). | |
| 1247 And if either is set, the enclosing answers | |
| 1248 <code>JVMTI_THREAD_STATE_ALIVE</code> and | |
| 1249 <code>JVMTI_THREAD_STATE_WAITING</code> are set. | |
| 1250 No more than one of | |
| 1251 <ul type="circle"> | |
| 1252 <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li> | |
| 1253 <li><code>JVMTI_THREAD_STATE_PARKED</code></li> | |
| 1254 <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li> | |
| 1255 </ul> | |
| 1256 can be set. And if any of these is set, the enclosing answers | |
| 1257 <code>JVMTI_THREAD_STATE_ALIVE</code> and | |
| 1258 <code>JVMTI_THREAD_STATE_WAITING</code> are set. | |
| 1259 Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set, | |
| 1260 then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set. | |
| 1261 If a state <i>A</i> is implemented using the mechanism of | |
| 1262 state <i>B</i> then it is state <i>A</i> which | |
| 1263 is returned by this function. | |
| 1264 For example, if <code>Thread.sleep(long)</code> | |
| 1265 is implemented using <code>Object.wait(long)</code> | |
| 1266 then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code> | |
| 1267 which is returned. | |
| 1268 More than one of | |
| 1269 <ul type="circle"> | |
| 1270 <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li> | |
| 1271 <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li> | |
| 1272 <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li> | |
| 1273 </ul> | |
| 1274 can be set, but if any is set, | |
| 1275 <code>JVMTI_THREAD_STATE_ALIVE</code> is set. | |
| 1276 <p/> | |
| 1277 And finally, | |
| 1278 <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless | |
| 1279 <code>JVMTI_THREAD_STATE_ALIVE</code> is not set. | |
| 1280 <p/> | |
| 1281 The thread state representation is designed for extension in future versions | |
| 1282 of the specification; thread state values should be used accordingly, that is | |
| 1283 they should not be used as ordinals. | |
| 1284 Most queries can be made by testing a single bit, if use in a switch statement is desired, | |
| 1285 the state bits should be masked with the interesting bits. | |
| 1286 All bits not defined above are reserved for future use. | |
| 1287 A VM, compliant to the current specification, must set reserved bits to zero. | |
| 1288 An agent should ignore reserved bits -- | |
| 1289 they should not be assumed to be zero and thus should not be included in comparisons. | |
| 1290 <p/> | |
| 1291 <b>Examples</b> | |
| 1292 <p/> | |
| 1293 Note that the values below exclude reserved and vendor bits. | |
| 1294 <p/> | |
| 1295 The state of a thread blocked at a <code>synchronized</code>-statement would be: | |
| 1296 <example> | |
| 1297 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | |
| 1298 </example> | |
| 1299 The state of a thread which hasn't started yet would be: | |
| 1300 <example> | |
| 1301 0 | |
| 1302 </example> | |
| 1303 The state of a thread at a <code>Object.wait(3000)</code> would be: | |
| 1304 <example> | |
| 1305 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING + | |
| 1306 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT + | |
| 1307 JVMTI_THREAD_STATE_MONITOR_WAITING | |
| 1308 </example> | |
| 1309 The state of a thread suspended while runnable would be: | |
| 1310 <example> | |
| 1311 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED | |
| 1312 </example> | |
| 1313 <p/> | |
| 1314 <b>Testing the State</b> | |
| 1315 <p/> | |
| 1316 In most cases, the thread state can be determined by testing the one bit corresponding | |
| 1317 to that question. For example, the code to test if a thread is sleeping: | |
| 1318 <example> | |
| 1319 jint state; | |
| 1320 jvmtiError err; | |
| 1321 | |
| 1322 err = (*jvmti)->GetThreadState(jvmti, thread, &state); | |
| 1323 if (err == JVMTI_ERROR_NONE) { | |
| 1324 if (state & JVMTI_THREAD_STATE_SLEEPING) { ... | |
| 1325 </example> | |
| 1326 <p/> | |
| 1327 For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be: | |
| 1328 <example> | |
| 1329 if (state & JVMTI_THREAD_STATE_WAITING) { ... | |
| 1330 </example> | |
| 1331 For some states, more than one bit will need to be tested as is the case | |
| 1332 when testing if a thread has not yet been started: | |
| 1333 <example> | |
| 1334 if ((state & (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0) { ... | |
| 1335 </example> | |
| 1336 To distinguish timed from untimed <code>Object.wait</code>: | |
| 1337 <example> | |
| 1338 if (state & JVMTI_THREAD_STATE_IN_OBJECT_WAIT) { | |
| 1339 if (state & JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT) { | |
| 1340 printf("in Object.wait(long timeout)\n"); | |
| 1341 } else { | |
| 1342 printf("in Object.wait()\n"); | |
| 1343 } | |
| 1344 } | |
| 1345 </example> | |
| 1346 <p/> | |
| 1347 <b>Relationship to <code>java.lang.Thread.State</code></b> | |
| 1348 <p/> | |
| 1349 The thread state represented by <code>java.lang.Thread.State</code> | |
| 1350 returned from <code>java.lang.Thread.getState()</code> is a subset of the | |
| 1351 information returned from this function. | |
| 1352 The corresponding <code>java.lang.Thread.State</code> can be determined | |
| 1353 by using the provided conversion masks. | |
| 1354 For example, this returns the name of the <code>java.lang.Thread.State</code> thread state: | |
| 1355 <example> | |
| 1356 err = (*jvmti)->GetThreadState(jvmti, thread, &state); | |
| 1357 abortOnError(err); | |
| 1358 switch (state & JVMTI_JAVA_LANG_THREAD_STATE_MASK) { | |
| 1359 case JVMTI_JAVA_LANG_THREAD_STATE_NEW: | |
| 1360 return "NEW"; | |
| 1361 case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED: | |
| 1362 return "TERMINATED"; | |
| 1363 case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE: | |
| 1364 return "RUNNABLE"; | |
| 1365 case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED: | |
| 1366 return "BLOCKED"; | |
| 1367 case JVMTI_JAVA_LANG_THREAD_STATE_WAITING: | |
| 1368 return "WAITING"; | |
| 1369 case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING: | |
| 1370 return "TIMED_WAITING"; | |
| 1371 } | |
| 1372 </example> | |
| 1373 </description> | |
| 1374 <origin>new</origin> | |
| 1375 <capabilities> | |
| 1376 </capabilities> | |
| 1377 <parameters> | |
| 1378 <param id="thread"> | |
| 1379 <jthread null="current" started="maybe" impl="noconvert"/> | |
| 1380 <description> | |
| 1381 The thread to query. | |
| 1382 </description> | |
| 1383 </param> | |
| 1384 <param id="thread_state_ptr"> | |
| 1385 <outptr><jint/></outptr> | |
| 1386 <description> | |
| 1387 On return, points to state flags, | |
| 1388 as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>. | |
| 1389 </description> | |
| 1390 </param> | |
| 1391 </parameters> | |
| 1392 <errors> | |
| 1393 </errors> | |
| 1394 </function> | |
| 1395 | |
| 1396 <function id="GetCurrentThread" phase="start" num="18" since="1.1"> | |
| 1397 <synopsis>Get Current Thread</synopsis> | |
| 1398 <description> | |
| 1399 Get the current thread. | |
| 1400 The current thread is the Java programming language thread which has called the function. | |
| 1401 <p/> | |
| 1402 Note that most <jvmti/> functions that take a thread | |
| 1403 as an argument will accept <code>NULL</code> to mean | |
| 1404 the current thread. | |
| 1405 </description> | |
| 1406 <origin>new</origin> | |
| 1407 <capabilities> | |
| 1408 </capabilities> | |
| 1409 <parameters> | |
| 1410 <param id="thread_ptr"> | |
| 1411 <outptr><jthread/></outptr> | |
| 1412 <description> | |
| 1413 On return, points to the current thread. | |
| 1414 </description> | |
| 1415 </param> | |
| 1416 </parameters> | |
| 1417 <errors> | |
| 1418 </errors> | |
| 1419 </function> | |
| 1420 | |
| 1421 <function id="GetAllThreads" num="4"> | |
| 1422 <synopsis>Get All Threads</synopsis> | |
| 1423 <description> | |
| 1424 Get all live threads. | |
| 1425 The threads are Java programming language threads; | |
| 1426 that is, threads that are attached to the VM. | |
| 1427 A thread is live if <code>java.lang.Thread.isAlive()</code> | |
| 1428 would return <code>true</code>, that is, the thread has | |
| 1429 been started and has not yet died. | |
| 1430 The universe of threads is determined by the context of the <jvmti/> | |
| 1431 environment, which typically is all threads attached to the VM. | |
| 1432 Note that this includes <jvmti/> agent threads | |
| 1433 (see <functionlink id="RunAgentThread"/>). | |
| 1434 </description> | |
| 1435 <origin>jvmdi</origin> | |
| 1436 <capabilities> | |
| 1437 </capabilities> | |
| 1438 <parameters> | |
| 1439 <param id="threads_count_ptr"> | |
| 1440 <outptr><jint/></outptr> | |
| 1441 <description> | |
| 1442 On return, points to the number of running threads. | |
| 1443 </description> | |
| 1444 </param> | |
| 1445 <param id="threads_ptr"> | |
| 1446 <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf> | |
| 1447 <description> | |
| 1448 On return, points to an array of references, one | |
| 1449 for each running thread. | |
| 1450 </description> | |
| 1451 </param> | |
| 1452 </parameters> | |
| 1453 <errors> | |
| 1454 </errors> | |
| 1455 </function> | |
| 1456 | |
| 1457 <function id="SuspendThread" num="5"> | |
| 1458 <synopsis>Suspend Thread</synopsis> | |
| 1459 <description> | |
| 1460 Suspend the specified thread. If the calling thread is specified, | |
| 1461 this function will not return until some other thread calls | |
| 1462 <functionlink id="ResumeThread"></functionlink>. | |
| 1463 If the thread is currently suspended, this function | |
| 1464 does nothing and returns an error. | |
| 1465 </description> | |
| 1466 <origin>jvmdi</origin> | |
| 1467 <capabilities> | |
| 1468 <required id="can_suspend"></required> | |
| 1469 </capabilities> | |
| 1470 <parameters> | |
| 1471 <param id="thread"> | |
| 1472 <jthread null="current"/> | |
| 1473 <description> | |
| 1474 The thread to suspend. | |
| 1475 </description> | |
| 1476 </param> | |
| 1477 </parameters> | |
| 1478 <errors> | |
| 1479 <error id="JVMTI_ERROR_THREAD_SUSPENDED"> | |
| 1480 Thread already suspended. | |
| 1481 </error> | |
| 1482 </errors> | |
| 1483 </function> | |
| 1484 | |
| 1485 <elide> | |
| 1486 <function id="SuspendAllThreads" num="101"> | |
| 1487 <synopsis>Suspend All Threads</synopsis> | |
| 1488 <description> | |
| 1489 <issue> | |
| 1490 There has been no explicit call for this function, and it will | |
| 1491 thus be removed if there is no interest. | |
| 1492 </issue> | |
| 1493 Suspend all live threads except: | |
| 1494 <ul> | |
| 1495 <li>already suspended threads</li> | |
| 1496 <li>those listed in <paramlink id="except_list"></paramlink></li> | |
| 1497 <li>certain system (non application) threads, as determined | |
| 1498 by the VM implementation</li> | |
| 1499 </ul> | |
| 1500 The threads are Java programming language threads; | |
| 1501 native threads which are not attached to the VM are not | |
| 1502 Java programming language threads. | |
| 1503 A thread is live if <code>java.lang.Thread.isAlive()</code> | |
| 1504 would return <code>true</code>, that is, the thread has | |
| 1505 been started and has not yet died. | |
| 1506 The universe of threads is determined | |
| 1507 by the context of the <jvmti/> | |
| 1508 environment, which, typically, is all threads attached to the VM, | |
| 1509 except critical VM internal threads and <jvmti/> agent threads | |
| 1510 (see <functionlink id="RunAgentThread"/>). | |
| 1511 <p/> | |
| 1512 If the calling thread is specified, | |
| 1513 all other threads are suspended first then the caller thread is suspended - | |
| 1514 this function will not return until some other thread calls | |
| 1515 <functionlink id="ResumeThread"></functionlink>. | |
| 1516 <p/> | |
| 1517 The list of actually | |
| 1518 suspended threads is returned in | |
| 1519 <paramlink id="suspended_list_ptr"></paramlink>. | |
| 1520 Suspension is as defined in <functionlink id="SuspendThread"></functionlink>. | |
| 1521 <functionlink id="ResumeThreadList"></functionlink> | |
| 1522 can be used to resume the suspended threads. | |
| 1523 </description> | |
| 1524 <origin>new</origin> | |
| 1525 <capabilities> | |
| 1526 <required id="can_suspend"></required> | |
| 1527 </capabilities> | |
| 1528 <parameters> | |
| 1529 <param id="except_count"> | |
| 1530 <jint min="0"/> | |
| 1531 <description> | |
| 1532 The number of threads in the list of threads not to be suspended. | |
| 1533 </description> | |
| 1534 </param> | |
| 1535 <param id="except_list"> | |
| 1536 <inbuf incount="except_count"> | |
| 1537 <jthread/> | |
| 1538 <nullok>not an error if <code>except_count == 0</code></nullok> | |
| 1539 </inbuf> | |
| 1540 <description> | |
| 1541 The list of threads not to be suspended. | |
| 1542 </description> | |
| 1543 </param> | |
| 1544 <param id="suspended_count_ptr"> | |
| 1545 <outptr><jint/></outptr> | |
| 1546 <description> | |
| 1547 On return, points to the number of threads suspended by this call. | |
| 1548 </description> | |
| 1549 </param> | |
| 1550 <param id="suspended_list_ptr"> | |
| 1551 <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf> | |
| 1552 <description> | |
| 1553 On return, points to an array of references, one | |
| 1554 for each thread suspended. | |
| 1555 </description> | |
| 1556 </param> | |
| 1557 </parameters> | |
| 1558 <errors> | |
| 1559 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
| 1560 A thread in <paramlink id="except_list"></paramlink> was invalid. | |
| 1561 </error> | |
| 1562 <error id="JVMTI_ERROR_NULL_POINTER"> | |
| 1563 Both <paramlink id="except_list"></paramlink> was <code>NULL</code> | |
| 1564 and <paramlink id="except_count"></paramlink> was non-zero. | |
| 1565 </error> | |
| 1566 </errors> | |
| 1567 </function> | |
| 1568 </elide> | |
| 1569 | |
| 1570 <function id="SuspendThreadList" num="92"> | |
| 1571 <synopsis>Suspend Thread List</synopsis> | |
| 1572 <description> | |
| 1573 Suspend the <paramlink id="request_count"></paramlink> | |
| 1574 threads specified in the | |
| 1575 <paramlink id="request_list"></paramlink> array. | |
| 1576 Threads may be resumed with | |
| 1577 <functionlink id="ResumeThreadList"></functionlink> or | |
| 1578 <functionlink id="ResumeThread"></functionlink>. | |
| 1579 If the calling thread is specified in the | |
| 1580 <paramlink id="request_list"></paramlink> array, this function will | |
| 1581 not return until some other thread resumes it. | |
| 1582 Errors encountered in the suspension of a thread | |
| 1583 are returned in the <paramlink id="results"></paramlink> | |
| 1584 array, <b>not</b> in the return value of this function. | |
| 1585 Threads that are currently suspended do not change state. | |
| 1586 </description> | |
| 1587 <origin>jvmdi</origin> | |
| 1588 <capabilities> | |
| 1589 <required id="can_suspend"></required> | |
| 1590 </capabilities> | |
| 1591 <parameters> | |
| 1592 <param id="request_count"> | |
| 1593 <jint min="0"/> | |
| 1594 <description> | |
| 1595 The number of threads to suspend. | |
| 1596 </description> | |
| 1597 </param> | |
| 1598 <param id="request_list"> | |
| 1599 <inbuf incount="request_count"><jthread/></inbuf> | |
| 1600 <description> | |
| 1601 The list of threads to suspend. | |
| 1602 </description> | |
| 1603 </param> | |
| 1604 <param id="results"> | |
| 1605 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> | |
| 1606 <description> | |
| 1607 An agent supplied array of | |
| 1608 <paramlink id="request_count"></paramlink> elements. | |
| 1609 On return, filled with the error code for | |
| 1610 the suspend of the corresponding thread. | |
| 1611 The error code will be | |
| 1612 <errorlink id="JVMTI_ERROR_NONE"></errorlink> | |
| 1613 if the thread was suspended by this call. | |
| 1614 Possible error codes are those specified | |
| 1615 for <functionlink id="SuspendThread"></functionlink>. | |
| 1616 </description> | |
| 1617 </param> | |
| 1618 </parameters> | |
| 1619 <errors> | |
| 1620 </errors> | |
| 1621 </function> | |
| 1622 | |
| 1623 <function id="ResumeThread" num="6"> | |
| 1624 <synopsis>Resume Thread</synopsis> | |
| 1625 <description> | |
| 1626 Resume a suspended thread. | |
| 1627 Any threads currently suspended through | |
| 1628 a <jvmti/> suspend function (eg. | |
| 1629 <functionlink id="SuspendThread"></functionlink>) | |
| 1630 or <code>java.lang.Thread.suspend()</code> | |
| 1631 will resume execution; | |
| 1632 all other threads are unaffected. | |
| 1633 </description> | |
| 1634 <origin>jvmdi</origin> | |
| 1635 <capabilities> | |
| 1636 <required id="can_suspend"></required> | |
| 1637 </capabilities> | |
| 1638 <parameters> | |
| 1639 <param id="thread"> | |
| 1640 <jthread/> | |
| 1641 <description> | |
| 1642 The thread to resume. | |
| 1643 </description> | |
| 1644 </param> | |
| 1645 </parameters> | |
| 1646 <errors> | |
| 1647 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 1648 Thread was not suspended. | |
| 1649 </error> | |
| 1650 <error id="JVMTI_ERROR_INVALID_TYPESTATE"> | |
| 1651 The state of the thread has been modified, and is now inconsistent. | |
| 1652 </error> | |
| 1653 </errors> | |
| 1654 </function> | |
| 1655 | |
| 1656 <function id="ResumeThreadList" num="93"> | |
| 1657 <synopsis>Resume Thread List</synopsis> | |
| 1658 <description> | |
| 1659 Resume the <paramlink id="request_count"></paramlink> | |
| 1660 threads specified in the | |
| 1661 <paramlink id="request_list"></paramlink> array. | |
| 1662 Any thread suspended through | |
| 1663 a <jvmti/> suspend function (eg. | |
| 1664 <functionlink id="SuspendThreadList"></functionlink>) | |
| 1665 or <code>java.lang.Thread.suspend()</code> | |
| 1666 will resume execution. | |
| 1667 </description> | |
| 1668 <origin>jvmdi</origin> | |
| 1669 <capabilities> | |
| 1670 <required id="can_suspend"></required> | |
| 1671 </capabilities> | |
| 1672 <parameters> | |
| 1673 <param id="request_count"> | |
| 1674 <jint min="0"/> | |
| 1675 <description> | |
| 1676 The number of threads to resume. | |
| 1677 </description> | |
| 1678 </param> | |
| 1679 <param id="request_list"> | |
| 1680 <inbuf incount="request_count"><jthread/></inbuf> | |
| 1681 <description> | |
| 1682 The threads to resume. | |
| 1683 </description> | |
| 1684 </param> | |
| 1685 <param id="results"> | |
| 1686 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> | |
| 1687 <description> | |
| 1688 An agent supplied array of | |
| 1689 <paramlink id="request_count"></paramlink> elements. | |
| 1690 On return, filled with the error code for | |
| 1691 the resume of the corresponding thread. | |
| 1692 The error code will be | |
| 1693 <errorlink id="JVMTI_ERROR_NONE"></errorlink> | |
| 1694 if the thread was suspended by this call. | |
| 1695 Possible error codes are those specified | |
| 1696 for <functionlink id="ResumeThread"></functionlink>. | |
| 1697 </description> | |
| 1698 </param> | |
| 1699 </parameters> | |
| 1700 <errors> | |
| 1701 </errors> | |
| 1702 </function> | |
| 1703 | |
| 1704 <function id="StopThread" num="7"> | |
| 1705 <synopsis>Stop Thread</synopsis> | |
| 1706 <description> | |
| 1707 Send the specified asynchronous exception to the specified thread | |
| 1708 (similar to <code>java.lang.Thread.stop</code>). | |
| 1709 Normally, this function is used to kill the specified thread with an | |
| 1710 instance of the exception <code>ThreadDeath</code>. | |
| 1711 </description> | |
| 1712 <origin>jvmdi</origin> | |
| 1713 <capabilities> | |
| 1714 <required id="can_signal_thread"></required> | |
| 1715 </capabilities> | |
| 1716 <parameters> | |
| 1717 <param id="thread"> | |
| 1718 <jthread/> | |
| 1719 <description> | |
| 1720 The thread to stop. | |
| 1721 </description> | |
| 1722 </param> | |
| 1723 <param id="exception"> | |
| 1724 <jobject/> | |
| 1725 <description> | |
| 1726 The asynchronous exception object. | |
| 1727 </description> | |
| 1728 </param> | |
| 1729 </parameters> | |
| 1730 <errors> | |
| 1731 </errors> | |
| 1732 </function> | |
| 1733 | |
| 1734 <function id="InterruptThread" num="8"> | |
| 1735 <synopsis>Interrupt Thread</synopsis> | |
| 1736 <description> | |
| 1737 Interrupt the specified thread | |
| 1738 (similar to <code>java.lang.Thread.interrupt</code>). | |
| 1739 </description> | |
| 1740 <origin>jvmdi</origin> | |
| 1741 <capabilities> | |
| 1742 <required id="can_signal_thread"></required> | |
| 1743 </capabilities> | |
| 1744 <parameters> | |
| 1745 <param id="thread"> | |
| 1746 <jthread impl="noconvert"/> | |
| 1747 <description> | |
| 1748 The thread to interrupt. | |
| 1749 </description> | |
| 1750 </param> | |
| 1751 </parameters> | |
| 1752 <errors> | |
| 1753 </errors> | |
| 1754 </function> | |
| 1755 | |
| 1756 <function id="GetThreadInfo" num="9"> | |
| 1757 <synopsis>Get Thread Info</synopsis> | |
| 1758 <typedef id="jvmtiThreadInfo" label="Thread information structure"> | |
| 1759 <field id="name"> | |
| 1760 <allocfieldbuf><char/></allocfieldbuf> | |
| 1761 <description> | |
| 1762 The thread name, encoded as a | |
| 1763 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 1764 </description> | |
| 1765 </field> | |
| 1766 <field id="priority"> | |
| 1767 <jint/> | |
| 1768 <description> | |
| 1769 The thread priority. See the thread priority constants: | |
| 1770 <datalink id="jvmtiThreadPriority"></datalink>. | |
| 1771 </description> | |
| 1772 </field> | |
| 1773 <field id="is_daemon"> | |
| 1774 <jboolean/> | |
| 1775 <description> | |
| 1776 Is this a daemon thread? | |
| 1777 </description> | |
| 1778 </field> | |
| 1779 <field id="thread_group"> | |
| 1780 <jthreadGroup/> | |
| 1781 <description> | |
| 1782 The thread group to which this thread belongs. | |
| 1783 <code>NULL</code> if the thread has died. | |
| 1784 </description> | |
| 1785 </field> | |
| 1786 <field id="context_class_loader"> | |
| 1787 <jobject/> | |
| 1788 <description> | |
| 1789 The context class loader associated with this thread. | |
| 1790 </description> | |
| 1791 </field> | |
| 1792 </typedef> | |
| 1793 <description> | |
| 1794 Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure | |
| 1795 are filled in with details of the specified thread. | |
| 1796 </description> | |
| 1797 <origin>jvmdi</origin> | |
| 1798 <capabilities> | |
| 1799 </capabilities> | |
| 1800 <parameters> | |
| 1801 <param id="thread"> | |
| 1802 <jthread null="current" impl="noconvert" started="maybe"/> | |
| 1803 <description> | |
| 1804 The thread to query. | |
| 1805 </description> | |
| 1806 </param> | |
| 1807 <param id="info_ptr"> | |
| 1808 <outptr><struct>jvmtiThreadInfo</struct></outptr> | |
| 1809 <description> | |
| 1810 On return, filled with information describing the specified thread. | |
| 1811 <p/> | |
| 1812 For JDK 1.1 implementations that don't | |
| 1813 recognize context class loaders, | |
| 1814 the <code>context_class_loader</code> field will be NULL. | |
| 1815 </description> | |
| 1816 </param> | |
| 1817 </parameters> | |
| 1818 <errors> | |
| 1819 </errors> | |
| 1820 </function> | |
| 1821 | |
| 1822 <function id="GetOwnedMonitorInfo" num="10"> | |
| 1823 <synopsis>Get Owned Monitor Info</synopsis> | |
| 1824 <description> | |
| 1825 Get information about the monitors owned by the | |
| 1826 specified thread. | |
| 1827 </description> | |
| 1828 <origin>jvmdiClone</origin> | |
| 1829 <capabilities> | |
| 1830 <required id="can_get_owned_monitor_info"></required> | |
| 1831 </capabilities> | |
| 1832 <parameters> | |
| 1833 <param id="thread"> | |
| 1834 <jthread null="current"/> | |
| 1835 <description> | |
| 1836 The thread to query. | |
| 1837 </description> | |
| 1838 </param> | |
| 1839 <param id="owned_monitor_count_ptr"> | |
| 1840 <outptr><jint/></outptr> | |
| 1841 <description> | |
| 1842 The number of monitors returned. | |
| 1843 </description> | |
| 1844 </param> | |
| 1845 <param id="owned_monitors_ptr"> | |
| 1846 <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf> | |
| 1847 <description> | |
| 1848 The array of owned monitors. | |
| 1849 </description> | |
| 1850 </param> | |
| 1851 </parameters> | |
| 1852 <errors> | |
| 1853 </errors> | |
| 1854 </function> | |
| 1855 | |
| 1856 <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1"> | |
| 1857 <synopsis>Get Owned Monitor Stack Depth Info</synopsis> | |
| 1858 <typedef id="jvmtiMonitorStackDepthInfo" | |
| 1859 label="Monitor stack depth information structure"> | |
| 1860 <field id="monitor"> | |
| 1861 <jobject/> | |
| 1862 <description> | |
| 1863 The owned monitor. | |
| 1864 </description> | |
| 1865 </field> | |
| 1866 <field id="stack_depth"> | |
| 1867 <jint/> | |
| 1868 <description> | |
| 1869 The stack depth. Corresponds to the stack depth used in the | |
| 1870 <internallink id="stack">Stack Frame functions</internallink>. | |
| 1871 That is, zero is the current frame, one is the frame which | |
| 1872 called the current frame. And it is negative one if the | |
| 1873 implementation cannot determine the stack depth (e.g., for | |
| 1874 monitors acquired by JNI <code>MonitorEnter</code>). | |
| 1875 </description> | |
| 1876 </field> | |
| 1877 </typedef> | |
| 1878 <description> | |
| 1879 Get information about the monitors owned by the | |
| 1880 specified thread and the depth of the stack frame which locked them. | |
| 1881 </description> | |
| 1882 <origin>new</origin> | |
| 1883 <capabilities> | |
| 1884 <required id="can_get_owned_monitor_stack_depth_info"></required> | |
| 1885 </capabilities> | |
| 1886 <parameters> | |
| 1887 <param id="thread"> | |
| 1888 <jthread null="current"/> | |
| 1889 <description> | |
| 1890 The thread to query. | |
| 1891 </description> | |
| 1892 </param> | |
| 1893 <param id="monitor_info_count_ptr"> | |
| 1894 <outptr><jint/></outptr> | |
| 1895 <description> | |
| 1896 The number of monitors returned. | |
| 1897 </description> | |
| 1898 </param> | |
| 1899 <param id="monitor_info_ptr"> | |
|
10981
5c89346f2bdd
6493116: JVMTI Doc: GetOwnedMonitorStackDepthInfo has a typo in monitor_info_ptr parameter description
sspitsyn
parents:
7168
diff
changeset
|
1900 <allocbuf outcount="monitor_info_count_ptr"> |
| 0 | 1901 <struct>jvmtiMonitorStackDepthInfo</struct> |
| 1902 </allocbuf> | |
| 1903 <description> | |
| 1904 The array of owned monitor depth information. | |
| 1905 </description> | |
| 1906 </param> | |
| 1907 </parameters> | |
| 1908 <errors> | |
| 1909 </errors> | |
| 1910 </function> | |
| 1911 | |
| 1912 <function id="GetCurrentContendedMonitor" num="11"> | |
| 1913 <synopsis>Get Current Contended Monitor</synopsis> | |
| 1914 <description> | |
| 1915 Get the object, if any, whose monitor the specified thread is waiting to | |
| 1916 enter or waiting to regain through <code>java.lang.Object.wait</code>. | |
| 1917 </description> | |
| 1918 <origin>jvmdi</origin> | |
| 1919 <capabilities> | |
| 1920 <required id="can_get_current_contended_monitor"></required> | |
| 1921 </capabilities> | |
| 1922 <parameters> | |
| 1923 <param id="thread"> | |
| 1924 <jthread null="current"/> | |
| 1925 <description> | |
| 1926 The thread to query. | |
| 1927 </description> | |
| 1928 </param> | |
| 1929 <param id="monitor_ptr"> | |
| 1930 <outptr><jobject/></outptr> | |
| 1931 <description> | |
| 1932 On return, filled with the current contended monitor, or | |
| 1933 NULL if there is none. | |
| 1934 </description> | |
| 1935 </param> | |
| 1936 </parameters> | |
| 1937 <errors> | |
| 1938 </errors> | |
| 1939 </function> | |
| 1940 | |
| 1941 <callback id="jvmtiStartFunction"> | |
| 1942 <void/> | |
| 1943 <synopsis>Agent Start Function</synopsis> | |
| 1944 <description> | |
| 1945 Agent supplied callback function. | |
| 1946 This function is the entry point for an agent thread | |
| 1947 started with | |
| 1948 <functionlink id="RunAgentThread"></functionlink>. | |
| 1949 </description> | |
| 1950 <parameters> | |
| 1951 <param id="jvmti_env"> | |
| 1952 <outptr> | |
| 1953 <struct>jvmtiEnv</struct> | |
| 1954 </outptr> | |
| 1955 <description> | |
| 1956 The <jvmti/> environment. | |
| 1957 </description> | |
| 1958 </param> | |
| 1959 <param id="jni_env"> | |
| 1960 <outptr> | |
| 1961 <struct>JNIEnv</struct> | |
| 1962 </outptr> | |
| 1963 <description> | |
| 1964 The JNI environment. | |
| 1965 </description> | |
| 1966 </param> | |
| 1967 <param id="arg"> | |
| 1968 <outptr> | |
| 1969 <void/> | |
| 1970 </outptr> | |
| 1971 <description> | |
| 1972 The <code>arg</code> parameter passed to | |
| 1973 <functionlink id="RunAgentThread"></functionlink>. | |
| 1974 </description> | |
| 1975 </param> | |
| 1976 </parameters> | |
| 1977 </callback> | |
| 1978 | |
| 1979 <function id="RunAgentThread" num="12"> | |
| 1980 <synopsis>Run Agent Thread</synopsis> | |
| 1981 <description> | |
| 1982 Starts the execution of an agent thread. with the specified native function. | |
| 1983 The parameter <paramlink id="arg"></paramlink> is forwarded on to the | |
| 1984 <functionlink id="jvmtiStartFunction">start function</functionlink> | |
| 1985 (specified with <paramlink id="proc"></paramlink>) as its single argument. | |
| 1986 This function allows the creation of agent threads | |
| 1987 for handling communication with another process or for handling events | |
| 1988 without the need to load a special subclass of <code>java.lang.Thread</code> or | |
| 1989 implementer of <code>java.lang.Runnable</code>. | |
| 1990 Instead, the created thread can run entirely in native code. | |
| 1991 However, the created thread does require a newly created instance | |
| 1992 of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to | |
| 1993 which it will be associated. | |
| 1994 The thread object can be created with JNI calls. | |
| 1995 <p/> | |
| 1996 The following common thread priorities are provided for your convenience: | |
| 1997 <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const"> | |
| 1998 <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1"> | |
| 1999 Minimum possible thread priority | |
| 2000 </constant> | |
| 2001 <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5"> | |
| 2002 Normal thread priority | |
| 2003 </constant> | |
| 2004 <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10"> | |
| 2005 Maximum possible thread priority | |
| 2006 </constant> | |
| 2007 </constants> | |
| 2008 <p/> | |
| 2009 The new thread is started as a daemon thread with the specified | |
| 2010 <paramlink id="priority"></paramlink>. | |
| 2011 If enabled, a <eventlink id="ThreadStart"/> event will be sent. | |
| 2012 <p/> | |
| 2013 Since the thread has been started, the thread will be live when this function | |
| 2014 returns, unless the thread has died immediately. | |
| 2015 <p/> | |
| 2016 The thread group of the thread is ignored -- specifically, the thread is not | |
| 2017 added to the thread group and the thread is not seen on queries of the thread | |
| 2018 group at either the Java programming language or <jvmti/> levels. | |
| 2019 <p/> | |
| 2020 The thread is not visible to Java programming language queries but is | |
| 2021 included in <jvmti/> queries (for example, | |
| 2022 <functionlink id="GetAllThreads"/> and | |
| 2023 <functionlink id="GetAllStackTraces"/>). | |
| 2024 <p/> | |
| 2025 Upon execution of <code>proc</code>, the new thread will be attached to the | |
| 2026 VM--see the JNI documentation on | |
| 6919 | 2027 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#wp1060" |
| 0 | 2028 >Attaching to the VM</externallink>. |
| 2029 </description> | |
| 2030 <origin>jvmdiClone</origin> | |
| 2031 <capabilities> | |
| 2032 </capabilities> | |
| 2033 <parameters> | |
| 2034 <param id="thread"> | |
| 2035 <jthread impl="noconvert" started="no"/> | |
| 2036 <description> | |
| 2037 The thread to run. | |
| 2038 </description> | |
| 2039 </param> | |
| 2040 <param id="proc"> | |
| 2041 <ptrtype> | |
| 2042 <struct>jvmtiStartFunction</struct> | |
| 2043 </ptrtype> | |
| 2044 <description> | |
| 2045 The start function. | |
| 2046 </description> | |
| 2047 </param> | |
| 2048 <param id="arg"> | |
| 2049 <inbuf> | |
| 2050 <void/> | |
| 2051 <nullok><code>NULL</code> is passed to the start function</nullok> | |
| 2052 </inbuf> | |
| 2053 <description> | |
| 2054 The argument to the start function. | |
| 2055 </description> | |
| 2056 </param> | |
| 2057 <param id="priority"> | |
| 2058 <jint/> | |
| 2059 <description> | |
| 2060 The priority of the started thread. Any thread | |
| 2061 priority allowed by <code>java.lang.Thread.setPriority</code> can be used including | |
| 2062 those in <datalink id="jvmtiThreadPriority"></datalink>. | |
| 2063 </description> | |
| 2064 </param> | |
| 2065 </parameters> | |
| 2066 <errors> | |
| 2067 <error id="JVMTI_ERROR_INVALID_PRIORITY"> | |
| 2068 <paramlink id="priority"/> is less than | |
| 2069 <datalink id="JVMTI_THREAD_MIN_PRIORITY"/> | |
| 2070 or greater than | |
| 2071 <datalink id="JVMTI_THREAD_MAX_PRIORITY"/> | |
| 2072 </error> | |
| 2073 </errors> | |
| 2074 </function> | |
| 2075 | |
| 2076 <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103"> | |
| 2077 <synopsis>Set Thread Local Storage</synopsis> | |
| 2078 <description> | |
| 2079 The VM stores a pointer value associated with each environment-thread | |
| 2080 pair. This pointer value is called <i>thread-local storage</i>. | |
| 2081 This value is <code>NULL</code> unless set with this function. | |
| 2082 Agents can allocate memory in which they store thread specific | |
| 2083 information. By setting thread-local storage it can then be | |
| 2084 accessed with | |
| 2085 <functionlink id="GetThreadLocalStorage"></functionlink>. | |
| 2086 <p/> | |
| 2087 This function is called by the agent to set the value of the <jvmti/> | |
| 2088 thread-local storage. <jvmti/> supplies to the agent a pointer-size | |
| 2089 thread-local storage that can be used to record per-thread | |
| 2090 information. | |
| 2091 </description> | |
| 2092 <origin>jvmpi</origin> | |
| 2093 <capabilities> | |
| 2094 </capabilities> | |
| 2095 <parameters> | |
| 2096 <param id="thread"> | |
| 2097 <jthread null="current"/> | |
| 2098 <description> | |
| 2099 Store to this thread. | |
| 2100 </description> | |
| 2101 </param> | |
| 2102 <param id="data"> | |
| 2103 <inbuf> | |
| 2104 <void/> | |
| 2105 <nullok>value is set to <code>NULL</code></nullok> | |
| 2106 </inbuf> | |
| 2107 <description> | |
| 2108 The value to be entered into the thread-local storage. | |
| 2109 </description> | |
| 2110 </param> | |
| 2111 </parameters> | |
| 2112 <errors> | |
| 2113 </errors> | |
| 2114 </function> | |
| 2115 | |
| 2116 <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102"> | |
| 2117 <synopsis>Get Thread Local Storage</synopsis> | |
| 2118 <description> | |
| 2119 Called by the agent to get the value of the <jvmti/> thread-local | |
| 2120 storage. | |
| 2121 </description> | |
| 2122 <origin>jvmpi</origin> | |
| 2123 <capabilities> | |
| 2124 </capabilities> | |
| 2125 <parameters> | |
| 2126 <param id="thread"> | |
| 2127 <jthread null="current" impl="noconvert"/> | |
| 2128 <description> | |
| 2129 Retrieve from this thread. | |
| 2130 </description> | |
| 2131 </param> | |
| 2132 <param id="data_ptr"> | |
| 2133 <agentbuf><void/></agentbuf> | |
| 2134 <description> | |
| 2135 Pointer through which the value of the thread local | |
| 2136 storage is returned. | |
| 2137 If thread-local storage has not been set with | |
| 2138 <functionlink id="SetThreadLocalStorage"></functionlink> the returned | |
| 2139 pointer is <code>NULL</code>. | |
| 2140 </description> | |
| 2141 </param> | |
| 2142 </parameters> | |
| 2143 <errors> | |
| 2144 </errors> | |
| 2145 </function> | |
| 2146 | |
| 2147 </category> | |
| 2148 | |
| 2149 <category id="thread_groups" label="Thread Group"> | |
| 2150 <intro> | |
| 2151 </intro> | |
| 2152 | |
| 2153 <function id="GetTopThreadGroups" num="13"> | |
| 2154 <synopsis>Get Top Thread Groups</synopsis> | |
| 2155 <description> | |
| 2156 Return all top-level (parentless) thread groups in the VM. | |
| 2157 </description> | |
| 2158 <origin>jvmdi</origin> | |
| 2159 <capabilities> | |
| 2160 </capabilities> | |
| 2161 <parameters> | |
| 2162 <param id="group_count_ptr"> | |
| 2163 <outptr><jint/></outptr> | |
| 2164 <description> | |
| 2165 On return, points to the number of top-level thread groups. | |
| 2166 </description> | |
| 2167 </param> | |
| 2168 <param id="groups_ptr"> | |
| 2169 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> | |
| 2170 <description> | |
| 2171 On return, refers to a pointer to the top-level thread group array. | |
| 2172 </description> | |
| 2173 </param> | |
| 2174 </parameters> | |
| 2175 <errors> | |
| 2176 </errors> | |
| 2177 </function> | |
| 2178 | |
| 2179 <function id="GetThreadGroupInfo" num="14"> | |
| 2180 <synopsis>Get Thread Group Info</synopsis> | |
| 2181 <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure"> | |
| 2182 <field id="parent"> | |
| 2183 <jthreadGroup/> | |
| 2184 <description> | |
| 2185 The parent thread group. | |
| 2186 </description> | |
| 2187 </field> | |
| 2188 <field id="name"> | |
| 2189 <allocfieldbuf><char/></allocfieldbuf> | |
| 2190 <description> | |
| 2191 The thread group's name, encoded as a | |
| 2192 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 2193 </description> | |
| 2194 </field> | |
| 2195 <field id="max_priority"> | |
| 2196 <jint/> | |
| 2197 <description> | |
| 2198 The maximum priority for this thread group. | |
| 2199 </description> | |
| 2200 </field> | |
| 2201 <field id="is_daemon"> | |
| 2202 <jboolean/> | |
| 2203 <description> | |
| 2204 Is this a daemon thread group? | |
| 2205 </description> | |
| 2206 </field> | |
| 2207 </typedef> | |
| 2208 <description> | |
| 2209 Get information about the thread group. The fields of the | |
| 2210 <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure | |
| 2211 are filled in with details of the specified thread group. | |
| 2212 </description> | |
| 2213 <origin>jvmdi</origin> | |
| 2214 <capabilities> | |
| 2215 </capabilities> | |
| 2216 <parameters> | |
| 2217 <param id="group"> | |
| 2218 <jthreadGroup/> | |
| 2219 <description> | |
| 2220 The thread group to query. | |
| 2221 </description> | |
| 2222 </param> | |
| 2223 <param id="info_ptr"> | |
| 2224 <outptr><struct>jvmtiThreadGroupInfo</struct></outptr> | |
| 2225 <description> | |
| 2226 On return, filled with information describing the specified | |
| 2227 thread group. | |
| 2228 </description> | |
| 2229 </param> | |
| 2230 </parameters> | |
| 2231 <errors> | |
| 2232 </errors> | |
| 2233 </function> | |
| 2234 | |
| 2235 <function id="GetThreadGroupChildren" num="15"> | |
| 2236 <synopsis>Get Thread Group Children</synopsis> | |
| 2237 <description> | |
| 2238 Get the live threads and active subgroups in this thread group. | |
| 2239 </description> | |
| 2240 <origin>jvmdi</origin> | |
| 2241 <capabilities> | |
| 2242 </capabilities> | |
| 2243 <parameters> | |
| 2244 <param id="group"> | |
| 2245 <jthreadGroup/> | |
| 2246 <description> | |
| 2247 The group to query. | |
| 2248 </description> | |
| 2249 </param> | |
| 2250 <param id="thread_count_ptr"> | |
| 2251 <outptr><jint/></outptr> | |
| 2252 <description> | |
| 2253 On return, points to the number of live threads in this thread group. | |
| 2254 </description> | |
| 2255 </param> | |
| 2256 <param id="threads_ptr"> | |
| 2257 <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf> | |
| 2258 <description> | |
| 2259 On return, points to an array of the live threads in this thread group. | |
| 2260 </description> | |
| 2261 </param> | |
| 2262 <param id="group_count_ptr"> | |
| 2263 <outptr><jint/></outptr> | |
| 2264 <description> | |
| 2265 On return, points to the number of active child thread groups | |
| 2266 </description> | |
| 2267 </param> | |
| 2268 <param id="groups_ptr"> | |
| 2269 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> | |
| 2270 <description> | |
| 2271 On return, points to an array of the active child thread groups. | |
| 2272 </description> | |
| 2273 </param> | |
| 2274 </parameters> | |
| 2275 <errors> | |
| 2276 </errors> | |
| 2277 </function> | |
| 2278 </category> | |
| 2279 | |
| 2280 <category id="stack" label="Stack Frame"> | |
| 2281 <intro> | |
| 2282 These functions provide information about the stack of a thread. | |
| 2283 Stack frames are referenced by depth. | |
| 2284 The frame at depth zero is the current frame. | |
| 2285 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
2286 Stack frames are as described in |
|
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
2287 <vmspec chapter="3.6"/>, |
| 0 | 2288 That is, they correspond to method |
| 2289 invocations (including native methods) but do not correspond to platform native or | |
| 2290 VM internal frames. | |
| 2291 <p/> | |
| 2292 A <jvmti/> implementation may use method invocations to launch a thread and | |
| 2293 the corresponding frames may be included in the stack as presented by these functions -- | |
| 2294 that is, there may be frames shown | |
| 2295 deeper than <code>main()</code> and <code>run()</code>. | |
| 2296 However this presentation must be consistent across all <jvmti/> functionality which | |
| 2297 uses stack frames or stack depth. | |
| 2298 </intro> | |
| 2299 | |
| 2300 <typedef id="jvmtiFrameInfo" label="Stack frame information structure"> | |
| 2301 <description> | |
| 2302 Information about a stack frame is returned in this structure. | |
| 2303 </description> | |
| 2304 <field id="method"> | |
| 2305 <jmethodID/> | |
| 2306 <description> | |
| 2307 The method executing in this frame. | |
| 2308 </description> | |
| 2309 </field> | |
| 2310 <field id="location"> | |
| 2311 <jlocation/> | |
| 2312 <description> | |
| 2313 The index of the instruction executing in this frame. | |
| 2314 <code>-1</code> if the frame is executing a native method. | |
| 2315 </description> | |
| 2316 </field> | |
| 2317 </typedef> | |
| 2318 | |
| 2319 <typedef id="jvmtiStackInfo" label="Stack information structure"> | |
| 2320 <description> | |
| 2321 Information about a set of stack frames is returned in this structure. | |
| 2322 </description> | |
| 2323 <field id="thread"> | |
| 2324 <jthread/> | |
| 2325 <description> | |
| 2326 On return, the thread traced. | |
| 2327 </description> | |
| 2328 </field> | |
| 2329 <field id="state"> | |
| 2330 <jint/> | |
| 2331 <description> | |
| 2332 On return, the thread state. See <functionlink id="GetThreadState"></functionlink>. | |
| 2333 </description> | |
| 2334 </field> | |
| 2335 <field id="frame_buffer"> | |
| 2336 <outbuf incount="max_frame_count"> | |
| 2337 <struct>jvmtiFrameInfo</struct> | |
| 2338 </outbuf> | |
| 2339 <description> | |
| 2340 On return, this agent allocated buffer is filled | |
| 2341 with stack frame information. | |
| 2342 </description> | |
| 2343 </field> | |
| 2344 <field id="frame_count"> | |
| 2345 <jint/> | |
| 2346 <description> | |
| 2347 On return, the number of records filled into | |
| 2348 <code>frame_buffer</code>. | |
| 2349 This will be | |
| 2350 min(<code>max_frame_count</code>, <i>stackDepth</i>). | |
| 2351 </description> | |
| 2352 </field> | |
| 2353 </typedef> | |
| 2354 | |
| 2355 <function id="GetStackTrace" num="104"> | |
| 2356 <synopsis>Get Stack Trace</synopsis> | |
| 2357 <description> | |
| 2358 Get information about the stack of a thread. | |
| 2359 If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack, | |
| 2360 the <paramlink id="max_frame_count"></paramlink> topmost frames are returned, | |
| 2361 otherwise the entire stack is returned. | |
| 2362 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
| 2363 <p/> | |
| 2364 The following example causes up to five of the topmost frames | |
| 2365 to be returned and (if there are any frames) the currently | |
| 2366 executing method name to be printed. | |
| 2367 <example> | |
| 2368 jvmtiFrameInfo frames[5]; | |
| 2369 jint count; | |
| 2370 jvmtiError err; | |
| 2371 | |
| 2372 err = (*jvmti)->GetStackTrace(jvmti, aThread, 0, 5, | |
|
7168
73e64867adb7
8003690: Example code in JVMTI GetStackTrace documentation is broken
mikael
parents:
6919
diff
changeset
|
2373 frames, &count); |
| 0 | 2374 if (err == JVMTI_ERROR_NONE && count >= 1) { |
| 2375 char *methodName; | |
| 2376 err = (*jvmti)->GetMethodName(jvmti, frames[0].method, | |
|
7168
73e64867adb7
8003690: Example code in JVMTI GetStackTrace documentation is broken
mikael
parents:
6919
diff
changeset
|
2377 &methodName, NULL, NULL); |
| 0 | 2378 if (err == JVMTI_ERROR_NONE) { |
| 2379 printf("Executing method: %s", methodName); | |
| 2380 } | |
| 2381 } | |
| 2382 </example> | |
| 2383 <todo> | |
| 2384 check example code. | |
| 2385 </todo> | |
| 2386 <p/> | |
| 2387 The <paramlink id="thread"></paramlink> need not be suspended | |
| 2388 to call this function. | |
| 2389 <p/> | |
| 2390 The <functionlink id="GetLineNumberTable"></functionlink> | |
| 2391 function can be used to map locations to line numbers. Note that | |
| 2392 this mapping can be done lazily. | |
| 2393 </description> | |
| 2394 <origin>jvmpi</origin> | |
| 2395 <capabilities> | |
| 2396 </capabilities> | |
| 2397 <parameters> | |
| 2398 <param id="thread"> | |
| 2399 <jthread null="current"/> | |
| 2400 <description> | |
| 2401 Fetch the stack trace of this thread. | |
| 2402 </description> | |
| 2403 </param> | |
| 2404 <param id="start_depth"> | |
| 2405 <jint/> | |
| 2406 <description> | |
| 2407 Begin retrieving frames at this depth. | |
| 2408 If non-negative, count from the current frame, | |
| 2409 the first frame retrieved is at depth <code>start_depth</code>. | |
| 2410 For example, if zero, start from the current frame; if one, start from the | |
| 2411 caller of the current frame; if two, start from the caller of the | |
| 2412 caller of the current frame; and so on. | |
| 2413 If negative, count from below the oldest frame, | |
| 2414 the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>, | |
| 2415 where <i>stackDepth</i> is the count of frames on the stack. | |
| 2416 For example, if negative one, only the oldest frame is retrieved; | |
| 2417 if negative two, start from the frame called by the oldest frame. | |
| 2418 </description> | |
| 2419 </param> | |
| 2420 <param id="max_frame_count"> | |
| 2421 <jint min="0"/> | |
| 2422 <description> | |
| 2423 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. | |
| 2424 </description> | |
| 2425 </param> | |
| 2426 <param id="frame_buffer"> | |
| 2427 <outbuf incount="max_frame_count" outcount="count_ptr"> | |
| 2428 <struct>jvmtiFrameInfo</struct> | |
| 2429 </outbuf> | |
| 2430 <description> | |
| 2431 On return, this agent allocated buffer is filled | |
| 2432 with stack frame information. | |
| 2433 </description> | |
| 2434 </param> | |
| 2435 <param id="count_ptr"> | |
| 2436 <outptr><jint/></outptr> | |
| 2437 <description> | |
| 2438 On return, points to the number of records filled in. | |
| 2439 For non-negative <code>start_depth</code>, this will be | |
| 2440 min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>). | |
| 2441 For negative <code>start_depth</code>, this will be | |
| 2442 min(<code>max_frame_count</code>, <code>-start_depth</code>). | |
| 2443 </description> | |
| 2444 </param> | |
| 2445 </parameters> | |
| 2446 <errors> | |
| 2447 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 2448 <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>. | |
| 2449 Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>. | |
| 2450 </error> | |
| 2451 </errors> | |
| 2452 </function> | |
| 2453 | |
| 2454 | |
| 2455 <function id="GetAllStackTraces" num="100"> | |
| 2456 <synopsis>Get All Stack Traces</synopsis> | |
| 2457 <description> | |
| 2458 Get information about the stacks of all live threads | |
| 2459 (including <internallink id="RunAgentThread">agent threads</internallink>). | |
| 2460 If <paramlink id="max_frame_count"/> is less than the depth of a stack, | |
| 2461 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, | |
| 2462 otherwise the entire stack is returned. | |
| 2463 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
| 2464 <p/> | |
| 2465 All stacks are collected simultaneously, that is, no changes will occur to the | |
| 2466 thread state or stacks between the sampling of one thread and the next. | |
| 2467 The threads need not be suspended. | |
| 2468 | |
| 2469 <example> | |
| 2470 jvmtiStackInfo *stack_info; | |
| 2471 jint thread_count; | |
| 2472 int ti; | |
| 2473 jvmtiError err; | |
| 2474 | |
| 2475 err = (*jvmti)->GetAllStackTraces(jvmti, MAX_FRAMES, &stack_info, &thread_count); | |
| 2476 if (err != JVMTI_ERROR_NONE) { | |
| 2477 ... | |
| 2478 } | |
| 2479 for (ti = 0; ti < thread_count; ++ti) { | |
| 2480 jvmtiStackInfo *infop = &stack_info[ti]; | |
| 2481 jthread thread = infop->thread; | |
| 2482 jint state = infop->state; | |
| 2483 jvmtiFrameInfo *frames = infop->frame_buffer; | |
| 2484 int fi; | |
| 2485 | |
| 2486 myThreadAndStatePrinter(thread, state); | |
| 2487 for (fi = 0; fi < infop->frame_count; fi++) { | |
| 2488 myFramePrinter(frames[fi].method, frames[fi].location); | |
| 2489 } | |
| 2490 } | |
| 2491 /* this one Deallocate call frees all data allocated by GetAllStackTraces */ | |
| 2492 err = (*jvmti)->Deallocate(jvmti, stack_info); | |
| 2493 </example> | |
| 2494 <todo> | |
| 2495 check example code. | |
| 2496 </todo> | |
| 2497 | |
| 2498 </description> | |
| 2499 <origin>new</origin> | |
| 2500 <capabilities> | |
| 2501 </capabilities> | |
| 2502 <parameters> | |
| 2503 <param id="max_frame_count"> | |
| 2504 <jint min="0"/> | |
| 2505 <description> | |
| 2506 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. | |
| 2507 </description> | |
| 2508 </param> | |
| 2509 <param id="stack_info_ptr"> | |
| 2510 <allocbuf> | |
| 2511 <struct>jvmtiStackInfo</struct> | |
| 2512 </allocbuf> | |
| 2513 <description> | |
| 2514 On return, this buffer is filled | |
| 2515 with stack information for each thread. | |
| 2516 The number of <datalink id="jvmtiStackInfo"/> records is determined | |
| 2517 by <paramlink id="thread_count_ptr"/>. | |
| 2518 <p/> | |
| 2519 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> | |
| 2520 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. | |
| 2521 These buffers must not be separately deallocated. | |
| 2522 </description> | |
| 2523 </param> | |
| 2524 <param id="thread_count_ptr"> | |
| 2525 <outptr><jint/></outptr> | |
| 2526 <description> | |
| 2527 The number of threads traced. | |
| 2528 </description> | |
| 2529 </param> | |
| 2530 </parameters> | |
| 2531 <errors> | |
| 2532 </errors> | |
| 2533 </function> | |
| 2534 | |
| 2535 <function id="GetThreadListStackTraces" num="101"> | |
| 2536 <synopsis>Get Thread List Stack Traces</synopsis> | |
| 2537 <description> | |
| 2538 Get information about the stacks of the supplied threads. | |
| 2539 If <paramlink id="max_frame_count"/> is less than the depth of a stack, | |
| 2540 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, | |
| 2541 otherwise the entire stack is returned. | |
| 2542 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
| 2543 <p/> | |
| 2544 All stacks are collected simultaneously, that is, no changes will occur to the | |
| 2545 thread state or stacks between the sampling one thread and the next. | |
| 2546 The threads need not be suspended. | |
| 2547 <p/> | |
| 2548 If a thread has not yet started or terminates before the stack information is collected, | |
| 2549 a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero) | |
| 2550 will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked. | |
| 2551 <p/> | |
| 2552 See the example for the similar function | |
| 2553 <functionlink id="GetAllStackTraces"/>. | |
| 2554 </description> | |
| 2555 <origin>new</origin> | |
| 2556 <capabilities> | |
| 2557 </capabilities> | |
| 2558 <parameters> | |
| 2559 <param id="thread_count"> | |
| 2560 <jint min="0"/> | |
| 2561 <description> | |
| 2562 The number of threads to trace. | |
| 2563 </description> | |
| 2564 </param> | |
| 2565 <param id="thread_list"> | |
| 2566 <inbuf incount="thread_count"><jthread/></inbuf> | |
| 2567 <description> | |
| 2568 The list of threads to trace. | |
| 2569 </description> | |
| 2570 </param> | |
| 2571 <param id="max_frame_count"> | |
| 2572 <jint min="0"/> | |
| 2573 <description> | |
| 2574 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. | |
| 2575 </description> | |
| 2576 </param> | |
| 2577 <param id="stack_info_ptr"> | |
| 2578 <allocbuf outcount="thread_count"> | |
| 2579 <struct>jvmtiStackInfo</struct> | |
| 2580 </allocbuf> | |
| 2581 <description> | |
| 2582 On return, this buffer is filled | |
| 2583 with stack information for each thread. | |
| 2584 The number of <datalink id="jvmtiStackInfo"/> records is determined | |
| 2585 by <paramlink id="thread_count"/>. | |
| 2586 <p/> | |
| 2587 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> | |
| 2588 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. | |
| 2589 These buffers must not be separately deallocated. | |
| 2590 </description> | |
| 2591 </param> | |
| 2592 </parameters> | |
| 2593 <errors> | |
| 2594 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
| 2595 An element in <paramlink id="thread_list"/> is not a thread object. | |
| 2596 </error> | |
| 2597 </errors> | |
| 2598 </function> | |
| 2599 | |
| 2600 <elide> | |
| 2601 <function id="AsyncGetStackTrace" num="1000"> | |
| 2602 <synopsis>Get Stack Trace--Asynchronous</synopsis> | |
| 2603 <description> | |
| 2604 Get information about the entire stack of a thread (or a sub-section of it). | |
| 2605 This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink> | |
| 2606 and is reentrant and safe to call | |
| 2607 from asynchronous signal handlers. | |
| 2608 The stack trace is returned only for the calling thread. | |
| 2609 <p/> | |
| 2610 The <functionlink id="GetLineNumberTable"></functionlink> | |
| 2611 function can be used to map locations to line numbers. Note that | |
| 2612 this mapping can be done lazily. | |
| 2613 </description> | |
| 2614 <origin>jvmpi</origin> | |
| 2615 <capabilities> | |
| 2616 <required id="can_get_async_stack_trace"></required> | |
| 2617 <capability id="can_show_JVM_spec_async_frames"> | |
| 2618 If <code>false</code>, | |
| 2619 <paramlink id="use_java_stack"></paramlink> | |
| 2620 must be <code>false</code>. | |
| 2621 </capability> | |
| 2622 </capabilities> | |
| 2623 <parameters> | |
| 2624 <param id="use_java_stack"> | |
| 2625 <jboolean/> | |
| 2626 <description> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
2627 Return the stack showing <vmspec/> |
| 0 | 2628 model of the stack; |
| 2629 otherwise, show the internal representation of the stack with | |
| 2630 inlined and optimized methods missing. If the virtual machine | |
| 2631 is using the <i>Java Virtual Machine Specification</i> stack model | |
| 2632 internally, this flag is ignored. | |
| 2633 </description> | |
| 2634 </param> | |
| 2635 <param id="max_count"> | |
| 2636 <jint min="0"/> | |
| 2637 <description> | |
| 2638 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. | |
| 2639 Retrieve this many unless the stack depth is less than <code>max_count</code>. | |
| 2640 </description> | |
| 2641 </param> | |
| 2642 <param id="frame_buffer"> | |
| 2643 <outbuf incount="max_count" outcount="count_ptr"> | |
| 2644 <struct>jvmtiFrameInfo</struct> | |
| 2645 <nullok>this information is not returned</nullok> | |
| 2646 </outbuf> | |
| 2647 <description> | |
| 2648 The agent passes in a buffer | |
| 2649 large enough to hold <code>max_count</code> records of | |
| 2650 <datalink id="jvmtiFrameInfo"></datalink>. This buffer must be | |
| 2651 pre-allocated by the agent. | |
| 2652 </description> | |
| 2653 </param> | |
| 2654 <param id="count_ptr"> | |
| 2655 <outptr><jint/></outptr> | |
| 2656 <description> | |
| 2657 On return, points to the number of records filled in.. | |
| 2658 </description> | |
| 2659 </param> | |
| 2660 </parameters> | |
| 2661 <errors> | |
| 2662 <error id="JVMTI_ERROR_UNATTACHED_THREAD"> | |
| 2663 The thread being used to call this function is not attached | |
| 2664 to the virtual machine. Calls must be made from attached threads. | |
| 2665 </error> | |
| 2666 </errors> | |
| 2667 </function> | |
| 2668 </elide> | |
| 2669 | |
| 2670 <function id="GetFrameCount" num="16"> | |
| 2671 <synopsis>Get Frame Count</synopsis> | |
| 2672 <description> | |
| 2673 Get the number of frames currently in the specified thread's call stack. | |
| 2674 <p/> | |
| 2675 If this function is called for a thread actively executing bytecodes (for example, | |
| 2676 not the current thread and not suspended), the information returned is transient. | |
| 2677 </description> | |
| 2678 <origin>jvmdi</origin> | |
| 2679 <capabilities> | |
| 2680 </capabilities> | |
| 2681 <parameters> | |
| 2682 <param id="thread"> | |
| 2683 <jthread null="current"/> | |
| 2684 <description> | |
| 2685 The thread to query. | |
| 2686 </description> | |
| 2687 </param> | |
| 2688 <param id="count_ptr"> | |
| 2689 <outptr><jint/></outptr> | |
| 2690 <description> | |
| 2691 On return, points to the number of frames in the call stack. | |
| 2692 </description> | |
| 2693 </param> | |
| 2694 </parameters> | |
| 2695 <errors> | |
| 2696 </errors> | |
| 2697 </function> | |
| 2698 | |
| 2699 <function id="PopFrame" num="80"> | |
| 2700 <synopsis>Pop Frame</synopsis> | |
| 2701 <description> | |
| 2702 Pop the current frame of <code>thread</code>'s stack. | |
| 2703 Popping a frame takes you to the previous frame. | |
| 2704 When the thread is resumed, the execution | |
| 2705 state of the thread is reset to the state | |
| 2706 immediately before the called method was invoked. | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
2707 That is (using <vmspec/> terminology): |
| 0 | 2708 <ul> |
| 2709 <li>the current frame is discarded as the previous frame becomes the current one</li> | |
| 2710 <li>the operand stack is restored--the argument values are added back | |
| 2711 and if the invoke was not <code>invokestatic</code>, | |
| 2712 <code>objectref</code> is added back as well</li> | |
| 2713 <li>the Java virtual machine PC is restored to the opcode | |
| 2714 of the invoke instruction</li> | |
| 2715 </ul> | |
| 2716 Note however, that any changes to the arguments, which | |
| 2717 occurred in the called method, remain; | |
| 2718 when execution continues, the first instruction to | |
| 2719 execute will be the invoke. | |
| 2720 <p/> | |
| 2721 Between calling <code>PopFrame</code> and resuming the | |
| 2722 thread the state of the stack is undefined. | |
| 2723 To pop frames beyond the first, | |
| 2724 these three steps must be repeated: | |
| 2725 <ul> | |
| 2726 <li>suspend the thread via an event (step, breakpoint, ...)</li> | |
| 2727 <li>call <code>PopFrame</code></li> | |
| 2728 <li>resume the thread</li> | |
| 2729 </ul> | |
| 2730 <p/> | |
| 2731 A lock acquired by calling the called method | |
| 2732 (if it is a <code>synchronized</code> method) | |
| 2733 and locks acquired by entering <code>synchronized</code> | |
| 2734 blocks within the called method are released. | |
| 2735 Note: this does not apply to native locks or | |
| 2736 <code>java.util.concurrent.locks</code> locks. | |
| 2737 <p/> | |
| 2738 Finally blocks are not executed. | |
| 2739 <p/> | |
| 2740 Changes to global state are not addressed and thus remain changed. | |
| 2741 <p/> | |
| 2742 The specified thread must be suspended (which implies it cannot be the current thread). | |
| 2743 <p/> | |
| 2744 Both the called method and calling method must be non-native Java programming | |
| 2745 language methods. | |
| 2746 <p/> | |
| 2747 No <jvmti/> events are generated by this function. | |
| 2748 </description> | |
| 2749 <origin>jvmdi</origin> | |
| 2750 <capabilities> | |
| 2751 <required id="can_pop_frame"></required> | |
| 2752 </capabilities> | |
| 2753 <parameters> | |
| 2754 <param id="thread"> | |
| 2755 <jthread/> | |
| 2756 <description> | |
| 2757 The thread whose current frame is to be popped. | |
| 2758 </description> | |
| 2759 </param> | |
| 2760 </parameters> | |
| 2761 <errors> | |
| 2762 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2763 Called or calling method is a native method. | |
| 2764 The implementation is unable to pop this frame. | |
| 2765 </error> | |
| 2766 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 2767 Thread was not suspended. | |
| 2768 </error> | |
| 2769 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 2770 There are less than two stack frames on the call stack. | |
| 2771 </error> | |
| 2772 </errors> | |
| 2773 </function> | |
| 2774 | |
| 2775 <function id="GetFrameLocation" num="19"> | |
| 2776 <synopsis>Get Frame Location</synopsis> | |
| 2777 <description> | |
| 2778 <p/> | |
| 2779 For a Java programming language frame, return the location of the instruction | |
| 2780 currently executing. | |
| 2781 </description> | |
| 2782 <origin>jvmdiClone</origin> | |
| 2783 <capabilities> | |
| 2784 </capabilities> | |
| 2785 <parameters> | |
| 2786 <param id="thread"> | |
| 2787 <jthread null="current" frame="frame"/> | |
| 2788 <description> | |
| 2789 The thread of the frame to query. | |
| 2790 </description> | |
| 2791 </param> | |
| 2792 <param id="depth"> | |
| 2793 <jframeID thread="thread"/> | |
| 2794 <description> | |
| 2795 The depth of the frame to query. | |
| 2796 </description> | |
| 2797 </param> | |
| 2798 <param id="method_ptr"> | |
| 2799 <outptr><jmethodID/></outptr> | |
| 2800 <description> | |
| 2801 On return, points to the method for the current location. | |
| 2802 </description> | |
| 2803 </param> | |
| 2804 <param id="location_ptr"> | |
| 2805 <outptr><jlocation/></outptr> | |
| 2806 <description> | |
| 2807 On return, points to the index of the currently | |
| 2808 executing instruction. | |
| 2809 Is set to <code>-1</code> if the frame is executing | |
| 2810 a native method. | |
| 2811 </description> | |
| 2812 </param> | |
| 2813 </parameters> | |
| 2814 <errors> | |
| 2815 </errors> | |
| 2816 </function> | |
| 2817 | |
| 2818 <function id="NotifyFramePop" num="20"> | |
| 2819 <synopsis>Notify Frame Pop</synopsis> | |
| 2820 <description> | |
| 2821 When the frame that is currently at <paramlink id="depth"></paramlink> | |
| 2822 is popped from the stack, generate a | |
| 2823 <eventlink id="FramePop"></eventlink> event. See the | |
| 2824 <eventlink id="FramePop"></eventlink> event for details. | |
| 2825 Only frames corresponding to non-native Java programming language | |
| 2826 methods can receive notification. | |
| 2827 <p/> | |
| 2828 The specified thread must either be the current thread | |
| 2829 or the thread must be suspended. | |
| 2830 </description> | |
| 2831 <origin>jvmdi</origin> | |
| 2832 <capabilities> | |
| 2833 <required id="can_generate_frame_pop_events"></required> | |
| 2834 </capabilities> | |
| 2835 <parameters> | |
| 2836 <param id="thread"> | |
| 2837 <jthread null="current" frame="depth"/> | |
| 2838 <description> | |
| 2839 The thread of the frame for which the frame pop event will be generated. | |
| 2840 </description> | |
| 2841 </param> | |
| 2842 <param id="depth"> | |
| 2843 <jframeID thread="thread"/> | |
| 2844 <description> | |
| 2845 The depth of the frame for which the frame pop event will be generated. | |
| 2846 </description> | |
| 2847 </param> | |
| 2848 </parameters> | |
| 2849 <errors> | |
| 2850 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2851 The frame at <code>depth</code> is executing a | |
| 2852 native method. | |
| 2853 </error> | |
| 2854 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 2855 Thread was not suspended and was not the current thread. | |
| 2856 </error> | |
| 2857 </errors> | |
| 2858 </function> | |
| 2859 | |
| 2860 </category> | |
| 2861 | |
| 2862 <category id="ForceEarlyReturn" label="Force Early Return"> | |
| 2863 <intro> | |
| 2864 These functions allow an agent to force a method | |
| 2865 to return at any point during its execution. | |
| 2866 The method which will return early is referred to as the <i>called method</i>. | |
| 2867 The called method is the current method | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
2868 (as defined by |
|
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
2869 <vmspec chapter="3.6"/>) |
| 0 | 2870 for the specified thread at |
| 2871 the time the function is called. | |
| 2872 <p/> | |
| 2873 The specified thread must be suspended or must be the current thread. | |
| 2874 The return occurs when execution of Java programming | |
| 2875 language code is resumed on this thread. | |
| 2876 Between calling one of these functions and resumption | |
| 2877 of thread execution, the state of the stack is undefined. | |
| 2878 <p/> | |
| 2879 No further instructions are executed in the called method. | |
| 2880 Specifically, finally blocks are not executed. | |
| 2881 Note: this can cause inconsistent states in the application. | |
| 2882 <p/> | |
| 2883 A lock acquired by calling the called method | |
| 2884 (if it is a <code>synchronized</code> method) | |
| 2885 and locks acquired by entering <code>synchronized</code> | |
| 2886 blocks within the called method are released. | |
| 2887 Note: this does not apply to native locks or | |
| 2888 <code>java.util.concurrent.locks</code> locks. | |
| 2889 <p/> | |
| 2890 Events, such as <eventlink id="MethodExit"></eventlink>, | |
| 2891 are generated as they would be in a normal return. | |
| 2892 <p/> | |
| 2893 The called method must be a non-native Java programming | |
| 2894 language method. | |
| 2895 Forcing return on a thread with only one frame on the | |
| 2896 stack causes the thread to exit when resumed. | |
| 2897 </intro> | |
| 2898 | |
| 2899 <function id="ForceEarlyReturnObject" num="81" since="1.1"> | |
| 2900 <synopsis>Force Early Return - Object</synopsis> | |
| 2901 <description> | |
| 2902 This function can be used to return from a method whose | |
| 2903 result type is <code>Object</code> | |
| 2904 or a subclass of <code>Object</code>. | |
| 2905 </description> | |
| 2906 <origin>new</origin> | |
| 2907 <capabilities> | |
| 2908 <required id="can_force_early_return"></required> | |
| 2909 </capabilities> | |
| 2910 <parameters> | |
| 2911 <param id="thread"> | |
| 2912 <jthread null="current"/> | |
| 2913 <description> | |
| 2914 The thread whose current frame is to return early. | |
| 2915 </description> | |
| 2916 </param> | |
| 2917 <param id="value"> | |
| 2918 <jobject/> | |
| 2919 <description> | |
| 2920 The return value for the called frame. | |
| 2921 An object or <code>NULL</code>. | |
| 2922 </description> | |
| 2923 </param> | |
| 2924 </parameters> | |
| 2925 <errors> | |
| 2926 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2927 Attempted to return early from a frame | |
| 2928 corresponding to a native method. | |
| 2929 Or the implementation is unable to provide | |
| 2930 this functionality on this frame. | |
| 2931 </error> | |
| 2932 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 2933 The result type of the called method is not | |
| 2934 <code>Object</code> or a subclass of <code>Object</code>. | |
| 2935 </error> | |
| 2936 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 2937 The supplied <paramlink id="value"/> is not compatible with the | |
| 2938 result type of the called method. | |
| 2939 </error> | |
| 2940 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 2941 Thread was not the current thread and was not suspended. | |
| 2942 </error> | |
| 2943 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 2944 There are no more frames on the call stack. | |
| 2945 </error> | |
| 2946 </errors> | |
| 2947 </function> | |
| 2948 | |
| 2949 <function id="ForceEarlyReturnInt" num="82" since="1.1"> | |
| 2950 <synopsis>Force Early Return - Int</synopsis> | |
| 2951 <description> | |
| 2952 This function can be used to return from a method whose | |
| 2953 result type is <code>int</code>, <code>short</code>, | |
| 2954 <code>char</code>, <code>byte</code>, or | |
| 2955 <code>boolean</code>. | |
| 2956 </description> | |
| 2957 <origin>new</origin> | |
| 2958 <capabilities> | |
| 2959 <required id="can_force_early_return"></required> | |
| 2960 </capabilities> | |
| 2961 <parameters> | |
| 2962 <param id="thread"> | |
| 2963 <jthread null="current"/> | |
| 2964 <description> | |
| 2965 The thread whose current frame is to return early. | |
| 2966 </description> | |
| 2967 </param> | |
| 2968 <param id="value"> | |
| 2969 <jint/> | |
| 2970 <description> | |
| 2971 The return value for the called frame. | |
| 2972 </description> | |
| 2973 </param> | |
| 2974 </parameters> | |
| 2975 <errors> | |
| 2976 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2977 Attempted to return early from a frame | |
| 2978 corresponding to a native method. | |
| 2979 Or the implementation is unable to provide | |
| 2980 this functionality on this frame. | |
| 2981 </error> | |
| 2982 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 2983 The result type of the called method is not | |
| 2984 <code>int</code>, <code>short</code>, | |
| 2985 <code>char</code>, <code>byte</code>, or | |
| 2986 <code>boolean</code>. | |
| 2987 </error> | |
| 2988 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 2989 Thread was not the current thread and was not suspended. | |
| 2990 </error> | |
| 2991 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 2992 There are no frames on the call stack. | |
| 2993 </error> | |
| 2994 </errors> | |
| 2995 </function> | |
| 2996 | |
| 2997 <function id="ForceEarlyReturnLong" num="83" since="1.1"> | |
| 2998 <synopsis>Force Early Return - Long</synopsis> | |
| 2999 <description> | |
| 3000 This function can be used to return from a method whose | |
| 3001 result type is <code>long</code>. | |
| 3002 </description> | |
| 3003 <origin>new</origin> | |
| 3004 <capabilities> | |
| 3005 <required id="can_force_early_return"></required> | |
| 3006 </capabilities> | |
| 3007 <parameters> | |
| 3008 <param id="thread"> | |
| 3009 <jthread null="current"/> | |
| 3010 <description> | |
| 3011 The thread whose current frame is to return early. | |
| 3012 </description> | |
| 3013 </param> | |
| 3014 <param id="value"> | |
| 3015 <jlong/> | |
| 3016 <description> | |
| 3017 The return value for the called frame. | |
| 3018 </description> | |
| 3019 </param> | |
| 3020 </parameters> | |
| 3021 <errors> | |
| 3022 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3023 Attempted to return early from a frame | |
| 3024 corresponding to a native method. | |
| 3025 Or the implementation is unable to provide | |
| 3026 this functionality on this frame. | |
| 3027 </error> | |
| 3028 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3029 The result type of the called method is not <code>long</code>. | |
| 3030 </error> | |
| 3031 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3032 Thread was not the current thread and was not suspended. | |
| 3033 </error> | |
| 3034 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3035 There are no frames on the call stack. | |
| 3036 </error> | |
| 3037 </errors> | |
| 3038 </function> | |
| 3039 | |
| 3040 <function id="ForceEarlyReturnFloat" num="84" since="1.1"> | |
| 3041 <synopsis>Force Early Return - Float</synopsis> | |
| 3042 <description> | |
| 3043 This function can be used to return from a method whose | |
| 3044 result type is <code>float</code>. | |
| 3045 </description> | |
| 3046 <origin>new</origin> | |
| 3047 <capabilities> | |
| 3048 <required id="can_force_early_return"></required> | |
| 3049 </capabilities> | |
| 3050 <parameters> | |
| 3051 <param id="thread"> | |
| 3052 <jthread null="current"/> | |
| 3053 <description> | |
| 3054 The thread whose current frame is to return early. | |
| 3055 </description> | |
| 3056 </param> | |
| 3057 <param id="value"> | |
| 3058 <jfloat/> | |
| 3059 <description> | |
| 3060 The return value for the called frame. | |
| 3061 </description> | |
| 3062 </param> | |
| 3063 </parameters> | |
| 3064 <errors> | |
| 3065 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3066 Attempted to return early from a frame | |
| 3067 corresponding to a native method. | |
| 3068 Or the implementation is unable to provide | |
| 3069 this functionality on this frame. | |
| 3070 </error> | |
| 3071 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3072 The result type of the called method is not <code>float</code>. | |
| 3073 </error> | |
| 3074 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3075 Thread was not the current thread and was not suspended. | |
| 3076 </error> | |
| 3077 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3078 There are no frames on the call stack. | |
| 3079 </error> | |
| 3080 </errors> | |
| 3081 </function> | |
| 3082 | |
| 3083 <function id="ForceEarlyReturnDouble" num="85" since="1.1"> | |
| 3084 <synopsis>Force Early Return - Double</synopsis> | |
| 3085 <description> | |
| 3086 This function can be used to return from a method whose | |
| 3087 result type is <code>double</code>. | |
| 3088 </description> | |
| 3089 <origin>new</origin> | |
| 3090 <capabilities> | |
| 3091 <required id="can_force_early_return"></required> | |
| 3092 </capabilities> | |
| 3093 <parameters> | |
| 3094 <param id="thread"> | |
| 3095 <jthread null="current"/> | |
| 3096 <description> | |
| 3097 The thread whose current frame is to return early. | |
| 3098 </description> | |
| 3099 </param> | |
| 3100 <param id="value"> | |
| 3101 <jdouble/> | |
| 3102 <description> | |
| 3103 The return value for the called frame. | |
| 3104 </description> | |
| 3105 </param> | |
| 3106 </parameters> | |
| 3107 <errors> | |
| 3108 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3109 Attempted to return early from a frame corresponding to a native method. | |
| 3110 Or the implementation is unable to provide this functionality on this frame. | |
| 3111 </error> | |
| 3112 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3113 The result type of the called method is not <code>double</code>. | |
| 3114 </error> | |
| 3115 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3116 Thread was not the current thread and was not suspended. | |
| 3117 </error> | |
| 3118 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3119 There are no frames on the call stack. | |
| 3120 </error> | |
| 3121 </errors> | |
| 3122 </function> | |
| 3123 | |
| 3124 <function id="ForceEarlyReturnVoid" num="86" since="1.1"> | |
| 3125 <synopsis>Force Early Return - Void</synopsis> | |
| 3126 <description> | |
| 3127 This function can be used to return from a method with no result type. | |
| 3128 That is, the called method must be declared <code>void</code>. | |
| 3129 </description> | |
| 3130 <origin>new</origin> | |
| 3131 <capabilities> | |
| 3132 <required id="can_force_early_return"></required> | |
| 3133 </capabilities> | |
| 3134 <parameters> | |
| 3135 <param id="thread"> | |
| 3136 <jthread null="current"/> | |
| 3137 <description> | |
| 3138 The thread whose current frame is to return early. | |
| 3139 </description> | |
| 3140 </param> | |
| 3141 </parameters> | |
| 3142 <errors> | |
| 3143 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3144 Attempted to return early from a frame | |
| 3145 corresponding to a native method. | |
| 3146 Or the implementation is unable to provide | |
| 3147 this functionality on this frame. | |
| 3148 </error> | |
| 3149 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3150 The called method has a result type. | |
| 3151 </error> | |
| 3152 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3153 Thread was not the current thread and was not suspended. | |
| 3154 </error> | |
| 3155 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3156 There are no frames on the call stack. | |
| 3157 </error> | |
| 3158 </errors> | |
| 3159 </function> | |
| 3160 | |
| 3161 </category> | |
| 3162 | |
| 3163 <category id="Heap" label="Heap"> | |
| 3164 <intro> | |
| 3165 These functions are used to analyze the heap. | |
| 3166 Functionality includes the ability to view the objects in the | |
| 3167 heap and to tag these objects. | |
| 3168 </intro> | |
| 3169 | |
| 3170 <intro id="objectTags" label="Object Tags"> | |
| 3171 A <i>tag</i> is a value associated with an object. | |
| 3172 Tags are explicitly set by the agent using the | |
| 3173 <functionlink id="SetTag"></functionlink> function or by | |
| 3174 callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>. | |
| 3175 <p/> | |
| 3176 Tags are local to the environment; that is, the tags of one | |
| 3177 environment are not visible in another. | |
| 3178 <p/> | |
| 3179 Tags are <code>jlong</code> values which can be used | |
| 3180 simply to mark an object or to store a pointer to more detailed | |
| 3181 information. Objects which have not been tagged have a | |
| 3182 tag of zero. | |
| 3183 Setting a tag to zero makes the object untagged. | |
| 3184 </intro> | |
| 3185 | |
| 3186 <intro id="heapCallbacks" label="Heap Callback Functions"> | |
| 3187 Heap functions which iterate through the heap and recursively | |
| 3188 follow object references use agent supplied callback functions | |
| 3189 to deliver the information. | |
| 3190 <p/> | |
| 3191 These heap callback functions must adhere to the following restrictions -- | |
| 3192 These callbacks must not use JNI functions. | |
| 3193 These callbacks must not use <jvmti/> functions except | |
| 3194 <i>callback safe</i> functions which | |
| 3195 specifically allow such use (see the raw monitor, memory management, | |
| 3196 and environment local storage functions). | |
| 3197 <p/> | |
| 3198 An implementation may invoke a callback on an internal thread or | |
| 3199 the thread which called the iteration function. | |
| 3200 Heap callbacks are single threaded -- no more than one callback will | |
| 3201 be invoked at a time. | |
| 3202 <p/> | |
| 3203 The Heap Filter Flags can be used to prevent reporting | |
| 3204 based on the tag status of an object or its class. | |
| 3205 If no flags are set (the <code>jint</code> is zero), objects | |
| 3206 will not be filtered out. | |
| 3207 | |
| 3208 <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits"> | |
| 3209 <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4"> | |
| 3210 Filter out tagged objects. Objects which are tagged are not included. | |
| 3211 </constant> | |
| 3212 <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8"> | |
| 3213 Filter out untagged objects. Objects which are not tagged are not included. | |
| 3214 </constant> | |
| 3215 <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10"> | |
| 3216 Filter out objects with tagged classes. Objects whose class is tagged are not included. | |
| 3217 </constant> | |
| 3218 <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20"> | |
| 3219 Filter out objects with untagged classes. Objects whose class is not tagged are not included. | |
| 3220 </constant> | |
| 3221 </constants> | |
| 3222 | |
| 3223 <p/> | |
| 3224 The Heap Visit Control Flags are returned by the heap callbacks | |
| 3225 and can be used to abort the iteration. For the | |
| 3226 <functionlink id="jvmtiHeapReferenceCallback">Heap | |
| 3227 Reference Callback</functionlink>, it can also be used | |
| 3228 to prune the graph of traversed references | |
| 3229 (<code>JVMTI_VISIT_OBJECTS</code> is not set). | |
| 3230 | |
| 3231 <constants id="jvmtiHeapVisitControl" | |
| 3232 label="Heap Visit Control Flags" | |
| 3233 kind="bits" | |
| 3234 since="1.1"> | |
| 3235 <constant id="JVMTI_VISIT_OBJECTS" num="0x100"> | |
| 3236 If we are visiting an object and if this callback | |
| 3237 was initiated by <functionlink id="FollowReferences"/>, | |
| 3238 traverse the references of this object. | |
| 3239 Otherwise ignored. | |
| 3240 </constant> | |
| 3241 <constant id="JVMTI_VISIT_ABORT" num="0x8000"> | |
| 3242 Abort the iteration. Ignore all other bits. | |
| 3243 </constant> | |
| 3244 </constants> | |
| 3245 | |
| 3246 <p/> | |
| 3247 The Heap Reference Enumeration is provided by the | |
| 3248 <functionlink id="jvmtiHeapReferenceCallback">Heap | |
| 3249 Reference Callback</functionlink> and | |
| 3250 <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field | |
| 3251 Callback</functionlink> to | |
| 3252 describe the kind of reference | |
| 3253 being reported. | |
| 3254 | |
| 3255 <constants id="jvmtiHeapReferenceKind" | |
| 3256 label="Heap Reference Enumeration" | |
| 3257 kind="enum" | |
| 3258 since="1.1"> | |
| 3259 <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1"> | |
| 3260 Reference from an object to its class. | |
| 3261 </constant> | |
| 3262 <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2"> | |
| 3263 Reference from an object to the value of one of its instance fields. | |
| 3264 </constant> | |
| 3265 <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3"> | |
| 3266 Reference from an array to one of its elements. | |
| 3267 </constant> | |
| 3268 <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4"> | |
| 3269 Reference from a class to its class loader. | |
| 3270 </constant> | |
| 3271 <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5"> | |
| 3272 Reference from a class to its signers array. | |
| 3273 </constant> | |
| 3274 <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6"> | |
| 3275 Reference from a class to its protection domain. | |
| 3276 </constant> | |
| 3277 <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7"> | |
| 3278 Reference from a class to one of its interfaces. | |
| 3279 Note: interfaces are defined via a constant pool reference, | |
| 3280 so the referenced interfaces may also be reported with a | |
| 3281 <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. | |
| 3282 </constant> | |
| 3283 <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8"> | |
| 3284 Reference from a class to the value of one of its static fields. | |
| 3285 </constant> | |
| 3286 <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9"> | |
| 3287 Reference from a class to a resolved entry in the constant pool. | |
| 3288 </constant> | |
| 3289 <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10"> | |
| 3290 Reference from a class to its superclass. | |
| 3291 A callback is bot sent if the superclass is <code>java.lang.Object</code>. | |
| 3292 Note: loaded classes define superclasses via a constant pool | |
| 3293 reference, so the referenced superclass may also be reported with | |
| 3294 a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. | |
| 3295 </constant> | |
| 3296 <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21"> | |
| 3297 Heap root reference: JNI global reference. | |
| 3298 </constant> | |
| 3299 <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22"> | |
| 3300 Heap root reference: System class. | |
| 3301 </constant> | |
| 3302 <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23"> | |
| 3303 Heap root reference: monitor. | |
| 3304 </constant> | |
| 3305 <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24"> | |
| 3306 Heap root reference: local variable on the stack. | |
| 3307 </constant> | |
| 3308 <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25"> | |
| 3309 Heap root reference: JNI local reference. | |
| 3310 </constant> | |
| 3311 <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26"> | |
| 3312 Heap root reference: Thread. | |
| 3313 </constant> | |
| 3314 <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27"> | |
| 3315 Heap root reference: other heap root reference. | |
| 3316 </constant> | |
| 3317 </constants> | |
| 3318 | |
| 3319 <p/> | |
| 3320 Definitions for the single character type descriptors of | |
| 3321 primitive types. | |
| 3322 | |
| 3323 <constants id="jvmtiPrimitiveType" | |
| 3324 label="Primitive Type Enumeration" | |
| 3325 kind="enum" | |
| 3326 since="1.1"> | |
| 3327 <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90"> | |
| 3328 'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code> | |
| 3329 </constant> | |
| 3330 <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66"> | |
| 3331 'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code> | |
| 3332 </constant> | |
| 3333 <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67"> | |
| 3334 'C' - Java programming language <code>char</code> - JNI <code>jchar</code> | |
| 3335 </constant> | |
| 3336 <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83"> | |
| 3337 'S' - Java programming language <code>short</code> - JNI <code>jshort</code> | |
| 3338 </constant> | |
| 3339 <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73"> | |
| 3340 'I' - Java programming language <code>int</code> - JNI <code>jint</code> | |
| 3341 </constant> | |
| 3342 <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74"> | |
| 3343 'J' - Java programming language <code>long</code> - JNI <code>jlong</code> | |
| 3344 </constant> | |
| 3345 <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70"> | |
| 3346 'F' - Java programming language <code>float</code> - JNI <code>jfloat</code> | |
| 3347 </constant> | |
| 3348 <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68"> | |
| 3349 'D' - Java programming language <code>double</code> - JNI <code>jdouble</code> | |
| 3350 </constant> | |
| 3351 </constants> | |
| 3352 </intro> | |
| 3353 | |
| 3354 <typedef id="jvmtiHeapReferenceInfoField" | |
| 3355 label="Reference information structure for Field references" | |
| 3356 since="1.1"> | |
| 3357 <description> | |
| 3358 Reference information returned for | |
| 3359 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and | |
| 3360 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. | |
| 3361 </description> | |
| 3362 <field id="index"> | |
| 3363 <jint/> | |
| 3364 <description> | |
| 3365 For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the | |
| 3366 referrer object is not a class or an inteface. | |
| 3367 In this case, <code>index</code> is the index of the field | |
| 3368 in the class of the referrer object. | |
| 3369 This class is referred to below as <i>C</i>. | |
| 3370 <p/> | |
| 3371 For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, | |
| 3372 the referrer object is a class (referred to below as <i>C</i>) | |
| 3373 or an interface (referred to below as <i>I</i>). | |
| 3374 In this case, <code>index</code> is the index of the field in | |
| 3375 that class or interface. | |
| 3376 <p/> | |
| 3377 If the referrer object is not an interface, then the field | |
| 3378 indices are determined as follows: | |
| 3379 <ul> | |
| 3380 <li>make a list of all the fields in <i>C</i> and its | |
| 3381 superclasses, starting with all the fields in | |
| 3382 <code>java.lang.Object</code> and ending with all the | |
| 3383 fields in <i>C</i>.</li> | |
| 3384 <li>Within this list, put | |
| 3385 the fields for a given class in the order returned by | |
| 3386 <functionlink id="GetClassFields"/>.</li> | |
| 3387 <li>Assign the fields in this list indices | |
| 3388 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> | |
| 3389 is the count of the fields in all the interfaces | |
| 3390 implemented by <i>C</i>. | |
| 3391 Note that <i>C</i> implements all interfaces | |
| 3392 directly implemented by its superclasses; as well | |
| 3393 as all superinterfaces of these interfaces.</li> | |
| 3394 </ul> | |
| 3395 If the referrer object is an interface, then the field | |
| 3396 indices are determined as follows: | |
| 3397 <ul> | |
| 3398 <li>make a list of the fields directly declared in | |
| 3399 <i>I</i>.</li> | |
| 3400 <li>Within this list, put | |
| 3401 the fields in the order returned by | |
| 3402 <functionlink id="GetClassFields"/>.</li> | |
| 3403 <li>Assign the fields in this list indices | |
| 3404 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> | |
| 3405 is the count of the fields in all the superinterfaces | |
| 3406 of <i>I</i>.</li> | |
| 3407 </ul> | |
| 3408 All fields are included in this computation, regardless of | |
| 3409 field modifier (static, public, private, etc). | |
| 3410 <p/> | |
| 3411 For example, given the following classes and interfaces: | |
| 3412 <example> | |
| 3413 interface I0 { | |
| 3414 int p = 0; | |
| 3415 } | |
| 3416 | |
| 3417 interface I1 extends I0 { | |
| 3418 int x = 1; | |
| 3419 } | |
| 3420 | |
| 3421 interface I2 extends I0 { | |
| 3422 int y = 2; | |
| 3423 } | |
| 3424 | |
| 3425 class C1 implements I1 { | |
| 3426 public static int a = 3; | |
| 3427 private int b = 4; | |
| 3428 } | |
| 3429 | |
| 3430 class C2 extends C1 implements I2 { | |
| 3431 static int q = 5; | |
| 3432 final int r = 6; | |
| 3433 } | |
| 3434 </example> | |
| 3435 Assume that <functionlink id="GetClassFields"/> called on | |
| 3436 <code>C1</code> returns the fields of <code>C1</code> in the | |
| 3437 order: a, b; and that the fields of <code>C2</code> are | |
| 3438 returned in the order: q, r. | |
| 3439 An instance of class <code>C1</code> will have the | |
| 3440 following field indices: | |
| 3441 <dl><dd><table> | |
| 3442 <tr> | |
| 3443 <td> | |
| 3444 a | |
| 3445 </td> | |
| 3446 <td> | |
| 3447 2 | |
| 3448 </td> | |
| 3449 <td align="left"> | |
| 3450 The count of the fields in the interfaces | |
| 3451 implemented by <code>C1</code> is two (<i>n</i>=2): | |
| 3452 <code>p</code> of <code>I0</code> | |
| 3453 and <code>x</code> of <code>I1</code>. | |
| 3454 </td> | |
| 3455 </tr> | |
| 3456 <tr> | |
| 3457 <td> | |
| 3458 b | |
| 3459 </td> | |
| 3460 <td> | |
| 3461 3 | |
| 3462 </td> | |
| 3463 <td align="left"> | |
| 3464 the subsequent index. | |
| 3465 </td> | |
| 3466 </tr> | |
| 3467 </table></dd></dl> | |
| 3468 The class <code>C1</code> will have the same field indices. | |
| 3469 <p/> | |
| 3470 An instance of class <code>C2</code> will have the | |
| 3471 following field indices: | |
| 3472 <dl><dd><table> | |
| 3473 <tr> | |
| 3474 <td> | |
| 3475 a | |
| 3476 </td> | |
| 3477 <td> | |
| 3478 3 | |
| 3479 </td> | |
| 3480 <td align="left"> | |
| 3481 The count of the fields in the interfaces | |
| 3482 implemented by <code>C2</code> is three (<i>n</i>=3): | |
| 3483 <code>p</code> of <code>I0</code>, | |
| 3484 <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code> | |
| 3485 (an interface of <code>C2</code>). Note that the field <code>p</code> | |
| 3486 of <code>I0</code> is only included once. | |
| 3487 </td> | |
| 3488 </tr> | |
| 3489 <tr> | |
| 3490 <td> | |
| 3491 b | |
| 3492 </td> | |
| 3493 <td> | |
| 3494 4 | |
| 3495 </td> | |
| 3496 <td align="left"> | |
| 3497 the subsequent index to "a". | |
| 3498 </td> | |
| 3499 </tr> | |
| 3500 <tr> | |
| 3501 <td> | |
| 3502 q | |
| 3503 </td> | |
| 3504 <td> | |
| 3505 5 | |
| 3506 </td> | |
| 3507 <td align="left"> | |
| 3508 the subsequent index to "b". | |
| 3509 </td> | |
| 3510 </tr> | |
| 3511 <tr> | |
| 3512 <td> | |
| 3513 r | |
| 3514 </td> | |
| 3515 <td> | |
| 3516 6 | |
| 3517 </td> | |
| 3518 <td align="left"> | |
| 3519 the subsequent index to "q". | |
| 3520 </td> | |
| 3521 </tr> | |
| 3522 </table></dd></dl> | |
| 3523 The class <code>C2</code> will have the same field indices. | |
| 3524 Note that a field may have a different index depending on the | |
| 3525 object that is viewing it -- for example field "a" above. | |
| 3526 Note also: not all field indices may be visible from the | |
| 3527 callbacks, but all indices are shown for illustrative purposes. | |
| 3528 <p/> | |
| 3529 The interface <code>I1</code> will have the | |
| 3530 following field indices: | |
| 3531 <dl><dd><table> | |
| 3532 <tr> | |
| 3533 <td> | |
| 3534 x | |
| 3535 </td> | |
| 3536 <td> | |
| 3537 1 | |
| 3538 </td> | |
| 3539 <td align="left"> | |
| 3540 The count of the fields in the superinterfaces | |
| 3541 of <code>I1</code> is one (<i>n</i>=1): | |
| 3542 <code>p</code> of <code>I0</code>. | |
| 3543 </td> | |
| 3544 </tr> | |
| 3545 </table></dd></dl> | |
| 3546 </description> | |
| 3547 </field> | |
| 3548 </typedef> | |
| 3549 | |
| 3550 <typedef id="jvmtiHeapReferenceInfoArray" | |
| 3551 label="Reference information structure for Array references" | |
| 3552 since="1.1"> | |
| 3553 <description> | |
| 3554 Reference information returned for | |
| 3555 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. | |
| 3556 </description> | |
| 3557 <field id="index"> | |
| 3558 <jint/> | |
| 3559 <description> | |
| 3560 The array index. | |
| 3561 </description> | |
| 3562 </field> | |
| 3563 </typedef> | |
| 3564 | |
| 3565 <typedef id="jvmtiHeapReferenceInfoConstantPool" | |
| 3566 label="Reference information structure for Constant Pool references" | |
| 3567 since="1.1"> | |
| 3568 <description> | |
| 3569 Reference information returned for | |
| 3570 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. | |
| 3571 </description> | |
| 3572 <field id="index"> | |
| 3573 <jint/> | |
| 3574 <description> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
3575 The index into the constant pool of the class. See the description in |
|
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
3576 <vmspec chapter="4.4"/>. |
| 0 | 3577 </description> |
| 3578 </field> | |
| 3579 </typedef> | |
| 3580 | |
| 3581 <typedef id="jvmtiHeapReferenceInfoStackLocal" | |
| 3582 label="Reference information structure for Local Variable references" | |
| 3583 since="1.1"> | |
| 3584 <description> | |
| 3585 Reference information returned for | |
| 3586 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. | |
| 3587 </description> | |
| 3588 <field id="thread_tag"> | |
| 3589 <jlong/> | |
| 3590 <description> | |
| 3591 The tag of the thread corresponding to this stack, zero if not tagged. | |
| 3592 </description> | |
| 3593 </field> | |
| 3594 <field id="thread_id"> | |
| 3595 <jlong/> | |
| 3596 <description> | |
| 3597 The unique thread ID of the thread corresponding to this stack. | |
| 3598 </description> | |
| 3599 </field> | |
| 3600 <field id="depth"> | |
| 3601 <jint/> | |
| 3602 <description> | |
| 3603 The depth of the frame. | |
| 3604 </description> | |
| 3605 </field> | |
| 3606 <field id="method"> | |
| 3607 <jmethodID/> | |
| 3608 <description> | |
| 3609 The method executing in this frame. | |
| 3610 </description> | |
| 3611 </field> | |
| 3612 <field id="location"> | |
| 3613 <jlocation/> | |
| 3614 <description> | |
| 3615 The currently executing location in this frame. | |
| 3616 </description> | |
| 3617 </field> | |
| 3618 <field id="slot"> | |
| 3619 <jint/> | |
| 3620 <description> | |
| 3621 The slot number of the local variable. | |
| 3622 </description> | |
| 3623 </field> | |
| 3624 </typedef> | |
| 3625 | |
| 3626 <typedef id="jvmtiHeapReferenceInfoJniLocal" | |
| 3627 label="Reference information structure for JNI local references" | |
| 3628 since="1.1"> | |
| 3629 <description> | |
| 3630 Reference information returned for | |
| 3631 <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. | |
| 3632 </description> | |
| 3633 <field id="thread_tag"> | |
| 3634 <jlong/> | |
| 3635 <description> | |
| 3636 The tag of the thread corresponding to this stack, zero if not tagged. | |
| 3637 </description> | |
| 3638 </field> | |
| 3639 <field id="thread_id"> | |
| 3640 <jlong/> | |
| 3641 <description> | |
| 3642 The unique thread ID of the thread corresponding to this stack. | |
| 3643 </description> | |
| 3644 </field> | |
| 3645 <field id="depth"> | |
| 3646 <jint/> | |
| 3647 <description> | |
| 3648 The depth of the frame. | |
| 3649 </description> | |
| 3650 </field> | |
| 3651 <field id="method"> | |
| 3652 <jmethodID/> | |
| 3653 <description> | |
| 3654 The method executing in this frame. | |
| 3655 </description> | |
| 3656 </field> | |
| 3657 </typedef> | |
| 3658 | |
| 3659 <typedef id="jvmtiHeapReferenceInfoReserved" | |
| 3660 label="Reference information structure for Other references" | |
| 3661 since="1.1"> | |
| 3662 <description> | |
| 3663 Reference information returned for other references. | |
| 3664 </description> | |
| 3665 <field id="reserved1"> | |
| 3666 <jlong/> | |
| 3667 <description> | |
| 3668 reserved for future use. | |
| 3669 </description> | |
| 3670 </field> | |
| 3671 <field id="reserved2"> | |
| 3672 <jlong/> | |
| 3673 <description> | |
| 3674 reserved for future use. | |
| 3675 </description> | |
| 3676 </field> | |
| 3677 <field id="reserved3"> | |
| 3678 <jlong/> | |
| 3679 <description> | |
| 3680 reserved for future use. | |
| 3681 </description> | |
| 3682 </field> | |
| 3683 <field id="reserved4"> | |
| 3684 <jlong/> | |
| 3685 <description> | |
| 3686 reserved for future use. | |
| 3687 </description> | |
| 3688 </field> | |
| 3689 <field id="reserved5"> | |
| 3690 <jlong/> | |
| 3691 <description> | |
| 3692 reserved for future use. | |
| 3693 </description> | |
| 3694 </field> | |
| 3695 <field id="reserved6"> | |
| 3696 <jlong/> | |
| 3697 <description> | |
| 3698 reserved for future use. | |
| 3699 </description> | |
| 3700 </field> | |
| 3701 <field id="reserved7"> | |
| 3702 <jlong/> | |
| 3703 <description> | |
| 3704 reserved for future use. | |
| 3705 </description> | |
| 3706 </field> | |
| 3707 <field id="reserved8"> | |
| 3708 <jlong/> | |
| 3709 <description> | |
| 3710 reserved for future use. | |
| 3711 </description> | |
| 3712 </field> | |
| 3713 </typedef> | |
| 3714 | |
| 3715 <uniontypedef id="jvmtiHeapReferenceInfo" | |
| 3716 label="Reference information structure" | |
| 3717 since="1.1"> | |
| 3718 <description> | |
| 3719 The information returned about referrers. | |
| 3720 Represented as a union of the various kinds of reference information. | |
| 3721 </description> | |
| 3722 <field id="field"> | |
| 3723 <struct>jvmtiHeapReferenceInfoField</struct> | |
| 3724 <description> | |
| 3725 The referrer information for | |
| 3726 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> | |
| 3727 and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. | |
| 3728 </description> | |
| 3729 </field> | |
| 3730 <field id="array"> | |
| 3731 <struct>jvmtiHeapReferenceInfoArray</struct> | |
| 3732 <description> | |
| 3733 The referrer information for | |
| 3734 For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. | |
| 3735 </description> | |
| 3736 </field> | |
| 3737 <field id="constant_pool"> | |
| 3738 <struct>jvmtiHeapReferenceInfoConstantPool</struct> | |
| 3739 <description> | |
| 3740 The referrer information for | |
| 3741 For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. | |
| 3742 </description> | |
| 3743 </field> | |
| 3744 <field id="stack_local"> | |
| 3745 <struct>jvmtiHeapReferenceInfoStackLocal</struct> | |
| 3746 <description> | |
| 3747 The referrer information for | |
| 3748 For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. | |
| 3749 </description> | |
| 3750 </field> | |
| 3751 <field id="jni_local"> | |
| 3752 <struct>jvmtiHeapReferenceInfoJniLocal</struct> | |
| 3753 <description> | |
| 3754 The referrer information for | |
| 3755 For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. | |
| 3756 </description> | |
| 3757 </field> | |
| 3758 <field id="other"> | |
| 3759 <struct>jvmtiHeapReferenceInfoReserved</struct> | |
| 3760 <description> | |
| 3761 reserved for future use. | |
| 3762 </description> | |
| 3763 </field> | |
| 3764 </uniontypedef> | |
| 3765 | |
| 3766 <typedef id="jvmtiHeapCallbacks" | |
| 3767 label="Heap callback function structure" | |
| 3768 since="1.1"> | |
| 3769 <field id="heap_iteration_callback"> | |
| 3770 <ptrtype> | |
| 3771 <struct>jvmtiHeapIterationCallback</struct> | |
| 3772 </ptrtype> | |
| 3773 <description> | |
| 3774 The callback to be called to describe an | |
| 3775 object in the heap. Used by the | |
| 3776 <functionlink id="IterateThroughHeap"/> function, ignored by the | |
| 3777 <functionlink id="FollowReferences"/> function. | |
| 3778 </description> | |
| 3779 </field> | |
| 3780 <field id="heap_reference_callback"> | |
| 3781 <ptrtype> | |
| 3782 <struct>jvmtiHeapReferenceCallback</struct> | |
| 3783 </ptrtype> | |
| 3784 <description> | |
| 3785 The callback to be called to describe an | |
| 3786 object reference. Used by the | |
| 3787 <functionlink id="FollowReferences"/> function, ignored by the | |
| 3788 <functionlink id="IterateThroughHeap"/> function. | |
| 3789 </description> | |
| 3790 </field> | |
| 3791 <field id="primitive_field_callback"> | |
| 3792 <ptrtype> | |
| 3793 <struct>jvmtiPrimitiveFieldCallback</struct> | |
| 3794 </ptrtype> | |
| 3795 <description> | |
| 3796 The callback to be called to describe a | |
| 3797 primitive field. | |
| 3798 </description> | |
| 3799 </field> | |
| 3800 <field id="array_primitive_value_callback"> | |
| 3801 <ptrtype> | |
| 3802 <struct>jvmtiArrayPrimitiveValueCallback</struct> | |
| 3803 </ptrtype> | |
| 3804 <description> | |
| 3805 The callback to be called to describe an | |
| 3806 array of primitive values. | |
| 3807 </description> | |
| 3808 </field> | |
| 3809 <field id="string_primitive_value_callback"> | |
| 3810 <ptrtype> | |
| 3811 <struct>jvmtiStringPrimitiveValueCallback</struct> | |
| 3812 </ptrtype> | |
| 3813 <description> | |
| 3814 The callback to be called to describe a String value. | |
| 3815 </description> | |
| 3816 </field> | |
| 3817 <field id="reserved5"> | |
| 3818 <ptrtype> | |
| 3819 <struct>jvmtiReservedCallback</struct> | |
| 3820 </ptrtype> | |
| 3821 <description> | |
| 3822 Reserved for future use.. | |
| 3823 </description> | |
| 3824 </field> | |
| 3825 <field id="reserved6"> | |
| 3826 <ptrtype> | |
| 3827 <struct>jvmtiReservedCallback</struct> | |
| 3828 </ptrtype> | |
| 3829 <description> | |
| 3830 Reserved for future use.. | |
| 3831 </description> | |
| 3832 </field> | |
| 3833 <field id="reserved7"> | |
| 3834 <ptrtype> | |
| 3835 <struct>jvmtiReservedCallback</struct> | |
| 3836 </ptrtype> | |
| 3837 <description> | |
| 3838 Reserved for future use.. | |
| 3839 </description> | |
| 3840 </field> | |
| 3841 <field id="reserved8"> | |
| 3842 <ptrtype> | |
| 3843 <struct>jvmtiReservedCallback</struct> | |
| 3844 </ptrtype> | |
| 3845 <description> | |
| 3846 Reserved for future use.. | |
| 3847 </description> | |
| 3848 </field> | |
| 3849 <field id="reserved9"> | |
| 3850 <ptrtype> | |
| 3851 <struct>jvmtiReservedCallback</struct> | |
| 3852 </ptrtype> | |
| 3853 <description> | |
| 3854 Reserved for future use.. | |
| 3855 </description> | |
| 3856 </field> | |
| 3857 <field id="reserved10"> | |
| 3858 <ptrtype> | |
| 3859 <struct>jvmtiReservedCallback</struct> | |
| 3860 </ptrtype> | |
| 3861 <description> | |
| 3862 Reserved for future use.. | |
| 3863 </description> | |
| 3864 </field> | |
| 3865 <field id="reserved11"> | |
| 3866 <ptrtype> | |
| 3867 <struct>jvmtiReservedCallback</struct> | |
| 3868 </ptrtype> | |
| 3869 <description> | |
| 3870 Reserved for future use.. | |
| 3871 </description> | |
| 3872 </field> | |
| 3873 <field id="reserved12"> | |
| 3874 <ptrtype> | |
| 3875 <struct>jvmtiReservedCallback</struct> | |
| 3876 </ptrtype> | |
| 3877 <description> | |
| 3878 Reserved for future use.. | |
| 3879 </description> | |
| 3880 </field> | |
| 3881 <field id="reserved13"> | |
| 3882 <ptrtype> | |
| 3883 <struct>jvmtiReservedCallback</struct> | |
| 3884 </ptrtype> | |
| 3885 <description> | |
| 3886 Reserved for future use.. | |
| 3887 </description> | |
| 3888 </field> | |
| 3889 <field id="reserved14"> | |
| 3890 <ptrtype> | |
| 3891 <struct>jvmtiReservedCallback</struct> | |
| 3892 </ptrtype> | |
| 3893 <description> | |
| 3894 Reserved for future use.. | |
| 3895 </description> | |
| 3896 </field> | |
| 3897 <field id="reserved15"> | |
| 3898 <ptrtype> | |
| 3899 <struct>jvmtiReservedCallback</struct> | |
| 3900 </ptrtype> | |
| 3901 <description> | |
| 3902 Reserved for future use.. | |
| 3903 </description> | |
| 3904 </field> | |
| 3905 </typedef> | |
| 3906 | |
| 3907 | |
| 3908 <intro> | |
| 3909 <rationale> | |
| 3910 The heap dumping functionality (below) uses a callback | |
| 3911 for each object. While it would seem that a buffered approach | |
| 3912 would provide better throughput, tests do | |
| 3913 not show this to be the case--possibly due to locality of | |
| 3914 memory reference or array access overhead. | |
| 3915 </rationale> | |
| 3916 | |
| 3917 <issue> | |
| 3918 Still under investigation as to if java.lang.ref references | |
| 3919 are reported as a different type of reference. | |
| 3920 </issue> | |
| 3921 | |
| 3922 <issue> | |
| 3923 Should or can an indication of the cost or relative cost of | |
| 3924 these operations be included? | |
| 3925 </issue> | |
| 3926 | |
| 3927 </intro> | |
| 3928 | |
| 3929 <callback id="jvmtiHeapIterationCallback" since="1.1"> | |
| 3930 <jint/> | |
| 3931 <synopsis>Heap Iteration Callback</synopsis> | |
| 3932 <description> | |
| 3933 Agent supplied callback function. | |
| 3934 Describes (but does not pass in) an object in the heap. | |
| 3935 <p/> | |
| 3936 This function should return a bit vector of the desired | |
| 3937 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 3938 This will determine if the entire iteration should be aborted | |
| 3939 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 3940 <p/> | |
| 3941 See the <internallink id="heapCallbacks">heap callback | |
| 3942 function restrictions</internallink>. | |
| 3943 </description> | |
| 3944 <parameters> | |
| 3945 <param id="class_tag"> | |
| 3946 <jlong/> | |
| 3947 <description> | |
| 3948 The tag of the class of object (zero if the class is not tagged). | |
| 3949 If the object represents a runtime class, | |
| 3950 the <code>class_tag</code> is the tag | |
| 3951 associated with <code>java.lang.Class</code> | |
| 3952 (zero if <code>java.lang.Class</code> is not tagged). | |
| 3953 </description> | |
| 3954 </param> | |
| 3955 <param id="size"> | |
| 3956 <jlong/> | |
| 3957 <description> | |
| 3958 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 3959 </description> | |
| 3960 </param> | |
| 3961 <param id="tag_ptr"> | |
| 3962 <outptr><jlong/></outptr> | |
| 3963 <description> | |
| 3964 The object tag value, or zero if the object is not tagged. | |
| 3965 To set the tag value to be associated with the object | |
| 3966 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 3967 </description> | |
| 3968 </param> | |
| 3969 <param id="length"> | |
| 3970 <jint/> | |
| 3971 <description> | |
| 3972 If this object is an array, the length of the array. Otherwise negative one (-1). | |
| 3973 </description> | |
| 3974 </param> | |
| 3975 <param id="user_data"> | |
| 3976 <outptr><void/></outptr> | |
| 3977 <description> | |
| 3978 The user supplied data that was passed into the iteration function. | |
| 3979 </description> | |
| 3980 </param> | |
| 3981 </parameters> | |
| 3982 </callback> | |
| 3983 | |
| 3984 <callback id="jvmtiHeapReferenceCallback" since="1.1"> | |
| 3985 <jint/> | |
| 3986 <synopsis>Heap Reference Callback</synopsis> | |
| 3987 <description> | |
| 3988 Agent supplied callback function. | |
| 3989 Describes a reference from an object or the VM (the referrer) to another object | |
| 3990 (the referree) or a heap root to a referree. | |
| 3991 <p/> | |
| 3992 This function should return a bit vector of the desired | |
| 3993 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 3994 This will determine if the objects referenced by the referree | |
| 3995 should be visited or if the entire iteration should be aborted. | |
| 3996 <p/> | |
| 3997 See the <internallink id="heapCallbacks">heap callback | |
| 3998 function restrictions</internallink>. | |
| 3999 </description> | |
| 4000 <parameters> | |
| 4001 <param id="reference_kind"> | |
| 4002 <enum>jvmtiHeapReferenceKind</enum> | |
| 4003 <description> | |
| 4004 The kind of reference. | |
| 4005 </description> | |
| 4006 </param> | |
| 4007 <param id="reference_info"> | |
| 4008 <inptr> | |
| 4009 <struct>jvmtiHeapReferenceInfo</struct> | |
| 4010 </inptr> | |
| 4011 <description> | |
| 4012 Details about the reference. | |
| 6919 | 4013 Set when the <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> is |
| 0 | 4014 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, |
| 4015 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, | |
| 4016 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>, | |
| 4017 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>, | |
| 4018 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>, | |
| 4019 or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>. | |
| 4020 Otherwise <code>NULL</code>. | |
| 4021 </description> | |
| 4022 </param> | |
| 4023 <param id="class_tag"> | |
| 4024 <jlong/> | |
| 4025 <description> | |
| 4026 The tag of the class of referree object (zero if the class is not tagged). | |
| 4027 If the referree object represents a runtime class, | |
| 4028 the <code>class_tag</code> is the tag | |
| 4029 associated with <code>java.lang.Class</code> | |
| 4030 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4031 </description> | |
| 4032 </param> | |
| 4033 <param id="referrer_class_tag"> | |
| 4034 <jlong/> | |
| 4035 <description> | |
| 4036 The tag of the class of the referrer object (zero if the class is not tagged | |
| 4037 or the referree is a heap root). If the referrer object represents a runtime | |
| 4038 class, the <code>referrer_class_tag</code> is the tag associated with | |
| 4039 the <code>java.lang.Class</code> | |
| 4040 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4041 </description> | |
| 4042 </param> | |
| 4043 <param id="size"> | |
| 4044 <jlong/> | |
| 4045 <description> | |
| 4046 Size of the referree object (in bytes). | |
| 4047 See <functionlink id="GetObjectSize"/>. | |
| 4048 </description> | |
| 4049 </param> | |
| 4050 <param id="tag_ptr"> | |
| 4051 <outptr><jlong/></outptr> | |
| 4052 <description> | |
| 4053 Points to the referree object tag value, or zero if the object is not | |
| 4054 tagged. | |
| 4055 To set the tag value to be associated with the object | |
| 4056 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4057 </description> | |
| 4058 </param> | |
| 4059 <param id="referrer_tag_ptr"> | |
| 4060 <outptr><jlong/></outptr> | |
| 4061 <description> | |
| 4062 Points to the tag of the referrer object, or | |
| 4063 points to the zero if the referrer | |
| 4064 object is not tagged. | |
| 4065 <code>NULL</code> if the referrer in not an object (that is, | |
| 4066 this callback is reporting a heap root). | |
| 4067 To set the tag value to be associated with the referrer object | |
| 4068 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4069 If this callback is reporting a reference from an object to itself, | |
| 4070 <code>referrer_tag_ptr == tag_ptr</code>. | |
| 4071 </description> | |
| 4072 </param> | |
| 4073 <param id="length"> | |
| 4074 <jint/> | |
| 4075 <description> | |
| 4076 If this object is an array, the length of the array. Otherwise negative one (-1). | |
| 4077 </description> | |
| 4078 </param> | |
| 4079 <param id="user_data"> | |
| 4080 <outptr><void/></outptr> | |
| 4081 <description> | |
| 4082 The user supplied data that was passed into the iteration function. | |
| 4083 </description> | |
| 4084 </param> | |
| 4085 </parameters> | |
| 4086 </callback> | |
| 4087 | |
| 4088 <callback id="jvmtiPrimitiveFieldCallback" since="1.1"> | |
| 4089 <jint/> | |
| 4090 <synopsis>Primitive Field Callback</synopsis> | |
| 4091 <description> | |
| 4092 Agent supplied callback function which | |
| 4093 describes a primitive field of an object (<i>the object</i>). | |
| 4094 A primitive field is a field whose type is a primitive type. | |
| 4095 This callback will describe a static field if the object is a class, | |
| 4096 and otherwise will describe an instance field. | |
| 4097 <p/> | |
| 4098 This function should return a bit vector of the desired | |
| 4099 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4100 This will determine if the entire iteration should be aborted | |
| 4101 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4102 <p/> | |
| 4103 See the <internallink id="heapCallbacks">heap callback | |
| 4104 function restrictions</internallink>. | |
| 4105 </description> | |
| 4106 <parameters> | |
| 4107 <param id="kind"> | |
| 4108 <enum>jvmtiHeapReferenceKind</enum> | |
| 4109 <description> | |
| 4110 The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or | |
| 4111 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>). | |
| 4112 </description> | |
| 4113 </param> | |
| 4114 <param id="info"> | |
| 4115 <inptr> | |
| 4116 <struct>jvmtiHeapReferenceInfo</struct> | |
| 4117 </inptr> | |
| 4118 <description> | |
| 4119 Which field (the field index). | |
| 4120 </description> | |
| 4121 </param> | |
| 4122 <param id="object_class_tag"> | |
| 4123 <jlong/> | |
| 4124 <description> | |
| 4125 The tag of the class of the object (zero if the class is not tagged). | |
| 4126 If the object represents a runtime class, the | |
| 4127 <code>object_class_tag</code> is the tag | |
| 4128 associated with <code>java.lang.Class</code> | |
| 4129 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4130 </description> | |
| 4131 </param> | |
| 4132 <param id="object_tag_ptr"> | |
| 4133 <outptr><jlong/></outptr> | |
| 4134 <description> | |
| 4135 Points to the tag of the object, or zero if the object is not | |
| 4136 tagged. | |
| 4137 To set the tag value to be associated with the object | |
| 4138 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4139 </description> | |
| 4140 </param> | |
| 4141 <param id="value"> | |
| 4142 <jvalue/> | |
| 4143 <description> | |
| 4144 The value of the field. | |
| 4145 </description> | |
| 4146 </param> | |
| 4147 <param id="value_type"> | |
| 4148 <enum>jvmtiPrimitiveType</enum> | |
| 4149 <description> | |
| 4150 The type of the field. | |
| 4151 </description> | |
| 4152 </param> | |
| 4153 <param id="user_data"> | |
| 4154 <outptr><void/></outptr> | |
| 4155 <description> | |
| 4156 The user supplied data that was passed into the iteration function. | |
| 4157 </description> | |
| 4158 </param> | |
| 4159 </parameters> | |
| 4160 </callback> | |
| 4161 | |
| 4162 <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1"> | |
| 4163 <jint/> | |
| 4164 <synopsis>Array Primitive Value Callback</synopsis> | |
| 4165 <description> | |
| 4166 Agent supplied callback function. | |
| 4167 Describes the values in an array of a primitive type. | |
| 4168 <p/> | |
| 4169 This function should return a bit vector of the desired | |
| 4170 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4171 This will determine if the entire iteration should be aborted | |
| 4172 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4173 <p/> | |
| 4174 See the <internallink id="heapCallbacks">heap callback | |
| 4175 function restrictions</internallink>. | |
| 4176 </description> | |
| 4177 <parameters> | |
| 4178 <param id="class_tag"> | |
| 4179 <jlong/> | |
| 4180 <description> | |
| 4181 The tag of the class of the array object (zero if the class is not tagged). | |
| 4182 </description> | |
| 4183 </param> | |
| 4184 <param id="size"> | |
| 4185 <jlong/> | |
| 4186 <description> | |
| 4187 Size of the array (in bytes). | |
| 4188 See <functionlink id="GetObjectSize"/>. | |
| 4189 </description> | |
| 4190 </param> | |
| 4191 <param id="tag_ptr"> | |
| 4192 <outptr><jlong/></outptr> | |
| 4193 <description> | |
| 4194 Points to the tag of the array object, or zero if the object is not | |
| 4195 tagged. | |
| 4196 To set the tag value to be associated with the object | |
| 4197 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4198 </description> | |
| 4199 </param> | |
| 4200 <param id="element_count"> | |
| 4201 <jint/> | |
| 4202 <description> | |
| 4203 The length of the primitive array. | |
| 4204 </description> | |
| 4205 </param> | |
| 4206 <param id="element_type"> | |
| 4207 <enum>jvmtiPrimitiveType</enum> | |
| 4208 <description> | |
| 4209 The type of the elements of the array. | |
| 4210 </description> | |
| 4211 </param> | |
| 4212 <param id="elements"> | |
| 4213 <vmbuf><void/></vmbuf> | |
| 4214 <description> | |
| 4215 The elements of the array in a packed array of <code>element_count</code> | |
| 4216 items of <code>element_type</code> size each. | |
| 4217 </description> | |
| 4218 </param> | |
| 4219 <param id="user_data"> | |
| 4220 <outptr><void/></outptr> | |
| 4221 <description> | |
| 4222 The user supplied data that was passed into the iteration function. | |
| 4223 </description> | |
| 4224 </param> | |
| 4225 </parameters> | |
| 4226 </callback> | |
| 4227 | |
| 4228 <callback id="jvmtiStringPrimitiveValueCallback" since="1.1"> | |
| 4229 <jint/> | |
| 4230 <synopsis>String Primitive Value Callback</synopsis> | |
| 4231 <description> | |
| 4232 Agent supplied callback function. | |
| 4233 Describes the value of a java.lang.String. | |
| 4234 <p/> | |
| 4235 This function should return a bit vector of the desired | |
| 4236 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4237 This will determine if the entire iteration should be aborted | |
| 4238 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4239 <p/> | |
| 4240 See the <internallink id="heapCallbacks">heap callback | |
| 4241 function restrictions</internallink>. | |
| 4242 </description> | |
| 4243 <parameters> | |
| 4244 <param id="class_tag"> | |
| 4245 <jlong/> | |
| 4246 <description> | |
| 4247 The tag of the class of the String class (zero if the class is not tagged). | |
| 4248 <issue>Is this needed?</issue> | |
| 4249 </description> | |
| 4250 </param> | |
| 4251 <param id="size"> | |
| 4252 <jlong/> | |
| 4253 <description> | |
| 4254 Size of the string (in bytes). | |
| 4255 See <functionlink id="GetObjectSize"/>. | |
| 4256 </description> | |
| 4257 </param> | |
| 4258 <param id="tag_ptr"> | |
| 4259 <outptr><jlong/></outptr> | |
| 4260 <description> | |
| 4261 Points to the tag of the String object, or zero if the object is not | |
| 4262 tagged. | |
| 4263 To set the tag value to be associated with the object | |
| 4264 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4265 </description> | |
| 4266 </param> | |
| 4267 <param id="value"> | |
| 4268 <vmbuf><jchar/></vmbuf> | |
| 4269 <description> | |
| 4270 The value of the String, encoded as a Unicode string. | |
| 4271 </description> | |
| 4272 </param> | |
| 4273 <param id="value_length"> | |
| 4274 <jint/> | |
| 4275 <description> | |
| 4276 The length of the string. | |
| 4277 The length is equal to the number of 16-bit Unicode | |
| 4278 characters in the string. | |
| 4279 </description> | |
| 4280 </param> | |
| 4281 <param id="user_data"> | |
| 4282 <outptr><void/></outptr> | |
| 4283 <description> | |
| 4284 The user supplied data that was passed into the iteration function. | |
| 4285 </description> | |
| 4286 </param> | |
| 4287 </parameters> | |
| 4288 </callback> | |
| 4289 | |
| 4290 | |
| 4291 <callback id="jvmtiReservedCallback" since="1.1"> | |
| 4292 <jint/> | |
| 4293 <synopsis>reserved for future use Callback</synopsis> | |
| 4294 <description> | |
| 4295 Placeholder -- reserved for future use. | |
| 4296 </description> | |
| 4297 <parameters> | |
| 4298 </parameters> | |
| 4299 </callback> | |
| 4300 | |
| 4301 <function id="FollowReferences" num="115" since="1.1"> | |
| 4302 <synopsis>Follow References</synopsis> | |
| 4303 <description> | |
| 4304 This function initiates a traversal over the objects that are | |
| 4305 directly and indirectly reachable from the specified object or, | |
| 4306 if <code>initial_object</code> is not specified, all objects | |
| 4307 reachable from the heap roots. | |
| 4308 The heap root are the set of system classes, | |
| 4309 JNI globals, references from thread stacks, and other objects used as roots | |
| 4310 for the purposes of garbage collection. | |
| 4311 <p/> | |
| 4312 This function operates by traversing the reference graph. | |
| 4313 Let <i>A</i>, <i>B</i>, ... represent objects. | |
| 4314 When a reference from <i>A</i> to <i>B</i> is traversed, | |
| 4315 when a reference from a heap root to <i>B</i> is traversed, | |
| 4316 or when <i>B</i> is specified as the <paramlink id="initial_object"/>, | |
| 4317 then <i>B</i> is said to be <i>visited</i>. | |
| 4318 A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i> | |
| 4319 is visited. | |
| 4320 References are reported in the same order that the references are traversed. | |
| 4321 Object references are reported by invoking the agent supplied | |
| 4322 callback function <functionlink id="jvmtiHeapReferenceCallback"/>. | |
| 4323 In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known | |
| 4324 as the <i>referrer</i> and <i>B</i> as the <i>referree</i>. | |
| 4325 The callback is invoked exactly once for each reference from a referrer; | |
| 4326 this is true even if there are reference cycles or multiple paths to | |
| 4327 the referrer. | |
| 4328 There may be more than one reference between a referrer and a referree, | |
| 4329 each reference is reported. | |
| 4330 These references may be distinguished by examining the | |
| 4331 <datalink | |
| 4332 id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink> | |
| 4333 and | |
| 4334 <datalink | |
| 4335 id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink> | |
| 4336 parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback. | |
| 4337 <p/> | |
| 4338 This function reports a Java programming language view of object references, | |
| 4339 not a virtual machine implementation view. The following object references | |
| 4340 are reported when they are non-null: | |
| 4341 <ul> | |
| 4342 <li>Instance objects report references to each non-primitive instance fields | |
| 4343 (including inherited fields).</li> | |
| 4344 <li>Instance objects report a reference to the object type (class).</li> | |
| 4345 <li>Classes report a reference to the superclass and directly | |
| 4346 implemented/extended interfaces.</li> | |
| 4347 <li>Classes report a reference to the class loader, protection domain, | |
| 4348 signers, and resolved entries in the constant pool.</li> | |
| 4349 <li>Classes report a reference to each directly declared non-primitive | |
| 4350 static field.</li> | |
| 4351 <li>Arrays report a reference to the array type (class) and each | |
| 4352 array element.</li> | |
| 4353 <li>Primitive arrays report a reference to the array type.</li> | |
| 4354 </ul> | |
| 4355 <p/> | |
| 4356 This function can also be used to examine primitive (non-object) values. | |
| 4357 The primitive value of an array or String | |
| 4358 is reported after the object has been visited; | |
| 4359 it is reported by invoking the agent supplied callback function | |
| 4360 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or | |
| 4361 <functionlink id="jvmtiStringPrimitiveValueCallback"/>. | |
| 4362 A primitive field | |
| 4363 is reported after the object with that field is visited; | |
| 4364 it is reported by invoking the agent supplied callback function | |
| 4365 <functionlink id="jvmtiPrimitiveFieldCallback"/>. | |
| 4366 <p/> | |
| 4367 Whether a callback is provided or is <code>NULL</code> only determines | |
| 4368 whether the callback will be invoked, it does not influence | |
| 4369 which objects are visited nor does it influence whether other callbacks | |
| 4370 will be invoked. | |
| 4371 However, the | |
| 4372 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink> | |
| 4373 returned by <functionlink id="jvmtiHeapReferenceCallback"/> | |
| 4374 do determine if the objects referenced by the | |
| 4375 current object as visited. | |
| 4376 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> | |
| 4377 and <paramlink id="klass"/> provided as parameters to this function | |
| 4378 do not control which objects are visited but they do control which | |
| 4379 objects and primitive values are reported by the callbacks. | |
| 4380 For example, if the only callback that was set is | |
| 6919 | 4381 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code> |
| 0 | 4382 is set to the array of bytes class, then only arrays of byte will be |
| 4383 reported. | |
| 4384 The table below summarizes this: | |
| 4385 <p/> | |
| 4386 <table> | |
| 4387 <tr> | |
| 4388 <th/> | |
| 4389 <th> | |
| 4390 Controls objects visited | |
| 4391 </th> | |
| 4392 <th> | |
| 4393 Controls objects reported | |
| 4394 </th> | |
| 4395 <th> | |
| 4396 Controls primitives reported | |
| 4397 </th> | |
| 4398 </tr> | |
| 4399 <tr> | |
| 4400 <th align="left"> | |
| 4401 the | |
| 4402 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
| 4403 returned by <functionlink id="jvmtiHeapReferenceCallback"/> | |
| 4404 </th> | |
| 4405 <td> | |
| 4406 <b>Yes</b> | |
| 4407 </td> | |
| 4408 <td> | |
| 4409 <b>Yes</b>, since visits are controlled | |
| 4410 </td> | |
| 4411 <td> | |
| 4412 <b>Yes</b>, since visits are controlled | |
| 4413 </td> | |
| 4414 </tr> | |
| 4415 <tr> | |
| 4416 <th align="left"> | |
| 6919 | 4417 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> |
| 0 | 4418 in <paramlink id="callbacks"/> set |
| 4419 </th> | |
| 4420 <td> | |
| 4421 No | |
| 4422 </td> | |
| 4423 <td> | |
| 4424 <b>Yes</b> | |
| 4425 </td> | |
| 4426 <td> | |
| 4427 No | |
| 4428 </td> | |
| 4429 </tr> | |
| 4430 <tr> | |
| 4431 <th align="left"> | |
| 4432 <paramlink id="heap_filter"/> | |
| 4433 </th> | |
| 4434 <td> | |
| 4435 No | |
| 4436 </td> | |
| 4437 <td> | |
| 4438 <b>Yes</b> | |
| 4439 </td> | |
| 4440 <td> | |
| 4441 <b>Yes</b> | |
| 4442 </td> | |
| 4443 </tr> | |
| 4444 <tr> | |
| 4445 <th align="left"> | |
| 4446 <paramlink id="klass"/> | |
| 4447 </th> | |
| 4448 <td> | |
| 4449 No | |
| 4450 </td> | |
| 4451 <td> | |
| 4452 <b>Yes</b> | |
| 4453 </td> | |
| 4454 <td> | |
| 4455 <b>Yes</b> | |
| 4456 </td> | |
| 4457 </tr> | |
| 4458 </table> | |
| 4459 <p/> | |
| 4460 During the execution of this function the state of the heap | |
| 4461 does not change: no objects are allocated, no objects are | |
| 4462 garbage collected, and the state of objects (including | |
| 4463 held values) does not change. | |
| 4464 As a result, threads executing Java | |
| 4465 programming language code, threads attempting to resume the | |
| 4466 execution of Java programming language code, and threads | |
| 4467 attempting to execute JNI functions are typically stalled. | |
| 4468 </description> | |
| 4469 <origin>new</origin> | |
| 4470 <capabilities> | |
| 4471 <required id="can_tag_objects"></required> | |
| 4472 </capabilities> | |
| 4473 <parameters> | |
| 4474 <param id="heap_filter"> | |
| 4475 <jint/> | |
| 4476 <description> | |
| 4477 This bit vector of | |
| 4478 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>. | |
| 4479 restricts the objects for which the callback function is called. | |
| 4480 This applies to both the object and primitive callbacks. | |
| 4481 </description> | |
| 4482 </param> | |
| 4483 <param id="klass"> | |
| 4484 <ptrtype> | |
| 4485 <jclass/> | |
| 4486 <nullok>callbacks are not limited to instances of a particular | |
| 4487 class</nullok> | |
| 4488 </ptrtype> | |
| 4489 <description> | |
| 4490 Callbacks are only reported when the object is an instance of | |
| 4491 this class. | |
| 4492 Objects which are instances of a subclass of <code>klass</code> | |
| 4493 are not reported. | |
| 4494 If <code>klass</code> is an interface, no objects are reported. | |
| 4495 This applies to both the object and primitive callbacks. | |
| 4496 </description> | |
| 4497 </param> | |
| 4498 <param id="initial_object"> | |
| 4499 <ptrtype> | |
| 4500 <jobject/> | |
| 4501 <nullok>references are followed from the heap roots</nullok> | |
| 4502 </ptrtype> | |
| 4503 <description> | |
| 4504 The object to follow | |
| 4505 </description> | |
| 4506 </param> | |
| 4507 <param id="callbacks"> | |
| 4508 <inptr> | |
| 4509 <struct>jvmtiHeapCallbacks</struct> | |
| 4510 </inptr> | |
| 4511 <description> | |
| 4512 Structure defining the set of callback functions. | |
| 4513 </description> | |
| 4514 </param> | |
| 4515 <param id="user_data"> | |
| 4516 <inbuf> | |
| 4517 <void/> | |
| 4518 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 4519 </inbuf> | |
| 4520 <description> | |
| 4521 User supplied data to be passed to the callback. | |
| 4522 </description> | |
| 4523 </param> | |
| 4524 </parameters> | |
| 4525 <errors> | |
| 4526 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 4527 <paramlink id="klass"/> is not a valid class. | |
| 4528 </error> | |
| 4529 <error id="JVMTI_ERROR_INVALID_OBJECT"> | |
| 4530 <paramlink id="initial_object"/> is not a valid object. | |
| 4531 </error> | |
| 4532 </errors> | |
| 4533 </function> | |
| 4534 | |
| 4535 | |
| 4536 <function id="IterateThroughHeap" num="116" since="1.1"> | |
| 4537 <synopsis>Iterate Through Heap</synopsis> | |
| 4538 <description> | |
| 4539 Initiate an iteration over all objects in the heap. | |
| 4540 This includes both reachable and | |
| 4541 unreachable objects. Objects are visited in no particular order. | |
| 4542 <p/> | |
| 4543 Heap objects are reported by invoking the agent supplied | |
| 4544 callback function <functionlink id="jvmtiHeapIterationCallback"/>. | |
| 4545 References between objects are not reported. | |
| 4546 If only reachable objects are desired, or if object reference information | |
| 4547 is needed, use <functionlink id="FollowReferences"/>. | |
| 4548 <p/> | |
| 4549 This function can also be used to examine primitive (non-object) values. | |
| 4550 The primitive value of an array or String | |
| 4551 is reported after the object has been visited; | |
| 4552 it is reported by invoking the agent supplied callback function | |
| 4553 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or | |
| 4554 <functionlink id="jvmtiStringPrimitiveValueCallback"/>. | |
| 4555 A primitive field | |
| 4556 is reported after the object with that field is visited; | |
| 4557 it is reported by invoking the agent supplied | |
| 4558 callback function | |
| 4559 <functionlink id="jvmtiPrimitiveFieldCallback"/>. | |
| 4560 <p/> | |
| 4561 Unless the iteration is aborted by the | |
| 4562 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
| 4563 returned by a callback, all objects in the heap are visited. | |
| 4564 Whether a callback is provided or is <code>NULL</code> only determines | |
| 4565 whether the callback will be invoked, it does not influence | |
| 4566 which objects are visited nor does it influence whether other callbacks | |
| 4567 will be invoked. | |
| 4568 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> | |
| 4569 and <paramlink id="klass"/> provided as parameters to this function | |
| 4570 do not control which objects are visited but they do control which | |
| 4571 objects and primitive values are reported by the callbacks. | |
| 4572 For example, if the only callback that was set is | |
| 6919 | 4573 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code> |
| 0 | 4574 is set to the array of bytes class, then only arrays of byte will be |
| 4575 reported. The table below summarizes this (contrast this with | |
| 4576 <functionlink id="FollowReferences"/>): | |
| 4577 <p/> | |
| 4578 <table> | |
| 4579 <tr> | |
| 4580 <th/> | |
| 4581 <th> | |
| 4582 Controls objects visited | |
| 4583 </th> | |
| 4584 <th> | |
| 4585 Controls objects reported | |
| 4586 </th> | |
| 4587 <th> | |
| 4588 Controls primitives reported | |
| 4589 </th> | |
| 4590 </tr> | |
| 4591 <tr> | |
| 4592 <th align="left"> | |
| 4593 the | |
| 4594 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
| 4595 returned by <functionlink id="jvmtiHeapIterationCallback"/> | |
| 4596 </th> | |
| 4597 <td> | |
| 4598 No<br/>(unless they abort the iteration) | |
| 4599 </td> | |
| 4600 <td> | |
| 4601 No<br/>(unless they abort the iteration) | |
| 4602 </td> | |
| 4603 <td> | |
| 4604 No<br/>(unless they abort the iteration) | |
| 4605 </td> | |
| 4606 </tr> | |
| 4607 <tr> | |
| 4608 <th align="left"> | |
| 6919 | 4609 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> |
| 0 | 4610 in <paramlink id="callbacks"/> set |
| 4611 </th> | |
| 4612 <td> | |
| 4613 No | |
| 4614 </td> | |
| 4615 <td> | |
| 4616 <b>Yes</b> | |
| 4617 </td> | |
| 4618 <td> | |
| 4619 No | |
| 4620 </td> | |
| 4621 </tr> | |
| 4622 <tr> | |
| 4623 <th align="left"> | |
| 4624 <paramlink id="heap_filter"/> | |
| 4625 </th> | |
| 4626 <td> | |
| 4627 No | |
| 4628 </td> | |
| 4629 <td> | |
| 4630 <b>Yes</b> | |
| 4631 </td> | |
| 4632 <td> | |
| 4633 <b>Yes</b> | |
| 4634 </td> | |
| 4635 </tr> | |
| 4636 <tr> | |
| 4637 <th align="left"> | |
| 4638 <paramlink id="klass"/> | |
| 4639 </th> | |
| 4640 <td> | |
| 4641 No | |
| 4642 </td> | |
| 4643 <td> | |
| 4644 <b>Yes</b> | |
| 4645 </td> | |
| 4646 <td> | |
| 4647 <b>Yes</b> | |
| 4648 </td> | |
| 4649 </tr> | |
| 4650 </table> | |
| 4651 <p/> | |
| 4652 During the execution of this function the state of the heap | |
| 4653 does not change: no objects are allocated, no objects are | |
| 4654 garbage collected, and the state of objects (including | |
| 4655 held values) does not change. | |
| 4656 As a result, threads executing Java | |
| 4657 programming language code, threads attempting to resume the | |
| 4658 execution of Java programming language code, and threads | |
| 4659 attempting to execute JNI functions are typically stalled. | |
| 4660 </description> | |
| 4661 <origin>new</origin> | |
| 4662 <capabilities> | |
| 4663 <required id="can_tag_objects"></required> | |
| 4664 </capabilities> | |
| 4665 <parameters> | |
| 4666 <param id="heap_filter"> | |
| 4667 <jint/> | |
| 4668 <description> | |
| 4669 This bit vector of | |
| 4670 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>. | |
| 4671 restricts the objects for which the callback function is called. | |
| 4672 This applies to both the object and primitive callbacks. | |
| 4673 </description> | |
| 4674 </param> | |
| 4675 <param id="klass"> | |
| 4676 <ptrtype> | |
| 4677 <jclass/> | |
| 4678 <nullok>callbacks are not limited to instances of a particular class</nullok> | |
| 4679 </ptrtype> | |
| 4680 <description> | |
| 4681 Callbacks are only reported when the object is an instance of | |
| 4682 this class. | |
| 4683 Objects which are instances of a subclass of <code>klass</code> | |
| 4684 are not reported. | |
| 4685 If <code>klass</code> is an interface, no objects are reported. | |
| 4686 This applies to both the object and primitive callbacks. | |
| 4687 </description> | |
| 4688 </param> | |
| 4689 <param id="callbacks"> | |
| 4690 <inptr> | |
| 4691 <struct>jvmtiHeapCallbacks</struct> | |
| 4692 </inptr> | |
| 4693 <description> | |
| 4694 Structure defining the set callback functions. | |
| 4695 </description> | |
| 4696 </param> | |
| 4697 <param id="user_data"> | |
| 4698 <inbuf> | |
| 4699 <void/> | |
| 4700 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 4701 </inbuf> | |
| 4702 <description> | |
| 4703 User supplied data to be passed to the callback. | |
| 4704 </description> | |
| 4705 </param> | |
| 4706 </parameters> | |
| 4707 <errors> | |
| 4708 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 4709 <paramlink id="klass"/> is not a valid class. | |
| 4710 </error> | |
| 4711 </errors> | |
| 4712 </function> | |
| 4713 | |
| 4714 <function id="GetTag" phase="start" num="106"> | |
| 4715 <synopsis>Get Tag</synopsis> | |
| 4716 <description> | |
| 4717 Retrieve the tag associated with an object. | |
| 4718 The tag is a long value typically used to store a | |
| 4719 unique identifier or pointer to object information. | |
| 4720 The tag is set with | |
| 4721 <functionlink id="SetTag"></functionlink>. | |
| 4722 Objects for which no tags have been set return a | |
| 4723 tag value of zero. | |
| 4724 </description> | |
| 4725 <origin>new</origin> | |
| 4726 <capabilities> | |
| 4727 <required id="can_tag_objects"></required> | |
| 4728 </capabilities> | |
| 4729 <parameters> | |
| 4730 <param id="object"> | |
| 4731 <jobject/> | |
| 4732 <description> | |
| 4733 The object whose tag is to be retrieved. | |
| 4734 </description> | |
| 4735 </param> | |
| 4736 <param id="tag_ptr"> | |
| 4737 <outptr><jlong/></outptr> | |
| 4738 <description> | |
| 4739 On return, the referenced long is set to the value | |
| 4740 of the tag. | |
| 4741 </description> | |
| 4742 </param> | |
| 4743 </parameters> | |
| 4744 <errors> | |
| 4745 </errors> | |
| 4746 </function> | |
| 4747 | |
| 4748 <function id="SetTag" phase="start" num="107"> | |
| 4749 <synopsis>Set Tag</synopsis> | |
| 4750 <description> | |
| 4751 Set the tag associated with an object. | |
| 4752 The tag is a long value typically used to store a | |
| 4753 unique identifier or pointer to object information. | |
| 4754 The tag is visible with | |
| 4755 <functionlink id="GetTag"></functionlink>. | |
| 4756 </description> | |
| 4757 <origin>new</origin> | |
| 4758 <capabilities> | |
| 4759 <required id="can_tag_objects"></required> | |
| 4760 </capabilities> | |
| 4761 <parameters> | |
| 4762 <param id="object"> | |
| 4763 <jobject/> | |
| 4764 <description> | |
| 4765 The object whose tag is to be set. | |
| 4766 </description> | |
| 4767 </param> | |
| 4768 <param id="tag"> | |
| 4769 <jlong/> | |
| 4770 <description> | |
| 4771 The new value of the tag. | |
| 4772 </description> | |
| 4773 </param> | |
| 4774 </parameters> | |
| 4775 <errors> | |
| 4776 </errors> | |
| 4777 </function> | |
| 4778 | |
| 4779 <function id="GetObjectsWithTags" num="114"> | |
| 4780 <synopsis>Get Objects With Tags</synopsis> | |
| 4781 <description> | |
| 4782 Return objects in the heap with the specified tags. | |
| 4783 The format is parallel arrays of objects and tags. | |
| 4784 </description> | |
| 4785 <origin>new</origin> | |
| 4786 <capabilities> | |
| 4787 <required id="can_tag_objects"></required> | |
| 4788 </capabilities> | |
| 4789 <parameters> | |
| 4790 <param id="tag_count"> | |
| 4791 <jint min="0"/> | |
| 4792 <description> | |
| 4793 Number of tags to scan for. | |
| 4794 </description> | |
| 4795 </param> | |
| 4796 <param id="tags"> | |
| 4797 <inbuf incount="tag_count"> | |
| 4798 <jlong/> | |
| 4799 </inbuf> | |
| 4800 <description> | |
| 4801 Scan for objects with these tags. | |
| 4802 Zero is not permitted in this array. | |
| 4803 </description> | |
| 4804 </param> | |
| 4805 <param id="count_ptr"> | |
| 4806 <outptr> | |
| 4807 <jint/> | |
| 4808 </outptr> | |
| 4809 <description> | |
| 4810 Return the number of objects with any of the tags | |
| 4811 in <paramlink id="tags"/>. | |
| 4812 </description> | |
| 4813 </param> | |
| 4814 <param id="object_result_ptr"> | |
| 4815 <allocbuf outcount="count_ptr"> | |
| 4816 <jobject/> | |
| 4817 <nullok>this information is not returned</nullok> | |
| 4818 </allocbuf> | |
| 4819 <description> | |
| 4820 Returns the array of objects with any of the tags | |
| 4821 in <paramlink id="tags"/>. | |
| 4822 </description> | |
| 4823 </param> | |
| 4824 <param id="tag_result_ptr"> | |
| 4825 <allocbuf outcount="count_ptr"> | |
| 4826 <jlong/> | |
| 4827 <nullok>this information is not returned</nullok> | |
| 4828 </allocbuf> | |
| 4829 <description> | |
| 4830 For each object in <paramlink id="object_result_ptr"/>, | |
| 4831 return the tag at the corresponding index. | |
| 4832 </description> | |
| 4833 </param> | |
| 4834 </parameters> | |
| 4835 <errors> | |
| 4836 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 4837 Zero is present in <paramlink id="tags"></paramlink>. | |
| 4838 </error> | |
| 4839 </errors> | |
| 4840 </function> | |
| 4841 | |
| 4842 <function id="ForceGarbageCollection" num="108"> | |
| 4843 <synopsis>Force Garbage Collection</synopsis> | |
| 4844 <description> | |
| 4845 Force the VM to perform a garbage collection. | |
| 4846 The garbage collection is as complete as possible. | |
| 4847 This function does not cause finalizers to be run. | |
| 4848 This function does not return until the garbage collection | |
| 4849 is finished. | |
| 4850 <p/> | |
| 4851 Although garbage collection is as complete | |
| 4852 as possible there is no guarantee that all | |
| 4853 <eventlink id="ObjectFree"/> | |
| 4854 events will have been | |
| 4855 sent by the time that this function | |
| 4856 returns. In particular, an object may be | |
| 4857 prevented from being freed because it | |
| 4858 is awaiting finalization. | |
| 4859 </description> | |
| 4860 <origin>new</origin> | |
| 4861 <capabilities> | |
| 4862 </capabilities> | |
| 4863 <parameters> | |
| 4864 </parameters> | |
| 4865 <errors> | |
| 4866 </errors> | |
| 4867 </function> | |
| 4868 | |
| 4869 | |
| 4870 </category> | |
| 4871 | |
| 4872 <category id="Heap_1_0" label="Heap (1.0)"> | |
| 4873 <intro> | |
| 4874 <b> | |
| 4875 These functions and data types were introduced in the original | |
| 4876 <jvmti/> version 1.0 and have been superseded by more | |
| 4877 </b> | |
| 4878 <internallink id="Heap"><b>powerful and flexible versions</b></internallink> | |
| 4879 <b> | |
| 4880 which: | |
| 4881 </b> | |
| 4882 <ul> | |
| 4883 <li> | |
| 4884 <b> | |
| 4885 Allow access to primitive values (the value of Strings, arrays, | |
| 4886 and primitive fields) | |
| 4887 </b> | |
| 4888 </li> | |
| 4889 <li> | |
| 4890 <b> | |
| 4891 Allow the tag of the referrer to be set, thus enabling more | |
| 4892 efficient localized reference graph building | |
| 4893 </b> | |
| 4894 </li> | |
| 4895 <li> | |
| 4896 <b> | |
| 4897 Provide more extensive filtering abilities | |
| 4898 </b> | |
| 4899 </li> | |
| 4900 <li> | |
| 4901 <b> | |
| 4902 Are extensible, allowing their abilities to grow in future versions of <jvmti/> | |
| 4903 </b> | |
| 4904 </li> | |
| 4905 </ul> | |
| 4906 <p/> | |
| 4907 <b>Please use the </b> | |
| 4908 <internallink id="Heap"><b>current Heap functions</b></internallink>. | |
| 4909 <p/> | |
| 4910 <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum"> | |
| 4911 <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1"> | |
| 4912 Tagged objects only. | |
| 4913 </constant> | |
| 4914 <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2"> | |
| 4915 Untagged objects only. | |
| 4916 </constant> | |
| 4917 <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3"> | |
| 4918 Either tagged or untagged objects. | |
| 4919 </constant> | |
| 4920 </constants> | |
| 4921 | |
| 4922 <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum"> | |
| 4923 <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1"> | |
| 4924 JNI global reference. | |
| 4925 </constant> | |
| 4926 <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2"> | |
| 4927 System class. | |
| 4928 </constant> | |
| 4929 <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3"> | |
| 4930 Monitor. | |
| 4931 </constant> | |
| 4932 <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4"> | |
| 4933 Stack local. | |
| 4934 </constant> | |
| 4935 <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5"> | |
| 4936 JNI local reference. | |
| 4937 </constant> | |
| 4938 <constant id="JVMTI_HEAP_ROOT_THREAD" num="6"> | |
| 4939 Thread. | |
| 4940 </constant> | |
| 4941 <constant id="JVMTI_HEAP_ROOT_OTHER" num="7"> | |
| 4942 Other. | |
| 4943 </constant> | |
| 4944 </constants> | |
| 4945 | |
| 4946 <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum"> | |
| 4947 <constant id="JVMTI_REFERENCE_CLASS" num="1"> | |
| 4948 Reference from an object to its class. | |
| 4949 </constant> | |
| 4950 <constant id="JVMTI_REFERENCE_FIELD" num="2"> | |
| 4951 Reference from an object to the value of one of its instance fields. | |
| 4952 For references of this kind the <code>referrer_index</code> | |
| 4953 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 4954 jvmtiObjectReferenceCallback</internallink> is the index of the | |
| 4955 the instance field. The index is based on the order of all the | |
| 4956 object's fields. This includes all fields of the directly declared | |
| 4957 static and instance fields in the class, and includes all fields (both | |
| 4958 public and private) fields declared in superclasses and superinterfaces. | |
| 4959 The index is thus calculated by summing the index of the field in the directly | |
| 4960 declared class (see <functionlink id="GetClassFields"/>), with the total | |
| 4961 number of fields (both public and private) declared in all superclasses | |
| 4962 and superinterfaces. The index starts at zero. | |
| 4963 </constant> | |
| 4964 <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3"> | |
| 4965 Reference from an array to one of its elements. | |
| 4966 For references of this kind the <code>referrer_index</code> | |
| 4967 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 4968 jvmtiObjectReferenceCallback</internallink> is the array index. | |
| 4969 </constant> | |
| 4970 <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4"> | |
| 4971 Reference from a class to its class loader. | |
| 4972 </constant> | |
| 4973 <constant id="JVMTI_REFERENCE_SIGNERS" num="5"> | |
| 4974 Reference from a class to its signers array. | |
| 4975 </constant> | |
| 4976 <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6"> | |
| 4977 Reference from a class to its protection domain. | |
| 4978 </constant> | |
| 4979 <constant id="JVMTI_REFERENCE_INTERFACE" num="7"> | |
| 4980 Reference from a class to one of its interfaces. | |
| 4981 </constant> | |
| 4982 <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8"> | |
| 4983 Reference from a class to the value of one of its static fields. | |
| 4984 For references of this kind the <code>referrer_index</code> | |
| 4985 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 4986 jvmtiObjectReferenceCallback</internallink> is the index of the | |
| 4987 the static field. The index is based on the order of all the | |
| 4988 object's fields. This includes all fields of the directly declared | |
| 4989 static and instance fields in the class, and includes all fields (both | |
| 4990 public and private) fields declared in superclasses and superinterfaces. | |
| 4991 The index is thus calculated by summing the index of the field in the directly | |
| 4992 declared class (see <functionlink id="GetClassFields"/>), with the total | |
| 4993 number of fields (both public and private) declared in all superclasses | |
| 4994 and superinterfaces. The index starts at zero. | |
| 4995 Note: this definition differs from that in the <jvmti/> 1.0 Specification. | |
| 4996 <rationale>No known implementations used the 1.0 definition.</rationale> | |
| 4997 </constant> | |
| 4998 <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9"> | |
| 4999 Reference from a class to a resolved entry in the constant pool. | |
| 5000 For references of this kind the <code>referrer_index</code> | |
| 5001 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 5002 jvmtiObjectReferenceCallback</internallink> is the index into | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
5003 constant pool table of the class, starting at 1. See |
|
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
5004 <vmspec chapter="4.4"/>. |
| 0 | 5005 </constant> |
| 5006 </constants> | |
| 5007 | |
| 5008 <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum"> | |
| 5009 <constant id="JVMTI_ITERATION_CONTINUE" num="1"> | |
| 5010 Continue the iteration. | |
| 5011 If this is a reference iteration, follow the references of this object. | |
| 5012 </constant> | |
| 5013 <constant id="JVMTI_ITERATION_IGNORE" num="2"> | |
| 5014 Continue the iteration. | |
| 5015 If this is a reference iteration, ignore the references of this object. | |
| 5016 </constant> | |
| 5017 <constant id="JVMTI_ITERATION_ABORT" num="0"> | |
| 5018 Abort the iteration. | |
| 5019 </constant> | |
| 5020 </constants> | |
| 5021 </intro> | |
| 5022 | |
| 5023 <callback id="jvmtiHeapObjectCallback"> | |
| 5024 <enum>jvmtiIterationControl</enum> | |
| 5025 <synopsis>Heap Object Callback</synopsis> | |
| 5026 <description> | |
| 5027 Agent supplied callback function. | |
| 5028 Describes (but does not pass in) an object in the heap. | |
| 5029 <p/> | |
| 5030 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5031 or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5032 <p/> | |
| 5033 See the <internallink id="heapCallbacks">heap callback | |
| 5034 function restrictions</internallink>. | |
| 5035 </description> | |
| 5036 <parameters> | |
| 5037 <param id="class_tag"> | |
| 5038 <jlong/> | |
| 5039 <description> | |
| 5040 The tag of the class of object (zero if the class is not tagged). | |
| 5041 If the object represents a runtime class, | |
| 5042 the <code>class_tag</code> is the tag | |
| 5043 associated with <code>java.lang.Class</code> | |
| 5044 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5045 </description> | |
| 5046 </param> | |
| 5047 <param id="size"> | |
| 5048 <jlong/> | |
| 5049 <description> | |
| 5050 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 5051 </description> | |
| 5052 </param> | |
| 5053 <param id="tag_ptr"> | |
| 5054 <outptr><jlong/></outptr> | |
| 5055 <description> | |
| 5056 The object tag value, or zero if the object is not tagged. | |
| 5057 To set the tag value to be associated with the object | |
| 5058 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5059 </description> | |
| 5060 </param> | |
| 5061 <param id="user_data"> | |
| 5062 <outptr><void/></outptr> | |
| 5063 <description> | |
| 5064 The user supplied data that was passed into the iteration function. | |
| 5065 </description> | |
| 5066 </param> | |
| 5067 </parameters> | |
| 5068 </callback> | |
| 5069 | |
| 5070 <callback id="jvmtiHeapRootCallback"> | |
| 5071 <enum>jvmtiIterationControl</enum> | |
| 5072 <synopsis>Heap Root Object Callback</synopsis> | |
| 5073 <description> | |
| 5074 Agent supplied callback function. | |
| 5075 Describes (but does not pass in) an object that is a root for the purposes | |
| 5076 of garbage collection. | |
| 5077 <p/> | |
| 5078 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5079 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
| 5080 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5081 <p/> | |
| 5082 See the <internallink id="heapCallbacks">heap callback | |
| 5083 function restrictions</internallink>. | |
| 5084 </description> | |
| 5085 <parameters> | |
| 5086 <param id="root_kind"> | |
| 5087 <enum>jvmtiHeapRootKind</enum> | |
| 5088 <description> | |
| 5089 The kind of heap root. | |
| 5090 </description> | |
| 5091 </param> | |
| 5092 <param id="class_tag"> | |
| 5093 <jlong/> | |
| 5094 <description> | |
| 5095 The tag of the class of object (zero if the class is not tagged). | |
| 5096 If the object represents a runtime class, the <code>class_tag</code> is the tag | |
| 5097 associated with <code>java.lang.Class</code> | |
| 5098 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5099 </description> | |
| 5100 </param> | |
| 5101 <param id="size"> | |
| 5102 <jlong/> | |
| 5103 <description> | |
| 5104 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 5105 </description> | |
| 5106 </param> | |
| 5107 <param id="tag_ptr"> | |
| 5108 <outptr><jlong/></outptr> | |
| 5109 <description> | |
| 5110 The object tag value, or zero if the object is not tagged. | |
| 5111 To set the tag value to be associated with the object | |
| 5112 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5113 </description> | |
| 5114 </param> | |
| 5115 <param id="user_data"> | |
| 5116 <outptr><void/></outptr> | |
| 5117 <description> | |
| 5118 The user supplied data that was passed into the iteration function. | |
| 5119 </description> | |
| 5120 </param> | |
| 5121 </parameters> | |
| 5122 </callback> | |
| 5123 | |
| 5124 <callback id="jvmtiStackReferenceCallback"> | |
| 5125 <enum>jvmtiIterationControl</enum> | |
| 5126 <synopsis>Stack Reference Object Callback</synopsis> | |
| 5127 <description> | |
| 5128 Agent supplied callback function. | |
| 5129 Describes (but does not pass in) an object on the stack that is a root for | |
| 5130 the purposes of garbage collection. | |
| 5131 <p/> | |
| 5132 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5133 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
| 5134 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5135 <p/> | |
| 5136 See the <internallink id="heapCallbacks">heap callback | |
| 5137 function restrictions</internallink>. | |
| 5138 </description> | |
| 5139 <parameters> | |
| 5140 <param id="root_kind"> | |
| 5141 <enum>jvmtiHeapRootKind</enum> | |
| 5142 <description> | |
| 5143 The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or | |
| 5144 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>). | |
| 5145 </description> | |
| 5146 </param> | |
| 5147 <param id="class_tag"> | |
| 5148 <jlong/> | |
| 5149 <description> | |
| 5150 The tag of the class of object (zero if the class is not tagged). | |
| 5151 If the object represents a runtime class, the <code>class_tag</code> is the tag | |
| 5152 associated with <code>java.lang.Class</code> | |
| 5153 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5154 </description> | |
| 5155 </param> | |
| 5156 <param id="size"> | |
| 5157 <jlong/> | |
| 5158 <description> | |
| 5159 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 5160 </description> | |
| 5161 </param> | |
| 5162 <param id="tag_ptr"> | |
| 5163 <outptr><jlong/></outptr> | |
| 5164 <description> | |
| 5165 The object tag value, or zero if the object is not tagged. | |
| 5166 To set the tag value to be associated with the object | |
| 5167 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5168 </description> | |
| 5169 </param> | |
| 5170 <param id="thread_tag"> | |
| 5171 <jlong/> | |
| 5172 <description> | |
| 5173 The tag of the thread corresponding to this stack, zero if not tagged. | |
| 5174 </description> | |
| 5175 </param> | |
| 5176 <param id="depth"> | |
| 5177 <jint/> | |
| 5178 <description> | |
| 5179 The depth of the frame. | |
| 5180 </description> | |
| 5181 </param> | |
| 5182 <param id="method"> | |
| 5183 <jmethodID/> | |
| 5184 <description> | |
| 5185 The method executing in this frame. | |
| 5186 </description> | |
| 5187 </param> | |
| 5188 <param id="slot"> | |
| 5189 <jint/> | |
| 5190 <description> | |
| 5191 The slot number. | |
| 5192 </description> | |
| 5193 </param> | |
| 5194 <param id="user_data"> | |
| 5195 <outptr><void/></outptr> | |
| 5196 <description> | |
| 5197 The user supplied data that was passed into the iteration function. | |
| 5198 </description> | |
| 5199 </param> | |
| 5200 </parameters> | |
| 5201 </callback> | |
| 5202 | |
| 5203 <callback id="jvmtiObjectReferenceCallback"> | |
| 5204 <enum>jvmtiIterationControl</enum> | |
| 5205 <synopsis>Object Reference Callback</synopsis> | |
| 5206 <description> | |
| 5207 Agent supplied callback function. | |
| 5208 Describes a reference from an object (the referrer) to another object | |
| 5209 (the referree). | |
| 5210 <p/> | |
| 5211 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5212 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
| 5213 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5214 <p/> | |
| 5215 See the <internallink id="heapCallbacks">heap callback | |
| 5216 function restrictions</internallink>. | |
| 5217 </description> | |
| 5218 <parameters> | |
| 5219 <param id="reference_kind"> | |
| 5220 <enum>jvmtiObjectReferenceKind</enum> | |
| 5221 <description> | |
| 5222 The type of reference. | |
| 5223 </description> | |
| 5224 </param> | |
| 5225 <param id="class_tag"> | |
| 5226 <jlong/> | |
| 5227 <description> | |
| 5228 The tag of the class of referree object (zero if the class is not tagged). | |
| 5229 If the referree object represents a runtime class, | |
| 5230 the <code>class_tag</code> is the tag | |
| 5231 associated with <code>java.lang.Class</code> | |
| 5232 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5233 </description> | |
| 5234 </param> | |
| 5235 <param id="size"> | |
| 5236 <jlong/> | |
| 5237 <description> | |
| 5238 Size of the referree object (in bytes). | |
| 5239 See <functionlink id="GetObjectSize"/>. | |
| 5240 </description> | |
| 5241 </param> | |
| 5242 <param id="tag_ptr"> | |
| 5243 <outptr><jlong/></outptr> | |
| 5244 <description> | |
| 5245 The referree object tag value, or zero if the object is not | |
| 5246 tagged. | |
| 5247 To set the tag value to be associated with the object | |
| 5248 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5249 </description> | |
| 5250 </param> | |
| 5251 <param id="referrer_tag"> | |
| 5252 <jlong/> | |
| 5253 <description> | |
| 5254 The tag of the referrer object, or zero if the referrer | |
| 5255 object is not tagged. | |
| 5256 </description> | |
| 5257 </param> | |
| 5258 <param id="referrer_index"> | |
| 5259 <jint/> | |
| 5260 <description> | |
| 5261 For references of type <code>JVMTI_REFERENCE_FIELD</code> or | |
| 5262 <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index | |
| 5263 of the field in the referrer object. The index is based on the | |
| 5264 order of all the object's fields - see <internallink | |
| 5265 id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink> | |
| 5266 or <internallink | |
| 5267 id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD | |
| 5268 </internallink> for further description. | |
| 5269 <p/> | |
| 5270 For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code> | |
| 5271 the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT"> | |
| 5272 JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description. | |
| 5273 <p/> | |
| 5274 For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code> | |
| 5275 the index into the constant pool of the class - see | |
| 5276 <internallink id="JVMTI_REFERENCE_CONSTANT_POOL"> | |
| 5277 JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further | |
| 5278 description. | |
| 5279 <p/> | |
| 5280 For references of other kinds the <code>referrer_index</code> is | |
| 5281 <code>-1</code>. | |
| 5282 </description> | |
| 5283 </param> | |
| 5284 <param id="user_data"> | |
| 5285 <outptr><void/></outptr> | |
| 5286 <description> | |
| 5287 The user supplied data that was passed into the iteration function. | |
| 5288 </description> | |
| 5289 </param> | |
| 5290 </parameters> | |
| 5291 </callback> | |
| 5292 | |
| 5293 <function id="IterateOverObjectsReachableFromObject" num="109"> | |
| 5294 <synopsis>Iterate Over Objects Reachable From Object</synopsis> | |
| 5295 <description> | |
| 5296 This function iterates over all objects that are directly | |
| 5297 and indirectly reachable from the specified object. | |
| 5298 For each object <i>A</i> (known | |
| 5299 as the referrer) with a reference to object <i>B</i> the specified | |
| 5300 callback function is called to describe the object reference. | |
| 5301 The callback is called exactly once for each reference from a referrer; | |
| 5302 this is true even if there are reference cycles or multiple paths to | |
| 5303 the referrer. | |
| 5304 There may be more than one reference between a referrer and a referree, | |
| 5305 These may be distinguished by the | |
| 5306 <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and | |
| 5307 <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>. | |
| 5308 The callback for an object will always occur after the callback for | |
| 5309 its referrer. | |
| 5310 <p/> | |
| 5311 See <functionlink id="FollowReferences"/> for the object | |
| 5312 references which are reported. | |
| 5313 <p/> | |
| 5314 During the execution of this function the state of the heap | |
| 5315 does not change: no objects are allocated, no objects are | |
| 5316 garbage collected, and the state of objects (including | |
| 5317 held values) does not change. | |
| 5318 As a result, threads executing Java | |
| 5319 programming language code, threads attempting to resume the | |
| 5320 execution of Java programming language code, and threads | |
| 5321 attempting to execute JNI functions are typically stalled. | |
| 5322 </description> | |
| 5323 <origin>new</origin> | |
| 5324 <capabilities> | |
| 5325 <required id="can_tag_objects"></required> | |
| 5326 </capabilities> | |
| 5327 <parameters> | |
| 5328 <param id="object"> | |
| 5329 <jobject/> | |
| 5330 <description> | |
| 5331 The object | |
| 5332 </description> | |
| 5333 </param> | |
| 5334 <param id="object_reference_callback"> | |
| 5335 <ptrtype> | |
| 5336 <struct>jvmtiObjectReferenceCallback</struct> | |
| 5337 </ptrtype> | |
| 5338 <description> | |
| 5339 The callback to be called to describe each | |
| 5340 object reference. | |
| 5341 </description> | |
| 5342 </param> | |
| 5343 <param id="user_data"> | |
| 5344 <inbuf> | |
| 5345 <void/> | |
| 5346 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5347 </inbuf> | |
| 5348 <description> | |
| 5349 User supplied data to be passed to the callback. | |
| 5350 </description> | |
| 5351 </param> | |
| 5352 </parameters> | |
| 5353 <errors> | |
| 5354 </errors> | |
| 5355 </function> | |
| 5356 | |
| 5357 <function id="IterateOverReachableObjects" num="110"> | |
| 5358 <synopsis>Iterate Over Reachable Objects</synopsis> | |
| 5359 <description> | |
| 5360 This function iterates over the root objects and all objects that | |
| 5361 are directly and indirectly reachable from the root objects. | |
| 5362 The root objects comprise the set of system classes, | |
| 5363 JNI globals, references from thread stacks, and other objects used as roots | |
| 5364 for the purposes of garbage collection. | |
| 5365 <p/> | |
| 5366 For each root the <paramlink id="heap_root_callback"></paramlink> | |
| 5367 or <paramlink id="stack_ref_callback"></paramlink> callback is called. | |
| 5368 An object can be a root object for more than one reason and in that case | |
| 5369 the appropriate callback is called for each reason. | |
| 5370 <p/> | |
| 5371 For each object reference the <paramlink id="object_ref_callback"></paramlink> | |
| 5372 callback function is called to describe the object reference. | |
| 5373 The callback is called exactly once for each reference from a referrer; | |
| 5374 this is true even if there are reference cycles or multiple paths to | |
| 5375 the referrer. | |
| 5376 There may be more than one reference between a referrer and a referree, | |
| 5377 These may be distinguished by the | |
| 5378 <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and | |
| 5379 <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>. | |
| 5380 The callback for an object will always occur after the callback for | |
| 5381 its referrer. | |
| 5382 <p/> | |
| 5383 See <functionlink id="FollowReferences"/> for the object | |
| 5384 references which are reported. | |
| 5385 <p/> | |
| 5386 Roots are always reported to the profiler before any object references | |
| 5387 are reported. In other words, the <paramlink id="object_ref_callback"></paramlink> | |
| 5388 callback will not be called until the appropriate callback has been called | |
| 5389 for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is | |
| 5390 specified as <code>NULL</code> then this function returns after | |
| 5391 reporting the root objects to the profiler. | |
| 5392 <p/> | |
| 5393 During the execution of this function the state of the heap | |
| 5394 does not change: no objects are allocated, no objects are | |
| 5395 garbage collected, and the state of objects (including | |
| 5396 held values) does not change. | |
| 5397 As a result, threads executing Java | |
| 5398 programming language code, threads attempting to resume the | |
| 5399 execution of Java programming language code, and threads | |
| 5400 attempting to execute JNI functions are typically stalled. | |
| 5401 </description> | |
| 5402 <origin>new</origin> | |
| 5403 <capabilities> | |
| 5404 <required id="can_tag_objects"></required> | |
| 5405 </capabilities> | |
| 5406 <parameters> | |
| 5407 <param id="heap_root_callback"> | |
| 5408 <ptrtype> | |
| 5409 <struct>jvmtiHeapRootCallback</struct> | |
| 5410 <nullok>do not report heap roots</nullok> | |
| 5411 </ptrtype> | |
| 5412 <description> | |
| 5413 The callback function to be called for each heap root of type | |
| 5414 <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>, | |
| 5415 <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>, | |
| 5416 <code>JVMTI_HEAP_ROOT_MONITOR</code>, | |
| 5417 <code>JVMTI_HEAP_ROOT_THREAD</code>, or | |
| 5418 <code>JVMTI_HEAP_ROOT_OTHER</code>. | |
| 5419 </description> | |
| 5420 </param> | |
| 5421 <param id="stack_ref_callback"> | |
| 5422 <ptrtype> | |
| 5423 <struct>jvmtiStackReferenceCallback</struct> | |
| 5424 <nullok>do not report stack references</nullok> | |
| 5425 </ptrtype> | |
| 5426 <description> | |
| 5427 The callback function to be called for each heap root of | |
| 5428 <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or | |
| 5429 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>. | |
| 5430 </description> | |
| 5431 </param> | |
| 5432 <param id="object_ref_callback"> | |
| 5433 <ptrtype> | |
| 5434 <struct>jvmtiObjectReferenceCallback</struct> | |
| 5435 <nullok>do not follow references from the root objects</nullok> | |
| 5436 </ptrtype> | |
| 5437 <description> | |
| 5438 The callback function to be called for each object reference. | |
| 5439 </description> | |
| 5440 </param> | |
| 5441 <param id="user_data"> | |
| 5442 <inbuf> | |
| 5443 <void/> | |
| 5444 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5445 </inbuf> | |
| 5446 <description> | |
| 5447 User supplied data to be passed to the callback. | |
| 5448 </description> | |
| 5449 </param> | |
| 5450 </parameters> | |
| 5451 <errors> | |
| 5452 </errors> | |
| 5453 </function> | |
| 5454 | |
| 5455 <function id="IterateOverHeap" num="111"> | |
| 5456 <synopsis>Iterate Over Heap</synopsis> | |
| 5457 <description> | |
| 5458 Iterate over all objects in the heap. This includes both reachable and | |
| 5459 unreachable objects. | |
| 5460 <p/> | |
| 5461 The <paramlink id="object_filter"></paramlink> parameter indicates the | |
| 5462 objects for which the callback function is called. If this parameter | |
| 5463 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be | |
| 5464 called for every object that is tagged. If the parameter is | |
| 5465 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be | |
| 5466 for objects that are not tagged. If the parameter | |
| 5467 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be | |
| 5468 called for every object in the heap, irrespective of whether it is | |
| 5469 tagged or not. | |
| 5470 <p/> | |
| 5471 During the execution of this function the state of the heap | |
| 5472 does not change: no objects are allocated, no objects are | |
| 5473 garbage collected, and the state of objects (including | |
| 5474 held values) does not change. | |
| 5475 As a result, threads executing Java | |
| 5476 programming language code, threads attempting to resume the | |
| 5477 execution of Java programming language code, and threads | |
| 5478 attempting to execute JNI functions are typically stalled. | |
| 5479 </description> | |
| 5480 <origin>new</origin> | |
| 5481 <capabilities> | |
| 5482 <required id="can_tag_objects"></required> | |
| 5483 </capabilities> | |
| 5484 <parameters> | |
| 5485 <param id="object_filter"> | |
| 5486 <enum>jvmtiHeapObjectFilter</enum> | |
| 5487 <description> | |
| 5488 Indicates the objects for which the callback function is called. | |
| 5489 </description> | |
| 5490 </param> | |
| 5491 <param id="heap_object_callback"> | |
| 5492 <ptrtype> | |
| 5493 <struct>jvmtiHeapObjectCallback</struct> | |
| 5494 </ptrtype> | |
| 5495 <description> | |
| 5496 The iterator function to be called for each | |
| 5497 object matching the <paramlink id="object_filter"/>. | |
| 5498 </description> | |
| 5499 </param> | |
| 5500 <param id="user_data"> | |
| 5501 <inbuf> | |
| 5502 <void/> | |
| 5503 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5504 </inbuf> | |
| 5505 <description> | |
| 5506 User supplied data to be passed to the callback. | |
| 5507 </description> | |
| 5508 </param> | |
| 5509 </parameters> | |
| 5510 <errors> | |
| 5511 </errors> | |
| 5512 </function> | |
| 5513 | |
| 5514 <function id="IterateOverInstancesOfClass" num="112"> | |
| 5515 <synopsis>Iterate Over Instances Of Class</synopsis> | |
| 5516 <description> | |
| 5517 Iterate over all objects in the heap that are instances of the specified class. | |
| 5518 This includes direct instances of the specified class and | |
| 5519 instances of all subclasses of the specified class. | |
| 5520 This includes both reachable and unreachable objects. | |
| 5521 <p/> | |
| 5522 The <paramlink id="object_filter"></paramlink> parameter indicates the | |
| 5523 objects for which the callback function is called. If this parameter | |
| 5524 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be | |
| 5525 called for every object that is tagged. If the parameter is | |
| 5526 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be | |
| 5527 called for objects that are not tagged. If the parameter | |
| 5528 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be | |
| 5529 called for every object in the heap, irrespective of whether it is | |
| 5530 tagged or not. | |
| 5531 <p/> | |
| 5532 During the execution of this function the state of the heap | |
| 5533 does not change: no objects are allocated, no objects are | |
| 5534 garbage collected, and the state of objects (including | |
| 5535 held values) does not change. | |
| 5536 As a result, threads executing Java | |
| 5537 programming language code, threads attempting to resume the | |
| 5538 execution of Java programming language code, and threads | |
| 5539 attempting to execute JNI functions are typically stalled. | |
| 5540 </description> | |
| 5541 <origin>new</origin> | |
| 5542 <capabilities> | |
| 5543 <required id="can_tag_objects"></required> | |
| 5544 </capabilities> | |
| 5545 <parameters> | |
| 5546 <param id="klass"> | |
| 5547 <jclass/> | |
| 5548 <description> | |
| 5549 Iterate over objects of this class only. | |
| 5550 </description> | |
| 5551 </param> | |
| 5552 <param id="object_filter"> | |
| 5553 <enum>jvmtiHeapObjectFilter</enum> | |
| 5554 <description> | |
| 5555 Indicates the objects for which the callback function is called. | |
| 5556 </description> | |
| 5557 </param> | |
| 5558 <param id="heap_object_callback"> | |
| 5559 <ptrtype> | |
| 5560 <struct>jvmtiHeapObjectCallback</struct> | |
| 5561 </ptrtype> | |
| 5562 <description> | |
| 5563 The iterator function to be called for each | |
| 5564 <paramlink id="klass"/> instance matching | |
| 5565 the <paramlink id="object_filter"/>. | |
| 5566 </description> | |
| 5567 </param> | |
| 5568 <param id="user_data"> | |
| 5569 <inbuf> | |
| 5570 <void/> | |
| 5571 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5572 </inbuf> | |
| 5573 <description> | |
| 5574 User supplied data to be passed to the callback. | |
| 5575 </description> | |
| 5576 </param> | |
| 5577 </parameters> | |
| 5578 <errors> | |
| 5579 </errors> | |
| 5580 </function> | |
| 5581 | |
| 5582 </category> | |
| 5583 | |
| 5584 <category id="local" label="Local Variable"> | |
| 5585 | |
| 5586 <intro> | |
| 5587 These functions are used to retrieve or set the value of a local variable. | |
| 5588 The variable is identified by the depth of the frame containing its | |
| 5589 value and the variable's slot number within that frame. | |
| 5590 The mapping of variables to | |
| 5591 slot numbers can be obtained with the function | |
| 5592 <functionlink id="GetLocalVariableTable"></functionlink>. | |
| 5593 </intro> | |
| 5594 | |
| 5595 <function id="GetLocalObject" num="21"> | |
| 5596 <synopsis>Get Local Variable - Object</synopsis> | |
| 5597 <description> | |
| 5598 This function can be used to retrieve the value of a local | |
| 5599 variable whose type is <code>Object</code> or a subclass of <code>Object</code>. | |
| 5600 </description> | |
| 5601 <origin>jvmdi</origin> | |
| 5602 <capabilities> | |
| 5603 <required id="can_access_local_variables"></required> | |
| 5604 </capabilities> | |
| 5605 <parameters> | |
| 5606 <param id="thread"> | |
| 5607 <jthread null="current" frame="frame"/> | |
| 5608 <description> | |
| 5609 The thread of the frame containing the variable's value. | |
| 5610 </description> | |
| 5611 </param> | |
| 5612 <param id="depth"> | |
| 5613 <jframeID thread="thread"/> | |
| 5614 <description> | |
| 5615 The depth of the frame containing the variable's value. | |
| 5616 </description> | |
| 5617 </param> | |
| 5618 <param id="slot"> | |
| 5619 <jint/> | |
| 5620 <description> | |
| 5621 The variable's slot number. | |
| 5622 </description> | |
| 5623 </param> | |
| 5624 <param id="value_ptr"> | |
| 5625 <outptr><jobject/></outptr> | |
| 5626 <description> | |
| 5627 On return, points to the variable's value. | |
| 5628 </description> | |
| 5629 </param> | |
| 5630 </parameters> | |
| 5631 <errors> | |
| 5632 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5633 Invalid <code>slot</code>. | |
| 5634 </error> | |
| 5635 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5636 The variable type is not | |
| 5637 <code>Object</code> or a subclass of <code>Object</code>. | |
| 5638 </error> | |
| 5639 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5640 Not a visible frame | |
| 5641 </error> | |
| 5642 </errors> | |
| 5643 </function> | |
| 5644 | |
| 2019 | 5645 <function id="GetLocalInstance" num="155" since="1.2"> |
| 5646 <synopsis>Get Local Instance</synopsis> | |
| 5647 <description> | |
| 5648 This function can be used to retrieve the value of the local object | |
| 5649 variable at slot 0 (the "<code>this</code>" object) from non-static | |
| 5650 frames. This function can retrieve the "<code>this</code>" object from | |
| 5651 native method frames, whereas <code>GetLocalObject()</code> would | |
| 5652 return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases. | |
| 5653 </description> | |
| 5654 <origin>new</origin> | |
| 5655 <capabilities> | |
| 5656 <required id="can_access_local_variables"></required> | |
| 5657 </capabilities> | |
| 5658 <parameters> | |
| 5659 <param id="thread"> | |
| 5660 <jthread null="current" frame="frame"/> | |
| 5661 <description> | |
| 5662 The thread of the frame containing the variable's value. | |
| 5663 </description> | |
| 5664 </param> | |
| 5665 <param id="depth"> | |
| 5666 <jframeID thread="thread"/> | |
| 5667 <description> | |
| 5668 The depth of the frame containing the variable's value. | |
| 5669 </description> | |
| 5670 </param> | |
| 5671 <param id="value_ptr"> | |
| 5672 <outptr><jobject/></outptr> | |
| 5673 <description> | |
| 5674 On return, points to the variable's value. | |
| 5675 </description> | |
| 5676 </param> | |
| 5677 </parameters> | |
| 5678 <errors> | |
| 5679 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5680 If the specified frame is a static method frame. | |
| 5681 </error> | |
| 5682 </errors> | |
| 5683 </function> | |
| 0 | 5684 <function id="GetLocalInt" num="22"> |
| 5685 <synopsis>Get Local Variable - Int</synopsis> | |
| 5686 <description> | |
| 5687 This function can be used to retrieve the value of a local | |
| 5688 variable whose type is <code>int</code>, | |
| 5689 <code>short</code>, <code>char</code>, <code>byte</code>, or | |
| 5690 <code>boolean</code>. | |
| 5691 </description> | |
| 5692 <origin>jvmdi</origin> | |
| 5693 <capabilities> | |
| 5694 <required id="can_access_local_variables"></required> | |
| 5695 </capabilities> | |
| 5696 <parameters> | |
| 5697 <param id="thread"> | |
| 5698 <jthread null="current" frame="frame"/> | |
| 5699 <description> | |
| 5700 The thread of the frame containing the variable's value. | |
| 5701 </description> | |
| 5702 </param> | |
| 5703 <param id="depth"> | |
| 5704 <jframeID thread="thread"/> | |
| 5705 <description> | |
| 5706 The depth of the frame containing the variable's value. | |
| 5707 </description> | |
| 5708 </param> | |
| 5709 <param id="slot"> | |
| 5710 <jint/> | |
| 5711 <description> | |
| 5712 The variable's slot number. | |
| 5713 </description> | |
| 5714 </param> | |
| 5715 <param id="value_ptr"> | |
| 5716 <outptr><jint/></outptr> | |
| 5717 <description> | |
| 5718 On return, points to the variable's value. | |
| 5719 </description> | |
| 5720 </param> | |
| 5721 </parameters> | |
| 5722 <errors> | |
| 5723 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5724 Invalid <code>slot</code>. | |
| 5725 </error> | |
| 5726 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5727 The variable type is not | |
| 5728 <code>int</code>, <code>short</code>, | |
| 5729 <code>char</code>, <code>byte</code>, or | |
| 5730 <code>boolean</code>. | |
| 5731 </error> | |
| 5732 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5733 Not a visible frame | |
| 5734 </error> | |
| 5735 </errors> | |
| 5736 </function> | |
| 5737 | |
| 5738 <function id="GetLocalLong" num="23"> | |
| 5739 <synopsis>Get Local Variable - Long</synopsis> | |
| 5740 <description> | |
| 5741 This function can be used to retrieve the value of a local | |
| 5742 variable whose type is <code>long</code>. | |
| 5743 </description> | |
| 5744 <origin>jvmdi</origin> | |
| 5745 <capabilities> | |
| 5746 <required id="can_access_local_variables"></required> | |
| 5747 </capabilities> | |
| 5748 <parameters> | |
| 5749 <param id="thread"> | |
| 5750 <jthread null="current" frame="frame"/> | |
| 5751 <description> | |
| 5752 The thread of the frame containing the variable's value. | |
| 5753 </description> | |
| 5754 </param> | |
| 5755 <param id="depth"> | |
| 5756 <jframeID thread="thread"/> | |
| 5757 <description> | |
| 5758 The depth of the frame containing the variable's value. | |
| 5759 </description> | |
| 5760 </param> | |
| 5761 <param id="slot"> | |
| 5762 <jint/> | |
| 5763 <description> | |
| 5764 The variable's slot number. | |
| 5765 </description> | |
| 5766 </param> | |
| 5767 <param id="value_ptr"> | |
| 5768 <outptr><jlong/></outptr> | |
| 5769 <description> | |
| 5770 On return, points to the variable's value. | |
| 5771 </description> | |
| 5772 </param> | |
| 5773 </parameters> | |
| 5774 <errors> | |
| 5775 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5776 Invalid <code>slot</code>. | |
| 5777 </error> | |
| 5778 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5779 The variable type is not <code>long</code>. | |
| 5780 </error> | |
| 5781 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5782 Not a visible frame | |
| 5783 </error> | |
| 5784 </errors> | |
| 5785 </function> | |
| 5786 | |
| 5787 <function id="GetLocalFloat" num="24"> | |
| 5788 <synopsis>Get Local Variable - Float</synopsis> | |
| 5789 <description> | |
| 5790 This function can be used to retrieve the value of a local | |
| 5791 variable whose type is <code>float</code>. | |
| 5792 </description> | |
| 5793 <origin>jvmdi</origin> | |
| 5794 <capabilities> | |
| 5795 <required id="can_access_local_variables"></required> | |
| 5796 </capabilities> | |
| 5797 <parameters> | |
| 5798 <param id="thread"> | |
| 5799 <jthread null="current" frame="frame"/> | |
| 5800 <description> | |
| 5801 The thread of the frame containing the variable's value. | |
| 5802 </description> | |
| 5803 </param> | |
| 5804 <param id="depth"> | |
| 5805 <jframeID thread="thread"/> | |
| 5806 <description> | |
| 5807 The depth of the frame containing the variable's value. | |
| 5808 </description> | |
| 5809 </param> | |
| 5810 <param id="slot"> | |
| 5811 <jint/> | |
| 5812 <description> | |
| 5813 The variable's slot number. | |
| 5814 </description> | |
| 5815 </param> | |
| 5816 <param id="value_ptr"> | |
| 5817 <outptr><jfloat/></outptr> | |
| 5818 <description> | |
| 5819 On return, points to the variable's value. | |
| 5820 </description> | |
| 5821 </param> | |
| 5822 </parameters> | |
| 5823 <errors> | |
| 5824 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5825 Invalid <code>slot</code>. | |
| 5826 </error> | |
| 5827 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5828 The variable type is not <code>float</code>. | |
| 5829 </error> | |
| 5830 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5831 Not a visible frame | |
| 5832 </error> | |
| 5833 </errors> | |
| 5834 </function> | |
| 5835 | |
| 5836 <function id="GetLocalDouble" num="25"> | |
| 5837 <synopsis>Get Local Variable - Double</synopsis> | |
| 5838 <description> | |
| 5839 This function can be used to retrieve the value of a local | |
| 5840 variable whose type is <code>long</code>. | |
| 5841 </description> | |
| 5842 <origin>jvmdi</origin> | |
| 5843 <capabilities> | |
| 5844 <required id="can_access_local_variables"></required> | |
| 5845 </capabilities> | |
| 5846 <parameters> | |
| 5847 <param id="thread"> | |
| 5848 <jthread null="current" frame="frame"/> | |
| 5849 <description> | |
| 5850 The thread of the frame containing the variable's value. | |
| 5851 </description> | |
| 5852 </param> | |
| 5853 <param id="depth"> | |
| 5854 <jframeID thread="thread"/> | |
| 5855 <description> | |
| 5856 The depth of the frame containing the variable's value. | |
| 5857 </description> | |
| 5858 </param> | |
| 5859 <param id="slot"> | |
| 5860 <jint/> | |
| 5861 <description> | |
| 5862 The variable's slot number. | |
| 5863 </description> | |
| 5864 </param> | |
| 5865 <param id="value_ptr"> | |
| 5866 <outptr><jdouble/></outptr> | |
| 5867 <description> | |
| 5868 On return, points to the variable's value. | |
| 5869 </description> | |
| 5870 </param> | |
| 5871 </parameters> | |
| 5872 <errors> | |
| 5873 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5874 Invalid <code>slot</code>. | |
| 5875 </error> | |
| 5876 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5877 The variable type is not <code>double</code>. | |
| 5878 </error> | |
| 5879 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5880 Not a visible frame | |
| 5881 </error> | |
| 5882 </errors> | |
| 5883 </function> | |
| 5884 | |
| 5885 <function id="SetLocalObject" num="26"> | |
| 5886 <synopsis>Set Local Variable - Object</synopsis> | |
| 5887 <description> | |
| 5888 This function can be used to set the value of a local | |
| 5889 variable whose type is <code>Object</code> or a subclass of <code>Object</code>. | |
| 5890 </description> | |
| 5891 <origin>jvmdi</origin> | |
| 5892 <capabilities> | |
| 5893 <required id="can_access_local_variables"></required> | |
| 5894 </capabilities> | |
| 5895 <parameters> | |
| 5896 <param id="thread"> | |
| 5897 <jthread null="current" frame="frame"/> | |
| 5898 <description> | |
| 5899 The thread of the frame containing the variable's value. | |
| 5900 </description> | |
| 5901 </param> | |
| 5902 <param id="depth"> | |
| 5903 <jframeID thread="thread"/> | |
| 5904 <description> | |
| 5905 The depth of the frame containing the variable's value. | |
| 5906 </description> | |
| 5907 </param> | |
| 5908 <param id="slot"> | |
| 5909 <jint/> | |
| 5910 <description> | |
| 5911 The variable's slot number. | |
| 5912 </description> | |
| 5913 </param> | |
| 5914 <param id="value"> | |
| 5915 <jobject/> | |
| 5916 <description> | |
| 5917 The new value for the variable. | |
| 5918 </description> | |
| 5919 </param> | |
| 5920 </parameters> | |
| 5921 <errors> | |
| 5922 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5923 Invalid <code>slot</code>. | |
| 5924 </error> | |
| 5925 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5926 The variable type is not | |
| 5927 <code>Object</code> or a subclass of <code>Object</code>. | |
| 5928 </error> | |
| 5929 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5930 The supplied <paramlink id="value"/> is not compatible | |
| 5931 with the variable type. | |
| 5932 </error> | |
| 5933 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5934 Not a visible frame | |
| 5935 </error> | |
| 5936 </errors> | |
| 5937 </function> | |
| 5938 | |
| 5939 <function id="SetLocalInt" num="27"> | |
| 5940 <synopsis>Set Local Variable - Int</synopsis> | |
| 5941 <description> | |
| 5942 This function can be used to set the value of a local | |
| 5943 variable whose type is <code>int</code>, | |
| 5944 <code>short</code>, <code>char</code>, <code>byte</code>, or | |
| 5945 <code>boolean</code>. | |
| 5946 </description> | |
| 5947 <origin>jvmdi</origin> | |
| 5948 <capabilities> | |
| 5949 <required id="can_access_local_variables"></required> | |
| 5950 </capabilities> | |
| 5951 <parameters> | |
| 5952 <param id="thread"> | |
| 5953 <jthread null="current" frame="frame"/> | |
| 5954 <description> | |
| 5955 The thread of the frame containing the variable's value. | |
| 5956 </description> | |
| 5957 </param> | |
| 5958 <param id="depth"> | |
| 5959 <jframeID thread="thread"/> | |
| 5960 <description> | |
| 5961 The depth of the frame containing the variable's value. | |
| 5962 </description> | |
| 5963 </param> | |
| 5964 <param id="slot"> | |
| 5965 <jint/> | |
| 5966 <description> | |
| 5967 The variable's slot number. | |
| 5968 </description> | |
| 5969 </param> | |
| 5970 <param id="value"> | |
| 5971 <jint/> | |
| 5972 <description> | |
| 5973 The new value for the variable. | |
| 5974 </description> | |
| 5975 </param> | |
| 5976 </parameters> | |
| 5977 <errors> | |
| 5978 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5979 Invalid <code>slot</code>. | |
| 5980 </error> | |
| 5981 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5982 The variable type is not | |
| 5983 <code>int</code>, <code>short</code>, | |
| 5984 <code>char</code>, <code>byte</code>, or | |
| 5985 <code>boolean</code>. | |
| 5986 </error> | |
| 5987 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5988 Not a visible frame | |
| 5989 </error> | |
| 5990 </errors> | |
| 5991 </function> | |
| 5992 | |
| 5993 <function id="SetLocalLong" num="28"> | |
| 5994 <synopsis>Set Local Variable - Long</synopsis> | |
| 5995 <description> | |
| 5996 This function can be used to set the value of a local | |
| 5997 variable whose type is <code>long</code>. | |
| 5998 </description> | |
| 5999 <origin>jvmdi</origin> | |
| 6000 <capabilities> | |
| 6001 <required id="can_access_local_variables"></required> | |
| 6002 </capabilities> | |
| 6003 <parameters> | |
| 6004 <param id="thread"> | |
| 6005 <jthread null="current" frame="frame"/> | |
| 6006 <description> | |
| 6007 The thread of the frame containing the variable's value. | |
| 6008 </description> | |
| 6009 </param> | |
| 6010 <param id="depth"> | |
| 6011 <jframeID thread="thread"/> | |
| 6012 <description> | |
| 6013 The depth of the frame containing the variable's value. | |
| 6014 </description> | |
| 6015 </param> | |
| 6016 <param id="slot"> | |
| 6017 <jint/> | |
| 6018 <description> | |
| 6019 The variable's slot number. | |
| 6020 </description> | |
| 6021 </param> | |
| 6022 <param id="value"> | |
| 6023 <jlong/> | |
| 6024 <description> | |
| 6025 The new value for the variable. | |
| 6026 </description> | |
| 6027 </param> | |
| 6028 </parameters> | |
| 6029 <errors> | |
| 6030 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6031 Invalid <code>slot</code>. | |
| 6032 </error> | |
| 6033 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6034 The variable type is not <code>long</code>. | |
| 6035 </error> | |
| 6036 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6037 Not a visible frame | |
| 6038 </error> | |
| 6039 </errors> | |
| 6040 </function> | |
| 6041 | |
| 6042 <function id="SetLocalFloat" num="29"> | |
| 6043 <synopsis>Set Local Variable - Float</synopsis> | |
| 6044 <description> | |
| 6045 This function can be used to set the value of a local | |
| 6046 variable whose type is <code>float</code>. | |
| 6047 </description> | |
| 6048 <origin>jvmdi</origin> | |
| 6049 <capabilities> | |
| 6050 <required id="can_access_local_variables"></required> | |
| 6051 </capabilities> | |
| 6052 <parameters> | |
| 6053 <param id="thread"> | |
| 6054 <jthread null="current" frame="frame"/> | |
| 6055 <description> | |
| 6056 The thread of the frame containing the variable's value. | |
| 6057 </description> | |
| 6058 </param> | |
| 6059 <param id="depth"> | |
| 6060 <jframeID thread="thread"/> | |
| 6061 <description> | |
| 6062 The depth of the frame containing the variable's value. | |
| 6063 </description> | |
| 6064 </param> | |
| 6065 <param id="slot"> | |
| 6066 <jint/> | |
| 6067 <description> | |
| 6068 The variable's slot number. | |
| 6069 </description> | |
| 6070 </param> | |
| 6071 <param id="value"> | |
| 6072 <jfloat/> | |
| 6073 <description> | |
| 6074 The new value for the variable. | |
| 6075 </description> | |
| 6076 </param> | |
| 6077 </parameters> | |
| 6078 <errors> | |
| 6079 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6080 Invalid <code>slot</code>. | |
| 6081 </error> | |
| 6082 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6083 The variable type is not <code>float</code>. | |
| 6084 </error> | |
| 6085 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6086 Not a visible frame | |
| 6087 </error> | |
| 6088 </errors> | |
| 6089 </function> | |
| 6090 | |
| 6091 <function id="SetLocalDouble" num="30"> | |
| 6092 <synopsis>Set Local Variable - Double</synopsis> | |
| 6093 <description> | |
| 6094 This function can be used to set the value of a local | |
| 6095 variable whose type is <code>double</code>. | |
| 6096 </description> | |
| 6097 <origin>jvmdi</origin> | |
| 6098 <capabilities> | |
| 6099 <required id="can_access_local_variables"></required> | |
| 6100 </capabilities> | |
| 6101 <parameters> | |
| 6102 <param id="thread"> | |
| 6103 <jthread null="current" frame="frame"/> | |
| 6104 <description> | |
| 6105 The thread of the frame containing the variable's value. | |
| 6106 </description> | |
| 6107 </param> | |
| 6108 <param id="depth"> | |
| 6109 <jframeID thread="thread"/> | |
| 6110 <description> | |
| 6111 The depth of the frame containing the variable's value. | |
| 6112 </description> | |
| 6113 </param> | |
| 6114 <param id="slot"> | |
| 6115 <jint/> | |
| 6116 <description> | |
| 6117 The variable's slot number. | |
| 6118 </description> | |
| 6119 </param> | |
| 6120 <param id="value"> | |
| 6121 <jdouble/> | |
| 6122 <description> | |
| 6123 The new value for the variable. | |
| 6124 </description> | |
| 6125 </param> | |
| 6126 </parameters> | |
| 6127 <errors> | |
| 6128 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6129 Invalid <code>slot</code>. | |
| 6130 </error> | |
| 6131 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6132 The variable type is not <code>double</code>. | |
| 6133 </error> | |
| 6134 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6135 Not a visible frame | |
| 6136 </error> | |
| 6137 </errors> | |
| 6138 </function> | |
| 6139 </category> | |
| 6140 | |
| 6141 <category id="breakpointCategory" label="Breakpoint"> | |
| 6142 | |
| 6143 <intro> | |
| 6144 </intro> | |
| 6145 | |
| 6146 <function id="SetBreakpoint" num="38"> | |
| 6147 <synopsis>Set Breakpoint</synopsis> | |
| 6148 <description> | |
| 6149 Set a breakpoint at the instruction indicated by | |
| 6150 <code>method</code> and <code>location</code>. | |
| 6151 An instruction can only have one breakpoint. | |
| 6152 <p/> | |
| 6153 Whenever the designated instruction is about to be executed, a | |
| 6154 <eventlink id="Breakpoint"></eventlink> event is generated. | |
| 6155 </description> | |
| 6156 <origin>jvmdi</origin> | |
| 6157 <capabilities> | |
| 6158 <required id="can_generate_breakpoint_events"></required> | |
| 6159 </capabilities> | |
| 6160 <parameters> | |
| 6161 <param id="klass"> | |
| 6162 <jclass method="method"/> | |
| 6163 <description> | |
| 6164 The class in which to set the breakpoint | |
| 6165 </description> | |
| 6166 </param> | |
| 6167 <param id="method"> | |
| 6168 <jmethodID class="klass"/> | |
| 6169 <description> | |
| 6170 The method in which to set the breakpoint | |
| 6171 </description> | |
| 6172 </param> | |
| 6173 <param id="location"> | |
| 6174 <jlocation/> | |
| 6175 <description> | |
| 6176 the index of the instruction at which to set the breakpoint | |
| 6177 | |
| 6178 </description> | |
| 6179 </param> | |
| 6180 </parameters> | |
| 6181 <errors> | |
| 6182 <error id="JVMTI_ERROR_DUPLICATE"> | |
| 6183 The designated bytecode already has a breakpoint. | |
| 6184 </error> | |
| 6185 </errors> | |
| 6186 </function> | |
| 6187 | |
| 6188 <function id="ClearBreakpoint" num="39"> | |
| 6189 <synopsis>Clear Breakpoint</synopsis> | |
| 6190 <description> | |
| 6191 Clear the breakpoint at the bytecode indicated by | |
| 6192 <code>method</code> and <code>location</code>. | |
| 6193 </description> | |
| 6194 <origin>jvmdi</origin> | |
| 6195 <capabilities> | |
| 6196 <required id="can_generate_breakpoint_events"></required> | |
| 6197 </capabilities> | |
| 6198 <parameters> | |
| 6199 <param id="klass"> | |
| 6200 <jclass method="method"/> | |
| 6201 <description> | |
| 6202 The class in which to clear the breakpoint | |
| 6203 </description> | |
| 6204 </param> | |
| 6205 <param id="method"> | |
| 6206 <jmethodID class="klass"/> | |
| 6207 <description> | |
| 6208 The method in which to clear the breakpoint | |
| 6209 </description> | |
| 6210 </param> | |
| 6211 <param id="location"> | |
| 6212 <jlocation/> | |
| 6213 <description> | |
| 6214 the index of the instruction at which to clear the breakpoint | |
| 6215 </description> | |
| 6216 </param> | |
| 6217 </parameters> | |
| 6218 <errors> | |
| 6219 <error id="JVMTI_ERROR_NOT_FOUND"> | |
| 6220 There's no breakpoint at the designated bytecode. | |
| 6221 </error> | |
| 6222 </errors> | |
| 6223 </function> | |
| 6224 | |
| 6225 </category> | |
| 6226 | |
| 6227 <category id="fieldWatch" label="Watched Field"> | |
| 6228 | |
| 6229 <intro> | |
| 6230 </intro> | |
| 6231 | |
| 6232 <function id="SetFieldAccessWatch" num="41"> | |
| 6233 <synopsis>Set Field Access Watch</synopsis> | |
| 6234 <description> | |
| 6235 Generate a <eventlink id="FieldAccess"></eventlink> event | |
| 6236 when the field specified | |
| 6237 by <code>klass</code> and | |
| 6238 <code>field</code> is about to be accessed. | |
| 6239 An event will be generated for each access of the field | |
| 6240 until it is canceled with | |
| 6241 <functionlink id="ClearFieldAccessWatch"></functionlink>. | |
| 6242 Field accesses from Java programming language code or from JNI code are watched, | |
| 6243 fields modified by other means are not watched. | |
| 6244 Note that <jvmti/> users should be aware that their own field accesses | |
| 6245 will trigger the watch. | |
| 6246 A field can only have one field access watch set. | |
| 6247 Modification of a field is not considered an access--use | |
| 6248 <functionlink id="SetFieldModificationWatch"></functionlink> | |
| 6249 to monitor modifications. | |
| 6250 </description> | |
| 6251 <origin>jvmdi</origin> | |
| 6252 <capabilities> | |
| 6253 <required id="can_generate_field_access_events"></required> | |
| 6254 </capabilities> | |
| 6255 <parameters> | |
| 6256 <param id="klass"> | |
| 6257 <jclass field="field"/> | |
| 6258 <description> | |
| 6259 The class containing the field to watch | |
| 6260 </description> | |
| 6261 </param> | |
| 6262 <param id="field"> | |
| 6263 <jfieldID class="klass"/> | |
| 6264 <description> | |
| 6265 The field to watch | |
| 6266 | |
| 6267 </description> | |
| 6268 </param> | |
| 6269 </parameters> | |
| 6270 <errors> | |
| 6271 <error id="JVMTI_ERROR_DUPLICATE"> | |
| 6272 The designated field is already being watched for accesses. | |
| 6273 </error> | |
| 6274 </errors> | |
| 6275 </function> | |
| 6276 | |
| 6277 <function id="ClearFieldAccessWatch" num="42"> | |
| 6278 <synopsis>Clear Field Access Watch</synopsis> | |
| 6279 <description> | |
| 6280 Cancel a field access watch previously set by | |
| 6281 <functionlink id="SetFieldAccessWatch"></functionlink>, on the | |
| 6282 field specified | |
| 6283 by <code>klass</code> and | |
| 6284 <code>field</code>. | |
| 6285 </description> | |
| 6286 <origin>jvmdi</origin> | |
| 6287 <capabilities> | |
| 6288 <required id="can_generate_field_access_events"></required> | |
| 6289 </capabilities> | |
| 6290 <parameters> | |
| 6291 <param id="klass"> | |
| 6292 <jclass field="field"/> | |
| 6293 <description> | |
| 6294 The class containing the field to watch | |
| 6295 </description> | |
| 6296 </param> | |
| 6297 <param id="field"> | |
| 6298 <jfieldID class="klass"/> | |
| 6299 <description> | |
| 6300 The field to watch | |
| 6301 | |
| 6302 </description> | |
| 6303 </param> | |
| 6304 </parameters> | |
| 6305 <errors> | |
| 6306 <error id="JVMTI_ERROR_NOT_FOUND"> | |
| 6307 The designated field is not being watched for accesses. | |
| 6308 </error> | |
| 6309 </errors> | |
| 6310 </function> | |
| 6311 | |
| 6312 <function id="SetFieldModificationWatch" num="43"> | |
| 6313 <synopsis>Set Field Modification Watch</synopsis> | |
| 6314 <description> | |
| 6315 Generate a <eventlink id="FieldModification"></eventlink> event | |
| 6316 when the field specified | |
| 6317 by <code>klass</code> and | |
| 6318 <code>field</code> is about to be modified. | |
| 6319 An event will be generated for each modification of the field | |
| 6320 until it is canceled with | |
| 6321 <functionlink id="ClearFieldModificationWatch"></functionlink>. | |
| 6322 Field modifications from Java programming language code or from JNI code are watched, | |
| 6323 fields modified by other means are not watched. | |
| 6324 Note that <jvmti/> users should be aware that their own field modifications | |
| 6325 will trigger the watch. | |
| 6326 A field can only have one field modification watch set. | |
| 6327 </description> | |
| 6328 <origin>jvmdi</origin> | |
| 6329 <capabilities> | |
| 6330 <required id="can_generate_field_modification_events"></required> | |
| 6331 </capabilities> | |
| 6332 <parameters> | |
| 6333 <param id="klass"> | |
| 6334 <jclass field="field"/> | |
| 6335 <description> | |
| 6336 The class containing the field to watch | |
| 6337 </description> | |
| 6338 </param> | |
| 6339 <param id="field"> | |
| 6340 <jfieldID class="klass"/> | |
| 6341 <description> | |
| 6342 The field to watch | |
| 6343 | |
| 6344 </description> | |
| 6345 </param> | |
| 6346 </parameters> | |
| 6347 <errors> | |
| 6348 <error id="JVMTI_ERROR_DUPLICATE"> | |
| 6349 The designated field is already being watched for modifications. | |
| 6350 </error> | |
| 6351 </errors> | |
| 6352 </function> | |
| 6353 | |
| 6354 <function id="ClearFieldModificationWatch" num="44"> | |
| 6355 <synopsis>Clear Field Modification Watch</synopsis> | |
| 6356 <description> | |
| 6357 | |
| 6358 Cancel a field modification watch previously set by | |
| 6359 <functionlink id="SetFieldModificationWatch"></functionlink>, on the | |
| 6360 field specified | |
| 6361 by <code>klass</code> and | |
| 6362 <code>field</code>. | |
| 6363 </description> | |
| 6364 <origin>jvmdi</origin> | |
| 6365 <capabilities> | |
| 6366 <required id="can_generate_field_modification_events"></required> | |
| 6367 </capabilities> | |
| 6368 <parameters> | |
| 6369 <param id="klass"> | |
| 6370 <jclass field="field"/> | |
| 6371 <description> | |
| 6372 The class containing the field to watch | |
| 6373 </description> | |
| 6374 </param> | |
| 6375 <param id="field"> | |
| 6376 <jfieldID class="klass"/> | |
| 6377 <description> | |
| 6378 The field to watch | |
| 6379 | |
| 6380 </description> | |
| 6381 </param> | |
| 6382 </parameters> | |
| 6383 <errors> | |
| 6384 <error id="JVMTI_ERROR_NOT_FOUND"> | |
| 6385 The designated field is not being watched for modifications. | |
| 6386 </error> | |
| 6387 </errors> | |
| 6388 </function> | |
| 6389 </category> | |
| 6390 | |
| 6391 <category id="class" label="Class"> | |
| 6392 | |
| 6393 <intro> | |
| 6394 </intro> | |
| 6395 | |
| 6396 <function id="GetLoadedClasses" jkernel="yes" num="78"> | |
| 6397 <synopsis>Get Loaded Classes</synopsis> | |
| 6398 <description> | |
| 6399 Return an array of all classes loaded in the virtual machine. | |
| 6400 The number of classes in the array is returned via | |
| 6401 <code>class_count_ptr</code>, and the array itself via | |
| 6402 <code>classes_ptr</code>. | |
| 6403 <p/> | |
| 6404 Array classes of all types (including arrays of primitive types) are | |
| 6405 included in the returned list. Primitive classes (for example, | |
| 6406 <code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list. | |
| 6407 </description> | |
| 6408 <origin>jvmdi</origin> | |
| 6409 <capabilities> | |
| 6410 </capabilities> | |
| 6411 <parameters> | |
| 6412 <param id="class_count_ptr"> | |
| 6413 <outptr><jint/></outptr> | |
| 6414 <description> | |
| 6415 On return, points to the number of classes. | |
| 6416 </description> | |
| 6417 </param> | |
| 6418 <param id="classes_ptr"> | |
| 6419 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf> | |
| 6420 <description> | |
| 6421 On return, points to an array of references, one | |
| 6422 for each class. | |
| 6423 </description> | |
| 6424 </param> | |
| 6425 </parameters> | |
| 6426 <errors> | |
| 6427 </errors> | |
| 6428 </function> | |
| 6429 | |
| 6430 <function id="GetClassLoaderClasses" jkernel="yes" num="79"> | |
| 6431 <synopsis>Get Classloader Classes</synopsis> | |
| 6432 <description> | |
| 6433 Returns an array of those classes for which this class loader has | |
| 6434 been recorded as an initiating loader. Each | |
| 6435 class in the returned array was created by this class loader, | |
| 6436 either by defining it directly or by delegation to another class loader. | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
6437 See <vmspec chapter="5.3"/>. |
| 0 | 6438 <p/> |
| 6439 For JDK version 1.1 implementations that don't | |
| 6440 recognize the distinction between initiating and defining class loaders, | |
| 6441 this function should return all classes loaded in the virtual machine. | |
| 6442 The number of classes in the array is returned via | |
| 6443 <code>class_count_ptr</code>, and the array itself via | |
| 6444 <code>classes_ptr</code>. | |
| 6445 </description> | |
| 6446 <origin>jvmdi</origin> | |
| 6447 <capabilities> | |
| 6448 </capabilities> | |
| 6449 <parameters> | |
| 6450 <param id="initiating_loader"> | |
| 6451 <ptrtype> | |
| 6452 <jobject/> | |
| 6453 <nullok>the classes initiated by the bootstrap loader will be returned</nullok> | |
| 6454 </ptrtype> | |
| 6455 <description> | |
| 6456 An initiating class loader. | |
| 6457 </description> | |
| 6458 </param> | |
| 6459 <param id="class_count_ptr"> | |
| 6460 <outptr><jint/></outptr> | |
| 6461 <description> | |
| 6462 On return, points to the number of classes. | |
| 6463 </description> | |
| 6464 </param> | |
| 6465 <param id="classes_ptr"> | |
| 6466 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf> | |
| 6467 <description> | |
| 6468 On return, points to an array of references, one | |
| 6469 for each class. | |
| 6470 </description> | |
| 6471 </param> | |
| 6472 </parameters> | |
| 6473 <errors> | |
| 6474 </errors> | |
| 6475 </function> | |
| 6476 | |
| 6477 <function id="GetClassSignature" phase="start" num="48"> | |
| 6478 <synopsis>Get Class Signature</synopsis> | |
| 6479 <description> | |
| 6480 For the class indicated by <code>klass</code>, return the | |
| 6919 | 6481 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16432">JNI |
| 0 | 6482 type signature</externallink> |
| 6483 and the generic signature of the class. | |
| 6484 For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code> | |
| 6485 and <code>int[]</code> is <code>"[I"</code> | |
| 6486 The returned name for primitive classes | |
| 6487 is the type signature character of the corresponding primitive type. | |
| 6488 For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>. | |
| 6489 </description> | |
| 6490 <origin>jvmdiClone</origin> | |
| 6491 <capabilities> | |
| 6492 </capabilities> | |
| 6493 <parameters> | |
| 6494 <param id="klass"> | |
| 6495 <jclass/> | |
| 6496 <description> | |
| 6497 The class to query. | |
| 6498 </description> | |
| 6499 </param> | |
| 6500 <param id="signature_ptr"> | |
| 6501 <allocbuf> | |
| 6502 <char/> | |
| 6503 <nullok>the signature is not returned</nullok> | |
| 6504 </allocbuf> | |
| 6505 <description> | |
| 6506 On return, points to the JNI type signature of the class, encoded as a | |
| 6507 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 6508 </description> | |
| 6509 </param> | |
| 6510 <param id="generic_ptr"> | |
| 6511 <allocbuf> | |
| 6512 <char/> | |
| 6513 <nullok>the generic signature is not returned</nullok> | |
| 6514 </allocbuf> | |
| 6515 <description> | |
| 6516 On return, points to the generic signature of the class, encoded as a | |
| 6517 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 6518 If there is no generic signature attribute for the class, then, | |
| 6519 on return, points to <code>NULL</code>. | |
| 6520 </description> | |
| 6521 </param> | |
| 6522 </parameters> | |
| 6523 <errors> | |
| 6524 </errors> | |
| 6525 </function> | |
| 6526 | |
| 6527 <function id="GetClassStatus" phase="start" num="49"> | |
| 6528 <synopsis>Get Class Status</synopsis> | |
| 6529 <description> | |
| 6530 Get the status of the class. Zero or more of the following bits can be | |
| 6531 set. | |
| 6532 <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits"> | |
| 6533 <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1"> | |
| 6534 Class bytecodes have been verified | |
| 6535 </constant> | |
| 6536 <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2"> | |
| 6537 Class preparation is complete | |
| 6538 </constant> | |
| 6539 <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4"> | |
| 6540 Class initialization is complete. Static initializer has been run. | |
| 6541 </constant> | |
| 6542 <constant id="JVMTI_CLASS_STATUS_ERROR" num="8"> | |
| 6543 Error during initialization makes class unusable | |
| 6544 </constant> | |
| 6545 <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16"> | |
| 6546 Class is an array. If set, all other bits are zero. | |
| 6547 </constant> | |
| 6548 <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32"> | |
| 6549 Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6550 If set, all other bits are zero. | |
| 6551 </constant> | |
| 6552 </constants> | |
| 6553 </description> | |
| 6554 <origin>jvmdi</origin> | |
| 6555 <capabilities> | |
| 6556 </capabilities> | |
| 6557 <parameters> | |
| 6558 <param id="klass"> | |
| 6559 <jclass/> | |
| 6560 <description> | |
| 6561 The class to query. | |
| 6562 </description> | |
| 6563 </param> | |
| 6564 <param id="status_ptr"> | |
| 6565 <outptr><jint/></outptr> | |
| 6566 <description> | |
| 6567 On return, points to the current state of this class as one or | |
| 6568 more of the <internallink id="jvmtiClassStatus">class status flags</internallink>. | |
| 6569 </description> | |
| 6570 </param> | |
| 6571 </parameters> | |
| 6572 <errors> | |
| 6573 </errors> | |
| 6574 </function> | |
| 6575 | |
| 6576 <function id="GetSourceFileName" phase="start" num="50"> | |
| 6577 <synopsis>Get Source File Name</synopsis> | |
| 6578 <description> | |
| 6579 For the class indicated by <code>klass</code>, return the source file | |
| 6580 name via <code>source_name_ptr</code>. The returned string | |
| 6581 is a file name only and never contains a directory name. | |
| 6582 <p/> | |
| 6583 For primitive classes (for example, <code>java.lang.Integer.TYPE</code>) | |
| 6584 and for arrays this function returns | |
| 6585 <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>. | |
| 6586 </description> | |
| 6587 <origin>jvmdi</origin> | |
| 6588 <capabilities> | |
| 6589 <required id="can_get_source_file_name"></required> | |
| 6590 </capabilities> | |
| 6591 <parameters> | |
| 6592 <param id="klass"> | |
| 6593 <jclass/> | |
| 6594 <description> | |
| 6595 The class to query. | |
| 6596 </description> | |
| 6597 </param> | |
| 6598 <param id="source_name_ptr"> | |
| 6599 <allocbuf><char/></allocbuf> | |
| 6600 <description> | |
| 6601 On return, points to the class's source file name, encoded as a | |
| 6602 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 6603 </description> | |
| 6604 </param> | |
| 6605 </parameters> | |
| 6606 <errors> | |
| 6607 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 6608 Class information does not include a source file name. This includes | |
| 6609 cases where the class is an array class or primitive class. | |
| 6610 </error> | |
| 6611 </errors> | |
| 6612 </function> | |
| 6613 | |
| 6614 <function id="GetClassModifiers" phase="start" num="51"> | |
| 6615 <synopsis>Get Class Modifiers</synopsis> | |
| 6616 <description> | |
| 6617 For the class indicated by <code>klass</code>, return the access | |
| 6618 flags | |
| 6619 via <code>modifiers_ptr</code>. | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
6620 Access flags are defined in <vmspec chapter="4"/>. |
| 0 | 6621 <p/> |
| 6622 If the class is an array class, then its public, private, and protected | |
| 6623 modifiers are the same as those of its component type. For arrays of | |
| 6624 primitives, this component type is represented by one of the primitive | |
| 6625 classes (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6626 <p/> | |
| 6627 If the class is a primitive class, its public modifier is always true, | |
| 6628 and its protected and private modifiers are always false. | |
| 6629 <p/> | |
| 6630 If the class is an array class or a primitive class then its final | |
| 6631 modifier is always true and its interface modifier is always false. | |
| 6632 The values of its other modifiers are not determined by this specification. | |
| 6633 | |
| 6634 </description> | |
| 6635 <origin>jvmdi</origin> | |
| 6636 <capabilities> | |
| 6637 </capabilities> | |
| 6638 <parameters> | |
| 6639 <param id="klass"> | |
| 6640 <jclass/> | |
| 6641 <description> | |
| 6642 The class to query. | |
| 6643 </description> | |
| 6644 </param> | |
| 6645 <param id="modifiers_ptr"> | |
| 6646 <outptr><jint/></outptr> | |
| 6647 <description> | |
| 6648 On return, points to the current access flags of this class. | |
| 6649 | |
| 6650 </description> | |
| 6651 </param> | |
| 6652 </parameters> | |
| 6653 <errors> | |
| 6654 </errors> | |
| 6655 </function> | |
| 6656 | |
| 6657 <function id="GetClassMethods" phase="start" num="52"> | |
| 6658 <synopsis>Get Class Methods</synopsis> | |
| 6659 <description> | |
| 6660 For the class indicated by <code>klass</code>, return a count of | |
| 6661 methods via <code>method_count_ptr</code> and a list of | |
| 6662 method IDs via <code>methods_ptr</code>. The method list contains | |
| 6663 constructors and static initializers as well as true methods. | |
| 6664 Only directly declared methods are returned (not inherited methods). | |
| 6665 An empty method list is returned for array classes and primitive classes | |
| 6666 (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6667 </description> | |
| 6668 <origin>jvmdi</origin> | |
| 6669 <capabilities> | |
| 6670 <capability id="can_maintain_original_method_order"/> | |
| 6671 </capabilities> | |
| 6672 <parameters> | |
| 6673 <param id="klass"> | |
| 6674 <jclass/> | |
| 6675 <description> | |
| 6676 The class to query. | |
| 6677 </description> | |
| 6678 </param> | |
| 6679 <param id="method_count_ptr"> | |
| 6680 <outptr><jint/></outptr> | |
| 6681 <description> | |
| 6682 On return, points to the number of methods declared in this class. | |
| 6683 </description> | |
| 6684 </param> | |
| 6685 <param id="methods_ptr"> | |
| 6686 <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf> | |
| 6687 <description> | |
| 6688 On return, points to the method ID array. | |
| 6689 </description> | |
| 6690 </param> | |
| 6691 </parameters> | |
| 6692 <errors> | |
| 6693 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
| 6694 <paramlink id="klass"></paramlink> is not prepared. | |
| 6695 </error> | |
| 6696 </errors> | |
| 6697 </function> | |
| 6698 | |
| 6699 <function id="GetClassFields" phase="start" num="53"> | |
| 6700 <synopsis>Get Class Fields</synopsis> | |
| 6701 <description> | |
| 6702 For the class indicated by <code>klass</code>, return a count of fields | |
| 6703 via <code>field_count_ptr</code> and a list of field IDs via | |
| 6704 <code>fields_ptr</code>. | |
| 6705 Only directly declared fields are returned (not inherited fields). | |
| 6706 Fields are returned in the order they occur in the class file. | |
| 6707 An empty field list is returned for array classes and primitive classes | |
| 6708 (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6709 Use JNI to determine the length of an array. | |
| 6710 </description> | |
| 6711 <origin>jvmdi</origin> | |
| 6712 <capabilities> | |
| 6713 </capabilities> | |
| 6714 <parameters> | |
| 6715 <param id="klass"> | |
| 6716 <jclass/> | |
| 6717 <description> | |
| 6718 The class to query. | |
| 6719 </description> | |
| 6720 </param> | |
| 6721 <param id="field_count_ptr"> | |
| 6722 <outptr><jint/></outptr> | |
| 6723 <description> | |
| 6724 On return, points to the number of fields declared in this class. | |
| 6725 </description> | |
| 6726 </param> | |
| 6727 <param id="fields_ptr"> | |
| 6728 <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf> | |
| 6729 <description> | |
| 6730 On return, points to the field ID array. | |
| 6731 </description> | |
| 6732 </param> | |
| 6733 </parameters> | |
| 6734 <errors> | |
| 6735 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
| 6736 <paramlink id="klass"></paramlink> is not prepared. | |
| 6737 </error> | |
| 6738 </errors> | |
| 6739 </function> | |
| 6740 | |
| 6741 <function id="GetImplementedInterfaces" phase="start" num="54"> | |
| 6742 <synopsis>Get Implemented Interfaces</synopsis> | |
| 6743 <description> | |
| 6744 Return the direct super-interfaces of this class. For a class, this | |
| 6745 function returns the interfaces declared in its <code>implements</code> | |
| 6746 clause. For an interface, this function returns the interfaces declared in | |
| 6747 its <code>extends</code> clause. | |
| 6748 An empty interface list is returned for array classes and primitive classes | |
| 6749 (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6750 </description> | |
| 6751 <origin>jvmdi</origin> | |
| 6752 <capabilities> | |
| 6753 </capabilities> | |
| 6754 <parameters> | |
| 6755 <param id="klass"> | |
| 6756 <jclass/> | |
| 6757 <description> | |
| 6758 The class to query. | |
| 6759 </description> | |
| 6760 </param> | |
| 6761 <param id="interface_count_ptr"> | |
| 6762 <outptr><jint/></outptr> | |
| 6763 <description> | |
| 6764 On return, points to the number of interfaces. | |
| 6765 </description> | |
| 6766 </param> | |
| 6767 <param id="interfaces_ptr"> | |
| 6768 <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf> | |
| 6769 <description> | |
| 6770 On return, points to the interface array. | |
| 6771 </description> | |
| 6772 </param> | |
| 6773 </parameters> | |
| 6774 <errors> | |
| 6775 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
| 6776 <paramlink id="klass"></paramlink> is not prepared. | |
| 6777 </error> | |
| 6778 </errors> | |
| 6779 </function> | |
| 6780 | |
| 6781 <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1"> | |
| 6782 <synopsis>Get Class Version Numbers</synopsis> | |
| 6783 <description> | |
| 6784 For the class indicated by <code>klass</code>, | |
| 6785 return the minor and major version numbers, | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
6786 as defined in |
|
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
6787 <vmspec chapter="4"/>. |
| 0 | 6788 </description> |
| 6789 <origin>new</origin> | |
| 6790 <capabilities> | |
| 6791 </capabilities> | |
| 6792 <parameters> | |
| 6793 <param id="klass"> | |
| 6794 <jclass/> | |
| 6795 <description> | |
| 6796 The class to query. | |
| 6797 </description> | |
| 6798 </param> | |
| 6799 <param id="minor_version_ptr"> | |
| 6800 <outptr><jint/></outptr> | |
| 6801 <description> | |
| 6802 On return, points to the value of the | |
| 6803 <code>minor_version</code> item of the | |
| 6804 Class File Format. | |
| 6805 Note: to be consistent with the Class File Format, | |
| 6806 the minor version number is the first parameter. | |
| 6807 </description> | |
| 6808 </param> | |
| 6809 <param id="major_version_ptr"> | |
| 6810 <outptr><jint/></outptr> | |
| 6811 <description> | |
| 6812 On return, points to the value of the | |
| 6813 <code>major_version</code> item of the | |
| 6814 Class File Format. | |
| 6815 </description> | |
| 6816 </param> | |
| 6817 </parameters> | |
| 6818 <errors> | |
| 6819 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 6820 The class is a primitive or array class. | |
| 6821 </error> | |
| 6822 </errors> | |
| 6823 </function> | |
| 6824 | |
| 6825 <function id="GetConstantPool" phase="start" num="146" since="1.1"> | |
| 6826 <synopsis>Get Constant Pool</synopsis> | |
| 6827 <description> | |
| 6828 For the class indicated by <code>klass</code>, | |
| 6829 return the raw bytes of the constant pool in the format of the | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
6830 <code>constant_pool</code> item of |
|
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
6831 <vmspec chapter="4"/>. |
| 0 | 6832 The format of the constant pool may differ between versions |
| 6833 of the Class File Format, so, the | |
| 6834 <functionlink id="GetClassVersionNumbers">minor and major | |
| 6835 class version numbers</functionlink> should be checked for | |
| 6836 compatibility. | |
| 6837 <p/> | |
| 6838 The returned constant pool might not have the same layout or | |
| 6839 contents as the constant pool in the defining class file. | |
| 6840 The constant pool returned by GetConstantPool() may have | |
| 6841 more or fewer entries than the defining constant pool. | |
| 6842 Entries may be in a different order. | |
| 6843 The constant pool returned by GetConstantPool() will match the | |
| 6844 constant pool used by | |
| 6845 <functionlink id="GetBytecodes">GetBytecodes()</functionlink>. | |
| 6846 That is, the bytecodes returned by GetBytecodes() will have | |
| 6847 constant pool indices which refer to constant pool entries returned | |
| 6848 by GetConstantPool(). | |
| 6849 Note that since <functionlink id="RetransformClasses"/> | |
| 6850 and <functionlink id="RedefineClasses"/> can change | |
| 6851 the constant pool, the constant pool returned by this function | |
| 6852 can change accordingly. Thus, the correspondence between | |
| 6853 GetConstantPool() and GetBytecodes() does not hold if there | |
| 6854 is an intervening class retransformation or redefinition. | |
| 6855 The value of a constant pool entry used by a given bytecode will | |
| 6856 match that of the defining class file (even if the indices don't match). | |
| 6857 Constant pool entries which are not used directly or indirectly by | |
| 6858 bytecodes (for example, UTF-8 strings associated with annotations) are | |
| 6859 not required to exist in the returned constant pool. | |
| 6860 </description> | |
| 6861 <origin>new</origin> | |
| 6862 <capabilities> | |
| 6863 <required id="can_get_constant_pool"></required> | |
| 6864 </capabilities> | |
| 6865 <parameters> | |
| 6866 <param id="klass"> | |
| 6867 <jclass/> | |
| 6868 <description> | |
| 6869 The class to query. | |
| 6870 </description> | |
| 6871 </param> | |
| 6872 <param id="constant_pool_count_ptr"> | |
| 6873 <outptr><jint/></outptr> | |
| 6874 <description> | |
| 6875 On return, points to the number of entries | |
| 6876 in the constant pool table plus one. | |
| 6877 This corresponds to the <code>constant_pool_count</code> | |
| 6878 item of the Class File Format. | |
| 6879 </description> | |
| 6880 </param> | |
| 6881 <param id="constant_pool_byte_count_ptr"> | |
| 6882 <outptr><jint/></outptr> | |
| 6883 <description> | |
| 6884 On return, points to the number of bytes | |
| 6885 in the returned raw constant pool. | |
| 6886 </description> | |
| 6887 </param> | |
| 6888 <param id="constant_pool_bytes_ptr"> | |
| 6889 <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf> | |
| 6890 <description> | |
| 6891 On return, points to the raw constant pool, that is the bytes | |
| 6892 defined by the <code>constant_pool</code> item of the | |
| 6893 Class File Format | |
| 6894 </description> | |
| 6895 </param> | |
| 6896 </parameters> | |
| 6897 <errors> | |
| 6898 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 6899 The class is a primitive or array class. | |
| 6900 </error> | |
| 6901 </errors> | |
| 6902 </function> | |
| 6903 | |
| 6904 <function id="IsInterface" phase="start" num="55"> | |
| 6905 <synopsis>Is Interface</synopsis> | |
| 6906 <description> | |
| 6907 Determines whether a class object reference represents an interface. | |
| 6908 The <code>jboolean</code> result is | |
| 6909 <code>JNI_TRUE</code> if the "class" is actually an interface, | |
| 6910 <code>JNI_FALSE</code> otherwise. | |
| 6911 </description> | |
| 6912 <origin>jvmdi</origin> | |
| 6913 <capabilities> | |
| 6914 </capabilities> | |
| 6915 <parameters> | |
| 6916 <param id="klass"> | |
| 6917 <jclass/> | |
| 6918 <description> | |
| 6919 The class to query. | |
| 6920 </description> | |
| 6921 </param> | |
| 6922 <param id="is_interface_ptr"> | |
| 6923 <outptr><jboolean/></outptr> | |
| 6924 <description> | |
| 6925 On return, points to the boolean result of this function. | |
| 6926 | |
| 6927 </description> | |
| 6928 </param> | |
| 6929 </parameters> | |
| 6930 <errors> | |
| 6931 </errors> | |
| 6932 </function> | |
| 6933 | |
| 6934 <function id="IsArrayClass" phase="start" num="56"> | |
| 6935 <synopsis>Is Array Class</synopsis> | |
| 6936 <description> | |
| 6937 Determines whether a class object reference represents an array. | |
| 6938 The <code>jboolean</code> result is | |
| 6939 <code>JNI_TRUE</code> if the class is an array, | |
| 6940 <code>JNI_FALSE</code> otherwise. | |
| 6941 </description> | |
| 6942 <origin>jvmdi</origin> | |
| 6943 <capabilities> | |
| 6944 </capabilities> | |
| 6945 <parameters> | |
| 6946 <param id="klass"> | |
| 6947 <jclass/> | |
| 6948 <description> | |
| 6949 The class to query. | |
| 6950 </description> | |
| 6951 </param> | |
| 6952 <param id="is_array_class_ptr"> | |
| 6953 <outptr><jboolean/></outptr> | |
| 6954 <description> | |
| 6955 On return, points to the boolean result of this function. | |
| 6956 | |
| 6957 </description> | |
| 6958 </param> | |
| 6959 </parameters> | |
| 6960 <errors> | |
| 6961 </errors> | |
| 6962 </function> | |
| 6963 | |
| 6964 <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1"> | |
| 6965 <synopsis>Is Modifiable Class</synopsis> | |
| 6966 <description> | |
| 6967 Determines whether a class is modifiable. | |
| 6968 If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/> | |
| 6969 returns <code>JNI_TRUE</code>) the class can be | |
| 6970 redefined with <functionlink id="RedefineClasses"/> (assuming | |
| 6971 the agent possesses the | |
| 6972 <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/> | |
| 6973 capability) or | |
| 6974 retransformed with <functionlink id="RetransformClasses"/> (assuming | |
| 6975 the agent possesses the | |
| 6976 <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> | |
| 6977 capability). | |
| 6978 If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/> | |
| 6979 returns <code>JNI_FALSE</code>) the class can be neither | |
| 6980 redefined nor retransformed. | |
| 6981 <p/> | |
| 6982 Primitive classes (for example, <code>java.lang.Integer.TYPE</code>) | |
| 6983 and array classes are never modifiable. | |
| 6984 <p/> | |
| 6985 </description> | |
| 6986 <origin>new</origin> | |
| 6987 <capabilities> | |
| 6988 <capability id="can_redefine_any_class"> | |
| 6989 If possessed then all classes (except primitive and array classes) | |
| 6990 are modifiable. | |
| 6991 </capability> | |
| 6992 <capability id="can_redefine_classes"> | |
| 6993 No effect on the result of the function. | |
| 6994 But must additionally be possessed to modify the class with | |
| 6995 <functionlink id="RedefineClasses"/>. | |
| 6996 </capability> | |
| 6997 <capability id="can_retransform_classes"> | |
| 6998 No effect on the result of the function. | |
| 6999 But must additionally be possessed to modify the class with | |
| 7000 <functionlink id="RetransformClasses"/>. | |
| 7001 </capability> | |
| 7002 </capabilities> | |
| 7003 <parameters> | |
| 7004 <param id="klass"> | |
| 7005 <jclass/> | |
| 7006 <description> | |
| 7007 The class to query. | |
| 7008 </description> | |
| 7009 </param> | |
| 7010 <param id="is_modifiable_class_ptr"> | |
| 7011 <outptr><jboolean/></outptr> | |
| 7012 <description> | |
| 7013 On return, points to the boolean result of this function. | |
| 7014 </description> | |
| 7015 </param> | |
| 7016 </parameters> | |
| 7017 <errors> | |
| 7018 </errors> | |
| 7019 </function> | |
| 7020 | |
| 7021 <function id="GetClassLoader" phase="start" num="57"> | |
| 7022 <synopsis>Get Class Loader</synopsis> | |
| 7023 <description> | |
| 7024 For the class indicated by <code>klass</code>, return via | |
| 7025 <code>classloader_ptr</code> a reference to the class loader for the | |
| 7026 class. | |
| 7027 </description> | |
| 7028 <origin>jvmdi</origin> | |
| 7029 <capabilities> | |
| 7030 </capabilities> | |
| 7031 <parameters> | |
| 7032 <param id="klass"> | |
| 7033 <jclass/> | |
| 7034 <description> | |
| 7035 The class to query. | |
| 7036 </description> | |
| 7037 </param> | |
| 7038 <param id="classloader_ptr"> | |
| 7039 <outptr><jobject/></outptr> | |
| 7040 <description> | |
| 7041 On return, points to the class loader that loaded | |
| 7042 this class. | |
| 7043 If the class was not created by a class loader | |
| 7044 or if the class loader is the bootstrap class loader, | |
| 7045 points to <code>NULL</code>. | |
| 7046 </description> | |
| 7047 </param> | |
| 7048 </parameters> | |
| 7049 <errors> | |
| 7050 </errors> | |
| 7051 | |
| 7052 </function> | |
| 7053 | |
| 7054 <function id="GetSourceDebugExtension" phase="start" num="90"> | |
| 7055 <synopsis>Get Source Debug Extension</synopsis> | |
| 7056 <description> | |
| 7057 For the class indicated by <code>klass</code>, return the debug | |
| 7058 extension via <code>source_debug_extension_ptr</code>. | |
| 7059 The returned string | |
| 7060 contains exactly the debug extension information present in the | |
| 7061 class file of <code>klass</code>. | |
| 7062 </description> | |
| 7063 <origin>jvmdi</origin> | |
| 7064 <capabilities> | |
| 7065 <required id="can_get_source_debug_extension"></required> | |
| 7066 </capabilities> | |
| 7067 <parameters> | |
| 7068 <param id="klass"> | |
| 7069 <jclass/> | |
| 7070 <description> | |
| 7071 The class to query. | |
| 7072 </description> | |
| 7073 </param> | |
| 7074 <param id="source_debug_extension_ptr"> | |
| 7075 <allocbuf><char/></allocbuf> | |
| 7076 <description> | |
| 7077 On return, points to the class's debug extension, encoded as a | |
| 7078 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7079 </description> | |
| 7080 </param> | |
| 7081 </parameters> | |
| 7082 <errors> | |
| 7083 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 7084 Class information does not include a debug extension. | |
| 7085 </error> | |
| 7086 </errors> | |
| 7087 </function> | |
| 7088 | |
| 7089 <function id="RetransformClasses" jkernel="yes" num="152" since="1.1"> | |
| 7090 <synopsis>Retransform Classes</synopsis> | |
| 7091 <description> | |
| 7092 This function facilitates the | |
| 7093 <internallink id="bci">bytecode instrumentation</internallink> | |
| 7094 of already loaded classes. | |
| 7095 To replace the class definition without reference to the existing | |
| 7096 bytecodes, as one might do when recompiling from source for | |
| 7097 fix-and-continue debugging, <functionlink id="RedefineClasses"/> | |
| 7098 function should be used instead. | |
| 7099 <p/> | |
| 7100 When classes are initially loaded or when they are | |
| 7101 <functionlink id="RedefineClasses">redefined</functionlink>, | |
| 7102 the initial class file bytes can be transformed with the | |
| 7103 <eventlink id="ClassFileLoadHook"/> event. | |
| 7104 This function reruns the transformation process | |
| 7105 (whether or not a transformation has previously occurred). | |
| 7106 This retransformation follows these steps: | |
| 7107 <ul> | |
| 7108 <li>starting from the initial class file bytes | |
| 7109 </li> | |
| 7110 <li>for each <fieldlink id="can_retransform_classes" | |
| 7111 struct="jvmtiCapabilities">retransformation | |
| 7112 incapable</fieldlink> | |
| 7113 agent which received a | |
| 7114 <code>ClassFileLoadHook</code> event during the previous | |
| 7115 load or redefine, the bytes it returned | |
| 7116 (via the <code>new_class_data</code> parameter) | |
| 7117 are reused as the output of the transformation; | |
| 7118 note that this is equivalent to reapplying | |
| 7119 the previous transformation, unaltered. except that | |
| 7120 the <code>ClassFileLoadHook</code> event | |
| 7121 is <b>not</b> sent to these agents | |
| 7122 </li> | |
| 7123 <li>for each <fieldlink id="can_retransform_classes" | |
| 7124 struct="jvmtiCapabilities">retransformation | |
| 7125 capable</fieldlink> | |
| 7126 agent, the <code>ClassFileLoadHook</code> event is sent, | |
| 7127 allowing a new transformation to be applied | |
| 7128 </li> | |
| 7129 <li>the transformed class file bytes are installed as the new | |
| 7130 definition of the class | |
| 7131 </li> | |
| 7132 </ul> | |
| 7133 See the <eventlink id="ClassFileLoadHook"/> event for more details. | |
| 7134 <p/> | |
| 7135 The initial class file bytes represent the bytes passed to | |
| 7136 <code>ClassLoader.defineClass</code> | |
| 7137 or <code>RedefineClasses</code> (before any transformations | |
| 7138 were applied), however they may not exactly match them. | |
| 7139 The constant pool may differ in ways described in | |
| 7140 <functionlink id="GetConstantPool"/>. | |
| 7141 Constant pool indices in the bytecodes of methods will correspond. | |
| 7142 Some attributes may not be present. | |
| 7143 Where order is not meaningful, for example the order of methods, | |
| 7144 order may not be preserved. | |
| 7145 <p/> | |
| 7146 Retransformation can cause new versions of methods to be installed. | |
| 7147 Old method versions may become | |
| 7148 <internallink id="obsoleteMethods">obsolete</internallink> | |
| 7149 The new method version will be used on new invokes. | |
| 7150 If a method has active stack frames, those active frames continue to | |
| 7151 run the bytecodes of the original method version. | |
| 7152 <p/> | |
| 7153 This function does not cause any initialization except that which | |
| 7154 would occur under the customary JVM semantics. | |
| 7155 In other words, retransforming a class does not cause its initializers to be | |
| 7156 run. The values of static fields will remain as they were | |
| 7157 prior to the call. | |
| 7158 <p/> | |
| 7159 Threads need not be suspended. | |
| 7160 <p/> | |
| 7161 All breakpoints in the class are cleared. | |
| 7162 <p/> | |
| 7163 All attributes are updated. | |
| 7164 <p/> | |
| 7165 Instances of the retransformed class are not affected -- fields retain their | |
| 7166 previous values. | |
| 7167 <functionlink id="GetTag">Tags</functionlink> on the instances are | |
| 7168 also unaffected. | |
| 7169 <p/> | |
| 7170 In response to this call, no events other than the | |
| 7171 <eventlink id="ClassFileLoadHook"/> event | |
| 7172 will be sent. | |
| 7173 <p/> | |
| 7174 The retransformation may change method bodies, the constant pool and attributes. | |
| 7175 The retransformation must not add, remove or rename fields or methods, change the | |
| 7176 signatures of methods, change modifiers, or change inheritance. | |
| 7177 These restrictions may be lifted in future versions. | |
| 7178 See the error return description below for information on error codes | |
| 7179 returned if an unsupported retransformation is attempted. | |
| 7180 The class file bytes are not verified or installed until they have passed | |
| 7181 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the | |
| 7182 returned error code reflects the result of the transformations. | |
| 7183 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, | |
| 7184 none of the classes to be retransformed will have a new definition installed. | |
| 7185 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) | |
| 7186 all of the classes to be retransformed will have their new definitions installed. | |
| 7187 </description> | |
| 7188 <origin>new</origin> | |
| 7189 <capabilities> | |
| 7190 <required id="can_retransform_classes"></required> | |
| 7191 <capability id="can_retransform_any_class"></capability> | |
| 7192 </capabilities> | |
| 7193 <parameters> | |
| 7194 <param id="class_count"> | |
| 7195 <jint min="0"/> | |
| 7196 <description> | |
| 7197 The number of classes to be retransformed. | |
| 7198 </description> | |
| 7199 </param> | |
| 7200 <param id="classes"> | |
| 7201 <inbuf incount="class_count"><jclass/></inbuf> | |
| 7202 <description> | |
| 7203 The array of classes to be retransformed. | |
| 7204 </description> | |
| 7205 </param> | |
| 7206 </parameters> | |
| 7207 <errors> | |
| 7208 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> | |
| 7209 One of the <paramlink id="classes"/> cannot be modified. | |
| 7210 See <functionlink id="IsModifiableClass"/>. | |
| 7211 </error> | |
| 7212 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 7213 One of the <paramlink id="classes"/> is not a valid class. | |
| 7214 </error> | |
| 7215 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> | |
| 7216 A retransformed class file has a version number not supported by this VM. | |
| 7217 </error> | |
| 7218 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> | |
| 7219 A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>). | |
| 7220 </error> | |
| 7221 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> | |
| 7222 The retransformed class file definitions would lead to a circular definition | |
| 7223 (the VM would return a <code>ClassCircularityError</code>). | |
| 7224 </error> | |
| 7225 <error id="JVMTI_ERROR_FAILS_VERIFICATION"> | |
| 7226 The retransformed class file bytes fail verification. | |
| 7227 </error> | |
| 7228 <error id="JVMTI_ERROR_NAMES_DONT_MATCH"> | |
| 7229 The class name defined in a retransformed class file is | |
| 7230 different from the name in the old class object. | |
| 7231 </error> | |
| 7232 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> | |
| 7233 A retransformed class file would require adding a method. | |
| 7234 </error> | |
| 7235 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> | |
| 7236 A retransformed class file changes a field. | |
| 7237 </error> | |
| 7238 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> | |
| 7239 A direct superclass is different for a retransformed class file, | |
| 7240 or the set of directly implemented | |
| 7241 interfaces is different. | |
| 7242 </error> | |
| 7243 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> | |
| 7244 A retransformed class file does not declare a method | |
| 7245 declared in the old class version. | |
| 7246 </error> | |
| 7247 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> | |
| 7248 A retransformed class file has different class modifiers. | |
| 7249 </error> | |
| 7250 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> | |
| 7251 A method in the retransformed class file has different modifiers | |
| 7252 than its counterpart in the old class version. | |
| 7253 </error> | |
| 7254 </errors> | |
| 7255 </function> | |
| 7256 | |
| 7257 <function id="RedefineClasses" jkernel="yes" num="87"> | |
| 7258 <synopsis>Redefine Classes</synopsis> | |
| 7259 <typedef id="jvmtiClassDefinition" label="Class redefinition description"> | |
| 7260 <field id="klass"> | |
| 7261 <jclass/> | |
| 7262 <description> | |
| 7263 Class object for this class | |
| 7264 </description> | |
| 7265 </field> | |
| 7266 <field id="class_byte_count"> | |
| 7267 <jint/> | |
| 7268 <description> | |
| 7269 Number of bytes defining class (below) | |
| 7270 </description> | |
| 7271 </field> | |
| 7272 <field id="class_bytes"> | |
| 7273 <inbuf incount="class_byte_count"><uchar/></inbuf> | |
| 7274 <description> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7275 Bytes defining class (in <vmspec chapter="4"/>) |
| 0 | 7276 </description> |
| 7277 </field> | |
| 7278 </typedef> | |
| 7279 <description> | |
| 7280 All classes given are redefined according to the definitions | |
| 7281 supplied. | |
| 7282 This function is used to replace the definition of a class | |
| 7283 with a new definition, as might be needed in fix-and-continue | |
| 7284 debugging. | |
| 7285 Where the existing class file bytes are to be transformed, for | |
| 7286 example in | |
| 7287 <internallink id="bci">bytecode instrumentation</internallink>, | |
| 7288 <functionlink id="RetransformClasses"/> should be used. | |
| 7289 <p/> | |
| 7290 Redefinition can cause new versions of methods to be installed. | |
| 7291 Old method versions may become | |
| 7292 <internallink id="obsoleteMethods">obsolete</internallink> | |
| 7293 The new method version will be used on new invokes. | |
| 7294 If a method has active stack frames, those active frames continue to | |
| 7295 run the bytecodes of the original method version. | |
| 7296 If resetting of stack frames is desired, use | |
| 7297 <functionlink id="PopFrame"></functionlink> | |
| 7298 to pop frames with obsolete method versions. | |
| 7299 <p/> | |
| 7300 This function does not cause any initialization except that which | |
| 7301 would occur under the customary JVM semantics. | |
| 7302 In other words, redefining a class does not cause its initializers to be | |
| 7303 run. The values of static fields will remain as they were | |
| 7304 prior to the call. | |
| 7305 <p/> | |
| 7306 Threads need not be suspended. | |
| 7307 <p/> | |
| 7308 All breakpoints in the class are cleared. | |
| 7309 <p/> | |
| 7310 All attributes are updated. | |
| 7311 <p/> | |
| 7312 Instances of the redefined class are not affected -- fields retain their | |
| 7313 previous values. | |
| 7314 <functionlink id="GetTag">Tags</functionlink> on the instances are | |
| 7315 also unaffected. | |
| 7316 <p/> | |
| 7317 In response to this call, the <jvmti/> event | |
| 7318 <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink> | |
| 7319 will be sent (if enabled), but no other <jvmti/> events will be sent. | |
| 7320 <p/> | |
| 7321 The redefinition may change method bodies, the constant pool and attributes. | |
| 7322 The redefinition must not add, remove or rename fields or methods, change the | |
| 7323 signatures of methods, change modifiers, or change inheritance. | |
| 7324 These restrictions may be lifted in future versions. | |
| 7325 See the error return description below for information on error codes | |
| 7326 returned if an unsupported redefinition is attempted. | |
| 7327 The class file bytes are not verified or installed until they have passed | |
| 7328 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the | |
| 7329 returned error code reflects the result of the transformations applied | |
| 7330 to the bytes passed into <paramlink id="class_definitions"/>. | |
| 7331 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, | |
| 7332 none of the classes to be redefined will have a new definition installed. | |
| 7333 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) | |
| 7334 all of the classes to be redefined will have their new definitions installed. | |
| 7335 </description> | |
| 7336 <origin>jvmdi</origin> | |
| 7337 <capabilities> | |
| 7338 <required id="can_redefine_classes"></required> | |
| 7339 <capability id="can_redefine_any_class"></capability> | |
| 7340 </capabilities> | |
| 7341 <parameters> | |
| 7342 <param id="class_count"> | |
| 7343 <jint min="0"/> | |
| 7344 <description> | |
| 7345 The number of classes specified in <code>class_definitions</code> | |
| 7346 </description> | |
| 7347 </param> | |
| 7348 <param id="class_definitions"> | |
| 7349 <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf> | |
| 7350 <description> | |
| 7351 The array of new class definitions | |
| 7352 </description> | |
| 7353 </param> | |
| 7354 </parameters> | |
| 7355 <errors> | |
| 7356 <error id="JVMTI_ERROR_NULL_POINTER"> | |
| 7357 One of <code>class_bytes</code> is <code>NULL</code>. | |
| 7358 </error> | |
| 7359 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> | |
| 7360 An element of <code>class_definitions</code> cannot be modified. | |
| 7361 See <functionlink id="IsModifiableClass"/>. | |
| 7362 </error> | |
| 7363 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 7364 An element of <code>class_definitions</code> is not a valid class. | |
| 7365 </error> | |
| 7366 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> | |
| 7367 A new class file has a version number not supported by this VM. | |
| 7368 </error> | |
| 7369 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> | |
| 7370 A new class file is malformed (The VM would return a <code>ClassFormatError</code>). | |
| 7371 </error> | |
| 7372 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> | |
| 7373 The new class file definitions would lead to a circular definition | |
| 7374 (the VM would return a <code>ClassCircularityError</code>). | |
| 7375 </error> | |
| 7376 <error id="JVMTI_ERROR_FAILS_VERIFICATION"> | |
| 7377 The class bytes fail verification. | |
| 7378 </error> | |
| 7379 <error id="JVMTI_ERROR_NAMES_DONT_MATCH"> | |
| 7380 The class name defined in a new class file is | |
| 7381 different from the name in the old class object. | |
| 7382 </error> | |
| 7383 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> | |
| 7384 A new class file would require adding a method. | |
| 7385 </error> | |
| 7386 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> | |
| 7387 A new class version changes a field. | |
| 7388 </error> | |
| 7389 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> | |
| 7390 A direct superclass is different for a new class | |
| 7391 version, or the set of directly implemented | |
| 7392 interfaces is different. | |
| 7393 </error> | |
| 7394 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> | |
| 7395 A new class version does not declare a method | |
| 7396 declared in the old class version. | |
| 7397 </error> | |
| 7398 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> | |
| 7399 A new class version has different modifiers. | |
| 7400 </error> | |
| 7401 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> | |
| 7402 A method in the new class version has different modifiers | |
| 7403 than its counterpart in the old class version. | |
| 7404 </error> | |
| 7405 </errors> | |
| 7406 </function> | |
| 7407 | |
| 7408 </category> | |
| 7409 | |
| 7410 <category id="object" label="Object"> | |
| 7411 | |
| 7412 <function id="GetObjectSize" jkernel="yes" phase="start" num="154"> | |
| 7413 <synopsis>Get Object Size</synopsis> | |
| 7414 <description> | |
| 7415 For the object indicated by <code>object</code>, | |
| 7416 return via <code>size_ptr</code> the size of the object. | |
| 7417 This size is an implementation-specific approximation of | |
| 7418 the amount of storage consumed by this object. | |
| 7419 It may include some or all of the object's overhead, and thus | |
| 7420 is useful for comparison within an implementation but not | |
| 7421 between implementations. | |
| 7422 The estimate may change during a single invocation of the JVM. | |
| 7423 </description> | |
| 7424 <origin>new</origin> | |
| 7425 <capabilities> | |
| 7426 </capabilities> | |
| 7427 <parameters> | |
| 7428 <param id="object"> | |
| 7429 <jobject/> | |
| 7430 <description> | |
| 7431 The object to query. | |
| 7432 </description> | |
| 7433 </param> | |
| 7434 <param id="size_ptr"> | |
| 7435 <outptr><jlong/></outptr> | |
| 7436 <description> | |
| 7437 On return, points to the object's size in bytes. | |
| 7438 </description> | |
| 7439 </param> | |
| 7440 </parameters> | |
| 7441 <errors> | |
| 7442 </errors> | |
| 7443 </function> | |
| 7444 | |
| 7445 <function id="GetObjectHashCode" phase="start" num="58"> | |
| 7446 <synopsis>Get Object Hash Code</synopsis> | |
| 7447 <description> | |
| 7448 For the object indicated by <code>object</code>, | |
| 7449 return via <code>hash_code_ptr</code> a hash code. | |
| 7450 This hash code could be used to maintain a hash table of object references, | |
| 7451 however, on some implementations this can cause significant performance | |
| 7452 impacts--in most cases | |
| 7453 <internallink id="Heap">tags</internallink> | |
| 7454 will be a more efficient means of associating information with objects. | |
| 7455 This function guarantees | |
| 7456 the same hash code value for a particular object throughout its life | |
| 7457 </description> | |
| 7458 <origin>jvmdi</origin> | |
| 7459 <capabilities> | |
| 7460 </capabilities> | |
| 7461 <parameters> | |
| 7462 <param id="object"> | |
| 7463 <jobject/> | |
| 7464 <description> | |
| 7465 The object to query. | |
| 7466 </description> | |
| 7467 </param> | |
| 7468 <param id="hash_code_ptr"> | |
| 7469 <outptr><jint/></outptr> | |
| 7470 <description> | |
| 7471 On return, points to the object's hash code. | |
| 7472 </description> | |
| 7473 </param> | |
| 7474 </parameters> | |
| 7475 <errors> | |
| 7476 </errors> | |
| 7477 </function> | |
| 7478 | |
| 7479 <function id="GetObjectMonitorUsage" num="59"> | |
| 7480 <synopsis>Get Object Monitor Usage</synopsis> | |
| 7481 <typedef id="jvmtiMonitorUsage" label="Object monitor usage information"> | |
| 7482 <field id="owner"> | |
| 7483 <jthread/> | |
| 7484 <description> | |
| 7485 The thread owning this monitor, or <code>NULL</code> if unused | |
| 7486 </description> | |
| 7487 </field> | |
| 7488 <field id="entry_count"> | |
| 7489 <jint/> | |
| 7490 <description> | |
| 7491 The number of times the owning thread has entered the monitor | |
| 7492 </description> | |
| 7493 </field> | |
| 7494 <field id="waiter_count"> | |
| 7495 <jint/> | |
| 7496 <description> | |
| 7497 The number of threads waiting to own this monitor | |
| 7498 </description> | |
| 7499 </field> | |
| 7500 <field id="waiters"> | |
| 7501 <allocfieldbuf><jthread/></allocfieldbuf> | |
| 7502 <description> | |
| 7503 The <code>waiter_count</code> waiting threads | |
| 7504 </description> | |
| 7505 </field> | |
| 7506 <field id="notify_waiter_count"> | |
| 7507 <jint/> | |
| 7508 <description> | |
| 7509 The number of threads waiting to be notified by this monitor | |
| 7510 </description> | |
| 7511 </field> | |
| 7512 <field id="notify_waiters"> | |
| 7513 <allocfieldbuf><jthread/></allocfieldbuf> | |
| 7514 <description> | |
| 7515 The <code>notify_waiter_count</code> threads waiting to be notified | |
| 7516 </description> | |
| 7517 </field> | |
| 7518 </typedef> | |
| 7519 <description> | |
| 7520 Get information about the object's monitor. | |
| 7521 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure | |
| 7522 are filled in with information about usage of the monitor. | |
| 7523 <todo> | |
| 7524 Decide and then clarify suspend requirements. | |
| 7525 </todo> | |
| 7526 </description> | |
| 7527 <origin>jvmdi</origin> | |
| 7528 <capabilities> | |
| 7529 <required id="can_get_monitor_info"></required> | |
| 7530 </capabilities> | |
| 7531 <parameters> | |
| 7532 <param id="object"> | |
| 7533 <jobject/> | |
| 7534 <description> | |
| 7535 The object to query. | |
| 7536 </description> | |
| 7537 </param> | |
| 7538 <param id="info_ptr"> | |
| 7539 <outptr><struct>jvmtiMonitorUsage</struct></outptr> | |
| 7540 <description> | |
| 7541 On return, filled with monitor information for the | |
| 7542 specified object. | |
| 7543 </description> | |
| 7544 </param> | |
| 7545 </parameters> | |
| 7546 <errors> | |
| 7547 </errors> | |
| 7548 </function> | |
| 7549 | |
| 7550 <elide> | |
| 7551 <function id="GetObjectMonitors" num="116"> | |
| 7552 <synopsis>Get Object Monitors</synopsis> | |
| 7553 <description> | |
| 7554 Return the list of object monitors. | |
| 7555 <p/> | |
| 7556 Note: details about each monitor can be examined with | |
| 7557 <functionlink id="GetObjectMonitorUsage"></functionlink>. | |
| 7558 </description> | |
| 7559 <origin>new</origin> | |
| 7560 <capabilities> | |
| 7561 <required id="can_get_monitor_info"></required> | |
| 7562 </capabilities> | |
| 7563 <parameters> | |
| 7564 <param id="monitorCnt"> | |
| 7565 <outptr><jint/></outptr> | |
| 7566 <description> | |
| 7567 On return, pointer to the number | |
| 7568 of monitors returned in <code>monitors_ptr</code>. | |
| 7569 </description> | |
| 7570 </param> | |
| 7571 <param id="monitors_ptr"> | |
| 7572 <allocbuf outcount="monitorCnt"><jobject/></allocbuf> | |
| 7573 <description> | |
| 7574 On return, pointer to the monitor list. | |
| 7575 </description> | |
| 7576 </param> | |
| 7577 </parameters> | |
| 7578 <errors> | |
| 7579 </errors> | |
| 7580 </function> | |
| 7581 </elide> | |
| 7582 | |
| 7583 </category> | |
| 7584 | |
| 7585 <category id="fieldCategory" label="Field"> | |
| 7586 | |
| 7587 <intro> | |
| 7588 </intro> | |
| 7589 | |
| 7590 <function id="GetFieldName" phase="start" num="60"> | |
| 7591 <synopsis>Get Field Name (and Signature)</synopsis> | |
| 7592 <description> | |
| 7593 For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>, | |
| 7594 return the field name via <paramlink id="name_ptr"/> and field signature via | |
| 7595 <paramlink id="signature_ptr"/>. | |
| 7596 <p/> | |
| 7597 Field signatures are defined in the JNI Specification and | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7598 are referred to as <code>field descriptors</code> in |
|
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7599 <vmspec chapter="4.3.2"/>. |
| 0 | 7600 </description> |
| 7601 <origin>jvmdiClone</origin> | |
| 7602 <capabilities> | |
| 7603 </capabilities> | |
| 7604 <parameters> | |
| 7605 <param id="klass"> | |
| 7606 <jclass field="field"/> | |
| 7607 <description> | |
| 7608 The class of the field to query. | |
| 7609 </description> | |
| 7610 </param> | |
| 7611 <param id="field"> | |
| 7612 <jfieldID class="klass"/> | |
| 7613 <description> | |
| 7614 The field to query. | |
| 7615 </description> | |
| 7616 </param> | |
| 7617 <param id="name_ptr"> | |
| 7618 <allocbuf> | |
| 7619 <char/> | |
| 7620 <nullok>the name is not returned</nullok> | |
| 7621 </allocbuf> | |
| 7622 <description> | |
| 7623 On return, points to the field name, encoded as a | |
| 7624 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7625 </description> | |
| 7626 </param> | |
| 7627 <param id="signature_ptr"> | |
| 7628 <allocbuf> | |
| 7629 <char/> | |
| 7630 <nullok>the signature is not returned</nullok> | |
| 7631 </allocbuf> | |
| 7632 <description> | |
| 7633 On return, points to the field signature, encoded as a | |
| 7634 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7635 </description> | |
| 7636 </param> | |
| 7637 <param id="generic_ptr"> | |
| 7638 <allocbuf> | |
| 7639 <char/> | |
| 7640 <nullok>the generic signature is not returned</nullok> | |
| 7641 </allocbuf> | |
| 7642 <description> | |
| 7643 On return, points to the generic signature of the field, encoded as a | |
| 7644 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7645 If there is no generic signature attribute for the field, then, | |
| 7646 on return, points to <code>NULL</code>. | |
| 7647 </description> | |
| 7648 </param> | |
| 7649 </parameters> | |
| 7650 <errors> | |
| 7651 </errors> | |
| 7652 </function> | |
| 7653 | |
| 7654 <function id="GetFieldDeclaringClass" phase="start" num="61"> | |
| 7655 <synopsis>Get Field Declaring Class</synopsis> | |
| 7656 <description> | |
| 7657 For the field indicated by <code>klass</code> and <code>field</code> | |
| 7658 return the class that defined it via <code>declaring_class_ptr</code>. | |
| 7659 The declaring class will either be <code>klass</code>, a superclass, or | |
| 7660 an implemented interface. | |
| 7661 </description> | |
| 7662 <origin>jvmdi</origin> | |
| 7663 <capabilities> | |
| 7664 </capabilities> | |
| 7665 <parameters> | |
| 7666 <param id="klass"> | |
| 7667 <jclass field="field"/> | |
| 7668 <description> | |
| 7669 The class to query. | |
| 7670 </description> | |
| 7671 </param> | |
| 7672 <param id="field"> | |
| 7673 <jfieldID class="klass"/> | |
| 7674 <description> | |
| 7675 The field to query. | |
| 7676 </description> | |
| 7677 </param> | |
| 7678 <param id="declaring_class_ptr"> | |
| 7679 <outptr><jclass/></outptr> | |
| 7680 <description> | |
| 7681 On return, points to the declaring class | |
| 7682 </description> | |
| 7683 </param> | |
| 7684 </parameters> | |
| 7685 <errors> | |
| 7686 </errors> | |
| 7687 </function> | |
| 7688 | |
| 7689 <function id="GetFieldModifiers" phase="start" num="62"> | |
| 7690 <synopsis>Get Field Modifiers</synopsis> | |
| 7691 <description> | |
| 7692 For the field indicated by <code>klass</code> and <code>field</code> | |
| 7693 return the access flags via <code>modifiers_ptr</code>. | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7694 Access flags are defined in <vmspec chapter="4"/>. |
| 0 | 7695 </description> |
| 7696 <origin>jvmdi</origin> | |
| 7697 <capabilities> | |
| 7698 </capabilities> | |
| 7699 <parameters> | |
| 7700 <param id="klass"> | |
| 7701 <jclass field="field"/> | |
| 7702 <description> | |
| 7703 The class to query. | |
| 7704 </description> | |
| 7705 </param> | |
| 7706 <param id="field"> | |
| 7707 <jfieldID class="klass"/> | |
| 7708 <description> | |
| 7709 The field to query. | |
| 7710 </description> | |
| 7711 </param> | |
| 7712 <param id="modifiers_ptr"> | |
| 7713 <outptr><jint/></outptr> | |
| 7714 <description> | |
| 7715 On return, points to the access flags. | |
| 7716 </description> | |
| 7717 </param> | |
| 7718 </parameters> | |
| 7719 <errors> | |
| 7720 </errors> | |
| 7721 </function> | |
| 7722 | |
| 7723 <function id="IsFieldSynthetic" phase="start" num="63"> | |
| 7724 <synopsis>Is Field Synthetic</synopsis> | |
| 7725 <description> | |
| 7726 For the field indicated by <code>klass</code> and <code>field</code>, return a | |
| 7727 value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>. | |
| 7728 Synthetic fields are generated by the compiler but not present in the | |
| 7729 original source code. | |
| 7730 </description> | |
| 7731 <origin>jvmdi</origin> | |
| 7732 <capabilities> | |
| 7733 <required id="can_get_synthetic_attribute"></required> | |
| 7734 </capabilities> | |
| 7735 <parameters> | |
| 7736 <param id="klass"> | |
| 7737 <jclass field="field"/> | |
| 7738 <description> | |
| 7739 The class of the field to query. | |
| 7740 </description> | |
| 7741 </param> | |
| 7742 <param id="field"> | |
| 7743 <jfieldID class="klass"/> | |
| 7744 <description> | |
| 7745 The field to query. | |
| 7746 </description> | |
| 7747 </param> | |
| 7748 <param id="is_synthetic_ptr"> | |
| 7749 <outptr><jboolean/></outptr> | |
| 7750 <description> | |
| 7751 On return, points to the boolean result of this function. | |
| 7752 </description> | |
| 7753 </param> | |
| 7754 </parameters> | |
| 7755 <errors> | |
| 7756 </errors> | |
| 7757 </function> | |
| 7758 | |
| 7759 </category> | |
| 7760 | |
| 7761 <category id="method" label="Method"> | |
| 7762 | |
| 7763 <intro> | |
| 7764 These functions provide information about a method (represented as a | |
| 7765 <typelink id="jmethodID"/>) and set how methods are processed. | |
| 7766 </intro> | |
| 7767 | |
| 7768 <intro id="obsoleteMethods" label="Obsolete Methods"> | |
| 7769 The functions <functionlink id="RetransformClasses"/> and | |
| 7770 <functionlink id="RedefineClasses"/> can cause new versions | |
| 7771 of methods to be installed. | |
| 7772 An original version of a method is considered equivalent | |
| 7773 to the new version if: | |
| 7774 <ul> | |
| 7775 <li>their bytecodes are the same except for indices into the | |
| 7776 constant pool and </li> | |
| 7777 <li>the referenced constants are equal.</li> | |
| 7778 </ul> | |
| 7779 An original method version which is not equivalent to the | |
| 7780 new method version is called obsolete and is assigned a new method ID; | |
| 7781 the original method ID now refers to the new method version. | |
| 7782 A method ID can be tested for obsolescence with | |
| 7783 <functionlink id="IsMethodObsolete"/>. | |
| 7784 </intro> | |
| 7785 | |
| 7786 <function id="GetMethodName" phase="start" num="64"> | |
| 7787 <synopsis>Get Method Name (and Signature)</synopsis> | |
| 7788 <description> | |
| 7789 For the method indicated by <code>method</code>, | |
| 7790 return the method name via <code>name_ptr</code> and method signature via | |
| 7791 <code>signature_ptr</code>. | |
| 7792 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7793 Method signatures are defined in the JNI Specification and are |
|
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7794 referred to as <code>method descriptors</code> in |
|
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7795 <vmspec chapter="4.3.3"/>. |
| 0 | 7796 Note this is different |
| 7797 than method signatures as defined in the <i>Java Language Specification</i>. | |
| 7798 </description> | |
| 7799 <origin>jvmdiClone</origin> | |
| 7800 <capabilities> | |
| 7801 </capabilities> | |
| 7802 <parameters> | |
| 7803 <param id="method"> | |
| 7804 <jmethodID/> | |
| 7805 <description> | |
| 7806 The method to query. | |
| 7807 </description> | |
| 7808 </param> | |
| 7809 <param id="name_ptr"> | |
| 7810 <allocbuf> | |
| 7811 <char/> | |
| 7812 <nullok>the name is not returned</nullok> | |
| 7813 </allocbuf> | |
| 7814 <description> | |
| 7815 On return, points to the method name, encoded as a | |
| 7816 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7817 </description> | |
| 7818 </param> | |
| 7819 <param id="signature_ptr"> | |
| 7820 <allocbuf> | |
| 7821 <char/> | |
| 7822 <nullok>the signature is not returned</nullok> | |
| 7823 </allocbuf> | |
| 7824 <description> | |
| 7825 On return, points to the method signature, encoded as a | |
| 7826 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7827 </description> | |
| 7828 </param> | |
| 7829 <param id="generic_ptr"> | |
| 7830 <allocbuf> | |
| 7831 <char/> | |
| 7832 <nullok>the generic signature is not returned</nullok> | |
| 7833 </allocbuf> | |
| 7834 <description> | |
| 7835 On return, points to the generic signature of the method, encoded as a | |
| 7836 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7837 If there is no generic signature attribute for the method, then, | |
| 7838 on return, points to <code>NULL</code>. | |
| 7839 </description> | |
| 7840 </param> | |
| 7841 </parameters> | |
| 7842 <errors> | |
| 7843 </errors> | |
| 7844 </function> | |
| 7845 | |
| 7846 <function id="GetMethodDeclaringClass" phase="start" num="65"> | |
| 7847 <synopsis>Get Method Declaring Class</synopsis> | |
| 7848 <description> | |
| 7849 For the method indicated by <code>method</code>, | |
| 7850 return the class that defined it via <code>declaring_class_ptr</code>. | |
| 7851 </description> | |
| 7852 <origin>jvmdi</origin> | |
| 7853 <capabilities> | |
| 7854 </capabilities> | |
| 7855 <parameters> | |
| 7856 <param id="klass"> | |
| 7857 <jclass method="method"/> | |
| 7858 <description> | |
| 7859 The class to query. | |
| 7860 </description> | |
| 7861 </param> | |
| 7862 <param id="method"> | |
| 7863 <jmethodID class="klass"/> | |
| 7864 <description> | |
| 7865 The method to query. | |
| 7866 </description> | |
| 7867 </param> | |
| 7868 <param id="declaring_class_ptr"> | |
| 7869 <outptr><jclass/></outptr> | |
| 7870 <description> | |
| 7871 On return, points to the declaring class | |
| 7872 </description> | |
| 7873 </param> | |
| 7874 </parameters> | |
| 7875 <errors> | |
| 7876 </errors> | |
| 7877 </function> | |
| 7878 | |
| 7879 <function id="GetMethodModifiers" phase="start" num="66"> | |
| 7880 <synopsis>Get Method Modifiers</synopsis> | |
| 7881 <description> | |
| 7882 For the method indicated by <code>method</code>, | |
| 7883 return the access flags via <code>modifiers_ptr</code>. | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7884 Access flags are defined in <vmspec chapter="4"/>. |
| 0 | 7885 </description> |
| 7886 <origin>jvmdi</origin> | |
| 7887 <capabilities> | |
| 7888 </capabilities> | |
| 7889 <parameters> | |
| 7890 <param id="klass"> | |
| 7891 <jclass method="method"/> | |
| 7892 <description> | |
| 7893 The class to query. | |
| 7894 </description> | |
| 7895 </param> | |
| 7896 <param id="method"> | |
| 7897 <jmethodID class="klass"/> | |
| 7898 <description> | |
| 7899 The method to query. | |
| 7900 </description> | |
| 7901 </param> | |
| 7902 <param id="modifiers_ptr"> | |
| 7903 <outptr><jint/></outptr> | |
| 7904 <description> | |
| 7905 On return, points to the access flags. | |
| 7906 </description> | |
| 7907 </param> | |
| 7908 </parameters> | |
| 7909 <errors> | |
| 7910 </errors> | |
| 7911 </function> | |
| 7912 | |
| 7913 <function id="GetMaxLocals" phase="start" num="68"> | |
| 7914 <synopsis>Get Max Locals</synopsis> | |
| 7915 <description> | |
| 7916 For the method indicated by <code>method</code>, | |
| 7917 return the number of local variable slots used by the method, | |
| 7918 including the local variables used to pass parameters to the | |
| 7919 method on its invocation. | |
| 7920 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7921 See <code>max_locals</code> in <vmspec chapter="4.7.3"/>. |
| 0 | 7922 </description> |
| 7923 <origin>jvmdi</origin> | |
| 7924 <capabilities> | |
| 7925 </capabilities> | |
| 7926 <parameters> | |
| 7927 <param id="klass"> | |
| 7928 <jclass method="method"/> | |
| 7929 <description> | |
| 7930 The class to query. | |
| 7931 </description> | |
| 7932 </param> | |
| 7933 <param id="method"> | |
| 7934 <jmethodID class="klass" native="error"/> | |
| 7935 <description> | |
| 7936 The method to query. | |
| 7937 </description> | |
| 7938 </param> | |
| 7939 <param id="max_ptr"> | |
| 7940 <outptr><jint/></outptr> | |
| 7941 <description> | |
| 7942 On return, points to the maximum number of local slots | |
| 7943 </description> | |
| 7944 </param> | |
| 7945 </parameters> | |
| 7946 <errors> | |
| 7947 </errors> | |
| 7948 </function> | |
| 7949 | |
| 7950 <function id="GetArgumentsSize" phase="start" num="69"> | |
| 7951 <synopsis>Get Arguments Size</synopsis> | |
| 7952 <description> | |
| 7953 For the method indicated by <code>method</code>, | |
| 7954 return via <code>max_ptr</code> the number of local variable slots used | |
| 7955 by the method's arguments. | |
| 7956 Note that two-word arguments use two slots. | |
| 7957 </description> | |
| 7958 <origin>jvmdi</origin> | |
| 7959 <capabilities> | |
| 7960 </capabilities> | |
| 7961 <parameters> | |
| 7962 <param id="klass"> | |
| 7963 <jclass method="method"/> | |
| 7964 <description> | |
| 7965 The class to query. | |
| 7966 </description> | |
| 7967 </param> | |
| 7968 <param id="method"> | |
| 7969 <jmethodID class="klass" native="error"/> | |
| 7970 <description> | |
| 7971 The method to query. | |
| 7972 </description> | |
| 7973 </param> | |
| 7974 <param id="size_ptr"> | |
| 7975 <outptr><jint/></outptr> | |
| 7976 <description> | |
| 7977 On return, points to the number of argument slots | |
| 7978 </description> | |
| 7979 </param> | |
| 7980 </parameters> | |
| 7981 <errors> | |
| 7982 </errors> | |
| 7983 </function> | |
| 7984 | |
| 7985 <function id="GetLineNumberTable" phase="start" num="70"> | |
| 7986 <synopsis>Get Line Number Table</synopsis> | |
| 7987 <typedef id="jvmtiLineNumberEntry" label="Line number table entry"> | |
| 7988 <field id="start_location"> | |
| 7989 <jlocation/> | |
| 7990 <description> | |
| 7991 the <datalink id="jlocation"></datalink> where the line begins | |
| 7992 </description> | |
| 7993 </field> | |
| 7994 <field id="line_number"> | |
| 7995 <jint/> | |
| 7996 <description> | |
| 7997 the line number | |
| 7998 </description> | |
| 7999 </field> | |
| 8000 </typedef> | |
| 8001 <description> | |
| 8002 For the method indicated by <code>method</code>, | |
| 8003 return a table of source line number entries. The size of the table is | |
| 8004 returned via <code>entry_count_ptr</code> and the table itself is | |
| 8005 returned via <code>table_ptr</code>. | |
| 8006 </description> | |
| 8007 <origin>jvmdi</origin> | |
| 8008 <capabilities> | |
| 8009 <required id="can_get_line_numbers"></required> | |
| 8010 </capabilities> | |
| 8011 <parameters> | |
| 8012 <param id="klass"> | |
| 8013 <jclass method="method"/> | |
| 8014 <description> | |
| 8015 The class to query. | |
| 8016 </description> | |
| 8017 </param> | |
| 8018 <param id="method"> | |
| 8019 <jmethodID class="klass" native="error"/> | |
| 8020 <description> | |
| 8021 The method to query. | |
| 8022 </description> | |
| 8023 </param> | |
| 8024 <param id="entry_count_ptr"> | |
| 8025 <outptr><jint/></outptr> | |
| 8026 <description> | |
| 8027 On return, points to the number of entries in the table | |
| 8028 </description> | |
| 8029 </param> | |
| 8030 <param id="table_ptr"> | |
| 8031 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf> | |
| 8032 <description> | |
| 8033 On return, points to the line number table pointer. | |
| 8034 </description> | |
| 8035 </param> | |
| 8036 </parameters> | |
| 8037 <errors> | |
| 8038 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 8039 Class information does not include line numbers. | |
| 8040 </error> | |
| 8041 </errors> | |
| 8042 </function> | |
| 8043 | |
| 8044 <function id="GetMethodLocation" phase="start" num="71"> | |
| 8045 <synopsis>Get Method Location</synopsis> | |
| 8046 <description> | |
| 8047 For the method indicated by <code>method</code>, | |
| 8048 return the beginning and ending addresses through | |
| 8049 <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a | |
| 8050 conventional byte code indexing scheme, | |
| 8051 <code>start_location_ptr</code> will always point to zero | |
| 8052 and <code>end_location_ptr</code> | |
| 8053 will always point to the byte code count minus one. | |
| 8054 </description> | |
| 8055 <origin>jvmdi</origin> | |
| 8056 <capabilities> | |
| 8057 </capabilities> | |
| 8058 <parameters> | |
| 8059 <param id="klass"> | |
| 8060 <jclass method="method"/> | |
| 8061 <description> | |
| 8062 The class to query. | |
| 8063 </description> | |
| 8064 </param> | |
| 8065 <param id="method"> | |
| 8066 <jmethodID class="klass" native="error"/> | |
| 8067 <description> | |
| 8068 The method to query. | |
| 8069 </description> | |
| 8070 </param> | |
| 8071 <param id="start_location_ptr"> | |
| 8072 <outptr><jlocation/></outptr> | |
| 8073 <description> | |
| 8074 On return, points to the first location, or | |
| 8075 <code>-1</code> if location information is not available. | |
| 8076 If the information is available and | |
| 8077 <functionlink id="GetJLocationFormat"></functionlink> | |
| 8078 returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink> | |
| 8079 then this will always be zero. | |
| 8080 </description> | |
| 8081 </param> | |
| 8082 <param id="end_location_ptr"> | |
| 8083 <outptr><jlocation/></outptr> | |
| 8084 <description> | |
| 8085 On return, points to the last location, | |
| 8086 or <code>-1</code> if location information is not available. | |
| 8087 </description> | |
| 8088 </param> | |
| 8089 </parameters> | |
| 8090 <errors> | |
| 8091 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 8092 Class information does not include method sizes. | |
| 8093 </error> | |
| 8094 </errors> | |
| 8095 </function> | |
| 8096 | |
| 8097 <function id="GetLocalVariableTable" num="72"> | |
| 8098 <synopsis>Get Local Variable Table</synopsis> | |
| 8099 <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry"> | |
| 8100 <field id="start_location"> | |
| 8101 <jlocation/> | |
| 8102 <description> | |
| 8103 The code array index where the local variable is first valid | |
| 8104 (that is, where it must have a value). | |
| 8105 </description> | |
| 8106 </field> | |
| 8107 <field id="length"> | |
| 8108 <jint/> | |
| 8109 <description> | |
| 8110 The length of the valid section for this local variable. | |
| 8111 The last code array index where the local variable is valid | |
| 8112 is <code>start_location + length</code>. | |
| 8113 </description> | |
| 8114 </field> | |
| 8115 <field id="name"> | |
| 8116 <allocfieldbuf><char/></allocfieldbuf> | |
| 8117 <description> | |
| 8118 The local variable name, encoded as a | |
| 8119 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8120 </description> | |
| 8121 </field> | |
| 8122 <field id="signature"> | |
| 8123 <allocfieldbuf><char/></allocfieldbuf> | |
| 8124 <description> | |
| 8125 The local variable's type signature, encoded as a | |
| 8126 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8127 The signature format is the same as that defined in | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
8128 <vmspec chapter="4.3.2"/>. |
| 0 | 8129 </description> |
| 8130 </field> | |
| 8131 <field id="generic_signature"> | |
| 8132 <allocfieldbuf><char/></allocfieldbuf> | |
| 8133 <description> | |
| 8134 The local variable's generic signature, encoded as a | |
| 8135 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8136 The value of this field will be <code>NULL</code> for any local | |
| 8137 variable which does not have a generic type. | |
| 8138 </description> | |
| 8139 </field> | |
| 8140 <field id="slot"> | |
| 8141 <jint/> | |
| 8142 <description> | |
| 8143 The local variable's slot. See <internallink id="local">Local Variables</internallink>. | |
| 8144 </description> | |
| 8145 </field> | |
| 8146 </typedef> | |
| 8147 <description> | |
| 8148 Return local variable information. | |
| 8149 </description> | |
| 8150 <origin>jvmdiClone</origin> | |
| 8151 <capabilities> | |
| 8152 <required id="can_access_local_variables"></required> | |
| 8153 </capabilities> | |
| 8154 <parameters> | |
| 8155 <param id="method"> | |
| 8156 <jmethodID native="error"/> | |
| 8157 <description> | |
| 8158 The method to query. | |
| 8159 </description> | |
| 8160 </param> | |
| 8161 <param id="entry_count_ptr"> | |
| 8162 <outptr><jint/></outptr> | |
| 8163 <description> | |
| 8164 On return, points to the number of entries in the table | |
| 8165 </description> | |
| 8166 </param> | |
| 8167 <param id="table_ptr"> | |
| 8168 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf> | |
| 8169 <description> | |
| 8170 On return, points to an array of local variable table entries. | |
| 8171 </description> | |
| 8172 </param> | |
| 8173 </parameters> | |
| 8174 <errors> | |
| 8175 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 8176 Class information does not include local variable | |
| 8177 information. | |
| 8178 </error> | |
| 8179 </errors> | |
| 8180 </function> | |
| 8181 | |
| 8182 <function id="GetBytecodes" phase="start" num="75"> | |
| 8183 <synopsis>Get Bytecodes</synopsis> | |
| 8184 <description> | |
| 8185 For the method indicated by <code>method</code>, | |
| 8186 return the byte codes that implement the method. The number of | |
| 8187 bytecodes is returned via <code>bytecode_count_ptr</code>. The byte codes | |
| 8188 themselves are returned via <code>bytecodes_ptr</code>. | |
| 8189 </description> | |
| 8190 <origin>jvmdi</origin> | |
| 8191 <capabilities> | |
| 8192 <required id="can_get_bytecodes"></required> | |
| 8193 </capabilities> | |
| 8194 <parameters> | |
| 8195 <param id="klass"> | |
| 8196 <jclass method="method"/> | |
| 8197 <description> | |
| 8198 The class to query. | |
| 8199 </description> | |
| 8200 </param> | |
| 8201 <param id="method"> | |
| 8202 <jmethodID class="klass" native="error"/> | |
| 8203 <description> | |
| 8204 The method to query. | |
| 8205 </description> | |
| 8206 </param> | |
| 8207 <param id="bytecode_count_ptr"> | |
| 8208 <outptr><jint/></outptr> | |
| 8209 <description> | |
| 8210 On return, points to the length of the byte code array | |
| 8211 </description> | |
| 8212 </param> | |
| 8213 <param id="bytecodes_ptr"> | |
| 8214 <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf> | |
| 8215 <description> | |
| 8216 On return, points to the pointer to the byte code array | |
| 8217 </description> | |
| 8218 </param> | |
| 8219 </parameters> | |
| 8220 <errors> | |
| 8221 </errors> | |
| 8222 </function> | |
| 8223 | |
| 8224 <function id="IsMethodNative" phase="start" num="76"> | |
| 8225 <synopsis>Is Method Native</synopsis> | |
| 8226 <description> | |
| 8227 For the method indicated by <code>method</code>, return a | |
| 8228 value indicating whether the method is native via <code>is_native_ptr</code> | |
| 8229 </description> | |
| 8230 <origin>jvmdi</origin> | |
| 8231 <capabilities> | |
| 8232 </capabilities> | |
| 8233 <parameters> | |
| 8234 <param id="klass"> | |
| 8235 <jclass method="method"/> | |
| 8236 <description> | |
| 8237 The class to query. | |
| 8238 </description> | |
| 8239 </param> | |
| 8240 <param id="method"> | |
| 8241 <jmethodID class="klass"/> | |
| 8242 <description> | |
| 8243 The method to query. | |
| 8244 </description> | |
| 8245 </param> | |
| 8246 <param id="is_native_ptr"> | |
| 8247 <outptr><jboolean/></outptr> | |
| 8248 <description> | |
| 8249 On return, points to the boolean result of this function. | |
| 8250 </description> | |
| 8251 </param> | |
| 8252 </parameters> | |
| 8253 <errors> | |
| 8254 </errors> | |
| 8255 </function> | |
| 8256 | |
| 8257 <function id="IsMethodSynthetic" phase="start" num="77"> | |
| 8258 <synopsis>Is Method Synthetic</synopsis> | |
| 8259 <description> | |
| 8260 For the method indicated by <code>method</code>, return a | |
| 8261 value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>. | |
| 8262 Synthetic methods are generated by the compiler but not present in the | |
| 8263 original source code. | |
| 8264 </description> | |
| 8265 <origin>jvmdi</origin> | |
| 8266 <capabilities> | |
| 8267 <required id="can_get_synthetic_attribute"></required> | |
| 8268 </capabilities> | |
| 8269 <parameters> | |
| 8270 <param id="klass"> | |
| 8271 <jclass method="method"/> | |
| 8272 <description> | |
| 8273 The class to query. | |
| 8274 </description> | |
| 8275 </param> | |
| 8276 <param id="method"> | |
| 8277 <jmethodID class="klass"/> | |
| 8278 <description> | |
| 8279 The method to query. | |
| 8280 </description> | |
| 8281 </param> | |
| 8282 <param id="is_synthetic_ptr"> | |
| 8283 <outptr><jboolean/></outptr> | |
| 8284 <description> | |
| 8285 On return, points to the boolean result of this function. | |
| 8286 </description> | |
| 8287 </param> | |
| 8288 </parameters> | |
| 8289 <errors> | |
| 8290 </errors> | |
| 8291 </function> | |
| 8292 | |
| 8293 <function id="IsMethodObsolete" phase="start" num="91"> | |
| 8294 <synopsis>Is Method Obsolete</synopsis> | |
| 8295 <description> | |
| 8296 Determine if a method ID refers to an | |
| 8297 <internallink id="obsoleteMethods">obsolete</internallink> | |
| 8298 method version. | |
| 8299 </description> | |
| 8300 <origin>jvmdi</origin> | |
| 8301 <capabilities> | |
| 8302 </capabilities> | |
| 8303 <parameters> | |
| 8304 <param id="klass"> | |
| 8305 <jclass method="method"/> | |
| 8306 <description> | |
| 8307 The class to query. | |
| 8308 </description> | |
| 8309 </param> | |
| 8310 <param id="method"> | |
| 8311 <jmethodID class="klass"/> | |
| 8312 <description> | |
| 8313 The method ID to query. | |
| 8314 </description> | |
| 8315 </param> | |
| 8316 <param id="is_obsolete_ptr"> | |
| 8317 <outptr><jboolean/></outptr> | |
| 8318 <description> | |
| 8319 On return, points to the boolean result of this function. | |
| 8320 </description> | |
| 8321 </param> | |
| 8322 </parameters> | |
| 8323 <errors> | |
| 8324 </errors> | |
| 8325 </function> | |
| 8326 | |
| 8327 <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1"> | |
| 8328 <synopsis>Set Native Method Prefix</synopsis> | |
| 8329 <description> | |
| 8330 This function modifies the failure handling of | |
| 8331 native method resolution by allowing retry | |
| 8332 with a prefix applied to the name. | |
| 8333 When used with the | |
| 8334 <eventlink id="ClassFileLoadHook">ClassFileLoadHook | |
| 8335 event</eventlink>, it enables native methods to be | |
| 8336 <internallink id="bci">instrumented</internallink>. | |
| 8337 <p/> | |
| 8338 Since native methods cannot be directly instrumented | |
| 8339 (they have no bytecodes), they must be wrapped with | |
| 8340 a non-native method which can be instrumented. | |
| 8341 For example, if we had: | |
| 8342 <example> | |
| 8343 native boolean foo(int x);</example> | |
| 8344 <p/> | |
| 8345 We could transform the class file (with the | |
| 8346 ClassFileLoadHook event) so that this becomes: | |
| 8347 <example> | |
| 8348 boolean foo(int x) { | |
| 8349 <i>... record entry to foo ...</i> | |
| 8350 return wrapped_foo(x); | |
| 8351 } | |
| 8352 | |
| 8353 native boolean wrapped_foo(int x);</example> | |
| 8354 <p/> | |
| 8355 Where foo becomes a wrapper for the actual native method | |
| 8356 with the appended prefix "wrapped_". Note that | |
| 8357 "wrapped_" would be a poor choice of prefix since it | |
| 8358 might conceivably form the name of an existing method | |
| 8359 thus something like "$$$MyAgentWrapped$$$_" would be | |
| 8360 better but would make these examples less readable. | |
| 8361 <p/> | |
| 8362 The wrapper will allow data to be collected on the native | |
| 8363 method call, but now the problem becomes linking up the | |
| 8364 wrapped method with the native implementation. | |
| 8365 That is, the method <code>wrapped_foo</code> needs to be | |
| 8366 resolved to the native implementation of <code>foo</code>, | |
| 8367 which might be: | |
| 8368 <example> | |
| 8369 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example> | |
| 8370 <p/> | |
| 8371 This function allows the prefix to be specified and the | |
| 8372 proper resolution to occur. | |
| 8373 Specifically, when the standard resolution fails, the | |
| 8374 resolution is retried taking the prefix into consideration. | |
| 8375 There are two ways that resolution occurs, explicit | |
| 8376 resolution with the JNI function <code>RegisterNatives</code> | |
| 8377 and the normal automatic resolution. For | |
| 8378 <code>RegisterNatives</code>, the VM will attempt this | |
| 8379 association: | |
| 8380 <example> | |
| 8381 method(foo) -> nativeImplementation(foo)</example> | |
| 8382 <p/> | |
| 8383 When this fails, the resolution will be retried with | |
| 8384 the specified prefix prepended to the method name, | |
| 8385 yielding the correct resolution: | |
| 8386 <example> | |
| 8387 method(wrapped_foo) -> nativeImplementation(foo)</example> | |
| 8388 <p/> | |
| 8389 For automatic resolution, the VM will attempt: | |
| 8390 <example> | |
| 8391 method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example> | |
| 8392 <p/> | |
| 8393 When this fails, the resolution will be retried with | |
| 8394 the specified prefix deleted from the implementation name, | |
| 8395 yielding the correct resolution: | |
| 8396 <example> | |
| 8397 method(wrapped_foo) -> nativeImplementation(foo)</example> | |
| 8398 <p/> | |
| 8399 Note that since the prefix is only used when standard | |
| 8400 resolution fails, native methods can be wrapped selectively. | |
| 8401 <p/> | |
| 8402 Since each <jvmti/> environment is independent and | |
| 8403 can do its own transformation of the bytecodes, more | |
| 8404 than one layer of wrappers may be applied. Thus each | |
| 8405 environment needs its own prefix. Since transformations | |
| 8406 are applied in order, the prefixes, if applied, will | |
| 8407 be applied in the same order. | |
| 8408 The order of transformation application is described in | |
| 8409 the <eventlink id="ClassFileLoadHook"/> event. | |
| 8410 Thus if three environments applied | |
| 8411 wrappers, <code>foo</code> might become | |
| 8412 <code>$env3_$env2_$env1_foo</code>. But if, say, | |
| 8413 the second environment did not apply a wrapper to | |
| 8414 <code>foo</code> it would be just | |
| 8415 <code>$env3_$env1_foo</code>. To be able to | |
| 8416 efficiently determine the sequence of prefixes, | |
| 8417 an intermediate prefix is only applied if its non-native | |
| 8418 wrapper exists. Thus, in the last example, even though | |
| 8419 <code>$env1_foo</code> is not a native method, the | |
| 8420 <code>$env1_</code> prefix is applied since | |
| 8421 <code>$env1_foo</code> exists. | |
| 8422 <p/> | |
| 8423 Since the prefixes are used at resolution time | |
| 8424 and since resolution may be arbitrarily delayed, a | |
| 8425 native method prefix must remain set as long as there | |
| 8426 are corresponding prefixed native methods. | |
| 8427 </description> | |
| 8428 <origin>new</origin> | |
| 8429 <capabilities> | |
| 8430 <required id="can_set_native_method_prefix"></required> | |
| 8431 </capabilities> | |
| 8432 <parameters> | |
| 8433 <param id="prefix"> | |
| 8434 <inbuf> | |
| 8435 <char/> | |
| 8436 <nullok> | |
| 8437 any existing prefix in this environment is cancelled | |
| 8438 </nullok> | |
| 8439 </inbuf> | |
| 8440 <description> | |
| 8441 The prefix to apply, encoded as a | |
| 8442 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8443 </description> | |
| 8444 </param> | |
| 8445 </parameters> | |
| 8446 <errors> | |
| 8447 </errors> | |
| 8448 </function> | |
| 8449 | |
| 8450 <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1"> | |
| 8451 <synopsis>Set Native Method Prefixes</synopsis> | |
| 8452 <description> | |
| 8453 For a normal agent, <functionlink id="SetNativeMethodPrefix"/> | |
| 8454 will provide all needed native method prefixing. | |
| 8455 For a meta-agent that performs multiple independent class | |
| 8456 file transformations (for example as a proxy for another | |
| 8457 layer of agents) this function allows each transformation | |
| 8458 to have its own prefix. | |
| 8459 The prefixes are applied in the order supplied and are | |
| 8460 processed in the same manor as described for the | |
| 8461 application of prefixes from multiple <jvmti/> environments | |
| 8462 in <functionlink id="SetNativeMethodPrefix"/>. | |
| 8463 <p/> | |
| 8464 Any previous prefixes are replaced. Thus, calling this | |
| 8465 function with a <paramlink id="prefix_count"/> of <code>0</code> | |
| 8466 disables prefixing in this environment. | |
| 8467 <p/> | |
| 8468 <functionlink id="SetNativeMethodPrefix"/> and this function | |
| 8469 are the two ways to set the prefixes. | |
| 8470 Calling <code>SetNativeMethodPrefix</code> with | |
| 8471 a prefix is the same as calling this function with | |
| 8472 <paramlink id="prefix_count"/> of <code>1</code>. | |
| 8473 Calling <code>SetNativeMethodPrefix</code> with | |
| 8474 <code>NULL</code> is the same as calling this function with | |
| 8475 <paramlink id="prefix_count"/> of <code>0</code>. | |
| 8476 </description> | |
| 8477 <origin>new</origin> | |
| 8478 <capabilities> | |
| 8479 <required id="can_set_native_method_prefix"></required> | |
| 8480 </capabilities> | |
| 8481 <parameters> | |
| 8482 <param id="prefix_count"> | |
| 8483 <jint min="0"/> | |
| 8484 <description> | |
| 8485 The number of prefixes to apply. | |
| 8486 </description> | |
| 8487 </param> | |
| 8488 <param id="prefixes"> | |
| 8489 <agentbuf> | |
| 8490 <char/> | |
| 8491 </agentbuf> | |
| 8492 <description> | |
| 8493 The prefixes to apply for this environment, each encoded as a | |
| 8494 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8495 </description> | |
| 8496 </param> | |
| 8497 </parameters> | |
| 8498 <errors> | |
| 8499 </errors> | |
| 8500 </function> | |
| 8501 | |
| 8502 </category> | |
| 8503 | |
| 8504 <category id="RawMonitors" label="Raw Monitor"> | |
| 8505 | |
| 8506 <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31"> | |
| 8507 <synopsis>Create Raw Monitor</synopsis> | |
| 8508 <description> | |
| 8509 Create a raw monitor. | |
| 8510 </description> | |
| 8511 <origin>jvmdi</origin> | |
| 8512 <capabilities> | |
| 8513 </capabilities> | |
| 8514 <parameters> | |
| 8515 <param id="name"> | |
| 8516 <inbuf><char/></inbuf> | |
| 8517 <description> | |
| 8518 A name to identify the monitor, encoded as a | |
| 8519 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8520 </description> | |
| 8521 </param> | |
| 8522 <param id="monitor_ptr"> | |
| 8523 <outptr><jrawMonitorID/></outptr> | |
| 8524 <description> | |
| 8525 On return, points to the created monitor. | |
| 8526 </description> | |
| 8527 </param> | |
| 8528 </parameters> | |
| 8529 <errors> | |
| 8530 </errors> | |
| 8531 </function> | |
| 8532 | |
| 8533 <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32"> | |
| 8534 <synopsis>Destroy Raw Monitor</synopsis> | |
| 8535 <description> | |
| 8536 Destroy the raw monitor. | |
| 8537 If the monitor being destroyed has been entered by this thread, it will be | |
| 8538 exited before it is destroyed. | |
| 8539 If the monitor being destroyed has been entered by another thread, | |
| 8540 an error will be returned and the monitor will not be destroyed. | |
| 8541 </description> | |
| 8542 <origin>jvmdi</origin> | |
| 8543 <capabilities> | |
| 8544 </capabilities> | |
| 8545 <parameters> | |
| 8546 <param id="monitor"> | |
| 8547 <jrawMonitorID/> | |
| 8548 <description> | |
| 8549 The monitor | |
| 8550 </description> | |
| 8551 </param> | |
| 8552 </parameters> | |
| 8553 <errors> | |
| 8554 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8555 Not monitor owner | |
| 8556 </error> | |
| 8557 </errors> | |
| 8558 </function> | |
| 8559 | |
| 8560 <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33"> | |
| 8561 <synopsis>Raw Monitor Enter</synopsis> | |
| 8562 <description> | |
| 8563 Gain exclusive ownership of a raw monitor. | |
| 8564 The same thread may enter a monitor more then once. | |
| 8565 The thread must | |
| 8566 <functionlink id="RawMonitorExit">exit</functionlink> | |
| 8567 the monitor the same number of times as it is entered. | |
| 8568 If a monitor is entered during <code>OnLoad</code> (before attached threads exist) | |
| 8569 and has not exited when attached threads come into existence, the enter | |
| 8570 is considered to have occurred on the main thread. | |
| 8571 </description> | |
| 8572 <origin>jvmdi</origin> | |
| 8573 <capabilities> | |
| 8574 </capabilities> | |
| 8575 <parameters> | |
| 8576 <param id="monitor"> | |
| 8577 <jrawMonitorID/> | |
| 8578 <description> | |
| 8579 The monitor | |
| 8580 </description> | |
| 8581 </param> | |
| 8582 </parameters> | |
| 8583 <errors> | |
| 8584 </errors> | |
| 8585 </function> | |
| 8586 | |
| 8587 <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34"> | |
| 8588 <synopsis>Raw Monitor Exit</synopsis> | |
| 8589 <description> | |
| 8590 Release exclusive ownership of a raw monitor. | |
| 8591 </description> | |
| 8592 <origin>jvmdi</origin> | |
| 8593 <capabilities> | |
| 8594 </capabilities> | |
| 8595 <parameters> | |
| 8596 <param id="monitor"> | |
| 8597 <jrawMonitorID/> | |
| 8598 <description> | |
| 8599 The monitor | |
| 8600 </description> | |
| 8601 </param> | |
| 8602 </parameters> | |
| 8603 <errors> | |
| 8604 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8605 Not monitor owner | |
| 8606 </error> | |
| 8607 </errors> | |
| 8608 </function> | |
| 8609 | |
| 8610 <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35"> | |
| 8611 <synopsis>Raw Monitor Wait</synopsis> | |
| 8612 <description> | |
| 8613 Wait for notification of the raw monitor. | |
| 8614 <p/> | |
| 8615 Causes the current thread to wait until either another thread calls | |
| 8616 <functionlink id="RawMonitorNotify"/> or | |
| 8617 <functionlink id="RawMonitorNotifyAll"/> | |
| 8618 for the specified raw monitor, or the specified | |
| 8619 <paramlink id="millis">timeout</paramlink> | |
| 8620 has elapsed. | |
| 8621 </description> | |
| 8622 <origin>jvmdi</origin> | |
| 8623 <capabilities> | |
| 8624 </capabilities> | |
| 8625 <parameters> | |
| 8626 <param id="monitor"> | |
| 8627 <jrawMonitorID/> | |
| 8628 <description> | |
| 8629 The monitor | |
| 8630 </description> | |
| 8631 </param> | |
| 8632 <param id="millis"> | |
| 8633 <jlong/> | |
| 8634 <description> | |
| 8635 The timeout, in milliseconds. If the timeout is | |
| 8636 zero, then real time is not taken into consideration | |
| 8637 and the thread simply waits until notified. | |
| 8638 </description> | |
| 8639 </param> | |
| 8640 </parameters> | |
| 8641 <errors> | |
| 8642 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8643 Not monitor owner | |
| 8644 </error> | |
| 8645 <error id="JVMTI_ERROR_INTERRUPT"> | |
| 8646 Wait was interrupted, try again | |
| 8647 </error> | |
| 8648 </errors> | |
| 8649 </function> | |
| 8650 | |
| 8651 <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36"> | |
| 8652 <synopsis>Raw Monitor Notify</synopsis> | |
| 8653 <description> | |
| 8654 Notify a single thread waiting on the raw monitor. | |
| 8655 </description> | |
| 8656 <origin>jvmdi</origin> | |
| 8657 <capabilities> | |
| 8658 </capabilities> | |
| 8659 <parameters> | |
| 8660 <param id="monitor"> | |
| 8661 <jrawMonitorID/> | |
| 8662 <description> | |
| 8663 The monitor | |
| 8664 </description> | |
| 8665 </param> | |
| 8666 </parameters> | |
| 8667 <errors> | |
| 8668 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8669 Not monitor owner | |
| 8670 </error> | |
| 8671 </errors> | |
| 8672 </function> | |
| 8673 | |
| 8674 <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37"> | |
| 8675 <synopsis>Raw Monitor Notify All</synopsis> | |
| 8676 <description> | |
| 8677 Notify all threads waiting on the raw monitor. | |
| 8678 </description> | |
| 8679 <origin>jvmdi</origin> | |
| 8680 <capabilities> | |
| 8681 </capabilities> | |
| 8682 <parameters> | |
| 8683 <param id="monitor"> | |
| 8684 <jrawMonitorID/> | |
| 8685 <description> | |
| 8686 The monitor | |
| 8687 </description> | |
| 8688 </param> | |
| 8689 </parameters> | |
| 8690 <errors> | |
| 8691 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8692 Not monitor owner | |
| 8693 </error> | |
| 8694 </errors> | |
| 8695 </function> | |
| 8696 | |
| 8697 <elide> | |
| 8698 <function id="GetRawMonitorUse" num="118"> | |
| 8699 <synopsis>Get Raw Monitor Use</synopsis> | |
| 8700 <description> | |
| 8701 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure | |
| 8702 are filled in with information about usage of the raw monitor. | |
| 8703 </description> | |
| 8704 <origin>new</origin> | |
| 8705 <capabilities> | |
| 8706 <required id="can_get_raw_monitor_usage"></required> | |
| 8707 </capabilities> | |
| 8708 <parameters> | |
| 8709 <param id="monitor"> | |
| 8710 <jrawMonitorID/> | |
| 8711 <description> | |
| 8712 the raw monitor to query. | |
| 8713 </description> | |
| 8714 </param> | |
| 8715 <param id="info_ptr"> | |
| 8716 <outptr><struct>jvmtiMonitorUsage</struct></outptr> | |
| 8717 <description> | |
| 8718 On return, filled with monitor information for the | |
| 8719 specified raw monitor. | |
| 8720 </description> | |
| 8721 </param> | |
| 8722 </parameters> | |
| 8723 <errors> | |
| 8724 </errors> | |
| 8725 </function> | |
| 8726 | |
| 8727 <function id="GetRawMonitors" num="119"> | |
| 8728 <synopsis>Get Raw Monitors</synopsis> | |
| 8729 <description> | |
| 8730 Return the list of raw monitors. | |
| 8731 <p/> | |
| 8732 Note: details about each monitor can be examined with | |
| 8733 <functionlink id="GetRawMonitorUse"></functionlink>. | |
| 8734 </description> | |
| 8735 <origin>new</origin> | |
| 8736 <capabilities> | |
| 8737 <required id="can_get_raw_monitor_usage"></required> | |
| 8738 </capabilities> | |
| 8739 <parameters> | |
| 8740 <param id="monitorCnt"> | |
| 8741 <outptr><jint/></outptr> | |
| 8742 <description> | |
| 8743 On return, pointer to the number | |
| 8744 of monitors returned in <code>monitors_ptr</code>. | |
| 8745 </description> | |
| 8746 </param> | |
| 8747 <param id="monitors_ptr"> | |
| 8748 <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf> | |
| 8749 <description> | |
| 8750 On return, pointer to the monitor list. | |
| 8751 </description> | |
| 8752 </param> | |
| 8753 </parameters> | |
| 8754 <errors> | |
| 8755 </errors> | |
| 8756 </function> | |
| 8757 </elide> | |
| 8758 </category> | |
| 8759 | |
| 8760 <category id="jniIntercept" label="JNI Function Interception"> | |
| 8761 | |
| 8762 <intro> | |
| 8763 Provides the ability to intercept and resend | |
| 8764 Java Native Interface (JNI) function calls | |
| 8765 by manipulating the JNI function table. | |
| 6919 | 8766 See <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html">JNI |
| 0 | 8767 Functions</externallink> in the <i>Java Native Interface Specification</i>. |
| 8768 <p/> | |
| 8769 The following example illustrates intercepting the | |
| 8770 <code>NewGlobalRef</code> JNI call in order to count reference | |
| 8771 creation. | |
| 8772 <example> | |
| 8773 JNIEnv original_jni_Functions; | |
| 8774 JNIEnv redirected_jni_Functions; | |
| 8775 int my_global_ref_count = 0; | |
| 8776 | |
| 8777 jobject | |
| 8778 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) { | |
| 8779 ++my_global_ref_count; | |
| 8780 return originalJNIFunctions->NewGlobalRef(env, lobj); | |
| 8781 } | |
| 8782 | |
| 8783 void | |
| 8784 myInit() { | |
| 8785 jvmtiError err; | |
| 8786 | |
| 8787 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &original_jni_Functions); | |
| 8788 if (err != JVMTI_ERROR_NONE) { | |
| 8789 die(); | |
| 8790 } | |
| 8791 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &redirected_jni_Functions); | |
| 8792 if (err != JVMTI_ERROR_NONE) { | |
| 8793 die(); | |
| 8794 } | |
| 8795 redirectedJNIFunctions->NewGlobalRef = MyNewGlobalRef; | |
| 8796 err = (*jvmti_env)->SetJNIFunctionTable(jvmti_env, redirected_jni_Functions); | |
| 8797 if (err != JVMTI_ERROR_NONE) { | |
| 8798 die(); | |
| 8799 } | |
| 8800 } | |
| 8801 </example> | |
| 8802 Sometime after <code>myInit</code> is called the user's JNI | |
| 8803 code is executed which makes the call to create a new global | |
| 8804 reference. Instead of going to the normal JNI implementation | |
| 8805 the call goes to <code>myNewGlobalRef</code>. Note that a | |
| 8806 copy of the original function table is kept so that the normal | |
| 8807 JNI function can be called after the data is collected. | |
| 8808 Note also that any JNI functions which are not overwritten | |
| 8809 will behave normally. | |
| 8810 <todo> | |
| 8811 check that the example compiles and executes. | |
| 8812 </todo> | |
| 8813 </intro> | |
| 8814 | |
| 8815 <function id="SetJNIFunctionTable" phase="start" num="120"> | |
| 8816 <synopsis>Set JNI Function Table</synopsis> | |
| 8817 <description> | |
| 8818 Set the JNI function table | |
| 8819 in all current and future JNI environments. | |
| 8820 As a result, all future JNI calls are directed to the specified functions. | |
| 8821 Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the | |
| 8822 function table to pass to this function. | |
| 8823 For this function to take effect the the updated table entries must be | |
| 8824 used by the JNI clients. | |
| 8825 Since the table is defined <code>const</code> some compilers may optimize | |
| 8826 away the access to the table, thus preventing this function from taking | |
| 8827 effect. | |
| 8828 The table is copied--changes to the local copy of the | |
| 8829 table have no effect. | |
| 8830 This function affects only the function table, all other aspects of the environment are | |
| 8831 unaffected. | |
| 8832 See the examples <internallink id="jniIntercept">above</internallink>. | |
| 8833 </description> | |
| 8834 <origin>new</origin> | |
| 8835 <capabilities> | |
| 8836 </capabilities> | |
| 8837 <parameters> | |
| 8838 <param id="function_table"> | |
| 8839 <inptr> | |
| 8840 <struct>jniNativeInterface</struct> | |
| 8841 </inptr> | |
| 8842 <description> | |
| 8843 Points to the new JNI function table. | |
| 8844 </description> | |
| 8845 </param> | |
| 8846 </parameters> | |
| 8847 <errors> | |
| 8848 </errors> | |
| 8849 </function> | |
| 8850 | |
| 8851 <function id="GetJNIFunctionTable" phase="start" num="121"> | |
| 8852 <synopsis>Get JNI Function Table</synopsis> | |
| 8853 <description> | |
| 8854 Get the JNI function table. | |
| 8855 The JNI function table is copied into allocated memory. | |
| 8856 If <functionlink id="SetJNIFunctionTable"></functionlink> | |
| 8857 has been called, the modified (not the original) function | |
| 8858 table is returned. | |
| 8859 Only the function table is copied, no other aspects of the environment | |
| 8860 are copied. | |
| 8861 See the examples <internallink id="jniIntercept">above</internallink>. | |
| 8862 </description> | |
| 8863 <origin>new</origin> | |
| 8864 <capabilities> | |
| 8865 </capabilities> | |
| 8866 <parameters> | |
| 8867 <param id="function_table"> | |
| 8868 <allocbuf> | |
| 8869 <struct>jniNativeInterface</struct> | |
| 8870 </allocbuf> | |
| 8871 <description> | |
| 8872 On return, <code>*function_table</code> | |
| 8873 points a newly allocated copy of the JNI function table. | |
| 8874 </description> | |
| 8875 </param> | |
| 8876 </parameters> | |
| 8877 <errors> | |
| 8878 </errors> | |
| 8879 </function> | |
| 8880 | |
| 8881 </category> | |
| 8882 | |
| 8883 <category id="eventManagement" label="Event Management"> | |
| 8884 | |
| 8885 <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122"> | |
| 8886 <synopsis>Set Event Callbacks</synopsis> | |
| 8887 <description> | |
| 8888 Set the functions to be called for each event. | |
| 8889 The callbacks are specified by supplying a replacement function table. | |
| 8890 The function table is copied--changes to the local copy of the | |
| 8891 table have no effect. | |
| 8892 This is an atomic action, all callbacks are set at once. | |
| 8893 No events are sent before this function is called. | |
| 8894 When an entry is <code>NULL</code> or when the event is beyond | |
| 8895 <paramlink id="size_of_callbacks"></paramlink> no event is sent. | |
| 8896 Details on events are | |
| 8897 described <internallink id="EventSection">later</internallink> in this document. | |
| 8898 An event must be enabled and have a callback in order to be | |
| 8899 sent--the order in which this function and | |
| 8900 <functionlink id="SetEventNotificationMode"></functionlink> | |
| 8901 are called does not affect the result. | |
| 8902 </description> | |
| 8903 <origin>new</origin> | |
| 8904 <capabilities> | |
| 8905 </capabilities> | |
| 8906 <parameters> | |
| 8907 <param id="callbacks"> | |
| 8908 <inptr> | |
| 8909 <struct>jvmtiEventCallbacks</struct> | |
| 8910 <nullok>remove the existing callbacks</nullok> | |
| 8911 </inptr> | |
| 8912 <description> | |
| 8913 The new event callbacks. | |
| 8914 </description> | |
| 8915 </param> | |
| 8916 <param id="size_of_callbacks"> | |
| 8917 <jint min="0"/> | |
| 8918 <description> | |
| 8919 <code>sizeof(jvmtiEventCallbacks)</code>--for version | |
| 8920 compatibility. | |
| 8921 </description> | |
| 8922 </param> | |
| 8923 </parameters> | |
| 8924 <errors> | |
| 8925 </errors> | |
| 8926 </function> | |
| 8927 | |
| 8928 <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2"> | |
| 8929 <synopsis>Set Event Notification Mode</synopsis> | |
| 8930 <description> | |
| 8931 Control the generation of events. | |
| 8932 <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum"> | |
| 8933 <constant id="JVMTI_ENABLE" num="1"> | |
| 8934 If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>, | |
| 8935 the event <paramlink id="event_type"></paramlink> will be enabled | |
| 8936 </constant> | |
| 8937 <constant id="JVMTI_DISABLE" num="0"> | |
| 8938 If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>, | |
| 8939 the event <paramlink id="event_type"></paramlink> will be disabled | |
| 8940 </constant> | |
| 8941 </constants> | |
| 8942 If <code>thread</code> is <code>NULL</code>, | |
| 8943 the event is enabled or disabled globally; otherwise, it is | |
| 8944 enabled or disabled for a particular thread. | |
| 8945 An event is generated for | |
| 8946 a particular thread if it is enabled either at the thread or global | |
| 8947 levels. | |
| 8948 <p/> | |
| 8949 See <internallink id="EventIndex">below</internallink> for information on specific events. | |
| 8950 <p/> | |
| 8951 The following events cannot be controlled at the thread | |
| 8952 level through this function. | |
| 8953 <ul> | |
| 8954 <li><eventlink id="VMInit"></eventlink></li> | |
| 8955 <li><eventlink id="VMStart"></eventlink></li> | |
| 8956 <li><eventlink id="VMDeath"></eventlink></li> | |
| 8957 <li><eventlink id="ThreadStart"></eventlink></li> | |
| 8958 <li><eventlink id="CompiledMethodLoad"></eventlink></li> | |
| 8959 <li><eventlink id="CompiledMethodUnload"></eventlink></li> | |
| 8960 <li><eventlink id="DynamicCodeGenerated"></eventlink></li> | |
| 8961 <li><eventlink id="DataDumpRequest"></eventlink></li> | |
| 8962 </ul> | |
| 8963 <p/> | |
| 8964 Initially, no events are enabled at either the thread level | |
| 8965 or the global level. | |
| 8966 <p/> | |
| 8967 Any needed capabilities (see Event Enabling Capabilities below) must be possessed | |
| 8968 before calling this function. | |
| 8969 <p/> | |
| 8970 Details on events are | |
| 8971 described <internallink id="EventSection">below</internallink>. | |
| 8972 </description> | |
| 8973 <origin>jvmdiClone</origin> | |
| 8974 <eventcapabilities></eventcapabilities> | |
| 8975 <parameters> | |
| 8976 <param id="mode"> | |
| 8977 <enum>jvmtiEventMode</enum> | |
| 8978 <description> | |
| 8979 <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code> | |
| 8980 </description> | |
| 8981 </param> | |
| 8982 <param id="event_type"> | |
| 8983 <enum>jvmtiEvent</enum> | |
| 8984 <description> | |
| 8985 the event to control | |
| 8986 </description> | |
| 8987 </param> | |
| 8988 <param id="event_thread"> | |
| 8989 <ptrtype> | |
| 8990 <jthread impl="noconvert"/> | |
| 8991 <nullok>event is controlled at the global level</nullok> | |
| 8992 </ptrtype> | |
| 8993 <description> | |
| 8994 The thread to control | |
| 8995 </description> | |
| 8996 </param> | |
| 8997 <param id="..."> | |
| 8998 <varargs/> | |
| 8999 <description> | |
| 9000 for future expansion | |
| 9001 </description> | |
| 9002 </param> | |
| 9003 </parameters> | |
| 9004 <errors> | |
| 9005 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
| 9006 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread. | |
| 9007 </error> | |
| 9008 <error id="JVMTI_ERROR_THREAD_NOT_ALIVE"> | |
| 9009 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead). | |
| 9010 </error> | |
| 9011 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 9012 thread level control was attempted on events which do not | |
| 9013 permit thread level control. | |
| 9014 </error> | |
| 9015 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> | |
| 9016 The Required Event Enabling Capability is not possessed. | |
| 9017 </error> | |
| 9018 </errors> | |
| 9019 </function> | |
| 9020 | |
| 9021 <function id="GenerateEvents" num="123"> | |
| 9022 <synopsis>Generate Events</synopsis> | |
| 9023 <description> | |
| 9024 Generate events to represent the current state of the VM. | |
| 9025 For example, if <paramlink id="event_type"/> is | |
| 9026 <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>, | |
| 9027 a <eventlink id="CompiledMethodLoad"></eventlink> event will be | |
| 9028 sent for each currently compiled method. | |
| 9029 Methods that were loaded and now have been unloaded are not sent. | |
| 9030 The history of what events have previously been sent does not | |
| 9031 effect what events are sent by this function--for example, | |
| 9032 all currently compiled methods | |
| 9033 will be sent each time this function is called. | |
| 9034 <p/> | |
| 9035 This function is useful when | |
| 9036 events may have been missed due to the agent attaching after program | |
| 9037 execution begins; this function generates the missed events. | |
| 9038 <p/> | |
| 9039 Attempts to execute Java programming language code or | |
| 9040 JNI functions may be paused until this function returns - | |
| 9041 so neither should be called from the thread sending the event. | |
| 9042 This function returns only after the missed events have been | |
| 9043 sent, processed and have returned. | |
| 9044 The event may be sent on a different thread than the thread | |
| 9045 on which the event occurred. | |
| 9046 The callback for the event must be set with | |
| 9047 <functionlink id="SetEventCallbacks"></functionlink> | |
| 9048 and the event must be enabled with | |
| 9049 <functionlink id="SetEventNotificationMode"></functionlink> | |
| 9050 or the events will not occur. | |
| 9051 If the VM no longer has the information to generate some or | |
| 9052 all of the requested events, the events are simply not sent - | |
| 9053 no error is returned. | |
| 9054 <p/> | |
| 9055 Only the following events are supported: | |
| 9056 <ul> | |
| 9057 <li><eventlink id="CompiledMethodLoad"></eventlink></li> | |
| 9058 <li><eventlink id="DynamicCodeGenerated"></eventlink></li> | |
| 9059 </ul> | |
| 9060 </description> | |
| 9061 <origin>new</origin> | |
| 9062 <capabilities> | |
| 9063 <capability id="can_generate_compiled_method_load_events"></capability> | |
| 9064 </capabilities> | |
| 9065 <parameters> | |
| 9066 <param id="event_type"> | |
| 9067 <enum>jvmtiEvent</enum> | |
| 9068 <description> | |
| 9069 The type of event to generate. Must be one of these: | |
| 9070 <ul> | |
| 9071 <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li> | |
| 9072 <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li> | |
| 9073 </ul> | |
| 9074 </description> | |
| 9075 </param> | |
| 9076 </parameters> | |
| 9077 <errors> | |
| 9078 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> | |
| 9079 <paramlink id="event_type"/> is | |
| 9080 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> | |
| 9081 and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink> | |
| 9082 is <code>false</code>. | |
| 9083 </error> | |
| 9084 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 9085 <paramlink id="event_type"/> is other than | |
| 9086 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> | |
| 9087 or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>. | |
| 9088 </error> | |
| 9089 </errors> | |
| 9090 </function> | |
| 9091 | |
| 9092 </category> | |
| 9093 | |
| 9094 <category id="extension" label="Extension Mechanism"> | |
| 9095 | |
| 9096 <intro> | |
| 9097 These functions | |
| 9098 allow a <jvmti/> implementation to provide functions and events | |
| 9099 beyond those defined in this specification. | |
| 9100 <p/> | |
| 9101 Both extension functions and extension events have parameters | |
| 9102 each of which has a 'type' and 'kind' chosen from the following tables: | |
| 9103 | |
| 9104 <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum"> | |
| 9105 <constant id="JVMTI_TYPE_JBYTE" num="101"> | |
| 9106 Java programming language primitive type - <code>byte</code>. | |
| 9107 JNI type <code>jbyte</code>. | |
| 9108 </constant> | |
| 9109 <constant id="JVMTI_TYPE_JCHAR" num="102"> | |
| 9110 Java programming language primitive type - <code>char</code>. | |
| 9111 JNI type <code>jchar</code>. | |
| 9112 </constant> | |
| 9113 <constant id="JVMTI_TYPE_JSHORT" num="103"> | |
| 9114 Java programming language primitive type - <code>short</code>. | |
| 9115 JNI type <code>jshort</code>. | |
| 9116 </constant> | |
| 9117 <constant id="JVMTI_TYPE_JINT" num="104"> | |
| 9118 Java programming language primitive type - <code>int</code>. | |
| 9119 JNI type <datalink id="jint"></datalink>. | |
| 9120 </constant> | |
| 9121 <constant id="JVMTI_TYPE_JLONG" num="105"> | |
| 9122 Java programming language primitive type - <code>long</code>. | |
| 9123 JNI type <datalink id="jlong"></datalink>. | |
| 9124 </constant> | |
| 9125 <constant id="JVMTI_TYPE_JFLOAT" num="106"> | |
| 9126 Java programming language primitive type - <code>float</code>. | |
| 9127 JNI type <datalink id="jfloat"></datalink>. | |
| 9128 </constant> | |
| 9129 <constant id="JVMTI_TYPE_JDOUBLE" num="107"> | |
| 9130 Java programming language primitive type - <code>double</code>. | |
| 9131 JNI type <datalink id="jdouble"></datalink>. | |
| 9132 </constant> | |
| 9133 <constant id="JVMTI_TYPE_JBOOLEAN" num="108"> | |
| 9134 Java programming language primitive type - <code>boolean</code>. | |
| 9135 JNI type <datalink id="jboolean"></datalink>. | |
| 9136 </constant> | |
| 9137 <constant id="JVMTI_TYPE_JOBJECT" num="109"> | |
| 9138 Java programming language object type - <code>java.lang.Object</code>. | |
| 9139 JNI type <datalink id="jobject"></datalink>. | |
| 9140 Returned values are JNI local references and must be managed. | |
| 9141 </constant> | |
| 9142 <constant id="JVMTI_TYPE_JTHREAD" num="110"> | |
| 9143 Java programming language object type - <code>java.lang.Thread</code>. | |
| 9144 <jvmti/> type <datalink id="jthread"></datalink>. | |
| 9145 Returned values are JNI local references and must be managed. | |
| 9146 </constant> | |
| 9147 <constant id="JVMTI_TYPE_JCLASS" num="111"> | |
| 9148 Java programming language object type - <code>java.lang.Class</code>. | |
| 9149 JNI type <datalink id="jclass"></datalink>. | |
| 9150 Returned values are JNI local references and must be managed. | |
| 9151 </constant> | |
| 9152 <constant id="JVMTI_TYPE_JVALUE" num="112"> | |
| 9153 Union of all Java programming language primitive and object types - | |
| 9154 JNI type <datalink id="jvalue"></datalink>. | |
| 9155 Returned values which represent object types are JNI local references and must be managed. | |
| 9156 </constant> | |
| 9157 <constant id="JVMTI_TYPE_JFIELDID" num="113"> | |
| 9158 Java programming language field identifier - | |
| 9159 JNI type <datalink id="jfieldID"></datalink>. | |
| 9160 </constant> | |
| 9161 <constant id="JVMTI_TYPE_JMETHODID" num="114"> | |
| 9162 Java programming language method identifier - | |
| 9163 JNI type <datalink id="jmethodID"></datalink>. | |
| 9164 </constant> | |
| 9165 <constant id="JVMTI_TYPE_CCHAR" num="115"> | |
| 9166 C programming language type - <code>char</code>. | |
| 9167 </constant> | |
| 9168 <constant id="JVMTI_TYPE_CVOID" num="116"> | |
| 9169 C programming language type - <code>void</code>. | |
| 9170 </constant> | |
| 9171 <constant id="JVMTI_TYPE_JNIENV" num="117"> | |
| 9172 JNI environment - <code>JNIEnv</code>. | |
| 9173 Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type. | |
| 9174 </constant> | |
| 9175 </constants> | |
| 9176 | |
| 9177 <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum"> | |
| 9178 <constant id="JVMTI_KIND_IN" num="91"> | |
| 9179 Ingoing argument - <code>foo</code>. | |
| 9180 </constant> | |
| 9181 <constant id="JVMTI_KIND_IN_PTR" num="92"> | |
| 9182 Ingoing pointer argument - <code>const foo*</code>. | |
| 9183 </constant> | |
| 9184 <constant id="JVMTI_KIND_IN_BUF" num="93"> | |
| 9185 Ingoing array argument - <code>const foo*</code>. | |
| 9186 </constant> | |
| 9187 <constant id="JVMTI_KIND_ALLOC_BUF" num="94"> | |
| 9188 Outgoing allocated array argument - <code>foo**</code>. | |
| 9189 Free with <code>Deallocate</code>. | |
| 9190 </constant> | |
| 9191 <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95"> | |
| 9192 Outgoing allocated array of allocated arrays argument - <code>foo***</code>. | |
| 9193 Free with <code>Deallocate</code>. | |
| 9194 </constant> | |
| 9195 <constant id="JVMTI_KIND_OUT" num="96"> | |
| 9196 Outgoing argument - <code>foo*</code>. | |
| 9197 </constant> | |
| 9198 <constant id="JVMTI_KIND_OUT_BUF" num="97"> | |
| 9199 Outgoing array argument (pre-allocated by agent) - <code>foo*</code>. | |
| 9200 Do not <code>Deallocate</code>. | |
| 9201 </constant> | |
| 9202 </constants> | |
| 9203 | |
| 9204 </intro> | |
| 9205 | |
| 9206 <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info"> | |
| 9207 <field id="name"> | |
| 9208 <allocfieldbuf><char/></allocfieldbuf> | |
| 9209 <description> | |
| 9210 The parameter name, encoded as a | |
| 9211 <internallink id="mUTF">modified UTF-8</internallink> string | |
| 9212 </description> | |
| 9213 </field> | |
| 9214 <field id="kind"> | |
| 9215 <enum>jvmtiParamKind</enum> | |
| 9216 <description> | |
| 9217 The kind of the parameter - type modifiers | |
| 9218 </description> | |
| 9219 </field> | |
| 9220 <field id="base_type"> | |
| 9221 <enum>jvmtiParamTypes</enum> | |
| 9222 <description> | |
| 9223 The base type of the parameter - modified by <code>kind</code> | |
| 9224 </description> | |
| 9225 </field> | |
| 9226 <field id="null_ok"> | |
| 9227 <jboolean/> | |
| 9228 <description> | |
| 9229 Is a <code>NULL</code> argument permitted? Applies only to pointer and object types. | |
| 9230 </description> | |
| 9231 </field> | |
| 9232 </typedef> | |
| 9233 | |
| 9234 <callback id="jvmtiExtensionFunction"> | |
| 9235 <enum>jvmtiError</enum> | |
| 9236 <synopsis>Extension Function</synopsis> | |
| 9237 <description> | |
| 9238 This is the implementation-specific extension function. | |
| 9239 </description> | |
| 9240 <parameters> | |
| 9241 <param id="jvmti_env"> | |
| 9242 <outptr> | |
| 9243 <struct>jvmtiEnv</struct> | |
| 9244 </outptr> | |
| 9245 <description> | |
| 9246 The <jvmti/> environment is the only fixed parameter for extension functions. | |
| 9247 </description> | |
| 9248 </param> | |
| 9249 <param id="..."> | |
| 9250 <varargs/> | |
| 9251 <description> | |
| 9252 The extension function-specific parameters | |
| 9253 </description> | |
| 9254 </param> | |
| 9255 </parameters> | |
| 9256 </callback> | |
| 9257 | |
| 9258 <function id="GetExtensionFunctions" phase="onload" num="124"> | |
| 9259 <synopsis>Get Extension Functions</synopsis> | |
| 9260 | |
| 9261 <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info"> | |
| 9262 <field id="func"> | |
| 9263 <ptrtype> | |
| 9264 <struct>jvmtiExtensionFunction</struct> | |
| 9265 </ptrtype> | |
| 9266 <description> | |
| 9267 The actual function to call | |
| 9268 </description> | |
| 9269 </field> | |
| 9270 <field id="id"> | |
| 9271 <allocfieldbuf><char/></allocfieldbuf> | |
| 9272 <description> | |
| 9273 The identifier for the extension function, encoded as a | |
| 9274 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9275 Uses package name conventions. | |
| 9276 For example, <code>com.sun.hotspot.bar</code> | |
| 9277 </description> | |
| 9278 </field> | |
| 9279 <field id="short_description"> | |
| 9280 <allocfieldbuf><char/></allocfieldbuf> | |
| 9281 <description> | |
| 9282 A one sentence description of the function, encoded as a | |
| 9283 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9284 </description> | |
| 9285 </field> | |
| 9286 <field id="param_count"> | |
| 9287 <jint/> | |
| 9288 <description> | |
| 9289 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code> | |
| 9290 </description> | |
| 9291 </field> | |
| 9292 <field id="params"> | |
| 9293 <allocfieldbuf outcount="param_count"> | |
| 9294 <struct>jvmtiParamInfo</struct> | |
| 9295 </allocfieldbuf> | |
| 9296 <description> | |
| 9297 Array of | |
| 9298 <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> | |
| 9299 parameters (<code>jvmtiEnv *jvmti_env</code> excluded) | |
| 9300 </description> | |
| 9301 </field> | |
| 9302 <field id="error_count"> | |
| 9303 <jint/> | |
| 9304 <description> | |
| 9305 The number of possible error returns (excluding universal errors) | |
| 9306 </description> | |
| 9307 </field> | |
| 9308 <field id="errors"> | |
| 9309 <allocfieldbuf outcount="error_count"> | |
| 9310 <enum>jvmtiError</enum> | |
| 9311 </allocfieldbuf> | |
| 9312 <description> | |
| 9313 Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> | |
| 9314 possible errors | |
| 9315 </description> | |
| 9316 </field> | |
| 9317 </typedef> | |
| 9318 | |
| 9319 <description> | |
| 9320 Returns the set of extension functions. | |
| 9321 </description> | |
| 9322 <origin>new</origin> | |
| 9323 <capabilities> | |
| 9324 </capabilities> | |
| 9325 <parameters> | |
| 9326 <param id="extension_count_ptr"> | |
| 9327 <outptr><jint/></outptr> | |
| 9328 <description> | |
| 9329 On return, points to the number of extension functions | |
| 9330 </description> | |
| 9331 </param> | |
| 9332 <param id="extensions"> | |
| 9333 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf> | |
| 9334 <description> | |
| 9335 Returns an array of extension function info, one per function | |
| 9336 </description> | |
| 9337 </param> | |
| 9338 </parameters> | |
| 9339 <errors> | |
| 9340 </errors> | |
| 9341 </function> | |
| 9342 | |
| 9343 <function id="GetExtensionEvents" phase="onload" num="125"> | |
| 9344 <synopsis>Get Extension Events</synopsis> | |
| 9345 | |
| 9346 <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info"> | |
| 9347 <field id="extension_event_index"> | |
| 9348 <jint/> | |
| 9349 <description> | |
| 9350 The identifying index of the event | |
| 9351 </description> | |
| 9352 </field> | |
| 9353 <field id="id"> | |
| 9354 <allocfieldbuf><char/></allocfieldbuf> | |
| 9355 <description> | |
| 9356 The identifier for the extension event, encoded as a | |
| 9357 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9358 Uses package name conventions. | |
| 9359 For example, <code>com.sun.hotspot.bar</code> | |
| 9360 </description> | |
| 9361 </field> | |
| 9362 <field id="short_description"> | |
| 9363 <allocfieldbuf><char/></allocfieldbuf> | |
| 9364 <description> | |
| 9365 A one sentence description of the event, encoded as a | |
| 9366 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9367 </description> | |
| 9368 </field> | |
| 9369 <field id="param_count"> | |
| 9370 <jint/> | |
| 9371 <description> | |
| 9372 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code> | |
| 9373 </description> | |
| 9374 </field> | |
| 9375 <field id="params"> | |
| 9376 <allocfieldbuf outcount="param_count"> | |
| 9377 <struct>jvmtiParamInfo</struct> | |
| 9378 </allocfieldbuf> | |
| 9379 <description> | |
| 9380 Array of | |
| 9381 <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink> | |
| 9382 parameters (<code>jvmtiEnv *jvmti_env</code> excluded) | |
| 9383 </description> | |
| 9384 </field> | |
| 9385 </typedef> | |
| 9386 | |
| 9387 <description> | |
| 9388 Returns the set of extension events. | |
| 9389 </description> | |
| 9390 <origin>new</origin> | |
| 9391 <capabilities> | |
| 9392 </capabilities> | |
| 9393 <parameters> | |
| 9394 <param id="extension_count_ptr"> | |
| 9395 <outptr><jint/></outptr> | |
| 9396 <description> | |
| 9397 On return, points to the number of extension events | |
| 9398 </description> | |
| 9399 </param> | |
| 9400 <param id="extensions"> | |
| 9401 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf> | |
| 9402 <description> | |
| 9403 Returns an array of extension event info, one per event | |
| 9404 </description> | |
| 9405 </param> | |
| 9406 </parameters> | |
| 9407 <errors> | |
| 9408 </errors> | |
| 9409 </function> | |
| 9410 | |
| 9411 <callback id="jvmtiExtensionEvent"> | |
| 9412 <void/> | |
| 9413 <synopsis>Extension Event</synopsis> | |
| 9414 <description> | |
| 9415 This is the implementation-specific event. | |
| 9416 The event handler is set with | |
| 9417 <functionlink id="SetExtensionEventCallback"/>. | |
| 9418 <p/> | |
| 9419 Event handlers for extension events must be declared varargs to match this definition. | |
| 9420 Failure to do so could result in calling convention mismatch and undefined behavior | |
| 9421 on some platforms. | |
| 9422 <p/> | |
| 9423 For example, if the <code>jvmtiParamInfo</code> | |
| 9424 returned by <functionlink id="GetExtensionEvents"/> indicates that | |
| 9425 there is a <code>jint</code> parameter, the event handler should be | |
| 9426 declared: | |
| 9427 <example> | |
| 9428 void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...) | |
| 9429 </example> | |
| 9430 Note the terminal "<code>...</code>" which indicates varargs. | |
| 9431 </description> | |
| 9432 <parameters> | |
| 9433 <param id="jvmti_env"> | |
| 9434 <outptr> | |
| 9435 <struct>jvmtiEnv</struct> | |
| 9436 </outptr> | |
| 9437 <description> | |
| 9438 The <jvmti/> environment is the only fixed parameter for extension events. | |
| 9439 </description> | |
| 9440 </param> | |
| 9441 <param id="..."> | |
| 9442 <varargs/> | |
| 9443 <description> | |
| 9444 The extension event-specific parameters | |
| 9445 </description> | |
| 9446 </param> | |
| 9447 </parameters> | |
| 9448 </callback> | |
| 9449 | |
| 9450 <function id="SetExtensionEventCallback" phase="onload" num="126"> | |
| 9451 <synopsis>Set Extension Event Callback</synopsis> | |
| 9452 | |
| 9453 <description> | |
| 9454 Sets the callback function for an extension event and | |
| 9455 enables the event. Or, if the callback is <code>NULL</code>, disables | |
| 9456 the event. Note that unlike standard events, setting | |
| 9457 the callback and enabling the event are a single operation. | |
| 9458 </description> | |
| 9459 <origin>new</origin> | |
| 9460 <capabilities> | |
| 9461 </capabilities> | |
| 9462 <parameters> | |
| 9463 <param id="extension_event_index"> | |
| 9464 <jint/> | |
| 9465 <description> | |
| 9466 Identifies which callback to set. | |
| 9467 This index is the | |
| 9468 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink> | |
| 9469 field of | |
| 9470 <datalink id="jvmtiExtensionEventInfo"/>. | |
| 9471 </description> | |
| 9472 </param> | |
| 9473 <param id="callback"> | |
| 9474 <ptrtype> | |
| 9475 <struct>jvmtiExtensionEvent</struct> | |
| 9476 <nullok>disable the event</nullok> | |
| 9477 </ptrtype> | |
| 9478 <description> | |
| 9479 If <code>callback</code> is non-<code>NULL</code>, | |
| 9480 set <code>callback</code> to be the event callback function | |
| 9481 and enable the event. | |
| 9482 </description> | |
| 9483 </param> | |
| 9484 </parameters> | |
| 9485 <errors> | |
| 9486 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 9487 <paramlink id="extension_event_index"/> is not an | |
| 9488 <fieldlink id="extension_event_index" | |
| 9489 struct="jvmtiExtensionEventInfo"/> | |
| 9490 returned by | |
| 9491 <functionlink id="GetExtensionEvents"/> | |
| 9492 </error> | |
| 9493 </errors> | |
| 9494 </function> | |
| 9495 | |
| 9496 </category> | |
| 9497 | |
| 9498 <category id="capability" label="Capability"> | |
| 9499 | |
| 9500 <intro> | |
| 9501 The capabilities functions allow you to change the | |
| 9502 functionality available to <jvmti/>--that is, | |
| 9503 which <jvmti/> | |
| 9504 functions can be called, what events can be generated, | |
| 9505 and what functionality these events and functions can | |
| 9506 provide. | |
| 9507 <p/> | |
| 9508 The "Capabilities" section of each function and event describe which | |
| 9509 capabilities, if any, they are associated with. "Required Functionality" | |
| 9510 means it is available for use and no capabilities must be added to use it. | |
| 9511 "Optional Functionality" means the agent must possess the capability | |
| 9512 before it can be used. | |
| 9513 To possess a capability, the agent must | |
| 9514 <functionlink id="AddCapabilities">add the capability</functionlink>. | |
| 9515 "Optional Features" describe capabilities which, | |
| 9516 if added, extend the feature set. | |
| 9517 <p/> | |
| 9518 The potentially available capabilities of each <jvmti/> implementation are different. | |
| 9519 Depending on the implementation, a capability: | |
| 9520 <ul> | |
| 9521 <li>may never be added</li> | |
| 9522 <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li> | |
| 9523 <li>may be added only during the <code>OnLoad</code> phase</li> | |
| 9524 <li>may be possessed by only one environment at a time</li> | |
| 9525 <li>may be possessed by only one environment at a time, | |
| 9526 and only during the <code>OnLoad</code> phase</li> | |
| 9527 <li>and so on ...</li> | |
| 9528 </ul> | |
| 9529 Frequently, the addition of a capability may incur a cost in execution speed, start up | |
| 9530 time, and/or memory footprint. Note that the overhead of using a capability | |
| 9531 is completely different than the overhead of possessing a capability. | |
| 9532 Take single stepping as an example. When single stepping is on (that | |
| 9533 is, when the event is enabled and thus actively sending events) | |
| 9534 the overhead of sending and processing an event | |
| 9535 on each instruction is huge in any implementation. | |
| 9536 However, the overhead of possessing the capability may be small or large, | |
| 9537 depending on the implementation. Also, when and if a capability is potentially | |
| 9538 available depends on the implementation. Some examples: | |
| 9539 <ul> | |
| 9540 <li>One VM might perform all execution by compiling bytecodes into | |
| 9541 native code and be unable to generate single step instructions. | |
| 9542 In this implementation the capability can not be added.</li> | |
| 9543 <li>Another VM may be able to switch execution to a single stepping | |
| 9544 interpreter at any time. In this implementation, having the capability has no | |
| 9545 overhead and could be added at any time.</li> | |
| 9546 <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted | |
| 9547 execution engine at start up, but be unable to switch between them. | |
| 9548 In this implementation the capability would need to be added | |
| 9549 during the <code>OnLoad</code> phase (before bytecode | |
| 9550 execution begins) and would have a large impact on execution speed | |
| 9551 even if single stepping was never used.</li> | |
| 9552 <li>Still another VM might be able to add an "is single stepping on" check | |
| 9553 into compiled bytecodes or a generated interpreter. Again in this implementation | |
| 9554 the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test | |
| 9555 and branch on each instruction) would be considerably less.</li> | |
| 9556 </ul> | |
| 9557 <p/> | |
| 9558 Each <jvmti/> <internallink id="environments">environment</internallink> | |
| 9559 has its own set of capabilities. | |
| 9560 Initially, that set is empty. | |
| 9561 Any desired capability must be added. | |
| 9562 If possible, capabilities should be added during the <code>OnLoad</code> phase. For most | |
| 9563 virtual machines certain capabilities require special set up for | |
| 9564 the virtual machine and this set up must happen | |
| 9565 during the <code>OnLoad</code> phase, before the virtual machine begins execution. | |
| 9566 Once a capability is added, it can | |
| 9567 only be removed if explicitly relinquished by the environment. | |
| 9568 <p/> | |
| 9569 The agent can, | |
| 9570 <functionlink id="GetPotentialCapabilities">determine what | |
| 9571 capabilities this VM can potentially provide</functionlink>, | |
| 9572 <functionlink id="AddCapabilities">add the capabilities | |
| 9573 to be used</functionlink>, | |
| 9574 <functionlink id="RelinquishCapabilities">release capabilities | |
| 9575 which are no longer needed</functionlink>, and | |
| 9576 <functionlink id="GetCapabilities">examine the currently available | |
| 9577 capabilities</functionlink>. | |
| 9578 </intro> | |
| 9579 | |
| 9580 <intro id="capabilityExamples" label="Capability Examples"> | |
| 9581 For example, a freshly started agent (in the <code>OnLoad</code> function) | |
| 9582 wants to enable all possible capabilities. | |
| 9583 Note that, in general, this is not advisable as the agent may suffer | |
| 9584 a performance penalty for functionality it is not using. | |
| 9585 The code might look like this in C: | |
| 9586 <example> | |
| 9587 jvmtiCapabilities capa; | |
| 9588 jvmtiError err; | |
| 9589 | |
| 9590 err = (*jvmti)->GetPotentialCapabilities(jvmti, &capa); | |
| 9591 if (err == JVMTI_ERROR_NONE) { | |
| 9592 err = (*jvmti)->AddCapabilities(jvmti, &capa); | |
| 9593 </example> | |
| 9594 For example, if an agent wants to check if it can get | |
| 9595 the bytecodes of a method (that is, it wants to check | |
| 9596 if it previously added this capability and has not | |
| 9597 relinquished it), the code might | |
| 9598 look like this in C: | |
| 9599 <example> | |
| 9600 jvmtiCapabilities capa; | |
| 9601 jvmtiError err; | |
| 9602 | |
| 9603 err = (*jvmti)->GetCapabilities(jvmti, &capa); | |
| 9604 if (err == JVMTI_ERROR_NONE) { | |
| 9605 if (capa.can_get_bytecodes) { ... } } | |
| 9606 </example> | |
| 9607 </intro> | |
| 9608 | |
| 9609 <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure"> | |
| 9610 <description> | |
| 9611 The functions in this category use this capabilities structure | |
| 9612 which contains boolean flags corresponding to each capability: | |
| 9613 </description> | |
| 9614 <capabilityfield id="can_tag_objects"> | |
| 9615 <description> | |
| 9616 Can set and get tags, as described in the | |
| 9617 <internallink id="Heap">Heap category</internallink>. | |
| 9618 </description> | |
| 9619 </capabilityfield> | |
| 9620 <capabilityfield id="can_generate_field_modification_events"> | |
| 9621 <description> | |
| 9622 Can set watchpoints on field modification - | |
| 9623 <functionlink id="SetFieldModificationWatch"></functionlink> | |
| 9624 </description> | |
| 9625 </capabilityfield> | |
| 9626 <capabilityfield id="can_generate_field_access_events"> | |
| 9627 <description> | |
| 9628 Can set watchpoints on field access - | |
| 9629 <functionlink id="SetFieldAccessWatch"></functionlink> | |
| 9630 </description> | |
| 9631 </capabilityfield> | |
| 9632 <capabilityfield id="can_get_bytecodes"> | |
| 9633 <description> | |
| 9634 Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink> | |
| 9635 </description> | |
| 9636 </capabilityfield> | |
| 9637 <capabilityfield id="can_get_synthetic_attribute"> | |
| 9638 <description> | |
| 9639 Can test if a field or method is synthetic - | |
| 9640 <functionlink id="IsFieldSynthetic"></functionlink> and | |
| 9641 <functionlink id="IsMethodSynthetic"></functionlink> | |
| 9642 </description> | |
| 9643 </capabilityfield> | |
| 9644 <capabilityfield id="can_get_owned_monitor_info"> | |
| 9645 <description> | |
| 9646 Can get information about ownership of monitors - | |
| 9647 <functionlink id="GetOwnedMonitorInfo"></functionlink> | |
| 9648 </description> | |
| 9649 </capabilityfield> | |
| 9650 <capabilityfield id="can_get_current_contended_monitor"> | |
| 9651 <description> | |
| 9652 Can <functionlink id="GetCurrentContendedMonitor"></functionlink> | |
| 9653 </description> | |
| 9654 </capabilityfield> | |
| 9655 <capabilityfield id="can_get_monitor_info"> | |
| 9656 <description> | |
| 9657 Can <functionlink id="GetObjectMonitorUsage"></functionlink> | |
| 9658 </description> | |
| 9659 </capabilityfield> | |
| 9660 <capabilityfield id="can_pop_frame"> | |
| 9661 <description> | |
| 9662 Can pop frames off the stack - <functionlink id="PopFrame"></functionlink> | |
| 9663 </description> | |
| 9664 </capabilityfield> | |
| 9665 <capabilityfield id="can_redefine_classes"> | |
| 9666 <description> | |
| 9667 Can redefine classes with <functionlink id="RedefineClasses"/>. | |
| 9668 </description> | |
| 9669 </capabilityfield> | |
| 9670 <capabilityfield id="can_signal_thread"> | |
| 9671 <description> | |
| 9672 Can send stop or interrupt to threads | |
| 9673 </description> | |
| 9674 </capabilityfield> | |
| 9675 <capabilityfield id="can_get_source_file_name"> | |
| 9676 <description> | |
| 9677 Can get the source file name of a class | |
| 9678 </description> | |
| 9679 </capabilityfield> | |
| 9680 <capabilityfield id="can_get_line_numbers"> | |
| 9681 <description> | |
| 9682 Can get the line number table of a method | |
| 9683 </description> | |
| 9684 </capabilityfield> | |
| 9685 <capabilityfield id="can_get_source_debug_extension"> | |
| 9686 <description> | |
| 9687 Can get the source debug extension of a class | |
| 9688 </description> | |
| 9689 </capabilityfield> | |
| 9690 <capabilityfield id="can_access_local_variables"> | |
| 9691 <description> | |
| 9692 Can set and get local variables | |
| 9693 </description> | |
| 9694 </capabilityfield> | |
| 9695 <capabilityfield id="can_maintain_original_method_order"> | |
| 9696 <description> | |
| 9697 Can return methods in the order they occur in the class file | |
| 9698 </description> | |
| 9699 </capabilityfield> | |
| 9700 <capabilityfield id="can_generate_single_step_events"> | |
| 9701 <description> | |
| 9702 Can get <eventlink id="SingleStep">single step</eventlink> events | |
| 9703 </description> | |
| 9704 </capabilityfield> | |
| 9705 <capabilityfield id="can_generate_exception_events"> | |
| 9706 <description> | |
| 9707 Can get <eventlink id="Exception">exception thrown</eventlink> and | |
| 9708 <eventlink id="ExceptionCatch">exception catch</eventlink> events | |
| 9709 </description> | |
| 9710 </capabilityfield> | |
| 9711 <capabilityfield id="can_generate_frame_pop_events"> | |
| 9712 <description> | |
| 9713 Can <functionlink id="NotifyFramePop">set</functionlink> and thus get | |
| 9714 <eventlink id="FramePop"></eventlink> events | |
| 9715 </description> | |
| 9716 </capabilityfield> | |
| 9717 <capabilityfield id="can_generate_breakpoint_events"> | |
| 9718 <description> | |
| 9719 Can <functionlink id="SetBreakpoint">set</functionlink> and thus get | |
| 9720 <eventlink id="Breakpoint"></eventlink> events | |
| 9721 </description> | |
| 9722 </capabilityfield> | |
| 9723 <capabilityfield id="can_suspend"> | |
| 9724 <description> | |
| 9725 Can suspend and resume threads | |
| 9726 </description> | |
| 9727 </capabilityfield> | |
| 9728 <capabilityfield id="can_redefine_any_class"> | |
| 9729 <description> | |
| 9730 Can modify (retransform or redefine) any non-primitive non-array class. | |
| 9731 See <functionlink id="IsModifiableClass"/>. | |
| 9732 </description> | |
| 9733 </capabilityfield> | |
| 9734 <capabilityfield id="can_get_current_thread_cpu_time"> | |
| 9735 <description> | |
| 9736 Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink> | |
| 9737 current thread CPU time | |
| 9738 </description> | |
| 9739 </capabilityfield> | |
| 9740 <capabilityfield id="can_get_thread_cpu_time"> | |
| 9741 <description> | |
| 9742 Can <functionlink id="GetThreadCpuTime">get</functionlink> | |
| 9743 thread CPU time | |
| 9744 </description> | |
| 9745 </capabilityfield> | |
| 9746 <capabilityfield id="can_generate_method_entry_events" | |
| 9747 disp1="can_generate" disp2="_method_entry_events" | |
| 9748 > | |
| 9749 <description> | |
| 9750 Can generate method entry events on entering a method | |
| 9751 </description> | |
| 9752 </capabilityfield> | |
| 9753 <capabilityfield id="can_generate_method_exit_events" | |
| 9754 disp1="can_generate" disp2="_method_exit_events" | |
| 9755 > | |
| 9756 <description> | |
| 9757 Can generate method exit events on leaving a method | |
| 9758 </description> | |
| 9759 </capabilityfield> | |
| 9760 <capabilityfield id="can_generate_all_class_hook_events" | |
| 9761 disp1="can_generate" disp2="_all_class_hook_events" | |
| 9762 > | |
| 9763 <description> | |
| 9764 Can generate ClassFileLoadHook events for every loaded class. | |
| 9765 </description> | |
| 9766 </capabilityfield> | |
| 9767 <capabilityfield id="can_generate_compiled_method_load_events" | |
| 9768 disp1="can_generate" disp2="_compiled_method_load_events" | |
| 9769 > | |
| 9770 <description> | |
| 9771 Can generate events when a method is compiled or unloaded | |
| 9772 </description> | |
| 9773 </capabilityfield> | |
| 9774 <capabilityfield id="can_generate_monitor_events" | |
| 9775 disp1="can_generate" disp2="_monitor_events" | |
| 9776 > | |
| 9777 <description> | |
| 9778 Can generate events on monitor activity | |
| 9779 </description> | |
| 9780 </capabilityfield> | |
| 9781 <capabilityfield id="can_generate_vm_object_alloc_events" | |
| 9782 disp1="can_generate" disp2="_vm_object_alloc_events" | |
| 9783 > | |
| 9784 <description> | |
| 9785 Can generate events on VM allocation of an object | |
| 9786 </description> | |
| 9787 </capabilityfield> | |
| 9788 <capabilityfield id="can_generate_native_method_bind_events" | |
| 9789 disp1="can_generate" disp2="_native_method_bind_events" | |
| 9790 > | |
| 9791 <description> | |
| 9792 Can generate events when a native method is bound to its | |
| 9793 implementation | |
| 9794 </description> | |
| 9795 </capabilityfield> | |
| 9796 <capabilityfield id="can_generate_garbage_collection_events" | |
| 9797 disp1="can_generate" disp2="_garbage_collection_events" | |
| 9798 > | |
| 9799 <description> | |
| 9800 Can generate events when garbage collection begins or ends | |
| 9801 </description> | |
| 9802 </capabilityfield> | |
| 9803 <capabilityfield id="can_generate_object_free_events" | |
| 9804 disp1="can_generate" disp2="_object_free_events" | |
| 9805 > | |
| 9806 <description> | |
| 9807 Can generate events when the garbage collector frees an object | |
| 9808 </description> | |
| 9809 </capabilityfield> | |
| 9810 <capabilityfield id="can_force_early_return" since="1.1"> | |
| 9811 <description> | |
| 9812 Can return early from a method, as described in the | |
| 9813 <internallink id="ForceEarlyReturn">Force Early Return category</internallink>. | |
| 9814 </description> | |
| 9815 </capabilityfield> | |
| 9816 <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1"> | |
| 9817 <description> | |
| 9818 Can get information about owned monitors with stack depth - | |
| 9819 <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink> | |
| 9820 </description> | |
| 9821 </capabilityfield> | |
| 9822 <capabilityfield id="can_get_constant_pool" since="1.1"> | |
| 9823 <description> | |
| 9824 Can get the constant pool of a class - | |
| 9825 <functionlink id="GetConstantPool"></functionlink> | |
| 9826 </description> | |
| 9827 </capabilityfield> | |
| 9828 <capabilityfield id="can_set_native_method_prefix" since="1.1"> | |
| 9829 <description> | |
| 9830 Can set prefix to be applied when native method cannot be resolved - | |
| 9831 <functionlink id="SetNativeMethodPrefix"/> and | |
| 9832 <functionlink id="SetNativeMethodPrefixes"/> | |
| 9833 </description> | |
| 9834 </capabilityfield> | |
| 9835 <capabilityfield id="can_retransform_classes" since="1.1"> | |
| 9836 <description> | |
| 9837 Can retransform classes with <functionlink id="RetransformClasses"/>. | |
| 9838 In addition to the restrictions imposed by the specific | |
| 9839 implementation on this capability (see the | |
| 9840 <internallink id="capability">Capability</internallink> section), | |
| 9841 this capability must be set before the | |
| 9842 <eventlink id="ClassFileLoadHook"/> event is enabled for the | |
| 9843 first time in this environment. | |
| 9844 An environment that possesses this capability at the time that | |
| 9845 <code>ClassFileLoadHook</code> is enabled for the first time is | |
| 9846 said to be <i>retransformation capable</i>. | |
| 9847 An environment that does not possess this capability at the time that | |
| 9848 <code>ClassFileLoadHook</code> is enabled for the first time is | |
| 9849 said to be <i>retransformation incapable</i>. | |
| 9850 </description> | |
| 9851 </capabilityfield> | |
| 9852 <capabilityfield id="can_retransform_any_class" since="1.1"> | |
| 9853 <description> | |
| 9854 <functionlink id="RetransformClasses"/> can be called on any class | |
| 9855 (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> | |
| 9856 must also be set) | |
| 9857 </description> | |
| 9858 </capabilityfield> | |
| 9859 <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1"> | |
| 9860 <description> | |
| 9861 Can generate events when the VM is unable to allocate memory from | |
| 9862 the <tm>Java</tm> platform heap. | |
| 9863 See <eventlink id="ResourceExhausted"/>. | |
| 9864 </description> | |
| 9865 </capabilityfield> | |
| 9866 <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1"> | |
| 9867 <description> | |
| 9868 Can generate events when the VM is unable to create a thread. | |
| 9869 See <eventlink id="ResourceExhausted"/>. | |
| 9870 </description> | |
| 9871 </capabilityfield> | |
| 9872 </capabilitiestypedef> | |
| 9873 | |
| 9874 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140"> | |
| 9875 <synopsis>Get Potential Capabilities</synopsis> | |
| 9876 <description> | |
| 9877 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/> | |
| 9878 features that can potentially be possessed by this environment | |
| 9879 at this time. | |
| 9880 The returned capabilities differ from the complete set of capabilities | |
| 9881 implemented by the VM in two cases: another environment possesses | |
| 9882 capabilities that can only be possessed by one environment, or the | |
| 9883 current <functionlink id="GetPhase">phase</functionlink> is live, | |
| 9884 and certain capabilities can only be added during the <code>OnLoad</code> phase. | |
| 9885 The <functionlink id="AddCapabilities"></functionlink> function | |
| 9886 may be used to set any or all or these capabilities. | |
| 9887 Currently possessed capabilities are included. | |
| 9888 <p/> | |
| 9889 Typically this function is used in the <code>OnLoad</code> function. | |
| 9890 Some virtual machines may allow a limited set of capabilities to be | |
| 9891 added in the live phase. | |
| 9892 In this case, the set of potentially available capabilities | |
| 9893 will likely differ from the <code>OnLoad</code> phase set. | |
| 9894 <p/> | |
| 9895 See the | |
| 9896 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 9897 </description> | |
| 9898 <origin>new</origin> | |
| 9899 <capabilities> | |
| 9900 </capabilities> | |
| 9901 <parameters> | |
| 9902 <param id="capabilities_ptr"> | |
| 9903 <outptr><struct>jvmtiCapabilities</struct></outptr> | |
| 9904 <description> | |
| 9905 On return, points to the <jvmti/> capabilities that may be added. | |
| 9906 </description> | |
| 9907 </param> | |
| 9908 </parameters> | |
| 9909 <errors> | |
| 9910 </errors> | |
| 9911 </function> | |
| 9912 | |
| 9913 <elide> | |
| 9914 <function id="EstimateCostOfCapabilities" phase="onload" num="141"> | |
| 9915 <synopsis>Estimate Cost Of Capabilities</synopsis> | |
| 9916 <description> | |
| 9917 <issue>There is strong opposition to this function. The concern is | |
| 9918 that it would be difficult or impossible to provide meaningful | |
| 9919 numbers, as the amount of impact is conditional on many factors | |
| 9920 that a single number could not represent. There is doubt that | |
| 9921 conditional implementations would be used or are even a good idea. | |
| 9922 The thought is that release documentation for the implementation | |
| 9923 would be the best means of exposing this information. | |
| 9924 Unless new arguments are presented, I intend to remove this | |
| 9925 function in the next revision. | |
| 9926 </issue> | |
| 9927 <p/> | |
| 9928 Return via the <paramlink id="time_impact_ptr"></paramlink> and | |
| 9929 <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact | |
| 9930 of adding the capabilities pointed to by | |
| 9931 <paramlink id="capabilities_ptr"></paramlink>. | |
| 9932 The returned estimates are in percentage of additional overhead, thus | |
| 9933 a time impact of 100 mean the application might run | |
| 9934 at half the speed. | |
| 9935 The estimates are very rough approximations and are not guaranteed. | |
| 9936 Note also, that the estimates are of the impact of having the | |
| 9937 capability available--when and if it is used the impact may be | |
| 9938 much greater. | |
| 9939 Estimates can be for a single capability or for a set of | |
| 9940 capabilities. Note that the costs are not necessarily additive, | |
| 9941 adding support for one capability might make another available | |
| 9942 for free or conversely having two capabilities at once may | |
| 9943 have multiplicative impact. | |
| 9944 Estimates are relative to the current set of capabilities - | |
| 9945 that is, how much more impact given the currently possessed capabilities. | |
| 9946 <p/> | |
| 9947 Typically this function is used in the OnLoad function, | |
| 9948 some virtual machines may allow a limited set of capabilities to be | |
| 9949 added in the live phase. | |
| 9950 In this case, the set of potentially available capabilities | |
| 9951 will likely differ from the OnLoad phase set. | |
| 9952 <p/> | |
| 9953 See the | |
| 9954 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 9955 </description> | |
| 9956 <origin>new</origin> | |
| 9957 <capabilities> | |
| 9958 </capabilities> | |
| 9959 <parameters> | |
| 9960 <param id="capabilities_ptr"> | |
| 9961 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
| 9962 <description> | |
| 9963 points to the <jvmti/> capabilities to evaluate. | |
| 9964 </description> | |
| 9965 </param> | |
| 9966 <param id="time_impact_ptr"> | |
| 9967 <outptr><jint/></outptr> | |
| 9968 <description> | |
| 9969 On return, points to the estimated percentage increase in | |
| 9970 run time if this capability was added. | |
| 9971 </description> | |
| 9972 </param> | |
| 9973 <param id="space_impact_ptr"> | |
| 9974 <outptr><jint/></outptr> | |
| 9975 <description> | |
| 9976 On return, points to the estimated percentage increase in | |
| 9977 memory space used if this capability was added. | |
| 9978 </description> | |
| 9979 </param> | |
| 9980 </parameters> | |
| 9981 <errors> | |
| 9982 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 9983 The desired capabilities are not even potentially available. | |
| 9984 </error> | |
| 9985 </errors> | |
| 9986 </function> | |
| 9987 </elide> | |
| 9988 | |
| 9989 <function id="AddCapabilities" jkernel="yes" phase="onload" num="142"> | |
| 9990 <synopsis>Add Capabilities</synopsis> | |
| 9991 <description> | |
| 9992 Set new capabilities by adding the capabilities | |
| 9993 whose values are set to one (<code>1</code>) in | |
| 9994 <code>*</code><paramlink id="capabilities_ptr"></paramlink>. | |
| 9995 All previous capabilities are retained. | |
| 9996 Typically this function is used in the <code>OnLoad</code> function. | |
| 9997 Some virtual machines may allow a limited set of capabilities to be | |
| 9998 added in the live phase. | |
| 9999 <p/> | |
| 10000 See the | |
| 10001 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 10002 </description> | |
| 10003 <origin>new</origin> | |
| 10004 <capabilities> | |
| 10005 </capabilities> | |
| 10006 <parameters> | |
| 10007 <param id="capabilities_ptr"> | |
| 10008 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
| 10009 <description> | |
| 10010 Points to the <jvmti/> capabilities to add. | |
| 10011 </description> | |
| 10012 </param> | |
| 10013 </parameters> | |
| 10014 <errors> | |
| 10015 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10016 The desired capabilities are not even potentially available. | |
| 10017 </error> | |
| 10018 </errors> | |
| 10019 </function> | |
| 10020 | |
| 10021 | |
| 10022 <function id="RelinquishCapabilities" phase="onload" num="143"> | |
| 10023 <synopsis>Relinquish Capabilities</synopsis> | |
| 10024 <description> | |
| 10025 Relinquish the capabilities | |
| 10026 whose values are set to one (<code>1</code>) in | |
| 10027 <code>*</code><paramlink id="capabilities_ptr"></paramlink>. | |
| 10028 Some implementations may allow only one environment to have a capability | |
| 10029 (see the <internallink id="capability">capability introduction</internallink>). | |
| 10030 This function releases capabilities | |
| 10031 so that they may be used by other agents. | |
| 10032 All other capabilities are retained. | |
| 10033 The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>. | |
| 10034 Attempting to relinquish a capability that the agent does not possess is not an error. | |
| 10035 <issue> | |
| 10036 It is possible for the agent to be actively using capabilities | |
| 10037 which are being relinquished. For example, a thread is currently | |
| 10038 suspended and can_suspend is being relinquished or an event is currently | |
| 10039 enabled and can_generate_whatever is being relinquished. | |
| 10040 There are three possible ways we could spec this: | |
| 10041 <ul> | |
| 10042 <li>relinquish automatically releases them</li> | |
| 10043 <li>relinquish checks and returns some error code if held</li> | |
| 10044 <li>it is the agent's responsibility and it is not checked</li> | |
| 10045 </ul> | |
| 10046 One of these should be chosen. | |
| 10047 </issue> | |
| 10048 </description> | |
| 10049 <origin>new</origin> | |
| 10050 <capabilities> | |
| 10051 </capabilities> | |
| 10052 <parameters> | |
| 10053 <param id="capabilities_ptr"> | |
| 10054 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
| 10055 <description> | |
| 10056 Points to the <jvmti/> capabilities to relinquish. | |
| 10057 </description> | |
| 10058 </param> | |
| 10059 </parameters> | |
| 10060 <errors> | |
| 10061 </errors> | |
| 10062 </function> | |
| 10063 | |
| 10064 | |
| 10065 | |
| 10066 <function id="GetCapabilities" jkernel="yes" phase="any" num="89"> | |
| 10067 <synopsis>Get Capabilities</synopsis> | |
| 10068 <description> | |
| 10069 Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/> | |
| 10070 features which this environment currently possesses. | |
| 10071 Each possessed capability is indicated by a one (<code>1</code>) in the | |
| 10072 corresponding field of the <internallink id="jvmtiCapabilities">capabilities | |
| 10073 structure</internallink>. | |
| 10074 An environment does not possess a capability unless it has been successfully added with | |
| 10075 <functionlink id="AddCapabilities"/>. | |
| 10076 An environment only loses possession of a capability if it has been relinquished with | |
| 10077 <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result | |
| 10078 of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which | |
| 10079 have been made. | |
| 10080 <p/> | |
| 10081 See the | |
| 10082 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 10083 </description> | |
| 10084 <origin>jvmdiClone</origin> | |
| 10085 <capabilities> | |
| 10086 </capabilities> | |
| 10087 <parameters> | |
| 10088 <param id="capabilities_ptr"> | |
| 10089 <outptr><struct>jvmtiCapabilities</struct></outptr> | |
| 10090 <description> | |
| 10091 On return, points to the <jvmti/> capabilities. | |
| 10092 </description> | |
| 10093 </param> | |
| 10094 </parameters> | |
| 10095 <errors> | |
| 10096 </errors> | |
| 10097 </function> | |
| 10098 | |
| 10099 </category> | |
| 10100 | |
| 10101 | |
| 10102 <category id="timers" label="Timers"> | |
| 10103 | |
| 10104 <intro> | |
| 10105 These functions provide timing information. | |
| 10106 The resolution at which the time is updated is not specified. | |
| 10107 They provides nanosecond precision, but not necessarily nanosecond accuracy. | |
| 10108 Details about the timers, such as their maximum values, can be accessed with | |
| 10109 the timer information functions. | |
| 10110 </intro> | |
| 10111 | |
| 10112 <typedef id="jvmtiTimerInfo" label="Timer Info"> | |
| 10113 <description> | |
| 10114 The information function for each timer returns this data structure. | |
| 10115 </description> | |
| 10116 <field id="max_value"> | |
| 10117 <jlong/> | |
| 10118 <description> | |
| 10119 The maximum value the timer can reach. | |
| 10120 After this value is reached the timer wraps back to zero. | |
| 10121 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10122 it may appear to be a negative number. | |
| 10123 </description> | |
| 10124 </field> | |
| 10125 <field id="may_skip_forward"> | |
| 10126 <jboolean/> | |
| 10127 <description> | |
| 10128 If true, the timer can be externally adjusted and as a result skip forward. | |
| 10129 If false, the timer value will never increase faster than real time. | |
| 10130 </description> | |
| 10131 </field> | |
| 10132 <field id="may_skip_backward"> | |
| 10133 <jboolean/> | |
| 10134 <description> | |
| 10135 If true, the timer can be externally adjusted and as a result skip backward. | |
| 10136 If false, the timer value will be monotonically increasing. | |
| 10137 </description> | |
| 10138 </field> | |
| 10139 <field id="kind"> | |
| 10140 <enum>jvmtiTimerKind</enum> | |
| 10141 <description> | |
| 10142 The kind of timer. | |
| 10143 On a platform that does not distinguish between user and system time, <datalink | |
| 10144 id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink> | |
| 10145 is returned. | |
| 10146 </description> | |
| 10147 </field> | |
| 10148 <field id="reserved1"> | |
| 10149 <jlong/> | |
| 10150 <description> | |
| 10151 Reserved for future use. | |
| 10152 </description> | |
| 10153 </field> | |
| 10154 <field id="reserved2"> | |
| 10155 <jlong/> | |
| 10156 <description> | |
| 10157 Reserved for future use. | |
| 10158 </description> | |
| 10159 </field> | |
| 10160 </typedef> | |
| 10161 | |
| 10162 <intro> | |
| 10163 Where the timer kind is -- | |
| 10164 | |
| 10165 <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum"> | |
| 10166 <constant id="JVMTI_TIMER_USER_CPU" num="30"> | |
| 10167 CPU time that a thread is in user mode. | |
| 10168 </constant> | |
| 10169 <constant id="JVMTI_TIMER_TOTAL_CPU" num="31"> | |
| 10170 CPU time that a thread is in user or system mode. | |
| 10171 </constant> | |
| 10172 <constant id="JVMTI_TIMER_ELAPSED" num="32"> | |
| 10173 Elapsed time. | |
| 10174 </constant> | |
| 10175 </constants> | |
| 10176 </intro> | |
| 10177 | |
| 10178 <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe" impl="innative notrace" phase="start" num="134"> | |
| 10179 <synopsis>Get Current Thread CPU Timer Information</synopsis> | |
| 10180 <description> | |
| 10181 Get information about the | |
| 10182 <functionlink id="GetCurrentThreadCpuTime"/> timer. | |
| 10183 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
| 10184 are filled in with details about the timer. | |
| 10185 This information is specific to the platform and the implementation of | |
| 10186 <functionlink id="GetCurrentThreadCpuTime"/> and thus | |
| 10187 does not vary by thread nor does it vary | |
| 10188 during a particular invocation of the VM. | |
| 10189 <p/> | |
| 10190 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> | |
| 10191 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values | |
| 10192 returned by <code>GetCurrentThreadCpuTimerInfo</code> | |
| 10193 and <functionlink id="GetThreadCpuTimerInfo"/> | |
| 10194 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. | |
| 10195 </description> | |
| 10196 <origin>new</origin> | |
| 10197 <capabilities> | |
| 10198 <required id="can_get_current_thread_cpu_time"> | |
| 10199 Can get current thread CPU time. | |
| 10200 </required> | |
| 10201 </capabilities> | |
| 10202 <parameters> | |
| 10203 <param id="info_ptr"> | |
| 10204 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
| 10205 <description> | |
| 10206 On return, filled with information describing the time | |
| 10207 returned by <functionlink id="GetCurrentThreadCpuTime"/>. | |
| 10208 </description> | |
| 10209 </param> | |
| 10210 </parameters> | |
| 10211 <errors> | |
| 10212 </errors> | |
| 10213 </function> | |
| 10214 | |
| 10215 <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135"> | |
| 10216 <synopsis>Get Current Thread CPU Time</synopsis> | |
| 10217 <description> | |
| 10218 Return the CPU time utilized by the current thread. | |
| 10219 <p/> | |
| 10220 Note that the <functionlink id="GetThreadCpuTime"/> | |
| 10221 function provides CPU time for any thread, including | |
| 10222 the current thread. <code>GetCurrentThreadCpuTime</code> | |
| 10223 exists to support platforms which cannot | |
| 10224 supply CPU time for threads other than the current | |
| 10225 thread or which have more accurate information for | |
| 10226 the current thread (see | |
| 10227 <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs | |
| 10228 <functionlink id="GetThreadCpuTimerInfo"/>). | |
| 10229 On many platforms this call will be equivalent to: | |
| 10230 <example> | |
| 10231 GetThreadCpuTime(env, NULL, nanos_ptr) | |
| 10232 </example> | |
| 10233 </description> | |
| 10234 <origin>new</origin> | |
| 10235 <capabilities> | |
| 10236 <required id="can_get_current_thread_cpu_time"> | |
| 10237 Can get current thread CPU time. | |
| 10238 <p/> | |
| 10239 If this capability is enabled after threads have started, | |
| 10240 the implementation may choose any time up | |
| 10241 to and including the time that the capability is enabled | |
| 10242 as the point where CPU time collection starts. | |
| 10243 <p/> | |
| 10244 This capability must be potentially available on any | |
| 10245 platform where | |
| 10246 <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink> | |
| 10247 is potentially available. | |
| 10248 </required> | |
| 10249 </capabilities> | |
| 10250 <parameters> | |
| 10251 <param id="nanos_ptr"> | |
| 10252 <outptr><jlong/></outptr> | |
| 10253 <description> | |
| 10254 On return, points to the CPU time used by this thread | |
| 10255 in nanoseconds. | |
| 10256 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10257 it may appear to be a negative number. | |
| 10258 </description> | |
| 10259 </param> | |
| 10260 </parameters> | |
| 10261 <errors> | |
| 10262 </errors> | |
| 10263 </function> | |
| 10264 | |
| 10265 <function id="GetThreadCpuTimerInfo" num="136"> | |
| 10266 <synopsis>Get Thread CPU Timer Information</synopsis> | |
| 10267 <description> | |
| 10268 Get information about the | |
| 10269 <functionlink id="GetThreadCpuTime"/> timer. | |
| 10270 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
| 10271 are filled in with details about the timer. | |
| 10272 This information is specific to the platform and the implementation of | |
| 10273 <functionlink id="GetThreadCpuTime"/> and thus | |
| 10274 does not vary by thread nor does it vary | |
| 10275 during a particular invocation of the VM. | |
| 10276 <p/> | |
| 10277 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> | |
| 10278 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values | |
| 10279 returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/> | |
| 10280 and <code>GetThreadCpuTimerInfo</code> | |
| 10281 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. | |
| 10282 </description> | |
| 10283 <origin>new</origin> | |
| 10284 <capabilities> | |
| 10285 <required id="can_get_thread_cpu_time"> | |
| 10286 Can get thread CPU time. | |
| 10287 </required> | |
| 10288 </capabilities> | |
| 10289 <parameters> | |
| 10290 <param id="info_ptr"> | |
| 10291 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
| 10292 <description> | |
| 10293 On return, filled with information describing the time | |
| 10294 returned by <functionlink id="GetThreadCpuTime"/>. | |
| 10295 </description> | |
| 10296 </param> | |
| 10297 </parameters> | |
| 10298 <errors> | |
| 10299 </errors> | |
| 10300 </function> | |
| 10301 | |
| 10302 <function id="GetThreadCpuTime" num="137"> | |
| 10303 <synopsis>Get Thread CPU Time</synopsis> | |
| 10304 <description> | |
| 10305 Return the CPU time utilized by the specified thread. | |
| 10306 <p/> | |
| 10307 Get information about this timer with | |
| 10308 <functionlink id="GetThreadCpuTimerInfo"/>. | |
| 10309 </description> | |
| 10310 <origin>new</origin> | |
| 10311 <capabilities> | |
| 10312 <required id="can_get_thread_cpu_time"> | |
| 10313 Can get thread CPU time. | |
| 10314 <p/> | |
| 10315 If this capability is enabled after threads have started, | |
| 10316 the implementation may choose any time up | |
| 10317 to and including the time that the capability is enabled | |
| 10318 as the point where CPU time collection starts. | |
| 10319 </required> | |
| 10320 </capabilities> | |
| 10321 <parameters> | |
| 10322 <param id="thread"> | |
| 10323 <jthread null="current"/> | |
| 10324 <description> | |
| 10325 The thread to query. | |
| 10326 </description> | |
| 10327 </param> | |
| 10328 <param id="nanos_ptr"> | |
| 10329 <outptr><jlong/></outptr> | |
| 10330 <description> | |
| 10331 On return, points to the CPU time used by the specified thread | |
| 10332 in nanoseconds. | |
| 10333 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10334 it may appear to be a negative number. | |
| 10335 </description> | |
| 10336 </param> | |
| 10337 </parameters> | |
| 10338 <errors> | |
| 10339 </errors> | |
| 10340 </function> | |
| 10341 | |
| 10342 <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138"> | |
| 10343 <synopsis>Get Timer Information</synopsis> | |
| 10344 <description> | |
| 10345 Get information about the | |
| 10346 <functionlink id="GetTime"/> timer. | |
| 10347 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
| 10348 are filled in with details about the timer. | |
| 10349 This information will not change during a particular invocation of the VM. | |
| 10350 </description> | |
| 10351 <origin>new</origin> | |
| 10352 <capabilities> | |
| 10353 </capabilities> | |
| 10354 <parameters> | |
| 10355 <param id="info_ptr"> | |
| 10356 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
| 10357 <description> | |
| 10358 On return, filled with information describing the time | |
| 10359 returned by <functionlink id="GetTime"/>. | |
| 10360 </description> | |
| 10361 </param> | |
| 10362 </parameters> | |
| 10363 <errors> | |
| 10364 </errors> | |
| 10365 </function> | |
| 10366 | |
| 10367 <function id="GetTime" phase="any" callbacksafe="safe" num="139"> | |
| 10368 <synopsis>Get Time</synopsis> | |
| 10369 <description> | |
| 10370 Return the current value of the system timer, in nanoseconds. | |
| 10371 <p/> | |
| 10372 The value returned represents nanoseconds since some fixed but | |
| 10373 arbitrary time (perhaps in the future, so values may be | |
| 10374 negative). This function provides nanosecond precision, but not | |
| 10375 necessarily nanosecond accuracy. No guarantees are made about | |
| 10376 how frequently values change. | |
| 10377 <p/> | |
| 10378 Get information about this timer with | |
| 10379 <functionlink id="GetTimerInfo"/>. | |
| 10380 </description> | |
| 10381 <origin>new</origin> | |
| 10382 <capabilities> | |
| 10383 </capabilities> | |
| 10384 <parameters> | |
| 10385 <param id="nanos_ptr"> | |
| 10386 <outptr><jlong/></outptr> | |
| 10387 <description> | |
| 10388 On return, points to the time in nanoseconds. | |
| 10389 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10390 it may appear to be a negative number. | |
| 10391 </description> | |
| 10392 </param> | |
| 10393 </parameters> | |
| 10394 <errors> | |
| 10395 </errors> | |
| 10396 </function> | |
| 10397 | |
| 10398 <function id="GetAvailableProcessors" phase="any" num="144"> | |
| 10399 <synopsis>Get Available Processors</synopsis> | |
| 10400 <description> | |
| 10401 Returns the number of processors available to the Java virtual machine. | |
| 10402 <p/> | |
| 10403 This value may change during a particular invocation of the virtual machine. | |
| 10404 Applications that are sensitive to the number of available processors should | |
| 10405 therefore occasionally poll this property. | |
| 10406 </description> | |
| 10407 <origin>new</origin> | |
| 10408 <capabilities> | |
| 10409 </capabilities> | |
| 10410 <parameters> | |
| 10411 <param id="processor_count_ptr"> | |
| 10412 <outptr><jint/></outptr> | |
| 10413 <description> | |
| 10414 On return, points to the maximum number of processors available to the | |
| 10415 virtual machine; never smaller than one. | |
| 10416 </description> | |
| 10417 </param> | |
| 10418 </parameters> | |
| 10419 <errors> | |
| 10420 </errors> | |
| 10421 </function> | |
| 10422 | |
| 10423 </category> | |
| 10424 | |
| 10425 | |
| 10426 <category id="classLoaderSearch" label="Class Loader Search"> | |
| 10427 | |
| 10428 <intro> | |
| 10429 These functions allow the agent to add to the locations that a class loader searches for a class. | |
| 10430 This is useful for installing instrumentation under the correct class loader. | |
| 10431 </intro> | |
| 10432 | |
| 10433 <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149"> | |
| 10434 <synopsis>Add To Bootstrap Class Loader Search</synopsis> | |
| 10435 <description> | |
| 10436 This function can be used to cause instrumentation classes to be defined by the | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
10437 bootstrap class loader. See <vmspec chapter="5.3.1"/>. |
| 0 | 10438 After the bootstrap |
| 10439 class loader unsuccessfully searches for a class, the specified platform-dependent | |
| 10440 search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in | |
| 10441 the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, | |
| 10442 the segments will be searched in the order that this function was called. | |
| 10443 <p/> | |
| 10444 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent | |
| 10445 search path segment to be searched after the bootstrap class loader unsuccessfully searches | |
| 10446 for a class. The segment is typically a directory or JAR file. | |
| 10447 <p/> | |
| 10448 In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent | |
| 6919 | 10449 path to a <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html"> |
| 0 | 10450 JAR file</externallink>. The agent should take care that the JAR file does not |
| 10451 contain any classes or resources other than those to be defined by the bootstrap | |
| 10452 class loader for the purposes of instrumentation. | |
| 10453 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
10454 <vmspec/> specifies that a subsequent attempt to resolve a symbolic |
| 0 | 10455 reference that the Java virtual machine has previously unsuccessfully attempted |
| 10456 to resolve always fails with the same error that was thrown as a result of the | |
| 10457 initial resolution attempt. Consequently, if the JAR file contains an entry | |
| 10458 that corresponds to a class for which the Java virtual machine has | |
| 10459 unsuccessfully attempted to resolve a reference, then subsequent attempts to | |
| 10460 resolve that reference will fail with the same error as the initial attempt. | |
| 10461 </description> | |
| 10462 <origin>new</origin> | |
| 10463 <capabilities> | |
| 10464 </capabilities> | |
| 10465 <parameters> | |
| 10466 <param id="segment"> | |
| 10467 <inbuf><char/></inbuf> | |
| 10468 <description> | |
| 10469 The platform-dependent search path segment, encoded as a | |
| 10470 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10471 </description> | |
| 10472 </param> | |
| 10473 </parameters> | |
| 10474 <errors> | |
| 10475 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 10476 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an | |
| 10477 existing JAR file is an invalid path. | |
| 10478 </error> | |
| 10479 </errors> | |
| 10480 </function> | |
| 10481 | |
| 10482 <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1"> | |
| 10483 <synopsis>Add To System Class Loader Search</synopsis> | |
| 10484 <description> | |
| 10485 This function can be used to cause instrumentation classes to be | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
10486 defined by the system class loader. See <vmspec chapter="5.3.2"/>. |
| 0 | 10487 After the class loader unsuccessfully searches for a class, the specified platform-dependent search |
| 10488 path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the | |
| 10489 <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the | |
| 10490 segments will be searched in the order that this function was called. | |
| 10491 <p/> | |
| 10492 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent | |
| 10493 search path segment to be searched after the system class loader unsuccessfully searches | |
| 10494 for a class. The segment is typically a directory or JAR file. | |
| 10495 <p/> | |
| 10496 In the live phase the <paramlink id="segment"/> is a platform-dependent path to a <externallink | |
| 6919 | 10497 id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">JAR file</externallink> to be |
| 0 | 10498 searched after the system class loader unsuccessfully searches for a class. The agent should |
| 10499 take care that the JAR file does not contain any classes or resources other than those to be | |
| 10500 defined by the system class loader for the purposes of instrumentation. | |
| 10501 <p/> | |
| 10502 In the live phase the system class loader supports adding a JAR file to be searched if | |
| 10503 the system class loader implements a method name <code>appendToClassPathForInstrumentation</code> | |
| 10504 which takes a single parameter of type <code>java.lang.String</code>. The method is not required | |
| 10505 to have <code>public</code> access. | |
| 10506 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
10507 <vmspec/> specifies that a subsequent attempt to resolve a symbolic |
| 0 | 10508 reference that the Java virtual machine has previously unsuccessfully attempted |
| 10509 to resolve always fails with the same error that was thrown as a result of the | |
| 10510 initial resolution attempt. Consequently, if the JAR file contains an entry | |
| 10511 that corresponds to a class for which the Java virtual machine has | |
| 10512 unsuccessfully attempted to resolve a reference, then subsequent attempts to | |
| 10513 resolve that reference will fail with the same error as the initial attempt. | |
| 10514 </description> | |
| 10515 <origin>new</origin> | |
| 10516 <capabilities> | |
| 10517 </capabilities> | |
| 10518 <parameters> | |
| 10519 <param id="segment"> | |
| 10520 <inbuf><char/></inbuf> | |
| 10521 <description> | |
| 10522 The platform-dependent search path segment, encoded as a | |
| 10523 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10524 </description> | |
| 10525 </param> | |
| 10526 </parameters> | |
| 10527 <errors> | |
| 10528 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 10529 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an | |
| 10530 existing JAR file is an invalid path. | |
| 10531 </error> | |
| 10532 <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED"> | |
| 10533 Operation not supported by the system class loader. | |
| 10534 </error> | |
| 10535 </errors> | |
| 10536 </function> | |
| 10537 | |
| 10538 </category> | |
| 10539 | |
| 10540 | |
| 10541 <category id="props" label="System Properties"> | |
| 10542 | |
| 10543 <intro> | |
| 10544 These functions get and set system properties. | |
| 10545 </intro> | |
| 10546 | |
| 10547 <function id="GetSystemProperties" phase="onload" num="130"> | |
| 10548 <synopsis>Get System Properties</synopsis> | |
| 10549 <description> | |
| 10550 The list of VM system property keys which may be used with | |
| 10551 <functionlink id="GetSystemProperty"/> is returned. | |
| 10552 It is strongly recommended that virtual machines provide the | |
| 10553 following property keys: | |
| 10554 <ul> | |
| 10555 <li><code>java.vm.vendor</code></li> | |
| 10556 <li><code>java.vm.version</code></li> | |
| 10557 <li><code>java.vm.name</code></li> | |
| 10558 <li><code>java.vm.info</code></li> | |
| 10559 <li><code>java.library.path</code></li> | |
| 10560 <li><code>java.class.path</code></li> | |
| 10561 </ul> | |
| 10562 Provides access to system properties defined by and used | |
| 10563 by the VM. | |
| 10564 Properties set on the command-line are included. | |
| 10565 This allows getting and setting of these properties | |
| 10566 before the VM even begins executing bytecodes. | |
| 10567 Since this is a VM view of system properties, the set of available | |
| 10568 properties will usually be different than that | |
| 10569 in <code>java.lang.System.getProperties</code>. | |
| 10570 JNI method invocation may be used to access | |
| 10571 <code>java.lang.System.getProperties</code>. | |
| 10572 <p/> | |
| 10573 The set of properties may grow during execution. | |
| 10574 </description> | |
| 10575 <origin>new</origin> | |
| 10576 <capabilities> | |
| 10577 </capabilities> | |
| 10578 <parameters> | |
| 10579 <param id="count_ptr"> | |
| 10580 <outptr><jint/></outptr> | |
| 10581 <description> | |
| 10582 On return, points to the number of property keys returned. | |
| 10583 </description> | |
| 10584 </param> | |
| 10585 <param id="property_ptr"> | |
| 10586 <allocallocbuf outcount="count_ptr"><char/></allocallocbuf> | |
| 10587 <description> | |
| 10588 On return, points to an array of property keys, encoded as | |
| 10589 <internallink id="mUTF">modified UTF-8</internallink> strings. | |
| 10590 </description> | |
| 10591 </param> | |
| 10592 </parameters> | |
| 10593 <errors> | |
| 10594 </errors> | |
| 10595 </function> | |
| 10596 | |
| 10597 <function id="GetSystemProperty" phase="onload" num="131"> | |
| 10598 <synopsis>Get System Property</synopsis> | |
| 10599 <description> | |
| 10600 Return a VM system property value given the property key. | |
| 10601 <p/> | |
| 10602 The function <functionlink id="GetSystemProperties"/> | |
| 10603 returns the set of property keys which may be used. | |
| 10604 The properties which can be retrieved may grow during | |
| 10605 execution. | |
| 10606 <p/> | |
| 10607 Since this is a VM view of system properties, the values | |
| 10608 of properties may differ from that returned by | |
| 10609 <code>java.lang.System.getProperty(String)</code>. | |
| 10610 A typical VM might copy the values of the VM system | |
| 10611 properties into the <code>Properties</code> held by | |
| 10612 <code>java.lang.System</code> during the initialization | |
| 10613 of that class. Thereafter any changes to the VM system | |
| 10614 properties (with <functionlink id="SetSystemProperty"/>) | |
| 10615 or the <code>java.lang.System</code> system properties | |
| 10616 (with <code>java.lang.System.setProperty(String,String)</code>) | |
| 10617 would cause the values to diverge. | |
| 10618 JNI method invocation may be used to access | |
| 10619 <code>java.lang.System.getProperty(String)</code>. | |
| 10620 </description> | |
| 10621 <origin>new</origin> | |
| 10622 <capabilities> | |
| 10623 </capabilities> | |
| 10624 <parameters> | |
| 10625 <param id="property"> | |
| 10626 <inbuf><char/></inbuf> | |
| 10627 <description> | |
| 10628 The key of the property to retrieve, encoded as a | |
| 10629 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10630 </description> | |
| 10631 </param> | |
| 10632 <param id="value_ptr"> | |
| 10633 <allocbuf><char/></allocbuf> | |
| 10634 <description> | |
| 10635 On return, points to the property value, encoded as a | |
| 10636 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10637 </description> | |
| 10638 </param> | |
| 10639 </parameters> | |
| 10640 <errors> | |
| 10641 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10642 This property is not available. | |
| 10643 Use <functionlink id="GetSystemProperties"/> to find available properties. | |
| 10644 </error> | |
| 10645 </errors> | |
| 10646 </function> | |
| 10647 | |
| 10648 <function id="SetSystemProperty" phase="onloadOnly" num="132"> | |
| 10649 <synopsis>Set System Property</synopsis> | |
| 10650 <description> | |
| 10651 Set a VM system property value. | |
| 10652 <p/> | |
| 10653 The function <functionlink id="GetSystemProperties"/> | |
| 10654 returns the set of property keys, some of these may be settable. | |
| 10655 See <functionlink id="GetSystemProperty"/>. | |
| 10656 </description> | |
| 10657 <origin>new</origin> | |
| 10658 <capabilities> | |
| 10659 </capabilities> | |
| 10660 <parameters> | |
| 10661 <param id="property"> | |
| 10662 <inbuf><char/></inbuf> | |
| 10663 <description> | |
| 10664 The key of the property, encoded as a | |
| 10665 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10666 </description> | |
| 10667 </param> | |
|
2100
b1a2afa37ec4
7003271: Hotspot should track cumulative Java heap bytes allocated on a per-thread basis
phh
parents:
2019
diff
changeset
|
10668 <param id="value_ptr"> |
| 0 | 10669 <inbuf> |
| 10670 <char/> | |
| 10671 <nullok> | |
| 10672 do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/> | |
| 10673 if the property is not writeable | |
| 10674 </nullok> | |
| 10675 </inbuf> | |
| 10676 <description> | |
| 10677 The property value to set, encoded as a | |
| 10678 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10679 </description> | |
| 10680 </param> | |
| 10681 </parameters> | |
| 10682 <errors> | |
| 10683 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10684 This property is not available or is not writeable. | |
| 10685 </error> | |
| 10686 </errors> | |
| 10687 </function> | |
| 10688 | |
| 10689 </category> | |
| 10690 | |
| 10691 <category id="general" label="General"> | |
| 10692 | |
| 10693 <intro> | |
| 10694 </intro> | |
| 10695 | |
| 10696 <function id="GetPhase" jkernel="yes" phase="any" num="133"> | |
| 10697 <synopsis>Get Phase</synopsis> | |
| 10698 <description> | |
| 10699 Return the current phase of VM execution. | |
| 10700 The phases proceed in sequence: | |
| 10701 <constants id="jvmtiPhase" label="Phases of execution" kind="enum"> | |
| 10702 <constant id="JVMTI_PHASE_ONLOAD" num="1"> | |
| 10703 <code>OnLoad</code> phase: while in the | |
| 10704 <internallink id="onload"><code>Agent_OnLoad</code></internallink> function. | |
| 10705 </constant> | |
| 10706 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2"> | |
| 10707 Primordial phase: between return from <code>Agent_OnLoad</code> and the | |
| 10708 <code>VMStart</code> event. | |
| 10709 </constant> | |
| 10710 <constant id="JVMTI_PHASE_START" num="6"> | |
| 10711 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event | |
| 10712 is sent and until the <code>VMInit</code> event is sent. | |
| 10713 </constant> | |
| 10714 <constant id="JVMTI_PHASE_LIVE" num="4"> | |
| 10715 Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent | |
| 10716 and until the <eventlink id="VMDeath"></eventlink> event returns. | |
| 10717 </constant> | |
| 10718 <constant id="JVMTI_PHASE_DEAD" num="8"> | |
| 10719 Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after | |
| 10720 start-up failure. | |
| 10721 </constant> | |
| 10722 </constants> | |
| 10723 In the case of start-up failure the VM will proceed directly to the dead | |
| 10724 phase skipping intermediate phases and neither a <code>VMInit</code> nor | |
| 10725 <code>VMDeath</code> event will be sent. | |
| 10726 <p/> | |
| 10727 Most <jvmti/> functions operate only in the live phase. | |
| 10728 The following functions operate in either the <code>OnLoad</code> or live phases: | |
| 10729 <functionphaselist phase="onload"/> | |
| 10730 The following functions operate in only the <code>OnLoad</code> phase: | |
| 10731 <functionphaselist phase="onloadOnly"/> | |
| 10732 The following functions operate in the start or live phases: | |
| 10733 <functionphaselist phase="start"/> | |
| 10734 The following functions operate in any phase: | |
| 10735 <functionphaselist phase="any"/> | |
| 10736 JNI functions (except the Invocation API) must only be used in the start or live phases. | |
| 10737 <p/> | |
| 10738 Most <jvmti/> events are sent only in the live phase. | |
| 10739 The following events operate in others phases: | |
| 10740 <eventphaselist phase="start"/> | |
| 10741 <eventphaselist phase="any"/> | |
| 10742 </description> | |
| 10743 <origin>new</origin> | |
| 10744 <capabilities> | |
| 10745 </capabilities> | |
| 10746 <parameters> | |
| 10747 <param id="phase_ptr"> | |
| 10748 <outptr><enum>jvmtiPhase</enum></outptr> | |
| 10749 <description> | |
| 10750 On return, points to the phase. | |
| 10751 </description> | |
| 10752 </param> | |
| 10753 </parameters> | |
| 10754 <errors> | |
| 10755 </errors> | |
| 10756 </function> | |
| 10757 | |
| 10758 <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127"> | |
| 10759 <synopsis>Dispose Environment</synopsis> | |
| 10760 <description> | |
| 10761 Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code> | |
| 10762 (see <internallink id="environments"><jvmti/> Environments</internallink>). | |
| 10763 Dispose of any resources held by the environment. | |
| 10764 <issue> | |
| 10765 What resources are reclaimed? What is undone? | |
| 10766 Breakpoints,watchpoints removed? | |
| 10767 </issue> | |
| 10768 Threads suspended by this environment are not resumed by this call, | |
| 10769 this must be done explicitly by the agent. | |
| 10770 Memory allocated by this environment via calls to <jvmti/> functions | |
| 10771 is not released, this can be done explicitly by the agent | |
| 10772 by calling <functionlink id="Deallocate"/>. | |
| 10773 Raw monitors created by this environment are not destroyed, | |
| 10774 this can be done explicitly by the agent | |
| 10775 by calling <functionlink id="DestroyRawMonitor"/>. | |
| 10776 The state of threads waiting on raw monitors created by this environment | |
| 10777 are not affected. | |
| 10778 <p/> | |
| 10779 Any <functionlink id="SetNativeMethodPrefix">native method | |
| 10780 prefixes</functionlink> for this environment will be unset; | |
| 10781 the agent must remove any prefixed native methods before | |
| 10782 dispose is called. | |
| 10783 <p/> | |
| 10784 Any <internallink id="capability">capabilities</internallink> | |
| 10785 held by this environment are relinquished. | |
| 10786 <p/> | |
| 10787 Events enabled by this environment will no longer be sent, however | |
| 10788 event handlers currently running will continue to run. Caution must | |
| 10789 be exercised in the design of event handlers whose environment may | |
| 10790 be disposed and thus become invalid during their execution. | |
| 10791 <p/> | |
| 10792 This environment may not be used after this call. | |
| 10793 This call returns to the caller. | |
| 10794 </description> | |
| 10795 <origin>new</origin> | |
| 10796 <capabilities> | |
| 10797 </capabilities> | |
| 10798 <parameters> | |
| 10799 </parameters> | |
| 10800 <errors> | |
| 10801 </errors> | |
| 10802 </function> | |
| 10803 | |
| 10804 <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148"> | |
| 10805 <synopsis>Set Environment Local Storage</synopsis> | |
| 10806 <description> | |
| 10807 The VM stores a pointer value associated with each environment. | |
| 10808 This pointer value is called <i>environment-local storage</i>. | |
| 10809 This value is <code>NULL</code> unless set with this function. | |
| 10810 Agents can allocate memory in which they store environment specific | |
| 10811 information. By setting environment-local storage it can then be | |
| 10812 accessed with | |
| 10813 <functionlink id="GetEnvironmentLocalStorage"></functionlink>. | |
| 10814 <p/> | |
| 10815 Called by the agent to set the value of the <jvmti/> | |
| 10816 environment-local storage. <jvmti/> supplies to the agent a pointer-size | |
| 10817 environment-local storage that can be used to record per-environment | |
| 10818 information. | |
| 10819 </description> | |
| 10820 <origin>new</origin> | |
| 10821 <capabilities> | |
| 10822 </capabilities> | |
| 10823 <parameters> | |
| 10824 <param id="data"> | |
| 10825 <inbuf> | |
| 10826 <void/> | |
| 10827 <nullok>value is set to <code>NULL</code></nullok> | |
| 10828 </inbuf> | |
| 10829 <description> | |
| 10830 The value to be entered into the environment-local storage. | |
| 10831 </description> | |
| 10832 </param> | |
| 10833 </parameters> | |
| 10834 <errors> | |
| 10835 </errors> | |
| 10836 </function> | |
| 10837 | |
| 10838 <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147"> | |
| 10839 <synopsis>Get Environment Local Storage</synopsis> | |
| 10840 <description> | |
| 10841 Called by the agent to get the value of the <jvmti/> environment-local | |
| 10842 storage. | |
| 10843 </description> | |
| 10844 <origin>new</origin> | |
| 10845 <capabilities> | |
| 10846 </capabilities> | |
| 10847 <parameters> | |
| 10848 <param id="data_ptr"> | |
| 10849 <agentbuf><void/></agentbuf> | |
| 10850 <description> | |
| 10851 Pointer through which the value of the environment local | |
| 10852 storage is returned. | |
| 10853 If environment-local storage has not been set with | |
| 10854 <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned | |
| 10855 pointer is <code>NULL</code>. | |
| 10856 </description> | |
| 10857 </param> | |
| 10858 </parameters> | |
| 10859 <errors> | |
| 10860 </errors> | |
| 10861 </function> | |
| 10862 | |
| 10863 <function id="GetVersionNumber" jkernel="yes" phase="any" num="88"> | |
| 10864 <synopsis>Get Version Number</synopsis> | |
| 10865 <description> | |
| 10866 Return the <jvmti/> version via <code>version_ptr</code>. | |
| 10867 The return value is the version identifier. | |
| 10868 The version identifier includes major, minor and micro | |
| 10869 version as well as the interface type. | |
| 10870 <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits"> | |
| 10871 <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000"> | |
| 10872 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI. | |
| 10873 </constant> | |
| 10874 <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000"> | |
| 10875 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>. | |
| 10876 </constant> | |
| 10877 </constants> | |
| 10878 <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits"> | |
| 10879 <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000"> | |
| 10880 Mask to extract interface type. | |
| 10881 The value of the version returned by this function masked with | |
| 10882 <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always | |
| 10883 <code>JVMTI_VERSION_INTERFACE_JVMTI</code> | |
| 10884 since this is a <jvmti/> function. | |
| 10885 </constant> | |
| 10886 <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000"> | |
| 10887 Mask to extract major version number. | |
| 10888 </constant> | |
| 10889 <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00"> | |
| 10890 Mask to extract minor version number. | |
| 10891 </constant> | |
| 10892 <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF"> | |
| 10893 Mask to extract micro version number. | |
| 10894 </constant> | |
| 10895 </constants> | |
| 10896 <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits"> | |
| 10897 <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16"> | |
| 10898 Shift to extract major version number. | |
| 10899 </constant> | |
| 10900 <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8"> | |
| 10901 Shift to extract minor version number. | |
| 10902 </constant> | |
| 10903 <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0"> | |
| 10904 Shift to extract micro version number. | |
| 10905 </constant> | |
| 10906 </constants> | |
| 10907 </description> | |
| 10908 <origin>jvmdi</origin> | |
| 10909 <capabilities> | |
| 10910 </capabilities> | |
| 10911 <parameters> | |
| 10912 <param id="version_ptr"> | |
| 10913 <outptr><jint/></outptr> | |
| 10914 <description> | |
| 10915 On return, points to the <jvmti/> version. | |
| 10916 </description> | |
| 10917 </param> | |
| 10918 </parameters> | |
| 10919 <errors> | |
| 10920 </errors> | |
| 10921 </function> | |
| 10922 | |
| 10923 | |
| 10924 <function id="GetErrorName" phase="any" num="128"> | |
| 10925 <synopsis>Get Error Name</synopsis> | |
| 10926 <description> | |
| 10927 Return the symbolic name for an | |
| 10928 <internallink id="ErrorSection">error code</internallink>. | |
| 10929 <p/> | |
| 10930 For example | |
| 10931 <code>GetErrorName(env, JVMTI_ERROR_NONE, &err_name)</code> | |
| 10932 would return in <code>err_name</code> the string | |
| 10933 <code>"JVMTI_ERROR_NONE"</code>. | |
| 10934 </description> | |
| 10935 <origin>new</origin> | |
| 10936 <capabilities> | |
| 10937 </capabilities> | |
| 10938 <parameters> | |
| 10939 <param id="error"> | |
| 10940 <enum>jvmtiError</enum> | |
| 10941 <description> | |
| 10942 The error code. | |
| 10943 </description> | |
| 10944 </param> | |
| 10945 <param id="name_ptr"> | |
| 10946 <allocbuf><char/></allocbuf> | |
| 10947 <description> | |
| 10948 On return, points to the error name. | |
| 10949 The name is encoded as a | |
| 10950 <internallink id="mUTF">modified UTF-8</internallink> string, | |
| 10951 but is restricted to the ASCII subset. | |
| 10952 </description> | |
| 10953 </param> | |
| 10954 </parameters> | |
| 10955 <errors> | |
| 10956 </errors> | |
| 10957 </function> | |
| 10958 | |
| 10959 <function id="SetVerboseFlag" phase="any" num="150"> | |
| 10960 <synopsis>Set Verbose Flag</synopsis> | |
| 10961 <description> | |
| 10962 <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum"> | |
| 10963 <constant id="JVMTI_VERBOSE_OTHER" num="0"> | |
| 10964 Verbose output other than the below. | |
| 10965 </constant> | |
| 10966 <constant id="JVMTI_VERBOSE_GC" num="1"> | |
| 10967 Verbose garbage collector output, like that specified with <code>-verbose:gc</code>. | |
| 10968 </constant> | |
| 10969 <constant id="JVMTI_VERBOSE_CLASS" num="2"> | |
| 10970 Verbose class loading output, like that specified with <code>-verbose:class</code>. | |
| 10971 </constant> | |
| 10972 <constant id="JVMTI_VERBOSE_JNI" num="4"> | |
| 10973 Verbose JNI output, like that specified with <code>-verbose:jni</code>. | |
| 10974 </constant> | |
| 10975 </constants> | |
| 10976 Control verbose output. | |
| 10977 This is the output which typically is sent to <code>stderr</code>. | |
| 10978 </description> | |
| 10979 <origin>new</origin> | |
| 10980 <capabilities> | |
| 10981 </capabilities> | |
| 10982 <parameters> | |
| 10983 <param id="flag"> | |
| 10984 <enum>jvmtiVerboseFlag</enum> | |
| 10985 <description> | |
| 10986 Which verbose flag to set. | |
| 10987 </description> | |
| 10988 </param> | |
| 10989 <param id="value"> | |
| 10990 <jboolean/> | |
| 10991 <description> | |
| 10992 New value of the flag. | |
| 10993 </description> | |
| 10994 </param> | |
| 10995 </parameters> | |
| 10996 <errors> | |
| 10997 </errors> | |
| 10998 </function> | |
| 10999 | |
| 11000 | |
| 11001 <function id="GetJLocationFormat" phase="any" num="129"> | |
| 11002 <synopsis>Get JLocation Format</synopsis> | |
| 11003 <description> | |
| 11004 Although the greatest functionality is achieved with location information | |
| 11005 referencing the virtual machine bytecode index, the definition of | |
| 11006 <code>jlocation</code> has intentionally been left unconstrained to allow VM | |
| 11007 implementations that do not have this information. | |
| 11008 <p/> | |
| 11009 This function describes the representation of <code>jlocation</code> used in this VM. | |
| 11010 If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>, | |
| 11011 <code>jlocation</code>s can | |
| 11012 be used as in indices into the array returned by | |
| 11013 <functionlink id="GetBytecodes"></functionlink>. | |
| 11014 <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum"> | |
| 11015 <constant id="JVMTI_JLOCATION_JVMBCI" num="1"> | |
| 11016 <code>jlocation</code> values represent virtual machine | |
| 11017 bytecode indices--that is, offsets into the | |
| 11018 virtual machine code for a method. | |
| 11019 </constant> | |
| 11020 <constant id="JVMTI_JLOCATION_MACHINEPC" num="2"> | |
| 11021 <code>jlocation</code> values represent native machine | |
| 11022 program counter values. | |
| 11023 </constant> | |
| 11024 <constant id="JVMTI_JLOCATION_OTHER" num="0"> | |
| 11025 <code>jlocation</code> values have some other representation. | |
| 11026 </constant> | |
| 11027 </constants> | |
| 11028 </description> | |
| 11029 <origin>new</origin> | |
| 11030 <capabilities> | |
| 11031 </capabilities> | |
| 11032 <parameters> | |
| 11033 <param id="format_ptr"> | |
| 11034 <outptr><enum>jvmtiJlocationFormat</enum></outptr> | |
| 11035 <description> | |
| 11036 On return, points to the format identifier for <code>jlocation</code> values. | |
| 11037 </description> | |
| 11038 </param> | |
| 11039 </parameters> | |
| 11040 <errors> | |
| 11041 </errors> | |
| 11042 </function> | |
| 11043 | |
| 11044 </category> | |
| 11045 | |
| 11046 </functionsection> | |
| 11047 | |
| 11048 <errorsection label="Error Reference"> | |
| 11049 <intro> | |
| 11050 Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code. | |
| 11051 <p/> | |
| 11052 It is the responsibility of the agent to call <jvmti/> functions with | |
| 11053 valid parameters and in the proper context (calling thread is attached, | |
| 11054 phase is correct, etc.). | |
| 11055 Detecting some error conditions may be difficult, inefficient, or | |
| 11056 impossible for an implementation. | |
| 11057 The errors listed in | |
| 11058 <internallink id="reqerrors">Function Specific Required Errors</internallink> | |
| 11059 must be detected by the implementation. | |
| 11060 All other errors represent the recommended response to the error | |
| 11061 condition. | |
| 11062 </intro> | |
| 11063 | |
| 11064 <errorcategory id="universal-error" label="Universal Errors"> | |
| 11065 <intro> | |
| 11066 The following errors may be returned by any function | |
| 11067 </intro> | |
| 11068 | |
| 11069 <errorid id="JVMTI_ERROR_NONE" num="0"> | |
| 11070 No error has occurred. This is the error code that is returned | |
| 11071 on successful completion of the function. | |
| 11072 </errorid> | |
| 11073 <errorid id="JVMTI_ERROR_NULL_POINTER" num="100"> | |
| 11074 Pointer is unexpectedly <code>NULL</code>. | |
| 11075 </errorid> | |
| 11076 <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110"> | |
| 11077 The function attempted to allocate memory and no more memory was | |
| 11078 available for allocation. | |
| 11079 </errorid> | |
| 11080 <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111"> | |
| 11081 The desired functionality has not been enabled in this virtual machine. | |
| 11082 </errorid> | |
| 11083 <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115"> | |
| 11084 The thread being used to call this function is not attached | |
| 11085 to the virtual machine. Calls must be made from attached threads. | |
| 11086 See <code>AttachCurrentThread</code> in the JNI invocation API. | |
| 11087 </errorid> | |
| 11088 <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116"> | |
| 11089 The <jvmti/> environment provided is no longer connected or is | |
| 11090 not an environment. | |
| 11091 </errorid> | |
| 11092 <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112"> | |
| 11093 The desired functionality is not available in the current | |
| 11094 <functionlink id="GetPhase">phase</functionlink>. | |
| 11095 Always returned if the virtual machine has completed running. | |
| 11096 </errorid> | |
| 11097 <errorid id="JVMTI_ERROR_INTERNAL" num="113"> | |
| 11098 An unexpected internal error has occurred. | |
| 11099 </errorid> | |
| 11100 </errorcategory> | |
| 11101 | |
| 11102 <errorcategory id="reqerrors" label="Function Specific Required Errors"> | |
| 11103 <intro> | |
| 11104 The following errors are returned by some <jvmti/> functions and must | |
| 11105 be returned by the implementation when the condition occurs. | |
| 11106 </intro> | |
| 11107 | |
| 11108 <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12"> | |
| 11109 Invalid priority. | |
| 11110 </errorid> | |
| 11111 <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13"> | |
| 11112 Thread was not suspended. | |
| 11113 </errorid> | |
| 11114 <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14"> | |
| 11115 Thread already suspended. | |
| 11116 </errorid> | |
| 11117 <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15"> | |
| 11118 This operation requires the thread to be alive--that is, | |
| 11119 it must be started and not yet have died. | |
| 11120 </errorid> | |
| 11121 <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22"> | |
| 11122 The class has been loaded but not yet prepared. | |
| 11123 </errorid> | |
| 11124 <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31"> | |
| 11125 There are no Java programming language or JNI stack frames at the specified depth. | |
| 11126 </errorid> | |
| 11127 <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32"> | |
| 11128 Information about the frame is not available (e.g. for native frames). | |
| 11129 </errorid> | |
| 11130 <errorid id="JVMTI_ERROR_DUPLICATE" num="40"> | |
| 11131 Item already set. | |
| 11132 </errorid> | |
| 11133 <errorid id="JVMTI_ERROR_NOT_FOUND" num="41"> | |
| 11134 Desired element (e.g. field or breakpoint) not found | |
| 11135 </errorid> | |
| 11136 <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51"> | |
| 11137 This thread doesn't own the raw monitor. | |
| 11138 </errorid> | |
| 11139 <errorid id="JVMTI_ERROR_INTERRUPT" num="52"> | |
| 11140 The call has been interrupted before completion. | |
| 11141 </errorid> | |
| 11142 <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79"> | |
| 11143 The class cannot be modified. | |
| 11144 </errorid> | |
| 11145 <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98"> | |
| 11146 The functionality is not available in this virtual machine. | |
| 11147 </errorid> | |
| 11148 <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101"> | |
| 11149 The requested information is not available. | |
| 11150 </errorid> | |
| 11151 <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102"> | |
| 11152 The specified event type ID is not recognized. | |
| 11153 </errorid> | |
| 11154 <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104"> | |
| 11155 The requested information is not available for native method. | |
| 11156 </errorid> | |
| 11157 <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106"> | |
| 11158 The class loader does not support this operation. | |
| 11159 </errorid> | |
| 11160 </errorcategory> | |
| 11161 | |
| 11162 <errorcategory id="function-specific-errors" label="Function Specific Agent Errors"> | |
| 11163 <intro> | |
| 11164 The following errors are returned by some <jvmti/> functions. | |
| 11165 They are returned in the event of invalid parameters passed by the | |
| 11166 agent or usage in an invalid context. | |
| 11167 An implementation is not required to detect these errors. | |
| 11168 </intro> | |
| 11169 | |
| 11170 <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10"> | |
| 11171 The passed thread is not a valid thread. | |
| 11172 </errorid> | |
| 11173 <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25"> | |
| 11174 Invalid field. | |
| 11175 </errorid> | |
| 11176 <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23"> | |
| 11177 Invalid method. | |
| 11178 </errorid> | |
| 11179 <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24"> | |
| 11180 Invalid location. | |
| 11181 </errorid> | |
| 11182 <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20"> | |
| 11183 Invalid object. | |
| 11184 </errorid> | |
| 11185 <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21"> | |
| 11186 Invalid class. | |
| 11187 </errorid> | |
| 11188 <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34"> | |
| 11189 The variable is not an appropriate type for the function used. | |
| 11190 </errorid> | |
| 11191 <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35"> | |
| 11192 Invalid slot. | |
| 11193 </errorid> | |
| 11194 <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99"> | |
| 11195 The capability being used is false in this environment. | |
| 11196 </errorid> | |
| 11197 <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11"> | |
| 11198 Thread group invalid. | |
| 11199 </errorid> | |
| 11200 <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50"> | |
| 11201 Invalid raw monitor. | |
| 11202 </errorid> | |
| 11203 <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103"> | |
| 11204 Illegal argument. | |
| 11205 </errorid> | |
| 11206 <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65"> | |
| 11207 The state of the thread has been modified, and is now inconsistent. | |
| 11208 </errorid> | |
| 11209 <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68"> | |
| 11210 A new class file has a version number not supported by this VM. | |
| 11211 </errorid> | |
| 11212 <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60"> | |
| 11213 A new class file is malformed (the VM would return a <code>ClassFormatError</code>). | |
| 11214 </errorid> | |
| 11215 <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61"> | |
| 11216 The new class file definitions would lead to a circular | |
| 11217 definition (the VM would return a <code>ClassCircularityError</code>). | |
| 11218 </errorid> | |
| 11219 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63"> | |
| 11220 A new class file would require adding a method. | |
| 11221 </errorid> | |
| 11222 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64"> | |
| 11223 A new class version changes a field. | |
| 11224 </errorid> | |
| 11225 <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62"> | |
| 11226 The class bytes fail verification. | |
| 11227 </errorid> | |
| 11228 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66"> | |
| 11229 A direct superclass is different for the new class | |
| 11230 version, or the set of directly implemented | |
| 11231 interfaces is different. | |
| 11232 </errorid> | |
| 11233 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67"> | |
| 11234 A new class version does not declare a method | |
| 11235 declared in the old class version. | |
| 11236 </errorid> | |
| 11237 <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69"> | |
| 11238 The class name defined in the new class file is | |
| 11239 different from the name in the old class object. | |
| 11240 </errorid> | |
| 11241 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70"> | |
| 11242 A new class version has different modifiers. | |
| 11243 </errorid> | |
| 11244 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71"> | |
| 11245 A method in the new class version has different modifiers | |
| 11246 than its counterpart in the old class version. | |
| 11247 </errorid> | |
| 11248 </errorcategory> | |
| 11249 </errorsection> | |
| 11250 | |
| 11251 <eventsection label="Events"> | |
| 11252 <intro label="Handling Events" id="eventIntro"> | |
| 11253 Agents can be informed of many events that occur in application | |
| 11254 programs. | |
| 11255 <p/> | |
| 11256 To handle events, designate a set of callback functions with | |
| 11257 <functionlink id="SetEventCallbacks"></functionlink>. | |
| 11258 For each event the corresponding callback function will be | |
| 11259 called. | |
| 11260 Arguments to the callback function provide additional | |
| 11261 information about the event. | |
| 11262 <p/> | |
| 11263 The callback function is usually called from within an application | |
| 11264 thread. The <jvmti/> implementation does not | |
| 11265 queue events in any way. This means | |
| 11266 that event callback functions must be written | |
| 11267 carefully. Here are some general guidelines. See | |
| 11268 the individual event descriptions for further | |
| 11269 suggestions. | |
| 11270 <p/> | |
| 11271 <ul> | |
| 11272 <li>Any exception thrown during the execution of an event callback can | |
| 11273 overwrite any current pending exception in the current application thread. | |
| 11274 Care must be taken to preserve a pending exception | |
| 11275 when an event callback makes a JNI call that might generate an exception. | |
| 11276 </li> | |
| 11277 <li>Event callback functions must be re-entrant. The <jvmti/> implementation does | |
| 11278 not queue events. If an agent needs to process events one at a time, it | |
| 11279 can use a raw monitor inside the | |
| 11280 event callback functions to serialize event processing. | |
| 11281 </li> | |
| 11282 <li>Event callback functions that execute JNI's FindClass function to load | |
| 11283 classes need to note that FindClass locates the class loader associated | |
| 11284 with the current native method. For the purposes of class loading, an | |
| 11285 event callback that includes a JNI environment as a parameter to the | |
| 11286 callback will treated as if it is a native call, where the native method | |
| 11287 is in the class of the event thread's current frame. | |
| 11288 </li> | |
| 11289 </ul> | |
| 11290 <p/> | |
| 11291 Some <jvmti/> events identify objects with JNI references. | |
| 11292 All references | |
| 11293 in <jvmti/> events are JNI local references and will become invalid | |
| 11294 after the event callback returns. | |
| 11295 Unless stated otherwise, memory referenced by pointers sent in event | |
| 11296 callbacks may not be referenced after the event callback returns. | |
| 11297 <p/> | |
| 11298 Except where stated otherwise, events are delivered on the thread | |
| 11299 that caused the event. | |
| 11300 Events are sent at the time they occur. | |
| 11301 The specification for each event includes the set of | |
| 11302 <functionlink id="GetPhase">phases</functionlink> in which it can be sent; | |
| 11303 if an event triggering activity occurs during another phase, no event | |
| 11304 is sent. | |
| 11305 <p/> | |
| 11306 A thread that generates an event does not change its execution status | |
| 11307 (for example, the event does not cause the thread to be suspended). | |
| 11308 If an agent wishes the event to result in suspension, then the agent | |
| 11309 is responsible for explicitly suspending the thread with | |
| 11310 <functionlink id="SuspendThread"></functionlink>. | |
| 11311 <p/> | |
| 11312 If an event is enabled in multiple environments, the event will be sent | |
| 11313 to each agent in the order that the environments were created. | |
| 11314 </intro> | |
| 11315 | |
| 11316 <intro label="Enabling Events" id="enablingevents"> | |
| 11317 All events are initially disabled. In order to receive any | |
| 11318 event: | |
| 11319 <ul> | |
| 11320 <li> | |
| 11321 If the event requires a capability, that capability must | |
| 11322 be added with | |
| 11323 <functionlink id="AddCapabilities"></functionlink>. | |
| 11324 </li> | |
| 11325 <li> | |
| 11326 A callback for the event must be set with | |
| 11327 <functionlink id="SetEventCallbacks"></functionlink>. | |
| 11328 </li> | |
| 11329 <li> | |
| 11330 The event must be enabled with | |
| 11331 <functionlink id="SetEventNotificationMode"></functionlink>. | |
| 11332 </li> | |
| 11333 </ul> | |
| 11334 </intro> | |
| 11335 | |
| 11336 <intro label="Multiple Co-located Events" id="eventorder"> | |
| 11337 In many situations it is possible for multiple events to occur | |
| 11338 at the same location in one thread. When this happens, all the events | |
| 11339 are reported through the event callbacks in the order specified in this section. | |
| 11340 <p/> | |
| 11341 If the current location is at the entry point of a method, the | |
| 11342 <eventlink id="MethodEntry"></eventlink> event is reported before | |
| 11343 any other event at the current location in the same thread. | |
| 11344 <p/> | |
| 11345 If an exception catch has been detected at the current location, | |
| 11346 either because it is the beginning of a catch clause or a native method | |
| 11347 that cleared a pending exception has returned, the | |
| 11348 <code>exceptionCatch</code> event is reported before | |
| 11349 any other event at the current location in the same thread. | |
| 11350 <p/> | |
| 11351 If a <code>singleStep</code> event or | |
| 11352 <code>breakpoint</code> event is triggered at the | |
| 11353 current location, the event is defined to occur | |
| 11354 immediately before the code at the current location is executed. | |
| 11355 These events are reported before any events which are triggered | |
| 11356 by the execution of code at the current location in the same | |
| 11357 thread (specifically: | |
| 11358 <code>exception</code>, | |
| 11359 <code>fieldAccess</code>, and | |
| 11360 <code>fieldModification</code>). | |
| 11361 If both a step and breakpoint event are triggered for the same thread and | |
| 11362 location, the step event is reported before the breakpoint event. | |
| 11363 <p/> | |
| 11364 If the current location is the exit point of a method (that is, the last | |
| 11365 location before returning to the caller), the | |
| 11366 <eventlink id="MethodExit"></eventlink> event and | |
| 11367 the <eventlink id="FramePop"></eventlink> event (if requested) | |
| 11368 are reported after all other events at the current location in the same | |
| 11369 thread. There is no specified ordering of these two events | |
| 11370 with respect to each other. | |
| 11371 <p/> | |
| 11372 Co-located events can be triggered during the processing of some other | |
| 11373 event by the agent at the same location in the same thread. | |
| 11374 If such an event, of type <i>y</i>, is triggered during the processing of | |
| 11375 an event of type <i>x</i>, and if <i>x</i> | |
| 11376 precedes <i>y</i> in the ordering specified above, the co-located event | |
| 11377 <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede | |
| 11378 <i>y</i>, <i>y</i> is not reported for the current thread and location. | |
| 11379 For example, if a breakpoint is set at the current location | |
| 11380 during the processing of <eventlink id="SingleStep"></eventlink>, | |
| 11381 that breakpoint will be reported before the thread moves off the current | |
| 11382 location. | |
| 11383 <p/>The following events are never considered to be co-located with | |
| 11384 other events. | |
| 11385 <ul> | |
| 11386 <li><eventlink id="VMStart"></eventlink></li> | |
| 11387 <li><eventlink id="VMInit"></eventlink></li> | |
| 11388 <li><eventlink id="VMDeath"></eventlink></li> | |
| 11389 <li><eventlink id="ThreadStart"></eventlink></li> | |
| 11390 <li><eventlink id="ThreadEnd"></eventlink></li> | |
| 11391 <li><eventlink id="ClassLoad"></eventlink></li> | |
| 11392 <li><eventlink id="ClassPrepare"></eventlink></li> | |
| 11393 </ul> | |
| 11394 </intro> | |
| 11395 | |
| 11396 <intro label="Event Callbacks" id="jvmtiEventCallbacks"> | |
| 11397 The event callback structure below is used to specify the handler function | |
| 11398 for events. It is set with the | |
| 11399 <functionlink id="SetEventCallbacks"></functionlink> function. | |
| 11400 </intro> | |
| 11401 | |
| 11402 <event label="Single Step" | |
| 11403 id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60"> | |
| 11404 <description> | |
| 11405 Single step events allow the agent to trace thread execution | |
| 11406 at the finest granularity allowed by the VM. A single step event is | |
| 11407 generated whenever a thread reaches a new location. | |
| 11408 Typically, single step events represent the completion of one VM | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
11409 instruction as defined in <vmspec/>. However, some implementations |
| 0 | 11410 may define locations differently. In any case the |
| 11411 <code>method</code> and <code>location</code> | |
| 11412 parameters uniquely identify the current location and allow | |
| 11413 the mapping to source file and line number when that information is | |
| 11414 available. | |
| 11415 <p/> | |
| 11416 No single step events are generated from within native methods. | |
| 11417 </description> | |
| 11418 <origin>jvmdi</origin> | |
| 11419 <capabilities> | |
| 11420 <required id="can_generate_single_step_events"></required> | |
| 11421 </capabilities> | |
| 11422 <parameters> | |
| 11423 <param id="jni_env"> | |
| 11424 <outptr> | |
| 11425 <struct>JNIEnv</struct> | |
| 11426 </outptr> | |
| 11427 <description> | |
| 11428 The JNI environment of the event (current) thread | |
| 11429 </description> | |
| 11430 </param> | |
| 11431 <param id="thread"> | |
| 11432 <jthread/> | |
| 11433 <description> | |
| 11434 Thread about to execution a new instruction | |
| 11435 </description> | |
| 11436 </param> | |
| 11437 <param id="klass"> | |
| 11438 <jclass method="method"/> | |
| 11439 <description> | |
| 11440 Class of the method about to execute a new instruction | |
| 11441 </description> | |
| 11442 </param> | |
| 11443 <param id="method"> | |
| 11444 <jmethodID class="klass"/> | |
| 11445 <description> | |
| 11446 Method about to execute a new instruction | |
| 11447 </description> | |
| 11448 </param> | |
| 11449 <param id="location"> | |
| 11450 <jlocation/> | |
| 11451 <description> | |
| 11452 Location of the new instruction | |
| 11453 </description> | |
| 11454 </param> | |
| 11455 </parameters> | |
| 11456 </event> | |
| 11457 | |
| 11458 <event label="Breakpoint" | |
| 11459 id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62"> | |
| 11460 <description> | |
| 11461 Breakpoint events are generated whenever a thread reaches a location | |
| 11462 designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>. | |
| 11463 The <code>method</code> and <code>location</code> | |
| 11464 parameters uniquely identify the current location and allow | |
| 11465 the mapping to source file and line number when that information is | |
| 11466 available. | |
| 11467 </description> | |
| 11468 <origin>jvmdi</origin> | |
| 11469 <capabilities> | |
| 11470 <required id="can_generate_breakpoint_events"></required> | |
| 11471 </capabilities> | |
| 11472 <parameters> | |
| 11473 <param id="jni_env"> | |
| 11474 <outptr> | |
| 11475 <struct>JNIEnv</struct> | |
| 11476 </outptr> | |
| 11477 <description> | |
| 11478 The JNI environment of the event (current) thread. | |
| 11479 </description> | |
| 11480 </param> | |
| 11481 <param id="thread"> | |
| 11482 <jthread/> | |
| 11483 <description> | |
| 11484 Thread that hit the breakpoint | |
| 11485 </description> | |
| 11486 </param> | |
| 11487 <param id="klass"> | |
| 11488 <jclass method="method"/> | |
| 11489 <description> | |
| 11490 Class of the method that hit the breakpoint | |
| 11491 </description> | |
| 11492 </param> | |
| 11493 <param id="method"> | |
| 11494 <jmethodID class="klass"/> | |
| 11495 <description> | |
| 11496 Method that hit the breakpoint | |
| 11497 </description> | |
| 11498 </param> | |
| 11499 <param id="location"> | |
| 11500 <jlocation/> | |
| 11501 <description> | |
| 11502 location of the breakpoint | |
| 11503 </description> | |
| 11504 </param> | |
| 11505 </parameters> | |
| 11506 </event> | |
| 11507 | |
| 11508 <event label="Field Access" | |
| 11509 id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63"> | |
| 11510 <description> | |
| 11511 Field access events are generated whenever a thread accesses | |
| 11512 a field that was designated as a watchpoint | |
| 11513 with <functionlink id="SetFieldAccessWatch"></functionlink>. | |
| 11514 The <code>method</code> and <code>location</code> | |
| 11515 parameters uniquely identify the current location and allow | |
| 11516 the mapping to source file and line number when that information is | |
| 11517 available. | |
| 11518 </description> | |
| 11519 <origin>jvmdi</origin> | |
| 11520 <capabilities> | |
| 11521 <required id="can_generate_field_access_events"></required> | |
| 11522 </capabilities> | |
| 11523 <parameters> | |
| 11524 <param id="jni_env"> | |
| 11525 <outptr> | |
| 11526 <struct>JNIEnv</struct> | |
| 11527 </outptr> | |
| 11528 <description> | |
| 11529 The JNI environment of the event (current) thread | |
| 11530 </description> | |
| 11531 </param> | |
| 11532 <param id="thread"> | |
| 11533 <jthread/> | |
| 11534 <description> | |
| 11535 Thread accessing the field | |
| 11536 </description> | |
| 11537 </param> | |
| 11538 <param id="klass"> | |
| 11539 <jclass method="method"/> | |
| 11540 <description> | |
| 11541 Class of the method where the access is occurring | |
| 11542 </description> | |
| 11543 </param> | |
| 11544 <param id="method"> | |
| 11545 <jmethodID class="klass"/> | |
| 11546 <description> | |
| 11547 Method where the access is occurring | |
| 11548 </description> | |
| 11549 </param> | |
| 11550 <param id="location"> | |
| 11551 <jlocation/> | |
| 11552 <description> | |
| 11553 Location where the access is occurring | |
| 11554 </description> | |
| 11555 </param> | |
| 11556 <param id="field_klass"> | |
| 11557 <jclass field="field"/> | |
| 11558 <description> | |
| 11559 Class of the field being accessed | |
| 11560 </description> | |
| 11561 </param> | |
| 11562 <param id="object"> | |
| 11563 <jobject/> | |
| 11564 <description> | |
| 11565 Object with the field being accessed if the field is an | |
| 11566 instance field; <code>NULL</code> otherwise | |
| 11567 </description> | |
| 11568 </param> | |
| 11569 <param id="field"> | |
| 11570 <jfieldID class="field_klass"/> | |
| 11571 <description> | |
| 11572 Field being accessed | |
| 11573 </description> | |
| 11574 </param> | |
| 11575 </parameters> | |
| 11576 </event> | |
| 11577 | |
| 11578 <event label="Field Modification" | |
| 11579 id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64"> | |
| 11580 <description> | |
| 11581 Field modification events are generated whenever a thread modifies | |
| 11582 a field that was designated as a watchpoint | |
| 11583 with <functionlink id="SetFieldModificationWatch"></functionlink>. | |
| 11584 The <code>method</code> and <code>location</code> | |
| 11585 parameters uniquely identify the current location and allow | |
| 11586 the mapping to source file and line number when that information is | |
| 11587 available. | |
| 11588 </description> | |
| 11589 <origin>jvmdi</origin> | |
| 11590 <capabilities> | |
| 11591 <required id="can_generate_field_modification_events"></required> | |
| 11592 </capabilities> | |
| 11593 <parameters> | |
| 11594 <param id="jni_env"> | |
| 11595 <outptr> | |
| 11596 <struct>JNIEnv</struct> | |
| 11597 </outptr> | |
| 11598 <description> | |
| 11599 The JNI environment of the event (current) thread | |
| 11600 </description> | |
| 11601 </param> | |
| 11602 <param id="thread"> | |
| 11603 <jthread/> | |
| 11604 <description> | |
| 11605 Thread modifying the field | |
| 11606 </description> | |
| 11607 </param> | |
| 11608 <param id="klass"> | |
| 11609 <jclass method="method"/> | |
| 11610 <description> | |
| 11611 Class of the method where the modification is occurring | |
| 11612 </description> | |
| 11613 </param> | |
| 11614 <param id="method"> | |
| 11615 <jmethodID class="klass"/> | |
| 11616 <description> | |
| 11617 Method where the modification is occurring | |
| 11618 </description> | |
| 11619 </param> | |
| 11620 <param id="location"> | |
| 11621 <jlocation/> | |
| 11622 <description> | |
| 11623 Location where the modification is occurring | |
| 11624 </description> | |
| 11625 </param> | |
| 11626 <param id="field_klass"> | |
| 11627 <jclass field="field"/> | |
| 11628 <description> | |
| 11629 Class of the field being modified | |
| 11630 </description> | |
| 11631 </param> | |
| 11632 <param id="object"> | |
| 11633 <jobject/> | |
| 11634 <description> | |
| 11635 Object with the field being modified if the field is an | |
| 11636 instance field; <code>NULL</code> otherwise | |
| 11637 </description> | |
| 11638 </param> | |
| 11639 <param id="field"> | |
| 11640 <jfieldID class="field_klass"/> | |
| 11641 <description> | |
| 11642 Field being modified | |
| 11643 </description> | |
| 11644 </param> | |
| 11645 <param id="signature_type"> | |
| 11646 <char/> | |
| 11647 <description> | |
| 11648 Signature type of the new value | |
| 11649 </description> | |
| 11650 </param> | |
| 11651 <param id="new_value"> | |
| 11652 <jvalue/> | |
| 11653 <description> | |
| 11654 The new value | |
| 11655 </description> | |
| 11656 </param> | |
| 11657 </parameters> | |
| 11658 </event> | |
| 11659 | |
| 11660 <event label="Frame Pop" | |
| 11661 id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61"> | |
| 11662 <description> | |
| 11663 Frame pop events are generated upon exit from a single method | |
| 11664 in a single frame as specified | |
| 11665 in a call to <functionlink id="NotifyFramePop"></functionlink>. | |
| 11666 This is true whether termination is caused by | |
| 11667 executing its return instruction | |
| 11668 or by throwing an exception to its caller | |
| 11669 (see <paramlink id="was_popped_by_exception"></paramlink>). | |
| 11670 However, frame pops caused by the <functionlink id="PopFrame"/> | |
| 11671 function are not reported. | |
| 11672 <p/> | |
| 11673 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
| 11674 identifies the executable location in the returning method, | |
| 11675 immediately prior to the return. | |
| 11676 </description> | |
| 11677 <origin>jvmdi</origin> | |
| 11678 <capabilities> | |
| 11679 <required id="can_generate_frame_pop_events"></required> | |
| 11680 </capabilities> | |
| 11681 <parameters> | |
| 11682 <param id="jni_env"> | |
| 11683 <outptr> | |
| 11684 <struct>JNIEnv</struct> | |
| 11685 </outptr> | |
| 11686 <description> | |
| 11687 The JNI environment of the event (current) thread | |
| 11688 </description> | |
| 11689 </param> | |
| 11690 <param id="thread"> | |
| 11691 <jthread/> | |
| 11692 <description> | |
| 11693 Thread that is popping the frame | |
| 11694 </description> | |
| 11695 </param> | |
| 11696 <param id="klass"> | |
| 11697 <jclass method="method"/> | |
| 11698 <description> | |
| 11699 Class of the method being popped | |
| 11700 </description> | |
| 11701 </param> | |
| 11702 <param id="method"> | |
| 11703 <jmethodID class="klass"/> | |
| 11704 <description> | |
| 11705 Method being popped | |
| 11706 </description> | |
| 11707 </param> | |
| 11708 <param id="was_popped_by_exception"> | |
| 11709 <jboolean/> | |
| 11710 <description> | |
| 11711 True if frame was popped by a thrown exception. | |
| 11712 False if method exited through its return instruction. | |
| 11713 </description> | |
| 11714 </param> | |
| 11715 </parameters> | |
| 11716 </event> | |
| 11717 | |
| 11718 <event label="Method Entry" | |
| 11719 id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65"> | |
| 11720 <description> | |
| 11721 Method entry events are generated upon entry of Java | |
| 11722 programming language methods (including native methods). | |
| 11723 <p/> | |
| 11724 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
| 11725 identifies the initial executable location in | |
| 11726 the method. | |
| 11727 <p/> | |
| 11728 Enabling method | |
| 11729 entry or exit events will significantly degrade performance on many platforms and is thus | |
| 11730 not advised for performance critical usage (such as profiling). | |
| 11731 <internallink id="bci">Bytecode instrumentation</internallink> should be | |
| 11732 used in these cases. | |
| 11733 </description> | |
| 11734 <origin>jvmdi</origin> | |
| 11735 <capabilities> | |
| 11736 <required id="can_generate_method_entry_events"></required> | |
| 11737 </capabilities> | |
| 11738 <parameters> | |
| 11739 <param id="jni_env"> | |
| 11740 <outptr> | |
| 11741 <struct>JNIEnv</struct> | |
| 11742 </outptr> | |
| 11743 <description> | |
| 11744 The JNI environment of the event (current) thread | |
| 11745 </description> | |
| 11746 </param> | |
| 11747 <param id="thread"> | |
| 11748 <jthread/> | |
| 11749 <description> | |
| 11750 Thread entering the method | |
| 11751 </description> | |
| 11752 </param> | |
| 11753 <param id="klass"> | |
| 11754 <jclass method="method"/> | |
| 11755 <description> | |
| 11756 Class of the method being entered | |
| 11757 </description> | |
| 11758 </param> | |
| 11759 <param id="method"> | |
| 11760 <jmethodID class="klass"/> | |
| 11761 <description> | |
| 11762 Method being entered | |
| 11763 </description> | |
| 11764 </param> | |
| 11765 </parameters> | |
| 11766 </event> | |
| 11767 | |
| 11768 <event label="Method Exit" | |
| 11769 id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66"> | |
| 11770 <description> | |
| 11771 Method exit events are generated upon exit from Java | |
| 11772 programming language methods (including native methods). | |
| 11773 This is true whether termination is caused by | |
| 11774 executing its return instruction | |
| 11775 or by throwing an exception to its caller | |
| 11776 (see <paramlink id="was_popped_by_exception"></paramlink>). | |
| 11777 <p/> | |
| 11778 The <code>method</code> field uniquely identifies the | |
| 11779 method being entered or exited. The <code>frame</code> field provides | |
| 11780 access to the stack frame for the method. | |
| 11781 <p/> | |
| 11782 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
| 11783 identifies the executable location in the returning method | |
| 11784 immediately prior to the return. | |
| 11785 <p/> | |
| 11786 Enabling method | |
| 11787 entry or exit events will significantly degrade performance on many platforms and is thus | |
| 11788 not advised for performance critical usage (such as profiling). | |
| 11789 <internallink id="bci">Bytecode instrumentation</internallink> should be | |
| 11790 used in these cases. | |
| 11791 </description> | |
| 11792 <origin>jvmdi</origin> | |
| 11793 <capabilities> | |
| 11794 <required id="can_generate_method_exit_events"></required> | |
| 11795 </capabilities> | |
| 11796 <parameters> | |
| 11797 <param id="jni_env"> | |
| 11798 <outptr> | |
| 11799 <struct>JNIEnv</struct> | |
| 11800 </outptr> | |
| 11801 <description> | |
| 11802 The JNI environment of the event (current) thread | |
| 11803 </description> | |
| 11804 </param> | |
| 11805 <param id="thread"> | |
| 11806 <jthread/> | |
| 11807 <description> | |
| 11808 Thread exiting the method | |
| 11809 </description> | |
| 11810 </param> | |
| 11811 <param id="klass"> | |
| 11812 <jclass method="method"/> | |
| 11813 <description> | |
| 11814 Class of the method being exited | |
| 11815 </description> | |
| 11816 </param> | |
| 11817 <param id="method"> | |
| 11818 <jmethodID class="klass"/> | |
| 11819 <description> | |
| 11820 Method being exited | |
| 11821 </description> | |
| 11822 </param> | |
| 11823 <param id="was_popped_by_exception"> | |
| 11824 <jboolean/> | |
| 11825 <description> | |
| 11826 True if frame was popped by a thrown exception. | |
| 11827 False if method exited through its return instruction. | |
| 11828 </description> | |
| 11829 </param> | |
| 11830 <param id="return_value"> | |
| 11831 <jvalue/> | |
| 11832 <description> | |
| 11833 The return value of the method being exited. | |
| 11834 Undefined and should not be used if | |
| 11835 <paramlink id="was_popped_by_exception"></paramlink> | |
| 11836 is true. | |
| 11837 </description> | |
| 11838 </param> | |
| 11839 </parameters> | |
| 11840 </event> | |
| 11841 | |
| 11842 <event label="Native Method Bind" phase="any" | |
| 11843 id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67"> | |
| 11844 <description> | |
| 11845 A Native Method Bind event is sent when a VM binds a | |
| 11846 Java programming language native method | |
| 11847 to the address of a function that implements the native method. | |
| 11848 This will occur when the native method is called for the first time | |
| 11849 and also occurs when the JNI function <code>RegisterNatives</code> is called. | |
| 11850 This event allows the bind to be redirected to an agent-specified | |
| 11851 proxy function. | |
| 11852 This event is not sent when the native method is unbound. | |
| 11853 Typically, this proxy function will need to be specific to a | |
| 11854 particular method or, to handle the general case, automatically | |
| 11855 generated assembly code, since after instrumentation code is | |
| 11856 executed the function at the original binding | |
| 11857 address will usually be invoked. | |
| 11858 The original binding can be restored or the redirection changed | |
| 11859 by use of the JNI function <code>RegisterNatives</code>. | |
| 11860 Some events may be sent during the primordial phase, JNI and | |
| 11861 most of <jvmti/> cannot be used at this time but the method and | |
| 11862 address can be saved for use later. | |
| 11863 </description> | |
| 11864 <origin>new</origin> | |
| 11865 <capabilities> | |
| 11866 <required id="can_generate_native_method_bind_events"></required> | |
| 11867 </capabilities> | |
| 11868 <parameters> | |
| 11869 <param id="jni_env"> | |
| 11870 <outptr> | |
| 11871 <struct>JNIEnv</struct> | |
| 11872 </outptr> | |
| 11873 <description> | |
| 11874 The JNI environment of the event (current) thread | |
| 11875 Will be <code>NULL</code> if sent during the primordial | |
| 11876 <functionlink id="GetPhase">phase</functionlink>. | |
| 11877 </description> | |
| 11878 </param> | |
| 11879 <param id="thread"> | |
| 11880 <jthread/> | |
| 11881 <description> | |
| 11882 Thread requesting the bind | |
| 11883 </description> | |
| 11884 </param> | |
| 11885 <param id="klass"> | |
| 11886 <jclass method="method"/> | |
| 11887 <description> | |
| 11888 Class of the method being bound | |
| 11889 </description> | |
| 11890 </param> | |
| 11891 <param id="method"> | |
| 11892 <jmethodID class="klass"/> | |
| 11893 <description> | |
| 11894 Native method being bound | |
| 11895 </description> | |
| 11896 </param> | |
| 11897 <param id="address"> | |
| 11898 <outptr><void/></outptr> | |
| 11899 <description> | |
| 11900 The address the VM is about to bind to--that is, the | |
| 11901 address of the implementation of the native method | |
| 11902 </description> | |
| 11903 </param> | |
| 11904 <param id="new_address_ptr"> | |
| 11905 <agentbuf><void/></agentbuf> | |
| 11906 <description> | |
| 11907 if the referenced address is changed (that is, if | |
| 11908 <code>*new_address_ptr</code> is set), the binding | |
| 11909 will instead be made to the supplied address. | |
| 11910 </description> | |
| 11911 </param> | |
| 11912 </parameters> | |
| 11913 </event> | |
| 11914 | |
| 11915 <event label="Exception" | |
| 11916 id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58"> | |
| 11917 <description> | |
| 11918 Exception events are generated whenever an exception is first detected | |
| 11919 in a Java programming language method. | |
| 11920 Where "exception" means any <code>java.lang.Throwable</code>. | |
| 11921 The exception may have been thrown by a Java programming language or native | |
| 11922 method, but in the case of native methods, the event is not generated | |
| 11923 until the exception is first seen by a Java programming language method. If an exception is | |
| 11924 set and cleared in a native method (and thus is never visible to Java programming language code), | |
| 11925 no exception event is generated. | |
| 11926 <p/> | |
| 11927 The <code>method</code> and <code>location</code> | |
| 11928 parameters uniquely identify the current location | |
| 11929 (where the exception was detected) and allow | |
| 11930 the mapping to source file and line number when that information is | |
| 11931 available. The <code>exception</code> field identifies the thrown | |
| 11932 exception object. The <code>catch_method</code> | |
| 11933 and <code>catch_location</code> identify the location of the catch clause, | |
| 11934 if any, that handles the thrown exception. If there is no such catch clause, | |
| 11935 each field is set to 0. There is no guarantee that the thread will ever | |
| 11936 reach this catch clause. If there are native methods on the call stack | |
| 11937 between the throw location and the catch clause, the exception may | |
| 11938 be reset by one of those native methods. | |
| 11939 Similarly, exceptions that are reported as uncaught (<code>catch_klass</code> | |
| 11940 et al. set to 0) may in fact be caught by native code. | |
| 11941 Agents can check for these occurrences by monitoring | |
| 11942 <eventlink id="ExceptionCatch"></eventlink> events. | |
| 11943 Note that finally clauses are implemented as catch and re-throw. Therefore they | |
| 11944 will be reported in the catch location. | |
| 11945 </description> | |
| 11946 <origin>jvmdi</origin> | |
| 11947 <capabilities> | |
| 11948 <required id="can_generate_exception_events"></required> | |
| 11949 </capabilities> | |
| 11950 <parameters> | |
| 11951 <param id="jni_env"> | |
| 11952 <outptr> | |
| 11953 <struct>JNIEnv</struct> | |
| 11954 </outptr> | |
| 11955 <description> | |
| 11956 The JNI environment of the event (current) thread | |
| 11957 </description> | |
| 11958 </param> | |
| 11959 <param id="thread"> | |
| 11960 <jthread/> | |
| 11961 <description> | |
| 11962 Thread generating the exception | |
| 11963 </description> | |
| 11964 </param> | |
| 11965 <param id="klass"> | |
| 11966 <jclass method="method"/> | |
| 11967 <description> | |
| 11968 Class generating the exception | |
| 11969 </description> | |
| 11970 </param> | |
| 11971 <param id="method"> | |
| 11972 <jmethodID class="klass"/> | |
| 11973 <description> | |
| 11974 Method generating the exception | |
| 11975 </description> | |
| 11976 </param> | |
| 11977 <param id="location"> | |
| 11978 <jlocation/> | |
| 11979 <description> | |
| 11980 Location where exception occurred | |
| 11981 </description> | |
| 11982 </param> | |
| 11983 <param id="exception"> | |
| 11984 <jobject/> | |
| 11985 <description> | |
| 11986 The exception being thrown | |
| 11987 </description> | |
| 11988 </param> | |
| 11989 <param id="catch_klass"> | |
| 11990 <jclass method="catch_method"/> | |
| 11991 <description> | |
| 11992 Class that will catch the exception, or <code>NULL</code> if no known catch | |
| 11993 </description> | |
| 11994 </param> | |
| 11995 <param id="catch_method"> | |
| 11996 <jmethodID class="catch_klass"/> | |
| 11997 <description> | |
| 11998 Method that will catch the exception, or <code>NULL</code> if no known catch | |
| 11999 </description> | |
| 12000 </param> | |
| 12001 <param id="catch_location"> | |
| 12002 <jlocation/> | |
| 12003 <description> | |
| 12004 location which will catch the exception or zero if no known catch | |
| 12005 </description> | |
| 12006 </param> | |
| 12007 </parameters> | |
| 12008 </event> | |
| 12009 | |
| 12010 <event label="Exception Catch" | |
| 12011 id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59"> | |
| 12012 <description> | |
| 12013 Exception catch events are generated whenever a thrown exception is caught. | |
| 12014 Where "exception" means any <code>java.lang.Throwable</code>. | |
| 12015 If the exception is caught in a Java programming language method, the event is generated | |
| 12016 when the catch clause is reached. If the exception is caught in a native | |
| 12017 method, the event is generated as soon as control is returned to a Java programming language | |
| 12018 method. Exception catch events are generated for any exception for which | |
| 12019 a throw was detected in a Java programming language method. | |
| 12020 Note that finally clauses are implemented as catch and re-throw. Therefore they | |
| 12021 will generate exception catch events. | |
| 12022 <p/> | |
| 12023 The <code>method</code> and <code>location</code> | |
| 12024 parameters uniquely identify the current location | |
| 12025 and allow the mapping to source file and line number when that information is | |
| 12026 available. For exceptions caught in a Java programming language method, the | |
| 12027 <code>exception</code> object identifies the exception object. Exceptions | |
| 12028 caught in native methods are not necessarily available by the time the | |
| 12029 exception catch is reported, so the <code>exception</code> field is set | |
| 12030 to <code>NULL</code>. | |
| 12031 </description> | |
| 12032 <origin>jvmdi</origin> | |
| 12033 <capabilities> | |
| 12034 <required id="can_generate_exception_events"></required> | |
| 12035 </capabilities> | |
| 12036 <parameters> | |
| 12037 <param id="jni_env"> | |
| 12038 <outptr> | |
| 12039 <struct>JNIEnv</struct> | |
| 12040 </outptr> | |
| 12041 <description> | |
| 12042 The JNI environment of the event (current) thread | |
| 12043 </description> | |
| 12044 </param> | |
| 12045 <param id="thread"> | |
| 12046 <jthread/> | |
| 12047 <description> | |
| 12048 Thread catching the exception | |
| 12049 </description> | |
| 12050 </param> | |
| 12051 <param id="klass"> | |
| 12052 <jclass method="method"/> | |
| 12053 <description> | |
| 12054 Class catching the exception | |
| 12055 </description> | |
| 12056 </param> | |
| 12057 <param id="method"> | |
| 12058 <jmethodID class="klass"/> | |
| 12059 <description> | |
| 12060 Method catching the exception | |
| 12061 </description> | |
| 12062 </param> | |
| 12063 <param id="location"> | |
| 12064 <jlocation/> | |
| 12065 <description> | |
| 12066 Location where exception is being caught | |
| 12067 </description> | |
| 12068 </param> | |
| 12069 <param id="exception"> | |
| 12070 <jobject/> | |
| 12071 <description> | |
| 12072 Exception being caught | |
| 12073 </description> | |
| 12074 </param> | |
| 12075 </parameters> | |
| 12076 </event> | |
| 12077 | |
| 12078 <event label="Thread Start" | |
| 12079 id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start"> | |
| 12080 <description> | |
| 12081 Thread start events are generated by a new thread before its initial | |
| 12082 method executes. | |
| 12083 <p/> | |
| 12084 A thread may be listed in the array returned by | |
| 12085 <functionlink id="GetAllThreads"></functionlink> | |
| 12086 before its thread start event is generated. | |
| 12087 It is possible for other events to be generated | |
| 12088 on a thread before its thread start event. | |
| 12089 <p/> | |
| 12090 The event is sent on the newly started <paramlink id="thread"></paramlink>. | |
| 12091 </description> | |
| 12092 <origin>jvmdi</origin> | |
| 12093 <capabilities> | |
| 12094 </capabilities> | |
| 12095 <parameters> | |
| 12096 <param id="jni_env"> | |
| 12097 <outptr> | |
| 12098 <struct>JNIEnv</struct> | |
| 12099 </outptr> | |
| 12100 <description> | |
| 12101 The JNI environment of the event (current) thread. | |
| 12102 </description> | |
| 12103 </param> | |
| 12104 <param id="thread"> | |
| 12105 <jthread/> | |
| 12106 <description> | |
| 12107 Thread starting | |
| 12108 </description> | |
| 12109 </param> | |
| 12110 </parameters> | |
| 12111 </event> | |
| 12112 | |
| 12113 <event label="Thread End" | |
| 12114 id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start"> | |
| 12115 <description> | |
| 12116 Thread end events are generated by a terminating thread | |
| 12117 after its initial method has finished execution. | |
| 12118 <p/> | |
| 12119 A thread may be listed in the array returned by | |
| 12120 <functionlink id="GetAllThreads"></functionlink> | |
| 12121 after its thread end event is generated. | |
| 12122 No events are generated on a thread | |
| 12123 after its thread end event. | |
| 12124 <p/> | |
| 12125 The event is sent on the dying <paramlink id="thread"></paramlink>. | |
| 12126 </description> | |
| 12127 <origin>jvmdi</origin> | |
| 12128 <capabilities> | |
| 12129 </capabilities> | |
| 12130 <parameters> | |
| 12131 <param id="jni_env"> | |
| 12132 <outptr> | |
| 12133 <struct>JNIEnv</struct> | |
| 12134 </outptr> | |
| 12135 <description> | |
| 12136 The JNI environment of the event (current) thread. | |
| 12137 </description> | |
| 12138 </param> | |
| 12139 <param id="thread"> | |
| 12140 <jthread/> | |
| 12141 <description> | |
| 12142 Thread ending | |
| 12143 </description> | |
| 12144 </param> | |
| 12145 </parameters> | |
| 12146 </event> | |
| 12147 | |
| 12148 <event label="Class Load" | |
| 12149 id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55"> | |
| 12150 <description> | |
| 12151 A class load event is generated when a class is first loaded. The order | |
| 12152 of class load events generated by a particular thread are guaranteed | |
| 12153 to match the order of class loading within that thread. | |
| 12154 Array class creation does not generate a class load event. | |
| 12155 The creation of a primitive class (for example, java.lang.Integer.TYPE) | |
| 12156 does not generate a class load event. | |
| 12157 <p/> | |
| 12158 This event is sent at an early stage in loading the class. As | |
| 12159 a result the class should be used carefully. Note, for example, | |
| 12160 that methods and fields are not yet loaded, so queries for methods, | |
| 12161 fields, subclasses, and so on will not give correct results. | |
| 12162 See "Loading of Classes and Interfaces" in the <i>Java Language | |
| 12163 Specification</i>. For most | |
| 12164 purposes the <eventlink id="ClassPrepare"></eventlink> event will | |
| 12165 be more useful. | |
| 12166 </description> | |
| 12167 <origin>jvmdi</origin> | |
| 12168 <capabilities> | |
| 12169 </capabilities> | |
| 12170 <parameters> | |
| 12171 <param id="jni_env"> | |
| 12172 <outptr> | |
| 12173 <struct>JNIEnv</struct> | |
| 12174 </outptr> | |
| 12175 <description> | |
| 12176 The JNI environment of the event (current) thread | |
| 12177 </description> | |
| 12178 </param> | |
| 12179 <param id="thread"> | |
| 12180 <jthread/> | |
| 12181 <description> | |
| 12182 Thread loading the class | |
| 12183 </description> | |
| 12184 </param> | |
| 12185 <param id="klass"> | |
| 12186 <jclass/> | |
| 12187 <description> | |
| 12188 Class being loaded | |
| 12189 </description> | |
| 12190 </param> | |
| 12191 </parameters> | |
| 12192 </event> | |
| 12193 | |
| 12194 <elide> | |
| 12195 <event label="Class Unload" | |
| 12196 id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57"> | |
| 12197 <description> | |
| 12198 A class unload event is generated when the class is about to be unloaded. | |
| 12199 Class unload events take place during garbage collection and must be | |
| 12200 handled extremely carefully. The garbage collector holds many locks | |
| 12201 and has suspended all other threads, so the event handler cannot depend | |
| 12202 on the ability to acquire any locks. The class unload event handler should | |
| 12203 do as little as possible, perhaps by queuing information to be processed | |
| 12204 later. In particular, the <code>jclass</code> should be used only in | |
| 12205 the JNI function <code>isSameObject</code> or in the following <jvmti/> functions: | |
| 12206 <ul> | |
| 12207 <li><functionlink id="GetClassSignature"></functionlink></li> | |
| 12208 <li><functionlink id="GetSourceFileName"></functionlink></li> | |
| 12209 <li><functionlink id="IsInterface"></functionlink></li> | |
| 12210 <li><functionlink id="IsArrayClass"></functionlink></li> | |
| 12211 </ul> | |
| 12212 </description> | |
| 12213 <origin>jvmdi</origin> | |
| 12214 <capabilities> | |
| 12215 </capabilities> | |
| 12216 <parameters> | |
| 12217 <param id="jni_env"> | |
| 12218 <outptr> | |
| 12219 <struct>JNIEnv</struct> | |
| 12220 </outptr> | |
| 12221 <description> | |
| 12222 The JNI environment of the event (current) thread | |
| 12223 </description> | |
| 12224 </param> | |
| 12225 <param id="thread"> | |
| 12226 <jthread/> | |
| 12227 <description> | |
| 12228 Thread generating the class unload | |
| 12229 </description> | |
| 12230 </param> | |
| 12231 <param id="klass"> | |
| 12232 <jclass/> | |
| 12233 <description> | |
| 12234 Class being unloaded | |
| 12235 </description> | |
| 12236 </param> | |
| 12237 </parameters> | |
| 12238 </event> | |
| 12239 </elide> | |
| 12240 | |
| 12241 <event label="Class Prepare" | |
| 12242 id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56"> | |
| 12243 <description> | |
| 12244 A class prepare event is generated when class preparation is complete. | |
| 12245 At this point, class fields, methods, and implemented interfaces are | |
| 12246 available, and no code from the class has been executed. Since array | |
| 12247 classes never have fields or methods, class prepare events are not | |
| 12248 generated for them. Class prepare events are not generated for | |
| 12249 primitive classes (for example, <code>java.lang.Integer.TYPE</code>). | |
| 12250 </description> | |
| 12251 <origin>jvmdi</origin> | |
| 12252 <capabilities> | |
| 12253 </capabilities> | |
| 12254 <parameters> | |
| 12255 <param id="jni_env"> | |
| 12256 <outptr> | |
| 12257 <struct>JNIEnv</struct> | |
| 12258 </outptr> | |
| 12259 <description> | |
| 12260 The JNI environment of the event (current) thread | |
| 12261 </description> | |
| 12262 </param> | |
| 12263 <param id="thread"> | |
| 12264 <jthread/> | |
| 12265 <description> | |
| 12266 Thread generating the class prepare | |
| 12267 </description> | |
| 12268 </param> | |
| 12269 <param id="klass"> | |
| 12270 <jclass/> | |
| 12271 <description> | |
| 12272 Class being prepared | |
| 12273 </description> | |
| 12274 </param> | |
| 12275 </parameters> | |
| 12276 </event> | |
| 12277 | |
| 12278 <event label="Class File Load Hook" phase="any" | |
| 12279 id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54"> | |
| 12280 <description> | |
| 12281 This event is sent when the VM obtains class file data, | |
| 12282 but before it constructs | |
| 12283 the in-memory representation for that class. | |
| 12284 This event is also sent when the class is being modified by the | |
| 12285 <functionlink id="RetransformClasses"/> function or | |
| 12286 the <functionlink id="RedefineClasses"/> function, | |
| 12287 called in any <jvmti/> environment. | |
| 12288 The agent can instrument | |
| 12289 the existing class file data sent by the VM to include profiling/debugging hooks. | |
| 12290 See the description of | |
| 12291 <internallink id="bci">bytecode instrumentation</internallink> | |
| 12292 for usage information. | |
| 12293 <p/> | |
| 12294 This event may be sent before the VM is initialized (the primordial | |
| 12295 <functionlink id="GetPhase">phase</functionlink>). During this time | |
| 12296 no VM resources should be created. Some classes might not be compatible | |
| 12297 with the function (eg. ROMized classes) and this event will not be | |
| 12298 generated for these classes. | |
| 12299 <p/> | |
| 12300 The agent must allocate the space for the modified | |
| 12301 class file data buffer | |
| 12302 using the memory allocation function | |
| 12303 <functionlink id="Allocate"></functionlink> because the | |
| 12304 VM is responsible for freeing the new class file data buffer | |
| 12305 using <functionlink id="Deallocate"></functionlink>. | |
| 12306 Note that <functionlink id="Allocate"></functionlink> | |
| 12307 is permitted during the primordial phase. | |
| 12308 <p/> | |
| 12309 If the agent wishes to modify the class file, it must set | |
| 12310 <code>new_class_data</code> to point | |
| 12311 to the newly instrumented class file data buffer and set | |
| 12312 <code>new_class_data_len</code> to the length of that | |
| 12313 buffer before returning | |
| 12314 from this call. If no modification is desired, the agent simply | |
| 12315 does not set <code>new_class_data</code>. If multiple agents | |
| 12316 have enabled this event the results are chained. That is, if | |
| 12317 <code>new_class_data</code> has been set, it becomes the | |
| 12318 <code>class_data</code> for the next agent. | |
| 12319 <p/> | |
| 12320 The order that this event is sent to each environment differs | |
| 12321 from other events. | |
| 12322 This event is sent to environments in the following order: | |
| 12323 <ul> | |
| 12324 <li><fieldlink id="can_retransform_classes" | |
| 12325 struct="jvmtiCapabilities">retransformation | |
| 12326 incapable</fieldlink> | |
| 12327 environments, in the | |
| 12328 order in which they were created | |
| 12329 </li> | |
| 12330 <li><fieldlink id="can_retransform_classes" | |
| 12331 struct="jvmtiCapabilities">retransformation | |
| 12332 capable</fieldlink> | |
| 12333 environments, in the | |
| 12334 order in which they were created | |
| 12335 </li> | |
| 12336 </ul> | |
| 12337 When triggered by <functionlink id="RetransformClasses"/>, | |
| 12338 this event is sent only to <fieldlink id="can_retransform_classes" | |
| 12339 struct="jvmtiCapabilities">retransformation | |
| 12340 capable</fieldlink> | |
| 12341 environments. | |
| 12342 </description> | |
| 12343 <origin>jvmpi</origin> | |
| 12344 <capabilities> | |
| 12345 <capability id="can_generate_all_class_hook_events"></capability> | |
| 12346 </capabilities> | |
| 12347 <parameters> | |
| 12348 <param id="jni_env"> | |
| 12349 <outptr> | |
| 12350 <struct>JNIEnv</struct> | |
| 12351 </outptr> | |
| 12352 <description> | |
| 12353 The JNI environment of the event (current) thread. | |
| 12354 Will be <code>NULL</code> if sent during the primordial | |
| 12355 <functionlink id="GetPhase">phase</functionlink>. | |
| 12356 </description> | |
| 12357 </param> | |
| 12358 <param id="class_being_redefined"> | |
| 12359 <jclass/> | |
| 12360 <description> | |
| 12361 The class being | |
| 12362 <functionlink id="RedefineClasses">redefined</functionlink> or | |
| 12363 <functionlink id="RetransformClasses">retransformed</functionlink>. | |
| 12364 <code>NULL</code> if sent by class load. | |
| 12365 </description> | |
| 12366 </param> | |
| 12367 <param id="loader"> | |
| 12368 <jobject/> | |
| 12369 <description> | |
| 12370 The class loader loading the class. | |
| 12371 <code>NULL</code> if the bootstrap class loader. | |
| 12372 </description> | |
| 12373 </param> | |
| 12374 <param id="name"> | |
| 12375 <vmbuf><char/></vmbuf> | |
| 12376 <description> | |
| 12377 Name of class being loaded as a VM internal qualified name | |
| 12378 (for example, "java/util/List"), encoded as a | |
| 12379 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 12380 Note: if the class is defined with a <code>NULL</code> name or | |
| 12381 without a name specified, <code>name</code> will be <code>NULL</code>. | |
| 12382 </description> | |
| 12383 </param> | |
| 12384 <param id="protection_domain"> | |
| 12385 <jobject/> | |
| 12386 <description> | |
| 12387 The <code>ProtectionDomain</code> of the class. | |
| 12388 </description> | |
| 12389 </param> | |
| 12390 <param id="class_data_len"> | |
| 12391 <jint/> | |
| 12392 <description> | |
| 12393 Length of current class file data buffer. | |
| 12394 </description> | |
| 12395 </param> | |
| 12396 <param id="class_data"> | |
| 12397 <vmbuf><uchar/></vmbuf> | |
| 12398 <description> | |
| 12399 Pointer to the current class file data buffer. | |
| 12400 </description> | |
| 12401 </param> | |
| 12402 <param id="new_class_data_len"> | |
| 12403 <outptr><jint/></outptr> | |
| 12404 <description> | |
| 12405 Pointer to the length of the new class file data buffer. | |
| 12406 </description> | |
| 12407 </param> | |
| 12408 <param id="new_class_data"> | |
| 12409 <agentbuf incount="new_class_data_len"><uchar/></agentbuf> | |
| 12410 <description> | |
| 12411 Pointer to the pointer to the instrumented class file data buffer. | |
| 12412 </description> | |
| 12413 </param> | |
| 12414 </parameters> | |
| 12415 </event> | |
| 12416 | |
| 12417 <event label="VM Start Event" | |
| 12418 id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start"> | |
| 12419 <description> | |
| 12420 The VM initialization event signals the start of the VM. | |
| 12421 At this time JNI is live but the VM is not yet fully initialized. | |
| 12422 Once this event is generated, the agent is free to call any JNI function. | |
| 12423 This event signals the beginning of the start phase, | |
| 12424 <jvmti/> functions permitted in the start phase may be called. | |
| 12425 <p/> | |
| 12426 In the case of VM start-up failure, this event will not be sent. | |
| 12427 </description> | |
| 12428 <origin>jvmdi</origin> | |
| 12429 <capabilities> | |
| 12430 </capabilities> | |
| 12431 <parameters> | |
| 12432 <param id="jni_env"> | |
| 12433 <outptr> | |
| 12434 <struct>JNIEnv</struct> | |
| 12435 </outptr> | |
| 12436 <description> | |
| 12437 The JNI environment of the event (current) thread. | |
| 12438 </description> | |
| 12439 </param> | |
| 12440 </parameters> | |
| 12441 </event> | |
| 12442 | |
| 12443 <event label="VM Initialization Event" | |
| 12444 id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50"> | |
| 12445 <description> | |
| 12446 The VM initialization event signals the completion of VM initialization. Once | |
| 12447 this event is generated, the agent is free to call any JNI or <jvmti/> | |
| 12448 function. The VM initialization event can be preceded by or can be concurrent | |
| 12449 with other events, but | |
| 12450 the preceding events should be handled carefully, if at all, because the | |
| 12451 VM has not completed its initialization. The thread start event for the | |
| 12452 main application thread is guaranteed not to occur until after the | |
| 12453 handler for the VM initialization event returns. | |
| 12454 <p/> | |
| 12455 In the case of VM start-up failure, this event will not be sent. | |
| 12456 </description> | |
| 12457 <origin>jvmdi</origin> | |
| 12458 <capabilities> | |
| 12459 </capabilities> | |
| 12460 <parameters> | |
| 12461 <param id="jni_env"> | |
| 12462 <outptr> | |
| 12463 <struct>JNIEnv</struct> | |
| 12464 </outptr> | |
| 12465 <description> | |
| 12466 The JNI environment of the event (current) thread. | |
| 12467 </description> | |
| 12468 </param> | |
| 12469 <param id="thread"> | |
| 12470 <jthread/> | |
| 12471 <description> | |
| 12472 The initial thread | |
| 12473 </description> | |
| 12474 </param> | |
| 12475 </parameters> | |
| 12476 </event> | |
| 12477 | |
| 12478 <event label="VM Death Event" | |
| 12479 id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51"> | |
| 12480 <description> | |
| 12481 The VM death event notifies the agent of the termination of the VM. | |
| 12482 No events will occur after the VMDeath event. | |
| 12483 <p/> | |
| 12484 In the case of VM start-up failure, this event will not be sent. | |
| 12485 Note that <internallink id="onunload">Agent_OnUnload</internallink> | |
| 12486 will still be called in these cases. | |
| 12487 </description> | |
| 12488 <origin>jvmdi</origin> | |
| 12489 <capabilities> | |
| 12490 </capabilities> | |
| 12491 <parameters> | |
| 12492 <param id="jni_env"> | |
| 12493 <outptr> | |
| 12494 <struct>JNIEnv</struct> | |
| 12495 </outptr> | |
| 12496 <description> | |
| 12497 The JNI environment of the event (current) thread | |
| 12498 </description> | |
| 12499 </param> | |
| 12500 </parameters> | |
| 12501 </event> | |
| 12502 | |
| 12503 <event label="Compiled Method Load" | |
| 12504 id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68"> | |
| 12505 <description> | |
| 12506 Sent when a method is compiled and loaded into memory by the VM. | |
| 12507 If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent. | |
| 12508 If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent, | |
| 12509 followed by a new <code>CompiledMethodLoad</code> event. | |
| 12510 Note that a single method may have multiple compiled forms, and that | |
| 12511 this event will be sent for each form. | |
| 12512 Note also that several methods may be inlined into a single | |
| 12513 address range, and that this event will be sent for each method. | |
| 12514 <p/> | |
| 12515 These events can be sent after their initial occurrence with | |
| 12516 <functionlink id="GenerateEvents"></functionlink>. | |
| 12517 </description> | |
| 12518 <origin>jvmpi</origin> | |
| 12519 <typedef id="jvmtiAddrLocationMap" label="Native address to location entry"> | |
| 12520 <field id="start_address"> | |
| 12521 <vmbuf><void/></vmbuf> | |
| 12522 <description> | |
| 12523 Starting native address of code corresponding to a location | |
| 12524 </description> | |
| 12525 </field> | |
| 12526 <field id="location"> | |
| 12527 <jlocation/> | |
| 12528 <description> | |
| 12529 Corresponding location. See | |
| 12530 <functionlink id="GetJLocationFormat"></functionlink> | |
| 12531 for the meaning of location. | |
| 12532 </description> | |
| 12533 </field> | |
| 12534 </typedef> | |
| 12535 <capabilities> | |
| 12536 <required id="can_generate_compiled_method_load_events"></required> | |
| 12537 </capabilities> | |
| 12538 <parameters> | |
| 12539 <param id="klass"> | |
| 12540 <jclass method="method"/> | |
| 12541 <description> | |
| 12542 Class of the method being compiled and loaded | |
| 12543 </description> | |
| 12544 </param> | |
| 12545 <param id="method"> | |
| 12546 <jmethodID class="klass"/> | |
| 12547 <description> | |
| 12548 Method being compiled and loaded | |
| 12549 </description> | |
| 12550 </param> | |
| 12551 <param id="code_size"> | |
| 12552 <jint/> | |
| 12553 <description> | |
| 12554 Size of compiled code | |
| 12555 </description> | |
| 12556 </param> | |
| 12557 <param id="code_addr"> | |
| 12558 <vmbuf><void/></vmbuf> | |
| 12559 <description> | |
| 12560 Address where compiled method code is loaded | |
| 12561 </description> | |
| 12562 </param> | |
| 12563 <param id="map_length"> | |
| 12564 <jint/> | |
| 12565 <description> | |
| 12566 Number of <typelink id="jvmtiAddrLocationMap"></typelink> | |
| 12567 entries in the address map. | |
| 12568 Zero if mapping information cannot be supplied. | |
| 12569 </description> | |
| 12570 </param> | |
| 12571 <param id="map"> | |
| 12572 <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf> | |
| 12573 <description> | |
| 12574 Map from native addresses to location. | |
| 12575 The native address range of each entry is from | |
| 12576 <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink> | |
| 12577 to <code>start_address-1</code> of the next entry. | |
| 12578 <code>NULL</code> if mapping information cannot be supplied. | |
| 12579 </description> | |
| 12580 </param> | |
| 12581 <param id="compile_info"> | |
| 12582 <vmbuf><void/></vmbuf> | |
| 12583 <description> | |
| 12584 VM-specific compilation information. | |
| 12585 The referenced compile information is managed by the VM | |
| 12586 and must not depend on the agent for collection. | |
| 12587 A VM implementation defines the content and lifetime | |
| 12588 of the information. | |
| 12589 </description> | |
| 12590 </param> | |
| 12591 </parameters> | |
| 12592 </event> | |
| 12593 | |
| 12594 <event label="Compiled Method Unload" | |
| 12595 id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69"> | |
| 12596 <description> | |
| 12597 Sent when a compiled method is unloaded from memory. | |
| 12598 This event might not be sent on the thread which performed the unload. | |
| 12599 This event may be sent sometime after the unload occurs, but | |
| 12600 will be sent before the memory is reused | |
| 12601 by a newly generated compiled method. This event may be sent after | |
| 12602 the class is unloaded. | |
| 12603 </description> | |
| 12604 <origin>jvmpi</origin> | |
| 12605 <capabilities> | |
| 12606 <required id="can_generate_compiled_method_load_events"></required> | |
| 12607 </capabilities> | |
| 12608 <parameters> | |
| 12609 <param id="klass"> | |
| 12610 <jclass method="method"/> | |
| 12611 <description> | |
| 12612 Class of the compiled method being unloaded. | |
| 12613 </description> | |
| 12614 </param> | |
| 12615 <param id="method"> | |
| 12616 <jmethodID class="klass"/> | |
| 12617 <description> | |
| 12618 Compiled method being unloaded. | |
| 12619 For identification of the compiled method only -- the class | |
| 12620 may be unloaded and therefore the method should not be used | |
| 12621 as an argument to further JNI or <jvmti/> functions. | |
| 12622 </description> | |
| 12623 </param> | |
| 12624 <param id="code_addr"> | |
| 12625 <vmbuf><void/></vmbuf> | |
| 12626 <description> | |
| 12627 Address where compiled method code was loaded. | |
| 12628 For identification of the compiled method only -- | |
| 12629 the space may have been reclaimed. | |
| 12630 </description> | |
| 12631 </param> | |
| 12632 </parameters> | |
| 12633 </event> | |
| 12634 | |
| 12635 <event label="Dynamic Code Generated" phase="any" | |
| 12636 id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70"> | |
| 12637 <description> | |
| 12638 Sent when a component of the virtual machine is generated dynamically. | |
| 12639 This does not correspond to Java programming language code that is | |
| 12640 compiled--see <eventlink id="CompiledMethodLoad"></eventlink>. | |
| 12641 This is for native code--for example, an interpreter that is generated | |
| 12642 differently depending on command-line options. | |
| 12643 <p/> | |
| 12644 Note that this event has no controlling capability. | |
| 12645 If a VM cannot generate these events, it simply does not send any. | |
| 12646 <p/> | |
| 12647 These events can be sent after their initial occurrence with | |
| 12648 <functionlink id="GenerateEvents"></functionlink>. | |
| 12649 </description> | |
| 12650 <origin>jvmpi</origin> | |
| 12651 <capabilities> | |
| 12652 </capabilities> | |
| 12653 <parameters> | |
| 12654 <param id="name"> | |
| 12655 <vmbuf><char/></vmbuf> | |
| 12656 <description> | |
| 12657 Name of the code, encoded as a | |
| 12658 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 12659 Intended for display to an end-user. | |
| 12660 The name might not be unique. | |
| 12661 </description> | |
| 12662 </param> | |
| 12663 <param id="address"> | |
| 12664 <vmbuf><void/></vmbuf> | |
| 12665 <description> | |
| 12666 Native address of the code | |
| 12667 </description> | |
| 12668 </param> | |
| 12669 <param id="length"> | |
| 12670 <jint/> | |
| 12671 <description> | |
| 12672 Length in bytes of the code | |
| 12673 </description> | |
| 12674 </param> | |
| 12675 </parameters> | |
| 12676 </event> | |
| 12677 | |
| 12678 <event label="Data Dump Request" | |
| 12679 id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71"> | |
| 12680 <description> | |
| 12681 Sent by the VM to request the agent to dump its data. This | |
| 12682 is just a hint and the agent need not react to this event. | |
| 12683 This is useful for processing command-line signals from users. For | |
| 12684 example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris | |
| 12685 causes the VM to send this event to the agent. | |
| 12686 </description> | |
| 12687 <origin>jvmpi</origin> | |
| 12688 <capabilities> | |
| 12689 </capabilities> | |
| 12690 <parameters> | |
| 12691 </parameters> | |
| 12692 </event> | |
| 12693 | |
| 12694 <event label="Monitor Contended Enter" | |
| 12695 id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75"> | |
| 12696 <description> | |
| 12697 Sent when a thread is attempting to enter a Java programming language | |
| 12698 monitor already acquired by another thread. | |
| 12699 </description> | |
| 12700 <origin>jvmpi</origin> | |
| 12701 <capabilities> | |
| 12702 <required id="can_generate_monitor_events"></required> | |
| 12703 </capabilities> | |
| 12704 <parameters> | |
| 12705 <param id="jni_env"> | |
| 12706 <outptr> | |
| 12707 <struct>JNIEnv</struct> | |
| 12708 </outptr> | |
| 12709 <description> | |
| 12710 The JNI environment of the event (current) thread | |
| 12711 </description> | |
| 12712 </param> | |
| 12713 <param id="thread"> | |
| 12714 <jthread/> | |
| 12715 <description> | |
| 12716 JNI local reference to the thread | |
| 12717 attempting to enter the monitor | |
| 12718 </description> | |
| 12719 </param> | |
| 12720 <param id="object"> | |
| 12721 <jobject/> | |
| 12722 <description> | |
| 12723 JNI local reference to the monitor | |
| 12724 </description> | |
| 12725 </param> | |
| 12726 </parameters> | |
| 12727 </event> | |
| 12728 | |
| 12729 <event label="Monitor Contended Entered" | |
| 12730 id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76"> | |
| 12731 <description> | |
| 12732 Sent when a thread enters a Java programming language | |
| 12733 monitor after waiting for it to be released by another thread. | |
| 12734 </description> | |
| 12735 <origin>jvmpi</origin> | |
| 12736 <capabilities> | |
| 12737 <required id="can_generate_monitor_events"></required> | |
| 12738 </capabilities> | |
| 12739 <parameters> | |
| 12740 <param id="jni_env"> | |
| 12741 <outptr> | |
| 12742 <struct>JNIEnv</struct> | |
| 12743 </outptr> | |
| 12744 <description> | |
| 12745 The JNI environment of the event (current) thread | |
| 12746 </description> | |
| 12747 </param> | |
| 12748 <param id="thread"> | |
| 12749 <jthread/> | |
| 12750 <description> | |
| 12751 JNI local reference to the thread entering | |
| 12752 the monitor | |
| 12753 </description> | |
| 12754 </param> | |
| 12755 <param id="object"> | |
| 12756 <jobject/> | |
| 12757 <description> | |
| 12758 JNI local reference to the monitor | |
| 12759 </description> | |
| 12760 </param> | |
| 12761 </parameters> | |
| 12762 </event> | |
| 12763 | |
| 12764 <event label="Monitor Wait" | |
| 12765 id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73"> | |
| 12766 <description> | |
| 12767 Sent when a thread is about to wait on an object. | |
| 12768 </description> | |
| 12769 <origin>jvmpi</origin> | |
| 12770 <capabilities> | |
| 12771 <required id="can_generate_monitor_events"></required> | |
| 12772 </capabilities> | |
| 12773 <parameters> | |
| 12774 <param id="jni_env"> | |
| 12775 <outptr> | |
| 12776 <struct>JNIEnv</struct> | |
| 12777 </outptr> | |
| 12778 <description> | |
| 12779 The JNI environment of the event (current) thread | |
| 12780 </description> | |
| 12781 </param> | |
| 12782 <param id="thread"> | |
| 12783 <jthread/> | |
| 12784 <description> | |
| 12785 JNI local reference to the thread about to wait | |
| 12786 </description> | |
| 12787 </param> | |
| 12788 <param id="object"> | |
| 12789 <jobject/> | |
| 12790 <description> | |
| 12791 JNI local reference to the monitor | |
| 12792 </description> | |
| 12793 </param> | |
| 12794 <param id="timeout"> | |
| 12795 <jlong/> | |
| 12796 <description> | |
| 12797 The number of milliseconds the thread will wait | |
| 12798 </description> | |
| 12799 </param> | |
| 12800 </parameters> | |
| 12801 </event> | |
| 12802 | |
| 12803 <event label="Monitor Waited" | |
| 12804 id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74"> | |
| 12805 <description> | |
| 12806 Sent when a thread finishes waiting on an object. | |
| 12807 </description> | |
| 12808 <origin>jvmpi</origin> | |
| 12809 <capabilities> | |
| 12810 <required id="can_generate_monitor_events"></required> | |
| 12811 </capabilities> | |
| 12812 <parameters> | |
| 12813 <param id="jni_env"> | |
| 12814 <outptr> | |
| 12815 <struct>JNIEnv</struct> | |
| 12816 </outptr> | |
| 12817 <description> | |
| 12818 The JNI environment of the event (current) thread | |
| 12819 </description> | |
| 12820 </param> | |
| 12821 <param id="thread"> | |
| 12822 <jthread/> | |
| 12823 <description> | |
| 12824 JNI local reference to the thread that was finished waiting | |
| 12825 </description> | |
| 12826 </param> | |
| 12827 <param id="object"> | |
| 12828 <jobject/> | |
| 12829 <description> | |
| 12830 JNI local reference to the monitor. | |
| 12831 </description> | |
| 12832 </param> | |
| 12833 <param id="timed_out"> | |
| 12834 <jboolean/> | |
| 12835 <description> | |
| 12836 True if the monitor timed out | |
| 12837 </description> | |
| 12838 </param> | |
| 12839 </parameters> | |
| 12840 </event> | |
| 12841 | |
| 12842 <event label="Resource Exhausted" | |
| 12843 id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80" | |
| 12844 since="1.1"> | |
| 12845 <description> | |
| 12846 Sent when a VM resource needed by a running application has been exhausted. | |
| 12847 Except as required by the optional capabilities, the set of resources | |
| 12848 which report exhaustion is implementation dependent. | |
| 12849 <p/> | |
| 12850 The following bit flags define the properties of the resource exhaustion: | |
| 12851 <constants id="jvmtiResourceExhaustionFlags" | |
| 12852 label="Resource Exhaustion Flags" | |
| 12853 kind="bits" | |
| 12854 since="1.1"> | |
| 12855 <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001"> | |
| 12856 After this event returns, the VM will throw a | |
| 12857 <code>java.lang.OutOfMemoryError</code>. | |
| 12858 </constant> | |
| 12859 <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002"> | |
| 12860 The VM was unable to allocate memory from the <tm>Java</tm> | |
| 12861 platform <i>heap</i>. | |
| 12862 The <i>heap</i> is the runtime | |
| 12863 data area from which memory for all class instances and | |
| 12864 arrays are allocated. | |
| 12865 </constant> | |
| 12866 <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004"> | |
| 12867 The VM was unable to create a thread. | |
| 12868 </constant> | |
| 12869 </constants> | |
| 12870 </description> | |
| 12871 <origin>new</origin> | |
| 12872 <capabilities> | |
| 12873 <capability id="can_generate_resource_exhaustion_heap_events"> | |
| 12874 Can generate events when the VM is unable to allocate memory from the | |
| 12875 <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>. | |
| 12876 </capability> | |
| 12877 <capability id="can_generate_resource_exhaustion_threads_events"> | |
| 12878 Can generate events when the VM is unable to | |
| 12879 <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create | |
| 12880 a thread</internallink>. | |
| 12881 </capability> | |
| 12882 </capabilities> | |
| 12883 <parameters> | |
| 12884 <param id="jni_env"> | |
| 12885 <outptr> | |
| 12886 <struct>JNIEnv</struct> | |
| 12887 </outptr> | |
| 12888 <description> | |
| 12889 The JNI environment of the event (current) thread | |
| 12890 </description> | |
| 12891 </param> | |
| 12892 <param id="flags"> | |
| 12893 <jint/> | |
| 12894 <description> | |
| 12895 Flags defining the properties of the of resource exhaustion | |
| 12896 as specified by the | |
| 12897 <internallink id="jvmtiResourceExhaustionFlags">Resource | |
| 12898 Exhaustion Flags</internallink>. | |
| 12899 </description> | |
| 12900 </param> | |
| 12901 <param id="reserved"> | |
| 12902 <vmbuf><void/></vmbuf> | |
| 12903 <description> | |
| 12904 Reserved. | |
| 12905 </description> | |
| 12906 </param> | |
| 12907 <param id="description"> | |
| 12908 <vmbuf><char/></vmbuf> | |
| 12909 <description> | |
| 12910 Description of the resource exhaustion, encoded as a | |
| 12911 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 12912 </description> | |
| 12913 </param> | |
| 12914 </parameters> | |
| 12915 </event> | |
| 12916 | |
| 12917 <event label="VM Object Allocation" | |
| 12918 id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84"> | |
| 12919 <description> | |
| 12920 Sent when a method causes the virtual machine to allocate an | |
| 12921 Object visible to Java programming language code and the | |
| 12922 allocation is not detectable by other intrumentation mechanisms. | |
| 12923 Generally object allocation should be detected by instrumenting | |
| 12924 the bytecodes of allocating methods. | |
| 12925 Object allocation generated in native code by JNI function | |
| 12926 calls should be detected using | |
| 12927 <internallink id="jniIntercept">JNI function interception</internallink>. | |
| 12928 Some methods might not have associated bytecodes and are not | |
| 12929 native methods, they instead are executed directly by the | |
| 12930 VM. These methods should send this event. | |
| 12931 Virtual machines which are incapable of bytecode instrumentation | |
| 12932 for some or all of their methods can send this event. | |
| 12933 <p/> | |
| 12934 Typical examples where this event might be sent: | |
| 12935 <ul> | |
| 12936 <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li> | |
| 12937 <li>Methods not represented by bytecodes -- for example, VM intrinsics and | |
| 12938 J2ME preloaded classes</li> | |
| 12939 </ul> | |
| 12940 Cases where this event would not be generated: | |
| 12941 <ul> | |
| 12942 <li>Allocation due to bytecodes -- for example, the <code>new</code> | |
| 12943 and <code>newarray</code> VM instructions</li> | |
| 12944 <li>Allocation due to JNI function calls -- for example, | |
| 12945 <code>AllocObject</code></li> | |
| 12946 <li>Allocations during VM initialization</li> | |
| 12947 <li>VM internal objects</li> | |
| 12948 </ul> | |
| 12949 </description> | |
| 12950 <origin>new</origin> | |
| 12951 <capabilities> | |
| 12952 <required id="can_generate_vm_object_alloc_events"></required> | |
| 12953 </capabilities> | |
| 12954 <parameters> | |
| 12955 <param id="jni_env"> | |
| 12956 <outptr> | |
| 12957 <struct>JNIEnv</struct> | |
| 12958 </outptr> | |
| 12959 <description> | |
| 12960 The JNI environment of the event (current) thread | |
| 12961 </description> | |
| 12962 </param> | |
| 12963 <param id="thread"> | |
| 12964 <jthread/> | |
| 12965 <description> | |
| 12966 Thread allocating the object. | |
| 12967 </description> | |
| 12968 </param> | |
| 12969 <param id="object"> | |
| 12970 <jobject/> | |
| 12971 <description> | |
| 12972 JNI local reference to the object that was allocated | |
| 12973 </description> | |
| 12974 </param> | |
| 12975 <param id="object_klass"> | |
| 12976 <jclass/> | |
| 12977 <description> | |
| 12978 JNI local reference to the class of the object | |
| 12979 </description> | |
| 12980 </param> | |
| 12981 <param id="size"> | |
| 12982 <jlong/> | |
| 12983 <description> | |
| 12984 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 12985 </description> | |
| 12986 </param> | |
| 12987 </parameters> | |
| 12988 </event> | |
| 12989 | |
| 12990 <event label="Object Free" | |
| 12991 id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83"> | |
| 12992 <description> | |
| 12993 An Object Free event is sent when the garbage collector frees an object. | |
| 12994 Events are only sent for tagged objects--see | |
| 12995 <internallink id="Heap">heap functions</internallink>. | |
| 12996 <p/> | |
| 12997 The event handler must not use JNI functions and | |
| 12998 must not use <jvmti/> functions except those which | |
| 12999 specifically allow such use (see the raw monitor, memory management, | |
| 13000 and environment local storage functions). | |
| 13001 </description> | |
| 13002 <origin>new</origin> | |
| 13003 <capabilities> | |
| 13004 <required id="can_generate_object_free_events"></required> | |
| 13005 </capabilities> | |
| 13006 <parameters> | |
| 13007 <param id="tag"> | |
| 13008 <jlong/> | |
| 13009 <description> | |
| 13010 The freed object's tag | |
| 13011 </description> | |
| 13012 </param> | |
| 13013 </parameters> | |
| 13014 </event> | |
| 13015 | |
| 13016 <event label="Garbage Collection Start" | |
| 13017 id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81"> | |
| 13018 <description> | |
|
2125
7246a374a9f2
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
2100
diff
changeset
|
13019 A Garbage Collection Start event is sent when a |
|
7246a374a9f2
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
2100
diff
changeset
|
13020 garbage collection pause begins. |
| 0 | 13021 Only stop-the-world collections are reported--that is, collections during |
| 13022 which all threads cease to modify the state of the Java virtual machine. | |
| 13023 This means that some collectors will never generate these events. | |
| 13024 This event is sent while the VM is still stopped, thus | |
| 13025 the event handler must not use JNI functions and | |
| 13026 must not use <jvmti/> functions except those which | |
| 13027 specifically allow such use (see the raw monitor, memory management, | |
| 13028 and environment local storage functions). | |
| 13029 <p/> | |
| 13030 This event is always sent as a matched pair with | |
| 13031 <eventlink id="GarbageCollectionFinish"/> | |
| 13032 (assuming both events are enabled) and no garbage collection | |
| 13033 events will occur between them. | |
| 13034 </description> | |
| 13035 <origin>new</origin> | |
| 13036 <capabilities> | |
| 13037 <required id="can_generate_garbage_collection_events"></required> | |
| 13038 </capabilities> | |
| 13039 <parameters> | |
| 13040 </parameters> | |
| 13041 </event> | |
| 13042 | |
| 13043 <event label="Garbage Collection Finish" | |
| 13044 id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82"> | |
| 13045 <description> | |
|
2125
7246a374a9f2
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
2100
diff
changeset
|
13046 A Garbage Collection Finish event is sent when a |
|
7246a374a9f2
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
2100
diff
changeset
|
13047 garbage collection pause ends. |
| 0 | 13048 This event is sent while the VM is still stopped, thus |
| 13049 the event handler must not use JNI functions and | |
| 13050 must not use <jvmti/> functions except those which | |
| 13051 specifically allow such use (see the raw monitor, memory management, | |
| 13052 and environment local storage functions). | |
| 13053 <p/> | |
| 13054 Some agents may need to do post garbage collection operations that | |
| 13055 require the use of the disallowed <jvmti/> or JNI functions. For these | |
| 13056 cases an agent thread can be created which waits on a raw monitor, | |
| 13057 and the handler for the Garbage Collection Finish event simply | |
| 13058 notifies the raw monitor | |
| 13059 <p/> | |
| 13060 This event is always sent as a matched pair with | |
| 13061 <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled). | |
| 13062 <issue> | |
| 13063 The most important use of this event is to provide timing information, | |
| 13064 and thus additional information is not required. However, | |
| 13065 information about the collection which is "free" should be included - | |
| 13066 what that information is needs to be determined. | |
| 13067 </issue> | |
| 13068 </description> | |
| 13069 <origin>new</origin> | |
| 13070 <capabilities> | |
| 13071 <required id="can_generate_garbage_collection_events"></required> | |
| 13072 </capabilities> | |
| 13073 <parameters> | |
| 13074 </parameters> | |
| 13075 </event> | |
| 13076 | |
| 13077 <elide> | |
| 13078 <event label="Verbose Output" phase="any" | |
| 13079 id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85"> | |
| 13080 <description> | |
| 13081 Send verbose messages as strings. | |
| 13082 <issue> | |
| 13083 This format is extremely fragile, as it can change with each | |
| 13084 platform, collector and version. Alternatives include: | |
| 13085 <ul> | |
| 13086 <li>building off Java programming language M and M APIs</li> | |
| 13087 <li>XML</li> | |
| 13088 <li>key/value pairs</li> | |
| 13089 <li>removing it</li> | |
| 13090 </ul> | |
| 13091 </issue> | |
| 13092 <issue> | |
| 13093 Though this seemed trivial to implement. | |
| 13094 In the RI it appears this will be quite complex. | |
| 13095 </issue> | |
| 13096 </description> | |
| 13097 <origin>new</origin> | |
| 13098 <capabilities> | |
| 13099 </capabilities> | |
| 13100 <parameters> | |
| 13101 <param id="flag"> | |
| 13102 <enum>jvmtiVerboseFlag</enum> | |
| 13103 <description> | |
| 13104 Which verbose output is being sent. | |
| 13105 </description> | |
| 13106 </param> | |
| 13107 <param id="message"> | |
| 13108 <vmbuf><char/></vmbuf> | |
| 13109 <description> | |
| 13110 Message text, encoded as a | |
| 13111 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 13112 </description> | |
| 13113 </param> | |
| 13114 </parameters> | |
| 13115 </event> | |
| 13116 </elide> | |
| 13117 | |
| 13118 </eventsection> | |
| 13119 | |
| 13120 <datasection> | |
| 13121 <intro> | |
| 13122 <jvmti/> extends the data types defined by JNI. | |
| 13123 </intro> | |
| 13124 <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface"> | |
| 13125 <basetype id="jboolean"> | |
| 13126 <description> | |
| 13127 Holds a Java programming language <code>boolean</code>. | |
| 13128 Unsigned 8 bits. | |
| 13129 </description> | |
| 13130 </basetype> | |
| 6919 | 13131 <basetype id="jchar"> |
| 13132 <description> | |
| 13133 Holds a Java programming language <code>char</code>. | |
| 13134 Unsigned 16 bits. | |
| 13135 </description> | |
| 13136 </basetype> | |
| 0 | 13137 <basetype id="jint"> |
| 13138 <description> | |
| 13139 Holds a Java programming language <code>int</code>. | |
| 13140 Signed 32 bits. | |
| 13141 </description> | |
| 13142 </basetype> | |
| 13143 <basetype id="jlong"> | |
| 13144 <description> | |
| 13145 Holds a Java programming language <code>long</code>. | |
| 13146 Signed 64 bits. | |
| 13147 </description> | |
| 13148 </basetype> | |
| 13149 <basetype id="jfloat"> | |
| 13150 <description> | |
| 13151 Holds a Java programming language <code>float</code>. | |
| 13152 32 bits. | |
| 13153 </description> | |
| 13154 </basetype> | |
| 13155 <basetype id="jdouble"> | |
| 13156 <description> | |
| 13157 Holds a Java programming language <code>double</code>. | |
| 13158 64 bits. | |
| 13159 </description> | |
| 13160 </basetype> | |
| 13161 <basetype id="jobject"> | |
| 13162 <description> | |
| 13163 Holds a Java programming language object. | |
| 13164 </description> | |
| 13165 </basetype> | |
| 13166 <basetype id="jclass"> | |
| 13167 <description> | |
| 13168 Holds a Java programming language class. | |
| 13169 </description> | |
| 13170 </basetype> | |
| 13171 <basetype id="jvalue"> | |
| 13172 <description> | |
| 13173 Is a union of all primitive types and <code>jobject</code>. Thus, holds any Java | |
| 13174 programming language value. | |
| 13175 </description> | |
| 13176 </basetype> | |
| 13177 <basetype id="jfieldID"> | |
| 13178 <description> | |
| 13179 Identifies a Java programming language field. | |
| 13180 <code>jfieldID</code>s returned by <jvmti/> functions and events may be | |
| 13181 safely stored. | |
| 13182 </description> | |
| 13183 </basetype> | |
| 13184 <basetype id="jmethodID"> | |
| 13185 <description> | |
| 13186 Identifies a Java programming language method, initializer, or constructor. | |
| 13187 <code>jmethodID</code>s returned by <jvmti/> functions and events may be | |
| 13188 safely stored. However, if the class is unloaded, they become invalid | |
| 13189 and must not be used. | |
| 13190 </description> | |
| 13191 </basetype> | |
| 13192 <basetype id="JNIEnv"> | |
| 13193 <description> | |
| 13194 Pointer to the JNI function table. Pointer to this (<code>JNIEnv *</code>) | |
| 13195 is a JNI environment. | |
| 13196 </description> | |
| 13197 </basetype> | |
| 13198 </basetypes> | |
| 13199 | |
| 13200 <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types"> | |
| 13201 <basetype id="jvmtiEnv"> | |
| 13202 <description> | |
| 13203 The <jvmti/> <internallink id="environments">environment</internallink> pointer. | |
| 13204 See the <internallink id="FunctionSection">Function Section</internallink>. | |
| 13205 <code>jvmtiEnv</code> points to the | |
| 13206 <internallink id="FunctionTable">function table</internallink> pointer. | |
| 13207 </description> | |
| 13208 </basetype> | |
| 13209 <basetype id="jthread"> | |
| 13210 <definition>typedef jobject jthread;</definition> | |
| 13211 <description> | |
| 13212 Subtype of <datalink id="jobject"></datalink> that holds a thread. | |
| 13213 </description> | |
| 13214 </basetype> | |
| 13215 <basetype id="jthreadGroup"> | |
| 13216 <definition>typedef jobject jthreadGroup;</definition> | |
| 13217 <description> | |
| 13218 Subtype of <datalink id="jobject"></datalink> that holds a thread group. | |
| 13219 </description> | |
| 13220 </basetype> | |
| 13221 <basetype id="jlocation"> | |
| 13222 <definition>typedef jlong jlocation;</definition> | |
| 13223 <description> | |
| 13224 A 64 bit value, representing a monotonically increasing | |
| 13225 executable position within a method. | |
| 13226 <code>-1</code> indicates a native method. | |
| 13227 See <functionlink id="GetJLocationFormat"></functionlink> for the format on a | |
| 13228 given VM. | |
| 13229 </description> | |
| 13230 </basetype> | |
| 13231 <basetype id="jrawMonitorID"> | |
| 13232 <definition>struct _jrawMonitorID; | |
| 13233 typedef struct _jrawMonitorID *jrawMonitorID;</definition> | |
| 13234 <description> | |
| 13235 A raw monitor. | |
| 13236 </description> | |
| 13237 </basetype> | |
| 13238 <basetype id="jvmtiError"> | |
| 13239 <description> | |
| 13240 Holds an error return code. | |
| 13241 See the <internallink id="ErrorSection">Error section</internallink> for possible values. | |
| 13242 <example> | |
| 13243 typedef enum { | |
| 13244 JVMTI_ERROR_NONE = 0, | |
| 13245 JVMTI_ERROR_INVALID_THREAD = 10, | |
| 13246 ... | |
| 13247 } jvmtiError; | |
| 13248 </example> | |
| 13249 </description> | |
| 13250 </basetype> | |
| 13251 <basetype id="jvmtiEvent"> | |
| 13252 <description> | |
| 13253 An identifier for an event type. | |
| 13254 See the <internallink id="EventSection">Event section</internallink> for possible values. | |
| 13255 It is guaranteed that future versions of this specification will | |
| 13256 never assign zero as an event type identifier. | |
| 13257 <example> | |
| 13258 typedef enum { | |
| 13259 JVMTI_EVENT_SINGLE_STEP = 1, | |
| 13260 JVMTI_EVENT_BREAKPOINT = 2, | |
| 13261 ... | |
| 13262 } jvmtiEvent; | |
| 13263 </example> | |
| 13264 </description> | |
| 13265 </basetype> | |
| 13266 <basetype id="jvmtiEventCallbacks"> | |
| 13267 <description> | |
| 13268 The callbacks used for events. | |
| 13269 <example> | |
| 13270 typedef struct { | |
| 13271 jvmtiEventVMInit VMInit; | |
| 13272 jvmtiEventVMDeath VMDeath; | |
| 13273 ... | |
| 13274 } jvmtiEventCallbacks; | |
| 13275 </example> | |
| 13276 See <internallink id="jvmtiEventCallbacks">event callbacks</internallink> | |
| 13277 for the complete structure. | |
| 13278 <p/> | |
| 13279 Where, for example, the VM initialization callback is defined: | |
| 13280 <example> | |
| 13281 typedef void (JNICALL *jvmtiEventVMInit) | |
| 13282 (jvmtiEnv *jvmti_env, | |
| 13283 JNIEnv* jni_env, | |
| 13284 jthread thread); | |
| 13285 </example> | |
| 13286 See the individual events for the callback function definition. | |
| 13287 </description> | |
| 13288 </basetype> | |
| 13289 <basetype id="jniNativeInterface"> | |
| 13290 <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition> | |
| 13291 <description> | |
| 13292 Typedef for the JNI function table <code>JNINativeInterface</code> | |
| 13293 defined in the | |
| 6919 | 13294 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp23720">JNI Specification</externallink>. |
| 0 | 13295 The JNI reference implementation defines this with an underscore. |
| 13296 </description> | |
| 13297 </basetype> | |
| 13298 </basetypes> | |
| 13299 | |
| 13300 </datasection> | |
| 13301 | |
| 13302 <issuessection label="Issues"> | |
| 13303 <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic"> | |
| 13304 JVMDI requires that the agent suspend threads before calling | |
| 13305 certain sensitive functions. JVMPI requires garbage collection to be | |
| 13306 disabled before calling certain sensitive functions. | |
| 13307 It was suggested that rather than have this requirement, that | |
| 13308 VM place itself in a suitable state before performing an | |
| 13309 operation. This makes considerable sense since each VM | |
| 13310 knows its requirements and can most easily arrange a | |
| 13311 safe state. | |
| 13312 <p/> | |
| 13313 The ability to externally suspend/resume threads will, of | |
| 13314 course, remain. The ability to enable/disable garbage collection will not. | |
| 13315 <p/> | |
| 13316 This issue is resolved--suspend will not | |
| 13317 be required. The spec has been updated to reflect this. | |
| 13318 </intro> | |
| 13319 | |
| 13320 <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling"> | |
| 13321 There are a variety of approaches to sampling call stacks. | |
| 13322 The biggest bifurcation is between VM controlled and agent | |
| 13323 controlled. | |
| 13324 <p/> | |
| 13325 This issue is resolved--agent controlled | |
| 13326 sampling will be the approach. | |
| 13327 </intro> | |
| 13328 | |
| 13329 <intro id="threadRepresentation" label="Resolved Issue: Thread Representation"> | |
| 13330 JVMDI represents threads as jthread. JVMPI primarily | |
| 13331 uses JNIEnv* to represent threads. | |
| 13332 <p/> | |
| 13333 The Expert Group has chosen jthread as the representation | |
| 13334 for threads in <jvmti/>. | |
| 13335 JNIEnv* is sent by | |
| 13336 events since it is needed to JNI functions. JNIEnv, per the | |
| 13337 JNI spec, are not supposed to be used outside their thread. | |
| 13338 </intro> | |
| 13339 | |
| 13340 <intro id="design" label="Resolved Issue: Method Representation"> | |
| 13341 The JNI spec allows an implementation to depend on jclass/jmethodID | |
| 13342 pairs, rather than simply a jmethodID, to reference a method. | |
| 13343 JVMDI, for consistency, choose the same representation. | |
| 13344 JVMPI, however, specifies that a jmethodID alone maps to a | |
| 13345 method. Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store | |
| 13346 pointers in jmethodIDs, and as a result, a jmethodID is sufficient. | |
| 13347 In fact, any JVM implementation that supports JVMPI must have | |
| 13348 such a representation. | |
| 13349 <jvmti/> will use jmethodID as a unique representation of a method | |
| 13350 (no jclass is used). | |
| 13351 There should be efficiency gains, particularly in | |
| 13352 functionality like stack dumping, to this representation. | |
| 13353 <p/> | |
| 13354 Note that fields were not used in JVMPI and that the access profile | |
| 13355 of fields differs from methods--for implementation efficiency | |
| 13356 reasons, a jclass/jfieldID pair will still be needed for field | |
| 13357 reference. | |
| 13358 </intro> | |
| 13359 | |
| 13360 <intro id="localReferenceIssue" label="Resolved Issue: Local References"> | |
| 13361 Functions return local references. | |
| 13362 </intro> | |
| 13363 | |
| 13364 <intro id="frameRep" label="Resolved Issue: Representation of frames"> | |
| 13365 In JVMDI, a frame ID is used to represent a frame. Problem with this | |
| 13366 is that a VM must track when a frame becomes invalid, a far better | |
| 13367 approach, and the one used in <jvmti/>, is to reference frames by depth. | |
| 13368 </intro> | |
| 13369 | |
| 13370 <intro id="requiredCapabilities" label="Issue: Required Capabilities"> | |
| 13371 Currently, having a required capabilities means that the functionality | |
| 13372 is optional. Capabilities are useful even for required functionality | |
| 13373 since they can inform the VM is needed set-up. Thus, there should be | |
| 13374 a set of capabilities that a conformant implementation must provide | |
| 13375 (if requested during Agent_OnLoad). | |
| 13376 </intro> | |
| 13377 | |
| 13378 <intro id="taghint" label="Proposal: add tag hint function"> | |
| 13379 A hint of the percentage of objects that will be tagged would | |
| 13380 help the VM pick a good implementation. | |
| 13381 </intro> | |
| 13382 | |
| 13383 <intro id="moreMonitorQueries" label="Request: More Monitor Quires"> | |
| 13384 How difficult or easy would be to extend the monitor_info category to include | |
| 13385 <pre> | |
| 13386 - current number of monitors | |
| 13387 - enumeration of monitors | |
| 13388 - enumeration of threads waiting on a given monitor | |
| 13389 </pre> | |
| 13390 The reason for my question is the fact that current get_monitor_info support | |
| 13391 requires the agent to specify a given thread to get the info which is probably | |
| 13392 OK in the profiling/debugging space, while in the monitoring space the agent | |
| 13393 could be watching the monitor list and then decide which thread to ask for | |
| 13394 the info. You might ask why is this important for monitoring .... I think it | |
| 13395 can aid in the detection/prediction of application contention caused by hot-locks. | |
| 13396 </intro> | |
| 13397 </issuessection> | |
| 13398 | |
| 13399 <changehistory id="ChangeHistory" update="09/05/07"> | |
| 13400 <intro> | |
| 13401 The <jvmti/> specification is an evolving document with major, minor, | |
| 13402 and micro version numbers. | |
| 13403 A released version of the specification is uniquely identified | |
| 13404 by its major and minor version. | |
| 13405 The functions, events, and capabilities in this specification | |
| 13406 indicate a "Since" value which is the major and minor version in | |
| 13407 which it was introduced. | |
| 13408 The version of the specification implemented by the VM can | |
| 13409 be retrieved at runtime with the <functionlink id="GetVersionNumber"/> | |
| 13410 function. | |
| 13411 </intro> | |
| 13412 <change date="14 Nov 2002"> | |
| 13413 Converted to XML document. | |
| 13414 </change> | |
| 13415 <change date="14 Nov 2002"> | |
| 13416 Elided heap dump functions (for now) since what was there | |
| 13417 was wrong. | |
| 13418 </change> | |
| 13419 <change date="18 Nov 2002"> | |
| 13420 Added detail throughout. | |
| 13421 </change> | |
| 13422 <change date="18 Nov 2002"> | |
| 13423 Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE. | |
| 13424 </change> | |
| 13425 <change date="19 Nov 2002"> | |
| 13426 Added AsyncGetStackTrace. | |
| 13427 </change> | |
| 13428 <change date="19 Nov 2002"> | |
| 13429 Added jframeID return to GetStackTrace. | |
| 13430 </change> | |
| 13431 <change date="19 Nov 2002"> | |
| 13432 Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there | |
| 13433 since they are redundant with GetStackTrace. | |
| 13434 </change> | |
| 13435 <change date="19 Nov 2002"> | |
| 13436 Elided ClearAllBreakpoints since it has always been redundant. | |
| 13437 </change> | |
| 13438 <change date="19 Nov 2002"> | |
| 13439 Added GetSystemProperties. | |
| 13440 </change> | |
| 13441 <change date="19 Nov 2002"> | |
| 13442 Changed the thread local storage functions to use jthread. | |
| 13443 </change> | |
| 13444 <change date="20 Nov 2002"> | |
| 13445 Added GetJLocationFormat. | |
| 13446 </change> | |
| 13447 <change date="22 Nov 2002"> | |
| 13448 Added events and introductory text. | |
| 13449 </change> | |
| 13450 <change date="22 Nov 2002"> | |
| 13451 Cross reference type and constant definitions. | |
| 13452 </change> | |
| 13453 <change date="24 Nov 2002"> | |
| 13454 Added DTD. | |
| 13455 </change> | |
| 13456 <change date="24 Nov 2002"> | |
| 13457 Added capabilities function section. | |
| 13458 </change> | |
| 13459 <change date="29 Nov 2002"> | |
| 13460 Assign capabilities to each function and event. | |
| 13461 </change> | |
| 13462 <change date="29 Nov 2002"> | |
| 13463 Add <internallink id="jniIntercept">JNI interception functions</internallink>. | |
| 13464 </change> | |
| 13465 <change date="30 Nov 2002"> | |
| 13466 Auto generate SetEventNotificationMode capabilities. | |
| 13467 </change> | |
| 13468 <change date="30 Nov 2002"> | |
| 13469 Add <eventlink id="VMObjectAlloc"></eventlink> event. | |
| 13470 </change> | |
| 13471 <change date="30 Nov 2002"> | |
| 13472 Add <eventlink id="DynamicCodeGenerated"></eventlink> event. | |
| 13473 </change> | |
| 13474 <change date="30 Nov 2002"> | |
| 13475 Add const to declarations. | |
| 13476 </change> | |
| 13477 <change date="30 Nov 2002"> | |
| 13478 Change method exit and frame pop to send on exception. | |
| 13479 </change> | |
| 13480 <change date="1 Dec 2002"> | |
| 13481 Add ForceGarbageCollection. | |
| 13482 </change> | |
| 13483 <change date="2 Dec 2002"> | |
| 13484 Redo Xrun section; clarify GetStackTrace and add example; | |
| 13485 Fix width problems; use "agent" consistently. | |
| 13486 </change> | |
| 13487 <change date="8 Dec 2002"> | |
| 13488 Remove previous start-up intro. | |
| 13489 Add <internallink id="environments"><jvmti/> Environments</internallink> | |
| 13490 section. | |
| 13491 </change> | |
| 13492 <change date="8 Dec 2002"> | |
| 13493 Add <functionlink id="DisposeEnvironment"></functionlink>. | |
| 13494 </change> | |
| 13495 <change date="9 Dec 2002"> | |
| 13496 Numerous minor updates. | |
| 13497 </change> | |
| 13498 <change date="15 Dec 2002"> | |
| 13499 Add heap profiling functions added: | |
| 13500 get/set annotation, iterate live objects/heap. | |
| 13501 Add heap profiling functions place holder added: | |
| 13502 heap roots. | |
| 13503 Heap profiling event added: object free. | |
| 13504 Heap profiling event redesigned: vm object allocation. | |
| 13505 Heap profiling event placeholders added: garbage collection start/finish. | |
| 13506 Native method bind event added. | |
| 13507 </change> | |
| 13508 <change date="19 Dec 2002"> | |
| 13509 Revamp suspend/resume functions. | |
| 13510 Add origin information with jvmdi tag. | |
| 13511 Misc fixes. | |
| 13512 </change> | |
| 13513 <change date="24 Dec 2002"> | |
| 13514 Add semantics to types. | |
| 13515 </change> | |
| 13516 <change date="27 Dec 2002"> | |
| 13517 Add local reference section. | |
| 13518 Autogenerate parameter descriptions from types. | |
| 13519 </change> | |
| 13520 <change date="28 Dec 2002"> | |
| 13521 Document that RunAgentThread sends threadStart. | |
| 13522 </change> | |
| 13523 <change date="29 Dec 2002"> | |
| 13524 Remove redundant local ref and dealloc warning. | |
| 13525 Convert GetRawMonitorName to allocated buffer. | |
| 13526 Add GenerateEvents. | |
| 13527 </change> | |
| 13528 <change date="30 Dec 2002"> | |
| 13529 Make raw monitors a type and rename to "jrawMonitorID". | |
| 13530 </change> | |
| 13531 <change date="1 Jan 2003"> | |
| 13532 Include origin information. | |
| 13533 Clean-up JVMDI issue references. | |
| 13534 Remove Deallocate warnings which are now automatically generated. | |
| 13535 </change> | |
| 13536 <change date="2 Jan 2003"> | |
| 13537 Fix representation issues for jthread. | |
| 13538 </change> | |
| 13539 <change date="3 Jan 2003"> | |
| 13540 Make capabilities buffered out to 64 bits - and do it automatically. | |
| 13541 </change> | |
| 13542 <change date="4 Jan 2003"> | |
| 13543 Make constants which are enumeration into enum types. | |
| 13544 Parameters now of enum type. | |
| 13545 Clean-up and index type section. | |
| 13546 Replace remaining datadef entities with callback. | |
| 13547 </change> | |
| 13548 <change date="7 Jan 2003"> | |
| 13549 Correct GenerateEvents description. | |
| 13550 More internal semantics work. | |
| 13551 </change> | |
| 13552 <change date="9 Jan 2003"> | |
| 13553 Replace previous GetSystemProperties with two functions | |
| 13554 which use allocated information instead fixed. | |
| 13555 Add SetSystemProperty. | |
| 13556 More internal semantics work. | |
| 13557 </change> | |
| 13558 <change date="12 Jan 2003"> | |
| 13559 Add varargs to end of SetEventNotificationMode. | |
| 13560 </change> | |
| 13561 <change date="20 Jan 2003"> | |
| 13562 Finish fixing spec to reflect that alloc sizes are jlong. | |
| 13563 </change> | |
| 13564 <change date="22 Jan 2003"> | |
| 13565 Allow NULL as RunAgentThread arg. | |
| 13566 </change> | |
| 13567 <change date="22 Jan 2003"> | |
| 13568 Fixed names to standardized naming convention | |
| 13569 Removed AsyncGetStackTrace. | |
| 13570 </change> | |
| 13571 <change date="29 Jan 2003"> | |
| 13572 Since we are using jthread, removed GetThread. | |
| 13573 </change> | |
| 13574 <change date="31 Jan 2003"> | |
| 13575 Change GetFieldName to allow NULLs like GetMethodName. | |
| 13576 </change> | |
| 13577 <change date="29 Feb 2003" version="v40"> | |
| 13578 Rewrite the introductory text, adding sections on | |
| 13579 start-up, environments and bytecode instrumentation. | |
| 13580 Change the command line arguments per EG discussions. | |
| 13581 Add an introduction to the capabilities section. | |
| 13582 Add the extension mechanism category and functions. | |
| 13583 Mark for deletion, but clarified anyhow, SuspendAllThreads. | |
| 13584 Rename IterateOverLiveObjects to IterateOverReachableObjects and | |
| 13585 change the text accordingly. | |
| 13586 Clarify IterateOverHeap. | |
| 13587 Clarify CompiledMethodLoad. | |
| 13588 Discuss prerequisite state for Calling Functions. | |
| 13589 Clarify SetAllocationHooks. | |
| 13590 Added issues ("To be resolved:") through-out. | |
| 13591 And so on... | |
| 13592 </change> | |
| 13593 <change date="6 Mar 2003" version="v41"> | |
| 13594 Remove struct from the call to GetOwnedMonitorInfo. | |
| 13595 Automatically generate most error documentation, remove | |
| 13596 (rather broken) hand written error doc. | |
| 13597 Better describe capability use (empty initial set). | |
| 13598 Add min value to jint params. | |
| 13599 Remove the capability can_access_thread_local_storage. | |
| 13600 Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY; | |
| 13601 same for *NOT_IMPLEMENTED. | |
| 13602 Description fixes. | |
| 13603 </change> | |
| 13604 <change date="8 Mar 2003" version="v42"> | |
| 13605 Rename GetClassSignature to GetClassName. | |
| 13606 Rename IterateOverClassObjects to IterateOverInstancesOfClass. | |
| 13607 Remove GetMaxStack (operand stack isn't used in <jvmti/>). | |
| 13608 Description fixes: define launch-time, remove native frame pop | |
| 13609 from PopFrame, and assorted clarifications. | |
| 13610 </change> | |
| 13611 <change date="8 Mar 2003" version="v43"> | |
| 13612 Fix minor editing problem. | |
| 13613 </change> | |
| 13614 <change date="10 Mar 2003" version="v44"> | |
| 13615 Add phase information. | |
| 13616 Remap (compact) event numbers. | |
| 13617 </change> | |
| 13618 <change date="11 Mar 2003" version="v45"> | |
| 13619 More phase information - allow "any". | |
| 13620 Elide raw monitor queries and events. | |
| 13621 Minor description fixes. | |
| 13622 </change> | |
| 13623 <change date="12 Mar 2003" version="v46"> | |
| 13624 Add GetPhase. | |
| 13625 Use "phase" through document. | |
| 13626 Elide GetRawMonitorName. | |
| 13627 Elide GetObjectMonitors. | |
| 13628 </change> | |
| 13629 <change date="12 Mar 2003" version="v47"> | |
| 13630 Fixes from link, XML, and spell checking. | |
| 13631 Auto-generate the callback structure. | |
| 13632 </change> | |
| 13633 <change date="13 Mar 2003" version="v48"> | |
| 13634 One character XML fix. | |
| 13635 </change> | |
| 13636 <change date="13 Mar 2003" version="v49"> | |
| 13637 Change function parameter names to be consistent with | |
| 13638 event parameters (fooBarBaz becomes foo_bar_baz). | |
| 13639 </change> | |
| 13640 <change date="14 Mar 2003" version="v50"> | |
| 13641 Fix broken link. Fix thread markers. | |
| 13642 </change> | |
| 13643 <change date="14 Mar 2003" version="v51"> | |
| 13644 Change constants so they are under 128 to workaround | |
| 13645 compiler problems. | |
| 13646 </change> | |
| 13647 <change date="23 Mar 2003" version="v52"> | |
| 13648 Overhaul capabilities. Separate GetStackTrace into | |
| 13649 GetStackTrace and GetStackFrames. | |
| 13650 </change> | |
| 13651 <change date="8 Apr 2003" version="v54"> | |
| 13652 Use depth instead of jframeID to reference frames. | |
| 13653 Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames. | |
| 13654 Remove frame arg from events. | |
| 13655 </change> | |
| 13656 <change date="9 Apr 2003" version="v55"> | |
| 13657 Remove GetObjectWithAnnotation since tests show bufferred approach more efficient. | |
| 13658 Add missing annotation_count to GetObjectsWithAnnotations | |
| 13659 </change> | |
| 13660 <change date="10 Apr 2003" version="v56"> | |
| 13661 Remove confusing parenthetical statement in GetObjectsWithAnnotations | |
| 13662 </change> | |
| 13663 <change date="13 Apr 2003" version="v58"> | |
| 13664 Replace jclass/jmethodID representation of method with simply jmethodID; | |
| 13665 Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate. | |
| 13666 Replace can_access_frames with can_access_local_variables; remove from purely stack access. | |
| 13667 Use can_get_synthetic_attribute; fix description. | |
| 13668 Clarify that zero length arrays must be deallocated. | |
| 13669 Clarify RelinquishCapabilities. | |
| 13670 Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE. | |
| 13671 </change> | |
| 13672 <change date="27 Apr 2003" version="v59"> | |
| 13673 Remove lingering indirect references to OBSOLETE_METHOD_ID. | |
| 13674 </change> | |
| 13675 <change date="4 May 2003" version="v60"> | |
| 13676 Allow DestroyRawMonitor during OnLoad. | |
| 13677 </change> | |
| 13678 <change date="7 May 2003" version="v61"> | |
| 13679 Added not monitor owner error return to DestroyRawMonitor. | |
| 13680 </change> | |
| 13681 <change date="13 May 2003" version="v62"> | |
| 13682 Clarify semantics of raw monitors. | |
| 13683 Change flags on <code>GetThreadStatus</code>. | |
| 13684 <code>GetClassLoader</code> return NULL for the bootstrap class loader. | |
| 13685 Add <code>GetClassName</code> issue. | |
| 13686 Define local variable signature. | |
| 13687 Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>. | |
| 13688 Remove over specification in <code>GetObjectsWithAnnotations</code>. | |
| 13689 Elide <code>SetAllocationHooks</code>. | |
| 13690 Elide <code>SuspendAllThreads</code>. | |
| 13691 </change> | |
| 13692 <change date="14 May 2003" version="v63"> | |
| 13693 Define the data type <code>jvmtiEventCallbacks</code>. | |
| 13694 Zero length allocations return NULL. | |
| 13695 Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>. | |
| 13696 Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED. | |
| 13697 </change> | |
| 13698 <change date="15 May 2003" version="v64"> | |
| 13699 Better wording, per review. | |
| 13700 </change> | |
| 13701 <change date="15 May 2003" version="v65"> | |
| 13702 First Alpha. | |
| 13703 Make jmethodID and jfieldID unique, jclass not used. | |
| 13704 </change> | |
| 13705 <change date="27 May 2003" version="v66"> | |
| 13706 Fix minor XSLT errors. | |
| 13707 </change> | |
| 13708 <change date="13 June 2003" version="v67"> | |
| 13709 Undo making jfieldID unique (jmethodID still is). | |
| 13710 </change> | |
| 13711 <change date="17 June 2003" version="v68"> | |
| 13712 Changes per June 11th Expert Group meeting -- | |
| 13713 Overhaul Heap functionality: single callback, | |
| 13714 remove GetHeapRoots, add reachable iterators, | |
| 13715 and rename "annotation" to "tag". | |
| 13716 NULL thread parameter on most functions is current | |
| 13717 thread. | |
| 13718 Add timers. | |
| 13719 Remove ForceExit. | |
| 13720 Add GetEnvironmentLocalStorage. | |
| 13721 Add verbose flag and event. | |
| 13722 Add AddToBootstrapClassLoaderSearch. | |
| 13723 Update ClassFileLoadHook. | |
| 13724 </change> | |
| 13725 <change date="18 June 2003" version="v69"> | |
| 13726 Clean up issues sections. | |
| 13727 Rename GetClassName back to GetClassSignature and | |
| 13728 fix description. | |
| 13729 Add generic signature to GetClassSignature, | |
| 13730 GetFieldSignature, GetMethodSignature, and | |
| 13731 GetLocalVariableTable. | |
| 13732 Elide EstimateCostOfCapabilities. | |
| 13733 Clarify that the system property functions operate | |
| 13734 on the VM view of system properties. | |
| 13735 Clarify Agent_OnLoad. | |
| 13736 Remove "const" from JNIEnv* in events. | |
| 13737 Add metadata accessors. | |
| 13738 </change> | |
| 13739 <change date="18 June 2003" version="v70"> | |
| 13740 Add start_depth to GetStackTrace. | |
| 13741 Move system properties to a new category. | |
| 13742 Add GetObjectSize. | |
| 13743 Remove "X" from command line flags. | |
| 13744 XML, HTML, and spell check corrections. | |
| 13745 </change> | |
| 13746 <change date="19 June 2003" version="v71"> | |
| 13747 Fix JVMTI_HEAP_ROOT_THREAD to be 6. | |
| 13748 Make each synopsis match the function name. | |
| 13749 Fix unclear wording. | |
| 13750 </change> | |
| 13751 <change date="26 June 2003" version="v72"> | |
| 13752 SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value | |
| 13753 to be set to NULL. | |
| 13754 NotifyFramePop, GetFrameLocationm and all the local variable operations | |
| 13755 needed to have their wording about frames fixed. | |
| 13756 Grammar and clarity need to be fixed throughout. | |
| 13757 Capitalization and puntuation need to be consistent. | |
| 13758 Need micro version number and masks for accessing major, minor, and micro. | |
| 13759 The error code lists should indicate which must be returned by | |
| 13760 an implementation. | |
| 13761 The command line properties should be visible in the properties functions. | |
| 13762 Disallow popping from the current thread. | |
| 13763 Allow implementations to return opaque frame error when they cannot pop. | |
| 13764 The NativeMethodBind event should be sent during any phase. | |
| 13765 The DynamicCodeGenerated event should be sent during any phase. | |
| 13766 The following functions should be allowed to operate before VMInit: | |
| 13767 Set/GetEnvironmentLocalStorage | |
| 13768 GetMethodDeclaringClass | |
| 13769 GetClassSignature | |
| 13770 GetClassModifiers | |
| 13771 IsInterface | |
| 13772 IsArrayClass | |
| 13773 GetMethodName | |
| 13774 GetMethodModifiers | |
| 13775 GetMaxLocals | |
| 13776 GetArgumentsSize | |
| 13777 GetLineNumberTable | |
| 13778 GetMethodLocation | |
| 13779 IsMethodNative | |
| 13780 IsMethodSynthetic. | |
| 13781 Other changes (to XSL): | |
| 13782 Argument description should show asterisk after not before pointers. | |
| 13783 NotifyFramePop, GetFrameLocationm and all the local variable operations | |
| 13784 should hsve the NO_MORE_FRAMES error added. | |
| 13785 Not alive threads should have a different error return than invalid thread. | |
| 13786 </change> | |
| 13787 <change date="7 July 2003" version="v73"> | |
| 13788 VerboseOutput event was missing message parameter. | |
| 13789 Minor fix-ups. | |
| 13790 </change> | |
| 13791 <change date="14 July 2003" version="v74"> | |
| 13792 Technical Publications Department corrections. | |
| 13793 Allow thread and environment local storage to be set to NULL. | |
| 13794 </change> | |
| 13795 <change date="23 July 2003" version="v75"> | |
| 13796 Use new Agent_OnLoad rather than overloaded JVM_OnLoad. | |
| 13797 Add JNICALL to callbacks (XSL). | |
| 13798 Document JNICALL requirement for both events and callbacks (XSL). | |
| 13799 Restrict RedefineClasses to methods and attributes. | |
| 13800 Elide the VerboseOutput event. | |
| 13801 VMObjectAlloc: restrict when event is sent and remove method parameter. | |
| 13802 Finish loose ends from Tech Pubs edit. | |
| 13803 </change> | |
| 13804 <change date="24 July 2003" version="v76"> | |
| 13805 Change ClassFileLoadHook event to send the class instead of a boolean of redefine. | |
| 13806 </change> | |
| 13807 <change date="24 July 2003" version="v77"> | |
| 13808 XML fixes. | |
| 13809 Minor text clarifications and corrections. | |
| 13810 </change> | |
| 13811 <change date="24 July 2003" version="v78"> | |
| 13812 Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>. | |
| 13813 Clarify that stack frames are JVM Spec frames. | |
| 13814 Split can_get_source_info into can_get_source_file_name, can_get_line_numbers, | |
| 13815 and can_get_source_debug_extension. | |
| 13816 PopFrame cannot have a native calling method. | |
| 13817 Removed incorrect statement in GetClassloaderClasses | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
13818 (see <vmspec chapter="4.4"/>). |
| 0 | 13819 </change> |
| 13820 <change date="24 July 2003" version="v79"> | |
| 13821 XML and text fixes. | |
| 13822 Move stack frame description into Stack Frame category. | |
| 13823 </change> | |
| 13824 <change date="26 July 2003" version="v80"> | |
| 13825 Allow NULL (means bootstrap loader) for GetClassloaderClasses. | |
| 13826 Add new heap reference kinds for references from classes. | |
| 13827 Add timer information struct and query functions. | |
| 13828 Add AvailableProcessors. | |
| 13829 Rename GetOtherThreadCpuTime to GetThreadCpuTime. | |
| 13830 Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE | |
| 13831 to SetEventNotification mode. | |
| 13832 Add initial thread to the VM_INIT event. | |
| 13833 Remove platform assumptions from AddToBootstrapClassLoaderSearch. | |
| 13834 </change> | |
| 13835 <change date="26 July 2003" version="v81"> | |
| 13836 Grammar and clarity changes per review. | |
| 13837 </change> | |
| 13838 <change date="27 July 2003" version="v82"> | |
| 13839 More grammar and clarity changes per review. | |
| 13840 Add Agent_OnUnload. | |
| 13841 </change> | |
| 13842 <change date="28 July 2003" version="v83"> | |
| 13843 Change return type of Agent_OnUnload to void. | |
| 13844 </change> | |
| 13845 <change date="28 July 2003" version="v84"> | |
| 13846 Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT. | |
| 13847 </change> | |
| 13848 <change date="28 July 2003" version="v85"> | |
| 13849 Steal java.lang.Runtime.availableProcessors() wording for | |
| 13850 AvailableProcessors(). | |
| 13851 Guarantee that zero will never be an event ID. | |
| 13852 Remove some issues which are no longer issues. | |
| 13853 Per review, rename and more completely document the timer | |
| 13854 information functions. | |
| 13855 </change> | |
| 13856 <change date="29 July 2003" version="v86"> | |
| 13857 Non-spec visible change to XML controlled implementation: | |
| 13858 SetThreadLocalStorage must run in VM mode. | |
| 13859 </change> | |
| 13860 <change date="5 August 2003" version="0.1.87"> | |
| 13861 Add GetErrorName. | |
| 13862 Add varargs warning to jvmtiExtensionEvent. | |
| 13863 Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent. | |
| 13864 Remove unused can_get_exception_info capability. | |
| 13865 Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction. | |
| 13866 Fix jvmtiExtensionFunctionInfo.func declared type. | |
| 13867 Extension function returns error code. | |
| 13868 Use new version numbering. | |
| 13869 </change> | |
| 13870 <change date="5 August 2003" version="0.2.88"> | |
| 13871 Remove the ClassUnload event. | |
| 13872 </change> | |
| 13873 <change date="8 August 2003" version="0.2.89"> | |
| 13874 Heap reference iterator callbacks return an enum that | |
| 13875 allows outgoing object references to be ignored. | |
| 13876 Allow JNIEnv as a param type to extension events/functions. | |
| 13877 </change> | |
| 13878 <change date="15 August 2003" version="0.2.90"> | |
| 13879 Fix a typo. | |
| 13880 </change> | |
| 13881 <change date="2 September 2003" version="0.2.91"> | |
| 13882 Remove all metadata functions: GetClassMetadata, | |
| 13883 GetFieldMetadata, and GetMethodMetadata. | |
| 13884 </change> | |
| 13885 <change date="1 October 2003" version="0.2.92"> | |
| 13886 Mark the functions Allocate. Deallocate, RawMonitor*, | |
| 13887 SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage | |
| 13888 as safe for use in heap callbacks and GC events. | |
| 13889 </change> | |
| 13890 <change date="24 November 2003" version="0.2.93"> | |
| 13891 Add pass through opaque user data pointer to heap iterate | |
| 13892 functions and callbacks. | |
| 13893 In the CompiledMethodUnload event, send the code address. | |
| 13894 Add GarbageCollectionOccurred event. | |
| 13895 Add constant pool reference kind. | |
| 13896 Mark the functions CreateRawMonitor and DestroyRawMonitor | |
| 13897 as safe for use in heap callbacks and GC events. | |
| 13898 Clarify: VMDeath, GetCurrentThreadCpuTimerInfo, | |
| 13899 GetThreadCpuTimerInfo, IterateOverReachableObjects, | |
| 13900 IterateOverObjectsReachableFromObject, GetTime and | |
| 13901 JVMTI_ERROR_NULL_POINTER. | |
| 13902 Add missing errors to: GenerateEvents and | |
| 13903 AddToBootstrapClassLoaderSearch. | |
| 13904 Fix description of ClassFileLoadHook name parameter. | |
| 13905 In heap callbacks and GC/ObjectFree events, specify | |
| 13906 that only explicitly allowed functions can be called. | |
| 13907 Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime, | |
| 13908 GetTimerInfo, and GetTime during callback. | |
| 13909 Allow calling SetTag/GetTag during the onload phase. | |
| 13910 SetEventNotificationMode, add: error attempted inappropriate | |
| 13911 thread level control. | |
| 13912 Remove jvmtiExceptionHandlerEntry. | |
| 13913 Fix handling of native methods on the stack -- | |
| 13914 location_ptr param of GetFrameLocation, remove | |
| 13915 JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation, | |
| 13916 jvmtiFrameInfo.location, and jlocation. | |
| 13917 Remove typo (from JVMPI) implying that the MonitorWaited | |
| 13918 event is sent on sleep. | |
| 13919 </change> | |
| 13920 <change date="25 November 2003" version="0.2.94"> | |
| 13921 Clarifications and typos. | |
| 13922 </change> | |
| 13923 <change date="3 December 2003" version="0.2.95"> | |
| 13924 Allow NULL user_data in heap iterators. | |
| 13925 </change> | |
| 13926 <change date="28 January 2004" version="0.2.97"> | |
| 13927 Add GetThreadState, deprecate GetThreadStatus. | |
| 13928 </change> | |
| 13929 <change date="29 January 2004" version="0.2.98"> | |
| 13930 INVALID_SLOT and TYPE_MISMATCH errors should be optional. | |
| 13931 </change> | |
| 13932 <change date="12 February 2004" version="0.2.102"> | |
| 13933 Remove MonitorContendedExit. | |
| 13934 Added JNIEnv parameter to VMObjectAlloc. | |
| 13935 Clarified definition of class_tag and referrer_index | |
| 13936 parameters to heap callbacks. | |
| 13937 </change> | |
| 13938 <change date="16 Febuary 2004" version="0.2.103"> | |
| 13939 Document JAVA_TOOL_OPTIONS. | |
| 13940 </change> | |
| 13941 <change date="17 Febuary 2004" version="0.2.105"> | |
| 13942 Divide start phase into primordial and start. | |
| 13943 Add VMStart event | |
| 13944 Change phase associations of functions and events. | |
| 13945 </change> | |
| 13946 <change date="18 Febuary 2004" version="0.3.6"> | |
| 13947 Elide deprecated GetThreadStatus. | |
| 13948 Bump minor version, subtract 100 from micro version | |
| 13949 </change> | |
| 13950 <change date="18 Febuary 2004" version="0.3.7"> | |
| 13951 Document that timer nanosecond values are unsigned. | |
| 13952 Clarify text having to do with native methods. | |
| 13953 </change> | |
| 13954 <change date="19 Febuary 2004" version="0.3.8"> | |
| 13955 Fix typos. | |
| 13956 Remove elided deprecated GetThreadStatus. | |
| 13957 </change> | |
| 13958 <change date="23 Febuary 2004" version="0.3.9"> | |
| 13959 Require NotifyFramePop to act on suspended threads. | |
| 13960 </change> | |
| 13961 <change date="24 Febuary 2004" version="0.3.10"> | |
| 13962 Add capabilities | |
| 13963 (<internallink id="jvmtiCapabilities.can_redefine_any_class" | |
| 13964 ><code>can_redefine_any_class</code></internallink> | |
| 13965 and | |
| 13966 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events" | |
| 13967 ><code>can_generate_all_class_hook_events</code></internallink>) | |
| 13968 and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>) | |
| 13969 which allow some classes to be unmodifiable. | |
| 13970 </change> | |
| 13971 <change date="28 Febuary 2004" version="0.3.11"> | |
| 13972 Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode. | |
| 13973 </change> | |
| 13974 <change date="8 March 2004" version="0.3.12"> | |
| 13975 Clarified CompiledMethodUnload so that it is clear the event | |
| 13976 may be posted after the class has been unloaded. | |
| 13977 </change> | |
| 13978 <change date="5 March 2004" version="0.3.13"> | |
| 13979 Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize. | |
| 13980 </change> | |
| 13981 <change date="13 March 2004" version="0.3.14"> | |
| 13982 Added guideline for the use of the JNI FindClass function in event | |
| 13983 callback functions. | |
| 13984 </change> | |
| 13985 <change date="15 March 2004" version="0.3.15"> | |
| 13986 Add GetAllStackTraces and GetThreadListStackTraces. | |
| 13987 </change> | |
| 13988 <change date="19 March 2004" version="0.3.16"> | |
| 13989 ClassLoad and ClassPrepare events can be posted during start phase. | |
| 13990 </change> | |
| 13991 <change date="25 March 2004" version="0.3.17"> | |
| 13992 Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable, | |
| 13993 GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes. | |
| 13994 </change> | |
| 13995 <change date="29 March 2004" version="0.3.18"> | |
| 13996 Return the timer kind in the timer information structure. | |
| 13997 </change> | |
| 13998 <change date="31 March 2004" version="0.3.19"> | |
| 13999 Spec clarifications: | |
| 14000 JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>. | |
| 14001 ForceGarbageCollection does not run finalizers. | |
| 14002 The context of the specification is the Java platform. | |
| 14003 Warn about early instrumentation. | |
| 14004 </change> | |
| 14005 <change date="1 April 2004" version="0.3.20"> | |
| 14006 Refinements to the above clarifications and | |
| 14007 Clarify that an error returned by Agent_OnLoad terminates the VM. | |
| 14008 </change> | |
| 14009 <change date="1 April 2004" version="0.3.21"> | |
| 14010 Array class creation does not generate a class load event. | |
| 14011 </change> | |
| 14012 <change date="7 April 2004" version="0.3.22"> | |
| 14013 Align thread state hierarchy more closely with java.lang.Thread.State. | |
| 14014 </change> | |
| 14015 <change date="12 April 2004" version="0.3.23"> | |
| 14016 Clarify the documentation of thread state. | |
| 14017 </change> | |
| 14018 <change date="19 April 2004" version="0.3.24"> | |
| 14019 Remove GarbageCollectionOccurred event -- can be done by agent. | |
| 14020 </change> | |
| 14021 <change date="22 April 2004" version="0.3.25"> | |
| 14022 Define "command-line option". | |
| 14023 </change> | |
| 14024 <change date="29 April 2004" version="0.3.26"> | |
| 14025 Describe the intended use of bytecode instrumentation. | |
| 14026 Fix description of extension event first parameter. | |
| 14027 </change> | |
| 14028 <change date="30 April 2004" version="0.3.27"> | |
| 14029 Clarification and typos. | |
| 14030 </change> | |
| 14031 <change date="18 May 2004" version="0.3.28"> | |
| 14032 Remove DataDumpRequest event. | |
| 14033 </change> | |
| 14034 <change date="18 May 2004" version="0.3.29"> | |
| 14035 Clarify RawMonitorWait with zero timeout. | |
| 14036 Clarify thread state after RunAgentThread. | |
| 14037 </change> | |
| 14038 <change date="24 May 2004" version="0.3.30"> | |
| 14039 Clean-up: fix bad/old links, etc. | |
| 14040 </change> | |
| 14041 <change date="30 May 2004" version="0.3.31"> | |
| 14042 Clarifications including: | |
| 14043 All character strings are modified UTF-8. | |
| 14044 Agent thread visibiity. | |
| 14045 Meaning of obsolete method version. | |
| 14046 Thread invoking heap callbacks, | |
| 14047 </change> | |
| 14048 <change date="1 June 2004" version="1.0.32"> | |
| 14049 Bump major.minor version numbers to "1.0". | |
| 14050 </change> | |
| 14051 <change date="2 June 2004" version="1.0.33"> | |
| 14052 Clarify interaction between ForceGarbageCollection | |
| 14053 and ObjectFree. | |
| 14054 </change> | |
| 14055 <change date="6 June 2004" version="1.0.34"> | |
| 14056 Restrict AddToBootstrapClassLoaderSearch and | |
| 14057 SetSystemProperty to the OnLoad phase only. | |
| 14058 </change> | |
| 14059 <change date="11 June 2004" version="1.0.35"> | |
| 14060 Fix typo in SetTag. | |
| 14061 </change> | |
| 14062 <change date="18 June 2004" version="1.0.36"> | |
| 14063 Fix trademarks. | |
| 14064 Add missing parameter in example GetThreadState usage. | |
| 14065 </change> | |
| 14066 <change date="4 August 2004" version="1.0.37"> | |
| 14067 Copyright updates. | |
| 14068 </change> | |
| 14069 <change date="5 November 2004" version="1.0.38"> | |
| 14070 Add missing function table layout. | |
| 14071 Add missing description of C++ member function format of functions. | |
| 14072 Clarify that name in CFLH can be NULL. | |
| 14073 Released as part of <tm>J2SE</tm> 5.0. | |
| 14074 </change> | |
| 14075 <change date="24 April 2005" version="1.1.47"> | |
| 14076 Bump major.minor version numbers to "1.1". | |
| 14077 Add ForceEarlyReturn* functions. | |
| 14078 Add GetOwnedMonitorStackDepthInfo function. | |
| 14079 Add GetCurrentThread function. | |
| 14080 Add "since" version marker. | |
| 14081 Add AddToSystemClassLoaderSearch. | |
| 14082 Allow AddToBootstrapClassLoaderSearch be used in live phase. | |
| 14083 Fix historic rubbish in the descriptions of the heap_object_callback | |
| 14084 parameter of IterateOverHeap and IterateOverInstancesOfClass functions; | |
| 14085 disallow NULL for this parameter. | |
| 14086 Clarify, correct and make consistent: wording about current thread, | |
| 14087 opaque frames and insufficient number of frames in PopFrame. | |
| 14088 Consistently use "current frame" rather than "topmost". | |
| 14089 Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal* | |
| 14090 by making them compatible with those in ForceEarlyReturn*. | |
| 14091 Many other clarifications and wording clean ups. | |
| 14092 </change> | |
| 14093 <change date="25 April 2005" version="1.1.48"> | |
| 14094 Add GetConstantPool. | |
| 14095 Switch references to the first edition of the VM Spec, to the seconds edition. | |
| 14096 </change> | |
| 14097 <change date="26 April 2005" version="1.1.49"> | |
| 14098 Clarify minor/major version order in GetConstantPool. | |
| 14099 </change> | |
| 14100 <change date="26 April 2005" version="1.1.50"> | |
| 14101 Add SetNativeMethodPrefix and SetNativeMethodPrefixes. | |
| 14102 Reassign GetOwnedMonitorStackDepthInfo to position 153. | |
| 14103 Break out Class Loader Search in its own documentation category. | |
| 14104 Deal with overly long lines in XML source. | |
| 14105 </change> | |
| 14106 <change date="29 April 2005" version="1.1.51"> | |
| 14107 Allow agents be started in the live phase. | |
| 14108 Added paragraph about deploying agents. | |
| 14109 </change> | |
| 14110 <change date="30 April 2005" version="1.1.52"> | |
| 14111 Add specification description to SetNativeMethodPrefix(es). | |
| 14112 Better define the conditions on GetConstantPool. | |
| 14113 </change> | |
| 14114 <change date="30 April 2005" version="1.1.53"> | |
| 14115 Break out the GetClassVersionNumber function from GetConstantPool. | |
| 14116 Clean-up the references to the VM Spec. | |
| 14117 </change> | |
| 14118 <change date="1 May 2005" version="1.1.54"> | |
| 14119 Allow SetNativeMethodPrefix(es) in any phase. | |
| 14120 Add clarifications about the impact of redefinition on GetConstantPool. | |
| 14121 </change> | |
| 14122 <change date="2 May 2005" version="1.1.56"> | |
| 14123 Various clarifications to SetNativeMethodPrefix(es). | |
| 14124 </change> | |
| 14125 <change date="2 May 2005" version="1.1.57"> | |
| 14126 Add missing performance warning to the method entry event. | |
| 14127 </change> | |
| 14128 <change date="5 May 2005" version="1.1.58"> | |
| 14129 Remove internal JVMDI support. | |
| 14130 </change> | |
| 14131 <change date="8 May 2005" version="1.1.59"> | |
| 14132 Add <functionlink id="RetransformClasses"/>. | |
| 14133 Revamp the bytecode instrumentation documentation. | |
| 14134 Change <functionlink id="IsMethodObsolete"/> to no longer | |
| 14135 require the can_redefine_classes capability. | |
| 14136 </change> | |
| 14137 <change date="11 May 2005" version="1.1.63"> | |
| 14138 Clarifications for retransformation. | |
| 14139 </change> | |
| 14140 <change date="11 May 2005" version="1.1.64"> | |
| 14141 Clarifications for retransformation, per review. | |
| 14142 Lock "retransformation (in)capable" at class load enable time. | |
| 14143 </change> | |
| 14144 <change date="4 June 2005" version="1.1.67"> | |
| 14145 Add new heap functionity which supports reporting primitive values, | |
| 14146 allows setting the referrer tag, and has more powerful filtering: | |
| 14147 FollowReferences, IterateThroughHeap, and their associated | |
| 14148 callbacks, structs, enums, and constants. | |
| 14149 </change> | |
| 14150 <change date="4 June 2005" version="1.1.68"> | |
| 14151 Clarification. | |
| 14152 </change> | |
| 14153 <change date="6 June 2005" version="1.1.69"> | |
| 14154 FollowReferences, IterateThroughHeap: Put callbacks in a struct; | |
| 14155 Add missing error codes; reduce bits in the visit control flags. | |
| 14156 </change> | |
| 14157 <change date="14 June 2005" version="1.1.70"> | |
| 14158 More on new heap functionity: spec clean-up per review. | |
| 14159 </change> | |
| 14160 <change date="15 June 2005" version="1.1.71"> | |
| 14161 More on new heap functionity: Rename old heap section to Heap (1.0). | |
| 14162 </change> | |
| 14163 <change date="21 June 2005" version="1.1.72"> | |
| 14164 Fix typos. | |
| 14165 </change> | |
| 14166 <change date="27 June 2005" version="1.1.73"> | |
| 14167 Make referrer info structure a union. | |
| 14168 </change> | |
| 14169 <change date="9 September 2005" version="1.1.74"> | |
| 14170 In new heap functions: | |
| 14171 Add missing superclass reference kind. | |
| 14172 Use a single scheme for computing field indexes. | |
| 14173 Remove outdated references to struct based referrer info. | |
| 14174 </change> | |
| 14175 <change date="12 September 2005" version="1.1.75"> | |
| 14176 Don't callback during FollowReferences on frivolous java.lang.Object superclass. | |
| 14177 </change> | |
| 14178 <change date="13 September 2005" version="1.1.76"> | |
| 14179 In string primitive callback, length now Unicode length. | |
| 14180 In array and string primitive callbacks, value now "const". | |
| 14181 Note possible compiler impacts on setting JNI function table. | |
| 14182 </change> | |
| 14183 <change date="13 September 2005" version="1.1.77"> | |
| 14184 GetClassVersionNumbers() and GetConstantPool() should return | |
| 14185 error on array or primitive class. | |
| 14186 </change> | |
| 14187 <change date="14 September 2005" version="1.1.78"> | |
| 14188 Grammar fixes. | |
| 14189 </change> | |
| 14190 <change date="26 September 2005" version="1.1.79"> | |
| 14191 Add IsModifiableClass query. | |
| 14192 </change> | |
| 14193 <change date="9 February 2006" version="1.1.81"> | |
| 14194 Add referrer_class_tag parameter to jvmtiHeapReferenceCallback. | |
| 14195 </change> | |
| 14196 <change date="13 February 2006" version="1.1.82"> | |
| 14197 Doc fixes: update can_redefine_any_class to include retransform. | |
| 14198 Clarify that exception events cover all Throwables. | |
| 14199 In GetStackTrace, no test is done for start_depth too big if start_depth is zero, | |
| 14200 Clarify fields reported in Primitive Field Callback -- static vs instance. | |
| 14201 Repair confusing names of heap types, including callback names. | |
| 14202 Require consistent usage of stack depth in the face of thread launch methods. | |
| 14203 Note incompatibility of <jvmti/> memory management with other systems. | |
| 14204 </change> | |
| 14205 <change date="14 February 2006" version="1.1.85"> | |
| 14206 Fix typos and missing renames. | |
| 14207 </change> | |
| 14208 <change date="13 March 2006" version="1.1.86"> | |
| 14209 Clarify that jmethodIDs and jfieldIDs can be saved. | |
| 14210 Clarify that Iterate Over Instances Of Class includes subclasses. | |
| 14211 </change> | |
| 14212 <change date="14 March 2006" version="1.1.87"> | |
| 14213 Better phrasing. | |
| 14214 </change> | |
| 14215 <change date="16 March 2006" version="1.1.88"> | |
| 14216 Match the referrer_index for static fields in Object Reference Callback | |
| 14217 with the Reference Implementation (and all other known implementations); | |
| 14218 that is, make it match the definition for instance fields. | |
| 14219 In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover | |
| 14220 an invalid thread in the list; and specify that not started threads | |
| 14221 return empty stacks. | |
| 14222 </change> | |
| 14223 <change date="17 March 2006" version="1.1.89"> | |
| 14224 Typo. | |
| 14225 </change> | |
| 14226 <change date="25 March 2006" version="1.1.90"> | |
| 14227 Typo. | |
| 14228 </change> | |
| 14229 <change date="6 April 2006" version="1.1.91"> | |
| 14230 Remove restrictions on AddToBootstrapClassLoaderSearch and | |
| 14231 AddToSystemClassLoaderSearch. | |
| 14232 </change> | |
| 14233 <change date="1 May 2006" version="1.1.93"> | |
| 14234 Changed spec to return -1 for monitor stack depth for the | |
| 14235 implementation which can not determine stack depth. | |
| 14236 </change> | |
| 14237 <change date="3 May 2006" version="1.1.94"> | |
| 14238 Corrections for readability and accuracy courtesy of Alan Pratt of IBM. | |
| 14239 List the object relationships reported in FollowReferences. | |
| 14240 </change> | |
| 14241 <change date="5 May 2006" version="1.1.95"> | |
| 14242 Clarify the object relationships reported in FollowReferences. | |
| 14243 </change> | |
| 14244 <change date="28 June 2006" version="1.1.98"> | |
| 14245 Clarify DisposeEnvironment; add warning. | |
| 14246 Fix typos in SetLocalXXX "retrieve" => "set". | |
| 14247 Clarify that native method prefixes must remain set while used. | |
| 14248 Clarify that exactly one Agent_OnXXX is called per agent. | |
| 14249 Clarify that library loading is independent from start-up. | |
| 14250 Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec. | |
| 14251 </change> | |
| 14252 <change date="31 July 2006" version="1.1.99"> | |
| 14253 Clarify the interaction between functions and exceptions. | |
| 14254 Clarify and give examples of field indices. | |
| 14255 Remove confusing "That is" sentence from MonitorWait and MonitorWaited events. | |
| 14256 Update links to point to Java 6. | |
| 14257 </change> | |
| 14258 <change date="6 August 2006" version="1.1.102"> | |
| 14259 Add ResourceExhaustedEvent. | |
| 14260 </change> | |
| 6919 | 14261 <change date="11 October 2012" version="1.2.2"> |
| 14262 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool. | |
| 14263 </change> | |
| 0 | 14264 </changehistory> |
| 14265 | |
| 14266 </specification> | |
| 14267 <!-- Keep this comment at the end of the file | |
| 14268 Local variables: | |
| 14269 mode: sgml | |
| 14270 sgml-omittag:t | |
| 14271 sgml-shorttag:t | |
| 14272 sgml-namecase-general:t | |
| 14273 sgml-general-insert-case:lower | |
| 14274 sgml-minimize-attributes:nil | |
| 14275 sgml-always-quote-attributes:t | |
| 14276 sgml-indent-step:2 | |
| 14277 sgml-indent-data:t | |
| 14278 sgml-parent-document:nil | |
| 14279 sgml-exposed-tags:nil | |
| 14280 sgml-local-catalogs:nil | |
| 14281 sgml-local-ecat-files:nil | |
| 14282 End: | |
| 14283 --> |