Mercurial > hg > truffle
annotate src/share/vm/prims/jvmti.xml @ 12355:cefad50507d8
Merge with hs25-b53
| author | Gilles Duboscq <duboscq@ssw.jku.at> |
|---|---|
| date | Fri, 11 Oct 2013 10:38:03 +0200 |
| parents | 8e94527f601e |
| children |
| rev | line source |
|---|---|
| 0 | 1 <?xml version="1.0" encoding="ISO-8859-1"?> |
| 2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?> | |
| 3 <!-- | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
4 Copyright (c) 2002, 2013, 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" |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
361 microversion="3"> |
| 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/> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
434 |
| 0 | 435 An agent may be started at VM startup by specifying the agent library |
| 436 name using a <internallink id="starting">command line option</internallink>. | |
| 437 Some implementations may support a mechanism to <internallink id="onattach"> | |
| 438 start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>. | |
| 439 The details of how this is initiated are implementation specific. | |
| 440 </intro> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
441 |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
442 <intro id="entry point" label="Statically Linked Agents (since version 1.2.3)"> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
443 |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
444 A native JVMTI Agent may be <i>statically linked</i> with the VM. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
445 The manner in which the library and VM image are combined is |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
446 implementation-dependent. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
447 An agent L whose image has been combined with the VM is defined as |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
448 <i>statically linked</i> if and only if the agent exports a function |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
449 called Agent_OnLoad_L. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
450 <p/> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
451 If a <i>statically linked</i> agent L exports a function called |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
452 Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
453 function will be ignored. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
454 If an agent L is <i>statically linked</i>, an Agent_OnLoad_L |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
455 function will be invoked with the same arguments and expected return |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
456 value as specified for the Agent_OnLoad function. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
457 An agent L that is <i>statically linked</i> will prohibit an agent of |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
458 the same name from being loaded dynamically. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
459 <p/> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
460 The VM will invoke the Agent_OnUnload_L function of the agent, if such |
| 12220 | 461 a function is exported, at the same point during VM execution as it would |
| 462 have called the dynamic entry point Agent_OnUnLoad. A statically loaded | |
| 463 agent cannot be unloaded. The Agent_OnUnload_L function will still be | |
| 464 called to do any other agent shutdown related tasks. | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
465 If a <i>statically linked</i> agent L exports a function called |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
466 Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
467 function will be ignored. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
468 <p/> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
469 If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
470 will be invoked with the same arguments and expected return value as |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
471 specified for the Agent_OnAttach function. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
472 If a <i>statically linked</i> agent L exports a function called |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
473 Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
474 function will be ignored. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
475 </intro> |
| 0 | 476 |
| 477 <intro id="starting" label="Agent Command Line Options"> | |
| 478 The term "command-line option" is used below to | |
| 479 mean options supplied in the <code>JavaVMInitArgs</code> argument | |
| 480 to the <code>JNI_CreateJavaVM</code> function of the JNI | |
| 481 Invocation API. | |
| 482 <p/> | |
| 483 One of the two following | |
| 484 command-line options is used on VM startup to | |
| 485 properly load and run agents. | |
| 486 These arguments identify the library containing | |
| 487 the agent as well as an options | |
| 488 string to be passed in at startup. | |
| 489 <dl> | |
| 490 <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt> | |
| 491 <dd> | |
| 492 The name following <code>-agentlib:</code> is the name of the | |
| 493 library to load. Lookup of the library, both its full name and location, | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
494 proceeds in a platform-specific manner. |
| 0 | 495 Typically, the <i><agent-lib-name></i> is expanded to an |
| 496 operating system specific file name. | |
| 497 The <i><options></i> will be passed to the agent on start-up. | |
| 498 For example, if the option | |
| 499 <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to | |
| 500 load the shared library <code>foo.dll</code> from the system <code>PATH</code> | |
| 501 under <tm>Windows</tm> or <code>libfoo.so</code> from the | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
502 <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
503 environment. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
504 If the agent library is statically linked into the executable |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
505 then no actual loading takes place. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
506 <p/> |
| 0 | 507 </dd> |
| 508 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt> | |
| 509 <dd> | |
| 510 The path following <code>-agentpath:</code> is the absolute path from which | |
| 511 to load the library. | |
| 512 No library name expansion will occur. | |
| 513 The <i><options></i> will be passed to the agent on start-up. | |
| 514 For example, if the option | |
| 515 <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
516 load the shared library <code>c:\myLibs\foo.dll</code>. If the agent |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
517 library is statically linked into the executable |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
518 then no actual loading takes place. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
519 <p/> |
| 0 | 520 </dd> |
| 521 </dl> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
522 For a dynamic shared library agent, the start-up routine |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
523 <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
524 in the library will be invoked. If the agent library is statically linked |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
525 into the executable then the system will attempt to invoke the |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
526 <code>Agent_OnLoad_<agent-lib-name></code> entry point where |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
527 <agent-lib-name> is the basename of the |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
528 agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>, |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
529 the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine. |
| 0 | 530 <p/> |
| 531 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code> | |
| 532 will be searched for JNI native method implementations to facilitate the | |
| 533 use of Java programming language code in tools, as is needed for | |
| 534 <internallink id="bci">bytecode instrumentation</internallink>. | |
| 535 <p/> | |
| 536 The agent libraries will be searched after all other libraries have been | |
| 537 searched (agents wishing to override or intercept the native method | |
| 538 implementations of non-agent methods can use the | |
| 539 <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>). | |
| 540 <p/> | |
| 541 These switches do the above and nothing more - they do not change the | |
| 542 state of the VM or <jvmti/>. No command line options are needed | |
| 543 to enable <jvmti/> | |
| 544 or aspects of <jvmti/>, this is handled programmatically | |
| 545 by the use of | |
| 546 <internallink id="capability">capabilities</internallink>. | |
| 547 </intro> | |
| 548 | |
| 549 <intro id="startup" label="Agent Start-Up"> | |
| 550 The VM starts each agent by invoking a start-up function. | |
| 551 If the agent is started in the <code>OnLoad</code> | |
| 552 <functionlink id="GetPhase">phase</functionlink> the function | |
| 553 <internallink id="onload"><code>Agent_OnLoad</code></internallink> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
554 or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
555 for statically linked agents will be invoked. |
| 0 | 556 If the agent is started in the live |
| 557 <functionlink id="GetPhase">phase</functionlink> the function | |
| 558 <internallink id="onattach"><code>Agent_OnAttach</code></internallink> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
559 or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
560 for statically linked agents will be invoked. |
| 0 | 561 Exactly one call to a start-up function is made per agent. |
| 562 </intro> | |
| 563 | |
| 564 <intro id="onload" label="Agent Start-Up (OnLoad phase)"> | |
| 565 If an agent is started during the <code>OnLoad</code> phase then its | |
| 566 agent library must export a start-up function with the following prototype: | |
| 567 <example> | |
| 568 JNIEXPORT jint JNICALL | |
| 569 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
570 Or for a statically linked agent named 'L': |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
571 <example> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
572 JNIEXPORT jint JNICALL |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
573 Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
574 |
| 0 | 575 The VM will start the agent by calling this function. |
| 576 It will be called early enough in VM initialization that: | |
| 577 <ul> | |
| 578 <li><functionlink id="SetSystemProperty">system properties</functionlink> | |
| 579 may be set before they have been used in the start-up of the VM</li> | |
| 580 <li>the full set of | |
| 581 <internallink id="capability">capabilities</internallink> | |
| 582 is still available (note that capabilities that configure the VM | |
| 583 may only be available at this time--see the | |
| 584 <internallink id="capability">Capability function section</internallink>)</li> | |
| 585 <li>no bytecodes have executed</li> | |
| 586 <li>no classes have been loaded</li> | |
| 587 <li>no objects have been created</li> | |
| 588 </ul> | |
| 589 <p/> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
590 The VM will call the <code>Agent_OnLoad</code> or |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
591 <code>Agent_OnLoad_<agent-lib-name></code> function with |
| 0 | 592 <i><options></i> as the second argument - |
| 593 that is, using the command-line option examples, | |
| 594 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> | |
| 595 argument of <code>Agent_OnLoad</code>. | |
| 596 The <code>options</code> argument is encoded as a | |
| 597 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 598 If <i>=<options></i> is not specified, | |
| 599 a zero length string is passed to <code>options</code>. | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
600 The lifespan of the <code>options</code> string is the |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
601 <code>Agent_OnLoad</code> or <code>Agent_OnLoad_<agent-lib-name></code> |
| 0 | 602 call. If needed beyond this time the string or parts of the string must |
| 603 be copied. | |
| 604 The period between when <code>Agent_OnLoad</code> is called and when it | |
| 605 returns is called the <i>OnLoad phase</i>. | |
| 606 Since the VM is not initialized during the OnLoad | |
| 607 <functionlink id="GetPhase">phase</functionlink>, | |
| 608 the set of allowed operations | |
| 609 inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the | |
| 610 functionality available at this time). | |
| 611 The agent can safely process the options and set | |
| 612 event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once | |
| 613 the VM initialization event is received | |
| 614 (that is, the <eventlink id="VMInit">VMInit</eventlink> | |
| 615 callback is invoked), the agent | |
| 616 can complete its initialization. | |
| 617 <rationale> | |
| 618 Early startup is required so that agents can set the desired capabilities, | |
| 619 many of which must be set before the VM is initialized. | |
| 620 In JVMDI, the -Xdebug command-line option provided | |
| 621 very coarse-grain control of capabilities. | |
| 622 JVMPI implementations use various tricks to provide a single "JVMPI on" switch. | |
| 623 No reasonable command-line | |
| 624 option could provide the fine-grain of control required to balance needed capabilities vs | |
| 625 performance impact. | |
| 626 Early startup is also needed so that agents can control the execution | |
| 627 environment - modifying the file system and system properties to install | |
| 628 their functionality. | |
| 629 </rationale> | |
| 630 <p/> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
631 The return value from <code>Agent_OnLoad</code> or |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
632 <code>Agent_OnLoad_<agent-lib-name></code> is used to indicate an error. |
| 0 | 633 Any value other than zero indicates an error and causes termination of the VM. |
| 634 </intro> | |
| 635 | |
| 636 <intro id="onattach" label="Agent Start-Up (Live phase)"> | |
| 637 A VM may support a mechanism that allows agents to be started in the VM during the live | |
| 638 <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported, | |
| 639 are implementation specific. For example, a tool may use some platform specific mechanism, | |
| 640 or implementation specific API, to attach to the running VM, and request it start a given | |
| 641 agent. | |
| 642 <p/> | |
| 643 If an agent is started during the live phase then its agent library | |
| 644 must export a start-up function | |
| 645 with the following prototype: | |
| 646 <example> | |
| 647 JNIEXPORT jint JNICALL | |
| 648 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
649 Or for a statically linked agent named 'L': |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
650 <example> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
651 JNIEXPORT jint JNICALL |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
652 Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
653 |
| 0 | 654 <p/> |
| 655 The VM will start the agent by calling this function. | |
| 656 It will be called in the context of a thread | |
| 657 that is attached to the VM. The first argument <i><vm></i> is the Java VM. | |
| 658 The <i><options></i> argument is the startup options provided to the agent. | |
| 659 <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8 | |
| 660 </internallink> string. | |
| 661 If startup options were not provided, a zero length string is passed to | |
| 662 <code>options</code>. The lifespan of the <code>options</code> string is the | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
663 <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name></code> call. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
664 If needed beyond this time the string or parts of the string must be copied. |
| 0 | 665 <p/> |
| 666 Note that some <internallink id="capability">capabilities</internallink> | |
| 667 may not be available in the live phase. | |
| 668 <p/> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
669 The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
670 ></code> function initializes the agent and returns a value |
| 0 | 671 to the VM to indicate if an error occurred. Any value other than zero indicates an error. |
| 672 An error does not cause the VM to terminate. Instead the VM ignores the error, or takes | |
| 673 some implementation specific action -- for example it might print an error to standard error, | |
| 674 or record the error in a system log. | |
| 675 </intro> | |
| 676 | |
| 677 <intro id="onunload" label="Agent Shutdown"> | |
| 678 The library may optionally export a | |
| 679 shutdown function with the following prototype: | |
| 680 <example> | |
| 681 JNIEXPORT void JNICALL | |
| 682 Agent_OnUnload(JavaVM *vm)</example> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
683 Or for a statically linked agent named 'L': |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
684 <example> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
685 JNIEXPORT void JNICALL |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
686 Agent_OnUnload_L(JavaVM *vm)</example> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
687 |
| 0 | 688 This function will be called by the VM when the library is about to be unloaded. |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
689 The library will be unloaded (unless it is statically linked into the |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
690 executable) and this function will be called if some platform specific |
| 0 | 691 mechanism causes the unload (an unload mechanism is not specified in this document) |
| 692 or the library is (in effect) unloaded by the termination of the VM whether through | |
| 693 normal termination or VM failure, including start-up failure. | |
| 694 Uncontrolled shutdown is, of couse, an exception to this rule. | |
| 695 Note the distinction between this function and the | |
| 696 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event | |
| 697 to be sent, the VM must have run at least to the point of initialization and a valid | |
| 698 <jvmti/> environment must exist which has set a callback for VMDeath | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
699 and enabled the event. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
700 None of these are required for <code>Agent_OnUnload</code> or |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
701 <code>Agent_OnUnload_<agent-lib-name></code> and this function |
| 0 | 702 is also called if the library is unloaded for other reasons. |
| 703 In the case that a VM Death event is sent, it will be sent before this | |
| 704 function is called (assuming this function is called due to VM termination). | |
| 705 This function can be used to clean-up resources allocated by the agent. | |
| 706 </intro> | |
| 707 | |
| 708 <intro id="tooloptions" label="JAVA_TOOL_OPTIONS"> | |
| 709 Since the command-line cannot always be accessed or modified, for example in embedded VMs | |
| 710 or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is | |
| 711 provided so that agents may be launched in these cases. | |
| 712 <p/> | |
| 713 Platforms which support environment variables or other named strings, may support the | |
| 714 <code>JAVA_TOOL_OPTIONS</code> variable. This variable will be broken into options at white-space | |
| 715 boundaries. White-space characters include space, tab, carriage-return, new-line, | |
| 716 vertical-tab, and form-feed. Sequences of white-space characters are considered | |
| 717 equivalent to a single white-space character. No white-space is included in the options | |
| 718 unless quoted. Quoting is as follows: | |
| 719 <ul> | |
| 720 <li>All characters enclosed between a pair of single quote marks (''), except a single | |
| 721 quote, are quoted.</li> | |
| 722 <li>Double quote characters have no special meaning inside a pair of single quote marks.</li> | |
| 723 <li>All characters enclosed between a pair of double quote marks (""), except a double | |
| 724 quote, are quoted.</li> | |
| 725 <li>Single quote characters have no special meaning inside a pair of double quote marks.</li> | |
| 726 <li>A quoted part can start or end anywhere in the variable.</li> | |
| 727 <li>White-space characters have no special meaning when quoted -- they are included in | |
| 728 the option like any other character and do not mark white-space boundaries.</li> | |
| 729 <li>The pair of quote marks is not included in the option.</li> | |
| 730 </ul> | |
| 731 <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied | |
| 732 in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is | |
| 733 a concern; for example, the Reference Implementation disables this feature on Unix systems when | |
| 734 the effective user or group ID differs from the real ID. | |
| 735 This feature is intended to support the initialization of tools -- specifically including the | |
| 736 launching of native or Java programming language agents. Multiple tools may wish to use this | |
| 737 feature, so the variable should not be overwritten, instead, options should be appended to | |
| 738 the variable. Note that since the variable is processed at the time of the JNI Invocation | |
| 739 API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled. | |
| 740 </intro> | |
| 741 | |
| 742 <intro id="environments" label="Environments"> | |
| 743 The <jvmti/> specification supports the use of multiple simultaneous | |
| 744 <jvmti/> agents. | |
| 745 Each agent has its own <jvmti/> environment. | |
| 746 That is, the <jvmti/> state is | |
| 747 separate for each agent - changes to one environment do not affect the | |
| 748 others. The state of a <jvmti/> | |
| 749 environment includes: | |
| 750 <ul> | |
| 751 <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li> | |
| 752 <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li> | |
| 753 <li><internallink id="capability">the capabilities</internallink></li> | |
| 754 <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li> | |
| 755 </ul> | |
| 756 Although their <jvmti/> state | |
| 757 is separate, agents inspect and modify the shared state | |
| 758 of the VM, they also share the native environment in which they execute. | |
| 759 As such, an agent can perturb the results of other agents or cause them | |
| 760 to fail. It is the responsibility of the agent writer to specify the level | |
| 761 of compatibility with other agents. <jvmti/> implementations are not capable | |
| 762 of preventing destructive interactions between agents. Techniques to reduce | |
| 763 the likelihood of these occurrences are beyond the scope of this document. | |
| 764 <p/> | |
| 765 An agent creates a <jvmti/> environment | |
| 766 by passing a <jvmti/> version | |
| 767 as the interface ID to the JNI Invocation API function | |
| 6919 | 768 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><code>GetEnv</code></externallink>. |
| 0 | 769 See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink> |
| 770 for more details on the creation and use of | |
| 771 <jvmti/> environments. | |
| 772 Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from | |
| 773 <internallink id="onload"><code>Agent_OnLoad</code></internallink>. | |
| 774 </intro> | |
| 775 | |
| 776 <intro id="bci" label="Bytecode Instrumentation"> | |
| 777 This interface does not include some events that one might expect in an interface with | |
| 778 profiling support. Some examples include object allocation events and full speed | |
| 779 method enter and exit events. The interface instead provides support for | |
| 780 <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine | |
| 781 bytecode instructions which comprise the target program. Typically, these alterations | |
| 782 are to add "events" to the code of a method - for example, to add, at the beginning of a method, | |
| 783 a call to <code>MyProfiler.methodEntered()</code>. | |
| 784 Since the changes are purely additive, they do not modify application | |
| 785 state or behavior. | |
| 786 Because the inserted agent code is standard bytecodes, the VM can run at full speed, | |
| 787 optimizing not only the target program but also the instrumentation. If the | |
| 788 instrumentation does not involve switching from bytecode execution, no expensive | |
| 789 state transitions are needed. The result is high performance events. | |
| 790 This approach also provides complete control to the agent: instrumentation can be | |
| 791 restricted to "interesting" portions of the code (e.g., the end user's code) and | |
| 792 can be conditional. Instrumentation can run entirely in Java programming language | |
| 793 code or can call into the native agent. Instrumentation can simply maintain | |
| 794 counters or can statistically sample events. | |
| 795 <p/> | |
| 796 Instrumentation can be inserted in one of three ways: | |
| 797 <ul> | |
| 798 <li> | |
| 799 Static Instrumentation: The class file is instrumented before it | |
| 800 is loaded into the VM - for example, by creating a duplicate directory of | |
| 801 <code>*.class</code> files which have been modified to add the instrumentation. | |
| 802 This method is extremely awkward and, in general, an agent cannot know | |
| 803 the origin of the class files which will be loaded. | |
| 804 </li> | |
| 805 <li> | |
| 806 Load-Time Instrumentation: When a class file is loaded by the VM, the raw | |
| 807 bytes of the class file are sent for instrumentation to the agent. | |
| 808 The <eventlink id="ClassFileLoadHook"/> | |
| 809 event, triggered by the class load, | |
| 810 provides this functionality. This mechanism provides efficient | |
| 811 and complete access to one-time instrumentation. | |
| 812 </li> | |
| 813 <li> | |
| 814 Dynamic Instrumentation: A class which is already loaded (and possibly | |
| 815 even running) is modified. This optional feature is provided by the | |
| 816 <eventlink id="ClassFileLoadHook"/> event, triggered by calling the | |
| 817 <functionlink id="RetransformClasses"/> function. | |
| 818 Classes can be modified multiple times and can be returned to their | |
| 819 original state. | |
| 820 The mechanism allows instrumentation which changes during the | |
| 821 course of execution. | |
| 822 </li> | |
| 823 </ul> | |
| 824 <p/> | |
| 825 The class modification functionality provided in this interface | |
| 826 is intended to provide a mechanism for instrumentation | |
| 827 (the <eventlink id="ClassFileLoadHook"/> event | |
| 828 and the <functionlink id="RetransformClasses"/> function) | |
| 829 and, during development, for fix-and-continue debugging | |
| 830 (the <functionlink id="RedefineClasses"/> function). | |
| 831 <p/> | |
| 832 Care must be taken to avoid perturbing dependencies, especially when | |
| 833 instrumenting core classes. For example, an approach to getting notification | |
| 834 of every object allocation is to instrument the constructor on | |
| 835 <code>Object</code>. Assuming that the constructor is initially | |
| 836 empty, the constructor could be changed to: | |
| 837 <example> | |
| 838 public Object() { | |
| 839 MyProfiler.allocationTracker(this); | |
| 840 } | |
| 841 </example> | |
| 842 However, if this change was made using the | |
| 843 <eventlink id="ClassFileLoadHook"/> | |
| 844 event then this might impact a typical VM as follows: | |
| 845 the first created object will call the constructor causing a class load of | |
| 846 <code>MyProfiler</code>; which will then cause | |
| 847 object creation, and since <code>MyProfiler</code> isn't loaded yet, | |
| 848 infinite recursion; resulting in a stack overflow. A refinement of this | |
| 849 would be to delay invoking the tracking method until a safe time. For | |
| 850 example, <code>trackAllocations</code> could be set in the | |
| 851 handler for the <code>VMInit</code> event. | |
| 852 <example> | |
| 853 static boolean trackAllocations = false; | |
| 854 | |
| 855 public Object() { | |
| 856 if (trackAllocations) { | |
| 857 MyProfiler.allocationTracker(this); | |
| 858 } | |
| 859 } | |
| 860 </example> | |
| 861 <p/> | |
| 862 The <functionlink id="SetNativeMethodPrefix"/> allows native methods | |
| 863 to be instrumented by the use of wrapper methods. | |
| 864 </intro> | |
| 865 | |
| 866 <intro id="mUTF" label="Modified UTF-8 String Encoding"> | |
| 867 <jvmti/> uses modified UTF-8 to encode character strings. | |
| 868 This is the same encoding used by JNI. | |
| 869 Modified UTF-8 differs | |
| 870 from standard UTF-8 in the representation of supplementary characters | |
| 871 and of the null character. See the | |
| 6919 | 872 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16542"> |
| 0 | 873 Modified UTF-8 Strings</externallink> |
| 874 section of the JNI specification for details. | |
| 875 </intro> | |
| 876 | |
| 877 <intro id="context" label="Specification Context"> | |
| 878 Since this interface provides access to the state of applications running in the | |
| 879 Java virtual machine; | |
| 880 terminology refers to the Java platform and not the native | |
| 881 platform (unless stated otherwise). For example: | |
| 882 <ul> | |
| 883 <li>"thread" means Java programming language thread.</li> | |
| 884 <li>"stack frame" means Java virtual machine stack frame.</li> | |
| 885 <li>"class" means Java programming language class.</li> | |
| 886 <li>"heap" means Java virtual machine heap.</li> | |
| 887 <li>"monitor" means Java programming language object monitor.</li> | |
| 888 </ul> | |
| 889 <p/> | |
| 890 Sun, Sun Microsystems, the Sun logo, Java, and JVM | |
|
1552
c18cbe5936b8
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
0
diff
changeset
|
891 are trademarks or registered trademarks of Oracle |
|
c18cbe5936b8
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
0
diff
changeset
|
892 and/or its affiliates, in the U.S. and other countries. |
| 0 | 893 </intro> |
| 894 | |
| 895 | |
| 896 <functionsection label="Functions"> | |
| 897 <intro id="jvmtiEnvAccess" label="Accessing Functions"> | |
| 898 Native code accesses <jvmti/> features | |
| 899 by calling <jvmti/> functions. | |
| 900 Access to <jvmti/> functions is by use of an interface pointer | |
| 901 in the same manner as | |
| 6919 | 902 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html">Java |
| 0 | 903 Native Interface (JNI) functions</externallink> are accessed. |
| 904 The <jvmti/> interface pointer is called the | |
| 905 <i>environment pointer</i>. | |
| 906 <p/> | |
| 907 An environment pointer is a pointer to an environment and has | |
| 908 the type <code>jvmtiEnv*</code>. | |
| 909 An environment has information about its <jvmti/> connection. | |
| 910 The first value in the environment is a pointer to the function table. | |
| 911 The function table is an array of pointers to <jvmti/> functions. | |
| 912 Every function pointer is at a predefined offset inside the | |
| 913 array. | |
| 914 <p/> | |
| 915 When used from the C language: | |
| 916 double indirection is used to access the functions; | |
| 917 the environment pointer provides context and is the first | |
| 918 parameter of each function call; for example: | |
| 919 <example> | |
| 920 jvmtiEnv *jvmti; | |
| 921 ... | |
| 922 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &class_count, &classes); | |
| 923 </example> | |
| 924 <p/> | |
| 925 When used from the C++ language: | |
| 926 functions are accessed as member functions of <code>jvmtiEnv</code>; | |
| 927 the environment pointer is not passed to the function call; for example: | |
| 928 <example> | |
| 929 jvmtiEnv *jvmti; | |
| 930 ... | |
| 931 jvmtiError err = jvmti->GetLoadedClasses(&class_count, &classes); | |
| 932 </example> | |
| 933 Unless otherwise stated, all examples and declarations in this | |
| 934 specification use the C language. | |
| 935 <p/> | |
| 936 A <jvmti/> environment can be obtained through the JNI Invocation API | |
| 937 <code>GetEnv</code> function: | |
| 938 <example> | |
| 939 jvmtiEnv *jvmti; | |
| 940 ... | |
| 941 (*jvm)->GetEnv(jvm, &jvmti, JVMTI_VERSION_1_0); | |
| 942 </example> | |
| 943 Each call to <code>GetEnv</code> | |
| 944 creates a new <jvmti/> connection and thus | |
| 945 a new <jvmti/> environment. | |
| 946 The <code>version</code> argument of <code>GetEnv</code> must be | |
| 947 a <jvmti/> version. | |
| 948 The returned environment may have a different version than the | |
| 949 requested version but the returned environment must be compatible. | |
| 950 <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a | |
| 951 compatible version is not available, if <jvmti/> is not supported or | |
| 952 <jvmti/> is not supported in the current VM configuration. | |
| 953 Other interfaces may be added for creating <jvmti/> environments | |
| 954 in specific contexts. | |
| 955 Each environment has its own state (for example, | |
| 956 <functionlink id="SetEventNotificationMode">desired events</functionlink>, | |
| 957 <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and | |
| 958 <functionlink id="AddCapabilities">capabilities</functionlink>). | |
| 959 An environment is released with | |
| 960 <functionlink id="DisposeEnvironment"></functionlink>. | |
| 961 Thus, unlike JNI which has one environment per thread, <jvmti/> environments work | |
| 962 across threads and are created dynamically. | |
| 963 </intro> | |
| 964 | |
| 965 <intro id="functionReturn" label="Function Return Values"> | |
| 966 <jvmti/> functions always return an | |
| 967 <internallink id="ErrorSection">error code</internallink> via the | |
| 968 <datalink id="jvmtiError"/> function return value. | |
| 969 Some functions can return additional | |
| 970 values through pointers provided by the calling function. | |
| 971 In some cases, <jvmti/> functions allocate memory that your program must | |
| 972 explicitly deallocate. This is indicated in the individual <jvmti/> | |
| 973 function descriptions. Empty lists, arrays, sequences, etc are | |
| 974 returned as <code>NULL</code>. | |
| 975 <p/> | |
| 976 In the event that the <jvmti/> function encounters | |
| 977 an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values | |
| 978 of memory referenced by argument pointers is undefined, but no memory | |
| 979 will have been allocated and no global references will have been allocated. | |
| 980 If the error occurs because of invalid input, no action will have occurred. | |
| 981 </intro> | |
| 982 | |
| 983 <intro id="refs" label="Managing JNI Object References"> | |
| 984 <jvmti/> functions identify objects with JNI references | |
| 985 (<datalink id="jobject"/> and <datalink id="jclass"/>) | |
| 986 and their derivatives | |
| 987 (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>). | |
| 988 References passed to | |
| 989 <jvmti/> functions can be either global or local, but they must be | |
| 990 strong references. All references returned by <jvmti/> functions are | |
| 991 local references--these local references are created | |
| 992 during the <jvmti/> call. | |
| 993 Local references are a resource that must be managed (see the | |
| 6919 | 994 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp18654">JNI Documentation</externallink>). |
| 0 | 995 When threads return from native code all local references |
| 996 are freed. Note that some threads, including typical | |
| 997 agent threads, will never return from native code. | |
| 998 A thread is ensured the ability to create sixteen local | |
| 999 references without the need for any explicit management. | |
| 1000 For threads executing a limited number of <jvmti/> calls before | |
| 1001 returning from native code | |
| 1002 (for example, threads processing events), | |
| 1003 it may be determined that no explicit management | |
| 1004 is needed. | |
| 1005 However, long running agent threads will need explicit | |
| 1006 local reference management--usually with the JNI functions | |
| 1007 <code>PushLocalFrame</code> and <code>PopLocalFrame</code>. | |
| 1008 Conversely, to preserve references beyond the | |
| 1009 return from native code, they must be converted to global references. | |
| 1010 These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> | |
| 1011 as they are not <datalink id="jobject"/>s. | |
| 1012 </intro> | |
| 1013 | |
| 1014 <intro id="prereqState" label="Prerequisite State for Calling Functions"> | |
| 1015 Unless the function explicitly states that the agent must bring | |
| 1016 a thread or the VM to a particular state (for example, suspended), | |
| 1017 the <jvmti/> implementation is responsible for bringing the VM to a | |
| 1018 safe and consistent state for performing the function. | |
| 1019 </intro> | |
| 1020 | |
| 1021 <intro id="functionsExceptions" label="Exceptions and Functions"> | |
| 1022 <jvmti/> functions never throw exceptions; error conditions are | |
| 1023 communicated via the | |
| 1024 <internallink id="functionReturn">function return value</internallink>. | |
| 1025 Any existing exception state is preserved across a call to a | |
| 1026 <jvmti/> function. | |
| 1027 See the | |
| 1028 <externallink | |
| 6919 | 1029 id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html#wp770" |
| 0 | 1030 >Java Exceptions</externallink> |
| 1031 section of the JNI specification for information on handling exceptions. | |
| 1032 </intro> | |
| 1033 | |
| 1034 <category id="memory" label="Memory Management"> | |
| 1035 <intro> | |
| 1036 These functions provide for the allocation and deallocation of | |
| 1037 memory used by <jvmti/> functionality and can be used to provide | |
| 1038 working memory for agents. | |
| 1039 Memory managed by <jvmti/> is not compatible with other memory | |
| 1040 allocation libraries and mechanisms. | |
| 1041 </intro> | |
| 1042 | |
| 1043 <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46"> | |
| 1044 <synopsis>Allocate</synopsis> | |
| 1045 <description> | |
| 1046 Allocate an area of memory through the <jvmti/> allocator. | |
| 1047 The allocated | |
| 1048 memory should be freed with <functionlink id="Deallocate"></functionlink>. | |
| 1049 </description> | |
| 1050 <origin>jvmdi</origin> | |
| 1051 <capabilities> | |
| 1052 </capabilities> | |
| 1053 <parameters> | |
| 1054 <param id="size"> | |
| 1055 <jlong/> | |
| 1056 <description> | |
| 1057 The number of bytes to allocate. | |
| 1058 <rationale> | |
| 1059 <code>jlong</code> is used for compatibility with JVMDI. | |
| 1060 </rationale> | |
| 1061 </description> | |
| 1062 </param> | |
| 1063 <param id="mem_ptr"> | |
| 1064 <allocbuf incount="size"><uchar/></allocbuf> | |
| 1065 <description> | |
| 1066 On return, a pointer to the beginning of the allocated memory. | |
| 1067 If <code>size</code> is zero, <code>NULL</code> is returned. | |
| 1068 </description> | |
| 1069 </param> | |
| 1070 </parameters> | |
| 1071 <errors> | |
| 1072 <error id="JVMTI_ERROR_OUT_OF_MEMORY"> | |
| 1073 Memory request cannot be honored. | |
| 1074 </error> | |
| 1075 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 1076 <paramlink id="size"></paramlink> is less than zero. | |
| 1077 </error> | |
| 1078 </errors> | |
| 1079 </function> | |
| 1080 | |
| 1081 <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47"> | |
| 1082 <synopsis>Deallocate</synopsis> | |
| 1083 <description> | |
| 1084 Deallocate <code>mem</code> using the <jvmti/> allocator. | |
| 1085 This function should | |
| 1086 be used to deallocate any memory allocated and returned | |
| 1087 by a <jvmti/> function | |
| 1088 (including memory allocated with <functionlink id="Allocate"></functionlink>). | |
| 1089 All allocated memory must be deallocated | |
| 1090 or the memory cannot be reclaimed. | |
| 1091 </description> | |
| 1092 <origin>jvmdi</origin> | |
| 1093 <capabilities> | |
| 1094 </capabilities> | |
| 1095 <parameters> | |
| 1096 <param id="mem"> | |
| 1097 <outbuf> | |
| 1098 <uchar/> | |
| 1099 <nullok>the call is ignored</nullok> | |
| 1100 </outbuf> | |
| 1101 <description> | |
| 1102 A pointer to the beginning of the allocated memory. | |
| 1103 Please ignore "On return, the elements are set." | |
| 1104 <todo>keep it from generating "On return, the elements are set"</todo> | |
| 1105 </description> | |
| 1106 </param> | |
| 1107 </parameters> | |
| 1108 <errors> | |
| 1109 </errors> | |
| 1110 </function> | |
| 1111 </category> | |
| 1112 | |
| 1113 <category id="threadCategory" label="Thread"> | |
| 1114 <intro> | |
| 1115 </intro> | |
| 1116 | |
| 1117 <function id="GetThreadState" num="17"> | |
| 1118 <synopsis>Get Thread State</synopsis> | |
| 1119 <description> | |
| 1120 Get the state of a thread. The state of the thread is represented by the | |
| 1121 answers to the hierarchical set of questions below: | |
| 1122 <ul type="circle"> | |
| 1123 <li><i>Alive?</i> | |
| 1124 <ul> | |
| 1125 <li>Not alive. | |
| 1126 <ul type="circle"> | |
| 1127 <li><i>Why not alive?</i> | |
| 1128 <ul> | |
| 1129 <li>New.</li> | |
| 1130 <li>Terminated (<datalink | |
| 1131 id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li> | |
| 1132 </ul> | |
| 1133 </li> | |
| 1134 </ul> | |
| 1135 </li> | |
| 1136 <li>Alive (<datalink | |
| 1137 id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>) | |
| 1138 <ul type="circle"> | |
| 1139 <li><i>Suspended?</i> | |
| 1140 <ul> | |
| 1141 <li>Suspended (<datalink | |
| 1142 id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li> | |
| 1143 <li>Not suspended</li> | |
| 1144 </ul> | |
| 1145 </li> | |
| 1146 <li><i>Interrupted?</i> | |
| 1147 <ul> | |
| 1148 <li>Interrupted (<datalink | |
| 1149 id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li> | |
| 1150 <li>Not interrupted.</li> | |
| 1151 </ul> | |
| 1152 </li> | |
| 1153 <li><i>In native?</i> | |
| 1154 <ul> | |
| 1155 <li>In native code (<datalink | |
| 1156 id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li> | |
| 1157 <li>In Java programming language code</li> | |
| 1158 </ul> | |
| 1159 </li> | |
| 1160 <li><i>What alive state?</i> | |
| 1161 <ul> | |
| 1162 <li>Runnable (<datalink | |
| 1163 id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li> | |
| 1164 <li>Blocked (<datalink | |
| 1165 id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li> | |
| 1166 <li>Waiting (<datalink | |
| 1167 id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>) | |
| 1168 <ul type="circle"> | |
| 1169 <li><i>Timed wait?</i> | |
| 1170 <ul> | |
| 1171 <li>Indefinite (<datalink | |
| 1172 id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li> | |
| 1173 <li>Timed (<datalink | |
| 1174 id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li> | |
| 1175 </ul> | |
| 1176 </li> | |
| 1177 <li><i>Why waiting?</i> | |
| 1178 <ul> | |
| 1179 <li>Object.wait (<datalink | |
| 1180 id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li> | |
| 1181 <li>LockSupport.park (<datalink | |
| 1182 id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li> | |
| 1183 <li>Sleeping (<datalink | |
| 1184 id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li> | |
| 1185 </ul> | |
| 1186 </li> | |
| 1187 </ul> | |
| 1188 </li> | |
| 1189 </ul> | |
| 1190 </li> | |
| 1191 </ul> | |
| 1192 </li> | |
| 1193 </ul> | |
| 1194 </li> | |
| 1195 </ul> | |
| 1196 <p/> | |
| 1197 The answers are represented by the following bit vector. | |
| 1198 <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits"> | |
| 1199 <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001"> | |
| 1200 Thread is alive. Zero if thread is new (not started) or terminated. | |
| 1201 </constant> | |
| 1202 <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002"> | |
| 1203 Thread has completed execution. | |
| 1204 </constant> | |
| 1205 <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004"> | |
| 1206 Thread is runnable. | |
| 1207 </constant> | |
| 1208 <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400"> | |
| 1209 Thread is waiting to enter a synchronization block/method or, | |
| 1210 after an <code>Object.wait()</code>, waiting to re-enter a | |
| 1211 synchronization block/method. | |
| 1212 </constant> | |
| 1213 <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080"> | |
| 1214 Thread is waiting. | |
| 1215 </constant> | |
| 1216 <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010"> | |
| 1217 Thread is waiting without a timeout. | |
| 1218 For example, <code>Object.wait()</code>. | |
| 1219 </constant> | |
| 1220 <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020"> | |
| 1221 Thread is waiting with a maximum time to wait specified. | |
| 1222 For example, <code>Object.wait(long)</code>. | |
| 1223 </constant> | |
| 1224 <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040"> | |
| 1225 Thread is sleeping -- <code>Thread.sleep(long)</code>. | |
| 1226 </constant> | |
| 1227 <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100"> | |
| 1228 Thread is waiting on an object monitor -- <code>Object.wait</code>. | |
| 1229 </constant> | |
| 1230 <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200"> | |
| 1231 Thread is parked, for example: <code>LockSupport.park</code>, | |
| 1232 <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>. | |
| 1233 </constant> | |
| 1234 <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000"> | |
| 1235 Thread suspended. | |
| 1236 <code>java.lang.Thread.suspend()</code> | |
| 1237 or a <jvmti/> suspend function | |
| 1238 (such as <functionlink id="SuspendThread"></functionlink>) | |
| 1239 has been called on the thread. If this bit | |
| 1240 is set, the other bits refer to the thread state before suspension. | |
| 1241 </constant> | |
| 1242 <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000"> | |
| 1243 Thread has been interrupted. | |
| 1244 </constant> | |
| 1245 <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000"> | |
| 1246 Thread is in native code--that is, a native method is running | |
| 1247 which has not called back into the VM or Java programming | |
| 1248 language code. | |
| 1249 <p/> | |
| 1250 This flag is not set when running VM compiled Java programming | |
| 1251 language code nor is it set when running VM code or | |
| 1252 VM support code. Native VM interface functions, such as JNI and | |
| 1253 <jvmti/> functions, may be implemented as VM code. | |
| 1254 </constant> | |
| 1255 <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000"> | |
| 1256 Defined by VM vendor. | |
| 1257 </constant> | |
| 1258 <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000"> | |
| 1259 Defined by VM vendor. | |
| 1260 </constant> | |
| 1261 <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000"> | |
| 1262 Defined by VM vendor. | |
| 1263 </constant> | |
| 1264 </constants> | |
| 1265 The following definitions are used to convert <jvmti/> thread state | |
| 1266 to <code>java.lang.Thread.State</code> style states. | |
| 1267 <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits"> | |
| 1268 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK" | |
| 1269 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"> | |
| 1270 Mask the state with this before comparison | |
| 1271 </constant> | |
| 1272 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW" | |
| 1273 num="0"> | |
| 1274 <code>java.lang.Thread.State.NEW</code> | |
| 1275 </constant> | |
| 1276 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED" | |
| 1277 num="JVMTI_THREAD_STATE_TERMINATED"> | |
| 1278 <code>java.lang.Thread.State.TERMINATED</code> | |
| 1279 </constant> | |
| 1280 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE" | |
| 1281 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE"> | |
| 1282 <code>java.lang.Thread.State.RUNNABLE</code> | |
| 1283 </constant> | |
| 1284 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED" | |
| 1285 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"> | |
| 1286 <code>java.lang.Thread.State.BLOCKED</code> | |
| 1287 </constant> | |
| 1288 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING" | |
| 1289 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY"> | |
| 1290 <code>java.lang.Thread.State.WAITING</code> | |
| 1291 </constant> | |
| 1292 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING" | |
| 1293 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"> | |
| 1294 <code>java.lang.Thread.State.TIMED_WAITING</code> | |
| 1295 </constant> | |
| 1296 </constants> | |
| 1297 <b>Rules</b> | |
| 1298 <p/> | |
| 1299 There can be no more than one answer to a question, although there can be no | |
| 1300 answer (because the answer is unknown, does not apply, or none of the answers is | |
| 1301 correct). An answer is set only when the enclosing answers match. | |
| 1302 That is, no more than one of | |
| 1303 <ul type="circle"> | |
| 1304 <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li> | |
| 1305 <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li> | |
| 1306 <li><code>JVMTI_THREAD_STATE_WAITING</code></li> | |
| 1307 </ul> | |
| 1308 can be set (a <tm>J2SE</tm> compliant implementation will always set | |
| 1309 one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set). | |
| 1310 And if any of these are set, the enclosing answer | |
| 1311 <code>JVMTI_THREAD_STATE_ALIVE</code> is set. | |
| 1312 No more than one of | |
| 1313 <ul type="circle"> | |
| 1314 <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li> | |
| 1315 <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li> | |
| 1316 </ul> | |
| 1317 can be set (a <tm>J2SE</tm> compliant implementation will always set | |
| 1318 one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set). | |
| 1319 And if either is set, the enclosing answers | |
| 1320 <code>JVMTI_THREAD_STATE_ALIVE</code> and | |
| 1321 <code>JVMTI_THREAD_STATE_WAITING</code> are set. | |
| 1322 No more than one of | |
| 1323 <ul type="circle"> | |
| 1324 <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li> | |
| 1325 <li><code>JVMTI_THREAD_STATE_PARKED</code></li> | |
| 1326 <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li> | |
| 1327 </ul> | |
| 1328 can be set. And if any of these is set, the enclosing answers | |
| 1329 <code>JVMTI_THREAD_STATE_ALIVE</code> and | |
| 1330 <code>JVMTI_THREAD_STATE_WAITING</code> are set. | |
| 1331 Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set, | |
| 1332 then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set. | |
| 1333 If a state <i>A</i> is implemented using the mechanism of | |
| 1334 state <i>B</i> then it is state <i>A</i> which | |
| 1335 is returned by this function. | |
| 1336 For example, if <code>Thread.sleep(long)</code> | |
| 1337 is implemented using <code>Object.wait(long)</code> | |
| 1338 then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code> | |
| 1339 which is returned. | |
| 1340 More than one of | |
| 1341 <ul type="circle"> | |
| 1342 <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li> | |
| 1343 <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li> | |
| 1344 <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li> | |
| 1345 </ul> | |
| 1346 can be set, but if any is set, | |
| 1347 <code>JVMTI_THREAD_STATE_ALIVE</code> is set. | |
| 1348 <p/> | |
| 1349 And finally, | |
| 1350 <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless | |
| 1351 <code>JVMTI_THREAD_STATE_ALIVE</code> is not set. | |
| 1352 <p/> | |
| 1353 The thread state representation is designed for extension in future versions | |
| 1354 of the specification; thread state values should be used accordingly, that is | |
| 1355 they should not be used as ordinals. | |
| 1356 Most queries can be made by testing a single bit, if use in a switch statement is desired, | |
| 1357 the state bits should be masked with the interesting bits. | |
| 1358 All bits not defined above are reserved for future use. | |
| 1359 A VM, compliant to the current specification, must set reserved bits to zero. | |
| 1360 An agent should ignore reserved bits -- | |
| 1361 they should not be assumed to be zero and thus should not be included in comparisons. | |
| 1362 <p/> | |
| 1363 <b>Examples</b> | |
| 1364 <p/> | |
| 1365 Note that the values below exclude reserved and vendor bits. | |
| 1366 <p/> | |
| 1367 The state of a thread blocked at a <code>synchronized</code>-statement would be: | |
| 1368 <example> | |
| 1369 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | |
| 1370 </example> | |
| 1371 The state of a thread which hasn't started yet would be: | |
| 1372 <example> | |
| 1373 0 | |
| 1374 </example> | |
| 1375 The state of a thread at a <code>Object.wait(3000)</code> would be: | |
| 1376 <example> | |
| 1377 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING + | |
| 1378 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT + | |
| 1379 JVMTI_THREAD_STATE_MONITOR_WAITING | |
| 1380 </example> | |
| 1381 The state of a thread suspended while runnable would be: | |
| 1382 <example> | |
| 1383 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED | |
| 1384 </example> | |
| 1385 <p/> | |
| 1386 <b>Testing the State</b> | |
| 1387 <p/> | |
| 1388 In most cases, the thread state can be determined by testing the one bit corresponding | |
| 1389 to that question. For example, the code to test if a thread is sleeping: | |
| 1390 <example> | |
| 1391 jint state; | |
| 1392 jvmtiError err; | |
| 1393 | |
| 1394 err = (*jvmti)->GetThreadState(jvmti, thread, &state); | |
| 1395 if (err == JVMTI_ERROR_NONE) { | |
| 1396 if (state & JVMTI_THREAD_STATE_SLEEPING) { ... | |
| 1397 </example> | |
| 1398 <p/> | |
| 1399 For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be: | |
| 1400 <example> | |
| 1401 if (state & JVMTI_THREAD_STATE_WAITING) { ... | |
| 1402 </example> | |
| 1403 For some states, more than one bit will need to be tested as is the case | |
| 1404 when testing if a thread has not yet been started: | |
| 1405 <example> | |
| 1406 if ((state & (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0) { ... | |
| 1407 </example> | |
| 1408 To distinguish timed from untimed <code>Object.wait</code>: | |
| 1409 <example> | |
| 1410 if (state & JVMTI_THREAD_STATE_IN_OBJECT_WAIT) { | |
| 1411 if (state & JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT) { | |
| 1412 printf("in Object.wait(long timeout)\n"); | |
| 1413 } else { | |
| 1414 printf("in Object.wait()\n"); | |
| 1415 } | |
| 1416 } | |
| 1417 </example> | |
| 1418 <p/> | |
| 1419 <b>Relationship to <code>java.lang.Thread.State</code></b> | |
| 1420 <p/> | |
| 1421 The thread state represented by <code>java.lang.Thread.State</code> | |
| 1422 returned from <code>java.lang.Thread.getState()</code> is a subset of the | |
| 1423 information returned from this function. | |
| 1424 The corresponding <code>java.lang.Thread.State</code> can be determined | |
| 1425 by using the provided conversion masks. | |
| 1426 For example, this returns the name of the <code>java.lang.Thread.State</code> thread state: | |
| 1427 <example> | |
| 1428 err = (*jvmti)->GetThreadState(jvmti, thread, &state); | |
| 1429 abortOnError(err); | |
| 1430 switch (state & JVMTI_JAVA_LANG_THREAD_STATE_MASK) { | |
| 1431 case JVMTI_JAVA_LANG_THREAD_STATE_NEW: | |
| 1432 return "NEW"; | |
| 1433 case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED: | |
| 1434 return "TERMINATED"; | |
| 1435 case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE: | |
| 1436 return "RUNNABLE"; | |
| 1437 case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED: | |
| 1438 return "BLOCKED"; | |
| 1439 case JVMTI_JAVA_LANG_THREAD_STATE_WAITING: | |
| 1440 return "WAITING"; | |
| 1441 case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING: | |
| 1442 return "TIMED_WAITING"; | |
| 1443 } | |
| 1444 </example> | |
| 1445 </description> | |
| 1446 <origin>new</origin> | |
| 1447 <capabilities> | |
| 1448 </capabilities> | |
| 1449 <parameters> | |
| 1450 <param id="thread"> | |
| 1451 <jthread null="current" started="maybe" impl="noconvert"/> | |
| 1452 <description> | |
| 1453 The thread to query. | |
| 1454 </description> | |
| 1455 </param> | |
| 1456 <param id="thread_state_ptr"> | |
| 1457 <outptr><jint/></outptr> | |
| 1458 <description> | |
| 1459 On return, points to state flags, | |
| 1460 as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>. | |
| 1461 </description> | |
| 1462 </param> | |
| 1463 </parameters> | |
| 1464 <errors> | |
| 1465 </errors> | |
| 1466 </function> | |
| 1467 | |
| 1468 <function id="GetCurrentThread" phase="start" num="18" since="1.1"> | |
| 1469 <synopsis>Get Current Thread</synopsis> | |
| 1470 <description> | |
| 1471 Get the current thread. | |
| 1472 The current thread is the Java programming language thread which has called the function. | |
| 1473 <p/> | |
| 1474 Note that most <jvmti/> functions that take a thread | |
| 1475 as an argument will accept <code>NULL</code> to mean | |
| 1476 the current thread. | |
| 1477 </description> | |
| 1478 <origin>new</origin> | |
| 1479 <capabilities> | |
| 1480 </capabilities> | |
| 1481 <parameters> | |
| 1482 <param id="thread_ptr"> | |
| 1483 <outptr><jthread/></outptr> | |
| 1484 <description> | |
| 1485 On return, points to the current thread. | |
| 1486 </description> | |
| 1487 </param> | |
| 1488 </parameters> | |
| 1489 <errors> | |
| 1490 </errors> | |
| 1491 </function> | |
| 1492 | |
| 1493 <function id="GetAllThreads" num="4"> | |
| 1494 <synopsis>Get All Threads</synopsis> | |
| 1495 <description> | |
| 1496 Get all live threads. | |
| 1497 The threads are Java programming language threads; | |
| 1498 that is, threads that are attached to the VM. | |
| 1499 A thread is live if <code>java.lang.Thread.isAlive()</code> | |
| 1500 would return <code>true</code>, that is, the thread has | |
| 1501 been started and has not yet died. | |
| 1502 The universe of threads is determined by the context of the <jvmti/> | |
| 1503 environment, which typically is all threads attached to the VM. | |
| 1504 Note that this includes <jvmti/> agent threads | |
| 1505 (see <functionlink id="RunAgentThread"/>). | |
| 1506 </description> | |
| 1507 <origin>jvmdi</origin> | |
| 1508 <capabilities> | |
| 1509 </capabilities> | |
| 1510 <parameters> | |
| 1511 <param id="threads_count_ptr"> | |
| 1512 <outptr><jint/></outptr> | |
| 1513 <description> | |
| 1514 On return, points to the number of running threads. | |
| 1515 </description> | |
| 1516 </param> | |
| 1517 <param id="threads_ptr"> | |
| 1518 <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf> | |
| 1519 <description> | |
| 1520 On return, points to an array of references, one | |
| 1521 for each running thread. | |
| 1522 </description> | |
| 1523 </param> | |
| 1524 </parameters> | |
| 1525 <errors> | |
| 1526 </errors> | |
| 1527 </function> | |
| 1528 | |
| 1529 <function id="SuspendThread" num="5"> | |
| 1530 <synopsis>Suspend Thread</synopsis> | |
| 1531 <description> | |
| 1532 Suspend the specified thread. If the calling thread is specified, | |
| 1533 this function will not return until some other thread calls | |
| 1534 <functionlink id="ResumeThread"></functionlink>. | |
| 1535 If the thread is currently suspended, this function | |
| 1536 does nothing and returns an error. | |
| 1537 </description> | |
| 1538 <origin>jvmdi</origin> | |
| 1539 <capabilities> | |
| 1540 <required id="can_suspend"></required> | |
| 1541 </capabilities> | |
| 1542 <parameters> | |
| 1543 <param id="thread"> | |
| 1544 <jthread null="current"/> | |
| 1545 <description> | |
| 1546 The thread to suspend. | |
| 1547 </description> | |
| 1548 </param> | |
| 1549 </parameters> | |
| 1550 <errors> | |
| 1551 <error id="JVMTI_ERROR_THREAD_SUSPENDED"> | |
| 1552 Thread already suspended. | |
| 1553 </error> | |
| 1554 </errors> | |
| 1555 </function> | |
| 1556 | |
| 1557 <elide> | |
| 1558 <function id="SuspendAllThreads" num="101"> | |
| 1559 <synopsis>Suspend All Threads</synopsis> | |
| 1560 <description> | |
| 1561 <issue> | |
| 1562 There has been no explicit call for this function, and it will | |
| 1563 thus be removed if there is no interest. | |
| 1564 </issue> | |
| 1565 Suspend all live threads except: | |
| 1566 <ul> | |
| 1567 <li>already suspended threads</li> | |
| 1568 <li>those listed in <paramlink id="except_list"></paramlink></li> | |
| 1569 <li>certain system (non application) threads, as determined | |
| 1570 by the VM implementation</li> | |
| 1571 </ul> | |
| 1572 The threads are Java programming language threads; | |
| 1573 native threads which are not attached to the VM are not | |
| 1574 Java programming language threads. | |
| 1575 A thread is live if <code>java.lang.Thread.isAlive()</code> | |
| 1576 would return <code>true</code>, that is, the thread has | |
| 1577 been started and has not yet died. | |
| 1578 The universe of threads is determined | |
| 1579 by the context of the <jvmti/> | |
| 1580 environment, which, typically, is all threads attached to the VM, | |
| 1581 except critical VM internal threads and <jvmti/> agent threads | |
| 1582 (see <functionlink id="RunAgentThread"/>). | |
| 1583 <p/> | |
| 1584 If the calling thread is specified, | |
| 1585 all other threads are suspended first then the caller thread is suspended - | |
| 1586 this function will not return until some other thread calls | |
| 1587 <functionlink id="ResumeThread"></functionlink>. | |
| 1588 <p/> | |
| 1589 The list of actually | |
| 1590 suspended threads is returned in | |
| 1591 <paramlink id="suspended_list_ptr"></paramlink>. | |
| 1592 Suspension is as defined in <functionlink id="SuspendThread"></functionlink>. | |
| 1593 <functionlink id="ResumeThreadList"></functionlink> | |
| 1594 can be used to resume the suspended threads. | |
| 1595 </description> | |
| 1596 <origin>new</origin> | |
| 1597 <capabilities> | |
| 1598 <required id="can_suspend"></required> | |
| 1599 </capabilities> | |
| 1600 <parameters> | |
| 1601 <param id="except_count"> | |
| 1602 <jint min="0"/> | |
| 1603 <description> | |
| 1604 The number of threads in the list of threads not to be suspended. | |
| 1605 </description> | |
| 1606 </param> | |
| 1607 <param id="except_list"> | |
| 1608 <inbuf incount="except_count"> | |
| 1609 <jthread/> | |
| 1610 <nullok>not an error if <code>except_count == 0</code></nullok> | |
| 1611 </inbuf> | |
| 1612 <description> | |
| 1613 The list of threads not to be suspended. | |
| 1614 </description> | |
| 1615 </param> | |
| 1616 <param id="suspended_count_ptr"> | |
| 1617 <outptr><jint/></outptr> | |
| 1618 <description> | |
| 1619 On return, points to the number of threads suspended by this call. | |
| 1620 </description> | |
| 1621 </param> | |
| 1622 <param id="suspended_list_ptr"> | |
| 1623 <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf> | |
| 1624 <description> | |
| 1625 On return, points to an array of references, one | |
| 1626 for each thread suspended. | |
| 1627 </description> | |
| 1628 </param> | |
| 1629 </parameters> | |
| 1630 <errors> | |
| 1631 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
| 1632 A thread in <paramlink id="except_list"></paramlink> was invalid. | |
| 1633 </error> | |
| 1634 <error id="JVMTI_ERROR_NULL_POINTER"> | |
| 1635 Both <paramlink id="except_list"></paramlink> was <code>NULL</code> | |
| 1636 and <paramlink id="except_count"></paramlink> was non-zero. | |
| 1637 </error> | |
| 1638 </errors> | |
| 1639 </function> | |
| 1640 </elide> | |
| 1641 | |
| 1642 <function id="SuspendThreadList" num="92"> | |
| 1643 <synopsis>Suspend Thread List</synopsis> | |
| 1644 <description> | |
| 1645 Suspend the <paramlink id="request_count"></paramlink> | |
| 1646 threads specified in the | |
| 1647 <paramlink id="request_list"></paramlink> array. | |
| 1648 Threads may be resumed with | |
| 1649 <functionlink id="ResumeThreadList"></functionlink> or | |
| 1650 <functionlink id="ResumeThread"></functionlink>. | |
| 1651 If the calling thread is specified in the | |
| 1652 <paramlink id="request_list"></paramlink> array, this function will | |
| 1653 not return until some other thread resumes it. | |
| 1654 Errors encountered in the suspension of a thread | |
| 1655 are returned in the <paramlink id="results"></paramlink> | |
| 1656 array, <b>not</b> in the return value of this function. | |
| 1657 Threads that are currently suspended do not change state. | |
| 1658 </description> | |
| 1659 <origin>jvmdi</origin> | |
| 1660 <capabilities> | |
| 1661 <required id="can_suspend"></required> | |
| 1662 </capabilities> | |
| 1663 <parameters> | |
| 1664 <param id="request_count"> | |
| 1665 <jint min="0"/> | |
| 1666 <description> | |
| 1667 The number of threads to suspend. | |
| 1668 </description> | |
| 1669 </param> | |
| 1670 <param id="request_list"> | |
| 1671 <inbuf incount="request_count"><jthread/></inbuf> | |
| 1672 <description> | |
| 1673 The list of threads to suspend. | |
| 1674 </description> | |
| 1675 </param> | |
| 1676 <param id="results"> | |
| 1677 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> | |
| 1678 <description> | |
| 1679 An agent supplied array of | |
| 1680 <paramlink id="request_count"></paramlink> elements. | |
| 1681 On return, filled with the error code for | |
| 1682 the suspend of the corresponding thread. | |
| 1683 The error code will be | |
| 1684 <errorlink id="JVMTI_ERROR_NONE"></errorlink> | |
| 1685 if the thread was suspended by this call. | |
| 1686 Possible error codes are those specified | |
| 1687 for <functionlink id="SuspendThread"></functionlink>. | |
| 1688 </description> | |
| 1689 </param> | |
| 1690 </parameters> | |
| 1691 <errors> | |
| 1692 </errors> | |
| 1693 </function> | |
| 1694 | |
| 1695 <function id="ResumeThread" num="6"> | |
| 1696 <synopsis>Resume Thread</synopsis> | |
| 1697 <description> | |
| 1698 Resume a suspended thread. | |
| 1699 Any threads currently suspended through | |
| 1700 a <jvmti/> suspend function (eg. | |
| 1701 <functionlink id="SuspendThread"></functionlink>) | |
| 1702 or <code>java.lang.Thread.suspend()</code> | |
| 1703 will resume execution; | |
| 1704 all other threads are unaffected. | |
| 1705 </description> | |
| 1706 <origin>jvmdi</origin> | |
| 1707 <capabilities> | |
| 1708 <required id="can_suspend"></required> | |
| 1709 </capabilities> | |
| 1710 <parameters> | |
| 1711 <param id="thread"> | |
| 1712 <jthread/> | |
| 1713 <description> | |
| 1714 The thread to resume. | |
| 1715 </description> | |
| 1716 </param> | |
| 1717 </parameters> | |
| 1718 <errors> | |
| 1719 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 1720 Thread was not suspended. | |
| 1721 </error> | |
| 1722 <error id="JVMTI_ERROR_INVALID_TYPESTATE"> | |
| 1723 The state of the thread has been modified, and is now inconsistent. | |
| 1724 </error> | |
| 1725 </errors> | |
| 1726 </function> | |
| 1727 | |
| 1728 <function id="ResumeThreadList" num="93"> | |
| 1729 <synopsis>Resume Thread List</synopsis> | |
| 1730 <description> | |
| 1731 Resume the <paramlink id="request_count"></paramlink> | |
| 1732 threads specified in the | |
| 1733 <paramlink id="request_list"></paramlink> array. | |
| 1734 Any thread suspended through | |
| 1735 a <jvmti/> suspend function (eg. | |
| 1736 <functionlink id="SuspendThreadList"></functionlink>) | |
| 1737 or <code>java.lang.Thread.suspend()</code> | |
| 1738 will resume execution. | |
| 1739 </description> | |
| 1740 <origin>jvmdi</origin> | |
| 1741 <capabilities> | |
| 1742 <required id="can_suspend"></required> | |
| 1743 </capabilities> | |
| 1744 <parameters> | |
| 1745 <param id="request_count"> | |
| 1746 <jint min="0"/> | |
| 1747 <description> | |
| 1748 The number of threads to resume. | |
| 1749 </description> | |
| 1750 </param> | |
| 1751 <param id="request_list"> | |
| 1752 <inbuf incount="request_count"><jthread/></inbuf> | |
| 1753 <description> | |
| 1754 The threads to resume. | |
| 1755 </description> | |
| 1756 </param> | |
| 1757 <param id="results"> | |
| 1758 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> | |
| 1759 <description> | |
| 1760 An agent supplied array of | |
| 1761 <paramlink id="request_count"></paramlink> elements. | |
| 1762 On return, filled with the error code for | |
| 1763 the resume of the corresponding thread. | |
| 1764 The error code will be | |
| 1765 <errorlink id="JVMTI_ERROR_NONE"></errorlink> | |
| 1766 if the thread was suspended by this call. | |
| 1767 Possible error codes are those specified | |
| 1768 for <functionlink id="ResumeThread"></functionlink>. | |
| 1769 </description> | |
| 1770 </param> | |
| 1771 </parameters> | |
| 1772 <errors> | |
| 1773 </errors> | |
| 1774 </function> | |
| 1775 | |
| 1776 <function id="StopThread" num="7"> | |
| 1777 <synopsis>Stop Thread</synopsis> | |
| 1778 <description> | |
| 1779 Send the specified asynchronous exception to the specified thread | |
| 1780 (similar to <code>java.lang.Thread.stop</code>). | |
| 1781 Normally, this function is used to kill the specified thread with an | |
| 1782 instance of the exception <code>ThreadDeath</code>. | |
| 1783 </description> | |
| 1784 <origin>jvmdi</origin> | |
| 1785 <capabilities> | |
| 1786 <required id="can_signal_thread"></required> | |
| 1787 </capabilities> | |
| 1788 <parameters> | |
| 1789 <param id="thread"> | |
| 1790 <jthread/> | |
| 1791 <description> | |
| 1792 The thread to stop. | |
| 1793 </description> | |
| 1794 </param> | |
| 1795 <param id="exception"> | |
| 1796 <jobject/> | |
| 1797 <description> | |
| 1798 The asynchronous exception object. | |
| 1799 </description> | |
| 1800 </param> | |
| 1801 </parameters> | |
| 1802 <errors> | |
| 1803 </errors> | |
| 1804 </function> | |
| 1805 | |
| 1806 <function id="InterruptThread" num="8"> | |
| 1807 <synopsis>Interrupt Thread</synopsis> | |
| 1808 <description> | |
| 1809 Interrupt the specified thread | |
| 1810 (similar to <code>java.lang.Thread.interrupt</code>). | |
| 1811 </description> | |
| 1812 <origin>jvmdi</origin> | |
| 1813 <capabilities> | |
| 1814 <required id="can_signal_thread"></required> | |
| 1815 </capabilities> | |
| 1816 <parameters> | |
| 1817 <param id="thread"> | |
| 1818 <jthread impl="noconvert"/> | |
| 1819 <description> | |
| 1820 The thread to interrupt. | |
| 1821 </description> | |
| 1822 </param> | |
| 1823 </parameters> | |
| 1824 <errors> | |
| 1825 </errors> | |
| 1826 </function> | |
| 1827 | |
| 1828 <function id="GetThreadInfo" num="9"> | |
| 1829 <synopsis>Get Thread Info</synopsis> | |
| 1830 <typedef id="jvmtiThreadInfo" label="Thread information structure"> | |
| 1831 <field id="name"> | |
| 1832 <allocfieldbuf><char/></allocfieldbuf> | |
| 1833 <description> | |
| 1834 The thread name, encoded as a | |
| 1835 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 1836 </description> | |
| 1837 </field> | |
| 1838 <field id="priority"> | |
| 1839 <jint/> | |
| 1840 <description> | |
| 1841 The thread priority. See the thread priority constants: | |
| 1842 <datalink id="jvmtiThreadPriority"></datalink>. | |
| 1843 </description> | |
| 1844 </field> | |
| 1845 <field id="is_daemon"> | |
| 1846 <jboolean/> | |
| 1847 <description> | |
| 1848 Is this a daemon thread? | |
| 1849 </description> | |
| 1850 </field> | |
| 1851 <field id="thread_group"> | |
| 1852 <jthreadGroup/> | |
| 1853 <description> | |
| 1854 The thread group to which this thread belongs. | |
| 1855 <code>NULL</code> if the thread has died. | |
| 1856 </description> | |
| 1857 </field> | |
| 1858 <field id="context_class_loader"> | |
| 1859 <jobject/> | |
| 1860 <description> | |
| 1861 The context class loader associated with this thread. | |
| 1862 </description> | |
| 1863 </field> | |
| 1864 </typedef> | |
| 1865 <description> | |
| 1866 Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure | |
| 1867 are filled in with details of the specified thread. | |
| 1868 </description> | |
| 1869 <origin>jvmdi</origin> | |
| 1870 <capabilities> | |
| 1871 </capabilities> | |
| 1872 <parameters> | |
| 1873 <param id="thread"> | |
| 1874 <jthread null="current" impl="noconvert" started="maybe"/> | |
| 1875 <description> | |
| 1876 The thread to query. | |
| 1877 </description> | |
| 1878 </param> | |
| 1879 <param id="info_ptr"> | |
| 1880 <outptr><struct>jvmtiThreadInfo</struct></outptr> | |
| 1881 <description> | |
| 1882 On return, filled with information describing the specified thread. | |
| 1883 <p/> | |
| 1884 For JDK 1.1 implementations that don't | |
| 1885 recognize context class loaders, | |
| 1886 the <code>context_class_loader</code> field will be NULL. | |
| 1887 </description> | |
| 1888 </param> | |
| 1889 </parameters> | |
| 1890 <errors> | |
| 1891 </errors> | |
| 1892 </function> | |
| 1893 | |
| 1894 <function id="GetOwnedMonitorInfo" num="10"> | |
| 1895 <synopsis>Get Owned Monitor Info</synopsis> | |
| 1896 <description> | |
| 1897 Get information about the monitors owned by the | |
| 1898 specified thread. | |
| 1899 </description> | |
| 1900 <origin>jvmdiClone</origin> | |
| 1901 <capabilities> | |
| 1902 <required id="can_get_owned_monitor_info"></required> | |
| 1903 </capabilities> | |
| 1904 <parameters> | |
| 1905 <param id="thread"> | |
| 1906 <jthread null="current"/> | |
| 1907 <description> | |
| 1908 The thread to query. | |
| 1909 </description> | |
| 1910 </param> | |
| 1911 <param id="owned_monitor_count_ptr"> | |
| 1912 <outptr><jint/></outptr> | |
| 1913 <description> | |
| 1914 The number of monitors returned. | |
| 1915 </description> | |
| 1916 </param> | |
| 1917 <param id="owned_monitors_ptr"> | |
| 1918 <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf> | |
| 1919 <description> | |
| 1920 The array of owned monitors. | |
| 1921 </description> | |
| 1922 </param> | |
| 1923 </parameters> | |
| 1924 <errors> | |
| 1925 </errors> | |
| 1926 </function> | |
| 1927 | |
| 1928 <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1"> | |
| 1929 <synopsis>Get Owned Monitor Stack Depth Info</synopsis> | |
| 1930 <typedef id="jvmtiMonitorStackDepthInfo" | |
| 1931 label="Monitor stack depth information structure"> | |
| 1932 <field id="monitor"> | |
| 1933 <jobject/> | |
| 1934 <description> | |
| 1935 The owned monitor. | |
| 1936 </description> | |
| 1937 </field> | |
| 1938 <field id="stack_depth"> | |
| 1939 <jint/> | |
| 1940 <description> | |
| 1941 The stack depth. Corresponds to the stack depth used in the | |
| 1942 <internallink id="stack">Stack Frame functions</internallink>. | |
| 1943 That is, zero is the current frame, one is the frame which | |
| 1944 called the current frame. And it is negative one if the | |
| 1945 implementation cannot determine the stack depth (e.g., for | |
| 1946 monitors acquired by JNI <code>MonitorEnter</code>). | |
| 1947 </description> | |
| 1948 </field> | |
| 1949 </typedef> | |
| 1950 <description> | |
| 1951 Get information about the monitors owned by the | |
| 1952 specified thread and the depth of the stack frame which locked them. | |
| 1953 </description> | |
| 1954 <origin>new</origin> | |
| 1955 <capabilities> | |
| 1956 <required id="can_get_owned_monitor_stack_depth_info"></required> | |
| 1957 </capabilities> | |
| 1958 <parameters> | |
| 1959 <param id="thread"> | |
| 1960 <jthread null="current"/> | |
| 1961 <description> | |
| 1962 The thread to query. | |
| 1963 </description> | |
| 1964 </param> | |
| 1965 <param id="monitor_info_count_ptr"> | |
| 1966 <outptr><jint/></outptr> | |
| 1967 <description> | |
| 1968 The number of monitors returned. | |
| 1969 </description> | |
| 1970 </param> | |
| 1971 <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
|
1972 <allocbuf outcount="monitor_info_count_ptr"> |
| 0 | 1973 <struct>jvmtiMonitorStackDepthInfo</struct> |
| 1974 </allocbuf> | |
| 1975 <description> | |
| 1976 The array of owned monitor depth information. | |
| 1977 </description> | |
| 1978 </param> | |
| 1979 </parameters> | |
| 1980 <errors> | |
| 1981 </errors> | |
| 1982 </function> | |
| 1983 | |
| 1984 <function id="GetCurrentContendedMonitor" num="11"> | |
| 1985 <synopsis>Get Current Contended Monitor</synopsis> | |
| 1986 <description> | |
| 1987 Get the object, if any, whose monitor the specified thread is waiting to | |
| 1988 enter or waiting to regain through <code>java.lang.Object.wait</code>. | |
| 1989 </description> | |
| 1990 <origin>jvmdi</origin> | |
| 1991 <capabilities> | |
| 1992 <required id="can_get_current_contended_monitor"></required> | |
| 1993 </capabilities> | |
| 1994 <parameters> | |
| 1995 <param id="thread"> | |
| 1996 <jthread null="current"/> | |
| 1997 <description> | |
| 1998 The thread to query. | |
| 1999 </description> | |
| 2000 </param> | |
| 2001 <param id="monitor_ptr"> | |
| 2002 <outptr><jobject/></outptr> | |
| 2003 <description> | |
| 2004 On return, filled with the current contended monitor, or | |
| 2005 NULL if there is none. | |
| 2006 </description> | |
| 2007 </param> | |
| 2008 </parameters> | |
| 2009 <errors> | |
| 2010 </errors> | |
| 2011 </function> | |
| 2012 | |
| 2013 <callback id="jvmtiStartFunction"> | |
| 2014 <void/> | |
| 2015 <synopsis>Agent Start Function</synopsis> | |
| 2016 <description> | |
| 2017 Agent supplied callback function. | |
| 2018 This function is the entry point for an agent thread | |
| 2019 started with | |
| 2020 <functionlink id="RunAgentThread"></functionlink>. | |
| 2021 </description> | |
| 2022 <parameters> | |
| 2023 <param id="jvmti_env"> | |
| 2024 <outptr> | |
| 2025 <struct>jvmtiEnv</struct> | |
| 2026 </outptr> | |
| 2027 <description> | |
| 2028 The <jvmti/> environment. | |
| 2029 </description> | |
| 2030 </param> | |
| 2031 <param id="jni_env"> | |
| 2032 <outptr> | |
| 2033 <struct>JNIEnv</struct> | |
| 2034 </outptr> | |
| 2035 <description> | |
| 2036 The JNI environment. | |
| 2037 </description> | |
| 2038 </param> | |
| 2039 <param id="arg"> | |
| 2040 <outptr> | |
| 2041 <void/> | |
| 2042 </outptr> | |
| 2043 <description> | |
| 2044 The <code>arg</code> parameter passed to | |
| 2045 <functionlink id="RunAgentThread"></functionlink>. | |
| 2046 </description> | |
| 2047 </param> | |
| 2048 </parameters> | |
| 2049 </callback> | |
| 2050 | |
| 2051 <function id="RunAgentThread" num="12"> | |
| 2052 <synopsis>Run Agent Thread</synopsis> | |
| 2053 <description> | |
| 2054 Starts the execution of an agent thread. with the specified native function. | |
| 2055 The parameter <paramlink id="arg"></paramlink> is forwarded on to the | |
| 2056 <functionlink id="jvmtiStartFunction">start function</functionlink> | |
| 2057 (specified with <paramlink id="proc"></paramlink>) as its single argument. | |
| 2058 This function allows the creation of agent threads | |
| 2059 for handling communication with another process or for handling events | |
| 2060 without the need to load a special subclass of <code>java.lang.Thread</code> or | |
| 2061 implementer of <code>java.lang.Runnable</code>. | |
| 2062 Instead, the created thread can run entirely in native code. | |
| 2063 However, the created thread does require a newly created instance | |
| 2064 of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to | |
| 2065 which it will be associated. | |
| 2066 The thread object can be created with JNI calls. | |
| 2067 <p/> | |
| 2068 The following common thread priorities are provided for your convenience: | |
| 2069 <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const"> | |
| 2070 <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1"> | |
| 2071 Minimum possible thread priority | |
| 2072 </constant> | |
| 2073 <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5"> | |
| 2074 Normal thread priority | |
| 2075 </constant> | |
| 2076 <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10"> | |
| 2077 Maximum possible thread priority | |
| 2078 </constant> | |
| 2079 </constants> | |
| 2080 <p/> | |
| 2081 The new thread is started as a daemon thread with the specified | |
| 2082 <paramlink id="priority"></paramlink>. | |
| 2083 If enabled, a <eventlink id="ThreadStart"/> event will be sent. | |
| 2084 <p/> | |
| 2085 Since the thread has been started, the thread will be live when this function | |
| 2086 returns, unless the thread has died immediately. | |
| 2087 <p/> | |
| 2088 The thread group of the thread is ignored -- specifically, the thread is not | |
| 2089 added to the thread group and the thread is not seen on queries of the thread | |
| 2090 group at either the Java programming language or <jvmti/> levels. | |
| 2091 <p/> | |
| 2092 The thread is not visible to Java programming language queries but is | |
| 2093 included in <jvmti/> queries (for example, | |
| 2094 <functionlink id="GetAllThreads"/> and | |
| 2095 <functionlink id="GetAllStackTraces"/>). | |
| 2096 <p/> | |
| 2097 Upon execution of <code>proc</code>, the new thread will be attached to the | |
| 2098 VM--see the JNI documentation on | |
| 6919 | 2099 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#wp1060" |
| 0 | 2100 >Attaching to the VM</externallink>. |
| 2101 </description> | |
| 2102 <origin>jvmdiClone</origin> | |
| 2103 <capabilities> | |
| 2104 </capabilities> | |
| 2105 <parameters> | |
| 2106 <param id="thread"> | |
| 2107 <jthread impl="noconvert" started="no"/> | |
| 2108 <description> | |
| 2109 The thread to run. | |
| 2110 </description> | |
| 2111 </param> | |
| 2112 <param id="proc"> | |
| 2113 <ptrtype> | |
| 2114 <struct>jvmtiStartFunction</struct> | |
| 2115 </ptrtype> | |
| 2116 <description> | |
| 2117 The start function. | |
| 2118 </description> | |
| 2119 </param> | |
| 2120 <param id="arg"> | |
| 2121 <inbuf> | |
| 2122 <void/> | |
| 2123 <nullok><code>NULL</code> is passed to the start function</nullok> | |
| 2124 </inbuf> | |
| 2125 <description> | |
| 2126 The argument to the start function. | |
| 2127 </description> | |
| 2128 </param> | |
| 2129 <param id="priority"> | |
| 2130 <jint/> | |
| 2131 <description> | |
| 2132 The priority of the started thread. Any thread | |
| 2133 priority allowed by <code>java.lang.Thread.setPriority</code> can be used including | |
| 2134 those in <datalink id="jvmtiThreadPriority"></datalink>. | |
| 2135 </description> | |
| 2136 </param> | |
| 2137 </parameters> | |
| 2138 <errors> | |
| 2139 <error id="JVMTI_ERROR_INVALID_PRIORITY"> | |
| 2140 <paramlink id="priority"/> is less than | |
| 2141 <datalink id="JVMTI_THREAD_MIN_PRIORITY"/> | |
| 2142 or greater than | |
| 2143 <datalink id="JVMTI_THREAD_MAX_PRIORITY"/> | |
| 2144 </error> | |
| 2145 </errors> | |
| 2146 </function> | |
| 2147 | |
| 2148 <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103"> | |
| 2149 <synopsis>Set Thread Local Storage</synopsis> | |
| 2150 <description> | |
| 2151 The VM stores a pointer value associated with each environment-thread | |
| 2152 pair. This pointer value is called <i>thread-local storage</i>. | |
| 2153 This value is <code>NULL</code> unless set with this function. | |
| 2154 Agents can allocate memory in which they store thread specific | |
| 2155 information. By setting thread-local storage it can then be | |
| 2156 accessed with | |
| 2157 <functionlink id="GetThreadLocalStorage"></functionlink>. | |
| 2158 <p/> | |
| 2159 This function is called by the agent to set the value of the <jvmti/> | |
| 2160 thread-local storage. <jvmti/> supplies to the agent a pointer-size | |
| 2161 thread-local storage that can be used to record per-thread | |
| 2162 information. | |
| 2163 </description> | |
| 2164 <origin>jvmpi</origin> | |
| 2165 <capabilities> | |
| 2166 </capabilities> | |
| 2167 <parameters> | |
| 2168 <param id="thread"> | |
| 2169 <jthread null="current"/> | |
| 2170 <description> | |
| 2171 Store to this thread. | |
| 2172 </description> | |
| 2173 </param> | |
| 2174 <param id="data"> | |
| 2175 <inbuf> | |
| 2176 <void/> | |
| 2177 <nullok>value is set to <code>NULL</code></nullok> | |
| 2178 </inbuf> | |
| 2179 <description> | |
| 2180 The value to be entered into the thread-local storage. | |
| 2181 </description> | |
| 2182 </param> | |
| 2183 </parameters> | |
| 2184 <errors> | |
| 2185 </errors> | |
| 2186 </function> | |
| 2187 | |
| 2188 <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102"> | |
| 2189 <synopsis>Get Thread Local Storage</synopsis> | |
| 2190 <description> | |
| 2191 Called by the agent to get the value of the <jvmti/> thread-local | |
| 2192 storage. | |
| 2193 </description> | |
| 2194 <origin>jvmpi</origin> | |
| 2195 <capabilities> | |
| 2196 </capabilities> | |
| 2197 <parameters> | |
| 2198 <param id="thread"> | |
| 2199 <jthread null="current" impl="noconvert"/> | |
| 2200 <description> | |
| 2201 Retrieve from this thread. | |
| 2202 </description> | |
| 2203 </param> | |
| 2204 <param id="data_ptr"> | |
| 2205 <agentbuf><void/></agentbuf> | |
| 2206 <description> | |
| 2207 Pointer through which the value of the thread local | |
| 2208 storage is returned. | |
| 2209 If thread-local storage has not been set with | |
| 2210 <functionlink id="SetThreadLocalStorage"></functionlink> the returned | |
| 2211 pointer is <code>NULL</code>. | |
| 2212 </description> | |
| 2213 </param> | |
| 2214 </parameters> | |
| 2215 <errors> | |
| 2216 </errors> | |
| 2217 </function> | |
| 2218 | |
| 2219 </category> | |
| 2220 | |
| 2221 <category id="thread_groups" label="Thread Group"> | |
| 2222 <intro> | |
| 2223 </intro> | |
| 2224 | |
| 2225 <function id="GetTopThreadGroups" num="13"> | |
| 2226 <synopsis>Get Top Thread Groups</synopsis> | |
| 2227 <description> | |
| 2228 Return all top-level (parentless) thread groups in the VM. | |
| 2229 </description> | |
| 2230 <origin>jvmdi</origin> | |
| 2231 <capabilities> | |
| 2232 </capabilities> | |
| 2233 <parameters> | |
| 2234 <param id="group_count_ptr"> | |
| 2235 <outptr><jint/></outptr> | |
| 2236 <description> | |
| 2237 On return, points to the number of top-level thread groups. | |
| 2238 </description> | |
| 2239 </param> | |
| 2240 <param id="groups_ptr"> | |
| 2241 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> | |
| 2242 <description> | |
| 2243 On return, refers to a pointer to the top-level thread group array. | |
| 2244 </description> | |
| 2245 </param> | |
| 2246 </parameters> | |
| 2247 <errors> | |
| 2248 </errors> | |
| 2249 </function> | |
| 2250 | |
| 2251 <function id="GetThreadGroupInfo" num="14"> | |
| 2252 <synopsis>Get Thread Group Info</synopsis> | |
| 2253 <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure"> | |
| 2254 <field id="parent"> | |
| 2255 <jthreadGroup/> | |
| 2256 <description> | |
| 2257 The parent thread group. | |
| 2258 </description> | |
| 2259 </field> | |
| 2260 <field id="name"> | |
| 2261 <allocfieldbuf><char/></allocfieldbuf> | |
| 2262 <description> | |
| 2263 The thread group's name, encoded as a | |
| 2264 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 2265 </description> | |
| 2266 </field> | |
| 2267 <field id="max_priority"> | |
| 2268 <jint/> | |
| 2269 <description> | |
| 2270 The maximum priority for this thread group. | |
| 2271 </description> | |
| 2272 </field> | |
| 2273 <field id="is_daemon"> | |
| 2274 <jboolean/> | |
| 2275 <description> | |
| 2276 Is this a daemon thread group? | |
| 2277 </description> | |
| 2278 </field> | |
| 2279 </typedef> | |
| 2280 <description> | |
| 2281 Get information about the thread group. The fields of the | |
| 2282 <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure | |
| 2283 are filled in with details of the specified thread group. | |
| 2284 </description> | |
| 2285 <origin>jvmdi</origin> | |
| 2286 <capabilities> | |
| 2287 </capabilities> | |
| 2288 <parameters> | |
| 2289 <param id="group"> | |
| 2290 <jthreadGroup/> | |
| 2291 <description> | |
| 2292 The thread group to query. | |
| 2293 </description> | |
| 2294 </param> | |
| 2295 <param id="info_ptr"> | |
| 2296 <outptr><struct>jvmtiThreadGroupInfo</struct></outptr> | |
| 2297 <description> | |
| 2298 On return, filled with information describing the specified | |
| 2299 thread group. | |
| 2300 </description> | |
| 2301 </param> | |
| 2302 </parameters> | |
| 2303 <errors> | |
| 2304 </errors> | |
| 2305 </function> | |
| 2306 | |
| 2307 <function id="GetThreadGroupChildren" num="15"> | |
| 2308 <synopsis>Get Thread Group Children</synopsis> | |
| 2309 <description> | |
| 2310 Get the live threads and active subgroups in this thread group. | |
| 2311 </description> | |
| 2312 <origin>jvmdi</origin> | |
| 2313 <capabilities> | |
| 2314 </capabilities> | |
| 2315 <parameters> | |
| 2316 <param id="group"> | |
| 2317 <jthreadGroup/> | |
| 2318 <description> | |
| 2319 The group to query. | |
| 2320 </description> | |
| 2321 </param> | |
| 2322 <param id="thread_count_ptr"> | |
| 2323 <outptr><jint/></outptr> | |
| 2324 <description> | |
| 2325 On return, points to the number of live threads in this thread group. | |
| 2326 </description> | |
| 2327 </param> | |
| 2328 <param id="threads_ptr"> | |
| 2329 <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf> | |
| 2330 <description> | |
| 2331 On return, points to an array of the live threads in this thread group. | |
| 2332 </description> | |
| 2333 </param> | |
| 2334 <param id="group_count_ptr"> | |
| 2335 <outptr><jint/></outptr> | |
| 2336 <description> | |
| 2337 On return, points to the number of active child thread groups | |
| 2338 </description> | |
| 2339 </param> | |
| 2340 <param id="groups_ptr"> | |
| 2341 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> | |
| 2342 <description> | |
| 2343 On return, points to an array of the active child thread groups. | |
| 2344 </description> | |
| 2345 </param> | |
| 2346 </parameters> | |
| 2347 <errors> | |
| 2348 </errors> | |
| 2349 </function> | |
| 2350 </category> | |
| 2351 | |
| 2352 <category id="stack" label="Stack Frame"> | |
| 2353 <intro> | |
| 2354 These functions provide information about the stack of a thread. | |
| 2355 Stack frames are referenced by depth. | |
| 2356 The frame at depth zero is the current frame. | |
| 2357 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
2358 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
|
2359 <vmspec chapter="3.6"/>, |
| 0 | 2360 That is, they correspond to method |
| 2361 invocations (including native methods) but do not correspond to platform native or | |
| 2362 VM internal frames. | |
| 2363 <p/> | |
| 2364 A <jvmti/> implementation may use method invocations to launch a thread and | |
| 2365 the corresponding frames may be included in the stack as presented by these functions -- | |
| 2366 that is, there may be frames shown | |
| 2367 deeper than <code>main()</code> and <code>run()</code>. | |
| 2368 However this presentation must be consistent across all <jvmti/> functionality which | |
| 2369 uses stack frames or stack depth. | |
| 2370 </intro> | |
| 2371 | |
| 2372 <typedef id="jvmtiFrameInfo" label="Stack frame information structure"> | |
| 2373 <description> | |
| 2374 Information about a stack frame is returned in this structure. | |
| 2375 </description> | |
| 2376 <field id="method"> | |
| 2377 <jmethodID/> | |
| 2378 <description> | |
| 2379 The method executing in this frame. | |
| 2380 </description> | |
| 2381 </field> | |
| 2382 <field id="location"> | |
| 2383 <jlocation/> | |
| 2384 <description> | |
| 2385 The index of the instruction executing in this frame. | |
| 2386 <code>-1</code> if the frame is executing a native method. | |
| 2387 </description> | |
| 2388 </field> | |
| 2389 </typedef> | |
| 2390 | |
| 2391 <typedef id="jvmtiStackInfo" label="Stack information structure"> | |
| 2392 <description> | |
| 2393 Information about a set of stack frames is returned in this structure. | |
| 2394 </description> | |
| 2395 <field id="thread"> | |
| 2396 <jthread/> | |
| 2397 <description> | |
| 2398 On return, the thread traced. | |
| 2399 </description> | |
| 2400 </field> | |
| 2401 <field id="state"> | |
| 2402 <jint/> | |
| 2403 <description> | |
| 2404 On return, the thread state. See <functionlink id="GetThreadState"></functionlink>. | |
| 2405 </description> | |
| 2406 </field> | |
| 2407 <field id="frame_buffer"> | |
| 2408 <outbuf incount="max_frame_count"> | |
| 2409 <struct>jvmtiFrameInfo</struct> | |
| 2410 </outbuf> | |
| 2411 <description> | |
| 2412 On return, this agent allocated buffer is filled | |
| 2413 with stack frame information. | |
| 2414 </description> | |
| 2415 </field> | |
| 2416 <field id="frame_count"> | |
| 2417 <jint/> | |
| 2418 <description> | |
| 2419 On return, the number of records filled into | |
| 2420 <code>frame_buffer</code>. | |
| 2421 This will be | |
| 2422 min(<code>max_frame_count</code>, <i>stackDepth</i>). | |
| 2423 </description> | |
| 2424 </field> | |
| 2425 </typedef> | |
| 2426 | |
| 2427 <function id="GetStackTrace" num="104"> | |
| 2428 <synopsis>Get Stack Trace</synopsis> | |
| 2429 <description> | |
| 2430 Get information about the stack of a thread. | |
| 2431 If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack, | |
| 2432 the <paramlink id="max_frame_count"></paramlink> topmost frames are returned, | |
| 2433 otherwise the entire stack is returned. | |
| 2434 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
| 2435 <p/> | |
| 2436 The following example causes up to five of the topmost frames | |
| 2437 to be returned and (if there are any frames) the currently | |
| 2438 executing method name to be printed. | |
| 2439 <example> | |
| 2440 jvmtiFrameInfo frames[5]; | |
| 2441 jint count; | |
| 2442 jvmtiError err; | |
| 2443 | |
| 2444 err = (*jvmti)->GetStackTrace(jvmti, aThread, 0, 5, | |
|
7168
73e64867adb7
8003690: Example code in JVMTI GetStackTrace documentation is broken
mikael
parents:
6919
diff
changeset
|
2445 frames, &count); |
| 0 | 2446 if (err == JVMTI_ERROR_NONE && count >= 1) { |
| 2447 char *methodName; | |
| 2448 err = (*jvmti)->GetMethodName(jvmti, frames[0].method, | |
|
7168
73e64867adb7
8003690: Example code in JVMTI GetStackTrace documentation is broken
mikael
parents:
6919
diff
changeset
|
2449 &methodName, NULL, NULL); |
| 0 | 2450 if (err == JVMTI_ERROR_NONE) { |
| 2451 printf("Executing method: %s", methodName); | |
| 2452 } | |
| 2453 } | |
| 2454 </example> | |
| 2455 <todo> | |
| 2456 check example code. | |
| 2457 </todo> | |
| 2458 <p/> | |
| 2459 The <paramlink id="thread"></paramlink> need not be suspended | |
| 2460 to call this function. | |
| 2461 <p/> | |
| 2462 The <functionlink id="GetLineNumberTable"></functionlink> | |
| 2463 function can be used to map locations to line numbers. Note that | |
| 2464 this mapping can be done lazily. | |
| 2465 </description> | |
| 2466 <origin>jvmpi</origin> | |
| 2467 <capabilities> | |
| 2468 </capabilities> | |
| 2469 <parameters> | |
| 2470 <param id="thread"> | |
| 2471 <jthread null="current"/> | |
| 2472 <description> | |
| 2473 Fetch the stack trace of this thread. | |
| 2474 </description> | |
| 2475 </param> | |
| 2476 <param id="start_depth"> | |
| 2477 <jint/> | |
| 2478 <description> | |
| 2479 Begin retrieving frames at this depth. | |
| 2480 If non-negative, count from the current frame, | |
| 2481 the first frame retrieved is at depth <code>start_depth</code>. | |
| 2482 For example, if zero, start from the current frame; if one, start from the | |
| 2483 caller of the current frame; if two, start from the caller of the | |
| 2484 caller of the current frame; and so on. | |
| 2485 If negative, count from below the oldest frame, | |
| 2486 the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>, | |
| 2487 where <i>stackDepth</i> is the count of frames on the stack. | |
| 2488 For example, if negative one, only the oldest frame is retrieved; | |
| 2489 if negative two, start from the frame called by the oldest frame. | |
| 2490 </description> | |
| 2491 </param> | |
| 2492 <param id="max_frame_count"> | |
| 2493 <jint min="0"/> | |
| 2494 <description> | |
| 2495 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. | |
| 2496 </description> | |
| 2497 </param> | |
| 2498 <param id="frame_buffer"> | |
| 2499 <outbuf incount="max_frame_count" outcount="count_ptr"> | |
| 2500 <struct>jvmtiFrameInfo</struct> | |
| 2501 </outbuf> | |
| 2502 <description> | |
| 2503 On return, this agent allocated buffer is filled | |
| 2504 with stack frame information. | |
| 2505 </description> | |
| 2506 </param> | |
| 2507 <param id="count_ptr"> | |
| 2508 <outptr><jint/></outptr> | |
| 2509 <description> | |
| 2510 On return, points to the number of records filled in. | |
| 2511 For non-negative <code>start_depth</code>, this will be | |
| 2512 min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>). | |
| 2513 For negative <code>start_depth</code>, this will be | |
| 2514 min(<code>max_frame_count</code>, <code>-start_depth</code>). | |
| 2515 </description> | |
| 2516 </param> | |
| 2517 </parameters> | |
| 2518 <errors> | |
| 2519 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 2520 <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>. | |
| 2521 Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>. | |
| 2522 </error> | |
| 2523 </errors> | |
| 2524 </function> | |
| 2525 | |
| 2526 | |
| 2527 <function id="GetAllStackTraces" num="100"> | |
| 2528 <synopsis>Get All Stack Traces</synopsis> | |
| 2529 <description> | |
| 2530 Get information about the stacks of all live threads | |
| 2531 (including <internallink id="RunAgentThread">agent threads</internallink>). | |
| 2532 If <paramlink id="max_frame_count"/> is less than the depth of a stack, | |
| 2533 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, | |
| 2534 otherwise the entire stack is returned. | |
| 2535 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
| 2536 <p/> | |
| 2537 All stacks are collected simultaneously, that is, no changes will occur to the | |
| 2538 thread state or stacks between the sampling of one thread and the next. | |
| 2539 The threads need not be suspended. | |
| 2540 | |
| 2541 <example> | |
| 2542 jvmtiStackInfo *stack_info; | |
| 2543 jint thread_count; | |
| 2544 int ti; | |
| 2545 jvmtiError err; | |
| 2546 | |
| 2547 err = (*jvmti)->GetAllStackTraces(jvmti, MAX_FRAMES, &stack_info, &thread_count); | |
| 2548 if (err != JVMTI_ERROR_NONE) { | |
| 2549 ... | |
| 2550 } | |
| 2551 for (ti = 0; ti < thread_count; ++ti) { | |
| 2552 jvmtiStackInfo *infop = &stack_info[ti]; | |
| 2553 jthread thread = infop->thread; | |
| 2554 jint state = infop->state; | |
| 2555 jvmtiFrameInfo *frames = infop->frame_buffer; | |
| 2556 int fi; | |
| 2557 | |
| 2558 myThreadAndStatePrinter(thread, state); | |
| 2559 for (fi = 0; fi < infop->frame_count; fi++) { | |
| 2560 myFramePrinter(frames[fi].method, frames[fi].location); | |
| 2561 } | |
| 2562 } | |
| 2563 /* this one Deallocate call frees all data allocated by GetAllStackTraces */ | |
| 2564 err = (*jvmti)->Deallocate(jvmti, stack_info); | |
| 2565 </example> | |
| 2566 <todo> | |
| 2567 check example code. | |
| 2568 </todo> | |
| 2569 | |
| 2570 </description> | |
| 2571 <origin>new</origin> | |
| 2572 <capabilities> | |
| 2573 </capabilities> | |
| 2574 <parameters> | |
| 2575 <param id="max_frame_count"> | |
| 2576 <jint min="0"/> | |
| 2577 <description> | |
| 2578 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. | |
| 2579 </description> | |
| 2580 </param> | |
| 2581 <param id="stack_info_ptr"> | |
| 2582 <allocbuf> | |
| 2583 <struct>jvmtiStackInfo</struct> | |
| 2584 </allocbuf> | |
| 2585 <description> | |
| 2586 On return, this buffer is filled | |
| 2587 with stack information for each thread. | |
| 2588 The number of <datalink id="jvmtiStackInfo"/> records is determined | |
| 2589 by <paramlink id="thread_count_ptr"/>. | |
| 2590 <p/> | |
| 2591 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> | |
| 2592 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. | |
| 2593 These buffers must not be separately deallocated. | |
| 2594 </description> | |
| 2595 </param> | |
| 2596 <param id="thread_count_ptr"> | |
| 2597 <outptr><jint/></outptr> | |
| 2598 <description> | |
| 2599 The number of threads traced. | |
| 2600 </description> | |
| 2601 </param> | |
| 2602 </parameters> | |
| 2603 <errors> | |
| 2604 </errors> | |
| 2605 </function> | |
| 2606 | |
| 2607 <function id="GetThreadListStackTraces" num="101"> | |
| 2608 <synopsis>Get Thread List Stack Traces</synopsis> | |
| 2609 <description> | |
| 2610 Get information about the stacks of the supplied threads. | |
| 2611 If <paramlink id="max_frame_count"/> is less than the depth of a stack, | |
| 2612 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, | |
| 2613 otherwise the entire stack is returned. | |
| 2614 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
| 2615 <p/> | |
| 2616 All stacks are collected simultaneously, that is, no changes will occur to the | |
| 2617 thread state or stacks between the sampling one thread and the next. | |
| 2618 The threads need not be suspended. | |
| 2619 <p/> | |
| 2620 If a thread has not yet started or terminates before the stack information is collected, | |
| 2621 a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero) | |
| 2622 will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked. | |
| 2623 <p/> | |
| 2624 See the example for the similar function | |
| 2625 <functionlink id="GetAllStackTraces"/>. | |
| 2626 </description> | |
| 2627 <origin>new</origin> | |
| 2628 <capabilities> | |
| 2629 </capabilities> | |
| 2630 <parameters> | |
| 2631 <param id="thread_count"> | |
| 2632 <jint min="0"/> | |
| 2633 <description> | |
| 2634 The number of threads to trace. | |
| 2635 </description> | |
| 2636 </param> | |
| 2637 <param id="thread_list"> | |
| 2638 <inbuf incount="thread_count"><jthread/></inbuf> | |
| 2639 <description> | |
| 2640 The list of threads to trace. | |
| 2641 </description> | |
| 2642 </param> | |
| 2643 <param id="max_frame_count"> | |
| 2644 <jint min="0"/> | |
| 2645 <description> | |
| 2646 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. | |
| 2647 </description> | |
| 2648 </param> | |
| 2649 <param id="stack_info_ptr"> | |
| 2650 <allocbuf outcount="thread_count"> | |
| 2651 <struct>jvmtiStackInfo</struct> | |
| 2652 </allocbuf> | |
| 2653 <description> | |
| 2654 On return, this buffer is filled | |
| 2655 with stack information for each thread. | |
| 2656 The number of <datalink id="jvmtiStackInfo"/> records is determined | |
| 2657 by <paramlink id="thread_count"/>. | |
| 2658 <p/> | |
| 2659 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> | |
| 2660 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. | |
| 2661 These buffers must not be separately deallocated. | |
| 2662 </description> | |
| 2663 </param> | |
| 2664 </parameters> | |
| 2665 <errors> | |
| 2666 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
| 2667 An element in <paramlink id="thread_list"/> is not a thread object. | |
| 2668 </error> | |
| 2669 </errors> | |
| 2670 </function> | |
| 2671 | |
| 2672 <elide> | |
| 2673 <function id="AsyncGetStackTrace" num="1000"> | |
| 2674 <synopsis>Get Stack Trace--Asynchronous</synopsis> | |
| 2675 <description> | |
| 2676 Get information about the entire stack of a thread (or a sub-section of it). | |
| 2677 This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink> | |
| 2678 and is reentrant and safe to call | |
| 2679 from asynchronous signal handlers. | |
| 2680 The stack trace is returned only for the calling thread. | |
| 2681 <p/> | |
| 2682 The <functionlink id="GetLineNumberTable"></functionlink> | |
| 2683 function can be used to map locations to line numbers. Note that | |
| 2684 this mapping can be done lazily. | |
| 2685 </description> | |
| 2686 <origin>jvmpi</origin> | |
| 2687 <capabilities> | |
| 2688 <required id="can_get_async_stack_trace"></required> | |
| 2689 <capability id="can_show_JVM_spec_async_frames"> | |
| 2690 If <code>false</code>, | |
| 2691 <paramlink id="use_java_stack"></paramlink> | |
| 2692 must be <code>false</code>. | |
| 2693 </capability> | |
| 2694 </capabilities> | |
| 2695 <parameters> | |
| 2696 <param id="use_java_stack"> | |
| 2697 <jboolean/> | |
| 2698 <description> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
2699 Return the stack showing <vmspec/> |
| 0 | 2700 model of the stack; |
| 2701 otherwise, show the internal representation of the stack with | |
| 2702 inlined and optimized methods missing. If the virtual machine | |
| 2703 is using the <i>Java Virtual Machine Specification</i> stack model | |
| 2704 internally, this flag is ignored. | |
| 2705 </description> | |
| 2706 </param> | |
| 2707 <param id="max_count"> | |
| 2708 <jint min="0"/> | |
| 2709 <description> | |
| 2710 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. | |
| 2711 Retrieve this many unless the stack depth is less than <code>max_count</code>. | |
| 2712 </description> | |
| 2713 </param> | |
| 2714 <param id="frame_buffer"> | |
| 2715 <outbuf incount="max_count" outcount="count_ptr"> | |
| 2716 <struct>jvmtiFrameInfo</struct> | |
| 2717 <nullok>this information is not returned</nullok> | |
| 2718 </outbuf> | |
| 2719 <description> | |
| 2720 The agent passes in a buffer | |
| 2721 large enough to hold <code>max_count</code> records of | |
| 2722 <datalink id="jvmtiFrameInfo"></datalink>. This buffer must be | |
| 2723 pre-allocated by the agent. | |
| 2724 </description> | |
| 2725 </param> | |
| 2726 <param id="count_ptr"> | |
| 2727 <outptr><jint/></outptr> | |
| 2728 <description> | |
| 2729 On return, points to the number of records filled in.. | |
| 2730 </description> | |
| 2731 </param> | |
| 2732 </parameters> | |
| 2733 <errors> | |
| 2734 <error id="JVMTI_ERROR_UNATTACHED_THREAD"> | |
| 2735 The thread being used to call this function is not attached | |
| 2736 to the virtual machine. Calls must be made from attached threads. | |
| 2737 </error> | |
| 2738 </errors> | |
| 2739 </function> | |
| 2740 </elide> | |
| 2741 | |
| 2742 <function id="GetFrameCount" num="16"> | |
| 2743 <synopsis>Get Frame Count</synopsis> | |
| 2744 <description> | |
| 2745 Get the number of frames currently in the specified thread's call stack. | |
| 2746 <p/> | |
| 2747 If this function is called for a thread actively executing bytecodes (for example, | |
| 2748 not the current thread and not suspended), the information returned is transient. | |
| 2749 </description> | |
| 2750 <origin>jvmdi</origin> | |
| 2751 <capabilities> | |
| 2752 </capabilities> | |
| 2753 <parameters> | |
| 2754 <param id="thread"> | |
| 2755 <jthread null="current"/> | |
| 2756 <description> | |
| 2757 The thread to query. | |
| 2758 </description> | |
| 2759 </param> | |
| 2760 <param id="count_ptr"> | |
| 2761 <outptr><jint/></outptr> | |
| 2762 <description> | |
| 2763 On return, points to the number of frames in the call stack. | |
| 2764 </description> | |
| 2765 </param> | |
| 2766 </parameters> | |
| 2767 <errors> | |
| 2768 </errors> | |
| 2769 </function> | |
| 2770 | |
| 2771 <function id="PopFrame" num="80"> | |
| 2772 <synopsis>Pop Frame</synopsis> | |
| 2773 <description> | |
| 2774 Pop the current frame of <code>thread</code>'s stack. | |
| 2775 Popping a frame takes you to the previous frame. | |
| 2776 When the thread is resumed, the execution | |
| 2777 state of the thread is reset to the state | |
| 2778 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
|
2779 That is (using <vmspec/> terminology): |
| 0 | 2780 <ul> |
| 2781 <li>the current frame is discarded as the previous frame becomes the current one</li> | |
| 2782 <li>the operand stack is restored--the argument values are added back | |
| 2783 and if the invoke was not <code>invokestatic</code>, | |
| 2784 <code>objectref</code> is added back as well</li> | |
| 2785 <li>the Java virtual machine PC is restored to the opcode | |
| 2786 of the invoke instruction</li> | |
| 2787 </ul> | |
| 2788 Note however, that any changes to the arguments, which | |
| 2789 occurred in the called method, remain; | |
| 2790 when execution continues, the first instruction to | |
| 2791 execute will be the invoke. | |
| 2792 <p/> | |
| 2793 Between calling <code>PopFrame</code> and resuming the | |
| 2794 thread the state of the stack is undefined. | |
| 2795 To pop frames beyond the first, | |
| 2796 these three steps must be repeated: | |
| 2797 <ul> | |
| 2798 <li>suspend the thread via an event (step, breakpoint, ...)</li> | |
| 2799 <li>call <code>PopFrame</code></li> | |
| 2800 <li>resume the thread</li> | |
| 2801 </ul> | |
| 2802 <p/> | |
| 2803 A lock acquired by calling the called method | |
| 2804 (if it is a <code>synchronized</code> method) | |
| 2805 and locks acquired by entering <code>synchronized</code> | |
| 2806 blocks within the called method are released. | |
| 2807 Note: this does not apply to native locks or | |
| 2808 <code>java.util.concurrent.locks</code> locks. | |
| 2809 <p/> | |
| 2810 Finally blocks are not executed. | |
| 2811 <p/> | |
| 2812 Changes to global state are not addressed and thus remain changed. | |
| 2813 <p/> | |
| 2814 The specified thread must be suspended (which implies it cannot be the current thread). | |
| 2815 <p/> | |
| 2816 Both the called method and calling method must be non-native Java programming | |
| 2817 language methods. | |
| 2818 <p/> | |
| 2819 No <jvmti/> events are generated by this function. | |
| 2820 </description> | |
| 2821 <origin>jvmdi</origin> | |
| 2822 <capabilities> | |
| 2823 <required id="can_pop_frame"></required> | |
| 2824 </capabilities> | |
| 2825 <parameters> | |
| 2826 <param id="thread"> | |
| 2827 <jthread/> | |
| 2828 <description> | |
| 2829 The thread whose current frame is to be popped. | |
| 2830 </description> | |
| 2831 </param> | |
| 2832 </parameters> | |
| 2833 <errors> | |
| 2834 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2835 Called or calling method is a native method. | |
| 2836 The implementation is unable to pop this frame. | |
| 2837 </error> | |
| 2838 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 2839 Thread was not suspended. | |
| 2840 </error> | |
| 2841 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 2842 There are less than two stack frames on the call stack. | |
| 2843 </error> | |
| 2844 </errors> | |
| 2845 </function> | |
| 2846 | |
| 2847 <function id="GetFrameLocation" num="19"> | |
| 2848 <synopsis>Get Frame Location</synopsis> | |
| 2849 <description> | |
| 2850 <p/> | |
| 2851 For a Java programming language frame, return the location of the instruction | |
| 2852 currently executing. | |
| 2853 </description> | |
| 2854 <origin>jvmdiClone</origin> | |
| 2855 <capabilities> | |
| 2856 </capabilities> | |
| 2857 <parameters> | |
| 2858 <param id="thread"> | |
| 2859 <jthread null="current" frame="frame"/> | |
| 2860 <description> | |
| 2861 The thread of the frame to query. | |
| 2862 </description> | |
| 2863 </param> | |
| 2864 <param id="depth"> | |
| 2865 <jframeID thread="thread"/> | |
| 2866 <description> | |
| 2867 The depth of the frame to query. | |
| 2868 </description> | |
| 2869 </param> | |
| 2870 <param id="method_ptr"> | |
| 2871 <outptr><jmethodID/></outptr> | |
| 2872 <description> | |
| 2873 On return, points to the method for the current location. | |
| 2874 </description> | |
| 2875 </param> | |
| 2876 <param id="location_ptr"> | |
| 2877 <outptr><jlocation/></outptr> | |
| 2878 <description> | |
| 2879 On return, points to the index of the currently | |
| 2880 executing instruction. | |
| 2881 Is set to <code>-1</code> if the frame is executing | |
| 2882 a native method. | |
| 2883 </description> | |
| 2884 </param> | |
| 2885 </parameters> | |
| 2886 <errors> | |
| 2887 </errors> | |
| 2888 </function> | |
| 2889 | |
| 2890 <function id="NotifyFramePop" num="20"> | |
| 2891 <synopsis>Notify Frame Pop</synopsis> | |
| 2892 <description> | |
| 2893 When the frame that is currently at <paramlink id="depth"></paramlink> | |
| 2894 is popped from the stack, generate a | |
| 2895 <eventlink id="FramePop"></eventlink> event. See the | |
| 2896 <eventlink id="FramePop"></eventlink> event for details. | |
| 2897 Only frames corresponding to non-native Java programming language | |
| 2898 methods can receive notification. | |
| 2899 <p/> | |
| 2900 The specified thread must either be the current thread | |
| 2901 or the thread must be suspended. | |
| 2902 </description> | |
| 2903 <origin>jvmdi</origin> | |
| 2904 <capabilities> | |
| 2905 <required id="can_generate_frame_pop_events"></required> | |
| 2906 </capabilities> | |
| 2907 <parameters> | |
| 2908 <param id="thread"> | |
| 2909 <jthread null="current" frame="depth"/> | |
| 2910 <description> | |
| 2911 The thread of the frame for which the frame pop event will be generated. | |
| 2912 </description> | |
| 2913 </param> | |
| 2914 <param id="depth"> | |
| 2915 <jframeID thread="thread"/> | |
| 2916 <description> | |
| 2917 The depth of the frame for which the frame pop event will be generated. | |
| 2918 </description> | |
| 2919 </param> | |
| 2920 </parameters> | |
| 2921 <errors> | |
| 2922 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2923 The frame at <code>depth</code> is executing a | |
| 2924 native method. | |
| 2925 </error> | |
| 2926 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 2927 Thread was not suspended and was not the current thread. | |
| 2928 </error> | |
| 2929 </errors> | |
| 2930 </function> | |
| 2931 | |
| 2932 </category> | |
| 2933 | |
| 2934 <category id="ForceEarlyReturn" label="Force Early Return"> | |
| 2935 <intro> | |
| 2936 These functions allow an agent to force a method | |
| 2937 to return at any point during its execution. | |
| 2938 The method which will return early is referred to as the <i>called method</i>. | |
| 2939 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
|
2940 (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
|
2941 <vmspec chapter="3.6"/>) |
| 0 | 2942 for the specified thread at |
| 2943 the time the function is called. | |
| 2944 <p/> | |
| 2945 The specified thread must be suspended or must be the current thread. | |
| 2946 The return occurs when execution of Java programming | |
| 2947 language code is resumed on this thread. | |
| 2948 Between calling one of these functions and resumption | |
| 2949 of thread execution, the state of the stack is undefined. | |
| 2950 <p/> | |
| 2951 No further instructions are executed in the called method. | |
| 2952 Specifically, finally blocks are not executed. | |
| 2953 Note: this can cause inconsistent states in the application. | |
| 2954 <p/> | |
| 2955 A lock acquired by calling the called method | |
| 2956 (if it is a <code>synchronized</code> method) | |
| 2957 and locks acquired by entering <code>synchronized</code> | |
| 2958 blocks within the called method are released. | |
| 2959 Note: this does not apply to native locks or | |
| 2960 <code>java.util.concurrent.locks</code> locks. | |
| 2961 <p/> | |
| 2962 Events, such as <eventlink id="MethodExit"></eventlink>, | |
| 2963 are generated as they would be in a normal return. | |
| 2964 <p/> | |
| 2965 The called method must be a non-native Java programming | |
| 2966 language method. | |
| 2967 Forcing return on a thread with only one frame on the | |
| 2968 stack causes the thread to exit when resumed. | |
| 2969 </intro> | |
| 2970 | |
| 2971 <function id="ForceEarlyReturnObject" num="81" since="1.1"> | |
| 2972 <synopsis>Force Early Return - Object</synopsis> | |
| 2973 <description> | |
| 2974 This function can be used to return from a method whose | |
| 2975 result type is <code>Object</code> | |
| 2976 or a subclass of <code>Object</code>. | |
| 2977 </description> | |
| 2978 <origin>new</origin> | |
| 2979 <capabilities> | |
| 2980 <required id="can_force_early_return"></required> | |
| 2981 </capabilities> | |
| 2982 <parameters> | |
| 2983 <param id="thread"> | |
| 2984 <jthread null="current"/> | |
| 2985 <description> | |
| 2986 The thread whose current frame is to return early. | |
| 2987 </description> | |
| 2988 </param> | |
| 2989 <param id="value"> | |
| 2990 <jobject/> | |
| 2991 <description> | |
| 2992 The return value for the called frame. | |
| 2993 An object or <code>NULL</code>. | |
| 2994 </description> | |
| 2995 </param> | |
| 2996 </parameters> | |
| 2997 <errors> | |
| 2998 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2999 Attempted to return early from a frame | |
| 3000 corresponding to a native method. | |
| 3001 Or the implementation is unable to provide | |
| 3002 this functionality on this frame. | |
| 3003 </error> | |
| 3004 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3005 The result type of the called method is not | |
| 3006 <code>Object</code> or a subclass of <code>Object</code>. | |
| 3007 </error> | |
| 3008 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3009 The supplied <paramlink id="value"/> is not compatible with the | |
| 3010 result type of the called method. | |
| 3011 </error> | |
| 3012 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3013 Thread was not the current thread and was not suspended. | |
| 3014 </error> | |
| 3015 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3016 There are no more frames on the call stack. | |
| 3017 </error> | |
| 3018 </errors> | |
| 3019 </function> | |
| 3020 | |
| 3021 <function id="ForceEarlyReturnInt" num="82" since="1.1"> | |
| 3022 <synopsis>Force Early Return - Int</synopsis> | |
| 3023 <description> | |
| 3024 This function can be used to return from a method whose | |
| 3025 result type is <code>int</code>, <code>short</code>, | |
| 3026 <code>char</code>, <code>byte</code>, or | |
| 3027 <code>boolean</code>. | |
| 3028 </description> | |
| 3029 <origin>new</origin> | |
| 3030 <capabilities> | |
| 3031 <required id="can_force_early_return"></required> | |
| 3032 </capabilities> | |
| 3033 <parameters> | |
| 3034 <param id="thread"> | |
| 3035 <jthread null="current"/> | |
| 3036 <description> | |
| 3037 The thread whose current frame is to return early. | |
| 3038 </description> | |
| 3039 </param> | |
| 3040 <param id="value"> | |
| 3041 <jint/> | |
| 3042 <description> | |
| 3043 The return value for the called frame. | |
| 3044 </description> | |
| 3045 </param> | |
| 3046 </parameters> | |
| 3047 <errors> | |
| 3048 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3049 Attempted to return early from a frame | |
| 3050 corresponding to a native method. | |
| 3051 Or the implementation is unable to provide | |
| 3052 this functionality on this frame. | |
| 3053 </error> | |
| 3054 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3055 The result type of the called method is not | |
| 3056 <code>int</code>, <code>short</code>, | |
| 3057 <code>char</code>, <code>byte</code>, or | |
| 3058 <code>boolean</code>. | |
| 3059 </error> | |
| 3060 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3061 Thread was not the current thread and was not suspended. | |
| 3062 </error> | |
| 3063 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3064 There are no frames on the call stack. | |
| 3065 </error> | |
| 3066 </errors> | |
| 3067 </function> | |
| 3068 | |
| 3069 <function id="ForceEarlyReturnLong" num="83" since="1.1"> | |
| 3070 <synopsis>Force Early Return - Long</synopsis> | |
| 3071 <description> | |
| 3072 This function can be used to return from a method whose | |
| 3073 result type is <code>long</code>. | |
| 3074 </description> | |
| 3075 <origin>new</origin> | |
| 3076 <capabilities> | |
| 3077 <required id="can_force_early_return"></required> | |
| 3078 </capabilities> | |
| 3079 <parameters> | |
| 3080 <param id="thread"> | |
| 3081 <jthread null="current"/> | |
| 3082 <description> | |
| 3083 The thread whose current frame is to return early. | |
| 3084 </description> | |
| 3085 </param> | |
| 3086 <param id="value"> | |
| 3087 <jlong/> | |
| 3088 <description> | |
| 3089 The return value for the called frame. | |
| 3090 </description> | |
| 3091 </param> | |
| 3092 </parameters> | |
| 3093 <errors> | |
| 3094 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3095 Attempted to return early from a frame | |
| 3096 corresponding to a native method. | |
| 3097 Or the implementation is unable to provide | |
| 3098 this functionality on this frame. | |
| 3099 </error> | |
| 3100 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3101 The result type of the called method is not <code>long</code>. | |
| 3102 </error> | |
| 3103 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3104 Thread was not the current thread and was not suspended. | |
| 3105 </error> | |
| 3106 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3107 There are no frames on the call stack. | |
| 3108 </error> | |
| 3109 </errors> | |
| 3110 </function> | |
| 3111 | |
| 3112 <function id="ForceEarlyReturnFloat" num="84" since="1.1"> | |
| 3113 <synopsis>Force Early Return - Float</synopsis> | |
| 3114 <description> | |
| 3115 This function can be used to return from a method whose | |
| 3116 result type is <code>float</code>. | |
| 3117 </description> | |
| 3118 <origin>new</origin> | |
| 3119 <capabilities> | |
| 3120 <required id="can_force_early_return"></required> | |
| 3121 </capabilities> | |
| 3122 <parameters> | |
| 3123 <param id="thread"> | |
| 3124 <jthread null="current"/> | |
| 3125 <description> | |
| 3126 The thread whose current frame is to return early. | |
| 3127 </description> | |
| 3128 </param> | |
| 3129 <param id="value"> | |
| 3130 <jfloat/> | |
| 3131 <description> | |
| 3132 The return value for the called frame. | |
| 3133 </description> | |
| 3134 </param> | |
| 3135 </parameters> | |
| 3136 <errors> | |
| 3137 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3138 Attempted to return early from a frame | |
| 3139 corresponding to a native method. | |
| 3140 Or the implementation is unable to provide | |
| 3141 this functionality on this frame. | |
| 3142 </error> | |
| 3143 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3144 The result type of the called method is not <code>float</code>. | |
| 3145 </error> | |
| 3146 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3147 Thread was not the current thread and was not suspended. | |
| 3148 </error> | |
| 3149 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3150 There are no frames on the call stack. | |
| 3151 </error> | |
| 3152 </errors> | |
| 3153 </function> | |
| 3154 | |
| 3155 <function id="ForceEarlyReturnDouble" num="85" since="1.1"> | |
| 3156 <synopsis>Force Early Return - Double</synopsis> | |
| 3157 <description> | |
| 3158 This function can be used to return from a method whose | |
| 3159 result type is <code>double</code>. | |
| 3160 </description> | |
| 3161 <origin>new</origin> | |
| 3162 <capabilities> | |
| 3163 <required id="can_force_early_return"></required> | |
| 3164 </capabilities> | |
| 3165 <parameters> | |
| 3166 <param id="thread"> | |
| 3167 <jthread null="current"/> | |
| 3168 <description> | |
| 3169 The thread whose current frame is to return early. | |
| 3170 </description> | |
| 3171 </param> | |
| 3172 <param id="value"> | |
| 3173 <jdouble/> | |
| 3174 <description> | |
| 3175 The return value for the called frame. | |
| 3176 </description> | |
| 3177 </param> | |
| 3178 </parameters> | |
| 3179 <errors> | |
| 3180 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3181 Attempted to return early from a frame corresponding to a native method. | |
| 3182 Or the implementation is unable to provide this functionality on this frame. | |
| 3183 </error> | |
| 3184 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3185 The result type of the called method is not <code>double</code>. | |
| 3186 </error> | |
| 3187 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3188 Thread was not the current thread and was not suspended. | |
| 3189 </error> | |
| 3190 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3191 There are no frames on the call stack. | |
| 3192 </error> | |
| 3193 </errors> | |
| 3194 </function> | |
| 3195 | |
| 3196 <function id="ForceEarlyReturnVoid" num="86" since="1.1"> | |
| 3197 <synopsis>Force Early Return - Void</synopsis> | |
| 3198 <description> | |
| 3199 This function can be used to return from a method with no result type. | |
| 3200 That is, the called method must be declared <code>void</code>. | |
| 3201 </description> | |
| 3202 <origin>new</origin> | |
| 3203 <capabilities> | |
| 3204 <required id="can_force_early_return"></required> | |
| 3205 </capabilities> | |
| 3206 <parameters> | |
| 3207 <param id="thread"> | |
| 3208 <jthread null="current"/> | |
| 3209 <description> | |
| 3210 The thread whose current frame is to return early. | |
| 3211 </description> | |
| 3212 </param> | |
| 3213 </parameters> | |
| 3214 <errors> | |
| 3215 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3216 Attempted to return early from a frame | |
| 3217 corresponding to a native method. | |
| 3218 Or the implementation is unable to provide | |
| 3219 this functionality on this frame. | |
| 3220 </error> | |
| 3221 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3222 The called method has a result type. | |
| 3223 </error> | |
| 3224 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3225 Thread was not the current thread and was not suspended. | |
| 3226 </error> | |
| 3227 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3228 There are no frames on the call stack. | |
| 3229 </error> | |
| 3230 </errors> | |
| 3231 </function> | |
| 3232 | |
| 3233 </category> | |
| 3234 | |
| 3235 <category id="Heap" label="Heap"> | |
| 3236 <intro> | |
| 3237 These functions are used to analyze the heap. | |
| 3238 Functionality includes the ability to view the objects in the | |
| 3239 heap and to tag these objects. | |
| 3240 </intro> | |
| 3241 | |
| 3242 <intro id="objectTags" label="Object Tags"> | |
| 3243 A <i>tag</i> is a value associated with an object. | |
| 3244 Tags are explicitly set by the agent using the | |
| 3245 <functionlink id="SetTag"></functionlink> function or by | |
| 3246 callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>. | |
| 3247 <p/> | |
| 3248 Tags are local to the environment; that is, the tags of one | |
| 3249 environment are not visible in another. | |
| 3250 <p/> | |
| 3251 Tags are <code>jlong</code> values which can be used | |
| 3252 simply to mark an object or to store a pointer to more detailed | |
| 3253 information. Objects which have not been tagged have a | |
| 3254 tag of zero. | |
| 3255 Setting a tag to zero makes the object untagged. | |
| 3256 </intro> | |
| 3257 | |
| 3258 <intro id="heapCallbacks" label="Heap Callback Functions"> | |
| 3259 Heap functions which iterate through the heap and recursively | |
| 3260 follow object references use agent supplied callback functions | |
| 3261 to deliver the information. | |
| 3262 <p/> | |
| 3263 These heap callback functions must adhere to the following restrictions -- | |
| 3264 These callbacks must not use JNI functions. | |
| 3265 These callbacks must not use <jvmti/> functions except | |
| 3266 <i>callback safe</i> functions which | |
| 3267 specifically allow such use (see the raw monitor, memory management, | |
| 3268 and environment local storage functions). | |
| 3269 <p/> | |
| 3270 An implementation may invoke a callback on an internal thread or | |
| 3271 the thread which called the iteration function. | |
| 3272 Heap callbacks are single threaded -- no more than one callback will | |
| 3273 be invoked at a time. | |
| 3274 <p/> | |
| 3275 The Heap Filter Flags can be used to prevent reporting | |
| 3276 based on the tag status of an object or its class. | |
| 3277 If no flags are set (the <code>jint</code> is zero), objects | |
| 3278 will not be filtered out. | |
| 3279 | |
| 3280 <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits"> | |
| 3281 <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4"> | |
| 3282 Filter out tagged objects. Objects which are tagged are not included. | |
| 3283 </constant> | |
| 3284 <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8"> | |
| 3285 Filter out untagged objects. Objects which are not tagged are not included. | |
| 3286 </constant> | |
| 3287 <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10"> | |
| 3288 Filter out objects with tagged classes. Objects whose class is tagged are not included. | |
| 3289 </constant> | |
| 3290 <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20"> | |
| 3291 Filter out objects with untagged classes. Objects whose class is not tagged are not included. | |
| 3292 </constant> | |
| 3293 </constants> | |
| 3294 | |
| 3295 <p/> | |
| 3296 The Heap Visit Control Flags are returned by the heap callbacks | |
| 3297 and can be used to abort the iteration. For the | |
| 3298 <functionlink id="jvmtiHeapReferenceCallback">Heap | |
| 3299 Reference Callback</functionlink>, it can also be used | |
| 3300 to prune the graph of traversed references | |
| 3301 (<code>JVMTI_VISIT_OBJECTS</code> is not set). | |
| 3302 | |
| 3303 <constants id="jvmtiHeapVisitControl" | |
| 3304 label="Heap Visit Control Flags" | |
| 3305 kind="bits" | |
| 3306 since="1.1"> | |
| 3307 <constant id="JVMTI_VISIT_OBJECTS" num="0x100"> | |
| 3308 If we are visiting an object and if this callback | |
| 3309 was initiated by <functionlink id="FollowReferences"/>, | |
| 3310 traverse the references of this object. | |
| 3311 Otherwise ignored. | |
| 3312 </constant> | |
| 3313 <constant id="JVMTI_VISIT_ABORT" num="0x8000"> | |
| 3314 Abort the iteration. Ignore all other bits. | |
| 3315 </constant> | |
| 3316 </constants> | |
| 3317 | |
| 3318 <p/> | |
| 3319 The Heap Reference Enumeration is provided by the | |
| 3320 <functionlink id="jvmtiHeapReferenceCallback">Heap | |
| 3321 Reference Callback</functionlink> and | |
| 3322 <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field | |
| 3323 Callback</functionlink> to | |
| 3324 describe the kind of reference | |
| 3325 being reported. | |
| 3326 | |
| 3327 <constants id="jvmtiHeapReferenceKind" | |
| 3328 label="Heap Reference Enumeration" | |
| 3329 kind="enum" | |
| 3330 since="1.1"> | |
| 3331 <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1"> | |
| 3332 Reference from an object to its class. | |
| 3333 </constant> | |
| 3334 <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2"> | |
| 3335 Reference from an object to the value of one of its instance fields. | |
| 3336 </constant> | |
| 3337 <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3"> | |
| 3338 Reference from an array to one of its elements. | |
| 3339 </constant> | |
| 3340 <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4"> | |
| 3341 Reference from a class to its class loader. | |
| 3342 </constant> | |
| 3343 <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5"> | |
| 3344 Reference from a class to its signers array. | |
| 3345 </constant> | |
| 3346 <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6"> | |
| 3347 Reference from a class to its protection domain. | |
| 3348 </constant> | |
| 3349 <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7"> | |
| 3350 Reference from a class to one of its interfaces. | |
| 3351 Note: interfaces are defined via a constant pool reference, | |
| 3352 so the referenced interfaces may also be reported with a | |
| 3353 <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. | |
| 3354 </constant> | |
| 3355 <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8"> | |
| 3356 Reference from a class to the value of one of its static fields. | |
| 3357 </constant> | |
| 3358 <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9"> | |
| 3359 Reference from a class to a resolved entry in the constant pool. | |
| 3360 </constant> | |
| 3361 <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10"> | |
| 3362 Reference from a class to its superclass. | |
| 3363 A callback is bot sent if the superclass is <code>java.lang.Object</code>. | |
| 3364 Note: loaded classes define superclasses via a constant pool | |
| 3365 reference, so the referenced superclass may also be reported with | |
| 3366 a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. | |
| 3367 </constant> | |
| 3368 <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21"> | |
| 3369 Heap root reference: JNI global reference. | |
| 3370 </constant> | |
| 3371 <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22"> | |
| 3372 Heap root reference: System class. | |
| 3373 </constant> | |
| 3374 <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23"> | |
| 3375 Heap root reference: monitor. | |
| 3376 </constant> | |
| 3377 <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24"> | |
| 3378 Heap root reference: local variable on the stack. | |
| 3379 </constant> | |
| 3380 <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25"> | |
| 3381 Heap root reference: JNI local reference. | |
| 3382 </constant> | |
| 3383 <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26"> | |
| 3384 Heap root reference: Thread. | |
| 3385 </constant> | |
| 3386 <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27"> | |
| 3387 Heap root reference: other heap root reference. | |
| 3388 </constant> | |
| 3389 </constants> | |
| 3390 | |
| 3391 <p/> | |
| 3392 Definitions for the single character type descriptors of | |
| 3393 primitive types. | |
| 3394 | |
| 3395 <constants id="jvmtiPrimitiveType" | |
| 3396 label="Primitive Type Enumeration" | |
| 3397 kind="enum" | |
| 3398 since="1.1"> | |
| 3399 <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90"> | |
| 3400 'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code> | |
| 3401 </constant> | |
| 3402 <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66"> | |
| 3403 'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code> | |
| 3404 </constant> | |
| 3405 <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67"> | |
| 3406 'C' - Java programming language <code>char</code> - JNI <code>jchar</code> | |
| 3407 </constant> | |
| 3408 <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83"> | |
| 3409 'S' - Java programming language <code>short</code> - JNI <code>jshort</code> | |
| 3410 </constant> | |
| 3411 <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73"> | |
| 3412 'I' - Java programming language <code>int</code> - JNI <code>jint</code> | |
| 3413 </constant> | |
| 3414 <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74"> | |
| 3415 'J' - Java programming language <code>long</code> - JNI <code>jlong</code> | |
| 3416 </constant> | |
| 3417 <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70"> | |
| 3418 'F' - Java programming language <code>float</code> - JNI <code>jfloat</code> | |
| 3419 </constant> | |
| 3420 <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68"> | |
| 3421 'D' - Java programming language <code>double</code> - JNI <code>jdouble</code> | |
| 3422 </constant> | |
| 3423 </constants> | |
| 3424 </intro> | |
| 3425 | |
| 3426 <typedef id="jvmtiHeapReferenceInfoField" | |
| 3427 label="Reference information structure for Field references" | |
| 3428 since="1.1"> | |
| 3429 <description> | |
| 3430 Reference information returned for | |
| 3431 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and | |
| 3432 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. | |
| 3433 </description> | |
| 3434 <field id="index"> | |
| 3435 <jint/> | |
| 3436 <description> | |
| 3437 For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the | |
| 3438 referrer object is not a class or an inteface. | |
| 3439 In this case, <code>index</code> is the index of the field | |
| 3440 in the class of the referrer object. | |
| 3441 This class is referred to below as <i>C</i>. | |
| 3442 <p/> | |
| 3443 For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, | |
| 3444 the referrer object is a class (referred to below as <i>C</i>) | |
| 3445 or an interface (referred to below as <i>I</i>). | |
| 3446 In this case, <code>index</code> is the index of the field in | |
| 3447 that class or interface. | |
| 3448 <p/> | |
| 3449 If the referrer object is not an interface, then the field | |
| 3450 indices are determined as follows: | |
| 3451 <ul> | |
| 3452 <li>make a list of all the fields in <i>C</i> and its | |
| 3453 superclasses, starting with all the fields in | |
| 3454 <code>java.lang.Object</code> and ending with all the | |
| 3455 fields in <i>C</i>.</li> | |
| 3456 <li>Within this list, put | |
| 3457 the fields for a given class in the order returned by | |
| 3458 <functionlink id="GetClassFields"/>.</li> | |
| 3459 <li>Assign the fields in this list indices | |
| 3460 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> | |
| 3461 is the count of the fields in all the interfaces | |
| 3462 implemented by <i>C</i>. | |
| 3463 Note that <i>C</i> implements all interfaces | |
| 3464 directly implemented by its superclasses; as well | |
| 3465 as all superinterfaces of these interfaces.</li> | |
| 3466 </ul> | |
| 3467 If the referrer object is an interface, then the field | |
| 3468 indices are determined as follows: | |
| 3469 <ul> | |
| 3470 <li>make a list of the fields directly declared in | |
| 3471 <i>I</i>.</li> | |
| 3472 <li>Within this list, put | |
| 3473 the fields in the order returned by | |
| 3474 <functionlink id="GetClassFields"/>.</li> | |
| 3475 <li>Assign the fields in this list indices | |
| 3476 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> | |
| 3477 is the count of the fields in all the superinterfaces | |
| 3478 of <i>I</i>.</li> | |
| 3479 </ul> | |
| 3480 All fields are included in this computation, regardless of | |
| 3481 field modifier (static, public, private, etc). | |
| 3482 <p/> | |
| 3483 For example, given the following classes and interfaces: | |
| 3484 <example> | |
| 3485 interface I0 { | |
| 3486 int p = 0; | |
| 3487 } | |
| 3488 | |
| 3489 interface I1 extends I0 { | |
| 3490 int x = 1; | |
| 3491 } | |
| 3492 | |
| 3493 interface I2 extends I0 { | |
| 3494 int y = 2; | |
| 3495 } | |
| 3496 | |
| 3497 class C1 implements I1 { | |
| 3498 public static int a = 3; | |
| 3499 private int b = 4; | |
| 3500 } | |
| 3501 | |
| 3502 class C2 extends C1 implements I2 { | |
| 3503 static int q = 5; | |
| 3504 final int r = 6; | |
| 3505 } | |
| 3506 </example> | |
| 3507 Assume that <functionlink id="GetClassFields"/> called on | |
| 3508 <code>C1</code> returns the fields of <code>C1</code> in the | |
| 3509 order: a, b; and that the fields of <code>C2</code> are | |
| 3510 returned in the order: q, r. | |
| 3511 An instance of class <code>C1</code> will have the | |
| 3512 following field indices: | |
| 3513 <dl><dd><table> | |
| 3514 <tr> | |
| 3515 <td> | |
| 3516 a | |
| 3517 </td> | |
| 3518 <td> | |
| 3519 2 | |
| 3520 </td> | |
| 3521 <td align="left"> | |
| 3522 The count of the fields in the interfaces | |
| 3523 implemented by <code>C1</code> is two (<i>n</i>=2): | |
| 3524 <code>p</code> of <code>I0</code> | |
| 3525 and <code>x</code> of <code>I1</code>. | |
| 3526 </td> | |
| 3527 </tr> | |
| 3528 <tr> | |
| 3529 <td> | |
| 3530 b | |
| 3531 </td> | |
| 3532 <td> | |
| 3533 3 | |
| 3534 </td> | |
| 3535 <td align="left"> | |
| 3536 the subsequent index. | |
| 3537 </td> | |
| 3538 </tr> | |
| 3539 </table></dd></dl> | |
| 3540 The class <code>C1</code> will have the same field indices. | |
| 3541 <p/> | |
| 3542 An instance of class <code>C2</code> will have the | |
| 3543 following field indices: | |
| 3544 <dl><dd><table> | |
| 3545 <tr> | |
| 3546 <td> | |
| 3547 a | |
| 3548 </td> | |
| 3549 <td> | |
| 3550 3 | |
| 3551 </td> | |
| 3552 <td align="left"> | |
| 3553 The count of the fields in the interfaces | |
| 3554 implemented by <code>C2</code> is three (<i>n</i>=3): | |
| 3555 <code>p</code> of <code>I0</code>, | |
| 3556 <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code> | |
| 3557 (an interface of <code>C2</code>). Note that the field <code>p</code> | |
| 3558 of <code>I0</code> is only included once. | |
| 3559 </td> | |
| 3560 </tr> | |
| 3561 <tr> | |
| 3562 <td> | |
| 3563 b | |
| 3564 </td> | |
| 3565 <td> | |
| 3566 4 | |
| 3567 </td> | |
| 3568 <td align="left"> | |
| 3569 the subsequent index to "a". | |
| 3570 </td> | |
| 3571 </tr> | |
| 3572 <tr> | |
| 3573 <td> | |
| 3574 q | |
| 3575 </td> | |
| 3576 <td> | |
| 3577 5 | |
| 3578 </td> | |
| 3579 <td align="left"> | |
| 3580 the subsequent index to "b". | |
| 3581 </td> | |
| 3582 </tr> | |
| 3583 <tr> | |
| 3584 <td> | |
| 3585 r | |
| 3586 </td> | |
| 3587 <td> | |
| 3588 6 | |
| 3589 </td> | |
| 3590 <td align="left"> | |
| 3591 the subsequent index to "q". | |
| 3592 </td> | |
| 3593 </tr> | |
| 3594 </table></dd></dl> | |
| 3595 The class <code>C2</code> will have the same field indices. | |
| 3596 Note that a field may have a different index depending on the | |
| 3597 object that is viewing it -- for example field "a" above. | |
| 3598 Note also: not all field indices may be visible from the | |
| 3599 callbacks, but all indices are shown for illustrative purposes. | |
| 3600 <p/> | |
| 3601 The interface <code>I1</code> will have the | |
| 3602 following field indices: | |
| 3603 <dl><dd><table> | |
| 3604 <tr> | |
| 3605 <td> | |
| 3606 x | |
| 3607 </td> | |
| 3608 <td> | |
| 3609 1 | |
| 3610 </td> | |
| 3611 <td align="left"> | |
| 3612 The count of the fields in the superinterfaces | |
| 3613 of <code>I1</code> is one (<i>n</i>=1): | |
| 3614 <code>p</code> of <code>I0</code>. | |
| 3615 </td> | |
| 3616 </tr> | |
| 3617 </table></dd></dl> | |
| 3618 </description> | |
| 3619 </field> | |
| 3620 </typedef> | |
| 3621 | |
| 3622 <typedef id="jvmtiHeapReferenceInfoArray" | |
| 3623 label="Reference information structure for Array references" | |
| 3624 since="1.1"> | |
| 3625 <description> | |
| 3626 Reference information returned for | |
| 3627 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. | |
| 3628 </description> | |
| 3629 <field id="index"> | |
| 3630 <jint/> | |
| 3631 <description> | |
| 3632 The array index. | |
| 3633 </description> | |
| 3634 </field> | |
| 3635 </typedef> | |
| 3636 | |
| 3637 <typedef id="jvmtiHeapReferenceInfoConstantPool" | |
| 3638 label="Reference information structure for Constant Pool references" | |
| 3639 since="1.1"> | |
| 3640 <description> | |
| 3641 Reference information returned for | |
| 3642 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. | |
| 3643 </description> | |
| 3644 <field id="index"> | |
| 3645 <jint/> | |
| 3646 <description> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
3647 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
|
3648 <vmspec chapter="4.4"/>. |
| 0 | 3649 </description> |
| 3650 </field> | |
| 3651 </typedef> | |
| 3652 | |
| 3653 <typedef id="jvmtiHeapReferenceInfoStackLocal" | |
| 3654 label="Reference information structure for Local Variable references" | |
| 3655 since="1.1"> | |
| 3656 <description> | |
| 3657 Reference information returned for | |
| 3658 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. | |
| 3659 </description> | |
| 3660 <field id="thread_tag"> | |
| 3661 <jlong/> | |
| 3662 <description> | |
| 3663 The tag of the thread corresponding to this stack, zero if not tagged. | |
| 3664 </description> | |
| 3665 </field> | |
| 3666 <field id="thread_id"> | |
| 3667 <jlong/> | |
| 3668 <description> | |
| 3669 The unique thread ID of the thread corresponding to this stack. | |
| 3670 </description> | |
| 3671 </field> | |
| 3672 <field id="depth"> | |
| 3673 <jint/> | |
| 3674 <description> | |
| 3675 The depth of the frame. | |
| 3676 </description> | |
| 3677 </field> | |
| 3678 <field id="method"> | |
| 3679 <jmethodID/> | |
| 3680 <description> | |
| 3681 The method executing in this frame. | |
| 3682 </description> | |
| 3683 </field> | |
| 3684 <field id="location"> | |
| 3685 <jlocation/> | |
| 3686 <description> | |
| 3687 The currently executing location in this frame. | |
| 3688 </description> | |
| 3689 </field> | |
| 3690 <field id="slot"> | |
| 3691 <jint/> | |
| 3692 <description> | |
| 3693 The slot number of the local variable. | |
| 3694 </description> | |
| 3695 </field> | |
| 3696 </typedef> | |
| 3697 | |
| 3698 <typedef id="jvmtiHeapReferenceInfoJniLocal" | |
| 3699 label="Reference information structure for JNI local references" | |
| 3700 since="1.1"> | |
| 3701 <description> | |
| 3702 Reference information returned for | |
| 3703 <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. | |
| 3704 </description> | |
| 3705 <field id="thread_tag"> | |
| 3706 <jlong/> | |
| 3707 <description> | |
| 3708 The tag of the thread corresponding to this stack, zero if not tagged. | |
| 3709 </description> | |
| 3710 </field> | |
| 3711 <field id="thread_id"> | |
| 3712 <jlong/> | |
| 3713 <description> | |
| 3714 The unique thread ID of the thread corresponding to this stack. | |
| 3715 </description> | |
| 3716 </field> | |
| 3717 <field id="depth"> | |
| 3718 <jint/> | |
| 3719 <description> | |
| 3720 The depth of the frame. | |
| 3721 </description> | |
| 3722 </field> | |
| 3723 <field id="method"> | |
| 3724 <jmethodID/> | |
| 3725 <description> | |
| 3726 The method executing in this frame. | |
| 3727 </description> | |
| 3728 </field> | |
| 3729 </typedef> | |
| 3730 | |
| 3731 <typedef id="jvmtiHeapReferenceInfoReserved" | |
| 3732 label="Reference information structure for Other references" | |
| 3733 since="1.1"> | |
| 3734 <description> | |
| 3735 Reference information returned for other references. | |
| 3736 </description> | |
| 3737 <field id="reserved1"> | |
| 3738 <jlong/> | |
| 3739 <description> | |
| 3740 reserved for future use. | |
| 3741 </description> | |
| 3742 </field> | |
| 3743 <field id="reserved2"> | |
| 3744 <jlong/> | |
| 3745 <description> | |
| 3746 reserved for future use. | |
| 3747 </description> | |
| 3748 </field> | |
| 3749 <field id="reserved3"> | |
| 3750 <jlong/> | |
| 3751 <description> | |
| 3752 reserved for future use. | |
| 3753 </description> | |
| 3754 </field> | |
| 3755 <field id="reserved4"> | |
| 3756 <jlong/> | |
| 3757 <description> | |
| 3758 reserved for future use. | |
| 3759 </description> | |
| 3760 </field> | |
| 3761 <field id="reserved5"> | |
| 3762 <jlong/> | |
| 3763 <description> | |
| 3764 reserved for future use. | |
| 3765 </description> | |
| 3766 </field> | |
| 3767 <field id="reserved6"> | |
| 3768 <jlong/> | |
| 3769 <description> | |
| 3770 reserved for future use. | |
| 3771 </description> | |
| 3772 </field> | |
| 3773 <field id="reserved7"> | |
| 3774 <jlong/> | |
| 3775 <description> | |
| 3776 reserved for future use. | |
| 3777 </description> | |
| 3778 </field> | |
| 3779 <field id="reserved8"> | |
| 3780 <jlong/> | |
| 3781 <description> | |
| 3782 reserved for future use. | |
| 3783 </description> | |
| 3784 </field> | |
| 3785 </typedef> | |
| 3786 | |
| 3787 <uniontypedef id="jvmtiHeapReferenceInfo" | |
| 3788 label="Reference information structure" | |
| 3789 since="1.1"> | |
| 3790 <description> | |
| 3791 The information returned about referrers. | |
| 3792 Represented as a union of the various kinds of reference information. | |
| 3793 </description> | |
| 3794 <field id="field"> | |
| 3795 <struct>jvmtiHeapReferenceInfoField</struct> | |
| 3796 <description> | |
| 3797 The referrer information for | |
| 3798 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> | |
| 3799 and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. | |
| 3800 </description> | |
| 3801 </field> | |
| 3802 <field id="array"> | |
| 3803 <struct>jvmtiHeapReferenceInfoArray</struct> | |
| 3804 <description> | |
| 3805 The referrer information for | |
| 3806 For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. | |
| 3807 </description> | |
| 3808 </field> | |
| 3809 <field id="constant_pool"> | |
| 3810 <struct>jvmtiHeapReferenceInfoConstantPool</struct> | |
| 3811 <description> | |
| 3812 The referrer information for | |
| 3813 For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. | |
| 3814 </description> | |
| 3815 </field> | |
| 3816 <field id="stack_local"> | |
| 3817 <struct>jvmtiHeapReferenceInfoStackLocal</struct> | |
| 3818 <description> | |
| 3819 The referrer information for | |
| 3820 For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. | |
| 3821 </description> | |
| 3822 </field> | |
| 3823 <field id="jni_local"> | |
| 3824 <struct>jvmtiHeapReferenceInfoJniLocal</struct> | |
| 3825 <description> | |
| 3826 The referrer information for | |
| 3827 For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. | |
| 3828 </description> | |
| 3829 </field> | |
| 3830 <field id="other"> | |
| 3831 <struct>jvmtiHeapReferenceInfoReserved</struct> | |
| 3832 <description> | |
| 3833 reserved for future use. | |
| 3834 </description> | |
| 3835 </field> | |
| 3836 </uniontypedef> | |
| 3837 | |
| 3838 <typedef id="jvmtiHeapCallbacks" | |
| 3839 label="Heap callback function structure" | |
| 3840 since="1.1"> | |
| 3841 <field id="heap_iteration_callback"> | |
| 3842 <ptrtype> | |
| 3843 <struct>jvmtiHeapIterationCallback</struct> | |
| 3844 </ptrtype> | |
| 3845 <description> | |
| 3846 The callback to be called to describe an | |
| 3847 object in the heap. Used by the | |
| 3848 <functionlink id="IterateThroughHeap"/> function, ignored by the | |
| 3849 <functionlink id="FollowReferences"/> function. | |
| 3850 </description> | |
| 3851 </field> | |
| 3852 <field id="heap_reference_callback"> | |
| 3853 <ptrtype> | |
| 3854 <struct>jvmtiHeapReferenceCallback</struct> | |
| 3855 </ptrtype> | |
| 3856 <description> | |
| 3857 The callback to be called to describe an | |
| 3858 object reference. Used by the | |
| 3859 <functionlink id="FollowReferences"/> function, ignored by the | |
| 3860 <functionlink id="IterateThroughHeap"/> function. | |
| 3861 </description> | |
| 3862 </field> | |
| 3863 <field id="primitive_field_callback"> | |
| 3864 <ptrtype> | |
| 3865 <struct>jvmtiPrimitiveFieldCallback</struct> | |
| 3866 </ptrtype> | |
| 3867 <description> | |
| 3868 The callback to be called to describe a | |
| 3869 primitive field. | |
| 3870 </description> | |
| 3871 </field> | |
| 3872 <field id="array_primitive_value_callback"> | |
| 3873 <ptrtype> | |
| 3874 <struct>jvmtiArrayPrimitiveValueCallback</struct> | |
| 3875 </ptrtype> | |
| 3876 <description> | |
| 3877 The callback to be called to describe an | |
| 3878 array of primitive values. | |
| 3879 </description> | |
| 3880 </field> | |
| 3881 <field id="string_primitive_value_callback"> | |
| 3882 <ptrtype> | |
| 3883 <struct>jvmtiStringPrimitiveValueCallback</struct> | |
| 3884 </ptrtype> | |
| 3885 <description> | |
| 3886 The callback to be called to describe a String value. | |
| 3887 </description> | |
| 3888 </field> | |
| 3889 <field id="reserved5"> | |
| 3890 <ptrtype> | |
| 3891 <struct>jvmtiReservedCallback</struct> | |
| 3892 </ptrtype> | |
| 3893 <description> | |
| 3894 Reserved for future use.. | |
| 3895 </description> | |
| 3896 </field> | |
| 3897 <field id="reserved6"> | |
| 3898 <ptrtype> | |
| 3899 <struct>jvmtiReservedCallback</struct> | |
| 3900 </ptrtype> | |
| 3901 <description> | |
| 3902 Reserved for future use.. | |
| 3903 </description> | |
| 3904 </field> | |
| 3905 <field id="reserved7"> | |
| 3906 <ptrtype> | |
| 3907 <struct>jvmtiReservedCallback</struct> | |
| 3908 </ptrtype> | |
| 3909 <description> | |
| 3910 Reserved for future use.. | |
| 3911 </description> | |
| 3912 </field> | |
| 3913 <field id="reserved8"> | |
| 3914 <ptrtype> | |
| 3915 <struct>jvmtiReservedCallback</struct> | |
| 3916 </ptrtype> | |
| 3917 <description> | |
| 3918 Reserved for future use.. | |
| 3919 </description> | |
| 3920 </field> | |
| 3921 <field id="reserved9"> | |
| 3922 <ptrtype> | |
| 3923 <struct>jvmtiReservedCallback</struct> | |
| 3924 </ptrtype> | |
| 3925 <description> | |
| 3926 Reserved for future use.. | |
| 3927 </description> | |
| 3928 </field> | |
| 3929 <field id="reserved10"> | |
| 3930 <ptrtype> | |
| 3931 <struct>jvmtiReservedCallback</struct> | |
| 3932 </ptrtype> | |
| 3933 <description> | |
| 3934 Reserved for future use.. | |
| 3935 </description> | |
| 3936 </field> | |
| 3937 <field id="reserved11"> | |
| 3938 <ptrtype> | |
| 3939 <struct>jvmtiReservedCallback</struct> | |
| 3940 </ptrtype> | |
| 3941 <description> | |
| 3942 Reserved for future use.. | |
| 3943 </description> | |
| 3944 </field> | |
| 3945 <field id="reserved12"> | |
| 3946 <ptrtype> | |
| 3947 <struct>jvmtiReservedCallback</struct> | |
| 3948 </ptrtype> | |
| 3949 <description> | |
| 3950 Reserved for future use.. | |
| 3951 </description> | |
| 3952 </field> | |
| 3953 <field id="reserved13"> | |
| 3954 <ptrtype> | |
| 3955 <struct>jvmtiReservedCallback</struct> | |
| 3956 </ptrtype> | |
| 3957 <description> | |
| 3958 Reserved for future use.. | |
| 3959 </description> | |
| 3960 </field> | |
| 3961 <field id="reserved14"> | |
| 3962 <ptrtype> | |
| 3963 <struct>jvmtiReservedCallback</struct> | |
| 3964 </ptrtype> | |
| 3965 <description> | |
| 3966 Reserved for future use.. | |
| 3967 </description> | |
| 3968 </field> | |
| 3969 <field id="reserved15"> | |
| 3970 <ptrtype> | |
| 3971 <struct>jvmtiReservedCallback</struct> | |
| 3972 </ptrtype> | |
| 3973 <description> | |
| 3974 Reserved for future use.. | |
| 3975 </description> | |
| 3976 </field> | |
| 3977 </typedef> | |
| 3978 | |
| 3979 | |
| 3980 <intro> | |
| 3981 <rationale> | |
| 3982 The heap dumping functionality (below) uses a callback | |
| 3983 for each object. While it would seem that a buffered approach | |
| 3984 would provide better throughput, tests do | |
| 3985 not show this to be the case--possibly due to locality of | |
| 3986 memory reference or array access overhead. | |
| 3987 </rationale> | |
| 3988 | |
| 3989 <issue> | |
| 3990 Still under investigation as to if java.lang.ref references | |
| 3991 are reported as a different type of reference. | |
| 3992 </issue> | |
| 3993 | |
| 3994 <issue> | |
| 3995 Should or can an indication of the cost or relative cost of | |
| 3996 these operations be included? | |
| 3997 </issue> | |
| 3998 | |
| 3999 </intro> | |
| 4000 | |
| 4001 <callback id="jvmtiHeapIterationCallback" since="1.1"> | |
| 4002 <jint/> | |
| 4003 <synopsis>Heap Iteration Callback</synopsis> | |
| 4004 <description> | |
| 4005 Agent supplied callback function. | |
| 4006 Describes (but does not pass in) an object in the heap. | |
| 4007 <p/> | |
| 4008 This function should return a bit vector of the desired | |
| 4009 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4010 This will determine if the entire iteration should be aborted | |
| 4011 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4012 <p/> | |
| 4013 See the <internallink id="heapCallbacks">heap callback | |
| 4014 function restrictions</internallink>. | |
| 4015 </description> | |
| 4016 <parameters> | |
| 4017 <param id="class_tag"> | |
| 4018 <jlong/> | |
| 4019 <description> | |
| 4020 The tag of the class of object (zero if the class is not tagged). | |
| 4021 If the object represents a runtime class, | |
| 4022 the <code>class_tag</code> is the tag | |
| 4023 associated with <code>java.lang.Class</code> | |
| 4024 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4025 </description> | |
| 4026 </param> | |
| 4027 <param id="size"> | |
| 4028 <jlong/> | |
| 4029 <description> | |
| 4030 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 4031 </description> | |
| 4032 </param> | |
| 4033 <param id="tag_ptr"> | |
| 4034 <outptr><jlong/></outptr> | |
| 4035 <description> | |
| 4036 The object tag value, or zero if the object is not tagged. | |
| 4037 To set the tag value to be associated with the object | |
| 4038 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4039 </description> | |
| 4040 </param> | |
| 4041 <param id="length"> | |
| 4042 <jint/> | |
| 4043 <description> | |
| 4044 If this object is an array, the length of the array. Otherwise negative one (-1). | |
| 4045 </description> | |
| 4046 </param> | |
| 4047 <param id="user_data"> | |
| 4048 <outptr><void/></outptr> | |
| 4049 <description> | |
| 4050 The user supplied data that was passed into the iteration function. | |
| 4051 </description> | |
| 4052 </param> | |
| 4053 </parameters> | |
| 4054 </callback> | |
| 4055 | |
| 4056 <callback id="jvmtiHeapReferenceCallback" since="1.1"> | |
| 4057 <jint/> | |
| 4058 <synopsis>Heap Reference Callback</synopsis> | |
| 4059 <description> | |
| 4060 Agent supplied callback function. | |
| 4061 Describes a reference from an object or the VM (the referrer) to another object | |
| 4062 (the referree) or a heap root to a referree. | |
| 4063 <p/> | |
| 4064 This function should return a bit vector of the desired | |
| 4065 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4066 This will determine if the objects referenced by the referree | |
| 4067 should be visited or if the entire iteration should be aborted. | |
| 4068 <p/> | |
| 4069 See the <internallink id="heapCallbacks">heap callback | |
| 4070 function restrictions</internallink>. | |
| 4071 </description> | |
| 4072 <parameters> | |
| 4073 <param id="reference_kind"> | |
| 4074 <enum>jvmtiHeapReferenceKind</enum> | |
| 4075 <description> | |
| 4076 The kind of reference. | |
| 4077 </description> | |
| 4078 </param> | |
| 4079 <param id="reference_info"> | |
| 4080 <inptr> | |
| 4081 <struct>jvmtiHeapReferenceInfo</struct> | |
| 4082 </inptr> | |
| 4083 <description> | |
| 4084 Details about the reference. | |
| 6919 | 4085 Set when the <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> is |
| 0 | 4086 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, |
| 4087 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, | |
| 4088 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>, | |
| 4089 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>, | |
| 4090 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>, | |
| 4091 or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>. | |
| 4092 Otherwise <code>NULL</code>. | |
| 4093 </description> | |
| 4094 </param> | |
| 4095 <param id="class_tag"> | |
| 4096 <jlong/> | |
| 4097 <description> | |
| 4098 The tag of the class of referree object (zero if the class is not tagged). | |
| 4099 If the referree object represents a runtime class, | |
| 4100 the <code>class_tag</code> is the tag | |
| 4101 associated with <code>java.lang.Class</code> | |
| 4102 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4103 </description> | |
| 4104 </param> | |
| 4105 <param id="referrer_class_tag"> | |
| 4106 <jlong/> | |
| 4107 <description> | |
| 4108 The tag of the class of the referrer object (zero if the class is not tagged | |
| 4109 or the referree is a heap root). If the referrer object represents a runtime | |
| 4110 class, the <code>referrer_class_tag</code> is the tag associated with | |
| 4111 the <code>java.lang.Class</code> | |
| 4112 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4113 </description> | |
| 4114 </param> | |
| 4115 <param id="size"> | |
| 4116 <jlong/> | |
| 4117 <description> | |
| 4118 Size of the referree object (in bytes). | |
| 4119 See <functionlink id="GetObjectSize"/>. | |
| 4120 </description> | |
| 4121 </param> | |
| 4122 <param id="tag_ptr"> | |
| 4123 <outptr><jlong/></outptr> | |
| 4124 <description> | |
| 4125 Points to the referree object tag value, or zero if the object is not | |
| 4126 tagged. | |
| 4127 To set the tag value to be associated with the object | |
| 4128 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4129 </description> | |
| 4130 </param> | |
| 4131 <param id="referrer_tag_ptr"> | |
| 4132 <outptr><jlong/></outptr> | |
| 4133 <description> | |
| 4134 Points to the tag of the referrer object, or | |
| 4135 points to the zero if the referrer | |
| 4136 object is not tagged. | |
| 4137 <code>NULL</code> if the referrer in not an object (that is, | |
| 4138 this callback is reporting a heap root). | |
| 4139 To set the tag value to be associated with the referrer object | |
| 4140 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4141 If this callback is reporting a reference from an object to itself, | |
| 4142 <code>referrer_tag_ptr == tag_ptr</code>. | |
| 4143 </description> | |
| 4144 </param> | |
| 4145 <param id="length"> | |
| 4146 <jint/> | |
| 4147 <description> | |
| 4148 If this object is an array, the length of the array. Otherwise negative one (-1). | |
| 4149 </description> | |
| 4150 </param> | |
| 4151 <param id="user_data"> | |
| 4152 <outptr><void/></outptr> | |
| 4153 <description> | |
| 4154 The user supplied data that was passed into the iteration function. | |
| 4155 </description> | |
| 4156 </param> | |
| 4157 </parameters> | |
| 4158 </callback> | |
| 4159 | |
| 4160 <callback id="jvmtiPrimitiveFieldCallback" since="1.1"> | |
| 4161 <jint/> | |
| 4162 <synopsis>Primitive Field Callback</synopsis> | |
| 4163 <description> | |
| 4164 Agent supplied callback function which | |
| 4165 describes a primitive field of an object (<i>the object</i>). | |
| 4166 A primitive field is a field whose type is a primitive type. | |
| 4167 This callback will describe a static field if the object is a class, | |
| 4168 and otherwise will describe an instance field. | |
| 4169 <p/> | |
| 4170 This function should return a bit vector of the desired | |
| 4171 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4172 This will determine if the entire iteration should be aborted | |
| 4173 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4174 <p/> | |
| 4175 See the <internallink id="heapCallbacks">heap callback | |
| 4176 function restrictions</internallink>. | |
| 4177 </description> | |
| 4178 <parameters> | |
| 4179 <param id="kind"> | |
| 4180 <enum>jvmtiHeapReferenceKind</enum> | |
| 4181 <description> | |
| 4182 The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or | |
| 4183 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>). | |
| 4184 </description> | |
| 4185 </param> | |
| 4186 <param id="info"> | |
| 4187 <inptr> | |
| 4188 <struct>jvmtiHeapReferenceInfo</struct> | |
| 4189 </inptr> | |
| 4190 <description> | |
| 4191 Which field (the field index). | |
| 4192 </description> | |
| 4193 </param> | |
| 4194 <param id="object_class_tag"> | |
| 4195 <jlong/> | |
| 4196 <description> | |
| 4197 The tag of the class of the object (zero if the class is not tagged). | |
| 4198 If the object represents a runtime class, the | |
| 4199 <code>object_class_tag</code> is the tag | |
| 4200 associated with <code>java.lang.Class</code> | |
| 4201 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4202 </description> | |
| 4203 </param> | |
| 4204 <param id="object_tag_ptr"> | |
| 4205 <outptr><jlong/></outptr> | |
| 4206 <description> | |
| 4207 Points to the tag of the object, or zero if the object is not | |
| 4208 tagged. | |
| 4209 To set the tag value to be associated with the object | |
| 4210 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4211 </description> | |
| 4212 </param> | |
| 4213 <param id="value"> | |
| 4214 <jvalue/> | |
| 4215 <description> | |
| 4216 The value of the field. | |
| 4217 </description> | |
| 4218 </param> | |
| 4219 <param id="value_type"> | |
| 4220 <enum>jvmtiPrimitiveType</enum> | |
| 4221 <description> | |
| 4222 The type of the field. | |
| 4223 </description> | |
| 4224 </param> | |
| 4225 <param id="user_data"> | |
| 4226 <outptr><void/></outptr> | |
| 4227 <description> | |
| 4228 The user supplied data that was passed into the iteration function. | |
| 4229 </description> | |
| 4230 </param> | |
| 4231 </parameters> | |
| 4232 </callback> | |
| 4233 | |
| 4234 <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1"> | |
| 4235 <jint/> | |
| 4236 <synopsis>Array Primitive Value Callback</synopsis> | |
| 4237 <description> | |
| 4238 Agent supplied callback function. | |
| 4239 Describes the values in an array of a primitive type. | |
| 4240 <p/> | |
| 4241 This function should return a bit vector of the desired | |
| 4242 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4243 This will determine if the entire iteration should be aborted | |
| 4244 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4245 <p/> | |
| 4246 See the <internallink id="heapCallbacks">heap callback | |
| 4247 function restrictions</internallink>. | |
| 4248 </description> | |
| 4249 <parameters> | |
| 4250 <param id="class_tag"> | |
| 4251 <jlong/> | |
| 4252 <description> | |
| 4253 The tag of the class of the array object (zero if the class is not tagged). | |
| 4254 </description> | |
| 4255 </param> | |
| 4256 <param id="size"> | |
| 4257 <jlong/> | |
| 4258 <description> | |
| 4259 Size of the array (in bytes). | |
| 4260 See <functionlink id="GetObjectSize"/>. | |
| 4261 </description> | |
| 4262 </param> | |
| 4263 <param id="tag_ptr"> | |
| 4264 <outptr><jlong/></outptr> | |
| 4265 <description> | |
| 4266 Points to the tag of the array object, or zero if the object is not | |
| 4267 tagged. | |
| 4268 To set the tag value to be associated with the object | |
| 4269 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4270 </description> | |
| 4271 </param> | |
| 4272 <param id="element_count"> | |
| 4273 <jint/> | |
| 4274 <description> | |
| 4275 The length of the primitive array. | |
| 4276 </description> | |
| 4277 </param> | |
| 4278 <param id="element_type"> | |
| 4279 <enum>jvmtiPrimitiveType</enum> | |
| 4280 <description> | |
| 4281 The type of the elements of the array. | |
| 4282 </description> | |
| 4283 </param> | |
| 4284 <param id="elements"> | |
| 4285 <vmbuf><void/></vmbuf> | |
| 4286 <description> | |
| 4287 The elements of the array in a packed array of <code>element_count</code> | |
| 4288 items of <code>element_type</code> size each. | |
| 4289 </description> | |
| 4290 </param> | |
| 4291 <param id="user_data"> | |
| 4292 <outptr><void/></outptr> | |
| 4293 <description> | |
| 4294 The user supplied data that was passed into the iteration function. | |
| 4295 </description> | |
| 4296 </param> | |
| 4297 </parameters> | |
| 4298 </callback> | |
| 4299 | |
| 4300 <callback id="jvmtiStringPrimitiveValueCallback" since="1.1"> | |
| 4301 <jint/> | |
| 4302 <synopsis>String Primitive Value Callback</synopsis> | |
| 4303 <description> | |
| 4304 Agent supplied callback function. | |
| 4305 Describes the value of a java.lang.String. | |
| 4306 <p/> | |
| 4307 This function should return a bit vector of the desired | |
| 4308 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4309 This will determine if the entire iteration should be aborted | |
| 4310 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4311 <p/> | |
| 4312 See the <internallink id="heapCallbacks">heap callback | |
| 4313 function restrictions</internallink>. | |
| 4314 </description> | |
| 4315 <parameters> | |
| 4316 <param id="class_tag"> | |
| 4317 <jlong/> | |
| 4318 <description> | |
| 4319 The tag of the class of the String class (zero if the class is not tagged). | |
| 4320 <issue>Is this needed?</issue> | |
| 4321 </description> | |
| 4322 </param> | |
| 4323 <param id="size"> | |
| 4324 <jlong/> | |
| 4325 <description> | |
| 4326 Size of the string (in bytes). | |
| 4327 See <functionlink id="GetObjectSize"/>. | |
| 4328 </description> | |
| 4329 </param> | |
| 4330 <param id="tag_ptr"> | |
| 4331 <outptr><jlong/></outptr> | |
| 4332 <description> | |
| 4333 Points to the tag of the String object, or zero if the object is not | |
| 4334 tagged. | |
| 4335 To set the tag value to be associated with the object | |
| 4336 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4337 </description> | |
| 4338 </param> | |
| 4339 <param id="value"> | |
| 4340 <vmbuf><jchar/></vmbuf> | |
| 4341 <description> | |
| 4342 The value of the String, encoded as a Unicode string. | |
| 4343 </description> | |
| 4344 </param> | |
| 4345 <param id="value_length"> | |
| 4346 <jint/> | |
| 4347 <description> | |
| 4348 The length of the string. | |
| 4349 The length is equal to the number of 16-bit Unicode | |
| 4350 characters in the string. | |
| 4351 </description> | |
| 4352 </param> | |
| 4353 <param id="user_data"> | |
| 4354 <outptr><void/></outptr> | |
| 4355 <description> | |
| 4356 The user supplied data that was passed into the iteration function. | |
| 4357 </description> | |
| 4358 </param> | |
| 4359 </parameters> | |
| 4360 </callback> | |
| 4361 | |
| 4362 | |
| 4363 <callback id="jvmtiReservedCallback" since="1.1"> | |
| 4364 <jint/> | |
| 4365 <synopsis>reserved for future use Callback</synopsis> | |
| 4366 <description> | |
| 4367 Placeholder -- reserved for future use. | |
| 4368 </description> | |
| 4369 <parameters> | |
| 4370 </parameters> | |
| 4371 </callback> | |
| 4372 | |
| 4373 <function id="FollowReferences" num="115" since="1.1"> | |
| 4374 <synopsis>Follow References</synopsis> | |
| 4375 <description> | |
| 4376 This function initiates a traversal over the objects that are | |
| 4377 directly and indirectly reachable from the specified object or, | |
| 4378 if <code>initial_object</code> is not specified, all objects | |
| 4379 reachable from the heap roots. | |
| 4380 The heap root are the set of system classes, | |
| 4381 JNI globals, references from thread stacks, and other objects used as roots | |
| 4382 for the purposes of garbage collection. | |
| 4383 <p/> | |
| 4384 This function operates by traversing the reference graph. | |
| 4385 Let <i>A</i>, <i>B</i>, ... represent objects. | |
| 4386 When a reference from <i>A</i> to <i>B</i> is traversed, | |
| 4387 when a reference from a heap root to <i>B</i> is traversed, | |
| 4388 or when <i>B</i> is specified as the <paramlink id="initial_object"/>, | |
| 4389 then <i>B</i> is said to be <i>visited</i>. | |
| 4390 A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i> | |
| 4391 is visited. | |
| 4392 References are reported in the same order that the references are traversed. | |
| 4393 Object references are reported by invoking the agent supplied | |
| 4394 callback function <functionlink id="jvmtiHeapReferenceCallback"/>. | |
| 4395 In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known | |
| 4396 as the <i>referrer</i> and <i>B</i> as the <i>referree</i>. | |
| 4397 The callback is invoked exactly once for each reference from a referrer; | |
| 4398 this is true even if there are reference cycles or multiple paths to | |
| 4399 the referrer. | |
| 4400 There may be more than one reference between a referrer and a referree, | |
| 4401 each reference is reported. | |
| 4402 These references may be distinguished by examining the | |
| 4403 <datalink | |
| 4404 id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink> | |
| 4405 and | |
| 4406 <datalink | |
| 4407 id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink> | |
| 4408 parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback. | |
| 4409 <p/> | |
| 4410 This function reports a Java programming language view of object references, | |
| 4411 not a virtual machine implementation view. The following object references | |
| 4412 are reported when they are non-null: | |
| 4413 <ul> | |
| 4414 <li>Instance objects report references to each non-primitive instance fields | |
| 4415 (including inherited fields).</li> | |
| 4416 <li>Instance objects report a reference to the object type (class).</li> | |
| 4417 <li>Classes report a reference to the superclass and directly | |
| 4418 implemented/extended interfaces.</li> | |
| 4419 <li>Classes report a reference to the class loader, protection domain, | |
| 4420 signers, and resolved entries in the constant pool.</li> | |
| 4421 <li>Classes report a reference to each directly declared non-primitive | |
| 4422 static field.</li> | |
| 4423 <li>Arrays report a reference to the array type (class) and each | |
| 4424 array element.</li> | |
| 4425 <li>Primitive arrays report a reference to the array type.</li> | |
| 4426 </ul> | |
| 4427 <p/> | |
| 4428 This function can also be used to examine primitive (non-object) values. | |
| 4429 The primitive value of an array or String | |
| 4430 is reported after the object has been visited; | |
| 4431 it is reported by invoking the agent supplied callback function | |
| 4432 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or | |
| 4433 <functionlink id="jvmtiStringPrimitiveValueCallback"/>. | |
| 4434 A primitive field | |
| 4435 is reported after the object with that field is visited; | |
| 4436 it is reported by invoking the agent supplied callback function | |
| 4437 <functionlink id="jvmtiPrimitiveFieldCallback"/>. | |
| 4438 <p/> | |
| 4439 Whether a callback is provided or is <code>NULL</code> only determines | |
| 4440 whether the callback will be invoked, it does not influence | |
| 4441 which objects are visited nor does it influence whether other callbacks | |
| 4442 will be invoked. | |
| 4443 However, the | |
| 4444 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink> | |
| 4445 returned by <functionlink id="jvmtiHeapReferenceCallback"/> | |
| 4446 do determine if the objects referenced by the | |
| 4447 current object as visited. | |
| 4448 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> | |
| 4449 and <paramlink id="klass"/> provided as parameters to this function | |
| 4450 do not control which objects are visited but they do control which | |
| 4451 objects and primitive values are reported by the callbacks. | |
| 4452 For example, if the only callback that was set is | |
| 6919 | 4453 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code> |
| 0 | 4454 is set to the array of bytes class, then only arrays of byte will be |
| 4455 reported. | |
| 4456 The table below summarizes this: | |
| 4457 <p/> | |
| 4458 <table> | |
| 4459 <tr> | |
| 4460 <th/> | |
| 4461 <th> | |
| 4462 Controls objects visited | |
| 4463 </th> | |
| 4464 <th> | |
| 4465 Controls objects reported | |
| 4466 </th> | |
| 4467 <th> | |
| 4468 Controls primitives reported | |
| 4469 </th> | |
| 4470 </tr> | |
| 4471 <tr> | |
| 4472 <th align="left"> | |
| 4473 the | |
| 4474 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
| 4475 returned by <functionlink id="jvmtiHeapReferenceCallback"/> | |
| 4476 </th> | |
| 4477 <td> | |
| 4478 <b>Yes</b> | |
| 4479 </td> | |
| 4480 <td> | |
| 4481 <b>Yes</b>, since visits are controlled | |
| 4482 </td> | |
| 4483 <td> | |
| 4484 <b>Yes</b>, since visits are controlled | |
| 4485 </td> | |
| 4486 </tr> | |
| 4487 <tr> | |
| 4488 <th align="left"> | |
| 6919 | 4489 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> |
| 0 | 4490 in <paramlink id="callbacks"/> set |
| 4491 </th> | |
| 4492 <td> | |
| 4493 No | |
| 4494 </td> | |
| 4495 <td> | |
| 4496 <b>Yes</b> | |
| 4497 </td> | |
| 4498 <td> | |
| 4499 No | |
| 4500 </td> | |
| 4501 </tr> | |
| 4502 <tr> | |
| 4503 <th align="left"> | |
| 4504 <paramlink id="heap_filter"/> | |
| 4505 </th> | |
| 4506 <td> | |
| 4507 No | |
| 4508 </td> | |
| 4509 <td> | |
| 4510 <b>Yes</b> | |
| 4511 </td> | |
| 4512 <td> | |
| 4513 <b>Yes</b> | |
| 4514 </td> | |
| 4515 </tr> | |
| 4516 <tr> | |
| 4517 <th align="left"> | |
| 4518 <paramlink id="klass"/> | |
| 4519 </th> | |
| 4520 <td> | |
| 4521 No | |
| 4522 </td> | |
| 4523 <td> | |
| 4524 <b>Yes</b> | |
| 4525 </td> | |
| 4526 <td> | |
| 4527 <b>Yes</b> | |
| 4528 </td> | |
| 4529 </tr> | |
| 4530 </table> | |
| 4531 <p/> | |
| 4532 During the execution of this function the state of the heap | |
| 4533 does not change: no objects are allocated, no objects are | |
| 4534 garbage collected, and the state of objects (including | |
| 4535 held values) does not change. | |
| 4536 As a result, threads executing Java | |
| 4537 programming language code, threads attempting to resume the | |
| 4538 execution of Java programming language code, and threads | |
| 4539 attempting to execute JNI functions are typically stalled. | |
| 4540 </description> | |
| 4541 <origin>new</origin> | |
| 4542 <capabilities> | |
| 4543 <required id="can_tag_objects"></required> | |
| 4544 </capabilities> | |
| 4545 <parameters> | |
| 4546 <param id="heap_filter"> | |
| 4547 <jint/> | |
| 4548 <description> | |
| 4549 This bit vector of | |
| 4550 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>. | |
| 4551 restricts the objects for which the callback function is called. | |
| 4552 This applies to both the object and primitive callbacks. | |
| 4553 </description> | |
| 4554 </param> | |
| 4555 <param id="klass"> | |
| 4556 <ptrtype> | |
| 4557 <jclass/> | |
| 4558 <nullok>callbacks are not limited to instances of a particular | |
| 4559 class</nullok> | |
| 4560 </ptrtype> | |
| 4561 <description> | |
| 4562 Callbacks are only reported when the object is an instance of | |
| 4563 this class. | |
| 4564 Objects which are instances of a subclass of <code>klass</code> | |
| 4565 are not reported. | |
| 4566 If <code>klass</code> is an interface, no objects are reported. | |
| 4567 This applies to both the object and primitive callbacks. | |
| 4568 </description> | |
| 4569 </param> | |
| 4570 <param id="initial_object"> | |
| 4571 <ptrtype> | |
| 4572 <jobject/> | |
| 4573 <nullok>references are followed from the heap roots</nullok> | |
| 4574 </ptrtype> | |
| 4575 <description> | |
| 4576 The object to follow | |
| 4577 </description> | |
| 4578 </param> | |
| 4579 <param id="callbacks"> | |
| 4580 <inptr> | |
| 4581 <struct>jvmtiHeapCallbacks</struct> | |
| 4582 </inptr> | |
| 4583 <description> | |
| 4584 Structure defining the set of callback functions. | |
| 4585 </description> | |
| 4586 </param> | |
| 4587 <param id="user_data"> | |
| 4588 <inbuf> | |
| 4589 <void/> | |
| 4590 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 4591 </inbuf> | |
| 4592 <description> | |
| 4593 User supplied data to be passed to the callback. | |
| 4594 </description> | |
| 4595 </param> | |
| 4596 </parameters> | |
| 4597 <errors> | |
| 4598 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 4599 <paramlink id="klass"/> is not a valid class. | |
| 4600 </error> | |
| 4601 <error id="JVMTI_ERROR_INVALID_OBJECT"> | |
| 4602 <paramlink id="initial_object"/> is not a valid object. | |
| 4603 </error> | |
| 4604 </errors> | |
| 4605 </function> | |
| 4606 | |
| 4607 | |
| 4608 <function id="IterateThroughHeap" num="116" since="1.1"> | |
| 4609 <synopsis>Iterate Through Heap</synopsis> | |
| 4610 <description> | |
| 4611 Initiate an iteration over all objects in the heap. | |
| 4612 This includes both reachable and | |
| 4613 unreachable objects. Objects are visited in no particular order. | |
| 4614 <p/> | |
| 4615 Heap objects are reported by invoking the agent supplied | |
| 4616 callback function <functionlink id="jvmtiHeapIterationCallback"/>. | |
| 4617 References between objects are not reported. | |
| 4618 If only reachable objects are desired, or if object reference information | |
| 4619 is needed, use <functionlink id="FollowReferences"/>. | |
| 4620 <p/> | |
| 4621 This function can also be used to examine primitive (non-object) values. | |
| 4622 The primitive value of an array or String | |
| 4623 is reported after the object has been visited; | |
| 4624 it is reported by invoking the agent supplied callback function | |
| 4625 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or | |
| 4626 <functionlink id="jvmtiStringPrimitiveValueCallback"/>. | |
| 4627 A primitive field | |
| 4628 is reported after the object with that field is visited; | |
| 4629 it is reported by invoking the agent supplied | |
| 4630 callback function | |
| 4631 <functionlink id="jvmtiPrimitiveFieldCallback"/>. | |
| 4632 <p/> | |
| 4633 Unless the iteration is aborted by the | |
| 4634 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
| 4635 returned by a callback, all objects in the heap are visited. | |
| 4636 Whether a callback is provided or is <code>NULL</code> only determines | |
| 4637 whether the callback will be invoked, it does not influence | |
| 4638 which objects are visited nor does it influence whether other callbacks | |
| 4639 will be invoked. | |
| 4640 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> | |
| 4641 and <paramlink id="klass"/> provided as parameters to this function | |
| 4642 do not control which objects are visited but they do control which | |
| 4643 objects and primitive values are reported by the callbacks. | |
| 4644 For example, if the only callback that was set is | |
| 6919 | 4645 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code> |
| 0 | 4646 is set to the array of bytes class, then only arrays of byte will be |
| 4647 reported. The table below summarizes this (contrast this with | |
| 4648 <functionlink id="FollowReferences"/>): | |
| 4649 <p/> | |
| 4650 <table> | |
| 4651 <tr> | |
| 4652 <th/> | |
| 4653 <th> | |
| 4654 Controls objects visited | |
| 4655 </th> | |
| 4656 <th> | |
| 4657 Controls objects reported | |
| 4658 </th> | |
| 4659 <th> | |
| 4660 Controls primitives reported | |
| 4661 </th> | |
| 4662 </tr> | |
| 4663 <tr> | |
| 4664 <th align="left"> | |
| 4665 the | |
| 4666 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
| 4667 returned by <functionlink id="jvmtiHeapIterationCallback"/> | |
| 4668 </th> | |
| 4669 <td> | |
| 4670 No<br/>(unless they abort the iteration) | |
| 4671 </td> | |
| 4672 <td> | |
| 4673 No<br/>(unless they abort the iteration) | |
| 4674 </td> | |
| 4675 <td> | |
| 4676 No<br/>(unless they abort the iteration) | |
| 4677 </td> | |
| 4678 </tr> | |
| 4679 <tr> | |
| 4680 <th align="left"> | |
| 6919 | 4681 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> |
| 0 | 4682 in <paramlink id="callbacks"/> set |
| 4683 </th> | |
| 4684 <td> | |
| 4685 No | |
| 4686 </td> | |
| 4687 <td> | |
| 4688 <b>Yes</b> | |
| 4689 </td> | |
| 4690 <td> | |
| 4691 No | |
| 4692 </td> | |
| 4693 </tr> | |
| 4694 <tr> | |
| 4695 <th align="left"> | |
| 4696 <paramlink id="heap_filter"/> | |
| 4697 </th> | |
| 4698 <td> | |
| 4699 No | |
| 4700 </td> | |
| 4701 <td> | |
| 4702 <b>Yes</b> | |
| 4703 </td> | |
| 4704 <td> | |
| 4705 <b>Yes</b> | |
| 4706 </td> | |
| 4707 </tr> | |
| 4708 <tr> | |
| 4709 <th align="left"> | |
| 4710 <paramlink id="klass"/> | |
| 4711 </th> | |
| 4712 <td> | |
| 4713 No | |
| 4714 </td> | |
| 4715 <td> | |
| 4716 <b>Yes</b> | |
| 4717 </td> | |
| 4718 <td> | |
| 4719 <b>Yes</b> | |
| 4720 </td> | |
| 4721 </tr> | |
| 4722 </table> | |
| 4723 <p/> | |
| 4724 During the execution of this function the state of the heap | |
| 4725 does not change: no objects are allocated, no objects are | |
| 4726 garbage collected, and the state of objects (including | |
| 4727 held values) does not change. | |
| 4728 As a result, threads executing Java | |
| 4729 programming language code, threads attempting to resume the | |
| 4730 execution of Java programming language code, and threads | |
| 4731 attempting to execute JNI functions are typically stalled. | |
| 4732 </description> | |
| 4733 <origin>new</origin> | |
| 4734 <capabilities> | |
| 4735 <required id="can_tag_objects"></required> | |
| 4736 </capabilities> | |
| 4737 <parameters> | |
| 4738 <param id="heap_filter"> | |
| 4739 <jint/> | |
| 4740 <description> | |
| 4741 This bit vector of | |
| 4742 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>. | |
| 4743 restricts the objects for which the callback function is called. | |
| 4744 This applies to both the object and primitive callbacks. | |
| 4745 </description> | |
| 4746 </param> | |
| 4747 <param id="klass"> | |
| 4748 <ptrtype> | |
| 4749 <jclass/> | |
| 4750 <nullok>callbacks are not limited to instances of a particular class</nullok> | |
| 4751 </ptrtype> | |
| 4752 <description> | |
| 4753 Callbacks are only reported when the object is an instance of | |
| 4754 this class. | |
| 4755 Objects which are instances of a subclass of <code>klass</code> | |
| 4756 are not reported. | |
| 4757 If <code>klass</code> is an interface, no objects are reported. | |
| 4758 This applies to both the object and primitive callbacks. | |
| 4759 </description> | |
| 4760 </param> | |
| 4761 <param id="callbacks"> | |
| 4762 <inptr> | |
| 4763 <struct>jvmtiHeapCallbacks</struct> | |
| 4764 </inptr> | |
| 4765 <description> | |
| 4766 Structure defining the set callback functions. | |
| 4767 </description> | |
| 4768 </param> | |
| 4769 <param id="user_data"> | |
| 4770 <inbuf> | |
| 4771 <void/> | |
| 4772 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 4773 </inbuf> | |
| 4774 <description> | |
| 4775 User supplied data to be passed to the callback. | |
| 4776 </description> | |
| 4777 </param> | |
| 4778 </parameters> | |
| 4779 <errors> | |
| 4780 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 4781 <paramlink id="klass"/> is not a valid class. | |
| 4782 </error> | |
| 4783 </errors> | |
| 4784 </function> | |
| 4785 | |
| 4786 <function id="GetTag" phase="start" num="106"> | |
| 4787 <synopsis>Get Tag</synopsis> | |
| 4788 <description> | |
| 4789 Retrieve the tag associated with an object. | |
| 4790 The tag is a long value typically used to store a | |
| 4791 unique identifier or pointer to object information. | |
| 4792 The tag is set with | |
| 4793 <functionlink id="SetTag"></functionlink>. | |
| 4794 Objects for which no tags have been set return a | |
| 4795 tag value of zero. | |
| 4796 </description> | |
| 4797 <origin>new</origin> | |
| 4798 <capabilities> | |
| 4799 <required id="can_tag_objects"></required> | |
| 4800 </capabilities> | |
| 4801 <parameters> | |
| 4802 <param id="object"> | |
| 4803 <jobject/> | |
| 4804 <description> | |
| 4805 The object whose tag is to be retrieved. | |
| 4806 </description> | |
| 4807 </param> | |
| 4808 <param id="tag_ptr"> | |
| 4809 <outptr><jlong/></outptr> | |
| 4810 <description> | |
| 4811 On return, the referenced long is set to the value | |
| 4812 of the tag. | |
| 4813 </description> | |
| 4814 </param> | |
| 4815 </parameters> | |
| 4816 <errors> | |
| 4817 </errors> | |
| 4818 </function> | |
| 4819 | |
| 4820 <function id="SetTag" phase="start" num="107"> | |
| 4821 <synopsis>Set Tag</synopsis> | |
| 4822 <description> | |
| 4823 Set the tag associated with an object. | |
| 4824 The tag is a long value typically used to store a | |
| 4825 unique identifier or pointer to object information. | |
| 4826 The tag is visible with | |
| 4827 <functionlink id="GetTag"></functionlink>. | |
| 4828 </description> | |
| 4829 <origin>new</origin> | |
| 4830 <capabilities> | |
| 4831 <required id="can_tag_objects"></required> | |
| 4832 </capabilities> | |
| 4833 <parameters> | |
| 4834 <param id="object"> | |
| 4835 <jobject/> | |
| 4836 <description> | |
| 4837 The object whose tag is to be set. | |
| 4838 </description> | |
| 4839 </param> | |
| 4840 <param id="tag"> | |
| 4841 <jlong/> | |
| 4842 <description> | |
| 4843 The new value of the tag. | |
| 4844 </description> | |
| 4845 </param> | |
| 4846 </parameters> | |
| 4847 <errors> | |
| 4848 </errors> | |
| 4849 </function> | |
| 4850 | |
| 4851 <function id="GetObjectsWithTags" num="114"> | |
| 4852 <synopsis>Get Objects With Tags</synopsis> | |
| 4853 <description> | |
| 4854 Return objects in the heap with the specified tags. | |
| 4855 The format is parallel arrays of objects and tags. | |
| 4856 </description> | |
| 4857 <origin>new</origin> | |
| 4858 <capabilities> | |
| 4859 <required id="can_tag_objects"></required> | |
| 4860 </capabilities> | |
| 4861 <parameters> | |
| 4862 <param id="tag_count"> | |
| 4863 <jint min="0"/> | |
| 4864 <description> | |
| 4865 Number of tags to scan for. | |
| 4866 </description> | |
| 4867 </param> | |
| 4868 <param id="tags"> | |
| 4869 <inbuf incount="tag_count"> | |
| 4870 <jlong/> | |
| 4871 </inbuf> | |
| 4872 <description> | |
| 4873 Scan for objects with these tags. | |
| 4874 Zero is not permitted in this array. | |
| 4875 </description> | |
| 4876 </param> | |
| 4877 <param id="count_ptr"> | |
| 4878 <outptr> | |
| 4879 <jint/> | |
| 4880 </outptr> | |
| 4881 <description> | |
| 4882 Return the number of objects with any of the tags | |
| 4883 in <paramlink id="tags"/>. | |
| 4884 </description> | |
| 4885 </param> | |
| 4886 <param id="object_result_ptr"> | |
| 4887 <allocbuf outcount="count_ptr"> | |
| 4888 <jobject/> | |
| 4889 <nullok>this information is not returned</nullok> | |
| 4890 </allocbuf> | |
| 4891 <description> | |
| 4892 Returns the array of objects with any of the tags | |
| 4893 in <paramlink id="tags"/>. | |
| 4894 </description> | |
| 4895 </param> | |
| 4896 <param id="tag_result_ptr"> | |
| 4897 <allocbuf outcount="count_ptr"> | |
| 4898 <jlong/> | |
| 4899 <nullok>this information is not returned</nullok> | |
| 4900 </allocbuf> | |
| 4901 <description> | |
| 4902 For each object in <paramlink id="object_result_ptr"/>, | |
| 4903 return the tag at the corresponding index. | |
| 4904 </description> | |
| 4905 </param> | |
| 4906 </parameters> | |
| 4907 <errors> | |
| 4908 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 4909 Zero is present in <paramlink id="tags"></paramlink>. | |
| 4910 </error> | |
| 4911 </errors> | |
| 4912 </function> | |
| 4913 | |
| 4914 <function id="ForceGarbageCollection" num="108"> | |
| 4915 <synopsis>Force Garbage Collection</synopsis> | |
| 4916 <description> | |
| 4917 Force the VM to perform a garbage collection. | |
| 4918 The garbage collection is as complete as possible. | |
| 4919 This function does not cause finalizers to be run. | |
| 4920 This function does not return until the garbage collection | |
| 4921 is finished. | |
| 4922 <p/> | |
| 4923 Although garbage collection is as complete | |
| 4924 as possible there is no guarantee that all | |
| 4925 <eventlink id="ObjectFree"/> | |
| 4926 events will have been | |
| 4927 sent by the time that this function | |
| 4928 returns. In particular, an object may be | |
| 4929 prevented from being freed because it | |
| 4930 is awaiting finalization. | |
| 4931 </description> | |
| 4932 <origin>new</origin> | |
| 4933 <capabilities> | |
| 4934 </capabilities> | |
| 4935 <parameters> | |
| 4936 </parameters> | |
| 4937 <errors> | |
| 4938 </errors> | |
| 4939 </function> | |
| 4940 | |
| 4941 | |
| 4942 </category> | |
| 4943 | |
| 4944 <category id="Heap_1_0" label="Heap (1.0)"> | |
| 4945 <intro> | |
| 4946 <b> | |
| 4947 These functions and data types were introduced in the original | |
| 4948 <jvmti/> version 1.0 and have been superseded by more | |
| 4949 </b> | |
| 4950 <internallink id="Heap"><b>powerful and flexible versions</b></internallink> | |
| 4951 <b> | |
| 4952 which: | |
| 4953 </b> | |
| 4954 <ul> | |
| 4955 <li> | |
| 4956 <b> | |
| 4957 Allow access to primitive values (the value of Strings, arrays, | |
| 4958 and primitive fields) | |
| 4959 </b> | |
| 4960 </li> | |
| 4961 <li> | |
| 4962 <b> | |
| 4963 Allow the tag of the referrer to be set, thus enabling more | |
| 4964 efficient localized reference graph building | |
| 4965 </b> | |
| 4966 </li> | |
| 4967 <li> | |
| 4968 <b> | |
| 4969 Provide more extensive filtering abilities | |
| 4970 </b> | |
| 4971 </li> | |
| 4972 <li> | |
| 4973 <b> | |
| 4974 Are extensible, allowing their abilities to grow in future versions of <jvmti/> | |
| 4975 </b> | |
| 4976 </li> | |
| 4977 </ul> | |
| 4978 <p/> | |
| 4979 <b>Please use the </b> | |
| 4980 <internallink id="Heap"><b>current Heap functions</b></internallink>. | |
| 4981 <p/> | |
| 4982 <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum"> | |
| 4983 <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1"> | |
| 4984 Tagged objects only. | |
| 4985 </constant> | |
| 4986 <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2"> | |
| 4987 Untagged objects only. | |
| 4988 </constant> | |
| 4989 <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3"> | |
| 4990 Either tagged or untagged objects. | |
| 4991 </constant> | |
| 4992 </constants> | |
| 4993 | |
| 4994 <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum"> | |
| 4995 <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1"> | |
| 4996 JNI global reference. | |
| 4997 </constant> | |
| 4998 <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2"> | |
| 4999 System class. | |
| 5000 </constant> | |
| 5001 <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3"> | |
| 5002 Monitor. | |
| 5003 </constant> | |
| 5004 <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4"> | |
| 5005 Stack local. | |
| 5006 </constant> | |
| 5007 <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5"> | |
| 5008 JNI local reference. | |
| 5009 </constant> | |
| 5010 <constant id="JVMTI_HEAP_ROOT_THREAD" num="6"> | |
| 5011 Thread. | |
| 5012 </constant> | |
| 5013 <constant id="JVMTI_HEAP_ROOT_OTHER" num="7"> | |
| 5014 Other. | |
| 5015 </constant> | |
| 5016 </constants> | |
| 5017 | |
| 5018 <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum"> | |
| 5019 <constant id="JVMTI_REFERENCE_CLASS" num="1"> | |
| 5020 Reference from an object to its class. | |
| 5021 </constant> | |
| 5022 <constant id="JVMTI_REFERENCE_FIELD" num="2"> | |
| 5023 Reference from an object to the value of one of its instance fields. | |
| 5024 For references of this kind the <code>referrer_index</code> | |
| 5025 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 5026 jvmtiObjectReferenceCallback</internallink> is the index of the | |
| 5027 the instance field. The index is based on the order of all the | |
| 5028 object's fields. This includes all fields of the directly declared | |
| 5029 static and instance fields in the class, and includes all fields (both | |
| 5030 public and private) fields declared in superclasses and superinterfaces. | |
| 5031 The index is thus calculated by summing the index of the field in the directly | |
| 5032 declared class (see <functionlink id="GetClassFields"/>), with the total | |
| 5033 number of fields (both public and private) declared in all superclasses | |
| 5034 and superinterfaces. The index starts at zero. | |
| 5035 </constant> | |
| 5036 <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3"> | |
| 5037 Reference from an array to one of its elements. | |
| 5038 For references of this kind the <code>referrer_index</code> | |
| 5039 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 5040 jvmtiObjectReferenceCallback</internallink> is the array index. | |
| 5041 </constant> | |
| 5042 <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4"> | |
| 5043 Reference from a class to its class loader. | |
| 5044 </constant> | |
| 5045 <constant id="JVMTI_REFERENCE_SIGNERS" num="5"> | |
| 5046 Reference from a class to its signers array. | |
| 5047 </constant> | |
| 5048 <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6"> | |
| 5049 Reference from a class to its protection domain. | |
| 5050 </constant> | |
| 5051 <constant id="JVMTI_REFERENCE_INTERFACE" num="7"> | |
| 5052 Reference from a class to one of its interfaces. | |
| 5053 </constant> | |
| 5054 <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8"> | |
| 5055 Reference from a class to the value of one of its static fields. | |
| 5056 For references of this kind the <code>referrer_index</code> | |
| 5057 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 5058 jvmtiObjectReferenceCallback</internallink> is the index of the | |
| 5059 the static field. The index is based on the order of all the | |
| 5060 object's fields. This includes all fields of the directly declared | |
| 5061 static and instance fields in the class, and includes all fields (both | |
| 5062 public and private) fields declared in superclasses and superinterfaces. | |
| 5063 The index is thus calculated by summing the index of the field in the directly | |
| 5064 declared class (see <functionlink id="GetClassFields"/>), with the total | |
| 5065 number of fields (both public and private) declared in all superclasses | |
| 5066 and superinterfaces. The index starts at zero. | |
| 5067 Note: this definition differs from that in the <jvmti/> 1.0 Specification. | |
| 5068 <rationale>No known implementations used the 1.0 definition.</rationale> | |
| 5069 </constant> | |
| 5070 <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9"> | |
| 5071 Reference from a class to a resolved entry in the constant pool. | |
| 5072 For references of this kind the <code>referrer_index</code> | |
| 5073 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 5074 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
|
5075 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
|
5076 <vmspec chapter="4.4"/>. |
| 0 | 5077 </constant> |
| 5078 </constants> | |
| 5079 | |
| 5080 <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum"> | |
| 5081 <constant id="JVMTI_ITERATION_CONTINUE" num="1"> | |
| 5082 Continue the iteration. | |
| 5083 If this is a reference iteration, follow the references of this object. | |
| 5084 </constant> | |
| 5085 <constant id="JVMTI_ITERATION_IGNORE" num="2"> | |
| 5086 Continue the iteration. | |
| 5087 If this is a reference iteration, ignore the references of this object. | |
| 5088 </constant> | |
| 5089 <constant id="JVMTI_ITERATION_ABORT" num="0"> | |
| 5090 Abort the iteration. | |
| 5091 </constant> | |
| 5092 </constants> | |
| 5093 </intro> | |
| 5094 | |
| 5095 <callback id="jvmtiHeapObjectCallback"> | |
| 5096 <enum>jvmtiIterationControl</enum> | |
| 5097 <synopsis>Heap Object Callback</synopsis> | |
| 5098 <description> | |
| 5099 Agent supplied callback function. | |
| 5100 Describes (but does not pass in) an object in the heap. | |
| 5101 <p/> | |
| 5102 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5103 or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5104 <p/> | |
| 5105 See the <internallink id="heapCallbacks">heap callback | |
| 5106 function restrictions</internallink>. | |
| 5107 </description> | |
| 5108 <parameters> | |
| 5109 <param id="class_tag"> | |
| 5110 <jlong/> | |
| 5111 <description> | |
| 5112 The tag of the class of object (zero if the class is not tagged). | |
| 5113 If the object represents a runtime class, | |
| 5114 the <code>class_tag</code> is the tag | |
| 5115 associated with <code>java.lang.Class</code> | |
| 5116 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5117 </description> | |
| 5118 </param> | |
| 5119 <param id="size"> | |
| 5120 <jlong/> | |
| 5121 <description> | |
| 5122 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 5123 </description> | |
| 5124 </param> | |
| 5125 <param id="tag_ptr"> | |
| 5126 <outptr><jlong/></outptr> | |
| 5127 <description> | |
| 5128 The object tag value, or zero if the object is not tagged. | |
| 5129 To set the tag value to be associated with the object | |
| 5130 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5131 </description> | |
| 5132 </param> | |
| 5133 <param id="user_data"> | |
| 5134 <outptr><void/></outptr> | |
| 5135 <description> | |
| 5136 The user supplied data that was passed into the iteration function. | |
| 5137 </description> | |
| 5138 </param> | |
| 5139 </parameters> | |
| 5140 </callback> | |
| 5141 | |
| 5142 <callback id="jvmtiHeapRootCallback"> | |
| 5143 <enum>jvmtiIterationControl</enum> | |
| 5144 <synopsis>Heap Root Object Callback</synopsis> | |
| 5145 <description> | |
| 5146 Agent supplied callback function. | |
| 5147 Describes (but does not pass in) an object that is a root for the purposes | |
| 5148 of garbage collection. | |
| 5149 <p/> | |
| 5150 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5151 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
| 5152 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5153 <p/> | |
| 5154 See the <internallink id="heapCallbacks">heap callback | |
| 5155 function restrictions</internallink>. | |
| 5156 </description> | |
| 5157 <parameters> | |
| 5158 <param id="root_kind"> | |
| 5159 <enum>jvmtiHeapRootKind</enum> | |
| 5160 <description> | |
| 5161 The kind of heap root. | |
| 5162 </description> | |
| 5163 </param> | |
| 5164 <param id="class_tag"> | |
| 5165 <jlong/> | |
| 5166 <description> | |
| 5167 The tag of the class of object (zero if the class is not tagged). | |
| 5168 If the object represents a runtime class, the <code>class_tag</code> is the tag | |
| 5169 associated with <code>java.lang.Class</code> | |
| 5170 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5171 </description> | |
| 5172 </param> | |
| 5173 <param id="size"> | |
| 5174 <jlong/> | |
| 5175 <description> | |
| 5176 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 5177 </description> | |
| 5178 </param> | |
| 5179 <param id="tag_ptr"> | |
| 5180 <outptr><jlong/></outptr> | |
| 5181 <description> | |
| 5182 The object tag value, or zero if the object is not tagged. | |
| 5183 To set the tag value to be associated with the object | |
| 5184 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5185 </description> | |
| 5186 </param> | |
| 5187 <param id="user_data"> | |
| 5188 <outptr><void/></outptr> | |
| 5189 <description> | |
| 5190 The user supplied data that was passed into the iteration function. | |
| 5191 </description> | |
| 5192 </param> | |
| 5193 </parameters> | |
| 5194 </callback> | |
| 5195 | |
| 5196 <callback id="jvmtiStackReferenceCallback"> | |
| 5197 <enum>jvmtiIterationControl</enum> | |
| 5198 <synopsis>Stack Reference Object Callback</synopsis> | |
| 5199 <description> | |
| 5200 Agent supplied callback function. | |
| 5201 Describes (but does not pass in) an object on the stack that is a root for | |
| 5202 the purposes of garbage collection. | |
| 5203 <p/> | |
| 5204 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5205 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
| 5206 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5207 <p/> | |
| 5208 See the <internallink id="heapCallbacks">heap callback | |
| 5209 function restrictions</internallink>. | |
| 5210 </description> | |
| 5211 <parameters> | |
| 5212 <param id="root_kind"> | |
| 5213 <enum>jvmtiHeapRootKind</enum> | |
| 5214 <description> | |
| 5215 The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or | |
| 5216 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>). | |
| 5217 </description> | |
| 5218 </param> | |
| 5219 <param id="class_tag"> | |
| 5220 <jlong/> | |
| 5221 <description> | |
| 5222 The tag of the class of object (zero if the class is not tagged). | |
| 5223 If the object represents a runtime class, the <code>class_tag</code> is the tag | |
| 5224 associated with <code>java.lang.Class</code> | |
| 5225 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5226 </description> | |
| 5227 </param> | |
| 5228 <param id="size"> | |
| 5229 <jlong/> | |
| 5230 <description> | |
| 5231 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 5232 </description> | |
| 5233 </param> | |
| 5234 <param id="tag_ptr"> | |
| 5235 <outptr><jlong/></outptr> | |
| 5236 <description> | |
| 5237 The object tag value, or zero if the object is not tagged. | |
| 5238 To set the tag value to be associated with the object | |
| 5239 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5240 </description> | |
| 5241 </param> | |
| 5242 <param id="thread_tag"> | |
| 5243 <jlong/> | |
| 5244 <description> | |
| 5245 The tag of the thread corresponding to this stack, zero if not tagged. | |
| 5246 </description> | |
| 5247 </param> | |
| 5248 <param id="depth"> | |
| 5249 <jint/> | |
| 5250 <description> | |
| 5251 The depth of the frame. | |
| 5252 </description> | |
| 5253 </param> | |
| 5254 <param id="method"> | |
| 5255 <jmethodID/> | |
| 5256 <description> | |
| 5257 The method executing in this frame. | |
| 5258 </description> | |
| 5259 </param> | |
| 5260 <param id="slot"> | |
| 5261 <jint/> | |
| 5262 <description> | |
| 5263 The slot number. | |
| 5264 </description> | |
| 5265 </param> | |
| 5266 <param id="user_data"> | |
| 5267 <outptr><void/></outptr> | |
| 5268 <description> | |
| 5269 The user supplied data that was passed into the iteration function. | |
| 5270 </description> | |
| 5271 </param> | |
| 5272 </parameters> | |
| 5273 </callback> | |
| 5274 | |
| 5275 <callback id="jvmtiObjectReferenceCallback"> | |
| 5276 <enum>jvmtiIterationControl</enum> | |
| 5277 <synopsis>Object Reference Callback</synopsis> | |
| 5278 <description> | |
| 5279 Agent supplied callback function. | |
| 5280 Describes a reference from an object (the referrer) to another object | |
| 5281 (the referree). | |
| 5282 <p/> | |
| 5283 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5284 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
| 5285 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5286 <p/> | |
| 5287 See the <internallink id="heapCallbacks">heap callback | |
| 5288 function restrictions</internallink>. | |
| 5289 </description> | |
| 5290 <parameters> | |
| 5291 <param id="reference_kind"> | |
| 5292 <enum>jvmtiObjectReferenceKind</enum> | |
| 5293 <description> | |
| 5294 The type of reference. | |
| 5295 </description> | |
| 5296 </param> | |
| 5297 <param id="class_tag"> | |
| 5298 <jlong/> | |
| 5299 <description> | |
| 5300 The tag of the class of referree object (zero if the class is not tagged). | |
| 5301 If the referree object represents a runtime class, | |
| 5302 the <code>class_tag</code> is the tag | |
| 5303 associated with <code>java.lang.Class</code> | |
| 5304 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5305 </description> | |
| 5306 </param> | |
| 5307 <param id="size"> | |
| 5308 <jlong/> | |
| 5309 <description> | |
| 5310 Size of the referree object (in bytes). | |
| 5311 See <functionlink id="GetObjectSize"/>. | |
| 5312 </description> | |
| 5313 </param> | |
| 5314 <param id="tag_ptr"> | |
| 5315 <outptr><jlong/></outptr> | |
| 5316 <description> | |
| 5317 The referree object tag value, or zero if the object is not | |
| 5318 tagged. | |
| 5319 To set the tag value to be associated with the object | |
| 5320 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5321 </description> | |
| 5322 </param> | |
| 5323 <param id="referrer_tag"> | |
| 5324 <jlong/> | |
| 5325 <description> | |
| 5326 The tag of the referrer object, or zero if the referrer | |
| 5327 object is not tagged. | |
| 5328 </description> | |
| 5329 </param> | |
| 5330 <param id="referrer_index"> | |
| 5331 <jint/> | |
| 5332 <description> | |
| 5333 For references of type <code>JVMTI_REFERENCE_FIELD</code> or | |
| 5334 <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index | |
| 5335 of the field in the referrer object. The index is based on the | |
| 5336 order of all the object's fields - see <internallink | |
| 5337 id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink> | |
| 5338 or <internallink | |
| 5339 id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD | |
| 5340 </internallink> for further description. | |
| 5341 <p/> | |
| 5342 For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code> | |
| 5343 the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT"> | |
| 5344 JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description. | |
| 5345 <p/> | |
| 5346 For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code> | |
| 5347 the index into the constant pool of the class - see | |
| 5348 <internallink id="JVMTI_REFERENCE_CONSTANT_POOL"> | |
| 5349 JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further | |
| 5350 description. | |
| 5351 <p/> | |
| 5352 For references of other kinds the <code>referrer_index</code> is | |
| 5353 <code>-1</code>. | |
| 5354 </description> | |
| 5355 </param> | |
| 5356 <param id="user_data"> | |
| 5357 <outptr><void/></outptr> | |
| 5358 <description> | |
| 5359 The user supplied data that was passed into the iteration function. | |
| 5360 </description> | |
| 5361 </param> | |
| 5362 </parameters> | |
| 5363 </callback> | |
| 5364 | |
| 5365 <function id="IterateOverObjectsReachableFromObject" num="109"> | |
| 5366 <synopsis>Iterate Over Objects Reachable From Object</synopsis> | |
| 5367 <description> | |
| 5368 This function iterates over all objects that are directly | |
| 5369 and indirectly reachable from the specified object. | |
| 5370 For each object <i>A</i> (known | |
| 5371 as the referrer) with a reference to object <i>B</i> the specified | |
| 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 During the execution of this function the state of the heap | |
| 5387 does not change: no objects are allocated, no objects are | |
| 5388 garbage collected, and the state of objects (including | |
| 5389 held values) does not change. | |
| 5390 As a result, threads executing Java | |
| 5391 programming language code, threads attempting to resume the | |
| 5392 execution of Java programming language code, and threads | |
| 5393 attempting to execute JNI functions are typically stalled. | |
| 5394 </description> | |
| 5395 <origin>new</origin> | |
| 5396 <capabilities> | |
| 5397 <required id="can_tag_objects"></required> | |
| 5398 </capabilities> | |
| 5399 <parameters> | |
| 5400 <param id="object"> | |
| 5401 <jobject/> | |
| 5402 <description> | |
| 5403 The object | |
| 5404 </description> | |
| 5405 </param> | |
| 5406 <param id="object_reference_callback"> | |
| 5407 <ptrtype> | |
| 5408 <struct>jvmtiObjectReferenceCallback</struct> | |
| 5409 </ptrtype> | |
| 5410 <description> | |
| 5411 The callback to be called to describe each | |
| 5412 object reference. | |
| 5413 </description> | |
| 5414 </param> | |
| 5415 <param id="user_data"> | |
| 5416 <inbuf> | |
| 5417 <void/> | |
| 5418 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5419 </inbuf> | |
| 5420 <description> | |
| 5421 User supplied data to be passed to the callback. | |
| 5422 </description> | |
| 5423 </param> | |
| 5424 </parameters> | |
| 5425 <errors> | |
| 5426 </errors> | |
| 5427 </function> | |
| 5428 | |
| 5429 <function id="IterateOverReachableObjects" num="110"> | |
| 5430 <synopsis>Iterate Over Reachable Objects</synopsis> | |
| 5431 <description> | |
| 5432 This function iterates over the root objects and all objects that | |
| 5433 are directly and indirectly reachable from the root objects. | |
| 5434 The root objects comprise the set of system classes, | |
| 5435 JNI globals, references from thread stacks, and other objects used as roots | |
| 5436 for the purposes of garbage collection. | |
| 5437 <p/> | |
| 5438 For each root the <paramlink id="heap_root_callback"></paramlink> | |
| 5439 or <paramlink id="stack_ref_callback"></paramlink> callback is called. | |
| 5440 An object can be a root object for more than one reason and in that case | |
| 5441 the appropriate callback is called for each reason. | |
| 5442 <p/> | |
| 5443 For each object reference the <paramlink id="object_ref_callback"></paramlink> | |
| 5444 callback function is called to describe the object reference. | |
| 5445 The callback is called exactly once for each reference from a referrer; | |
| 5446 this is true even if there are reference cycles or multiple paths to | |
| 5447 the referrer. | |
| 5448 There may be more than one reference between a referrer and a referree, | |
| 5449 These may be distinguished by the | |
| 5450 <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and | |
| 5451 <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>. | |
| 5452 The callback for an object will always occur after the callback for | |
| 5453 its referrer. | |
| 5454 <p/> | |
| 5455 See <functionlink id="FollowReferences"/> for the object | |
| 5456 references which are reported. | |
| 5457 <p/> | |
| 5458 Roots are always reported to the profiler before any object references | |
| 5459 are reported. In other words, the <paramlink id="object_ref_callback"></paramlink> | |
| 5460 callback will not be called until the appropriate callback has been called | |
| 5461 for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is | |
| 5462 specified as <code>NULL</code> then this function returns after | |
| 5463 reporting the root objects to the profiler. | |
| 5464 <p/> | |
| 5465 During the execution of this function the state of the heap | |
| 5466 does not change: no objects are allocated, no objects are | |
| 5467 garbage collected, and the state of objects (including | |
| 5468 held values) does not change. | |
| 5469 As a result, threads executing Java | |
| 5470 programming language code, threads attempting to resume the | |
| 5471 execution of Java programming language code, and threads | |
| 5472 attempting to execute JNI functions are typically stalled. | |
| 5473 </description> | |
| 5474 <origin>new</origin> | |
| 5475 <capabilities> | |
| 5476 <required id="can_tag_objects"></required> | |
| 5477 </capabilities> | |
| 5478 <parameters> | |
| 5479 <param id="heap_root_callback"> | |
| 5480 <ptrtype> | |
| 5481 <struct>jvmtiHeapRootCallback</struct> | |
| 5482 <nullok>do not report heap roots</nullok> | |
| 5483 </ptrtype> | |
| 5484 <description> | |
| 5485 The callback function to be called for each heap root of type | |
| 5486 <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>, | |
| 5487 <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>, | |
| 5488 <code>JVMTI_HEAP_ROOT_MONITOR</code>, | |
| 5489 <code>JVMTI_HEAP_ROOT_THREAD</code>, or | |
| 5490 <code>JVMTI_HEAP_ROOT_OTHER</code>. | |
| 5491 </description> | |
| 5492 </param> | |
| 5493 <param id="stack_ref_callback"> | |
| 5494 <ptrtype> | |
| 5495 <struct>jvmtiStackReferenceCallback</struct> | |
| 5496 <nullok>do not report stack references</nullok> | |
| 5497 </ptrtype> | |
| 5498 <description> | |
| 5499 The callback function to be called for each heap root of | |
| 5500 <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or | |
| 5501 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>. | |
| 5502 </description> | |
| 5503 </param> | |
| 5504 <param id="object_ref_callback"> | |
| 5505 <ptrtype> | |
| 5506 <struct>jvmtiObjectReferenceCallback</struct> | |
| 5507 <nullok>do not follow references from the root objects</nullok> | |
| 5508 </ptrtype> | |
| 5509 <description> | |
| 5510 The callback function to be called for each object reference. | |
| 5511 </description> | |
| 5512 </param> | |
| 5513 <param id="user_data"> | |
| 5514 <inbuf> | |
| 5515 <void/> | |
| 5516 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5517 </inbuf> | |
| 5518 <description> | |
| 5519 User supplied data to be passed to the callback. | |
| 5520 </description> | |
| 5521 </param> | |
| 5522 </parameters> | |
| 5523 <errors> | |
| 5524 </errors> | |
| 5525 </function> | |
| 5526 | |
| 5527 <function id="IterateOverHeap" num="111"> | |
| 5528 <synopsis>Iterate Over Heap</synopsis> | |
| 5529 <description> | |
| 5530 Iterate over all objects in the heap. This includes both reachable and | |
| 5531 unreachable objects. | |
| 5532 <p/> | |
| 5533 The <paramlink id="object_filter"></paramlink> parameter indicates the | |
| 5534 objects for which the callback function is called. If this parameter | |
| 5535 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be | |
| 5536 called for every object that is tagged. If the parameter is | |
| 5537 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be | |
| 5538 for objects that are not tagged. If the parameter | |
| 5539 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be | |
| 5540 called for every object in the heap, irrespective of whether it is | |
| 5541 tagged or not. | |
| 5542 <p/> | |
| 5543 During the execution of this function the state of the heap | |
| 5544 does not change: no objects are allocated, no objects are | |
| 5545 garbage collected, and the state of objects (including | |
| 5546 held values) does not change. | |
| 5547 As a result, threads executing Java | |
| 5548 programming language code, threads attempting to resume the | |
| 5549 execution of Java programming language code, and threads | |
| 5550 attempting to execute JNI functions are typically stalled. | |
| 5551 </description> | |
| 5552 <origin>new</origin> | |
| 5553 <capabilities> | |
| 5554 <required id="can_tag_objects"></required> | |
| 5555 </capabilities> | |
| 5556 <parameters> | |
| 5557 <param id="object_filter"> | |
| 5558 <enum>jvmtiHeapObjectFilter</enum> | |
| 5559 <description> | |
| 5560 Indicates the objects for which the callback function is called. | |
| 5561 </description> | |
| 5562 </param> | |
| 5563 <param id="heap_object_callback"> | |
| 5564 <ptrtype> | |
| 5565 <struct>jvmtiHeapObjectCallback</struct> | |
| 5566 </ptrtype> | |
| 5567 <description> | |
| 5568 The iterator function to be called for each | |
| 5569 object matching the <paramlink id="object_filter"/>. | |
| 5570 </description> | |
| 5571 </param> | |
| 5572 <param id="user_data"> | |
| 5573 <inbuf> | |
| 5574 <void/> | |
| 5575 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5576 </inbuf> | |
| 5577 <description> | |
| 5578 User supplied data to be passed to the callback. | |
| 5579 </description> | |
| 5580 </param> | |
| 5581 </parameters> | |
| 5582 <errors> | |
| 5583 </errors> | |
| 5584 </function> | |
| 5585 | |
| 5586 <function id="IterateOverInstancesOfClass" num="112"> | |
| 5587 <synopsis>Iterate Over Instances Of Class</synopsis> | |
| 5588 <description> | |
| 5589 Iterate over all objects in the heap that are instances of the specified class. | |
| 5590 This includes direct instances of the specified class and | |
| 5591 instances of all subclasses of the specified class. | |
| 5592 This includes both reachable and unreachable objects. | |
| 5593 <p/> | |
| 5594 The <paramlink id="object_filter"></paramlink> parameter indicates the | |
| 5595 objects for which the callback function is called. If this parameter | |
| 5596 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be | |
| 5597 called for every object that is tagged. If the parameter is | |
| 5598 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be | |
| 5599 called for objects that are not tagged. If the parameter | |
| 5600 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be | |
| 5601 called for every object in the heap, irrespective of whether it is | |
| 5602 tagged or not. | |
| 5603 <p/> | |
| 5604 During the execution of this function the state of the heap | |
| 5605 does not change: no objects are allocated, no objects are | |
| 5606 garbage collected, and the state of objects (including | |
| 5607 held values) does not change. | |
| 5608 As a result, threads executing Java | |
| 5609 programming language code, threads attempting to resume the | |
| 5610 execution of Java programming language code, and threads | |
| 5611 attempting to execute JNI functions are typically stalled. | |
| 5612 </description> | |
| 5613 <origin>new</origin> | |
| 5614 <capabilities> | |
| 5615 <required id="can_tag_objects"></required> | |
| 5616 </capabilities> | |
| 5617 <parameters> | |
| 5618 <param id="klass"> | |
| 5619 <jclass/> | |
| 5620 <description> | |
| 5621 Iterate over objects of this class only. | |
| 5622 </description> | |
| 5623 </param> | |
| 5624 <param id="object_filter"> | |
| 5625 <enum>jvmtiHeapObjectFilter</enum> | |
| 5626 <description> | |
| 5627 Indicates the objects for which the callback function is called. | |
| 5628 </description> | |
| 5629 </param> | |
| 5630 <param id="heap_object_callback"> | |
| 5631 <ptrtype> | |
| 5632 <struct>jvmtiHeapObjectCallback</struct> | |
| 5633 </ptrtype> | |
| 5634 <description> | |
| 5635 The iterator function to be called for each | |
| 5636 <paramlink id="klass"/> instance matching | |
| 5637 the <paramlink id="object_filter"/>. | |
| 5638 </description> | |
| 5639 </param> | |
| 5640 <param id="user_data"> | |
| 5641 <inbuf> | |
| 5642 <void/> | |
| 5643 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5644 </inbuf> | |
| 5645 <description> | |
| 5646 User supplied data to be passed to the callback. | |
| 5647 </description> | |
| 5648 </param> | |
| 5649 </parameters> | |
| 5650 <errors> | |
| 5651 </errors> | |
| 5652 </function> | |
| 5653 | |
| 5654 </category> | |
| 5655 | |
| 5656 <category id="local" label="Local Variable"> | |
| 5657 | |
| 5658 <intro> | |
| 5659 These functions are used to retrieve or set the value of a local variable. | |
| 5660 The variable is identified by the depth of the frame containing its | |
| 5661 value and the variable's slot number within that frame. | |
| 5662 The mapping of variables to | |
| 5663 slot numbers can be obtained with the function | |
| 5664 <functionlink id="GetLocalVariableTable"></functionlink>. | |
| 5665 </intro> | |
| 5666 | |
| 5667 <function id="GetLocalObject" num="21"> | |
| 5668 <synopsis>Get Local Variable - Object</synopsis> | |
| 5669 <description> | |
| 5670 This function can be used to retrieve the value of a local | |
| 5671 variable whose type is <code>Object</code> or a subclass of <code>Object</code>. | |
| 5672 </description> | |
| 5673 <origin>jvmdi</origin> | |
| 5674 <capabilities> | |
| 5675 <required id="can_access_local_variables"></required> | |
| 5676 </capabilities> | |
| 5677 <parameters> | |
| 5678 <param id="thread"> | |
| 5679 <jthread null="current" frame="frame"/> | |
| 5680 <description> | |
| 5681 The thread of the frame containing the variable's value. | |
| 5682 </description> | |
| 5683 </param> | |
| 5684 <param id="depth"> | |
| 5685 <jframeID thread="thread"/> | |
| 5686 <description> | |
| 5687 The depth of the frame containing the variable's value. | |
| 5688 </description> | |
| 5689 </param> | |
| 5690 <param id="slot"> | |
| 5691 <jint/> | |
| 5692 <description> | |
| 5693 The variable's slot number. | |
| 5694 </description> | |
| 5695 </param> | |
| 5696 <param id="value_ptr"> | |
| 5697 <outptr><jobject/></outptr> | |
| 5698 <description> | |
| 5699 On return, points to the variable's value. | |
| 5700 </description> | |
| 5701 </param> | |
| 5702 </parameters> | |
| 5703 <errors> | |
| 5704 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5705 Invalid <code>slot</code>. | |
| 5706 </error> | |
| 5707 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5708 The variable type is not | |
| 5709 <code>Object</code> or a subclass of <code>Object</code>. | |
| 5710 </error> | |
| 5711 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5712 Not a visible frame | |
| 5713 </error> | |
| 5714 </errors> | |
| 5715 </function> | |
| 5716 | |
| 2019 | 5717 <function id="GetLocalInstance" num="155" since="1.2"> |
| 5718 <synopsis>Get Local Instance</synopsis> | |
| 5719 <description> | |
| 5720 This function can be used to retrieve the value of the local object | |
| 5721 variable at slot 0 (the "<code>this</code>" object) from non-static | |
| 5722 frames. This function can retrieve the "<code>this</code>" object from | |
| 5723 native method frames, whereas <code>GetLocalObject()</code> would | |
| 5724 return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases. | |
| 5725 </description> | |
| 5726 <origin>new</origin> | |
| 5727 <capabilities> | |
| 5728 <required id="can_access_local_variables"></required> | |
| 5729 </capabilities> | |
| 5730 <parameters> | |
| 5731 <param id="thread"> | |
| 5732 <jthread null="current" frame="frame"/> | |
| 5733 <description> | |
| 5734 The thread of the frame containing the variable's value. | |
| 5735 </description> | |
| 5736 </param> | |
| 5737 <param id="depth"> | |
| 5738 <jframeID thread="thread"/> | |
| 5739 <description> | |
| 5740 The depth of the frame containing the variable's value. | |
| 5741 </description> | |
| 5742 </param> | |
| 5743 <param id="value_ptr"> | |
| 5744 <outptr><jobject/></outptr> | |
| 5745 <description> | |
| 5746 On return, points to the variable's value. | |
| 5747 </description> | |
| 5748 </param> | |
| 5749 </parameters> | |
| 5750 <errors> | |
| 5751 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5752 If the specified frame is a static method frame. | |
| 5753 </error> | |
| 5754 </errors> | |
| 5755 </function> | |
| 0 | 5756 <function id="GetLocalInt" num="22"> |
| 5757 <synopsis>Get Local Variable - Int</synopsis> | |
| 5758 <description> | |
| 5759 This function can be used to retrieve the value of a local | |
| 5760 variable whose type is <code>int</code>, | |
| 5761 <code>short</code>, <code>char</code>, <code>byte</code>, or | |
| 5762 <code>boolean</code>. | |
| 5763 </description> | |
| 5764 <origin>jvmdi</origin> | |
| 5765 <capabilities> | |
| 5766 <required id="can_access_local_variables"></required> | |
| 5767 </capabilities> | |
| 5768 <parameters> | |
| 5769 <param id="thread"> | |
| 5770 <jthread null="current" frame="frame"/> | |
| 5771 <description> | |
| 5772 The thread of the frame containing the variable's value. | |
| 5773 </description> | |
| 5774 </param> | |
| 5775 <param id="depth"> | |
| 5776 <jframeID thread="thread"/> | |
| 5777 <description> | |
| 5778 The depth of the frame containing the variable's value. | |
| 5779 </description> | |
| 5780 </param> | |
| 5781 <param id="slot"> | |
| 5782 <jint/> | |
| 5783 <description> | |
| 5784 The variable's slot number. | |
| 5785 </description> | |
| 5786 </param> | |
| 5787 <param id="value_ptr"> | |
| 5788 <outptr><jint/></outptr> | |
| 5789 <description> | |
| 5790 On return, points to the variable's value. | |
| 5791 </description> | |
| 5792 </param> | |
| 5793 </parameters> | |
| 5794 <errors> | |
| 5795 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5796 Invalid <code>slot</code>. | |
| 5797 </error> | |
| 5798 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5799 The variable type is not | |
| 5800 <code>int</code>, <code>short</code>, | |
| 5801 <code>char</code>, <code>byte</code>, or | |
| 5802 <code>boolean</code>. | |
| 5803 </error> | |
| 5804 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5805 Not a visible frame | |
| 5806 </error> | |
| 5807 </errors> | |
| 5808 </function> | |
| 5809 | |
| 5810 <function id="GetLocalLong" num="23"> | |
| 5811 <synopsis>Get Local Variable - Long</synopsis> | |
| 5812 <description> | |
| 5813 This function can be used to retrieve the value of a local | |
| 5814 variable whose type is <code>long</code>. | |
| 5815 </description> | |
| 5816 <origin>jvmdi</origin> | |
| 5817 <capabilities> | |
| 5818 <required id="can_access_local_variables"></required> | |
| 5819 </capabilities> | |
| 5820 <parameters> | |
| 5821 <param id="thread"> | |
| 5822 <jthread null="current" frame="frame"/> | |
| 5823 <description> | |
| 5824 The thread of the frame containing the variable's value. | |
| 5825 </description> | |
| 5826 </param> | |
| 5827 <param id="depth"> | |
| 5828 <jframeID thread="thread"/> | |
| 5829 <description> | |
| 5830 The depth of the frame containing the variable's value. | |
| 5831 </description> | |
| 5832 </param> | |
| 5833 <param id="slot"> | |
| 5834 <jint/> | |
| 5835 <description> | |
| 5836 The variable's slot number. | |
| 5837 </description> | |
| 5838 </param> | |
| 5839 <param id="value_ptr"> | |
| 5840 <outptr><jlong/></outptr> | |
| 5841 <description> | |
| 5842 On return, points to the variable's value. | |
| 5843 </description> | |
| 5844 </param> | |
| 5845 </parameters> | |
| 5846 <errors> | |
| 5847 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5848 Invalid <code>slot</code>. | |
| 5849 </error> | |
| 5850 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5851 The variable type is not <code>long</code>. | |
| 5852 </error> | |
| 5853 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5854 Not a visible frame | |
| 5855 </error> | |
| 5856 </errors> | |
| 5857 </function> | |
| 5858 | |
| 5859 <function id="GetLocalFloat" num="24"> | |
| 5860 <synopsis>Get Local Variable - Float</synopsis> | |
| 5861 <description> | |
| 5862 This function can be used to retrieve the value of a local | |
| 5863 variable whose type is <code>float</code>. | |
| 5864 </description> | |
| 5865 <origin>jvmdi</origin> | |
| 5866 <capabilities> | |
| 5867 <required id="can_access_local_variables"></required> | |
| 5868 </capabilities> | |
| 5869 <parameters> | |
| 5870 <param id="thread"> | |
| 5871 <jthread null="current" frame="frame"/> | |
| 5872 <description> | |
| 5873 The thread of the frame containing the variable's value. | |
| 5874 </description> | |
| 5875 </param> | |
| 5876 <param id="depth"> | |
| 5877 <jframeID thread="thread"/> | |
| 5878 <description> | |
| 5879 The depth of the frame containing the variable's value. | |
| 5880 </description> | |
| 5881 </param> | |
| 5882 <param id="slot"> | |
| 5883 <jint/> | |
| 5884 <description> | |
| 5885 The variable's slot number. | |
| 5886 </description> | |
| 5887 </param> | |
| 5888 <param id="value_ptr"> | |
| 5889 <outptr><jfloat/></outptr> | |
| 5890 <description> | |
| 5891 On return, points to the variable's value. | |
| 5892 </description> | |
| 5893 </param> | |
| 5894 </parameters> | |
| 5895 <errors> | |
| 5896 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5897 Invalid <code>slot</code>. | |
| 5898 </error> | |
| 5899 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5900 The variable type is not <code>float</code>. | |
| 5901 </error> | |
| 5902 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5903 Not a visible frame | |
| 5904 </error> | |
| 5905 </errors> | |
| 5906 </function> | |
| 5907 | |
| 5908 <function id="GetLocalDouble" num="25"> | |
| 5909 <synopsis>Get Local Variable - Double</synopsis> | |
| 5910 <description> | |
| 5911 This function can be used to retrieve the value of a local | |
| 5912 variable whose type is <code>long</code>. | |
| 5913 </description> | |
| 5914 <origin>jvmdi</origin> | |
| 5915 <capabilities> | |
| 5916 <required id="can_access_local_variables"></required> | |
| 5917 </capabilities> | |
| 5918 <parameters> | |
| 5919 <param id="thread"> | |
| 5920 <jthread null="current" frame="frame"/> | |
| 5921 <description> | |
| 5922 The thread of the frame containing the variable's value. | |
| 5923 </description> | |
| 5924 </param> | |
| 5925 <param id="depth"> | |
| 5926 <jframeID thread="thread"/> | |
| 5927 <description> | |
| 5928 The depth of the frame containing the variable's value. | |
| 5929 </description> | |
| 5930 </param> | |
| 5931 <param id="slot"> | |
| 5932 <jint/> | |
| 5933 <description> | |
| 5934 The variable's slot number. | |
| 5935 </description> | |
| 5936 </param> | |
| 5937 <param id="value_ptr"> | |
| 5938 <outptr><jdouble/></outptr> | |
| 5939 <description> | |
| 5940 On return, points to the variable's value. | |
| 5941 </description> | |
| 5942 </param> | |
| 5943 </parameters> | |
| 5944 <errors> | |
| 5945 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5946 Invalid <code>slot</code>. | |
| 5947 </error> | |
| 5948 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5949 The variable type is not <code>double</code>. | |
| 5950 </error> | |
| 5951 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5952 Not a visible frame | |
| 5953 </error> | |
| 5954 </errors> | |
| 5955 </function> | |
| 5956 | |
| 5957 <function id="SetLocalObject" num="26"> | |
| 5958 <synopsis>Set Local Variable - Object</synopsis> | |
| 5959 <description> | |
| 5960 This function can be used to set the value of a local | |
| 5961 variable whose type is <code>Object</code> or a subclass of <code>Object</code>. | |
| 5962 </description> | |
| 5963 <origin>jvmdi</origin> | |
| 5964 <capabilities> | |
| 5965 <required id="can_access_local_variables"></required> | |
| 5966 </capabilities> | |
| 5967 <parameters> | |
| 5968 <param id="thread"> | |
| 5969 <jthread null="current" frame="frame"/> | |
| 5970 <description> | |
| 5971 The thread of the frame containing the variable's value. | |
| 5972 </description> | |
| 5973 </param> | |
| 5974 <param id="depth"> | |
| 5975 <jframeID thread="thread"/> | |
| 5976 <description> | |
| 5977 The depth of the frame containing the variable's value. | |
| 5978 </description> | |
| 5979 </param> | |
| 5980 <param id="slot"> | |
| 5981 <jint/> | |
| 5982 <description> | |
| 5983 The variable's slot number. | |
| 5984 </description> | |
| 5985 </param> | |
| 5986 <param id="value"> | |
| 5987 <jobject/> | |
| 5988 <description> | |
| 5989 The new value for the variable. | |
| 5990 </description> | |
| 5991 </param> | |
| 5992 </parameters> | |
| 5993 <errors> | |
| 5994 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5995 Invalid <code>slot</code>. | |
| 5996 </error> | |
| 5997 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5998 The variable type is not | |
| 5999 <code>Object</code> or a subclass of <code>Object</code>. | |
| 6000 </error> | |
| 6001 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6002 The supplied <paramlink id="value"/> is not compatible | |
| 6003 with the variable type. | |
| 6004 </error> | |
| 6005 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6006 Not a visible frame | |
| 6007 </error> | |
| 6008 </errors> | |
| 6009 </function> | |
| 6010 | |
| 6011 <function id="SetLocalInt" num="27"> | |
| 6012 <synopsis>Set Local Variable - Int</synopsis> | |
| 6013 <description> | |
| 6014 This function can be used to set the value of a local | |
| 6015 variable whose type is <code>int</code>, | |
| 6016 <code>short</code>, <code>char</code>, <code>byte</code>, or | |
| 6017 <code>boolean</code>. | |
| 6018 </description> | |
| 6019 <origin>jvmdi</origin> | |
| 6020 <capabilities> | |
| 6021 <required id="can_access_local_variables"></required> | |
| 6022 </capabilities> | |
| 6023 <parameters> | |
| 6024 <param id="thread"> | |
| 6025 <jthread null="current" frame="frame"/> | |
| 6026 <description> | |
| 6027 The thread of the frame containing the variable's value. | |
| 6028 </description> | |
| 6029 </param> | |
| 6030 <param id="depth"> | |
| 6031 <jframeID thread="thread"/> | |
| 6032 <description> | |
| 6033 The depth of the frame containing the variable's value. | |
| 6034 </description> | |
| 6035 </param> | |
| 6036 <param id="slot"> | |
| 6037 <jint/> | |
| 6038 <description> | |
| 6039 The variable's slot number. | |
| 6040 </description> | |
| 6041 </param> | |
| 6042 <param id="value"> | |
| 6043 <jint/> | |
| 6044 <description> | |
| 6045 The new value for the variable. | |
| 6046 </description> | |
| 6047 </param> | |
| 6048 </parameters> | |
| 6049 <errors> | |
| 6050 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6051 Invalid <code>slot</code>. | |
| 6052 </error> | |
| 6053 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6054 The variable type is not | |
| 6055 <code>int</code>, <code>short</code>, | |
| 6056 <code>char</code>, <code>byte</code>, or | |
| 6057 <code>boolean</code>. | |
| 6058 </error> | |
| 6059 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6060 Not a visible frame | |
| 6061 </error> | |
| 6062 </errors> | |
| 6063 </function> | |
| 6064 | |
| 6065 <function id="SetLocalLong" num="28"> | |
| 6066 <synopsis>Set Local Variable - Long</synopsis> | |
| 6067 <description> | |
| 6068 This function can be used to set the value of a local | |
| 6069 variable whose type is <code>long</code>. | |
| 6070 </description> | |
| 6071 <origin>jvmdi</origin> | |
| 6072 <capabilities> | |
| 6073 <required id="can_access_local_variables"></required> | |
| 6074 </capabilities> | |
| 6075 <parameters> | |
| 6076 <param id="thread"> | |
| 6077 <jthread null="current" frame="frame"/> | |
| 6078 <description> | |
| 6079 The thread of the frame containing the variable's value. | |
| 6080 </description> | |
| 6081 </param> | |
| 6082 <param id="depth"> | |
| 6083 <jframeID thread="thread"/> | |
| 6084 <description> | |
| 6085 The depth of the frame containing the variable's value. | |
| 6086 </description> | |
| 6087 </param> | |
| 6088 <param id="slot"> | |
| 6089 <jint/> | |
| 6090 <description> | |
| 6091 The variable's slot number. | |
| 6092 </description> | |
| 6093 </param> | |
| 6094 <param id="value"> | |
| 6095 <jlong/> | |
| 6096 <description> | |
| 6097 The new value for the variable. | |
| 6098 </description> | |
| 6099 </param> | |
| 6100 </parameters> | |
| 6101 <errors> | |
| 6102 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6103 Invalid <code>slot</code>. | |
| 6104 </error> | |
| 6105 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6106 The variable type is not <code>long</code>. | |
| 6107 </error> | |
| 6108 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6109 Not a visible frame | |
| 6110 </error> | |
| 6111 </errors> | |
| 6112 </function> | |
| 6113 | |
| 6114 <function id="SetLocalFloat" num="29"> | |
| 6115 <synopsis>Set Local Variable - Float</synopsis> | |
| 6116 <description> | |
| 6117 This function can be used to set the value of a local | |
| 6118 variable whose type is <code>float</code>. | |
| 6119 </description> | |
| 6120 <origin>jvmdi</origin> | |
| 6121 <capabilities> | |
| 6122 <required id="can_access_local_variables"></required> | |
| 6123 </capabilities> | |
| 6124 <parameters> | |
| 6125 <param id="thread"> | |
| 6126 <jthread null="current" frame="frame"/> | |
| 6127 <description> | |
| 6128 The thread of the frame containing the variable's value. | |
| 6129 </description> | |
| 6130 </param> | |
| 6131 <param id="depth"> | |
| 6132 <jframeID thread="thread"/> | |
| 6133 <description> | |
| 6134 The depth of the frame containing the variable's value. | |
| 6135 </description> | |
| 6136 </param> | |
| 6137 <param id="slot"> | |
| 6138 <jint/> | |
| 6139 <description> | |
| 6140 The variable's slot number. | |
| 6141 </description> | |
| 6142 </param> | |
| 6143 <param id="value"> | |
| 6144 <jfloat/> | |
| 6145 <description> | |
| 6146 The new value for the variable. | |
| 6147 </description> | |
| 6148 </param> | |
| 6149 </parameters> | |
| 6150 <errors> | |
| 6151 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6152 Invalid <code>slot</code>. | |
| 6153 </error> | |
| 6154 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6155 The variable type is not <code>float</code>. | |
| 6156 </error> | |
| 6157 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6158 Not a visible frame | |
| 6159 </error> | |
| 6160 </errors> | |
| 6161 </function> | |
| 6162 | |
| 6163 <function id="SetLocalDouble" num="30"> | |
| 6164 <synopsis>Set Local Variable - Double</synopsis> | |
| 6165 <description> | |
| 6166 This function can be used to set the value of a local | |
| 6167 variable whose type is <code>double</code>. | |
| 6168 </description> | |
| 6169 <origin>jvmdi</origin> | |
| 6170 <capabilities> | |
| 6171 <required id="can_access_local_variables"></required> | |
| 6172 </capabilities> | |
| 6173 <parameters> | |
| 6174 <param id="thread"> | |
| 6175 <jthread null="current" frame="frame"/> | |
| 6176 <description> | |
| 6177 The thread of the frame containing the variable's value. | |
| 6178 </description> | |
| 6179 </param> | |
| 6180 <param id="depth"> | |
| 6181 <jframeID thread="thread"/> | |
| 6182 <description> | |
| 6183 The depth of the frame containing the variable's value. | |
| 6184 </description> | |
| 6185 </param> | |
| 6186 <param id="slot"> | |
| 6187 <jint/> | |
| 6188 <description> | |
| 6189 The variable's slot number. | |
| 6190 </description> | |
| 6191 </param> | |
| 6192 <param id="value"> | |
| 6193 <jdouble/> | |
| 6194 <description> | |
| 6195 The new value for the variable. | |
| 6196 </description> | |
| 6197 </param> | |
| 6198 </parameters> | |
| 6199 <errors> | |
| 6200 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6201 Invalid <code>slot</code>. | |
| 6202 </error> | |
| 6203 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6204 The variable type is not <code>double</code>. | |
| 6205 </error> | |
| 6206 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6207 Not a visible frame | |
| 6208 </error> | |
| 6209 </errors> | |
| 6210 </function> | |
| 6211 </category> | |
| 6212 | |
| 6213 <category id="breakpointCategory" label="Breakpoint"> | |
| 6214 | |
| 6215 <intro> | |
| 6216 </intro> | |
| 6217 | |
| 6218 <function id="SetBreakpoint" num="38"> | |
| 6219 <synopsis>Set Breakpoint</synopsis> | |
| 6220 <description> | |
| 6221 Set a breakpoint at the instruction indicated by | |
| 6222 <code>method</code> and <code>location</code>. | |
| 6223 An instruction can only have one breakpoint. | |
| 6224 <p/> | |
| 6225 Whenever the designated instruction is about to be executed, a | |
| 6226 <eventlink id="Breakpoint"></eventlink> event is generated. | |
| 6227 </description> | |
| 6228 <origin>jvmdi</origin> | |
| 6229 <capabilities> | |
| 6230 <required id="can_generate_breakpoint_events"></required> | |
| 6231 </capabilities> | |
| 6232 <parameters> | |
| 6233 <param id="klass"> | |
| 6234 <jclass method="method"/> | |
| 6235 <description> | |
| 6236 The class in which to set the breakpoint | |
| 6237 </description> | |
| 6238 </param> | |
| 6239 <param id="method"> | |
| 6240 <jmethodID class="klass"/> | |
| 6241 <description> | |
| 6242 The method in which to set the breakpoint | |
| 6243 </description> | |
| 6244 </param> | |
| 6245 <param id="location"> | |
| 6246 <jlocation/> | |
| 6247 <description> | |
| 6248 the index of the instruction at which to set the breakpoint | |
| 6249 | |
| 6250 </description> | |
| 6251 </param> | |
| 6252 </parameters> | |
| 6253 <errors> | |
| 6254 <error id="JVMTI_ERROR_DUPLICATE"> | |
| 6255 The designated bytecode already has a breakpoint. | |
| 6256 </error> | |
| 6257 </errors> | |
| 6258 </function> | |
| 6259 | |
| 6260 <function id="ClearBreakpoint" num="39"> | |
| 6261 <synopsis>Clear Breakpoint</synopsis> | |
| 6262 <description> | |
| 6263 Clear the breakpoint at the bytecode indicated by | |
| 6264 <code>method</code> and <code>location</code>. | |
| 6265 </description> | |
| 6266 <origin>jvmdi</origin> | |
| 6267 <capabilities> | |
| 6268 <required id="can_generate_breakpoint_events"></required> | |
| 6269 </capabilities> | |
| 6270 <parameters> | |
| 6271 <param id="klass"> | |
| 6272 <jclass method="method"/> | |
| 6273 <description> | |
| 6274 The class in which to clear the breakpoint | |
| 6275 </description> | |
| 6276 </param> | |
| 6277 <param id="method"> | |
| 6278 <jmethodID class="klass"/> | |
| 6279 <description> | |
| 6280 The method in which to clear the breakpoint | |
| 6281 </description> | |
| 6282 </param> | |
| 6283 <param id="location"> | |
| 6284 <jlocation/> | |
| 6285 <description> | |
| 6286 the index of the instruction at which to clear the breakpoint | |
| 6287 </description> | |
| 6288 </param> | |
| 6289 </parameters> | |
| 6290 <errors> | |
| 6291 <error id="JVMTI_ERROR_NOT_FOUND"> | |
| 6292 There's no breakpoint at the designated bytecode. | |
| 6293 </error> | |
| 6294 </errors> | |
| 6295 </function> | |
| 6296 | |
| 6297 </category> | |
| 6298 | |
| 6299 <category id="fieldWatch" label="Watched Field"> | |
| 6300 | |
| 6301 <intro> | |
| 6302 </intro> | |
| 6303 | |
| 6304 <function id="SetFieldAccessWatch" num="41"> | |
| 6305 <synopsis>Set Field Access Watch</synopsis> | |
| 6306 <description> | |
| 6307 Generate a <eventlink id="FieldAccess"></eventlink> event | |
| 6308 when the field specified | |
| 6309 by <code>klass</code> and | |
| 6310 <code>field</code> is about to be accessed. | |
| 6311 An event will be generated for each access of the field | |
| 6312 until it is canceled with | |
| 6313 <functionlink id="ClearFieldAccessWatch"></functionlink>. | |
| 6314 Field accesses from Java programming language code or from JNI code are watched, | |
| 6315 fields modified by other means are not watched. | |
| 6316 Note that <jvmti/> users should be aware that their own field accesses | |
| 6317 will trigger the watch. | |
| 6318 A field can only have one field access watch set. | |
| 6319 Modification of a field is not considered an access--use | |
| 6320 <functionlink id="SetFieldModificationWatch"></functionlink> | |
| 6321 to monitor modifications. | |
| 6322 </description> | |
| 6323 <origin>jvmdi</origin> | |
| 6324 <capabilities> | |
| 6325 <required id="can_generate_field_access_events"></required> | |
| 6326 </capabilities> | |
| 6327 <parameters> | |
| 6328 <param id="klass"> | |
| 6329 <jclass field="field"/> | |
| 6330 <description> | |
| 6331 The class containing the field to watch | |
| 6332 </description> | |
| 6333 </param> | |
| 6334 <param id="field"> | |
| 6335 <jfieldID class="klass"/> | |
| 6336 <description> | |
| 6337 The field to watch | |
| 6338 | |
| 6339 </description> | |
| 6340 </param> | |
| 6341 </parameters> | |
| 6342 <errors> | |
| 6343 <error id="JVMTI_ERROR_DUPLICATE"> | |
| 6344 The designated field is already being watched for accesses. | |
| 6345 </error> | |
| 6346 </errors> | |
| 6347 </function> | |
| 6348 | |
| 6349 <function id="ClearFieldAccessWatch" num="42"> | |
| 6350 <synopsis>Clear Field Access Watch</synopsis> | |
| 6351 <description> | |
| 6352 Cancel a field access watch previously set by | |
| 6353 <functionlink id="SetFieldAccessWatch"></functionlink>, on the | |
| 6354 field specified | |
| 6355 by <code>klass</code> and | |
| 6356 <code>field</code>. | |
| 6357 </description> | |
| 6358 <origin>jvmdi</origin> | |
| 6359 <capabilities> | |
| 6360 <required id="can_generate_field_access_events"></required> | |
| 6361 </capabilities> | |
| 6362 <parameters> | |
| 6363 <param id="klass"> | |
| 6364 <jclass field="field"/> | |
| 6365 <description> | |
| 6366 The class containing the field to watch | |
| 6367 </description> | |
| 6368 </param> | |
| 6369 <param id="field"> | |
| 6370 <jfieldID class="klass"/> | |
| 6371 <description> | |
| 6372 The field to watch | |
| 6373 | |
| 6374 </description> | |
| 6375 </param> | |
| 6376 </parameters> | |
| 6377 <errors> | |
| 6378 <error id="JVMTI_ERROR_NOT_FOUND"> | |
| 6379 The designated field is not being watched for accesses. | |
| 6380 </error> | |
| 6381 </errors> | |
| 6382 </function> | |
| 6383 | |
| 6384 <function id="SetFieldModificationWatch" num="43"> | |
| 6385 <synopsis>Set Field Modification Watch</synopsis> | |
| 6386 <description> | |
| 6387 Generate a <eventlink id="FieldModification"></eventlink> event | |
| 6388 when the field specified | |
| 6389 by <code>klass</code> and | |
| 6390 <code>field</code> is about to be modified. | |
| 6391 An event will be generated for each modification of the field | |
| 6392 until it is canceled with | |
| 6393 <functionlink id="ClearFieldModificationWatch"></functionlink>. | |
| 6394 Field modifications from Java programming language code or from JNI code are watched, | |
| 6395 fields modified by other means are not watched. | |
| 6396 Note that <jvmti/> users should be aware that their own field modifications | |
| 6397 will trigger the watch. | |
| 6398 A field can only have one field modification watch set. | |
| 6399 </description> | |
| 6400 <origin>jvmdi</origin> | |
| 6401 <capabilities> | |
| 6402 <required id="can_generate_field_modification_events"></required> | |
| 6403 </capabilities> | |
| 6404 <parameters> | |
| 6405 <param id="klass"> | |
| 6406 <jclass field="field"/> | |
| 6407 <description> | |
| 6408 The class containing the field to watch | |
| 6409 </description> | |
| 6410 </param> | |
| 6411 <param id="field"> | |
| 6412 <jfieldID class="klass"/> | |
| 6413 <description> | |
| 6414 The field to watch | |
| 6415 | |
| 6416 </description> | |
| 6417 </param> | |
| 6418 </parameters> | |
| 6419 <errors> | |
| 6420 <error id="JVMTI_ERROR_DUPLICATE"> | |
| 6421 The designated field is already being watched for modifications. | |
| 6422 </error> | |
| 6423 </errors> | |
| 6424 </function> | |
| 6425 | |
| 6426 <function id="ClearFieldModificationWatch" num="44"> | |
| 6427 <synopsis>Clear Field Modification Watch</synopsis> | |
| 6428 <description> | |
| 6429 | |
| 6430 Cancel a field modification watch previously set by | |
| 6431 <functionlink id="SetFieldModificationWatch"></functionlink>, on the | |
| 6432 field specified | |
| 6433 by <code>klass</code> and | |
| 6434 <code>field</code>. | |
| 6435 </description> | |
| 6436 <origin>jvmdi</origin> | |
| 6437 <capabilities> | |
| 6438 <required id="can_generate_field_modification_events"></required> | |
| 6439 </capabilities> | |
| 6440 <parameters> | |
| 6441 <param id="klass"> | |
| 6442 <jclass field="field"/> | |
| 6443 <description> | |
| 6444 The class containing the field to watch | |
| 6445 </description> | |
| 6446 </param> | |
| 6447 <param id="field"> | |
| 6448 <jfieldID class="klass"/> | |
| 6449 <description> | |
| 6450 The field to watch | |
| 6451 | |
| 6452 </description> | |
| 6453 </param> | |
| 6454 </parameters> | |
| 6455 <errors> | |
| 6456 <error id="JVMTI_ERROR_NOT_FOUND"> | |
| 6457 The designated field is not being watched for modifications. | |
| 6458 </error> | |
| 6459 </errors> | |
| 6460 </function> | |
| 6461 </category> | |
| 6462 | |
| 6463 <category id="class" label="Class"> | |
| 6464 | |
| 6465 <intro> | |
| 6466 </intro> | |
| 6467 | |
| 6468 <function id="GetLoadedClasses" jkernel="yes" num="78"> | |
| 6469 <synopsis>Get Loaded Classes</synopsis> | |
| 6470 <description> | |
| 6471 Return an array of all classes loaded in the virtual machine. | |
| 6472 The number of classes in the array is returned via | |
| 6473 <code>class_count_ptr</code>, and the array itself via | |
| 6474 <code>classes_ptr</code>. | |
| 6475 <p/> | |
| 6476 Array classes of all types (including arrays of primitive types) are | |
| 6477 included in the returned list. Primitive classes (for example, | |
| 6478 <code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list. | |
| 6479 </description> | |
| 6480 <origin>jvmdi</origin> | |
| 6481 <capabilities> | |
| 6482 </capabilities> | |
| 6483 <parameters> | |
| 6484 <param id="class_count_ptr"> | |
| 6485 <outptr><jint/></outptr> | |
| 6486 <description> | |
| 6487 On return, points to the number of classes. | |
| 6488 </description> | |
| 6489 </param> | |
| 6490 <param id="classes_ptr"> | |
| 6491 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf> | |
| 6492 <description> | |
| 6493 On return, points to an array of references, one | |
| 6494 for each class. | |
| 6495 </description> | |
| 6496 </param> | |
| 6497 </parameters> | |
| 6498 <errors> | |
| 6499 </errors> | |
| 6500 </function> | |
| 6501 | |
| 6502 <function id="GetClassLoaderClasses" jkernel="yes" num="79"> | |
| 6503 <synopsis>Get Classloader Classes</synopsis> | |
| 6504 <description> | |
| 6505 Returns an array of those classes for which this class loader has | |
| 6506 been recorded as an initiating loader. Each | |
| 6507 class in the returned array was created by this class loader, | |
| 6508 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
|
6509 See <vmspec chapter="5.3"/>. |
| 0 | 6510 <p/> |
| 6511 For JDK version 1.1 implementations that don't | |
| 6512 recognize the distinction between initiating and defining class loaders, | |
| 6513 this function should return all classes loaded in the virtual machine. | |
| 6514 The number of classes in the array is returned via | |
| 6515 <code>class_count_ptr</code>, and the array itself via | |
| 6516 <code>classes_ptr</code>. | |
| 6517 </description> | |
| 6518 <origin>jvmdi</origin> | |
| 6519 <capabilities> | |
| 6520 </capabilities> | |
| 6521 <parameters> | |
| 6522 <param id="initiating_loader"> | |
| 6523 <ptrtype> | |
| 6524 <jobject/> | |
| 6525 <nullok>the classes initiated by the bootstrap loader will be returned</nullok> | |
| 6526 </ptrtype> | |
| 6527 <description> | |
| 6528 An initiating class loader. | |
| 6529 </description> | |
| 6530 </param> | |
| 6531 <param id="class_count_ptr"> | |
| 6532 <outptr><jint/></outptr> | |
| 6533 <description> | |
| 6534 On return, points to the number of classes. | |
| 6535 </description> | |
| 6536 </param> | |
| 6537 <param id="classes_ptr"> | |
| 6538 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf> | |
| 6539 <description> | |
| 6540 On return, points to an array of references, one | |
| 6541 for each class. | |
| 6542 </description> | |
| 6543 </param> | |
| 6544 </parameters> | |
| 6545 <errors> | |
| 6546 </errors> | |
| 6547 </function> | |
| 6548 | |
| 6549 <function id="GetClassSignature" phase="start" num="48"> | |
| 6550 <synopsis>Get Class Signature</synopsis> | |
| 6551 <description> | |
| 6552 For the class indicated by <code>klass</code>, return the | |
| 6919 | 6553 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16432">JNI |
| 0 | 6554 type signature</externallink> |
| 6555 and the generic signature of the class. | |
| 6556 For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code> | |
| 6557 and <code>int[]</code> is <code>"[I"</code> | |
| 6558 The returned name for primitive classes | |
| 6559 is the type signature character of the corresponding primitive type. | |
| 6560 For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>. | |
| 6561 </description> | |
| 6562 <origin>jvmdiClone</origin> | |
| 6563 <capabilities> | |
| 6564 </capabilities> | |
| 6565 <parameters> | |
| 6566 <param id="klass"> | |
| 6567 <jclass/> | |
| 6568 <description> | |
| 6569 The class to query. | |
| 6570 </description> | |
| 6571 </param> | |
| 6572 <param id="signature_ptr"> | |
| 6573 <allocbuf> | |
| 6574 <char/> | |
| 6575 <nullok>the signature is not returned</nullok> | |
| 6576 </allocbuf> | |
| 6577 <description> | |
| 6578 On return, points to the JNI type signature of the class, encoded as a | |
| 6579 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 6580 </description> | |
| 6581 </param> | |
| 6582 <param id="generic_ptr"> | |
| 6583 <allocbuf> | |
| 6584 <char/> | |
| 6585 <nullok>the generic signature is not returned</nullok> | |
| 6586 </allocbuf> | |
| 6587 <description> | |
| 6588 On return, points to the generic signature of the class, encoded as a | |
| 6589 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 6590 If there is no generic signature attribute for the class, then, | |
| 6591 on return, points to <code>NULL</code>. | |
| 6592 </description> | |
| 6593 </param> | |
| 6594 </parameters> | |
| 6595 <errors> | |
| 6596 </errors> | |
| 6597 </function> | |
| 6598 | |
| 6599 <function id="GetClassStatus" phase="start" num="49"> | |
| 6600 <synopsis>Get Class Status</synopsis> | |
| 6601 <description> | |
| 6602 Get the status of the class. Zero or more of the following bits can be | |
| 6603 set. | |
| 6604 <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits"> | |
| 6605 <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1"> | |
| 6606 Class bytecodes have been verified | |
| 6607 </constant> | |
| 6608 <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2"> | |
| 6609 Class preparation is complete | |
| 6610 </constant> | |
| 6611 <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4"> | |
| 6612 Class initialization is complete. Static initializer has been run. | |
| 6613 </constant> | |
| 6614 <constant id="JVMTI_CLASS_STATUS_ERROR" num="8"> | |
| 6615 Error during initialization makes class unusable | |
| 6616 </constant> | |
| 6617 <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16"> | |
| 6618 Class is an array. If set, all other bits are zero. | |
| 6619 </constant> | |
| 6620 <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32"> | |
| 6621 Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6622 If set, all other bits are zero. | |
| 6623 </constant> | |
| 6624 </constants> | |
| 6625 </description> | |
| 6626 <origin>jvmdi</origin> | |
| 6627 <capabilities> | |
| 6628 </capabilities> | |
| 6629 <parameters> | |
| 6630 <param id="klass"> | |
| 6631 <jclass/> | |
| 6632 <description> | |
| 6633 The class to query. | |
| 6634 </description> | |
| 6635 </param> | |
| 6636 <param id="status_ptr"> | |
| 6637 <outptr><jint/></outptr> | |
| 6638 <description> | |
| 6639 On return, points to the current state of this class as one or | |
| 6640 more of the <internallink id="jvmtiClassStatus">class status flags</internallink>. | |
| 6641 </description> | |
| 6642 </param> | |
| 6643 </parameters> | |
| 6644 <errors> | |
| 6645 </errors> | |
| 6646 </function> | |
| 6647 | |
| 6648 <function id="GetSourceFileName" phase="start" num="50"> | |
| 6649 <synopsis>Get Source File Name</synopsis> | |
| 6650 <description> | |
| 6651 For the class indicated by <code>klass</code>, return the source file | |
| 6652 name via <code>source_name_ptr</code>. The returned string | |
| 6653 is a file name only and never contains a directory name. | |
| 6654 <p/> | |
| 6655 For primitive classes (for example, <code>java.lang.Integer.TYPE</code>) | |
| 6656 and for arrays this function returns | |
| 6657 <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>. | |
| 6658 </description> | |
| 6659 <origin>jvmdi</origin> | |
| 6660 <capabilities> | |
| 6661 <required id="can_get_source_file_name"></required> | |
| 6662 </capabilities> | |
| 6663 <parameters> | |
| 6664 <param id="klass"> | |
| 6665 <jclass/> | |
| 6666 <description> | |
| 6667 The class to query. | |
| 6668 </description> | |
| 6669 </param> | |
| 6670 <param id="source_name_ptr"> | |
| 6671 <allocbuf><char/></allocbuf> | |
| 6672 <description> | |
| 6673 On return, points to the class's source file name, encoded as a | |
| 6674 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 6675 </description> | |
| 6676 </param> | |
| 6677 </parameters> | |
| 6678 <errors> | |
| 6679 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 6680 Class information does not include a source file name. This includes | |
| 6681 cases where the class is an array class or primitive class. | |
| 6682 </error> | |
| 6683 </errors> | |
| 6684 </function> | |
| 6685 | |
| 6686 <function id="GetClassModifiers" phase="start" num="51"> | |
| 6687 <synopsis>Get Class Modifiers</synopsis> | |
| 6688 <description> | |
| 6689 For the class indicated by <code>klass</code>, return the access | |
| 6690 flags | |
| 6691 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
|
6692 Access flags are defined in <vmspec chapter="4"/>. |
| 0 | 6693 <p/> |
| 6694 If the class is an array class, then its public, private, and protected | |
| 6695 modifiers are the same as those of its component type. For arrays of | |
| 6696 primitives, this component type is represented by one of the primitive | |
| 6697 classes (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6698 <p/> | |
| 6699 If the class is a primitive class, its public modifier is always true, | |
| 6700 and its protected and private modifiers are always false. | |
| 6701 <p/> | |
| 6702 If the class is an array class or a primitive class then its final | |
| 6703 modifier is always true and its interface modifier is always false. | |
| 6704 The values of its other modifiers are not determined by this specification. | |
| 6705 | |
| 6706 </description> | |
| 6707 <origin>jvmdi</origin> | |
| 6708 <capabilities> | |
| 6709 </capabilities> | |
| 6710 <parameters> | |
| 6711 <param id="klass"> | |
| 6712 <jclass/> | |
| 6713 <description> | |
| 6714 The class to query. | |
| 6715 </description> | |
| 6716 </param> | |
| 6717 <param id="modifiers_ptr"> | |
| 6718 <outptr><jint/></outptr> | |
| 6719 <description> | |
| 6720 On return, points to the current access flags of this class. | |
| 6721 | |
| 6722 </description> | |
| 6723 </param> | |
| 6724 </parameters> | |
| 6725 <errors> | |
| 6726 </errors> | |
| 6727 </function> | |
| 6728 | |
| 6729 <function id="GetClassMethods" phase="start" num="52"> | |
| 6730 <synopsis>Get Class Methods</synopsis> | |
| 6731 <description> | |
| 6732 For the class indicated by <code>klass</code>, return a count of | |
| 6733 methods via <code>method_count_ptr</code> and a list of | |
| 6734 method IDs via <code>methods_ptr</code>. The method list contains | |
| 6735 constructors and static initializers as well as true methods. | |
| 6736 Only directly declared methods are returned (not inherited methods). | |
| 6737 An empty method list is returned for array classes and primitive classes | |
| 6738 (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6739 </description> | |
| 6740 <origin>jvmdi</origin> | |
| 6741 <capabilities> | |
| 6742 <capability id="can_maintain_original_method_order"/> | |
| 6743 </capabilities> | |
| 6744 <parameters> | |
| 6745 <param id="klass"> | |
| 6746 <jclass/> | |
| 6747 <description> | |
| 6748 The class to query. | |
| 6749 </description> | |
| 6750 </param> | |
| 6751 <param id="method_count_ptr"> | |
| 6752 <outptr><jint/></outptr> | |
| 6753 <description> | |
| 6754 On return, points to the number of methods declared in this class. | |
| 6755 </description> | |
| 6756 </param> | |
| 6757 <param id="methods_ptr"> | |
| 6758 <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf> | |
| 6759 <description> | |
| 6760 On return, points to the method ID array. | |
| 6761 </description> | |
| 6762 </param> | |
| 6763 </parameters> | |
| 6764 <errors> | |
| 6765 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
| 6766 <paramlink id="klass"></paramlink> is not prepared. | |
| 6767 </error> | |
| 6768 </errors> | |
| 6769 </function> | |
| 6770 | |
| 6771 <function id="GetClassFields" phase="start" num="53"> | |
| 6772 <synopsis>Get Class Fields</synopsis> | |
| 6773 <description> | |
| 6774 For the class indicated by <code>klass</code>, return a count of fields | |
| 6775 via <code>field_count_ptr</code> and a list of field IDs via | |
| 6776 <code>fields_ptr</code>. | |
| 6777 Only directly declared fields are returned (not inherited fields). | |
| 6778 Fields are returned in the order they occur in the class file. | |
| 6779 An empty field list is returned for array classes and primitive classes | |
| 6780 (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6781 Use JNI to determine the length of an array. | |
| 6782 </description> | |
| 6783 <origin>jvmdi</origin> | |
| 6784 <capabilities> | |
| 6785 </capabilities> | |
| 6786 <parameters> | |
| 6787 <param id="klass"> | |
| 6788 <jclass/> | |
| 6789 <description> | |
| 6790 The class to query. | |
| 6791 </description> | |
| 6792 </param> | |
| 6793 <param id="field_count_ptr"> | |
| 6794 <outptr><jint/></outptr> | |
| 6795 <description> | |
| 6796 On return, points to the number of fields declared in this class. | |
| 6797 </description> | |
| 6798 </param> | |
| 6799 <param id="fields_ptr"> | |
| 6800 <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf> | |
| 6801 <description> | |
| 6802 On return, points to the field ID array. | |
| 6803 </description> | |
| 6804 </param> | |
| 6805 </parameters> | |
| 6806 <errors> | |
| 6807 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
| 6808 <paramlink id="klass"></paramlink> is not prepared. | |
| 6809 </error> | |
| 6810 </errors> | |
| 6811 </function> | |
| 6812 | |
| 6813 <function id="GetImplementedInterfaces" phase="start" num="54"> | |
| 6814 <synopsis>Get Implemented Interfaces</synopsis> | |
| 6815 <description> | |
| 6816 Return the direct super-interfaces of this class. For a class, this | |
| 6817 function returns the interfaces declared in its <code>implements</code> | |
| 6818 clause. For an interface, this function returns the interfaces declared in | |
| 6819 its <code>extends</code> clause. | |
| 6820 An empty interface list is returned for array classes and primitive classes | |
| 6821 (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6822 </description> | |
| 6823 <origin>jvmdi</origin> | |
| 6824 <capabilities> | |
| 6825 </capabilities> | |
| 6826 <parameters> | |
| 6827 <param id="klass"> | |
| 6828 <jclass/> | |
| 6829 <description> | |
| 6830 The class to query. | |
| 6831 </description> | |
| 6832 </param> | |
| 6833 <param id="interface_count_ptr"> | |
| 6834 <outptr><jint/></outptr> | |
| 6835 <description> | |
| 6836 On return, points to the number of interfaces. | |
| 6837 </description> | |
| 6838 </param> | |
| 6839 <param id="interfaces_ptr"> | |
| 6840 <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf> | |
| 6841 <description> | |
| 6842 On return, points to the interface array. | |
| 6843 </description> | |
| 6844 </param> | |
| 6845 </parameters> | |
| 6846 <errors> | |
| 6847 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
| 6848 <paramlink id="klass"></paramlink> is not prepared. | |
| 6849 </error> | |
| 6850 </errors> | |
| 6851 </function> | |
| 6852 | |
| 6853 <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1"> | |
| 6854 <synopsis>Get Class Version Numbers</synopsis> | |
| 6855 <description> | |
| 6856 For the class indicated by <code>klass</code>, | |
| 6857 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
|
6858 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
|
6859 <vmspec chapter="4"/>. |
| 0 | 6860 </description> |
| 6861 <origin>new</origin> | |
| 6862 <capabilities> | |
| 6863 </capabilities> | |
| 6864 <parameters> | |
| 6865 <param id="klass"> | |
| 6866 <jclass/> | |
| 6867 <description> | |
| 6868 The class to query. | |
| 6869 </description> | |
| 6870 </param> | |
| 6871 <param id="minor_version_ptr"> | |
| 6872 <outptr><jint/></outptr> | |
| 6873 <description> | |
| 6874 On return, points to the value of the | |
| 6875 <code>minor_version</code> item of the | |
| 6876 Class File Format. | |
| 6877 Note: to be consistent with the Class File Format, | |
| 6878 the minor version number is the first parameter. | |
| 6879 </description> | |
| 6880 </param> | |
| 6881 <param id="major_version_ptr"> | |
| 6882 <outptr><jint/></outptr> | |
| 6883 <description> | |
| 6884 On return, points to the value of the | |
| 6885 <code>major_version</code> item of the | |
| 6886 Class File Format. | |
| 6887 </description> | |
| 6888 </param> | |
| 6889 </parameters> | |
| 6890 <errors> | |
| 6891 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 6892 The class is a primitive or array class. | |
| 6893 </error> | |
| 6894 </errors> | |
| 6895 </function> | |
| 6896 | |
| 6897 <function id="GetConstantPool" phase="start" num="146" since="1.1"> | |
| 6898 <synopsis>Get Constant Pool</synopsis> | |
| 6899 <description> | |
| 6900 For the class indicated by <code>klass</code>, | |
| 6901 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
|
6902 <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
|
6903 <vmspec chapter="4"/>. |
| 0 | 6904 The format of the constant pool may differ between versions |
| 6905 of the Class File Format, so, the | |
| 6906 <functionlink id="GetClassVersionNumbers">minor and major | |
| 6907 class version numbers</functionlink> should be checked for | |
| 6908 compatibility. | |
| 6909 <p/> | |
| 6910 The returned constant pool might not have the same layout or | |
| 6911 contents as the constant pool in the defining class file. | |
| 6912 The constant pool returned by GetConstantPool() may have | |
| 6913 more or fewer entries than the defining constant pool. | |
| 6914 Entries may be in a different order. | |
| 6915 The constant pool returned by GetConstantPool() will match the | |
| 6916 constant pool used by | |
| 6917 <functionlink id="GetBytecodes">GetBytecodes()</functionlink>. | |
| 6918 That is, the bytecodes returned by GetBytecodes() will have | |
| 6919 constant pool indices which refer to constant pool entries returned | |
| 6920 by GetConstantPool(). | |
| 6921 Note that since <functionlink id="RetransformClasses"/> | |
| 6922 and <functionlink id="RedefineClasses"/> can change | |
| 6923 the constant pool, the constant pool returned by this function | |
| 6924 can change accordingly. Thus, the correspondence between | |
| 6925 GetConstantPool() and GetBytecodes() does not hold if there | |
| 6926 is an intervening class retransformation or redefinition. | |
| 6927 The value of a constant pool entry used by a given bytecode will | |
| 6928 match that of the defining class file (even if the indices don't match). | |
| 6929 Constant pool entries which are not used directly or indirectly by | |
| 6930 bytecodes (for example, UTF-8 strings associated with annotations) are | |
| 6931 not required to exist in the returned constant pool. | |
| 6932 </description> | |
| 6933 <origin>new</origin> | |
| 6934 <capabilities> | |
| 6935 <required id="can_get_constant_pool"></required> | |
| 6936 </capabilities> | |
| 6937 <parameters> | |
| 6938 <param id="klass"> | |
| 6939 <jclass/> | |
| 6940 <description> | |
| 6941 The class to query. | |
| 6942 </description> | |
| 6943 </param> | |
| 6944 <param id="constant_pool_count_ptr"> | |
| 6945 <outptr><jint/></outptr> | |
| 6946 <description> | |
| 6947 On return, points to the number of entries | |
| 6948 in the constant pool table plus one. | |
| 6949 This corresponds to the <code>constant_pool_count</code> | |
| 6950 item of the Class File Format. | |
| 6951 </description> | |
| 6952 </param> | |
| 6953 <param id="constant_pool_byte_count_ptr"> | |
| 6954 <outptr><jint/></outptr> | |
| 6955 <description> | |
| 6956 On return, points to the number of bytes | |
| 6957 in the returned raw constant pool. | |
| 6958 </description> | |
| 6959 </param> | |
| 6960 <param id="constant_pool_bytes_ptr"> | |
| 6961 <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf> | |
| 6962 <description> | |
| 6963 On return, points to the raw constant pool, that is the bytes | |
| 6964 defined by the <code>constant_pool</code> item of the | |
| 6965 Class File Format | |
| 6966 </description> | |
| 6967 </param> | |
| 6968 </parameters> | |
| 6969 <errors> | |
| 6970 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 6971 The class is a primitive or array class. | |
| 6972 </error> | |
| 6973 </errors> | |
| 6974 </function> | |
| 6975 | |
| 6976 <function id="IsInterface" phase="start" num="55"> | |
| 6977 <synopsis>Is Interface</synopsis> | |
| 6978 <description> | |
| 6979 Determines whether a class object reference represents an interface. | |
| 6980 The <code>jboolean</code> result is | |
| 6981 <code>JNI_TRUE</code> if the "class" is actually an interface, | |
| 6982 <code>JNI_FALSE</code> otherwise. | |
| 6983 </description> | |
| 6984 <origin>jvmdi</origin> | |
| 6985 <capabilities> | |
| 6986 </capabilities> | |
| 6987 <parameters> | |
| 6988 <param id="klass"> | |
| 6989 <jclass/> | |
| 6990 <description> | |
| 6991 The class to query. | |
| 6992 </description> | |
| 6993 </param> | |
| 6994 <param id="is_interface_ptr"> | |
| 6995 <outptr><jboolean/></outptr> | |
| 6996 <description> | |
| 6997 On return, points to the boolean result of this function. | |
| 6998 | |
| 6999 </description> | |
| 7000 </param> | |
| 7001 </parameters> | |
| 7002 <errors> | |
| 7003 </errors> | |
| 7004 </function> | |
| 7005 | |
| 7006 <function id="IsArrayClass" phase="start" num="56"> | |
| 7007 <synopsis>Is Array Class</synopsis> | |
| 7008 <description> | |
| 7009 Determines whether a class object reference represents an array. | |
| 7010 The <code>jboolean</code> result is | |
| 7011 <code>JNI_TRUE</code> if the class is an array, | |
| 7012 <code>JNI_FALSE</code> otherwise. | |
| 7013 </description> | |
| 7014 <origin>jvmdi</origin> | |
| 7015 <capabilities> | |
| 7016 </capabilities> | |
| 7017 <parameters> | |
| 7018 <param id="klass"> | |
| 7019 <jclass/> | |
| 7020 <description> | |
| 7021 The class to query. | |
| 7022 </description> | |
| 7023 </param> | |
| 7024 <param id="is_array_class_ptr"> | |
| 7025 <outptr><jboolean/></outptr> | |
| 7026 <description> | |
| 7027 On return, points to the boolean result of this function. | |
| 7028 | |
| 7029 </description> | |
| 7030 </param> | |
| 7031 </parameters> | |
| 7032 <errors> | |
| 7033 </errors> | |
| 7034 </function> | |
| 7035 | |
| 7036 <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1"> | |
| 7037 <synopsis>Is Modifiable Class</synopsis> | |
| 7038 <description> | |
| 7039 Determines whether a class is modifiable. | |
| 7040 If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/> | |
| 7041 returns <code>JNI_TRUE</code>) the class can be | |
| 7042 redefined with <functionlink id="RedefineClasses"/> (assuming | |
| 7043 the agent possesses the | |
| 7044 <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/> | |
| 7045 capability) or | |
| 7046 retransformed with <functionlink id="RetransformClasses"/> (assuming | |
| 7047 the agent possesses the | |
| 7048 <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> | |
| 7049 capability). | |
| 7050 If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/> | |
| 7051 returns <code>JNI_FALSE</code>) the class can be neither | |
| 7052 redefined nor retransformed. | |
| 7053 <p/> | |
| 7054 Primitive classes (for example, <code>java.lang.Integer.TYPE</code>) | |
| 7055 and array classes are never modifiable. | |
| 7056 <p/> | |
| 7057 </description> | |
| 7058 <origin>new</origin> | |
| 7059 <capabilities> | |
| 7060 <capability id="can_redefine_any_class"> | |
| 7061 If possessed then all classes (except primitive and array classes) | |
| 7062 are modifiable. | |
| 7063 </capability> | |
| 7064 <capability id="can_redefine_classes"> | |
| 7065 No effect on the result of the function. | |
| 7066 But must additionally be possessed to modify the class with | |
| 7067 <functionlink id="RedefineClasses"/>. | |
| 7068 </capability> | |
| 7069 <capability id="can_retransform_classes"> | |
| 7070 No effect on the result of the function. | |
| 7071 But must additionally be possessed to modify the class with | |
| 7072 <functionlink id="RetransformClasses"/>. | |
| 7073 </capability> | |
| 7074 </capabilities> | |
| 7075 <parameters> | |
| 7076 <param id="klass"> | |
| 7077 <jclass/> | |
| 7078 <description> | |
| 7079 The class to query. | |
| 7080 </description> | |
| 7081 </param> | |
| 7082 <param id="is_modifiable_class_ptr"> | |
| 7083 <outptr><jboolean/></outptr> | |
| 7084 <description> | |
| 7085 On return, points to the boolean result of this function. | |
| 7086 </description> | |
| 7087 </param> | |
| 7088 </parameters> | |
| 7089 <errors> | |
| 7090 </errors> | |
| 7091 </function> | |
| 7092 | |
| 7093 <function id="GetClassLoader" phase="start" num="57"> | |
| 7094 <synopsis>Get Class Loader</synopsis> | |
| 7095 <description> | |
| 7096 For the class indicated by <code>klass</code>, return via | |
| 7097 <code>classloader_ptr</code> a reference to the class loader for the | |
| 7098 class. | |
| 7099 </description> | |
| 7100 <origin>jvmdi</origin> | |
| 7101 <capabilities> | |
| 7102 </capabilities> | |
| 7103 <parameters> | |
| 7104 <param id="klass"> | |
| 7105 <jclass/> | |
| 7106 <description> | |
| 7107 The class to query. | |
| 7108 </description> | |
| 7109 </param> | |
| 7110 <param id="classloader_ptr"> | |
| 7111 <outptr><jobject/></outptr> | |
| 7112 <description> | |
| 7113 On return, points to the class loader that loaded | |
| 7114 this class. | |
| 7115 If the class was not created by a class loader | |
| 7116 or if the class loader is the bootstrap class loader, | |
| 7117 points to <code>NULL</code>. | |
| 7118 </description> | |
| 7119 </param> | |
| 7120 </parameters> | |
| 7121 <errors> | |
| 7122 </errors> | |
| 7123 | |
| 7124 </function> | |
| 7125 | |
| 7126 <function id="GetSourceDebugExtension" phase="start" num="90"> | |
| 7127 <synopsis>Get Source Debug Extension</synopsis> | |
| 7128 <description> | |
| 7129 For the class indicated by <code>klass</code>, return the debug | |
| 7130 extension via <code>source_debug_extension_ptr</code>. | |
| 7131 The returned string | |
| 7132 contains exactly the debug extension information present in the | |
| 7133 class file of <code>klass</code>. | |
| 7134 </description> | |
| 7135 <origin>jvmdi</origin> | |
| 7136 <capabilities> | |
| 7137 <required id="can_get_source_debug_extension"></required> | |
| 7138 </capabilities> | |
| 7139 <parameters> | |
| 7140 <param id="klass"> | |
| 7141 <jclass/> | |
| 7142 <description> | |
| 7143 The class to query. | |
| 7144 </description> | |
| 7145 </param> | |
| 7146 <param id="source_debug_extension_ptr"> | |
| 7147 <allocbuf><char/></allocbuf> | |
| 7148 <description> | |
| 7149 On return, points to the class's debug extension, encoded as a | |
| 7150 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7151 </description> | |
| 7152 </param> | |
| 7153 </parameters> | |
| 7154 <errors> | |
| 7155 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 7156 Class information does not include a debug extension. | |
| 7157 </error> | |
| 7158 </errors> | |
| 7159 </function> | |
| 7160 | |
| 7161 <function id="RetransformClasses" jkernel="yes" num="152" since="1.1"> | |
| 7162 <synopsis>Retransform Classes</synopsis> | |
| 7163 <description> | |
| 7164 This function facilitates the | |
| 7165 <internallink id="bci">bytecode instrumentation</internallink> | |
| 7166 of already loaded classes. | |
| 7167 To replace the class definition without reference to the existing | |
| 7168 bytecodes, as one might do when recompiling from source for | |
| 7169 fix-and-continue debugging, <functionlink id="RedefineClasses"/> | |
| 7170 function should be used instead. | |
| 7171 <p/> | |
| 7172 When classes are initially loaded or when they are | |
| 7173 <functionlink id="RedefineClasses">redefined</functionlink>, | |
| 7174 the initial class file bytes can be transformed with the | |
| 7175 <eventlink id="ClassFileLoadHook"/> event. | |
| 7176 This function reruns the transformation process | |
| 7177 (whether or not a transformation has previously occurred). | |
| 7178 This retransformation follows these steps: | |
| 7179 <ul> | |
| 7180 <li>starting from the initial class file bytes | |
| 7181 </li> | |
| 7182 <li>for each <fieldlink id="can_retransform_classes" | |
| 7183 struct="jvmtiCapabilities">retransformation | |
| 7184 incapable</fieldlink> | |
| 7185 agent which received a | |
| 7186 <code>ClassFileLoadHook</code> event during the previous | |
| 7187 load or redefine, the bytes it returned | |
| 7188 (via the <code>new_class_data</code> parameter) | |
| 7189 are reused as the output of the transformation; | |
| 7190 note that this is equivalent to reapplying | |
| 7191 the previous transformation, unaltered. except that | |
| 7192 the <code>ClassFileLoadHook</code> event | |
| 7193 is <b>not</b> sent to these agents | |
| 7194 </li> | |
| 7195 <li>for each <fieldlink id="can_retransform_classes" | |
| 7196 struct="jvmtiCapabilities">retransformation | |
| 7197 capable</fieldlink> | |
| 7198 agent, the <code>ClassFileLoadHook</code> event is sent, | |
| 7199 allowing a new transformation to be applied | |
| 7200 </li> | |
| 7201 <li>the transformed class file bytes are installed as the new | |
| 7202 definition of the class | |
| 7203 </li> | |
| 7204 </ul> | |
| 7205 See the <eventlink id="ClassFileLoadHook"/> event for more details. | |
| 7206 <p/> | |
| 7207 The initial class file bytes represent the bytes passed to | |
| 7208 <code>ClassLoader.defineClass</code> | |
| 7209 or <code>RedefineClasses</code> (before any transformations | |
| 7210 were applied), however they may not exactly match them. | |
| 7211 The constant pool may differ in ways described in | |
| 7212 <functionlink id="GetConstantPool"/>. | |
| 7213 Constant pool indices in the bytecodes of methods will correspond. | |
| 7214 Some attributes may not be present. | |
| 7215 Where order is not meaningful, for example the order of methods, | |
| 7216 order may not be preserved. | |
| 7217 <p/> | |
| 7218 Retransformation can cause new versions of methods to be installed. | |
| 7219 Old method versions may become | |
| 7220 <internallink id="obsoleteMethods">obsolete</internallink> | |
| 7221 The new method version will be used on new invokes. | |
| 7222 If a method has active stack frames, those active frames continue to | |
| 7223 run the bytecodes of the original method version. | |
| 7224 <p/> | |
| 7225 This function does not cause any initialization except that which | |
| 7226 would occur under the customary JVM semantics. | |
| 7227 In other words, retransforming a class does not cause its initializers to be | |
| 7228 run. The values of static fields will remain as they were | |
| 7229 prior to the call. | |
| 7230 <p/> | |
| 7231 Threads need not be suspended. | |
| 7232 <p/> | |
| 7233 All breakpoints in the class are cleared. | |
| 7234 <p/> | |
| 7235 All attributes are updated. | |
| 7236 <p/> | |
| 7237 Instances of the retransformed class are not affected -- fields retain their | |
| 7238 previous values. | |
| 7239 <functionlink id="GetTag">Tags</functionlink> on the instances are | |
| 7240 also unaffected. | |
| 7241 <p/> | |
| 7242 In response to this call, no events other than the | |
| 7243 <eventlink id="ClassFileLoadHook"/> event | |
| 7244 will be sent. | |
| 7245 <p/> | |
| 7246 The retransformation may change method bodies, the constant pool and attributes. | |
| 7247 The retransformation must not add, remove or rename fields or methods, change the | |
| 7248 signatures of methods, change modifiers, or change inheritance. | |
| 7249 These restrictions may be lifted in future versions. | |
| 7250 See the error return description below for information on error codes | |
| 7251 returned if an unsupported retransformation is attempted. | |
| 7252 The class file bytes are not verified or installed until they have passed | |
| 7253 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the | |
| 7254 returned error code reflects the result of the transformations. | |
| 7255 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, | |
| 7256 none of the classes to be retransformed will have a new definition installed. | |
| 7257 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) | |
| 7258 all of the classes to be retransformed will have their new definitions installed. | |
| 7259 </description> | |
| 7260 <origin>new</origin> | |
| 7261 <capabilities> | |
| 7262 <required id="can_retransform_classes"></required> | |
| 7263 <capability id="can_retransform_any_class"></capability> | |
| 7264 </capabilities> | |
| 7265 <parameters> | |
| 7266 <param id="class_count"> | |
| 7267 <jint min="0"/> | |
| 7268 <description> | |
| 7269 The number of classes to be retransformed. | |
| 7270 </description> | |
| 7271 </param> | |
| 7272 <param id="classes"> | |
| 7273 <inbuf incount="class_count"><jclass/></inbuf> | |
| 7274 <description> | |
| 7275 The array of classes to be retransformed. | |
| 7276 </description> | |
| 7277 </param> | |
| 7278 </parameters> | |
| 7279 <errors> | |
| 7280 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> | |
| 7281 One of the <paramlink id="classes"/> cannot be modified. | |
| 7282 See <functionlink id="IsModifiableClass"/>. | |
| 7283 </error> | |
| 7284 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 7285 One of the <paramlink id="classes"/> is not a valid class. | |
| 7286 </error> | |
| 7287 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> | |
| 7288 A retransformed class file has a version number not supported by this VM. | |
| 7289 </error> | |
| 7290 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> | |
| 7291 A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>). | |
| 7292 </error> | |
| 7293 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> | |
| 7294 The retransformed class file definitions would lead to a circular definition | |
| 7295 (the VM would return a <code>ClassCircularityError</code>). | |
| 7296 </error> | |
| 7297 <error id="JVMTI_ERROR_FAILS_VERIFICATION"> | |
| 7298 The retransformed class file bytes fail verification. | |
| 7299 </error> | |
| 7300 <error id="JVMTI_ERROR_NAMES_DONT_MATCH"> | |
| 7301 The class name defined in a retransformed class file is | |
| 7302 different from the name in the old class object. | |
| 7303 </error> | |
| 7304 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> | |
| 7305 A retransformed class file would require adding a method. | |
| 7306 </error> | |
| 7307 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> | |
| 7308 A retransformed class file changes a field. | |
| 7309 </error> | |
| 7310 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> | |
| 7311 A direct superclass is different for a retransformed class file, | |
| 7312 or the set of directly implemented | |
| 7313 interfaces is different. | |
| 7314 </error> | |
| 7315 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> | |
| 7316 A retransformed class file does not declare a method | |
| 7317 declared in the old class version. | |
| 7318 </error> | |
| 7319 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> | |
| 7320 A retransformed class file has different class modifiers. | |
| 7321 </error> | |
| 7322 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> | |
| 7323 A method in the retransformed class file has different modifiers | |
| 7324 than its counterpart in the old class version. | |
| 7325 </error> | |
| 7326 </errors> | |
| 7327 </function> | |
| 7328 | |
| 7329 <function id="RedefineClasses" jkernel="yes" num="87"> | |
| 7330 <synopsis>Redefine Classes</synopsis> | |
| 7331 <typedef id="jvmtiClassDefinition" label="Class redefinition description"> | |
| 7332 <field id="klass"> | |
| 7333 <jclass/> | |
| 7334 <description> | |
| 7335 Class object for this class | |
| 7336 </description> | |
| 7337 </field> | |
| 7338 <field id="class_byte_count"> | |
| 7339 <jint/> | |
| 7340 <description> | |
| 7341 Number of bytes defining class (below) | |
| 7342 </description> | |
| 7343 </field> | |
| 7344 <field id="class_bytes"> | |
| 7345 <inbuf incount="class_byte_count"><uchar/></inbuf> | |
| 7346 <description> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7347 Bytes defining class (in <vmspec chapter="4"/>) |
| 0 | 7348 </description> |
| 7349 </field> | |
| 7350 </typedef> | |
| 7351 <description> | |
| 7352 All classes given are redefined according to the definitions | |
| 7353 supplied. | |
| 7354 This function is used to replace the definition of a class | |
| 7355 with a new definition, as might be needed in fix-and-continue | |
| 7356 debugging. | |
| 7357 Where the existing class file bytes are to be transformed, for | |
| 7358 example in | |
| 7359 <internallink id="bci">bytecode instrumentation</internallink>, | |
| 7360 <functionlink id="RetransformClasses"/> should be used. | |
| 7361 <p/> | |
| 7362 Redefinition can cause new versions of methods to be installed. | |
| 7363 Old method versions may become | |
| 7364 <internallink id="obsoleteMethods">obsolete</internallink> | |
| 7365 The new method version will be used on new invokes. | |
| 7366 If a method has active stack frames, those active frames continue to | |
| 7367 run the bytecodes of the original method version. | |
| 7368 If resetting of stack frames is desired, use | |
| 7369 <functionlink id="PopFrame"></functionlink> | |
| 7370 to pop frames with obsolete method versions. | |
| 7371 <p/> | |
| 7372 This function does not cause any initialization except that which | |
| 7373 would occur under the customary JVM semantics. | |
| 7374 In other words, redefining a class does not cause its initializers to be | |
| 7375 run. The values of static fields will remain as they were | |
| 7376 prior to the call. | |
| 7377 <p/> | |
| 7378 Threads need not be suspended. | |
| 7379 <p/> | |
| 7380 All breakpoints in the class are cleared. | |
| 7381 <p/> | |
| 7382 All attributes are updated. | |
| 7383 <p/> | |
| 7384 Instances of the redefined class are not affected -- fields retain their | |
| 7385 previous values. | |
| 7386 <functionlink id="GetTag">Tags</functionlink> on the instances are | |
| 7387 also unaffected. | |
| 7388 <p/> | |
| 7389 In response to this call, the <jvmti/> event | |
| 7390 <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink> | |
| 7391 will be sent (if enabled), but no other <jvmti/> events will be sent. | |
| 7392 <p/> | |
| 7393 The redefinition may change method bodies, the constant pool and attributes. | |
| 7394 The redefinition must not add, remove or rename fields or methods, change the | |
| 7395 signatures of methods, change modifiers, or change inheritance. | |
| 7396 These restrictions may be lifted in future versions. | |
| 7397 See the error return description below for information on error codes | |
| 7398 returned if an unsupported redefinition is attempted. | |
| 7399 The class file bytes are not verified or installed until they have passed | |
| 7400 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the | |
| 7401 returned error code reflects the result of the transformations applied | |
| 7402 to the bytes passed into <paramlink id="class_definitions"/>. | |
| 7403 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, | |
| 7404 none of the classes to be redefined will have a new definition installed. | |
| 7405 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) | |
| 7406 all of the classes to be redefined will have their new definitions installed. | |
| 7407 </description> | |
| 7408 <origin>jvmdi</origin> | |
| 7409 <capabilities> | |
| 7410 <required id="can_redefine_classes"></required> | |
| 7411 <capability id="can_redefine_any_class"></capability> | |
| 7412 </capabilities> | |
| 7413 <parameters> | |
| 7414 <param id="class_count"> | |
| 7415 <jint min="0"/> | |
| 7416 <description> | |
| 7417 The number of classes specified in <code>class_definitions</code> | |
| 7418 </description> | |
| 7419 </param> | |
| 7420 <param id="class_definitions"> | |
| 7421 <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf> | |
| 7422 <description> | |
| 7423 The array of new class definitions | |
| 7424 </description> | |
| 7425 </param> | |
| 7426 </parameters> | |
| 7427 <errors> | |
| 7428 <error id="JVMTI_ERROR_NULL_POINTER"> | |
| 7429 One of <code>class_bytes</code> is <code>NULL</code>. | |
| 7430 </error> | |
| 7431 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> | |
| 7432 An element of <code>class_definitions</code> cannot be modified. | |
| 7433 See <functionlink id="IsModifiableClass"/>. | |
| 7434 </error> | |
| 7435 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 7436 An element of <code>class_definitions</code> is not a valid class. | |
| 7437 </error> | |
| 7438 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> | |
| 7439 A new class file has a version number not supported by this VM. | |
| 7440 </error> | |
| 7441 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> | |
| 7442 A new class file is malformed (The VM would return a <code>ClassFormatError</code>). | |
| 7443 </error> | |
| 7444 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> | |
| 7445 The new class file definitions would lead to a circular definition | |
| 7446 (the VM would return a <code>ClassCircularityError</code>). | |
| 7447 </error> | |
| 7448 <error id="JVMTI_ERROR_FAILS_VERIFICATION"> | |
| 7449 The class bytes fail verification. | |
| 7450 </error> | |
| 7451 <error id="JVMTI_ERROR_NAMES_DONT_MATCH"> | |
| 7452 The class name defined in a new class file is | |
| 7453 different from the name in the old class object. | |
| 7454 </error> | |
| 7455 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> | |
| 7456 A new class file would require adding a method. | |
| 7457 </error> | |
| 7458 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> | |
| 7459 A new class version changes a field. | |
| 7460 </error> | |
| 7461 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> | |
| 7462 A direct superclass is different for a new class | |
| 7463 version, or the set of directly implemented | |
| 7464 interfaces is different. | |
| 7465 </error> | |
| 7466 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> | |
| 7467 A new class version does not declare a method | |
| 7468 declared in the old class version. | |
| 7469 </error> | |
| 7470 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> | |
| 7471 A new class version has different modifiers. | |
| 7472 </error> | |
| 7473 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> | |
| 7474 A method in the new class version has different modifiers | |
| 7475 than its counterpart in the old class version. | |
| 7476 </error> | |
| 7477 </errors> | |
| 7478 </function> | |
| 7479 | |
| 7480 </category> | |
| 7481 | |
| 7482 <category id="object" label="Object"> | |
| 7483 | |
| 7484 <function id="GetObjectSize" jkernel="yes" phase="start" num="154"> | |
| 7485 <synopsis>Get Object Size</synopsis> | |
| 7486 <description> | |
| 7487 For the object indicated by <code>object</code>, | |
| 7488 return via <code>size_ptr</code> the size of the object. | |
| 7489 This size is an implementation-specific approximation of | |
| 7490 the amount of storage consumed by this object. | |
| 7491 It may include some or all of the object's overhead, and thus | |
| 7492 is useful for comparison within an implementation but not | |
| 7493 between implementations. | |
| 7494 The estimate may change during a single invocation of the JVM. | |
| 7495 </description> | |
| 7496 <origin>new</origin> | |
| 7497 <capabilities> | |
| 7498 </capabilities> | |
| 7499 <parameters> | |
| 7500 <param id="object"> | |
| 7501 <jobject/> | |
| 7502 <description> | |
| 7503 The object to query. | |
| 7504 </description> | |
| 7505 </param> | |
| 7506 <param id="size_ptr"> | |
| 7507 <outptr><jlong/></outptr> | |
| 7508 <description> | |
| 7509 On return, points to the object's size in bytes. | |
| 7510 </description> | |
| 7511 </param> | |
| 7512 </parameters> | |
| 7513 <errors> | |
| 7514 </errors> | |
| 7515 </function> | |
| 7516 | |
| 7517 <function id="GetObjectHashCode" phase="start" num="58"> | |
| 7518 <synopsis>Get Object Hash Code</synopsis> | |
| 7519 <description> | |
| 7520 For the object indicated by <code>object</code>, | |
| 7521 return via <code>hash_code_ptr</code> a hash code. | |
| 7522 This hash code could be used to maintain a hash table of object references, | |
| 7523 however, on some implementations this can cause significant performance | |
| 7524 impacts--in most cases | |
| 7525 <internallink id="Heap">tags</internallink> | |
| 7526 will be a more efficient means of associating information with objects. | |
| 7527 This function guarantees | |
| 7528 the same hash code value for a particular object throughout its life | |
| 7529 </description> | |
| 7530 <origin>jvmdi</origin> | |
| 7531 <capabilities> | |
| 7532 </capabilities> | |
| 7533 <parameters> | |
| 7534 <param id="object"> | |
| 7535 <jobject/> | |
| 7536 <description> | |
| 7537 The object to query. | |
| 7538 </description> | |
| 7539 </param> | |
| 7540 <param id="hash_code_ptr"> | |
| 7541 <outptr><jint/></outptr> | |
| 7542 <description> | |
| 7543 On return, points to the object's hash code. | |
| 7544 </description> | |
| 7545 </param> | |
| 7546 </parameters> | |
| 7547 <errors> | |
| 7548 </errors> | |
| 7549 </function> | |
| 7550 | |
| 7551 <function id="GetObjectMonitorUsage" num="59"> | |
| 7552 <synopsis>Get Object Monitor Usage</synopsis> | |
| 7553 <typedef id="jvmtiMonitorUsage" label="Object monitor usage information"> | |
| 7554 <field id="owner"> | |
| 7555 <jthread/> | |
| 7556 <description> | |
| 7557 The thread owning this monitor, or <code>NULL</code> if unused | |
| 7558 </description> | |
| 7559 </field> | |
| 7560 <field id="entry_count"> | |
| 7561 <jint/> | |
| 7562 <description> | |
| 7563 The number of times the owning thread has entered the monitor | |
| 7564 </description> | |
| 7565 </field> | |
| 7566 <field id="waiter_count"> | |
| 7567 <jint/> | |
| 7568 <description> | |
| 7569 The number of threads waiting to own this monitor | |
| 7570 </description> | |
| 7571 </field> | |
| 7572 <field id="waiters"> | |
| 7573 <allocfieldbuf><jthread/></allocfieldbuf> | |
| 7574 <description> | |
| 7575 The <code>waiter_count</code> waiting threads | |
| 7576 </description> | |
| 7577 </field> | |
| 7578 <field id="notify_waiter_count"> | |
| 7579 <jint/> | |
| 7580 <description> | |
| 7581 The number of threads waiting to be notified by this monitor | |
| 7582 </description> | |
| 7583 </field> | |
| 7584 <field id="notify_waiters"> | |
| 7585 <allocfieldbuf><jthread/></allocfieldbuf> | |
| 7586 <description> | |
| 7587 The <code>notify_waiter_count</code> threads waiting to be notified | |
| 7588 </description> | |
| 7589 </field> | |
| 7590 </typedef> | |
| 7591 <description> | |
| 7592 Get information about the object's monitor. | |
| 7593 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure | |
| 7594 are filled in with information about usage of the monitor. | |
| 7595 <todo> | |
| 7596 Decide and then clarify suspend requirements. | |
| 7597 </todo> | |
| 7598 </description> | |
| 7599 <origin>jvmdi</origin> | |
| 7600 <capabilities> | |
| 7601 <required id="can_get_monitor_info"></required> | |
| 7602 </capabilities> | |
| 7603 <parameters> | |
| 7604 <param id="object"> | |
| 7605 <jobject/> | |
| 7606 <description> | |
| 7607 The object to query. | |
| 7608 </description> | |
| 7609 </param> | |
| 7610 <param id="info_ptr"> | |
| 7611 <outptr><struct>jvmtiMonitorUsage</struct></outptr> | |
| 7612 <description> | |
| 7613 On return, filled with monitor information for the | |
| 7614 specified object. | |
| 7615 </description> | |
| 7616 </param> | |
| 7617 </parameters> | |
| 7618 <errors> | |
| 7619 </errors> | |
| 7620 </function> | |
| 7621 | |
| 7622 <elide> | |
| 7623 <function id="GetObjectMonitors" num="116"> | |
| 7624 <synopsis>Get Object Monitors</synopsis> | |
| 7625 <description> | |
| 7626 Return the list of object monitors. | |
| 7627 <p/> | |
| 7628 Note: details about each monitor can be examined with | |
| 7629 <functionlink id="GetObjectMonitorUsage"></functionlink>. | |
| 7630 </description> | |
| 7631 <origin>new</origin> | |
| 7632 <capabilities> | |
| 7633 <required id="can_get_monitor_info"></required> | |
| 7634 </capabilities> | |
| 7635 <parameters> | |
| 7636 <param id="monitorCnt"> | |
| 7637 <outptr><jint/></outptr> | |
| 7638 <description> | |
| 7639 On return, pointer to the number | |
| 7640 of monitors returned in <code>monitors_ptr</code>. | |
| 7641 </description> | |
| 7642 </param> | |
| 7643 <param id="monitors_ptr"> | |
| 7644 <allocbuf outcount="monitorCnt"><jobject/></allocbuf> | |
| 7645 <description> | |
| 7646 On return, pointer to the monitor list. | |
| 7647 </description> | |
| 7648 </param> | |
| 7649 </parameters> | |
| 7650 <errors> | |
| 7651 </errors> | |
| 7652 </function> | |
| 7653 </elide> | |
| 7654 | |
| 7655 </category> | |
| 7656 | |
| 7657 <category id="fieldCategory" label="Field"> | |
| 7658 | |
| 7659 <intro> | |
| 7660 </intro> | |
| 7661 | |
| 7662 <function id="GetFieldName" phase="start" num="60"> | |
| 7663 <synopsis>Get Field Name (and Signature)</synopsis> | |
| 7664 <description> | |
| 7665 For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>, | |
| 7666 return the field name via <paramlink id="name_ptr"/> and field signature via | |
| 7667 <paramlink id="signature_ptr"/>. | |
| 7668 <p/> | |
| 7669 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
|
7670 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
|
7671 <vmspec chapter="4.3.2"/>. |
| 0 | 7672 </description> |
| 7673 <origin>jvmdiClone</origin> | |
| 7674 <capabilities> | |
| 7675 </capabilities> | |
| 7676 <parameters> | |
| 7677 <param id="klass"> | |
| 7678 <jclass field="field"/> | |
| 7679 <description> | |
| 7680 The class of the field to query. | |
| 7681 </description> | |
| 7682 </param> | |
| 7683 <param id="field"> | |
| 7684 <jfieldID class="klass"/> | |
| 7685 <description> | |
| 7686 The field to query. | |
| 7687 </description> | |
| 7688 </param> | |
| 7689 <param id="name_ptr"> | |
| 7690 <allocbuf> | |
| 7691 <char/> | |
| 7692 <nullok>the name is not returned</nullok> | |
| 7693 </allocbuf> | |
| 7694 <description> | |
| 7695 On return, points to the field name, encoded as a | |
| 7696 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7697 </description> | |
| 7698 </param> | |
| 7699 <param id="signature_ptr"> | |
| 7700 <allocbuf> | |
| 7701 <char/> | |
| 7702 <nullok>the signature is not returned</nullok> | |
| 7703 </allocbuf> | |
| 7704 <description> | |
| 7705 On return, points to the field signature, encoded as a | |
| 7706 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7707 </description> | |
| 7708 </param> | |
| 7709 <param id="generic_ptr"> | |
| 7710 <allocbuf> | |
| 7711 <char/> | |
| 7712 <nullok>the generic signature is not returned</nullok> | |
| 7713 </allocbuf> | |
| 7714 <description> | |
| 7715 On return, points to the generic signature of the field, encoded as a | |
| 7716 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7717 If there is no generic signature attribute for the field, then, | |
| 7718 on return, points to <code>NULL</code>. | |
| 7719 </description> | |
| 7720 </param> | |
| 7721 </parameters> | |
| 7722 <errors> | |
| 7723 </errors> | |
| 7724 </function> | |
| 7725 | |
| 7726 <function id="GetFieldDeclaringClass" phase="start" num="61"> | |
| 7727 <synopsis>Get Field Declaring Class</synopsis> | |
| 7728 <description> | |
| 7729 For the field indicated by <code>klass</code> and <code>field</code> | |
| 7730 return the class that defined it via <code>declaring_class_ptr</code>. | |
| 7731 The declaring class will either be <code>klass</code>, a superclass, or | |
| 7732 an implemented interface. | |
| 7733 </description> | |
| 7734 <origin>jvmdi</origin> | |
| 7735 <capabilities> | |
| 7736 </capabilities> | |
| 7737 <parameters> | |
| 7738 <param id="klass"> | |
| 7739 <jclass field="field"/> | |
| 7740 <description> | |
| 7741 The class to query. | |
| 7742 </description> | |
| 7743 </param> | |
| 7744 <param id="field"> | |
| 7745 <jfieldID class="klass"/> | |
| 7746 <description> | |
| 7747 The field to query. | |
| 7748 </description> | |
| 7749 </param> | |
| 7750 <param id="declaring_class_ptr"> | |
| 7751 <outptr><jclass/></outptr> | |
| 7752 <description> | |
| 7753 On return, points to the declaring class | |
| 7754 </description> | |
| 7755 </param> | |
| 7756 </parameters> | |
| 7757 <errors> | |
| 7758 </errors> | |
| 7759 </function> | |
| 7760 | |
| 7761 <function id="GetFieldModifiers" phase="start" num="62"> | |
| 7762 <synopsis>Get Field Modifiers</synopsis> | |
| 7763 <description> | |
| 7764 For the field indicated by <code>klass</code> and <code>field</code> | |
| 7765 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
|
7766 Access flags are defined in <vmspec chapter="4"/>. |
| 0 | 7767 </description> |
| 7768 <origin>jvmdi</origin> | |
| 7769 <capabilities> | |
| 7770 </capabilities> | |
| 7771 <parameters> | |
| 7772 <param id="klass"> | |
| 7773 <jclass field="field"/> | |
| 7774 <description> | |
| 7775 The class to query. | |
| 7776 </description> | |
| 7777 </param> | |
| 7778 <param id="field"> | |
| 7779 <jfieldID class="klass"/> | |
| 7780 <description> | |
| 7781 The field to query. | |
| 7782 </description> | |
| 7783 </param> | |
| 7784 <param id="modifiers_ptr"> | |
| 7785 <outptr><jint/></outptr> | |
| 7786 <description> | |
| 7787 On return, points to the access flags. | |
| 7788 </description> | |
| 7789 </param> | |
| 7790 </parameters> | |
| 7791 <errors> | |
| 7792 </errors> | |
| 7793 </function> | |
| 7794 | |
| 7795 <function id="IsFieldSynthetic" phase="start" num="63"> | |
| 7796 <synopsis>Is Field Synthetic</synopsis> | |
| 7797 <description> | |
| 7798 For the field indicated by <code>klass</code> and <code>field</code>, return a | |
| 7799 value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>. | |
| 7800 Synthetic fields are generated by the compiler but not present in the | |
| 7801 original source code. | |
| 7802 </description> | |
| 7803 <origin>jvmdi</origin> | |
| 7804 <capabilities> | |
| 7805 <required id="can_get_synthetic_attribute"></required> | |
| 7806 </capabilities> | |
| 7807 <parameters> | |
| 7808 <param id="klass"> | |
| 7809 <jclass field="field"/> | |
| 7810 <description> | |
| 7811 The class of the field to query. | |
| 7812 </description> | |
| 7813 </param> | |
| 7814 <param id="field"> | |
| 7815 <jfieldID class="klass"/> | |
| 7816 <description> | |
| 7817 The field to query. | |
| 7818 </description> | |
| 7819 </param> | |
| 7820 <param id="is_synthetic_ptr"> | |
| 7821 <outptr><jboolean/></outptr> | |
| 7822 <description> | |
| 7823 On return, points to the boolean result of this function. | |
| 7824 </description> | |
| 7825 </param> | |
| 7826 </parameters> | |
| 7827 <errors> | |
| 7828 </errors> | |
| 7829 </function> | |
| 7830 | |
| 7831 </category> | |
| 7832 | |
| 7833 <category id="method" label="Method"> | |
| 7834 | |
| 7835 <intro> | |
| 7836 These functions provide information about a method (represented as a | |
| 7837 <typelink id="jmethodID"/>) and set how methods are processed. | |
| 7838 </intro> | |
| 7839 | |
| 7840 <intro id="obsoleteMethods" label="Obsolete Methods"> | |
| 7841 The functions <functionlink id="RetransformClasses"/> and | |
| 7842 <functionlink id="RedefineClasses"/> can cause new versions | |
| 7843 of methods to be installed. | |
| 7844 An original version of a method is considered equivalent | |
| 7845 to the new version if: | |
| 7846 <ul> | |
| 7847 <li>their bytecodes are the same except for indices into the | |
| 7848 constant pool and </li> | |
| 7849 <li>the referenced constants are equal.</li> | |
| 7850 </ul> | |
| 7851 An original method version which is not equivalent to the | |
| 7852 new method version is called obsolete and is assigned a new method ID; | |
| 7853 the original method ID now refers to the new method version. | |
| 7854 A method ID can be tested for obsolescence with | |
| 7855 <functionlink id="IsMethodObsolete"/>. | |
| 7856 </intro> | |
| 7857 | |
| 7858 <function id="GetMethodName" phase="start" num="64"> | |
| 7859 <synopsis>Get Method Name (and Signature)</synopsis> | |
| 7860 <description> | |
| 7861 For the method indicated by <code>method</code>, | |
| 7862 return the method name via <code>name_ptr</code> and method signature via | |
| 7863 <code>signature_ptr</code>. | |
| 7864 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7865 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
|
7866 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
|
7867 <vmspec chapter="4.3.3"/>. |
| 0 | 7868 Note this is different |
| 7869 than method signatures as defined in the <i>Java Language Specification</i>. | |
| 7870 </description> | |
| 7871 <origin>jvmdiClone</origin> | |
| 7872 <capabilities> | |
| 7873 </capabilities> | |
| 7874 <parameters> | |
| 7875 <param id="method"> | |
| 7876 <jmethodID/> | |
| 7877 <description> | |
| 7878 The method to query. | |
| 7879 </description> | |
| 7880 </param> | |
| 7881 <param id="name_ptr"> | |
| 7882 <allocbuf> | |
| 7883 <char/> | |
| 7884 <nullok>the name is not returned</nullok> | |
| 7885 </allocbuf> | |
| 7886 <description> | |
| 7887 On return, points to the method name, encoded as a | |
| 7888 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7889 </description> | |
| 7890 </param> | |
| 7891 <param id="signature_ptr"> | |
| 7892 <allocbuf> | |
| 7893 <char/> | |
| 7894 <nullok>the signature is not returned</nullok> | |
| 7895 </allocbuf> | |
| 7896 <description> | |
| 7897 On return, points to the method signature, encoded as a | |
| 7898 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7899 </description> | |
| 7900 </param> | |
| 7901 <param id="generic_ptr"> | |
| 7902 <allocbuf> | |
| 7903 <char/> | |
| 7904 <nullok>the generic signature is not returned</nullok> | |
| 7905 </allocbuf> | |
| 7906 <description> | |
| 7907 On return, points to the generic signature of the method, encoded as a | |
| 7908 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7909 If there is no generic signature attribute for the method, then, | |
| 7910 on return, points to <code>NULL</code>. | |
| 7911 </description> | |
| 7912 </param> | |
| 7913 </parameters> | |
| 7914 <errors> | |
| 7915 </errors> | |
| 7916 </function> | |
| 7917 | |
| 7918 <function id="GetMethodDeclaringClass" phase="start" num="65"> | |
| 7919 <synopsis>Get Method Declaring Class</synopsis> | |
| 7920 <description> | |
| 7921 For the method indicated by <code>method</code>, | |
| 7922 return the class that defined it via <code>declaring_class_ptr</code>. | |
| 7923 </description> | |
| 7924 <origin>jvmdi</origin> | |
| 7925 <capabilities> | |
| 7926 </capabilities> | |
| 7927 <parameters> | |
| 7928 <param id="klass"> | |
| 7929 <jclass method="method"/> | |
| 7930 <description> | |
| 7931 The class to query. | |
| 7932 </description> | |
| 7933 </param> | |
| 7934 <param id="method"> | |
| 7935 <jmethodID class="klass"/> | |
| 7936 <description> | |
| 7937 The method to query. | |
| 7938 </description> | |
| 7939 </param> | |
| 7940 <param id="declaring_class_ptr"> | |
| 7941 <outptr><jclass/></outptr> | |
| 7942 <description> | |
| 7943 On return, points to the declaring class | |
| 7944 </description> | |
| 7945 </param> | |
| 7946 </parameters> | |
| 7947 <errors> | |
| 7948 </errors> | |
| 7949 </function> | |
| 7950 | |
| 7951 <function id="GetMethodModifiers" phase="start" num="66"> | |
| 7952 <synopsis>Get Method Modifiers</synopsis> | |
| 7953 <description> | |
| 7954 For the method indicated by <code>method</code>, | |
| 7955 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
|
7956 Access flags are defined in <vmspec chapter="4"/>. |
| 0 | 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"/> | |
| 7970 <description> | |
| 7971 The method to query. | |
| 7972 </description> | |
| 7973 </param> | |
| 7974 <param id="modifiers_ptr"> | |
| 7975 <outptr><jint/></outptr> | |
| 7976 <description> | |
| 7977 On return, points to the access flags. | |
| 7978 </description> | |
| 7979 </param> | |
| 7980 </parameters> | |
| 7981 <errors> | |
| 7982 </errors> | |
| 7983 </function> | |
| 7984 | |
| 7985 <function id="GetMaxLocals" phase="start" num="68"> | |
| 7986 <synopsis>Get Max Locals</synopsis> | |
| 7987 <description> | |
| 7988 For the method indicated by <code>method</code>, | |
| 7989 return the number of local variable slots used by the method, | |
| 7990 including the local variables used to pass parameters to the | |
| 7991 method on its invocation. | |
| 7992 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7993 See <code>max_locals</code> in <vmspec chapter="4.7.3"/>. |
| 0 | 7994 </description> |
| 7995 <origin>jvmdi</origin> | |
| 7996 <capabilities> | |
| 7997 </capabilities> | |
| 7998 <parameters> | |
| 7999 <param id="klass"> | |
| 8000 <jclass method="method"/> | |
| 8001 <description> | |
| 8002 The class to query. | |
| 8003 </description> | |
| 8004 </param> | |
| 8005 <param id="method"> | |
| 8006 <jmethodID class="klass" native="error"/> | |
| 8007 <description> | |
| 8008 The method to query. | |
| 8009 </description> | |
| 8010 </param> | |
| 8011 <param id="max_ptr"> | |
| 8012 <outptr><jint/></outptr> | |
| 8013 <description> | |
| 8014 On return, points to the maximum number of local slots | |
| 8015 </description> | |
| 8016 </param> | |
| 8017 </parameters> | |
| 8018 <errors> | |
| 8019 </errors> | |
| 8020 </function> | |
| 8021 | |
| 8022 <function id="GetArgumentsSize" phase="start" num="69"> | |
| 8023 <synopsis>Get Arguments Size</synopsis> | |
| 8024 <description> | |
| 8025 For the method indicated by <code>method</code>, | |
| 8026 return via <code>max_ptr</code> the number of local variable slots used | |
| 8027 by the method's arguments. | |
| 8028 Note that two-word arguments use two slots. | |
| 8029 </description> | |
| 8030 <origin>jvmdi</origin> | |
| 8031 <capabilities> | |
| 8032 </capabilities> | |
| 8033 <parameters> | |
| 8034 <param id="klass"> | |
| 8035 <jclass method="method"/> | |
| 8036 <description> | |
| 8037 The class to query. | |
| 8038 </description> | |
| 8039 </param> | |
| 8040 <param id="method"> | |
| 8041 <jmethodID class="klass" native="error"/> | |
| 8042 <description> | |
| 8043 The method to query. | |
| 8044 </description> | |
| 8045 </param> | |
| 8046 <param id="size_ptr"> | |
| 8047 <outptr><jint/></outptr> | |
| 8048 <description> | |
| 8049 On return, points to the number of argument slots | |
| 8050 </description> | |
| 8051 </param> | |
| 8052 </parameters> | |
| 8053 <errors> | |
| 8054 </errors> | |
| 8055 </function> | |
| 8056 | |
| 8057 <function id="GetLineNumberTable" phase="start" num="70"> | |
| 8058 <synopsis>Get Line Number Table</synopsis> | |
| 8059 <typedef id="jvmtiLineNumberEntry" label="Line number table entry"> | |
| 8060 <field id="start_location"> | |
| 8061 <jlocation/> | |
| 8062 <description> | |
| 8063 the <datalink id="jlocation"></datalink> where the line begins | |
| 8064 </description> | |
| 8065 </field> | |
| 8066 <field id="line_number"> | |
| 8067 <jint/> | |
| 8068 <description> | |
| 8069 the line number | |
| 8070 </description> | |
| 8071 </field> | |
| 8072 </typedef> | |
| 8073 <description> | |
| 8074 For the method indicated by <code>method</code>, | |
| 8075 return a table of source line number entries. The size of the table is | |
| 8076 returned via <code>entry_count_ptr</code> and the table itself is | |
| 8077 returned via <code>table_ptr</code>. | |
| 8078 </description> | |
| 8079 <origin>jvmdi</origin> | |
| 8080 <capabilities> | |
| 8081 <required id="can_get_line_numbers"></required> | |
| 8082 </capabilities> | |
| 8083 <parameters> | |
| 8084 <param id="klass"> | |
| 8085 <jclass method="method"/> | |
| 8086 <description> | |
| 8087 The class to query. | |
| 8088 </description> | |
| 8089 </param> | |
| 8090 <param id="method"> | |
| 8091 <jmethodID class="klass" native="error"/> | |
| 8092 <description> | |
| 8093 The method to query. | |
| 8094 </description> | |
| 8095 </param> | |
| 8096 <param id="entry_count_ptr"> | |
| 8097 <outptr><jint/></outptr> | |
| 8098 <description> | |
| 8099 On return, points to the number of entries in the table | |
| 8100 </description> | |
| 8101 </param> | |
| 8102 <param id="table_ptr"> | |
| 8103 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf> | |
| 8104 <description> | |
| 8105 On return, points to the line number table pointer. | |
| 8106 </description> | |
| 8107 </param> | |
| 8108 </parameters> | |
| 8109 <errors> | |
| 8110 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 8111 Class information does not include line numbers. | |
| 8112 </error> | |
| 8113 </errors> | |
| 8114 </function> | |
| 8115 | |
| 8116 <function id="GetMethodLocation" phase="start" num="71"> | |
| 8117 <synopsis>Get Method Location</synopsis> | |
| 8118 <description> | |
| 8119 For the method indicated by <code>method</code>, | |
| 8120 return the beginning and ending addresses through | |
| 8121 <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a | |
| 8122 conventional byte code indexing scheme, | |
| 8123 <code>start_location_ptr</code> will always point to zero | |
| 8124 and <code>end_location_ptr</code> | |
| 8125 will always point to the byte code count minus one. | |
| 8126 </description> | |
| 8127 <origin>jvmdi</origin> | |
| 8128 <capabilities> | |
| 8129 </capabilities> | |
| 8130 <parameters> | |
| 8131 <param id="klass"> | |
| 8132 <jclass method="method"/> | |
| 8133 <description> | |
| 8134 The class to query. | |
| 8135 </description> | |
| 8136 </param> | |
| 8137 <param id="method"> | |
| 8138 <jmethodID class="klass" native="error"/> | |
| 8139 <description> | |
| 8140 The method to query. | |
| 8141 </description> | |
| 8142 </param> | |
| 8143 <param id="start_location_ptr"> | |
| 8144 <outptr><jlocation/></outptr> | |
| 8145 <description> | |
| 8146 On return, points to the first location, or | |
| 8147 <code>-1</code> if location information is not available. | |
| 8148 If the information is available and | |
| 8149 <functionlink id="GetJLocationFormat"></functionlink> | |
| 8150 returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink> | |
| 8151 then this will always be zero. | |
| 8152 </description> | |
| 8153 </param> | |
| 8154 <param id="end_location_ptr"> | |
| 8155 <outptr><jlocation/></outptr> | |
| 8156 <description> | |
| 8157 On return, points to the last location, | |
| 8158 or <code>-1</code> if location information is not available. | |
| 8159 </description> | |
| 8160 </param> | |
| 8161 </parameters> | |
| 8162 <errors> | |
| 8163 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 8164 Class information does not include method sizes. | |
| 8165 </error> | |
| 8166 </errors> | |
| 8167 </function> | |
| 8168 | |
| 8169 <function id="GetLocalVariableTable" num="72"> | |
| 8170 <synopsis>Get Local Variable Table</synopsis> | |
| 8171 <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry"> | |
| 8172 <field id="start_location"> | |
| 8173 <jlocation/> | |
| 8174 <description> | |
| 8175 The code array index where the local variable is first valid | |
| 8176 (that is, where it must have a value). | |
| 8177 </description> | |
| 8178 </field> | |
| 8179 <field id="length"> | |
| 8180 <jint/> | |
| 8181 <description> | |
| 8182 The length of the valid section for this local variable. | |
| 8183 The last code array index where the local variable is valid | |
| 8184 is <code>start_location + length</code>. | |
| 8185 </description> | |
| 8186 </field> | |
| 8187 <field id="name"> | |
| 8188 <allocfieldbuf><char/></allocfieldbuf> | |
| 8189 <description> | |
| 8190 The local variable name, encoded as a | |
| 8191 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8192 </description> | |
| 8193 </field> | |
| 8194 <field id="signature"> | |
| 8195 <allocfieldbuf><char/></allocfieldbuf> | |
| 8196 <description> | |
| 8197 The local variable's type signature, encoded as a | |
| 8198 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8199 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
|
8200 <vmspec chapter="4.3.2"/>. |
| 0 | 8201 </description> |
| 8202 </field> | |
| 8203 <field id="generic_signature"> | |
| 8204 <allocfieldbuf><char/></allocfieldbuf> | |
| 8205 <description> | |
| 8206 The local variable's generic signature, encoded as a | |
| 8207 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8208 The value of this field will be <code>NULL</code> for any local | |
| 8209 variable which does not have a generic type. | |
| 8210 </description> | |
| 8211 </field> | |
| 8212 <field id="slot"> | |
| 8213 <jint/> | |
| 8214 <description> | |
| 8215 The local variable's slot. See <internallink id="local">Local Variables</internallink>. | |
| 8216 </description> | |
| 8217 </field> | |
| 8218 </typedef> | |
| 8219 <description> | |
| 8220 Return local variable information. | |
| 8221 </description> | |
| 8222 <origin>jvmdiClone</origin> | |
| 8223 <capabilities> | |
| 8224 <required id="can_access_local_variables"></required> | |
| 8225 </capabilities> | |
| 8226 <parameters> | |
| 8227 <param id="method"> | |
| 8228 <jmethodID native="error"/> | |
| 8229 <description> | |
| 8230 The method to query. | |
| 8231 </description> | |
| 8232 </param> | |
| 8233 <param id="entry_count_ptr"> | |
| 8234 <outptr><jint/></outptr> | |
| 8235 <description> | |
| 8236 On return, points to the number of entries in the table | |
| 8237 </description> | |
| 8238 </param> | |
| 8239 <param id="table_ptr"> | |
| 8240 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf> | |
| 8241 <description> | |
| 8242 On return, points to an array of local variable table entries. | |
| 8243 </description> | |
| 8244 </param> | |
| 8245 </parameters> | |
| 8246 <errors> | |
| 8247 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 8248 Class information does not include local variable | |
| 8249 information. | |
| 8250 </error> | |
| 8251 </errors> | |
| 8252 </function> | |
| 8253 | |
| 8254 <function id="GetBytecodes" phase="start" num="75"> | |
| 8255 <synopsis>Get Bytecodes</synopsis> | |
| 8256 <description> | |
| 8257 For the method indicated by <code>method</code>, | |
| 8258 return the byte codes that implement the method. The number of | |
| 8259 bytecodes is returned via <code>bytecode_count_ptr</code>. The byte codes | |
| 8260 themselves are returned via <code>bytecodes_ptr</code>. | |
| 8261 </description> | |
| 8262 <origin>jvmdi</origin> | |
| 8263 <capabilities> | |
| 8264 <required id="can_get_bytecodes"></required> | |
| 8265 </capabilities> | |
| 8266 <parameters> | |
| 8267 <param id="klass"> | |
| 8268 <jclass method="method"/> | |
| 8269 <description> | |
| 8270 The class to query. | |
| 8271 </description> | |
| 8272 </param> | |
| 8273 <param id="method"> | |
| 8274 <jmethodID class="klass" native="error"/> | |
| 8275 <description> | |
| 8276 The method to query. | |
| 8277 </description> | |
| 8278 </param> | |
| 8279 <param id="bytecode_count_ptr"> | |
| 8280 <outptr><jint/></outptr> | |
| 8281 <description> | |
| 8282 On return, points to the length of the byte code array | |
| 8283 </description> | |
| 8284 </param> | |
| 8285 <param id="bytecodes_ptr"> | |
| 8286 <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf> | |
| 8287 <description> | |
| 8288 On return, points to the pointer to the byte code array | |
| 8289 </description> | |
| 8290 </param> | |
| 8291 </parameters> | |
| 8292 <errors> | |
| 8293 </errors> | |
| 8294 </function> | |
| 8295 | |
| 8296 <function id="IsMethodNative" phase="start" num="76"> | |
| 8297 <synopsis>Is Method Native</synopsis> | |
| 8298 <description> | |
| 8299 For the method indicated by <code>method</code>, return a | |
| 8300 value indicating whether the method is native via <code>is_native_ptr</code> | |
| 8301 </description> | |
| 8302 <origin>jvmdi</origin> | |
| 8303 <capabilities> | |
| 8304 </capabilities> | |
| 8305 <parameters> | |
| 8306 <param id="klass"> | |
| 8307 <jclass method="method"/> | |
| 8308 <description> | |
| 8309 The class to query. | |
| 8310 </description> | |
| 8311 </param> | |
| 8312 <param id="method"> | |
| 8313 <jmethodID class="klass"/> | |
| 8314 <description> | |
| 8315 The method to query. | |
| 8316 </description> | |
| 8317 </param> | |
| 8318 <param id="is_native_ptr"> | |
| 8319 <outptr><jboolean/></outptr> | |
| 8320 <description> | |
| 8321 On return, points to the boolean result of this function. | |
| 8322 </description> | |
| 8323 </param> | |
| 8324 </parameters> | |
| 8325 <errors> | |
| 8326 </errors> | |
| 8327 </function> | |
| 8328 | |
| 8329 <function id="IsMethodSynthetic" phase="start" num="77"> | |
| 8330 <synopsis>Is Method Synthetic</synopsis> | |
| 8331 <description> | |
| 8332 For the method indicated by <code>method</code>, return a | |
| 8333 value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>. | |
| 8334 Synthetic methods are generated by the compiler but not present in the | |
| 8335 original source code. | |
| 8336 </description> | |
| 8337 <origin>jvmdi</origin> | |
| 8338 <capabilities> | |
| 8339 <required id="can_get_synthetic_attribute"></required> | |
| 8340 </capabilities> | |
| 8341 <parameters> | |
| 8342 <param id="klass"> | |
| 8343 <jclass method="method"/> | |
| 8344 <description> | |
| 8345 The class to query. | |
| 8346 </description> | |
| 8347 </param> | |
| 8348 <param id="method"> | |
| 8349 <jmethodID class="klass"/> | |
| 8350 <description> | |
| 8351 The method to query. | |
| 8352 </description> | |
| 8353 </param> | |
| 8354 <param id="is_synthetic_ptr"> | |
| 8355 <outptr><jboolean/></outptr> | |
| 8356 <description> | |
| 8357 On return, points to the boolean result of this function. | |
| 8358 </description> | |
| 8359 </param> | |
| 8360 </parameters> | |
| 8361 <errors> | |
| 8362 </errors> | |
| 8363 </function> | |
| 8364 | |
| 8365 <function id="IsMethodObsolete" phase="start" num="91"> | |
| 8366 <synopsis>Is Method Obsolete</synopsis> | |
| 8367 <description> | |
| 8368 Determine if a method ID refers to an | |
| 8369 <internallink id="obsoleteMethods">obsolete</internallink> | |
| 8370 method version. | |
| 8371 </description> | |
| 8372 <origin>jvmdi</origin> | |
| 8373 <capabilities> | |
| 8374 </capabilities> | |
| 8375 <parameters> | |
| 8376 <param id="klass"> | |
| 8377 <jclass method="method"/> | |
| 8378 <description> | |
| 8379 The class to query. | |
| 8380 </description> | |
| 8381 </param> | |
| 8382 <param id="method"> | |
| 8383 <jmethodID class="klass"/> | |
| 8384 <description> | |
| 8385 The method ID to query. | |
| 8386 </description> | |
| 8387 </param> | |
| 8388 <param id="is_obsolete_ptr"> | |
| 8389 <outptr><jboolean/></outptr> | |
| 8390 <description> | |
| 8391 On return, points to the boolean result of this function. | |
| 8392 </description> | |
| 8393 </param> | |
| 8394 </parameters> | |
| 8395 <errors> | |
| 8396 </errors> | |
| 8397 </function> | |
| 8398 | |
| 8399 <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1"> | |
| 8400 <synopsis>Set Native Method Prefix</synopsis> | |
| 8401 <description> | |
| 8402 This function modifies the failure handling of | |
| 8403 native method resolution by allowing retry | |
| 8404 with a prefix applied to the name. | |
| 8405 When used with the | |
| 8406 <eventlink id="ClassFileLoadHook">ClassFileLoadHook | |
| 8407 event</eventlink>, it enables native methods to be | |
| 8408 <internallink id="bci">instrumented</internallink>. | |
| 8409 <p/> | |
| 8410 Since native methods cannot be directly instrumented | |
| 8411 (they have no bytecodes), they must be wrapped with | |
| 8412 a non-native method which can be instrumented. | |
| 8413 For example, if we had: | |
| 8414 <example> | |
| 8415 native boolean foo(int x);</example> | |
| 8416 <p/> | |
| 8417 We could transform the class file (with the | |
| 8418 ClassFileLoadHook event) so that this becomes: | |
| 8419 <example> | |
| 8420 boolean foo(int x) { | |
| 8421 <i>... record entry to foo ...</i> | |
| 8422 return wrapped_foo(x); | |
| 8423 } | |
| 8424 | |
| 8425 native boolean wrapped_foo(int x);</example> | |
| 8426 <p/> | |
| 8427 Where foo becomes a wrapper for the actual native method | |
| 8428 with the appended prefix "wrapped_". Note that | |
| 8429 "wrapped_" would be a poor choice of prefix since it | |
| 8430 might conceivably form the name of an existing method | |
| 8431 thus something like "$$$MyAgentWrapped$$$_" would be | |
| 8432 better but would make these examples less readable. | |
| 8433 <p/> | |
| 8434 The wrapper will allow data to be collected on the native | |
| 8435 method call, but now the problem becomes linking up the | |
| 8436 wrapped method with the native implementation. | |
| 8437 That is, the method <code>wrapped_foo</code> needs to be | |
| 8438 resolved to the native implementation of <code>foo</code>, | |
| 8439 which might be: | |
| 8440 <example> | |
| 8441 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example> | |
| 8442 <p/> | |
| 8443 This function allows the prefix to be specified and the | |
| 8444 proper resolution to occur. | |
| 8445 Specifically, when the standard resolution fails, the | |
| 8446 resolution is retried taking the prefix into consideration. | |
| 8447 There are two ways that resolution occurs, explicit | |
| 8448 resolution with the JNI function <code>RegisterNatives</code> | |
| 8449 and the normal automatic resolution. For | |
| 8450 <code>RegisterNatives</code>, the VM will attempt this | |
| 8451 association: | |
| 8452 <example> | |
| 8453 method(foo) -> nativeImplementation(foo)</example> | |
| 8454 <p/> | |
| 8455 When this fails, the resolution will be retried with | |
| 8456 the specified prefix prepended to the method name, | |
| 8457 yielding the correct resolution: | |
| 8458 <example> | |
| 8459 method(wrapped_foo) -> nativeImplementation(foo)</example> | |
| 8460 <p/> | |
| 8461 For automatic resolution, the VM will attempt: | |
| 8462 <example> | |
| 8463 method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example> | |
| 8464 <p/> | |
| 8465 When this fails, the resolution will be retried with | |
| 8466 the specified prefix deleted from the implementation name, | |
| 8467 yielding the correct resolution: | |
| 8468 <example> | |
| 8469 method(wrapped_foo) -> nativeImplementation(foo)</example> | |
| 8470 <p/> | |
| 8471 Note that since the prefix is only used when standard | |
| 8472 resolution fails, native methods can be wrapped selectively. | |
| 8473 <p/> | |
| 8474 Since each <jvmti/> environment is independent and | |
| 8475 can do its own transformation of the bytecodes, more | |
| 8476 than one layer of wrappers may be applied. Thus each | |
| 8477 environment needs its own prefix. Since transformations | |
| 8478 are applied in order, the prefixes, if applied, will | |
| 8479 be applied in the same order. | |
| 8480 The order of transformation application is described in | |
| 8481 the <eventlink id="ClassFileLoadHook"/> event. | |
| 8482 Thus if three environments applied | |
| 8483 wrappers, <code>foo</code> might become | |
| 8484 <code>$env3_$env2_$env1_foo</code>. But if, say, | |
| 8485 the second environment did not apply a wrapper to | |
| 8486 <code>foo</code> it would be just | |
| 8487 <code>$env3_$env1_foo</code>. To be able to | |
| 8488 efficiently determine the sequence of prefixes, | |
| 8489 an intermediate prefix is only applied if its non-native | |
| 8490 wrapper exists. Thus, in the last example, even though | |
| 8491 <code>$env1_foo</code> is not a native method, the | |
| 8492 <code>$env1_</code> prefix is applied since | |
| 8493 <code>$env1_foo</code> exists. | |
| 8494 <p/> | |
| 8495 Since the prefixes are used at resolution time | |
| 8496 and since resolution may be arbitrarily delayed, a | |
| 8497 native method prefix must remain set as long as there | |
| 8498 are corresponding prefixed native methods. | |
| 8499 </description> | |
| 8500 <origin>new</origin> | |
| 8501 <capabilities> | |
| 8502 <required id="can_set_native_method_prefix"></required> | |
| 8503 </capabilities> | |
| 8504 <parameters> | |
| 8505 <param id="prefix"> | |
| 8506 <inbuf> | |
| 8507 <char/> | |
| 8508 <nullok> | |
| 8509 any existing prefix in this environment is cancelled | |
| 8510 </nullok> | |
| 8511 </inbuf> | |
| 8512 <description> | |
| 8513 The prefix to apply, encoded as a | |
| 8514 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8515 </description> | |
| 8516 </param> | |
| 8517 </parameters> | |
| 8518 <errors> | |
| 8519 </errors> | |
| 8520 </function> | |
| 8521 | |
| 8522 <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1"> | |
| 8523 <synopsis>Set Native Method Prefixes</synopsis> | |
| 8524 <description> | |
| 8525 For a normal agent, <functionlink id="SetNativeMethodPrefix"/> | |
| 8526 will provide all needed native method prefixing. | |
| 8527 For a meta-agent that performs multiple independent class | |
| 8528 file transformations (for example as a proxy for another | |
| 8529 layer of agents) this function allows each transformation | |
| 8530 to have its own prefix. | |
| 8531 The prefixes are applied in the order supplied and are | |
| 8532 processed in the same manor as described for the | |
| 8533 application of prefixes from multiple <jvmti/> environments | |
| 8534 in <functionlink id="SetNativeMethodPrefix"/>. | |
| 8535 <p/> | |
| 8536 Any previous prefixes are replaced. Thus, calling this | |
| 8537 function with a <paramlink id="prefix_count"/> of <code>0</code> | |
| 8538 disables prefixing in this environment. | |
| 8539 <p/> | |
| 8540 <functionlink id="SetNativeMethodPrefix"/> and this function | |
| 8541 are the two ways to set the prefixes. | |
| 8542 Calling <code>SetNativeMethodPrefix</code> with | |
| 8543 a prefix is the same as calling this function with | |
| 8544 <paramlink id="prefix_count"/> of <code>1</code>. | |
| 8545 Calling <code>SetNativeMethodPrefix</code> with | |
| 8546 <code>NULL</code> is the same as calling this function with | |
| 8547 <paramlink id="prefix_count"/> of <code>0</code>. | |
| 8548 </description> | |
| 8549 <origin>new</origin> | |
| 8550 <capabilities> | |
| 8551 <required id="can_set_native_method_prefix"></required> | |
| 8552 </capabilities> | |
| 8553 <parameters> | |
| 8554 <param id="prefix_count"> | |
| 8555 <jint min="0"/> | |
| 8556 <description> | |
| 8557 The number of prefixes to apply. | |
| 8558 </description> | |
| 8559 </param> | |
| 8560 <param id="prefixes"> | |
| 8561 <agentbuf> | |
| 8562 <char/> | |
| 8563 </agentbuf> | |
| 8564 <description> | |
| 8565 The prefixes to apply for this environment, each encoded as a | |
| 8566 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8567 </description> | |
| 8568 </param> | |
| 8569 </parameters> | |
| 8570 <errors> | |
| 8571 </errors> | |
| 8572 </function> | |
| 8573 | |
| 8574 </category> | |
| 8575 | |
| 8576 <category id="RawMonitors" label="Raw Monitor"> | |
| 8577 | |
| 8578 <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31"> | |
| 8579 <synopsis>Create Raw Monitor</synopsis> | |
| 8580 <description> | |
| 8581 Create a raw monitor. | |
| 8582 </description> | |
| 8583 <origin>jvmdi</origin> | |
| 8584 <capabilities> | |
| 8585 </capabilities> | |
| 8586 <parameters> | |
| 8587 <param id="name"> | |
| 8588 <inbuf><char/></inbuf> | |
| 8589 <description> | |
| 8590 A name to identify the monitor, encoded as a | |
| 8591 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8592 </description> | |
| 8593 </param> | |
| 8594 <param id="monitor_ptr"> | |
| 8595 <outptr><jrawMonitorID/></outptr> | |
| 8596 <description> | |
| 8597 On return, points to the created monitor. | |
| 8598 </description> | |
| 8599 </param> | |
| 8600 </parameters> | |
| 8601 <errors> | |
| 8602 </errors> | |
| 8603 </function> | |
| 8604 | |
| 8605 <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32"> | |
| 8606 <synopsis>Destroy Raw Monitor</synopsis> | |
| 8607 <description> | |
| 8608 Destroy the raw monitor. | |
| 8609 If the monitor being destroyed has been entered by this thread, it will be | |
| 8610 exited before it is destroyed. | |
| 8611 If the monitor being destroyed has been entered by another thread, | |
| 8612 an error will be returned and the monitor will not be destroyed. | |
| 8613 </description> | |
| 8614 <origin>jvmdi</origin> | |
| 8615 <capabilities> | |
| 8616 </capabilities> | |
| 8617 <parameters> | |
| 8618 <param id="monitor"> | |
| 8619 <jrawMonitorID/> | |
| 8620 <description> | |
| 8621 The monitor | |
| 8622 </description> | |
| 8623 </param> | |
| 8624 </parameters> | |
| 8625 <errors> | |
| 8626 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8627 Not monitor owner | |
| 8628 </error> | |
| 8629 </errors> | |
| 8630 </function> | |
| 8631 | |
| 8632 <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33"> | |
| 8633 <synopsis>Raw Monitor Enter</synopsis> | |
| 8634 <description> | |
| 8635 Gain exclusive ownership of a raw monitor. | |
| 8636 The same thread may enter a monitor more then once. | |
| 8637 The thread must | |
| 8638 <functionlink id="RawMonitorExit">exit</functionlink> | |
| 8639 the monitor the same number of times as it is entered. | |
| 8640 If a monitor is entered during <code>OnLoad</code> (before attached threads exist) | |
| 8641 and has not exited when attached threads come into existence, the enter | |
| 8642 is considered to have occurred on the main thread. | |
| 8643 </description> | |
| 8644 <origin>jvmdi</origin> | |
| 8645 <capabilities> | |
| 8646 </capabilities> | |
| 8647 <parameters> | |
| 8648 <param id="monitor"> | |
| 8649 <jrawMonitorID/> | |
| 8650 <description> | |
| 8651 The monitor | |
| 8652 </description> | |
| 8653 </param> | |
| 8654 </parameters> | |
| 8655 <errors> | |
| 8656 </errors> | |
| 8657 </function> | |
| 8658 | |
| 8659 <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34"> | |
| 8660 <synopsis>Raw Monitor Exit</synopsis> | |
| 8661 <description> | |
| 8662 Release exclusive ownership of a raw monitor. | |
| 8663 </description> | |
| 8664 <origin>jvmdi</origin> | |
| 8665 <capabilities> | |
| 8666 </capabilities> | |
| 8667 <parameters> | |
| 8668 <param id="monitor"> | |
| 8669 <jrawMonitorID/> | |
| 8670 <description> | |
| 8671 The monitor | |
| 8672 </description> | |
| 8673 </param> | |
| 8674 </parameters> | |
| 8675 <errors> | |
| 8676 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8677 Not monitor owner | |
| 8678 </error> | |
| 8679 </errors> | |
| 8680 </function> | |
| 8681 | |
| 8682 <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35"> | |
| 8683 <synopsis>Raw Monitor Wait</synopsis> | |
| 8684 <description> | |
| 8685 Wait for notification of the raw monitor. | |
| 8686 <p/> | |
| 8687 Causes the current thread to wait until either another thread calls | |
| 8688 <functionlink id="RawMonitorNotify"/> or | |
| 8689 <functionlink id="RawMonitorNotifyAll"/> | |
| 8690 for the specified raw monitor, or the specified | |
| 8691 <paramlink id="millis">timeout</paramlink> | |
| 8692 has elapsed. | |
| 8693 </description> | |
| 8694 <origin>jvmdi</origin> | |
| 8695 <capabilities> | |
| 8696 </capabilities> | |
| 8697 <parameters> | |
| 8698 <param id="monitor"> | |
| 8699 <jrawMonitorID/> | |
| 8700 <description> | |
| 8701 The monitor | |
| 8702 </description> | |
| 8703 </param> | |
| 8704 <param id="millis"> | |
| 8705 <jlong/> | |
| 8706 <description> | |
| 8707 The timeout, in milliseconds. If the timeout is | |
| 8708 zero, then real time is not taken into consideration | |
| 8709 and the thread simply waits until notified. | |
| 8710 </description> | |
| 8711 </param> | |
| 8712 </parameters> | |
| 8713 <errors> | |
| 8714 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8715 Not monitor owner | |
| 8716 </error> | |
| 8717 <error id="JVMTI_ERROR_INTERRUPT"> | |
| 8718 Wait was interrupted, try again | |
| 8719 </error> | |
| 8720 </errors> | |
| 8721 </function> | |
| 8722 | |
| 8723 <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36"> | |
| 8724 <synopsis>Raw Monitor Notify</synopsis> | |
| 8725 <description> | |
| 8726 Notify a single thread waiting on the raw monitor. | |
| 8727 </description> | |
| 8728 <origin>jvmdi</origin> | |
| 8729 <capabilities> | |
| 8730 </capabilities> | |
| 8731 <parameters> | |
| 8732 <param id="monitor"> | |
| 8733 <jrawMonitorID/> | |
| 8734 <description> | |
| 8735 The monitor | |
| 8736 </description> | |
| 8737 </param> | |
| 8738 </parameters> | |
| 8739 <errors> | |
| 8740 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8741 Not monitor owner | |
| 8742 </error> | |
| 8743 </errors> | |
| 8744 </function> | |
| 8745 | |
| 8746 <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37"> | |
| 8747 <synopsis>Raw Monitor Notify All</synopsis> | |
| 8748 <description> | |
| 8749 Notify all threads waiting on the raw monitor. | |
| 8750 </description> | |
| 8751 <origin>jvmdi</origin> | |
| 8752 <capabilities> | |
| 8753 </capabilities> | |
| 8754 <parameters> | |
| 8755 <param id="monitor"> | |
| 8756 <jrawMonitorID/> | |
| 8757 <description> | |
| 8758 The monitor | |
| 8759 </description> | |
| 8760 </param> | |
| 8761 </parameters> | |
| 8762 <errors> | |
| 8763 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8764 Not monitor owner | |
| 8765 </error> | |
| 8766 </errors> | |
| 8767 </function> | |
| 8768 | |
| 8769 <elide> | |
| 8770 <function id="GetRawMonitorUse" num="118"> | |
| 8771 <synopsis>Get Raw Monitor Use</synopsis> | |
| 8772 <description> | |
| 8773 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure | |
| 8774 are filled in with information about usage of the raw monitor. | |
| 8775 </description> | |
| 8776 <origin>new</origin> | |
| 8777 <capabilities> | |
| 8778 <required id="can_get_raw_monitor_usage"></required> | |
| 8779 </capabilities> | |
| 8780 <parameters> | |
| 8781 <param id="monitor"> | |
| 8782 <jrawMonitorID/> | |
| 8783 <description> | |
| 8784 the raw monitor to query. | |
| 8785 </description> | |
| 8786 </param> | |
| 8787 <param id="info_ptr"> | |
| 8788 <outptr><struct>jvmtiMonitorUsage</struct></outptr> | |
| 8789 <description> | |
| 8790 On return, filled with monitor information for the | |
| 8791 specified raw monitor. | |
| 8792 </description> | |
| 8793 </param> | |
| 8794 </parameters> | |
| 8795 <errors> | |
| 8796 </errors> | |
| 8797 </function> | |
| 8798 | |
| 8799 <function id="GetRawMonitors" num="119"> | |
| 8800 <synopsis>Get Raw Monitors</synopsis> | |
| 8801 <description> | |
| 8802 Return the list of raw monitors. | |
| 8803 <p/> | |
| 8804 Note: details about each monitor can be examined with | |
| 8805 <functionlink id="GetRawMonitorUse"></functionlink>. | |
| 8806 </description> | |
| 8807 <origin>new</origin> | |
| 8808 <capabilities> | |
| 8809 <required id="can_get_raw_monitor_usage"></required> | |
| 8810 </capabilities> | |
| 8811 <parameters> | |
| 8812 <param id="monitorCnt"> | |
| 8813 <outptr><jint/></outptr> | |
| 8814 <description> | |
| 8815 On return, pointer to the number | |
| 8816 of monitors returned in <code>monitors_ptr</code>. | |
| 8817 </description> | |
| 8818 </param> | |
| 8819 <param id="monitors_ptr"> | |
| 8820 <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf> | |
| 8821 <description> | |
| 8822 On return, pointer to the monitor list. | |
| 8823 </description> | |
| 8824 </param> | |
| 8825 </parameters> | |
| 8826 <errors> | |
| 8827 </errors> | |
| 8828 </function> | |
| 8829 </elide> | |
| 8830 </category> | |
| 8831 | |
| 8832 <category id="jniIntercept" label="JNI Function Interception"> | |
| 8833 | |
| 8834 <intro> | |
| 8835 Provides the ability to intercept and resend | |
| 8836 Java Native Interface (JNI) function calls | |
| 8837 by manipulating the JNI function table. | |
| 6919 | 8838 See <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html">JNI |
| 0 | 8839 Functions</externallink> in the <i>Java Native Interface Specification</i>. |
| 8840 <p/> | |
| 8841 The following example illustrates intercepting the | |
| 8842 <code>NewGlobalRef</code> JNI call in order to count reference | |
| 8843 creation. | |
| 8844 <example> | |
| 8845 JNIEnv original_jni_Functions; | |
| 8846 JNIEnv redirected_jni_Functions; | |
| 8847 int my_global_ref_count = 0; | |
| 8848 | |
| 8849 jobject | |
| 8850 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) { | |
| 8851 ++my_global_ref_count; | |
| 8852 return originalJNIFunctions->NewGlobalRef(env, lobj); | |
| 8853 } | |
| 8854 | |
| 8855 void | |
| 8856 myInit() { | |
| 8857 jvmtiError err; | |
| 8858 | |
| 8859 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &original_jni_Functions); | |
| 8860 if (err != JVMTI_ERROR_NONE) { | |
| 8861 die(); | |
| 8862 } | |
| 8863 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &redirected_jni_Functions); | |
| 8864 if (err != JVMTI_ERROR_NONE) { | |
| 8865 die(); | |
| 8866 } | |
| 8867 redirectedJNIFunctions->NewGlobalRef = MyNewGlobalRef; | |
| 8868 err = (*jvmti_env)->SetJNIFunctionTable(jvmti_env, redirected_jni_Functions); | |
| 8869 if (err != JVMTI_ERROR_NONE) { | |
| 8870 die(); | |
| 8871 } | |
| 8872 } | |
| 8873 </example> | |
| 8874 Sometime after <code>myInit</code> is called the user's JNI | |
| 8875 code is executed which makes the call to create a new global | |
| 8876 reference. Instead of going to the normal JNI implementation | |
| 8877 the call goes to <code>myNewGlobalRef</code>. Note that a | |
| 8878 copy of the original function table is kept so that the normal | |
| 8879 JNI function can be called after the data is collected. | |
| 8880 Note also that any JNI functions which are not overwritten | |
| 8881 will behave normally. | |
| 8882 <todo> | |
| 8883 check that the example compiles and executes. | |
| 8884 </todo> | |
| 8885 </intro> | |
| 8886 | |
| 8887 <function id="SetJNIFunctionTable" phase="start" num="120"> | |
| 8888 <synopsis>Set JNI Function Table</synopsis> | |
| 8889 <description> | |
| 8890 Set the JNI function table | |
| 8891 in all current and future JNI environments. | |
| 8892 As a result, all future JNI calls are directed to the specified functions. | |
| 8893 Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the | |
| 8894 function table to pass to this function. | |
| 8895 For this function to take effect the the updated table entries must be | |
| 8896 used by the JNI clients. | |
| 8897 Since the table is defined <code>const</code> some compilers may optimize | |
| 8898 away the access to the table, thus preventing this function from taking | |
| 8899 effect. | |
| 8900 The table is copied--changes to the local copy of the | |
| 8901 table have no effect. | |
| 8902 This function affects only the function table, all other aspects of the environment are | |
| 8903 unaffected. | |
| 8904 See the examples <internallink id="jniIntercept">above</internallink>. | |
| 8905 </description> | |
| 8906 <origin>new</origin> | |
| 8907 <capabilities> | |
| 8908 </capabilities> | |
| 8909 <parameters> | |
| 8910 <param id="function_table"> | |
| 8911 <inptr> | |
| 8912 <struct>jniNativeInterface</struct> | |
| 8913 </inptr> | |
| 8914 <description> | |
| 8915 Points to the new JNI function table. | |
| 8916 </description> | |
| 8917 </param> | |
| 8918 </parameters> | |
| 8919 <errors> | |
| 8920 </errors> | |
| 8921 </function> | |
| 8922 | |
| 8923 <function id="GetJNIFunctionTable" phase="start" num="121"> | |
| 8924 <synopsis>Get JNI Function Table</synopsis> | |
| 8925 <description> | |
| 8926 Get the JNI function table. | |
| 8927 The JNI function table is copied into allocated memory. | |
| 8928 If <functionlink id="SetJNIFunctionTable"></functionlink> | |
| 8929 has been called, the modified (not the original) function | |
| 8930 table is returned. | |
| 8931 Only the function table is copied, no other aspects of the environment | |
| 8932 are copied. | |
| 8933 See the examples <internallink id="jniIntercept">above</internallink>. | |
| 8934 </description> | |
| 8935 <origin>new</origin> | |
| 8936 <capabilities> | |
| 8937 </capabilities> | |
| 8938 <parameters> | |
| 8939 <param id="function_table"> | |
| 8940 <allocbuf> | |
| 8941 <struct>jniNativeInterface</struct> | |
| 8942 </allocbuf> | |
| 8943 <description> | |
| 8944 On return, <code>*function_table</code> | |
| 8945 points a newly allocated copy of the JNI function table. | |
| 8946 </description> | |
| 8947 </param> | |
| 8948 </parameters> | |
| 8949 <errors> | |
| 8950 </errors> | |
| 8951 </function> | |
| 8952 | |
| 8953 </category> | |
| 8954 | |
| 8955 <category id="eventManagement" label="Event Management"> | |
| 8956 | |
| 8957 <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122"> | |
| 8958 <synopsis>Set Event Callbacks</synopsis> | |
| 8959 <description> | |
| 8960 Set the functions to be called for each event. | |
| 8961 The callbacks are specified by supplying a replacement function table. | |
| 8962 The function table is copied--changes to the local copy of the | |
| 8963 table have no effect. | |
| 8964 This is an atomic action, all callbacks are set at once. | |
| 8965 No events are sent before this function is called. | |
| 8966 When an entry is <code>NULL</code> or when the event is beyond | |
| 8967 <paramlink id="size_of_callbacks"></paramlink> no event is sent. | |
| 8968 Details on events are | |
| 8969 described <internallink id="EventSection">later</internallink> in this document. | |
| 8970 An event must be enabled and have a callback in order to be | |
| 8971 sent--the order in which this function and | |
| 8972 <functionlink id="SetEventNotificationMode"></functionlink> | |
| 8973 are called does not affect the result. | |
| 8974 </description> | |
| 8975 <origin>new</origin> | |
| 8976 <capabilities> | |
| 8977 </capabilities> | |
| 8978 <parameters> | |
| 8979 <param id="callbacks"> | |
| 8980 <inptr> | |
| 8981 <struct>jvmtiEventCallbacks</struct> | |
| 8982 <nullok>remove the existing callbacks</nullok> | |
| 8983 </inptr> | |
| 8984 <description> | |
| 8985 The new event callbacks. | |
| 8986 </description> | |
| 8987 </param> | |
| 8988 <param id="size_of_callbacks"> | |
| 8989 <jint min="0"/> | |
| 8990 <description> | |
| 8991 <code>sizeof(jvmtiEventCallbacks)</code>--for version | |
| 8992 compatibility. | |
| 8993 </description> | |
| 8994 </param> | |
| 8995 </parameters> | |
| 8996 <errors> | |
| 8997 </errors> | |
| 8998 </function> | |
| 8999 | |
| 9000 <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2"> | |
| 9001 <synopsis>Set Event Notification Mode</synopsis> | |
| 9002 <description> | |
| 9003 Control the generation of events. | |
| 9004 <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum"> | |
| 9005 <constant id="JVMTI_ENABLE" num="1"> | |
| 9006 If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>, | |
| 9007 the event <paramlink id="event_type"></paramlink> will be enabled | |
| 9008 </constant> | |
| 9009 <constant id="JVMTI_DISABLE" num="0"> | |
| 9010 If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>, | |
| 9011 the event <paramlink id="event_type"></paramlink> will be disabled | |
| 9012 </constant> | |
| 9013 </constants> | |
| 9014 If <code>thread</code> is <code>NULL</code>, | |
| 9015 the event is enabled or disabled globally; otherwise, it is | |
| 9016 enabled or disabled for a particular thread. | |
| 9017 An event is generated for | |
| 9018 a particular thread if it is enabled either at the thread or global | |
| 9019 levels. | |
| 9020 <p/> | |
| 9021 See <internallink id="EventIndex">below</internallink> for information on specific events. | |
| 9022 <p/> | |
| 9023 The following events cannot be controlled at the thread | |
| 9024 level through this function. | |
| 9025 <ul> | |
| 9026 <li><eventlink id="VMInit"></eventlink></li> | |
| 9027 <li><eventlink id="VMStart"></eventlink></li> | |
| 9028 <li><eventlink id="VMDeath"></eventlink></li> | |
| 9029 <li><eventlink id="ThreadStart"></eventlink></li> | |
| 9030 <li><eventlink id="CompiledMethodLoad"></eventlink></li> | |
| 9031 <li><eventlink id="CompiledMethodUnload"></eventlink></li> | |
| 9032 <li><eventlink id="DynamicCodeGenerated"></eventlink></li> | |
| 9033 <li><eventlink id="DataDumpRequest"></eventlink></li> | |
| 9034 </ul> | |
| 9035 <p/> | |
| 9036 Initially, no events are enabled at either the thread level | |
| 9037 or the global level. | |
| 9038 <p/> | |
| 9039 Any needed capabilities (see Event Enabling Capabilities below) must be possessed | |
| 9040 before calling this function. | |
| 9041 <p/> | |
| 9042 Details on events are | |
| 9043 described <internallink id="EventSection">below</internallink>. | |
| 9044 </description> | |
| 9045 <origin>jvmdiClone</origin> | |
| 9046 <eventcapabilities></eventcapabilities> | |
| 9047 <parameters> | |
| 9048 <param id="mode"> | |
| 9049 <enum>jvmtiEventMode</enum> | |
| 9050 <description> | |
| 9051 <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code> | |
| 9052 </description> | |
| 9053 </param> | |
| 9054 <param id="event_type"> | |
| 9055 <enum>jvmtiEvent</enum> | |
| 9056 <description> | |
| 9057 the event to control | |
| 9058 </description> | |
| 9059 </param> | |
| 9060 <param id="event_thread"> | |
| 9061 <ptrtype> | |
| 9062 <jthread impl="noconvert"/> | |
| 9063 <nullok>event is controlled at the global level</nullok> | |
| 9064 </ptrtype> | |
| 9065 <description> | |
| 9066 The thread to control | |
| 9067 </description> | |
| 9068 </param> | |
| 9069 <param id="..."> | |
| 9070 <varargs/> | |
| 9071 <description> | |
| 9072 for future expansion | |
| 9073 </description> | |
| 9074 </param> | |
| 9075 </parameters> | |
| 9076 <errors> | |
| 9077 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
| 9078 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread. | |
| 9079 </error> | |
| 9080 <error id="JVMTI_ERROR_THREAD_NOT_ALIVE"> | |
| 9081 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead). | |
| 9082 </error> | |
| 9083 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 9084 thread level control was attempted on events which do not | |
| 9085 permit thread level control. | |
| 9086 </error> | |
| 9087 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> | |
| 9088 The Required Event Enabling Capability is not possessed. | |
| 9089 </error> | |
| 9090 </errors> | |
| 9091 </function> | |
| 9092 | |
| 9093 <function id="GenerateEvents" num="123"> | |
| 9094 <synopsis>Generate Events</synopsis> | |
| 9095 <description> | |
| 9096 Generate events to represent the current state of the VM. | |
| 9097 For example, if <paramlink id="event_type"/> is | |
| 9098 <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>, | |
| 9099 a <eventlink id="CompiledMethodLoad"></eventlink> event will be | |
| 9100 sent for each currently compiled method. | |
| 9101 Methods that were loaded and now have been unloaded are not sent. | |
| 9102 The history of what events have previously been sent does not | |
| 9103 effect what events are sent by this function--for example, | |
| 9104 all currently compiled methods | |
| 9105 will be sent each time this function is called. | |
| 9106 <p/> | |
| 9107 This function is useful when | |
| 9108 events may have been missed due to the agent attaching after program | |
| 9109 execution begins; this function generates the missed events. | |
| 9110 <p/> | |
| 9111 Attempts to execute Java programming language code or | |
| 9112 JNI functions may be paused until this function returns - | |
| 9113 so neither should be called from the thread sending the event. | |
| 9114 This function returns only after the missed events have been | |
| 9115 sent, processed and have returned. | |
| 9116 The event may be sent on a different thread than the thread | |
| 9117 on which the event occurred. | |
| 9118 The callback for the event must be set with | |
| 9119 <functionlink id="SetEventCallbacks"></functionlink> | |
| 9120 and the event must be enabled with | |
| 9121 <functionlink id="SetEventNotificationMode"></functionlink> | |
| 9122 or the events will not occur. | |
| 9123 If the VM no longer has the information to generate some or | |
| 9124 all of the requested events, the events are simply not sent - | |
| 9125 no error is returned. | |
| 9126 <p/> | |
| 9127 Only the following events are supported: | |
| 9128 <ul> | |
| 9129 <li><eventlink id="CompiledMethodLoad"></eventlink></li> | |
| 9130 <li><eventlink id="DynamicCodeGenerated"></eventlink></li> | |
| 9131 </ul> | |
| 9132 </description> | |
| 9133 <origin>new</origin> | |
| 9134 <capabilities> | |
| 9135 <capability id="can_generate_compiled_method_load_events"></capability> | |
| 9136 </capabilities> | |
| 9137 <parameters> | |
| 9138 <param id="event_type"> | |
| 9139 <enum>jvmtiEvent</enum> | |
| 9140 <description> | |
| 9141 The type of event to generate. Must be one of these: | |
| 9142 <ul> | |
| 9143 <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li> | |
| 9144 <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li> | |
| 9145 </ul> | |
| 9146 </description> | |
| 9147 </param> | |
| 9148 </parameters> | |
| 9149 <errors> | |
| 9150 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> | |
| 9151 <paramlink id="event_type"/> is | |
| 9152 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> | |
| 9153 and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink> | |
| 9154 is <code>false</code>. | |
| 9155 </error> | |
| 9156 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 9157 <paramlink id="event_type"/> is other than | |
| 9158 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> | |
| 9159 or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>. | |
| 9160 </error> | |
| 9161 </errors> | |
| 9162 </function> | |
| 9163 | |
| 9164 </category> | |
| 9165 | |
| 9166 <category id="extension" label="Extension Mechanism"> | |
| 9167 | |
| 9168 <intro> | |
| 9169 These functions | |
| 9170 allow a <jvmti/> implementation to provide functions and events | |
| 9171 beyond those defined in this specification. | |
| 9172 <p/> | |
| 9173 Both extension functions and extension events have parameters | |
| 9174 each of which has a 'type' and 'kind' chosen from the following tables: | |
| 9175 | |
| 9176 <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum"> | |
| 9177 <constant id="JVMTI_TYPE_JBYTE" num="101"> | |
| 9178 Java programming language primitive type - <code>byte</code>. | |
| 9179 JNI type <code>jbyte</code>. | |
| 9180 </constant> | |
| 9181 <constant id="JVMTI_TYPE_JCHAR" num="102"> | |
| 9182 Java programming language primitive type - <code>char</code>. | |
| 9183 JNI type <code>jchar</code>. | |
| 9184 </constant> | |
| 9185 <constant id="JVMTI_TYPE_JSHORT" num="103"> | |
| 9186 Java programming language primitive type - <code>short</code>. | |
| 9187 JNI type <code>jshort</code>. | |
| 9188 </constant> | |
| 9189 <constant id="JVMTI_TYPE_JINT" num="104"> | |
| 9190 Java programming language primitive type - <code>int</code>. | |
| 9191 JNI type <datalink id="jint"></datalink>. | |
| 9192 </constant> | |
| 9193 <constant id="JVMTI_TYPE_JLONG" num="105"> | |
| 9194 Java programming language primitive type - <code>long</code>. | |
| 9195 JNI type <datalink id="jlong"></datalink>. | |
| 9196 </constant> | |
| 9197 <constant id="JVMTI_TYPE_JFLOAT" num="106"> | |
| 9198 Java programming language primitive type - <code>float</code>. | |
| 9199 JNI type <datalink id="jfloat"></datalink>. | |
| 9200 </constant> | |
| 9201 <constant id="JVMTI_TYPE_JDOUBLE" num="107"> | |
| 9202 Java programming language primitive type - <code>double</code>. | |
| 9203 JNI type <datalink id="jdouble"></datalink>. | |
| 9204 </constant> | |
| 9205 <constant id="JVMTI_TYPE_JBOOLEAN" num="108"> | |
| 9206 Java programming language primitive type - <code>boolean</code>. | |
| 9207 JNI type <datalink id="jboolean"></datalink>. | |
| 9208 </constant> | |
| 9209 <constant id="JVMTI_TYPE_JOBJECT" num="109"> | |
| 9210 Java programming language object type - <code>java.lang.Object</code>. | |
| 9211 JNI type <datalink id="jobject"></datalink>. | |
| 9212 Returned values are JNI local references and must be managed. | |
| 9213 </constant> | |
| 9214 <constant id="JVMTI_TYPE_JTHREAD" num="110"> | |
| 9215 Java programming language object type - <code>java.lang.Thread</code>. | |
| 9216 <jvmti/> type <datalink id="jthread"></datalink>. | |
| 9217 Returned values are JNI local references and must be managed. | |
| 9218 </constant> | |
| 9219 <constant id="JVMTI_TYPE_JCLASS" num="111"> | |
| 9220 Java programming language object type - <code>java.lang.Class</code>. | |
| 9221 JNI type <datalink id="jclass"></datalink>. | |
| 9222 Returned values are JNI local references and must be managed. | |
| 9223 </constant> | |
| 9224 <constant id="JVMTI_TYPE_JVALUE" num="112"> | |
| 9225 Union of all Java programming language primitive and object types - | |
| 9226 JNI type <datalink id="jvalue"></datalink>. | |
| 9227 Returned values which represent object types are JNI local references and must be managed. | |
| 9228 </constant> | |
| 9229 <constant id="JVMTI_TYPE_JFIELDID" num="113"> | |
| 9230 Java programming language field identifier - | |
| 9231 JNI type <datalink id="jfieldID"></datalink>. | |
| 9232 </constant> | |
| 9233 <constant id="JVMTI_TYPE_JMETHODID" num="114"> | |
| 9234 Java programming language method identifier - | |
| 9235 JNI type <datalink id="jmethodID"></datalink>. | |
| 9236 </constant> | |
| 9237 <constant id="JVMTI_TYPE_CCHAR" num="115"> | |
| 9238 C programming language type - <code>char</code>. | |
| 9239 </constant> | |
| 9240 <constant id="JVMTI_TYPE_CVOID" num="116"> | |
| 9241 C programming language type - <code>void</code>. | |
| 9242 </constant> | |
| 9243 <constant id="JVMTI_TYPE_JNIENV" num="117"> | |
| 9244 JNI environment - <code>JNIEnv</code>. | |
| 9245 Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type. | |
| 9246 </constant> | |
| 9247 </constants> | |
| 9248 | |
| 9249 <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum"> | |
| 9250 <constant id="JVMTI_KIND_IN" num="91"> | |
| 9251 Ingoing argument - <code>foo</code>. | |
| 9252 </constant> | |
| 9253 <constant id="JVMTI_KIND_IN_PTR" num="92"> | |
| 9254 Ingoing pointer argument - <code>const foo*</code>. | |
| 9255 </constant> | |
| 9256 <constant id="JVMTI_KIND_IN_BUF" num="93"> | |
| 9257 Ingoing array argument - <code>const foo*</code>. | |
| 9258 </constant> | |
| 9259 <constant id="JVMTI_KIND_ALLOC_BUF" num="94"> | |
| 9260 Outgoing allocated array argument - <code>foo**</code>. | |
| 9261 Free with <code>Deallocate</code>. | |
| 9262 </constant> | |
| 9263 <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95"> | |
| 9264 Outgoing allocated array of allocated arrays argument - <code>foo***</code>. | |
| 9265 Free with <code>Deallocate</code>. | |
| 9266 </constant> | |
| 9267 <constant id="JVMTI_KIND_OUT" num="96"> | |
| 9268 Outgoing argument - <code>foo*</code>. | |
| 9269 </constant> | |
| 9270 <constant id="JVMTI_KIND_OUT_BUF" num="97"> | |
| 9271 Outgoing array argument (pre-allocated by agent) - <code>foo*</code>. | |
| 9272 Do not <code>Deallocate</code>. | |
| 9273 </constant> | |
| 9274 </constants> | |
| 9275 | |
| 9276 </intro> | |
| 9277 | |
| 9278 <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info"> | |
| 9279 <field id="name"> | |
| 9280 <allocfieldbuf><char/></allocfieldbuf> | |
| 9281 <description> | |
| 9282 The parameter name, encoded as a | |
| 9283 <internallink id="mUTF">modified UTF-8</internallink> string | |
| 9284 </description> | |
| 9285 </field> | |
| 9286 <field id="kind"> | |
| 9287 <enum>jvmtiParamKind</enum> | |
| 9288 <description> | |
| 9289 The kind of the parameter - type modifiers | |
| 9290 </description> | |
| 9291 </field> | |
| 9292 <field id="base_type"> | |
| 9293 <enum>jvmtiParamTypes</enum> | |
| 9294 <description> | |
| 9295 The base type of the parameter - modified by <code>kind</code> | |
| 9296 </description> | |
| 9297 </field> | |
| 9298 <field id="null_ok"> | |
| 9299 <jboolean/> | |
| 9300 <description> | |
| 9301 Is a <code>NULL</code> argument permitted? Applies only to pointer and object types. | |
| 9302 </description> | |
| 9303 </field> | |
| 9304 </typedef> | |
| 9305 | |
| 9306 <callback id="jvmtiExtensionFunction"> | |
| 9307 <enum>jvmtiError</enum> | |
| 9308 <synopsis>Extension Function</synopsis> | |
| 9309 <description> | |
| 9310 This is the implementation-specific extension function. | |
| 9311 </description> | |
| 9312 <parameters> | |
| 9313 <param id="jvmti_env"> | |
| 9314 <outptr> | |
| 9315 <struct>jvmtiEnv</struct> | |
| 9316 </outptr> | |
| 9317 <description> | |
| 9318 The <jvmti/> environment is the only fixed parameter for extension functions. | |
| 9319 </description> | |
| 9320 </param> | |
| 9321 <param id="..."> | |
| 9322 <varargs/> | |
| 9323 <description> | |
| 9324 The extension function-specific parameters | |
| 9325 </description> | |
| 9326 </param> | |
| 9327 </parameters> | |
| 9328 </callback> | |
| 9329 | |
| 9330 <function id="GetExtensionFunctions" phase="onload" num="124"> | |
| 9331 <synopsis>Get Extension Functions</synopsis> | |
| 9332 | |
| 9333 <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info"> | |
| 9334 <field id="func"> | |
| 9335 <ptrtype> | |
| 9336 <struct>jvmtiExtensionFunction</struct> | |
| 9337 </ptrtype> | |
| 9338 <description> | |
| 9339 The actual function to call | |
| 9340 </description> | |
| 9341 </field> | |
| 9342 <field id="id"> | |
| 9343 <allocfieldbuf><char/></allocfieldbuf> | |
| 9344 <description> | |
| 9345 The identifier for the extension function, encoded as a | |
| 9346 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9347 Uses package name conventions. | |
| 9348 For example, <code>com.sun.hotspot.bar</code> | |
| 9349 </description> | |
| 9350 </field> | |
| 9351 <field id="short_description"> | |
| 9352 <allocfieldbuf><char/></allocfieldbuf> | |
| 9353 <description> | |
| 9354 A one sentence description of the function, encoded as a | |
| 9355 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9356 </description> | |
| 9357 </field> | |
| 9358 <field id="param_count"> | |
| 9359 <jint/> | |
| 9360 <description> | |
| 9361 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code> | |
| 9362 </description> | |
| 9363 </field> | |
| 9364 <field id="params"> | |
| 9365 <allocfieldbuf outcount="param_count"> | |
| 9366 <struct>jvmtiParamInfo</struct> | |
| 9367 </allocfieldbuf> | |
| 9368 <description> | |
| 9369 Array of | |
| 9370 <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> | |
| 9371 parameters (<code>jvmtiEnv *jvmti_env</code> excluded) | |
| 9372 </description> | |
| 9373 </field> | |
| 9374 <field id="error_count"> | |
| 9375 <jint/> | |
| 9376 <description> | |
| 9377 The number of possible error returns (excluding universal errors) | |
| 9378 </description> | |
| 9379 </field> | |
| 9380 <field id="errors"> | |
| 9381 <allocfieldbuf outcount="error_count"> | |
| 9382 <enum>jvmtiError</enum> | |
| 9383 </allocfieldbuf> | |
| 9384 <description> | |
| 9385 Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> | |
| 9386 possible errors | |
| 9387 </description> | |
| 9388 </field> | |
| 9389 </typedef> | |
| 9390 | |
| 9391 <description> | |
| 9392 Returns the set of extension functions. | |
| 9393 </description> | |
| 9394 <origin>new</origin> | |
| 9395 <capabilities> | |
| 9396 </capabilities> | |
| 9397 <parameters> | |
| 9398 <param id="extension_count_ptr"> | |
| 9399 <outptr><jint/></outptr> | |
| 9400 <description> | |
| 9401 On return, points to the number of extension functions | |
| 9402 </description> | |
| 9403 </param> | |
| 9404 <param id="extensions"> | |
| 9405 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf> | |
| 9406 <description> | |
| 9407 Returns an array of extension function info, one per function | |
| 9408 </description> | |
| 9409 </param> | |
| 9410 </parameters> | |
| 9411 <errors> | |
| 9412 </errors> | |
| 9413 </function> | |
| 9414 | |
| 9415 <function id="GetExtensionEvents" phase="onload" num="125"> | |
| 9416 <synopsis>Get Extension Events</synopsis> | |
| 9417 | |
| 9418 <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info"> | |
| 9419 <field id="extension_event_index"> | |
| 9420 <jint/> | |
| 9421 <description> | |
| 9422 The identifying index of the event | |
| 9423 </description> | |
| 9424 </field> | |
| 9425 <field id="id"> | |
| 9426 <allocfieldbuf><char/></allocfieldbuf> | |
| 9427 <description> | |
| 9428 The identifier for the extension event, encoded as a | |
| 9429 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9430 Uses package name conventions. | |
| 9431 For example, <code>com.sun.hotspot.bar</code> | |
| 9432 </description> | |
| 9433 </field> | |
| 9434 <field id="short_description"> | |
| 9435 <allocfieldbuf><char/></allocfieldbuf> | |
| 9436 <description> | |
| 9437 A one sentence description of the event, encoded as a | |
| 9438 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9439 </description> | |
| 9440 </field> | |
| 9441 <field id="param_count"> | |
| 9442 <jint/> | |
| 9443 <description> | |
| 9444 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code> | |
| 9445 </description> | |
| 9446 </field> | |
| 9447 <field id="params"> | |
| 9448 <allocfieldbuf outcount="param_count"> | |
| 9449 <struct>jvmtiParamInfo</struct> | |
| 9450 </allocfieldbuf> | |
| 9451 <description> | |
| 9452 Array of | |
| 9453 <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink> | |
| 9454 parameters (<code>jvmtiEnv *jvmti_env</code> excluded) | |
| 9455 </description> | |
| 9456 </field> | |
| 9457 </typedef> | |
| 9458 | |
| 9459 <description> | |
| 9460 Returns the set of extension events. | |
| 9461 </description> | |
| 9462 <origin>new</origin> | |
| 9463 <capabilities> | |
| 9464 </capabilities> | |
| 9465 <parameters> | |
| 9466 <param id="extension_count_ptr"> | |
| 9467 <outptr><jint/></outptr> | |
| 9468 <description> | |
| 9469 On return, points to the number of extension events | |
| 9470 </description> | |
| 9471 </param> | |
| 9472 <param id="extensions"> | |
| 9473 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf> | |
| 9474 <description> | |
| 9475 Returns an array of extension event info, one per event | |
| 9476 </description> | |
| 9477 </param> | |
| 9478 </parameters> | |
| 9479 <errors> | |
| 9480 </errors> | |
| 9481 </function> | |
| 9482 | |
| 9483 <callback id="jvmtiExtensionEvent"> | |
| 9484 <void/> | |
| 9485 <synopsis>Extension Event</synopsis> | |
| 9486 <description> | |
| 9487 This is the implementation-specific event. | |
| 9488 The event handler is set with | |
| 9489 <functionlink id="SetExtensionEventCallback"/>. | |
| 9490 <p/> | |
| 9491 Event handlers for extension events must be declared varargs to match this definition. | |
| 9492 Failure to do so could result in calling convention mismatch and undefined behavior | |
| 9493 on some platforms. | |
| 9494 <p/> | |
| 9495 For example, if the <code>jvmtiParamInfo</code> | |
| 9496 returned by <functionlink id="GetExtensionEvents"/> indicates that | |
| 9497 there is a <code>jint</code> parameter, the event handler should be | |
| 9498 declared: | |
| 9499 <example> | |
| 9500 void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...) | |
| 9501 </example> | |
| 9502 Note the terminal "<code>...</code>" which indicates varargs. | |
| 9503 </description> | |
| 9504 <parameters> | |
| 9505 <param id="jvmti_env"> | |
| 9506 <outptr> | |
| 9507 <struct>jvmtiEnv</struct> | |
| 9508 </outptr> | |
| 9509 <description> | |
| 9510 The <jvmti/> environment is the only fixed parameter for extension events. | |
| 9511 </description> | |
| 9512 </param> | |
| 9513 <param id="..."> | |
| 9514 <varargs/> | |
| 9515 <description> | |
| 9516 The extension event-specific parameters | |
| 9517 </description> | |
| 9518 </param> | |
| 9519 </parameters> | |
| 9520 </callback> | |
| 9521 | |
| 9522 <function id="SetExtensionEventCallback" phase="onload" num="126"> | |
| 9523 <synopsis>Set Extension Event Callback</synopsis> | |
| 9524 | |
| 9525 <description> | |
| 9526 Sets the callback function for an extension event and | |
| 9527 enables the event. Or, if the callback is <code>NULL</code>, disables | |
| 9528 the event. Note that unlike standard events, setting | |
| 9529 the callback and enabling the event are a single operation. | |
| 9530 </description> | |
| 9531 <origin>new</origin> | |
| 9532 <capabilities> | |
| 9533 </capabilities> | |
| 9534 <parameters> | |
| 9535 <param id="extension_event_index"> | |
| 9536 <jint/> | |
| 9537 <description> | |
| 9538 Identifies which callback to set. | |
| 9539 This index is the | |
| 9540 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink> | |
| 9541 field of | |
| 9542 <datalink id="jvmtiExtensionEventInfo"/>. | |
| 9543 </description> | |
| 9544 </param> | |
| 9545 <param id="callback"> | |
| 9546 <ptrtype> | |
| 9547 <struct>jvmtiExtensionEvent</struct> | |
| 9548 <nullok>disable the event</nullok> | |
| 9549 </ptrtype> | |
| 9550 <description> | |
| 9551 If <code>callback</code> is non-<code>NULL</code>, | |
| 9552 set <code>callback</code> to be the event callback function | |
| 9553 and enable the event. | |
| 9554 </description> | |
| 9555 </param> | |
| 9556 </parameters> | |
| 9557 <errors> | |
| 9558 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 9559 <paramlink id="extension_event_index"/> is not an | |
| 9560 <fieldlink id="extension_event_index" | |
| 9561 struct="jvmtiExtensionEventInfo"/> | |
| 9562 returned by | |
| 9563 <functionlink id="GetExtensionEvents"/> | |
| 9564 </error> | |
| 9565 </errors> | |
| 9566 </function> | |
| 9567 | |
| 9568 </category> | |
| 9569 | |
| 9570 <category id="capability" label="Capability"> | |
| 9571 | |
| 9572 <intro> | |
| 9573 The capabilities functions allow you to change the | |
| 9574 functionality available to <jvmti/>--that is, | |
| 9575 which <jvmti/> | |
| 9576 functions can be called, what events can be generated, | |
| 9577 and what functionality these events and functions can | |
| 9578 provide. | |
| 9579 <p/> | |
| 9580 The "Capabilities" section of each function and event describe which | |
| 9581 capabilities, if any, they are associated with. "Required Functionality" | |
| 9582 means it is available for use and no capabilities must be added to use it. | |
| 9583 "Optional Functionality" means the agent must possess the capability | |
| 9584 before it can be used. | |
| 9585 To possess a capability, the agent must | |
| 9586 <functionlink id="AddCapabilities">add the capability</functionlink>. | |
| 9587 "Optional Features" describe capabilities which, | |
| 9588 if added, extend the feature set. | |
| 9589 <p/> | |
| 9590 The potentially available capabilities of each <jvmti/> implementation are different. | |
| 9591 Depending on the implementation, a capability: | |
| 9592 <ul> | |
| 9593 <li>may never be added</li> | |
| 9594 <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li> | |
| 9595 <li>may be added only during the <code>OnLoad</code> phase</li> | |
| 9596 <li>may be possessed by only one environment at a time</li> | |
| 9597 <li>may be possessed by only one environment at a time, | |
| 9598 and only during the <code>OnLoad</code> phase</li> | |
| 9599 <li>and so on ...</li> | |
| 9600 </ul> | |
| 9601 Frequently, the addition of a capability may incur a cost in execution speed, start up | |
| 9602 time, and/or memory footprint. Note that the overhead of using a capability | |
| 9603 is completely different than the overhead of possessing a capability. | |
| 9604 Take single stepping as an example. When single stepping is on (that | |
| 9605 is, when the event is enabled and thus actively sending events) | |
| 9606 the overhead of sending and processing an event | |
| 9607 on each instruction is huge in any implementation. | |
| 9608 However, the overhead of possessing the capability may be small or large, | |
| 9609 depending on the implementation. Also, when and if a capability is potentially | |
| 9610 available depends on the implementation. Some examples: | |
| 9611 <ul> | |
| 9612 <li>One VM might perform all execution by compiling bytecodes into | |
| 9613 native code and be unable to generate single step instructions. | |
| 9614 In this implementation the capability can not be added.</li> | |
| 9615 <li>Another VM may be able to switch execution to a single stepping | |
| 9616 interpreter at any time. In this implementation, having the capability has no | |
| 9617 overhead and could be added at any time.</li> | |
| 9618 <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted | |
| 9619 execution engine at start up, but be unable to switch between them. | |
| 9620 In this implementation the capability would need to be added | |
| 9621 during the <code>OnLoad</code> phase (before bytecode | |
| 9622 execution begins) and would have a large impact on execution speed | |
| 9623 even if single stepping was never used.</li> | |
| 9624 <li>Still another VM might be able to add an "is single stepping on" check | |
| 9625 into compiled bytecodes or a generated interpreter. Again in this implementation | |
| 9626 the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test | |
| 9627 and branch on each instruction) would be considerably less.</li> | |
| 9628 </ul> | |
| 9629 <p/> | |
| 9630 Each <jvmti/> <internallink id="environments">environment</internallink> | |
| 9631 has its own set of capabilities. | |
| 9632 Initially, that set is empty. | |
| 9633 Any desired capability must be added. | |
| 9634 If possible, capabilities should be added during the <code>OnLoad</code> phase. For most | |
| 9635 virtual machines certain capabilities require special set up for | |
| 9636 the virtual machine and this set up must happen | |
| 9637 during the <code>OnLoad</code> phase, before the virtual machine begins execution. | |
| 9638 Once a capability is added, it can | |
| 9639 only be removed if explicitly relinquished by the environment. | |
| 9640 <p/> | |
| 9641 The agent can, | |
| 9642 <functionlink id="GetPotentialCapabilities">determine what | |
| 9643 capabilities this VM can potentially provide</functionlink>, | |
| 9644 <functionlink id="AddCapabilities">add the capabilities | |
| 9645 to be used</functionlink>, | |
| 9646 <functionlink id="RelinquishCapabilities">release capabilities | |
| 9647 which are no longer needed</functionlink>, and | |
| 9648 <functionlink id="GetCapabilities">examine the currently available | |
| 9649 capabilities</functionlink>. | |
| 9650 </intro> | |
| 9651 | |
| 9652 <intro id="capabilityExamples" label="Capability Examples"> | |
| 9653 For example, a freshly started agent (in the <code>OnLoad</code> function) | |
| 9654 wants to enable all possible capabilities. | |
| 9655 Note that, in general, this is not advisable as the agent may suffer | |
| 9656 a performance penalty for functionality it is not using. | |
| 9657 The code might look like this in C: | |
| 9658 <example> | |
| 9659 jvmtiCapabilities capa; | |
| 9660 jvmtiError err; | |
| 9661 | |
| 9662 err = (*jvmti)->GetPotentialCapabilities(jvmti, &capa); | |
| 9663 if (err == JVMTI_ERROR_NONE) { | |
| 9664 err = (*jvmti)->AddCapabilities(jvmti, &capa); | |
| 9665 </example> | |
| 9666 For example, if an agent wants to check if it can get | |
| 9667 the bytecodes of a method (that is, it wants to check | |
| 9668 if it previously added this capability and has not | |
| 9669 relinquished it), the code might | |
| 9670 look like this in C: | |
| 9671 <example> | |
| 9672 jvmtiCapabilities capa; | |
| 9673 jvmtiError err; | |
| 9674 | |
| 9675 err = (*jvmti)->GetCapabilities(jvmti, &capa); | |
| 9676 if (err == JVMTI_ERROR_NONE) { | |
| 9677 if (capa.can_get_bytecodes) { ... } } | |
| 9678 </example> | |
| 9679 </intro> | |
| 9680 | |
| 9681 <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure"> | |
| 9682 <description> | |
| 9683 The functions in this category use this capabilities structure | |
| 9684 which contains boolean flags corresponding to each capability: | |
| 9685 </description> | |
| 9686 <capabilityfield id="can_tag_objects"> | |
| 9687 <description> | |
| 9688 Can set and get tags, as described in the | |
| 9689 <internallink id="Heap">Heap category</internallink>. | |
| 9690 </description> | |
| 9691 </capabilityfield> | |
| 9692 <capabilityfield id="can_generate_field_modification_events"> | |
| 9693 <description> | |
| 9694 Can set watchpoints on field modification - | |
| 9695 <functionlink id="SetFieldModificationWatch"></functionlink> | |
| 9696 </description> | |
| 9697 </capabilityfield> | |
| 9698 <capabilityfield id="can_generate_field_access_events"> | |
| 9699 <description> | |
| 9700 Can set watchpoints on field access - | |
| 9701 <functionlink id="SetFieldAccessWatch"></functionlink> | |
| 9702 </description> | |
| 9703 </capabilityfield> | |
| 9704 <capabilityfield id="can_get_bytecodes"> | |
| 9705 <description> | |
| 9706 Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink> | |
| 9707 </description> | |
| 9708 </capabilityfield> | |
| 9709 <capabilityfield id="can_get_synthetic_attribute"> | |
| 9710 <description> | |
| 9711 Can test if a field or method is synthetic - | |
| 9712 <functionlink id="IsFieldSynthetic"></functionlink> and | |
| 9713 <functionlink id="IsMethodSynthetic"></functionlink> | |
| 9714 </description> | |
| 9715 </capabilityfield> | |
| 9716 <capabilityfield id="can_get_owned_monitor_info"> | |
| 9717 <description> | |
| 9718 Can get information about ownership of monitors - | |
| 9719 <functionlink id="GetOwnedMonitorInfo"></functionlink> | |
| 9720 </description> | |
| 9721 </capabilityfield> | |
| 9722 <capabilityfield id="can_get_current_contended_monitor"> | |
| 9723 <description> | |
| 9724 Can <functionlink id="GetCurrentContendedMonitor"></functionlink> | |
| 9725 </description> | |
| 9726 </capabilityfield> | |
| 9727 <capabilityfield id="can_get_monitor_info"> | |
| 9728 <description> | |
| 9729 Can <functionlink id="GetObjectMonitorUsage"></functionlink> | |
| 9730 </description> | |
| 9731 </capabilityfield> | |
| 9732 <capabilityfield id="can_pop_frame"> | |
| 9733 <description> | |
| 9734 Can pop frames off the stack - <functionlink id="PopFrame"></functionlink> | |
| 9735 </description> | |
| 9736 </capabilityfield> | |
| 9737 <capabilityfield id="can_redefine_classes"> | |
| 9738 <description> | |
| 9739 Can redefine classes with <functionlink id="RedefineClasses"/>. | |
| 9740 </description> | |
| 9741 </capabilityfield> | |
| 9742 <capabilityfield id="can_signal_thread"> | |
| 9743 <description> | |
| 9744 Can send stop or interrupt to threads | |
| 9745 </description> | |
| 9746 </capabilityfield> | |
| 9747 <capabilityfield id="can_get_source_file_name"> | |
| 9748 <description> | |
| 9749 Can get the source file name of a class | |
| 9750 </description> | |
| 9751 </capabilityfield> | |
| 9752 <capabilityfield id="can_get_line_numbers"> | |
| 9753 <description> | |
| 9754 Can get the line number table of a method | |
| 9755 </description> | |
| 9756 </capabilityfield> | |
| 9757 <capabilityfield id="can_get_source_debug_extension"> | |
| 9758 <description> | |
| 9759 Can get the source debug extension of a class | |
| 9760 </description> | |
| 9761 </capabilityfield> | |
| 9762 <capabilityfield id="can_access_local_variables"> | |
| 9763 <description> | |
| 9764 Can set and get local variables | |
| 9765 </description> | |
| 9766 </capabilityfield> | |
| 9767 <capabilityfield id="can_maintain_original_method_order"> | |
| 9768 <description> | |
| 9769 Can return methods in the order they occur in the class file | |
| 9770 </description> | |
| 9771 </capabilityfield> | |
| 9772 <capabilityfield id="can_generate_single_step_events"> | |
| 9773 <description> | |
| 9774 Can get <eventlink id="SingleStep">single step</eventlink> events | |
| 9775 </description> | |
| 9776 </capabilityfield> | |
| 9777 <capabilityfield id="can_generate_exception_events"> | |
| 9778 <description> | |
| 9779 Can get <eventlink id="Exception">exception thrown</eventlink> and | |
| 9780 <eventlink id="ExceptionCatch">exception catch</eventlink> events | |
| 9781 </description> | |
| 9782 </capabilityfield> | |
| 9783 <capabilityfield id="can_generate_frame_pop_events"> | |
| 9784 <description> | |
| 9785 Can <functionlink id="NotifyFramePop">set</functionlink> and thus get | |
| 9786 <eventlink id="FramePop"></eventlink> events | |
| 9787 </description> | |
| 9788 </capabilityfield> | |
| 9789 <capabilityfield id="can_generate_breakpoint_events"> | |
| 9790 <description> | |
| 9791 Can <functionlink id="SetBreakpoint">set</functionlink> and thus get | |
| 9792 <eventlink id="Breakpoint"></eventlink> events | |
| 9793 </description> | |
| 9794 </capabilityfield> | |
| 9795 <capabilityfield id="can_suspend"> | |
| 9796 <description> | |
| 9797 Can suspend and resume threads | |
| 9798 </description> | |
| 9799 </capabilityfield> | |
| 9800 <capabilityfield id="can_redefine_any_class"> | |
| 9801 <description> | |
| 9802 Can modify (retransform or redefine) any non-primitive non-array class. | |
| 9803 See <functionlink id="IsModifiableClass"/>. | |
| 9804 </description> | |
| 9805 </capabilityfield> | |
| 9806 <capabilityfield id="can_get_current_thread_cpu_time"> | |
| 9807 <description> | |
| 9808 Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink> | |
| 9809 current thread CPU time | |
| 9810 </description> | |
| 9811 </capabilityfield> | |
| 9812 <capabilityfield id="can_get_thread_cpu_time"> | |
| 9813 <description> | |
| 9814 Can <functionlink id="GetThreadCpuTime">get</functionlink> | |
| 9815 thread CPU time | |
| 9816 </description> | |
| 9817 </capabilityfield> | |
| 9818 <capabilityfield id="can_generate_method_entry_events" | |
| 9819 disp1="can_generate" disp2="_method_entry_events" | |
| 9820 > | |
| 9821 <description> | |
| 9822 Can generate method entry events on entering a method | |
| 9823 </description> | |
| 9824 </capabilityfield> | |
| 9825 <capabilityfield id="can_generate_method_exit_events" | |
| 9826 disp1="can_generate" disp2="_method_exit_events" | |
| 9827 > | |
| 9828 <description> | |
| 9829 Can generate method exit events on leaving a method | |
| 9830 </description> | |
| 9831 </capabilityfield> | |
| 9832 <capabilityfield id="can_generate_all_class_hook_events" | |
| 9833 disp1="can_generate" disp2="_all_class_hook_events" | |
| 9834 > | |
| 9835 <description> | |
| 9836 Can generate ClassFileLoadHook events for every loaded class. | |
| 9837 </description> | |
| 9838 </capabilityfield> | |
| 9839 <capabilityfield id="can_generate_compiled_method_load_events" | |
| 9840 disp1="can_generate" disp2="_compiled_method_load_events" | |
| 9841 > | |
| 9842 <description> | |
| 9843 Can generate events when a method is compiled or unloaded | |
| 9844 </description> | |
| 9845 </capabilityfield> | |
| 9846 <capabilityfield id="can_generate_monitor_events" | |
| 9847 disp1="can_generate" disp2="_monitor_events" | |
| 9848 > | |
| 9849 <description> | |
| 9850 Can generate events on monitor activity | |
| 9851 </description> | |
| 9852 </capabilityfield> | |
| 9853 <capabilityfield id="can_generate_vm_object_alloc_events" | |
| 9854 disp1="can_generate" disp2="_vm_object_alloc_events" | |
| 9855 > | |
| 9856 <description> | |
| 9857 Can generate events on VM allocation of an object | |
| 9858 </description> | |
| 9859 </capabilityfield> | |
| 9860 <capabilityfield id="can_generate_native_method_bind_events" | |
| 9861 disp1="can_generate" disp2="_native_method_bind_events" | |
| 9862 > | |
| 9863 <description> | |
| 9864 Can generate events when a native method is bound to its | |
| 9865 implementation | |
| 9866 </description> | |
| 9867 </capabilityfield> | |
| 9868 <capabilityfield id="can_generate_garbage_collection_events" | |
| 9869 disp1="can_generate" disp2="_garbage_collection_events" | |
| 9870 > | |
| 9871 <description> | |
| 9872 Can generate events when garbage collection begins or ends | |
| 9873 </description> | |
| 9874 </capabilityfield> | |
| 9875 <capabilityfield id="can_generate_object_free_events" | |
| 9876 disp1="can_generate" disp2="_object_free_events" | |
| 9877 > | |
| 9878 <description> | |
| 9879 Can generate events when the garbage collector frees an object | |
| 9880 </description> | |
| 9881 </capabilityfield> | |
| 9882 <capabilityfield id="can_force_early_return" since="1.1"> | |
| 9883 <description> | |
| 9884 Can return early from a method, as described in the | |
| 9885 <internallink id="ForceEarlyReturn">Force Early Return category</internallink>. | |
| 9886 </description> | |
| 9887 </capabilityfield> | |
| 9888 <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1"> | |
| 9889 <description> | |
| 9890 Can get information about owned monitors with stack depth - | |
| 9891 <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink> | |
| 9892 </description> | |
| 9893 </capabilityfield> | |
| 9894 <capabilityfield id="can_get_constant_pool" since="1.1"> | |
| 9895 <description> | |
| 9896 Can get the constant pool of a class - | |
| 9897 <functionlink id="GetConstantPool"></functionlink> | |
| 9898 </description> | |
| 9899 </capabilityfield> | |
| 9900 <capabilityfield id="can_set_native_method_prefix" since="1.1"> | |
| 9901 <description> | |
| 9902 Can set prefix to be applied when native method cannot be resolved - | |
| 9903 <functionlink id="SetNativeMethodPrefix"/> and | |
| 9904 <functionlink id="SetNativeMethodPrefixes"/> | |
| 9905 </description> | |
| 9906 </capabilityfield> | |
| 9907 <capabilityfield id="can_retransform_classes" since="1.1"> | |
| 9908 <description> | |
| 9909 Can retransform classes with <functionlink id="RetransformClasses"/>. | |
| 9910 In addition to the restrictions imposed by the specific | |
| 9911 implementation on this capability (see the | |
| 9912 <internallink id="capability">Capability</internallink> section), | |
| 9913 this capability must be set before the | |
| 9914 <eventlink id="ClassFileLoadHook"/> event is enabled for the | |
| 9915 first time in this environment. | |
| 9916 An environment that possesses this capability at the time that | |
| 9917 <code>ClassFileLoadHook</code> is enabled for the first time is | |
| 9918 said to be <i>retransformation capable</i>. | |
| 9919 An environment that does not possess this capability at the time that | |
| 9920 <code>ClassFileLoadHook</code> is enabled for the first time is | |
| 9921 said to be <i>retransformation incapable</i>. | |
| 9922 </description> | |
| 9923 </capabilityfield> | |
| 9924 <capabilityfield id="can_retransform_any_class" since="1.1"> | |
| 9925 <description> | |
| 9926 <functionlink id="RetransformClasses"/> can be called on any class | |
| 9927 (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> | |
| 9928 must also be set) | |
| 9929 </description> | |
| 9930 </capabilityfield> | |
| 9931 <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1"> | |
| 9932 <description> | |
| 9933 Can generate events when the VM is unable to allocate memory from | |
| 9934 the <tm>Java</tm> platform heap. | |
| 9935 See <eventlink id="ResourceExhausted"/>. | |
| 9936 </description> | |
| 9937 </capabilityfield> | |
| 9938 <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1"> | |
| 9939 <description> | |
| 9940 Can generate events when the VM is unable to create a thread. | |
| 9941 See <eventlink id="ResourceExhausted"/>. | |
| 9942 </description> | |
| 9943 </capabilityfield> | |
| 9944 </capabilitiestypedef> | |
| 9945 | |
| 9946 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140"> | |
| 9947 <synopsis>Get Potential Capabilities</synopsis> | |
| 9948 <description> | |
| 9949 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/> | |
| 9950 features that can potentially be possessed by this environment | |
| 9951 at this time. | |
| 9952 The returned capabilities differ from the complete set of capabilities | |
| 9953 implemented by the VM in two cases: another environment possesses | |
| 9954 capabilities that can only be possessed by one environment, or the | |
| 9955 current <functionlink id="GetPhase">phase</functionlink> is live, | |
| 9956 and certain capabilities can only be added during the <code>OnLoad</code> phase. | |
| 9957 The <functionlink id="AddCapabilities"></functionlink> function | |
| 9958 may be used to set any or all or these capabilities. | |
| 9959 Currently possessed capabilities are included. | |
| 9960 <p/> | |
| 9961 Typically this function is used in the <code>OnLoad</code> function. | |
| 9962 Some virtual machines may allow a limited set of capabilities to be | |
| 9963 added in the live phase. | |
| 9964 In this case, the set of potentially available capabilities | |
| 9965 will likely differ from the <code>OnLoad</code> phase set. | |
| 9966 <p/> | |
| 9967 See the | |
| 9968 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 9969 </description> | |
| 9970 <origin>new</origin> | |
| 9971 <capabilities> | |
| 9972 </capabilities> | |
| 9973 <parameters> | |
| 9974 <param id="capabilities_ptr"> | |
| 9975 <outptr><struct>jvmtiCapabilities</struct></outptr> | |
| 9976 <description> | |
| 9977 On return, points to the <jvmti/> capabilities that may be added. | |
| 9978 </description> | |
| 9979 </param> | |
| 9980 </parameters> | |
| 9981 <errors> | |
| 9982 </errors> | |
| 9983 </function> | |
| 9984 | |
| 9985 <elide> | |
| 9986 <function id="EstimateCostOfCapabilities" phase="onload" num="141"> | |
| 9987 <synopsis>Estimate Cost Of Capabilities</synopsis> | |
| 9988 <description> | |
| 9989 <issue>There is strong opposition to this function. The concern is | |
| 9990 that it would be difficult or impossible to provide meaningful | |
| 9991 numbers, as the amount of impact is conditional on many factors | |
| 9992 that a single number could not represent. There is doubt that | |
| 9993 conditional implementations would be used or are even a good idea. | |
| 9994 The thought is that release documentation for the implementation | |
| 9995 would be the best means of exposing this information. | |
| 9996 Unless new arguments are presented, I intend to remove this | |
| 9997 function in the next revision. | |
| 9998 </issue> | |
| 9999 <p/> | |
| 10000 Return via the <paramlink id="time_impact_ptr"></paramlink> and | |
| 10001 <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact | |
| 10002 of adding the capabilities pointed to by | |
| 10003 <paramlink id="capabilities_ptr"></paramlink>. | |
| 10004 The returned estimates are in percentage of additional overhead, thus | |
| 10005 a time impact of 100 mean the application might run | |
| 10006 at half the speed. | |
| 10007 The estimates are very rough approximations and are not guaranteed. | |
| 10008 Note also, that the estimates are of the impact of having the | |
| 10009 capability available--when and if it is used the impact may be | |
| 10010 much greater. | |
| 10011 Estimates can be for a single capability or for a set of | |
| 10012 capabilities. Note that the costs are not necessarily additive, | |
| 10013 adding support for one capability might make another available | |
| 10014 for free or conversely having two capabilities at once may | |
| 10015 have multiplicative impact. | |
| 10016 Estimates are relative to the current set of capabilities - | |
| 10017 that is, how much more impact given the currently possessed capabilities. | |
| 10018 <p/> | |
| 10019 Typically this function is used in the OnLoad function, | |
| 10020 some virtual machines may allow a limited set of capabilities to be | |
| 10021 added in the live phase. | |
| 10022 In this case, the set of potentially available capabilities | |
| 10023 will likely differ from the OnLoad phase set. | |
| 10024 <p/> | |
| 10025 See the | |
| 10026 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 10027 </description> | |
| 10028 <origin>new</origin> | |
| 10029 <capabilities> | |
| 10030 </capabilities> | |
| 10031 <parameters> | |
| 10032 <param id="capabilities_ptr"> | |
| 10033 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
| 10034 <description> | |
| 10035 points to the <jvmti/> capabilities to evaluate. | |
| 10036 </description> | |
| 10037 </param> | |
| 10038 <param id="time_impact_ptr"> | |
| 10039 <outptr><jint/></outptr> | |
| 10040 <description> | |
| 10041 On return, points to the estimated percentage increase in | |
| 10042 run time if this capability was added. | |
| 10043 </description> | |
| 10044 </param> | |
| 10045 <param id="space_impact_ptr"> | |
| 10046 <outptr><jint/></outptr> | |
| 10047 <description> | |
| 10048 On return, points to the estimated percentage increase in | |
| 10049 memory space used if this capability was added. | |
| 10050 </description> | |
| 10051 </param> | |
| 10052 </parameters> | |
| 10053 <errors> | |
| 10054 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10055 The desired capabilities are not even potentially available. | |
| 10056 </error> | |
| 10057 </errors> | |
| 10058 </function> | |
| 10059 </elide> | |
| 10060 | |
| 10061 <function id="AddCapabilities" jkernel="yes" phase="onload" num="142"> | |
| 10062 <synopsis>Add Capabilities</synopsis> | |
| 10063 <description> | |
| 10064 Set new capabilities by adding the capabilities | |
| 10065 whose values are set to one (<code>1</code>) in | |
| 10066 <code>*</code><paramlink id="capabilities_ptr"></paramlink>. | |
| 10067 All previous capabilities are retained. | |
| 10068 Typically this function is used in the <code>OnLoad</code> function. | |
| 10069 Some virtual machines may allow a limited set of capabilities to be | |
| 10070 added in the live phase. | |
| 10071 <p/> | |
| 10072 See the | |
| 10073 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 10074 </description> | |
| 10075 <origin>new</origin> | |
| 10076 <capabilities> | |
| 10077 </capabilities> | |
| 10078 <parameters> | |
| 10079 <param id="capabilities_ptr"> | |
| 10080 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
| 10081 <description> | |
| 10082 Points to the <jvmti/> capabilities to add. | |
| 10083 </description> | |
| 10084 </param> | |
| 10085 </parameters> | |
| 10086 <errors> | |
| 10087 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10088 The desired capabilities are not even potentially available. | |
| 10089 </error> | |
| 10090 </errors> | |
| 10091 </function> | |
| 10092 | |
| 10093 | |
| 10094 <function id="RelinquishCapabilities" phase="onload" num="143"> | |
| 10095 <synopsis>Relinquish Capabilities</synopsis> | |
| 10096 <description> | |
| 10097 Relinquish the capabilities | |
| 10098 whose values are set to one (<code>1</code>) in | |
| 10099 <code>*</code><paramlink id="capabilities_ptr"></paramlink>. | |
| 10100 Some implementations may allow only one environment to have a capability | |
| 10101 (see the <internallink id="capability">capability introduction</internallink>). | |
| 10102 This function releases capabilities | |
| 10103 so that they may be used by other agents. | |
| 10104 All other capabilities are retained. | |
| 10105 The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>. | |
| 10106 Attempting to relinquish a capability that the agent does not possess is not an error. | |
| 10107 <issue> | |
| 10108 It is possible for the agent to be actively using capabilities | |
| 10109 which are being relinquished. For example, a thread is currently | |
| 10110 suspended and can_suspend is being relinquished or an event is currently | |
| 10111 enabled and can_generate_whatever is being relinquished. | |
| 10112 There are three possible ways we could spec this: | |
| 10113 <ul> | |
| 10114 <li>relinquish automatically releases them</li> | |
| 10115 <li>relinquish checks and returns some error code if held</li> | |
| 10116 <li>it is the agent's responsibility and it is not checked</li> | |
| 10117 </ul> | |
| 10118 One of these should be chosen. | |
| 10119 </issue> | |
| 10120 </description> | |
| 10121 <origin>new</origin> | |
| 10122 <capabilities> | |
| 10123 </capabilities> | |
| 10124 <parameters> | |
| 10125 <param id="capabilities_ptr"> | |
| 10126 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
| 10127 <description> | |
| 10128 Points to the <jvmti/> capabilities to relinquish. | |
| 10129 </description> | |
| 10130 </param> | |
| 10131 </parameters> | |
| 10132 <errors> | |
| 10133 </errors> | |
| 10134 </function> | |
| 10135 | |
| 10136 | |
| 10137 | |
| 10138 <function id="GetCapabilities" jkernel="yes" phase="any" num="89"> | |
| 10139 <synopsis>Get Capabilities</synopsis> | |
| 10140 <description> | |
| 10141 Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/> | |
| 10142 features which this environment currently possesses. | |
| 10143 Each possessed capability is indicated by a one (<code>1</code>) in the | |
| 10144 corresponding field of the <internallink id="jvmtiCapabilities">capabilities | |
| 10145 structure</internallink>. | |
| 10146 An environment does not possess a capability unless it has been successfully added with | |
| 10147 <functionlink id="AddCapabilities"/>. | |
| 10148 An environment only loses possession of a capability if it has been relinquished with | |
| 10149 <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result | |
| 10150 of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which | |
| 10151 have been made. | |
| 10152 <p/> | |
| 10153 See the | |
| 10154 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 10155 </description> | |
| 10156 <origin>jvmdiClone</origin> | |
| 10157 <capabilities> | |
| 10158 </capabilities> | |
| 10159 <parameters> | |
| 10160 <param id="capabilities_ptr"> | |
| 10161 <outptr><struct>jvmtiCapabilities</struct></outptr> | |
| 10162 <description> | |
| 10163 On return, points to the <jvmti/> capabilities. | |
| 10164 </description> | |
| 10165 </param> | |
| 10166 </parameters> | |
| 10167 <errors> | |
| 10168 </errors> | |
| 10169 </function> | |
| 10170 | |
| 10171 </category> | |
| 10172 | |
| 10173 | |
| 10174 <category id="timers" label="Timers"> | |
| 10175 | |
| 10176 <intro> | |
| 10177 These functions provide timing information. | |
| 10178 The resolution at which the time is updated is not specified. | |
| 10179 They provides nanosecond precision, but not necessarily nanosecond accuracy. | |
| 10180 Details about the timers, such as their maximum values, can be accessed with | |
| 10181 the timer information functions. | |
| 10182 </intro> | |
| 10183 | |
| 10184 <typedef id="jvmtiTimerInfo" label="Timer Info"> | |
| 10185 <description> | |
| 10186 The information function for each timer returns this data structure. | |
| 10187 </description> | |
| 10188 <field id="max_value"> | |
| 10189 <jlong/> | |
| 10190 <description> | |
| 10191 The maximum value the timer can reach. | |
| 10192 After this value is reached the timer wraps back to zero. | |
| 10193 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10194 it may appear to be a negative number. | |
| 10195 </description> | |
| 10196 </field> | |
| 10197 <field id="may_skip_forward"> | |
| 10198 <jboolean/> | |
| 10199 <description> | |
| 10200 If true, the timer can be externally adjusted and as a result skip forward. | |
| 10201 If false, the timer value will never increase faster than real time. | |
| 10202 </description> | |
| 10203 </field> | |
| 10204 <field id="may_skip_backward"> | |
| 10205 <jboolean/> | |
| 10206 <description> | |
| 10207 If true, the timer can be externally adjusted and as a result skip backward. | |
| 10208 If false, the timer value will be monotonically increasing. | |
| 10209 </description> | |
| 10210 </field> | |
| 10211 <field id="kind"> | |
| 10212 <enum>jvmtiTimerKind</enum> | |
| 10213 <description> | |
| 10214 The kind of timer. | |
| 10215 On a platform that does not distinguish between user and system time, <datalink | |
| 10216 id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink> | |
| 10217 is returned. | |
| 10218 </description> | |
| 10219 </field> | |
| 10220 <field id="reserved1"> | |
| 10221 <jlong/> | |
| 10222 <description> | |
| 10223 Reserved for future use. | |
| 10224 </description> | |
| 10225 </field> | |
| 10226 <field id="reserved2"> | |
| 10227 <jlong/> | |
| 10228 <description> | |
| 10229 Reserved for future use. | |
| 10230 </description> | |
| 10231 </field> | |
| 10232 </typedef> | |
| 10233 | |
| 10234 <intro> | |
| 10235 Where the timer kind is -- | |
| 10236 | |
| 10237 <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum"> | |
| 10238 <constant id="JVMTI_TIMER_USER_CPU" num="30"> | |
| 10239 CPU time that a thread is in user mode. | |
| 10240 </constant> | |
| 10241 <constant id="JVMTI_TIMER_TOTAL_CPU" num="31"> | |
| 10242 CPU time that a thread is in user or system mode. | |
| 10243 </constant> | |
| 10244 <constant id="JVMTI_TIMER_ELAPSED" num="32"> | |
| 10245 Elapsed time. | |
| 10246 </constant> | |
| 10247 </constants> | |
| 10248 </intro> | |
| 10249 | |
| 10250 <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe" impl="innative notrace" phase="start" num="134"> | |
| 10251 <synopsis>Get Current Thread CPU Timer Information</synopsis> | |
| 10252 <description> | |
| 10253 Get information about the | |
| 10254 <functionlink id="GetCurrentThreadCpuTime"/> timer. | |
| 10255 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
| 10256 are filled in with details about the timer. | |
| 10257 This information is specific to the platform and the implementation of | |
| 10258 <functionlink id="GetCurrentThreadCpuTime"/> and thus | |
| 10259 does not vary by thread nor does it vary | |
| 10260 during a particular invocation of the VM. | |
| 10261 <p/> | |
| 10262 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> | |
| 10263 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values | |
| 10264 returned by <code>GetCurrentThreadCpuTimerInfo</code> | |
| 10265 and <functionlink id="GetThreadCpuTimerInfo"/> | |
| 10266 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. | |
| 10267 </description> | |
| 10268 <origin>new</origin> | |
| 10269 <capabilities> | |
| 10270 <required id="can_get_current_thread_cpu_time"> | |
| 10271 Can get current thread CPU time. | |
| 10272 </required> | |
| 10273 </capabilities> | |
| 10274 <parameters> | |
| 10275 <param id="info_ptr"> | |
| 10276 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
| 10277 <description> | |
| 10278 On return, filled with information describing the time | |
| 10279 returned by <functionlink id="GetCurrentThreadCpuTime"/>. | |
| 10280 </description> | |
| 10281 </param> | |
| 10282 </parameters> | |
| 10283 <errors> | |
| 10284 </errors> | |
| 10285 </function> | |
| 10286 | |
| 10287 <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135"> | |
| 10288 <synopsis>Get Current Thread CPU Time</synopsis> | |
| 10289 <description> | |
| 10290 Return the CPU time utilized by the current thread. | |
| 10291 <p/> | |
| 10292 Note that the <functionlink id="GetThreadCpuTime"/> | |
| 10293 function provides CPU time for any thread, including | |
| 10294 the current thread. <code>GetCurrentThreadCpuTime</code> | |
| 10295 exists to support platforms which cannot | |
| 10296 supply CPU time for threads other than the current | |
| 10297 thread or which have more accurate information for | |
| 10298 the current thread (see | |
| 10299 <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs | |
| 10300 <functionlink id="GetThreadCpuTimerInfo"/>). | |
| 10301 On many platforms this call will be equivalent to: | |
| 10302 <example> | |
| 10303 GetThreadCpuTime(env, NULL, nanos_ptr) | |
| 10304 </example> | |
| 10305 </description> | |
| 10306 <origin>new</origin> | |
| 10307 <capabilities> | |
| 10308 <required id="can_get_current_thread_cpu_time"> | |
| 10309 Can get current thread CPU time. | |
| 10310 <p/> | |
| 10311 If this capability is enabled after threads have started, | |
| 10312 the implementation may choose any time up | |
| 10313 to and including the time that the capability is enabled | |
| 10314 as the point where CPU time collection starts. | |
| 10315 <p/> | |
| 10316 This capability must be potentially available on any | |
| 10317 platform where | |
| 10318 <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink> | |
| 10319 is potentially available. | |
| 10320 </required> | |
| 10321 </capabilities> | |
| 10322 <parameters> | |
| 10323 <param id="nanos_ptr"> | |
| 10324 <outptr><jlong/></outptr> | |
| 10325 <description> | |
| 10326 On return, points to the CPU time used by this thread | |
| 10327 in nanoseconds. | |
| 10328 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10329 it may appear to be a negative number. | |
| 10330 </description> | |
| 10331 </param> | |
| 10332 </parameters> | |
| 10333 <errors> | |
| 10334 </errors> | |
| 10335 </function> | |
| 10336 | |
| 10337 <function id="GetThreadCpuTimerInfo" num="136"> | |
| 10338 <synopsis>Get Thread CPU Timer Information</synopsis> | |
| 10339 <description> | |
| 10340 Get information about the | |
| 10341 <functionlink id="GetThreadCpuTime"/> timer. | |
| 10342 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
| 10343 are filled in with details about the timer. | |
| 10344 This information is specific to the platform and the implementation of | |
| 10345 <functionlink id="GetThreadCpuTime"/> and thus | |
| 10346 does not vary by thread nor does it vary | |
| 10347 during a particular invocation of the VM. | |
| 10348 <p/> | |
| 10349 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> | |
| 10350 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values | |
| 10351 returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/> | |
| 10352 and <code>GetThreadCpuTimerInfo</code> | |
| 10353 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. | |
| 10354 </description> | |
| 10355 <origin>new</origin> | |
| 10356 <capabilities> | |
| 10357 <required id="can_get_thread_cpu_time"> | |
| 10358 Can get thread CPU time. | |
| 10359 </required> | |
| 10360 </capabilities> | |
| 10361 <parameters> | |
| 10362 <param id="info_ptr"> | |
| 10363 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
| 10364 <description> | |
| 10365 On return, filled with information describing the time | |
| 10366 returned by <functionlink id="GetThreadCpuTime"/>. | |
| 10367 </description> | |
| 10368 </param> | |
| 10369 </parameters> | |
| 10370 <errors> | |
| 10371 </errors> | |
| 10372 </function> | |
| 10373 | |
| 10374 <function id="GetThreadCpuTime" num="137"> | |
| 10375 <synopsis>Get Thread CPU Time</synopsis> | |
| 10376 <description> | |
| 10377 Return the CPU time utilized by the specified thread. | |
| 10378 <p/> | |
| 10379 Get information about this timer with | |
| 10380 <functionlink id="GetThreadCpuTimerInfo"/>. | |
| 10381 </description> | |
| 10382 <origin>new</origin> | |
| 10383 <capabilities> | |
| 10384 <required id="can_get_thread_cpu_time"> | |
| 10385 Can get thread CPU time. | |
| 10386 <p/> | |
| 10387 If this capability is enabled after threads have started, | |
| 10388 the implementation may choose any time up | |
| 10389 to and including the time that the capability is enabled | |
| 10390 as the point where CPU time collection starts. | |
| 10391 </required> | |
| 10392 </capabilities> | |
| 10393 <parameters> | |
| 10394 <param id="thread"> | |
| 10395 <jthread null="current"/> | |
| 10396 <description> | |
| 10397 The thread to query. | |
| 10398 </description> | |
| 10399 </param> | |
| 10400 <param id="nanos_ptr"> | |
| 10401 <outptr><jlong/></outptr> | |
| 10402 <description> | |
| 10403 On return, points to the CPU time used by the specified thread | |
| 10404 in nanoseconds. | |
| 10405 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10406 it may appear to be a negative number. | |
| 10407 </description> | |
| 10408 </param> | |
| 10409 </parameters> | |
| 10410 <errors> | |
| 10411 </errors> | |
| 10412 </function> | |
| 10413 | |
| 10414 <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138"> | |
| 10415 <synopsis>Get Timer Information</synopsis> | |
| 10416 <description> | |
| 10417 Get information about the | |
| 10418 <functionlink id="GetTime"/> timer. | |
| 10419 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
| 10420 are filled in with details about the timer. | |
| 10421 This information will not change during a particular invocation of the VM. | |
| 10422 </description> | |
| 10423 <origin>new</origin> | |
| 10424 <capabilities> | |
| 10425 </capabilities> | |
| 10426 <parameters> | |
| 10427 <param id="info_ptr"> | |
| 10428 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
| 10429 <description> | |
| 10430 On return, filled with information describing the time | |
| 10431 returned by <functionlink id="GetTime"/>. | |
| 10432 </description> | |
| 10433 </param> | |
| 10434 </parameters> | |
| 10435 <errors> | |
| 10436 </errors> | |
| 10437 </function> | |
| 10438 | |
| 10439 <function id="GetTime" phase="any" callbacksafe="safe" num="139"> | |
| 10440 <synopsis>Get Time</synopsis> | |
| 10441 <description> | |
| 10442 Return the current value of the system timer, in nanoseconds. | |
| 10443 <p/> | |
| 10444 The value returned represents nanoseconds since some fixed but | |
| 10445 arbitrary time (perhaps in the future, so values may be | |
| 10446 negative). This function provides nanosecond precision, but not | |
| 10447 necessarily nanosecond accuracy. No guarantees are made about | |
| 10448 how frequently values change. | |
| 10449 <p/> | |
| 10450 Get information about this timer with | |
| 10451 <functionlink id="GetTimerInfo"/>. | |
| 10452 </description> | |
| 10453 <origin>new</origin> | |
| 10454 <capabilities> | |
| 10455 </capabilities> | |
| 10456 <parameters> | |
| 10457 <param id="nanos_ptr"> | |
| 10458 <outptr><jlong/></outptr> | |
| 10459 <description> | |
| 10460 On return, points to the time in nanoseconds. | |
| 10461 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10462 it may appear to be a negative number. | |
| 10463 </description> | |
| 10464 </param> | |
| 10465 </parameters> | |
| 10466 <errors> | |
| 10467 </errors> | |
| 10468 </function> | |
| 10469 | |
| 10470 <function id="GetAvailableProcessors" phase="any" num="144"> | |
| 10471 <synopsis>Get Available Processors</synopsis> | |
| 10472 <description> | |
| 10473 Returns the number of processors available to the Java virtual machine. | |
| 10474 <p/> | |
| 10475 This value may change during a particular invocation of the virtual machine. | |
| 10476 Applications that are sensitive to the number of available processors should | |
| 10477 therefore occasionally poll this property. | |
| 10478 </description> | |
| 10479 <origin>new</origin> | |
| 10480 <capabilities> | |
| 10481 </capabilities> | |
| 10482 <parameters> | |
| 10483 <param id="processor_count_ptr"> | |
| 10484 <outptr><jint/></outptr> | |
| 10485 <description> | |
| 10486 On return, points to the maximum number of processors available to the | |
| 10487 virtual machine; never smaller than one. | |
| 10488 </description> | |
| 10489 </param> | |
| 10490 </parameters> | |
| 10491 <errors> | |
| 10492 </errors> | |
| 10493 </function> | |
| 10494 | |
| 10495 </category> | |
| 10496 | |
| 10497 | |
| 10498 <category id="classLoaderSearch" label="Class Loader Search"> | |
| 10499 | |
| 10500 <intro> | |
| 10501 These functions allow the agent to add to the locations that a class loader searches for a class. | |
| 10502 This is useful for installing instrumentation under the correct class loader. | |
| 10503 </intro> | |
| 10504 | |
| 10505 <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149"> | |
| 10506 <synopsis>Add To Bootstrap Class Loader Search</synopsis> | |
| 10507 <description> | |
| 10508 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
|
10509 bootstrap class loader. See <vmspec chapter="5.3.1"/>. |
| 0 | 10510 After the bootstrap |
| 10511 class loader unsuccessfully searches for a class, the specified platform-dependent | |
| 10512 search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in | |
| 10513 the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, | |
| 10514 the segments will be searched in the order that this function was called. | |
| 10515 <p/> | |
| 10516 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent | |
| 10517 search path segment to be searched after the bootstrap class loader unsuccessfully searches | |
| 10518 for a class. The segment is typically a directory or JAR file. | |
| 10519 <p/> | |
| 10520 In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent | |
| 6919 | 10521 path to a <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html"> |
| 0 | 10522 JAR file</externallink>. The agent should take care that the JAR file does not |
| 10523 contain any classes or resources other than those to be defined by the bootstrap | |
| 10524 class loader for the purposes of instrumentation. | |
| 10525 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
10526 <vmspec/> specifies that a subsequent attempt to resolve a symbolic |
| 0 | 10527 reference that the Java virtual machine has previously unsuccessfully attempted |
| 10528 to resolve always fails with the same error that was thrown as a result of the | |
| 10529 initial resolution attempt. Consequently, if the JAR file contains an entry | |
| 10530 that corresponds to a class for which the Java virtual machine has | |
| 10531 unsuccessfully attempted to resolve a reference, then subsequent attempts to | |
| 10532 resolve that reference will fail with the same error as the initial attempt. | |
| 10533 </description> | |
| 10534 <origin>new</origin> | |
| 10535 <capabilities> | |
| 10536 </capabilities> | |
| 10537 <parameters> | |
| 10538 <param id="segment"> | |
| 10539 <inbuf><char/></inbuf> | |
| 10540 <description> | |
| 10541 The platform-dependent search path segment, encoded as a | |
| 10542 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10543 </description> | |
| 10544 </param> | |
| 10545 </parameters> | |
| 10546 <errors> | |
| 10547 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 10548 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an | |
| 10549 existing JAR file is an invalid path. | |
| 10550 </error> | |
| 10551 </errors> | |
| 10552 </function> | |
| 10553 | |
| 10554 <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1"> | |
| 10555 <synopsis>Add To System Class Loader Search</synopsis> | |
| 10556 <description> | |
| 10557 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
|
10558 defined by the system class loader. See <vmspec chapter="5.3.2"/>. |
| 0 | 10559 After the class loader unsuccessfully searches for a class, the specified platform-dependent search |
| 10560 path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the | |
| 10561 <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the | |
| 10562 segments will be searched in the order that this function was called. | |
| 10563 <p/> | |
| 10564 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent | |
| 10565 search path segment to be searched after the system class loader unsuccessfully searches | |
| 10566 for a class. The segment is typically a directory or JAR file. | |
| 10567 <p/> | |
| 10568 In the live phase the <paramlink id="segment"/> is a platform-dependent path to a <externallink | |
| 6919 | 10569 id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">JAR file</externallink> to be |
| 0 | 10570 searched after the system class loader unsuccessfully searches for a class. The agent should |
| 10571 take care that the JAR file does not contain any classes or resources other than those to be | |
| 10572 defined by the system class loader for the purposes of instrumentation. | |
| 10573 <p/> | |
| 10574 In the live phase the system class loader supports adding a JAR file to be searched if | |
| 10575 the system class loader implements a method name <code>appendToClassPathForInstrumentation</code> | |
| 10576 which takes a single parameter of type <code>java.lang.String</code>. The method is not required | |
| 10577 to have <code>public</code> access. | |
| 10578 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
10579 <vmspec/> specifies that a subsequent attempt to resolve a symbolic |
| 0 | 10580 reference that the Java virtual machine has previously unsuccessfully attempted |
| 10581 to resolve always fails with the same error that was thrown as a result of the | |
| 10582 initial resolution attempt. Consequently, if the JAR file contains an entry | |
| 10583 that corresponds to a class for which the Java virtual machine has | |
| 10584 unsuccessfully attempted to resolve a reference, then subsequent attempts to | |
| 10585 resolve that reference will fail with the same error as the initial attempt. | |
| 10586 </description> | |
| 10587 <origin>new</origin> | |
| 10588 <capabilities> | |
| 10589 </capabilities> | |
| 10590 <parameters> | |
| 10591 <param id="segment"> | |
| 10592 <inbuf><char/></inbuf> | |
| 10593 <description> | |
| 10594 The platform-dependent search path segment, encoded as a | |
| 10595 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10596 </description> | |
| 10597 </param> | |
| 10598 </parameters> | |
| 10599 <errors> | |
| 10600 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 10601 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an | |
| 10602 existing JAR file is an invalid path. | |
| 10603 </error> | |
| 10604 <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED"> | |
| 10605 Operation not supported by the system class loader. | |
| 10606 </error> | |
| 10607 </errors> | |
| 10608 </function> | |
| 10609 | |
| 10610 </category> | |
| 10611 | |
| 10612 | |
| 10613 <category id="props" label="System Properties"> | |
| 10614 | |
| 10615 <intro> | |
| 10616 These functions get and set system properties. | |
| 10617 </intro> | |
| 10618 | |
| 10619 <function id="GetSystemProperties" phase="onload" num="130"> | |
| 10620 <synopsis>Get System Properties</synopsis> | |
| 10621 <description> | |
| 10622 The list of VM system property keys which may be used with | |
| 10623 <functionlink id="GetSystemProperty"/> is returned. | |
| 10624 It is strongly recommended that virtual machines provide the | |
| 10625 following property keys: | |
| 10626 <ul> | |
| 10627 <li><code>java.vm.vendor</code></li> | |
| 10628 <li><code>java.vm.version</code></li> | |
| 10629 <li><code>java.vm.name</code></li> | |
| 10630 <li><code>java.vm.info</code></li> | |
| 10631 <li><code>java.library.path</code></li> | |
| 10632 <li><code>java.class.path</code></li> | |
| 10633 </ul> | |
| 10634 Provides access to system properties defined by and used | |
| 10635 by the VM. | |
| 10636 Properties set on the command-line are included. | |
| 10637 This allows getting and setting of these properties | |
| 10638 before the VM even begins executing bytecodes. | |
| 10639 Since this is a VM view of system properties, the set of available | |
| 10640 properties will usually be different than that | |
| 10641 in <code>java.lang.System.getProperties</code>. | |
| 10642 JNI method invocation may be used to access | |
| 10643 <code>java.lang.System.getProperties</code>. | |
| 10644 <p/> | |
| 10645 The set of properties may grow during execution. | |
| 10646 </description> | |
| 10647 <origin>new</origin> | |
| 10648 <capabilities> | |
| 10649 </capabilities> | |
| 10650 <parameters> | |
| 10651 <param id="count_ptr"> | |
| 10652 <outptr><jint/></outptr> | |
| 10653 <description> | |
| 10654 On return, points to the number of property keys returned. | |
| 10655 </description> | |
| 10656 </param> | |
| 10657 <param id="property_ptr"> | |
| 10658 <allocallocbuf outcount="count_ptr"><char/></allocallocbuf> | |
| 10659 <description> | |
| 10660 On return, points to an array of property keys, encoded as | |
| 10661 <internallink id="mUTF">modified UTF-8</internallink> strings. | |
| 10662 </description> | |
| 10663 </param> | |
| 10664 </parameters> | |
| 10665 <errors> | |
| 10666 </errors> | |
| 10667 </function> | |
| 10668 | |
| 10669 <function id="GetSystemProperty" phase="onload" num="131"> | |
| 10670 <synopsis>Get System Property</synopsis> | |
| 10671 <description> | |
| 10672 Return a VM system property value given the property key. | |
| 10673 <p/> | |
| 10674 The function <functionlink id="GetSystemProperties"/> | |
| 10675 returns the set of property keys which may be used. | |
| 10676 The properties which can be retrieved may grow during | |
| 10677 execution. | |
| 10678 <p/> | |
| 10679 Since this is a VM view of system properties, the values | |
| 10680 of properties may differ from that returned by | |
| 10681 <code>java.lang.System.getProperty(String)</code>. | |
| 10682 A typical VM might copy the values of the VM system | |
| 10683 properties into the <code>Properties</code> held by | |
| 10684 <code>java.lang.System</code> during the initialization | |
| 10685 of that class. Thereafter any changes to the VM system | |
| 10686 properties (with <functionlink id="SetSystemProperty"/>) | |
| 10687 or the <code>java.lang.System</code> system properties | |
| 10688 (with <code>java.lang.System.setProperty(String,String)</code>) | |
| 10689 would cause the values to diverge. | |
| 10690 JNI method invocation may be used to access | |
| 10691 <code>java.lang.System.getProperty(String)</code>. | |
| 10692 </description> | |
| 10693 <origin>new</origin> | |
| 10694 <capabilities> | |
| 10695 </capabilities> | |
| 10696 <parameters> | |
| 10697 <param id="property"> | |
| 10698 <inbuf><char/></inbuf> | |
| 10699 <description> | |
| 10700 The key of the property to retrieve, encoded as a | |
| 10701 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10702 </description> | |
| 10703 </param> | |
| 10704 <param id="value_ptr"> | |
| 10705 <allocbuf><char/></allocbuf> | |
| 10706 <description> | |
| 10707 On return, points to the property value, encoded as a | |
| 10708 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10709 </description> | |
| 10710 </param> | |
| 10711 </parameters> | |
| 10712 <errors> | |
| 10713 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10714 This property is not available. | |
| 10715 Use <functionlink id="GetSystemProperties"/> to find available properties. | |
| 10716 </error> | |
| 10717 </errors> | |
| 10718 </function> | |
| 10719 | |
| 10720 <function id="SetSystemProperty" phase="onloadOnly" num="132"> | |
| 10721 <synopsis>Set System Property</synopsis> | |
| 10722 <description> | |
| 10723 Set a VM system property value. | |
| 10724 <p/> | |
| 10725 The function <functionlink id="GetSystemProperties"/> | |
| 10726 returns the set of property keys, some of these may be settable. | |
| 10727 See <functionlink id="GetSystemProperty"/>. | |
| 10728 </description> | |
| 10729 <origin>new</origin> | |
| 10730 <capabilities> | |
| 10731 </capabilities> | |
| 10732 <parameters> | |
| 10733 <param id="property"> | |
| 10734 <inbuf><char/></inbuf> | |
| 10735 <description> | |
| 10736 The key of the property, encoded as a | |
| 10737 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10738 </description> | |
| 10739 </param> | |
|
2100
b1a2afa37ec4
7003271: Hotspot should track cumulative Java heap bytes allocated on a per-thread basis
phh
parents:
2019
diff
changeset
|
10740 <param id="value_ptr"> |
| 0 | 10741 <inbuf> |
| 10742 <char/> | |
| 10743 <nullok> | |
| 10744 do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/> | |
| 10745 if the property is not writeable | |
| 10746 </nullok> | |
| 10747 </inbuf> | |
| 10748 <description> | |
| 10749 The property value to set, encoded as a | |
| 10750 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10751 </description> | |
| 10752 </param> | |
| 10753 </parameters> | |
| 10754 <errors> | |
| 10755 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10756 This property is not available or is not writeable. | |
| 10757 </error> | |
| 10758 </errors> | |
| 10759 </function> | |
| 10760 | |
| 10761 </category> | |
| 10762 | |
| 10763 <category id="general" label="General"> | |
| 10764 | |
| 10765 <intro> | |
| 10766 </intro> | |
| 10767 | |
| 10768 <function id="GetPhase" jkernel="yes" phase="any" num="133"> | |
| 10769 <synopsis>Get Phase</synopsis> | |
| 10770 <description> | |
| 10771 Return the current phase of VM execution. | |
| 10772 The phases proceed in sequence: | |
| 10773 <constants id="jvmtiPhase" label="Phases of execution" kind="enum"> | |
| 10774 <constant id="JVMTI_PHASE_ONLOAD" num="1"> | |
| 10775 <code>OnLoad</code> phase: while in the | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
10776 <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
10777 or, for statically linked agents, the <internallink id="onload"> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
10778 <code>Agent_OnLoad_<agent-lib-name> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
10779 </code></internallink> function. |
| 0 | 10780 </constant> |
| 10781 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2"> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
10782 Primordial phase: between return from <code>Agent_OnLoad</code> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
10783 or <code>Agent_OnLoad_<agent-lib-name></code> and the |
| 0 | 10784 <code>VMStart</code> event. |
| 10785 </constant> | |
| 10786 <constant id="JVMTI_PHASE_START" num="6"> | |
| 10787 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event | |
| 10788 is sent and until the <code>VMInit</code> event is sent. | |
| 10789 </constant> | |
| 10790 <constant id="JVMTI_PHASE_LIVE" num="4"> | |
| 10791 Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent | |
| 10792 and until the <eventlink id="VMDeath"></eventlink> event returns. | |
| 10793 </constant> | |
| 10794 <constant id="JVMTI_PHASE_DEAD" num="8"> | |
| 10795 Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after | |
| 10796 start-up failure. | |
| 10797 </constant> | |
| 10798 </constants> | |
| 10799 In the case of start-up failure the VM will proceed directly to the dead | |
| 10800 phase skipping intermediate phases and neither a <code>VMInit</code> nor | |
| 10801 <code>VMDeath</code> event will be sent. | |
| 10802 <p/> | |
| 10803 Most <jvmti/> functions operate only in the live phase. | |
| 10804 The following functions operate in either the <code>OnLoad</code> or live phases: | |
| 10805 <functionphaselist phase="onload"/> | |
| 10806 The following functions operate in only the <code>OnLoad</code> phase: | |
| 10807 <functionphaselist phase="onloadOnly"/> | |
| 10808 The following functions operate in the start or live phases: | |
| 10809 <functionphaselist phase="start"/> | |
| 10810 The following functions operate in any phase: | |
| 10811 <functionphaselist phase="any"/> | |
| 10812 JNI functions (except the Invocation API) must only be used in the start or live phases. | |
| 10813 <p/> | |
| 10814 Most <jvmti/> events are sent only in the live phase. | |
| 10815 The following events operate in others phases: | |
| 10816 <eventphaselist phase="start"/> | |
| 10817 <eventphaselist phase="any"/> | |
| 10818 </description> | |
| 10819 <origin>new</origin> | |
| 10820 <capabilities> | |
| 10821 </capabilities> | |
| 10822 <parameters> | |
| 10823 <param id="phase_ptr"> | |
| 10824 <outptr><enum>jvmtiPhase</enum></outptr> | |
| 10825 <description> | |
| 10826 On return, points to the phase. | |
| 10827 </description> | |
| 10828 </param> | |
| 10829 </parameters> | |
| 10830 <errors> | |
| 10831 </errors> | |
| 10832 </function> | |
| 10833 | |
| 10834 <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127"> | |
| 10835 <synopsis>Dispose Environment</synopsis> | |
| 10836 <description> | |
| 10837 Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code> | |
| 10838 (see <internallink id="environments"><jvmti/> Environments</internallink>). | |
| 10839 Dispose of any resources held by the environment. | |
| 10840 <issue> | |
| 10841 What resources are reclaimed? What is undone? | |
| 10842 Breakpoints,watchpoints removed? | |
| 10843 </issue> | |
| 10844 Threads suspended by this environment are not resumed by this call, | |
| 10845 this must be done explicitly by the agent. | |
| 10846 Memory allocated by this environment via calls to <jvmti/> functions | |
| 10847 is not released, this can be done explicitly by the agent | |
| 10848 by calling <functionlink id="Deallocate"/>. | |
| 10849 Raw monitors created by this environment are not destroyed, | |
| 10850 this can be done explicitly by the agent | |
| 10851 by calling <functionlink id="DestroyRawMonitor"/>. | |
| 10852 The state of threads waiting on raw monitors created by this environment | |
| 10853 are not affected. | |
| 10854 <p/> | |
| 10855 Any <functionlink id="SetNativeMethodPrefix">native method | |
| 10856 prefixes</functionlink> for this environment will be unset; | |
| 10857 the agent must remove any prefixed native methods before | |
| 10858 dispose is called. | |
| 10859 <p/> | |
| 10860 Any <internallink id="capability">capabilities</internallink> | |
| 10861 held by this environment are relinquished. | |
| 10862 <p/> | |
| 10863 Events enabled by this environment will no longer be sent, however | |
| 10864 event handlers currently running will continue to run. Caution must | |
| 10865 be exercised in the design of event handlers whose environment may | |
| 10866 be disposed and thus become invalid during their execution. | |
| 10867 <p/> | |
| 10868 This environment may not be used after this call. | |
| 10869 This call returns to the caller. | |
| 10870 </description> | |
| 10871 <origin>new</origin> | |
| 10872 <capabilities> | |
| 10873 </capabilities> | |
| 10874 <parameters> | |
| 10875 </parameters> | |
| 10876 <errors> | |
| 10877 </errors> | |
| 10878 </function> | |
| 10879 | |
| 10880 <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148"> | |
| 10881 <synopsis>Set Environment Local Storage</synopsis> | |
| 10882 <description> | |
| 10883 The VM stores a pointer value associated with each environment. | |
| 10884 This pointer value is called <i>environment-local storage</i>. | |
| 10885 This value is <code>NULL</code> unless set with this function. | |
| 10886 Agents can allocate memory in which they store environment specific | |
| 10887 information. By setting environment-local storage it can then be | |
| 10888 accessed with | |
| 10889 <functionlink id="GetEnvironmentLocalStorage"></functionlink>. | |
| 10890 <p/> | |
| 10891 Called by the agent to set the value of the <jvmti/> | |
| 10892 environment-local storage. <jvmti/> supplies to the agent a pointer-size | |
| 10893 environment-local storage that can be used to record per-environment | |
| 10894 information. | |
| 10895 </description> | |
| 10896 <origin>new</origin> | |
| 10897 <capabilities> | |
| 10898 </capabilities> | |
| 10899 <parameters> | |
| 10900 <param id="data"> | |
| 10901 <inbuf> | |
| 10902 <void/> | |
| 10903 <nullok>value is set to <code>NULL</code></nullok> | |
| 10904 </inbuf> | |
| 10905 <description> | |
| 10906 The value to be entered into the environment-local storage. | |
| 10907 </description> | |
| 10908 </param> | |
| 10909 </parameters> | |
| 10910 <errors> | |
| 10911 </errors> | |
| 10912 </function> | |
| 10913 | |
| 10914 <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147"> | |
| 10915 <synopsis>Get Environment Local Storage</synopsis> | |
| 10916 <description> | |
| 10917 Called by the agent to get the value of the <jvmti/> environment-local | |
| 10918 storage. | |
| 10919 </description> | |
| 10920 <origin>new</origin> | |
| 10921 <capabilities> | |
| 10922 </capabilities> | |
| 10923 <parameters> | |
| 10924 <param id="data_ptr"> | |
| 10925 <agentbuf><void/></agentbuf> | |
| 10926 <description> | |
| 10927 Pointer through which the value of the environment local | |
| 10928 storage is returned. | |
| 10929 If environment-local storage has not been set with | |
| 10930 <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned | |
| 10931 pointer is <code>NULL</code>. | |
| 10932 </description> | |
| 10933 </param> | |
| 10934 </parameters> | |
| 10935 <errors> | |
| 10936 </errors> | |
| 10937 </function> | |
| 10938 | |
| 10939 <function id="GetVersionNumber" jkernel="yes" phase="any" num="88"> | |
| 10940 <synopsis>Get Version Number</synopsis> | |
| 10941 <description> | |
| 10942 Return the <jvmti/> version via <code>version_ptr</code>. | |
| 10943 The return value is the version identifier. | |
| 10944 The version identifier includes major, minor and micro | |
| 10945 version as well as the interface type. | |
| 10946 <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits"> | |
| 10947 <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000"> | |
| 10948 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI. | |
| 10949 </constant> | |
| 10950 <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000"> | |
| 10951 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>. | |
| 10952 </constant> | |
| 10953 </constants> | |
| 10954 <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits"> | |
| 10955 <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000"> | |
| 10956 Mask to extract interface type. | |
| 10957 The value of the version returned by this function masked with | |
| 10958 <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always | |
| 10959 <code>JVMTI_VERSION_INTERFACE_JVMTI</code> | |
| 10960 since this is a <jvmti/> function. | |
| 10961 </constant> | |
| 10962 <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000"> | |
| 10963 Mask to extract major version number. | |
| 10964 </constant> | |
| 10965 <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00"> | |
| 10966 Mask to extract minor version number. | |
| 10967 </constant> | |
| 10968 <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF"> | |
| 10969 Mask to extract micro version number. | |
| 10970 </constant> | |
| 10971 </constants> | |
| 10972 <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits"> | |
| 10973 <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16"> | |
| 10974 Shift to extract major version number. | |
| 10975 </constant> | |
| 10976 <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8"> | |
| 10977 Shift to extract minor version number. | |
| 10978 </constant> | |
| 10979 <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0"> | |
| 10980 Shift to extract micro version number. | |
| 10981 </constant> | |
| 10982 </constants> | |
| 10983 </description> | |
| 10984 <origin>jvmdi</origin> | |
| 10985 <capabilities> | |
| 10986 </capabilities> | |
| 10987 <parameters> | |
| 10988 <param id="version_ptr"> | |
| 10989 <outptr><jint/></outptr> | |
| 10990 <description> | |
| 10991 On return, points to the <jvmti/> version. | |
| 10992 </description> | |
| 10993 </param> | |
| 10994 </parameters> | |
| 10995 <errors> | |
| 10996 </errors> | |
| 10997 </function> | |
| 10998 | |
| 10999 | |
| 11000 <function id="GetErrorName" phase="any" num="128"> | |
| 11001 <synopsis>Get Error Name</synopsis> | |
| 11002 <description> | |
| 11003 Return the symbolic name for an | |
| 11004 <internallink id="ErrorSection">error code</internallink>. | |
| 11005 <p/> | |
| 11006 For example | |
| 11007 <code>GetErrorName(env, JVMTI_ERROR_NONE, &err_name)</code> | |
| 11008 would return in <code>err_name</code> the string | |
| 11009 <code>"JVMTI_ERROR_NONE"</code>. | |
| 11010 </description> | |
| 11011 <origin>new</origin> | |
| 11012 <capabilities> | |
| 11013 </capabilities> | |
| 11014 <parameters> | |
| 11015 <param id="error"> | |
| 11016 <enum>jvmtiError</enum> | |
| 11017 <description> | |
| 11018 The error code. | |
| 11019 </description> | |
| 11020 </param> | |
| 11021 <param id="name_ptr"> | |
| 11022 <allocbuf><char/></allocbuf> | |
| 11023 <description> | |
| 11024 On return, points to the error name. | |
| 11025 The name is encoded as a | |
| 11026 <internallink id="mUTF">modified UTF-8</internallink> string, | |
| 11027 but is restricted to the ASCII subset. | |
| 11028 </description> | |
| 11029 </param> | |
| 11030 </parameters> | |
| 11031 <errors> | |
| 11032 </errors> | |
| 11033 </function> | |
| 11034 | |
| 11035 <function id="SetVerboseFlag" phase="any" num="150"> | |
| 11036 <synopsis>Set Verbose Flag</synopsis> | |
| 11037 <description> | |
| 11038 <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum"> | |
| 11039 <constant id="JVMTI_VERBOSE_OTHER" num="0"> | |
| 11040 Verbose output other than the below. | |
| 11041 </constant> | |
| 11042 <constant id="JVMTI_VERBOSE_GC" num="1"> | |
| 11043 Verbose garbage collector output, like that specified with <code>-verbose:gc</code>. | |
| 11044 </constant> | |
| 11045 <constant id="JVMTI_VERBOSE_CLASS" num="2"> | |
| 11046 Verbose class loading output, like that specified with <code>-verbose:class</code>. | |
| 11047 </constant> | |
| 11048 <constant id="JVMTI_VERBOSE_JNI" num="4"> | |
| 11049 Verbose JNI output, like that specified with <code>-verbose:jni</code>. | |
| 11050 </constant> | |
| 11051 </constants> | |
| 11052 Control verbose output. | |
| 11053 This is the output which typically is sent to <code>stderr</code>. | |
| 11054 </description> | |
| 11055 <origin>new</origin> | |
| 11056 <capabilities> | |
| 11057 </capabilities> | |
| 11058 <parameters> | |
| 11059 <param id="flag"> | |
| 11060 <enum>jvmtiVerboseFlag</enum> | |
| 11061 <description> | |
| 11062 Which verbose flag to set. | |
| 11063 </description> | |
| 11064 </param> | |
| 11065 <param id="value"> | |
| 11066 <jboolean/> | |
| 11067 <description> | |
| 11068 New value of the flag. | |
| 11069 </description> | |
| 11070 </param> | |
| 11071 </parameters> | |
| 11072 <errors> | |
| 11073 </errors> | |
| 11074 </function> | |
| 11075 | |
| 11076 | |
| 11077 <function id="GetJLocationFormat" phase="any" num="129"> | |
| 11078 <synopsis>Get JLocation Format</synopsis> | |
| 11079 <description> | |
| 11080 Although the greatest functionality is achieved with location information | |
| 11081 referencing the virtual machine bytecode index, the definition of | |
| 11082 <code>jlocation</code> has intentionally been left unconstrained to allow VM | |
| 11083 implementations that do not have this information. | |
| 11084 <p/> | |
| 11085 This function describes the representation of <code>jlocation</code> used in this VM. | |
| 11086 If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>, | |
| 11087 <code>jlocation</code>s can | |
| 11088 be used as in indices into the array returned by | |
| 11089 <functionlink id="GetBytecodes"></functionlink>. | |
| 11090 <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum"> | |
| 11091 <constant id="JVMTI_JLOCATION_JVMBCI" num="1"> | |
| 11092 <code>jlocation</code> values represent virtual machine | |
| 11093 bytecode indices--that is, offsets into the | |
| 11094 virtual machine code for a method. | |
| 11095 </constant> | |
| 11096 <constant id="JVMTI_JLOCATION_MACHINEPC" num="2"> | |
| 11097 <code>jlocation</code> values represent native machine | |
| 11098 program counter values. | |
| 11099 </constant> | |
| 11100 <constant id="JVMTI_JLOCATION_OTHER" num="0"> | |
| 11101 <code>jlocation</code> values have some other representation. | |
| 11102 </constant> | |
| 11103 </constants> | |
| 11104 </description> | |
| 11105 <origin>new</origin> | |
| 11106 <capabilities> | |
| 11107 </capabilities> | |
| 11108 <parameters> | |
| 11109 <param id="format_ptr"> | |
| 11110 <outptr><enum>jvmtiJlocationFormat</enum></outptr> | |
| 11111 <description> | |
| 11112 On return, points to the format identifier for <code>jlocation</code> values. | |
| 11113 </description> | |
| 11114 </param> | |
| 11115 </parameters> | |
| 11116 <errors> | |
| 11117 </errors> | |
| 11118 </function> | |
| 11119 | |
| 11120 </category> | |
| 11121 | |
| 11122 </functionsection> | |
| 11123 | |
| 11124 <errorsection label="Error Reference"> | |
| 11125 <intro> | |
| 11126 Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code. | |
| 11127 <p/> | |
| 11128 It is the responsibility of the agent to call <jvmti/> functions with | |
| 11129 valid parameters and in the proper context (calling thread is attached, | |
| 11130 phase is correct, etc.). | |
| 11131 Detecting some error conditions may be difficult, inefficient, or | |
| 11132 impossible for an implementation. | |
| 11133 The errors listed in | |
| 11134 <internallink id="reqerrors">Function Specific Required Errors</internallink> | |
| 11135 must be detected by the implementation. | |
| 11136 All other errors represent the recommended response to the error | |
| 11137 condition. | |
| 11138 </intro> | |
| 11139 | |
| 11140 <errorcategory id="universal-error" label="Universal Errors"> | |
| 11141 <intro> | |
| 11142 The following errors may be returned by any function | |
| 11143 </intro> | |
| 11144 | |
| 11145 <errorid id="JVMTI_ERROR_NONE" num="0"> | |
| 11146 No error has occurred. This is the error code that is returned | |
| 11147 on successful completion of the function. | |
| 11148 </errorid> | |
| 11149 <errorid id="JVMTI_ERROR_NULL_POINTER" num="100"> | |
| 11150 Pointer is unexpectedly <code>NULL</code>. | |
| 11151 </errorid> | |
| 11152 <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110"> | |
| 11153 The function attempted to allocate memory and no more memory was | |
| 11154 available for allocation. | |
| 11155 </errorid> | |
| 11156 <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111"> | |
| 11157 The desired functionality has not been enabled in this virtual machine. | |
| 11158 </errorid> | |
| 11159 <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115"> | |
| 11160 The thread being used to call this function is not attached | |
| 11161 to the virtual machine. Calls must be made from attached threads. | |
| 11162 See <code>AttachCurrentThread</code> in the JNI invocation API. | |
| 11163 </errorid> | |
| 11164 <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116"> | |
| 11165 The <jvmti/> environment provided is no longer connected or is | |
| 11166 not an environment. | |
| 11167 </errorid> | |
| 11168 <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112"> | |
| 11169 The desired functionality is not available in the current | |
| 11170 <functionlink id="GetPhase">phase</functionlink>. | |
| 11171 Always returned if the virtual machine has completed running. | |
| 11172 </errorid> | |
| 11173 <errorid id="JVMTI_ERROR_INTERNAL" num="113"> | |
| 11174 An unexpected internal error has occurred. | |
| 11175 </errorid> | |
| 11176 </errorcategory> | |
| 11177 | |
| 11178 <errorcategory id="reqerrors" label="Function Specific Required Errors"> | |
| 11179 <intro> | |
| 11180 The following errors are returned by some <jvmti/> functions and must | |
| 11181 be returned by the implementation when the condition occurs. | |
| 11182 </intro> | |
| 11183 | |
| 11184 <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12"> | |
| 11185 Invalid priority. | |
| 11186 </errorid> | |
| 11187 <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13"> | |
| 11188 Thread was not suspended. | |
| 11189 </errorid> | |
| 11190 <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14"> | |
| 11191 Thread already suspended. | |
| 11192 </errorid> | |
| 11193 <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15"> | |
| 11194 This operation requires the thread to be alive--that is, | |
| 11195 it must be started and not yet have died. | |
| 11196 </errorid> | |
| 11197 <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22"> | |
| 11198 The class has been loaded but not yet prepared. | |
| 11199 </errorid> | |
| 11200 <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31"> | |
| 11201 There are no Java programming language or JNI stack frames at the specified depth. | |
| 11202 </errorid> | |
| 11203 <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32"> | |
| 11204 Information about the frame is not available (e.g. for native frames). | |
| 11205 </errorid> | |
| 11206 <errorid id="JVMTI_ERROR_DUPLICATE" num="40"> | |
| 11207 Item already set. | |
| 11208 </errorid> | |
| 11209 <errorid id="JVMTI_ERROR_NOT_FOUND" num="41"> | |
| 11210 Desired element (e.g. field or breakpoint) not found | |
| 11211 </errorid> | |
| 11212 <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51"> | |
| 11213 This thread doesn't own the raw monitor. | |
| 11214 </errorid> | |
| 11215 <errorid id="JVMTI_ERROR_INTERRUPT" num="52"> | |
| 11216 The call has been interrupted before completion. | |
| 11217 </errorid> | |
| 11218 <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79"> | |
| 11219 The class cannot be modified. | |
| 11220 </errorid> | |
| 11221 <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98"> | |
| 11222 The functionality is not available in this virtual machine. | |
| 11223 </errorid> | |
| 11224 <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101"> | |
| 11225 The requested information is not available. | |
| 11226 </errorid> | |
| 11227 <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102"> | |
| 11228 The specified event type ID is not recognized. | |
| 11229 </errorid> | |
| 11230 <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104"> | |
| 11231 The requested information is not available for native method. | |
| 11232 </errorid> | |
| 11233 <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106"> | |
| 11234 The class loader does not support this operation. | |
| 11235 </errorid> | |
| 11236 </errorcategory> | |
| 11237 | |
| 11238 <errorcategory id="function-specific-errors" label="Function Specific Agent Errors"> | |
| 11239 <intro> | |
| 11240 The following errors are returned by some <jvmti/> functions. | |
| 11241 They are returned in the event of invalid parameters passed by the | |
| 11242 agent or usage in an invalid context. | |
| 11243 An implementation is not required to detect these errors. | |
| 11244 </intro> | |
| 11245 | |
| 11246 <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10"> | |
| 11247 The passed thread is not a valid thread. | |
| 11248 </errorid> | |
| 11249 <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25"> | |
| 11250 Invalid field. | |
| 11251 </errorid> | |
| 11252 <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23"> | |
| 11253 Invalid method. | |
| 11254 </errorid> | |
| 11255 <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24"> | |
| 11256 Invalid location. | |
| 11257 </errorid> | |
| 11258 <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20"> | |
| 11259 Invalid object. | |
| 11260 </errorid> | |
| 11261 <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21"> | |
| 11262 Invalid class. | |
| 11263 </errorid> | |
| 11264 <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34"> | |
| 11265 The variable is not an appropriate type for the function used. | |
| 11266 </errorid> | |
| 11267 <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35"> | |
| 11268 Invalid slot. | |
| 11269 </errorid> | |
| 11270 <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99"> | |
| 11271 The capability being used is false in this environment. | |
| 11272 </errorid> | |
| 11273 <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11"> | |
| 11274 Thread group invalid. | |
| 11275 </errorid> | |
| 11276 <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50"> | |
| 11277 Invalid raw monitor. | |
| 11278 </errorid> | |
| 11279 <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103"> | |
| 11280 Illegal argument. | |
| 11281 </errorid> | |
| 11282 <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65"> | |
| 11283 The state of the thread has been modified, and is now inconsistent. | |
| 11284 </errorid> | |
| 11285 <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68"> | |
| 11286 A new class file has a version number not supported by this VM. | |
| 11287 </errorid> | |
| 11288 <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60"> | |
| 11289 A new class file is malformed (the VM would return a <code>ClassFormatError</code>). | |
| 11290 </errorid> | |
| 11291 <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61"> | |
| 11292 The new class file definitions would lead to a circular | |
| 11293 definition (the VM would return a <code>ClassCircularityError</code>). | |
| 11294 </errorid> | |
| 11295 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63"> | |
| 11296 A new class file would require adding a method. | |
| 11297 </errorid> | |
| 11298 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64"> | |
| 11299 A new class version changes a field. | |
| 11300 </errorid> | |
| 11301 <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62"> | |
| 11302 The class bytes fail verification. | |
| 11303 </errorid> | |
| 11304 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66"> | |
| 11305 A direct superclass is different for the new class | |
| 11306 version, or the set of directly implemented | |
| 11307 interfaces is different. | |
| 11308 </errorid> | |
| 11309 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67"> | |
| 11310 A new class version does not declare a method | |
| 11311 declared in the old class version. | |
| 11312 </errorid> | |
| 11313 <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69"> | |
| 11314 The class name defined in the new class file is | |
| 11315 different from the name in the old class object. | |
| 11316 </errorid> | |
| 11317 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70"> | |
| 11318 A new class version has different modifiers. | |
| 11319 </errorid> | |
| 11320 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71"> | |
| 11321 A method in the new class version has different modifiers | |
| 11322 than its counterpart in the old class version. | |
| 11323 </errorid> | |
| 11324 </errorcategory> | |
| 11325 </errorsection> | |
| 11326 | |
| 11327 <eventsection label="Events"> | |
| 11328 <intro label="Handling Events" id="eventIntro"> | |
| 11329 Agents can be informed of many events that occur in application | |
| 11330 programs. | |
| 11331 <p/> | |
| 11332 To handle events, designate a set of callback functions with | |
| 11333 <functionlink id="SetEventCallbacks"></functionlink>. | |
| 11334 For each event the corresponding callback function will be | |
| 11335 called. | |
| 11336 Arguments to the callback function provide additional | |
| 11337 information about the event. | |
| 11338 <p/> | |
| 11339 The callback function is usually called from within an application | |
| 11340 thread. The <jvmti/> implementation does not | |
| 11341 queue events in any way. This means | |
| 11342 that event callback functions must be written | |
| 11343 carefully. Here are some general guidelines. See | |
| 11344 the individual event descriptions for further | |
| 11345 suggestions. | |
| 11346 <p/> | |
| 11347 <ul> | |
| 11348 <li>Any exception thrown during the execution of an event callback can | |
| 11349 overwrite any current pending exception in the current application thread. | |
| 11350 Care must be taken to preserve a pending exception | |
| 11351 when an event callback makes a JNI call that might generate an exception. | |
| 11352 </li> | |
| 11353 <li>Event callback functions must be re-entrant. The <jvmti/> implementation does | |
| 11354 not queue events. If an agent needs to process events one at a time, it | |
| 11355 can use a raw monitor inside the | |
| 11356 event callback functions to serialize event processing. | |
| 11357 </li> | |
| 11358 <li>Event callback functions that execute JNI's FindClass function to load | |
| 11359 classes need to note that FindClass locates the class loader associated | |
| 11360 with the current native method. For the purposes of class loading, an | |
| 11361 event callback that includes a JNI environment as a parameter to the | |
| 11362 callback will treated as if it is a native call, where the native method | |
| 11363 is in the class of the event thread's current frame. | |
| 11364 </li> | |
| 11365 </ul> | |
| 11366 <p/> | |
| 11367 Some <jvmti/> events identify objects with JNI references. | |
| 11368 All references | |
| 11369 in <jvmti/> events are JNI local references and will become invalid | |
| 11370 after the event callback returns. | |
| 11371 Unless stated otherwise, memory referenced by pointers sent in event | |
| 11372 callbacks may not be referenced after the event callback returns. | |
| 11373 <p/> | |
| 11374 Except where stated otherwise, events are delivered on the thread | |
| 11375 that caused the event. | |
| 11376 Events are sent at the time they occur. | |
| 11377 The specification for each event includes the set of | |
| 11378 <functionlink id="GetPhase">phases</functionlink> in which it can be sent; | |
| 11379 if an event triggering activity occurs during another phase, no event | |
| 11380 is sent. | |
| 11381 <p/> | |
| 11382 A thread that generates an event does not change its execution status | |
| 11383 (for example, the event does not cause the thread to be suspended). | |
| 11384 If an agent wishes the event to result in suspension, then the agent | |
| 11385 is responsible for explicitly suspending the thread with | |
| 11386 <functionlink id="SuspendThread"></functionlink>. | |
| 11387 <p/> | |
| 11388 If an event is enabled in multiple environments, the event will be sent | |
| 11389 to each agent in the order that the environments were created. | |
| 11390 </intro> | |
| 11391 | |
| 11392 <intro label="Enabling Events" id="enablingevents"> | |
| 11393 All events are initially disabled. In order to receive any | |
| 11394 event: | |
| 11395 <ul> | |
| 11396 <li> | |
| 11397 If the event requires a capability, that capability must | |
| 11398 be added with | |
| 11399 <functionlink id="AddCapabilities"></functionlink>. | |
| 11400 </li> | |
| 11401 <li> | |
| 11402 A callback for the event must be set with | |
| 11403 <functionlink id="SetEventCallbacks"></functionlink>. | |
| 11404 </li> | |
| 11405 <li> | |
| 11406 The event must be enabled with | |
| 11407 <functionlink id="SetEventNotificationMode"></functionlink>. | |
| 11408 </li> | |
| 11409 </ul> | |
| 11410 </intro> | |
| 11411 | |
| 11412 <intro label="Multiple Co-located Events" id="eventorder"> | |
| 11413 In many situations it is possible for multiple events to occur | |
| 11414 at the same location in one thread. When this happens, all the events | |
| 11415 are reported through the event callbacks in the order specified in this section. | |
| 11416 <p/> | |
| 11417 If the current location is at the entry point of a method, the | |
| 11418 <eventlink id="MethodEntry"></eventlink> event is reported before | |
| 11419 any other event at the current location in the same thread. | |
| 11420 <p/> | |
| 11421 If an exception catch has been detected at the current location, | |
| 11422 either because it is the beginning of a catch clause or a native method | |
| 11423 that cleared a pending exception has returned, the | |
| 11424 <code>exceptionCatch</code> event is reported before | |
| 11425 any other event at the current location in the same thread. | |
| 11426 <p/> | |
| 11427 If a <code>singleStep</code> event or | |
| 11428 <code>breakpoint</code> event is triggered at the | |
| 11429 current location, the event is defined to occur | |
| 11430 immediately before the code at the current location is executed. | |
| 11431 These events are reported before any events which are triggered | |
| 11432 by the execution of code at the current location in the same | |
| 11433 thread (specifically: | |
| 11434 <code>exception</code>, | |
| 11435 <code>fieldAccess</code>, and | |
| 11436 <code>fieldModification</code>). | |
| 11437 If both a step and breakpoint event are triggered for the same thread and | |
| 11438 location, the step event is reported before the breakpoint event. | |
| 11439 <p/> | |
| 11440 If the current location is the exit point of a method (that is, the last | |
| 11441 location before returning to the caller), the | |
| 11442 <eventlink id="MethodExit"></eventlink> event and | |
| 11443 the <eventlink id="FramePop"></eventlink> event (if requested) | |
| 11444 are reported after all other events at the current location in the same | |
| 11445 thread. There is no specified ordering of these two events | |
| 11446 with respect to each other. | |
| 11447 <p/> | |
| 11448 Co-located events can be triggered during the processing of some other | |
| 11449 event by the agent at the same location in the same thread. | |
| 11450 If such an event, of type <i>y</i>, is triggered during the processing of | |
| 11451 an event of type <i>x</i>, and if <i>x</i> | |
| 11452 precedes <i>y</i> in the ordering specified above, the co-located event | |
| 11453 <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede | |
| 11454 <i>y</i>, <i>y</i> is not reported for the current thread and location. | |
| 11455 For example, if a breakpoint is set at the current location | |
| 11456 during the processing of <eventlink id="SingleStep"></eventlink>, | |
| 11457 that breakpoint will be reported before the thread moves off the current | |
| 11458 location. | |
| 11459 <p/>The following events are never considered to be co-located with | |
| 11460 other events. | |
| 11461 <ul> | |
| 11462 <li><eventlink id="VMStart"></eventlink></li> | |
| 11463 <li><eventlink id="VMInit"></eventlink></li> | |
| 11464 <li><eventlink id="VMDeath"></eventlink></li> | |
| 11465 <li><eventlink id="ThreadStart"></eventlink></li> | |
| 11466 <li><eventlink id="ThreadEnd"></eventlink></li> | |
| 11467 <li><eventlink id="ClassLoad"></eventlink></li> | |
| 11468 <li><eventlink id="ClassPrepare"></eventlink></li> | |
| 11469 </ul> | |
| 11470 </intro> | |
| 11471 | |
| 11472 <intro label="Event Callbacks" id="jvmtiEventCallbacks"> | |
| 11473 The event callback structure below is used to specify the handler function | |
| 11474 for events. It is set with the | |
| 11475 <functionlink id="SetEventCallbacks"></functionlink> function. | |
| 11476 </intro> | |
| 11477 | |
| 11478 <event label="Single Step" | |
| 11479 id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60"> | |
| 11480 <description> | |
| 11481 Single step events allow the agent to trace thread execution | |
| 11482 at the finest granularity allowed by the VM. A single step event is | |
| 11483 generated whenever a thread reaches a new location. | |
| 11484 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
|
11485 instruction as defined in <vmspec/>. However, some implementations |
| 0 | 11486 may define locations differently. In any case the |
| 11487 <code>method</code> and <code>location</code> | |
| 11488 parameters uniquely identify the current location and allow | |
| 11489 the mapping to source file and line number when that information is | |
| 11490 available. | |
| 11491 <p/> | |
| 11492 No single step events are generated from within native methods. | |
| 11493 </description> | |
| 11494 <origin>jvmdi</origin> | |
| 11495 <capabilities> | |
| 11496 <required id="can_generate_single_step_events"></required> | |
| 11497 </capabilities> | |
| 11498 <parameters> | |
| 11499 <param id="jni_env"> | |
| 11500 <outptr> | |
| 11501 <struct>JNIEnv</struct> | |
| 11502 </outptr> | |
| 11503 <description> | |
| 11504 The JNI environment of the event (current) thread | |
| 11505 </description> | |
| 11506 </param> | |
| 11507 <param id="thread"> | |
| 11508 <jthread/> | |
| 11509 <description> | |
| 11510 Thread about to execution a new instruction | |
| 11511 </description> | |
| 11512 </param> | |
| 11513 <param id="klass"> | |
| 11514 <jclass method="method"/> | |
| 11515 <description> | |
| 11516 Class of the method about to execute a new instruction | |
| 11517 </description> | |
| 11518 </param> | |
| 11519 <param id="method"> | |
| 11520 <jmethodID class="klass"/> | |
| 11521 <description> | |
| 11522 Method about to execute a new instruction | |
| 11523 </description> | |
| 11524 </param> | |
| 11525 <param id="location"> | |
| 11526 <jlocation/> | |
| 11527 <description> | |
| 11528 Location of the new instruction | |
| 11529 </description> | |
| 11530 </param> | |
| 11531 </parameters> | |
| 11532 </event> | |
| 11533 | |
| 11534 <event label="Breakpoint" | |
| 11535 id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62"> | |
| 11536 <description> | |
| 11537 Breakpoint events are generated whenever a thread reaches a location | |
| 11538 designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>. | |
| 11539 The <code>method</code> and <code>location</code> | |
| 11540 parameters uniquely identify the current location and allow | |
| 11541 the mapping to source file and line number when that information is | |
| 11542 available. | |
| 11543 </description> | |
| 11544 <origin>jvmdi</origin> | |
| 11545 <capabilities> | |
| 11546 <required id="can_generate_breakpoint_events"></required> | |
| 11547 </capabilities> | |
| 11548 <parameters> | |
| 11549 <param id="jni_env"> | |
| 11550 <outptr> | |
| 11551 <struct>JNIEnv</struct> | |
| 11552 </outptr> | |
| 11553 <description> | |
| 11554 The JNI environment of the event (current) thread. | |
| 11555 </description> | |
| 11556 </param> | |
| 11557 <param id="thread"> | |
| 11558 <jthread/> | |
| 11559 <description> | |
| 11560 Thread that hit the breakpoint | |
| 11561 </description> | |
| 11562 </param> | |
| 11563 <param id="klass"> | |
| 11564 <jclass method="method"/> | |
| 11565 <description> | |
| 11566 Class of the method that hit the breakpoint | |
| 11567 </description> | |
| 11568 </param> | |
| 11569 <param id="method"> | |
| 11570 <jmethodID class="klass"/> | |
| 11571 <description> | |
| 11572 Method that hit the breakpoint | |
| 11573 </description> | |
| 11574 </param> | |
| 11575 <param id="location"> | |
| 11576 <jlocation/> | |
| 11577 <description> | |
| 11578 location of the breakpoint | |
| 11579 </description> | |
| 11580 </param> | |
| 11581 </parameters> | |
| 11582 </event> | |
| 11583 | |
| 11584 <event label="Field Access" | |
| 11585 id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63"> | |
| 11586 <description> | |
| 11587 Field access events are generated whenever a thread accesses | |
| 11588 a field that was designated as a watchpoint | |
| 11589 with <functionlink id="SetFieldAccessWatch"></functionlink>. | |
| 11590 The <code>method</code> and <code>location</code> | |
| 11591 parameters uniquely identify the current location and allow | |
| 11592 the mapping to source file and line number when that information is | |
| 11593 available. | |
| 11594 </description> | |
| 11595 <origin>jvmdi</origin> | |
| 11596 <capabilities> | |
| 11597 <required id="can_generate_field_access_events"></required> | |
| 11598 </capabilities> | |
| 11599 <parameters> | |
| 11600 <param id="jni_env"> | |
| 11601 <outptr> | |
| 11602 <struct>JNIEnv</struct> | |
| 11603 </outptr> | |
| 11604 <description> | |
| 11605 The JNI environment of the event (current) thread | |
| 11606 </description> | |
| 11607 </param> | |
| 11608 <param id="thread"> | |
| 11609 <jthread/> | |
| 11610 <description> | |
| 11611 Thread accessing the field | |
| 11612 </description> | |
| 11613 </param> | |
| 11614 <param id="klass"> | |
| 11615 <jclass method="method"/> | |
| 11616 <description> | |
| 11617 Class of the method where the access is occurring | |
| 11618 </description> | |
| 11619 </param> | |
| 11620 <param id="method"> | |
| 11621 <jmethodID class="klass"/> | |
| 11622 <description> | |
| 11623 Method where the access is occurring | |
| 11624 </description> | |
| 11625 </param> | |
| 11626 <param id="location"> | |
| 11627 <jlocation/> | |
| 11628 <description> | |
| 11629 Location where the access is occurring | |
| 11630 </description> | |
| 11631 </param> | |
| 11632 <param id="field_klass"> | |
| 11633 <jclass field="field"/> | |
| 11634 <description> | |
| 11635 Class of the field being accessed | |
| 11636 </description> | |
| 11637 </param> | |
| 11638 <param id="object"> | |
| 11639 <jobject/> | |
| 11640 <description> | |
| 11641 Object with the field being accessed if the field is an | |
| 11642 instance field; <code>NULL</code> otherwise | |
| 11643 </description> | |
| 11644 </param> | |
| 11645 <param id="field"> | |
| 11646 <jfieldID class="field_klass"/> | |
| 11647 <description> | |
| 11648 Field being accessed | |
| 11649 </description> | |
| 11650 </param> | |
| 11651 </parameters> | |
| 11652 </event> | |
| 11653 | |
| 11654 <event label="Field Modification" | |
| 11655 id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64"> | |
| 11656 <description> | |
| 11657 Field modification events are generated whenever a thread modifies | |
| 11658 a field that was designated as a watchpoint | |
| 11659 with <functionlink id="SetFieldModificationWatch"></functionlink>. | |
| 11660 The <code>method</code> and <code>location</code> | |
| 11661 parameters uniquely identify the current location and allow | |
| 11662 the mapping to source file and line number when that information is | |
| 11663 available. | |
| 11664 </description> | |
| 11665 <origin>jvmdi</origin> | |
| 11666 <capabilities> | |
| 11667 <required id="can_generate_field_modification_events"></required> | |
| 11668 </capabilities> | |
| 11669 <parameters> | |
| 11670 <param id="jni_env"> | |
| 11671 <outptr> | |
| 11672 <struct>JNIEnv</struct> | |
| 11673 </outptr> | |
| 11674 <description> | |
| 11675 The JNI environment of the event (current) thread | |
| 11676 </description> | |
| 11677 </param> | |
| 11678 <param id="thread"> | |
| 11679 <jthread/> | |
| 11680 <description> | |
| 11681 Thread modifying the field | |
| 11682 </description> | |
| 11683 </param> | |
| 11684 <param id="klass"> | |
| 11685 <jclass method="method"/> | |
| 11686 <description> | |
| 11687 Class of the method where the modification is occurring | |
| 11688 </description> | |
| 11689 </param> | |
| 11690 <param id="method"> | |
| 11691 <jmethodID class="klass"/> | |
| 11692 <description> | |
| 11693 Method where the modification is occurring | |
| 11694 </description> | |
| 11695 </param> | |
| 11696 <param id="location"> | |
| 11697 <jlocation/> | |
| 11698 <description> | |
| 11699 Location where the modification is occurring | |
| 11700 </description> | |
| 11701 </param> | |
| 11702 <param id="field_klass"> | |
| 11703 <jclass field="field"/> | |
| 11704 <description> | |
| 11705 Class of the field being modified | |
| 11706 </description> | |
| 11707 </param> | |
| 11708 <param id="object"> | |
| 11709 <jobject/> | |
| 11710 <description> | |
| 11711 Object with the field being modified if the field is an | |
| 11712 instance field; <code>NULL</code> otherwise | |
| 11713 </description> | |
| 11714 </param> | |
| 11715 <param id="field"> | |
| 11716 <jfieldID class="field_klass"/> | |
| 11717 <description> | |
| 11718 Field being modified | |
| 11719 </description> | |
| 11720 </param> | |
| 11721 <param id="signature_type"> | |
| 11722 <char/> | |
| 11723 <description> | |
| 11724 Signature type of the new value | |
| 11725 </description> | |
| 11726 </param> | |
| 11727 <param id="new_value"> | |
| 11728 <jvalue/> | |
| 11729 <description> | |
| 11730 The new value | |
| 11731 </description> | |
| 11732 </param> | |
| 11733 </parameters> | |
| 11734 </event> | |
| 11735 | |
| 11736 <event label="Frame Pop" | |
| 11737 id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61"> | |
| 11738 <description> | |
| 11739 Frame pop events are generated upon exit from a single method | |
| 11740 in a single frame as specified | |
| 11741 in a call to <functionlink id="NotifyFramePop"></functionlink>. | |
| 11742 This is true whether termination is caused by | |
| 11743 executing its return instruction | |
| 11744 or by throwing an exception to its caller | |
| 11745 (see <paramlink id="was_popped_by_exception"></paramlink>). | |
| 11746 However, frame pops caused by the <functionlink id="PopFrame"/> | |
| 11747 function are not reported. | |
| 11748 <p/> | |
| 11749 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
| 11750 identifies the executable location in the returning method, | |
| 11751 immediately prior to the return. | |
| 11752 </description> | |
| 11753 <origin>jvmdi</origin> | |
| 11754 <capabilities> | |
| 11755 <required id="can_generate_frame_pop_events"></required> | |
| 11756 </capabilities> | |
| 11757 <parameters> | |
| 11758 <param id="jni_env"> | |
| 11759 <outptr> | |
| 11760 <struct>JNIEnv</struct> | |
| 11761 </outptr> | |
| 11762 <description> | |
| 11763 The JNI environment of the event (current) thread | |
| 11764 </description> | |
| 11765 </param> | |
| 11766 <param id="thread"> | |
| 11767 <jthread/> | |
| 11768 <description> | |
| 11769 Thread that is popping the frame | |
| 11770 </description> | |
| 11771 </param> | |
| 11772 <param id="klass"> | |
| 11773 <jclass method="method"/> | |
| 11774 <description> | |
| 11775 Class of the method being popped | |
| 11776 </description> | |
| 11777 </param> | |
| 11778 <param id="method"> | |
| 11779 <jmethodID class="klass"/> | |
| 11780 <description> | |
| 11781 Method being popped | |
| 11782 </description> | |
| 11783 </param> | |
| 11784 <param id="was_popped_by_exception"> | |
| 11785 <jboolean/> | |
| 11786 <description> | |
| 11787 True if frame was popped by a thrown exception. | |
| 11788 False if method exited through its return instruction. | |
| 11789 </description> | |
| 11790 </param> | |
| 11791 </parameters> | |
| 11792 </event> | |
| 11793 | |
| 11794 <event label="Method Entry" | |
| 11795 id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65"> | |
| 11796 <description> | |
| 11797 Method entry events are generated upon entry of Java | |
| 11798 programming language methods (including native methods). | |
| 11799 <p/> | |
| 11800 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
| 11801 identifies the initial executable location in | |
| 11802 the method. | |
| 11803 <p/> | |
| 11804 Enabling method | |
| 11805 entry or exit events will significantly degrade performance on many platforms and is thus | |
| 11806 not advised for performance critical usage (such as profiling). | |
| 11807 <internallink id="bci">Bytecode instrumentation</internallink> should be | |
| 11808 used in these cases. | |
| 11809 </description> | |
| 11810 <origin>jvmdi</origin> | |
| 11811 <capabilities> | |
| 11812 <required id="can_generate_method_entry_events"></required> | |
| 11813 </capabilities> | |
| 11814 <parameters> | |
| 11815 <param id="jni_env"> | |
| 11816 <outptr> | |
| 11817 <struct>JNIEnv</struct> | |
| 11818 </outptr> | |
| 11819 <description> | |
| 11820 The JNI environment of the event (current) thread | |
| 11821 </description> | |
| 11822 </param> | |
| 11823 <param id="thread"> | |
| 11824 <jthread/> | |
| 11825 <description> | |
| 11826 Thread entering the method | |
| 11827 </description> | |
| 11828 </param> | |
| 11829 <param id="klass"> | |
| 11830 <jclass method="method"/> | |
| 11831 <description> | |
| 11832 Class of the method being entered | |
| 11833 </description> | |
| 11834 </param> | |
| 11835 <param id="method"> | |
| 11836 <jmethodID class="klass"/> | |
| 11837 <description> | |
| 11838 Method being entered | |
| 11839 </description> | |
| 11840 </param> | |
| 11841 </parameters> | |
| 11842 </event> | |
| 11843 | |
| 11844 <event label="Method Exit" | |
| 11845 id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66"> | |
| 11846 <description> | |
| 11847 Method exit events are generated upon exit from Java | |
| 11848 programming language methods (including native methods). | |
| 11849 This is true whether termination is caused by | |
| 11850 executing its return instruction | |
| 11851 or by throwing an exception to its caller | |
| 11852 (see <paramlink id="was_popped_by_exception"></paramlink>). | |
| 11853 <p/> | |
| 11854 The <code>method</code> field uniquely identifies the | |
| 11855 method being entered or exited. The <code>frame</code> field provides | |
| 11856 access to the stack frame for the method. | |
| 11857 <p/> | |
| 11858 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
| 11859 identifies the executable location in the returning method | |
| 11860 immediately prior to the return. | |
| 11861 <p/> | |
| 11862 Enabling method | |
| 11863 entry or exit events will significantly degrade performance on many platforms and is thus | |
| 11864 not advised for performance critical usage (such as profiling). | |
| 11865 <internallink id="bci">Bytecode instrumentation</internallink> should be | |
| 11866 used in these cases. | |
| 11867 </description> | |
| 11868 <origin>jvmdi</origin> | |
| 11869 <capabilities> | |
| 11870 <required id="can_generate_method_exit_events"></required> | |
| 11871 </capabilities> | |
| 11872 <parameters> | |
| 11873 <param id="jni_env"> | |
| 11874 <outptr> | |
| 11875 <struct>JNIEnv</struct> | |
| 11876 </outptr> | |
| 11877 <description> | |
| 11878 The JNI environment of the event (current) thread | |
| 11879 </description> | |
| 11880 </param> | |
| 11881 <param id="thread"> | |
| 11882 <jthread/> | |
| 11883 <description> | |
| 11884 Thread exiting the method | |
| 11885 </description> | |
| 11886 </param> | |
| 11887 <param id="klass"> | |
| 11888 <jclass method="method"/> | |
| 11889 <description> | |
| 11890 Class of the method being exited | |
| 11891 </description> | |
| 11892 </param> | |
| 11893 <param id="method"> | |
| 11894 <jmethodID class="klass"/> | |
| 11895 <description> | |
| 11896 Method being exited | |
| 11897 </description> | |
| 11898 </param> | |
| 11899 <param id="was_popped_by_exception"> | |
| 11900 <jboolean/> | |
| 11901 <description> | |
| 11902 True if frame was popped by a thrown exception. | |
| 11903 False if method exited through its return instruction. | |
| 11904 </description> | |
| 11905 </param> | |
| 11906 <param id="return_value"> | |
| 11907 <jvalue/> | |
| 11908 <description> | |
| 11909 The return value of the method being exited. | |
| 11910 Undefined and should not be used if | |
| 11911 <paramlink id="was_popped_by_exception"></paramlink> | |
| 11912 is true. | |
| 11913 </description> | |
| 11914 </param> | |
| 11915 </parameters> | |
| 11916 </event> | |
| 11917 | |
| 11918 <event label="Native Method Bind" phase="any" | |
| 11919 id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67"> | |
| 11920 <description> | |
| 11921 A Native Method Bind event is sent when a VM binds a | |
| 11922 Java programming language native method | |
| 11923 to the address of a function that implements the native method. | |
| 11924 This will occur when the native method is called for the first time | |
| 11925 and also occurs when the JNI function <code>RegisterNatives</code> is called. | |
| 11926 This event allows the bind to be redirected to an agent-specified | |
| 11927 proxy function. | |
| 11928 This event is not sent when the native method is unbound. | |
| 11929 Typically, this proxy function will need to be specific to a | |
| 11930 particular method or, to handle the general case, automatically | |
| 11931 generated assembly code, since after instrumentation code is | |
| 11932 executed the function at the original binding | |
| 11933 address will usually be invoked. | |
| 11934 The original binding can be restored or the redirection changed | |
| 11935 by use of the JNI function <code>RegisterNatives</code>. | |
| 11936 Some events may be sent during the primordial phase, JNI and | |
| 11937 most of <jvmti/> cannot be used at this time but the method and | |
| 11938 address can be saved for use later. | |
| 11939 </description> | |
| 11940 <origin>new</origin> | |
| 11941 <capabilities> | |
| 11942 <required id="can_generate_native_method_bind_events"></required> | |
| 11943 </capabilities> | |
| 11944 <parameters> | |
| 11945 <param id="jni_env"> | |
| 11946 <outptr> | |
| 11947 <struct>JNIEnv</struct> | |
| 11948 </outptr> | |
| 11949 <description> | |
| 11950 The JNI environment of the event (current) thread | |
| 11951 Will be <code>NULL</code> if sent during the primordial | |
| 11952 <functionlink id="GetPhase">phase</functionlink>. | |
| 11953 </description> | |
| 11954 </param> | |
| 11955 <param id="thread"> | |
| 11956 <jthread/> | |
| 11957 <description> | |
| 11958 Thread requesting the bind | |
| 11959 </description> | |
| 11960 </param> | |
| 11961 <param id="klass"> | |
| 11962 <jclass method="method"/> | |
| 11963 <description> | |
| 11964 Class of the method being bound | |
| 11965 </description> | |
| 11966 </param> | |
| 11967 <param id="method"> | |
| 11968 <jmethodID class="klass"/> | |
| 11969 <description> | |
| 11970 Native method being bound | |
| 11971 </description> | |
| 11972 </param> | |
| 11973 <param id="address"> | |
| 11974 <outptr><void/></outptr> | |
| 11975 <description> | |
| 11976 The address the VM is about to bind to--that is, the | |
| 11977 address of the implementation of the native method | |
| 11978 </description> | |
| 11979 </param> | |
| 11980 <param id="new_address_ptr"> | |
| 11981 <agentbuf><void/></agentbuf> | |
| 11982 <description> | |
| 11983 if the referenced address is changed (that is, if | |
| 11984 <code>*new_address_ptr</code> is set), the binding | |
| 11985 will instead be made to the supplied address. | |
| 11986 </description> | |
| 11987 </param> | |
| 11988 </parameters> | |
| 11989 </event> | |
| 11990 | |
| 11991 <event label="Exception" | |
| 11992 id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58"> | |
| 11993 <description> | |
| 11994 Exception events are generated whenever an exception is first detected | |
| 11995 in a Java programming language method. | |
| 11996 Where "exception" means any <code>java.lang.Throwable</code>. | |
| 11997 The exception may have been thrown by a Java programming language or native | |
| 11998 method, but in the case of native methods, the event is not generated | |
| 11999 until the exception is first seen by a Java programming language method. If an exception is | |
| 12000 set and cleared in a native method (and thus is never visible to Java programming language code), | |
| 12001 no exception event is generated. | |
| 12002 <p/> | |
| 12003 The <code>method</code> and <code>location</code> | |
| 12004 parameters uniquely identify the current location | |
| 12005 (where the exception was detected) and allow | |
| 12006 the mapping to source file and line number when that information is | |
| 12007 available. The <code>exception</code> field identifies the thrown | |
| 12008 exception object. The <code>catch_method</code> | |
| 12009 and <code>catch_location</code> identify the location of the catch clause, | |
| 12010 if any, that handles the thrown exception. If there is no such catch clause, | |
| 12011 each field is set to 0. There is no guarantee that the thread will ever | |
| 12012 reach this catch clause. If there are native methods on the call stack | |
| 12013 between the throw location and the catch clause, the exception may | |
| 12014 be reset by one of those native methods. | |
| 12015 Similarly, exceptions that are reported as uncaught (<code>catch_klass</code> | |
| 12016 et al. set to 0) may in fact be caught by native code. | |
| 12017 Agents can check for these occurrences by monitoring | |
| 12018 <eventlink id="ExceptionCatch"></eventlink> events. | |
| 12019 Note that finally clauses are implemented as catch and re-throw. Therefore they | |
| 12020 will be reported in the catch location. | |
| 12021 </description> | |
| 12022 <origin>jvmdi</origin> | |
| 12023 <capabilities> | |
| 12024 <required id="can_generate_exception_events"></required> | |
| 12025 </capabilities> | |
| 12026 <parameters> | |
| 12027 <param id="jni_env"> | |
| 12028 <outptr> | |
| 12029 <struct>JNIEnv</struct> | |
| 12030 </outptr> | |
| 12031 <description> | |
| 12032 The JNI environment of the event (current) thread | |
| 12033 </description> | |
| 12034 </param> | |
| 12035 <param id="thread"> | |
| 12036 <jthread/> | |
| 12037 <description> | |
| 12038 Thread generating the exception | |
| 12039 </description> | |
| 12040 </param> | |
| 12041 <param id="klass"> | |
| 12042 <jclass method="method"/> | |
| 12043 <description> | |
| 12044 Class generating the exception | |
| 12045 </description> | |
| 12046 </param> | |
| 12047 <param id="method"> | |
| 12048 <jmethodID class="klass"/> | |
| 12049 <description> | |
| 12050 Method generating the exception | |
| 12051 </description> | |
| 12052 </param> | |
| 12053 <param id="location"> | |
| 12054 <jlocation/> | |
| 12055 <description> | |
| 12056 Location where exception occurred | |
| 12057 </description> | |
| 12058 </param> | |
| 12059 <param id="exception"> | |
| 12060 <jobject/> | |
| 12061 <description> | |
| 12062 The exception being thrown | |
| 12063 </description> | |
| 12064 </param> | |
| 12065 <param id="catch_klass"> | |
| 12066 <jclass method="catch_method"/> | |
| 12067 <description> | |
| 12068 Class that will catch the exception, or <code>NULL</code> if no known catch | |
| 12069 </description> | |
| 12070 </param> | |
| 12071 <param id="catch_method"> | |
| 12072 <jmethodID class="catch_klass"/> | |
| 12073 <description> | |
| 12074 Method that will catch the exception, or <code>NULL</code> if no known catch | |
| 12075 </description> | |
| 12076 </param> | |
| 12077 <param id="catch_location"> | |
| 12078 <jlocation/> | |
| 12079 <description> | |
| 12080 location which will catch the exception or zero if no known catch | |
| 12081 </description> | |
| 12082 </param> | |
| 12083 </parameters> | |
| 12084 </event> | |
| 12085 | |
| 12086 <event label="Exception Catch" | |
| 12087 id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59"> | |
| 12088 <description> | |
| 12089 Exception catch events are generated whenever a thrown exception is caught. | |
| 12090 Where "exception" means any <code>java.lang.Throwable</code>. | |
| 12091 If the exception is caught in a Java programming language method, the event is generated | |
| 12092 when the catch clause is reached. If the exception is caught in a native | |
| 12093 method, the event is generated as soon as control is returned to a Java programming language | |
| 12094 method. Exception catch events are generated for any exception for which | |
| 12095 a throw was detected in a Java programming language method. | |
| 12096 Note that finally clauses are implemented as catch and re-throw. Therefore they | |
| 12097 will generate exception catch events. | |
| 12098 <p/> | |
| 12099 The <code>method</code> and <code>location</code> | |
| 12100 parameters uniquely identify the current location | |
| 12101 and allow the mapping to source file and line number when that information is | |
| 12102 available. For exceptions caught in a Java programming language method, the | |
| 12103 <code>exception</code> object identifies the exception object. Exceptions | |
| 12104 caught in native methods are not necessarily available by the time the | |
| 12105 exception catch is reported, so the <code>exception</code> field is set | |
| 12106 to <code>NULL</code>. | |
| 12107 </description> | |
| 12108 <origin>jvmdi</origin> | |
| 12109 <capabilities> | |
| 12110 <required id="can_generate_exception_events"></required> | |
| 12111 </capabilities> | |
| 12112 <parameters> | |
| 12113 <param id="jni_env"> | |
| 12114 <outptr> | |
| 12115 <struct>JNIEnv</struct> | |
| 12116 </outptr> | |
| 12117 <description> | |
| 12118 The JNI environment of the event (current) thread | |
| 12119 </description> | |
| 12120 </param> | |
| 12121 <param id="thread"> | |
| 12122 <jthread/> | |
| 12123 <description> | |
| 12124 Thread catching the exception | |
| 12125 </description> | |
| 12126 </param> | |
| 12127 <param id="klass"> | |
| 12128 <jclass method="method"/> | |
| 12129 <description> | |
| 12130 Class catching the exception | |
| 12131 </description> | |
| 12132 </param> | |
| 12133 <param id="method"> | |
| 12134 <jmethodID class="klass"/> | |
| 12135 <description> | |
| 12136 Method catching the exception | |
| 12137 </description> | |
| 12138 </param> | |
| 12139 <param id="location"> | |
| 12140 <jlocation/> | |
| 12141 <description> | |
| 12142 Location where exception is being caught | |
| 12143 </description> | |
| 12144 </param> | |
| 12145 <param id="exception"> | |
| 12146 <jobject/> | |
| 12147 <description> | |
| 12148 Exception being caught | |
| 12149 </description> | |
| 12150 </param> | |
| 12151 </parameters> | |
| 12152 </event> | |
| 12153 | |
| 12154 <event label="Thread Start" | |
| 12155 id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start"> | |
| 12156 <description> | |
| 12157 Thread start events are generated by a new thread before its initial | |
| 12158 method executes. | |
| 12159 <p/> | |
| 12160 A thread may be listed in the array returned by | |
| 12161 <functionlink id="GetAllThreads"></functionlink> | |
| 12162 before its thread start event is generated. | |
| 12163 It is possible for other events to be generated | |
| 12164 on a thread before its thread start event. | |
| 12165 <p/> | |
| 12166 The event is sent on the newly started <paramlink id="thread"></paramlink>. | |
| 12167 </description> | |
| 12168 <origin>jvmdi</origin> | |
| 12169 <capabilities> | |
| 12170 </capabilities> | |
| 12171 <parameters> | |
| 12172 <param id="jni_env"> | |
| 12173 <outptr> | |
| 12174 <struct>JNIEnv</struct> | |
| 12175 </outptr> | |
| 12176 <description> | |
| 12177 The JNI environment of the event (current) thread. | |
| 12178 </description> | |
| 12179 </param> | |
| 12180 <param id="thread"> | |
| 12181 <jthread/> | |
| 12182 <description> | |
| 12183 Thread starting | |
| 12184 </description> | |
| 12185 </param> | |
| 12186 </parameters> | |
| 12187 </event> | |
| 12188 | |
| 12189 <event label="Thread End" | |
| 12190 id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start"> | |
| 12191 <description> | |
| 12192 Thread end events are generated by a terminating thread | |
| 12193 after its initial method has finished execution. | |
| 12194 <p/> | |
| 12195 A thread may be listed in the array returned by | |
| 12196 <functionlink id="GetAllThreads"></functionlink> | |
| 12197 after its thread end event is generated. | |
| 12198 No events are generated on a thread | |
| 12199 after its thread end event. | |
| 12200 <p/> | |
| 12201 The event is sent on the dying <paramlink id="thread"></paramlink>. | |
| 12202 </description> | |
| 12203 <origin>jvmdi</origin> | |
| 12204 <capabilities> | |
| 12205 </capabilities> | |
| 12206 <parameters> | |
| 12207 <param id="jni_env"> | |
| 12208 <outptr> | |
| 12209 <struct>JNIEnv</struct> | |
| 12210 </outptr> | |
| 12211 <description> | |
| 12212 The JNI environment of the event (current) thread. | |
| 12213 </description> | |
| 12214 </param> | |
| 12215 <param id="thread"> | |
| 12216 <jthread/> | |
| 12217 <description> | |
| 12218 Thread ending | |
| 12219 </description> | |
| 12220 </param> | |
| 12221 </parameters> | |
| 12222 </event> | |
| 12223 | |
| 12224 <event label="Class Load" | |
| 12225 id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55"> | |
| 12226 <description> | |
| 12227 A class load event is generated when a class is first loaded. The order | |
| 12228 of class load events generated by a particular thread are guaranteed | |
| 12229 to match the order of class loading within that thread. | |
| 12230 Array class creation does not generate a class load event. | |
| 12231 The creation of a primitive class (for example, java.lang.Integer.TYPE) | |
| 12232 does not generate a class load event. | |
| 12233 <p/> | |
| 12234 This event is sent at an early stage in loading the class. As | |
| 12235 a result the class should be used carefully. Note, for example, | |
| 12236 that methods and fields are not yet loaded, so queries for methods, | |
| 12237 fields, subclasses, and so on will not give correct results. | |
| 12238 See "Loading of Classes and Interfaces" in the <i>Java Language | |
| 12239 Specification</i>. For most | |
| 12240 purposes the <eventlink id="ClassPrepare"></eventlink> event will | |
| 12241 be more useful. | |
| 12242 </description> | |
| 12243 <origin>jvmdi</origin> | |
| 12244 <capabilities> | |
| 12245 </capabilities> | |
| 12246 <parameters> | |
| 12247 <param id="jni_env"> | |
| 12248 <outptr> | |
| 12249 <struct>JNIEnv</struct> | |
| 12250 </outptr> | |
| 12251 <description> | |
| 12252 The JNI environment of the event (current) thread | |
| 12253 </description> | |
| 12254 </param> | |
| 12255 <param id="thread"> | |
| 12256 <jthread/> | |
| 12257 <description> | |
| 12258 Thread loading the class | |
| 12259 </description> | |
| 12260 </param> | |
| 12261 <param id="klass"> | |
| 12262 <jclass/> | |
| 12263 <description> | |
| 12264 Class being loaded | |
| 12265 </description> | |
| 12266 </param> | |
| 12267 </parameters> | |
| 12268 </event> | |
| 12269 | |
| 12270 <elide> | |
| 12271 <event label="Class Unload" | |
| 12272 id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57"> | |
| 12273 <description> | |
| 12274 A class unload event is generated when the class is about to be unloaded. | |
| 12275 Class unload events take place during garbage collection and must be | |
| 12276 handled extremely carefully. The garbage collector holds many locks | |
| 12277 and has suspended all other threads, so the event handler cannot depend | |
| 12278 on the ability to acquire any locks. The class unload event handler should | |
| 12279 do as little as possible, perhaps by queuing information to be processed | |
| 12280 later. In particular, the <code>jclass</code> should be used only in | |
| 12281 the JNI function <code>isSameObject</code> or in the following <jvmti/> functions: | |
| 12282 <ul> | |
| 12283 <li><functionlink id="GetClassSignature"></functionlink></li> | |
| 12284 <li><functionlink id="GetSourceFileName"></functionlink></li> | |
| 12285 <li><functionlink id="IsInterface"></functionlink></li> | |
| 12286 <li><functionlink id="IsArrayClass"></functionlink></li> | |
| 12287 </ul> | |
| 12288 </description> | |
| 12289 <origin>jvmdi</origin> | |
| 12290 <capabilities> | |
| 12291 </capabilities> | |
| 12292 <parameters> | |
| 12293 <param id="jni_env"> | |
| 12294 <outptr> | |
| 12295 <struct>JNIEnv</struct> | |
| 12296 </outptr> | |
| 12297 <description> | |
| 12298 The JNI environment of the event (current) thread | |
| 12299 </description> | |
| 12300 </param> | |
| 12301 <param id="thread"> | |
| 12302 <jthread/> | |
| 12303 <description> | |
| 12304 Thread generating the class unload | |
| 12305 </description> | |
| 12306 </param> | |
| 12307 <param id="klass"> | |
| 12308 <jclass/> | |
| 12309 <description> | |
| 12310 Class being unloaded | |
| 12311 </description> | |
| 12312 </param> | |
| 12313 </parameters> | |
| 12314 </event> | |
| 12315 </elide> | |
| 12316 | |
| 12317 <event label="Class Prepare" | |
| 12318 id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56"> | |
| 12319 <description> | |
| 12320 A class prepare event is generated when class preparation is complete. | |
| 12321 At this point, class fields, methods, and implemented interfaces are | |
| 12322 available, and no code from the class has been executed. Since array | |
| 12323 classes never have fields or methods, class prepare events are not | |
| 12324 generated for them. Class prepare events are not generated for | |
| 12325 primitive classes (for example, <code>java.lang.Integer.TYPE</code>). | |
| 12326 </description> | |
| 12327 <origin>jvmdi</origin> | |
| 12328 <capabilities> | |
| 12329 </capabilities> | |
| 12330 <parameters> | |
| 12331 <param id="jni_env"> | |
| 12332 <outptr> | |
| 12333 <struct>JNIEnv</struct> | |
| 12334 </outptr> | |
| 12335 <description> | |
| 12336 The JNI environment of the event (current) thread | |
| 12337 </description> | |
| 12338 </param> | |
| 12339 <param id="thread"> | |
| 12340 <jthread/> | |
| 12341 <description> | |
| 12342 Thread generating the class prepare | |
| 12343 </description> | |
| 12344 </param> | |
| 12345 <param id="klass"> | |
| 12346 <jclass/> | |
| 12347 <description> | |
| 12348 Class being prepared | |
| 12349 </description> | |
| 12350 </param> | |
| 12351 </parameters> | |
| 12352 </event> | |
| 12353 | |
| 12354 <event label="Class File Load Hook" phase="any" | |
| 12355 id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54"> | |
| 12356 <description> | |
| 12357 This event is sent when the VM obtains class file data, | |
| 12358 but before it constructs | |
| 12359 the in-memory representation for that class. | |
| 12360 This event is also sent when the class is being modified by the | |
| 12361 <functionlink id="RetransformClasses"/> function or | |
| 12362 the <functionlink id="RedefineClasses"/> function, | |
| 12363 called in any <jvmti/> environment. | |
| 12364 The agent can instrument | |
| 12365 the existing class file data sent by the VM to include profiling/debugging hooks. | |
| 12366 See the description of | |
| 12367 <internallink id="bci">bytecode instrumentation</internallink> | |
| 12368 for usage information. | |
| 12369 <p/> | |
| 12370 This event may be sent before the VM is initialized (the primordial | |
| 12371 <functionlink id="GetPhase">phase</functionlink>). During this time | |
| 12372 no VM resources should be created. Some classes might not be compatible | |
| 12373 with the function (eg. ROMized classes) and this event will not be | |
| 12374 generated for these classes. | |
| 12375 <p/> | |
| 12376 The agent must allocate the space for the modified | |
| 12377 class file data buffer | |
| 12378 using the memory allocation function | |
| 12379 <functionlink id="Allocate"></functionlink> because the | |
| 12380 VM is responsible for freeing the new class file data buffer | |
| 12381 using <functionlink id="Deallocate"></functionlink>. | |
| 12382 Note that <functionlink id="Allocate"></functionlink> | |
| 12383 is permitted during the primordial phase. | |
| 12384 <p/> | |
| 12385 If the agent wishes to modify the class file, it must set | |
| 12386 <code>new_class_data</code> to point | |
| 12387 to the newly instrumented class file data buffer and set | |
| 12388 <code>new_class_data_len</code> to the length of that | |
| 12389 buffer before returning | |
| 12390 from this call. If no modification is desired, the agent simply | |
| 12391 does not set <code>new_class_data</code>. If multiple agents | |
| 12392 have enabled this event the results are chained. That is, if | |
| 12393 <code>new_class_data</code> has been set, it becomes the | |
| 12394 <code>class_data</code> for the next agent. | |
| 12395 <p/> | |
| 12396 The order that this event is sent to each environment differs | |
| 12397 from other events. | |
| 12398 This event is sent to environments in the following order: | |
| 12399 <ul> | |
| 12400 <li><fieldlink id="can_retransform_classes" | |
| 12401 struct="jvmtiCapabilities">retransformation | |
| 12402 incapable</fieldlink> | |
| 12403 environments, in the | |
| 12404 order in which they were created | |
| 12405 </li> | |
| 12406 <li><fieldlink id="can_retransform_classes" | |
| 12407 struct="jvmtiCapabilities">retransformation | |
| 12408 capable</fieldlink> | |
| 12409 environments, in the | |
| 12410 order in which they were created | |
| 12411 </li> | |
| 12412 </ul> | |
| 12413 When triggered by <functionlink id="RetransformClasses"/>, | |
| 12414 this event is sent only to <fieldlink id="can_retransform_classes" | |
| 12415 struct="jvmtiCapabilities">retransformation | |
| 12416 capable</fieldlink> | |
| 12417 environments. | |
| 12418 </description> | |
| 12419 <origin>jvmpi</origin> | |
| 12420 <capabilities> | |
| 12421 <capability id="can_generate_all_class_hook_events"></capability> | |
| 12422 </capabilities> | |
| 12423 <parameters> | |
| 12424 <param id="jni_env"> | |
| 12425 <outptr> | |
| 12426 <struct>JNIEnv</struct> | |
| 12427 </outptr> | |
| 12428 <description> | |
| 12429 The JNI environment of the event (current) thread. | |
| 12430 Will be <code>NULL</code> if sent during the primordial | |
| 12431 <functionlink id="GetPhase">phase</functionlink>. | |
| 12432 </description> | |
| 12433 </param> | |
| 12434 <param id="class_being_redefined"> | |
| 12435 <jclass/> | |
| 12436 <description> | |
| 12437 The class being | |
| 12438 <functionlink id="RedefineClasses">redefined</functionlink> or | |
| 12439 <functionlink id="RetransformClasses">retransformed</functionlink>. | |
| 12440 <code>NULL</code> if sent by class load. | |
| 12441 </description> | |
| 12442 </param> | |
| 12443 <param id="loader"> | |
| 12444 <jobject/> | |
| 12445 <description> | |
| 12446 The class loader loading the class. | |
| 12447 <code>NULL</code> if the bootstrap class loader. | |
| 12448 </description> | |
| 12449 </param> | |
| 12450 <param id="name"> | |
| 12451 <vmbuf><char/></vmbuf> | |
| 12452 <description> | |
| 12453 Name of class being loaded as a VM internal qualified name | |
| 12454 (for example, "java/util/List"), encoded as a | |
| 12455 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 12456 Note: if the class is defined with a <code>NULL</code> name or | |
| 12457 without a name specified, <code>name</code> will be <code>NULL</code>. | |
| 12458 </description> | |
| 12459 </param> | |
| 12460 <param id="protection_domain"> | |
| 12461 <jobject/> | |
| 12462 <description> | |
| 12463 The <code>ProtectionDomain</code> of the class. | |
| 12464 </description> | |
| 12465 </param> | |
| 12466 <param id="class_data_len"> | |
| 12467 <jint/> | |
| 12468 <description> | |
| 12469 Length of current class file data buffer. | |
| 12470 </description> | |
| 12471 </param> | |
| 12472 <param id="class_data"> | |
| 12473 <vmbuf><uchar/></vmbuf> | |
| 12474 <description> | |
| 12475 Pointer to the current class file data buffer. | |
| 12476 </description> | |
| 12477 </param> | |
| 12478 <param id="new_class_data_len"> | |
| 12479 <outptr><jint/></outptr> | |
| 12480 <description> | |
| 12481 Pointer to the length of the new class file data buffer. | |
| 12482 </description> | |
| 12483 </param> | |
| 12484 <param id="new_class_data"> | |
| 12485 <agentbuf incount="new_class_data_len"><uchar/></agentbuf> | |
| 12486 <description> | |
| 12487 Pointer to the pointer to the instrumented class file data buffer. | |
| 12488 </description> | |
| 12489 </param> | |
| 12490 </parameters> | |
| 12491 </event> | |
| 12492 | |
| 12493 <event label="VM Start Event" | |
| 12494 id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start"> | |
| 12495 <description> | |
| 12496 The VM initialization event signals the start of the VM. | |
| 12497 At this time JNI is live but the VM is not yet fully initialized. | |
| 12498 Once this event is generated, the agent is free to call any JNI function. | |
| 12499 This event signals the beginning of the start phase, | |
| 12500 <jvmti/> functions permitted in the start phase may be called. | |
| 12501 <p/> | |
| 12502 In the case of VM start-up failure, this event will not be sent. | |
| 12503 </description> | |
| 12504 <origin>jvmdi</origin> | |
| 12505 <capabilities> | |
| 12506 </capabilities> | |
| 12507 <parameters> | |
| 12508 <param id="jni_env"> | |
| 12509 <outptr> | |
| 12510 <struct>JNIEnv</struct> | |
| 12511 </outptr> | |
| 12512 <description> | |
| 12513 The JNI environment of the event (current) thread. | |
| 12514 </description> | |
| 12515 </param> | |
| 12516 </parameters> | |
| 12517 </event> | |
| 12518 | |
| 12519 <event label="VM Initialization Event" | |
| 12520 id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50"> | |
| 12521 <description> | |
| 12522 The VM initialization event signals the completion of VM initialization. Once | |
| 12523 this event is generated, the agent is free to call any JNI or <jvmti/> | |
| 12524 function. The VM initialization event can be preceded by or can be concurrent | |
| 12525 with other events, but | |
| 12526 the preceding events should be handled carefully, if at all, because the | |
| 12527 VM has not completed its initialization. The thread start event for the | |
| 12528 main application thread is guaranteed not to occur until after the | |
| 12529 handler for the VM initialization event returns. | |
| 12530 <p/> | |
| 12531 In the case of VM start-up failure, this event will not be sent. | |
| 12532 </description> | |
| 12533 <origin>jvmdi</origin> | |
| 12534 <capabilities> | |
| 12535 </capabilities> | |
| 12536 <parameters> | |
| 12537 <param id="jni_env"> | |
| 12538 <outptr> | |
| 12539 <struct>JNIEnv</struct> | |
| 12540 </outptr> | |
| 12541 <description> | |
| 12542 The JNI environment of the event (current) thread. | |
| 12543 </description> | |
| 12544 </param> | |
| 12545 <param id="thread"> | |
| 12546 <jthread/> | |
| 12547 <description> | |
| 12548 The initial thread | |
| 12549 </description> | |
| 12550 </param> | |
| 12551 </parameters> | |
| 12552 </event> | |
| 12553 | |
| 12554 <event label="VM Death Event" | |
| 12555 id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51"> | |
| 12556 <description> | |
| 12557 The VM death event notifies the agent of the termination of the VM. | |
| 12558 No events will occur after the VMDeath event. | |
| 12559 <p/> | |
| 12560 In the case of VM start-up failure, this event will not be sent. | |
| 12561 Note that <internallink id="onunload">Agent_OnUnload</internallink> | |
| 12562 will still be called in these cases. | |
| 12563 </description> | |
| 12564 <origin>jvmdi</origin> | |
| 12565 <capabilities> | |
| 12566 </capabilities> | |
| 12567 <parameters> | |
| 12568 <param id="jni_env"> | |
| 12569 <outptr> | |
| 12570 <struct>JNIEnv</struct> | |
| 12571 </outptr> | |
| 12572 <description> | |
| 12573 The JNI environment of the event (current) thread | |
| 12574 </description> | |
| 12575 </param> | |
| 12576 </parameters> | |
| 12577 </event> | |
| 12578 | |
| 12579 <event label="Compiled Method Load" | |
| 12580 id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68"> | |
| 12581 <description> | |
| 12582 Sent when a method is compiled and loaded into memory by the VM. | |
| 12583 If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent. | |
| 12584 If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent, | |
| 12585 followed by a new <code>CompiledMethodLoad</code> event. | |
| 12586 Note that a single method may have multiple compiled forms, and that | |
| 12587 this event will be sent for each form. | |
| 12588 Note also that several methods may be inlined into a single | |
| 12589 address range, and that this event will be sent for each method. | |
| 12590 <p/> | |
| 12591 These events can be sent after their initial occurrence with | |
| 12592 <functionlink id="GenerateEvents"></functionlink>. | |
| 12593 </description> | |
| 12594 <origin>jvmpi</origin> | |
| 12595 <typedef id="jvmtiAddrLocationMap" label="Native address to location entry"> | |
| 12596 <field id="start_address"> | |
| 12597 <vmbuf><void/></vmbuf> | |
| 12598 <description> | |
| 12599 Starting native address of code corresponding to a location | |
| 12600 </description> | |
| 12601 </field> | |
| 12602 <field id="location"> | |
| 12603 <jlocation/> | |
| 12604 <description> | |
| 12605 Corresponding location. See | |
| 12606 <functionlink id="GetJLocationFormat"></functionlink> | |
| 12607 for the meaning of location. | |
| 12608 </description> | |
| 12609 </field> | |
| 12610 </typedef> | |
| 12611 <capabilities> | |
| 12612 <required id="can_generate_compiled_method_load_events"></required> | |
| 12613 </capabilities> | |
| 12614 <parameters> | |
| 12615 <param id="klass"> | |
| 12616 <jclass method="method"/> | |
| 12617 <description> | |
| 12618 Class of the method being compiled and loaded | |
| 12619 </description> | |
| 12620 </param> | |
| 12621 <param id="method"> | |
| 12622 <jmethodID class="klass"/> | |
| 12623 <description> | |
| 12624 Method being compiled and loaded | |
| 12625 </description> | |
| 12626 </param> | |
| 12627 <param id="code_size"> | |
| 12628 <jint/> | |
| 12629 <description> | |
| 12630 Size of compiled code | |
| 12631 </description> | |
| 12632 </param> | |
| 12633 <param id="code_addr"> | |
| 12634 <vmbuf><void/></vmbuf> | |
| 12635 <description> | |
| 12636 Address where compiled method code is loaded | |
| 12637 </description> | |
| 12638 </param> | |
| 12639 <param id="map_length"> | |
| 12640 <jint/> | |
| 12641 <description> | |
| 12642 Number of <typelink id="jvmtiAddrLocationMap"></typelink> | |
| 12643 entries in the address map. | |
| 12644 Zero if mapping information cannot be supplied. | |
| 12645 </description> | |
| 12646 </param> | |
| 12647 <param id="map"> | |
| 12648 <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf> | |
| 12649 <description> | |
| 12650 Map from native addresses to location. | |
| 12651 The native address range of each entry is from | |
| 12652 <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink> | |
| 12653 to <code>start_address-1</code> of the next entry. | |
| 12654 <code>NULL</code> if mapping information cannot be supplied. | |
| 12655 </description> | |
| 12656 </param> | |
| 12657 <param id="compile_info"> | |
| 12658 <vmbuf><void/></vmbuf> | |
| 12659 <description> | |
| 12660 VM-specific compilation information. | |
| 12661 The referenced compile information is managed by the VM | |
| 12662 and must not depend on the agent for collection. | |
| 12663 A VM implementation defines the content and lifetime | |
| 12664 of the information. | |
| 12665 </description> | |
| 12666 </param> | |
| 12667 </parameters> | |
| 12668 </event> | |
| 12669 | |
| 12670 <event label="Compiled Method Unload" | |
| 12671 id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69"> | |
| 12672 <description> | |
| 12673 Sent when a compiled method is unloaded from memory. | |
| 12674 This event might not be sent on the thread which performed the unload. | |
| 12675 This event may be sent sometime after the unload occurs, but | |
| 12676 will be sent before the memory is reused | |
| 12677 by a newly generated compiled method. This event may be sent after | |
| 12678 the class is unloaded. | |
| 12679 </description> | |
| 12680 <origin>jvmpi</origin> | |
| 12681 <capabilities> | |
| 12682 <required id="can_generate_compiled_method_load_events"></required> | |
| 12683 </capabilities> | |
| 12684 <parameters> | |
| 12685 <param id="klass"> | |
| 12686 <jclass method="method"/> | |
| 12687 <description> | |
| 12688 Class of the compiled method being unloaded. | |
| 12689 </description> | |
| 12690 </param> | |
| 12691 <param id="method"> | |
| 12692 <jmethodID class="klass"/> | |
| 12693 <description> | |
| 12694 Compiled method being unloaded. | |
| 12695 For identification of the compiled method only -- the class | |
| 12696 may be unloaded and therefore the method should not be used | |
| 12697 as an argument to further JNI or <jvmti/> functions. | |
| 12698 </description> | |
| 12699 </param> | |
| 12700 <param id="code_addr"> | |
| 12701 <vmbuf><void/></vmbuf> | |
| 12702 <description> | |
| 12703 Address where compiled method code was loaded. | |
| 12704 For identification of the compiled method only -- | |
| 12705 the space may have been reclaimed. | |
| 12706 </description> | |
| 12707 </param> | |
| 12708 </parameters> | |
| 12709 </event> | |
| 12710 | |
| 12711 <event label="Dynamic Code Generated" phase="any" | |
| 12712 id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70"> | |
| 12713 <description> | |
| 12714 Sent when a component of the virtual machine is generated dynamically. | |
| 12715 This does not correspond to Java programming language code that is | |
| 12716 compiled--see <eventlink id="CompiledMethodLoad"></eventlink>. | |
| 12717 This is for native code--for example, an interpreter that is generated | |
| 12718 differently depending on command-line options. | |
| 12719 <p/> | |
| 12720 Note that this event has no controlling capability. | |
| 12721 If a VM cannot generate these events, it simply does not send any. | |
| 12722 <p/> | |
| 12723 These events can be sent after their initial occurrence with | |
| 12724 <functionlink id="GenerateEvents"></functionlink>. | |
| 12725 </description> | |
| 12726 <origin>jvmpi</origin> | |
| 12727 <capabilities> | |
| 12728 </capabilities> | |
| 12729 <parameters> | |
| 12730 <param id="name"> | |
| 12731 <vmbuf><char/></vmbuf> | |
| 12732 <description> | |
| 12733 Name of the code, encoded as a | |
| 12734 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 12735 Intended for display to an end-user. | |
| 12736 The name might not be unique. | |
| 12737 </description> | |
| 12738 </param> | |
| 12739 <param id="address"> | |
| 12740 <vmbuf><void/></vmbuf> | |
| 12741 <description> | |
| 12742 Native address of the code | |
| 12743 </description> | |
| 12744 </param> | |
| 12745 <param id="length"> | |
| 12746 <jint/> | |
| 12747 <description> | |
| 12748 Length in bytes of the code | |
| 12749 </description> | |
| 12750 </param> | |
| 12751 </parameters> | |
| 12752 </event> | |
| 12753 | |
| 12754 <event label="Data Dump Request" | |
| 12755 id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71"> | |
| 12756 <description> | |
| 12757 Sent by the VM to request the agent to dump its data. This | |
| 12758 is just a hint and the agent need not react to this event. | |
| 12759 This is useful for processing command-line signals from users. For | |
| 12760 example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris | |
| 12761 causes the VM to send this event to the agent. | |
| 12762 </description> | |
| 12763 <origin>jvmpi</origin> | |
| 12764 <capabilities> | |
| 12765 </capabilities> | |
| 12766 <parameters> | |
| 12767 </parameters> | |
| 12768 </event> | |
| 12769 | |
| 12770 <event label="Monitor Contended Enter" | |
| 12771 id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75"> | |
| 12772 <description> | |
| 12773 Sent when a thread is attempting to enter a Java programming language | |
| 12774 monitor already acquired by another thread. | |
| 12775 </description> | |
| 12776 <origin>jvmpi</origin> | |
| 12777 <capabilities> | |
| 12778 <required id="can_generate_monitor_events"></required> | |
| 12779 </capabilities> | |
| 12780 <parameters> | |
| 12781 <param id="jni_env"> | |
| 12782 <outptr> | |
| 12783 <struct>JNIEnv</struct> | |
| 12784 </outptr> | |
| 12785 <description> | |
| 12786 The JNI environment of the event (current) thread | |
| 12787 </description> | |
| 12788 </param> | |
| 12789 <param id="thread"> | |
| 12790 <jthread/> | |
| 12791 <description> | |
| 12792 JNI local reference to the thread | |
| 12793 attempting to enter the monitor | |
| 12794 </description> | |
| 12795 </param> | |
| 12796 <param id="object"> | |
| 12797 <jobject/> | |
| 12798 <description> | |
| 12799 JNI local reference to the monitor | |
| 12800 </description> | |
| 12801 </param> | |
| 12802 </parameters> | |
| 12803 </event> | |
| 12804 | |
| 12805 <event label="Monitor Contended Entered" | |
| 12806 id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76"> | |
| 12807 <description> | |
| 12808 Sent when a thread enters a Java programming language | |
| 12809 monitor after waiting for it to be released by another thread. | |
| 12810 </description> | |
| 12811 <origin>jvmpi</origin> | |
| 12812 <capabilities> | |
| 12813 <required id="can_generate_monitor_events"></required> | |
| 12814 </capabilities> | |
| 12815 <parameters> | |
| 12816 <param id="jni_env"> | |
| 12817 <outptr> | |
| 12818 <struct>JNIEnv</struct> | |
| 12819 </outptr> | |
| 12820 <description> | |
| 12821 The JNI environment of the event (current) thread | |
| 12822 </description> | |
| 12823 </param> | |
| 12824 <param id="thread"> | |
| 12825 <jthread/> | |
| 12826 <description> | |
| 12827 JNI local reference to the thread entering | |
| 12828 the monitor | |
| 12829 </description> | |
| 12830 </param> | |
| 12831 <param id="object"> | |
| 12832 <jobject/> | |
| 12833 <description> | |
| 12834 JNI local reference to the monitor | |
| 12835 </description> | |
| 12836 </param> | |
| 12837 </parameters> | |
| 12838 </event> | |
| 12839 | |
| 12840 <event label="Monitor Wait" | |
| 12841 id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73"> | |
| 12842 <description> | |
| 12843 Sent when a thread is about to wait on an object. | |
| 12844 </description> | |
| 12845 <origin>jvmpi</origin> | |
| 12846 <capabilities> | |
| 12847 <required id="can_generate_monitor_events"></required> | |
| 12848 </capabilities> | |
| 12849 <parameters> | |
| 12850 <param id="jni_env"> | |
| 12851 <outptr> | |
| 12852 <struct>JNIEnv</struct> | |
| 12853 </outptr> | |
| 12854 <description> | |
| 12855 The JNI environment of the event (current) thread | |
| 12856 </description> | |
| 12857 </param> | |
| 12858 <param id="thread"> | |
| 12859 <jthread/> | |
| 12860 <description> | |
| 12861 JNI local reference to the thread about to wait | |
| 12862 </description> | |
| 12863 </param> | |
| 12864 <param id="object"> | |
| 12865 <jobject/> | |
| 12866 <description> | |
| 12867 JNI local reference to the monitor | |
| 12868 </description> | |
| 12869 </param> | |
| 12870 <param id="timeout"> | |
| 12871 <jlong/> | |
| 12872 <description> | |
| 12873 The number of milliseconds the thread will wait | |
| 12874 </description> | |
| 12875 </param> | |
| 12876 </parameters> | |
| 12877 </event> | |
| 12878 | |
| 12879 <event label="Monitor Waited" | |
| 12880 id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74"> | |
| 12881 <description> | |
| 12882 Sent when a thread finishes waiting on an object. | |
| 12883 </description> | |
| 12884 <origin>jvmpi</origin> | |
| 12885 <capabilities> | |
| 12886 <required id="can_generate_monitor_events"></required> | |
| 12887 </capabilities> | |
| 12888 <parameters> | |
| 12889 <param id="jni_env"> | |
| 12890 <outptr> | |
| 12891 <struct>JNIEnv</struct> | |
| 12892 </outptr> | |
| 12893 <description> | |
| 12894 The JNI environment of the event (current) thread | |
| 12895 </description> | |
| 12896 </param> | |
| 12897 <param id="thread"> | |
| 12898 <jthread/> | |
| 12899 <description> | |
| 12900 JNI local reference to the thread that was finished waiting | |
| 12901 </description> | |
| 12902 </param> | |
| 12903 <param id="object"> | |
| 12904 <jobject/> | |
| 12905 <description> | |
| 12906 JNI local reference to the monitor. | |
| 12907 </description> | |
| 12908 </param> | |
| 12909 <param id="timed_out"> | |
| 12910 <jboolean/> | |
| 12911 <description> | |
| 12912 True if the monitor timed out | |
| 12913 </description> | |
| 12914 </param> | |
| 12915 </parameters> | |
| 12916 </event> | |
| 12917 | |
| 12918 <event label="Resource Exhausted" | |
| 12919 id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80" | |
| 12920 since="1.1"> | |
| 12921 <description> | |
| 12922 Sent when a VM resource needed by a running application has been exhausted. | |
| 12923 Except as required by the optional capabilities, the set of resources | |
| 12924 which report exhaustion is implementation dependent. | |
| 12925 <p/> | |
| 12926 The following bit flags define the properties of the resource exhaustion: | |
| 12927 <constants id="jvmtiResourceExhaustionFlags" | |
| 12928 label="Resource Exhaustion Flags" | |
| 12929 kind="bits" | |
| 12930 since="1.1"> | |
| 12931 <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001"> | |
| 12932 After this event returns, the VM will throw a | |
| 12933 <code>java.lang.OutOfMemoryError</code>. | |
| 12934 </constant> | |
| 12935 <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002"> | |
| 12936 The VM was unable to allocate memory from the <tm>Java</tm> | |
| 12937 platform <i>heap</i>. | |
| 12938 The <i>heap</i> is the runtime | |
| 12939 data area from which memory for all class instances and | |
| 12940 arrays are allocated. | |
| 12941 </constant> | |
| 12942 <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004"> | |
| 12943 The VM was unable to create a thread. | |
| 12944 </constant> | |
| 12945 </constants> | |
| 12946 </description> | |
| 12947 <origin>new</origin> | |
| 12948 <capabilities> | |
| 12949 <capability id="can_generate_resource_exhaustion_heap_events"> | |
| 12950 Can generate events when the VM is unable to allocate memory from the | |
| 12951 <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>. | |
| 12952 </capability> | |
| 12953 <capability id="can_generate_resource_exhaustion_threads_events"> | |
| 12954 Can generate events when the VM is unable to | |
| 12955 <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create | |
| 12956 a thread</internallink>. | |
| 12957 </capability> | |
| 12958 </capabilities> | |
| 12959 <parameters> | |
| 12960 <param id="jni_env"> | |
| 12961 <outptr> | |
| 12962 <struct>JNIEnv</struct> | |
| 12963 </outptr> | |
| 12964 <description> | |
| 12965 The JNI environment of the event (current) thread | |
| 12966 </description> | |
| 12967 </param> | |
| 12968 <param id="flags"> | |
| 12969 <jint/> | |
| 12970 <description> | |
| 12971 Flags defining the properties of the of resource exhaustion | |
| 12972 as specified by the | |
| 12973 <internallink id="jvmtiResourceExhaustionFlags">Resource | |
| 12974 Exhaustion Flags</internallink>. | |
| 12975 </description> | |
| 12976 </param> | |
| 12977 <param id="reserved"> | |
| 12978 <vmbuf><void/></vmbuf> | |
| 12979 <description> | |
| 12980 Reserved. | |
| 12981 </description> | |
| 12982 </param> | |
| 12983 <param id="description"> | |
| 12984 <vmbuf><char/></vmbuf> | |
| 12985 <description> | |
| 12986 Description of the resource exhaustion, encoded as a | |
| 12987 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 12988 </description> | |
| 12989 </param> | |
| 12990 </parameters> | |
| 12991 </event> | |
| 12992 | |
| 12993 <event label="VM Object Allocation" | |
| 12994 id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84"> | |
| 12995 <description> | |
| 12996 Sent when a method causes the virtual machine to allocate an | |
| 12997 Object visible to Java programming language code and the | |
| 12998 allocation is not detectable by other intrumentation mechanisms. | |
| 12999 Generally object allocation should be detected by instrumenting | |
| 13000 the bytecodes of allocating methods. | |
| 13001 Object allocation generated in native code by JNI function | |
| 13002 calls should be detected using | |
| 13003 <internallink id="jniIntercept">JNI function interception</internallink>. | |
| 13004 Some methods might not have associated bytecodes and are not | |
| 13005 native methods, they instead are executed directly by the | |
| 13006 VM. These methods should send this event. | |
| 13007 Virtual machines which are incapable of bytecode instrumentation | |
| 13008 for some or all of their methods can send this event. | |
| 13009 <p/> | |
| 13010 Typical examples where this event might be sent: | |
| 13011 <ul> | |
| 13012 <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li> | |
| 13013 <li>Methods not represented by bytecodes -- for example, VM intrinsics and | |
| 13014 J2ME preloaded classes</li> | |
| 13015 </ul> | |
| 13016 Cases where this event would not be generated: | |
| 13017 <ul> | |
| 13018 <li>Allocation due to bytecodes -- for example, the <code>new</code> | |
| 13019 and <code>newarray</code> VM instructions</li> | |
| 13020 <li>Allocation due to JNI function calls -- for example, | |
| 13021 <code>AllocObject</code></li> | |
| 13022 <li>Allocations during VM initialization</li> | |
| 13023 <li>VM internal objects</li> | |
| 13024 </ul> | |
| 13025 </description> | |
| 13026 <origin>new</origin> | |
| 13027 <capabilities> | |
| 13028 <required id="can_generate_vm_object_alloc_events"></required> | |
| 13029 </capabilities> | |
| 13030 <parameters> | |
| 13031 <param id="jni_env"> | |
| 13032 <outptr> | |
| 13033 <struct>JNIEnv</struct> | |
| 13034 </outptr> | |
| 13035 <description> | |
| 13036 The JNI environment of the event (current) thread | |
| 13037 </description> | |
| 13038 </param> | |
| 13039 <param id="thread"> | |
| 13040 <jthread/> | |
| 13041 <description> | |
| 13042 Thread allocating the object. | |
| 13043 </description> | |
| 13044 </param> | |
| 13045 <param id="object"> | |
| 13046 <jobject/> | |
| 13047 <description> | |
| 13048 JNI local reference to the object that was allocated | |
| 13049 </description> | |
| 13050 </param> | |
| 13051 <param id="object_klass"> | |
| 13052 <jclass/> | |
| 13053 <description> | |
| 13054 JNI local reference to the class of the object | |
| 13055 </description> | |
| 13056 </param> | |
| 13057 <param id="size"> | |
| 13058 <jlong/> | |
| 13059 <description> | |
| 13060 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 13061 </description> | |
| 13062 </param> | |
| 13063 </parameters> | |
| 13064 </event> | |
| 13065 | |
| 13066 <event label="Object Free" | |
| 13067 id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83"> | |
| 13068 <description> | |
| 13069 An Object Free event is sent when the garbage collector frees an object. | |
| 13070 Events are only sent for tagged objects--see | |
| 13071 <internallink id="Heap">heap functions</internallink>. | |
| 13072 <p/> | |
| 13073 The event handler must not use JNI functions and | |
| 13074 must not use <jvmti/> functions except those which | |
| 13075 specifically allow such use (see the raw monitor, memory management, | |
| 13076 and environment local storage functions). | |
| 13077 </description> | |
| 13078 <origin>new</origin> | |
| 13079 <capabilities> | |
| 13080 <required id="can_generate_object_free_events"></required> | |
| 13081 </capabilities> | |
| 13082 <parameters> | |
| 13083 <param id="tag"> | |
| 13084 <jlong/> | |
| 13085 <description> | |
| 13086 The freed object's tag | |
| 13087 </description> | |
| 13088 </param> | |
| 13089 </parameters> | |
| 13090 </event> | |
| 13091 | |
| 13092 <event label="Garbage Collection Start" | |
| 13093 id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81"> | |
| 13094 <description> | |
|
2125
7246a374a9f2
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
2100
diff
changeset
|
13095 A Garbage Collection Start event is sent when a |
|
7246a374a9f2
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
2100
diff
changeset
|
13096 garbage collection pause begins. |
| 0 | 13097 Only stop-the-world collections are reported--that is, collections during |
| 13098 which all threads cease to modify the state of the Java virtual machine. | |
| 13099 This means that some collectors will never generate these events. | |
| 13100 This event is sent while the VM is still stopped, thus | |
| 13101 the event handler must not use JNI functions and | |
| 13102 must not use <jvmti/> functions except those which | |
| 13103 specifically allow such use (see the raw monitor, memory management, | |
| 13104 and environment local storage functions). | |
| 13105 <p/> | |
| 13106 This event is always sent as a matched pair with | |
| 13107 <eventlink id="GarbageCollectionFinish"/> | |
| 13108 (assuming both events are enabled) and no garbage collection | |
| 13109 events will occur between them. | |
| 13110 </description> | |
| 13111 <origin>new</origin> | |
| 13112 <capabilities> | |
| 13113 <required id="can_generate_garbage_collection_events"></required> | |
| 13114 </capabilities> | |
| 13115 <parameters> | |
| 13116 </parameters> | |
| 13117 </event> | |
| 13118 | |
| 13119 <event label="Garbage Collection Finish" | |
| 13120 id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82"> | |
| 13121 <description> | |
|
2125
7246a374a9f2
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
2100
diff
changeset
|
13122 A Garbage Collection Finish event is sent when a |
|
7246a374a9f2
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
2100
diff
changeset
|
13123 garbage collection pause ends. |
| 0 | 13124 This event is sent while the VM is still stopped, thus |
| 13125 the event handler must not use JNI functions and | |
| 13126 must not use <jvmti/> functions except those which | |
| 13127 specifically allow such use (see the raw monitor, memory management, | |
| 13128 and environment local storage functions). | |
| 13129 <p/> | |
| 13130 Some agents may need to do post garbage collection operations that | |
| 13131 require the use of the disallowed <jvmti/> or JNI functions. For these | |
| 13132 cases an agent thread can be created which waits on a raw monitor, | |
| 13133 and the handler for the Garbage Collection Finish event simply | |
| 13134 notifies the raw monitor | |
| 13135 <p/> | |
| 13136 This event is always sent as a matched pair with | |
| 13137 <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled). | |
| 13138 <issue> | |
| 13139 The most important use of this event is to provide timing information, | |
| 13140 and thus additional information is not required. However, | |
| 13141 information about the collection which is "free" should be included - | |
| 13142 what that information is needs to be determined. | |
| 13143 </issue> | |
| 13144 </description> | |
| 13145 <origin>new</origin> | |
| 13146 <capabilities> | |
| 13147 <required id="can_generate_garbage_collection_events"></required> | |
| 13148 </capabilities> | |
| 13149 <parameters> | |
| 13150 </parameters> | |
| 13151 </event> | |
| 13152 | |
| 13153 <elide> | |
| 13154 <event label="Verbose Output" phase="any" | |
| 13155 id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85"> | |
| 13156 <description> | |
| 13157 Send verbose messages as strings. | |
| 13158 <issue> | |
| 13159 This format is extremely fragile, as it can change with each | |
| 13160 platform, collector and version. Alternatives include: | |
| 13161 <ul> | |
| 13162 <li>building off Java programming language M and M APIs</li> | |
| 13163 <li>XML</li> | |
| 13164 <li>key/value pairs</li> | |
| 13165 <li>removing it</li> | |
| 13166 </ul> | |
| 13167 </issue> | |
| 13168 <issue> | |
| 13169 Though this seemed trivial to implement. | |
| 13170 In the RI it appears this will be quite complex. | |
| 13171 </issue> | |
| 13172 </description> | |
| 13173 <origin>new</origin> | |
| 13174 <capabilities> | |
| 13175 </capabilities> | |
| 13176 <parameters> | |
| 13177 <param id="flag"> | |
| 13178 <enum>jvmtiVerboseFlag</enum> | |
| 13179 <description> | |
| 13180 Which verbose output is being sent. | |
| 13181 </description> | |
| 13182 </param> | |
| 13183 <param id="message"> | |
| 13184 <vmbuf><char/></vmbuf> | |
| 13185 <description> | |
| 13186 Message text, encoded as a | |
| 13187 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 13188 </description> | |
| 13189 </param> | |
| 13190 </parameters> | |
| 13191 </event> | |
| 13192 </elide> | |
| 13193 | |
| 13194 </eventsection> | |
| 13195 | |
| 13196 <datasection> | |
| 13197 <intro> | |
| 13198 <jvmti/> extends the data types defined by JNI. | |
| 13199 </intro> | |
| 13200 <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface"> | |
| 13201 <basetype id="jboolean"> | |
| 13202 <description> | |
| 13203 Holds a Java programming language <code>boolean</code>. | |
| 13204 Unsigned 8 bits. | |
| 13205 </description> | |
| 13206 </basetype> | |
| 6919 | 13207 <basetype id="jchar"> |
| 13208 <description> | |
| 13209 Holds a Java programming language <code>char</code>. | |
| 13210 Unsigned 16 bits. | |
| 13211 </description> | |
| 13212 </basetype> | |
| 0 | 13213 <basetype id="jint"> |
| 13214 <description> | |
| 13215 Holds a Java programming language <code>int</code>. | |
| 13216 Signed 32 bits. | |
| 13217 </description> | |
| 13218 </basetype> | |
| 13219 <basetype id="jlong"> | |
| 13220 <description> | |
| 13221 Holds a Java programming language <code>long</code>. | |
| 13222 Signed 64 bits. | |
| 13223 </description> | |
| 13224 </basetype> | |
| 13225 <basetype id="jfloat"> | |
| 13226 <description> | |
| 13227 Holds a Java programming language <code>float</code>. | |
| 13228 32 bits. | |
| 13229 </description> | |
| 13230 </basetype> | |
| 13231 <basetype id="jdouble"> | |
| 13232 <description> | |
| 13233 Holds a Java programming language <code>double</code>. | |
| 13234 64 bits. | |
| 13235 </description> | |
| 13236 </basetype> | |
| 13237 <basetype id="jobject"> | |
| 13238 <description> | |
| 13239 Holds a Java programming language object. | |
| 13240 </description> | |
| 13241 </basetype> | |
| 13242 <basetype id="jclass"> | |
| 13243 <description> | |
| 13244 Holds a Java programming language class. | |
| 13245 </description> | |
| 13246 </basetype> | |
| 13247 <basetype id="jvalue"> | |
| 13248 <description> | |
| 13249 Is a union of all primitive types and <code>jobject</code>. Thus, holds any Java | |
| 13250 programming language value. | |
| 13251 </description> | |
| 13252 </basetype> | |
| 13253 <basetype id="jfieldID"> | |
| 13254 <description> | |
| 13255 Identifies a Java programming language field. | |
| 13256 <code>jfieldID</code>s returned by <jvmti/> functions and events may be | |
| 13257 safely stored. | |
| 13258 </description> | |
| 13259 </basetype> | |
| 13260 <basetype id="jmethodID"> | |
| 13261 <description> | |
| 13262 Identifies a Java programming language method, initializer, or constructor. | |
| 13263 <code>jmethodID</code>s returned by <jvmti/> functions and events may be | |
| 13264 safely stored. However, if the class is unloaded, they become invalid | |
| 13265 and must not be used. | |
| 13266 </description> | |
| 13267 </basetype> | |
| 13268 <basetype id="JNIEnv"> | |
| 13269 <description> | |
| 13270 Pointer to the JNI function table. Pointer to this (<code>JNIEnv *</code>) | |
| 13271 is a JNI environment. | |
| 13272 </description> | |
| 13273 </basetype> | |
| 13274 </basetypes> | |
| 13275 | |
| 13276 <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types"> | |
| 13277 <basetype id="jvmtiEnv"> | |
| 13278 <description> | |
| 13279 The <jvmti/> <internallink id="environments">environment</internallink> pointer. | |
| 13280 See the <internallink id="FunctionSection">Function Section</internallink>. | |
| 13281 <code>jvmtiEnv</code> points to the | |
| 13282 <internallink id="FunctionTable">function table</internallink> pointer. | |
| 13283 </description> | |
| 13284 </basetype> | |
| 13285 <basetype id="jthread"> | |
| 13286 <definition>typedef jobject jthread;</definition> | |
| 13287 <description> | |
| 13288 Subtype of <datalink id="jobject"></datalink> that holds a thread. | |
| 13289 </description> | |
| 13290 </basetype> | |
| 13291 <basetype id="jthreadGroup"> | |
| 13292 <definition>typedef jobject jthreadGroup;</definition> | |
| 13293 <description> | |
| 13294 Subtype of <datalink id="jobject"></datalink> that holds a thread group. | |
| 13295 </description> | |
| 13296 </basetype> | |
| 13297 <basetype id="jlocation"> | |
| 13298 <definition>typedef jlong jlocation;</definition> | |
| 13299 <description> | |
| 13300 A 64 bit value, representing a monotonically increasing | |
| 13301 executable position within a method. | |
| 13302 <code>-1</code> indicates a native method. | |
| 13303 See <functionlink id="GetJLocationFormat"></functionlink> for the format on a | |
| 13304 given VM. | |
| 13305 </description> | |
| 13306 </basetype> | |
| 13307 <basetype id="jrawMonitorID"> | |
| 13308 <definition>struct _jrawMonitorID; | |
| 13309 typedef struct _jrawMonitorID *jrawMonitorID;</definition> | |
| 13310 <description> | |
| 13311 A raw monitor. | |
| 13312 </description> | |
| 13313 </basetype> | |
| 13314 <basetype id="jvmtiError"> | |
| 13315 <description> | |
| 13316 Holds an error return code. | |
| 13317 See the <internallink id="ErrorSection">Error section</internallink> for possible values. | |
| 13318 <example> | |
| 13319 typedef enum { | |
| 13320 JVMTI_ERROR_NONE = 0, | |
| 13321 JVMTI_ERROR_INVALID_THREAD = 10, | |
| 13322 ... | |
| 13323 } jvmtiError; | |
| 13324 </example> | |
| 13325 </description> | |
| 13326 </basetype> | |
| 13327 <basetype id="jvmtiEvent"> | |
| 13328 <description> | |
| 13329 An identifier for an event type. | |
| 13330 See the <internallink id="EventSection">Event section</internallink> for possible values. | |
| 13331 It is guaranteed that future versions of this specification will | |
| 13332 never assign zero as an event type identifier. | |
| 13333 <example> | |
| 13334 typedef enum { | |
| 13335 JVMTI_EVENT_SINGLE_STEP = 1, | |
| 13336 JVMTI_EVENT_BREAKPOINT = 2, | |
| 13337 ... | |
| 13338 } jvmtiEvent; | |
| 13339 </example> | |
| 13340 </description> | |
| 13341 </basetype> | |
| 13342 <basetype id="jvmtiEventCallbacks"> | |
| 13343 <description> | |
| 13344 The callbacks used for events. | |
| 13345 <example> | |
| 13346 typedef struct { | |
| 13347 jvmtiEventVMInit VMInit; | |
| 13348 jvmtiEventVMDeath VMDeath; | |
| 13349 ... | |
| 13350 } jvmtiEventCallbacks; | |
| 13351 </example> | |
| 13352 See <internallink id="jvmtiEventCallbacks">event callbacks</internallink> | |
| 13353 for the complete structure. | |
| 13354 <p/> | |
| 13355 Where, for example, the VM initialization callback is defined: | |
| 13356 <example> | |
| 13357 typedef void (JNICALL *jvmtiEventVMInit) | |
| 13358 (jvmtiEnv *jvmti_env, | |
| 13359 JNIEnv* jni_env, | |
| 13360 jthread thread); | |
| 13361 </example> | |
| 13362 See the individual events for the callback function definition. | |
| 13363 </description> | |
| 13364 </basetype> | |
| 13365 <basetype id="jniNativeInterface"> | |
| 13366 <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition> | |
| 13367 <description> | |
| 13368 Typedef for the JNI function table <code>JNINativeInterface</code> | |
| 13369 defined in the | |
| 6919 | 13370 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp23720">JNI Specification</externallink>. |
| 0 | 13371 The JNI reference implementation defines this with an underscore. |
| 13372 </description> | |
| 13373 </basetype> | |
| 13374 </basetypes> | |
| 13375 | |
| 13376 </datasection> | |
| 13377 | |
| 13378 <issuessection label="Issues"> | |
| 13379 <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic"> | |
| 13380 JVMDI requires that the agent suspend threads before calling | |
| 13381 certain sensitive functions. JVMPI requires garbage collection to be | |
| 13382 disabled before calling certain sensitive functions. | |
| 13383 It was suggested that rather than have this requirement, that | |
| 13384 VM place itself in a suitable state before performing an | |
| 13385 operation. This makes considerable sense since each VM | |
| 13386 knows its requirements and can most easily arrange a | |
| 13387 safe state. | |
| 13388 <p/> | |
| 13389 The ability to externally suspend/resume threads will, of | |
| 13390 course, remain. The ability to enable/disable garbage collection will not. | |
| 13391 <p/> | |
| 13392 This issue is resolved--suspend will not | |
| 13393 be required. The spec has been updated to reflect this. | |
| 13394 </intro> | |
| 13395 | |
| 13396 <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling"> | |
| 13397 There are a variety of approaches to sampling call stacks. | |
| 13398 The biggest bifurcation is between VM controlled and agent | |
| 13399 controlled. | |
| 13400 <p/> | |
| 13401 This issue is resolved--agent controlled | |
| 13402 sampling will be the approach. | |
| 13403 </intro> | |
| 13404 | |
| 13405 <intro id="threadRepresentation" label="Resolved Issue: Thread Representation"> | |
| 13406 JVMDI represents threads as jthread. JVMPI primarily | |
| 13407 uses JNIEnv* to represent threads. | |
| 13408 <p/> | |
| 13409 The Expert Group has chosen jthread as the representation | |
| 13410 for threads in <jvmti/>. | |
| 13411 JNIEnv* is sent by | |
| 13412 events since it is needed to JNI functions. JNIEnv, per the | |
| 13413 JNI spec, are not supposed to be used outside their thread. | |
| 13414 </intro> | |
| 13415 | |
| 13416 <intro id="design" label="Resolved Issue: Method Representation"> | |
| 13417 The JNI spec allows an implementation to depend on jclass/jmethodID | |
| 13418 pairs, rather than simply a jmethodID, to reference a method. | |
| 13419 JVMDI, for consistency, choose the same representation. | |
| 13420 JVMPI, however, specifies that a jmethodID alone maps to a | |
| 13421 method. Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store | |
| 13422 pointers in jmethodIDs, and as a result, a jmethodID is sufficient. | |
| 13423 In fact, any JVM implementation that supports JVMPI must have | |
| 13424 such a representation. | |
| 13425 <jvmti/> will use jmethodID as a unique representation of a method | |
| 13426 (no jclass is used). | |
| 13427 There should be efficiency gains, particularly in | |
| 13428 functionality like stack dumping, to this representation. | |
| 13429 <p/> | |
| 13430 Note that fields were not used in JVMPI and that the access profile | |
| 13431 of fields differs from methods--for implementation efficiency | |
| 13432 reasons, a jclass/jfieldID pair will still be needed for field | |
| 13433 reference. | |
| 13434 </intro> | |
| 13435 | |
| 13436 <intro id="localReferenceIssue" label="Resolved Issue: Local References"> | |
| 13437 Functions return local references. | |
| 13438 </intro> | |
| 13439 | |
| 13440 <intro id="frameRep" label="Resolved Issue: Representation of frames"> | |
| 13441 In JVMDI, a frame ID is used to represent a frame. Problem with this | |
| 13442 is that a VM must track when a frame becomes invalid, a far better | |
| 13443 approach, and the one used in <jvmti/>, is to reference frames by depth. | |
| 13444 </intro> | |
| 13445 | |
| 13446 <intro id="requiredCapabilities" label="Issue: Required Capabilities"> | |
| 13447 Currently, having a required capabilities means that the functionality | |
| 13448 is optional. Capabilities are useful even for required functionality | |
| 13449 since they can inform the VM is needed set-up. Thus, there should be | |
| 13450 a set of capabilities that a conformant implementation must provide | |
| 13451 (if requested during Agent_OnLoad). | |
| 13452 </intro> | |
| 13453 | |
| 13454 <intro id="taghint" label="Proposal: add tag hint function"> | |
| 13455 A hint of the percentage of objects that will be tagged would | |
| 13456 help the VM pick a good implementation. | |
| 13457 </intro> | |
| 13458 | |
| 13459 <intro id="moreMonitorQueries" label="Request: More Monitor Quires"> | |
| 13460 How difficult or easy would be to extend the monitor_info category to include | |
| 13461 <pre> | |
| 13462 - current number of monitors | |
| 13463 - enumeration of monitors | |
| 13464 - enumeration of threads waiting on a given monitor | |
| 13465 </pre> | |
| 13466 The reason for my question is the fact that current get_monitor_info support | |
| 13467 requires the agent to specify a given thread to get the info which is probably | |
| 13468 OK in the profiling/debugging space, while in the monitoring space the agent | |
| 13469 could be watching the monitor list and then decide which thread to ask for | |
| 13470 the info. You might ask why is this important for monitoring .... I think it | |
| 13471 can aid in the detection/prediction of application contention caused by hot-locks. | |
| 13472 </intro> | |
| 13473 </issuessection> | |
| 13474 | |
| 13475 <changehistory id="ChangeHistory" update="09/05/07"> | |
| 13476 <intro> | |
| 13477 The <jvmti/> specification is an evolving document with major, minor, | |
| 13478 and micro version numbers. | |
| 13479 A released version of the specification is uniquely identified | |
| 13480 by its major and minor version. | |
| 13481 The functions, events, and capabilities in this specification | |
| 13482 indicate a "Since" value which is the major and minor version in | |
| 13483 which it was introduced. | |
| 13484 The version of the specification implemented by the VM can | |
| 13485 be retrieved at runtime with the <functionlink id="GetVersionNumber"/> | |
| 13486 function. | |
| 13487 </intro> | |
| 13488 <change date="14 Nov 2002"> | |
| 13489 Converted to XML document. | |
| 13490 </change> | |
| 13491 <change date="14 Nov 2002"> | |
| 13492 Elided heap dump functions (for now) since what was there | |
| 13493 was wrong. | |
| 13494 </change> | |
| 13495 <change date="18 Nov 2002"> | |
| 13496 Added detail throughout. | |
| 13497 </change> | |
| 13498 <change date="18 Nov 2002"> | |
| 13499 Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE. | |
| 13500 </change> | |
| 13501 <change date="19 Nov 2002"> | |
| 13502 Added AsyncGetStackTrace. | |
| 13503 </change> | |
| 13504 <change date="19 Nov 2002"> | |
| 13505 Added jframeID return to GetStackTrace. | |
| 13506 </change> | |
| 13507 <change date="19 Nov 2002"> | |
| 13508 Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there | |
| 13509 since they are redundant with GetStackTrace. | |
| 13510 </change> | |
| 13511 <change date="19 Nov 2002"> | |
| 13512 Elided ClearAllBreakpoints since it has always been redundant. | |
| 13513 </change> | |
| 13514 <change date="19 Nov 2002"> | |
| 13515 Added GetSystemProperties. | |
| 13516 </change> | |
| 13517 <change date="19 Nov 2002"> | |
| 13518 Changed the thread local storage functions to use jthread. | |
| 13519 </change> | |
| 13520 <change date="20 Nov 2002"> | |
| 13521 Added GetJLocationFormat. | |
| 13522 </change> | |
| 13523 <change date="22 Nov 2002"> | |
| 13524 Added events and introductory text. | |
| 13525 </change> | |
| 13526 <change date="22 Nov 2002"> | |
| 13527 Cross reference type and constant definitions. | |
| 13528 </change> | |
| 13529 <change date="24 Nov 2002"> | |
| 13530 Added DTD. | |
| 13531 </change> | |
| 13532 <change date="24 Nov 2002"> | |
| 13533 Added capabilities function section. | |
| 13534 </change> | |
| 13535 <change date="29 Nov 2002"> | |
| 13536 Assign capabilities to each function and event. | |
| 13537 </change> | |
| 13538 <change date="29 Nov 2002"> | |
| 13539 Add <internallink id="jniIntercept">JNI interception functions</internallink>. | |
| 13540 </change> | |
| 13541 <change date="30 Nov 2002"> | |
| 13542 Auto generate SetEventNotificationMode capabilities. | |
| 13543 </change> | |
| 13544 <change date="30 Nov 2002"> | |
| 13545 Add <eventlink id="VMObjectAlloc"></eventlink> event. | |
| 13546 </change> | |
| 13547 <change date="30 Nov 2002"> | |
| 13548 Add <eventlink id="DynamicCodeGenerated"></eventlink> event. | |
| 13549 </change> | |
| 13550 <change date="30 Nov 2002"> | |
| 13551 Add const to declarations. | |
| 13552 </change> | |
| 13553 <change date="30 Nov 2002"> | |
| 13554 Change method exit and frame pop to send on exception. | |
| 13555 </change> | |
| 13556 <change date="1 Dec 2002"> | |
| 13557 Add ForceGarbageCollection. | |
| 13558 </change> | |
| 13559 <change date="2 Dec 2002"> | |
| 13560 Redo Xrun section; clarify GetStackTrace and add example; | |
| 13561 Fix width problems; use "agent" consistently. | |
| 13562 </change> | |
| 13563 <change date="8 Dec 2002"> | |
| 13564 Remove previous start-up intro. | |
| 13565 Add <internallink id="environments"><jvmti/> Environments</internallink> | |
| 13566 section. | |
| 13567 </change> | |
| 13568 <change date="8 Dec 2002"> | |
| 13569 Add <functionlink id="DisposeEnvironment"></functionlink>. | |
| 13570 </change> | |
| 13571 <change date="9 Dec 2002"> | |
| 13572 Numerous minor updates. | |
| 13573 </change> | |
| 13574 <change date="15 Dec 2002"> | |
| 13575 Add heap profiling functions added: | |
| 13576 get/set annotation, iterate live objects/heap. | |
| 13577 Add heap profiling functions place holder added: | |
| 13578 heap roots. | |
| 13579 Heap profiling event added: object free. | |
| 13580 Heap profiling event redesigned: vm object allocation. | |
| 13581 Heap profiling event placeholders added: garbage collection start/finish. | |
| 13582 Native method bind event added. | |
| 13583 </change> | |
| 13584 <change date="19 Dec 2002"> | |
| 13585 Revamp suspend/resume functions. | |
| 13586 Add origin information with jvmdi tag. | |
| 13587 Misc fixes. | |
| 13588 </change> | |
| 13589 <change date="24 Dec 2002"> | |
| 13590 Add semantics to types. | |
| 13591 </change> | |
| 13592 <change date="27 Dec 2002"> | |
| 13593 Add local reference section. | |
| 13594 Autogenerate parameter descriptions from types. | |
| 13595 </change> | |
| 13596 <change date="28 Dec 2002"> | |
| 13597 Document that RunAgentThread sends threadStart. | |
| 13598 </change> | |
| 13599 <change date="29 Dec 2002"> | |
| 13600 Remove redundant local ref and dealloc warning. | |
| 13601 Convert GetRawMonitorName to allocated buffer. | |
| 13602 Add GenerateEvents. | |
| 13603 </change> | |
| 13604 <change date="30 Dec 2002"> | |
| 13605 Make raw monitors a type and rename to "jrawMonitorID". | |
| 13606 </change> | |
| 13607 <change date="1 Jan 2003"> | |
| 13608 Include origin information. | |
| 13609 Clean-up JVMDI issue references. | |
| 13610 Remove Deallocate warnings which are now automatically generated. | |
| 13611 </change> | |
| 13612 <change date="2 Jan 2003"> | |
| 13613 Fix representation issues for jthread. | |
| 13614 </change> | |
| 13615 <change date="3 Jan 2003"> | |
| 13616 Make capabilities buffered out to 64 bits - and do it automatically. | |
| 13617 </change> | |
| 13618 <change date="4 Jan 2003"> | |
| 13619 Make constants which are enumeration into enum types. | |
| 13620 Parameters now of enum type. | |
| 13621 Clean-up and index type section. | |
| 13622 Replace remaining datadef entities with callback. | |
| 13623 </change> | |
| 13624 <change date="7 Jan 2003"> | |
| 13625 Correct GenerateEvents description. | |
| 13626 More internal semantics work. | |
| 13627 </change> | |
| 13628 <change date="9 Jan 2003"> | |
| 13629 Replace previous GetSystemProperties with two functions | |
| 13630 which use allocated information instead fixed. | |
| 13631 Add SetSystemProperty. | |
| 13632 More internal semantics work. | |
| 13633 </change> | |
| 13634 <change date="12 Jan 2003"> | |
| 13635 Add varargs to end of SetEventNotificationMode. | |
| 13636 </change> | |
| 13637 <change date="20 Jan 2003"> | |
| 13638 Finish fixing spec to reflect that alloc sizes are jlong. | |
| 13639 </change> | |
| 13640 <change date="22 Jan 2003"> | |
| 13641 Allow NULL as RunAgentThread arg. | |
| 13642 </change> | |
| 13643 <change date="22 Jan 2003"> | |
| 13644 Fixed names to standardized naming convention | |
| 13645 Removed AsyncGetStackTrace. | |
| 13646 </change> | |
| 13647 <change date="29 Jan 2003"> | |
| 13648 Since we are using jthread, removed GetThread. | |
| 13649 </change> | |
| 13650 <change date="31 Jan 2003"> | |
| 13651 Change GetFieldName to allow NULLs like GetMethodName. | |
| 13652 </change> | |
| 13653 <change date="29 Feb 2003" version="v40"> | |
| 13654 Rewrite the introductory text, adding sections on | |
| 13655 start-up, environments and bytecode instrumentation. | |
| 13656 Change the command line arguments per EG discussions. | |
| 13657 Add an introduction to the capabilities section. | |
| 13658 Add the extension mechanism category and functions. | |
| 13659 Mark for deletion, but clarified anyhow, SuspendAllThreads. | |
| 13660 Rename IterateOverLiveObjects to IterateOverReachableObjects and | |
| 13661 change the text accordingly. | |
| 13662 Clarify IterateOverHeap. | |
| 13663 Clarify CompiledMethodLoad. | |
| 13664 Discuss prerequisite state for Calling Functions. | |
| 13665 Clarify SetAllocationHooks. | |
| 13666 Added issues ("To be resolved:") through-out. | |
| 13667 And so on... | |
| 13668 </change> | |
| 13669 <change date="6 Mar 2003" version="v41"> | |
| 13670 Remove struct from the call to GetOwnedMonitorInfo. | |
| 13671 Automatically generate most error documentation, remove | |
| 13672 (rather broken) hand written error doc. | |
| 13673 Better describe capability use (empty initial set). | |
| 13674 Add min value to jint params. | |
| 13675 Remove the capability can_access_thread_local_storage. | |
| 13676 Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY; | |
| 13677 same for *NOT_IMPLEMENTED. | |
| 13678 Description fixes. | |
| 13679 </change> | |
| 13680 <change date="8 Mar 2003" version="v42"> | |
| 13681 Rename GetClassSignature to GetClassName. | |
| 13682 Rename IterateOverClassObjects to IterateOverInstancesOfClass. | |
| 13683 Remove GetMaxStack (operand stack isn't used in <jvmti/>). | |
| 13684 Description fixes: define launch-time, remove native frame pop | |
| 13685 from PopFrame, and assorted clarifications. | |
| 13686 </change> | |
| 13687 <change date="8 Mar 2003" version="v43"> | |
| 13688 Fix minor editing problem. | |
| 13689 </change> | |
| 13690 <change date="10 Mar 2003" version="v44"> | |
| 13691 Add phase information. | |
| 13692 Remap (compact) event numbers. | |
| 13693 </change> | |
| 13694 <change date="11 Mar 2003" version="v45"> | |
| 13695 More phase information - allow "any". | |
| 13696 Elide raw monitor queries and events. | |
| 13697 Minor description fixes. | |
| 13698 </change> | |
| 13699 <change date="12 Mar 2003" version="v46"> | |
| 13700 Add GetPhase. | |
| 13701 Use "phase" through document. | |
| 13702 Elide GetRawMonitorName. | |
| 13703 Elide GetObjectMonitors. | |
| 13704 </change> | |
| 13705 <change date="12 Mar 2003" version="v47"> | |
| 13706 Fixes from link, XML, and spell checking. | |
| 13707 Auto-generate the callback structure. | |
| 13708 </change> | |
| 13709 <change date="13 Mar 2003" version="v48"> | |
| 13710 One character XML fix. | |
| 13711 </change> | |
| 13712 <change date="13 Mar 2003" version="v49"> | |
| 13713 Change function parameter names to be consistent with | |
| 13714 event parameters (fooBarBaz becomes foo_bar_baz). | |
| 13715 </change> | |
| 13716 <change date="14 Mar 2003" version="v50"> | |
| 13717 Fix broken link. Fix thread markers. | |
| 13718 </change> | |
| 13719 <change date="14 Mar 2003" version="v51"> | |
| 13720 Change constants so they are under 128 to workaround | |
| 13721 compiler problems. | |
| 13722 </change> | |
| 13723 <change date="23 Mar 2003" version="v52"> | |
| 13724 Overhaul capabilities. Separate GetStackTrace into | |
| 13725 GetStackTrace and GetStackFrames. | |
| 13726 </change> | |
| 13727 <change date="8 Apr 2003" version="v54"> | |
| 13728 Use depth instead of jframeID to reference frames. | |
| 13729 Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames. | |
| 13730 Remove frame arg from events. | |
| 13731 </change> | |
| 13732 <change date="9 Apr 2003" version="v55"> | |
| 13733 Remove GetObjectWithAnnotation since tests show bufferred approach more efficient. | |
| 13734 Add missing annotation_count to GetObjectsWithAnnotations | |
| 13735 </change> | |
| 13736 <change date="10 Apr 2003" version="v56"> | |
| 13737 Remove confusing parenthetical statement in GetObjectsWithAnnotations | |
| 13738 </change> | |
| 13739 <change date="13 Apr 2003" version="v58"> | |
| 13740 Replace jclass/jmethodID representation of method with simply jmethodID; | |
| 13741 Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate. | |
| 13742 Replace can_access_frames with can_access_local_variables; remove from purely stack access. | |
| 13743 Use can_get_synthetic_attribute; fix description. | |
| 13744 Clarify that zero length arrays must be deallocated. | |
| 13745 Clarify RelinquishCapabilities. | |
| 13746 Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE. | |
| 13747 </change> | |
| 13748 <change date="27 Apr 2003" version="v59"> | |
| 13749 Remove lingering indirect references to OBSOLETE_METHOD_ID. | |
| 13750 </change> | |
| 13751 <change date="4 May 2003" version="v60"> | |
| 13752 Allow DestroyRawMonitor during OnLoad. | |
| 13753 </change> | |
| 13754 <change date="7 May 2003" version="v61"> | |
| 13755 Added not monitor owner error return to DestroyRawMonitor. | |
| 13756 </change> | |
| 13757 <change date="13 May 2003" version="v62"> | |
| 13758 Clarify semantics of raw monitors. | |
| 13759 Change flags on <code>GetThreadStatus</code>. | |
| 13760 <code>GetClassLoader</code> return NULL for the bootstrap class loader. | |
| 13761 Add <code>GetClassName</code> issue. | |
| 13762 Define local variable signature. | |
| 13763 Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>. | |
| 13764 Remove over specification in <code>GetObjectsWithAnnotations</code>. | |
| 13765 Elide <code>SetAllocationHooks</code>. | |
| 13766 Elide <code>SuspendAllThreads</code>. | |
| 13767 </change> | |
| 13768 <change date="14 May 2003" version="v63"> | |
| 13769 Define the data type <code>jvmtiEventCallbacks</code>. | |
| 13770 Zero length allocations return NULL. | |
| 13771 Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>. | |
| 13772 Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED. | |
| 13773 </change> | |
| 13774 <change date="15 May 2003" version="v64"> | |
| 13775 Better wording, per review. | |
| 13776 </change> | |
| 13777 <change date="15 May 2003" version="v65"> | |
| 13778 First Alpha. | |
| 13779 Make jmethodID and jfieldID unique, jclass not used. | |
| 13780 </change> | |
| 13781 <change date="27 May 2003" version="v66"> | |
| 13782 Fix minor XSLT errors. | |
| 13783 </change> | |
| 13784 <change date="13 June 2003" version="v67"> | |
| 13785 Undo making jfieldID unique (jmethodID still is). | |
| 13786 </change> | |
| 13787 <change date="17 June 2003" version="v68"> | |
| 13788 Changes per June 11th Expert Group meeting -- | |
| 13789 Overhaul Heap functionality: single callback, | |
| 13790 remove GetHeapRoots, add reachable iterators, | |
| 13791 and rename "annotation" to "tag". | |
| 13792 NULL thread parameter on most functions is current | |
| 13793 thread. | |
| 13794 Add timers. | |
| 13795 Remove ForceExit. | |
| 13796 Add GetEnvironmentLocalStorage. | |
| 13797 Add verbose flag and event. | |
| 13798 Add AddToBootstrapClassLoaderSearch. | |
| 13799 Update ClassFileLoadHook. | |
| 13800 </change> | |
| 13801 <change date="18 June 2003" version="v69"> | |
| 13802 Clean up issues sections. | |
| 13803 Rename GetClassName back to GetClassSignature and | |
| 13804 fix description. | |
| 13805 Add generic signature to GetClassSignature, | |
| 13806 GetFieldSignature, GetMethodSignature, and | |
| 13807 GetLocalVariableTable. | |
| 13808 Elide EstimateCostOfCapabilities. | |
| 13809 Clarify that the system property functions operate | |
| 13810 on the VM view of system properties. | |
| 13811 Clarify Agent_OnLoad. | |
| 13812 Remove "const" from JNIEnv* in events. | |
| 13813 Add metadata accessors. | |
| 13814 </change> | |
| 13815 <change date="18 June 2003" version="v70"> | |
| 13816 Add start_depth to GetStackTrace. | |
| 13817 Move system properties to a new category. | |
| 13818 Add GetObjectSize. | |
| 13819 Remove "X" from command line flags. | |
| 13820 XML, HTML, and spell check corrections. | |
| 13821 </change> | |
| 13822 <change date="19 June 2003" version="v71"> | |
| 13823 Fix JVMTI_HEAP_ROOT_THREAD to be 6. | |
| 13824 Make each synopsis match the function name. | |
| 13825 Fix unclear wording. | |
| 13826 </change> | |
| 13827 <change date="26 June 2003" version="v72"> | |
| 13828 SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value | |
| 13829 to be set to NULL. | |
| 13830 NotifyFramePop, GetFrameLocationm and all the local variable operations | |
| 13831 needed to have their wording about frames fixed. | |
| 13832 Grammar and clarity need to be fixed throughout. | |
| 13833 Capitalization and puntuation need to be consistent. | |
| 13834 Need micro version number and masks for accessing major, minor, and micro. | |
| 13835 The error code lists should indicate which must be returned by | |
| 13836 an implementation. | |
| 13837 The command line properties should be visible in the properties functions. | |
| 13838 Disallow popping from the current thread. | |
| 13839 Allow implementations to return opaque frame error when they cannot pop. | |
| 13840 The NativeMethodBind event should be sent during any phase. | |
| 13841 The DynamicCodeGenerated event should be sent during any phase. | |
| 13842 The following functions should be allowed to operate before VMInit: | |
| 13843 Set/GetEnvironmentLocalStorage | |
| 13844 GetMethodDeclaringClass | |
| 13845 GetClassSignature | |
| 13846 GetClassModifiers | |
| 13847 IsInterface | |
| 13848 IsArrayClass | |
| 13849 GetMethodName | |
| 13850 GetMethodModifiers | |
| 13851 GetMaxLocals | |
| 13852 GetArgumentsSize | |
| 13853 GetLineNumberTable | |
| 13854 GetMethodLocation | |
| 13855 IsMethodNative | |
| 13856 IsMethodSynthetic. | |
| 13857 Other changes (to XSL): | |
| 13858 Argument description should show asterisk after not before pointers. | |
| 13859 NotifyFramePop, GetFrameLocationm and all the local variable operations | |
| 13860 should hsve the NO_MORE_FRAMES error added. | |
| 13861 Not alive threads should have a different error return than invalid thread. | |
| 13862 </change> | |
| 13863 <change date="7 July 2003" version="v73"> | |
| 13864 VerboseOutput event was missing message parameter. | |
| 13865 Minor fix-ups. | |
| 13866 </change> | |
| 13867 <change date="14 July 2003" version="v74"> | |
| 13868 Technical Publications Department corrections. | |
| 13869 Allow thread and environment local storage to be set to NULL. | |
| 13870 </change> | |
| 13871 <change date="23 July 2003" version="v75"> | |
| 13872 Use new Agent_OnLoad rather than overloaded JVM_OnLoad. | |
| 13873 Add JNICALL to callbacks (XSL). | |
| 13874 Document JNICALL requirement for both events and callbacks (XSL). | |
| 13875 Restrict RedefineClasses to methods and attributes. | |
| 13876 Elide the VerboseOutput event. | |
| 13877 VMObjectAlloc: restrict when event is sent and remove method parameter. | |
| 13878 Finish loose ends from Tech Pubs edit. | |
| 13879 </change> | |
| 13880 <change date="24 July 2003" version="v76"> | |
| 13881 Change ClassFileLoadHook event to send the class instead of a boolean of redefine. | |
| 13882 </change> | |
| 13883 <change date="24 July 2003" version="v77"> | |
| 13884 XML fixes. | |
| 13885 Minor text clarifications and corrections. | |
| 13886 </change> | |
| 13887 <change date="24 July 2003" version="v78"> | |
| 13888 Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>. | |
| 13889 Clarify that stack frames are JVM Spec frames. | |
| 13890 Split can_get_source_info into can_get_source_file_name, can_get_line_numbers, | |
| 13891 and can_get_source_debug_extension. | |
| 13892 PopFrame cannot have a native calling method. | |
| 13893 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
|
13894 (see <vmspec chapter="4.4"/>). |
| 0 | 13895 </change> |
| 13896 <change date="24 July 2003" version="v79"> | |
| 13897 XML and text fixes. | |
| 13898 Move stack frame description into Stack Frame category. | |
| 13899 </change> | |
| 13900 <change date="26 July 2003" version="v80"> | |
| 13901 Allow NULL (means bootstrap loader) for GetClassloaderClasses. | |
| 13902 Add new heap reference kinds for references from classes. | |
| 13903 Add timer information struct and query functions. | |
| 13904 Add AvailableProcessors. | |
| 13905 Rename GetOtherThreadCpuTime to GetThreadCpuTime. | |
| 13906 Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE | |
| 13907 to SetEventNotification mode. | |
| 13908 Add initial thread to the VM_INIT event. | |
| 13909 Remove platform assumptions from AddToBootstrapClassLoaderSearch. | |
| 13910 </change> | |
| 13911 <change date="26 July 2003" version="v81"> | |
| 13912 Grammar and clarity changes per review. | |
| 13913 </change> | |
| 13914 <change date="27 July 2003" version="v82"> | |
| 13915 More grammar and clarity changes per review. | |
| 13916 Add Agent_OnUnload. | |
| 13917 </change> | |
| 13918 <change date="28 July 2003" version="v83"> | |
| 13919 Change return type of Agent_OnUnload to void. | |
| 13920 </change> | |
| 13921 <change date="28 July 2003" version="v84"> | |
| 13922 Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT. | |
| 13923 </change> | |
| 13924 <change date="28 July 2003" version="v85"> | |
| 13925 Steal java.lang.Runtime.availableProcessors() wording for | |
| 13926 AvailableProcessors(). | |
| 13927 Guarantee that zero will never be an event ID. | |
| 13928 Remove some issues which are no longer issues. | |
| 13929 Per review, rename and more completely document the timer | |
| 13930 information functions. | |
| 13931 </change> | |
| 13932 <change date="29 July 2003" version="v86"> | |
| 13933 Non-spec visible change to XML controlled implementation: | |
| 13934 SetThreadLocalStorage must run in VM mode. | |
| 13935 </change> | |
| 13936 <change date="5 August 2003" version="0.1.87"> | |
| 13937 Add GetErrorName. | |
| 13938 Add varargs warning to jvmtiExtensionEvent. | |
| 13939 Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent. | |
| 13940 Remove unused can_get_exception_info capability. | |
| 13941 Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction. | |
| 13942 Fix jvmtiExtensionFunctionInfo.func declared type. | |
| 13943 Extension function returns error code. | |
| 13944 Use new version numbering. | |
| 13945 </change> | |
| 13946 <change date="5 August 2003" version="0.2.88"> | |
| 13947 Remove the ClassUnload event. | |
| 13948 </change> | |
| 13949 <change date="8 August 2003" version="0.2.89"> | |
| 13950 Heap reference iterator callbacks return an enum that | |
| 13951 allows outgoing object references to be ignored. | |
| 13952 Allow JNIEnv as a param type to extension events/functions. | |
| 13953 </change> | |
| 13954 <change date="15 August 2003" version="0.2.90"> | |
| 13955 Fix a typo. | |
| 13956 </change> | |
| 13957 <change date="2 September 2003" version="0.2.91"> | |
| 13958 Remove all metadata functions: GetClassMetadata, | |
| 13959 GetFieldMetadata, and GetMethodMetadata. | |
| 13960 </change> | |
| 13961 <change date="1 October 2003" version="0.2.92"> | |
| 13962 Mark the functions Allocate. Deallocate, RawMonitor*, | |
| 13963 SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage | |
| 13964 as safe for use in heap callbacks and GC events. | |
| 13965 </change> | |
| 13966 <change date="24 November 2003" version="0.2.93"> | |
| 13967 Add pass through opaque user data pointer to heap iterate | |
| 13968 functions and callbacks. | |
| 13969 In the CompiledMethodUnload event, send the code address. | |
| 13970 Add GarbageCollectionOccurred event. | |
| 13971 Add constant pool reference kind. | |
| 13972 Mark the functions CreateRawMonitor and DestroyRawMonitor | |
| 13973 as safe for use in heap callbacks and GC events. | |
| 13974 Clarify: VMDeath, GetCurrentThreadCpuTimerInfo, | |
| 13975 GetThreadCpuTimerInfo, IterateOverReachableObjects, | |
| 13976 IterateOverObjectsReachableFromObject, GetTime and | |
| 13977 JVMTI_ERROR_NULL_POINTER. | |
| 13978 Add missing errors to: GenerateEvents and | |
| 13979 AddToBootstrapClassLoaderSearch. | |
| 13980 Fix description of ClassFileLoadHook name parameter. | |
| 13981 In heap callbacks and GC/ObjectFree events, specify | |
| 13982 that only explicitly allowed functions can be called. | |
| 13983 Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime, | |
| 13984 GetTimerInfo, and GetTime during callback. | |
| 13985 Allow calling SetTag/GetTag during the onload phase. | |
| 13986 SetEventNotificationMode, add: error attempted inappropriate | |
| 13987 thread level control. | |
| 13988 Remove jvmtiExceptionHandlerEntry. | |
| 13989 Fix handling of native methods on the stack -- | |
| 13990 location_ptr param of GetFrameLocation, remove | |
| 13991 JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation, | |
| 13992 jvmtiFrameInfo.location, and jlocation. | |
| 13993 Remove typo (from JVMPI) implying that the MonitorWaited | |
| 13994 event is sent on sleep. | |
| 13995 </change> | |
| 13996 <change date="25 November 2003" version="0.2.94"> | |
| 13997 Clarifications and typos. | |
| 13998 </change> | |
| 13999 <change date="3 December 2003" version="0.2.95"> | |
| 14000 Allow NULL user_data in heap iterators. | |
| 14001 </change> | |
| 14002 <change date="28 January 2004" version="0.2.97"> | |
| 14003 Add GetThreadState, deprecate GetThreadStatus. | |
| 14004 </change> | |
| 14005 <change date="29 January 2004" version="0.2.98"> | |
| 14006 INVALID_SLOT and TYPE_MISMATCH errors should be optional. | |
| 14007 </change> | |
| 14008 <change date="12 February 2004" version="0.2.102"> | |
| 14009 Remove MonitorContendedExit. | |
| 14010 Added JNIEnv parameter to VMObjectAlloc. | |
| 14011 Clarified definition of class_tag and referrer_index | |
| 14012 parameters to heap callbacks. | |
| 14013 </change> | |
| 14014 <change date="16 Febuary 2004" version="0.2.103"> | |
| 14015 Document JAVA_TOOL_OPTIONS. | |
| 14016 </change> | |
| 14017 <change date="17 Febuary 2004" version="0.2.105"> | |
| 14018 Divide start phase into primordial and start. | |
| 14019 Add VMStart event | |
| 14020 Change phase associations of functions and events. | |
| 14021 </change> | |
| 14022 <change date="18 Febuary 2004" version="0.3.6"> | |
| 14023 Elide deprecated GetThreadStatus. | |
| 14024 Bump minor version, subtract 100 from micro version | |
| 14025 </change> | |
| 14026 <change date="18 Febuary 2004" version="0.3.7"> | |
| 14027 Document that timer nanosecond values are unsigned. | |
| 14028 Clarify text having to do with native methods. | |
| 14029 </change> | |
| 14030 <change date="19 Febuary 2004" version="0.3.8"> | |
| 14031 Fix typos. | |
| 14032 Remove elided deprecated GetThreadStatus. | |
| 14033 </change> | |
| 14034 <change date="23 Febuary 2004" version="0.3.9"> | |
| 14035 Require NotifyFramePop to act on suspended threads. | |
| 14036 </change> | |
| 14037 <change date="24 Febuary 2004" version="0.3.10"> | |
| 14038 Add capabilities | |
| 14039 (<internallink id="jvmtiCapabilities.can_redefine_any_class" | |
| 14040 ><code>can_redefine_any_class</code></internallink> | |
| 14041 and | |
| 14042 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events" | |
| 14043 ><code>can_generate_all_class_hook_events</code></internallink>) | |
| 14044 and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>) | |
| 14045 which allow some classes to be unmodifiable. | |
| 14046 </change> | |
| 14047 <change date="28 Febuary 2004" version="0.3.11"> | |
| 14048 Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode. | |
| 14049 </change> | |
| 14050 <change date="8 March 2004" version="0.3.12"> | |
| 14051 Clarified CompiledMethodUnload so that it is clear the event | |
| 14052 may be posted after the class has been unloaded. | |
| 14053 </change> | |
| 14054 <change date="5 March 2004" version="0.3.13"> | |
| 14055 Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize. | |
| 14056 </change> | |
| 14057 <change date="13 March 2004" version="0.3.14"> | |
| 14058 Added guideline for the use of the JNI FindClass function in event | |
| 14059 callback functions. | |
| 14060 </change> | |
| 14061 <change date="15 March 2004" version="0.3.15"> | |
| 14062 Add GetAllStackTraces and GetThreadListStackTraces. | |
| 14063 </change> | |
| 14064 <change date="19 March 2004" version="0.3.16"> | |
| 14065 ClassLoad and ClassPrepare events can be posted during start phase. | |
| 14066 </change> | |
| 14067 <change date="25 March 2004" version="0.3.17"> | |
| 14068 Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable, | |
| 14069 GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes. | |
| 14070 </change> | |
| 14071 <change date="29 March 2004" version="0.3.18"> | |
| 14072 Return the timer kind in the timer information structure. | |
| 14073 </change> | |
| 14074 <change date="31 March 2004" version="0.3.19"> | |
| 14075 Spec clarifications: | |
| 14076 JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>. | |
| 14077 ForceGarbageCollection does not run finalizers. | |
| 14078 The context of the specification is the Java platform. | |
| 14079 Warn about early instrumentation. | |
| 14080 </change> | |
| 14081 <change date="1 April 2004" version="0.3.20"> | |
| 14082 Refinements to the above clarifications and | |
| 14083 Clarify that an error returned by Agent_OnLoad terminates the VM. | |
| 14084 </change> | |
| 14085 <change date="1 April 2004" version="0.3.21"> | |
| 14086 Array class creation does not generate a class load event. | |
| 14087 </change> | |
| 14088 <change date="7 April 2004" version="0.3.22"> | |
| 14089 Align thread state hierarchy more closely with java.lang.Thread.State. | |
| 14090 </change> | |
| 14091 <change date="12 April 2004" version="0.3.23"> | |
| 14092 Clarify the documentation of thread state. | |
| 14093 </change> | |
| 14094 <change date="19 April 2004" version="0.3.24"> | |
| 14095 Remove GarbageCollectionOccurred event -- can be done by agent. | |
| 14096 </change> | |
| 14097 <change date="22 April 2004" version="0.3.25"> | |
| 14098 Define "command-line option". | |
| 14099 </change> | |
| 14100 <change date="29 April 2004" version="0.3.26"> | |
| 14101 Describe the intended use of bytecode instrumentation. | |
| 14102 Fix description of extension event first parameter. | |
| 14103 </change> | |
| 14104 <change date="30 April 2004" version="0.3.27"> | |
| 14105 Clarification and typos. | |
| 14106 </change> | |
| 14107 <change date="18 May 2004" version="0.3.28"> | |
| 14108 Remove DataDumpRequest event. | |
| 14109 </change> | |
| 14110 <change date="18 May 2004" version="0.3.29"> | |
| 14111 Clarify RawMonitorWait with zero timeout. | |
| 14112 Clarify thread state after RunAgentThread. | |
| 14113 </change> | |
| 14114 <change date="24 May 2004" version="0.3.30"> | |
| 14115 Clean-up: fix bad/old links, etc. | |
| 14116 </change> | |
| 14117 <change date="30 May 2004" version="0.3.31"> | |
| 14118 Clarifications including: | |
| 14119 All character strings are modified UTF-8. | |
| 14120 Agent thread visibiity. | |
| 14121 Meaning of obsolete method version. | |
| 14122 Thread invoking heap callbacks, | |
| 14123 </change> | |
| 14124 <change date="1 June 2004" version="1.0.32"> | |
| 14125 Bump major.minor version numbers to "1.0". | |
| 14126 </change> | |
| 14127 <change date="2 June 2004" version="1.0.33"> | |
| 14128 Clarify interaction between ForceGarbageCollection | |
| 14129 and ObjectFree. | |
| 14130 </change> | |
| 14131 <change date="6 June 2004" version="1.0.34"> | |
| 14132 Restrict AddToBootstrapClassLoaderSearch and | |
| 14133 SetSystemProperty to the OnLoad phase only. | |
| 14134 </change> | |
| 14135 <change date="11 June 2004" version="1.0.35"> | |
| 14136 Fix typo in SetTag. | |
| 14137 </change> | |
| 14138 <change date="18 June 2004" version="1.0.36"> | |
| 14139 Fix trademarks. | |
| 14140 Add missing parameter in example GetThreadState usage. | |
| 14141 </change> | |
| 14142 <change date="4 August 2004" version="1.0.37"> | |
| 14143 Copyright updates. | |
| 14144 </change> | |
| 14145 <change date="5 November 2004" version="1.0.38"> | |
| 14146 Add missing function table layout. | |
| 14147 Add missing description of C++ member function format of functions. | |
| 14148 Clarify that name in CFLH can be NULL. | |
| 14149 Released as part of <tm>J2SE</tm> 5.0. | |
| 14150 </change> | |
| 14151 <change date="24 April 2005" version="1.1.47"> | |
| 14152 Bump major.minor version numbers to "1.1". | |
| 14153 Add ForceEarlyReturn* functions. | |
| 14154 Add GetOwnedMonitorStackDepthInfo function. | |
| 14155 Add GetCurrentThread function. | |
| 14156 Add "since" version marker. | |
| 14157 Add AddToSystemClassLoaderSearch. | |
| 14158 Allow AddToBootstrapClassLoaderSearch be used in live phase. | |
| 14159 Fix historic rubbish in the descriptions of the heap_object_callback | |
| 14160 parameter of IterateOverHeap and IterateOverInstancesOfClass functions; | |
| 14161 disallow NULL for this parameter. | |
| 14162 Clarify, correct and make consistent: wording about current thread, | |
| 14163 opaque frames and insufficient number of frames in PopFrame. | |
| 14164 Consistently use "current frame" rather than "topmost". | |
| 14165 Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal* | |
| 14166 by making them compatible with those in ForceEarlyReturn*. | |
| 14167 Many other clarifications and wording clean ups. | |
| 14168 </change> | |
| 14169 <change date="25 April 2005" version="1.1.48"> | |
| 14170 Add GetConstantPool. | |
| 14171 Switch references to the first edition of the VM Spec, to the seconds edition. | |
| 14172 </change> | |
| 14173 <change date="26 April 2005" version="1.1.49"> | |
| 14174 Clarify minor/major version order in GetConstantPool. | |
| 14175 </change> | |
| 14176 <change date="26 April 2005" version="1.1.50"> | |
| 14177 Add SetNativeMethodPrefix and SetNativeMethodPrefixes. | |
| 14178 Reassign GetOwnedMonitorStackDepthInfo to position 153. | |
| 14179 Break out Class Loader Search in its own documentation category. | |
| 14180 Deal with overly long lines in XML source. | |
| 14181 </change> | |
| 14182 <change date="29 April 2005" version="1.1.51"> | |
| 14183 Allow agents be started in the live phase. | |
| 14184 Added paragraph about deploying agents. | |
| 14185 </change> | |
| 14186 <change date="30 April 2005" version="1.1.52"> | |
| 14187 Add specification description to SetNativeMethodPrefix(es). | |
| 14188 Better define the conditions on GetConstantPool. | |
| 14189 </change> | |
| 14190 <change date="30 April 2005" version="1.1.53"> | |
| 14191 Break out the GetClassVersionNumber function from GetConstantPool. | |
| 14192 Clean-up the references to the VM Spec. | |
| 14193 </change> | |
| 14194 <change date="1 May 2005" version="1.1.54"> | |
| 14195 Allow SetNativeMethodPrefix(es) in any phase. | |
| 14196 Add clarifications about the impact of redefinition on GetConstantPool. | |
| 14197 </change> | |
| 14198 <change date="2 May 2005" version="1.1.56"> | |
| 14199 Various clarifications to SetNativeMethodPrefix(es). | |
| 14200 </change> | |
| 14201 <change date="2 May 2005" version="1.1.57"> | |
| 14202 Add missing performance warning to the method entry event. | |
| 14203 </change> | |
| 14204 <change date="5 May 2005" version="1.1.58"> | |
| 14205 Remove internal JVMDI support. | |
| 14206 </change> | |
| 14207 <change date="8 May 2005" version="1.1.59"> | |
| 14208 Add <functionlink id="RetransformClasses"/>. | |
| 14209 Revamp the bytecode instrumentation documentation. | |
| 14210 Change <functionlink id="IsMethodObsolete"/> to no longer | |
| 14211 require the can_redefine_classes capability. | |
| 14212 </change> | |
| 14213 <change date="11 May 2005" version="1.1.63"> | |
| 14214 Clarifications for retransformation. | |
| 14215 </change> | |
| 14216 <change date="11 May 2005" version="1.1.64"> | |
| 14217 Clarifications for retransformation, per review. | |
| 14218 Lock "retransformation (in)capable" at class load enable time. | |
| 14219 </change> | |
| 14220 <change date="4 June 2005" version="1.1.67"> | |
| 14221 Add new heap functionity which supports reporting primitive values, | |
| 14222 allows setting the referrer tag, and has more powerful filtering: | |
| 14223 FollowReferences, IterateThroughHeap, and their associated | |
| 14224 callbacks, structs, enums, and constants. | |
| 14225 </change> | |
| 14226 <change date="4 June 2005" version="1.1.68"> | |
| 14227 Clarification. | |
| 14228 </change> | |
| 14229 <change date="6 June 2005" version="1.1.69"> | |
| 14230 FollowReferences, IterateThroughHeap: Put callbacks in a struct; | |
| 14231 Add missing error codes; reduce bits in the visit control flags. | |
| 14232 </change> | |
| 14233 <change date="14 June 2005" version="1.1.70"> | |
| 14234 More on new heap functionity: spec clean-up per review. | |
| 14235 </change> | |
| 14236 <change date="15 June 2005" version="1.1.71"> | |
| 14237 More on new heap functionity: Rename old heap section to Heap (1.0). | |
| 14238 </change> | |
| 14239 <change date="21 June 2005" version="1.1.72"> | |
| 14240 Fix typos. | |
| 14241 </change> | |
| 14242 <change date="27 June 2005" version="1.1.73"> | |
| 14243 Make referrer info structure a union. | |
| 14244 </change> | |
| 14245 <change date="9 September 2005" version="1.1.74"> | |
| 14246 In new heap functions: | |
| 14247 Add missing superclass reference kind. | |
| 14248 Use a single scheme for computing field indexes. | |
| 14249 Remove outdated references to struct based referrer info. | |
| 14250 </change> | |
| 14251 <change date="12 September 2005" version="1.1.75"> | |
| 14252 Don't callback during FollowReferences on frivolous java.lang.Object superclass. | |
| 14253 </change> | |
| 14254 <change date="13 September 2005" version="1.1.76"> | |
| 14255 In string primitive callback, length now Unicode length. | |
| 14256 In array and string primitive callbacks, value now "const". | |
| 14257 Note possible compiler impacts on setting JNI function table. | |
| 14258 </change> | |
| 14259 <change date="13 September 2005" version="1.1.77"> | |
| 14260 GetClassVersionNumbers() and GetConstantPool() should return | |
| 14261 error on array or primitive class. | |
| 14262 </change> | |
| 14263 <change date="14 September 2005" version="1.1.78"> | |
| 14264 Grammar fixes. | |
| 14265 </change> | |
| 14266 <change date="26 September 2005" version="1.1.79"> | |
| 14267 Add IsModifiableClass query. | |
| 14268 </change> | |
| 14269 <change date="9 February 2006" version="1.1.81"> | |
| 14270 Add referrer_class_tag parameter to jvmtiHeapReferenceCallback. | |
| 14271 </change> | |
| 14272 <change date="13 February 2006" version="1.1.82"> | |
| 14273 Doc fixes: update can_redefine_any_class to include retransform. | |
| 14274 Clarify that exception events cover all Throwables. | |
| 14275 In GetStackTrace, no test is done for start_depth too big if start_depth is zero, | |
| 14276 Clarify fields reported in Primitive Field Callback -- static vs instance. | |
| 14277 Repair confusing names of heap types, including callback names. | |
| 14278 Require consistent usage of stack depth in the face of thread launch methods. | |
| 14279 Note incompatibility of <jvmti/> memory management with other systems. | |
| 14280 </change> | |
| 14281 <change date="14 February 2006" version="1.1.85"> | |
| 14282 Fix typos and missing renames. | |
| 14283 </change> | |
| 14284 <change date="13 March 2006" version="1.1.86"> | |
| 14285 Clarify that jmethodIDs and jfieldIDs can be saved. | |
| 14286 Clarify that Iterate Over Instances Of Class includes subclasses. | |
| 14287 </change> | |
| 14288 <change date="14 March 2006" version="1.1.87"> | |
| 14289 Better phrasing. | |
| 14290 </change> | |
| 14291 <change date="16 March 2006" version="1.1.88"> | |
| 14292 Match the referrer_index for static fields in Object Reference Callback | |
| 14293 with the Reference Implementation (and all other known implementations); | |
| 14294 that is, make it match the definition for instance fields. | |
| 14295 In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover | |
| 14296 an invalid thread in the list; and specify that not started threads | |
| 14297 return empty stacks. | |
| 14298 </change> | |
| 14299 <change date="17 March 2006" version="1.1.89"> | |
| 14300 Typo. | |
| 14301 </change> | |
| 14302 <change date="25 March 2006" version="1.1.90"> | |
| 14303 Typo. | |
| 14304 </change> | |
| 14305 <change date="6 April 2006" version="1.1.91"> | |
| 14306 Remove restrictions on AddToBootstrapClassLoaderSearch and | |
| 14307 AddToSystemClassLoaderSearch. | |
| 14308 </change> | |
| 14309 <change date="1 May 2006" version="1.1.93"> | |
| 14310 Changed spec to return -1 for monitor stack depth for the | |
| 14311 implementation which can not determine stack depth. | |
| 14312 </change> | |
| 14313 <change date="3 May 2006" version="1.1.94"> | |
| 14314 Corrections for readability and accuracy courtesy of Alan Pratt of IBM. | |
| 14315 List the object relationships reported in FollowReferences. | |
| 14316 </change> | |
| 14317 <change date="5 May 2006" version="1.1.95"> | |
| 14318 Clarify the object relationships reported in FollowReferences. | |
| 14319 </change> | |
| 14320 <change date="28 June 2006" version="1.1.98"> | |
| 14321 Clarify DisposeEnvironment; add warning. | |
| 14322 Fix typos in SetLocalXXX "retrieve" => "set". | |
| 14323 Clarify that native method prefixes must remain set while used. | |
| 14324 Clarify that exactly one Agent_OnXXX is called per agent. | |
| 14325 Clarify that library loading is independent from start-up. | |
| 14326 Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec. | |
| 14327 </change> | |
| 14328 <change date="31 July 2006" version="1.1.99"> | |
| 14329 Clarify the interaction between functions and exceptions. | |
| 14330 Clarify and give examples of field indices. | |
| 14331 Remove confusing "That is" sentence from MonitorWait and MonitorWaited events. | |
| 14332 Update links to point to Java 6. | |
| 14333 </change> | |
| 14334 <change date="6 August 2006" version="1.1.102"> | |
| 14335 Add ResourceExhaustedEvent. | |
| 14336 </change> | |
| 6919 | 14337 <change date="11 October 2012" version="1.2.2"> |
| 14338 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool. | |
| 14339 </change> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
14340 <change date="19 June 2013" version="1.2.3"> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
14341 Added support for statically linked agents. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
14342 </change> |
| 0 | 14343 </changehistory> |
| 14344 | |
| 14345 </specification> | |
| 14346 <!-- Keep this comment at the end of the file | |
| 14347 Local variables: | |
| 14348 mode: sgml | |
| 14349 sgml-omittag:t | |
| 14350 sgml-shorttag:t | |
| 14351 sgml-namecase-general:t | |
| 14352 sgml-general-insert-case:lower | |
| 14353 sgml-minimize-attributes:nil | |
| 14354 sgml-always-quote-attributes:t | |
| 14355 sgml-indent-step:2 | |
| 14356 sgml-indent-data:t | |
| 14357 sgml-parent-document:nil | |
| 14358 sgml-exposed-tags:nil | |
| 14359 sgml-local-catalogs:nil | |
| 14360 sgml-local-ecat-files:nil | |
| 14361 End: | |
| 14362 --> |