Mercurial > hg > truffle
annotate src/share/vm/prims/jvmti.xml @ 12190:edb5ab0f3fe5
8001107: @Stable annotation for constant folding of lazily evaluated variables
Reviewed-by: rbackman, twisti, kvn
Contributed-by: john.r.rose@oracle.com, vladimir.x.ivanov@oracle.com
| author | vlivanov |
|---|---|
| date | Tue, 10 Sep 2013 14:51:48 -0700 |
| parents | f92b82d454fa |
| children | 8e94527f601e |
| 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 |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
461 a function is exported, at the same point during startup as it would |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
462 have called the dynamic entry point Agent_OnUnLoad. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
463 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
|
464 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
|
465 function will be ignored. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
466 <p/> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
467 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
|
468 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
|
469 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
|
470 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
|
471 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
|
472 function will be ignored. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
473 </intro> |
| 0 | 474 |
| 475 <intro id="starting" label="Agent Command Line Options"> | |
| 476 The term "command-line option" is used below to | |
| 477 mean options supplied in the <code>JavaVMInitArgs</code> argument | |
| 478 to the <code>JNI_CreateJavaVM</code> function of the JNI | |
| 479 Invocation API. | |
| 480 <p/> | |
| 481 One of the two following | |
| 482 command-line options is used on VM startup to | |
| 483 properly load and run agents. | |
| 484 These arguments identify the library containing | |
| 485 the agent as well as an options | |
| 486 string to be passed in at startup. | |
| 487 <dl> | |
| 488 <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt> | |
| 489 <dd> | |
| 490 The name following <code>-agentlib:</code> is the name of the | |
| 491 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
|
492 proceeds in a platform-specific manner. |
| 0 | 493 Typically, the <i><agent-lib-name></i> is expanded to an |
| 494 operating system specific file name. | |
| 495 The <i><options></i> will be passed to the agent on start-up. | |
| 496 For example, if the option | |
| 497 <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to | |
| 498 load the shared library <code>foo.dll</code> from the system <code>PATH</code> | |
| 499 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
|
500 <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
|
501 environment. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
502 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
|
503 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
|
504 <p/> |
| 0 | 505 </dd> |
| 506 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt> | |
| 507 <dd> | |
| 508 The path following <code>-agentpath:</code> is the absolute path from which | |
| 509 to load the library. | |
| 510 No library name expansion will occur. | |
| 511 The <i><options></i> will be passed to the agent on start-up. | |
| 512 For example, if the option | |
| 513 <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
|
514 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
|
515 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
|
516 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
|
517 <p/> |
| 0 | 518 </dd> |
| 519 </dl> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
520 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
|
521 <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
|
522 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
|
523 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
|
524 <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
|
525 <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
|
526 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
|
527 the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine. |
| 0 | 528 <p/> |
| 529 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code> | |
| 530 will be searched for JNI native method implementations to facilitate the | |
| 531 use of Java programming language code in tools, as is needed for | |
| 532 <internallink id="bci">bytecode instrumentation</internallink>. | |
| 533 <p/> | |
| 534 The agent libraries will be searched after all other libraries have been | |
| 535 searched (agents wishing to override or intercept the native method | |
| 536 implementations of non-agent methods can use the | |
| 537 <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>). | |
| 538 <p/> | |
| 539 These switches do the above and nothing more - they do not change the | |
| 540 state of the VM or <jvmti/>. No command line options are needed | |
| 541 to enable <jvmti/> | |
| 542 or aspects of <jvmti/>, this is handled programmatically | |
| 543 by the use of | |
| 544 <internallink id="capability">capabilities</internallink>. | |
| 545 </intro> | |
| 546 | |
| 547 <intro id="startup" label="Agent Start-Up"> | |
| 548 The VM starts each agent by invoking a start-up function. | |
| 549 If the agent is started in the <code>OnLoad</code> | |
| 550 <functionlink id="GetPhase">phase</functionlink> the function | |
| 551 <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
|
552 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
|
553 for statically linked agents will be invoked. |
| 0 | 554 If the agent is started in the live |
| 555 <functionlink id="GetPhase">phase</functionlink> the function | |
| 556 <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
|
557 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
|
558 for statically linked agents will be invoked. |
| 0 | 559 Exactly one call to a start-up function is made per agent. |
| 560 </intro> | |
| 561 | |
| 562 <intro id="onload" label="Agent Start-Up (OnLoad phase)"> | |
| 563 If an agent is started during the <code>OnLoad</code> phase then its | |
| 564 agent library must export a start-up function with the following prototype: | |
| 565 <example> | |
| 566 JNIEXPORT jint JNICALL | |
| 567 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
|
568 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
|
569 <example> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
570 JNIEXPORT jint JNICALL |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
571 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
|
572 |
| 0 | 573 The VM will start the agent by calling this function. |
| 574 It will be called early enough in VM initialization that: | |
| 575 <ul> | |
| 576 <li><functionlink id="SetSystemProperty">system properties</functionlink> | |
| 577 may be set before they have been used in the start-up of the VM</li> | |
| 578 <li>the full set of | |
| 579 <internallink id="capability">capabilities</internallink> | |
| 580 is still available (note that capabilities that configure the VM | |
| 581 may only be available at this time--see the | |
| 582 <internallink id="capability">Capability function section</internallink>)</li> | |
| 583 <li>no bytecodes have executed</li> | |
| 584 <li>no classes have been loaded</li> | |
| 585 <li>no objects have been created</li> | |
| 586 </ul> | |
| 587 <p/> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
588 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
|
589 <code>Agent_OnLoad_<agent-lib-name></code> function with |
| 0 | 590 <i><options></i> as the second argument - |
| 591 that is, using the command-line option examples, | |
| 592 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> | |
| 593 argument of <code>Agent_OnLoad</code>. | |
| 594 The <code>options</code> argument is encoded as a | |
| 595 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 596 If <i>=<options></i> is not specified, | |
| 597 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
|
598 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
|
599 <code>Agent_OnLoad</code> or <code>Agent_OnLoad_<agent-lib-name></code> |
| 0 | 600 call. If needed beyond this time the string or parts of the string must |
| 601 be copied. | |
| 602 The period between when <code>Agent_OnLoad</code> is called and when it | |
| 603 returns is called the <i>OnLoad phase</i>. | |
| 604 Since the VM is not initialized during the OnLoad | |
| 605 <functionlink id="GetPhase">phase</functionlink>, | |
| 606 the set of allowed operations | |
| 607 inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the | |
| 608 functionality available at this time). | |
| 609 The agent can safely process the options and set | |
| 610 event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once | |
| 611 the VM initialization event is received | |
| 612 (that is, the <eventlink id="VMInit">VMInit</eventlink> | |
| 613 callback is invoked), the agent | |
| 614 can complete its initialization. | |
| 615 <rationale> | |
| 616 Early startup is required so that agents can set the desired capabilities, | |
| 617 many of which must be set before the VM is initialized. | |
| 618 In JVMDI, the -Xdebug command-line option provided | |
| 619 very coarse-grain control of capabilities. | |
| 620 JVMPI implementations use various tricks to provide a single "JVMPI on" switch. | |
| 621 No reasonable command-line | |
| 622 option could provide the fine-grain of control required to balance needed capabilities vs | |
| 623 performance impact. | |
| 624 Early startup is also needed so that agents can control the execution | |
| 625 environment - modifying the file system and system properties to install | |
| 626 their functionality. | |
| 627 </rationale> | |
| 628 <p/> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
629 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
|
630 <code>Agent_OnLoad_<agent-lib-name></code> is used to indicate an error. |
| 0 | 631 Any value other than zero indicates an error and causes termination of the VM. |
| 632 </intro> | |
| 633 | |
| 634 <intro id="onattach" label="Agent Start-Up (Live phase)"> | |
| 635 A VM may support a mechanism that allows agents to be started in the VM during the live | |
| 636 <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported, | |
| 637 are implementation specific. For example, a tool may use some platform specific mechanism, | |
| 638 or implementation specific API, to attach to the running VM, and request it start a given | |
| 639 agent. | |
| 640 <p/> | |
| 641 If an agent is started during the live phase then its agent library | |
| 642 must export a start-up function | |
| 643 with the following prototype: | |
| 644 <example> | |
| 645 JNIEXPORT jint JNICALL | |
| 646 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
|
647 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
|
648 <example> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
649 JNIEXPORT jint JNICALL |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
650 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
|
651 |
| 0 | 652 <p/> |
| 653 The VM will start the agent by calling this function. | |
| 654 It will be called in the context of a thread | |
| 655 that is attached to the VM. The first argument <i><vm></i> is the Java VM. | |
| 656 The <i><options></i> argument is the startup options provided to the agent. | |
| 657 <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8 | |
| 658 </internallink> string. | |
| 659 If startup options were not provided, a zero length string is passed to | |
| 660 <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
|
661 <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
|
662 If needed beyond this time the string or parts of the string must be copied. |
| 0 | 663 <p/> |
| 664 Note that some <internallink id="capability">capabilities</internallink> | |
| 665 may not be available in the live phase. | |
| 666 <p/> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
667 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
|
668 ></code> function initializes the agent and returns a value |
| 0 | 669 to the VM to indicate if an error occurred. Any value other than zero indicates an error. |
| 670 An error does not cause the VM to terminate. Instead the VM ignores the error, or takes | |
| 671 some implementation specific action -- for example it might print an error to standard error, | |
| 672 or record the error in a system log. | |
| 673 </intro> | |
| 674 | |
| 675 <intro id="onunload" label="Agent Shutdown"> | |
| 676 The library may optionally export a | |
| 677 shutdown function with the following prototype: | |
| 678 <example> | |
| 679 JNIEXPORT void JNICALL | |
| 680 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
|
681 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
|
682 <example> |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
683 JNIEXPORT void JNICALL |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
684 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
|
685 |
| 0 | 686 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
|
687 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
|
688 executable) and this function will be called if some platform specific |
| 0 | 689 mechanism causes the unload (an unload mechanism is not specified in this document) |
| 690 or the library is (in effect) unloaded by the termination of the VM whether through | |
| 691 normal termination or VM failure, including start-up failure. | |
| 692 Uncontrolled shutdown is, of couse, an exception to this rule. | |
| 693 Note the distinction between this function and the | |
| 694 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event | |
| 695 to be sent, the VM must have run at least to the point of initialization and a valid | |
| 696 <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
|
697 and enabled the event. |
|
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
698 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
|
699 <code>Agent_OnUnload_<agent-lib-name></code> and this function |
| 0 | 700 is also called if the library is unloaded for other reasons. |
| 701 In the case that a VM Death event is sent, it will be sent before this | |
| 702 function is called (assuming this function is called due to VM termination). | |
| 703 This function can be used to clean-up resources allocated by the agent. | |
| 704 </intro> | |
| 705 | |
| 706 <intro id="tooloptions" label="JAVA_TOOL_OPTIONS"> | |
| 707 Since the command-line cannot always be accessed or modified, for example in embedded VMs | |
| 708 or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is | |
| 709 provided so that agents may be launched in these cases. | |
| 710 <p/> | |
| 711 Platforms which support environment variables or other named strings, may support the | |
| 712 <code>JAVA_TOOL_OPTIONS</code> variable. This variable will be broken into options at white-space | |
| 713 boundaries. White-space characters include space, tab, carriage-return, new-line, | |
| 714 vertical-tab, and form-feed. Sequences of white-space characters are considered | |
| 715 equivalent to a single white-space character. No white-space is included in the options | |
| 716 unless quoted. Quoting is as follows: | |
| 717 <ul> | |
| 718 <li>All characters enclosed between a pair of single quote marks (''), except a single | |
| 719 quote, are quoted.</li> | |
| 720 <li>Double quote characters have no special meaning inside a pair of single quote marks.</li> | |
| 721 <li>All characters enclosed between a pair of double quote marks (""), except a double | |
| 722 quote, are quoted.</li> | |
| 723 <li>Single quote characters have no special meaning inside a pair of double quote marks.</li> | |
| 724 <li>A quoted part can start or end anywhere in the variable.</li> | |
| 725 <li>White-space characters have no special meaning when quoted -- they are included in | |
| 726 the option like any other character and do not mark white-space boundaries.</li> | |
| 727 <li>The pair of quote marks is not included in the option.</li> | |
| 728 </ul> | |
| 729 <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied | |
| 730 in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is | |
| 731 a concern; for example, the Reference Implementation disables this feature on Unix systems when | |
| 732 the effective user or group ID differs from the real ID. | |
| 733 This feature is intended to support the initialization of tools -- specifically including the | |
| 734 launching of native or Java programming language agents. Multiple tools may wish to use this | |
| 735 feature, so the variable should not be overwritten, instead, options should be appended to | |
| 736 the variable. Note that since the variable is processed at the time of the JNI Invocation | |
| 737 API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled. | |
| 738 </intro> | |
| 739 | |
| 740 <intro id="environments" label="Environments"> | |
| 741 The <jvmti/> specification supports the use of multiple simultaneous | |
| 742 <jvmti/> agents. | |
| 743 Each agent has its own <jvmti/> environment. | |
| 744 That is, the <jvmti/> state is | |
| 745 separate for each agent - changes to one environment do not affect the | |
| 746 others. The state of a <jvmti/> | |
| 747 environment includes: | |
| 748 <ul> | |
| 749 <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li> | |
| 750 <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li> | |
| 751 <li><internallink id="capability">the capabilities</internallink></li> | |
| 752 <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li> | |
| 753 </ul> | |
| 754 Although their <jvmti/> state | |
| 755 is separate, agents inspect and modify the shared state | |
| 756 of the VM, they also share the native environment in which they execute. | |
| 757 As such, an agent can perturb the results of other agents or cause them | |
| 758 to fail. It is the responsibility of the agent writer to specify the level | |
| 759 of compatibility with other agents. <jvmti/> implementations are not capable | |
| 760 of preventing destructive interactions between agents. Techniques to reduce | |
| 761 the likelihood of these occurrences are beyond the scope of this document. | |
| 762 <p/> | |
| 763 An agent creates a <jvmti/> environment | |
| 764 by passing a <jvmti/> version | |
| 765 as the interface ID to the JNI Invocation API function | |
| 6919 | 766 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><code>GetEnv</code></externallink>. |
| 0 | 767 See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink> |
| 768 for more details on the creation and use of | |
| 769 <jvmti/> environments. | |
| 770 Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from | |
| 771 <internallink id="onload"><code>Agent_OnLoad</code></internallink>. | |
| 772 </intro> | |
| 773 | |
| 774 <intro id="bci" label="Bytecode Instrumentation"> | |
| 775 This interface does not include some events that one might expect in an interface with | |
| 776 profiling support. Some examples include object allocation events and full speed | |
| 777 method enter and exit events. The interface instead provides support for | |
| 778 <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine | |
| 779 bytecode instructions which comprise the target program. Typically, these alterations | |
| 780 are to add "events" to the code of a method - for example, to add, at the beginning of a method, | |
| 781 a call to <code>MyProfiler.methodEntered()</code>. | |
| 782 Since the changes are purely additive, they do not modify application | |
| 783 state or behavior. | |
| 784 Because the inserted agent code is standard bytecodes, the VM can run at full speed, | |
| 785 optimizing not only the target program but also the instrumentation. If the | |
| 786 instrumentation does not involve switching from bytecode execution, no expensive | |
| 787 state transitions are needed. The result is high performance events. | |
| 788 This approach also provides complete control to the agent: instrumentation can be | |
| 789 restricted to "interesting" portions of the code (e.g., the end user's code) and | |
| 790 can be conditional. Instrumentation can run entirely in Java programming language | |
| 791 code or can call into the native agent. Instrumentation can simply maintain | |
| 792 counters or can statistically sample events. | |
| 793 <p/> | |
| 794 Instrumentation can be inserted in one of three ways: | |
| 795 <ul> | |
| 796 <li> | |
| 797 Static Instrumentation: The class file is instrumented before it | |
| 798 is loaded into the VM - for example, by creating a duplicate directory of | |
| 799 <code>*.class</code> files which have been modified to add the instrumentation. | |
| 800 This method is extremely awkward and, in general, an agent cannot know | |
| 801 the origin of the class files which will be loaded. | |
| 802 </li> | |
| 803 <li> | |
| 804 Load-Time Instrumentation: When a class file is loaded by the VM, the raw | |
| 805 bytes of the class file are sent for instrumentation to the agent. | |
| 806 The <eventlink id="ClassFileLoadHook"/> | |
| 807 event, triggered by the class load, | |
| 808 provides this functionality. This mechanism provides efficient | |
| 809 and complete access to one-time instrumentation. | |
| 810 </li> | |
| 811 <li> | |
| 812 Dynamic Instrumentation: A class which is already loaded (and possibly | |
| 813 even running) is modified. This optional feature is provided by the | |
| 814 <eventlink id="ClassFileLoadHook"/> event, triggered by calling the | |
| 815 <functionlink id="RetransformClasses"/> function. | |
| 816 Classes can be modified multiple times and can be returned to their | |
| 817 original state. | |
| 818 The mechanism allows instrumentation which changes during the | |
| 819 course of execution. | |
| 820 </li> | |
| 821 </ul> | |
| 822 <p/> | |
| 823 The class modification functionality provided in this interface | |
| 824 is intended to provide a mechanism for instrumentation | |
| 825 (the <eventlink id="ClassFileLoadHook"/> event | |
| 826 and the <functionlink id="RetransformClasses"/> function) | |
| 827 and, during development, for fix-and-continue debugging | |
| 828 (the <functionlink id="RedefineClasses"/> function). | |
| 829 <p/> | |
| 830 Care must be taken to avoid perturbing dependencies, especially when | |
| 831 instrumenting core classes. For example, an approach to getting notification | |
| 832 of every object allocation is to instrument the constructor on | |
| 833 <code>Object</code>. Assuming that the constructor is initially | |
| 834 empty, the constructor could be changed to: | |
| 835 <example> | |
| 836 public Object() { | |
| 837 MyProfiler.allocationTracker(this); | |
| 838 } | |
| 839 </example> | |
| 840 However, if this change was made using the | |
| 841 <eventlink id="ClassFileLoadHook"/> | |
| 842 event then this might impact a typical VM as follows: | |
| 843 the first created object will call the constructor causing a class load of | |
| 844 <code>MyProfiler</code>; which will then cause | |
| 845 object creation, and since <code>MyProfiler</code> isn't loaded yet, | |
| 846 infinite recursion; resulting in a stack overflow. A refinement of this | |
| 847 would be to delay invoking the tracking method until a safe time. For | |
| 848 example, <code>trackAllocations</code> could be set in the | |
| 849 handler for the <code>VMInit</code> event. | |
| 850 <example> | |
| 851 static boolean trackAllocations = false; | |
| 852 | |
| 853 public Object() { | |
| 854 if (trackAllocations) { | |
| 855 MyProfiler.allocationTracker(this); | |
| 856 } | |
| 857 } | |
| 858 </example> | |
| 859 <p/> | |
| 860 The <functionlink id="SetNativeMethodPrefix"/> allows native methods | |
| 861 to be instrumented by the use of wrapper methods. | |
| 862 </intro> | |
| 863 | |
| 864 <intro id="mUTF" label="Modified UTF-8 String Encoding"> | |
| 865 <jvmti/> uses modified UTF-8 to encode character strings. | |
| 866 This is the same encoding used by JNI. | |
| 867 Modified UTF-8 differs | |
| 868 from standard UTF-8 in the representation of supplementary characters | |
| 869 and of the null character. See the | |
| 6919 | 870 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16542"> |
| 0 | 871 Modified UTF-8 Strings</externallink> |
| 872 section of the JNI specification for details. | |
| 873 </intro> | |
| 874 | |
| 875 <intro id="context" label="Specification Context"> | |
| 876 Since this interface provides access to the state of applications running in the | |
| 877 Java virtual machine; | |
| 878 terminology refers to the Java platform and not the native | |
| 879 platform (unless stated otherwise). For example: | |
| 880 <ul> | |
| 881 <li>"thread" means Java programming language thread.</li> | |
| 882 <li>"stack frame" means Java virtual machine stack frame.</li> | |
| 883 <li>"class" means Java programming language class.</li> | |
| 884 <li>"heap" means Java virtual machine heap.</li> | |
| 885 <li>"monitor" means Java programming language object monitor.</li> | |
| 886 </ul> | |
| 887 <p/> | |
| 888 Sun, Sun Microsystems, the Sun logo, Java, and JVM | |
|
1552
c18cbe5936b8
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
0
diff
changeset
|
889 are trademarks or registered trademarks of Oracle |
|
c18cbe5936b8
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
0
diff
changeset
|
890 and/or its affiliates, in the U.S. and other countries. |
| 0 | 891 </intro> |
| 892 | |
| 893 | |
| 894 <functionsection label="Functions"> | |
| 895 <intro id="jvmtiEnvAccess" label="Accessing Functions"> | |
| 896 Native code accesses <jvmti/> features | |
| 897 by calling <jvmti/> functions. | |
| 898 Access to <jvmti/> functions is by use of an interface pointer | |
| 899 in the same manner as | |
| 6919 | 900 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html">Java |
| 0 | 901 Native Interface (JNI) functions</externallink> are accessed. |
| 902 The <jvmti/> interface pointer is called the | |
| 903 <i>environment pointer</i>. | |
| 904 <p/> | |
| 905 An environment pointer is a pointer to an environment and has | |
| 906 the type <code>jvmtiEnv*</code>. | |
| 907 An environment has information about its <jvmti/> connection. | |
| 908 The first value in the environment is a pointer to the function table. | |
| 909 The function table is an array of pointers to <jvmti/> functions. | |
| 910 Every function pointer is at a predefined offset inside the | |
| 911 array. | |
| 912 <p/> | |
| 913 When used from the C language: | |
| 914 double indirection is used to access the functions; | |
| 915 the environment pointer provides context and is the first | |
| 916 parameter of each function call; for example: | |
| 917 <example> | |
| 918 jvmtiEnv *jvmti; | |
| 919 ... | |
| 920 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &class_count, &classes); | |
| 921 </example> | |
| 922 <p/> | |
| 923 When used from the C++ language: | |
| 924 functions are accessed as member functions of <code>jvmtiEnv</code>; | |
| 925 the environment pointer is not passed to the function call; for example: | |
| 926 <example> | |
| 927 jvmtiEnv *jvmti; | |
| 928 ... | |
| 929 jvmtiError err = jvmti->GetLoadedClasses(&class_count, &classes); | |
| 930 </example> | |
| 931 Unless otherwise stated, all examples and declarations in this | |
| 932 specification use the C language. | |
| 933 <p/> | |
| 934 A <jvmti/> environment can be obtained through the JNI Invocation API | |
| 935 <code>GetEnv</code> function: | |
| 936 <example> | |
| 937 jvmtiEnv *jvmti; | |
| 938 ... | |
| 939 (*jvm)->GetEnv(jvm, &jvmti, JVMTI_VERSION_1_0); | |
| 940 </example> | |
| 941 Each call to <code>GetEnv</code> | |
| 942 creates a new <jvmti/> connection and thus | |
| 943 a new <jvmti/> environment. | |
| 944 The <code>version</code> argument of <code>GetEnv</code> must be | |
| 945 a <jvmti/> version. | |
| 946 The returned environment may have a different version than the | |
| 947 requested version but the returned environment must be compatible. | |
| 948 <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a | |
| 949 compatible version is not available, if <jvmti/> is not supported or | |
| 950 <jvmti/> is not supported in the current VM configuration. | |
| 951 Other interfaces may be added for creating <jvmti/> environments | |
| 952 in specific contexts. | |
| 953 Each environment has its own state (for example, | |
| 954 <functionlink id="SetEventNotificationMode">desired events</functionlink>, | |
| 955 <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and | |
| 956 <functionlink id="AddCapabilities">capabilities</functionlink>). | |
| 957 An environment is released with | |
| 958 <functionlink id="DisposeEnvironment"></functionlink>. | |
| 959 Thus, unlike JNI which has one environment per thread, <jvmti/> environments work | |
| 960 across threads and are created dynamically. | |
| 961 </intro> | |
| 962 | |
| 963 <intro id="functionReturn" label="Function Return Values"> | |
| 964 <jvmti/> functions always return an | |
| 965 <internallink id="ErrorSection">error code</internallink> via the | |
| 966 <datalink id="jvmtiError"/> function return value. | |
| 967 Some functions can return additional | |
| 968 values through pointers provided by the calling function. | |
| 969 In some cases, <jvmti/> functions allocate memory that your program must | |
| 970 explicitly deallocate. This is indicated in the individual <jvmti/> | |
| 971 function descriptions. Empty lists, arrays, sequences, etc are | |
| 972 returned as <code>NULL</code>. | |
| 973 <p/> | |
| 974 In the event that the <jvmti/> function encounters | |
| 975 an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values | |
| 976 of memory referenced by argument pointers is undefined, but no memory | |
| 977 will have been allocated and no global references will have been allocated. | |
| 978 If the error occurs because of invalid input, no action will have occurred. | |
| 979 </intro> | |
| 980 | |
| 981 <intro id="refs" label="Managing JNI Object References"> | |
| 982 <jvmti/> functions identify objects with JNI references | |
| 983 (<datalink id="jobject"/> and <datalink id="jclass"/>) | |
| 984 and their derivatives | |
| 985 (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>). | |
| 986 References passed to | |
| 987 <jvmti/> functions can be either global or local, but they must be | |
| 988 strong references. All references returned by <jvmti/> functions are | |
| 989 local references--these local references are created | |
| 990 during the <jvmti/> call. | |
| 991 Local references are a resource that must be managed (see the | |
| 6919 | 992 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp18654">JNI Documentation</externallink>). |
| 0 | 993 When threads return from native code all local references |
| 994 are freed. Note that some threads, including typical | |
| 995 agent threads, will never return from native code. | |
| 996 A thread is ensured the ability to create sixteen local | |
| 997 references without the need for any explicit management. | |
| 998 For threads executing a limited number of <jvmti/> calls before | |
| 999 returning from native code | |
| 1000 (for example, threads processing events), | |
| 1001 it may be determined that no explicit management | |
| 1002 is needed. | |
| 1003 However, long running agent threads will need explicit | |
| 1004 local reference management--usually with the JNI functions | |
| 1005 <code>PushLocalFrame</code> and <code>PopLocalFrame</code>. | |
| 1006 Conversely, to preserve references beyond the | |
| 1007 return from native code, they must be converted to global references. | |
| 1008 These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> | |
| 1009 as they are not <datalink id="jobject"/>s. | |
| 1010 </intro> | |
| 1011 | |
| 1012 <intro id="prereqState" label="Prerequisite State for Calling Functions"> | |
| 1013 Unless the function explicitly states that the agent must bring | |
| 1014 a thread or the VM to a particular state (for example, suspended), | |
| 1015 the <jvmti/> implementation is responsible for bringing the VM to a | |
| 1016 safe and consistent state for performing the function. | |
| 1017 </intro> | |
| 1018 | |
| 1019 <intro id="functionsExceptions" label="Exceptions and Functions"> | |
| 1020 <jvmti/> functions never throw exceptions; error conditions are | |
| 1021 communicated via the | |
| 1022 <internallink id="functionReturn">function return value</internallink>. | |
| 1023 Any existing exception state is preserved across a call to a | |
| 1024 <jvmti/> function. | |
| 1025 See the | |
| 1026 <externallink | |
| 6919 | 1027 id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html#wp770" |
| 0 | 1028 >Java Exceptions</externallink> |
| 1029 section of the JNI specification for information on handling exceptions. | |
| 1030 </intro> | |
| 1031 | |
| 1032 <category id="memory" label="Memory Management"> | |
| 1033 <intro> | |
| 1034 These functions provide for the allocation and deallocation of | |
| 1035 memory used by <jvmti/> functionality and can be used to provide | |
| 1036 working memory for agents. | |
| 1037 Memory managed by <jvmti/> is not compatible with other memory | |
| 1038 allocation libraries and mechanisms. | |
| 1039 </intro> | |
| 1040 | |
| 1041 <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46"> | |
| 1042 <synopsis>Allocate</synopsis> | |
| 1043 <description> | |
| 1044 Allocate an area of memory through the <jvmti/> allocator. | |
| 1045 The allocated | |
| 1046 memory should be freed with <functionlink id="Deallocate"></functionlink>. | |
| 1047 </description> | |
| 1048 <origin>jvmdi</origin> | |
| 1049 <capabilities> | |
| 1050 </capabilities> | |
| 1051 <parameters> | |
| 1052 <param id="size"> | |
| 1053 <jlong/> | |
| 1054 <description> | |
| 1055 The number of bytes to allocate. | |
| 1056 <rationale> | |
| 1057 <code>jlong</code> is used for compatibility with JVMDI. | |
| 1058 </rationale> | |
| 1059 </description> | |
| 1060 </param> | |
| 1061 <param id="mem_ptr"> | |
| 1062 <allocbuf incount="size"><uchar/></allocbuf> | |
| 1063 <description> | |
| 1064 On return, a pointer to the beginning of the allocated memory. | |
| 1065 If <code>size</code> is zero, <code>NULL</code> is returned. | |
| 1066 </description> | |
| 1067 </param> | |
| 1068 </parameters> | |
| 1069 <errors> | |
| 1070 <error id="JVMTI_ERROR_OUT_OF_MEMORY"> | |
| 1071 Memory request cannot be honored. | |
| 1072 </error> | |
| 1073 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 1074 <paramlink id="size"></paramlink> is less than zero. | |
| 1075 </error> | |
| 1076 </errors> | |
| 1077 </function> | |
| 1078 | |
| 1079 <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47"> | |
| 1080 <synopsis>Deallocate</synopsis> | |
| 1081 <description> | |
| 1082 Deallocate <code>mem</code> using the <jvmti/> allocator. | |
| 1083 This function should | |
| 1084 be used to deallocate any memory allocated and returned | |
| 1085 by a <jvmti/> function | |
| 1086 (including memory allocated with <functionlink id="Allocate"></functionlink>). | |
| 1087 All allocated memory must be deallocated | |
| 1088 or the memory cannot be reclaimed. | |
| 1089 </description> | |
| 1090 <origin>jvmdi</origin> | |
| 1091 <capabilities> | |
| 1092 </capabilities> | |
| 1093 <parameters> | |
| 1094 <param id="mem"> | |
| 1095 <outbuf> | |
| 1096 <uchar/> | |
| 1097 <nullok>the call is ignored</nullok> | |
| 1098 </outbuf> | |
| 1099 <description> | |
| 1100 A pointer to the beginning of the allocated memory. | |
| 1101 Please ignore "On return, the elements are set." | |
| 1102 <todo>keep it from generating "On return, the elements are set"</todo> | |
| 1103 </description> | |
| 1104 </param> | |
| 1105 </parameters> | |
| 1106 <errors> | |
| 1107 </errors> | |
| 1108 </function> | |
| 1109 </category> | |
| 1110 | |
| 1111 <category id="threadCategory" label="Thread"> | |
| 1112 <intro> | |
| 1113 </intro> | |
| 1114 | |
| 1115 <function id="GetThreadState" num="17"> | |
| 1116 <synopsis>Get Thread State</synopsis> | |
| 1117 <description> | |
| 1118 Get the state of a thread. The state of the thread is represented by the | |
| 1119 answers to the hierarchical set of questions below: | |
| 1120 <ul type="circle"> | |
| 1121 <li><i>Alive?</i> | |
| 1122 <ul> | |
| 1123 <li>Not alive. | |
| 1124 <ul type="circle"> | |
| 1125 <li><i>Why not alive?</i> | |
| 1126 <ul> | |
| 1127 <li>New.</li> | |
| 1128 <li>Terminated (<datalink | |
| 1129 id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li> | |
| 1130 </ul> | |
| 1131 </li> | |
| 1132 </ul> | |
| 1133 </li> | |
| 1134 <li>Alive (<datalink | |
| 1135 id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>) | |
| 1136 <ul type="circle"> | |
| 1137 <li><i>Suspended?</i> | |
| 1138 <ul> | |
| 1139 <li>Suspended (<datalink | |
| 1140 id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li> | |
| 1141 <li>Not suspended</li> | |
| 1142 </ul> | |
| 1143 </li> | |
| 1144 <li><i>Interrupted?</i> | |
| 1145 <ul> | |
| 1146 <li>Interrupted (<datalink | |
| 1147 id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li> | |
| 1148 <li>Not interrupted.</li> | |
| 1149 </ul> | |
| 1150 </li> | |
| 1151 <li><i>In native?</i> | |
| 1152 <ul> | |
| 1153 <li>In native code (<datalink | |
| 1154 id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li> | |
| 1155 <li>In Java programming language code</li> | |
| 1156 </ul> | |
| 1157 </li> | |
| 1158 <li><i>What alive state?</i> | |
| 1159 <ul> | |
| 1160 <li>Runnable (<datalink | |
| 1161 id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li> | |
| 1162 <li>Blocked (<datalink | |
| 1163 id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li> | |
| 1164 <li>Waiting (<datalink | |
| 1165 id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>) | |
| 1166 <ul type="circle"> | |
| 1167 <li><i>Timed wait?</i> | |
| 1168 <ul> | |
| 1169 <li>Indefinite (<datalink | |
| 1170 id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li> | |
| 1171 <li>Timed (<datalink | |
| 1172 id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li> | |
| 1173 </ul> | |
| 1174 </li> | |
| 1175 <li><i>Why waiting?</i> | |
| 1176 <ul> | |
| 1177 <li>Object.wait (<datalink | |
| 1178 id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li> | |
| 1179 <li>LockSupport.park (<datalink | |
| 1180 id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li> | |
| 1181 <li>Sleeping (<datalink | |
| 1182 id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li> | |
| 1183 </ul> | |
| 1184 </li> | |
| 1185 </ul> | |
| 1186 </li> | |
| 1187 </ul> | |
| 1188 </li> | |
| 1189 </ul> | |
| 1190 </li> | |
| 1191 </ul> | |
| 1192 </li> | |
| 1193 </ul> | |
| 1194 <p/> | |
| 1195 The answers are represented by the following bit vector. | |
| 1196 <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits"> | |
| 1197 <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001"> | |
| 1198 Thread is alive. Zero if thread is new (not started) or terminated. | |
| 1199 </constant> | |
| 1200 <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002"> | |
| 1201 Thread has completed execution. | |
| 1202 </constant> | |
| 1203 <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004"> | |
| 1204 Thread is runnable. | |
| 1205 </constant> | |
| 1206 <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400"> | |
| 1207 Thread is waiting to enter a synchronization block/method or, | |
| 1208 after an <code>Object.wait()</code>, waiting to re-enter a | |
| 1209 synchronization block/method. | |
| 1210 </constant> | |
| 1211 <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080"> | |
| 1212 Thread is waiting. | |
| 1213 </constant> | |
| 1214 <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010"> | |
| 1215 Thread is waiting without a timeout. | |
| 1216 For example, <code>Object.wait()</code>. | |
| 1217 </constant> | |
| 1218 <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020"> | |
| 1219 Thread is waiting with a maximum time to wait specified. | |
| 1220 For example, <code>Object.wait(long)</code>. | |
| 1221 </constant> | |
| 1222 <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040"> | |
| 1223 Thread is sleeping -- <code>Thread.sleep(long)</code>. | |
| 1224 </constant> | |
| 1225 <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100"> | |
| 1226 Thread is waiting on an object monitor -- <code>Object.wait</code>. | |
| 1227 </constant> | |
| 1228 <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200"> | |
| 1229 Thread is parked, for example: <code>LockSupport.park</code>, | |
| 1230 <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>. | |
| 1231 </constant> | |
| 1232 <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000"> | |
| 1233 Thread suspended. | |
| 1234 <code>java.lang.Thread.suspend()</code> | |
| 1235 or a <jvmti/> suspend function | |
| 1236 (such as <functionlink id="SuspendThread"></functionlink>) | |
| 1237 has been called on the thread. If this bit | |
| 1238 is set, the other bits refer to the thread state before suspension. | |
| 1239 </constant> | |
| 1240 <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000"> | |
| 1241 Thread has been interrupted. | |
| 1242 </constant> | |
| 1243 <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000"> | |
| 1244 Thread is in native code--that is, a native method is running | |
| 1245 which has not called back into the VM or Java programming | |
| 1246 language code. | |
| 1247 <p/> | |
| 1248 This flag is not set when running VM compiled Java programming | |
| 1249 language code nor is it set when running VM code or | |
| 1250 VM support code. Native VM interface functions, such as JNI and | |
| 1251 <jvmti/> functions, may be implemented as VM code. | |
| 1252 </constant> | |
| 1253 <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000"> | |
| 1254 Defined by VM vendor. | |
| 1255 </constant> | |
| 1256 <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000"> | |
| 1257 Defined by VM vendor. | |
| 1258 </constant> | |
| 1259 <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000"> | |
| 1260 Defined by VM vendor. | |
| 1261 </constant> | |
| 1262 </constants> | |
| 1263 The following definitions are used to convert <jvmti/> thread state | |
| 1264 to <code>java.lang.Thread.State</code> style states. | |
| 1265 <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits"> | |
| 1266 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK" | |
| 1267 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"> | |
| 1268 Mask the state with this before comparison | |
| 1269 </constant> | |
| 1270 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW" | |
| 1271 num="0"> | |
| 1272 <code>java.lang.Thread.State.NEW</code> | |
| 1273 </constant> | |
| 1274 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED" | |
| 1275 num="JVMTI_THREAD_STATE_TERMINATED"> | |
| 1276 <code>java.lang.Thread.State.TERMINATED</code> | |
| 1277 </constant> | |
| 1278 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE" | |
| 1279 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE"> | |
| 1280 <code>java.lang.Thread.State.RUNNABLE</code> | |
| 1281 </constant> | |
| 1282 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED" | |
| 1283 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"> | |
| 1284 <code>java.lang.Thread.State.BLOCKED</code> | |
| 1285 </constant> | |
| 1286 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING" | |
| 1287 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY"> | |
| 1288 <code>java.lang.Thread.State.WAITING</code> | |
| 1289 </constant> | |
| 1290 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING" | |
| 1291 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"> | |
| 1292 <code>java.lang.Thread.State.TIMED_WAITING</code> | |
| 1293 </constant> | |
| 1294 </constants> | |
| 1295 <b>Rules</b> | |
| 1296 <p/> | |
| 1297 There can be no more than one answer to a question, although there can be no | |
| 1298 answer (because the answer is unknown, does not apply, or none of the answers is | |
| 1299 correct). An answer is set only when the enclosing answers match. | |
| 1300 That is, no more than one of | |
| 1301 <ul type="circle"> | |
| 1302 <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li> | |
| 1303 <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li> | |
| 1304 <li><code>JVMTI_THREAD_STATE_WAITING</code></li> | |
| 1305 </ul> | |
| 1306 can be set (a <tm>J2SE</tm> compliant implementation will always set | |
| 1307 one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set). | |
| 1308 And if any of these are set, the enclosing answer | |
| 1309 <code>JVMTI_THREAD_STATE_ALIVE</code> is set. | |
| 1310 No more than one of | |
| 1311 <ul type="circle"> | |
| 1312 <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li> | |
| 1313 <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li> | |
| 1314 </ul> | |
| 1315 can be set (a <tm>J2SE</tm> compliant implementation will always set | |
| 1316 one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set). | |
| 1317 And if either is set, the enclosing answers | |
| 1318 <code>JVMTI_THREAD_STATE_ALIVE</code> and | |
| 1319 <code>JVMTI_THREAD_STATE_WAITING</code> are set. | |
| 1320 No more than one of | |
| 1321 <ul type="circle"> | |
| 1322 <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li> | |
| 1323 <li><code>JVMTI_THREAD_STATE_PARKED</code></li> | |
| 1324 <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li> | |
| 1325 </ul> | |
| 1326 can be set. And if any of these is set, the enclosing answers | |
| 1327 <code>JVMTI_THREAD_STATE_ALIVE</code> and | |
| 1328 <code>JVMTI_THREAD_STATE_WAITING</code> are set. | |
| 1329 Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set, | |
| 1330 then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set. | |
| 1331 If a state <i>A</i> is implemented using the mechanism of | |
| 1332 state <i>B</i> then it is state <i>A</i> which | |
| 1333 is returned by this function. | |
| 1334 For example, if <code>Thread.sleep(long)</code> | |
| 1335 is implemented using <code>Object.wait(long)</code> | |
| 1336 then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code> | |
| 1337 which is returned. | |
| 1338 More than one of | |
| 1339 <ul type="circle"> | |
| 1340 <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li> | |
| 1341 <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li> | |
| 1342 <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li> | |
| 1343 </ul> | |
| 1344 can be set, but if any is set, | |
| 1345 <code>JVMTI_THREAD_STATE_ALIVE</code> is set. | |
| 1346 <p/> | |
| 1347 And finally, | |
| 1348 <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless | |
| 1349 <code>JVMTI_THREAD_STATE_ALIVE</code> is not set. | |
| 1350 <p/> | |
| 1351 The thread state representation is designed for extension in future versions | |
| 1352 of the specification; thread state values should be used accordingly, that is | |
| 1353 they should not be used as ordinals. | |
| 1354 Most queries can be made by testing a single bit, if use in a switch statement is desired, | |
| 1355 the state bits should be masked with the interesting bits. | |
| 1356 All bits not defined above are reserved for future use. | |
| 1357 A VM, compliant to the current specification, must set reserved bits to zero. | |
| 1358 An agent should ignore reserved bits -- | |
| 1359 they should not be assumed to be zero and thus should not be included in comparisons. | |
| 1360 <p/> | |
| 1361 <b>Examples</b> | |
| 1362 <p/> | |
| 1363 Note that the values below exclude reserved and vendor bits. | |
| 1364 <p/> | |
| 1365 The state of a thread blocked at a <code>synchronized</code>-statement would be: | |
| 1366 <example> | |
| 1367 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | |
| 1368 </example> | |
| 1369 The state of a thread which hasn't started yet would be: | |
| 1370 <example> | |
| 1371 0 | |
| 1372 </example> | |
| 1373 The state of a thread at a <code>Object.wait(3000)</code> would be: | |
| 1374 <example> | |
| 1375 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING + | |
| 1376 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT + | |
| 1377 JVMTI_THREAD_STATE_MONITOR_WAITING | |
| 1378 </example> | |
| 1379 The state of a thread suspended while runnable would be: | |
| 1380 <example> | |
| 1381 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED | |
| 1382 </example> | |
| 1383 <p/> | |
| 1384 <b>Testing the State</b> | |
| 1385 <p/> | |
| 1386 In most cases, the thread state can be determined by testing the one bit corresponding | |
| 1387 to that question. For example, the code to test if a thread is sleeping: | |
| 1388 <example> | |
| 1389 jint state; | |
| 1390 jvmtiError err; | |
| 1391 | |
| 1392 err = (*jvmti)->GetThreadState(jvmti, thread, &state); | |
| 1393 if (err == JVMTI_ERROR_NONE) { | |
| 1394 if (state & JVMTI_THREAD_STATE_SLEEPING) { ... | |
| 1395 </example> | |
| 1396 <p/> | |
| 1397 For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be: | |
| 1398 <example> | |
| 1399 if (state & JVMTI_THREAD_STATE_WAITING) { ... | |
| 1400 </example> | |
| 1401 For some states, more than one bit will need to be tested as is the case | |
| 1402 when testing if a thread has not yet been started: | |
| 1403 <example> | |
| 1404 if ((state & (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0) { ... | |
| 1405 </example> | |
| 1406 To distinguish timed from untimed <code>Object.wait</code>: | |
| 1407 <example> | |
| 1408 if (state & JVMTI_THREAD_STATE_IN_OBJECT_WAIT) { | |
| 1409 if (state & JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT) { | |
| 1410 printf("in Object.wait(long timeout)\n"); | |
| 1411 } else { | |
| 1412 printf("in Object.wait()\n"); | |
| 1413 } | |
| 1414 } | |
| 1415 </example> | |
| 1416 <p/> | |
| 1417 <b>Relationship to <code>java.lang.Thread.State</code></b> | |
| 1418 <p/> | |
| 1419 The thread state represented by <code>java.lang.Thread.State</code> | |
| 1420 returned from <code>java.lang.Thread.getState()</code> is a subset of the | |
| 1421 information returned from this function. | |
| 1422 The corresponding <code>java.lang.Thread.State</code> can be determined | |
| 1423 by using the provided conversion masks. | |
| 1424 For example, this returns the name of the <code>java.lang.Thread.State</code> thread state: | |
| 1425 <example> | |
| 1426 err = (*jvmti)->GetThreadState(jvmti, thread, &state); | |
| 1427 abortOnError(err); | |
| 1428 switch (state & JVMTI_JAVA_LANG_THREAD_STATE_MASK) { | |
| 1429 case JVMTI_JAVA_LANG_THREAD_STATE_NEW: | |
| 1430 return "NEW"; | |
| 1431 case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED: | |
| 1432 return "TERMINATED"; | |
| 1433 case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE: | |
| 1434 return "RUNNABLE"; | |
| 1435 case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED: | |
| 1436 return "BLOCKED"; | |
| 1437 case JVMTI_JAVA_LANG_THREAD_STATE_WAITING: | |
| 1438 return "WAITING"; | |
| 1439 case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING: | |
| 1440 return "TIMED_WAITING"; | |
| 1441 } | |
| 1442 </example> | |
| 1443 </description> | |
| 1444 <origin>new</origin> | |
| 1445 <capabilities> | |
| 1446 </capabilities> | |
| 1447 <parameters> | |
| 1448 <param id="thread"> | |
| 1449 <jthread null="current" started="maybe" impl="noconvert"/> | |
| 1450 <description> | |
| 1451 The thread to query. | |
| 1452 </description> | |
| 1453 </param> | |
| 1454 <param id="thread_state_ptr"> | |
| 1455 <outptr><jint/></outptr> | |
| 1456 <description> | |
| 1457 On return, points to state flags, | |
| 1458 as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>. | |
| 1459 </description> | |
| 1460 </param> | |
| 1461 </parameters> | |
| 1462 <errors> | |
| 1463 </errors> | |
| 1464 </function> | |
| 1465 | |
| 1466 <function id="GetCurrentThread" phase="start" num="18" since="1.1"> | |
| 1467 <synopsis>Get Current Thread</synopsis> | |
| 1468 <description> | |
| 1469 Get the current thread. | |
| 1470 The current thread is the Java programming language thread which has called the function. | |
| 1471 <p/> | |
| 1472 Note that most <jvmti/> functions that take a thread | |
| 1473 as an argument will accept <code>NULL</code> to mean | |
| 1474 the current thread. | |
| 1475 </description> | |
| 1476 <origin>new</origin> | |
| 1477 <capabilities> | |
| 1478 </capabilities> | |
| 1479 <parameters> | |
| 1480 <param id="thread_ptr"> | |
| 1481 <outptr><jthread/></outptr> | |
| 1482 <description> | |
| 1483 On return, points to the current thread. | |
| 1484 </description> | |
| 1485 </param> | |
| 1486 </parameters> | |
| 1487 <errors> | |
| 1488 </errors> | |
| 1489 </function> | |
| 1490 | |
| 1491 <function id="GetAllThreads" num="4"> | |
| 1492 <synopsis>Get All Threads</synopsis> | |
| 1493 <description> | |
| 1494 Get all live threads. | |
| 1495 The threads are Java programming language threads; | |
| 1496 that is, threads that are attached to the VM. | |
| 1497 A thread is live if <code>java.lang.Thread.isAlive()</code> | |
| 1498 would return <code>true</code>, that is, the thread has | |
| 1499 been started and has not yet died. | |
| 1500 The universe of threads is determined by the context of the <jvmti/> | |
| 1501 environment, which typically is all threads attached to the VM. | |
| 1502 Note that this includes <jvmti/> agent threads | |
| 1503 (see <functionlink id="RunAgentThread"/>). | |
| 1504 </description> | |
| 1505 <origin>jvmdi</origin> | |
| 1506 <capabilities> | |
| 1507 </capabilities> | |
| 1508 <parameters> | |
| 1509 <param id="threads_count_ptr"> | |
| 1510 <outptr><jint/></outptr> | |
| 1511 <description> | |
| 1512 On return, points to the number of running threads. | |
| 1513 </description> | |
| 1514 </param> | |
| 1515 <param id="threads_ptr"> | |
| 1516 <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf> | |
| 1517 <description> | |
| 1518 On return, points to an array of references, one | |
| 1519 for each running thread. | |
| 1520 </description> | |
| 1521 </param> | |
| 1522 </parameters> | |
| 1523 <errors> | |
| 1524 </errors> | |
| 1525 </function> | |
| 1526 | |
| 1527 <function id="SuspendThread" num="5"> | |
| 1528 <synopsis>Suspend Thread</synopsis> | |
| 1529 <description> | |
| 1530 Suspend the specified thread. If the calling thread is specified, | |
| 1531 this function will not return until some other thread calls | |
| 1532 <functionlink id="ResumeThread"></functionlink>. | |
| 1533 If the thread is currently suspended, this function | |
| 1534 does nothing and returns an error. | |
| 1535 </description> | |
| 1536 <origin>jvmdi</origin> | |
| 1537 <capabilities> | |
| 1538 <required id="can_suspend"></required> | |
| 1539 </capabilities> | |
| 1540 <parameters> | |
| 1541 <param id="thread"> | |
| 1542 <jthread null="current"/> | |
| 1543 <description> | |
| 1544 The thread to suspend. | |
| 1545 </description> | |
| 1546 </param> | |
| 1547 </parameters> | |
| 1548 <errors> | |
| 1549 <error id="JVMTI_ERROR_THREAD_SUSPENDED"> | |
| 1550 Thread already suspended. | |
| 1551 </error> | |
| 1552 </errors> | |
| 1553 </function> | |
| 1554 | |
| 1555 <elide> | |
| 1556 <function id="SuspendAllThreads" num="101"> | |
| 1557 <synopsis>Suspend All Threads</synopsis> | |
| 1558 <description> | |
| 1559 <issue> | |
| 1560 There has been no explicit call for this function, and it will | |
| 1561 thus be removed if there is no interest. | |
| 1562 </issue> | |
| 1563 Suspend all live threads except: | |
| 1564 <ul> | |
| 1565 <li>already suspended threads</li> | |
| 1566 <li>those listed in <paramlink id="except_list"></paramlink></li> | |
| 1567 <li>certain system (non application) threads, as determined | |
| 1568 by the VM implementation</li> | |
| 1569 </ul> | |
| 1570 The threads are Java programming language threads; | |
| 1571 native threads which are not attached to the VM are not | |
| 1572 Java programming language threads. | |
| 1573 A thread is live if <code>java.lang.Thread.isAlive()</code> | |
| 1574 would return <code>true</code>, that is, the thread has | |
| 1575 been started and has not yet died. | |
| 1576 The universe of threads is determined | |
| 1577 by the context of the <jvmti/> | |
| 1578 environment, which, typically, is all threads attached to the VM, | |
| 1579 except critical VM internal threads and <jvmti/> agent threads | |
| 1580 (see <functionlink id="RunAgentThread"/>). | |
| 1581 <p/> | |
| 1582 If the calling thread is specified, | |
| 1583 all other threads are suspended first then the caller thread is suspended - | |
| 1584 this function will not return until some other thread calls | |
| 1585 <functionlink id="ResumeThread"></functionlink>. | |
| 1586 <p/> | |
| 1587 The list of actually | |
| 1588 suspended threads is returned in | |
| 1589 <paramlink id="suspended_list_ptr"></paramlink>. | |
| 1590 Suspension is as defined in <functionlink id="SuspendThread"></functionlink>. | |
| 1591 <functionlink id="ResumeThreadList"></functionlink> | |
| 1592 can be used to resume the suspended threads. | |
| 1593 </description> | |
| 1594 <origin>new</origin> | |
| 1595 <capabilities> | |
| 1596 <required id="can_suspend"></required> | |
| 1597 </capabilities> | |
| 1598 <parameters> | |
| 1599 <param id="except_count"> | |
| 1600 <jint min="0"/> | |
| 1601 <description> | |
| 1602 The number of threads in the list of threads not to be suspended. | |
| 1603 </description> | |
| 1604 </param> | |
| 1605 <param id="except_list"> | |
| 1606 <inbuf incount="except_count"> | |
| 1607 <jthread/> | |
| 1608 <nullok>not an error if <code>except_count == 0</code></nullok> | |
| 1609 </inbuf> | |
| 1610 <description> | |
| 1611 The list of threads not to be suspended. | |
| 1612 </description> | |
| 1613 </param> | |
| 1614 <param id="suspended_count_ptr"> | |
| 1615 <outptr><jint/></outptr> | |
| 1616 <description> | |
| 1617 On return, points to the number of threads suspended by this call. | |
| 1618 </description> | |
| 1619 </param> | |
| 1620 <param id="suspended_list_ptr"> | |
| 1621 <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf> | |
| 1622 <description> | |
| 1623 On return, points to an array of references, one | |
| 1624 for each thread suspended. | |
| 1625 </description> | |
| 1626 </param> | |
| 1627 </parameters> | |
| 1628 <errors> | |
| 1629 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
| 1630 A thread in <paramlink id="except_list"></paramlink> was invalid. | |
| 1631 </error> | |
| 1632 <error id="JVMTI_ERROR_NULL_POINTER"> | |
| 1633 Both <paramlink id="except_list"></paramlink> was <code>NULL</code> | |
| 1634 and <paramlink id="except_count"></paramlink> was non-zero. | |
| 1635 </error> | |
| 1636 </errors> | |
| 1637 </function> | |
| 1638 </elide> | |
| 1639 | |
| 1640 <function id="SuspendThreadList" num="92"> | |
| 1641 <synopsis>Suspend Thread List</synopsis> | |
| 1642 <description> | |
| 1643 Suspend the <paramlink id="request_count"></paramlink> | |
| 1644 threads specified in the | |
| 1645 <paramlink id="request_list"></paramlink> array. | |
| 1646 Threads may be resumed with | |
| 1647 <functionlink id="ResumeThreadList"></functionlink> or | |
| 1648 <functionlink id="ResumeThread"></functionlink>. | |
| 1649 If the calling thread is specified in the | |
| 1650 <paramlink id="request_list"></paramlink> array, this function will | |
| 1651 not return until some other thread resumes it. | |
| 1652 Errors encountered in the suspension of a thread | |
| 1653 are returned in the <paramlink id="results"></paramlink> | |
| 1654 array, <b>not</b> in the return value of this function. | |
| 1655 Threads that are currently suspended do not change state. | |
| 1656 </description> | |
| 1657 <origin>jvmdi</origin> | |
| 1658 <capabilities> | |
| 1659 <required id="can_suspend"></required> | |
| 1660 </capabilities> | |
| 1661 <parameters> | |
| 1662 <param id="request_count"> | |
| 1663 <jint min="0"/> | |
| 1664 <description> | |
| 1665 The number of threads to suspend. | |
| 1666 </description> | |
| 1667 </param> | |
| 1668 <param id="request_list"> | |
| 1669 <inbuf incount="request_count"><jthread/></inbuf> | |
| 1670 <description> | |
| 1671 The list of threads to suspend. | |
| 1672 </description> | |
| 1673 </param> | |
| 1674 <param id="results"> | |
| 1675 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> | |
| 1676 <description> | |
| 1677 An agent supplied array of | |
| 1678 <paramlink id="request_count"></paramlink> elements. | |
| 1679 On return, filled with the error code for | |
| 1680 the suspend of the corresponding thread. | |
| 1681 The error code will be | |
| 1682 <errorlink id="JVMTI_ERROR_NONE"></errorlink> | |
| 1683 if the thread was suspended by this call. | |
| 1684 Possible error codes are those specified | |
| 1685 for <functionlink id="SuspendThread"></functionlink>. | |
| 1686 </description> | |
| 1687 </param> | |
| 1688 </parameters> | |
| 1689 <errors> | |
| 1690 </errors> | |
| 1691 </function> | |
| 1692 | |
| 1693 <function id="ResumeThread" num="6"> | |
| 1694 <synopsis>Resume Thread</synopsis> | |
| 1695 <description> | |
| 1696 Resume a suspended thread. | |
| 1697 Any threads currently suspended through | |
| 1698 a <jvmti/> suspend function (eg. | |
| 1699 <functionlink id="SuspendThread"></functionlink>) | |
| 1700 or <code>java.lang.Thread.suspend()</code> | |
| 1701 will resume execution; | |
| 1702 all other threads are unaffected. | |
| 1703 </description> | |
| 1704 <origin>jvmdi</origin> | |
| 1705 <capabilities> | |
| 1706 <required id="can_suspend"></required> | |
| 1707 </capabilities> | |
| 1708 <parameters> | |
| 1709 <param id="thread"> | |
| 1710 <jthread/> | |
| 1711 <description> | |
| 1712 The thread to resume. | |
| 1713 </description> | |
| 1714 </param> | |
| 1715 </parameters> | |
| 1716 <errors> | |
| 1717 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 1718 Thread was not suspended. | |
| 1719 </error> | |
| 1720 <error id="JVMTI_ERROR_INVALID_TYPESTATE"> | |
| 1721 The state of the thread has been modified, and is now inconsistent. | |
| 1722 </error> | |
| 1723 </errors> | |
| 1724 </function> | |
| 1725 | |
| 1726 <function id="ResumeThreadList" num="93"> | |
| 1727 <synopsis>Resume Thread List</synopsis> | |
| 1728 <description> | |
| 1729 Resume the <paramlink id="request_count"></paramlink> | |
| 1730 threads specified in the | |
| 1731 <paramlink id="request_list"></paramlink> array. | |
| 1732 Any thread suspended through | |
| 1733 a <jvmti/> suspend function (eg. | |
| 1734 <functionlink id="SuspendThreadList"></functionlink>) | |
| 1735 or <code>java.lang.Thread.suspend()</code> | |
| 1736 will resume execution. | |
| 1737 </description> | |
| 1738 <origin>jvmdi</origin> | |
| 1739 <capabilities> | |
| 1740 <required id="can_suspend"></required> | |
| 1741 </capabilities> | |
| 1742 <parameters> | |
| 1743 <param id="request_count"> | |
| 1744 <jint min="0"/> | |
| 1745 <description> | |
| 1746 The number of threads to resume. | |
| 1747 </description> | |
| 1748 </param> | |
| 1749 <param id="request_list"> | |
| 1750 <inbuf incount="request_count"><jthread/></inbuf> | |
| 1751 <description> | |
| 1752 The threads to resume. | |
| 1753 </description> | |
| 1754 </param> | |
| 1755 <param id="results"> | |
| 1756 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> | |
| 1757 <description> | |
| 1758 An agent supplied array of | |
| 1759 <paramlink id="request_count"></paramlink> elements. | |
| 1760 On return, filled with the error code for | |
| 1761 the resume of the corresponding thread. | |
| 1762 The error code will be | |
| 1763 <errorlink id="JVMTI_ERROR_NONE"></errorlink> | |
| 1764 if the thread was suspended by this call. | |
| 1765 Possible error codes are those specified | |
| 1766 for <functionlink id="ResumeThread"></functionlink>. | |
| 1767 </description> | |
| 1768 </param> | |
| 1769 </parameters> | |
| 1770 <errors> | |
| 1771 </errors> | |
| 1772 </function> | |
| 1773 | |
| 1774 <function id="StopThread" num="7"> | |
| 1775 <synopsis>Stop Thread</synopsis> | |
| 1776 <description> | |
| 1777 Send the specified asynchronous exception to the specified thread | |
| 1778 (similar to <code>java.lang.Thread.stop</code>). | |
| 1779 Normally, this function is used to kill the specified thread with an | |
| 1780 instance of the exception <code>ThreadDeath</code>. | |
| 1781 </description> | |
| 1782 <origin>jvmdi</origin> | |
| 1783 <capabilities> | |
| 1784 <required id="can_signal_thread"></required> | |
| 1785 </capabilities> | |
| 1786 <parameters> | |
| 1787 <param id="thread"> | |
| 1788 <jthread/> | |
| 1789 <description> | |
| 1790 The thread to stop. | |
| 1791 </description> | |
| 1792 </param> | |
| 1793 <param id="exception"> | |
| 1794 <jobject/> | |
| 1795 <description> | |
| 1796 The asynchronous exception object. | |
| 1797 </description> | |
| 1798 </param> | |
| 1799 </parameters> | |
| 1800 <errors> | |
| 1801 </errors> | |
| 1802 </function> | |
| 1803 | |
| 1804 <function id="InterruptThread" num="8"> | |
| 1805 <synopsis>Interrupt Thread</synopsis> | |
| 1806 <description> | |
| 1807 Interrupt the specified thread | |
| 1808 (similar to <code>java.lang.Thread.interrupt</code>). | |
| 1809 </description> | |
| 1810 <origin>jvmdi</origin> | |
| 1811 <capabilities> | |
| 1812 <required id="can_signal_thread"></required> | |
| 1813 </capabilities> | |
| 1814 <parameters> | |
| 1815 <param id="thread"> | |
| 1816 <jthread impl="noconvert"/> | |
| 1817 <description> | |
| 1818 The thread to interrupt. | |
| 1819 </description> | |
| 1820 </param> | |
| 1821 </parameters> | |
| 1822 <errors> | |
| 1823 </errors> | |
| 1824 </function> | |
| 1825 | |
| 1826 <function id="GetThreadInfo" num="9"> | |
| 1827 <synopsis>Get Thread Info</synopsis> | |
| 1828 <typedef id="jvmtiThreadInfo" label="Thread information structure"> | |
| 1829 <field id="name"> | |
| 1830 <allocfieldbuf><char/></allocfieldbuf> | |
| 1831 <description> | |
| 1832 The thread name, encoded as a | |
| 1833 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 1834 </description> | |
| 1835 </field> | |
| 1836 <field id="priority"> | |
| 1837 <jint/> | |
| 1838 <description> | |
| 1839 The thread priority. See the thread priority constants: | |
| 1840 <datalink id="jvmtiThreadPriority"></datalink>. | |
| 1841 </description> | |
| 1842 </field> | |
| 1843 <field id="is_daemon"> | |
| 1844 <jboolean/> | |
| 1845 <description> | |
| 1846 Is this a daemon thread? | |
| 1847 </description> | |
| 1848 </field> | |
| 1849 <field id="thread_group"> | |
| 1850 <jthreadGroup/> | |
| 1851 <description> | |
| 1852 The thread group to which this thread belongs. | |
| 1853 <code>NULL</code> if the thread has died. | |
| 1854 </description> | |
| 1855 </field> | |
| 1856 <field id="context_class_loader"> | |
| 1857 <jobject/> | |
| 1858 <description> | |
| 1859 The context class loader associated with this thread. | |
| 1860 </description> | |
| 1861 </field> | |
| 1862 </typedef> | |
| 1863 <description> | |
| 1864 Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure | |
| 1865 are filled in with details of the specified thread. | |
| 1866 </description> | |
| 1867 <origin>jvmdi</origin> | |
| 1868 <capabilities> | |
| 1869 </capabilities> | |
| 1870 <parameters> | |
| 1871 <param id="thread"> | |
| 1872 <jthread null="current" impl="noconvert" started="maybe"/> | |
| 1873 <description> | |
| 1874 The thread to query. | |
| 1875 </description> | |
| 1876 </param> | |
| 1877 <param id="info_ptr"> | |
| 1878 <outptr><struct>jvmtiThreadInfo</struct></outptr> | |
| 1879 <description> | |
| 1880 On return, filled with information describing the specified thread. | |
| 1881 <p/> | |
| 1882 For JDK 1.1 implementations that don't | |
| 1883 recognize context class loaders, | |
| 1884 the <code>context_class_loader</code> field will be NULL. | |
| 1885 </description> | |
| 1886 </param> | |
| 1887 </parameters> | |
| 1888 <errors> | |
| 1889 </errors> | |
| 1890 </function> | |
| 1891 | |
| 1892 <function id="GetOwnedMonitorInfo" num="10"> | |
| 1893 <synopsis>Get Owned Monitor Info</synopsis> | |
| 1894 <description> | |
| 1895 Get information about the monitors owned by the | |
| 1896 specified thread. | |
| 1897 </description> | |
| 1898 <origin>jvmdiClone</origin> | |
| 1899 <capabilities> | |
| 1900 <required id="can_get_owned_monitor_info"></required> | |
| 1901 </capabilities> | |
| 1902 <parameters> | |
| 1903 <param id="thread"> | |
| 1904 <jthread null="current"/> | |
| 1905 <description> | |
| 1906 The thread to query. | |
| 1907 </description> | |
| 1908 </param> | |
| 1909 <param id="owned_monitor_count_ptr"> | |
| 1910 <outptr><jint/></outptr> | |
| 1911 <description> | |
| 1912 The number of monitors returned. | |
| 1913 </description> | |
| 1914 </param> | |
| 1915 <param id="owned_monitors_ptr"> | |
| 1916 <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf> | |
| 1917 <description> | |
| 1918 The array of owned monitors. | |
| 1919 </description> | |
| 1920 </param> | |
| 1921 </parameters> | |
| 1922 <errors> | |
| 1923 </errors> | |
| 1924 </function> | |
| 1925 | |
| 1926 <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1"> | |
| 1927 <synopsis>Get Owned Monitor Stack Depth Info</synopsis> | |
| 1928 <typedef id="jvmtiMonitorStackDepthInfo" | |
| 1929 label="Monitor stack depth information structure"> | |
| 1930 <field id="monitor"> | |
| 1931 <jobject/> | |
| 1932 <description> | |
| 1933 The owned monitor. | |
| 1934 </description> | |
| 1935 </field> | |
| 1936 <field id="stack_depth"> | |
| 1937 <jint/> | |
| 1938 <description> | |
| 1939 The stack depth. Corresponds to the stack depth used in the | |
| 1940 <internallink id="stack">Stack Frame functions</internallink>. | |
| 1941 That is, zero is the current frame, one is the frame which | |
| 1942 called the current frame. And it is negative one if the | |
| 1943 implementation cannot determine the stack depth (e.g., for | |
| 1944 monitors acquired by JNI <code>MonitorEnter</code>). | |
| 1945 </description> | |
| 1946 </field> | |
| 1947 </typedef> | |
| 1948 <description> | |
| 1949 Get information about the monitors owned by the | |
| 1950 specified thread and the depth of the stack frame which locked them. | |
| 1951 </description> | |
| 1952 <origin>new</origin> | |
| 1953 <capabilities> | |
| 1954 <required id="can_get_owned_monitor_stack_depth_info"></required> | |
| 1955 </capabilities> | |
| 1956 <parameters> | |
| 1957 <param id="thread"> | |
| 1958 <jthread null="current"/> | |
| 1959 <description> | |
| 1960 The thread to query. | |
| 1961 </description> | |
| 1962 </param> | |
| 1963 <param id="monitor_info_count_ptr"> | |
| 1964 <outptr><jint/></outptr> | |
| 1965 <description> | |
| 1966 The number of monitors returned. | |
| 1967 </description> | |
| 1968 </param> | |
| 1969 <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
|
1970 <allocbuf outcount="monitor_info_count_ptr"> |
| 0 | 1971 <struct>jvmtiMonitorStackDepthInfo</struct> |
| 1972 </allocbuf> | |
| 1973 <description> | |
| 1974 The array of owned monitor depth information. | |
| 1975 </description> | |
| 1976 </param> | |
| 1977 </parameters> | |
| 1978 <errors> | |
| 1979 </errors> | |
| 1980 </function> | |
| 1981 | |
| 1982 <function id="GetCurrentContendedMonitor" num="11"> | |
| 1983 <synopsis>Get Current Contended Monitor</synopsis> | |
| 1984 <description> | |
| 1985 Get the object, if any, whose monitor the specified thread is waiting to | |
| 1986 enter or waiting to regain through <code>java.lang.Object.wait</code>. | |
| 1987 </description> | |
| 1988 <origin>jvmdi</origin> | |
| 1989 <capabilities> | |
| 1990 <required id="can_get_current_contended_monitor"></required> | |
| 1991 </capabilities> | |
| 1992 <parameters> | |
| 1993 <param id="thread"> | |
| 1994 <jthread null="current"/> | |
| 1995 <description> | |
| 1996 The thread to query. | |
| 1997 </description> | |
| 1998 </param> | |
| 1999 <param id="monitor_ptr"> | |
| 2000 <outptr><jobject/></outptr> | |
| 2001 <description> | |
| 2002 On return, filled with the current contended monitor, or | |
| 2003 NULL if there is none. | |
| 2004 </description> | |
| 2005 </param> | |
| 2006 </parameters> | |
| 2007 <errors> | |
| 2008 </errors> | |
| 2009 </function> | |
| 2010 | |
| 2011 <callback id="jvmtiStartFunction"> | |
| 2012 <void/> | |
| 2013 <synopsis>Agent Start Function</synopsis> | |
| 2014 <description> | |
| 2015 Agent supplied callback function. | |
| 2016 This function is the entry point for an agent thread | |
| 2017 started with | |
| 2018 <functionlink id="RunAgentThread"></functionlink>. | |
| 2019 </description> | |
| 2020 <parameters> | |
| 2021 <param id="jvmti_env"> | |
| 2022 <outptr> | |
| 2023 <struct>jvmtiEnv</struct> | |
| 2024 </outptr> | |
| 2025 <description> | |
| 2026 The <jvmti/> environment. | |
| 2027 </description> | |
| 2028 </param> | |
| 2029 <param id="jni_env"> | |
| 2030 <outptr> | |
| 2031 <struct>JNIEnv</struct> | |
| 2032 </outptr> | |
| 2033 <description> | |
| 2034 The JNI environment. | |
| 2035 </description> | |
| 2036 </param> | |
| 2037 <param id="arg"> | |
| 2038 <outptr> | |
| 2039 <void/> | |
| 2040 </outptr> | |
| 2041 <description> | |
| 2042 The <code>arg</code> parameter passed to | |
| 2043 <functionlink id="RunAgentThread"></functionlink>. | |
| 2044 </description> | |
| 2045 </param> | |
| 2046 </parameters> | |
| 2047 </callback> | |
| 2048 | |
| 2049 <function id="RunAgentThread" num="12"> | |
| 2050 <synopsis>Run Agent Thread</synopsis> | |
| 2051 <description> | |
| 2052 Starts the execution of an agent thread. with the specified native function. | |
| 2053 The parameter <paramlink id="arg"></paramlink> is forwarded on to the | |
| 2054 <functionlink id="jvmtiStartFunction">start function</functionlink> | |
| 2055 (specified with <paramlink id="proc"></paramlink>) as its single argument. | |
| 2056 This function allows the creation of agent threads | |
| 2057 for handling communication with another process or for handling events | |
| 2058 without the need to load a special subclass of <code>java.lang.Thread</code> or | |
| 2059 implementer of <code>java.lang.Runnable</code>. | |
| 2060 Instead, the created thread can run entirely in native code. | |
| 2061 However, the created thread does require a newly created instance | |
| 2062 of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to | |
| 2063 which it will be associated. | |
| 2064 The thread object can be created with JNI calls. | |
| 2065 <p/> | |
| 2066 The following common thread priorities are provided for your convenience: | |
| 2067 <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const"> | |
| 2068 <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1"> | |
| 2069 Minimum possible thread priority | |
| 2070 </constant> | |
| 2071 <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5"> | |
| 2072 Normal thread priority | |
| 2073 </constant> | |
| 2074 <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10"> | |
| 2075 Maximum possible thread priority | |
| 2076 </constant> | |
| 2077 </constants> | |
| 2078 <p/> | |
| 2079 The new thread is started as a daemon thread with the specified | |
| 2080 <paramlink id="priority"></paramlink>. | |
| 2081 If enabled, a <eventlink id="ThreadStart"/> event will be sent. | |
| 2082 <p/> | |
| 2083 Since the thread has been started, the thread will be live when this function | |
| 2084 returns, unless the thread has died immediately. | |
| 2085 <p/> | |
| 2086 The thread group of the thread is ignored -- specifically, the thread is not | |
| 2087 added to the thread group and the thread is not seen on queries of the thread | |
| 2088 group at either the Java programming language or <jvmti/> levels. | |
| 2089 <p/> | |
| 2090 The thread is not visible to Java programming language queries but is | |
| 2091 included in <jvmti/> queries (for example, | |
| 2092 <functionlink id="GetAllThreads"/> and | |
| 2093 <functionlink id="GetAllStackTraces"/>). | |
| 2094 <p/> | |
| 2095 Upon execution of <code>proc</code>, the new thread will be attached to the | |
| 2096 VM--see the JNI documentation on | |
| 6919 | 2097 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#wp1060" |
| 0 | 2098 >Attaching to the VM</externallink>. |
| 2099 </description> | |
| 2100 <origin>jvmdiClone</origin> | |
| 2101 <capabilities> | |
| 2102 </capabilities> | |
| 2103 <parameters> | |
| 2104 <param id="thread"> | |
| 2105 <jthread impl="noconvert" started="no"/> | |
| 2106 <description> | |
| 2107 The thread to run. | |
| 2108 </description> | |
| 2109 </param> | |
| 2110 <param id="proc"> | |
| 2111 <ptrtype> | |
| 2112 <struct>jvmtiStartFunction</struct> | |
| 2113 </ptrtype> | |
| 2114 <description> | |
| 2115 The start function. | |
| 2116 </description> | |
| 2117 </param> | |
| 2118 <param id="arg"> | |
| 2119 <inbuf> | |
| 2120 <void/> | |
| 2121 <nullok><code>NULL</code> is passed to the start function</nullok> | |
| 2122 </inbuf> | |
| 2123 <description> | |
| 2124 The argument to the start function. | |
| 2125 </description> | |
| 2126 </param> | |
| 2127 <param id="priority"> | |
| 2128 <jint/> | |
| 2129 <description> | |
| 2130 The priority of the started thread. Any thread | |
| 2131 priority allowed by <code>java.lang.Thread.setPriority</code> can be used including | |
| 2132 those in <datalink id="jvmtiThreadPriority"></datalink>. | |
| 2133 </description> | |
| 2134 </param> | |
| 2135 </parameters> | |
| 2136 <errors> | |
| 2137 <error id="JVMTI_ERROR_INVALID_PRIORITY"> | |
| 2138 <paramlink id="priority"/> is less than | |
| 2139 <datalink id="JVMTI_THREAD_MIN_PRIORITY"/> | |
| 2140 or greater than | |
| 2141 <datalink id="JVMTI_THREAD_MAX_PRIORITY"/> | |
| 2142 </error> | |
| 2143 </errors> | |
| 2144 </function> | |
| 2145 | |
| 2146 <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103"> | |
| 2147 <synopsis>Set Thread Local Storage</synopsis> | |
| 2148 <description> | |
| 2149 The VM stores a pointer value associated with each environment-thread | |
| 2150 pair. This pointer value is called <i>thread-local storage</i>. | |
| 2151 This value is <code>NULL</code> unless set with this function. | |
| 2152 Agents can allocate memory in which they store thread specific | |
| 2153 information. By setting thread-local storage it can then be | |
| 2154 accessed with | |
| 2155 <functionlink id="GetThreadLocalStorage"></functionlink>. | |
| 2156 <p/> | |
| 2157 This function is called by the agent to set the value of the <jvmti/> | |
| 2158 thread-local storage. <jvmti/> supplies to the agent a pointer-size | |
| 2159 thread-local storage that can be used to record per-thread | |
| 2160 information. | |
| 2161 </description> | |
| 2162 <origin>jvmpi</origin> | |
| 2163 <capabilities> | |
| 2164 </capabilities> | |
| 2165 <parameters> | |
| 2166 <param id="thread"> | |
| 2167 <jthread null="current"/> | |
| 2168 <description> | |
| 2169 Store to this thread. | |
| 2170 </description> | |
| 2171 </param> | |
| 2172 <param id="data"> | |
| 2173 <inbuf> | |
| 2174 <void/> | |
| 2175 <nullok>value is set to <code>NULL</code></nullok> | |
| 2176 </inbuf> | |
| 2177 <description> | |
| 2178 The value to be entered into the thread-local storage. | |
| 2179 </description> | |
| 2180 </param> | |
| 2181 </parameters> | |
| 2182 <errors> | |
| 2183 </errors> | |
| 2184 </function> | |
| 2185 | |
| 2186 <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102"> | |
| 2187 <synopsis>Get Thread Local Storage</synopsis> | |
| 2188 <description> | |
| 2189 Called by the agent to get the value of the <jvmti/> thread-local | |
| 2190 storage. | |
| 2191 </description> | |
| 2192 <origin>jvmpi</origin> | |
| 2193 <capabilities> | |
| 2194 </capabilities> | |
| 2195 <parameters> | |
| 2196 <param id="thread"> | |
| 2197 <jthread null="current" impl="noconvert"/> | |
| 2198 <description> | |
| 2199 Retrieve from this thread. | |
| 2200 </description> | |
| 2201 </param> | |
| 2202 <param id="data_ptr"> | |
| 2203 <agentbuf><void/></agentbuf> | |
| 2204 <description> | |
| 2205 Pointer through which the value of the thread local | |
| 2206 storage is returned. | |
| 2207 If thread-local storage has not been set with | |
| 2208 <functionlink id="SetThreadLocalStorage"></functionlink> the returned | |
| 2209 pointer is <code>NULL</code>. | |
| 2210 </description> | |
| 2211 </param> | |
| 2212 </parameters> | |
| 2213 <errors> | |
| 2214 </errors> | |
| 2215 </function> | |
| 2216 | |
| 2217 </category> | |
| 2218 | |
| 2219 <category id="thread_groups" label="Thread Group"> | |
| 2220 <intro> | |
| 2221 </intro> | |
| 2222 | |
| 2223 <function id="GetTopThreadGroups" num="13"> | |
| 2224 <synopsis>Get Top Thread Groups</synopsis> | |
| 2225 <description> | |
| 2226 Return all top-level (parentless) thread groups in the VM. | |
| 2227 </description> | |
| 2228 <origin>jvmdi</origin> | |
| 2229 <capabilities> | |
| 2230 </capabilities> | |
| 2231 <parameters> | |
| 2232 <param id="group_count_ptr"> | |
| 2233 <outptr><jint/></outptr> | |
| 2234 <description> | |
| 2235 On return, points to the number of top-level thread groups. | |
| 2236 </description> | |
| 2237 </param> | |
| 2238 <param id="groups_ptr"> | |
| 2239 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> | |
| 2240 <description> | |
| 2241 On return, refers to a pointer to the top-level thread group array. | |
| 2242 </description> | |
| 2243 </param> | |
| 2244 </parameters> | |
| 2245 <errors> | |
| 2246 </errors> | |
| 2247 </function> | |
| 2248 | |
| 2249 <function id="GetThreadGroupInfo" num="14"> | |
| 2250 <synopsis>Get Thread Group Info</synopsis> | |
| 2251 <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure"> | |
| 2252 <field id="parent"> | |
| 2253 <jthreadGroup/> | |
| 2254 <description> | |
| 2255 The parent thread group. | |
| 2256 </description> | |
| 2257 </field> | |
| 2258 <field id="name"> | |
| 2259 <allocfieldbuf><char/></allocfieldbuf> | |
| 2260 <description> | |
| 2261 The thread group's name, encoded as a | |
| 2262 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 2263 </description> | |
| 2264 </field> | |
| 2265 <field id="max_priority"> | |
| 2266 <jint/> | |
| 2267 <description> | |
| 2268 The maximum priority for this thread group. | |
| 2269 </description> | |
| 2270 </field> | |
| 2271 <field id="is_daemon"> | |
| 2272 <jboolean/> | |
| 2273 <description> | |
| 2274 Is this a daemon thread group? | |
| 2275 </description> | |
| 2276 </field> | |
| 2277 </typedef> | |
| 2278 <description> | |
| 2279 Get information about the thread group. The fields of the | |
| 2280 <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure | |
| 2281 are filled in with details of the specified thread group. | |
| 2282 </description> | |
| 2283 <origin>jvmdi</origin> | |
| 2284 <capabilities> | |
| 2285 </capabilities> | |
| 2286 <parameters> | |
| 2287 <param id="group"> | |
| 2288 <jthreadGroup/> | |
| 2289 <description> | |
| 2290 The thread group to query. | |
| 2291 </description> | |
| 2292 </param> | |
| 2293 <param id="info_ptr"> | |
| 2294 <outptr><struct>jvmtiThreadGroupInfo</struct></outptr> | |
| 2295 <description> | |
| 2296 On return, filled with information describing the specified | |
| 2297 thread group. | |
| 2298 </description> | |
| 2299 </param> | |
| 2300 </parameters> | |
| 2301 <errors> | |
| 2302 </errors> | |
| 2303 </function> | |
| 2304 | |
| 2305 <function id="GetThreadGroupChildren" num="15"> | |
| 2306 <synopsis>Get Thread Group Children</synopsis> | |
| 2307 <description> | |
| 2308 Get the live threads and active subgroups in this thread group. | |
| 2309 </description> | |
| 2310 <origin>jvmdi</origin> | |
| 2311 <capabilities> | |
| 2312 </capabilities> | |
| 2313 <parameters> | |
| 2314 <param id="group"> | |
| 2315 <jthreadGroup/> | |
| 2316 <description> | |
| 2317 The group to query. | |
| 2318 </description> | |
| 2319 </param> | |
| 2320 <param id="thread_count_ptr"> | |
| 2321 <outptr><jint/></outptr> | |
| 2322 <description> | |
| 2323 On return, points to the number of live threads in this thread group. | |
| 2324 </description> | |
| 2325 </param> | |
| 2326 <param id="threads_ptr"> | |
| 2327 <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf> | |
| 2328 <description> | |
| 2329 On return, points to an array of the live threads in this thread group. | |
| 2330 </description> | |
| 2331 </param> | |
| 2332 <param id="group_count_ptr"> | |
| 2333 <outptr><jint/></outptr> | |
| 2334 <description> | |
| 2335 On return, points to the number of active child thread groups | |
| 2336 </description> | |
| 2337 </param> | |
| 2338 <param id="groups_ptr"> | |
| 2339 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> | |
| 2340 <description> | |
| 2341 On return, points to an array of the active child thread groups. | |
| 2342 </description> | |
| 2343 </param> | |
| 2344 </parameters> | |
| 2345 <errors> | |
| 2346 </errors> | |
| 2347 </function> | |
| 2348 </category> | |
| 2349 | |
| 2350 <category id="stack" label="Stack Frame"> | |
| 2351 <intro> | |
| 2352 These functions provide information about the stack of a thread. | |
| 2353 Stack frames are referenced by depth. | |
| 2354 The frame at depth zero is the current frame. | |
| 2355 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
2356 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
|
2357 <vmspec chapter="3.6"/>, |
| 0 | 2358 That is, they correspond to method |
| 2359 invocations (including native methods) but do not correspond to platform native or | |
| 2360 VM internal frames. | |
| 2361 <p/> | |
| 2362 A <jvmti/> implementation may use method invocations to launch a thread and | |
| 2363 the corresponding frames may be included in the stack as presented by these functions -- | |
| 2364 that is, there may be frames shown | |
| 2365 deeper than <code>main()</code> and <code>run()</code>. | |
| 2366 However this presentation must be consistent across all <jvmti/> functionality which | |
| 2367 uses stack frames or stack depth. | |
| 2368 </intro> | |
| 2369 | |
| 2370 <typedef id="jvmtiFrameInfo" label="Stack frame information structure"> | |
| 2371 <description> | |
| 2372 Information about a stack frame is returned in this structure. | |
| 2373 </description> | |
| 2374 <field id="method"> | |
| 2375 <jmethodID/> | |
| 2376 <description> | |
| 2377 The method executing in this frame. | |
| 2378 </description> | |
| 2379 </field> | |
| 2380 <field id="location"> | |
| 2381 <jlocation/> | |
| 2382 <description> | |
| 2383 The index of the instruction executing in this frame. | |
| 2384 <code>-1</code> if the frame is executing a native method. | |
| 2385 </description> | |
| 2386 </field> | |
| 2387 </typedef> | |
| 2388 | |
| 2389 <typedef id="jvmtiStackInfo" label="Stack information structure"> | |
| 2390 <description> | |
| 2391 Information about a set of stack frames is returned in this structure. | |
| 2392 </description> | |
| 2393 <field id="thread"> | |
| 2394 <jthread/> | |
| 2395 <description> | |
| 2396 On return, the thread traced. | |
| 2397 </description> | |
| 2398 </field> | |
| 2399 <field id="state"> | |
| 2400 <jint/> | |
| 2401 <description> | |
| 2402 On return, the thread state. See <functionlink id="GetThreadState"></functionlink>. | |
| 2403 </description> | |
| 2404 </field> | |
| 2405 <field id="frame_buffer"> | |
| 2406 <outbuf incount="max_frame_count"> | |
| 2407 <struct>jvmtiFrameInfo</struct> | |
| 2408 </outbuf> | |
| 2409 <description> | |
| 2410 On return, this agent allocated buffer is filled | |
| 2411 with stack frame information. | |
| 2412 </description> | |
| 2413 </field> | |
| 2414 <field id="frame_count"> | |
| 2415 <jint/> | |
| 2416 <description> | |
| 2417 On return, the number of records filled into | |
| 2418 <code>frame_buffer</code>. | |
| 2419 This will be | |
| 2420 min(<code>max_frame_count</code>, <i>stackDepth</i>). | |
| 2421 </description> | |
| 2422 </field> | |
| 2423 </typedef> | |
| 2424 | |
| 2425 <function id="GetStackTrace" num="104"> | |
| 2426 <synopsis>Get Stack Trace</synopsis> | |
| 2427 <description> | |
| 2428 Get information about the stack of a thread. | |
| 2429 If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack, | |
| 2430 the <paramlink id="max_frame_count"></paramlink> topmost frames are returned, | |
| 2431 otherwise the entire stack is returned. | |
| 2432 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
| 2433 <p/> | |
| 2434 The following example causes up to five of the topmost frames | |
| 2435 to be returned and (if there are any frames) the currently | |
| 2436 executing method name to be printed. | |
| 2437 <example> | |
| 2438 jvmtiFrameInfo frames[5]; | |
| 2439 jint count; | |
| 2440 jvmtiError err; | |
| 2441 | |
| 2442 err = (*jvmti)->GetStackTrace(jvmti, aThread, 0, 5, | |
|
7168
73e64867adb7
8003690: Example code in JVMTI GetStackTrace documentation is broken
mikael
parents:
6919
diff
changeset
|
2443 frames, &count); |
| 0 | 2444 if (err == JVMTI_ERROR_NONE && count >= 1) { |
| 2445 char *methodName; | |
| 2446 err = (*jvmti)->GetMethodName(jvmti, frames[0].method, | |
|
7168
73e64867adb7
8003690: Example code in JVMTI GetStackTrace documentation is broken
mikael
parents:
6919
diff
changeset
|
2447 &methodName, NULL, NULL); |
| 0 | 2448 if (err == JVMTI_ERROR_NONE) { |
| 2449 printf("Executing method: %s", methodName); | |
| 2450 } | |
| 2451 } | |
| 2452 </example> | |
| 2453 <todo> | |
| 2454 check example code. | |
| 2455 </todo> | |
| 2456 <p/> | |
| 2457 The <paramlink id="thread"></paramlink> need not be suspended | |
| 2458 to call this function. | |
| 2459 <p/> | |
| 2460 The <functionlink id="GetLineNumberTable"></functionlink> | |
| 2461 function can be used to map locations to line numbers. Note that | |
| 2462 this mapping can be done lazily. | |
| 2463 </description> | |
| 2464 <origin>jvmpi</origin> | |
| 2465 <capabilities> | |
| 2466 </capabilities> | |
| 2467 <parameters> | |
| 2468 <param id="thread"> | |
| 2469 <jthread null="current"/> | |
| 2470 <description> | |
| 2471 Fetch the stack trace of this thread. | |
| 2472 </description> | |
| 2473 </param> | |
| 2474 <param id="start_depth"> | |
| 2475 <jint/> | |
| 2476 <description> | |
| 2477 Begin retrieving frames at this depth. | |
| 2478 If non-negative, count from the current frame, | |
| 2479 the first frame retrieved is at depth <code>start_depth</code>. | |
| 2480 For example, if zero, start from the current frame; if one, start from the | |
| 2481 caller of the current frame; if two, start from the caller of the | |
| 2482 caller of the current frame; and so on. | |
| 2483 If negative, count from below the oldest frame, | |
| 2484 the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>, | |
| 2485 where <i>stackDepth</i> is the count of frames on the stack. | |
| 2486 For example, if negative one, only the oldest frame is retrieved; | |
| 2487 if negative two, start from the frame called by the oldest frame. | |
| 2488 </description> | |
| 2489 </param> | |
| 2490 <param id="max_frame_count"> | |
| 2491 <jint min="0"/> | |
| 2492 <description> | |
| 2493 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. | |
| 2494 </description> | |
| 2495 </param> | |
| 2496 <param id="frame_buffer"> | |
| 2497 <outbuf incount="max_frame_count" outcount="count_ptr"> | |
| 2498 <struct>jvmtiFrameInfo</struct> | |
| 2499 </outbuf> | |
| 2500 <description> | |
| 2501 On return, this agent allocated buffer is filled | |
| 2502 with stack frame information. | |
| 2503 </description> | |
| 2504 </param> | |
| 2505 <param id="count_ptr"> | |
| 2506 <outptr><jint/></outptr> | |
| 2507 <description> | |
| 2508 On return, points to the number of records filled in. | |
| 2509 For non-negative <code>start_depth</code>, this will be | |
| 2510 min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>). | |
| 2511 For negative <code>start_depth</code>, this will be | |
| 2512 min(<code>max_frame_count</code>, <code>-start_depth</code>). | |
| 2513 </description> | |
| 2514 </param> | |
| 2515 </parameters> | |
| 2516 <errors> | |
| 2517 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 2518 <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>. | |
| 2519 Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>. | |
| 2520 </error> | |
| 2521 </errors> | |
| 2522 </function> | |
| 2523 | |
| 2524 | |
| 2525 <function id="GetAllStackTraces" num="100"> | |
| 2526 <synopsis>Get All Stack Traces</synopsis> | |
| 2527 <description> | |
| 2528 Get information about the stacks of all live threads | |
| 2529 (including <internallink id="RunAgentThread">agent threads</internallink>). | |
| 2530 If <paramlink id="max_frame_count"/> is less than the depth of a stack, | |
| 2531 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, | |
| 2532 otherwise the entire stack is returned. | |
| 2533 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
| 2534 <p/> | |
| 2535 All stacks are collected simultaneously, that is, no changes will occur to the | |
| 2536 thread state or stacks between the sampling of one thread and the next. | |
| 2537 The threads need not be suspended. | |
| 2538 | |
| 2539 <example> | |
| 2540 jvmtiStackInfo *stack_info; | |
| 2541 jint thread_count; | |
| 2542 int ti; | |
| 2543 jvmtiError err; | |
| 2544 | |
| 2545 err = (*jvmti)->GetAllStackTraces(jvmti, MAX_FRAMES, &stack_info, &thread_count); | |
| 2546 if (err != JVMTI_ERROR_NONE) { | |
| 2547 ... | |
| 2548 } | |
| 2549 for (ti = 0; ti < thread_count; ++ti) { | |
| 2550 jvmtiStackInfo *infop = &stack_info[ti]; | |
| 2551 jthread thread = infop->thread; | |
| 2552 jint state = infop->state; | |
| 2553 jvmtiFrameInfo *frames = infop->frame_buffer; | |
| 2554 int fi; | |
| 2555 | |
| 2556 myThreadAndStatePrinter(thread, state); | |
| 2557 for (fi = 0; fi < infop->frame_count; fi++) { | |
| 2558 myFramePrinter(frames[fi].method, frames[fi].location); | |
| 2559 } | |
| 2560 } | |
| 2561 /* this one Deallocate call frees all data allocated by GetAllStackTraces */ | |
| 2562 err = (*jvmti)->Deallocate(jvmti, stack_info); | |
| 2563 </example> | |
| 2564 <todo> | |
| 2565 check example code. | |
| 2566 </todo> | |
| 2567 | |
| 2568 </description> | |
| 2569 <origin>new</origin> | |
| 2570 <capabilities> | |
| 2571 </capabilities> | |
| 2572 <parameters> | |
| 2573 <param id="max_frame_count"> | |
| 2574 <jint min="0"/> | |
| 2575 <description> | |
| 2576 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. | |
| 2577 </description> | |
| 2578 </param> | |
| 2579 <param id="stack_info_ptr"> | |
| 2580 <allocbuf> | |
| 2581 <struct>jvmtiStackInfo</struct> | |
| 2582 </allocbuf> | |
| 2583 <description> | |
| 2584 On return, this buffer is filled | |
| 2585 with stack information for each thread. | |
| 2586 The number of <datalink id="jvmtiStackInfo"/> records is determined | |
| 2587 by <paramlink id="thread_count_ptr"/>. | |
| 2588 <p/> | |
| 2589 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> | |
| 2590 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. | |
| 2591 These buffers must not be separately deallocated. | |
| 2592 </description> | |
| 2593 </param> | |
| 2594 <param id="thread_count_ptr"> | |
| 2595 <outptr><jint/></outptr> | |
| 2596 <description> | |
| 2597 The number of threads traced. | |
| 2598 </description> | |
| 2599 </param> | |
| 2600 </parameters> | |
| 2601 <errors> | |
| 2602 </errors> | |
| 2603 </function> | |
| 2604 | |
| 2605 <function id="GetThreadListStackTraces" num="101"> | |
| 2606 <synopsis>Get Thread List Stack Traces</synopsis> | |
| 2607 <description> | |
| 2608 Get information about the stacks of the supplied threads. | |
| 2609 If <paramlink id="max_frame_count"/> is less than the depth of a stack, | |
| 2610 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, | |
| 2611 otherwise the entire stack is returned. | |
| 2612 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
| 2613 <p/> | |
| 2614 All stacks are collected simultaneously, that is, no changes will occur to the | |
| 2615 thread state or stacks between the sampling one thread and the next. | |
| 2616 The threads need not be suspended. | |
| 2617 <p/> | |
| 2618 If a thread has not yet started or terminates before the stack information is collected, | |
| 2619 a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero) | |
| 2620 will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked. | |
| 2621 <p/> | |
| 2622 See the example for the similar function | |
| 2623 <functionlink id="GetAllStackTraces"/>. | |
| 2624 </description> | |
| 2625 <origin>new</origin> | |
| 2626 <capabilities> | |
| 2627 </capabilities> | |
| 2628 <parameters> | |
| 2629 <param id="thread_count"> | |
| 2630 <jint min="0"/> | |
| 2631 <description> | |
| 2632 The number of threads to trace. | |
| 2633 </description> | |
| 2634 </param> | |
| 2635 <param id="thread_list"> | |
| 2636 <inbuf incount="thread_count"><jthread/></inbuf> | |
| 2637 <description> | |
| 2638 The list of threads to trace. | |
| 2639 </description> | |
| 2640 </param> | |
| 2641 <param id="max_frame_count"> | |
| 2642 <jint min="0"/> | |
| 2643 <description> | |
| 2644 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. | |
| 2645 </description> | |
| 2646 </param> | |
| 2647 <param id="stack_info_ptr"> | |
| 2648 <allocbuf outcount="thread_count"> | |
| 2649 <struct>jvmtiStackInfo</struct> | |
| 2650 </allocbuf> | |
| 2651 <description> | |
| 2652 On return, this buffer is filled | |
| 2653 with stack information for each thread. | |
| 2654 The number of <datalink id="jvmtiStackInfo"/> records is determined | |
| 2655 by <paramlink id="thread_count"/>. | |
| 2656 <p/> | |
| 2657 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> | |
| 2658 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. | |
| 2659 These buffers must not be separately deallocated. | |
| 2660 </description> | |
| 2661 </param> | |
| 2662 </parameters> | |
| 2663 <errors> | |
| 2664 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
| 2665 An element in <paramlink id="thread_list"/> is not a thread object. | |
| 2666 </error> | |
| 2667 </errors> | |
| 2668 </function> | |
| 2669 | |
| 2670 <elide> | |
| 2671 <function id="AsyncGetStackTrace" num="1000"> | |
| 2672 <synopsis>Get Stack Trace--Asynchronous</synopsis> | |
| 2673 <description> | |
| 2674 Get information about the entire stack of a thread (or a sub-section of it). | |
| 2675 This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink> | |
| 2676 and is reentrant and safe to call | |
| 2677 from asynchronous signal handlers. | |
| 2678 The stack trace is returned only for the calling thread. | |
| 2679 <p/> | |
| 2680 The <functionlink id="GetLineNumberTable"></functionlink> | |
| 2681 function can be used to map locations to line numbers. Note that | |
| 2682 this mapping can be done lazily. | |
| 2683 </description> | |
| 2684 <origin>jvmpi</origin> | |
| 2685 <capabilities> | |
| 2686 <required id="can_get_async_stack_trace"></required> | |
| 2687 <capability id="can_show_JVM_spec_async_frames"> | |
| 2688 If <code>false</code>, | |
| 2689 <paramlink id="use_java_stack"></paramlink> | |
| 2690 must be <code>false</code>. | |
| 2691 </capability> | |
| 2692 </capabilities> | |
| 2693 <parameters> | |
| 2694 <param id="use_java_stack"> | |
| 2695 <jboolean/> | |
| 2696 <description> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
2697 Return the stack showing <vmspec/> |
| 0 | 2698 model of the stack; |
| 2699 otherwise, show the internal representation of the stack with | |
| 2700 inlined and optimized methods missing. If the virtual machine | |
| 2701 is using the <i>Java Virtual Machine Specification</i> stack model | |
| 2702 internally, this flag is ignored. | |
| 2703 </description> | |
| 2704 </param> | |
| 2705 <param id="max_count"> | |
| 2706 <jint min="0"/> | |
| 2707 <description> | |
| 2708 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. | |
| 2709 Retrieve this many unless the stack depth is less than <code>max_count</code>. | |
| 2710 </description> | |
| 2711 </param> | |
| 2712 <param id="frame_buffer"> | |
| 2713 <outbuf incount="max_count" outcount="count_ptr"> | |
| 2714 <struct>jvmtiFrameInfo</struct> | |
| 2715 <nullok>this information is not returned</nullok> | |
| 2716 </outbuf> | |
| 2717 <description> | |
| 2718 The agent passes in a buffer | |
| 2719 large enough to hold <code>max_count</code> records of | |
| 2720 <datalink id="jvmtiFrameInfo"></datalink>. This buffer must be | |
| 2721 pre-allocated by the agent. | |
| 2722 </description> | |
| 2723 </param> | |
| 2724 <param id="count_ptr"> | |
| 2725 <outptr><jint/></outptr> | |
| 2726 <description> | |
| 2727 On return, points to the number of records filled in.. | |
| 2728 </description> | |
| 2729 </param> | |
| 2730 </parameters> | |
| 2731 <errors> | |
| 2732 <error id="JVMTI_ERROR_UNATTACHED_THREAD"> | |
| 2733 The thread being used to call this function is not attached | |
| 2734 to the virtual machine. Calls must be made from attached threads. | |
| 2735 </error> | |
| 2736 </errors> | |
| 2737 </function> | |
| 2738 </elide> | |
| 2739 | |
| 2740 <function id="GetFrameCount" num="16"> | |
| 2741 <synopsis>Get Frame Count</synopsis> | |
| 2742 <description> | |
| 2743 Get the number of frames currently in the specified thread's call stack. | |
| 2744 <p/> | |
| 2745 If this function is called for a thread actively executing bytecodes (for example, | |
| 2746 not the current thread and not suspended), the information returned is transient. | |
| 2747 </description> | |
| 2748 <origin>jvmdi</origin> | |
| 2749 <capabilities> | |
| 2750 </capabilities> | |
| 2751 <parameters> | |
| 2752 <param id="thread"> | |
| 2753 <jthread null="current"/> | |
| 2754 <description> | |
| 2755 The thread to query. | |
| 2756 </description> | |
| 2757 </param> | |
| 2758 <param id="count_ptr"> | |
| 2759 <outptr><jint/></outptr> | |
| 2760 <description> | |
| 2761 On return, points to the number of frames in the call stack. | |
| 2762 </description> | |
| 2763 </param> | |
| 2764 </parameters> | |
| 2765 <errors> | |
| 2766 </errors> | |
| 2767 </function> | |
| 2768 | |
| 2769 <function id="PopFrame" num="80"> | |
| 2770 <synopsis>Pop Frame</synopsis> | |
| 2771 <description> | |
| 2772 Pop the current frame of <code>thread</code>'s stack. | |
| 2773 Popping a frame takes you to the previous frame. | |
| 2774 When the thread is resumed, the execution | |
| 2775 state of the thread is reset to the state | |
| 2776 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
|
2777 That is (using <vmspec/> terminology): |
| 0 | 2778 <ul> |
| 2779 <li>the current frame is discarded as the previous frame becomes the current one</li> | |
| 2780 <li>the operand stack is restored--the argument values are added back | |
| 2781 and if the invoke was not <code>invokestatic</code>, | |
| 2782 <code>objectref</code> is added back as well</li> | |
| 2783 <li>the Java virtual machine PC is restored to the opcode | |
| 2784 of the invoke instruction</li> | |
| 2785 </ul> | |
| 2786 Note however, that any changes to the arguments, which | |
| 2787 occurred in the called method, remain; | |
| 2788 when execution continues, the first instruction to | |
| 2789 execute will be the invoke. | |
| 2790 <p/> | |
| 2791 Between calling <code>PopFrame</code> and resuming the | |
| 2792 thread the state of the stack is undefined. | |
| 2793 To pop frames beyond the first, | |
| 2794 these three steps must be repeated: | |
| 2795 <ul> | |
| 2796 <li>suspend the thread via an event (step, breakpoint, ...)</li> | |
| 2797 <li>call <code>PopFrame</code></li> | |
| 2798 <li>resume the thread</li> | |
| 2799 </ul> | |
| 2800 <p/> | |
| 2801 A lock acquired by calling the called method | |
| 2802 (if it is a <code>synchronized</code> method) | |
| 2803 and locks acquired by entering <code>synchronized</code> | |
| 2804 blocks within the called method are released. | |
| 2805 Note: this does not apply to native locks or | |
| 2806 <code>java.util.concurrent.locks</code> locks. | |
| 2807 <p/> | |
| 2808 Finally blocks are not executed. | |
| 2809 <p/> | |
| 2810 Changes to global state are not addressed and thus remain changed. | |
| 2811 <p/> | |
| 2812 The specified thread must be suspended (which implies it cannot be the current thread). | |
| 2813 <p/> | |
| 2814 Both the called method and calling method must be non-native Java programming | |
| 2815 language methods. | |
| 2816 <p/> | |
| 2817 No <jvmti/> events are generated by this function. | |
| 2818 </description> | |
| 2819 <origin>jvmdi</origin> | |
| 2820 <capabilities> | |
| 2821 <required id="can_pop_frame"></required> | |
| 2822 </capabilities> | |
| 2823 <parameters> | |
| 2824 <param id="thread"> | |
| 2825 <jthread/> | |
| 2826 <description> | |
| 2827 The thread whose current frame is to be popped. | |
| 2828 </description> | |
| 2829 </param> | |
| 2830 </parameters> | |
| 2831 <errors> | |
| 2832 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2833 Called or calling method is a native method. | |
| 2834 The implementation is unable to pop this frame. | |
| 2835 </error> | |
| 2836 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 2837 Thread was not suspended. | |
| 2838 </error> | |
| 2839 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 2840 There are less than two stack frames on the call stack. | |
| 2841 </error> | |
| 2842 </errors> | |
| 2843 </function> | |
| 2844 | |
| 2845 <function id="GetFrameLocation" num="19"> | |
| 2846 <synopsis>Get Frame Location</synopsis> | |
| 2847 <description> | |
| 2848 <p/> | |
| 2849 For a Java programming language frame, return the location of the instruction | |
| 2850 currently executing. | |
| 2851 </description> | |
| 2852 <origin>jvmdiClone</origin> | |
| 2853 <capabilities> | |
| 2854 </capabilities> | |
| 2855 <parameters> | |
| 2856 <param id="thread"> | |
| 2857 <jthread null="current" frame="frame"/> | |
| 2858 <description> | |
| 2859 The thread of the frame to query. | |
| 2860 </description> | |
| 2861 </param> | |
| 2862 <param id="depth"> | |
| 2863 <jframeID thread="thread"/> | |
| 2864 <description> | |
| 2865 The depth of the frame to query. | |
| 2866 </description> | |
| 2867 </param> | |
| 2868 <param id="method_ptr"> | |
| 2869 <outptr><jmethodID/></outptr> | |
| 2870 <description> | |
| 2871 On return, points to the method for the current location. | |
| 2872 </description> | |
| 2873 </param> | |
| 2874 <param id="location_ptr"> | |
| 2875 <outptr><jlocation/></outptr> | |
| 2876 <description> | |
| 2877 On return, points to the index of the currently | |
| 2878 executing instruction. | |
| 2879 Is set to <code>-1</code> if the frame is executing | |
| 2880 a native method. | |
| 2881 </description> | |
| 2882 </param> | |
| 2883 </parameters> | |
| 2884 <errors> | |
| 2885 </errors> | |
| 2886 </function> | |
| 2887 | |
| 2888 <function id="NotifyFramePop" num="20"> | |
| 2889 <synopsis>Notify Frame Pop</synopsis> | |
| 2890 <description> | |
| 2891 When the frame that is currently at <paramlink id="depth"></paramlink> | |
| 2892 is popped from the stack, generate a | |
| 2893 <eventlink id="FramePop"></eventlink> event. See the | |
| 2894 <eventlink id="FramePop"></eventlink> event for details. | |
| 2895 Only frames corresponding to non-native Java programming language | |
| 2896 methods can receive notification. | |
| 2897 <p/> | |
| 2898 The specified thread must either be the current thread | |
| 2899 or the thread must be suspended. | |
| 2900 </description> | |
| 2901 <origin>jvmdi</origin> | |
| 2902 <capabilities> | |
| 2903 <required id="can_generate_frame_pop_events"></required> | |
| 2904 </capabilities> | |
| 2905 <parameters> | |
| 2906 <param id="thread"> | |
| 2907 <jthread null="current" frame="depth"/> | |
| 2908 <description> | |
| 2909 The thread of the frame for which the frame pop event will be generated. | |
| 2910 </description> | |
| 2911 </param> | |
| 2912 <param id="depth"> | |
| 2913 <jframeID thread="thread"/> | |
| 2914 <description> | |
| 2915 The depth of the frame for which the frame pop event will be generated. | |
| 2916 </description> | |
| 2917 </param> | |
| 2918 </parameters> | |
| 2919 <errors> | |
| 2920 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2921 The frame at <code>depth</code> is executing a | |
| 2922 native method. | |
| 2923 </error> | |
| 2924 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 2925 Thread was not suspended and was not the current thread. | |
| 2926 </error> | |
| 2927 </errors> | |
| 2928 </function> | |
| 2929 | |
| 2930 </category> | |
| 2931 | |
| 2932 <category id="ForceEarlyReturn" label="Force Early Return"> | |
| 2933 <intro> | |
| 2934 These functions allow an agent to force a method | |
| 2935 to return at any point during its execution. | |
| 2936 The method which will return early is referred to as the <i>called method</i>. | |
| 2937 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
|
2938 (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
|
2939 <vmspec chapter="3.6"/>) |
| 0 | 2940 for the specified thread at |
| 2941 the time the function is called. | |
| 2942 <p/> | |
| 2943 The specified thread must be suspended or must be the current thread. | |
| 2944 The return occurs when execution of Java programming | |
| 2945 language code is resumed on this thread. | |
| 2946 Between calling one of these functions and resumption | |
| 2947 of thread execution, the state of the stack is undefined. | |
| 2948 <p/> | |
| 2949 No further instructions are executed in the called method. | |
| 2950 Specifically, finally blocks are not executed. | |
| 2951 Note: this can cause inconsistent states in the application. | |
| 2952 <p/> | |
| 2953 A lock acquired by calling the called method | |
| 2954 (if it is a <code>synchronized</code> method) | |
| 2955 and locks acquired by entering <code>synchronized</code> | |
| 2956 blocks within the called method are released. | |
| 2957 Note: this does not apply to native locks or | |
| 2958 <code>java.util.concurrent.locks</code> locks. | |
| 2959 <p/> | |
| 2960 Events, such as <eventlink id="MethodExit"></eventlink>, | |
| 2961 are generated as they would be in a normal return. | |
| 2962 <p/> | |
| 2963 The called method must be a non-native Java programming | |
| 2964 language method. | |
| 2965 Forcing return on a thread with only one frame on the | |
| 2966 stack causes the thread to exit when resumed. | |
| 2967 </intro> | |
| 2968 | |
| 2969 <function id="ForceEarlyReturnObject" num="81" since="1.1"> | |
| 2970 <synopsis>Force Early Return - Object</synopsis> | |
| 2971 <description> | |
| 2972 This function can be used to return from a method whose | |
| 2973 result type is <code>Object</code> | |
| 2974 or a subclass of <code>Object</code>. | |
| 2975 </description> | |
| 2976 <origin>new</origin> | |
| 2977 <capabilities> | |
| 2978 <required id="can_force_early_return"></required> | |
| 2979 </capabilities> | |
| 2980 <parameters> | |
| 2981 <param id="thread"> | |
| 2982 <jthread null="current"/> | |
| 2983 <description> | |
| 2984 The thread whose current frame is to return early. | |
| 2985 </description> | |
| 2986 </param> | |
| 2987 <param id="value"> | |
| 2988 <jobject/> | |
| 2989 <description> | |
| 2990 The return value for the called frame. | |
| 2991 An object or <code>NULL</code>. | |
| 2992 </description> | |
| 2993 </param> | |
| 2994 </parameters> | |
| 2995 <errors> | |
| 2996 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 2997 Attempted to return early from a frame | |
| 2998 corresponding to a native method. | |
| 2999 Or the implementation is unable to provide | |
| 3000 this functionality on this frame. | |
| 3001 </error> | |
| 3002 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3003 The result type of the called method is not | |
| 3004 <code>Object</code> or a subclass of <code>Object</code>. | |
| 3005 </error> | |
| 3006 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3007 The supplied <paramlink id="value"/> is not compatible with the | |
| 3008 result type of the called method. | |
| 3009 </error> | |
| 3010 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3011 Thread was not the current thread and was not suspended. | |
| 3012 </error> | |
| 3013 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3014 There are no more frames on the call stack. | |
| 3015 </error> | |
| 3016 </errors> | |
| 3017 </function> | |
| 3018 | |
| 3019 <function id="ForceEarlyReturnInt" num="82" since="1.1"> | |
| 3020 <synopsis>Force Early Return - Int</synopsis> | |
| 3021 <description> | |
| 3022 This function can be used to return from a method whose | |
| 3023 result type is <code>int</code>, <code>short</code>, | |
| 3024 <code>char</code>, <code>byte</code>, or | |
| 3025 <code>boolean</code>. | |
| 3026 </description> | |
| 3027 <origin>new</origin> | |
| 3028 <capabilities> | |
| 3029 <required id="can_force_early_return"></required> | |
| 3030 </capabilities> | |
| 3031 <parameters> | |
| 3032 <param id="thread"> | |
| 3033 <jthread null="current"/> | |
| 3034 <description> | |
| 3035 The thread whose current frame is to return early. | |
| 3036 </description> | |
| 3037 </param> | |
| 3038 <param id="value"> | |
| 3039 <jint/> | |
| 3040 <description> | |
| 3041 The return value for the called frame. | |
| 3042 </description> | |
| 3043 </param> | |
| 3044 </parameters> | |
| 3045 <errors> | |
| 3046 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3047 Attempted to return early from a frame | |
| 3048 corresponding to a native method. | |
| 3049 Or the implementation is unable to provide | |
| 3050 this functionality on this frame. | |
| 3051 </error> | |
| 3052 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3053 The result type of the called method is not | |
| 3054 <code>int</code>, <code>short</code>, | |
| 3055 <code>char</code>, <code>byte</code>, or | |
| 3056 <code>boolean</code>. | |
| 3057 </error> | |
| 3058 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3059 Thread was not the current thread and was not suspended. | |
| 3060 </error> | |
| 3061 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3062 There are no frames on the call stack. | |
| 3063 </error> | |
| 3064 </errors> | |
| 3065 </function> | |
| 3066 | |
| 3067 <function id="ForceEarlyReturnLong" num="83" since="1.1"> | |
| 3068 <synopsis>Force Early Return - Long</synopsis> | |
| 3069 <description> | |
| 3070 This function can be used to return from a method whose | |
| 3071 result type is <code>long</code>. | |
| 3072 </description> | |
| 3073 <origin>new</origin> | |
| 3074 <capabilities> | |
| 3075 <required id="can_force_early_return"></required> | |
| 3076 </capabilities> | |
| 3077 <parameters> | |
| 3078 <param id="thread"> | |
| 3079 <jthread null="current"/> | |
| 3080 <description> | |
| 3081 The thread whose current frame is to return early. | |
| 3082 </description> | |
| 3083 </param> | |
| 3084 <param id="value"> | |
| 3085 <jlong/> | |
| 3086 <description> | |
| 3087 The return value for the called frame. | |
| 3088 </description> | |
| 3089 </param> | |
| 3090 </parameters> | |
| 3091 <errors> | |
| 3092 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3093 Attempted to return early from a frame | |
| 3094 corresponding to a native method. | |
| 3095 Or the implementation is unable to provide | |
| 3096 this functionality on this frame. | |
| 3097 </error> | |
| 3098 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3099 The result type of the called method is not <code>long</code>. | |
| 3100 </error> | |
| 3101 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3102 Thread was not the current thread and was not suspended. | |
| 3103 </error> | |
| 3104 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3105 There are no frames on the call stack. | |
| 3106 </error> | |
| 3107 </errors> | |
| 3108 </function> | |
| 3109 | |
| 3110 <function id="ForceEarlyReturnFloat" num="84" since="1.1"> | |
| 3111 <synopsis>Force Early Return - Float</synopsis> | |
| 3112 <description> | |
| 3113 This function can be used to return from a method whose | |
| 3114 result type is <code>float</code>. | |
| 3115 </description> | |
| 3116 <origin>new</origin> | |
| 3117 <capabilities> | |
| 3118 <required id="can_force_early_return"></required> | |
| 3119 </capabilities> | |
| 3120 <parameters> | |
| 3121 <param id="thread"> | |
| 3122 <jthread null="current"/> | |
| 3123 <description> | |
| 3124 The thread whose current frame is to return early. | |
| 3125 </description> | |
| 3126 </param> | |
| 3127 <param id="value"> | |
| 3128 <jfloat/> | |
| 3129 <description> | |
| 3130 The return value for the called frame. | |
| 3131 </description> | |
| 3132 </param> | |
| 3133 </parameters> | |
| 3134 <errors> | |
| 3135 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3136 Attempted to return early from a frame | |
| 3137 corresponding to a native method. | |
| 3138 Or the implementation is unable to provide | |
| 3139 this functionality on this frame. | |
| 3140 </error> | |
| 3141 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3142 The result type of the called method is not <code>float</code>. | |
| 3143 </error> | |
| 3144 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3145 Thread was not the current thread and was not suspended. | |
| 3146 </error> | |
| 3147 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3148 There are no frames on the call stack. | |
| 3149 </error> | |
| 3150 </errors> | |
| 3151 </function> | |
| 3152 | |
| 3153 <function id="ForceEarlyReturnDouble" num="85" since="1.1"> | |
| 3154 <synopsis>Force Early Return - Double</synopsis> | |
| 3155 <description> | |
| 3156 This function can be used to return from a method whose | |
| 3157 result type is <code>double</code>. | |
| 3158 </description> | |
| 3159 <origin>new</origin> | |
| 3160 <capabilities> | |
| 3161 <required id="can_force_early_return"></required> | |
| 3162 </capabilities> | |
| 3163 <parameters> | |
| 3164 <param id="thread"> | |
| 3165 <jthread null="current"/> | |
| 3166 <description> | |
| 3167 The thread whose current frame is to return early. | |
| 3168 </description> | |
| 3169 </param> | |
| 3170 <param id="value"> | |
| 3171 <jdouble/> | |
| 3172 <description> | |
| 3173 The return value for the called frame. | |
| 3174 </description> | |
| 3175 </param> | |
| 3176 </parameters> | |
| 3177 <errors> | |
| 3178 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3179 Attempted to return early from a frame corresponding to a native method. | |
| 3180 Or the implementation is unable to provide this functionality on this frame. | |
| 3181 </error> | |
| 3182 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3183 The result type of the called method is not <code>double</code>. | |
| 3184 </error> | |
| 3185 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3186 Thread was not the current thread and was not suspended. | |
| 3187 </error> | |
| 3188 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3189 There are no frames on the call stack. | |
| 3190 </error> | |
| 3191 </errors> | |
| 3192 </function> | |
| 3193 | |
| 3194 <function id="ForceEarlyReturnVoid" num="86" since="1.1"> | |
| 3195 <synopsis>Force Early Return - Void</synopsis> | |
| 3196 <description> | |
| 3197 This function can be used to return from a method with no result type. | |
| 3198 That is, the called method must be declared <code>void</code>. | |
| 3199 </description> | |
| 3200 <origin>new</origin> | |
| 3201 <capabilities> | |
| 3202 <required id="can_force_early_return"></required> | |
| 3203 </capabilities> | |
| 3204 <parameters> | |
| 3205 <param id="thread"> | |
| 3206 <jthread null="current"/> | |
| 3207 <description> | |
| 3208 The thread whose current frame is to return early. | |
| 3209 </description> | |
| 3210 </param> | |
| 3211 </parameters> | |
| 3212 <errors> | |
| 3213 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 3214 Attempted to return early from a frame | |
| 3215 corresponding to a native method. | |
| 3216 Or the implementation is unable to provide | |
| 3217 this functionality on this frame. | |
| 3218 </error> | |
| 3219 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 3220 The called method has a result type. | |
| 3221 </error> | |
| 3222 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
| 3223 Thread was not the current thread and was not suspended. | |
| 3224 </error> | |
| 3225 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
| 3226 There are no frames on the call stack. | |
| 3227 </error> | |
| 3228 </errors> | |
| 3229 </function> | |
| 3230 | |
| 3231 </category> | |
| 3232 | |
| 3233 <category id="Heap" label="Heap"> | |
| 3234 <intro> | |
| 3235 These functions are used to analyze the heap. | |
| 3236 Functionality includes the ability to view the objects in the | |
| 3237 heap and to tag these objects. | |
| 3238 </intro> | |
| 3239 | |
| 3240 <intro id="objectTags" label="Object Tags"> | |
| 3241 A <i>tag</i> is a value associated with an object. | |
| 3242 Tags are explicitly set by the agent using the | |
| 3243 <functionlink id="SetTag"></functionlink> function or by | |
| 3244 callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>. | |
| 3245 <p/> | |
| 3246 Tags are local to the environment; that is, the tags of one | |
| 3247 environment are not visible in another. | |
| 3248 <p/> | |
| 3249 Tags are <code>jlong</code> values which can be used | |
| 3250 simply to mark an object or to store a pointer to more detailed | |
| 3251 information. Objects which have not been tagged have a | |
| 3252 tag of zero. | |
| 3253 Setting a tag to zero makes the object untagged. | |
| 3254 </intro> | |
| 3255 | |
| 3256 <intro id="heapCallbacks" label="Heap Callback Functions"> | |
| 3257 Heap functions which iterate through the heap and recursively | |
| 3258 follow object references use agent supplied callback functions | |
| 3259 to deliver the information. | |
| 3260 <p/> | |
| 3261 These heap callback functions must adhere to the following restrictions -- | |
| 3262 These callbacks must not use JNI functions. | |
| 3263 These callbacks must not use <jvmti/> functions except | |
| 3264 <i>callback safe</i> functions which | |
| 3265 specifically allow such use (see the raw monitor, memory management, | |
| 3266 and environment local storage functions). | |
| 3267 <p/> | |
| 3268 An implementation may invoke a callback on an internal thread or | |
| 3269 the thread which called the iteration function. | |
| 3270 Heap callbacks are single threaded -- no more than one callback will | |
| 3271 be invoked at a time. | |
| 3272 <p/> | |
| 3273 The Heap Filter Flags can be used to prevent reporting | |
| 3274 based on the tag status of an object or its class. | |
| 3275 If no flags are set (the <code>jint</code> is zero), objects | |
| 3276 will not be filtered out. | |
| 3277 | |
| 3278 <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits"> | |
| 3279 <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4"> | |
| 3280 Filter out tagged objects. Objects which are tagged are not included. | |
| 3281 </constant> | |
| 3282 <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8"> | |
| 3283 Filter out untagged objects. Objects which are not tagged are not included. | |
| 3284 </constant> | |
| 3285 <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10"> | |
| 3286 Filter out objects with tagged classes. Objects whose class is tagged are not included. | |
| 3287 </constant> | |
| 3288 <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20"> | |
| 3289 Filter out objects with untagged classes. Objects whose class is not tagged are not included. | |
| 3290 </constant> | |
| 3291 </constants> | |
| 3292 | |
| 3293 <p/> | |
| 3294 The Heap Visit Control Flags are returned by the heap callbacks | |
| 3295 and can be used to abort the iteration. For the | |
| 3296 <functionlink id="jvmtiHeapReferenceCallback">Heap | |
| 3297 Reference Callback</functionlink>, it can also be used | |
| 3298 to prune the graph of traversed references | |
| 3299 (<code>JVMTI_VISIT_OBJECTS</code> is not set). | |
| 3300 | |
| 3301 <constants id="jvmtiHeapVisitControl" | |
| 3302 label="Heap Visit Control Flags" | |
| 3303 kind="bits" | |
| 3304 since="1.1"> | |
| 3305 <constant id="JVMTI_VISIT_OBJECTS" num="0x100"> | |
| 3306 If we are visiting an object and if this callback | |
| 3307 was initiated by <functionlink id="FollowReferences"/>, | |
| 3308 traverse the references of this object. | |
| 3309 Otherwise ignored. | |
| 3310 </constant> | |
| 3311 <constant id="JVMTI_VISIT_ABORT" num="0x8000"> | |
| 3312 Abort the iteration. Ignore all other bits. | |
| 3313 </constant> | |
| 3314 </constants> | |
| 3315 | |
| 3316 <p/> | |
| 3317 The Heap Reference Enumeration is provided by the | |
| 3318 <functionlink id="jvmtiHeapReferenceCallback">Heap | |
| 3319 Reference Callback</functionlink> and | |
| 3320 <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field | |
| 3321 Callback</functionlink> to | |
| 3322 describe the kind of reference | |
| 3323 being reported. | |
| 3324 | |
| 3325 <constants id="jvmtiHeapReferenceKind" | |
| 3326 label="Heap Reference Enumeration" | |
| 3327 kind="enum" | |
| 3328 since="1.1"> | |
| 3329 <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1"> | |
| 3330 Reference from an object to its class. | |
| 3331 </constant> | |
| 3332 <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2"> | |
| 3333 Reference from an object to the value of one of its instance fields. | |
| 3334 </constant> | |
| 3335 <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3"> | |
| 3336 Reference from an array to one of its elements. | |
| 3337 </constant> | |
| 3338 <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4"> | |
| 3339 Reference from a class to its class loader. | |
| 3340 </constant> | |
| 3341 <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5"> | |
| 3342 Reference from a class to its signers array. | |
| 3343 </constant> | |
| 3344 <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6"> | |
| 3345 Reference from a class to its protection domain. | |
| 3346 </constant> | |
| 3347 <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7"> | |
| 3348 Reference from a class to one of its interfaces. | |
| 3349 Note: interfaces are defined via a constant pool reference, | |
| 3350 so the referenced interfaces may also be reported with a | |
| 3351 <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. | |
| 3352 </constant> | |
| 3353 <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8"> | |
| 3354 Reference from a class to the value of one of its static fields. | |
| 3355 </constant> | |
| 3356 <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9"> | |
| 3357 Reference from a class to a resolved entry in the constant pool. | |
| 3358 </constant> | |
| 3359 <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10"> | |
| 3360 Reference from a class to its superclass. | |
| 3361 A callback is bot sent if the superclass is <code>java.lang.Object</code>. | |
| 3362 Note: loaded classes define superclasses via a constant pool | |
| 3363 reference, so the referenced superclass may also be reported with | |
| 3364 a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. | |
| 3365 </constant> | |
| 3366 <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21"> | |
| 3367 Heap root reference: JNI global reference. | |
| 3368 </constant> | |
| 3369 <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22"> | |
| 3370 Heap root reference: System class. | |
| 3371 </constant> | |
| 3372 <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23"> | |
| 3373 Heap root reference: monitor. | |
| 3374 </constant> | |
| 3375 <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24"> | |
| 3376 Heap root reference: local variable on the stack. | |
| 3377 </constant> | |
| 3378 <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25"> | |
| 3379 Heap root reference: JNI local reference. | |
| 3380 </constant> | |
| 3381 <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26"> | |
| 3382 Heap root reference: Thread. | |
| 3383 </constant> | |
| 3384 <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27"> | |
| 3385 Heap root reference: other heap root reference. | |
| 3386 </constant> | |
| 3387 </constants> | |
| 3388 | |
| 3389 <p/> | |
| 3390 Definitions for the single character type descriptors of | |
| 3391 primitive types. | |
| 3392 | |
| 3393 <constants id="jvmtiPrimitiveType" | |
| 3394 label="Primitive Type Enumeration" | |
| 3395 kind="enum" | |
| 3396 since="1.1"> | |
| 3397 <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90"> | |
| 3398 'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code> | |
| 3399 </constant> | |
| 3400 <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66"> | |
| 3401 'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code> | |
| 3402 </constant> | |
| 3403 <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67"> | |
| 3404 'C' - Java programming language <code>char</code> - JNI <code>jchar</code> | |
| 3405 </constant> | |
| 3406 <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83"> | |
| 3407 'S' - Java programming language <code>short</code> - JNI <code>jshort</code> | |
| 3408 </constant> | |
| 3409 <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73"> | |
| 3410 'I' - Java programming language <code>int</code> - JNI <code>jint</code> | |
| 3411 </constant> | |
| 3412 <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74"> | |
| 3413 'J' - Java programming language <code>long</code> - JNI <code>jlong</code> | |
| 3414 </constant> | |
| 3415 <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70"> | |
| 3416 'F' - Java programming language <code>float</code> - JNI <code>jfloat</code> | |
| 3417 </constant> | |
| 3418 <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68"> | |
| 3419 'D' - Java programming language <code>double</code> - JNI <code>jdouble</code> | |
| 3420 </constant> | |
| 3421 </constants> | |
| 3422 </intro> | |
| 3423 | |
| 3424 <typedef id="jvmtiHeapReferenceInfoField" | |
| 3425 label="Reference information structure for Field references" | |
| 3426 since="1.1"> | |
| 3427 <description> | |
| 3428 Reference information returned for | |
| 3429 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and | |
| 3430 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. | |
| 3431 </description> | |
| 3432 <field id="index"> | |
| 3433 <jint/> | |
| 3434 <description> | |
| 3435 For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the | |
| 3436 referrer object is not a class or an inteface. | |
| 3437 In this case, <code>index</code> is the index of the field | |
| 3438 in the class of the referrer object. | |
| 3439 This class is referred to below as <i>C</i>. | |
| 3440 <p/> | |
| 3441 For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, | |
| 3442 the referrer object is a class (referred to below as <i>C</i>) | |
| 3443 or an interface (referred to below as <i>I</i>). | |
| 3444 In this case, <code>index</code> is the index of the field in | |
| 3445 that class or interface. | |
| 3446 <p/> | |
| 3447 If the referrer object is not an interface, then the field | |
| 3448 indices are determined as follows: | |
| 3449 <ul> | |
| 3450 <li>make a list of all the fields in <i>C</i> and its | |
| 3451 superclasses, starting with all the fields in | |
| 3452 <code>java.lang.Object</code> and ending with all the | |
| 3453 fields in <i>C</i>.</li> | |
| 3454 <li>Within this list, put | |
| 3455 the fields for a given class in the order returned by | |
| 3456 <functionlink id="GetClassFields"/>.</li> | |
| 3457 <li>Assign the fields in this list indices | |
| 3458 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> | |
| 3459 is the count of the fields in all the interfaces | |
| 3460 implemented by <i>C</i>. | |
| 3461 Note that <i>C</i> implements all interfaces | |
| 3462 directly implemented by its superclasses; as well | |
| 3463 as all superinterfaces of these interfaces.</li> | |
| 3464 </ul> | |
| 3465 If the referrer object is an interface, then the field | |
| 3466 indices are determined as follows: | |
| 3467 <ul> | |
| 3468 <li>make a list of the fields directly declared in | |
| 3469 <i>I</i>.</li> | |
| 3470 <li>Within this list, put | |
| 3471 the fields in the order returned by | |
| 3472 <functionlink id="GetClassFields"/>.</li> | |
| 3473 <li>Assign the fields in this list indices | |
| 3474 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> | |
| 3475 is the count of the fields in all the superinterfaces | |
| 3476 of <i>I</i>.</li> | |
| 3477 </ul> | |
| 3478 All fields are included in this computation, regardless of | |
| 3479 field modifier (static, public, private, etc). | |
| 3480 <p/> | |
| 3481 For example, given the following classes and interfaces: | |
| 3482 <example> | |
| 3483 interface I0 { | |
| 3484 int p = 0; | |
| 3485 } | |
| 3486 | |
| 3487 interface I1 extends I0 { | |
| 3488 int x = 1; | |
| 3489 } | |
| 3490 | |
| 3491 interface I2 extends I0 { | |
| 3492 int y = 2; | |
| 3493 } | |
| 3494 | |
| 3495 class C1 implements I1 { | |
| 3496 public static int a = 3; | |
| 3497 private int b = 4; | |
| 3498 } | |
| 3499 | |
| 3500 class C2 extends C1 implements I2 { | |
| 3501 static int q = 5; | |
| 3502 final int r = 6; | |
| 3503 } | |
| 3504 </example> | |
| 3505 Assume that <functionlink id="GetClassFields"/> called on | |
| 3506 <code>C1</code> returns the fields of <code>C1</code> in the | |
| 3507 order: a, b; and that the fields of <code>C2</code> are | |
| 3508 returned in the order: q, r. | |
| 3509 An instance of class <code>C1</code> will have the | |
| 3510 following field indices: | |
| 3511 <dl><dd><table> | |
| 3512 <tr> | |
| 3513 <td> | |
| 3514 a | |
| 3515 </td> | |
| 3516 <td> | |
| 3517 2 | |
| 3518 </td> | |
| 3519 <td align="left"> | |
| 3520 The count of the fields in the interfaces | |
| 3521 implemented by <code>C1</code> is two (<i>n</i>=2): | |
| 3522 <code>p</code> of <code>I0</code> | |
| 3523 and <code>x</code> of <code>I1</code>. | |
| 3524 </td> | |
| 3525 </tr> | |
| 3526 <tr> | |
| 3527 <td> | |
| 3528 b | |
| 3529 </td> | |
| 3530 <td> | |
| 3531 3 | |
| 3532 </td> | |
| 3533 <td align="left"> | |
| 3534 the subsequent index. | |
| 3535 </td> | |
| 3536 </tr> | |
| 3537 </table></dd></dl> | |
| 3538 The class <code>C1</code> will have the same field indices. | |
| 3539 <p/> | |
| 3540 An instance of class <code>C2</code> will have the | |
| 3541 following field indices: | |
| 3542 <dl><dd><table> | |
| 3543 <tr> | |
| 3544 <td> | |
| 3545 a | |
| 3546 </td> | |
| 3547 <td> | |
| 3548 3 | |
| 3549 </td> | |
| 3550 <td align="left"> | |
| 3551 The count of the fields in the interfaces | |
| 3552 implemented by <code>C2</code> is three (<i>n</i>=3): | |
| 3553 <code>p</code> of <code>I0</code>, | |
| 3554 <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code> | |
| 3555 (an interface of <code>C2</code>). Note that the field <code>p</code> | |
| 3556 of <code>I0</code> is only included once. | |
| 3557 </td> | |
| 3558 </tr> | |
| 3559 <tr> | |
| 3560 <td> | |
| 3561 b | |
| 3562 </td> | |
| 3563 <td> | |
| 3564 4 | |
| 3565 </td> | |
| 3566 <td align="left"> | |
| 3567 the subsequent index to "a". | |
| 3568 </td> | |
| 3569 </tr> | |
| 3570 <tr> | |
| 3571 <td> | |
| 3572 q | |
| 3573 </td> | |
| 3574 <td> | |
| 3575 5 | |
| 3576 </td> | |
| 3577 <td align="left"> | |
| 3578 the subsequent index to "b". | |
| 3579 </td> | |
| 3580 </tr> | |
| 3581 <tr> | |
| 3582 <td> | |
| 3583 r | |
| 3584 </td> | |
| 3585 <td> | |
| 3586 6 | |
| 3587 </td> | |
| 3588 <td align="left"> | |
| 3589 the subsequent index to "q". | |
| 3590 </td> | |
| 3591 </tr> | |
| 3592 </table></dd></dl> | |
| 3593 The class <code>C2</code> will have the same field indices. | |
| 3594 Note that a field may have a different index depending on the | |
| 3595 object that is viewing it -- for example field "a" above. | |
| 3596 Note also: not all field indices may be visible from the | |
| 3597 callbacks, but all indices are shown for illustrative purposes. | |
| 3598 <p/> | |
| 3599 The interface <code>I1</code> will have the | |
| 3600 following field indices: | |
| 3601 <dl><dd><table> | |
| 3602 <tr> | |
| 3603 <td> | |
| 3604 x | |
| 3605 </td> | |
| 3606 <td> | |
| 3607 1 | |
| 3608 </td> | |
| 3609 <td align="left"> | |
| 3610 The count of the fields in the superinterfaces | |
| 3611 of <code>I1</code> is one (<i>n</i>=1): | |
| 3612 <code>p</code> of <code>I0</code>. | |
| 3613 </td> | |
| 3614 </tr> | |
| 3615 </table></dd></dl> | |
| 3616 </description> | |
| 3617 </field> | |
| 3618 </typedef> | |
| 3619 | |
| 3620 <typedef id="jvmtiHeapReferenceInfoArray" | |
| 3621 label="Reference information structure for Array references" | |
| 3622 since="1.1"> | |
| 3623 <description> | |
| 3624 Reference information returned for | |
| 3625 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. | |
| 3626 </description> | |
| 3627 <field id="index"> | |
| 3628 <jint/> | |
| 3629 <description> | |
| 3630 The array index. | |
| 3631 </description> | |
| 3632 </field> | |
| 3633 </typedef> | |
| 3634 | |
| 3635 <typedef id="jvmtiHeapReferenceInfoConstantPool" | |
| 3636 label="Reference information structure for Constant Pool references" | |
| 3637 since="1.1"> | |
| 3638 <description> | |
| 3639 Reference information returned for | |
| 3640 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. | |
| 3641 </description> | |
| 3642 <field id="index"> | |
| 3643 <jint/> | |
| 3644 <description> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
3645 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
|
3646 <vmspec chapter="4.4"/>. |
| 0 | 3647 </description> |
| 3648 </field> | |
| 3649 </typedef> | |
| 3650 | |
| 3651 <typedef id="jvmtiHeapReferenceInfoStackLocal" | |
| 3652 label="Reference information structure for Local Variable references" | |
| 3653 since="1.1"> | |
| 3654 <description> | |
| 3655 Reference information returned for | |
| 3656 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. | |
| 3657 </description> | |
| 3658 <field id="thread_tag"> | |
| 3659 <jlong/> | |
| 3660 <description> | |
| 3661 The tag of the thread corresponding to this stack, zero if not tagged. | |
| 3662 </description> | |
| 3663 </field> | |
| 3664 <field id="thread_id"> | |
| 3665 <jlong/> | |
| 3666 <description> | |
| 3667 The unique thread ID of the thread corresponding to this stack. | |
| 3668 </description> | |
| 3669 </field> | |
| 3670 <field id="depth"> | |
| 3671 <jint/> | |
| 3672 <description> | |
| 3673 The depth of the frame. | |
| 3674 </description> | |
| 3675 </field> | |
| 3676 <field id="method"> | |
| 3677 <jmethodID/> | |
| 3678 <description> | |
| 3679 The method executing in this frame. | |
| 3680 </description> | |
| 3681 </field> | |
| 3682 <field id="location"> | |
| 3683 <jlocation/> | |
| 3684 <description> | |
| 3685 The currently executing location in this frame. | |
| 3686 </description> | |
| 3687 </field> | |
| 3688 <field id="slot"> | |
| 3689 <jint/> | |
| 3690 <description> | |
| 3691 The slot number of the local variable. | |
| 3692 </description> | |
| 3693 </field> | |
| 3694 </typedef> | |
| 3695 | |
| 3696 <typedef id="jvmtiHeapReferenceInfoJniLocal" | |
| 3697 label="Reference information structure for JNI local references" | |
| 3698 since="1.1"> | |
| 3699 <description> | |
| 3700 Reference information returned for | |
| 3701 <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. | |
| 3702 </description> | |
| 3703 <field id="thread_tag"> | |
| 3704 <jlong/> | |
| 3705 <description> | |
| 3706 The tag of the thread corresponding to this stack, zero if not tagged. | |
| 3707 </description> | |
| 3708 </field> | |
| 3709 <field id="thread_id"> | |
| 3710 <jlong/> | |
| 3711 <description> | |
| 3712 The unique thread ID of the thread corresponding to this stack. | |
| 3713 </description> | |
| 3714 </field> | |
| 3715 <field id="depth"> | |
| 3716 <jint/> | |
| 3717 <description> | |
| 3718 The depth of the frame. | |
| 3719 </description> | |
| 3720 </field> | |
| 3721 <field id="method"> | |
| 3722 <jmethodID/> | |
| 3723 <description> | |
| 3724 The method executing in this frame. | |
| 3725 </description> | |
| 3726 </field> | |
| 3727 </typedef> | |
| 3728 | |
| 3729 <typedef id="jvmtiHeapReferenceInfoReserved" | |
| 3730 label="Reference information structure for Other references" | |
| 3731 since="1.1"> | |
| 3732 <description> | |
| 3733 Reference information returned for other references. | |
| 3734 </description> | |
| 3735 <field id="reserved1"> | |
| 3736 <jlong/> | |
| 3737 <description> | |
| 3738 reserved for future use. | |
| 3739 </description> | |
| 3740 </field> | |
| 3741 <field id="reserved2"> | |
| 3742 <jlong/> | |
| 3743 <description> | |
| 3744 reserved for future use. | |
| 3745 </description> | |
| 3746 </field> | |
| 3747 <field id="reserved3"> | |
| 3748 <jlong/> | |
| 3749 <description> | |
| 3750 reserved for future use. | |
| 3751 </description> | |
| 3752 </field> | |
| 3753 <field id="reserved4"> | |
| 3754 <jlong/> | |
| 3755 <description> | |
| 3756 reserved for future use. | |
| 3757 </description> | |
| 3758 </field> | |
| 3759 <field id="reserved5"> | |
| 3760 <jlong/> | |
| 3761 <description> | |
| 3762 reserved for future use. | |
| 3763 </description> | |
| 3764 </field> | |
| 3765 <field id="reserved6"> | |
| 3766 <jlong/> | |
| 3767 <description> | |
| 3768 reserved for future use. | |
| 3769 </description> | |
| 3770 </field> | |
| 3771 <field id="reserved7"> | |
| 3772 <jlong/> | |
| 3773 <description> | |
| 3774 reserved for future use. | |
| 3775 </description> | |
| 3776 </field> | |
| 3777 <field id="reserved8"> | |
| 3778 <jlong/> | |
| 3779 <description> | |
| 3780 reserved for future use. | |
| 3781 </description> | |
| 3782 </field> | |
| 3783 </typedef> | |
| 3784 | |
| 3785 <uniontypedef id="jvmtiHeapReferenceInfo" | |
| 3786 label="Reference information structure" | |
| 3787 since="1.1"> | |
| 3788 <description> | |
| 3789 The information returned about referrers. | |
| 3790 Represented as a union of the various kinds of reference information. | |
| 3791 </description> | |
| 3792 <field id="field"> | |
| 3793 <struct>jvmtiHeapReferenceInfoField</struct> | |
| 3794 <description> | |
| 3795 The referrer information for | |
| 3796 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> | |
| 3797 and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. | |
| 3798 </description> | |
| 3799 </field> | |
| 3800 <field id="array"> | |
| 3801 <struct>jvmtiHeapReferenceInfoArray</struct> | |
| 3802 <description> | |
| 3803 The referrer information for | |
| 3804 For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. | |
| 3805 </description> | |
| 3806 </field> | |
| 3807 <field id="constant_pool"> | |
| 3808 <struct>jvmtiHeapReferenceInfoConstantPool</struct> | |
| 3809 <description> | |
| 3810 The referrer information for | |
| 3811 For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. | |
| 3812 </description> | |
| 3813 </field> | |
| 3814 <field id="stack_local"> | |
| 3815 <struct>jvmtiHeapReferenceInfoStackLocal</struct> | |
| 3816 <description> | |
| 3817 The referrer information for | |
| 3818 For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. | |
| 3819 </description> | |
| 3820 </field> | |
| 3821 <field id="jni_local"> | |
| 3822 <struct>jvmtiHeapReferenceInfoJniLocal</struct> | |
| 3823 <description> | |
| 3824 The referrer information for | |
| 3825 For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. | |
| 3826 </description> | |
| 3827 </field> | |
| 3828 <field id="other"> | |
| 3829 <struct>jvmtiHeapReferenceInfoReserved</struct> | |
| 3830 <description> | |
| 3831 reserved for future use. | |
| 3832 </description> | |
| 3833 </field> | |
| 3834 </uniontypedef> | |
| 3835 | |
| 3836 <typedef id="jvmtiHeapCallbacks" | |
| 3837 label="Heap callback function structure" | |
| 3838 since="1.1"> | |
| 3839 <field id="heap_iteration_callback"> | |
| 3840 <ptrtype> | |
| 3841 <struct>jvmtiHeapIterationCallback</struct> | |
| 3842 </ptrtype> | |
| 3843 <description> | |
| 3844 The callback to be called to describe an | |
| 3845 object in the heap. Used by the | |
| 3846 <functionlink id="IterateThroughHeap"/> function, ignored by the | |
| 3847 <functionlink id="FollowReferences"/> function. | |
| 3848 </description> | |
| 3849 </field> | |
| 3850 <field id="heap_reference_callback"> | |
| 3851 <ptrtype> | |
| 3852 <struct>jvmtiHeapReferenceCallback</struct> | |
| 3853 </ptrtype> | |
| 3854 <description> | |
| 3855 The callback to be called to describe an | |
| 3856 object reference. Used by the | |
| 3857 <functionlink id="FollowReferences"/> function, ignored by the | |
| 3858 <functionlink id="IterateThroughHeap"/> function. | |
| 3859 </description> | |
| 3860 </field> | |
| 3861 <field id="primitive_field_callback"> | |
| 3862 <ptrtype> | |
| 3863 <struct>jvmtiPrimitiveFieldCallback</struct> | |
| 3864 </ptrtype> | |
| 3865 <description> | |
| 3866 The callback to be called to describe a | |
| 3867 primitive field. | |
| 3868 </description> | |
| 3869 </field> | |
| 3870 <field id="array_primitive_value_callback"> | |
| 3871 <ptrtype> | |
| 3872 <struct>jvmtiArrayPrimitiveValueCallback</struct> | |
| 3873 </ptrtype> | |
| 3874 <description> | |
| 3875 The callback to be called to describe an | |
| 3876 array of primitive values. | |
| 3877 </description> | |
| 3878 </field> | |
| 3879 <field id="string_primitive_value_callback"> | |
| 3880 <ptrtype> | |
| 3881 <struct>jvmtiStringPrimitiveValueCallback</struct> | |
| 3882 </ptrtype> | |
| 3883 <description> | |
| 3884 The callback to be called to describe a String value. | |
| 3885 </description> | |
| 3886 </field> | |
| 3887 <field id="reserved5"> | |
| 3888 <ptrtype> | |
| 3889 <struct>jvmtiReservedCallback</struct> | |
| 3890 </ptrtype> | |
| 3891 <description> | |
| 3892 Reserved for future use.. | |
| 3893 </description> | |
| 3894 </field> | |
| 3895 <field id="reserved6"> | |
| 3896 <ptrtype> | |
| 3897 <struct>jvmtiReservedCallback</struct> | |
| 3898 </ptrtype> | |
| 3899 <description> | |
| 3900 Reserved for future use.. | |
| 3901 </description> | |
| 3902 </field> | |
| 3903 <field id="reserved7"> | |
| 3904 <ptrtype> | |
| 3905 <struct>jvmtiReservedCallback</struct> | |
| 3906 </ptrtype> | |
| 3907 <description> | |
| 3908 Reserved for future use.. | |
| 3909 </description> | |
| 3910 </field> | |
| 3911 <field id="reserved8"> | |
| 3912 <ptrtype> | |
| 3913 <struct>jvmtiReservedCallback</struct> | |
| 3914 </ptrtype> | |
| 3915 <description> | |
| 3916 Reserved for future use.. | |
| 3917 </description> | |
| 3918 </field> | |
| 3919 <field id="reserved9"> | |
| 3920 <ptrtype> | |
| 3921 <struct>jvmtiReservedCallback</struct> | |
| 3922 </ptrtype> | |
| 3923 <description> | |
| 3924 Reserved for future use.. | |
| 3925 </description> | |
| 3926 </field> | |
| 3927 <field id="reserved10"> | |
| 3928 <ptrtype> | |
| 3929 <struct>jvmtiReservedCallback</struct> | |
| 3930 </ptrtype> | |
| 3931 <description> | |
| 3932 Reserved for future use.. | |
| 3933 </description> | |
| 3934 </field> | |
| 3935 <field id="reserved11"> | |
| 3936 <ptrtype> | |
| 3937 <struct>jvmtiReservedCallback</struct> | |
| 3938 </ptrtype> | |
| 3939 <description> | |
| 3940 Reserved for future use.. | |
| 3941 </description> | |
| 3942 </field> | |
| 3943 <field id="reserved12"> | |
| 3944 <ptrtype> | |
| 3945 <struct>jvmtiReservedCallback</struct> | |
| 3946 </ptrtype> | |
| 3947 <description> | |
| 3948 Reserved for future use.. | |
| 3949 </description> | |
| 3950 </field> | |
| 3951 <field id="reserved13"> | |
| 3952 <ptrtype> | |
| 3953 <struct>jvmtiReservedCallback</struct> | |
| 3954 </ptrtype> | |
| 3955 <description> | |
| 3956 Reserved for future use.. | |
| 3957 </description> | |
| 3958 </field> | |
| 3959 <field id="reserved14"> | |
| 3960 <ptrtype> | |
| 3961 <struct>jvmtiReservedCallback</struct> | |
| 3962 </ptrtype> | |
| 3963 <description> | |
| 3964 Reserved for future use.. | |
| 3965 </description> | |
| 3966 </field> | |
| 3967 <field id="reserved15"> | |
| 3968 <ptrtype> | |
| 3969 <struct>jvmtiReservedCallback</struct> | |
| 3970 </ptrtype> | |
| 3971 <description> | |
| 3972 Reserved for future use.. | |
| 3973 </description> | |
| 3974 </field> | |
| 3975 </typedef> | |
| 3976 | |
| 3977 | |
| 3978 <intro> | |
| 3979 <rationale> | |
| 3980 The heap dumping functionality (below) uses a callback | |
| 3981 for each object. While it would seem that a buffered approach | |
| 3982 would provide better throughput, tests do | |
| 3983 not show this to be the case--possibly due to locality of | |
| 3984 memory reference or array access overhead. | |
| 3985 </rationale> | |
| 3986 | |
| 3987 <issue> | |
| 3988 Still under investigation as to if java.lang.ref references | |
| 3989 are reported as a different type of reference. | |
| 3990 </issue> | |
| 3991 | |
| 3992 <issue> | |
| 3993 Should or can an indication of the cost or relative cost of | |
| 3994 these operations be included? | |
| 3995 </issue> | |
| 3996 | |
| 3997 </intro> | |
| 3998 | |
| 3999 <callback id="jvmtiHeapIterationCallback" since="1.1"> | |
| 4000 <jint/> | |
| 4001 <synopsis>Heap Iteration Callback</synopsis> | |
| 4002 <description> | |
| 4003 Agent supplied callback function. | |
| 4004 Describes (but does not pass in) an object in the heap. | |
| 4005 <p/> | |
| 4006 This function should return a bit vector of the desired | |
| 4007 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4008 This will determine if the entire iteration should be aborted | |
| 4009 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4010 <p/> | |
| 4011 See the <internallink id="heapCallbacks">heap callback | |
| 4012 function restrictions</internallink>. | |
| 4013 </description> | |
| 4014 <parameters> | |
| 4015 <param id="class_tag"> | |
| 4016 <jlong/> | |
| 4017 <description> | |
| 4018 The tag of the class of object (zero if the class is not tagged). | |
| 4019 If the object represents a runtime class, | |
| 4020 the <code>class_tag</code> is the tag | |
| 4021 associated with <code>java.lang.Class</code> | |
| 4022 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4023 </description> | |
| 4024 </param> | |
| 4025 <param id="size"> | |
| 4026 <jlong/> | |
| 4027 <description> | |
| 4028 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 4029 </description> | |
| 4030 </param> | |
| 4031 <param id="tag_ptr"> | |
| 4032 <outptr><jlong/></outptr> | |
| 4033 <description> | |
| 4034 The object tag value, or zero if the object is not tagged. | |
| 4035 To set the tag value to be associated with the object | |
| 4036 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4037 </description> | |
| 4038 </param> | |
| 4039 <param id="length"> | |
| 4040 <jint/> | |
| 4041 <description> | |
| 4042 If this object is an array, the length of the array. Otherwise negative one (-1). | |
| 4043 </description> | |
| 4044 </param> | |
| 4045 <param id="user_data"> | |
| 4046 <outptr><void/></outptr> | |
| 4047 <description> | |
| 4048 The user supplied data that was passed into the iteration function. | |
| 4049 </description> | |
| 4050 </param> | |
| 4051 </parameters> | |
| 4052 </callback> | |
| 4053 | |
| 4054 <callback id="jvmtiHeapReferenceCallback" since="1.1"> | |
| 4055 <jint/> | |
| 4056 <synopsis>Heap Reference Callback</synopsis> | |
| 4057 <description> | |
| 4058 Agent supplied callback function. | |
| 4059 Describes a reference from an object or the VM (the referrer) to another object | |
| 4060 (the referree) or a heap root to a referree. | |
| 4061 <p/> | |
| 4062 This function should return a bit vector of the desired | |
| 4063 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4064 This will determine if the objects referenced by the referree | |
| 4065 should be visited or if the entire iteration should be aborted. | |
| 4066 <p/> | |
| 4067 See the <internallink id="heapCallbacks">heap callback | |
| 4068 function restrictions</internallink>. | |
| 4069 </description> | |
| 4070 <parameters> | |
| 4071 <param id="reference_kind"> | |
| 4072 <enum>jvmtiHeapReferenceKind</enum> | |
| 4073 <description> | |
| 4074 The kind of reference. | |
| 4075 </description> | |
| 4076 </param> | |
| 4077 <param id="reference_info"> | |
| 4078 <inptr> | |
| 4079 <struct>jvmtiHeapReferenceInfo</struct> | |
| 4080 </inptr> | |
| 4081 <description> | |
| 4082 Details about the reference. | |
| 6919 | 4083 Set when the <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> is |
| 0 | 4084 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, |
| 4085 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, | |
| 4086 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>, | |
| 4087 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>, | |
| 4088 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>, | |
| 4089 or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>. | |
| 4090 Otherwise <code>NULL</code>. | |
| 4091 </description> | |
| 4092 </param> | |
| 4093 <param id="class_tag"> | |
| 4094 <jlong/> | |
| 4095 <description> | |
| 4096 The tag of the class of referree object (zero if the class is not tagged). | |
| 4097 If the referree object represents a runtime class, | |
| 4098 the <code>class_tag</code> is the tag | |
| 4099 associated with <code>java.lang.Class</code> | |
| 4100 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4101 </description> | |
| 4102 </param> | |
| 4103 <param id="referrer_class_tag"> | |
| 4104 <jlong/> | |
| 4105 <description> | |
| 4106 The tag of the class of the referrer object (zero if the class is not tagged | |
| 4107 or the referree is a heap root). If the referrer object represents a runtime | |
| 4108 class, the <code>referrer_class_tag</code> is the tag associated with | |
| 4109 the <code>java.lang.Class</code> | |
| 4110 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4111 </description> | |
| 4112 </param> | |
| 4113 <param id="size"> | |
| 4114 <jlong/> | |
| 4115 <description> | |
| 4116 Size of the referree object (in bytes). | |
| 4117 See <functionlink id="GetObjectSize"/>. | |
| 4118 </description> | |
| 4119 </param> | |
| 4120 <param id="tag_ptr"> | |
| 4121 <outptr><jlong/></outptr> | |
| 4122 <description> | |
| 4123 Points to the referree object tag value, or zero if the object is not | |
| 4124 tagged. | |
| 4125 To set the tag value to be associated with the object | |
| 4126 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4127 </description> | |
| 4128 </param> | |
| 4129 <param id="referrer_tag_ptr"> | |
| 4130 <outptr><jlong/></outptr> | |
| 4131 <description> | |
| 4132 Points to the tag of the referrer object, or | |
| 4133 points to the zero if the referrer | |
| 4134 object is not tagged. | |
| 4135 <code>NULL</code> if the referrer in not an object (that is, | |
| 4136 this callback is reporting a heap root). | |
| 4137 To set the tag value to be associated with the referrer object | |
| 4138 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4139 If this callback is reporting a reference from an object to itself, | |
| 4140 <code>referrer_tag_ptr == tag_ptr</code>. | |
| 4141 </description> | |
| 4142 </param> | |
| 4143 <param id="length"> | |
| 4144 <jint/> | |
| 4145 <description> | |
| 4146 If this object is an array, the length of the array. Otherwise negative one (-1). | |
| 4147 </description> | |
| 4148 </param> | |
| 4149 <param id="user_data"> | |
| 4150 <outptr><void/></outptr> | |
| 4151 <description> | |
| 4152 The user supplied data that was passed into the iteration function. | |
| 4153 </description> | |
| 4154 </param> | |
| 4155 </parameters> | |
| 4156 </callback> | |
| 4157 | |
| 4158 <callback id="jvmtiPrimitiveFieldCallback" since="1.1"> | |
| 4159 <jint/> | |
| 4160 <synopsis>Primitive Field Callback</synopsis> | |
| 4161 <description> | |
| 4162 Agent supplied callback function which | |
| 4163 describes a primitive field of an object (<i>the object</i>). | |
| 4164 A primitive field is a field whose type is a primitive type. | |
| 4165 This callback will describe a static field if the object is a class, | |
| 4166 and otherwise will describe an instance field. | |
| 4167 <p/> | |
| 4168 This function should return a bit vector of the desired | |
| 4169 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4170 This will determine if the entire iteration should be aborted | |
| 4171 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4172 <p/> | |
| 4173 See the <internallink id="heapCallbacks">heap callback | |
| 4174 function restrictions</internallink>. | |
| 4175 </description> | |
| 4176 <parameters> | |
| 4177 <param id="kind"> | |
| 4178 <enum>jvmtiHeapReferenceKind</enum> | |
| 4179 <description> | |
| 4180 The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or | |
| 4181 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>). | |
| 4182 </description> | |
| 4183 </param> | |
| 4184 <param id="info"> | |
| 4185 <inptr> | |
| 4186 <struct>jvmtiHeapReferenceInfo</struct> | |
| 4187 </inptr> | |
| 4188 <description> | |
| 4189 Which field (the field index). | |
| 4190 </description> | |
| 4191 </param> | |
| 4192 <param id="object_class_tag"> | |
| 4193 <jlong/> | |
| 4194 <description> | |
| 4195 The tag of the class of the object (zero if the class is not tagged). | |
| 4196 If the object represents a runtime class, the | |
| 4197 <code>object_class_tag</code> is the tag | |
| 4198 associated with <code>java.lang.Class</code> | |
| 4199 (zero if <code>java.lang.Class</code> is not tagged). | |
| 4200 </description> | |
| 4201 </param> | |
| 4202 <param id="object_tag_ptr"> | |
| 4203 <outptr><jlong/></outptr> | |
| 4204 <description> | |
| 4205 Points to the tag of the object, or zero if the object is not | |
| 4206 tagged. | |
| 4207 To set the tag value to be associated with the object | |
| 4208 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4209 </description> | |
| 4210 </param> | |
| 4211 <param id="value"> | |
| 4212 <jvalue/> | |
| 4213 <description> | |
| 4214 The value of the field. | |
| 4215 </description> | |
| 4216 </param> | |
| 4217 <param id="value_type"> | |
| 4218 <enum>jvmtiPrimitiveType</enum> | |
| 4219 <description> | |
| 4220 The type of the field. | |
| 4221 </description> | |
| 4222 </param> | |
| 4223 <param id="user_data"> | |
| 4224 <outptr><void/></outptr> | |
| 4225 <description> | |
| 4226 The user supplied data that was passed into the iteration function. | |
| 4227 </description> | |
| 4228 </param> | |
| 4229 </parameters> | |
| 4230 </callback> | |
| 4231 | |
| 4232 <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1"> | |
| 4233 <jint/> | |
| 4234 <synopsis>Array Primitive Value Callback</synopsis> | |
| 4235 <description> | |
| 4236 Agent supplied callback function. | |
| 4237 Describes the values in an array of a primitive type. | |
| 4238 <p/> | |
| 4239 This function should return a bit vector of the desired | |
| 4240 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4241 This will determine if the entire iteration should be aborted | |
| 4242 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4243 <p/> | |
| 4244 See the <internallink id="heapCallbacks">heap callback | |
| 4245 function restrictions</internallink>. | |
| 4246 </description> | |
| 4247 <parameters> | |
| 4248 <param id="class_tag"> | |
| 4249 <jlong/> | |
| 4250 <description> | |
| 4251 The tag of the class of the array object (zero if the class is not tagged). | |
| 4252 </description> | |
| 4253 </param> | |
| 4254 <param id="size"> | |
| 4255 <jlong/> | |
| 4256 <description> | |
| 4257 Size of the array (in bytes). | |
| 4258 See <functionlink id="GetObjectSize"/>. | |
| 4259 </description> | |
| 4260 </param> | |
| 4261 <param id="tag_ptr"> | |
| 4262 <outptr><jlong/></outptr> | |
| 4263 <description> | |
| 4264 Points to the tag of the array object, or zero if the object is not | |
| 4265 tagged. | |
| 4266 To set the tag value to be associated with the object | |
| 4267 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4268 </description> | |
| 4269 </param> | |
| 4270 <param id="element_count"> | |
| 4271 <jint/> | |
| 4272 <description> | |
| 4273 The length of the primitive array. | |
| 4274 </description> | |
| 4275 </param> | |
| 4276 <param id="element_type"> | |
| 4277 <enum>jvmtiPrimitiveType</enum> | |
| 4278 <description> | |
| 4279 The type of the elements of the array. | |
| 4280 </description> | |
| 4281 </param> | |
| 4282 <param id="elements"> | |
| 4283 <vmbuf><void/></vmbuf> | |
| 4284 <description> | |
| 4285 The elements of the array in a packed array of <code>element_count</code> | |
| 4286 items of <code>element_type</code> size each. | |
| 4287 </description> | |
| 4288 </param> | |
| 4289 <param id="user_data"> | |
| 4290 <outptr><void/></outptr> | |
| 4291 <description> | |
| 4292 The user supplied data that was passed into the iteration function. | |
| 4293 </description> | |
| 4294 </param> | |
| 4295 </parameters> | |
| 4296 </callback> | |
| 4297 | |
| 4298 <callback id="jvmtiStringPrimitiveValueCallback" since="1.1"> | |
| 4299 <jint/> | |
| 4300 <synopsis>String Primitive Value Callback</synopsis> | |
| 4301 <description> | |
| 4302 Agent supplied callback function. | |
| 4303 Describes the value of a java.lang.String. | |
| 4304 <p/> | |
| 4305 This function should return a bit vector of the desired | |
| 4306 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
| 4307 This will determine if the entire iteration should be aborted | |
| 4308 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
| 4309 <p/> | |
| 4310 See the <internallink id="heapCallbacks">heap callback | |
| 4311 function restrictions</internallink>. | |
| 4312 </description> | |
| 4313 <parameters> | |
| 4314 <param id="class_tag"> | |
| 4315 <jlong/> | |
| 4316 <description> | |
| 4317 The tag of the class of the String class (zero if the class is not tagged). | |
| 4318 <issue>Is this needed?</issue> | |
| 4319 </description> | |
| 4320 </param> | |
| 4321 <param id="size"> | |
| 4322 <jlong/> | |
| 4323 <description> | |
| 4324 Size of the string (in bytes). | |
| 4325 See <functionlink id="GetObjectSize"/>. | |
| 4326 </description> | |
| 4327 </param> | |
| 4328 <param id="tag_ptr"> | |
| 4329 <outptr><jlong/></outptr> | |
| 4330 <description> | |
| 4331 Points to the tag of the String object, or zero if the object is not | |
| 4332 tagged. | |
| 4333 To set the tag value to be associated with the object | |
| 4334 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 4335 </description> | |
| 4336 </param> | |
| 4337 <param id="value"> | |
| 4338 <vmbuf><jchar/></vmbuf> | |
| 4339 <description> | |
| 4340 The value of the String, encoded as a Unicode string. | |
| 4341 </description> | |
| 4342 </param> | |
| 4343 <param id="value_length"> | |
| 4344 <jint/> | |
| 4345 <description> | |
| 4346 The length of the string. | |
| 4347 The length is equal to the number of 16-bit Unicode | |
| 4348 characters in the string. | |
| 4349 </description> | |
| 4350 </param> | |
| 4351 <param id="user_data"> | |
| 4352 <outptr><void/></outptr> | |
| 4353 <description> | |
| 4354 The user supplied data that was passed into the iteration function. | |
| 4355 </description> | |
| 4356 </param> | |
| 4357 </parameters> | |
| 4358 </callback> | |
| 4359 | |
| 4360 | |
| 4361 <callback id="jvmtiReservedCallback" since="1.1"> | |
| 4362 <jint/> | |
| 4363 <synopsis>reserved for future use Callback</synopsis> | |
| 4364 <description> | |
| 4365 Placeholder -- reserved for future use. | |
| 4366 </description> | |
| 4367 <parameters> | |
| 4368 </parameters> | |
| 4369 </callback> | |
| 4370 | |
| 4371 <function id="FollowReferences" num="115" since="1.1"> | |
| 4372 <synopsis>Follow References</synopsis> | |
| 4373 <description> | |
| 4374 This function initiates a traversal over the objects that are | |
| 4375 directly and indirectly reachable from the specified object or, | |
| 4376 if <code>initial_object</code> is not specified, all objects | |
| 4377 reachable from the heap roots. | |
| 4378 The heap root are the set of system classes, | |
| 4379 JNI globals, references from thread stacks, and other objects used as roots | |
| 4380 for the purposes of garbage collection. | |
| 4381 <p/> | |
| 4382 This function operates by traversing the reference graph. | |
| 4383 Let <i>A</i>, <i>B</i>, ... represent objects. | |
| 4384 When a reference from <i>A</i> to <i>B</i> is traversed, | |
| 4385 when a reference from a heap root to <i>B</i> is traversed, | |
| 4386 or when <i>B</i> is specified as the <paramlink id="initial_object"/>, | |
| 4387 then <i>B</i> is said to be <i>visited</i>. | |
| 4388 A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i> | |
| 4389 is visited. | |
| 4390 References are reported in the same order that the references are traversed. | |
| 4391 Object references are reported by invoking the agent supplied | |
| 4392 callback function <functionlink id="jvmtiHeapReferenceCallback"/>. | |
| 4393 In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known | |
| 4394 as the <i>referrer</i> and <i>B</i> as the <i>referree</i>. | |
| 4395 The callback is invoked exactly once for each reference from a referrer; | |
| 4396 this is true even if there are reference cycles or multiple paths to | |
| 4397 the referrer. | |
| 4398 There may be more than one reference between a referrer and a referree, | |
| 4399 each reference is reported. | |
| 4400 These references may be distinguished by examining the | |
| 4401 <datalink | |
| 4402 id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink> | |
| 4403 and | |
| 4404 <datalink | |
| 4405 id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink> | |
| 4406 parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback. | |
| 4407 <p/> | |
| 4408 This function reports a Java programming language view of object references, | |
| 4409 not a virtual machine implementation view. The following object references | |
| 4410 are reported when they are non-null: | |
| 4411 <ul> | |
| 4412 <li>Instance objects report references to each non-primitive instance fields | |
| 4413 (including inherited fields).</li> | |
| 4414 <li>Instance objects report a reference to the object type (class).</li> | |
| 4415 <li>Classes report a reference to the superclass and directly | |
| 4416 implemented/extended interfaces.</li> | |
| 4417 <li>Classes report a reference to the class loader, protection domain, | |
| 4418 signers, and resolved entries in the constant pool.</li> | |
| 4419 <li>Classes report a reference to each directly declared non-primitive | |
| 4420 static field.</li> | |
| 4421 <li>Arrays report a reference to the array type (class) and each | |
| 4422 array element.</li> | |
| 4423 <li>Primitive arrays report a reference to the array type.</li> | |
| 4424 </ul> | |
| 4425 <p/> | |
| 4426 This function can also be used to examine primitive (non-object) values. | |
| 4427 The primitive value of an array or String | |
| 4428 is reported after the object has been visited; | |
| 4429 it is reported by invoking the agent supplied callback function | |
| 4430 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or | |
| 4431 <functionlink id="jvmtiStringPrimitiveValueCallback"/>. | |
| 4432 A primitive field | |
| 4433 is reported after the object with that field is visited; | |
| 4434 it is reported by invoking the agent supplied callback function | |
| 4435 <functionlink id="jvmtiPrimitiveFieldCallback"/>. | |
| 4436 <p/> | |
| 4437 Whether a callback is provided or is <code>NULL</code> only determines | |
| 4438 whether the callback will be invoked, it does not influence | |
| 4439 which objects are visited nor does it influence whether other callbacks | |
| 4440 will be invoked. | |
| 4441 However, the | |
| 4442 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink> | |
| 4443 returned by <functionlink id="jvmtiHeapReferenceCallback"/> | |
| 4444 do determine if the objects referenced by the | |
| 4445 current object as visited. | |
| 4446 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> | |
| 4447 and <paramlink id="klass"/> provided as parameters to this function | |
| 4448 do not control which objects are visited but they do control which | |
| 4449 objects and primitive values are reported by the callbacks. | |
| 4450 For example, if the only callback that was set is | |
| 6919 | 4451 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code> |
| 0 | 4452 is set to the array of bytes class, then only arrays of byte will be |
| 4453 reported. | |
| 4454 The table below summarizes this: | |
| 4455 <p/> | |
| 4456 <table> | |
| 4457 <tr> | |
| 4458 <th/> | |
| 4459 <th> | |
| 4460 Controls objects visited | |
| 4461 </th> | |
| 4462 <th> | |
| 4463 Controls objects reported | |
| 4464 </th> | |
| 4465 <th> | |
| 4466 Controls primitives reported | |
| 4467 </th> | |
| 4468 </tr> | |
| 4469 <tr> | |
| 4470 <th align="left"> | |
| 4471 the | |
| 4472 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
| 4473 returned by <functionlink id="jvmtiHeapReferenceCallback"/> | |
| 4474 </th> | |
| 4475 <td> | |
| 4476 <b>Yes</b> | |
| 4477 </td> | |
| 4478 <td> | |
| 4479 <b>Yes</b>, since visits are controlled | |
| 4480 </td> | |
| 4481 <td> | |
| 4482 <b>Yes</b>, since visits are controlled | |
| 4483 </td> | |
| 4484 </tr> | |
| 4485 <tr> | |
| 4486 <th align="left"> | |
| 6919 | 4487 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> |
| 0 | 4488 in <paramlink id="callbacks"/> set |
| 4489 </th> | |
| 4490 <td> | |
| 4491 No | |
| 4492 </td> | |
| 4493 <td> | |
| 4494 <b>Yes</b> | |
| 4495 </td> | |
| 4496 <td> | |
| 4497 No | |
| 4498 </td> | |
| 4499 </tr> | |
| 4500 <tr> | |
| 4501 <th align="left"> | |
| 4502 <paramlink id="heap_filter"/> | |
| 4503 </th> | |
| 4504 <td> | |
| 4505 No | |
| 4506 </td> | |
| 4507 <td> | |
| 4508 <b>Yes</b> | |
| 4509 </td> | |
| 4510 <td> | |
| 4511 <b>Yes</b> | |
| 4512 </td> | |
| 4513 </tr> | |
| 4514 <tr> | |
| 4515 <th align="left"> | |
| 4516 <paramlink id="klass"/> | |
| 4517 </th> | |
| 4518 <td> | |
| 4519 No | |
| 4520 </td> | |
| 4521 <td> | |
| 4522 <b>Yes</b> | |
| 4523 </td> | |
| 4524 <td> | |
| 4525 <b>Yes</b> | |
| 4526 </td> | |
| 4527 </tr> | |
| 4528 </table> | |
| 4529 <p/> | |
| 4530 During the execution of this function the state of the heap | |
| 4531 does not change: no objects are allocated, no objects are | |
| 4532 garbage collected, and the state of objects (including | |
| 4533 held values) does not change. | |
| 4534 As a result, threads executing Java | |
| 4535 programming language code, threads attempting to resume the | |
| 4536 execution of Java programming language code, and threads | |
| 4537 attempting to execute JNI functions are typically stalled. | |
| 4538 </description> | |
| 4539 <origin>new</origin> | |
| 4540 <capabilities> | |
| 4541 <required id="can_tag_objects"></required> | |
| 4542 </capabilities> | |
| 4543 <parameters> | |
| 4544 <param id="heap_filter"> | |
| 4545 <jint/> | |
| 4546 <description> | |
| 4547 This bit vector of | |
| 4548 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>. | |
| 4549 restricts the objects for which the callback function is called. | |
| 4550 This applies to both the object and primitive callbacks. | |
| 4551 </description> | |
| 4552 </param> | |
| 4553 <param id="klass"> | |
| 4554 <ptrtype> | |
| 4555 <jclass/> | |
| 4556 <nullok>callbacks are not limited to instances of a particular | |
| 4557 class</nullok> | |
| 4558 </ptrtype> | |
| 4559 <description> | |
| 4560 Callbacks are only reported when the object is an instance of | |
| 4561 this class. | |
| 4562 Objects which are instances of a subclass of <code>klass</code> | |
| 4563 are not reported. | |
| 4564 If <code>klass</code> is an interface, no objects are reported. | |
| 4565 This applies to both the object and primitive callbacks. | |
| 4566 </description> | |
| 4567 </param> | |
| 4568 <param id="initial_object"> | |
| 4569 <ptrtype> | |
| 4570 <jobject/> | |
| 4571 <nullok>references are followed from the heap roots</nullok> | |
| 4572 </ptrtype> | |
| 4573 <description> | |
| 4574 The object to follow | |
| 4575 </description> | |
| 4576 </param> | |
| 4577 <param id="callbacks"> | |
| 4578 <inptr> | |
| 4579 <struct>jvmtiHeapCallbacks</struct> | |
| 4580 </inptr> | |
| 4581 <description> | |
| 4582 Structure defining the set of callback functions. | |
| 4583 </description> | |
| 4584 </param> | |
| 4585 <param id="user_data"> | |
| 4586 <inbuf> | |
| 4587 <void/> | |
| 4588 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 4589 </inbuf> | |
| 4590 <description> | |
| 4591 User supplied data to be passed to the callback. | |
| 4592 </description> | |
| 4593 </param> | |
| 4594 </parameters> | |
| 4595 <errors> | |
| 4596 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 4597 <paramlink id="klass"/> is not a valid class. | |
| 4598 </error> | |
| 4599 <error id="JVMTI_ERROR_INVALID_OBJECT"> | |
| 4600 <paramlink id="initial_object"/> is not a valid object. | |
| 4601 </error> | |
| 4602 </errors> | |
| 4603 </function> | |
| 4604 | |
| 4605 | |
| 4606 <function id="IterateThroughHeap" num="116" since="1.1"> | |
| 4607 <synopsis>Iterate Through Heap</synopsis> | |
| 4608 <description> | |
| 4609 Initiate an iteration over all objects in the heap. | |
| 4610 This includes both reachable and | |
| 4611 unreachable objects. Objects are visited in no particular order. | |
| 4612 <p/> | |
| 4613 Heap objects are reported by invoking the agent supplied | |
| 4614 callback function <functionlink id="jvmtiHeapIterationCallback"/>. | |
| 4615 References between objects are not reported. | |
| 4616 If only reachable objects are desired, or if object reference information | |
| 4617 is needed, use <functionlink id="FollowReferences"/>. | |
| 4618 <p/> | |
| 4619 This function can also be used to examine primitive (non-object) values. | |
| 4620 The primitive value of an array or String | |
| 4621 is reported after the object has been visited; | |
| 4622 it is reported by invoking the agent supplied callback function | |
| 4623 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or | |
| 4624 <functionlink id="jvmtiStringPrimitiveValueCallback"/>. | |
| 4625 A primitive field | |
| 4626 is reported after the object with that field is visited; | |
| 4627 it is reported by invoking the agent supplied | |
| 4628 callback function | |
| 4629 <functionlink id="jvmtiPrimitiveFieldCallback"/>. | |
| 4630 <p/> | |
| 4631 Unless the iteration is aborted by the | |
| 4632 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
| 4633 returned by a callback, all objects in the heap are visited. | |
| 4634 Whether a callback is provided or is <code>NULL</code> only determines | |
| 4635 whether the callback will be invoked, it does not influence | |
| 4636 which objects are visited nor does it influence whether other callbacks | |
| 4637 will be invoked. | |
| 4638 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> | |
| 4639 and <paramlink id="klass"/> provided as parameters to this function | |
| 4640 do not control which objects are visited but they do control which | |
| 4641 objects and primitive values are reported by the callbacks. | |
| 4642 For example, if the only callback that was set is | |
| 6919 | 4643 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code> |
| 0 | 4644 is set to the array of bytes class, then only arrays of byte will be |
| 4645 reported. The table below summarizes this (contrast this with | |
| 4646 <functionlink id="FollowReferences"/>): | |
| 4647 <p/> | |
| 4648 <table> | |
| 4649 <tr> | |
| 4650 <th/> | |
| 4651 <th> | |
| 4652 Controls objects visited | |
| 4653 </th> | |
| 4654 <th> | |
| 4655 Controls objects reported | |
| 4656 </th> | |
| 4657 <th> | |
| 4658 Controls primitives reported | |
| 4659 </th> | |
| 4660 </tr> | |
| 4661 <tr> | |
| 4662 <th align="left"> | |
| 4663 the | |
| 4664 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
| 4665 returned by <functionlink id="jvmtiHeapIterationCallback"/> | |
| 4666 </th> | |
| 4667 <td> | |
| 4668 No<br/>(unless they abort the iteration) | |
| 4669 </td> | |
| 4670 <td> | |
| 4671 No<br/>(unless they abort the iteration) | |
| 4672 </td> | |
| 4673 <td> | |
| 4674 No<br/>(unless they abort the iteration) | |
| 4675 </td> | |
| 4676 </tr> | |
| 4677 <tr> | |
| 4678 <th align="left"> | |
| 6919 | 4679 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> |
| 0 | 4680 in <paramlink id="callbacks"/> set |
| 4681 </th> | |
| 4682 <td> | |
| 4683 No | |
| 4684 </td> | |
| 4685 <td> | |
| 4686 <b>Yes</b> | |
| 4687 </td> | |
| 4688 <td> | |
| 4689 No | |
| 4690 </td> | |
| 4691 </tr> | |
| 4692 <tr> | |
| 4693 <th align="left"> | |
| 4694 <paramlink id="heap_filter"/> | |
| 4695 </th> | |
| 4696 <td> | |
| 4697 No | |
| 4698 </td> | |
| 4699 <td> | |
| 4700 <b>Yes</b> | |
| 4701 </td> | |
| 4702 <td> | |
| 4703 <b>Yes</b> | |
| 4704 </td> | |
| 4705 </tr> | |
| 4706 <tr> | |
| 4707 <th align="left"> | |
| 4708 <paramlink id="klass"/> | |
| 4709 </th> | |
| 4710 <td> | |
| 4711 No | |
| 4712 </td> | |
| 4713 <td> | |
| 4714 <b>Yes</b> | |
| 4715 </td> | |
| 4716 <td> | |
| 4717 <b>Yes</b> | |
| 4718 </td> | |
| 4719 </tr> | |
| 4720 </table> | |
| 4721 <p/> | |
| 4722 During the execution of this function the state of the heap | |
| 4723 does not change: no objects are allocated, no objects are | |
| 4724 garbage collected, and the state of objects (including | |
| 4725 held values) does not change. | |
| 4726 As a result, threads executing Java | |
| 4727 programming language code, threads attempting to resume the | |
| 4728 execution of Java programming language code, and threads | |
| 4729 attempting to execute JNI functions are typically stalled. | |
| 4730 </description> | |
| 4731 <origin>new</origin> | |
| 4732 <capabilities> | |
| 4733 <required id="can_tag_objects"></required> | |
| 4734 </capabilities> | |
| 4735 <parameters> | |
| 4736 <param id="heap_filter"> | |
| 4737 <jint/> | |
| 4738 <description> | |
| 4739 This bit vector of | |
| 4740 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>. | |
| 4741 restricts the objects for which the callback function is called. | |
| 4742 This applies to both the object and primitive callbacks. | |
| 4743 </description> | |
| 4744 </param> | |
| 4745 <param id="klass"> | |
| 4746 <ptrtype> | |
| 4747 <jclass/> | |
| 4748 <nullok>callbacks are not limited to instances of a particular class</nullok> | |
| 4749 </ptrtype> | |
| 4750 <description> | |
| 4751 Callbacks are only reported when the object is an instance of | |
| 4752 this class. | |
| 4753 Objects which are instances of a subclass of <code>klass</code> | |
| 4754 are not reported. | |
| 4755 If <code>klass</code> is an interface, no objects are reported. | |
| 4756 This applies to both the object and primitive callbacks. | |
| 4757 </description> | |
| 4758 </param> | |
| 4759 <param id="callbacks"> | |
| 4760 <inptr> | |
| 4761 <struct>jvmtiHeapCallbacks</struct> | |
| 4762 </inptr> | |
| 4763 <description> | |
| 4764 Structure defining the set callback functions. | |
| 4765 </description> | |
| 4766 </param> | |
| 4767 <param id="user_data"> | |
| 4768 <inbuf> | |
| 4769 <void/> | |
| 4770 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 4771 </inbuf> | |
| 4772 <description> | |
| 4773 User supplied data to be passed to the callback. | |
| 4774 </description> | |
| 4775 </param> | |
| 4776 </parameters> | |
| 4777 <errors> | |
| 4778 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 4779 <paramlink id="klass"/> is not a valid class. | |
| 4780 </error> | |
| 4781 </errors> | |
| 4782 </function> | |
| 4783 | |
| 4784 <function id="GetTag" phase="start" num="106"> | |
| 4785 <synopsis>Get Tag</synopsis> | |
| 4786 <description> | |
| 4787 Retrieve the tag associated with an object. | |
| 4788 The tag is a long value typically used to store a | |
| 4789 unique identifier or pointer to object information. | |
| 4790 The tag is set with | |
| 4791 <functionlink id="SetTag"></functionlink>. | |
| 4792 Objects for which no tags have been set return a | |
| 4793 tag value of zero. | |
| 4794 </description> | |
| 4795 <origin>new</origin> | |
| 4796 <capabilities> | |
| 4797 <required id="can_tag_objects"></required> | |
| 4798 </capabilities> | |
| 4799 <parameters> | |
| 4800 <param id="object"> | |
| 4801 <jobject/> | |
| 4802 <description> | |
| 4803 The object whose tag is to be retrieved. | |
| 4804 </description> | |
| 4805 </param> | |
| 4806 <param id="tag_ptr"> | |
| 4807 <outptr><jlong/></outptr> | |
| 4808 <description> | |
| 4809 On return, the referenced long is set to the value | |
| 4810 of the tag. | |
| 4811 </description> | |
| 4812 </param> | |
| 4813 </parameters> | |
| 4814 <errors> | |
| 4815 </errors> | |
| 4816 </function> | |
| 4817 | |
| 4818 <function id="SetTag" phase="start" num="107"> | |
| 4819 <synopsis>Set Tag</synopsis> | |
| 4820 <description> | |
| 4821 Set the tag associated with an object. | |
| 4822 The tag is a long value typically used to store a | |
| 4823 unique identifier or pointer to object information. | |
| 4824 The tag is visible with | |
| 4825 <functionlink id="GetTag"></functionlink>. | |
| 4826 </description> | |
| 4827 <origin>new</origin> | |
| 4828 <capabilities> | |
| 4829 <required id="can_tag_objects"></required> | |
| 4830 </capabilities> | |
| 4831 <parameters> | |
| 4832 <param id="object"> | |
| 4833 <jobject/> | |
| 4834 <description> | |
| 4835 The object whose tag is to be set. | |
| 4836 </description> | |
| 4837 </param> | |
| 4838 <param id="tag"> | |
| 4839 <jlong/> | |
| 4840 <description> | |
| 4841 The new value of the tag. | |
| 4842 </description> | |
| 4843 </param> | |
| 4844 </parameters> | |
| 4845 <errors> | |
| 4846 </errors> | |
| 4847 </function> | |
| 4848 | |
| 4849 <function id="GetObjectsWithTags" num="114"> | |
| 4850 <synopsis>Get Objects With Tags</synopsis> | |
| 4851 <description> | |
| 4852 Return objects in the heap with the specified tags. | |
| 4853 The format is parallel arrays of objects and tags. | |
| 4854 </description> | |
| 4855 <origin>new</origin> | |
| 4856 <capabilities> | |
| 4857 <required id="can_tag_objects"></required> | |
| 4858 </capabilities> | |
| 4859 <parameters> | |
| 4860 <param id="tag_count"> | |
| 4861 <jint min="0"/> | |
| 4862 <description> | |
| 4863 Number of tags to scan for. | |
| 4864 </description> | |
| 4865 </param> | |
| 4866 <param id="tags"> | |
| 4867 <inbuf incount="tag_count"> | |
| 4868 <jlong/> | |
| 4869 </inbuf> | |
| 4870 <description> | |
| 4871 Scan for objects with these tags. | |
| 4872 Zero is not permitted in this array. | |
| 4873 </description> | |
| 4874 </param> | |
| 4875 <param id="count_ptr"> | |
| 4876 <outptr> | |
| 4877 <jint/> | |
| 4878 </outptr> | |
| 4879 <description> | |
| 4880 Return the number of objects with any of the tags | |
| 4881 in <paramlink id="tags"/>. | |
| 4882 </description> | |
| 4883 </param> | |
| 4884 <param id="object_result_ptr"> | |
| 4885 <allocbuf outcount="count_ptr"> | |
| 4886 <jobject/> | |
| 4887 <nullok>this information is not returned</nullok> | |
| 4888 </allocbuf> | |
| 4889 <description> | |
| 4890 Returns the array of objects with any of the tags | |
| 4891 in <paramlink id="tags"/>. | |
| 4892 </description> | |
| 4893 </param> | |
| 4894 <param id="tag_result_ptr"> | |
| 4895 <allocbuf outcount="count_ptr"> | |
| 4896 <jlong/> | |
| 4897 <nullok>this information is not returned</nullok> | |
| 4898 </allocbuf> | |
| 4899 <description> | |
| 4900 For each object in <paramlink id="object_result_ptr"/>, | |
| 4901 return the tag at the corresponding index. | |
| 4902 </description> | |
| 4903 </param> | |
| 4904 </parameters> | |
| 4905 <errors> | |
| 4906 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 4907 Zero is present in <paramlink id="tags"></paramlink>. | |
| 4908 </error> | |
| 4909 </errors> | |
| 4910 </function> | |
| 4911 | |
| 4912 <function id="ForceGarbageCollection" num="108"> | |
| 4913 <synopsis>Force Garbage Collection</synopsis> | |
| 4914 <description> | |
| 4915 Force the VM to perform a garbage collection. | |
| 4916 The garbage collection is as complete as possible. | |
| 4917 This function does not cause finalizers to be run. | |
| 4918 This function does not return until the garbage collection | |
| 4919 is finished. | |
| 4920 <p/> | |
| 4921 Although garbage collection is as complete | |
| 4922 as possible there is no guarantee that all | |
| 4923 <eventlink id="ObjectFree"/> | |
| 4924 events will have been | |
| 4925 sent by the time that this function | |
| 4926 returns. In particular, an object may be | |
| 4927 prevented from being freed because it | |
| 4928 is awaiting finalization. | |
| 4929 </description> | |
| 4930 <origin>new</origin> | |
| 4931 <capabilities> | |
| 4932 </capabilities> | |
| 4933 <parameters> | |
| 4934 </parameters> | |
| 4935 <errors> | |
| 4936 </errors> | |
| 4937 </function> | |
| 4938 | |
| 4939 | |
| 4940 </category> | |
| 4941 | |
| 4942 <category id="Heap_1_0" label="Heap (1.0)"> | |
| 4943 <intro> | |
| 4944 <b> | |
| 4945 These functions and data types were introduced in the original | |
| 4946 <jvmti/> version 1.0 and have been superseded by more | |
| 4947 </b> | |
| 4948 <internallink id="Heap"><b>powerful and flexible versions</b></internallink> | |
| 4949 <b> | |
| 4950 which: | |
| 4951 </b> | |
| 4952 <ul> | |
| 4953 <li> | |
| 4954 <b> | |
| 4955 Allow access to primitive values (the value of Strings, arrays, | |
| 4956 and primitive fields) | |
| 4957 </b> | |
| 4958 </li> | |
| 4959 <li> | |
| 4960 <b> | |
| 4961 Allow the tag of the referrer to be set, thus enabling more | |
| 4962 efficient localized reference graph building | |
| 4963 </b> | |
| 4964 </li> | |
| 4965 <li> | |
| 4966 <b> | |
| 4967 Provide more extensive filtering abilities | |
| 4968 </b> | |
| 4969 </li> | |
| 4970 <li> | |
| 4971 <b> | |
| 4972 Are extensible, allowing their abilities to grow in future versions of <jvmti/> | |
| 4973 </b> | |
| 4974 </li> | |
| 4975 </ul> | |
| 4976 <p/> | |
| 4977 <b>Please use the </b> | |
| 4978 <internallink id="Heap"><b>current Heap functions</b></internallink>. | |
| 4979 <p/> | |
| 4980 <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum"> | |
| 4981 <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1"> | |
| 4982 Tagged objects only. | |
| 4983 </constant> | |
| 4984 <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2"> | |
| 4985 Untagged objects only. | |
| 4986 </constant> | |
| 4987 <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3"> | |
| 4988 Either tagged or untagged objects. | |
| 4989 </constant> | |
| 4990 </constants> | |
| 4991 | |
| 4992 <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum"> | |
| 4993 <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1"> | |
| 4994 JNI global reference. | |
| 4995 </constant> | |
| 4996 <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2"> | |
| 4997 System class. | |
| 4998 </constant> | |
| 4999 <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3"> | |
| 5000 Monitor. | |
| 5001 </constant> | |
| 5002 <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4"> | |
| 5003 Stack local. | |
| 5004 </constant> | |
| 5005 <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5"> | |
| 5006 JNI local reference. | |
| 5007 </constant> | |
| 5008 <constant id="JVMTI_HEAP_ROOT_THREAD" num="6"> | |
| 5009 Thread. | |
| 5010 </constant> | |
| 5011 <constant id="JVMTI_HEAP_ROOT_OTHER" num="7"> | |
| 5012 Other. | |
| 5013 </constant> | |
| 5014 </constants> | |
| 5015 | |
| 5016 <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum"> | |
| 5017 <constant id="JVMTI_REFERENCE_CLASS" num="1"> | |
| 5018 Reference from an object to its class. | |
| 5019 </constant> | |
| 5020 <constant id="JVMTI_REFERENCE_FIELD" num="2"> | |
| 5021 Reference from an object to the value of one of its instance fields. | |
| 5022 For references of this kind the <code>referrer_index</code> | |
| 5023 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 5024 jvmtiObjectReferenceCallback</internallink> is the index of the | |
| 5025 the instance field. The index is based on the order of all the | |
| 5026 object's fields. This includes all fields of the directly declared | |
| 5027 static and instance fields in the class, and includes all fields (both | |
| 5028 public and private) fields declared in superclasses and superinterfaces. | |
| 5029 The index is thus calculated by summing the index of the field in the directly | |
| 5030 declared class (see <functionlink id="GetClassFields"/>), with the total | |
| 5031 number of fields (both public and private) declared in all superclasses | |
| 5032 and superinterfaces. The index starts at zero. | |
| 5033 </constant> | |
| 5034 <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3"> | |
| 5035 Reference from an array to one of its elements. | |
| 5036 For references of this kind the <code>referrer_index</code> | |
| 5037 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 5038 jvmtiObjectReferenceCallback</internallink> is the array index. | |
| 5039 </constant> | |
| 5040 <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4"> | |
| 5041 Reference from a class to its class loader. | |
| 5042 </constant> | |
| 5043 <constant id="JVMTI_REFERENCE_SIGNERS" num="5"> | |
| 5044 Reference from a class to its signers array. | |
| 5045 </constant> | |
| 5046 <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6"> | |
| 5047 Reference from a class to its protection domain. | |
| 5048 </constant> | |
| 5049 <constant id="JVMTI_REFERENCE_INTERFACE" num="7"> | |
| 5050 Reference from a class to one of its interfaces. | |
| 5051 </constant> | |
| 5052 <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8"> | |
| 5053 Reference from a class to the value of one of its static fields. | |
| 5054 For references of this kind the <code>referrer_index</code> | |
| 5055 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 5056 jvmtiObjectReferenceCallback</internallink> is the index of the | |
| 5057 the static field. The index is based on the order of all the | |
| 5058 object's fields. This includes all fields of the directly declared | |
| 5059 static and instance fields in the class, and includes all fields (both | |
| 5060 public and private) fields declared in superclasses and superinterfaces. | |
| 5061 The index is thus calculated by summing the index of the field in the directly | |
| 5062 declared class (see <functionlink id="GetClassFields"/>), with the total | |
| 5063 number of fields (both public and private) declared in all superclasses | |
| 5064 and superinterfaces. The index starts at zero. | |
| 5065 Note: this definition differs from that in the <jvmti/> 1.0 Specification. | |
| 5066 <rationale>No known implementations used the 1.0 definition.</rationale> | |
| 5067 </constant> | |
| 5068 <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9"> | |
| 5069 Reference from a class to a resolved entry in the constant pool. | |
| 5070 For references of this kind the <code>referrer_index</code> | |
| 5071 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
| 5072 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
|
5073 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
|
5074 <vmspec chapter="4.4"/>. |
| 0 | 5075 </constant> |
| 5076 </constants> | |
| 5077 | |
| 5078 <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum"> | |
| 5079 <constant id="JVMTI_ITERATION_CONTINUE" num="1"> | |
| 5080 Continue the iteration. | |
| 5081 If this is a reference iteration, follow the references of this object. | |
| 5082 </constant> | |
| 5083 <constant id="JVMTI_ITERATION_IGNORE" num="2"> | |
| 5084 Continue the iteration. | |
| 5085 If this is a reference iteration, ignore the references of this object. | |
| 5086 </constant> | |
| 5087 <constant id="JVMTI_ITERATION_ABORT" num="0"> | |
| 5088 Abort the iteration. | |
| 5089 </constant> | |
| 5090 </constants> | |
| 5091 </intro> | |
| 5092 | |
| 5093 <callback id="jvmtiHeapObjectCallback"> | |
| 5094 <enum>jvmtiIterationControl</enum> | |
| 5095 <synopsis>Heap Object Callback</synopsis> | |
| 5096 <description> | |
| 5097 Agent supplied callback function. | |
| 5098 Describes (but does not pass in) an object in the heap. | |
| 5099 <p/> | |
| 5100 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5101 or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5102 <p/> | |
| 5103 See the <internallink id="heapCallbacks">heap callback | |
| 5104 function restrictions</internallink>. | |
| 5105 </description> | |
| 5106 <parameters> | |
| 5107 <param id="class_tag"> | |
| 5108 <jlong/> | |
| 5109 <description> | |
| 5110 The tag of the class of object (zero if the class is not tagged). | |
| 5111 If the object represents a runtime class, | |
| 5112 the <code>class_tag</code> is the tag | |
| 5113 associated with <code>java.lang.Class</code> | |
| 5114 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5115 </description> | |
| 5116 </param> | |
| 5117 <param id="size"> | |
| 5118 <jlong/> | |
| 5119 <description> | |
| 5120 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 5121 </description> | |
| 5122 </param> | |
| 5123 <param id="tag_ptr"> | |
| 5124 <outptr><jlong/></outptr> | |
| 5125 <description> | |
| 5126 The object tag value, or zero if the object is not tagged. | |
| 5127 To set the tag value to be associated with the object | |
| 5128 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5129 </description> | |
| 5130 </param> | |
| 5131 <param id="user_data"> | |
| 5132 <outptr><void/></outptr> | |
| 5133 <description> | |
| 5134 The user supplied data that was passed into the iteration function. | |
| 5135 </description> | |
| 5136 </param> | |
| 5137 </parameters> | |
| 5138 </callback> | |
| 5139 | |
| 5140 <callback id="jvmtiHeapRootCallback"> | |
| 5141 <enum>jvmtiIterationControl</enum> | |
| 5142 <synopsis>Heap Root Object Callback</synopsis> | |
| 5143 <description> | |
| 5144 Agent supplied callback function. | |
| 5145 Describes (but does not pass in) an object that is a root for the purposes | |
| 5146 of garbage collection. | |
| 5147 <p/> | |
| 5148 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5149 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
| 5150 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5151 <p/> | |
| 5152 See the <internallink id="heapCallbacks">heap callback | |
| 5153 function restrictions</internallink>. | |
| 5154 </description> | |
| 5155 <parameters> | |
| 5156 <param id="root_kind"> | |
| 5157 <enum>jvmtiHeapRootKind</enum> | |
| 5158 <description> | |
| 5159 The kind of heap root. | |
| 5160 </description> | |
| 5161 </param> | |
| 5162 <param id="class_tag"> | |
| 5163 <jlong/> | |
| 5164 <description> | |
| 5165 The tag of the class of object (zero if the class is not tagged). | |
| 5166 If the object represents a runtime class, the <code>class_tag</code> is the tag | |
| 5167 associated with <code>java.lang.Class</code> | |
| 5168 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5169 </description> | |
| 5170 </param> | |
| 5171 <param id="size"> | |
| 5172 <jlong/> | |
| 5173 <description> | |
| 5174 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 5175 </description> | |
| 5176 </param> | |
| 5177 <param id="tag_ptr"> | |
| 5178 <outptr><jlong/></outptr> | |
| 5179 <description> | |
| 5180 The object tag value, or zero if the object is not tagged. | |
| 5181 To set the tag value to be associated with the object | |
| 5182 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5183 </description> | |
| 5184 </param> | |
| 5185 <param id="user_data"> | |
| 5186 <outptr><void/></outptr> | |
| 5187 <description> | |
| 5188 The user supplied data that was passed into the iteration function. | |
| 5189 </description> | |
| 5190 </param> | |
| 5191 </parameters> | |
| 5192 </callback> | |
| 5193 | |
| 5194 <callback id="jvmtiStackReferenceCallback"> | |
| 5195 <enum>jvmtiIterationControl</enum> | |
| 5196 <synopsis>Stack Reference Object Callback</synopsis> | |
| 5197 <description> | |
| 5198 Agent supplied callback function. | |
| 5199 Describes (but does not pass in) an object on the stack that is a root for | |
| 5200 the purposes of garbage collection. | |
| 5201 <p/> | |
| 5202 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5203 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
| 5204 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5205 <p/> | |
| 5206 See the <internallink id="heapCallbacks">heap callback | |
| 5207 function restrictions</internallink>. | |
| 5208 </description> | |
| 5209 <parameters> | |
| 5210 <param id="root_kind"> | |
| 5211 <enum>jvmtiHeapRootKind</enum> | |
| 5212 <description> | |
| 5213 The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or | |
| 5214 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>). | |
| 5215 </description> | |
| 5216 </param> | |
| 5217 <param id="class_tag"> | |
| 5218 <jlong/> | |
| 5219 <description> | |
| 5220 The tag of the class of object (zero if the class is not tagged). | |
| 5221 If the object represents a runtime class, the <code>class_tag</code> is the tag | |
| 5222 associated with <code>java.lang.Class</code> | |
| 5223 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5224 </description> | |
| 5225 </param> | |
| 5226 <param id="size"> | |
| 5227 <jlong/> | |
| 5228 <description> | |
| 5229 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 5230 </description> | |
| 5231 </param> | |
| 5232 <param id="tag_ptr"> | |
| 5233 <outptr><jlong/></outptr> | |
| 5234 <description> | |
| 5235 The object tag value, or zero if the object is not tagged. | |
| 5236 To set the tag value to be associated with the object | |
| 5237 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5238 </description> | |
| 5239 </param> | |
| 5240 <param id="thread_tag"> | |
| 5241 <jlong/> | |
| 5242 <description> | |
| 5243 The tag of the thread corresponding to this stack, zero if not tagged. | |
| 5244 </description> | |
| 5245 </param> | |
| 5246 <param id="depth"> | |
| 5247 <jint/> | |
| 5248 <description> | |
| 5249 The depth of the frame. | |
| 5250 </description> | |
| 5251 </param> | |
| 5252 <param id="method"> | |
| 5253 <jmethodID/> | |
| 5254 <description> | |
| 5255 The method executing in this frame. | |
| 5256 </description> | |
| 5257 </param> | |
| 5258 <param id="slot"> | |
| 5259 <jint/> | |
| 5260 <description> | |
| 5261 The slot number. | |
| 5262 </description> | |
| 5263 </param> | |
| 5264 <param id="user_data"> | |
| 5265 <outptr><void/></outptr> | |
| 5266 <description> | |
| 5267 The user supplied data that was passed into the iteration function. | |
| 5268 </description> | |
| 5269 </param> | |
| 5270 </parameters> | |
| 5271 </callback> | |
| 5272 | |
| 5273 <callback id="jvmtiObjectReferenceCallback"> | |
| 5274 <enum>jvmtiIterationControl</enum> | |
| 5275 <synopsis>Object Reference Callback</synopsis> | |
| 5276 <description> | |
| 5277 Agent supplied callback function. | |
| 5278 Describes a reference from an object (the referrer) to another object | |
| 5279 (the referree). | |
| 5280 <p/> | |
| 5281 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
| 5282 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
| 5283 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
| 5284 <p/> | |
| 5285 See the <internallink id="heapCallbacks">heap callback | |
| 5286 function restrictions</internallink>. | |
| 5287 </description> | |
| 5288 <parameters> | |
| 5289 <param id="reference_kind"> | |
| 5290 <enum>jvmtiObjectReferenceKind</enum> | |
| 5291 <description> | |
| 5292 The type of reference. | |
| 5293 </description> | |
| 5294 </param> | |
| 5295 <param id="class_tag"> | |
| 5296 <jlong/> | |
| 5297 <description> | |
| 5298 The tag of the class of referree object (zero if the class is not tagged). | |
| 5299 If the referree object represents a runtime class, | |
| 5300 the <code>class_tag</code> is the tag | |
| 5301 associated with <code>java.lang.Class</code> | |
| 5302 (zero if <code>java.lang.Class</code> is not tagged). | |
| 5303 </description> | |
| 5304 </param> | |
| 5305 <param id="size"> | |
| 5306 <jlong/> | |
| 5307 <description> | |
| 5308 Size of the referree object (in bytes). | |
| 5309 See <functionlink id="GetObjectSize"/>. | |
| 5310 </description> | |
| 5311 </param> | |
| 5312 <param id="tag_ptr"> | |
| 5313 <outptr><jlong/></outptr> | |
| 5314 <description> | |
| 5315 The referree object tag value, or zero if the object is not | |
| 5316 tagged. | |
| 5317 To set the tag value to be associated with the object | |
| 5318 the agent sets the <code>jlong</code> pointed to by the parameter. | |
| 5319 </description> | |
| 5320 </param> | |
| 5321 <param id="referrer_tag"> | |
| 5322 <jlong/> | |
| 5323 <description> | |
| 5324 The tag of the referrer object, or zero if the referrer | |
| 5325 object is not tagged. | |
| 5326 </description> | |
| 5327 </param> | |
| 5328 <param id="referrer_index"> | |
| 5329 <jint/> | |
| 5330 <description> | |
| 5331 For references of type <code>JVMTI_REFERENCE_FIELD</code> or | |
| 5332 <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index | |
| 5333 of the field in the referrer object. The index is based on the | |
| 5334 order of all the object's fields - see <internallink | |
| 5335 id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink> | |
| 5336 or <internallink | |
| 5337 id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD | |
| 5338 </internallink> for further description. | |
| 5339 <p/> | |
| 5340 For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code> | |
| 5341 the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT"> | |
| 5342 JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description. | |
| 5343 <p/> | |
| 5344 For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code> | |
| 5345 the index into the constant pool of the class - see | |
| 5346 <internallink id="JVMTI_REFERENCE_CONSTANT_POOL"> | |
| 5347 JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further | |
| 5348 description. | |
| 5349 <p/> | |
| 5350 For references of other kinds the <code>referrer_index</code> is | |
| 5351 <code>-1</code>. | |
| 5352 </description> | |
| 5353 </param> | |
| 5354 <param id="user_data"> | |
| 5355 <outptr><void/></outptr> | |
| 5356 <description> | |
| 5357 The user supplied data that was passed into the iteration function. | |
| 5358 </description> | |
| 5359 </param> | |
| 5360 </parameters> | |
| 5361 </callback> | |
| 5362 | |
| 5363 <function id="IterateOverObjectsReachableFromObject" num="109"> | |
| 5364 <synopsis>Iterate Over Objects Reachable From Object</synopsis> | |
| 5365 <description> | |
| 5366 This function iterates over all objects that are directly | |
| 5367 and indirectly reachable from the specified object. | |
| 5368 For each object <i>A</i> (known | |
| 5369 as the referrer) with a reference to object <i>B</i> the specified | |
| 5370 callback function is called to describe the object reference. | |
| 5371 The callback is called exactly once for each reference from a referrer; | |
| 5372 this is true even if there are reference cycles or multiple paths to | |
| 5373 the referrer. | |
| 5374 There may be more than one reference between a referrer and a referree, | |
| 5375 These may be distinguished by the | |
| 5376 <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and | |
| 5377 <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>. | |
| 5378 The callback for an object will always occur after the callback for | |
| 5379 its referrer. | |
| 5380 <p/> | |
| 5381 See <functionlink id="FollowReferences"/> for the object | |
| 5382 references which are reported. | |
| 5383 <p/> | |
| 5384 During the execution of this function the state of the heap | |
| 5385 does not change: no objects are allocated, no objects are | |
| 5386 garbage collected, and the state of objects (including | |
| 5387 held values) does not change. | |
| 5388 As a result, threads executing Java | |
| 5389 programming language code, threads attempting to resume the | |
| 5390 execution of Java programming language code, and threads | |
| 5391 attempting to execute JNI functions are typically stalled. | |
| 5392 </description> | |
| 5393 <origin>new</origin> | |
| 5394 <capabilities> | |
| 5395 <required id="can_tag_objects"></required> | |
| 5396 </capabilities> | |
| 5397 <parameters> | |
| 5398 <param id="object"> | |
| 5399 <jobject/> | |
| 5400 <description> | |
| 5401 The object | |
| 5402 </description> | |
| 5403 </param> | |
| 5404 <param id="object_reference_callback"> | |
| 5405 <ptrtype> | |
| 5406 <struct>jvmtiObjectReferenceCallback</struct> | |
| 5407 </ptrtype> | |
| 5408 <description> | |
| 5409 The callback to be called to describe each | |
| 5410 object reference. | |
| 5411 </description> | |
| 5412 </param> | |
| 5413 <param id="user_data"> | |
| 5414 <inbuf> | |
| 5415 <void/> | |
| 5416 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5417 </inbuf> | |
| 5418 <description> | |
| 5419 User supplied data to be passed to the callback. | |
| 5420 </description> | |
| 5421 </param> | |
| 5422 </parameters> | |
| 5423 <errors> | |
| 5424 </errors> | |
| 5425 </function> | |
| 5426 | |
| 5427 <function id="IterateOverReachableObjects" num="110"> | |
| 5428 <synopsis>Iterate Over Reachable Objects</synopsis> | |
| 5429 <description> | |
| 5430 This function iterates over the root objects and all objects that | |
| 5431 are directly and indirectly reachable from the root objects. | |
| 5432 The root objects comprise the set of system classes, | |
| 5433 JNI globals, references from thread stacks, and other objects used as roots | |
| 5434 for the purposes of garbage collection. | |
| 5435 <p/> | |
| 5436 For each root the <paramlink id="heap_root_callback"></paramlink> | |
| 5437 or <paramlink id="stack_ref_callback"></paramlink> callback is called. | |
| 5438 An object can be a root object for more than one reason and in that case | |
| 5439 the appropriate callback is called for each reason. | |
| 5440 <p/> | |
| 5441 For each object reference the <paramlink id="object_ref_callback"></paramlink> | |
| 5442 callback function is called to describe the object reference. | |
| 5443 The callback is called exactly once for each reference from a referrer; | |
| 5444 this is true even if there are reference cycles or multiple paths to | |
| 5445 the referrer. | |
| 5446 There may be more than one reference between a referrer and a referree, | |
| 5447 These may be distinguished by the | |
| 5448 <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and | |
| 5449 <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>. | |
| 5450 The callback for an object will always occur after the callback for | |
| 5451 its referrer. | |
| 5452 <p/> | |
| 5453 See <functionlink id="FollowReferences"/> for the object | |
| 5454 references which are reported. | |
| 5455 <p/> | |
| 5456 Roots are always reported to the profiler before any object references | |
| 5457 are reported. In other words, the <paramlink id="object_ref_callback"></paramlink> | |
| 5458 callback will not be called until the appropriate callback has been called | |
| 5459 for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is | |
| 5460 specified as <code>NULL</code> then this function returns after | |
| 5461 reporting the root objects to the profiler. | |
| 5462 <p/> | |
| 5463 During the execution of this function the state of the heap | |
| 5464 does not change: no objects are allocated, no objects are | |
| 5465 garbage collected, and the state of objects (including | |
| 5466 held values) does not change. | |
| 5467 As a result, threads executing Java | |
| 5468 programming language code, threads attempting to resume the | |
| 5469 execution of Java programming language code, and threads | |
| 5470 attempting to execute JNI functions are typically stalled. | |
| 5471 </description> | |
| 5472 <origin>new</origin> | |
| 5473 <capabilities> | |
| 5474 <required id="can_tag_objects"></required> | |
| 5475 </capabilities> | |
| 5476 <parameters> | |
| 5477 <param id="heap_root_callback"> | |
| 5478 <ptrtype> | |
| 5479 <struct>jvmtiHeapRootCallback</struct> | |
| 5480 <nullok>do not report heap roots</nullok> | |
| 5481 </ptrtype> | |
| 5482 <description> | |
| 5483 The callback function to be called for each heap root of type | |
| 5484 <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>, | |
| 5485 <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>, | |
| 5486 <code>JVMTI_HEAP_ROOT_MONITOR</code>, | |
| 5487 <code>JVMTI_HEAP_ROOT_THREAD</code>, or | |
| 5488 <code>JVMTI_HEAP_ROOT_OTHER</code>. | |
| 5489 </description> | |
| 5490 </param> | |
| 5491 <param id="stack_ref_callback"> | |
| 5492 <ptrtype> | |
| 5493 <struct>jvmtiStackReferenceCallback</struct> | |
| 5494 <nullok>do not report stack references</nullok> | |
| 5495 </ptrtype> | |
| 5496 <description> | |
| 5497 The callback function to be called for each heap root of | |
| 5498 <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or | |
| 5499 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>. | |
| 5500 </description> | |
| 5501 </param> | |
| 5502 <param id="object_ref_callback"> | |
| 5503 <ptrtype> | |
| 5504 <struct>jvmtiObjectReferenceCallback</struct> | |
| 5505 <nullok>do not follow references from the root objects</nullok> | |
| 5506 </ptrtype> | |
| 5507 <description> | |
| 5508 The callback function to be called for each object reference. | |
| 5509 </description> | |
| 5510 </param> | |
| 5511 <param id="user_data"> | |
| 5512 <inbuf> | |
| 5513 <void/> | |
| 5514 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5515 </inbuf> | |
| 5516 <description> | |
| 5517 User supplied data to be passed to the callback. | |
| 5518 </description> | |
| 5519 </param> | |
| 5520 </parameters> | |
| 5521 <errors> | |
| 5522 </errors> | |
| 5523 </function> | |
| 5524 | |
| 5525 <function id="IterateOverHeap" num="111"> | |
| 5526 <synopsis>Iterate Over Heap</synopsis> | |
| 5527 <description> | |
| 5528 Iterate over all objects in the heap. This includes both reachable and | |
| 5529 unreachable objects. | |
| 5530 <p/> | |
| 5531 The <paramlink id="object_filter"></paramlink> parameter indicates the | |
| 5532 objects for which the callback function is called. If this parameter | |
| 5533 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be | |
| 5534 called for every object that is tagged. If the parameter is | |
| 5535 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be | |
| 5536 for objects that are not tagged. If the parameter | |
| 5537 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be | |
| 5538 called for every object in the heap, irrespective of whether it is | |
| 5539 tagged or not. | |
| 5540 <p/> | |
| 5541 During the execution of this function the state of the heap | |
| 5542 does not change: no objects are allocated, no objects are | |
| 5543 garbage collected, and the state of objects (including | |
| 5544 held values) does not change. | |
| 5545 As a result, threads executing Java | |
| 5546 programming language code, threads attempting to resume the | |
| 5547 execution of Java programming language code, and threads | |
| 5548 attempting to execute JNI functions are typically stalled. | |
| 5549 </description> | |
| 5550 <origin>new</origin> | |
| 5551 <capabilities> | |
| 5552 <required id="can_tag_objects"></required> | |
| 5553 </capabilities> | |
| 5554 <parameters> | |
| 5555 <param id="object_filter"> | |
| 5556 <enum>jvmtiHeapObjectFilter</enum> | |
| 5557 <description> | |
| 5558 Indicates the objects for which the callback function is called. | |
| 5559 </description> | |
| 5560 </param> | |
| 5561 <param id="heap_object_callback"> | |
| 5562 <ptrtype> | |
| 5563 <struct>jvmtiHeapObjectCallback</struct> | |
| 5564 </ptrtype> | |
| 5565 <description> | |
| 5566 The iterator function to be called for each | |
| 5567 object matching the <paramlink id="object_filter"/>. | |
| 5568 </description> | |
| 5569 </param> | |
| 5570 <param id="user_data"> | |
| 5571 <inbuf> | |
| 5572 <void/> | |
| 5573 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5574 </inbuf> | |
| 5575 <description> | |
| 5576 User supplied data to be passed to the callback. | |
| 5577 </description> | |
| 5578 </param> | |
| 5579 </parameters> | |
| 5580 <errors> | |
| 5581 </errors> | |
| 5582 </function> | |
| 5583 | |
| 5584 <function id="IterateOverInstancesOfClass" num="112"> | |
| 5585 <synopsis>Iterate Over Instances Of Class</synopsis> | |
| 5586 <description> | |
| 5587 Iterate over all objects in the heap that are instances of the specified class. | |
| 5588 This includes direct instances of the specified class and | |
| 5589 instances of all subclasses of the specified class. | |
| 5590 This includes both reachable and unreachable objects. | |
| 5591 <p/> | |
| 5592 The <paramlink id="object_filter"></paramlink> parameter indicates the | |
| 5593 objects for which the callback function is called. If this parameter | |
| 5594 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be | |
| 5595 called for every object that is tagged. If the parameter is | |
| 5596 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be | |
| 5597 called for objects that are not tagged. If the parameter | |
| 5598 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be | |
| 5599 called for every object in the heap, irrespective of whether it is | |
| 5600 tagged or not. | |
| 5601 <p/> | |
| 5602 During the execution of this function the state of the heap | |
| 5603 does not change: no objects are allocated, no objects are | |
| 5604 garbage collected, and the state of objects (including | |
| 5605 held values) does not change. | |
| 5606 As a result, threads executing Java | |
| 5607 programming language code, threads attempting to resume the | |
| 5608 execution of Java programming language code, and threads | |
| 5609 attempting to execute JNI functions are typically stalled. | |
| 5610 </description> | |
| 5611 <origin>new</origin> | |
| 5612 <capabilities> | |
| 5613 <required id="can_tag_objects"></required> | |
| 5614 </capabilities> | |
| 5615 <parameters> | |
| 5616 <param id="klass"> | |
| 5617 <jclass/> | |
| 5618 <description> | |
| 5619 Iterate over objects of this class only. | |
| 5620 </description> | |
| 5621 </param> | |
| 5622 <param id="object_filter"> | |
| 5623 <enum>jvmtiHeapObjectFilter</enum> | |
| 5624 <description> | |
| 5625 Indicates the objects for which the callback function is called. | |
| 5626 </description> | |
| 5627 </param> | |
| 5628 <param id="heap_object_callback"> | |
| 5629 <ptrtype> | |
| 5630 <struct>jvmtiHeapObjectCallback</struct> | |
| 5631 </ptrtype> | |
| 5632 <description> | |
| 5633 The iterator function to be called for each | |
| 5634 <paramlink id="klass"/> instance matching | |
| 5635 the <paramlink id="object_filter"/>. | |
| 5636 </description> | |
| 5637 </param> | |
| 5638 <param id="user_data"> | |
| 5639 <inbuf> | |
| 5640 <void/> | |
| 5641 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
| 5642 </inbuf> | |
| 5643 <description> | |
| 5644 User supplied data to be passed to the callback. | |
| 5645 </description> | |
| 5646 </param> | |
| 5647 </parameters> | |
| 5648 <errors> | |
| 5649 </errors> | |
| 5650 </function> | |
| 5651 | |
| 5652 </category> | |
| 5653 | |
| 5654 <category id="local" label="Local Variable"> | |
| 5655 | |
| 5656 <intro> | |
| 5657 These functions are used to retrieve or set the value of a local variable. | |
| 5658 The variable is identified by the depth of the frame containing its | |
| 5659 value and the variable's slot number within that frame. | |
| 5660 The mapping of variables to | |
| 5661 slot numbers can be obtained with the function | |
| 5662 <functionlink id="GetLocalVariableTable"></functionlink>. | |
| 5663 </intro> | |
| 5664 | |
| 5665 <function id="GetLocalObject" num="21"> | |
| 5666 <synopsis>Get Local Variable - Object</synopsis> | |
| 5667 <description> | |
| 5668 This function can be used to retrieve the value of a local | |
| 5669 variable whose type is <code>Object</code> or a subclass of <code>Object</code>. | |
| 5670 </description> | |
| 5671 <origin>jvmdi</origin> | |
| 5672 <capabilities> | |
| 5673 <required id="can_access_local_variables"></required> | |
| 5674 </capabilities> | |
| 5675 <parameters> | |
| 5676 <param id="thread"> | |
| 5677 <jthread null="current" frame="frame"/> | |
| 5678 <description> | |
| 5679 The thread of the frame containing the variable's value. | |
| 5680 </description> | |
| 5681 </param> | |
| 5682 <param id="depth"> | |
| 5683 <jframeID thread="thread"/> | |
| 5684 <description> | |
| 5685 The depth of the frame containing the variable's value. | |
| 5686 </description> | |
| 5687 </param> | |
| 5688 <param id="slot"> | |
| 5689 <jint/> | |
| 5690 <description> | |
| 5691 The variable's slot number. | |
| 5692 </description> | |
| 5693 </param> | |
| 5694 <param id="value_ptr"> | |
| 5695 <outptr><jobject/></outptr> | |
| 5696 <description> | |
| 5697 On return, points to the variable's value. | |
| 5698 </description> | |
| 5699 </param> | |
| 5700 </parameters> | |
| 5701 <errors> | |
| 5702 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5703 Invalid <code>slot</code>. | |
| 5704 </error> | |
| 5705 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5706 The variable type is not | |
| 5707 <code>Object</code> or a subclass of <code>Object</code>. | |
| 5708 </error> | |
| 5709 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5710 Not a visible frame | |
| 5711 </error> | |
| 5712 </errors> | |
| 5713 </function> | |
| 5714 | |
| 2019 | 5715 <function id="GetLocalInstance" num="155" since="1.2"> |
| 5716 <synopsis>Get Local Instance</synopsis> | |
| 5717 <description> | |
| 5718 This function can be used to retrieve the value of the local object | |
| 5719 variable at slot 0 (the "<code>this</code>" object) from non-static | |
| 5720 frames. This function can retrieve the "<code>this</code>" object from | |
| 5721 native method frames, whereas <code>GetLocalObject()</code> would | |
| 5722 return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases. | |
| 5723 </description> | |
| 5724 <origin>new</origin> | |
| 5725 <capabilities> | |
| 5726 <required id="can_access_local_variables"></required> | |
| 5727 </capabilities> | |
| 5728 <parameters> | |
| 5729 <param id="thread"> | |
| 5730 <jthread null="current" frame="frame"/> | |
| 5731 <description> | |
| 5732 The thread of the frame containing the variable's value. | |
| 5733 </description> | |
| 5734 </param> | |
| 5735 <param id="depth"> | |
| 5736 <jframeID thread="thread"/> | |
| 5737 <description> | |
| 5738 The depth of the frame containing the variable's value. | |
| 5739 </description> | |
| 5740 </param> | |
| 5741 <param id="value_ptr"> | |
| 5742 <outptr><jobject/></outptr> | |
| 5743 <description> | |
| 5744 On return, points to the variable's value. | |
| 5745 </description> | |
| 5746 </param> | |
| 5747 </parameters> | |
| 5748 <errors> | |
| 5749 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5750 If the specified frame is a static method frame. | |
| 5751 </error> | |
| 5752 </errors> | |
| 5753 </function> | |
| 0 | 5754 <function id="GetLocalInt" num="22"> |
| 5755 <synopsis>Get Local Variable - Int</synopsis> | |
| 5756 <description> | |
| 5757 This function can be used to retrieve the value of a local | |
| 5758 variable whose type is <code>int</code>, | |
| 5759 <code>short</code>, <code>char</code>, <code>byte</code>, or | |
| 5760 <code>boolean</code>. | |
| 5761 </description> | |
| 5762 <origin>jvmdi</origin> | |
| 5763 <capabilities> | |
| 5764 <required id="can_access_local_variables"></required> | |
| 5765 </capabilities> | |
| 5766 <parameters> | |
| 5767 <param id="thread"> | |
| 5768 <jthread null="current" frame="frame"/> | |
| 5769 <description> | |
| 5770 The thread of the frame containing the variable's value. | |
| 5771 </description> | |
| 5772 </param> | |
| 5773 <param id="depth"> | |
| 5774 <jframeID thread="thread"/> | |
| 5775 <description> | |
| 5776 The depth of the frame containing the variable's value. | |
| 5777 </description> | |
| 5778 </param> | |
| 5779 <param id="slot"> | |
| 5780 <jint/> | |
| 5781 <description> | |
| 5782 The variable's slot number. | |
| 5783 </description> | |
| 5784 </param> | |
| 5785 <param id="value_ptr"> | |
| 5786 <outptr><jint/></outptr> | |
| 5787 <description> | |
| 5788 On return, points to the variable's value. | |
| 5789 </description> | |
| 5790 </param> | |
| 5791 </parameters> | |
| 5792 <errors> | |
| 5793 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5794 Invalid <code>slot</code>. | |
| 5795 </error> | |
| 5796 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5797 The variable type is not | |
| 5798 <code>int</code>, <code>short</code>, | |
| 5799 <code>char</code>, <code>byte</code>, or | |
| 5800 <code>boolean</code>. | |
| 5801 </error> | |
| 5802 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5803 Not a visible frame | |
| 5804 </error> | |
| 5805 </errors> | |
| 5806 </function> | |
| 5807 | |
| 5808 <function id="GetLocalLong" num="23"> | |
| 5809 <synopsis>Get Local Variable - Long</synopsis> | |
| 5810 <description> | |
| 5811 This function can be used to retrieve the value of a local | |
| 5812 variable whose type is <code>long</code>. | |
| 5813 </description> | |
| 5814 <origin>jvmdi</origin> | |
| 5815 <capabilities> | |
| 5816 <required id="can_access_local_variables"></required> | |
| 5817 </capabilities> | |
| 5818 <parameters> | |
| 5819 <param id="thread"> | |
| 5820 <jthread null="current" frame="frame"/> | |
| 5821 <description> | |
| 5822 The thread of the frame containing the variable's value. | |
| 5823 </description> | |
| 5824 </param> | |
| 5825 <param id="depth"> | |
| 5826 <jframeID thread="thread"/> | |
| 5827 <description> | |
| 5828 The depth of the frame containing the variable's value. | |
| 5829 </description> | |
| 5830 </param> | |
| 5831 <param id="slot"> | |
| 5832 <jint/> | |
| 5833 <description> | |
| 5834 The variable's slot number. | |
| 5835 </description> | |
| 5836 </param> | |
| 5837 <param id="value_ptr"> | |
| 5838 <outptr><jlong/></outptr> | |
| 5839 <description> | |
| 5840 On return, points to the variable's value. | |
| 5841 </description> | |
| 5842 </param> | |
| 5843 </parameters> | |
| 5844 <errors> | |
| 5845 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5846 Invalid <code>slot</code>. | |
| 5847 </error> | |
| 5848 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5849 The variable type is not <code>long</code>. | |
| 5850 </error> | |
| 5851 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5852 Not a visible frame | |
| 5853 </error> | |
| 5854 </errors> | |
| 5855 </function> | |
| 5856 | |
| 5857 <function id="GetLocalFloat" num="24"> | |
| 5858 <synopsis>Get Local Variable - Float</synopsis> | |
| 5859 <description> | |
| 5860 This function can be used to retrieve the value of a local | |
| 5861 variable whose type is <code>float</code>. | |
| 5862 </description> | |
| 5863 <origin>jvmdi</origin> | |
| 5864 <capabilities> | |
| 5865 <required id="can_access_local_variables"></required> | |
| 5866 </capabilities> | |
| 5867 <parameters> | |
| 5868 <param id="thread"> | |
| 5869 <jthread null="current" frame="frame"/> | |
| 5870 <description> | |
| 5871 The thread of the frame containing the variable's value. | |
| 5872 </description> | |
| 5873 </param> | |
| 5874 <param id="depth"> | |
| 5875 <jframeID thread="thread"/> | |
| 5876 <description> | |
| 5877 The depth of the frame containing the variable's value. | |
| 5878 </description> | |
| 5879 </param> | |
| 5880 <param id="slot"> | |
| 5881 <jint/> | |
| 5882 <description> | |
| 5883 The variable's slot number. | |
| 5884 </description> | |
| 5885 </param> | |
| 5886 <param id="value_ptr"> | |
| 5887 <outptr><jfloat/></outptr> | |
| 5888 <description> | |
| 5889 On return, points to the variable's value. | |
| 5890 </description> | |
| 5891 </param> | |
| 5892 </parameters> | |
| 5893 <errors> | |
| 5894 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5895 Invalid <code>slot</code>. | |
| 5896 </error> | |
| 5897 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5898 The variable type is not <code>float</code>. | |
| 5899 </error> | |
| 5900 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5901 Not a visible frame | |
| 5902 </error> | |
| 5903 </errors> | |
| 5904 </function> | |
| 5905 | |
| 5906 <function id="GetLocalDouble" num="25"> | |
| 5907 <synopsis>Get Local Variable - Double</synopsis> | |
| 5908 <description> | |
| 5909 This function can be used to retrieve the value of a local | |
| 5910 variable whose type is <code>long</code>. | |
| 5911 </description> | |
| 5912 <origin>jvmdi</origin> | |
| 5913 <capabilities> | |
| 5914 <required id="can_access_local_variables"></required> | |
| 5915 </capabilities> | |
| 5916 <parameters> | |
| 5917 <param id="thread"> | |
| 5918 <jthread null="current" frame="frame"/> | |
| 5919 <description> | |
| 5920 The thread of the frame containing the variable's value. | |
| 5921 </description> | |
| 5922 </param> | |
| 5923 <param id="depth"> | |
| 5924 <jframeID thread="thread"/> | |
| 5925 <description> | |
| 5926 The depth of the frame containing the variable's value. | |
| 5927 </description> | |
| 5928 </param> | |
| 5929 <param id="slot"> | |
| 5930 <jint/> | |
| 5931 <description> | |
| 5932 The variable's slot number. | |
| 5933 </description> | |
| 5934 </param> | |
| 5935 <param id="value_ptr"> | |
| 5936 <outptr><jdouble/></outptr> | |
| 5937 <description> | |
| 5938 On return, points to the variable's value. | |
| 5939 </description> | |
| 5940 </param> | |
| 5941 </parameters> | |
| 5942 <errors> | |
| 5943 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5944 Invalid <code>slot</code>. | |
| 5945 </error> | |
| 5946 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5947 The variable type is not <code>double</code>. | |
| 5948 </error> | |
| 5949 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 5950 Not a visible frame | |
| 5951 </error> | |
| 5952 </errors> | |
| 5953 </function> | |
| 5954 | |
| 5955 <function id="SetLocalObject" num="26"> | |
| 5956 <synopsis>Set Local Variable - Object</synopsis> | |
| 5957 <description> | |
| 5958 This function can be used to set the value of a local | |
| 5959 variable whose type is <code>Object</code> or a subclass of <code>Object</code>. | |
| 5960 </description> | |
| 5961 <origin>jvmdi</origin> | |
| 5962 <capabilities> | |
| 5963 <required id="can_access_local_variables"></required> | |
| 5964 </capabilities> | |
| 5965 <parameters> | |
| 5966 <param id="thread"> | |
| 5967 <jthread null="current" frame="frame"/> | |
| 5968 <description> | |
| 5969 The thread of the frame containing the variable's value. | |
| 5970 </description> | |
| 5971 </param> | |
| 5972 <param id="depth"> | |
| 5973 <jframeID thread="thread"/> | |
| 5974 <description> | |
| 5975 The depth of the frame containing the variable's value. | |
| 5976 </description> | |
| 5977 </param> | |
| 5978 <param id="slot"> | |
| 5979 <jint/> | |
| 5980 <description> | |
| 5981 The variable's slot number. | |
| 5982 </description> | |
| 5983 </param> | |
| 5984 <param id="value"> | |
| 5985 <jobject/> | |
| 5986 <description> | |
| 5987 The new value for the variable. | |
| 5988 </description> | |
| 5989 </param> | |
| 5990 </parameters> | |
| 5991 <errors> | |
| 5992 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 5993 Invalid <code>slot</code>. | |
| 5994 </error> | |
| 5995 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 5996 The variable type is not | |
| 5997 <code>Object</code> or a subclass of <code>Object</code>. | |
| 5998 </error> | |
| 5999 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6000 The supplied <paramlink id="value"/> is not compatible | |
| 6001 with the variable type. | |
| 6002 </error> | |
| 6003 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6004 Not a visible frame | |
| 6005 </error> | |
| 6006 </errors> | |
| 6007 </function> | |
| 6008 | |
| 6009 <function id="SetLocalInt" num="27"> | |
| 6010 <synopsis>Set Local Variable - Int</synopsis> | |
| 6011 <description> | |
| 6012 This function can be used to set the value of a local | |
| 6013 variable whose type is <code>int</code>, | |
| 6014 <code>short</code>, <code>char</code>, <code>byte</code>, or | |
| 6015 <code>boolean</code>. | |
| 6016 </description> | |
| 6017 <origin>jvmdi</origin> | |
| 6018 <capabilities> | |
| 6019 <required id="can_access_local_variables"></required> | |
| 6020 </capabilities> | |
| 6021 <parameters> | |
| 6022 <param id="thread"> | |
| 6023 <jthread null="current" frame="frame"/> | |
| 6024 <description> | |
| 6025 The thread of the frame containing the variable's value. | |
| 6026 </description> | |
| 6027 </param> | |
| 6028 <param id="depth"> | |
| 6029 <jframeID thread="thread"/> | |
| 6030 <description> | |
| 6031 The depth of the frame containing the variable's value. | |
| 6032 </description> | |
| 6033 </param> | |
| 6034 <param id="slot"> | |
| 6035 <jint/> | |
| 6036 <description> | |
| 6037 The variable's slot number. | |
| 6038 </description> | |
| 6039 </param> | |
| 6040 <param id="value"> | |
| 6041 <jint/> | |
| 6042 <description> | |
| 6043 The new value for the variable. | |
| 6044 </description> | |
| 6045 </param> | |
| 6046 </parameters> | |
| 6047 <errors> | |
| 6048 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6049 Invalid <code>slot</code>. | |
| 6050 </error> | |
| 6051 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6052 The variable type is not | |
| 6053 <code>int</code>, <code>short</code>, | |
| 6054 <code>char</code>, <code>byte</code>, or | |
| 6055 <code>boolean</code>. | |
| 6056 </error> | |
| 6057 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6058 Not a visible frame | |
| 6059 </error> | |
| 6060 </errors> | |
| 6061 </function> | |
| 6062 | |
| 6063 <function id="SetLocalLong" num="28"> | |
| 6064 <synopsis>Set Local Variable - Long</synopsis> | |
| 6065 <description> | |
| 6066 This function can be used to set the value of a local | |
| 6067 variable whose type is <code>long</code>. | |
| 6068 </description> | |
| 6069 <origin>jvmdi</origin> | |
| 6070 <capabilities> | |
| 6071 <required id="can_access_local_variables"></required> | |
| 6072 </capabilities> | |
| 6073 <parameters> | |
| 6074 <param id="thread"> | |
| 6075 <jthread null="current" frame="frame"/> | |
| 6076 <description> | |
| 6077 The thread of the frame containing the variable's value. | |
| 6078 </description> | |
| 6079 </param> | |
| 6080 <param id="depth"> | |
| 6081 <jframeID thread="thread"/> | |
| 6082 <description> | |
| 6083 The depth of the frame containing the variable's value. | |
| 6084 </description> | |
| 6085 </param> | |
| 6086 <param id="slot"> | |
| 6087 <jint/> | |
| 6088 <description> | |
| 6089 The variable's slot number. | |
| 6090 </description> | |
| 6091 </param> | |
| 6092 <param id="value"> | |
| 6093 <jlong/> | |
| 6094 <description> | |
| 6095 The new value for the variable. | |
| 6096 </description> | |
| 6097 </param> | |
| 6098 </parameters> | |
| 6099 <errors> | |
| 6100 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6101 Invalid <code>slot</code>. | |
| 6102 </error> | |
| 6103 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6104 The variable type is not <code>long</code>. | |
| 6105 </error> | |
| 6106 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6107 Not a visible frame | |
| 6108 </error> | |
| 6109 </errors> | |
| 6110 </function> | |
| 6111 | |
| 6112 <function id="SetLocalFloat" num="29"> | |
| 6113 <synopsis>Set Local Variable - Float</synopsis> | |
| 6114 <description> | |
| 6115 This function can be used to set the value of a local | |
| 6116 variable whose type is <code>float</code>. | |
| 6117 </description> | |
| 6118 <origin>jvmdi</origin> | |
| 6119 <capabilities> | |
| 6120 <required id="can_access_local_variables"></required> | |
| 6121 </capabilities> | |
| 6122 <parameters> | |
| 6123 <param id="thread"> | |
| 6124 <jthread null="current" frame="frame"/> | |
| 6125 <description> | |
| 6126 The thread of the frame containing the variable's value. | |
| 6127 </description> | |
| 6128 </param> | |
| 6129 <param id="depth"> | |
| 6130 <jframeID thread="thread"/> | |
| 6131 <description> | |
| 6132 The depth of the frame containing the variable's value. | |
| 6133 </description> | |
| 6134 </param> | |
| 6135 <param id="slot"> | |
| 6136 <jint/> | |
| 6137 <description> | |
| 6138 The variable's slot number. | |
| 6139 </description> | |
| 6140 </param> | |
| 6141 <param id="value"> | |
| 6142 <jfloat/> | |
| 6143 <description> | |
| 6144 The new value for the variable. | |
| 6145 </description> | |
| 6146 </param> | |
| 6147 </parameters> | |
| 6148 <errors> | |
| 6149 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6150 Invalid <code>slot</code>. | |
| 6151 </error> | |
| 6152 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6153 The variable type is not <code>float</code>. | |
| 6154 </error> | |
| 6155 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6156 Not a visible frame | |
| 6157 </error> | |
| 6158 </errors> | |
| 6159 </function> | |
| 6160 | |
| 6161 <function id="SetLocalDouble" num="30"> | |
| 6162 <synopsis>Set Local Variable - Double</synopsis> | |
| 6163 <description> | |
| 6164 This function can be used to set the value of a local | |
| 6165 variable whose type is <code>double</code>. | |
| 6166 </description> | |
| 6167 <origin>jvmdi</origin> | |
| 6168 <capabilities> | |
| 6169 <required id="can_access_local_variables"></required> | |
| 6170 </capabilities> | |
| 6171 <parameters> | |
| 6172 <param id="thread"> | |
| 6173 <jthread null="current" frame="frame"/> | |
| 6174 <description> | |
| 6175 The thread of the frame containing the variable's value. | |
| 6176 </description> | |
| 6177 </param> | |
| 6178 <param id="depth"> | |
| 6179 <jframeID thread="thread"/> | |
| 6180 <description> | |
| 6181 The depth of the frame containing the variable's value. | |
| 6182 </description> | |
| 6183 </param> | |
| 6184 <param id="slot"> | |
| 6185 <jint/> | |
| 6186 <description> | |
| 6187 The variable's slot number. | |
| 6188 </description> | |
| 6189 </param> | |
| 6190 <param id="value"> | |
| 6191 <jdouble/> | |
| 6192 <description> | |
| 6193 The new value for the variable. | |
| 6194 </description> | |
| 6195 </param> | |
| 6196 </parameters> | |
| 6197 <errors> | |
| 6198 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
| 6199 Invalid <code>slot</code>. | |
| 6200 </error> | |
| 6201 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
| 6202 The variable type is not <code>double</code>. | |
| 6203 </error> | |
| 6204 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
| 6205 Not a visible frame | |
| 6206 </error> | |
| 6207 </errors> | |
| 6208 </function> | |
| 6209 </category> | |
| 6210 | |
| 6211 <category id="breakpointCategory" label="Breakpoint"> | |
| 6212 | |
| 6213 <intro> | |
| 6214 </intro> | |
| 6215 | |
| 6216 <function id="SetBreakpoint" num="38"> | |
| 6217 <synopsis>Set Breakpoint</synopsis> | |
| 6218 <description> | |
| 6219 Set a breakpoint at the instruction indicated by | |
| 6220 <code>method</code> and <code>location</code>. | |
| 6221 An instruction can only have one breakpoint. | |
| 6222 <p/> | |
| 6223 Whenever the designated instruction is about to be executed, a | |
| 6224 <eventlink id="Breakpoint"></eventlink> event is generated. | |
| 6225 </description> | |
| 6226 <origin>jvmdi</origin> | |
| 6227 <capabilities> | |
| 6228 <required id="can_generate_breakpoint_events"></required> | |
| 6229 </capabilities> | |
| 6230 <parameters> | |
| 6231 <param id="klass"> | |
| 6232 <jclass method="method"/> | |
| 6233 <description> | |
| 6234 The class in which to set the breakpoint | |
| 6235 </description> | |
| 6236 </param> | |
| 6237 <param id="method"> | |
| 6238 <jmethodID class="klass"/> | |
| 6239 <description> | |
| 6240 The method in which to set the breakpoint | |
| 6241 </description> | |
| 6242 </param> | |
| 6243 <param id="location"> | |
| 6244 <jlocation/> | |
| 6245 <description> | |
| 6246 the index of the instruction at which to set the breakpoint | |
| 6247 | |
| 6248 </description> | |
| 6249 </param> | |
| 6250 </parameters> | |
| 6251 <errors> | |
| 6252 <error id="JVMTI_ERROR_DUPLICATE"> | |
| 6253 The designated bytecode already has a breakpoint. | |
| 6254 </error> | |
| 6255 </errors> | |
| 6256 </function> | |
| 6257 | |
| 6258 <function id="ClearBreakpoint" num="39"> | |
| 6259 <synopsis>Clear Breakpoint</synopsis> | |
| 6260 <description> | |
| 6261 Clear the breakpoint at the bytecode indicated by | |
| 6262 <code>method</code> and <code>location</code>. | |
| 6263 </description> | |
| 6264 <origin>jvmdi</origin> | |
| 6265 <capabilities> | |
| 6266 <required id="can_generate_breakpoint_events"></required> | |
| 6267 </capabilities> | |
| 6268 <parameters> | |
| 6269 <param id="klass"> | |
| 6270 <jclass method="method"/> | |
| 6271 <description> | |
| 6272 The class in which to clear the breakpoint | |
| 6273 </description> | |
| 6274 </param> | |
| 6275 <param id="method"> | |
| 6276 <jmethodID class="klass"/> | |
| 6277 <description> | |
| 6278 The method in which to clear the breakpoint | |
| 6279 </description> | |
| 6280 </param> | |
| 6281 <param id="location"> | |
| 6282 <jlocation/> | |
| 6283 <description> | |
| 6284 the index of the instruction at which to clear the breakpoint | |
| 6285 </description> | |
| 6286 </param> | |
| 6287 </parameters> | |
| 6288 <errors> | |
| 6289 <error id="JVMTI_ERROR_NOT_FOUND"> | |
| 6290 There's no breakpoint at the designated bytecode. | |
| 6291 </error> | |
| 6292 </errors> | |
| 6293 </function> | |
| 6294 | |
| 6295 </category> | |
| 6296 | |
| 6297 <category id="fieldWatch" label="Watched Field"> | |
| 6298 | |
| 6299 <intro> | |
| 6300 </intro> | |
| 6301 | |
| 6302 <function id="SetFieldAccessWatch" num="41"> | |
| 6303 <synopsis>Set Field Access Watch</synopsis> | |
| 6304 <description> | |
| 6305 Generate a <eventlink id="FieldAccess"></eventlink> event | |
| 6306 when the field specified | |
| 6307 by <code>klass</code> and | |
| 6308 <code>field</code> is about to be accessed. | |
| 6309 An event will be generated for each access of the field | |
| 6310 until it is canceled with | |
| 6311 <functionlink id="ClearFieldAccessWatch"></functionlink>. | |
| 6312 Field accesses from Java programming language code or from JNI code are watched, | |
| 6313 fields modified by other means are not watched. | |
| 6314 Note that <jvmti/> users should be aware that their own field accesses | |
| 6315 will trigger the watch. | |
| 6316 A field can only have one field access watch set. | |
| 6317 Modification of a field is not considered an access--use | |
| 6318 <functionlink id="SetFieldModificationWatch"></functionlink> | |
| 6319 to monitor modifications. | |
| 6320 </description> | |
| 6321 <origin>jvmdi</origin> | |
| 6322 <capabilities> | |
| 6323 <required id="can_generate_field_access_events"></required> | |
| 6324 </capabilities> | |
| 6325 <parameters> | |
| 6326 <param id="klass"> | |
| 6327 <jclass field="field"/> | |
| 6328 <description> | |
| 6329 The class containing the field to watch | |
| 6330 </description> | |
| 6331 </param> | |
| 6332 <param id="field"> | |
| 6333 <jfieldID class="klass"/> | |
| 6334 <description> | |
| 6335 The field to watch | |
| 6336 | |
| 6337 </description> | |
| 6338 </param> | |
| 6339 </parameters> | |
| 6340 <errors> | |
| 6341 <error id="JVMTI_ERROR_DUPLICATE"> | |
| 6342 The designated field is already being watched for accesses. | |
| 6343 </error> | |
| 6344 </errors> | |
| 6345 </function> | |
| 6346 | |
| 6347 <function id="ClearFieldAccessWatch" num="42"> | |
| 6348 <synopsis>Clear Field Access Watch</synopsis> | |
| 6349 <description> | |
| 6350 Cancel a field access watch previously set by | |
| 6351 <functionlink id="SetFieldAccessWatch"></functionlink>, on the | |
| 6352 field specified | |
| 6353 by <code>klass</code> and | |
| 6354 <code>field</code>. | |
| 6355 </description> | |
| 6356 <origin>jvmdi</origin> | |
| 6357 <capabilities> | |
| 6358 <required id="can_generate_field_access_events"></required> | |
| 6359 </capabilities> | |
| 6360 <parameters> | |
| 6361 <param id="klass"> | |
| 6362 <jclass field="field"/> | |
| 6363 <description> | |
| 6364 The class containing the field to watch | |
| 6365 </description> | |
| 6366 </param> | |
| 6367 <param id="field"> | |
| 6368 <jfieldID class="klass"/> | |
| 6369 <description> | |
| 6370 The field to watch | |
| 6371 | |
| 6372 </description> | |
| 6373 </param> | |
| 6374 </parameters> | |
| 6375 <errors> | |
| 6376 <error id="JVMTI_ERROR_NOT_FOUND"> | |
| 6377 The designated field is not being watched for accesses. | |
| 6378 </error> | |
| 6379 </errors> | |
| 6380 </function> | |
| 6381 | |
| 6382 <function id="SetFieldModificationWatch" num="43"> | |
| 6383 <synopsis>Set Field Modification Watch</synopsis> | |
| 6384 <description> | |
| 6385 Generate a <eventlink id="FieldModification"></eventlink> event | |
| 6386 when the field specified | |
| 6387 by <code>klass</code> and | |
| 6388 <code>field</code> is about to be modified. | |
| 6389 An event will be generated for each modification of the field | |
| 6390 until it is canceled with | |
| 6391 <functionlink id="ClearFieldModificationWatch"></functionlink>. | |
| 6392 Field modifications from Java programming language code or from JNI code are watched, | |
| 6393 fields modified by other means are not watched. | |
| 6394 Note that <jvmti/> users should be aware that their own field modifications | |
| 6395 will trigger the watch. | |
| 6396 A field can only have one field modification watch set. | |
| 6397 </description> | |
| 6398 <origin>jvmdi</origin> | |
| 6399 <capabilities> | |
| 6400 <required id="can_generate_field_modification_events"></required> | |
| 6401 </capabilities> | |
| 6402 <parameters> | |
| 6403 <param id="klass"> | |
| 6404 <jclass field="field"/> | |
| 6405 <description> | |
| 6406 The class containing the field to watch | |
| 6407 </description> | |
| 6408 </param> | |
| 6409 <param id="field"> | |
| 6410 <jfieldID class="klass"/> | |
| 6411 <description> | |
| 6412 The field to watch | |
| 6413 | |
| 6414 </description> | |
| 6415 </param> | |
| 6416 </parameters> | |
| 6417 <errors> | |
| 6418 <error id="JVMTI_ERROR_DUPLICATE"> | |
| 6419 The designated field is already being watched for modifications. | |
| 6420 </error> | |
| 6421 </errors> | |
| 6422 </function> | |
| 6423 | |
| 6424 <function id="ClearFieldModificationWatch" num="44"> | |
| 6425 <synopsis>Clear Field Modification Watch</synopsis> | |
| 6426 <description> | |
| 6427 | |
| 6428 Cancel a field modification watch previously set by | |
| 6429 <functionlink id="SetFieldModificationWatch"></functionlink>, on the | |
| 6430 field specified | |
| 6431 by <code>klass</code> and | |
| 6432 <code>field</code>. | |
| 6433 </description> | |
| 6434 <origin>jvmdi</origin> | |
| 6435 <capabilities> | |
| 6436 <required id="can_generate_field_modification_events"></required> | |
| 6437 </capabilities> | |
| 6438 <parameters> | |
| 6439 <param id="klass"> | |
| 6440 <jclass field="field"/> | |
| 6441 <description> | |
| 6442 The class containing the field to watch | |
| 6443 </description> | |
| 6444 </param> | |
| 6445 <param id="field"> | |
| 6446 <jfieldID class="klass"/> | |
| 6447 <description> | |
| 6448 The field to watch | |
| 6449 | |
| 6450 </description> | |
| 6451 </param> | |
| 6452 </parameters> | |
| 6453 <errors> | |
| 6454 <error id="JVMTI_ERROR_NOT_FOUND"> | |
| 6455 The designated field is not being watched for modifications. | |
| 6456 </error> | |
| 6457 </errors> | |
| 6458 </function> | |
| 6459 </category> | |
| 6460 | |
| 6461 <category id="class" label="Class"> | |
| 6462 | |
| 6463 <intro> | |
| 6464 </intro> | |
| 6465 | |
| 6466 <function id="GetLoadedClasses" jkernel="yes" num="78"> | |
| 6467 <synopsis>Get Loaded Classes</synopsis> | |
| 6468 <description> | |
| 6469 Return an array of all classes loaded in the virtual machine. | |
| 6470 The number of classes in the array is returned via | |
| 6471 <code>class_count_ptr</code>, and the array itself via | |
| 6472 <code>classes_ptr</code>. | |
| 6473 <p/> | |
| 6474 Array classes of all types (including arrays of primitive types) are | |
| 6475 included in the returned list. Primitive classes (for example, | |
| 6476 <code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list. | |
| 6477 </description> | |
| 6478 <origin>jvmdi</origin> | |
| 6479 <capabilities> | |
| 6480 </capabilities> | |
| 6481 <parameters> | |
| 6482 <param id="class_count_ptr"> | |
| 6483 <outptr><jint/></outptr> | |
| 6484 <description> | |
| 6485 On return, points to the number of classes. | |
| 6486 </description> | |
| 6487 </param> | |
| 6488 <param id="classes_ptr"> | |
| 6489 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf> | |
| 6490 <description> | |
| 6491 On return, points to an array of references, one | |
| 6492 for each class. | |
| 6493 </description> | |
| 6494 </param> | |
| 6495 </parameters> | |
| 6496 <errors> | |
| 6497 </errors> | |
| 6498 </function> | |
| 6499 | |
| 6500 <function id="GetClassLoaderClasses" jkernel="yes" num="79"> | |
| 6501 <synopsis>Get Classloader Classes</synopsis> | |
| 6502 <description> | |
| 6503 Returns an array of those classes for which this class loader has | |
| 6504 been recorded as an initiating loader. Each | |
| 6505 class in the returned array was created by this class loader, | |
| 6506 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
|
6507 See <vmspec chapter="5.3"/>. |
| 0 | 6508 <p/> |
| 6509 For JDK version 1.1 implementations that don't | |
| 6510 recognize the distinction between initiating and defining class loaders, | |
| 6511 this function should return all classes loaded in the virtual machine. | |
| 6512 The number of classes in the array is returned via | |
| 6513 <code>class_count_ptr</code>, and the array itself via | |
| 6514 <code>classes_ptr</code>. | |
| 6515 </description> | |
| 6516 <origin>jvmdi</origin> | |
| 6517 <capabilities> | |
| 6518 </capabilities> | |
| 6519 <parameters> | |
| 6520 <param id="initiating_loader"> | |
| 6521 <ptrtype> | |
| 6522 <jobject/> | |
| 6523 <nullok>the classes initiated by the bootstrap loader will be returned</nullok> | |
| 6524 </ptrtype> | |
| 6525 <description> | |
| 6526 An initiating class loader. | |
| 6527 </description> | |
| 6528 </param> | |
| 6529 <param id="class_count_ptr"> | |
| 6530 <outptr><jint/></outptr> | |
| 6531 <description> | |
| 6532 On return, points to the number of classes. | |
| 6533 </description> | |
| 6534 </param> | |
| 6535 <param id="classes_ptr"> | |
| 6536 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf> | |
| 6537 <description> | |
| 6538 On return, points to an array of references, one | |
| 6539 for each class. | |
| 6540 </description> | |
| 6541 </param> | |
| 6542 </parameters> | |
| 6543 <errors> | |
| 6544 </errors> | |
| 6545 </function> | |
| 6546 | |
| 6547 <function id="GetClassSignature" phase="start" num="48"> | |
| 6548 <synopsis>Get Class Signature</synopsis> | |
| 6549 <description> | |
| 6550 For the class indicated by <code>klass</code>, return the | |
| 6919 | 6551 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16432">JNI |
| 0 | 6552 type signature</externallink> |
| 6553 and the generic signature of the class. | |
| 6554 For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code> | |
| 6555 and <code>int[]</code> is <code>"[I"</code> | |
| 6556 The returned name for primitive classes | |
| 6557 is the type signature character of the corresponding primitive type. | |
| 6558 For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>. | |
| 6559 </description> | |
| 6560 <origin>jvmdiClone</origin> | |
| 6561 <capabilities> | |
| 6562 </capabilities> | |
| 6563 <parameters> | |
| 6564 <param id="klass"> | |
| 6565 <jclass/> | |
| 6566 <description> | |
| 6567 The class to query. | |
| 6568 </description> | |
| 6569 </param> | |
| 6570 <param id="signature_ptr"> | |
| 6571 <allocbuf> | |
| 6572 <char/> | |
| 6573 <nullok>the signature is not returned</nullok> | |
| 6574 </allocbuf> | |
| 6575 <description> | |
| 6576 On return, points to the JNI type signature of the class, encoded as a | |
| 6577 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 6578 </description> | |
| 6579 </param> | |
| 6580 <param id="generic_ptr"> | |
| 6581 <allocbuf> | |
| 6582 <char/> | |
| 6583 <nullok>the generic signature is not returned</nullok> | |
| 6584 </allocbuf> | |
| 6585 <description> | |
| 6586 On return, points to the generic signature of the class, encoded as a | |
| 6587 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 6588 If there is no generic signature attribute for the class, then, | |
| 6589 on return, points to <code>NULL</code>. | |
| 6590 </description> | |
| 6591 </param> | |
| 6592 </parameters> | |
| 6593 <errors> | |
| 6594 </errors> | |
| 6595 </function> | |
| 6596 | |
| 6597 <function id="GetClassStatus" phase="start" num="49"> | |
| 6598 <synopsis>Get Class Status</synopsis> | |
| 6599 <description> | |
| 6600 Get the status of the class. Zero or more of the following bits can be | |
| 6601 set. | |
| 6602 <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits"> | |
| 6603 <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1"> | |
| 6604 Class bytecodes have been verified | |
| 6605 </constant> | |
| 6606 <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2"> | |
| 6607 Class preparation is complete | |
| 6608 </constant> | |
| 6609 <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4"> | |
| 6610 Class initialization is complete. Static initializer has been run. | |
| 6611 </constant> | |
| 6612 <constant id="JVMTI_CLASS_STATUS_ERROR" num="8"> | |
| 6613 Error during initialization makes class unusable | |
| 6614 </constant> | |
| 6615 <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16"> | |
| 6616 Class is an array. If set, all other bits are zero. | |
| 6617 </constant> | |
| 6618 <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32"> | |
| 6619 Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6620 If set, all other bits are zero. | |
| 6621 </constant> | |
| 6622 </constants> | |
| 6623 </description> | |
| 6624 <origin>jvmdi</origin> | |
| 6625 <capabilities> | |
| 6626 </capabilities> | |
| 6627 <parameters> | |
| 6628 <param id="klass"> | |
| 6629 <jclass/> | |
| 6630 <description> | |
| 6631 The class to query. | |
| 6632 </description> | |
| 6633 </param> | |
| 6634 <param id="status_ptr"> | |
| 6635 <outptr><jint/></outptr> | |
| 6636 <description> | |
| 6637 On return, points to the current state of this class as one or | |
| 6638 more of the <internallink id="jvmtiClassStatus">class status flags</internallink>. | |
| 6639 </description> | |
| 6640 </param> | |
| 6641 </parameters> | |
| 6642 <errors> | |
| 6643 </errors> | |
| 6644 </function> | |
| 6645 | |
| 6646 <function id="GetSourceFileName" phase="start" num="50"> | |
| 6647 <synopsis>Get Source File Name</synopsis> | |
| 6648 <description> | |
| 6649 For the class indicated by <code>klass</code>, return the source file | |
| 6650 name via <code>source_name_ptr</code>. The returned string | |
| 6651 is a file name only and never contains a directory name. | |
| 6652 <p/> | |
| 6653 For primitive classes (for example, <code>java.lang.Integer.TYPE</code>) | |
| 6654 and for arrays this function returns | |
| 6655 <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>. | |
| 6656 </description> | |
| 6657 <origin>jvmdi</origin> | |
| 6658 <capabilities> | |
| 6659 <required id="can_get_source_file_name"></required> | |
| 6660 </capabilities> | |
| 6661 <parameters> | |
| 6662 <param id="klass"> | |
| 6663 <jclass/> | |
| 6664 <description> | |
| 6665 The class to query. | |
| 6666 </description> | |
| 6667 </param> | |
| 6668 <param id="source_name_ptr"> | |
| 6669 <allocbuf><char/></allocbuf> | |
| 6670 <description> | |
| 6671 On return, points to the class's source file name, encoded as a | |
| 6672 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 6673 </description> | |
| 6674 </param> | |
| 6675 </parameters> | |
| 6676 <errors> | |
| 6677 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 6678 Class information does not include a source file name. This includes | |
| 6679 cases where the class is an array class or primitive class. | |
| 6680 </error> | |
| 6681 </errors> | |
| 6682 </function> | |
| 6683 | |
| 6684 <function id="GetClassModifiers" phase="start" num="51"> | |
| 6685 <synopsis>Get Class Modifiers</synopsis> | |
| 6686 <description> | |
| 6687 For the class indicated by <code>klass</code>, return the access | |
| 6688 flags | |
| 6689 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
|
6690 Access flags are defined in <vmspec chapter="4"/>. |
| 0 | 6691 <p/> |
| 6692 If the class is an array class, then its public, private, and protected | |
| 6693 modifiers are the same as those of its component type. For arrays of | |
| 6694 primitives, this component type is represented by one of the primitive | |
| 6695 classes (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6696 <p/> | |
| 6697 If the class is a primitive class, its public modifier is always true, | |
| 6698 and its protected and private modifiers are always false. | |
| 6699 <p/> | |
| 6700 If the class is an array class or a primitive class then its final | |
| 6701 modifier is always true and its interface modifier is always false. | |
| 6702 The values of its other modifiers are not determined by this specification. | |
| 6703 | |
| 6704 </description> | |
| 6705 <origin>jvmdi</origin> | |
| 6706 <capabilities> | |
| 6707 </capabilities> | |
| 6708 <parameters> | |
| 6709 <param id="klass"> | |
| 6710 <jclass/> | |
| 6711 <description> | |
| 6712 The class to query. | |
| 6713 </description> | |
| 6714 </param> | |
| 6715 <param id="modifiers_ptr"> | |
| 6716 <outptr><jint/></outptr> | |
| 6717 <description> | |
| 6718 On return, points to the current access flags of this class. | |
| 6719 | |
| 6720 </description> | |
| 6721 </param> | |
| 6722 </parameters> | |
| 6723 <errors> | |
| 6724 </errors> | |
| 6725 </function> | |
| 6726 | |
| 6727 <function id="GetClassMethods" phase="start" num="52"> | |
| 6728 <synopsis>Get Class Methods</synopsis> | |
| 6729 <description> | |
| 6730 For the class indicated by <code>klass</code>, return a count of | |
| 6731 methods via <code>method_count_ptr</code> and a list of | |
| 6732 method IDs via <code>methods_ptr</code>. The method list contains | |
| 6733 constructors and static initializers as well as true methods. | |
| 6734 Only directly declared methods are returned (not inherited methods). | |
| 6735 An empty method list is returned for array classes and primitive classes | |
| 6736 (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6737 </description> | |
| 6738 <origin>jvmdi</origin> | |
| 6739 <capabilities> | |
| 6740 <capability id="can_maintain_original_method_order"/> | |
| 6741 </capabilities> | |
| 6742 <parameters> | |
| 6743 <param id="klass"> | |
| 6744 <jclass/> | |
| 6745 <description> | |
| 6746 The class to query. | |
| 6747 </description> | |
| 6748 </param> | |
| 6749 <param id="method_count_ptr"> | |
| 6750 <outptr><jint/></outptr> | |
| 6751 <description> | |
| 6752 On return, points to the number of methods declared in this class. | |
| 6753 </description> | |
| 6754 </param> | |
| 6755 <param id="methods_ptr"> | |
| 6756 <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf> | |
| 6757 <description> | |
| 6758 On return, points to the method ID array. | |
| 6759 </description> | |
| 6760 </param> | |
| 6761 </parameters> | |
| 6762 <errors> | |
| 6763 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
| 6764 <paramlink id="klass"></paramlink> is not prepared. | |
| 6765 </error> | |
| 6766 </errors> | |
| 6767 </function> | |
| 6768 | |
| 6769 <function id="GetClassFields" phase="start" num="53"> | |
| 6770 <synopsis>Get Class Fields</synopsis> | |
| 6771 <description> | |
| 6772 For the class indicated by <code>klass</code>, return a count of fields | |
| 6773 via <code>field_count_ptr</code> and a list of field IDs via | |
| 6774 <code>fields_ptr</code>. | |
| 6775 Only directly declared fields are returned (not inherited fields). | |
| 6776 Fields are returned in the order they occur in the class file. | |
| 6777 An empty field list is returned for array classes and primitive classes | |
| 6778 (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6779 Use JNI to determine the length of an array. | |
| 6780 </description> | |
| 6781 <origin>jvmdi</origin> | |
| 6782 <capabilities> | |
| 6783 </capabilities> | |
| 6784 <parameters> | |
| 6785 <param id="klass"> | |
| 6786 <jclass/> | |
| 6787 <description> | |
| 6788 The class to query. | |
| 6789 </description> | |
| 6790 </param> | |
| 6791 <param id="field_count_ptr"> | |
| 6792 <outptr><jint/></outptr> | |
| 6793 <description> | |
| 6794 On return, points to the number of fields declared in this class. | |
| 6795 </description> | |
| 6796 </param> | |
| 6797 <param id="fields_ptr"> | |
| 6798 <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf> | |
| 6799 <description> | |
| 6800 On return, points to the field ID array. | |
| 6801 </description> | |
| 6802 </param> | |
| 6803 </parameters> | |
| 6804 <errors> | |
| 6805 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
| 6806 <paramlink id="klass"></paramlink> is not prepared. | |
| 6807 </error> | |
| 6808 </errors> | |
| 6809 </function> | |
| 6810 | |
| 6811 <function id="GetImplementedInterfaces" phase="start" num="54"> | |
| 6812 <synopsis>Get Implemented Interfaces</synopsis> | |
| 6813 <description> | |
| 6814 Return the direct super-interfaces of this class. For a class, this | |
| 6815 function returns the interfaces declared in its <code>implements</code> | |
| 6816 clause. For an interface, this function returns the interfaces declared in | |
| 6817 its <code>extends</code> clause. | |
| 6818 An empty interface list is returned for array classes and primitive classes | |
| 6819 (for example, <code>java.lang.Integer.TYPE</code>). | |
| 6820 </description> | |
| 6821 <origin>jvmdi</origin> | |
| 6822 <capabilities> | |
| 6823 </capabilities> | |
| 6824 <parameters> | |
| 6825 <param id="klass"> | |
| 6826 <jclass/> | |
| 6827 <description> | |
| 6828 The class to query. | |
| 6829 </description> | |
| 6830 </param> | |
| 6831 <param id="interface_count_ptr"> | |
| 6832 <outptr><jint/></outptr> | |
| 6833 <description> | |
| 6834 On return, points to the number of interfaces. | |
| 6835 </description> | |
| 6836 </param> | |
| 6837 <param id="interfaces_ptr"> | |
| 6838 <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf> | |
| 6839 <description> | |
| 6840 On return, points to the interface array. | |
| 6841 </description> | |
| 6842 </param> | |
| 6843 </parameters> | |
| 6844 <errors> | |
| 6845 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
| 6846 <paramlink id="klass"></paramlink> is not prepared. | |
| 6847 </error> | |
| 6848 </errors> | |
| 6849 </function> | |
| 6850 | |
| 6851 <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1"> | |
| 6852 <synopsis>Get Class Version Numbers</synopsis> | |
| 6853 <description> | |
| 6854 For the class indicated by <code>klass</code>, | |
| 6855 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
|
6856 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
|
6857 <vmspec chapter="4"/>. |
| 0 | 6858 </description> |
| 6859 <origin>new</origin> | |
| 6860 <capabilities> | |
| 6861 </capabilities> | |
| 6862 <parameters> | |
| 6863 <param id="klass"> | |
| 6864 <jclass/> | |
| 6865 <description> | |
| 6866 The class to query. | |
| 6867 </description> | |
| 6868 </param> | |
| 6869 <param id="minor_version_ptr"> | |
| 6870 <outptr><jint/></outptr> | |
| 6871 <description> | |
| 6872 On return, points to the value of the | |
| 6873 <code>minor_version</code> item of the | |
| 6874 Class File Format. | |
| 6875 Note: to be consistent with the Class File Format, | |
| 6876 the minor version number is the first parameter. | |
| 6877 </description> | |
| 6878 </param> | |
| 6879 <param id="major_version_ptr"> | |
| 6880 <outptr><jint/></outptr> | |
| 6881 <description> | |
| 6882 On return, points to the value of the | |
| 6883 <code>major_version</code> item of the | |
| 6884 Class File Format. | |
| 6885 </description> | |
| 6886 </param> | |
| 6887 </parameters> | |
| 6888 <errors> | |
| 6889 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 6890 The class is a primitive or array class. | |
| 6891 </error> | |
| 6892 </errors> | |
| 6893 </function> | |
| 6894 | |
| 6895 <function id="GetConstantPool" phase="start" num="146" since="1.1"> | |
| 6896 <synopsis>Get Constant Pool</synopsis> | |
| 6897 <description> | |
| 6898 For the class indicated by <code>klass</code>, | |
| 6899 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
|
6900 <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
|
6901 <vmspec chapter="4"/>. |
| 0 | 6902 The format of the constant pool may differ between versions |
| 6903 of the Class File Format, so, the | |
| 6904 <functionlink id="GetClassVersionNumbers">minor and major | |
| 6905 class version numbers</functionlink> should be checked for | |
| 6906 compatibility. | |
| 6907 <p/> | |
| 6908 The returned constant pool might not have the same layout or | |
| 6909 contents as the constant pool in the defining class file. | |
| 6910 The constant pool returned by GetConstantPool() may have | |
| 6911 more or fewer entries than the defining constant pool. | |
| 6912 Entries may be in a different order. | |
| 6913 The constant pool returned by GetConstantPool() will match the | |
| 6914 constant pool used by | |
| 6915 <functionlink id="GetBytecodes">GetBytecodes()</functionlink>. | |
| 6916 That is, the bytecodes returned by GetBytecodes() will have | |
| 6917 constant pool indices which refer to constant pool entries returned | |
| 6918 by GetConstantPool(). | |
| 6919 Note that since <functionlink id="RetransformClasses"/> | |
| 6920 and <functionlink id="RedefineClasses"/> can change | |
| 6921 the constant pool, the constant pool returned by this function | |
| 6922 can change accordingly. Thus, the correspondence between | |
| 6923 GetConstantPool() and GetBytecodes() does not hold if there | |
| 6924 is an intervening class retransformation or redefinition. | |
| 6925 The value of a constant pool entry used by a given bytecode will | |
| 6926 match that of the defining class file (even if the indices don't match). | |
| 6927 Constant pool entries which are not used directly or indirectly by | |
| 6928 bytecodes (for example, UTF-8 strings associated with annotations) are | |
| 6929 not required to exist in the returned constant pool. | |
| 6930 </description> | |
| 6931 <origin>new</origin> | |
| 6932 <capabilities> | |
| 6933 <required id="can_get_constant_pool"></required> | |
| 6934 </capabilities> | |
| 6935 <parameters> | |
| 6936 <param id="klass"> | |
| 6937 <jclass/> | |
| 6938 <description> | |
| 6939 The class to query. | |
| 6940 </description> | |
| 6941 </param> | |
| 6942 <param id="constant_pool_count_ptr"> | |
| 6943 <outptr><jint/></outptr> | |
| 6944 <description> | |
| 6945 On return, points to the number of entries | |
| 6946 in the constant pool table plus one. | |
| 6947 This corresponds to the <code>constant_pool_count</code> | |
| 6948 item of the Class File Format. | |
| 6949 </description> | |
| 6950 </param> | |
| 6951 <param id="constant_pool_byte_count_ptr"> | |
| 6952 <outptr><jint/></outptr> | |
| 6953 <description> | |
| 6954 On return, points to the number of bytes | |
| 6955 in the returned raw constant pool. | |
| 6956 </description> | |
| 6957 </param> | |
| 6958 <param id="constant_pool_bytes_ptr"> | |
| 6959 <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf> | |
| 6960 <description> | |
| 6961 On return, points to the raw constant pool, that is the bytes | |
| 6962 defined by the <code>constant_pool</code> item of the | |
| 6963 Class File Format | |
| 6964 </description> | |
| 6965 </param> | |
| 6966 </parameters> | |
| 6967 <errors> | |
| 6968 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 6969 The class is a primitive or array class. | |
| 6970 </error> | |
| 6971 </errors> | |
| 6972 </function> | |
| 6973 | |
| 6974 <function id="IsInterface" phase="start" num="55"> | |
| 6975 <synopsis>Is Interface</synopsis> | |
| 6976 <description> | |
| 6977 Determines whether a class object reference represents an interface. | |
| 6978 The <code>jboolean</code> result is | |
| 6979 <code>JNI_TRUE</code> if the "class" is actually an interface, | |
| 6980 <code>JNI_FALSE</code> otherwise. | |
| 6981 </description> | |
| 6982 <origin>jvmdi</origin> | |
| 6983 <capabilities> | |
| 6984 </capabilities> | |
| 6985 <parameters> | |
| 6986 <param id="klass"> | |
| 6987 <jclass/> | |
| 6988 <description> | |
| 6989 The class to query. | |
| 6990 </description> | |
| 6991 </param> | |
| 6992 <param id="is_interface_ptr"> | |
| 6993 <outptr><jboolean/></outptr> | |
| 6994 <description> | |
| 6995 On return, points to the boolean result of this function. | |
| 6996 | |
| 6997 </description> | |
| 6998 </param> | |
| 6999 </parameters> | |
| 7000 <errors> | |
| 7001 </errors> | |
| 7002 </function> | |
| 7003 | |
| 7004 <function id="IsArrayClass" phase="start" num="56"> | |
| 7005 <synopsis>Is Array Class</synopsis> | |
| 7006 <description> | |
| 7007 Determines whether a class object reference represents an array. | |
| 7008 The <code>jboolean</code> result is | |
| 7009 <code>JNI_TRUE</code> if the class is an array, | |
| 7010 <code>JNI_FALSE</code> otherwise. | |
| 7011 </description> | |
| 7012 <origin>jvmdi</origin> | |
| 7013 <capabilities> | |
| 7014 </capabilities> | |
| 7015 <parameters> | |
| 7016 <param id="klass"> | |
| 7017 <jclass/> | |
| 7018 <description> | |
| 7019 The class to query. | |
| 7020 </description> | |
| 7021 </param> | |
| 7022 <param id="is_array_class_ptr"> | |
| 7023 <outptr><jboolean/></outptr> | |
| 7024 <description> | |
| 7025 On return, points to the boolean result of this function. | |
| 7026 | |
| 7027 </description> | |
| 7028 </param> | |
| 7029 </parameters> | |
| 7030 <errors> | |
| 7031 </errors> | |
| 7032 </function> | |
| 7033 | |
| 7034 <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1"> | |
| 7035 <synopsis>Is Modifiable Class</synopsis> | |
| 7036 <description> | |
| 7037 Determines whether a class is modifiable. | |
| 7038 If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/> | |
| 7039 returns <code>JNI_TRUE</code>) the class can be | |
| 7040 redefined with <functionlink id="RedefineClasses"/> (assuming | |
| 7041 the agent possesses the | |
| 7042 <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/> | |
| 7043 capability) or | |
| 7044 retransformed with <functionlink id="RetransformClasses"/> (assuming | |
| 7045 the agent possesses the | |
| 7046 <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> | |
| 7047 capability). | |
| 7048 If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/> | |
| 7049 returns <code>JNI_FALSE</code>) the class can be neither | |
| 7050 redefined nor retransformed. | |
| 7051 <p/> | |
| 7052 Primitive classes (for example, <code>java.lang.Integer.TYPE</code>) | |
| 7053 and array classes are never modifiable. | |
| 7054 <p/> | |
| 7055 </description> | |
| 7056 <origin>new</origin> | |
| 7057 <capabilities> | |
| 7058 <capability id="can_redefine_any_class"> | |
| 7059 If possessed then all classes (except primitive and array classes) | |
| 7060 are modifiable. | |
| 7061 </capability> | |
| 7062 <capability id="can_redefine_classes"> | |
| 7063 No effect on the result of the function. | |
| 7064 But must additionally be possessed to modify the class with | |
| 7065 <functionlink id="RedefineClasses"/>. | |
| 7066 </capability> | |
| 7067 <capability id="can_retransform_classes"> | |
| 7068 No effect on the result of the function. | |
| 7069 But must additionally be possessed to modify the class with | |
| 7070 <functionlink id="RetransformClasses"/>. | |
| 7071 </capability> | |
| 7072 </capabilities> | |
| 7073 <parameters> | |
| 7074 <param id="klass"> | |
| 7075 <jclass/> | |
| 7076 <description> | |
| 7077 The class to query. | |
| 7078 </description> | |
| 7079 </param> | |
| 7080 <param id="is_modifiable_class_ptr"> | |
| 7081 <outptr><jboolean/></outptr> | |
| 7082 <description> | |
| 7083 On return, points to the boolean result of this function. | |
| 7084 </description> | |
| 7085 </param> | |
| 7086 </parameters> | |
| 7087 <errors> | |
| 7088 </errors> | |
| 7089 </function> | |
| 7090 | |
| 7091 <function id="GetClassLoader" phase="start" num="57"> | |
| 7092 <synopsis>Get Class Loader</synopsis> | |
| 7093 <description> | |
| 7094 For the class indicated by <code>klass</code>, return via | |
| 7095 <code>classloader_ptr</code> a reference to the class loader for the | |
| 7096 class. | |
| 7097 </description> | |
| 7098 <origin>jvmdi</origin> | |
| 7099 <capabilities> | |
| 7100 </capabilities> | |
| 7101 <parameters> | |
| 7102 <param id="klass"> | |
| 7103 <jclass/> | |
| 7104 <description> | |
| 7105 The class to query. | |
| 7106 </description> | |
| 7107 </param> | |
| 7108 <param id="classloader_ptr"> | |
| 7109 <outptr><jobject/></outptr> | |
| 7110 <description> | |
| 7111 On return, points to the class loader that loaded | |
| 7112 this class. | |
| 7113 If the class was not created by a class loader | |
| 7114 or if the class loader is the bootstrap class loader, | |
| 7115 points to <code>NULL</code>. | |
| 7116 </description> | |
| 7117 </param> | |
| 7118 </parameters> | |
| 7119 <errors> | |
| 7120 </errors> | |
| 7121 | |
| 7122 </function> | |
| 7123 | |
| 7124 <function id="GetSourceDebugExtension" phase="start" num="90"> | |
| 7125 <synopsis>Get Source Debug Extension</synopsis> | |
| 7126 <description> | |
| 7127 For the class indicated by <code>klass</code>, return the debug | |
| 7128 extension via <code>source_debug_extension_ptr</code>. | |
| 7129 The returned string | |
| 7130 contains exactly the debug extension information present in the | |
| 7131 class file of <code>klass</code>. | |
| 7132 </description> | |
| 7133 <origin>jvmdi</origin> | |
| 7134 <capabilities> | |
| 7135 <required id="can_get_source_debug_extension"></required> | |
| 7136 </capabilities> | |
| 7137 <parameters> | |
| 7138 <param id="klass"> | |
| 7139 <jclass/> | |
| 7140 <description> | |
| 7141 The class to query. | |
| 7142 </description> | |
| 7143 </param> | |
| 7144 <param id="source_debug_extension_ptr"> | |
| 7145 <allocbuf><char/></allocbuf> | |
| 7146 <description> | |
| 7147 On return, points to the class's debug extension, encoded as a | |
| 7148 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7149 </description> | |
| 7150 </param> | |
| 7151 </parameters> | |
| 7152 <errors> | |
| 7153 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 7154 Class information does not include a debug extension. | |
| 7155 </error> | |
| 7156 </errors> | |
| 7157 </function> | |
| 7158 | |
| 7159 <function id="RetransformClasses" jkernel="yes" num="152" since="1.1"> | |
| 7160 <synopsis>Retransform Classes</synopsis> | |
| 7161 <description> | |
| 7162 This function facilitates the | |
| 7163 <internallink id="bci">bytecode instrumentation</internallink> | |
| 7164 of already loaded classes. | |
| 7165 To replace the class definition without reference to the existing | |
| 7166 bytecodes, as one might do when recompiling from source for | |
| 7167 fix-and-continue debugging, <functionlink id="RedefineClasses"/> | |
| 7168 function should be used instead. | |
| 7169 <p/> | |
| 7170 When classes are initially loaded or when they are | |
| 7171 <functionlink id="RedefineClasses">redefined</functionlink>, | |
| 7172 the initial class file bytes can be transformed with the | |
| 7173 <eventlink id="ClassFileLoadHook"/> event. | |
| 7174 This function reruns the transformation process | |
| 7175 (whether or not a transformation has previously occurred). | |
| 7176 This retransformation follows these steps: | |
| 7177 <ul> | |
| 7178 <li>starting from the initial class file bytes | |
| 7179 </li> | |
| 7180 <li>for each <fieldlink id="can_retransform_classes" | |
| 7181 struct="jvmtiCapabilities">retransformation | |
| 7182 incapable</fieldlink> | |
| 7183 agent which received a | |
| 7184 <code>ClassFileLoadHook</code> event during the previous | |
| 7185 load or redefine, the bytes it returned | |
| 7186 (via the <code>new_class_data</code> parameter) | |
| 7187 are reused as the output of the transformation; | |
| 7188 note that this is equivalent to reapplying | |
| 7189 the previous transformation, unaltered. except that | |
| 7190 the <code>ClassFileLoadHook</code> event | |
| 7191 is <b>not</b> sent to these agents | |
| 7192 </li> | |
| 7193 <li>for each <fieldlink id="can_retransform_classes" | |
| 7194 struct="jvmtiCapabilities">retransformation | |
| 7195 capable</fieldlink> | |
| 7196 agent, the <code>ClassFileLoadHook</code> event is sent, | |
| 7197 allowing a new transformation to be applied | |
| 7198 </li> | |
| 7199 <li>the transformed class file bytes are installed as the new | |
| 7200 definition of the class | |
| 7201 </li> | |
| 7202 </ul> | |
| 7203 See the <eventlink id="ClassFileLoadHook"/> event for more details. | |
| 7204 <p/> | |
| 7205 The initial class file bytes represent the bytes passed to | |
| 7206 <code>ClassLoader.defineClass</code> | |
| 7207 or <code>RedefineClasses</code> (before any transformations | |
| 7208 were applied), however they may not exactly match them. | |
| 7209 The constant pool may differ in ways described in | |
| 7210 <functionlink id="GetConstantPool"/>. | |
| 7211 Constant pool indices in the bytecodes of methods will correspond. | |
| 7212 Some attributes may not be present. | |
| 7213 Where order is not meaningful, for example the order of methods, | |
| 7214 order may not be preserved. | |
| 7215 <p/> | |
| 7216 Retransformation can cause new versions of methods to be installed. | |
| 7217 Old method versions may become | |
| 7218 <internallink id="obsoleteMethods">obsolete</internallink> | |
| 7219 The new method version will be used on new invokes. | |
| 7220 If a method has active stack frames, those active frames continue to | |
| 7221 run the bytecodes of the original method version. | |
| 7222 <p/> | |
| 7223 This function does not cause any initialization except that which | |
| 7224 would occur under the customary JVM semantics. | |
| 7225 In other words, retransforming a class does not cause its initializers to be | |
| 7226 run. The values of static fields will remain as they were | |
| 7227 prior to the call. | |
| 7228 <p/> | |
| 7229 Threads need not be suspended. | |
| 7230 <p/> | |
| 7231 All breakpoints in the class are cleared. | |
| 7232 <p/> | |
| 7233 All attributes are updated. | |
| 7234 <p/> | |
| 7235 Instances of the retransformed class are not affected -- fields retain their | |
| 7236 previous values. | |
| 7237 <functionlink id="GetTag">Tags</functionlink> on the instances are | |
| 7238 also unaffected. | |
| 7239 <p/> | |
| 7240 In response to this call, no events other than the | |
| 7241 <eventlink id="ClassFileLoadHook"/> event | |
| 7242 will be sent. | |
| 7243 <p/> | |
| 7244 The retransformation may change method bodies, the constant pool and attributes. | |
| 7245 The retransformation must not add, remove or rename fields or methods, change the | |
| 7246 signatures of methods, change modifiers, or change inheritance. | |
| 7247 These restrictions may be lifted in future versions. | |
| 7248 See the error return description below for information on error codes | |
| 7249 returned if an unsupported retransformation is attempted. | |
| 7250 The class file bytes are not verified or installed until they have passed | |
| 7251 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the | |
| 7252 returned error code reflects the result of the transformations. | |
| 7253 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, | |
| 7254 none of the classes to be retransformed will have a new definition installed. | |
| 7255 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) | |
| 7256 all of the classes to be retransformed will have their new definitions installed. | |
| 7257 </description> | |
| 7258 <origin>new</origin> | |
| 7259 <capabilities> | |
| 7260 <required id="can_retransform_classes"></required> | |
| 7261 <capability id="can_retransform_any_class"></capability> | |
| 7262 </capabilities> | |
| 7263 <parameters> | |
| 7264 <param id="class_count"> | |
| 7265 <jint min="0"/> | |
| 7266 <description> | |
| 7267 The number of classes to be retransformed. | |
| 7268 </description> | |
| 7269 </param> | |
| 7270 <param id="classes"> | |
| 7271 <inbuf incount="class_count"><jclass/></inbuf> | |
| 7272 <description> | |
| 7273 The array of classes to be retransformed. | |
| 7274 </description> | |
| 7275 </param> | |
| 7276 </parameters> | |
| 7277 <errors> | |
| 7278 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> | |
| 7279 One of the <paramlink id="classes"/> cannot be modified. | |
| 7280 See <functionlink id="IsModifiableClass"/>. | |
| 7281 </error> | |
| 7282 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 7283 One of the <paramlink id="classes"/> is not a valid class. | |
| 7284 </error> | |
| 7285 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> | |
| 7286 A retransformed class file has a version number not supported by this VM. | |
| 7287 </error> | |
| 7288 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> | |
| 7289 A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>). | |
| 7290 </error> | |
| 7291 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> | |
| 7292 The retransformed class file definitions would lead to a circular definition | |
| 7293 (the VM would return a <code>ClassCircularityError</code>). | |
| 7294 </error> | |
| 7295 <error id="JVMTI_ERROR_FAILS_VERIFICATION"> | |
| 7296 The retransformed class file bytes fail verification. | |
| 7297 </error> | |
| 7298 <error id="JVMTI_ERROR_NAMES_DONT_MATCH"> | |
| 7299 The class name defined in a retransformed class file is | |
| 7300 different from the name in the old class object. | |
| 7301 </error> | |
| 7302 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> | |
| 7303 A retransformed class file would require adding a method. | |
| 7304 </error> | |
| 7305 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> | |
| 7306 A retransformed class file changes a field. | |
| 7307 </error> | |
| 7308 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> | |
| 7309 A direct superclass is different for a retransformed class file, | |
| 7310 or the set of directly implemented | |
| 7311 interfaces is different. | |
| 7312 </error> | |
| 7313 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> | |
| 7314 A retransformed class file does not declare a method | |
| 7315 declared in the old class version. | |
| 7316 </error> | |
| 7317 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> | |
| 7318 A retransformed class file has different class modifiers. | |
| 7319 </error> | |
| 7320 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> | |
| 7321 A method in the retransformed class file has different modifiers | |
| 7322 than its counterpart in the old class version. | |
| 7323 </error> | |
| 7324 </errors> | |
| 7325 </function> | |
| 7326 | |
| 7327 <function id="RedefineClasses" jkernel="yes" num="87"> | |
| 7328 <synopsis>Redefine Classes</synopsis> | |
| 7329 <typedef id="jvmtiClassDefinition" label="Class redefinition description"> | |
| 7330 <field id="klass"> | |
| 7331 <jclass/> | |
| 7332 <description> | |
| 7333 Class object for this class | |
| 7334 </description> | |
| 7335 </field> | |
| 7336 <field id="class_byte_count"> | |
| 7337 <jint/> | |
| 7338 <description> | |
| 7339 Number of bytes defining class (below) | |
| 7340 </description> | |
| 7341 </field> | |
| 7342 <field id="class_bytes"> | |
| 7343 <inbuf incount="class_byte_count"><uchar/></inbuf> | |
| 7344 <description> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7345 Bytes defining class (in <vmspec chapter="4"/>) |
| 0 | 7346 </description> |
| 7347 </field> | |
| 7348 </typedef> | |
| 7349 <description> | |
| 7350 All classes given are redefined according to the definitions | |
| 7351 supplied. | |
| 7352 This function is used to replace the definition of a class | |
| 7353 with a new definition, as might be needed in fix-and-continue | |
| 7354 debugging. | |
| 7355 Where the existing class file bytes are to be transformed, for | |
| 7356 example in | |
| 7357 <internallink id="bci">bytecode instrumentation</internallink>, | |
| 7358 <functionlink id="RetransformClasses"/> should be used. | |
| 7359 <p/> | |
| 7360 Redefinition can cause new versions of methods to be installed. | |
| 7361 Old method versions may become | |
| 7362 <internallink id="obsoleteMethods">obsolete</internallink> | |
| 7363 The new method version will be used on new invokes. | |
| 7364 If a method has active stack frames, those active frames continue to | |
| 7365 run the bytecodes of the original method version. | |
| 7366 If resetting of stack frames is desired, use | |
| 7367 <functionlink id="PopFrame"></functionlink> | |
| 7368 to pop frames with obsolete method versions. | |
| 7369 <p/> | |
| 7370 This function does not cause any initialization except that which | |
| 7371 would occur under the customary JVM semantics. | |
| 7372 In other words, redefining a class does not cause its initializers to be | |
| 7373 run. The values of static fields will remain as they were | |
| 7374 prior to the call. | |
| 7375 <p/> | |
| 7376 Threads need not be suspended. | |
| 7377 <p/> | |
| 7378 All breakpoints in the class are cleared. | |
| 7379 <p/> | |
| 7380 All attributes are updated. | |
| 7381 <p/> | |
| 7382 Instances of the redefined class are not affected -- fields retain their | |
| 7383 previous values. | |
| 7384 <functionlink id="GetTag">Tags</functionlink> on the instances are | |
| 7385 also unaffected. | |
| 7386 <p/> | |
| 7387 In response to this call, the <jvmti/> event | |
| 7388 <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink> | |
| 7389 will be sent (if enabled), but no other <jvmti/> events will be sent. | |
| 7390 <p/> | |
| 7391 The redefinition may change method bodies, the constant pool and attributes. | |
| 7392 The redefinition must not add, remove or rename fields or methods, change the | |
| 7393 signatures of methods, change modifiers, or change inheritance. | |
| 7394 These restrictions may be lifted in future versions. | |
| 7395 See the error return description below for information on error codes | |
| 7396 returned if an unsupported redefinition is attempted. | |
| 7397 The class file bytes are not verified or installed until they have passed | |
| 7398 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the | |
| 7399 returned error code reflects the result of the transformations applied | |
| 7400 to the bytes passed into <paramlink id="class_definitions"/>. | |
| 7401 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, | |
| 7402 none of the classes to be redefined will have a new definition installed. | |
| 7403 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) | |
| 7404 all of the classes to be redefined will have their new definitions installed. | |
| 7405 </description> | |
| 7406 <origin>jvmdi</origin> | |
| 7407 <capabilities> | |
| 7408 <required id="can_redefine_classes"></required> | |
| 7409 <capability id="can_redefine_any_class"></capability> | |
| 7410 </capabilities> | |
| 7411 <parameters> | |
| 7412 <param id="class_count"> | |
| 7413 <jint min="0"/> | |
| 7414 <description> | |
| 7415 The number of classes specified in <code>class_definitions</code> | |
| 7416 </description> | |
| 7417 </param> | |
| 7418 <param id="class_definitions"> | |
| 7419 <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf> | |
| 7420 <description> | |
| 7421 The array of new class definitions | |
| 7422 </description> | |
| 7423 </param> | |
| 7424 </parameters> | |
| 7425 <errors> | |
| 7426 <error id="JVMTI_ERROR_NULL_POINTER"> | |
| 7427 One of <code>class_bytes</code> is <code>NULL</code>. | |
| 7428 </error> | |
| 7429 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> | |
| 7430 An element of <code>class_definitions</code> cannot be modified. | |
| 7431 See <functionlink id="IsModifiableClass"/>. | |
| 7432 </error> | |
| 7433 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
| 7434 An element of <code>class_definitions</code> is not a valid class. | |
| 7435 </error> | |
| 7436 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> | |
| 7437 A new class file has a version number not supported by this VM. | |
| 7438 </error> | |
| 7439 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> | |
| 7440 A new class file is malformed (The VM would return a <code>ClassFormatError</code>). | |
| 7441 </error> | |
| 7442 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> | |
| 7443 The new class file definitions would lead to a circular definition | |
| 7444 (the VM would return a <code>ClassCircularityError</code>). | |
| 7445 </error> | |
| 7446 <error id="JVMTI_ERROR_FAILS_VERIFICATION"> | |
| 7447 The class bytes fail verification. | |
| 7448 </error> | |
| 7449 <error id="JVMTI_ERROR_NAMES_DONT_MATCH"> | |
| 7450 The class name defined in a new class file is | |
| 7451 different from the name in the old class object. | |
| 7452 </error> | |
| 7453 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> | |
| 7454 A new class file would require adding a method. | |
| 7455 </error> | |
| 7456 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> | |
| 7457 A new class version changes a field. | |
| 7458 </error> | |
| 7459 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> | |
| 7460 A direct superclass is different for a new class | |
| 7461 version, or the set of directly implemented | |
| 7462 interfaces is different. | |
| 7463 </error> | |
| 7464 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> | |
| 7465 A new class version does not declare a method | |
| 7466 declared in the old class version. | |
| 7467 </error> | |
| 7468 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> | |
| 7469 A new class version has different modifiers. | |
| 7470 </error> | |
| 7471 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> | |
| 7472 A method in the new class version has different modifiers | |
| 7473 than its counterpart in the old class version. | |
| 7474 </error> | |
| 7475 </errors> | |
| 7476 </function> | |
| 7477 | |
| 7478 </category> | |
| 7479 | |
| 7480 <category id="object" label="Object"> | |
| 7481 | |
| 7482 <function id="GetObjectSize" jkernel="yes" phase="start" num="154"> | |
| 7483 <synopsis>Get Object Size</synopsis> | |
| 7484 <description> | |
| 7485 For the object indicated by <code>object</code>, | |
| 7486 return via <code>size_ptr</code> the size of the object. | |
| 7487 This size is an implementation-specific approximation of | |
| 7488 the amount of storage consumed by this object. | |
| 7489 It may include some or all of the object's overhead, and thus | |
| 7490 is useful for comparison within an implementation but not | |
| 7491 between implementations. | |
| 7492 The estimate may change during a single invocation of the JVM. | |
| 7493 </description> | |
| 7494 <origin>new</origin> | |
| 7495 <capabilities> | |
| 7496 </capabilities> | |
| 7497 <parameters> | |
| 7498 <param id="object"> | |
| 7499 <jobject/> | |
| 7500 <description> | |
| 7501 The object to query. | |
| 7502 </description> | |
| 7503 </param> | |
| 7504 <param id="size_ptr"> | |
| 7505 <outptr><jlong/></outptr> | |
| 7506 <description> | |
| 7507 On return, points to the object's size in bytes. | |
| 7508 </description> | |
| 7509 </param> | |
| 7510 </parameters> | |
| 7511 <errors> | |
| 7512 </errors> | |
| 7513 </function> | |
| 7514 | |
| 7515 <function id="GetObjectHashCode" phase="start" num="58"> | |
| 7516 <synopsis>Get Object Hash Code</synopsis> | |
| 7517 <description> | |
| 7518 For the object indicated by <code>object</code>, | |
| 7519 return via <code>hash_code_ptr</code> a hash code. | |
| 7520 This hash code could be used to maintain a hash table of object references, | |
| 7521 however, on some implementations this can cause significant performance | |
| 7522 impacts--in most cases | |
| 7523 <internallink id="Heap">tags</internallink> | |
| 7524 will be a more efficient means of associating information with objects. | |
| 7525 This function guarantees | |
| 7526 the same hash code value for a particular object throughout its life | |
| 7527 </description> | |
| 7528 <origin>jvmdi</origin> | |
| 7529 <capabilities> | |
| 7530 </capabilities> | |
| 7531 <parameters> | |
| 7532 <param id="object"> | |
| 7533 <jobject/> | |
| 7534 <description> | |
| 7535 The object to query. | |
| 7536 </description> | |
| 7537 </param> | |
| 7538 <param id="hash_code_ptr"> | |
| 7539 <outptr><jint/></outptr> | |
| 7540 <description> | |
| 7541 On return, points to the object's hash code. | |
| 7542 </description> | |
| 7543 </param> | |
| 7544 </parameters> | |
| 7545 <errors> | |
| 7546 </errors> | |
| 7547 </function> | |
| 7548 | |
| 7549 <function id="GetObjectMonitorUsage" num="59"> | |
| 7550 <synopsis>Get Object Monitor Usage</synopsis> | |
| 7551 <typedef id="jvmtiMonitorUsage" label="Object monitor usage information"> | |
| 7552 <field id="owner"> | |
| 7553 <jthread/> | |
| 7554 <description> | |
| 7555 The thread owning this monitor, or <code>NULL</code> if unused | |
| 7556 </description> | |
| 7557 </field> | |
| 7558 <field id="entry_count"> | |
| 7559 <jint/> | |
| 7560 <description> | |
| 7561 The number of times the owning thread has entered the monitor | |
| 7562 </description> | |
| 7563 </field> | |
| 7564 <field id="waiter_count"> | |
| 7565 <jint/> | |
| 7566 <description> | |
| 7567 The number of threads waiting to own this monitor | |
| 7568 </description> | |
| 7569 </field> | |
| 7570 <field id="waiters"> | |
| 7571 <allocfieldbuf><jthread/></allocfieldbuf> | |
| 7572 <description> | |
| 7573 The <code>waiter_count</code> waiting threads | |
| 7574 </description> | |
| 7575 </field> | |
| 7576 <field id="notify_waiter_count"> | |
| 7577 <jint/> | |
| 7578 <description> | |
| 7579 The number of threads waiting to be notified by this monitor | |
| 7580 </description> | |
| 7581 </field> | |
| 7582 <field id="notify_waiters"> | |
| 7583 <allocfieldbuf><jthread/></allocfieldbuf> | |
| 7584 <description> | |
| 7585 The <code>notify_waiter_count</code> threads waiting to be notified | |
| 7586 </description> | |
| 7587 </field> | |
| 7588 </typedef> | |
| 7589 <description> | |
| 7590 Get information about the object's monitor. | |
| 7591 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure | |
| 7592 are filled in with information about usage of the monitor. | |
| 7593 <todo> | |
| 7594 Decide and then clarify suspend requirements. | |
| 7595 </todo> | |
| 7596 </description> | |
| 7597 <origin>jvmdi</origin> | |
| 7598 <capabilities> | |
| 7599 <required id="can_get_monitor_info"></required> | |
| 7600 </capabilities> | |
| 7601 <parameters> | |
| 7602 <param id="object"> | |
| 7603 <jobject/> | |
| 7604 <description> | |
| 7605 The object to query. | |
| 7606 </description> | |
| 7607 </param> | |
| 7608 <param id="info_ptr"> | |
| 7609 <outptr><struct>jvmtiMonitorUsage</struct></outptr> | |
| 7610 <description> | |
| 7611 On return, filled with monitor information for the | |
| 7612 specified object. | |
| 7613 </description> | |
| 7614 </param> | |
| 7615 </parameters> | |
| 7616 <errors> | |
| 7617 </errors> | |
| 7618 </function> | |
| 7619 | |
| 7620 <elide> | |
| 7621 <function id="GetObjectMonitors" num="116"> | |
| 7622 <synopsis>Get Object Monitors</synopsis> | |
| 7623 <description> | |
| 7624 Return the list of object monitors. | |
| 7625 <p/> | |
| 7626 Note: details about each monitor can be examined with | |
| 7627 <functionlink id="GetObjectMonitorUsage"></functionlink>. | |
| 7628 </description> | |
| 7629 <origin>new</origin> | |
| 7630 <capabilities> | |
| 7631 <required id="can_get_monitor_info"></required> | |
| 7632 </capabilities> | |
| 7633 <parameters> | |
| 7634 <param id="monitorCnt"> | |
| 7635 <outptr><jint/></outptr> | |
| 7636 <description> | |
| 7637 On return, pointer to the number | |
| 7638 of monitors returned in <code>monitors_ptr</code>. | |
| 7639 </description> | |
| 7640 </param> | |
| 7641 <param id="monitors_ptr"> | |
| 7642 <allocbuf outcount="monitorCnt"><jobject/></allocbuf> | |
| 7643 <description> | |
| 7644 On return, pointer to the monitor list. | |
| 7645 </description> | |
| 7646 </param> | |
| 7647 </parameters> | |
| 7648 <errors> | |
| 7649 </errors> | |
| 7650 </function> | |
| 7651 </elide> | |
| 7652 | |
| 7653 </category> | |
| 7654 | |
| 7655 <category id="fieldCategory" label="Field"> | |
| 7656 | |
| 7657 <intro> | |
| 7658 </intro> | |
| 7659 | |
| 7660 <function id="GetFieldName" phase="start" num="60"> | |
| 7661 <synopsis>Get Field Name (and Signature)</synopsis> | |
| 7662 <description> | |
| 7663 For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>, | |
| 7664 return the field name via <paramlink id="name_ptr"/> and field signature via | |
| 7665 <paramlink id="signature_ptr"/>. | |
| 7666 <p/> | |
| 7667 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
|
7668 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
|
7669 <vmspec chapter="4.3.2"/>. |
| 0 | 7670 </description> |
| 7671 <origin>jvmdiClone</origin> | |
| 7672 <capabilities> | |
| 7673 </capabilities> | |
| 7674 <parameters> | |
| 7675 <param id="klass"> | |
| 7676 <jclass field="field"/> | |
| 7677 <description> | |
| 7678 The class of the field to query. | |
| 7679 </description> | |
| 7680 </param> | |
| 7681 <param id="field"> | |
| 7682 <jfieldID class="klass"/> | |
| 7683 <description> | |
| 7684 The field to query. | |
| 7685 </description> | |
| 7686 </param> | |
| 7687 <param id="name_ptr"> | |
| 7688 <allocbuf> | |
| 7689 <char/> | |
| 7690 <nullok>the name is not returned</nullok> | |
| 7691 </allocbuf> | |
| 7692 <description> | |
| 7693 On return, points to the field name, encoded as a | |
| 7694 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7695 </description> | |
| 7696 </param> | |
| 7697 <param id="signature_ptr"> | |
| 7698 <allocbuf> | |
| 7699 <char/> | |
| 7700 <nullok>the signature is not returned</nullok> | |
| 7701 </allocbuf> | |
| 7702 <description> | |
| 7703 On return, points to the field signature, encoded as a | |
| 7704 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7705 </description> | |
| 7706 </param> | |
| 7707 <param id="generic_ptr"> | |
| 7708 <allocbuf> | |
| 7709 <char/> | |
| 7710 <nullok>the generic signature is not returned</nullok> | |
| 7711 </allocbuf> | |
| 7712 <description> | |
| 7713 On return, points to the generic signature of the field, encoded as a | |
| 7714 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7715 If there is no generic signature attribute for the field, then, | |
| 7716 on return, points to <code>NULL</code>. | |
| 7717 </description> | |
| 7718 </param> | |
| 7719 </parameters> | |
| 7720 <errors> | |
| 7721 </errors> | |
| 7722 </function> | |
| 7723 | |
| 7724 <function id="GetFieldDeclaringClass" phase="start" num="61"> | |
| 7725 <synopsis>Get Field Declaring Class</synopsis> | |
| 7726 <description> | |
| 7727 For the field indicated by <code>klass</code> and <code>field</code> | |
| 7728 return the class that defined it via <code>declaring_class_ptr</code>. | |
| 7729 The declaring class will either be <code>klass</code>, a superclass, or | |
| 7730 an implemented interface. | |
| 7731 </description> | |
| 7732 <origin>jvmdi</origin> | |
| 7733 <capabilities> | |
| 7734 </capabilities> | |
| 7735 <parameters> | |
| 7736 <param id="klass"> | |
| 7737 <jclass field="field"/> | |
| 7738 <description> | |
| 7739 The class to query. | |
| 7740 </description> | |
| 7741 </param> | |
| 7742 <param id="field"> | |
| 7743 <jfieldID class="klass"/> | |
| 7744 <description> | |
| 7745 The field to query. | |
| 7746 </description> | |
| 7747 </param> | |
| 7748 <param id="declaring_class_ptr"> | |
| 7749 <outptr><jclass/></outptr> | |
| 7750 <description> | |
| 7751 On return, points to the declaring class | |
| 7752 </description> | |
| 7753 </param> | |
| 7754 </parameters> | |
| 7755 <errors> | |
| 7756 </errors> | |
| 7757 </function> | |
| 7758 | |
| 7759 <function id="GetFieldModifiers" phase="start" num="62"> | |
| 7760 <synopsis>Get Field Modifiers</synopsis> | |
| 7761 <description> | |
| 7762 For the field indicated by <code>klass</code> and <code>field</code> | |
| 7763 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
|
7764 Access flags are defined in <vmspec chapter="4"/>. |
| 0 | 7765 </description> |
| 7766 <origin>jvmdi</origin> | |
| 7767 <capabilities> | |
| 7768 </capabilities> | |
| 7769 <parameters> | |
| 7770 <param id="klass"> | |
| 7771 <jclass field="field"/> | |
| 7772 <description> | |
| 7773 The class to query. | |
| 7774 </description> | |
| 7775 </param> | |
| 7776 <param id="field"> | |
| 7777 <jfieldID class="klass"/> | |
| 7778 <description> | |
| 7779 The field to query. | |
| 7780 </description> | |
| 7781 </param> | |
| 7782 <param id="modifiers_ptr"> | |
| 7783 <outptr><jint/></outptr> | |
| 7784 <description> | |
| 7785 On return, points to the access flags. | |
| 7786 </description> | |
| 7787 </param> | |
| 7788 </parameters> | |
| 7789 <errors> | |
| 7790 </errors> | |
| 7791 </function> | |
| 7792 | |
| 7793 <function id="IsFieldSynthetic" phase="start" num="63"> | |
| 7794 <synopsis>Is Field Synthetic</synopsis> | |
| 7795 <description> | |
| 7796 For the field indicated by <code>klass</code> and <code>field</code>, return a | |
| 7797 value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>. | |
| 7798 Synthetic fields are generated by the compiler but not present in the | |
| 7799 original source code. | |
| 7800 </description> | |
| 7801 <origin>jvmdi</origin> | |
| 7802 <capabilities> | |
| 7803 <required id="can_get_synthetic_attribute"></required> | |
| 7804 </capabilities> | |
| 7805 <parameters> | |
| 7806 <param id="klass"> | |
| 7807 <jclass field="field"/> | |
| 7808 <description> | |
| 7809 The class of the field to query. | |
| 7810 </description> | |
| 7811 </param> | |
| 7812 <param id="field"> | |
| 7813 <jfieldID class="klass"/> | |
| 7814 <description> | |
| 7815 The field to query. | |
| 7816 </description> | |
| 7817 </param> | |
| 7818 <param id="is_synthetic_ptr"> | |
| 7819 <outptr><jboolean/></outptr> | |
| 7820 <description> | |
| 7821 On return, points to the boolean result of this function. | |
| 7822 </description> | |
| 7823 </param> | |
| 7824 </parameters> | |
| 7825 <errors> | |
| 7826 </errors> | |
| 7827 </function> | |
| 7828 | |
| 7829 </category> | |
| 7830 | |
| 7831 <category id="method" label="Method"> | |
| 7832 | |
| 7833 <intro> | |
| 7834 These functions provide information about a method (represented as a | |
| 7835 <typelink id="jmethodID"/>) and set how methods are processed. | |
| 7836 </intro> | |
| 7837 | |
| 7838 <intro id="obsoleteMethods" label="Obsolete Methods"> | |
| 7839 The functions <functionlink id="RetransformClasses"/> and | |
| 7840 <functionlink id="RedefineClasses"/> can cause new versions | |
| 7841 of methods to be installed. | |
| 7842 An original version of a method is considered equivalent | |
| 7843 to the new version if: | |
| 7844 <ul> | |
| 7845 <li>their bytecodes are the same except for indices into the | |
| 7846 constant pool and </li> | |
| 7847 <li>the referenced constants are equal.</li> | |
| 7848 </ul> | |
| 7849 An original method version which is not equivalent to the | |
| 7850 new method version is called obsolete and is assigned a new method ID; | |
| 7851 the original method ID now refers to the new method version. | |
| 7852 A method ID can be tested for obsolescence with | |
| 7853 <functionlink id="IsMethodObsolete"/>. | |
| 7854 </intro> | |
| 7855 | |
| 7856 <function id="GetMethodName" phase="start" num="64"> | |
| 7857 <synopsis>Get Method Name (and Signature)</synopsis> | |
| 7858 <description> | |
| 7859 For the method indicated by <code>method</code>, | |
| 7860 return the method name via <code>name_ptr</code> and method signature via | |
| 7861 <code>signature_ptr</code>. | |
| 7862 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7863 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
|
7864 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
|
7865 <vmspec chapter="4.3.3"/>. |
| 0 | 7866 Note this is different |
| 7867 than method signatures as defined in the <i>Java Language Specification</i>. | |
| 7868 </description> | |
| 7869 <origin>jvmdiClone</origin> | |
| 7870 <capabilities> | |
| 7871 </capabilities> | |
| 7872 <parameters> | |
| 7873 <param id="method"> | |
| 7874 <jmethodID/> | |
| 7875 <description> | |
| 7876 The method to query. | |
| 7877 </description> | |
| 7878 </param> | |
| 7879 <param id="name_ptr"> | |
| 7880 <allocbuf> | |
| 7881 <char/> | |
| 7882 <nullok>the name is not returned</nullok> | |
| 7883 </allocbuf> | |
| 7884 <description> | |
| 7885 On return, points to the method name, encoded as a | |
| 7886 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7887 </description> | |
| 7888 </param> | |
| 7889 <param id="signature_ptr"> | |
| 7890 <allocbuf> | |
| 7891 <char/> | |
| 7892 <nullok>the signature is not returned</nullok> | |
| 7893 </allocbuf> | |
| 7894 <description> | |
| 7895 On return, points to the method signature, encoded as a | |
| 7896 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7897 </description> | |
| 7898 </param> | |
| 7899 <param id="generic_ptr"> | |
| 7900 <allocbuf> | |
| 7901 <char/> | |
| 7902 <nullok>the generic signature is not returned</nullok> | |
| 7903 </allocbuf> | |
| 7904 <description> | |
| 7905 On return, points to the generic signature of the method, encoded as a | |
| 7906 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 7907 If there is no generic signature attribute for the method, then, | |
| 7908 on return, points to <code>NULL</code>. | |
| 7909 </description> | |
| 7910 </param> | |
| 7911 </parameters> | |
| 7912 <errors> | |
| 7913 </errors> | |
| 7914 </function> | |
| 7915 | |
| 7916 <function id="GetMethodDeclaringClass" phase="start" num="65"> | |
| 7917 <synopsis>Get Method Declaring Class</synopsis> | |
| 7918 <description> | |
| 7919 For the method indicated by <code>method</code>, | |
| 7920 return the class that defined it via <code>declaring_class_ptr</code>. | |
| 7921 </description> | |
| 7922 <origin>jvmdi</origin> | |
| 7923 <capabilities> | |
| 7924 </capabilities> | |
| 7925 <parameters> | |
| 7926 <param id="klass"> | |
| 7927 <jclass method="method"/> | |
| 7928 <description> | |
| 7929 The class to query. | |
| 7930 </description> | |
| 7931 </param> | |
| 7932 <param id="method"> | |
| 7933 <jmethodID class="klass"/> | |
| 7934 <description> | |
| 7935 The method to query. | |
| 7936 </description> | |
| 7937 </param> | |
| 7938 <param id="declaring_class_ptr"> | |
| 7939 <outptr><jclass/></outptr> | |
| 7940 <description> | |
| 7941 On return, points to the declaring class | |
| 7942 </description> | |
| 7943 </param> | |
| 7944 </parameters> | |
| 7945 <errors> | |
| 7946 </errors> | |
| 7947 </function> | |
| 7948 | |
| 7949 <function id="GetMethodModifiers" phase="start" num="66"> | |
| 7950 <synopsis>Get Method Modifiers</synopsis> | |
| 7951 <description> | |
| 7952 For the method indicated by <code>method</code>, | |
| 7953 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
|
7954 Access flags are defined in <vmspec chapter="4"/>. |
| 0 | 7955 </description> |
| 7956 <origin>jvmdi</origin> | |
| 7957 <capabilities> | |
| 7958 </capabilities> | |
| 7959 <parameters> | |
| 7960 <param id="klass"> | |
| 7961 <jclass method="method"/> | |
| 7962 <description> | |
| 7963 The class to query. | |
| 7964 </description> | |
| 7965 </param> | |
| 7966 <param id="method"> | |
| 7967 <jmethodID class="klass"/> | |
| 7968 <description> | |
| 7969 The method to query. | |
| 7970 </description> | |
| 7971 </param> | |
| 7972 <param id="modifiers_ptr"> | |
| 7973 <outptr><jint/></outptr> | |
| 7974 <description> | |
| 7975 On return, points to the access flags. | |
| 7976 </description> | |
| 7977 </param> | |
| 7978 </parameters> | |
| 7979 <errors> | |
| 7980 </errors> | |
| 7981 </function> | |
| 7982 | |
| 7983 <function id="GetMaxLocals" phase="start" num="68"> | |
| 7984 <synopsis>Get Max Locals</synopsis> | |
| 7985 <description> | |
| 7986 For the method indicated by <code>method</code>, | |
| 7987 return the number of local variable slots used by the method, | |
| 7988 including the local variables used to pass parameters to the | |
| 7989 method on its invocation. | |
| 7990 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
7991 See <code>max_locals</code> in <vmspec chapter="4.7.3"/>. |
| 0 | 7992 </description> |
| 7993 <origin>jvmdi</origin> | |
| 7994 <capabilities> | |
| 7995 </capabilities> | |
| 7996 <parameters> | |
| 7997 <param id="klass"> | |
| 7998 <jclass method="method"/> | |
| 7999 <description> | |
| 8000 The class to query. | |
| 8001 </description> | |
| 8002 </param> | |
| 8003 <param id="method"> | |
| 8004 <jmethodID class="klass" native="error"/> | |
| 8005 <description> | |
| 8006 The method to query. | |
| 8007 </description> | |
| 8008 </param> | |
| 8009 <param id="max_ptr"> | |
| 8010 <outptr><jint/></outptr> | |
| 8011 <description> | |
| 8012 On return, points to the maximum number of local slots | |
| 8013 </description> | |
| 8014 </param> | |
| 8015 </parameters> | |
| 8016 <errors> | |
| 8017 </errors> | |
| 8018 </function> | |
| 8019 | |
| 8020 <function id="GetArgumentsSize" phase="start" num="69"> | |
| 8021 <synopsis>Get Arguments Size</synopsis> | |
| 8022 <description> | |
| 8023 For the method indicated by <code>method</code>, | |
| 8024 return via <code>max_ptr</code> the number of local variable slots used | |
| 8025 by the method's arguments. | |
| 8026 Note that two-word arguments use two slots. | |
| 8027 </description> | |
| 8028 <origin>jvmdi</origin> | |
| 8029 <capabilities> | |
| 8030 </capabilities> | |
| 8031 <parameters> | |
| 8032 <param id="klass"> | |
| 8033 <jclass method="method"/> | |
| 8034 <description> | |
| 8035 The class to query. | |
| 8036 </description> | |
| 8037 </param> | |
| 8038 <param id="method"> | |
| 8039 <jmethodID class="klass" native="error"/> | |
| 8040 <description> | |
| 8041 The method to query. | |
| 8042 </description> | |
| 8043 </param> | |
| 8044 <param id="size_ptr"> | |
| 8045 <outptr><jint/></outptr> | |
| 8046 <description> | |
| 8047 On return, points to the number of argument slots | |
| 8048 </description> | |
| 8049 </param> | |
| 8050 </parameters> | |
| 8051 <errors> | |
| 8052 </errors> | |
| 8053 </function> | |
| 8054 | |
| 8055 <function id="GetLineNumberTable" phase="start" num="70"> | |
| 8056 <synopsis>Get Line Number Table</synopsis> | |
| 8057 <typedef id="jvmtiLineNumberEntry" label="Line number table entry"> | |
| 8058 <field id="start_location"> | |
| 8059 <jlocation/> | |
| 8060 <description> | |
| 8061 the <datalink id="jlocation"></datalink> where the line begins | |
| 8062 </description> | |
| 8063 </field> | |
| 8064 <field id="line_number"> | |
| 8065 <jint/> | |
| 8066 <description> | |
| 8067 the line number | |
| 8068 </description> | |
| 8069 </field> | |
| 8070 </typedef> | |
| 8071 <description> | |
| 8072 For the method indicated by <code>method</code>, | |
| 8073 return a table of source line number entries. The size of the table is | |
| 8074 returned via <code>entry_count_ptr</code> and the table itself is | |
| 8075 returned via <code>table_ptr</code>. | |
| 8076 </description> | |
| 8077 <origin>jvmdi</origin> | |
| 8078 <capabilities> | |
| 8079 <required id="can_get_line_numbers"></required> | |
| 8080 </capabilities> | |
| 8081 <parameters> | |
| 8082 <param id="klass"> | |
| 8083 <jclass method="method"/> | |
| 8084 <description> | |
| 8085 The class to query. | |
| 8086 </description> | |
| 8087 </param> | |
| 8088 <param id="method"> | |
| 8089 <jmethodID class="klass" native="error"/> | |
| 8090 <description> | |
| 8091 The method to query. | |
| 8092 </description> | |
| 8093 </param> | |
| 8094 <param id="entry_count_ptr"> | |
| 8095 <outptr><jint/></outptr> | |
| 8096 <description> | |
| 8097 On return, points to the number of entries in the table | |
| 8098 </description> | |
| 8099 </param> | |
| 8100 <param id="table_ptr"> | |
| 8101 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf> | |
| 8102 <description> | |
| 8103 On return, points to the line number table pointer. | |
| 8104 </description> | |
| 8105 </param> | |
| 8106 </parameters> | |
| 8107 <errors> | |
| 8108 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 8109 Class information does not include line numbers. | |
| 8110 </error> | |
| 8111 </errors> | |
| 8112 </function> | |
| 8113 | |
| 8114 <function id="GetMethodLocation" phase="start" num="71"> | |
| 8115 <synopsis>Get Method Location</synopsis> | |
| 8116 <description> | |
| 8117 For the method indicated by <code>method</code>, | |
| 8118 return the beginning and ending addresses through | |
| 8119 <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a | |
| 8120 conventional byte code indexing scheme, | |
| 8121 <code>start_location_ptr</code> will always point to zero | |
| 8122 and <code>end_location_ptr</code> | |
| 8123 will always point to the byte code count minus one. | |
| 8124 </description> | |
| 8125 <origin>jvmdi</origin> | |
| 8126 <capabilities> | |
| 8127 </capabilities> | |
| 8128 <parameters> | |
| 8129 <param id="klass"> | |
| 8130 <jclass method="method"/> | |
| 8131 <description> | |
| 8132 The class to query. | |
| 8133 </description> | |
| 8134 </param> | |
| 8135 <param id="method"> | |
| 8136 <jmethodID class="klass" native="error"/> | |
| 8137 <description> | |
| 8138 The method to query. | |
| 8139 </description> | |
| 8140 </param> | |
| 8141 <param id="start_location_ptr"> | |
| 8142 <outptr><jlocation/></outptr> | |
| 8143 <description> | |
| 8144 On return, points to the first location, or | |
| 8145 <code>-1</code> if location information is not available. | |
| 8146 If the information is available and | |
| 8147 <functionlink id="GetJLocationFormat"></functionlink> | |
| 8148 returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink> | |
| 8149 then this will always be zero. | |
| 8150 </description> | |
| 8151 </param> | |
| 8152 <param id="end_location_ptr"> | |
| 8153 <outptr><jlocation/></outptr> | |
| 8154 <description> | |
| 8155 On return, points to the last location, | |
| 8156 or <code>-1</code> if location information is not available. | |
| 8157 </description> | |
| 8158 </param> | |
| 8159 </parameters> | |
| 8160 <errors> | |
| 8161 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 8162 Class information does not include method sizes. | |
| 8163 </error> | |
| 8164 </errors> | |
| 8165 </function> | |
| 8166 | |
| 8167 <function id="GetLocalVariableTable" num="72"> | |
| 8168 <synopsis>Get Local Variable Table</synopsis> | |
| 8169 <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry"> | |
| 8170 <field id="start_location"> | |
| 8171 <jlocation/> | |
| 8172 <description> | |
| 8173 The code array index where the local variable is first valid | |
| 8174 (that is, where it must have a value). | |
| 8175 </description> | |
| 8176 </field> | |
| 8177 <field id="length"> | |
| 8178 <jint/> | |
| 8179 <description> | |
| 8180 The length of the valid section for this local variable. | |
| 8181 The last code array index where the local variable is valid | |
| 8182 is <code>start_location + length</code>. | |
| 8183 </description> | |
| 8184 </field> | |
| 8185 <field id="name"> | |
| 8186 <allocfieldbuf><char/></allocfieldbuf> | |
| 8187 <description> | |
| 8188 The local variable name, encoded as a | |
| 8189 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8190 </description> | |
| 8191 </field> | |
| 8192 <field id="signature"> | |
| 8193 <allocfieldbuf><char/></allocfieldbuf> | |
| 8194 <description> | |
| 8195 The local variable's type signature, encoded as a | |
| 8196 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8197 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
|
8198 <vmspec chapter="4.3.2"/>. |
| 0 | 8199 </description> |
| 8200 </field> | |
| 8201 <field id="generic_signature"> | |
| 8202 <allocfieldbuf><char/></allocfieldbuf> | |
| 8203 <description> | |
| 8204 The local variable's generic signature, encoded as a | |
| 8205 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8206 The value of this field will be <code>NULL</code> for any local | |
| 8207 variable which does not have a generic type. | |
| 8208 </description> | |
| 8209 </field> | |
| 8210 <field id="slot"> | |
| 8211 <jint/> | |
| 8212 <description> | |
| 8213 The local variable's slot. See <internallink id="local">Local Variables</internallink>. | |
| 8214 </description> | |
| 8215 </field> | |
| 8216 </typedef> | |
| 8217 <description> | |
| 8218 Return local variable information. | |
| 8219 </description> | |
| 8220 <origin>jvmdiClone</origin> | |
| 8221 <capabilities> | |
| 8222 <required id="can_access_local_variables"></required> | |
| 8223 </capabilities> | |
| 8224 <parameters> | |
| 8225 <param id="method"> | |
| 8226 <jmethodID native="error"/> | |
| 8227 <description> | |
| 8228 The method to query. | |
| 8229 </description> | |
| 8230 </param> | |
| 8231 <param id="entry_count_ptr"> | |
| 8232 <outptr><jint/></outptr> | |
| 8233 <description> | |
| 8234 On return, points to the number of entries in the table | |
| 8235 </description> | |
| 8236 </param> | |
| 8237 <param id="table_ptr"> | |
| 8238 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf> | |
| 8239 <description> | |
| 8240 On return, points to an array of local variable table entries. | |
| 8241 </description> | |
| 8242 </param> | |
| 8243 </parameters> | |
| 8244 <errors> | |
| 8245 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
| 8246 Class information does not include local variable | |
| 8247 information. | |
| 8248 </error> | |
| 8249 </errors> | |
| 8250 </function> | |
| 8251 | |
| 8252 <function id="GetBytecodes" phase="start" num="75"> | |
| 8253 <synopsis>Get Bytecodes</synopsis> | |
| 8254 <description> | |
| 8255 For the method indicated by <code>method</code>, | |
| 8256 return the byte codes that implement the method. The number of | |
| 8257 bytecodes is returned via <code>bytecode_count_ptr</code>. The byte codes | |
| 8258 themselves are returned via <code>bytecodes_ptr</code>. | |
| 8259 </description> | |
| 8260 <origin>jvmdi</origin> | |
| 8261 <capabilities> | |
| 8262 <required id="can_get_bytecodes"></required> | |
| 8263 </capabilities> | |
| 8264 <parameters> | |
| 8265 <param id="klass"> | |
| 8266 <jclass method="method"/> | |
| 8267 <description> | |
| 8268 The class to query. | |
| 8269 </description> | |
| 8270 </param> | |
| 8271 <param id="method"> | |
| 8272 <jmethodID class="klass" native="error"/> | |
| 8273 <description> | |
| 8274 The method to query. | |
| 8275 </description> | |
| 8276 </param> | |
| 8277 <param id="bytecode_count_ptr"> | |
| 8278 <outptr><jint/></outptr> | |
| 8279 <description> | |
| 8280 On return, points to the length of the byte code array | |
| 8281 </description> | |
| 8282 </param> | |
| 8283 <param id="bytecodes_ptr"> | |
| 8284 <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf> | |
| 8285 <description> | |
| 8286 On return, points to the pointer to the byte code array | |
| 8287 </description> | |
| 8288 </param> | |
| 8289 </parameters> | |
| 8290 <errors> | |
| 8291 </errors> | |
| 8292 </function> | |
| 8293 | |
| 8294 <function id="IsMethodNative" phase="start" num="76"> | |
| 8295 <synopsis>Is Method Native</synopsis> | |
| 8296 <description> | |
| 8297 For the method indicated by <code>method</code>, return a | |
| 8298 value indicating whether the method is native via <code>is_native_ptr</code> | |
| 8299 </description> | |
| 8300 <origin>jvmdi</origin> | |
| 8301 <capabilities> | |
| 8302 </capabilities> | |
| 8303 <parameters> | |
| 8304 <param id="klass"> | |
| 8305 <jclass method="method"/> | |
| 8306 <description> | |
| 8307 The class to query. | |
| 8308 </description> | |
| 8309 </param> | |
| 8310 <param id="method"> | |
| 8311 <jmethodID class="klass"/> | |
| 8312 <description> | |
| 8313 The method to query. | |
| 8314 </description> | |
| 8315 </param> | |
| 8316 <param id="is_native_ptr"> | |
| 8317 <outptr><jboolean/></outptr> | |
| 8318 <description> | |
| 8319 On return, points to the boolean result of this function. | |
| 8320 </description> | |
| 8321 </param> | |
| 8322 </parameters> | |
| 8323 <errors> | |
| 8324 </errors> | |
| 8325 </function> | |
| 8326 | |
| 8327 <function id="IsMethodSynthetic" phase="start" num="77"> | |
| 8328 <synopsis>Is Method Synthetic</synopsis> | |
| 8329 <description> | |
| 8330 For the method indicated by <code>method</code>, return a | |
| 8331 value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>. | |
| 8332 Synthetic methods are generated by the compiler but not present in the | |
| 8333 original source code. | |
| 8334 </description> | |
| 8335 <origin>jvmdi</origin> | |
| 8336 <capabilities> | |
| 8337 <required id="can_get_synthetic_attribute"></required> | |
| 8338 </capabilities> | |
| 8339 <parameters> | |
| 8340 <param id="klass"> | |
| 8341 <jclass method="method"/> | |
| 8342 <description> | |
| 8343 The class to query. | |
| 8344 </description> | |
| 8345 </param> | |
| 8346 <param id="method"> | |
| 8347 <jmethodID class="klass"/> | |
| 8348 <description> | |
| 8349 The method to query. | |
| 8350 </description> | |
| 8351 </param> | |
| 8352 <param id="is_synthetic_ptr"> | |
| 8353 <outptr><jboolean/></outptr> | |
| 8354 <description> | |
| 8355 On return, points to the boolean result of this function. | |
| 8356 </description> | |
| 8357 </param> | |
| 8358 </parameters> | |
| 8359 <errors> | |
| 8360 </errors> | |
| 8361 </function> | |
| 8362 | |
| 8363 <function id="IsMethodObsolete" phase="start" num="91"> | |
| 8364 <synopsis>Is Method Obsolete</synopsis> | |
| 8365 <description> | |
| 8366 Determine if a method ID refers to an | |
| 8367 <internallink id="obsoleteMethods">obsolete</internallink> | |
| 8368 method version. | |
| 8369 </description> | |
| 8370 <origin>jvmdi</origin> | |
| 8371 <capabilities> | |
| 8372 </capabilities> | |
| 8373 <parameters> | |
| 8374 <param id="klass"> | |
| 8375 <jclass method="method"/> | |
| 8376 <description> | |
| 8377 The class to query. | |
| 8378 </description> | |
| 8379 </param> | |
| 8380 <param id="method"> | |
| 8381 <jmethodID class="klass"/> | |
| 8382 <description> | |
| 8383 The method ID to query. | |
| 8384 </description> | |
| 8385 </param> | |
| 8386 <param id="is_obsolete_ptr"> | |
| 8387 <outptr><jboolean/></outptr> | |
| 8388 <description> | |
| 8389 On return, points to the boolean result of this function. | |
| 8390 </description> | |
| 8391 </param> | |
| 8392 </parameters> | |
| 8393 <errors> | |
| 8394 </errors> | |
| 8395 </function> | |
| 8396 | |
| 8397 <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1"> | |
| 8398 <synopsis>Set Native Method Prefix</synopsis> | |
| 8399 <description> | |
| 8400 This function modifies the failure handling of | |
| 8401 native method resolution by allowing retry | |
| 8402 with a prefix applied to the name. | |
| 8403 When used with the | |
| 8404 <eventlink id="ClassFileLoadHook">ClassFileLoadHook | |
| 8405 event</eventlink>, it enables native methods to be | |
| 8406 <internallink id="bci">instrumented</internallink>. | |
| 8407 <p/> | |
| 8408 Since native methods cannot be directly instrumented | |
| 8409 (they have no bytecodes), they must be wrapped with | |
| 8410 a non-native method which can be instrumented. | |
| 8411 For example, if we had: | |
| 8412 <example> | |
| 8413 native boolean foo(int x);</example> | |
| 8414 <p/> | |
| 8415 We could transform the class file (with the | |
| 8416 ClassFileLoadHook event) so that this becomes: | |
| 8417 <example> | |
| 8418 boolean foo(int x) { | |
| 8419 <i>... record entry to foo ...</i> | |
| 8420 return wrapped_foo(x); | |
| 8421 } | |
| 8422 | |
| 8423 native boolean wrapped_foo(int x);</example> | |
| 8424 <p/> | |
| 8425 Where foo becomes a wrapper for the actual native method | |
| 8426 with the appended prefix "wrapped_". Note that | |
| 8427 "wrapped_" would be a poor choice of prefix since it | |
| 8428 might conceivably form the name of an existing method | |
| 8429 thus something like "$$$MyAgentWrapped$$$_" would be | |
| 8430 better but would make these examples less readable. | |
| 8431 <p/> | |
| 8432 The wrapper will allow data to be collected on the native | |
| 8433 method call, but now the problem becomes linking up the | |
| 8434 wrapped method with the native implementation. | |
| 8435 That is, the method <code>wrapped_foo</code> needs to be | |
| 8436 resolved to the native implementation of <code>foo</code>, | |
| 8437 which might be: | |
| 8438 <example> | |
| 8439 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example> | |
| 8440 <p/> | |
| 8441 This function allows the prefix to be specified and the | |
| 8442 proper resolution to occur. | |
| 8443 Specifically, when the standard resolution fails, the | |
| 8444 resolution is retried taking the prefix into consideration. | |
| 8445 There are two ways that resolution occurs, explicit | |
| 8446 resolution with the JNI function <code>RegisterNatives</code> | |
| 8447 and the normal automatic resolution. For | |
| 8448 <code>RegisterNatives</code>, the VM will attempt this | |
| 8449 association: | |
| 8450 <example> | |
| 8451 method(foo) -> nativeImplementation(foo)</example> | |
| 8452 <p/> | |
| 8453 When this fails, the resolution will be retried with | |
| 8454 the specified prefix prepended to the method name, | |
| 8455 yielding the correct resolution: | |
| 8456 <example> | |
| 8457 method(wrapped_foo) -> nativeImplementation(foo)</example> | |
| 8458 <p/> | |
| 8459 For automatic resolution, the VM will attempt: | |
| 8460 <example> | |
| 8461 method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example> | |
| 8462 <p/> | |
| 8463 When this fails, the resolution will be retried with | |
| 8464 the specified prefix deleted from the implementation name, | |
| 8465 yielding the correct resolution: | |
| 8466 <example> | |
| 8467 method(wrapped_foo) -> nativeImplementation(foo)</example> | |
| 8468 <p/> | |
| 8469 Note that since the prefix is only used when standard | |
| 8470 resolution fails, native methods can be wrapped selectively. | |
| 8471 <p/> | |
| 8472 Since each <jvmti/> environment is independent and | |
| 8473 can do its own transformation of the bytecodes, more | |
| 8474 than one layer of wrappers may be applied. Thus each | |
| 8475 environment needs its own prefix. Since transformations | |
| 8476 are applied in order, the prefixes, if applied, will | |
| 8477 be applied in the same order. | |
| 8478 The order of transformation application is described in | |
| 8479 the <eventlink id="ClassFileLoadHook"/> event. | |
| 8480 Thus if three environments applied | |
| 8481 wrappers, <code>foo</code> might become | |
| 8482 <code>$env3_$env2_$env1_foo</code>. But if, say, | |
| 8483 the second environment did not apply a wrapper to | |
| 8484 <code>foo</code> it would be just | |
| 8485 <code>$env3_$env1_foo</code>. To be able to | |
| 8486 efficiently determine the sequence of prefixes, | |
| 8487 an intermediate prefix is only applied if its non-native | |
| 8488 wrapper exists. Thus, in the last example, even though | |
| 8489 <code>$env1_foo</code> is not a native method, the | |
| 8490 <code>$env1_</code> prefix is applied since | |
| 8491 <code>$env1_foo</code> exists. | |
| 8492 <p/> | |
| 8493 Since the prefixes are used at resolution time | |
| 8494 and since resolution may be arbitrarily delayed, a | |
| 8495 native method prefix must remain set as long as there | |
| 8496 are corresponding prefixed native methods. | |
| 8497 </description> | |
| 8498 <origin>new</origin> | |
| 8499 <capabilities> | |
| 8500 <required id="can_set_native_method_prefix"></required> | |
| 8501 </capabilities> | |
| 8502 <parameters> | |
| 8503 <param id="prefix"> | |
| 8504 <inbuf> | |
| 8505 <char/> | |
| 8506 <nullok> | |
| 8507 any existing prefix in this environment is cancelled | |
| 8508 </nullok> | |
| 8509 </inbuf> | |
| 8510 <description> | |
| 8511 The prefix to apply, encoded as a | |
| 8512 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8513 </description> | |
| 8514 </param> | |
| 8515 </parameters> | |
| 8516 <errors> | |
| 8517 </errors> | |
| 8518 </function> | |
| 8519 | |
| 8520 <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1"> | |
| 8521 <synopsis>Set Native Method Prefixes</synopsis> | |
| 8522 <description> | |
| 8523 For a normal agent, <functionlink id="SetNativeMethodPrefix"/> | |
| 8524 will provide all needed native method prefixing. | |
| 8525 For a meta-agent that performs multiple independent class | |
| 8526 file transformations (for example as a proxy for another | |
| 8527 layer of agents) this function allows each transformation | |
| 8528 to have its own prefix. | |
| 8529 The prefixes are applied in the order supplied and are | |
| 8530 processed in the same manor as described for the | |
| 8531 application of prefixes from multiple <jvmti/> environments | |
| 8532 in <functionlink id="SetNativeMethodPrefix"/>. | |
| 8533 <p/> | |
| 8534 Any previous prefixes are replaced. Thus, calling this | |
| 8535 function with a <paramlink id="prefix_count"/> of <code>0</code> | |
| 8536 disables prefixing in this environment. | |
| 8537 <p/> | |
| 8538 <functionlink id="SetNativeMethodPrefix"/> and this function | |
| 8539 are the two ways to set the prefixes. | |
| 8540 Calling <code>SetNativeMethodPrefix</code> with | |
| 8541 a prefix is the same as calling this function with | |
| 8542 <paramlink id="prefix_count"/> of <code>1</code>. | |
| 8543 Calling <code>SetNativeMethodPrefix</code> with | |
| 8544 <code>NULL</code> is the same as calling this function with | |
| 8545 <paramlink id="prefix_count"/> of <code>0</code>. | |
| 8546 </description> | |
| 8547 <origin>new</origin> | |
| 8548 <capabilities> | |
| 8549 <required id="can_set_native_method_prefix"></required> | |
| 8550 </capabilities> | |
| 8551 <parameters> | |
| 8552 <param id="prefix_count"> | |
| 8553 <jint min="0"/> | |
| 8554 <description> | |
| 8555 The number of prefixes to apply. | |
| 8556 </description> | |
| 8557 </param> | |
| 8558 <param id="prefixes"> | |
| 8559 <agentbuf> | |
| 8560 <char/> | |
| 8561 </agentbuf> | |
| 8562 <description> | |
| 8563 The prefixes to apply for this environment, each encoded as a | |
| 8564 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8565 </description> | |
| 8566 </param> | |
| 8567 </parameters> | |
| 8568 <errors> | |
| 8569 </errors> | |
| 8570 </function> | |
| 8571 | |
| 8572 </category> | |
| 8573 | |
| 8574 <category id="RawMonitors" label="Raw Monitor"> | |
| 8575 | |
| 8576 <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31"> | |
| 8577 <synopsis>Create Raw Monitor</synopsis> | |
| 8578 <description> | |
| 8579 Create a raw monitor. | |
| 8580 </description> | |
| 8581 <origin>jvmdi</origin> | |
| 8582 <capabilities> | |
| 8583 </capabilities> | |
| 8584 <parameters> | |
| 8585 <param id="name"> | |
| 8586 <inbuf><char/></inbuf> | |
| 8587 <description> | |
| 8588 A name to identify the monitor, encoded as a | |
| 8589 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 8590 </description> | |
| 8591 </param> | |
| 8592 <param id="monitor_ptr"> | |
| 8593 <outptr><jrawMonitorID/></outptr> | |
| 8594 <description> | |
| 8595 On return, points to the created monitor. | |
| 8596 </description> | |
| 8597 </param> | |
| 8598 </parameters> | |
| 8599 <errors> | |
| 8600 </errors> | |
| 8601 </function> | |
| 8602 | |
| 8603 <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32"> | |
| 8604 <synopsis>Destroy Raw Monitor</synopsis> | |
| 8605 <description> | |
| 8606 Destroy the raw monitor. | |
| 8607 If the monitor being destroyed has been entered by this thread, it will be | |
| 8608 exited before it is destroyed. | |
| 8609 If the monitor being destroyed has been entered by another thread, | |
| 8610 an error will be returned and the monitor will not be destroyed. | |
| 8611 </description> | |
| 8612 <origin>jvmdi</origin> | |
| 8613 <capabilities> | |
| 8614 </capabilities> | |
| 8615 <parameters> | |
| 8616 <param id="monitor"> | |
| 8617 <jrawMonitorID/> | |
| 8618 <description> | |
| 8619 The monitor | |
| 8620 </description> | |
| 8621 </param> | |
| 8622 </parameters> | |
| 8623 <errors> | |
| 8624 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8625 Not monitor owner | |
| 8626 </error> | |
| 8627 </errors> | |
| 8628 </function> | |
| 8629 | |
| 8630 <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33"> | |
| 8631 <synopsis>Raw Monitor Enter</synopsis> | |
| 8632 <description> | |
| 8633 Gain exclusive ownership of a raw monitor. | |
| 8634 The same thread may enter a monitor more then once. | |
| 8635 The thread must | |
| 8636 <functionlink id="RawMonitorExit">exit</functionlink> | |
| 8637 the monitor the same number of times as it is entered. | |
| 8638 If a monitor is entered during <code>OnLoad</code> (before attached threads exist) | |
| 8639 and has not exited when attached threads come into existence, the enter | |
| 8640 is considered to have occurred on the main thread. | |
| 8641 </description> | |
| 8642 <origin>jvmdi</origin> | |
| 8643 <capabilities> | |
| 8644 </capabilities> | |
| 8645 <parameters> | |
| 8646 <param id="monitor"> | |
| 8647 <jrawMonitorID/> | |
| 8648 <description> | |
| 8649 The monitor | |
| 8650 </description> | |
| 8651 </param> | |
| 8652 </parameters> | |
| 8653 <errors> | |
| 8654 </errors> | |
| 8655 </function> | |
| 8656 | |
| 8657 <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34"> | |
| 8658 <synopsis>Raw Monitor Exit</synopsis> | |
| 8659 <description> | |
| 8660 Release exclusive ownership of a raw monitor. | |
| 8661 </description> | |
| 8662 <origin>jvmdi</origin> | |
| 8663 <capabilities> | |
| 8664 </capabilities> | |
| 8665 <parameters> | |
| 8666 <param id="monitor"> | |
| 8667 <jrawMonitorID/> | |
| 8668 <description> | |
| 8669 The monitor | |
| 8670 </description> | |
| 8671 </param> | |
| 8672 </parameters> | |
| 8673 <errors> | |
| 8674 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8675 Not monitor owner | |
| 8676 </error> | |
| 8677 </errors> | |
| 8678 </function> | |
| 8679 | |
| 8680 <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35"> | |
| 8681 <synopsis>Raw Monitor Wait</synopsis> | |
| 8682 <description> | |
| 8683 Wait for notification of the raw monitor. | |
| 8684 <p/> | |
| 8685 Causes the current thread to wait until either another thread calls | |
| 8686 <functionlink id="RawMonitorNotify"/> or | |
| 8687 <functionlink id="RawMonitorNotifyAll"/> | |
| 8688 for the specified raw monitor, or the specified | |
| 8689 <paramlink id="millis">timeout</paramlink> | |
| 8690 has elapsed. | |
| 8691 </description> | |
| 8692 <origin>jvmdi</origin> | |
| 8693 <capabilities> | |
| 8694 </capabilities> | |
| 8695 <parameters> | |
| 8696 <param id="monitor"> | |
| 8697 <jrawMonitorID/> | |
| 8698 <description> | |
| 8699 The monitor | |
| 8700 </description> | |
| 8701 </param> | |
| 8702 <param id="millis"> | |
| 8703 <jlong/> | |
| 8704 <description> | |
| 8705 The timeout, in milliseconds. If the timeout is | |
| 8706 zero, then real time is not taken into consideration | |
| 8707 and the thread simply waits until notified. | |
| 8708 </description> | |
| 8709 </param> | |
| 8710 </parameters> | |
| 8711 <errors> | |
| 8712 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8713 Not monitor owner | |
| 8714 </error> | |
| 8715 <error id="JVMTI_ERROR_INTERRUPT"> | |
| 8716 Wait was interrupted, try again | |
| 8717 </error> | |
| 8718 </errors> | |
| 8719 </function> | |
| 8720 | |
| 8721 <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36"> | |
| 8722 <synopsis>Raw Monitor Notify</synopsis> | |
| 8723 <description> | |
| 8724 Notify a single thread waiting on the raw monitor. | |
| 8725 </description> | |
| 8726 <origin>jvmdi</origin> | |
| 8727 <capabilities> | |
| 8728 </capabilities> | |
| 8729 <parameters> | |
| 8730 <param id="monitor"> | |
| 8731 <jrawMonitorID/> | |
| 8732 <description> | |
| 8733 The monitor | |
| 8734 </description> | |
| 8735 </param> | |
| 8736 </parameters> | |
| 8737 <errors> | |
| 8738 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8739 Not monitor owner | |
| 8740 </error> | |
| 8741 </errors> | |
| 8742 </function> | |
| 8743 | |
| 8744 <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37"> | |
| 8745 <synopsis>Raw Monitor Notify All</synopsis> | |
| 8746 <description> | |
| 8747 Notify all threads waiting on the raw monitor. | |
| 8748 </description> | |
| 8749 <origin>jvmdi</origin> | |
| 8750 <capabilities> | |
| 8751 </capabilities> | |
| 8752 <parameters> | |
| 8753 <param id="monitor"> | |
| 8754 <jrawMonitorID/> | |
| 8755 <description> | |
| 8756 The monitor | |
| 8757 </description> | |
| 8758 </param> | |
| 8759 </parameters> | |
| 8760 <errors> | |
| 8761 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
| 8762 Not monitor owner | |
| 8763 </error> | |
| 8764 </errors> | |
| 8765 </function> | |
| 8766 | |
| 8767 <elide> | |
| 8768 <function id="GetRawMonitorUse" num="118"> | |
| 8769 <synopsis>Get Raw Monitor Use</synopsis> | |
| 8770 <description> | |
| 8771 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure | |
| 8772 are filled in with information about usage of the raw monitor. | |
| 8773 </description> | |
| 8774 <origin>new</origin> | |
| 8775 <capabilities> | |
| 8776 <required id="can_get_raw_monitor_usage"></required> | |
| 8777 </capabilities> | |
| 8778 <parameters> | |
| 8779 <param id="monitor"> | |
| 8780 <jrawMonitorID/> | |
| 8781 <description> | |
| 8782 the raw monitor to query. | |
| 8783 </description> | |
| 8784 </param> | |
| 8785 <param id="info_ptr"> | |
| 8786 <outptr><struct>jvmtiMonitorUsage</struct></outptr> | |
| 8787 <description> | |
| 8788 On return, filled with monitor information for the | |
| 8789 specified raw monitor. | |
| 8790 </description> | |
| 8791 </param> | |
| 8792 </parameters> | |
| 8793 <errors> | |
| 8794 </errors> | |
| 8795 </function> | |
| 8796 | |
| 8797 <function id="GetRawMonitors" num="119"> | |
| 8798 <synopsis>Get Raw Monitors</synopsis> | |
| 8799 <description> | |
| 8800 Return the list of raw monitors. | |
| 8801 <p/> | |
| 8802 Note: details about each monitor can be examined with | |
| 8803 <functionlink id="GetRawMonitorUse"></functionlink>. | |
| 8804 </description> | |
| 8805 <origin>new</origin> | |
| 8806 <capabilities> | |
| 8807 <required id="can_get_raw_monitor_usage"></required> | |
| 8808 </capabilities> | |
| 8809 <parameters> | |
| 8810 <param id="monitorCnt"> | |
| 8811 <outptr><jint/></outptr> | |
| 8812 <description> | |
| 8813 On return, pointer to the number | |
| 8814 of monitors returned in <code>monitors_ptr</code>. | |
| 8815 </description> | |
| 8816 </param> | |
| 8817 <param id="monitors_ptr"> | |
| 8818 <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf> | |
| 8819 <description> | |
| 8820 On return, pointer to the monitor list. | |
| 8821 </description> | |
| 8822 </param> | |
| 8823 </parameters> | |
| 8824 <errors> | |
| 8825 </errors> | |
| 8826 </function> | |
| 8827 </elide> | |
| 8828 </category> | |
| 8829 | |
| 8830 <category id="jniIntercept" label="JNI Function Interception"> | |
| 8831 | |
| 8832 <intro> | |
| 8833 Provides the ability to intercept and resend | |
| 8834 Java Native Interface (JNI) function calls | |
| 8835 by manipulating the JNI function table. | |
| 6919 | 8836 See <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html">JNI |
| 0 | 8837 Functions</externallink> in the <i>Java Native Interface Specification</i>. |
| 8838 <p/> | |
| 8839 The following example illustrates intercepting the | |
| 8840 <code>NewGlobalRef</code> JNI call in order to count reference | |
| 8841 creation. | |
| 8842 <example> | |
| 8843 JNIEnv original_jni_Functions; | |
| 8844 JNIEnv redirected_jni_Functions; | |
| 8845 int my_global_ref_count = 0; | |
| 8846 | |
| 8847 jobject | |
| 8848 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) { | |
| 8849 ++my_global_ref_count; | |
| 8850 return originalJNIFunctions->NewGlobalRef(env, lobj); | |
| 8851 } | |
| 8852 | |
| 8853 void | |
| 8854 myInit() { | |
| 8855 jvmtiError err; | |
| 8856 | |
| 8857 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &original_jni_Functions); | |
| 8858 if (err != JVMTI_ERROR_NONE) { | |
| 8859 die(); | |
| 8860 } | |
| 8861 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &redirected_jni_Functions); | |
| 8862 if (err != JVMTI_ERROR_NONE) { | |
| 8863 die(); | |
| 8864 } | |
| 8865 redirectedJNIFunctions->NewGlobalRef = MyNewGlobalRef; | |
| 8866 err = (*jvmti_env)->SetJNIFunctionTable(jvmti_env, redirected_jni_Functions); | |
| 8867 if (err != JVMTI_ERROR_NONE) { | |
| 8868 die(); | |
| 8869 } | |
| 8870 } | |
| 8871 </example> | |
| 8872 Sometime after <code>myInit</code> is called the user's JNI | |
| 8873 code is executed which makes the call to create a new global | |
| 8874 reference. Instead of going to the normal JNI implementation | |
| 8875 the call goes to <code>myNewGlobalRef</code>. Note that a | |
| 8876 copy of the original function table is kept so that the normal | |
| 8877 JNI function can be called after the data is collected. | |
| 8878 Note also that any JNI functions which are not overwritten | |
| 8879 will behave normally. | |
| 8880 <todo> | |
| 8881 check that the example compiles and executes. | |
| 8882 </todo> | |
| 8883 </intro> | |
| 8884 | |
| 8885 <function id="SetJNIFunctionTable" phase="start" num="120"> | |
| 8886 <synopsis>Set JNI Function Table</synopsis> | |
| 8887 <description> | |
| 8888 Set the JNI function table | |
| 8889 in all current and future JNI environments. | |
| 8890 As a result, all future JNI calls are directed to the specified functions. | |
| 8891 Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the | |
| 8892 function table to pass to this function. | |
| 8893 For this function to take effect the the updated table entries must be | |
| 8894 used by the JNI clients. | |
| 8895 Since the table is defined <code>const</code> some compilers may optimize | |
| 8896 away the access to the table, thus preventing this function from taking | |
| 8897 effect. | |
| 8898 The table is copied--changes to the local copy of the | |
| 8899 table have no effect. | |
| 8900 This function affects only the function table, all other aspects of the environment are | |
| 8901 unaffected. | |
| 8902 See the examples <internallink id="jniIntercept">above</internallink>. | |
| 8903 </description> | |
| 8904 <origin>new</origin> | |
| 8905 <capabilities> | |
| 8906 </capabilities> | |
| 8907 <parameters> | |
| 8908 <param id="function_table"> | |
| 8909 <inptr> | |
| 8910 <struct>jniNativeInterface</struct> | |
| 8911 </inptr> | |
| 8912 <description> | |
| 8913 Points to the new JNI function table. | |
| 8914 </description> | |
| 8915 </param> | |
| 8916 </parameters> | |
| 8917 <errors> | |
| 8918 </errors> | |
| 8919 </function> | |
| 8920 | |
| 8921 <function id="GetJNIFunctionTable" phase="start" num="121"> | |
| 8922 <synopsis>Get JNI Function Table</synopsis> | |
| 8923 <description> | |
| 8924 Get the JNI function table. | |
| 8925 The JNI function table is copied into allocated memory. | |
| 8926 If <functionlink id="SetJNIFunctionTable"></functionlink> | |
| 8927 has been called, the modified (not the original) function | |
| 8928 table is returned. | |
| 8929 Only the function table is copied, no other aspects of the environment | |
| 8930 are copied. | |
| 8931 See the examples <internallink id="jniIntercept">above</internallink>. | |
| 8932 </description> | |
| 8933 <origin>new</origin> | |
| 8934 <capabilities> | |
| 8935 </capabilities> | |
| 8936 <parameters> | |
| 8937 <param id="function_table"> | |
| 8938 <allocbuf> | |
| 8939 <struct>jniNativeInterface</struct> | |
| 8940 </allocbuf> | |
| 8941 <description> | |
| 8942 On return, <code>*function_table</code> | |
| 8943 points a newly allocated copy of the JNI function table. | |
| 8944 </description> | |
| 8945 </param> | |
| 8946 </parameters> | |
| 8947 <errors> | |
| 8948 </errors> | |
| 8949 </function> | |
| 8950 | |
| 8951 </category> | |
| 8952 | |
| 8953 <category id="eventManagement" label="Event Management"> | |
| 8954 | |
| 8955 <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122"> | |
| 8956 <synopsis>Set Event Callbacks</synopsis> | |
| 8957 <description> | |
| 8958 Set the functions to be called for each event. | |
| 8959 The callbacks are specified by supplying a replacement function table. | |
| 8960 The function table is copied--changes to the local copy of the | |
| 8961 table have no effect. | |
| 8962 This is an atomic action, all callbacks are set at once. | |
| 8963 No events are sent before this function is called. | |
| 8964 When an entry is <code>NULL</code> or when the event is beyond | |
| 8965 <paramlink id="size_of_callbacks"></paramlink> no event is sent. | |
| 8966 Details on events are | |
| 8967 described <internallink id="EventSection">later</internallink> in this document. | |
| 8968 An event must be enabled and have a callback in order to be | |
| 8969 sent--the order in which this function and | |
| 8970 <functionlink id="SetEventNotificationMode"></functionlink> | |
| 8971 are called does not affect the result. | |
| 8972 </description> | |
| 8973 <origin>new</origin> | |
| 8974 <capabilities> | |
| 8975 </capabilities> | |
| 8976 <parameters> | |
| 8977 <param id="callbacks"> | |
| 8978 <inptr> | |
| 8979 <struct>jvmtiEventCallbacks</struct> | |
| 8980 <nullok>remove the existing callbacks</nullok> | |
| 8981 </inptr> | |
| 8982 <description> | |
| 8983 The new event callbacks. | |
| 8984 </description> | |
| 8985 </param> | |
| 8986 <param id="size_of_callbacks"> | |
| 8987 <jint min="0"/> | |
| 8988 <description> | |
| 8989 <code>sizeof(jvmtiEventCallbacks)</code>--for version | |
| 8990 compatibility. | |
| 8991 </description> | |
| 8992 </param> | |
| 8993 </parameters> | |
| 8994 <errors> | |
| 8995 </errors> | |
| 8996 </function> | |
| 8997 | |
| 8998 <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2"> | |
| 8999 <synopsis>Set Event Notification Mode</synopsis> | |
| 9000 <description> | |
| 9001 Control the generation of events. | |
| 9002 <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum"> | |
| 9003 <constant id="JVMTI_ENABLE" num="1"> | |
| 9004 If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>, | |
| 9005 the event <paramlink id="event_type"></paramlink> will be enabled | |
| 9006 </constant> | |
| 9007 <constant id="JVMTI_DISABLE" num="0"> | |
| 9008 If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>, | |
| 9009 the event <paramlink id="event_type"></paramlink> will be disabled | |
| 9010 </constant> | |
| 9011 </constants> | |
| 9012 If <code>thread</code> is <code>NULL</code>, | |
| 9013 the event is enabled or disabled globally; otherwise, it is | |
| 9014 enabled or disabled for a particular thread. | |
| 9015 An event is generated for | |
| 9016 a particular thread if it is enabled either at the thread or global | |
| 9017 levels. | |
| 9018 <p/> | |
| 9019 See <internallink id="EventIndex">below</internallink> for information on specific events. | |
| 9020 <p/> | |
| 9021 The following events cannot be controlled at the thread | |
| 9022 level through this function. | |
| 9023 <ul> | |
| 9024 <li><eventlink id="VMInit"></eventlink></li> | |
| 9025 <li><eventlink id="VMStart"></eventlink></li> | |
| 9026 <li><eventlink id="VMDeath"></eventlink></li> | |
| 9027 <li><eventlink id="ThreadStart"></eventlink></li> | |
| 9028 <li><eventlink id="CompiledMethodLoad"></eventlink></li> | |
| 9029 <li><eventlink id="CompiledMethodUnload"></eventlink></li> | |
| 9030 <li><eventlink id="DynamicCodeGenerated"></eventlink></li> | |
| 9031 <li><eventlink id="DataDumpRequest"></eventlink></li> | |
| 9032 </ul> | |
| 9033 <p/> | |
| 9034 Initially, no events are enabled at either the thread level | |
| 9035 or the global level. | |
| 9036 <p/> | |
| 9037 Any needed capabilities (see Event Enabling Capabilities below) must be possessed | |
| 9038 before calling this function. | |
| 9039 <p/> | |
| 9040 Details on events are | |
| 9041 described <internallink id="EventSection">below</internallink>. | |
| 9042 </description> | |
| 9043 <origin>jvmdiClone</origin> | |
| 9044 <eventcapabilities></eventcapabilities> | |
| 9045 <parameters> | |
| 9046 <param id="mode"> | |
| 9047 <enum>jvmtiEventMode</enum> | |
| 9048 <description> | |
| 9049 <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code> | |
| 9050 </description> | |
| 9051 </param> | |
| 9052 <param id="event_type"> | |
| 9053 <enum>jvmtiEvent</enum> | |
| 9054 <description> | |
| 9055 the event to control | |
| 9056 </description> | |
| 9057 </param> | |
| 9058 <param id="event_thread"> | |
| 9059 <ptrtype> | |
| 9060 <jthread impl="noconvert"/> | |
| 9061 <nullok>event is controlled at the global level</nullok> | |
| 9062 </ptrtype> | |
| 9063 <description> | |
| 9064 The thread to control | |
| 9065 </description> | |
| 9066 </param> | |
| 9067 <param id="..."> | |
| 9068 <varargs/> | |
| 9069 <description> | |
| 9070 for future expansion | |
| 9071 </description> | |
| 9072 </param> | |
| 9073 </parameters> | |
| 9074 <errors> | |
| 9075 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
| 9076 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread. | |
| 9077 </error> | |
| 9078 <error id="JVMTI_ERROR_THREAD_NOT_ALIVE"> | |
| 9079 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead). | |
| 9080 </error> | |
| 9081 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 9082 thread level control was attempted on events which do not | |
| 9083 permit thread level control. | |
| 9084 </error> | |
| 9085 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> | |
| 9086 The Required Event Enabling Capability is not possessed. | |
| 9087 </error> | |
| 9088 </errors> | |
| 9089 </function> | |
| 9090 | |
| 9091 <function id="GenerateEvents" num="123"> | |
| 9092 <synopsis>Generate Events</synopsis> | |
| 9093 <description> | |
| 9094 Generate events to represent the current state of the VM. | |
| 9095 For example, if <paramlink id="event_type"/> is | |
| 9096 <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>, | |
| 9097 a <eventlink id="CompiledMethodLoad"></eventlink> event will be | |
| 9098 sent for each currently compiled method. | |
| 9099 Methods that were loaded and now have been unloaded are not sent. | |
| 9100 The history of what events have previously been sent does not | |
| 9101 effect what events are sent by this function--for example, | |
| 9102 all currently compiled methods | |
| 9103 will be sent each time this function is called. | |
| 9104 <p/> | |
| 9105 This function is useful when | |
| 9106 events may have been missed due to the agent attaching after program | |
| 9107 execution begins; this function generates the missed events. | |
| 9108 <p/> | |
| 9109 Attempts to execute Java programming language code or | |
| 9110 JNI functions may be paused until this function returns - | |
| 9111 so neither should be called from the thread sending the event. | |
| 9112 This function returns only after the missed events have been | |
| 9113 sent, processed and have returned. | |
| 9114 The event may be sent on a different thread than the thread | |
| 9115 on which the event occurred. | |
| 9116 The callback for the event must be set with | |
| 9117 <functionlink id="SetEventCallbacks"></functionlink> | |
| 9118 and the event must be enabled with | |
| 9119 <functionlink id="SetEventNotificationMode"></functionlink> | |
| 9120 or the events will not occur. | |
| 9121 If the VM no longer has the information to generate some or | |
| 9122 all of the requested events, the events are simply not sent - | |
| 9123 no error is returned. | |
| 9124 <p/> | |
| 9125 Only the following events are supported: | |
| 9126 <ul> | |
| 9127 <li><eventlink id="CompiledMethodLoad"></eventlink></li> | |
| 9128 <li><eventlink id="DynamicCodeGenerated"></eventlink></li> | |
| 9129 </ul> | |
| 9130 </description> | |
| 9131 <origin>new</origin> | |
| 9132 <capabilities> | |
| 9133 <capability id="can_generate_compiled_method_load_events"></capability> | |
| 9134 </capabilities> | |
| 9135 <parameters> | |
| 9136 <param id="event_type"> | |
| 9137 <enum>jvmtiEvent</enum> | |
| 9138 <description> | |
| 9139 The type of event to generate. Must be one of these: | |
| 9140 <ul> | |
| 9141 <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li> | |
| 9142 <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li> | |
| 9143 </ul> | |
| 9144 </description> | |
| 9145 </param> | |
| 9146 </parameters> | |
| 9147 <errors> | |
| 9148 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> | |
| 9149 <paramlink id="event_type"/> is | |
| 9150 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> | |
| 9151 and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink> | |
| 9152 is <code>false</code>. | |
| 9153 </error> | |
| 9154 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 9155 <paramlink id="event_type"/> is other than | |
| 9156 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> | |
| 9157 or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>. | |
| 9158 </error> | |
| 9159 </errors> | |
| 9160 </function> | |
| 9161 | |
| 9162 </category> | |
| 9163 | |
| 9164 <category id="extension" label="Extension Mechanism"> | |
| 9165 | |
| 9166 <intro> | |
| 9167 These functions | |
| 9168 allow a <jvmti/> implementation to provide functions and events | |
| 9169 beyond those defined in this specification. | |
| 9170 <p/> | |
| 9171 Both extension functions and extension events have parameters | |
| 9172 each of which has a 'type' and 'kind' chosen from the following tables: | |
| 9173 | |
| 9174 <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum"> | |
| 9175 <constant id="JVMTI_TYPE_JBYTE" num="101"> | |
| 9176 Java programming language primitive type - <code>byte</code>. | |
| 9177 JNI type <code>jbyte</code>. | |
| 9178 </constant> | |
| 9179 <constant id="JVMTI_TYPE_JCHAR" num="102"> | |
| 9180 Java programming language primitive type - <code>char</code>. | |
| 9181 JNI type <code>jchar</code>. | |
| 9182 </constant> | |
| 9183 <constant id="JVMTI_TYPE_JSHORT" num="103"> | |
| 9184 Java programming language primitive type - <code>short</code>. | |
| 9185 JNI type <code>jshort</code>. | |
| 9186 </constant> | |
| 9187 <constant id="JVMTI_TYPE_JINT" num="104"> | |
| 9188 Java programming language primitive type - <code>int</code>. | |
| 9189 JNI type <datalink id="jint"></datalink>. | |
| 9190 </constant> | |
| 9191 <constant id="JVMTI_TYPE_JLONG" num="105"> | |
| 9192 Java programming language primitive type - <code>long</code>. | |
| 9193 JNI type <datalink id="jlong"></datalink>. | |
| 9194 </constant> | |
| 9195 <constant id="JVMTI_TYPE_JFLOAT" num="106"> | |
| 9196 Java programming language primitive type - <code>float</code>. | |
| 9197 JNI type <datalink id="jfloat"></datalink>. | |
| 9198 </constant> | |
| 9199 <constant id="JVMTI_TYPE_JDOUBLE" num="107"> | |
| 9200 Java programming language primitive type - <code>double</code>. | |
| 9201 JNI type <datalink id="jdouble"></datalink>. | |
| 9202 </constant> | |
| 9203 <constant id="JVMTI_TYPE_JBOOLEAN" num="108"> | |
| 9204 Java programming language primitive type - <code>boolean</code>. | |
| 9205 JNI type <datalink id="jboolean"></datalink>. | |
| 9206 </constant> | |
| 9207 <constant id="JVMTI_TYPE_JOBJECT" num="109"> | |
| 9208 Java programming language object type - <code>java.lang.Object</code>. | |
| 9209 JNI type <datalink id="jobject"></datalink>. | |
| 9210 Returned values are JNI local references and must be managed. | |
| 9211 </constant> | |
| 9212 <constant id="JVMTI_TYPE_JTHREAD" num="110"> | |
| 9213 Java programming language object type - <code>java.lang.Thread</code>. | |
| 9214 <jvmti/> type <datalink id="jthread"></datalink>. | |
| 9215 Returned values are JNI local references and must be managed. | |
| 9216 </constant> | |
| 9217 <constant id="JVMTI_TYPE_JCLASS" num="111"> | |
| 9218 Java programming language object type - <code>java.lang.Class</code>. | |
| 9219 JNI type <datalink id="jclass"></datalink>. | |
| 9220 Returned values are JNI local references and must be managed. | |
| 9221 </constant> | |
| 9222 <constant id="JVMTI_TYPE_JVALUE" num="112"> | |
| 9223 Union of all Java programming language primitive and object types - | |
| 9224 JNI type <datalink id="jvalue"></datalink>. | |
| 9225 Returned values which represent object types are JNI local references and must be managed. | |
| 9226 </constant> | |
| 9227 <constant id="JVMTI_TYPE_JFIELDID" num="113"> | |
| 9228 Java programming language field identifier - | |
| 9229 JNI type <datalink id="jfieldID"></datalink>. | |
| 9230 </constant> | |
| 9231 <constant id="JVMTI_TYPE_JMETHODID" num="114"> | |
| 9232 Java programming language method identifier - | |
| 9233 JNI type <datalink id="jmethodID"></datalink>. | |
| 9234 </constant> | |
| 9235 <constant id="JVMTI_TYPE_CCHAR" num="115"> | |
| 9236 C programming language type - <code>char</code>. | |
| 9237 </constant> | |
| 9238 <constant id="JVMTI_TYPE_CVOID" num="116"> | |
| 9239 C programming language type - <code>void</code>. | |
| 9240 </constant> | |
| 9241 <constant id="JVMTI_TYPE_JNIENV" num="117"> | |
| 9242 JNI environment - <code>JNIEnv</code>. | |
| 9243 Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type. | |
| 9244 </constant> | |
| 9245 </constants> | |
| 9246 | |
| 9247 <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum"> | |
| 9248 <constant id="JVMTI_KIND_IN" num="91"> | |
| 9249 Ingoing argument - <code>foo</code>. | |
| 9250 </constant> | |
| 9251 <constant id="JVMTI_KIND_IN_PTR" num="92"> | |
| 9252 Ingoing pointer argument - <code>const foo*</code>. | |
| 9253 </constant> | |
| 9254 <constant id="JVMTI_KIND_IN_BUF" num="93"> | |
| 9255 Ingoing array argument - <code>const foo*</code>. | |
| 9256 </constant> | |
| 9257 <constant id="JVMTI_KIND_ALLOC_BUF" num="94"> | |
| 9258 Outgoing allocated array argument - <code>foo**</code>. | |
| 9259 Free with <code>Deallocate</code>. | |
| 9260 </constant> | |
| 9261 <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95"> | |
| 9262 Outgoing allocated array of allocated arrays argument - <code>foo***</code>. | |
| 9263 Free with <code>Deallocate</code>. | |
| 9264 </constant> | |
| 9265 <constant id="JVMTI_KIND_OUT" num="96"> | |
| 9266 Outgoing argument - <code>foo*</code>. | |
| 9267 </constant> | |
| 9268 <constant id="JVMTI_KIND_OUT_BUF" num="97"> | |
| 9269 Outgoing array argument (pre-allocated by agent) - <code>foo*</code>. | |
| 9270 Do not <code>Deallocate</code>. | |
| 9271 </constant> | |
| 9272 </constants> | |
| 9273 | |
| 9274 </intro> | |
| 9275 | |
| 9276 <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info"> | |
| 9277 <field id="name"> | |
| 9278 <allocfieldbuf><char/></allocfieldbuf> | |
| 9279 <description> | |
| 9280 The parameter name, encoded as a | |
| 9281 <internallink id="mUTF">modified UTF-8</internallink> string | |
| 9282 </description> | |
| 9283 </field> | |
| 9284 <field id="kind"> | |
| 9285 <enum>jvmtiParamKind</enum> | |
| 9286 <description> | |
| 9287 The kind of the parameter - type modifiers | |
| 9288 </description> | |
| 9289 </field> | |
| 9290 <field id="base_type"> | |
| 9291 <enum>jvmtiParamTypes</enum> | |
| 9292 <description> | |
| 9293 The base type of the parameter - modified by <code>kind</code> | |
| 9294 </description> | |
| 9295 </field> | |
| 9296 <field id="null_ok"> | |
| 9297 <jboolean/> | |
| 9298 <description> | |
| 9299 Is a <code>NULL</code> argument permitted? Applies only to pointer and object types. | |
| 9300 </description> | |
| 9301 </field> | |
| 9302 </typedef> | |
| 9303 | |
| 9304 <callback id="jvmtiExtensionFunction"> | |
| 9305 <enum>jvmtiError</enum> | |
| 9306 <synopsis>Extension Function</synopsis> | |
| 9307 <description> | |
| 9308 This is the implementation-specific extension function. | |
| 9309 </description> | |
| 9310 <parameters> | |
| 9311 <param id="jvmti_env"> | |
| 9312 <outptr> | |
| 9313 <struct>jvmtiEnv</struct> | |
| 9314 </outptr> | |
| 9315 <description> | |
| 9316 The <jvmti/> environment is the only fixed parameter for extension functions. | |
| 9317 </description> | |
| 9318 </param> | |
| 9319 <param id="..."> | |
| 9320 <varargs/> | |
| 9321 <description> | |
| 9322 The extension function-specific parameters | |
| 9323 </description> | |
| 9324 </param> | |
| 9325 </parameters> | |
| 9326 </callback> | |
| 9327 | |
| 9328 <function id="GetExtensionFunctions" phase="onload" num="124"> | |
| 9329 <synopsis>Get Extension Functions</synopsis> | |
| 9330 | |
| 9331 <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info"> | |
| 9332 <field id="func"> | |
| 9333 <ptrtype> | |
| 9334 <struct>jvmtiExtensionFunction</struct> | |
| 9335 </ptrtype> | |
| 9336 <description> | |
| 9337 The actual function to call | |
| 9338 </description> | |
| 9339 </field> | |
| 9340 <field id="id"> | |
| 9341 <allocfieldbuf><char/></allocfieldbuf> | |
| 9342 <description> | |
| 9343 The identifier for the extension function, encoded as a | |
| 9344 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9345 Uses package name conventions. | |
| 9346 For example, <code>com.sun.hotspot.bar</code> | |
| 9347 </description> | |
| 9348 </field> | |
| 9349 <field id="short_description"> | |
| 9350 <allocfieldbuf><char/></allocfieldbuf> | |
| 9351 <description> | |
| 9352 A one sentence description of the function, encoded as a | |
| 9353 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9354 </description> | |
| 9355 </field> | |
| 9356 <field id="param_count"> | |
| 9357 <jint/> | |
| 9358 <description> | |
| 9359 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code> | |
| 9360 </description> | |
| 9361 </field> | |
| 9362 <field id="params"> | |
| 9363 <allocfieldbuf outcount="param_count"> | |
| 9364 <struct>jvmtiParamInfo</struct> | |
| 9365 </allocfieldbuf> | |
| 9366 <description> | |
| 9367 Array of | |
| 9368 <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> | |
| 9369 parameters (<code>jvmtiEnv *jvmti_env</code> excluded) | |
| 9370 </description> | |
| 9371 </field> | |
| 9372 <field id="error_count"> | |
| 9373 <jint/> | |
| 9374 <description> | |
| 9375 The number of possible error returns (excluding universal errors) | |
| 9376 </description> | |
| 9377 </field> | |
| 9378 <field id="errors"> | |
| 9379 <allocfieldbuf outcount="error_count"> | |
| 9380 <enum>jvmtiError</enum> | |
| 9381 </allocfieldbuf> | |
| 9382 <description> | |
| 9383 Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> | |
| 9384 possible errors | |
| 9385 </description> | |
| 9386 </field> | |
| 9387 </typedef> | |
| 9388 | |
| 9389 <description> | |
| 9390 Returns the set of extension functions. | |
| 9391 </description> | |
| 9392 <origin>new</origin> | |
| 9393 <capabilities> | |
| 9394 </capabilities> | |
| 9395 <parameters> | |
| 9396 <param id="extension_count_ptr"> | |
| 9397 <outptr><jint/></outptr> | |
| 9398 <description> | |
| 9399 On return, points to the number of extension functions | |
| 9400 </description> | |
| 9401 </param> | |
| 9402 <param id="extensions"> | |
| 9403 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf> | |
| 9404 <description> | |
| 9405 Returns an array of extension function info, one per function | |
| 9406 </description> | |
| 9407 </param> | |
| 9408 </parameters> | |
| 9409 <errors> | |
| 9410 </errors> | |
| 9411 </function> | |
| 9412 | |
| 9413 <function id="GetExtensionEvents" phase="onload" num="125"> | |
| 9414 <synopsis>Get Extension Events</synopsis> | |
| 9415 | |
| 9416 <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info"> | |
| 9417 <field id="extension_event_index"> | |
| 9418 <jint/> | |
| 9419 <description> | |
| 9420 The identifying index of the event | |
| 9421 </description> | |
| 9422 </field> | |
| 9423 <field id="id"> | |
| 9424 <allocfieldbuf><char/></allocfieldbuf> | |
| 9425 <description> | |
| 9426 The identifier for the extension event, encoded as a | |
| 9427 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9428 Uses package name conventions. | |
| 9429 For example, <code>com.sun.hotspot.bar</code> | |
| 9430 </description> | |
| 9431 </field> | |
| 9432 <field id="short_description"> | |
| 9433 <allocfieldbuf><char/></allocfieldbuf> | |
| 9434 <description> | |
| 9435 A one sentence description of the event, encoded as a | |
| 9436 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 9437 </description> | |
| 9438 </field> | |
| 9439 <field id="param_count"> | |
| 9440 <jint/> | |
| 9441 <description> | |
| 9442 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code> | |
| 9443 </description> | |
| 9444 </field> | |
| 9445 <field id="params"> | |
| 9446 <allocfieldbuf outcount="param_count"> | |
| 9447 <struct>jvmtiParamInfo</struct> | |
| 9448 </allocfieldbuf> | |
| 9449 <description> | |
| 9450 Array of | |
| 9451 <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink> | |
| 9452 parameters (<code>jvmtiEnv *jvmti_env</code> excluded) | |
| 9453 </description> | |
| 9454 </field> | |
| 9455 </typedef> | |
| 9456 | |
| 9457 <description> | |
| 9458 Returns the set of extension events. | |
| 9459 </description> | |
| 9460 <origin>new</origin> | |
| 9461 <capabilities> | |
| 9462 </capabilities> | |
| 9463 <parameters> | |
| 9464 <param id="extension_count_ptr"> | |
| 9465 <outptr><jint/></outptr> | |
| 9466 <description> | |
| 9467 On return, points to the number of extension events | |
| 9468 </description> | |
| 9469 </param> | |
| 9470 <param id="extensions"> | |
| 9471 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf> | |
| 9472 <description> | |
| 9473 Returns an array of extension event info, one per event | |
| 9474 </description> | |
| 9475 </param> | |
| 9476 </parameters> | |
| 9477 <errors> | |
| 9478 </errors> | |
| 9479 </function> | |
| 9480 | |
| 9481 <callback id="jvmtiExtensionEvent"> | |
| 9482 <void/> | |
| 9483 <synopsis>Extension Event</synopsis> | |
| 9484 <description> | |
| 9485 This is the implementation-specific event. | |
| 9486 The event handler is set with | |
| 9487 <functionlink id="SetExtensionEventCallback"/>. | |
| 9488 <p/> | |
| 9489 Event handlers for extension events must be declared varargs to match this definition. | |
| 9490 Failure to do so could result in calling convention mismatch and undefined behavior | |
| 9491 on some platforms. | |
| 9492 <p/> | |
| 9493 For example, if the <code>jvmtiParamInfo</code> | |
| 9494 returned by <functionlink id="GetExtensionEvents"/> indicates that | |
| 9495 there is a <code>jint</code> parameter, the event handler should be | |
| 9496 declared: | |
| 9497 <example> | |
| 9498 void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...) | |
| 9499 </example> | |
| 9500 Note the terminal "<code>...</code>" which indicates varargs. | |
| 9501 </description> | |
| 9502 <parameters> | |
| 9503 <param id="jvmti_env"> | |
| 9504 <outptr> | |
| 9505 <struct>jvmtiEnv</struct> | |
| 9506 </outptr> | |
| 9507 <description> | |
| 9508 The <jvmti/> environment is the only fixed parameter for extension events. | |
| 9509 </description> | |
| 9510 </param> | |
| 9511 <param id="..."> | |
| 9512 <varargs/> | |
| 9513 <description> | |
| 9514 The extension event-specific parameters | |
| 9515 </description> | |
| 9516 </param> | |
| 9517 </parameters> | |
| 9518 </callback> | |
| 9519 | |
| 9520 <function id="SetExtensionEventCallback" phase="onload" num="126"> | |
| 9521 <synopsis>Set Extension Event Callback</synopsis> | |
| 9522 | |
| 9523 <description> | |
| 9524 Sets the callback function for an extension event and | |
| 9525 enables the event. Or, if the callback is <code>NULL</code>, disables | |
| 9526 the event. Note that unlike standard events, setting | |
| 9527 the callback and enabling the event are a single operation. | |
| 9528 </description> | |
| 9529 <origin>new</origin> | |
| 9530 <capabilities> | |
| 9531 </capabilities> | |
| 9532 <parameters> | |
| 9533 <param id="extension_event_index"> | |
| 9534 <jint/> | |
| 9535 <description> | |
| 9536 Identifies which callback to set. | |
| 9537 This index is the | |
| 9538 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink> | |
| 9539 field of | |
| 9540 <datalink id="jvmtiExtensionEventInfo"/>. | |
| 9541 </description> | |
| 9542 </param> | |
| 9543 <param id="callback"> | |
| 9544 <ptrtype> | |
| 9545 <struct>jvmtiExtensionEvent</struct> | |
| 9546 <nullok>disable the event</nullok> | |
| 9547 </ptrtype> | |
| 9548 <description> | |
| 9549 If <code>callback</code> is non-<code>NULL</code>, | |
| 9550 set <code>callback</code> to be the event callback function | |
| 9551 and enable the event. | |
| 9552 </description> | |
| 9553 </param> | |
| 9554 </parameters> | |
| 9555 <errors> | |
| 9556 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 9557 <paramlink id="extension_event_index"/> is not an | |
| 9558 <fieldlink id="extension_event_index" | |
| 9559 struct="jvmtiExtensionEventInfo"/> | |
| 9560 returned by | |
| 9561 <functionlink id="GetExtensionEvents"/> | |
| 9562 </error> | |
| 9563 </errors> | |
| 9564 </function> | |
| 9565 | |
| 9566 </category> | |
| 9567 | |
| 9568 <category id="capability" label="Capability"> | |
| 9569 | |
| 9570 <intro> | |
| 9571 The capabilities functions allow you to change the | |
| 9572 functionality available to <jvmti/>--that is, | |
| 9573 which <jvmti/> | |
| 9574 functions can be called, what events can be generated, | |
| 9575 and what functionality these events and functions can | |
| 9576 provide. | |
| 9577 <p/> | |
| 9578 The "Capabilities" section of each function and event describe which | |
| 9579 capabilities, if any, they are associated with. "Required Functionality" | |
| 9580 means it is available for use and no capabilities must be added to use it. | |
| 9581 "Optional Functionality" means the agent must possess the capability | |
| 9582 before it can be used. | |
| 9583 To possess a capability, the agent must | |
| 9584 <functionlink id="AddCapabilities">add the capability</functionlink>. | |
| 9585 "Optional Features" describe capabilities which, | |
| 9586 if added, extend the feature set. | |
| 9587 <p/> | |
| 9588 The potentially available capabilities of each <jvmti/> implementation are different. | |
| 9589 Depending on the implementation, a capability: | |
| 9590 <ul> | |
| 9591 <li>may never be added</li> | |
| 9592 <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li> | |
| 9593 <li>may be added only during the <code>OnLoad</code> phase</li> | |
| 9594 <li>may be possessed by only one environment at a time</li> | |
| 9595 <li>may be possessed by only one environment at a time, | |
| 9596 and only during the <code>OnLoad</code> phase</li> | |
| 9597 <li>and so on ...</li> | |
| 9598 </ul> | |
| 9599 Frequently, the addition of a capability may incur a cost in execution speed, start up | |
| 9600 time, and/or memory footprint. Note that the overhead of using a capability | |
| 9601 is completely different than the overhead of possessing a capability. | |
| 9602 Take single stepping as an example. When single stepping is on (that | |
| 9603 is, when the event is enabled and thus actively sending events) | |
| 9604 the overhead of sending and processing an event | |
| 9605 on each instruction is huge in any implementation. | |
| 9606 However, the overhead of possessing the capability may be small or large, | |
| 9607 depending on the implementation. Also, when and if a capability is potentially | |
| 9608 available depends on the implementation. Some examples: | |
| 9609 <ul> | |
| 9610 <li>One VM might perform all execution by compiling bytecodes into | |
| 9611 native code and be unable to generate single step instructions. | |
| 9612 In this implementation the capability can not be added.</li> | |
| 9613 <li>Another VM may be able to switch execution to a single stepping | |
| 9614 interpreter at any time. In this implementation, having the capability has no | |
| 9615 overhead and could be added at any time.</li> | |
| 9616 <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted | |
| 9617 execution engine at start up, but be unable to switch between them. | |
| 9618 In this implementation the capability would need to be added | |
| 9619 during the <code>OnLoad</code> phase (before bytecode | |
| 9620 execution begins) and would have a large impact on execution speed | |
| 9621 even if single stepping was never used.</li> | |
| 9622 <li>Still another VM might be able to add an "is single stepping on" check | |
| 9623 into compiled bytecodes or a generated interpreter. Again in this implementation | |
| 9624 the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test | |
| 9625 and branch on each instruction) would be considerably less.</li> | |
| 9626 </ul> | |
| 9627 <p/> | |
| 9628 Each <jvmti/> <internallink id="environments">environment</internallink> | |
| 9629 has its own set of capabilities. | |
| 9630 Initially, that set is empty. | |
| 9631 Any desired capability must be added. | |
| 9632 If possible, capabilities should be added during the <code>OnLoad</code> phase. For most | |
| 9633 virtual machines certain capabilities require special set up for | |
| 9634 the virtual machine and this set up must happen | |
| 9635 during the <code>OnLoad</code> phase, before the virtual machine begins execution. | |
| 9636 Once a capability is added, it can | |
| 9637 only be removed if explicitly relinquished by the environment. | |
| 9638 <p/> | |
| 9639 The agent can, | |
| 9640 <functionlink id="GetPotentialCapabilities">determine what | |
| 9641 capabilities this VM can potentially provide</functionlink>, | |
| 9642 <functionlink id="AddCapabilities">add the capabilities | |
| 9643 to be used</functionlink>, | |
| 9644 <functionlink id="RelinquishCapabilities">release capabilities | |
| 9645 which are no longer needed</functionlink>, and | |
| 9646 <functionlink id="GetCapabilities">examine the currently available | |
| 9647 capabilities</functionlink>. | |
| 9648 </intro> | |
| 9649 | |
| 9650 <intro id="capabilityExamples" label="Capability Examples"> | |
| 9651 For example, a freshly started agent (in the <code>OnLoad</code> function) | |
| 9652 wants to enable all possible capabilities. | |
| 9653 Note that, in general, this is not advisable as the agent may suffer | |
| 9654 a performance penalty for functionality it is not using. | |
| 9655 The code might look like this in C: | |
| 9656 <example> | |
| 9657 jvmtiCapabilities capa; | |
| 9658 jvmtiError err; | |
| 9659 | |
| 9660 err = (*jvmti)->GetPotentialCapabilities(jvmti, &capa); | |
| 9661 if (err == JVMTI_ERROR_NONE) { | |
| 9662 err = (*jvmti)->AddCapabilities(jvmti, &capa); | |
| 9663 </example> | |
| 9664 For example, if an agent wants to check if it can get | |
| 9665 the bytecodes of a method (that is, it wants to check | |
| 9666 if it previously added this capability and has not | |
| 9667 relinquished it), the code might | |
| 9668 look like this in C: | |
| 9669 <example> | |
| 9670 jvmtiCapabilities capa; | |
| 9671 jvmtiError err; | |
| 9672 | |
| 9673 err = (*jvmti)->GetCapabilities(jvmti, &capa); | |
| 9674 if (err == JVMTI_ERROR_NONE) { | |
| 9675 if (capa.can_get_bytecodes) { ... } } | |
| 9676 </example> | |
| 9677 </intro> | |
| 9678 | |
| 9679 <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure"> | |
| 9680 <description> | |
| 9681 The functions in this category use this capabilities structure | |
| 9682 which contains boolean flags corresponding to each capability: | |
| 9683 </description> | |
| 9684 <capabilityfield id="can_tag_objects"> | |
| 9685 <description> | |
| 9686 Can set and get tags, as described in the | |
| 9687 <internallink id="Heap">Heap category</internallink>. | |
| 9688 </description> | |
| 9689 </capabilityfield> | |
| 9690 <capabilityfield id="can_generate_field_modification_events"> | |
| 9691 <description> | |
| 9692 Can set watchpoints on field modification - | |
| 9693 <functionlink id="SetFieldModificationWatch"></functionlink> | |
| 9694 </description> | |
| 9695 </capabilityfield> | |
| 9696 <capabilityfield id="can_generate_field_access_events"> | |
| 9697 <description> | |
| 9698 Can set watchpoints on field access - | |
| 9699 <functionlink id="SetFieldAccessWatch"></functionlink> | |
| 9700 </description> | |
| 9701 </capabilityfield> | |
| 9702 <capabilityfield id="can_get_bytecodes"> | |
| 9703 <description> | |
| 9704 Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink> | |
| 9705 </description> | |
| 9706 </capabilityfield> | |
| 9707 <capabilityfield id="can_get_synthetic_attribute"> | |
| 9708 <description> | |
| 9709 Can test if a field or method is synthetic - | |
| 9710 <functionlink id="IsFieldSynthetic"></functionlink> and | |
| 9711 <functionlink id="IsMethodSynthetic"></functionlink> | |
| 9712 </description> | |
| 9713 </capabilityfield> | |
| 9714 <capabilityfield id="can_get_owned_monitor_info"> | |
| 9715 <description> | |
| 9716 Can get information about ownership of monitors - | |
| 9717 <functionlink id="GetOwnedMonitorInfo"></functionlink> | |
| 9718 </description> | |
| 9719 </capabilityfield> | |
| 9720 <capabilityfield id="can_get_current_contended_monitor"> | |
| 9721 <description> | |
| 9722 Can <functionlink id="GetCurrentContendedMonitor"></functionlink> | |
| 9723 </description> | |
| 9724 </capabilityfield> | |
| 9725 <capabilityfield id="can_get_monitor_info"> | |
| 9726 <description> | |
| 9727 Can <functionlink id="GetObjectMonitorUsage"></functionlink> | |
| 9728 </description> | |
| 9729 </capabilityfield> | |
| 9730 <capabilityfield id="can_pop_frame"> | |
| 9731 <description> | |
| 9732 Can pop frames off the stack - <functionlink id="PopFrame"></functionlink> | |
| 9733 </description> | |
| 9734 </capabilityfield> | |
| 9735 <capabilityfield id="can_redefine_classes"> | |
| 9736 <description> | |
| 9737 Can redefine classes with <functionlink id="RedefineClasses"/>. | |
| 9738 </description> | |
| 9739 </capabilityfield> | |
| 9740 <capabilityfield id="can_signal_thread"> | |
| 9741 <description> | |
| 9742 Can send stop or interrupt to threads | |
| 9743 </description> | |
| 9744 </capabilityfield> | |
| 9745 <capabilityfield id="can_get_source_file_name"> | |
| 9746 <description> | |
| 9747 Can get the source file name of a class | |
| 9748 </description> | |
| 9749 </capabilityfield> | |
| 9750 <capabilityfield id="can_get_line_numbers"> | |
| 9751 <description> | |
| 9752 Can get the line number table of a method | |
| 9753 </description> | |
| 9754 </capabilityfield> | |
| 9755 <capabilityfield id="can_get_source_debug_extension"> | |
| 9756 <description> | |
| 9757 Can get the source debug extension of a class | |
| 9758 </description> | |
| 9759 </capabilityfield> | |
| 9760 <capabilityfield id="can_access_local_variables"> | |
| 9761 <description> | |
| 9762 Can set and get local variables | |
| 9763 </description> | |
| 9764 </capabilityfield> | |
| 9765 <capabilityfield id="can_maintain_original_method_order"> | |
| 9766 <description> | |
| 9767 Can return methods in the order they occur in the class file | |
| 9768 </description> | |
| 9769 </capabilityfield> | |
| 9770 <capabilityfield id="can_generate_single_step_events"> | |
| 9771 <description> | |
| 9772 Can get <eventlink id="SingleStep">single step</eventlink> events | |
| 9773 </description> | |
| 9774 </capabilityfield> | |
| 9775 <capabilityfield id="can_generate_exception_events"> | |
| 9776 <description> | |
| 9777 Can get <eventlink id="Exception">exception thrown</eventlink> and | |
| 9778 <eventlink id="ExceptionCatch">exception catch</eventlink> events | |
| 9779 </description> | |
| 9780 </capabilityfield> | |
| 9781 <capabilityfield id="can_generate_frame_pop_events"> | |
| 9782 <description> | |
| 9783 Can <functionlink id="NotifyFramePop">set</functionlink> and thus get | |
| 9784 <eventlink id="FramePop"></eventlink> events | |
| 9785 </description> | |
| 9786 </capabilityfield> | |
| 9787 <capabilityfield id="can_generate_breakpoint_events"> | |
| 9788 <description> | |
| 9789 Can <functionlink id="SetBreakpoint">set</functionlink> and thus get | |
| 9790 <eventlink id="Breakpoint"></eventlink> events | |
| 9791 </description> | |
| 9792 </capabilityfield> | |
| 9793 <capabilityfield id="can_suspend"> | |
| 9794 <description> | |
| 9795 Can suspend and resume threads | |
| 9796 </description> | |
| 9797 </capabilityfield> | |
| 9798 <capabilityfield id="can_redefine_any_class"> | |
| 9799 <description> | |
| 9800 Can modify (retransform or redefine) any non-primitive non-array class. | |
| 9801 See <functionlink id="IsModifiableClass"/>. | |
| 9802 </description> | |
| 9803 </capabilityfield> | |
| 9804 <capabilityfield id="can_get_current_thread_cpu_time"> | |
| 9805 <description> | |
| 9806 Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink> | |
| 9807 current thread CPU time | |
| 9808 </description> | |
| 9809 </capabilityfield> | |
| 9810 <capabilityfield id="can_get_thread_cpu_time"> | |
| 9811 <description> | |
| 9812 Can <functionlink id="GetThreadCpuTime">get</functionlink> | |
| 9813 thread CPU time | |
| 9814 </description> | |
| 9815 </capabilityfield> | |
| 9816 <capabilityfield id="can_generate_method_entry_events" | |
| 9817 disp1="can_generate" disp2="_method_entry_events" | |
| 9818 > | |
| 9819 <description> | |
| 9820 Can generate method entry events on entering a method | |
| 9821 </description> | |
| 9822 </capabilityfield> | |
| 9823 <capabilityfield id="can_generate_method_exit_events" | |
| 9824 disp1="can_generate" disp2="_method_exit_events" | |
| 9825 > | |
| 9826 <description> | |
| 9827 Can generate method exit events on leaving a method | |
| 9828 </description> | |
| 9829 </capabilityfield> | |
| 9830 <capabilityfield id="can_generate_all_class_hook_events" | |
| 9831 disp1="can_generate" disp2="_all_class_hook_events" | |
| 9832 > | |
| 9833 <description> | |
| 9834 Can generate ClassFileLoadHook events for every loaded class. | |
| 9835 </description> | |
| 9836 </capabilityfield> | |
| 9837 <capabilityfield id="can_generate_compiled_method_load_events" | |
| 9838 disp1="can_generate" disp2="_compiled_method_load_events" | |
| 9839 > | |
| 9840 <description> | |
| 9841 Can generate events when a method is compiled or unloaded | |
| 9842 </description> | |
| 9843 </capabilityfield> | |
| 9844 <capabilityfield id="can_generate_monitor_events" | |
| 9845 disp1="can_generate" disp2="_monitor_events" | |
| 9846 > | |
| 9847 <description> | |
| 9848 Can generate events on monitor activity | |
| 9849 </description> | |
| 9850 </capabilityfield> | |
| 9851 <capabilityfield id="can_generate_vm_object_alloc_events" | |
| 9852 disp1="can_generate" disp2="_vm_object_alloc_events" | |
| 9853 > | |
| 9854 <description> | |
| 9855 Can generate events on VM allocation of an object | |
| 9856 </description> | |
| 9857 </capabilityfield> | |
| 9858 <capabilityfield id="can_generate_native_method_bind_events" | |
| 9859 disp1="can_generate" disp2="_native_method_bind_events" | |
| 9860 > | |
| 9861 <description> | |
| 9862 Can generate events when a native method is bound to its | |
| 9863 implementation | |
| 9864 </description> | |
| 9865 </capabilityfield> | |
| 9866 <capabilityfield id="can_generate_garbage_collection_events" | |
| 9867 disp1="can_generate" disp2="_garbage_collection_events" | |
| 9868 > | |
| 9869 <description> | |
| 9870 Can generate events when garbage collection begins or ends | |
| 9871 </description> | |
| 9872 </capabilityfield> | |
| 9873 <capabilityfield id="can_generate_object_free_events" | |
| 9874 disp1="can_generate" disp2="_object_free_events" | |
| 9875 > | |
| 9876 <description> | |
| 9877 Can generate events when the garbage collector frees an object | |
| 9878 </description> | |
| 9879 </capabilityfield> | |
| 9880 <capabilityfield id="can_force_early_return" since="1.1"> | |
| 9881 <description> | |
| 9882 Can return early from a method, as described in the | |
| 9883 <internallink id="ForceEarlyReturn">Force Early Return category</internallink>. | |
| 9884 </description> | |
| 9885 </capabilityfield> | |
| 9886 <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1"> | |
| 9887 <description> | |
| 9888 Can get information about owned monitors with stack depth - | |
| 9889 <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink> | |
| 9890 </description> | |
| 9891 </capabilityfield> | |
| 9892 <capabilityfield id="can_get_constant_pool" since="1.1"> | |
| 9893 <description> | |
| 9894 Can get the constant pool of a class - | |
| 9895 <functionlink id="GetConstantPool"></functionlink> | |
| 9896 </description> | |
| 9897 </capabilityfield> | |
| 9898 <capabilityfield id="can_set_native_method_prefix" since="1.1"> | |
| 9899 <description> | |
| 9900 Can set prefix to be applied when native method cannot be resolved - | |
| 9901 <functionlink id="SetNativeMethodPrefix"/> and | |
| 9902 <functionlink id="SetNativeMethodPrefixes"/> | |
| 9903 </description> | |
| 9904 </capabilityfield> | |
| 9905 <capabilityfield id="can_retransform_classes" since="1.1"> | |
| 9906 <description> | |
| 9907 Can retransform classes with <functionlink id="RetransformClasses"/>. | |
| 9908 In addition to the restrictions imposed by the specific | |
| 9909 implementation on this capability (see the | |
| 9910 <internallink id="capability">Capability</internallink> section), | |
| 9911 this capability must be set before the | |
| 9912 <eventlink id="ClassFileLoadHook"/> event is enabled for the | |
| 9913 first time in this environment. | |
| 9914 An environment that possesses this capability at the time that | |
| 9915 <code>ClassFileLoadHook</code> is enabled for the first time is | |
| 9916 said to be <i>retransformation capable</i>. | |
| 9917 An environment that does not possess this capability at the time that | |
| 9918 <code>ClassFileLoadHook</code> is enabled for the first time is | |
| 9919 said to be <i>retransformation incapable</i>. | |
| 9920 </description> | |
| 9921 </capabilityfield> | |
| 9922 <capabilityfield id="can_retransform_any_class" since="1.1"> | |
| 9923 <description> | |
| 9924 <functionlink id="RetransformClasses"/> can be called on any class | |
| 9925 (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> | |
| 9926 must also be set) | |
| 9927 </description> | |
| 9928 </capabilityfield> | |
| 9929 <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1"> | |
| 9930 <description> | |
| 9931 Can generate events when the VM is unable to allocate memory from | |
| 9932 the <tm>Java</tm> platform heap. | |
| 9933 See <eventlink id="ResourceExhausted"/>. | |
| 9934 </description> | |
| 9935 </capabilityfield> | |
| 9936 <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1"> | |
| 9937 <description> | |
| 9938 Can generate events when the VM is unable to create a thread. | |
| 9939 See <eventlink id="ResourceExhausted"/>. | |
| 9940 </description> | |
| 9941 </capabilityfield> | |
| 9942 </capabilitiestypedef> | |
| 9943 | |
| 9944 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140"> | |
| 9945 <synopsis>Get Potential Capabilities</synopsis> | |
| 9946 <description> | |
| 9947 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/> | |
| 9948 features that can potentially be possessed by this environment | |
| 9949 at this time. | |
| 9950 The returned capabilities differ from the complete set of capabilities | |
| 9951 implemented by the VM in two cases: another environment possesses | |
| 9952 capabilities that can only be possessed by one environment, or the | |
| 9953 current <functionlink id="GetPhase">phase</functionlink> is live, | |
| 9954 and certain capabilities can only be added during the <code>OnLoad</code> phase. | |
| 9955 The <functionlink id="AddCapabilities"></functionlink> function | |
| 9956 may be used to set any or all or these capabilities. | |
| 9957 Currently possessed capabilities are included. | |
| 9958 <p/> | |
| 9959 Typically this function is used in the <code>OnLoad</code> function. | |
| 9960 Some virtual machines may allow a limited set of capabilities to be | |
| 9961 added in the live phase. | |
| 9962 In this case, the set of potentially available capabilities | |
| 9963 will likely differ from the <code>OnLoad</code> phase set. | |
| 9964 <p/> | |
| 9965 See the | |
| 9966 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 9967 </description> | |
| 9968 <origin>new</origin> | |
| 9969 <capabilities> | |
| 9970 </capabilities> | |
| 9971 <parameters> | |
| 9972 <param id="capabilities_ptr"> | |
| 9973 <outptr><struct>jvmtiCapabilities</struct></outptr> | |
| 9974 <description> | |
| 9975 On return, points to the <jvmti/> capabilities that may be added. | |
| 9976 </description> | |
| 9977 </param> | |
| 9978 </parameters> | |
| 9979 <errors> | |
| 9980 </errors> | |
| 9981 </function> | |
| 9982 | |
| 9983 <elide> | |
| 9984 <function id="EstimateCostOfCapabilities" phase="onload" num="141"> | |
| 9985 <synopsis>Estimate Cost Of Capabilities</synopsis> | |
| 9986 <description> | |
| 9987 <issue>There is strong opposition to this function. The concern is | |
| 9988 that it would be difficult or impossible to provide meaningful | |
| 9989 numbers, as the amount of impact is conditional on many factors | |
| 9990 that a single number could not represent. There is doubt that | |
| 9991 conditional implementations would be used or are even a good idea. | |
| 9992 The thought is that release documentation for the implementation | |
| 9993 would be the best means of exposing this information. | |
| 9994 Unless new arguments are presented, I intend to remove this | |
| 9995 function in the next revision. | |
| 9996 </issue> | |
| 9997 <p/> | |
| 9998 Return via the <paramlink id="time_impact_ptr"></paramlink> and | |
| 9999 <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact | |
| 10000 of adding the capabilities pointed to by | |
| 10001 <paramlink id="capabilities_ptr"></paramlink>. | |
| 10002 The returned estimates are in percentage of additional overhead, thus | |
| 10003 a time impact of 100 mean the application might run | |
| 10004 at half the speed. | |
| 10005 The estimates are very rough approximations and are not guaranteed. | |
| 10006 Note also, that the estimates are of the impact of having the | |
| 10007 capability available--when and if it is used the impact may be | |
| 10008 much greater. | |
| 10009 Estimates can be for a single capability or for a set of | |
| 10010 capabilities. Note that the costs are not necessarily additive, | |
| 10011 adding support for one capability might make another available | |
| 10012 for free or conversely having two capabilities at once may | |
| 10013 have multiplicative impact. | |
| 10014 Estimates are relative to the current set of capabilities - | |
| 10015 that is, how much more impact given the currently possessed capabilities. | |
| 10016 <p/> | |
| 10017 Typically this function is used in the OnLoad function, | |
| 10018 some virtual machines may allow a limited set of capabilities to be | |
| 10019 added in the live phase. | |
| 10020 In this case, the set of potentially available capabilities | |
| 10021 will likely differ from the OnLoad phase set. | |
| 10022 <p/> | |
| 10023 See the | |
| 10024 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 10025 </description> | |
| 10026 <origin>new</origin> | |
| 10027 <capabilities> | |
| 10028 </capabilities> | |
| 10029 <parameters> | |
| 10030 <param id="capabilities_ptr"> | |
| 10031 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
| 10032 <description> | |
| 10033 points to the <jvmti/> capabilities to evaluate. | |
| 10034 </description> | |
| 10035 </param> | |
| 10036 <param id="time_impact_ptr"> | |
| 10037 <outptr><jint/></outptr> | |
| 10038 <description> | |
| 10039 On return, points to the estimated percentage increase in | |
| 10040 run time if this capability was added. | |
| 10041 </description> | |
| 10042 </param> | |
| 10043 <param id="space_impact_ptr"> | |
| 10044 <outptr><jint/></outptr> | |
| 10045 <description> | |
| 10046 On return, points to the estimated percentage increase in | |
| 10047 memory space used if this capability was added. | |
| 10048 </description> | |
| 10049 </param> | |
| 10050 </parameters> | |
| 10051 <errors> | |
| 10052 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10053 The desired capabilities are not even potentially available. | |
| 10054 </error> | |
| 10055 </errors> | |
| 10056 </function> | |
| 10057 </elide> | |
| 10058 | |
| 10059 <function id="AddCapabilities" jkernel="yes" phase="onload" num="142"> | |
| 10060 <synopsis>Add Capabilities</synopsis> | |
| 10061 <description> | |
| 10062 Set new capabilities by adding the capabilities | |
| 10063 whose values are set to one (<code>1</code>) in | |
| 10064 <code>*</code><paramlink id="capabilities_ptr"></paramlink>. | |
| 10065 All previous capabilities are retained. | |
| 10066 Typically this function is used in the <code>OnLoad</code> function. | |
| 10067 Some virtual machines may allow a limited set of capabilities to be | |
| 10068 added in the live phase. | |
| 10069 <p/> | |
| 10070 See the | |
| 10071 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 10072 </description> | |
| 10073 <origin>new</origin> | |
| 10074 <capabilities> | |
| 10075 </capabilities> | |
| 10076 <parameters> | |
| 10077 <param id="capabilities_ptr"> | |
| 10078 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
| 10079 <description> | |
| 10080 Points to the <jvmti/> capabilities to add. | |
| 10081 </description> | |
| 10082 </param> | |
| 10083 </parameters> | |
| 10084 <errors> | |
| 10085 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10086 The desired capabilities are not even potentially available. | |
| 10087 </error> | |
| 10088 </errors> | |
| 10089 </function> | |
| 10090 | |
| 10091 | |
| 10092 <function id="RelinquishCapabilities" phase="onload" num="143"> | |
| 10093 <synopsis>Relinquish Capabilities</synopsis> | |
| 10094 <description> | |
| 10095 Relinquish the capabilities | |
| 10096 whose values are set to one (<code>1</code>) in | |
| 10097 <code>*</code><paramlink id="capabilities_ptr"></paramlink>. | |
| 10098 Some implementations may allow only one environment to have a capability | |
| 10099 (see the <internallink id="capability">capability introduction</internallink>). | |
| 10100 This function releases capabilities | |
| 10101 so that they may be used by other agents. | |
| 10102 All other capabilities are retained. | |
| 10103 The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>. | |
| 10104 Attempting to relinquish a capability that the agent does not possess is not an error. | |
| 10105 <issue> | |
| 10106 It is possible for the agent to be actively using capabilities | |
| 10107 which are being relinquished. For example, a thread is currently | |
| 10108 suspended and can_suspend is being relinquished or an event is currently | |
| 10109 enabled and can_generate_whatever is being relinquished. | |
| 10110 There are three possible ways we could spec this: | |
| 10111 <ul> | |
| 10112 <li>relinquish automatically releases them</li> | |
| 10113 <li>relinquish checks and returns some error code if held</li> | |
| 10114 <li>it is the agent's responsibility and it is not checked</li> | |
| 10115 </ul> | |
| 10116 One of these should be chosen. | |
| 10117 </issue> | |
| 10118 </description> | |
| 10119 <origin>new</origin> | |
| 10120 <capabilities> | |
| 10121 </capabilities> | |
| 10122 <parameters> | |
| 10123 <param id="capabilities_ptr"> | |
| 10124 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
| 10125 <description> | |
| 10126 Points to the <jvmti/> capabilities to relinquish. | |
| 10127 </description> | |
| 10128 </param> | |
| 10129 </parameters> | |
| 10130 <errors> | |
| 10131 </errors> | |
| 10132 </function> | |
| 10133 | |
| 10134 | |
| 10135 | |
| 10136 <function id="GetCapabilities" jkernel="yes" phase="any" num="89"> | |
| 10137 <synopsis>Get Capabilities</synopsis> | |
| 10138 <description> | |
| 10139 Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/> | |
| 10140 features which this environment currently possesses. | |
| 10141 Each possessed capability is indicated by a one (<code>1</code>) in the | |
| 10142 corresponding field of the <internallink id="jvmtiCapabilities">capabilities | |
| 10143 structure</internallink>. | |
| 10144 An environment does not possess a capability unless it has been successfully added with | |
| 10145 <functionlink id="AddCapabilities"/>. | |
| 10146 An environment only loses possession of a capability if it has been relinquished with | |
| 10147 <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result | |
| 10148 of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which | |
| 10149 have been made. | |
| 10150 <p/> | |
| 10151 See the | |
| 10152 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
| 10153 </description> | |
| 10154 <origin>jvmdiClone</origin> | |
| 10155 <capabilities> | |
| 10156 </capabilities> | |
| 10157 <parameters> | |
| 10158 <param id="capabilities_ptr"> | |
| 10159 <outptr><struct>jvmtiCapabilities</struct></outptr> | |
| 10160 <description> | |
| 10161 On return, points to the <jvmti/> capabilities. | |
| 10162 </description> | |
| 10163 </param> | |
| 10164 </parameters> | |
| 10165 <errors> | |
| 10166 </errors> | |
| 10167 </function> | |
| 10168 | |
| 10169 </category> | |
| 10170 | |
| 10171 | |
| 10172 <category id="timers" label="Timers"> | |
| 10173 | |
| 10174 <intro> | |
| 10175 These functions provide timing information. | |
| 10176 The resolution at which the time is updated is not specified. | |
| 10177 They provides nanosecond precision, but not necessarily nanosecond accuracy. | |
| 10178 Details about the timers, such as their maximum values, can be accessed with | |
| 10179 the timer information functions. | |
| 10180 </intro> | |
| 10181 | |
| 10182 <typedef id="jvmtiTimerInfo" label="Timer Info"> | |
| 10183 <description> | |
| 10184 The information function for each timer returns this data structure. | |
| 10185 </description> | |
| 10186 <field id="max_value"> | |
| 10187 <jlong/> | |
| 10188 <description> | |
| 10189 The maximum value the timer can reach. | |
| 10190 After this value is reached the timer wraps back to zero. | |
| 10191 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10192 it may appear to be a negative number. | |
| 10193 </description> | |
| 10194 </field> | |
| 10195 <field id="may_skip_forward"> | |
| 10196 <jboolean/> | |
| 10197 <description> | |
| 10198 If true, the timer can be externally adjusted and as a result skip forward. | |
| 10199 If false, the timer value will never increase faster than real time. | |
| 10200 </description> | |
| 10201 </field> | |
| 10202 <field id="may_skip_backward"> | |
| 10203 <jboolean/> | |
| 10204 <description> | |
| 10205 If true, the timer can be externally adjusted and as a result skip backward. | |
| 10206 If false, the timer value will be monotonically increasing. | |
| 10207 </description> | |
| 10208 </field> | |
| 10209 <field id="kind"> | |
| 10210 <enum>jvmtiTimerKind</enum> | |
| 10211 <description> | |
| 10212 The kind of timer. | |
| 10213 On a platform that does not distinguish between user and system time, <datalink | |
| 10214 id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink> | |
| 10215 is returned. | |
| 10216 </description> | |
| 10217 </field> | |
| 10218 <field id="reserved1"> | |
| 10219 <jlong/> | |
| 10220 <description> | |
| 10221 Reserved for future use. | |
| 10222 </description> | |
| 10223 </field> | |
| 10224 <field id="reserved2"> | |
| 10225 <jlong/> | |
| 10226 <description> | |
| 10227 Reserved for future use. | |
| 10228 </description> | |
| 10229 </field> | |
| 10230 </typedef> | |
| 10231 | |
| 10232 <intro> | |
| 10233 Where the timer kind is -- | |
| 10234 | |
| 10235 <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum"> | |
| 10236 <constant id="JVMTI_TIMER_USER_CPU" num="30"> | |
| 10237 CPU time that a thread is in user mode. | |
| 10238 </constant> | |
| 10239 <constant id="JVMTI_TIMER_TOTAL_CPU" num="31"> | |
| 10240 CPU time that a thread is in user or system mode. | |
| 10241 </constant> | |
| 10242 <constant id="JVMTI_TIMER_ELAPSED" num="32"> | |
| 10243 Elapsed time. | |
| 10244 </constant> | |
| 10245 </constants> | |
| 10246 </intro> | |
| 10247 | |
| 10248 <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe" impl="innative notrace" phase="start" num="134"> | |
| 10249 <synopsis>Get Current Thread CPU Timer Information</synopsis> | |
| 10250 <description> | |
| 10251 Get information about the | |
| 10252 <functionlink id="GetCurrentThreadCpuTime"/> timer. | |
| 10253 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
| 10254 are filled in with details about the timer. | |
| 10255 This information is specific to the platform and the implementation of | |
| 10256 <functionlink id="GetCurrentThreadCpuTime"/> and thus | |
| 10257 does not vary by thread nor does it vary | |
| 10258 during a particular invocation of the VM. | |
| 10259 <p/> | |
| 10260 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> | |
| 10261 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values | |
| 10262 returned by <code>GetCurrentThreadCpuTimerInfo</code> | |
| 10263 and <functionlink id="GetThreadCpuTimerInfo"/> | |
| 10264 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. | |
| 10265 </description> | |
| 10266 <origin>new</origin> | |
| 10267 <capabilities> | |
| 10268 <required id="can_get_current_thread_cpu_time"> | |
| 10269 Can get current thread CPU time. | |
| 10270 </required> | |
| 10271 </capabilities> | |
| 10272 <parameters> | |
| 10273 <param id="info_ptr"> | |
| 10274 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
| 10275 <description> | |
| 10276 On return, filled with information describing the time | |
| 10277 returned by <functionlink id="GetCurrentThreadCpuTime"/>. | |
| 10278 </description> | |
| 10279 </param> | |
| 10280 </parameters> | |
| 10281 <errors> | |
| 10282 </errors> | |
| 10283 </function> | |
| 10284 | |
| 10285 <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135"> | |
| 10286 <synopsis>Get Current Thread CPU Time</synopsis> | |
| 10287 <description> | |
| 10288 Return the CPU time utilized by the current thread. | |
| 10289 <p/> | |
| 10290 Note that the <functionlink id="GetThreadCpuTime"/> | |
| 10291 function provides CPU time for any thread, including | |
| 10292 the current thread. <code>GetCurrentThreadCpuTime</code> | |
| 10293 exists to support platforms which cannot | |
| 10294 supply CPU time for threads other than the current | |
| 10295 thread or which have more accurate information for | |
| 10296 the current thread (see | |
| 10297 <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs | |
| 10298 <functionlink id="GetThreadCpuTimerInfo"/>). | |
| 10299 On many platforms this call will be equivalent to: | |
| 10300 <example> | |
| 10301 GetThreadCpuTime(env, NULL, nanos_ptr) | |
| 10302 </example> | |
| 10303 </description> | |
| 10304 <origin>new</origin> | |
| 10305 <capabilities> | |
| 10306 <required id="can_get_current_thread_cpu_time"> | |
| 10307 Can get current thread CPU time. | |
| 10308 <p/> | |
| 10309 If this capability is enabled after threads have started, | |
| 10310 the implementation may choose any time up | |
| 10311 to and including the time that the capability is enabled | |
| 10312 as the point where CPU time collection starts. | |
| 10313 <p/> | |
| 10314 This capability must be potentially available on any | |
| 10315 platform where | |
| 10316 <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink> | |
| 10317 is potentially available. | |
| 10318 </required> | |
| 10319 </capabilities> | |
| 10320 <parameters> | |
| 10321 <param id="nanos_ptr"> | |
| 10322 <outptr><jlong/></outptr> | |
| 10323 <description> | |
| 10324 On return, points to the CPU time used by this thread | |
| 10325 in nanoseconds. | |
| 10326 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10327 it may appear to be a negative number. | |
| 10328 </description> | |
| 10329 </param> | |
| 10330 </parameters> | |
| 10331 <errors> | |
| 10332 </errors> | |
| 10333 </function> | |
| 10334 | |
| 10335 <function id="GetThreadCpuTimerInfo" num="136"> | |
| 10336 <synopsis>Get Thread CPU Timer Information</synopsis> | |
| 10337 <description> | |
| 10338 Get information about the | |
| 10339 <functionlink id="GetThreadCpuTime"/> timer. | |
| 10340 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
| 10341 are filled in with details about the timer. | |
| 10342 This information is specific to the platform and the implementation of | |
| 10343 <functionlink id="GetThreadCpuTime"/> and thus | |
| 10344 does not vary by thread nor does it vary | |
| 10345 during a particular invocation of the VM. | |
| 10346 <p/> | |
| 10347 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> | |
| 10348 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values | |
| 10349 returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/> | |
| 10350 and <code>GetThreadCpuTimerInfo</code> | |
| 10351 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. | |
| 10352 </description> | |
| 10353 <origin>new</origin> | |
| 10354 <capabilities> | |
| 10355 <required id="can_get_thread_cpu_time"> | |
| 10356 Can get thread CPU time. | |
| 10357 </required> | |
| 10358 </capabilities> | |
| 10359 <parameters> | |
| 10360 <param id="info_ptr"> | |
| 10361 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
| 10362 <description> | |
| 10363 On return, filled with information describing the time | |
| 10364 returned by <functionlink id="GetThreadCpuTime"/>. | |
| 10365 </description> | |
| 10366 </param> | |
| 10367 </parameters> | |
| 10368 <errors> | |
| 10369 </errors> | |
| 10370 </function> | |
| 10371 | |
| 10372 <function id="GetThreadCpuTime" num="137"> | |
| 10373 <synopsis>Get Thread CPU Time</synopsis> | |
| 10374 <description> | |
| 10375 Return the CPU time utilized by the specified thread. | |
| 10376 <p/> | |
| 10377 Get information about this timer with | |
| 10378 <functionlink id="GetThreadCpuTimerInfo"/>. | |
| 10379 </description> | |
| 10380 <origin>new</origin> | |
| 10381 <capabilities> | |
| 10382 <required id="can_get_thread_cpu_time"> | |
| 10383 Can get thread CPU time. | |
| 10384 <p/> | |
| 10385 If this capability is enabled after threads have started, | |
| 10386 the implementation may choose any time up | |
| 10387 to and including the time that the capability is enabled | |
| 10388 as the point where CPU time collection starts. | |
| 10389 </required> | |
| 10390 </capabilities> | |
| 10391 <parameters> | |
| 10392 <param id="thread"> | |
| 10393 <jthread null="current"/> | |
| 10394 <description> | |
| 10395 The thread to query. | |
| 10396 </description> | |
| 10397 </param> | |
| 10398 <param id="nanos_ptr"> | |
| 10399 <outptr><jlong/></outptr> | |
| 10400 <description> | |
| 10401 On return, points to the CPU time used by the specified thread | |
| 10402 in nanoseconds. | |
| 10403 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10404 it may appear to be a negative number. | |
| 10405 </description> | |
| 10406 </param> | |
| 10407 </parameters> | |
| 10408 <errors> | |
| 10409 </errors> | |
| 10410 </function> | |
| 10411 | |
| 10412 <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138"> | |
| 10413 <synopsis>Get Timer Information</synopsis> | |
| 10414 <description> | |
| 10415 Get information about the | |
| 10416 <functionlink id="GetTime"/> timer. | |
| 10417 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
| 10418 are filled in with details about the timer. | |
| 10419 This information will not change during a particular invocation of the VM. | |
| 10420 </description> | |
| 10421 <origin>new</origin> | |
| 10422 <capabilities> | |
| 10423 </capabilities> | |
| 10424 <parameters> | |
| 10425 <param id="info_ptr"> | |
| 10426 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
| 10427 <description> | |
| 10428 On return, filled with information describing the time | |
| 10429 returned by <functionlink id="GetTime"/>. | |
| 10430 </description> | |
| 10431 </param> | |
| 10432 </parameters> | |
| 10433 <errors> | |
| 10434 </errors> | |
| 10435 </function> | |
| 10436 | |
| 10437 <function id="GetTime" phase="any" callbacksafe="safe" num="139"> | |
| 10438 <synopsis>Get Time</synopsis> | |
| 10439 <description> | |
| 10440 Return the current value of the system timer, in nanoseconds. | |
| 10441 <p/> | |
| 10442 The value returned represents nanoseconds since some fixed but | |
| 10443 arbitrary time (perhaps in the future, so values may be | |
| 10444 negative). This function provides nanosecond precision, but not | |
| 10445 necessarily nanosecond accuracy. No guarantees are made about | |
| 10446 how frequently values change. | |
| 10447 <p/> | |
| 10448 Get information about this timer with | |
| 10449 <functionlink id="GetTimerInfo"/>. | |
| 10450 </description> | |
| 10451 <origin>new</origin> | |
| 10452 <capabilities> | |
| 10453 </capabilities> | |
| 10454 <parameters> | |
| 10455 <param id="nanos_ptr"> | |
| 10456 <outptr><jlong/></outptr> | |
| 10457 <description> | |
| 10458 On return, points to the time in nanoseconds. | |
| 10459 This is an unsigned value. If tested or printed as a jlong (signed value) | |
| 10460 it may appear to be a negative number. | |
| 10461 </description> | |
| 10462 </param> | |
| 10463 </parameters> | |
| 10464 <errors> | |
| 10465 </errors> | |
| 10466 </function> | |
| 10467 | |
| 10468 <function id="GetAvailableProcessors" phase="any" num="144"> | |
| 10469 <synopsis>Get Available Processors</synopsis> | |
| 10470 <description> | |
| 10471 Returns the number of processors available to the Java virtual machine. | |
| 10472 <p/> | |
| 10473 This value may change during a particular invocation of the virtual machine. | |
| 10474 Applications that are sensitive to the number of available processors should | |
| 10475 therefore occasionally poll this property. | |
| 10476 </description> | |
| 10477 <origin>new</origin> | |
| 10478 <capabilities> | |
| 10479 </capabilities> | |
| 10480 <parameters> | |
| 10481 <param id="processor_count_ptr"> | |
| 10482 <outptr><jint/></outptr> | |
| 10483 <description> | |
| 10484 On return, points to the maximum number of processors available to the | |
| 10485 virtual machine; never smaller than one. | |
| 10486 </description> | |
| 10487 </param> | |
| 10488 </parameters> | |
| 10489 <errors> | |
| 10490 </errors> | |
| 10491 </function> | |
| 10492 | |
| 10493 </category> | |
| 10494 | |
| 10495 | |
| 10496 <category id="classLoaderSearch" label="Class Loader Search"> | |
| 10497 | |
| 10498 <intro> | |
| 10499 These functions allow the agent to add to the locations that a class loader searches for a class. | |
| 10500 This is useful for installing instrumentation under the correct class loader. | |
| 10501 </intro> | |
| 10502 | |
| 10503 <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149"> | |
| 10504 <synopsis>Add To Bootstrap Class Loader Search</synopsis> | |
| 10505 <description> | |
| 10506 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
|
10507 bootstrap class loader. See <vmspec chapter="5.3.1"/>. |
| 0 | 10508 After the bootstrap |
| 10509 class loader unsuccessfully searches for a class, the specified platform-dependent | |
| 10510 search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in | |
| 10511 the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, | |
| 10512 the segments will be searched in the order that this function was called. | |
| 10513 <p/> | |
| 10514 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent | |
| 10515 search path segment to be searched after the bootstrap class loader unsuccessfully searches | |
| 10516 for a class. The segment is typically a directory or JAR file. | |
| 10517 <p/> | |
| 10518 In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent | |
| 6919 | 10519 path to a <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html"> |
| 0 | 10520 JAR file</externallink>. The agent should take care that the JAR file does not |
| 10521 contain any classes or resources other than those to be defined by the bootstrap | |
| 10522 class loader for the purposes of instrumentation. | |
| 10523 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
10524 <vmspec/> specifies that a subsequent attempt to resolve a symbolic |
| 0 | 10525 reference that the Java virtual machine has previously unsuccessfully attempted |
| 10526 to resolve always fails with the same error that was thrown as a result of the | |
| 10527 initial resolution attempt. Consequently, if the JAR file contains an entry | |
| 10528 that corresponds to a class for which the Java virtual machine has | |
| 10529 unsuccessfully attempted to resolve a reference, then subsequent attempts to | |
| 10530 resolve that reference will fail with the same error as the initial attempt. | |
| 10531 </description> | |
| 10532 <origin>new</origin> | |
| 10533 <capabilities> | |
| 10534 </capabilities> | |
| 10535 <parameters> | |
| 10536 <param id="segment"> | |
| 10537 <inbuf><char/></inbuf> | |
| 10538 <description> | |
| 10539 The platform-dependent search path segment, encoded as a | |
| 10540 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10541 </description> | |
| 10542 </param> | |
| 10543 </parameters> | |
| 10544 <errors> | |
| 10545 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 10546 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an | |
| 10547 existing JAR file is an invalid path. | |
| 10548 </error> | |
| 10549 </errors> | |
| 10550 </function> | |
| 10551 | |
| 10552 <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1"> | |
| 10553 <synopsis>Add To System Class Loader Search</synopsis> | |
| 10554 <description> | |
| 10555 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
|
10556 defined by the system class loader. See <vmspec chapter="5.3.2"/>. |
| 0 | 10557 After the class loader unsuccessfully searches for a class, the specified platform-dependent search |
| 10558 path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the | |
| 10559 <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the | |
| 10560 segments will be searched in the order that this function was called. | |
| 10561 <p/> | |
| 10562 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent | |
| 10563 search path segment to be searched after the system class loader unsuccessfully searches | |
| 10564 for a class. The segment is typically a directory or JAR file. | |
| 10565 <p/> | |
| 10566 In the live phase the <paramlink id="segment"/> is a platform-dependent path to a <externallink | |
| 6919 | 10567 id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">JAR file</externallink> to be |
| 0 | 10568 searched after the system class loader unsuccessfully searches for a class. The agent should |
| 10569 take care that the JAR file does not contain any classes or resources other than those to be | |
| 10570 defined by the system class loader for the purposes of instrumentation. | |
| 10571 <p/> | |
| 10572 In the live phase the system class loader supports adding a JAR file to be searched if | |
| 10573 the system class loader implements a method name <code>appendToClassPathForInstrumentation</code> | |
| 10574 which takes a single parameter of type <code>java.lang.String</code>. The method is not required | |
| 10575 to have <code>public</code> access. | |
| 10576 <p/> | |
|
3330
1d80a2429f59
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
2125
diff
changeset
|
10577 <vmspec/> specifies that a subsequent attempt to resolve a symbolic |
| 0 | 10578 reference that the Java virtual machine has previously unsuccessfully attempted |
| 10579 to resolve always fails with the same error that was thrown as a result of the | |
| 10580 initial resolution attempt. Consequently, if the JAR file contains an entry | |
| 10581 that corresponds to a class for which the Java virtual machine has | |
| 10582 unsuccessfully attempted to resolve a reference, then subsequent attempts to | |
| 10583 resolve that reference will fail with the same error as the initial attempt. | |
| 10584 </description> | |
| 10585 <origin>new</origin> | |
| 10586 <capabilities> | |
| 10587 </capabilities> | |
| 10588 <parameters> | |
| 10589 <param id="segment"> | |
| 10590 <inbuf><char/></inbuf> | |
| 10591 <description> | |
| 10592 The platform-dependent search path segment, encoded as a | |
| 10593 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10594 </description> | |
| 10595 </param> | |
| 10596 </parameters> | |
| 10597 <errors> | |
| 10598 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
| 10599 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an | |
| 10600 existing JAR file is an invalid path. | |
| 10601 </error> | |
| 10602 <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED"> | |
| 10603 Operation not supported by the system class loader. | |
| 10604 </error> | |
| 10605 </errors> | |
| 10606 </function> | |
| 10607 | |
| 10608 </category> | |
| 10609 | |
| 10610 | |
| 10611 <category id="props" label="System Properties"> | |
| 10612 | |
| 10613 <intro> | |
| 10614 These functions get and set system properties. | |
| 10615 </intro> | |
| 10616 | |
| 10617 <function id="GetSystemProperties" phase="onload" num="130"> | |
| 10618 <synopsis>Get System Properties</synopsis> | |
| 10619 <description> | |
| 10620 The list of VM system property keys which may be used with | |
| 10621 <functionlink id="GetSystemProperty"/> is returned. | |
| 10622 It is strongly recommended that virtual machines provide the | |
| 10623 following property keys: | |
| 10624 <ul> | |
| 10625 <li><code>java.vm.vendor</code></li> | |
| 10626 <li><code>java.vm.version</code></li> | |
| 10627 <li><code>java.vm.name</code></li> | |
| 10628 <li><code>java.vm.info</code></li> | |
| 10629 <li><code>java.library.path</code></li> | |
| 10630 <li><code>java.class.path</code></li> | |
| 10631 </ul> | |
| 10632 Provides access to system properties defined by and used | |
| 10633 by the VM. | |
| 10634 Properties set on the command-line are included. | |
| 10635 This allows getting and setting of these properties | |
| 10636 before the VM even begins executing bytecodes. | |
| 10637 Since this is a VM view of system properties, the set of available | |
| 10638 properties will usually be different than that | |
| 10639 in <code>java.lang.System.getProperties</code>. | |
| 10640 JNI method invocation may be used to access | |
| 10641 <code>java.lang.System.getProperties</code>. | |
| 10642 <p/> | |
| 10643 The set of properties may grow during execution. | |
| 10644 </description> | |
| 10645 <origin>new</origin> | |
| 10646 <capabilities> | |
| 10647 </capabilities> | |
| 10648 <parameters> | |
| 10649 <param id="count_ptr"> | |
| 10650 <outptr><jint/></outptr> | |
| 10651 <description> | |
| 10652 On return, points to the number of property keys returned. | |
| 10653 </description> | |
| 10654 </param> | |
| 10655 <param id="property_ptr"> | |
| 10656 <allocallocbuf outcount="count_ptr"><char/></allocallocbuf> | |
| 10657 <description> | |
| 10658 On return, points to an array of property keys, encoded as | |
| 10659 <internallink id="mUTF">modified UTF-8</internallink> strings. | |
| 10660 </description> | |
| 10661 </param> | |
| 10662 </parameters> | |
| 10663 <errors> | |
| 10664 </errors> | |
| 10665 </function> | |
| 10666 | |
| 10667 <function id="GetSystemProperty" phase="onload" num="131"> | |
| 10668 <synopsis>Get System Property</synopsis> | |
| 10669 <description> | |
| 10670 Return a VM system property value given the property key. | |
| 10671 <p/> | |
| 10672 The function <functionlink id="GetSystemProperties"/> | |
| 10673 returns the set of property keys which may be used. | |
| 10674 The properties which can be retrieved may grow during | |
| 10675 execution. | |
| 10676 <p/> | |
| 10677 Since this is a VM view of system properties, the values | |
| 10678 of properties may differ from that returned by | |
| 10679 <code>java.lang.System.getProperty(String)</code>. | |
| 10680 A typical VM might copy the values of the VM system | |
| 10681 properties into the <code>Properties</code> held by | |
| 10682 <code>java.lang.System</code> during the initialization | |
| 10683 of that class. Thereafter any changes to the VM system | |
| 10684 properties (with <functionlink id="SetSystemProperty"/>) | |
| 10685 or the <code>java.lang.System</code> system properties | |
| 10686 (with <code>java.lang.System.setProperty(String,String)</code>) | |
| 10687 would cause the values to diverge. | |
| 10688 JNI method invocation may be used to access | |
| 10689 <code>java.lang.System.getProperty(String)</code>. | |
| 10690 </description> | |
| 10691 <origin>new</origin> | |
| 10692 <capabilities> | |
| 10693 </capabilities> | |
| 10694 <parameters> | |
| 10695 <param id="property"> | |
| 10696 <inbuf><char/></inbuf> | |
| 10697 <description> | |
| 10698 The key of the property to retrieve, encoded as a | |
| 10699 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10700 </description> | |
| 10701 </param> | |
| 10702 <param id="value_ptr"> | |
| 10703 <allocbuf><char/></allocbuf> | |
| 10704 <description> | |
| 10705 On return, points to the property value, encoded as a | |
| 10706 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10707 </description> | |
| 10708 </param> | |
| 10709 </parameters> | |
| 10710 <errors> | |
| 10711 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10712 This property is not available. | |
| 10713 Use <functionlink id="GetSystemProperties"/> to find available properties. | |
| 10714 </error> | |
| 10715 </errors> | |
| 10716 </function> | |
| 10717 | |
| 10718 <function id="SetSystemProperty" phase="onloadOnly" num="132"> | |
| 10719 <synopsis>Set System Property</synopsis> | |
| 10720 <description> | |
| 10721 Set a VM system property value. | |
| 10722 <p/> | |
| 10723 The function <functionlink id="GetSystemProperties"/> | |
| 10724 returns the set of property keys, some of these may be settable. | |
| 10725 See <functionlink id="GetSystemProperty"/>. | |
| 10726 </description> | |
| 10727 <origin>new</origin> | |
| 10728 <capabilities> | |
| 10729 </capabilities> | |
| 10730 <parameters> | |
| 10731 <param id="property"> | |
| 10732 <inbuf><char/></inbuf> | |
| 10733 <description> | |
| 10734 The key of the property, encoded as a | |
| 10735 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10736 </description> | |
| 10737 </param> | |
|
2100
b1a2afa37ec4
7003271: Hotspot should track cumulative Java heap bytes allocated on a per-thread basis
phh
parents:
2019
diff
changeset
|
10738 <param id="value_ptr"> |
| 0 | 10739 <inbuf> |
| 10740 <char/> | |
| 10741 <nullok> | |
| 10742 do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/> | |
| 10743 if the property is not writeable | |
| 10744 </nullok> | |
| 10745 </inbuf> | |
| 10746 <description> | |
| 10747 The property value to set, encoded as a | |
| 10748 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 10749 </description> | |
| 10750 </param> | |
| 10751 </parameters> | |
| 10752 <errors> | |
| 10753 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
| 10754 This property is not available or is not writeable. | |
| 10755 </error> | |
| 10756 </errors> | |
| 10757 </function> | |
| 10758 | |
| 10759 </category> | |
| 10760 | |
| 10761 <category id="general" label="General"> | |
| 10762 | |
| 10763 <intro> | |
| 10764 </intro> | |
| 10765 | |
| 10766 <function id="GetPhase" jkernel="yes" phase="any" num="133"> | |
| 10767 <synopsis>Get Phase</synopsis> | |
| 10768 <description> | |
| 10769 Return the current phase of VM execution. | |
| 10770 The phases proceed in sequence: | |
| 10771 <constants id="jvmtiPhase" label="Phases of execution" kind="enum"> | |
| 10772 <constant id="JVMTI_PHASE_ONLOAD" num="1"> | |
| 10773 <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
|
10774 <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
|
10775 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
|
10776 <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
|
10777 </code></internallink> function. |
| 0 | 10778 </constant> |
| 10779 <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
|
10780 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
|
10781 or <code>Agent_OnLoad_<agent-lib-name></code> and the |
| 0 | 10782 <code>VMStart</code> event. |
| 10783 </constant> | |
| 10784 <constant id="JVMTI_PHASE_START" num="6"> | |
| 10785 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event | |
| 10786 is sent and until the <code>VMInit</code> event is sent. | |
| 10787 </constant> | |
| 10788 <constant id="JVMTI_PHASE_LIVE" num="4"> | |
| 10789 Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent | |
| 10790 and until the <eventlink id="VMDeath"></eventlink> event returns. | |
| 10791 </constant> | |
| 10792 <constant id="JVMTI_PHASE_DEAD" num="8"> | |
| 10793 Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after | |
| 10794 start-up failure. | |
| 10795 </constant> | |
| 10796 </constants> | |
| 10797 In the case of start-up failure the VM will proceed directly to the dead | |
| 10798 phase skipping intermediate phases and neither a <code>VMInit</code> nor | |
| 10799 <code>VMDeath</code> event will be sent. | |
| 10800 <p/> | |
| 10801 Most <jvmti/> functions operate only in the live phase. | |
| 10802 The following functions operate in either the <code>OnLoad</code> or live phases: | |
| 10803 <functionphaselist phase="onload"/> | |
| 10804 The following functions operate in only the <code>OnLoad</code> phase: | |
| 10805 <functionphaselist phase="onloadOnly"/> | |
| 10806 The following functions operate in the start or live phases: | |
| 10807 <functionphaselist phase="start"/> | |
| 10808 The following functions operate in any phase: | |
| 10809 <functionphaselist phase="any"/> | |
| 10810 JNI functions (except the Invocation API) must only be used in the start or live phases. | |
| 10811 <p/> | |
| 10812 Most <jvmti/> events are sent only in the live phase. | |
| 10813 The following events operate in others phases: | |
| 10814 <eventphaselist phase="start"/> | |
| 10815 <eventphaselist phase="any"/> | |
| 10816 </description> | |
| 10817 <origin>new</origin> | |
| 10818 <capabilities> | |
| 10819 </capabilities> | |
| 10820 <parameters> | |
| 10821 <param id="phase_ptr"> | |
| 10822 <outptr><enum>jvmtiPhase</enum></outptr> | |
| 10823 <description> | |
| 10824 On return, points to the phase. | |
| 10825 </description> | |
| 10826 </param> | |
| 10827 </parameters> | |
| 10828 <errors> | |
| 10829 </errors> | |
| 10830 </function> | |
| 10831 | |
| 10832 <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127"> | |
| 10833 <synopsis>Dispose Environment</synopsis> | |
| 10834 <description> | |
| 10835 Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code> | |
| 10836 (see <internallink id="environments"><jvmti/> Environments</internallink>). | |
| 10837 Dispose of any resources held by the environment. | |
| 10838 <issue> | |
| 10839 What resources are reclaimed? What is undone? | |
| 10840 Breakpoints,watchpoints removed? | |
| 10841 </issue> | |
| 10842 Threads suspended by this environment are not resumed by this call, | |
| 10843 this must be done explicitly by the agent. | |
| 10844 Memory allocated by this environment via calls to <jvmti/> functions | |
| 10845 is not released, this can be done explicitly by the agent | |
| 10846 by calling <functionlink id="Deallocate"/>. | |
| 10847 Raw monitors created by this environment are not destroyed, | |
| 10848 this can be done explicitly by the agent | |
| 10849 by calling <functionlink id="DestroyRawMonitor"/>. | |
| 10850 The state of threads waiting on raw monitors created by this environment | |
| 10851 are not affected. | |
| 10852 <p/> | |
| 10853 Any <functionlink id="SetNativeMethodPrefix">native method | |
| 10854 prefixes</functionlink> for this environment will be unset; | |
| 10855 the agent must remove any prefixed native methods before | |
| 10856 dispose is called. | |
| 10857 <p/> | |
| 10858 Any <internallink id="capability">capabilities</internallink> | |
| 10859 held by this environment are relinquished. | |
| 10860 <p/> | |
| 10861 Events enabled by this environment will no longer be sent, however | |
| 10862 event handlers currently running will continue to run. Caution must | |
| 10863 be exercised in the design of event handlers whose environment may | |
| 10864 be disposed and thus become invalid during their execution. | |
| 10865 <p/> | |
| 10866 This environment may not be used after this call. | |
| 10867 This call returns to the caller. | |
| 10868 </description> | |
| 10869 <origin>new</origin> | |
| 10870 <capabilities> | |
| 10871 </capabilities> | |
| 10872 <parameters> | |
| 10873 </parameters> | |
| 10874 <errors> | |
| 10875 </errors> | |
| 10876 </function> | |
| 10877 | |
| 10878 <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148"> | |
| 10879 <synopsis>Set Environment Local Storage</synopsis> | |
| 10880 <description> | |
| 10881 The VM stores a pointer value associated with each environment. | |
| 10882 This pointer value is called <i>environment-local storage</i>. | |
| 10883 This value is <code>NULL</code> unless set with this function. | |
| 10884 Agents can allocate memory in which they store environment specific | |
| 10885 information. By setting environment-local storage it can then be | |
| 10886 accessed with | |
| 10887 <functionlink id="GetEnvironmentLocalStorage"></functionlink>. | |
| 10888 <p/> | |
| 10889 Called by the agent to set the value of the <jvmti/> | |
| 10890 environment-local storage. <jvmti/> supplies to the agent a pointer-size | |
| 10891 environment-local storage that can be used to record per-environment | |
| 10892 information. | |
| 10893 </description> | |
| 10894 <origin>new</origin> | |
| 10895 <capabilities> | |
| 10896 </capabilities> | |
| 10897 <parameters> | |
| 10898 <param id="data"> | |
| 10899 <inbuf> | |
| 10900 <void/> | |
| 10901 <nullok>value is set to <code>NULL</code></nullok> | |
| 10902 </inbuf> | |
| 10903 <description> | |
| 10904 The value to be entered into the environment-local storage. | |
| 10905 </description> | |
| 10906 </param> | |
| 10907 </parameters> | |
| 10908 <errors> | |
| 10909 </errors> | |
| 10910 </function> | |
| 10911 | |
| 10912 <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147"> | |
| 10913 <synopsis>Get Environment Local Storage</synopsis> | |
| 10914 <description> | |
| 10915 Called by the agent to get the value of the <jvmti/> environment-local | |
| 10916 storage. | |
| 10917 </description> | |
| 10918 <origin>new</origin> | |
| 10919 <capabilities> | |
| 10920 </capabilities> | |
| 10921 <parameters> | |
| 10922 <param id="data_ptr"> | |
| 10923 <agentbuf><void/></agentbuf> | |
| 10924 <description> | |
| 10925 Pointer through which the value of the environment local | |
| 10926 storage is returned. | |
| 10927 If environment-local storage has not been set with | |
| 10928 <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned | |
| 10929 pointer is <code>NULL</code>. | |
| 10930 </description> | |
| 10931 </param> | |
| 10932 </parameters> | |
| 10933 <errors> | |
| 10934 </errors> | |
| 10935 </function> | |
| 10936 | |
| 10937 <function id="GetVersionNumber" jkernel="yes" phase="any" num="88"> | |
| 10938 <synopsis>Get Version Number</synopsis> | |
| 10939 <description> | |
| 10940 Return the <jvmti/> version via <code>version_ptr</code>. | |
| 10941 The return value is the version identifier. | |
| 10942 The version identifier includes major, minor and micro | |
| 10943 version as well as the interface type. | |
| 10944 <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits"> | |
| 10945 <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000"> | |
| 10946 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI. | |
| 10947 </constant> | |
| 10948 <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000"> | |
| 10949 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>. | |
| 10950 </constant> | |
| 10951 </constants> | |
| 10952 <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits"> | |
| 10953 <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000"> | |
| 10954 Mask to extract interface type. | |
| 10955 The value of the version returned by this function masked with | |
| 10956 <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always | |
| 10957 <code>JVMTI_VERSION_INTERFACE_JVMTI</code> | |
| 10958 since this is a <jvmti/> function. | |
| 10959 </constant> | |
| 10960 <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000"> | |
| 10961 Mask to extract major version number. | |
| 10962 </constant> | |
| 10963 <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00"> | |
| 10964 Mask to extract minor version number. | |
| 10965 </constant> | |
| 10966 <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF"> | |
| 10967 Mask to extract micro version number. | |
| 10968 </constant> | |
| 10969 </constants> | |
| 10970 <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits"> | |
| 10971 <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16"> | |
| 10972 Shift to extract major version number. | |
| 10973 </constant> | |
| 10974 <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8"> | |
| 10975 Shift to extract minor version number. | |
| 10976 </constant> | |
| 10977 <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0"> | |
| 10978 Shift to extract micro version number. | |
| 10979 </constant> | |
| 10980 </constants> | |
| 10981 </description> | |
| 10982 <origin>jvmdi</origin> | |
| 10983 <capabilities> | |
| 10984 </capabilities> | |
| 10985 <parameters> | |
| 10986 <param id="version_ptr"> | |
| 10987 <outptr><jint/></outptr> | |
| 10988 <description> | |
| 10989 On return, points to the <jvmti/> version. | |
| 10990 </description> | |
| 10991 </param> | |
| 10992 </parameters> | |
| 10993 <errors> | |
| 10994 </errors> | |
| 10995 </function> | |
| 10996 | |
| 10997 | |
| 10998 <function id="GetErrorName" phase="any" num="128"> | |
| 10999 <synopsis>Get Error Name</synopsis> | |
| 11000 <description> | |
| 11001 Return the symbolic name for an | |
| 11002 <internallink id="ErrorSection">error code</internallink>. | |
| 11003 <p/> | |
| 11004 For example | |
| 11005 <code>GetErrorName(env, JVMTI_ERROR_NONE, &err_name)</code> | |
| 11006 would return in <code>err_name</code> the string | |
| 11007 <code>"JVMTI_ERROR_NONE"</code>. | |
| 11008 </description> | |
| 11009 <origin>new</origin> | |
| 11010 <capabilities> | |
| 11011 </capabilities> | |
| 11012 <parameters> | |
| 11013 <param id="error"> | |
| 11014 <enum>jvmtiError</enum> | |
| 11015 <description> | |
| 11016 The error code. | |
| 11017 </description> | |
| 11018 </param> | |
| 11019 <param id="name_ptr"> | |
| 11020 <allocbuf><char/></allocbuf> | |
| 11021 <description> | |
| 11022 On return, points to the error name. | |
| 11023 The name is encoded as a | |
| 11024 <internallink id="mUTF">modified UTF-8</internallink> string, | |
| 11025 but is restricted to the ASCII subset. | |
| 11026 </description> | |
| 11027 </param> | |
| 11028 </parameters> | |
| 11029 <errors> | |
| 11030 </errors> | |
| 11031 </function> | |
| 11032 | |
| 11033 <function id="SetVerboseFlag" phase="any" num="150"> | |
| 11034 <synopsis>Set Verbose Flag</synopsis> | |
| 11035 <description> | |
| 11036 <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum"> | |
| 11037 <constant id="JVMTI_VERBOSE_OTHER" num="0"> | |
| 11038 Verbose output other than the below. | |
| 11039 </constant> | |
| 11040 <constant id="JVMTI_VERBOSE_GC" num="1"> | |
| 11041 Verbose garbage collector output, like that specified with <code>-verbose:gc</code>. | |
| 11042 </constant> | |
| 11043 <constant id="JVMTI_VERBOSE_CLASS" num="2"> | |
| 11044 Verbose class loading output, like that specified with <code>-verbose:class</code>. | |
| 11045 </constant> | |
| 11046 <constant id="JVMTI_VERBOSE_JNI" num="4"> | |
| 11047 Verbose JNI output, like that specified with <code>-verbose:jni</code>. | |
| 11048 </constant> | |
| 11049 </constants> | |
| 11050 Control verbose output. | |
| 11051 This is the output which typically is sent to <code>stderr</code>. | |
| 11052 </description> | |
| 11053 <origin>new</origin> | |
| 11054 <capabilities> | |
| 11055 </capabilities> | |
| 11056 <parameters> | |
| 11057 <param id="flag"> | |
| 11058 <enum>jvmtiVerboseFlag</enum> | |
| 11059 <description> | |
| 11060 Which verbose flag to set. | |
| 11061 </description> | |
| 11062 </param> | |
| 11063 <param id="value"> | |
| 11064 <jboolean/> | |
| 11065 <description> | |
| 11066 New value of the flag. | |
| 11067 </description> | |
| 11068 </param> | |
| 11069 </parameters> | |
| 11070 <errors> | |
| 11071 </errors> | |
| 11072 </function> | |
| 11073 | |
| 11074 | |
| 11075 <function id="GetJLocationFormat" phase="any" num="129"> | |
| 11076 <synopsis>Get JLocation Format</synopsis> | |
| 11077 <description> | |
| 11078 Although the greatest functionality is achieved with location information | |
| 11079 referencing the virtual machine bytecode index, the definition of | |
| 11080 <code>jlocation</code> has intentionally been left unconstrained to allow VM | |
| 11081 implementations that do not have this information. | |
| 11082 <p/> | |
| 11083 This function describes the representation of <code>jlocation</code> used in this VM. | |
| 11084 If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>, | |
| 11085 <code>jlocation</code>s can | |
| 11086 be used as in indices into the array returned by | |
| 11087 <functionlink id="GetBytecodes"></functionlink>. | |
| 11088 <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum"> | |
| 11089 <constant id="JVMTI_JLOCATION_JVMBCI" num="1"> | |
| 11090 <code>jlocation</code> values represent virtual machine | |
| 11091 bytecode indices--that is, offsets into the | |
| 11092 virtual machine code for a method. | |
| 11093 </constant> | |
| 11094 <constant id="JVMTI_JLOCATION_MACHINEPC" num="2"> | |
| 11095 <code>jlocation</code> values represent native machine | |
| 11096 program counter values. | |
| 11097 </constant> | |
| 11098 <constant id="JVMTI_JLOCATION_OTHER" num="0"> | |
| 11099 <code>jlocation</code> values have some other representation. | |
| 11100 </constant> | |
| 11101 </constants> | |
| 11102 </description> | |
| 11103 <origin>new</origin> | |
| 11104 <capabilities> | |
| 11105 </capabilities> | |
| 11106 <parameters> | |
| 11107 <param id="format_ptr"> | |
| 11108 <outptr><enum>jvmtiJlocationFormat</enum></outptr> | |
| 11109 <description> | |
| 11110 On return, points to the format identifier for <code>jlocation</code> values. | |
| 11111 </description> | |
| 11112 </param> | |
| 11113 </parameters> | |
| 11114 <errors> | |
| 11115 </errors> | |
| 11116 </function> | |
| 11117 | |
| 11118 </category> | |
| 11119 | |
| 11120 </functionsection> | |
| 11121 | |
| 11122 <errorsection label="Error Reference"> | |
| 11123 <intro> | |
| 11124 Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code. | |
| 11125 <p/> | |
| 11126 It is the responsibility of the agent to call <jvmti/> functions with | |
| 11127 valid parameters and in the proper context (calling thread is attached, | |
| 11128 phase is correct, etc.). | |
| 11129 Detecting some error conditions may be difficult, inefficient, or | |
| 11130 impossible for an implementation. | |
| 11131 The errors listed in | |
| 11132 <internallink id="reqerrors">Function Specific Required Errors</internallink> | |
| 11133 must be detected by the implementation. | |
| 11134 All other errors represent the recommended response to the error | |
| 11135 condition. | |
| 11136 </intro> | |
| 11137 | |
| 11138 <errorcategory id="universal-error" label="Universal Errors"> | |
| 11139 <intro> | |
| 11140 The following errors may be returned by any function | |
| 11141 </intro> | |
| 11142 | |
| 11143 <errorid id="JVMTI_ERROR_NONE" num="0"> | |
| 11144 No error has occurred. This is the error code that is returned | |
| 11145 on successful completion of the function. | |
| 11146 </errorid> | |
| 11147 <errorid id="JVMTI_ERROR_NULL_POINTER" num="100"> | |
| 11148 Pointer is unexpectedly <code>NULL</code>. | |
| 11149 </errorid> | |
| 11150 <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110"> | |
| 11151 The function attempted to allocate memory and no more memory was | |
| 11152 available for allocation. | |
| 11153 </errorid> | |
| 11154 <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111"> | |
| 11155 The desired functionality has not been enabled in this virtual machine. | |
| 11156 </errorid> | |
| 11157 <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115"> | |
| 11158 The thread being used to call this function is not attached | |
| 11159 to the virtual machine. Calls must be made from attached threads. | |
| 11160 See <code>AttachCurrentThread</code> in the JNI invocation API. | |
| 11161 </errorid> | |
| 11162 <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116"> | |
| 11163 The <jvmti/> environment provided is no longer connected or is | |
| 11164 not an environment. | |
| 11165 </errorid> | |
| 11166 <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112"> | |
| 11167 The desired functionality is not available in the current | |
| 11168 <functionlink id="GetPhase">phase</functionlink>. | |
| 11169 Always returned if the virtual machine has completed running. | |
| 11170 </errorid> | |
| 11171 <errorid id="JVMTI_ERROR_INTERNAL" num="113"> | |
| 11172 An unexpected internal error has occurred. | |
| 11173 </errorid> | |
| 11174 </errorcategory> | |
| 11175 | |
| 11176 <errorcategory id="reqerrors" label="Function Specific Required Errors"> | |
| 11177 <intro> | |
| 11178 The following errors are returned by some <jvmti/> functions and must | |
| 11179 be returned by the implementation when the condition occurs. | |
| 11180 </intro> | |
| 11181 | |
| 11182 <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12"> | |
| 11183 Invalid priority. | |
| 11184 </errorid> | |
| 11185 <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13"> | |
| 11186 Thread was not suspended. | |
| 11187 </errorid> | |
| 11188 <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14"> | |
| 11189 Thread already suspended. | |
| 11190 </errorid> | |
| 11191 <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15"> | |
| 11192 This operation requires the thread to be alive--that is, | |
| 11193 it must be started and not yet have died. | |
| 11194 </errorid> | |
| 11195 <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22"> | |
| 11196 The class has been loaded but not yet prepared. | |
| 11197 </errorid> | |
| 11198 <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31"> | |
| 11199 There are no Java programming language or JNI stack frames at the specified depth. | |
| 11200 </errorid> | |
| 11201 <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32"> | |
| 11202 Information about the frame is not available (e.g. for native frames). | |
| 11203 </errorid> | |
| 11204 <errorid id="JVMTI_ERROR_DUPLICATE" num="40"> | |
| 11205 Item already set. | |
| 11206 </errorid> | |
| 11207 <errorid id="JVMTI_ERROR_NOT_FOUND" num="41"> | |
| 11208 Desired element (e.g. field or breakpoint) not found | |
| 11209 </errorid> | |
| 11210 <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51"> | |
| 11211 This thread doesn't own the raw monitor. | |
| 11212 </errorid> | |
| 11213 <errorid id="JVMTI_ERROR_INTERRUPT" num="52"> | |
| 11214 The call has been interrupted before completion. | |
| 11215 </errorid> | |
| 11216 <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79"> | |
| 11217 The class cannot be modified. | |
| 11218 </errorid> | |
| 11219 <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98"> | |
| 11220 The functionality is not available in this virtual machine. | |
| 11221 </errorid> | |
| 11222 <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101"> | |
| 11223 The requested information is not available. | |
| 11224 </errorid> | |
| 11225 <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102"> | |
| 11226 The specified event type ID is not recognized. | |
| 11227 </errorid> | |
| 11228 <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104"> | |
| 11229 The requested information is not available for native method. | |
| 11230 </errorid> | |
| 11231 <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106"> | |
| 11232 The class loader does not support this operation. | |
| 11233 </errorid> | |
| 11234 </errorcategory> | |
| 11235 | |
| 11236 <errorcategory id="function-specific-errors" label="Function Specific Agent Errors"> | |
| 11237 <intro> | |
| 11238 The following errors are returned by some <jvmti/> functions. | |
| 11239 They are returned in the event of invalid parameters passed by the | |
| 11240 agent or usage in an invalid context. | |
| 11241 An implementation is not required to detect these errors. | |
| 11242 </intro> | |
| 11243 | |
| 11244 <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10"> | |
| 11245 The passed thread is not a valid thread. | |
| 11246 </errorid> | |
| 11247 <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25"> | |
| 11248 Invalid field. | |
| 11249 </errorid> | |
| 11250 <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23"> | |
| 11251 Invalid method. | |
| 11252 </errorid> | |
| 11253 <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24"> | |
| 11254 Invalid location. | |
| 11255 </errorid> | |
| 11256 <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20"> | |
| 11257 Invalid object. | |
| 11258 </errorid> | |
| 11259 <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21"> | |
| 11260 Invalid class. | |
| 11261 </errorid> | |
| 11262 <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34"> | |
| 11263 The variable is not an appropriate type for the function used. | |
| 11264 </errorid> | |
| 11265 <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35"> | |
| 11266 Invalid slot. | |
| 11267 </errorid> | |
| 11268 <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99"> | |
| 11269 The capability being used is false in this environment. | |
| 11270 </errorid> | |
| 11271 <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11"> | |
| 11272 Thread group invalid. | |
| 11273 </errorid> | |
| 11274 <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50"> | |
| 11275 Invalid raw monitor. | |
| 11276 </errorid> | |
| 11277 <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103"> | |
| 11278 Illegal argument. | |
| 11279 </errorid> | |
| 11280 <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65"> | |
| 11281 The state of the thread has been modified, and is now inconsistent. | |
| 11282 </errorid> | |
| 11283 <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68"> | |
| 11284 A new class file has a version number not supported by this VM. | |
| 11285 </errorid> | |
| 11286 <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60"> | |
| 11287 A new class file is malformed (the VM would return a <code>ClassFormatError</code>). | |
| 11288 </errorid> | |
| 11289 <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61"> | |
| 11290 The new class file definitions would lead to a circular | |
| 11291 definition (the VM would return a <code>ClassCircularityError</code>). | |
| 11292 </errorid> | |
| 11293 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63"> | |
| 11294 A new class file would require adding a method. | |
| 11295 </errorid> | |
| 11296 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64"> | |
| 11297 A new class version changes a field. | |
| 11298 </errorid> | |
| 11299 <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62"> | |
| 11300 The class bytes fail verification. | |
| 11301 </errorid> | |
| 11302 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66"> | |
| 11303 A direct superclass is different for the new class | |
| 11304 version, or the set of directly implemented | |
| 11305 interfaces is different. | |
| 11306 </errorid> | |
| 11307 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67"> | |
| 11308 A new class version does not declare a method | |
| 11309 declared in the old class version. | |
| 11310 </errorid> | |
| 11311 <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69"> | |
| 11312 The class name defined in the new class file is | |
| 11313 different from the name in the old class object. | |
| 11314 </errorid> | |
| 11315 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70"> | |
| 11316 A new class version has different modifiers. | |
| 11317 </errorid> | |
| 11318 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71"> | |
| 11319 A method in the new class version has different modifiers | |
| 11320 than its counterpart in the old class version. | |
| 11321 </errorid> | |
| 11322 </errorcategory> | |
| 11323 </errorsection> | |
| 11324 | |
| 11325 <eventsection label="Events"> | |
| 11326 <intro label="Handling Events" id="eventIntro"> | |
| 11327 Agents can be informed of many events that occur in application | |
| 11328 programs. | |
| 11329 <p/> | |
| 11330 To handle events, designate a set of callback functions with | |
| 11331 <functionlink id="SetEventCallbacks"></functionlink>. | |
| 11332 For each event the corresponding callback function will be | |
| 11333 called. | |
| 11334 Arguments to the callback function provide additional | |
| 11335 information about the event. | |
| 11336 <p/> | |
| 11337 The callback function is usually called from within an application | |
| 11338 thread. The <jvmti/> implementation does not | |
| 11339 queue events in any way. This means | |
| 11340 that event callback functions must be written | |
| 11341 carefully. Here are some general guidelines. See | |
| 11342 the individual event descriptions for further | |
| 11343 suggestions. | |
| 11344 <p/> | |
| 11345 <ul> | |
| 11346 <li>Any exception thrown during the execution of an event callback can | |
| 11347 overwrite any current pending exception in the current application thread. | |
| 11348 Care must be taken to preserve a pending exception | |
| 11349 when an event callback makes a JNI call that might generate an exception. | |
| 11350 </li> | |
| 11351 <li>Event callback functions must be re-entrant. The <jvmti/> implementation does | |
| 11352 not queue events. If an agent needs to process events one at a time, it | |
| 11353 can use a raw monitor inside the | |
| 11354 event callback functions to serialize event processing. | |
| 11355 </li> | |
| 11356 <li>Event callback functions that execute JNI's FindClass function to load | |
| 11357 classes need to note that FindClass locates the class loader associated | |
| 11358 with the current native method. For the purposes of class loading, an | |
| 11359 event callback that includes a JNI environment as a parameter to the | |
| 11360 callback will treated as if it is a native call, where the native method | |
| 11361 is in the class of the event thread's current frame. | |
| 11362 </li> | |
| 11363 </ul> | |
| 11364 <p/> | |
| 11365 Some <jvmti/> events identify objects with JNI references. | |
| 11366 All references | |
| 11367 in <jvmti/> events are JNI local references and will become invalid | |
| 11368 after the event callback returns. | |
| 11369 Unless stated otherwise, memory referenced by pointers sent in event | |
| 11370 callbacks may not be referenced after the event callback returns. | |
| 11371 <p/> | |
| 11372 Except where stated otherwise, events are delivered on the thread | |
| 11373 that caused the event. | |
| 11374 Events are sent at the time they occur. | |
| 11375 The specification for each event includes the set of | |
| 11376 <functionlink id="GetPhase">phases</functionlink> in which it can be sent; | |
| 11377 if an event triggering activity occurs during another phase, no event | |
| 11378 is sent. | |
| 11379 <p/> | |
| 11380 A thread that generates an event does not change its execution status | |
| 11381 (for example, the event does not cause the thread to be suspended). | |
| 11382 If an agent wishes the event to result in suspension, then the agent | |
| 11383 is responsible for explicitly suspending the thread with | |
| 11384 <functionlink id="SuspendThread"></functionlink>. | |
| 11385 <p/> | |
| 11386 If an event is enabled in multiple environments, the event will be sent | |
| 11387 to each agent in the order that the environments were created. | |
| 11388 </intro> | |
| 11389 | |
| 11390 <intro label="Enabling Events" id="enablingevents"> | |
| 11391 All events are initially disabled. In order to receive any | |
| 11392 event: | |
| 11393 <ul> | |
| 11394 <li> | |
| 11395 If the event requires a capability, that capability must | |
| 11396 be added with | |
| 11397 <functionlink id="AddCapabilities"></functionlink>. | |
| 11398 </li> | |
| 11399 <li> | |
| 11400 A callback for the event must be set with | |
| 11401 <functionlink id="SetEventCallbacks"></functionlink>. | |
| 11402 </li> | |
| 11403 <li> | |
| 11404 The event must be enabled with | |
| 11405 <functionlink id="SetEventNotificationMode"></functionlink>. | |
| 11406 </li> | |
| 11407 </ul> | |
| 11408 </intro> | |
| 11409 | |
| 11410 <intro label="Multiple Co-located Events" id="eventorder"> | |
| 11411 In many situations it is possible for multiple events to occur | |
| 11412 at the same location in one thread. When this happens, all the events | |
| 11413 are reported through the event callbacks in the order specified in this section. | |
| 11414 <p/> | |
| 11415 If the current location is at the entry point of a method, the | |
| 11416 <eventlink id="MethodEntry"></eventlink> event is reported before | |
| 11417 any other event at the current location in the same thread. | |
| 11418 <p/> | |
| 11419 If an exception catch has been detected at the current location, | |
| 11420 either because it is the beginning of a catch clause or a native method | |
| 11421 that cleared a pending exception has returned, the | |
| 11422 <code>exceptionCatch</code> event is reported before | |
| 11423 any other event at the current location in the same thread. | |
| 11424 <p/> | |
| 11425 If a <code>singleStep</code> event or | |
| 11426 <code>breakpoint</code> event is triggered at the | |
| 11427 current location, the event is defined to occur | |
| 11428 immediately before the code at the current location is executed. | |
| 11429 These events are reported before any events which are triggered | |
| 11430 by the execution of code at the current location in the same | |
| 11431 thread (specifically: | |
| 11432 <code>exception</code>, | |
| 11433 <code>fieldAccess</code>, and | |
| 11434 <code>fieldModification</code>). | |
| 11435 If both a step and breakpoint event are triggered for the same thread and | |
| 11436 location, the step event is reported before the breakpoint event. | |
| 11437 <p/> | |
| 11438 If the current location is the exit point of a method (that is, the last | |
| 11439 location before returning to the caller), the | |
| 11440 <eventlink id="MethodExit"></eventlink> event and | |
| 11441 the <eventlink id="FramePop"></eventlink> event (if requested) | |
| 11442 are reported after all other events at the current location in the same | |
| 11443 thread. There is no specified ordering of these two events | |
| 11444 with respect to each other. | |
| 11445 <p/> | |
| 11446 Co-located events can be triggered during the processing of some other | |
| 11447 event by the agent at the same location in the same thread. | |
| 11448 If such an event, of type <i>y</i>, is triggered during the processing of | |
| 11449 an event of type <i>x</i>, and if <i>x</i> | |
| 11450 precedes <i>y</i> in the ordering specified above, the co-located event | |
| 11451 <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede | |
| 11452 <i>y</i>, <i>y</i> is not reported for the current thread and location. | |
| 11453 For example, if a breakpoint is set at the current location | |
| 11454 during the processing of <eventlink id="SingleStep"></eventlink>, | |
| 11455 that breakpoint will be reported before the thread moves off the current | |
| 11456 location. | |
| 11457 <p/>The following events are never considered to be co-located with | |
| 11458 other events. | |
| 11459 <ul> | |
| 11460 <li><eventlink id="VMStart"></eventlink></li> | |
| 11461 <li><eventlink id="VMInit"></eventlink></li> | |
| 11462 <li><eventlink id="VMDeath"></eventlink></li> | |
| 11463 <li><eventlink id="ThreadStart"></eventlink></li> | |
| 11464 <li><eventlink id="ThreadEnd"></eventlink></li> | |
| 11465 <li><eventlink id="ClassLoad"></eventlink></li> | |
| 11466 <li><eventlink id="ClassPrepare"></eventlink></li> | |
| 11467 </ul> | |
| 11468 </intro> | |
| 11469 | |
| 11470 <intro label="Event Callbacks" id="jvmtiEventCallbacks"> | |
| 11471 The event callback structure below is used to specify the handler function | |
| 11472 for events. It is set with the | |
| 11473 <functionlink id="SetEventCallbacks"></functionlink> function. | |
| 11474 </intro> | |
| 11475 | |
| 11476 <event label="Single Step" | |
| 11477 id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60"> | |
| 11478 <description> | |
| 11479 Single step events allow the agent to trace thread execution | |
| 11480 at the finest granularity allowed by the VM. A single step event is | |
| 11481 generated whenever a thread reaches a new location. | |
| 11482 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
|
11483 instruction as defined in <vmspec/>. However, some implementations |
| 0 | 11484 may define locations differently. In any case the |
| 11485 <code>method</code> and <code>location</code> | |
| 11486 parameters uniquely identify the current location and allow | |
| 11487 the mapping to source file and line number when that information is | |
| 11488 available. | |
| 11489 <p/> | |
| 11490 No single step events are generated from within native methods. | |
| 11491 </description> | |
| 11492 <origin>jvmdi</origin> | |
| 11493 <capabilities> | |
| 11494 <required id="can_generate_single_step_events"></required> | |
| 11495 </capabilities> | |
| 11496 <parameters> | |
| 11497 <param id="jni_env"> | |
| 11498 <outptr> | |
| 11499 <struct>JNIEnv</struct> | |
| 11500 </outptr> | |
| 11501 <description> | |
| 11502 The JNI environment of the event (current) thread | |
| 11503 </description> | |
| 11504 </param> | |
| 11505 <param id="thread"> | |
| 11506 <jthread/> | |
| 11507 <description> | |
| 11508 Thread about to execution a new instruction | |
| 11509 </description> | |
| 11510 </param> | |
| 11511 <param id="klass"> | |
| 11512 <jclass method="method"/> | |
| 11513 <description> | |
| 11514 Class of the method about to execute a new instruction | |
| 11515 </description> | |
| 11516 </param> | |
| 11517 <param id="method"> | |
| 11518 <jmethodID class="klass"/> | |
| 11519 <description> | |
| 11520 Method about to execute a new instruction | |
| 11521 </description> | |
| 11522 </param> | |
| 11523 <param id="location"> | |
| 11524 <jlocation/> | |
| 11525 <description> | |
| 11526 Location of the new instruction | |
| 11527 </description> | |
| 11528 </param> | |
| 11529 </parameters> | |
| 11530 </event> | |
| 11531 | |
| 11532 <event label="Breakpoint" | |
| 11533 id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62"> | |
| 11534 <description> | |
| 11535 Breakpoint events are generated whenever a thread reaches a location | |
| 11536 designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>. | |
| 11537 The <code>method</code> and <code>location</code> | |
| 11538 parameters uniquely identify the current location and allow | |
| 11539 the mapping to source file and line number when that information is | |
| 11540 available. | |
| 11541 </description> | |
| 11542 <origin>jvmdi</origin> | |
| 11543 <capabilities> | |
| 11544 <required id="can_generate_breakpoint_events"></required> | |
| 11545 </capabilities> | |
| 11546 <parameters> | |
| 11547 <param id="jni_env"> | |
| 11548 <outptr> | |
| 11549 <struct>JNIEnv</struct> | |
| 11550 </outptr> | |
| 11551 <description> | |
| 11552 The JNI environment of the event (current) thread. | |
| 11553 </description> | |
| 11554 </param> | |
| 11555 <param id="thread"> | |
| 11556 <jthread/> | |
| 11557 <description> | |
| 11558 Thread that hit the breakpoint | |
| 11559 </description> | |
| 11560 </param> | |
| 11561 <param id="klass"> | |
| 11562 <jclass method="method"/> | |
| 11563 <description> | |
| 11564 Class of the method that hit the breakpoint | |
| 11565 </description> | |
| 11566 </param> | |
| 11567 <param id="method"> | |
| 11568 <jmethodID class="klass"/> | |
| 11569 <description> | |
| 11570 Method that hit the breakpoint | |
| 11571 </description> | |
| 11572 </param> | |
| 11573 <param id="location"> | |
| 11574 <jlocation/> | |
| 11575 <description> | |
| 11576 location of the breakpoint | |
| 11577 </description> | |
| 11578 </param> | |
| 11579 </parameters> | |
| 11580 </event> | |
| 11581 | |
| 11582 <event label="Field Access" | |
| 11583 id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63"> | |
| 11584 <description> | |
| 11585 Field access events are generated whenever a thread accesses | |
| 11586 a field that was designated as a watchpoint | |
| 11587 with <functionlink id="SetFieldAccessWatch"></functionlink>. | |
| 11588 The <code>method</code> and <code>location</code> | |
| 11589 parameters uniquely identify the current location and allow | |
| 11590 the mapping to source file and line number when that information is | |
| 11591 available. | |
| 11592 </description> | |
| 11593 <origin>jvmdi</origin> | |
| 11594 <capabilities> | |
| 11595 <required id="can_generate_field_access_events"></required> | |
| 11596 </capabilities> | |
| 11597 <parameters> | |
| 11598 <param id="jni_env"> | |
| 11599 <outptr> | |
| 11600 <struct>JNIEnv</struct> | |
| 11601 </outptr> | |
| 11602 <description> | |
| 11603 The JNI environment of the event (current) thread | |
| 11604 </description> | |
| 11605 </param> | |
| 11606 <param id="thread"> | |
| 11607 <jthread/> | |
| 11608 <description> | |
| 11609 Thread accessing the field | |
| 11610 </description> | |
| 11611 </param> | |
| 11612 <param id="klass"> | |
| 11613 <jclass method="method"/> | |
| 11614 <description> | |
| 11615 Class of the method where the access is occurring | |
| 11616 </description> | |
| 11617 </param> | |
| 11618 <param id="method"> | |
| 11619 <jmethodID class="klass"/> | |
| 11620 <description> | |
| 11621 Method where the access is occurring | |
| 11622 </description> | |
| 11623 </param> | |
| 11624 <param id="location"> | |
| 11625 <jlocation/> | |
| 11626 <description> | |
| 11627 Location where the access is occurring | |
| 11628 </description> | |
| 11629 </param> | |
| 11630 <param id="field_klass"> | |
| 11631 <jclass field="field"/> | |
| 11632 <description> | |
| 11633 Class of the field being accessed | |
| 11634 </description> | |
| 11635 </param> | |
| 11636 <param id="object"> | |
| 11637 <jobject/> | |
| 11638 <description> | |
| 11639 Object with the field being accessed if the field is an | |
| 11640 instance field; <code>NULL</code> otherwise | |
| 11641 </description> | |
| 11642 </param> | |
| 11643 <param id="field"> | |
| 11644 <jfieldID class="field_klass"/> | |
| 11645 <description> | |
| 11646 Field being accessed | |
| 11647 </description> | |
| 11648 </param> | |
| 11649 </parameters> | |
| 11650 </event> | |
| 11651 | |
| 11652 <event label="Field Modification" | |
| 11653 id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64"> | |
| 11654 <description> | |
| 11655 Field modification events are generated whenever a thread modifies | |
| 11656 a field that was designated as a watchpoint | |
| 11657 with <functionlink id="SetFieldModificationWatch"></functionlink>. | |
| 11658 The <code>method</code> and <code>location</code> | |
| 11659 parameters uniquely identify the current location and allow | |
| 11660 the mapping to source file and line number when that information is | |
| 11661 available. | |
| 11662 </description> | |
| 11663 <origin>jvmdi</origin> | |
| 11664 <capabilities> | |
| 11665 <required id="can_generate_field_modification_events"></required> | |
| 11666 </capabilities> | |
| 11667 <parameters> | |
| 11668 <param id="jni_env"> | |
| 11669 <outptr> | |
| 11670 <struct>JNIEnv</struct> | |
| 11671 </outptr> | |
| 11672 <description> | |
| 11673 The JNI environment of the event (current) thread | |
| 11674 </description> | |
| 11675 </param> | |
| 11676 <param id="thread"> | |
| 11677 <jthread/> | |
| 11678 <description> | |
| 11679 Thread modifying the field | |
| 11680 </description> | |
| 11681 </param> | |
| 11682 <param id="klass"> | |
| 11683 <jclass method="method"/> | |
| 11684 <description> | |
| 11685 Class of the method where the modification is occurring | |
| 11686 </description> | |
| 11687 </param> | |
| 11688 <param id="method"> | |
| 11689 <jmethodID class="klass"/> | |
| 11690 <description> | |
| 11691 Method where the modification is occurring | |
| 11692 </description> | |
| 11693 </param> | |
| 11694 <param id="location"> | |
| 11695 <jlocation/> | |
| 11696 <description> | |
| 11697 Location where the modification is occurring | |
| 11698 </description> | |
| 11699 </param> | |
| 11700 <param id="field_klass"> | |
| 11701 <jclass field="field"/> | |
| 11702 <description> | |
| 11703 Class of the field being modified | |
| 11704 </description> | |
| 11705 </param> | |
| 11706 <param id="object"> | |
| 11707 <jobject/> | |
| 11708 <description> | |
| 11709 Object with the field being modified if the field is an | |
| 11710 instance field; <code>NULL</code> otherwise | |
| 11711 </description> | |
| 11712 </param> | |
| 11713 <param id="field"> | |
| 11714 <jfieldID class="field_klass"/> | |
| 11715 <description> | |
| 11716 Field being modified | |
| 11717 </description> | |
| 11718 </param> | |
| 11719 <param id="signature_type"> | |
| 11720 <char/> | |
| 11721 <description> | |
| 11722 Signature type of the new value | |
| 11723 </description> | |
| 11724 </param> | |
| 11725 <param id="new_value"> | |
| 11726 <jvalue/> | |
| 11727 <description> | |
| 11728 The new value | |
| 11729 </description> | |
| 11730 </param> | |
| 11731 </parameters> | |
| 11732 </event> | |
| 11733 | |
| 11734 <event label="Frame Pop" | |
| 11735 id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61"> | |
| 11736 <description> | |
| 11737 Frame pop events are generated upon exit from a single method | |
| 11738 in a single frame as specified | |
| 11739 in a call to <functionlink id="NotifyFramePop"></functionlink>. | |
| 11740 This is true whether termination is caused by | |
| 11741 executing its return instruction | |
| 11742 or by throwing an exception to its caller | |
| 11743 (see <paramlink id="was_popped_by_exception"></paramlink>). | |
| 11744 However, frame pops caused by the <functionlink id="PopFrame"/> | |
| 11745 function are not reported. | |
| 11746 <p/> | |
| 11747 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
| 11748 identifies the executable location in the returning method, | |
| 11749 immediately prior to the return. | |
| 11750 </description> | |
| 11751 <origin>jvmdi</origin> | |
| 11752 <capabilities> | |
| 11753 <required id="can_generate_frame_pop_events"></required> | |
| 11754 </capabilities> | |
| 11755 <parameters> | |
| 11756 <param id="jni_env"> | |
| 11757 <outptr> | |
| 11758 <struct>JNIEnv</struct> | |
| 11759 </outptr> | |
| 11760 <description> | |
| 11761 The JNI environment of the event (current) thread | |
| 11762 </description> | |
| 11763 </param> | |
| 11764 <param id="thread"> | |
| 11765 <jthread/> | |
| 11766 <description> | |
| 11767 Thread that is popping the frame | |
| 11768 </description> | |
| 11769 </param> | |
| 11770 <param id="klass"> | |
| 11771 <jclass method="method"/> | |
| 11772 <description> | |
| 11773 Class of the method being popped | |
| 11774 </description> | |
| 11775 </param> | |
| 11776 <param id="method"> | |
| 11777 <jmethodID class="klass"/> | |
| 11778 <description> | |
| 11779 Method being popped | |
| 11780 </description> | |
| 11781 </param> | |
| 11782 <param id="was_popped_by_exception"> | |
| 11783 <jboolean/> | |
| 11784 <description> | |
| 11785 True if frame was popped by a thrown exception. | |
| 11786 False if method exited through its return instruction. | |
| 11787 </description> | |
| 11788 </param> | |
| 11789 </parameters> | |
| 11790 </event> | |
| 11791 | |
| 11792 <event label="Method Entry" | |
| 11793 id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65"> | |
| 11794 <description> | |
| 11795 Method entry events are generated upon entry of Java | |
| 11796 programming language methods (including native methods). | |
| 11797 <p/> | |
| 11798 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
| 11799 identifies the initial executable location in | |
| 11800 the method. | |
| 11801 <p/> | |
| 11802 Enabling method | |
| 11803 entry or exit events will significantly degrade performance on many platforms and is thus | |
| 11804 not advised for performance critical usage (such as profiling). | |
| 11805 <internallink id="bci">Bytecode instrumentation</internallink> should be | |
| 11806 used in these cases. | |
| 11807 </description> | |
| 11808 <origin>jvmdi</origin> | |
| 11809 <capabilities> | |
| 11810 <required id="can_generate_method_entry_events"></required> | |
| 11811 </capabilities> | |
| 11812 <parameters> | |
| 11813 <param id="jni_env"> | |
| 11814 <outptr> | |
| 11815 <struct>JNIEnv</struct> | |
| 11816 </outptr> | |
| 11817 <description> | |
| 11818 The JNI environment of the event (current) thread | |
| 11819 </description> | |
| 11820 </param> | |
| 11821 <param id="thread"> | |
| 11822 <jthread/> | |
| 11823 <description> | |
| 11824 Thread entering the method | |
| 11825 </description> | |
| 11826 </param> | |
| 11827 <param id="klass"> | |
| 11828 <jclass method="method"/> | |
| 11829 <description> | |
| 11830 Class of the method being entered | |
| 11831 </description> | |
| 11832 </param> | |
| 11833 <param id="method"> | |
| 11834 <jmethodID class="klass"/> | |
| 11835 <description> | |
| 11836 Method being entered | |
| 11837 </description> | |
| 11838 </param> | |
| 11839 </parameters> | |
| 11840 </event> | |
| 11841 | |
| 11842 <event label="Method Exit" | |
| 11843 id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66"> | |
| 11844 <description> | |
| 11845 Method exit events are generated upon exit from Java | |
| 11846 programming language methods (including native methods). | |
| 11847 This is true whether termination is caused by | |
| 11848 executing its return instruction | |
| 11849 or by throwing an exception to its caller | |
| 11850 (see <paramlink id="was_popped_by_exception"></paramlink>). | |
| 11851 <p/> | |
| 11852 The <code>method</code> field uniquely identifies the | |
| 11853 method being entered or exited. The <code>frame</code> field provides | |
| 11854 access to the stack frame for the method. | |
| 11855 <p/> | |
| 11856 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
| 11857 identifies the executable location in the returning method | |
| 11858 immediately prior to the return. | |
| 11859 <p/> | |
| 11860 Enabling method | |
| 11861 entry or exit events will significantly degrade performance on many platforms and is thus | |
| 11862 not advised for performance critical usage (such as profiling). | |
| 11863 <internallink id="bci">Bytecode instrumentation</internallink> should be | |
| 11864 used in these cases. | |
| 11865 </description> | |
| 11866 <origin>jvmdi</origin> | |
| 11867 <capabilities> | |
| 11868 <required id="can_generate_method_exit_events"></required> | |
| 11869 </capabilities> | |
| 11870 <parameters> | |
| 11871 <param id="jni_env"> | |
| 11872 <outptr> | |
| 11873 <struct>JNIEnv</struct> | |
| 11874 </outptr> | |
| 11875 <description> | |
| 11876 The JNI environment of the event (current) thread | |
| 11877 </description> | |
| 11878 </param> | |
| 11879 <param id="thread"> | |
| 11880 <jthread/> | |
| 11881 <description> | |
| 11882 Thread exiting the method | |
| 11883 </description> | |
| 11884 </param> | |
| 11885 <param id="klass"> | |
| 11886 <jclass method="method"/> | |
| 11887 <description> | |
| 11888 Class of the method being exited | |
| 11889 </description> | |
| 11890 </param> | |
| 11891 <param id="method"> | |
| 11892 <jmethodID class="klass"/> | |
| 11893 <description> | |
| 11894 Method being exited | |
| 11895 </description> | |
| 11896 </param> | |
| 11897 <param id="was_popped_by_exception"> | |
| 11898 <jboolean/> | |
| 11899 <description> | |
| 11900 True if frame was popped by a thrown exception. | |
| 11901 False if method exited through its return instruction. | |
| 11902 </description> | |
| 11903 </param> | |
| 11904 <param id="return_value"> | |
| 11905 <jvalue/> | |
| 11906 <description> | |
| 11907 The return value of the method being exited. | |
| 11908 Undefined and should not be used if | |
| 11909 <paramlink id="was_popped_by_exception"></paramlink> | |
| 11910 is true. | |
| 11911 </description> | |
| 11912 </param> | |
| 11913 </parameters> | |
| 11914 </event> | |
| 11915 | |
| 11916 <event label="Native Method Bind" phase="any" | |
| 11917 id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67"> | |
| 11918 <description> | |
| 11919 A Native Method Bind event is sent when a VM binds a | |
| 11920 Java programming language native method | |
| 11921 to the address of a function that implements the native method. | |
| 11922 This will occur when the native method is called for the first time | |
| 11923 and also occurs when the JNI function <code>RegisterNatives</code> is called. | |
| 11924 This event allows the bind to be redirected to an agent-specified | |
| 11925 proxy function. | |
| 11926 This event is not sent when the native method is unbound. | |
| 11927 Typically, this proxy function will need to be specific to a | |
| 11928 particular method or, to handle the general case, automatically | |
| 11929 generated assembly code, since after instrumentation code is | |
| 11930 executed the function at the original binding | |
| 11931 address will usually be invoked. | |
| 11932 The original binding can be restored or the redirection changed | |
| 11933 by use of the JNI function <code>RegisterNatives</code>. | |
| 11934 Some events may be sent during the primordial phase, JNI and | |
| 11935 most of <jvmti/> cannot be used at this time but the method and | |
| 11936 address can be saved for use later. | |
| 11937 </description> | |
| 11938 <origin>new</origin> | |
| 11939 <capabilities> | |
| 11940 <required id="can_generate_native_method_bind_events"></required> | |
| 11941 </capabilities> | |
| 11942 <parameters> | |
| 11943 <param id="jni_env"> | |
| 11944 <outptr> | |
| 11945 <struct>JNIEnv</struct> | |
| 11946 </outptr> | |
| 11947 <description> | |
| 11948 The JNI environment of the event (current) thread | |
| 11949 Will be <code>NULL</code> if sent during the primordial | |
| 11950 <functionlink id="GetPhase">phase</functionlink>. | |
| 11951 </description> | |
| 11952 </param> | |
| 11953 <param id="thread"> | |
| 11954 <jthread/> | |
| 11955 <description> | |
| 11956 Thread requesting the bind | |
| 11957 </description> | |
| 11958 </param> | |
| 11959 <param id="klass"> | |
| 11960 <jclass method="method"/> | |
| 11961 <description> | |
| 11962 Class of the method being bound | |
| 11963 </description> | |
| 11964 </param> | |
| 11965 <param id="method"> | |
| 11966 <jmethodID class="klass"/> | |
| 11967 <description> | |
| 11968 Native method being bound | |
| 11969 </description> | |
| 11970 </param> | |
| 11971 <param id="address"> | |
| 11972 <outptr><void/></outptr> | |
| 11973 <description> | |
| 11974 The address the VM is about to bind to--that is, the | |
| 11975 address of the implementation of the native method | |
| 11976 </description> | |
| 11977 </param> | |
| 11978 <param id="new_address_ptr"> | |
| 11979 <agentbuf><void/></agentbuf> | |
| 11980 <description> | |
| 11981 if the referenced address is changed (that is, if | |
| 11982 <code>*new_address_ptr</code> is set), the binding | |
| 11983 will instead be made to the supplied address. | |
| 11984 </description> | |
| 11985 </param> | |
| 11986 </parameters> | |
| 11987 </event> | |
| 11988 | |
| 11989 <event label="Exception" | |
| 11990 id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58"> | |
| 11991 <description> | |
| 11992 Exception events are generated whenever an exception is first detected | |
| 11993 in a Java programming language method. | |
| 11994 Where "exception" means any <code>java.lang.Throwable</code>. | |
| 11995 The exception may have been thrown by a Java programming language or native | |
| 11996 method, but in the case of native methods, the event is not generated | |
| 11997 until the exception is first seen by a Java programming language method. If an exception is | |
| 11998 set and cleared in a native method (and thus is never visible to Java programming language code), | |
| 11999 no exception event is generated. | |
| 12000 <p/> | |
| 12001 The <code>method</code> and <code>location</code> | |
| 12002 parameters uniquely identify the current location | |
| 12003 (where the exception was detected) and allow | |
| 12004 the mapping to source file and line number when that information is | |
| 12005 available. The <code>exception</code> field identifies the thrown | |
| 12006 exception object. The <code>catch_method</code> | |
| 12007 and <code>catch_location</code> identify the location of the catch clause, | |
| 12008 if any, that handles the thrown exception. If there is no such catch clause, | |
| 12009 each field is set to 0. There is no guarantee that the thread will ever | |
| 12010 reach this catch clause. If there are native methods on the call stack | |
| 12011 between the throw location and the catch clause, the exception may | |
| 12012 be reset by one of those native methods. | |
| 12013 Similarly, exceptions that are reported as uncaught (<code>catch_klass</code> | |
| 12014 et al. set to 0) may in fact be caught by native code. | |
| 12015 Agents can check for these occurrences by monitoring | |
| 12016 <eventlink id="ExceptionCatch"></eventlink> events. | |
| 12017 Note that finally clauses are implemented as catch and re-throw. Therefore they | |
| 12018 will be reported in the catch location. | |
| 12019 </description> | |
| 12020 <origin>jvmdi</origin> | |
| 12021 <capabilities> | |
| 12022 <required id="can_generate_exception_events"></required> | |
| 12023 </capabilities> | |
| 12024 <parameters> | |
| 12025 <param id="jni_env"> | |
| 12026 <outptr> | |
| 12027 <struct>JNIEnv</struct> | |
| 12028 </outptr> | |
| 12029 <description> | |
| 12030 The JNI environment of the event (current) thread | |
| 12031 </description> | |
| 12032 </param> | |
| 12033 <param id="thread"> | |
| 12034 <jthread/> | |
| 12035 <description> | |
| 12036 Thread generating the exception | |
| 12037 </description> | |
| 12038 </param> | |
| 12039 <param id="klass"> | |
| 12040 <jclass method="method"/> | |
| 12041 <description> | |
| 12042 Class generating the exception | |
| 12043 </description> | |
| 12044 </param> | |
| 12045 <param id="method"> | |
| 12046 <jmethodID class="klass"/> | |
| 12047 <description> | |
| 12048 Method generating the exception | |
| 12049 </description> | |
| 12050 </param> | |
| 12051 <param id="location"> | |
| 12052 <jlocation/> | |
| 12053 <description> | |
| 12054 Location where exception occurred | |
| 12055 </description> | |
| 12056 </param> | |
| 12057 <param id="exception"> | |
| 12058 <jobject/> | |
| 12059 <description> | |
| 12060 The exception being thrown | |
| 12061 </description> | |
| 12062 </param> | |
| 12063 <param id="catch_klass"> | |
| 12064 <jclass method="catch_method"/> | |
| 12065 <description> | |
| 12066 Class that will catch the exception, or <code>NULL</code> if no known catch | |
| 12067 </description> | |
| 12068 </param> | |
| 12069 <param id="catch_method"> | |
| 12070 <jmethodID class="catch_klass"/> | |
| 12071 <description> | |
| 12072 Method that will catch the exception, or <code>NULL</code> if no known catch | |
| 12073 </description> | |
| 12074 </param> | |
| 12075 <param id="catch_location"> | |
| 12076 <jlocation/> | |
| 12077 <description> | |
| 12078 location which will catch the exception or zero if no known catch | |
| 12079 </description> | |
| 12080 </param> | |
| 12081 </parameters> | |
| 12082 </event> | |
| 12083 | |
| 12084 <event label="Exception Catch" | |
| 12085 id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59"> | |
| 12086 <description> | |
| 12087 Exception catch events are generated whenever a thrown exception is caught. | |
| 12088 Where "exception" means any <code>java.lang.Throwable</code>. | |
| 12089 If the exception is caught in a Java programming language method, the event is generated | |
| 12090 when the catch clause is reached. If the exception is caught in a native | |
| 12091 method, the event is generated as soon as control is returned to a Java programming language | |
| 12092 method. Exception catch events are generated for any exception for which | |
| 12093 a throw was detected in a Java programming language method. | |
| 12094 Note that finally clauses are implemented as catch and re-throw. Therefore they | |
| 12095 will generate exception catch events. | |
| 12096 <p/> | |
| 12097 The <code>method</code> and <code>location</code> | |
| 12098 parameters uniquely identify the current location | |
| 12099 and allow the mapping to source file and line number when that information is | |
| 12100 available. For exceptions caught in a Java programming language method, the | |
| 12101 <code>exception</code> object identifies the exception object. Exceptions | |
| 12102 caught in native methods are not necessarily available by the time the | |
| 12103 exception catch is reported, so the <code>exception</code> field is set | |
| 12104 to <code>NULL</code>. | |
| 12105 </description> | |
| 12106 <origin>jvmdi</origin> | |
| 12107 <capabilities> | |
| 12108 <required id="can_generate_exception_events"></required> | |
| 12109 </capabilities> | |
| 12110 <parameters> | |
| 12111 <param id="jni_env"> | |
| 12112 <outptr> | |
| 12113 <struct>JNIEnv</struct> | |
| 12114 </outptr> | |
| 12115 <description> | |
| 12116 The JNI environment of the event (current) thread | |
| 12117 </description> | |
| 12118 </param> | |
| 12119 <param id="thread"> | |
| 12120 <jthread/> | |
| 12121 <description> | |
| 12122 Thread catching the exception | |
| 12123 </description> | |
| 12124 </param> | |
| 12125 <param id="klass"> | |
| 12126 <jclass method="method"/> | |
| 12127 <description> | |
| 12128 Class catching the exception | |
| 12129 </description> | |
| 12130 </param> | |
| 12131 <param id="method"> | |
| 12132 <jmethodID class="klass"/> | |
| 12133 <description> | |
| 12134 Method catching the exception | |
| 12135 </description> | |
| 12136 </param> | |
| 12137 <param id="location"> | |
| 12138 <jlocation/> | |
| 12139 <description> | |
| 12140 Location where exception is being caught | |
| 12141 </description> | |
| 12142 </param> | |
| 12143 <param id="exception"> | |
| 12144 <jobject/> | |
| 12145 <description> | |
| 12146 Exception being caught | |
| 12147 </description> | |
| 12148 </param> | |
| 12149 </parameters> | |
| 12150 </event> | |
| 12151 | |
| 12152 <event label="Thread Start" | |
| 12153 id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start"> | |
| 12154 <description> | |
| 12155 Thread start events are generated by a new thread before its initial | |
| 12156 method executes. | |
| 12157 <p/> | |
| 12158 A thread may be listed in the array returned by | |
| 12159 <functionlink id="GetAllThreads"></functionlink> | |
| 12160 before its thread start event is generated. | |
| 12161 It is possible for other events to be generated | |
| 12162 on a thread before its thread start event. | |
| 12163 <p/> | |
| 12164 The event is sent on the newly started <paramlink id="thread"></paramlink>. | |
| 12165 </description> | |
| 12166 <origin>jvmdi</origin> | |
| 12167 <capabilities> | |
| 12168 </capabilities> | |
| 12169 <parameters> | |
| 12170 <param id="jni_env"> | |
| 12171 <outptr> | |
| 12172 <struct>JNIEnv</struct> | |
| 12173 </outptr> | |
| 12174 <description> | |
| 12175 The JNI environment of the event (current) thread. | |
| 12176 </description> | |
| 12177 </param> | |
| 12178 <param id="thread"> | |
| 12179 <jthread/> | |
| 12180 <description> | |
| 12181 Thread starting | |
| 12182 </description> | |
| 12183 </param> | |
| 12184 </parameters> | |
| 12185 </event> | |
| 12186 | |
| 12187 <event label="Thread End" | |
| 12188 id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start"> | |
| 12189 <description> | |
| 12190 Thread end events are generated by a terminating thread | |
| 12191 after its initial method has finished execution. | |
| 12192 <p/> | |
| 12193 A thread may be listed in the array returned by | |
| 12194 <functionlink id="GetAllThreads"></functionlink> | |
| 12195 after its thread end event is generated. | |
| 12196 No events are generated on a thread | |
| 12197 after its thread end event. | |
| 12198 <p/> | |
| 12199 The event is sent on the dying <paramlink id="thread"></paramlink>. | |
| 12200 </description> | |
| 12201 <origin>jvmdi</origin> | |
| 12202 <capabilities> | |
| 12203 </capabilities> | |
| 12204 <parameters> | |
| 12205 <param id="jni_env"> | |
| 12206 <outptr> | |
| 12207 <struct>JNIEnv</struct> | |
| 12208 </outptr> | |
| 12209 <description> | |
| 12210 The JNI environment of the event (current) thread. | |
| 12211 </description> | |
| 12212 </param> | |
| 12213 <param id="thread"> | |
| 12214 <jthread/> | |
| 12215 <description> | |
| 12216 Thread ending | |
| 12217 </description> | |
| 12218 </param> | |
| 12219 </parameters> | |
| 12220 </event> | |
| 12221 | |
| 12222 <event label="Class Load" | |
| 12223 id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55"> | |
| 12224 <description> | |
| 12225 A class load event is generated when a class is first loaded. The order | |
| 12226 of class load events generated by a particular thread are guaranteed | |
| 12227 to match the order of class loading within that thread. | |
| 12228 Array class creation does not generate a class load event. | |
| 12229 The creation of a primitive class (for example, java.lang.Integer.TYPE) | |
| 12230 does not generate a class load event. | |
| 12231 <p/> | |
| 12232 This event is sent at an early stage in loading the class. As | |
| 12233 a result the class should be used carefully. Note, for example, | |
| 12234 that methods and fields are not yet loaded, so queries for methods, | |
| 12235 fields, subclasses, and so on will not give correct results. | |
| 12236 See "Loading of Classes and Interfaces" in the <i>Java Language | |
| 12237 Specification</i>. For most | |
| 12238 purposes the <eventlink id="ClassPrepare"></eventlink> event will | |
| 12239 be more useful. | |
| 12240 </description> | |
| 12241 <origin>jvmdi</origin> | |
| 12242 <capabilities> | |
| 12243 </capabilities> | |
| 12244 <parameters> | |
| 12245 <param id="jni_env"> | |
| 12246 <outptr> | |
| 12247 <struct>JNIEnv</struct> | |
| 12248 </outptr> | |
| 12249 <description> | |
| 12250 The JNI environment of the event (current) thread | |
| 12251 </description> | |
| 12252 </param> | |
| 12253 <param id="thread"> | |
| 12254 <jthread/> | |
| 12255 <description> | |
| 12256 Thread loading the class | |
| 12257 </description> | |
| 12258 </param> | |
| 12259 <param id="klass"> | |
| 12260 <jclass/> | |
| 12261 <description> | |
| 12262 Class being loaded | |
| 12263 </description> | |
| 12264 </param> | |
| 12265 </parameters> | |
| 12266 </event> | |
| 12267 | |
| 12268 <elide> | |
| 12269 <event label="Class Unload" | |
| 12270 id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57"> | |
| 12271 <description> | |
| 12272 A class unload event is generated when the class is about to be unloaded. | |
| 12273 Class unload events take place during garbage collection and must be | |
| 12274 handled extremely carefully. The garbage collector holds many locks | |
| 12275 and has suspended all other threads, so the event handler cannot depend | |
| 12276 on the ability to acquire any locks. The class unload event handler should | |
| 12277 do as little as possible, perhaps by queuing information to be processed | |
| 12278 later. In particular, the <code>jclass</code> should be used only in | |
| 12279 the JNI function <code>isSameObject</code> or in the following <jvmti/> functions: | |
| 12280 <ul> | |
| 12281 <li><functionlink id="GetClassSignature"></functionlink></li> | |
| 12282 <li><functionlink id="GetSourceFileName"></functionlink></li> | |
| 12283 <li><functionlink id="IsInterface"></functionlink></li> | |
| 12284 <li><functionlink id="IsArrayClass"></functionlink></li> | |
| 12285 </ul> | |
| 12286 </description> | |
| 12287 <origin>jvmdi</origin> | |
| 12288 <capabilities> | |
| 12289 </capabilities> | |
| 12290 <parameters> | |
| 12291 <param id="jni_env"> | |
| 12292 <outptr> | |
| 12293 <struct>JNIEnv</struct> | |
| 12294 </outptr> | |
| 12295 <description> | |
| 12296 The JNI environment of the event (current) thread | |
| 12297 </description> | |
| 12298 </param> | |
| 12299 <param id="thread"> | |
| 12300 <jthread/> | |
| 12301 <description> | |
| 12302 Thread generating the class unload | |
| 12303 </description> | |
| 12304 </param> | |
| 12305 <param id="klass"> | |
| 12306 <jclass/> | |
| 12307 <description> | |
| 12308 Class being unloaded | |
| 12309 </description> | |
| 12310 </param> | |
| 12311 </parameters> | |
| 12312 </event> | |
| 12313 </elide> | |
| 12314 | |
| 12315 <event label="Class Prepare" | |
| 12316 id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56"> | |
| 12317 <description> | |
| 12318 A class prepare event is generated when class preparation is complete. | |
| 12319 At this point, class fields, methods, and implemented interfaces are | |
| 12320 available, and no code from the class has been executed. Since array | |
| 12321 classes never have fields or methods, class prepare events are not | |
| 12322 generated for them. Class prepare events are not generated for | |
| 12323 primitive classes (for example, <code>java.lang.Integer.TYPE</code>). | |
| 12324 </description> | |
| 12325 <origin>jvmdi</origin> | |
| 12326 <capabilities> | |
| 12327 </capabilities> | |
| 12328 <parameters> | |
| 12329 <param id="jni_env"> | |
| 12330 <outptr> | |
| 12331 <struct>JNIEnv</struct> | |
| 12332 </outptr> | |
| 12333 <description> | |
| 12334 The JNI environment of the event (current) thread | |
| 12335 </description> | |
| 12336 </param> | |
| 12337 <param id="thread"> | |
| 12338 <jthread/> | |
| 12339 <description> | |
| 12340 Thread generating the class prepare | |
| 12341 </description> | |
| 12342 </param> | |
| 12343 <param id="klass"> | |
| 12344 <jclass/> | |
| 12345 <description> | |
| 12346 Class being prepared | |
| 12347 </description> | |
| 12348 </param> | |
| 12349 </parameters> | |
| 12350 </event> | |
| 12351 | |
| 12352 <event label="Class File Load Hook" phase="any" | |
| 12353 id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54"> | |
| 12354 <description> | |
| 12355 This event is sent when the VM obtains class file data, | |
| 12356 but before it constructs | |
| 12357 the in-memory representation for that class. | |
| 12358 This event is also sent when the class is being modified by the | |
| 12359 <functionlink id="RetransformClasses"/> function or | |
| 12360 the <functionlink id="RedefineClasses"/> function, | |
| 12361 called in any <jvmti/> environment. | |
| 12362 The agent can instrument | |
| 12363 the existing class file data sent by the VM to include profiling/debugging hooks. | |
| 12364 See the description of | |
| 12365 <internallink id="bci">bytecode instrumentation</internallink> | |
| 12366 for usage information. | |
| 12367 <p/> | |
| 12368 This event may be sent before the VM is initialized (the primordial | |
| 12369 <functionlink id="GetPhase">phase</functionlink>). During this time | |
| 12370 no VM resources should be created. Some classes might not be compatible | |
| 12371 with the function (eg. ROMized classes) and this event will not be | |
| 12372 generated for these classes. | |
| 12373 <p/> | |
| 12374 The agent must allocate the space for the modified | |
| 12375 class file data buffer | |
| 12376 using the memory allocation function | |
| 12377 <functionlink id="Allocate"></functionlink> because the | |
| 12378 VM is responsible for freeing the new class file data buffer | |
| 12379 using <functionlink id="Deallocate"></functionlink>. | |
| 12380 Note that <functionlink id="Allocate"></functionlink> | |
| 12381 is permitted during the primordial phase. | |
| 12382 <p/> | |
| 12383 If the agent wishes to modify the class file, it must set | |
| 12384 <code>new_class_data</code> to point | |
| 12385 to the newly instrumented class file data buffer and set | |
| 12386 <code>new_class_data_len</code> to the length of that | |
| 12387 buffer before returning | |
| 12388 from this call. If no modification is desired, the agent simply | |
| 12389 does not set <code>new_class_data</code>. If multiple agents | |
| 12390 have enabled this event the results are chained. That is, if | |
| 12391 <code>new_class_data</code> has been set, it becomes the | |
| 12392 <code>class_data</code> for the next agent. | |
| 12393 <p/> | |
| 12394 The order that this event is sent to each environment differs | |
| 12395 from other events. | |
| 12396 This event is sent to environments in the following order: | |
| 12397 <ul> | |
| 12398 <li><fieldlink id="can_retransform_classes" | |
| 12399 struct="jvmtiCapabilities">retransformation | |
| 12400 incapable</fieldlink> | |
| 12401 environments, in the | |
| 12402 order in which they were created | |
| 12403 </li> | |
| 12404 <li><fieldlink id="can_retransform_classes" | |
| 12405 struct="jvmtiCapabilities">retransformation | |
| 12406 capable</fieldlink> | |
| 12407 environments, in the | |
| 12408 order in which they were created | |
| 12409 </li> | |
| 12410 </ul> | |
| 12411 When triggered by <functionlink id="RetransformClasses"/>, | |
| 12412 this event is sent only to <fieldlink id="can_retransform_classes" | |
| 12413 struct="jvmtiCapabilities">retransformation | |
| 12414 capable</fieldlink> | |
| 12415 environments. | |
| 12416 </description> | |
| 12417 <origin>jvmpi</origin> | |
| 12418 <capabilities> | |
| 12419 <capability id="can_generate_all_class_hook_events"></capability> | |
| 12420 </capabilities> | |
| 12421 <parameters> | |
| 12422 <param id="jni_env"> | |
| 12423 <outptr> | |
| 12424 <struct>JNIEnv</struct> | |
| 12425 </outptr> | |
| 12426 <description> | |
| 12427 The JNI environment of the event (current) thread. | |
| 12428 Will be <code>NULL</code> if sent during the primordial | |
| 12429 <functionlink id="GetPhase">phase</functionlink>. | |
| 12430 </description> | |
| 12431 </param> | |
| 12432 <param id="class_being_redefined"> | |
| 12433 <jclass/> | |
| 12434 <description> | |
| 12435 The class being | |
| 12436 <functionlink id="RedefineClasses">redefined</functionlink> or | |
| 12437 <functionlink id="RetransformClasses">retransformed</functionlink>. | |
| 12438 <code>NULL</code> if sent by class load. | |
| 12439 </description> | |
| 12440 </param> | |
| 12441 <param id="loader"> | |
| 12442 <jobject/> | |
| 12443 <description> | |
| 12444 The class loader loading the class. | |
| 12445 <code>NULL</code> if the bootstrap class loader. | |
| 12446 </description> | |
| 12447 </param> | |
| 12448 <param id="name"> | |
| 12449 <vmbuf><char/></vmbuf> | |
| 12450 <description> | |
| 12451 Name of class being loaded as a VM internal qualified name | |
| 12452 (for example, "java/util/List"), encoded as a | |
| 12453 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 12454 Note: if the class is defined with a <code>NULL</code> name or | |
| 12455 without a name specified, <code>name</code> will be <code>NULL</code>. | |
| 12456 </description> | |
| 12457 </param> | |
| 12458 <param id="protection_domain"> | |
| 12459 <jobject/> | |
| 12460 <description> | |
| 12461 The <code>ProtectionDomain</code> of the class. | |
| 12462 </description> | |
| 12463 </param> | |
| 12464 <param id="class_data_len"> | |
| 12465 <jint/> | |
| 12466 <description> | |
| 12467 Length of current class file data buffer. | |
| 12468 </description> | |
| 12469 </param> | |
| 12470 <param id="class_data"> | |
| 12471 <vmbuf><uchar/></vmbuf> | |
| 12472 <description> | |
| 12473 Pointer to the current class file data buffer. | |
| 12474 </description> | |
| 12475 </param> | |
| 12476 <param id="new_class_data_len"> | |
| 12477 <outptr><jint/></outptr> | |
| 12478 <description> | |
| 12479 Pointer to the length of the new class file data buffer. | |
| 12480 </description> | |
| 12481 </param> | |
| 12482 <param id="new_class_data"> | |
| 12483 <agentbuf incount="new_class_data_len"><uchar/></agentbuf> | |
| 12484 <description> | |
| 12485 Pointer to the pointer to the instrumented class file data buffer. | |
| 12486 </description> | |
| 12487 </param> | |
| 12488 </parameters> | |
| 12489 </event> | |
| 12490 | |
| 12491 <event label="VM Start Event" | |
| 12492 id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start"> | |
| 12493 <description> | |
| 12494 The VM initialization event signals the start of the VM. | |
| 12495 At this time JNI is live but the VM is not yet fully initialized. | |
| 12496 Once this event is generated, the agent is free to call any JNI function. | |
| 12497 This event signals the beginning of the start phase, | |
| 12498 <jvmti/> functions permitted in the start phase may be called. | |
| 12499 <p/> | |
| 12500 In the case of VM start-up failure, this event will not be sent. | |
| 12501 </description> | |
| 12502 <origin>jvmdi</origin> | |
| 12503 <capabilities> | |
| 12504 </capabilities> | |
| 12505 <parameters> | |
| 12506 <param id="jni_env"> | |
| 12507 <outptr> | |
| 12508 <struct>JNIEnv</struct> | |
| 12509 </outptr> | |
| 12510 <description> | |
| 12511 The JNI environment of the event (current) thread. | |
| 12512 </description> | |
| 12513 </param> | |
| 12514 </parameters> | |
| 12515 </event> | |
| 12516 | |
| 12517 <event label="VM Initialization Event" | |
| 12518 id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50"> | |
| 12519 <description> | |
| 12520 The VM initialization event signals the completion of VM initialization. Once | |
| 12521 this event is generated, the agent is free to call any JNI or <jvmti/> | |
| 12522 function. The VM initialization event can be preceded by or can be concurrent | |
| 12523 with other events, but | |
| 12524 the preceding events should be handled carefully, if at all, because the | |
| 12525 VM has not completed its initialization. The thread start event for the | |
| 12526 main application thread is guaranteed not to occur until after the | |
| 12527 handler for the VM initialization event returns. | |
| 12528 <p/> | |
| 12529 In the case of VM start-up failure, this event will not be sent. | |
| 12530 </description> | |
| 12531 <origin>jvmdi</origin> | |
| 12532 <capabilities> | |
| 12533 </capabilities> | |
| 12534 <parameters> | |
| 12535 <param id="jni_env"> | |
| 12536 <outptr> | |
| 12537 <struct>JNIEnv</struct> | |
| 12538 </outptr> | |
| 12539 <description> | |
| 12540 The JNI environment of the event (current) thread. | |
| 12541 </description> | |
| 12542 </param> | |
| 12543 <param id="thread"> | |
| 12544 <jthread/> | |
| 12545 <description> | |
| 12546 The initial thread | |
| 12547 </description> | |
| 12548 </param> | |
| 12549 </parameters> | |
| 12550 </event> | |
| 12551 | |
| 12552 <event label="VM Death Event" | |
| 12553 id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51"> | |
| 12554 <description> | |
| 12555 The VM death event notifies the agent of the termination of the VM. | |
| 12556 No events will occur after the VMDeath event. | |
| 12557 <p/> | |
| 12558 In the case of VM start-up failure, this event will not be sent. | |
| 12559 Note that <internallink id="onunload">Agent_OnUnload</internallink> | |
| 12560 will still be called in these cases. | |
| 12561 </description> | |
| 12562 <origin>jvmdi</origin> | |
| 12563 <capabilities> | |
| 12564 </capabilities> | |
| 12565 <parameters> | |
| 12566 <param id="jni_env"> | |
| 12567 <outptr> | |
| 12568 <struct>JNIEnv</struct> | |
| 12569 </outptr> | |
| 12570 <description> | |
| 12571 The JNI environment of the event (current) thread | |
| 12572 </description> | |
| 12573 </param> | |
| 12574 </parameters> | |
| 12575 </event> | |
| 12576 | |
| 12577 <event label="Compiled Method Load" | |
| 12578 id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68"> | |
| 12579 <description> | |
| 12580 Sent when a method is compiled and loaded into memory by the VM. | |
| 12581 If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent. | |
| 12582 If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent, | |
| 12583 followed by a new <code>CompiledMethodLoad</code> event. | |
| 12584 Note that a single method may have multiple compiled forms, and that | |
| 12585 this event will be sent for each form. | |
| 12586 Note also that several methods may be inlined into a single | |
| 12587 address range, and that this event will be sent for each method. | |
| 12588 <p/> | |
| 12589 These events can be sent after their initial occurrence with | |
| 12590 <functionlink id="GenerateEvents"></functionlink>. | |
| 12591 </description> | |
| 12592 <origin>jvmpi</origin> | |
| 12593 <typedef id="jvmtiAddrLocationMap" label="Native address to location entry"> | |
| 12594 <field id="start_address"> | |
| 12595 <vmbuf><void/></vmbuf> | |
| 12596 <description> | |
| 12597 Starting native address of code corresponding to a location | |
| 12598 </description> | |
| 12599 </field> | |
| 12600 <field id="location"> | |
| 12601 <jlocation/> | |
| 12602 <description> | |
| 12603 Corresponding location. See | |
| 12604 <functionlink id="GetJLocationFormat"></functionlink> | |
| 12605 for the meaning of location. | |
| 12606 </description> | |
| 12607 </field> | |
| 12608 </typedef> | |
| 12609 <capabilities> | |
| 12610 <required id="can_generate_compiled_method_load_events"></required> | |
| 12611 </capabilities> | |
| 12612 <parameters> | |
| 12613 <param id="klass"> | |
| 12614 <jclass method="method"/> | |
| 12615 <description> | |
| 12616 Class of the method being compiled and loaded | |
| 12617 </description> | |
| 12618 </param> | |
| 12619 <param id="method"> | |
| 12620 <jmethodID class="klass"/> | |
| 12621 <description> | |
| 12622 Method being compiled and loaded | |
| 12623 </description> | |
| 12624 </param> | |
| 12625 <param id="code_size"> | |
| 12626 <jint/> | |
| 12627 <description> | |
| 12628 Size of compiled code | |
| 12629 </description> | |
| 12630 </param> | |
| 12631 <param id="code_addr"> | |
| 12632 <vmbuf><void/></vmbuf> | |
| 12633 <description> | |
| 12634 Address where compiled method code is loaded | |
| 12635 </description> | |
| 12636 </param> | |
| 12637 <param id="map_length"> | |
| 12638 <jint/> | |
| 12639 <description> | |
| 12640 Number of <typelink id="jvmtiAddrLocationMap"></typelink> | |
| 12641 entries in the address map. | |
| 12642 Zero if mapping information cannot be supplied. | |
| 12643 </description> | |
| 12644 </param> | |
| 12645 <param id="map"> | |
| 12646 <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf> | |
| 12647 <description> | |
| 12648 Map from native addresses to location. | |
| 12649 The native address range of each entry is from | |
| 12650 <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink> | |
| 12651 to <code>start_address-1</code> of the next entry. | |
| 12652 <code>NULL</code> if mapping information cannot be supplied. | |
| 12653 </description> | |
| 12654 </param> | |
| 12655 <param id="compile_info"> | |
| 12656 <vmbuf><void/></vmbuf> | |
| 12657 <description> | |
| 12658 VM-specific compilation information. | |
| 12659 The referenced compile information is managed by the VM | |
| 12660 and must not depend on the agent for collection. | |
| 12661 A VM implementation defines the content and lifetime | |
| 12662 of the information. | |
| 12663 </description> | |
| 12664 </param> | |
| 12665 </parameters> | |
| 12666 </event> | |
| 12667 | |
| 12668 <event label="Compiled Method Unload" | |
| 12669 id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69"> | |
| 12670 <description> | |
| 12671 Sent when a compiled method is unloaded from memory. | |
| 12672 This event might not be sent on the thread which performed the unload. | |
| 12673 This event may be sent sometime after the unload occurs, but | |
| 12674 will be sent before the memory is reused | |
| 12675 by a newly generated compiled method. This event may be sent after | |
| 12676 the class is unloaded. | |
| 12677 </description> | |
| 12678 <origin>jvmpi</origin> | |
| 12679 <capabilities> | |
| 12680 <required id="can_generate_compiled_method_load_events"></required> | |
| 12681 </capabilities> | |
| 12682 <parameters> | |
| 12683 <param id="klass"> | |
| 12684 <jclass method="method"/> | |
| 12685 <description> | |
| 12686 Class of the compiled method being unloaded. | |
| 12687 </description> | |
| 12688 </param> | |
| 12689 <param id="method"> | |
| 12690 <jmethodID class="klass"/> | |
| 12691 <description> | |
| 12692 Compiled method being unloaded. | |
| 12693 For identification of the compiled method only -- the class | |
| 12694 may be unloaded and therefore the method should not be used | |
| 12695 as an argument to further JNI or <jvmti/> functions. | |
| 12696 </description> | |
| 12697 </param> | |
| 12698 <param id="code_addr"> | |
| 12699 <vmbuf><void/></vmbuf> | |
| 12700 <description> | |
| 12701 Address where compiled method code was loaded. | |
| 12702 For identification of the compiled method only -- | |
| 12703 the space may have been reclaimed. | |
| 12704 </description> | |
| 12705 </param> | |
| 12706 </parameters> | |
| 12707 </event> | |
| 12708 | |
| 12709 <event label="Dynamic Code Generated" phase="any" | |
| 12710 id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70"> | |
| 12711 <description> | |
| 12712 Sent when a component of the virtual machine is generated dynamically. | |
| 12713 This does not correspond to Java programming language code that is | |
| 12714 compiled--see <eventlink id="CompiledMethodLoad"></eventlink>. | |
| 12715 This is for native code--for example, an interpreter that is generated | |
| 12716 differently depending on command-line options. | |
| 12717 <p/> | |
| 12718 Note that this event has no controlling capability. | |
| 12719 If a VM cannot generate these events, it simply does not send any. | |
| 12720 <p/> | |
| 12721 These events can be sent after their initial occurrence with | |
| 12722 <functionlink id="GenerateEvents"></functionlink>. | |
| 12723 </description> | |
| 12724 <origin>jvmpi</origin> | |
| 12725 <capabilities> | |
| 12726 </capabilities> | |
| 12727 <parameters> | |
| 12728 <param id="name"> | |
| 12729 <vmbuf><char/></vmbuf> | |
| 12730 <description> | |
| 12731 Name of the code, encoded as a | |
| 12732 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 12733 Intended for display to an end-user. | |
| 12734 The name might not be unique. | |
| 12735 </description> | |
| 12736 </param> | |
| 12737 <param id="address"> | |
| 12738 <vmbuf><void/></vmbuf> | |
| 12739 <description> | |
| 12740 Native address of the code | |
| 12741 </description> | |
| 12742 </param> | |
| 12743 <param id="length"> | |
| 12744 <jint/> | |
| 12745 <description> | |
| 12746 Length in bytes of the code | |
| 12747 </description> | |
| 12748 </param> | |
| 12749 </parameters> | |
| 12750 </event> | |
| 12751 | |
| 12752 <event label="Data Dump Request" | |
| 12753 id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71"> | |
| 12754 <description> | |
| 12755 Sent by the VM to request the agent to dump its data. This | |
| 12756 is just a hint and the agent need not react to this event. | |
| 12757 This is useful for processing command-line signals from users. For | |
| 12758 example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris | |
| 12759 causes the VM to send this event to the agent. | |
| 12760 </description> | |
| 12761 <origin>jvmpi</origin> | |
| 12762 <capabilities> | |
| 12763 </capabilities> | |
| 12764 <parameters> | |
| 12765 </parameters> | |
| 12766 </event> | |
| 12767 | |
| 12768 <event label="Monitor Contended Enter" | |
| 12769 id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75"> | |
| 12770 <description> | |
| 12771 Sent when a thread is attempting to enter a Java programming language | |
| 12772 monitor already acquired by another thread. | |
| 12773 </description> | |
| 12774 <origin>jvmpi</origin> | |
| 12775 <capabilities> | |
| 12776 <required id="can_generate_monitor_events"></required> | |
| 12777 </capabilities> | |
| 12778 <parameters> | |
| 12779 <param id="jni_env"> | |
| 12780 <outptr> | |
| 12781 <struct>JNIEnv</struct> | |
| 12782 </outptr> | |
| 12783 <description> | |
| 12784 The JNI environment of the event (current) thread | |
| 12785 </description> | |
| 12786 </param> | |
| 12787 <param id="thread"> | |
| 12788 <jthread/> | |
| 12789 <description> | |
| 12790 JNI local reference to the thread | |
| 12791 attempting to enter the monitor | |
| 12792 </description> | |
| 12793 </param> | |
| 12794 <param id="object"> | |
| 12795 <jobject/> | |
| 12796 <description> | |
| 12797 JNI local reference to the monitor | |
| 12798 </description> | |
| 12799 </param> | |
| 12800 </parameters> | |
| 12801 </event> | |
| 12802 | |
| 12803 <event label="Monitor Contended Entered" | |
| 12804 id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76"> | |
| 12805 <description> | |
| 12806 Sent when a thread enters a Java programming language | |
| 12807 monitor after waiting for it to be released by another thread. | |
| 12808 </description> | |
| 12809 <origin>jvmpi</origin> | |
| 12810 <capabilities> | |
| 12811 <required id="can_generate_monitor_events"></required> | |
| 12812 </capabilities> | |
| 12813 <parameters> | |
| 12814 <param id="jni_env"> | |
| 12815 <outptr> | |
| 12816 <struct>JNIEnv</struct> | |
| 12817 </outptr> | |
| 12818 <description> | |
| 12819 The JNI environment of the event (current) thread | |
| 12820 </description> | |
| 12821 </param> | |
| 12822 <param id="thread"> | |
| 12823 <jthread/> | |
| 12824 <description> | |
| 12825 JNI local reference to the thread entering | |
| 12826 the monitor | |
| 12827 </description> | |
| 12828 </param> | |
| 12829 <param id="object"> | |
| 12830 <jobject/> | |
| 12831 <description> | |
| 12832 JNI local reference to the monitor | |
| 12833 </description> | |
| 12834 </param> | |
| 12835 </parameters> | |
| 12836 </event> | |
| 12837 | |
| 12838 <event label="Monitor Wait" | |
| 12839 id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73"> | |
| 12840 <description> | |
| 12841 Sent when a thread is about to wait on an object. | |
| 12842 </description> | |
| 12843 <origin>jvmpi</origin> | |
| 12844 <capabilities> | |
| 12845 <required id="can_generate_monitor_events"></required> | |
| 12846 </capabilities> | |
| 12847 <parameters> | |
| 12848 <param id="jni_env"> | |
| 12849 <outptr> | |
| 12850 <struct>JNIEnv</struct> | |
| 12851 </outptr> | |
| 12852 <description> | |
| 12853 The JNI environment of the event (current) thread | |
| 12854 </description> | |
| 12855 </param> | |
| 12856 <param id="thread"> | |
| 12857 <jthread/> | |
| 12858 <description> | |
| 12859 JNI local reference to the thread about to wait | |
| 12860 </description> | |
| 12861 </param> | |
| 12862 <param id="object"> | |
| 12863 <jobject/> | |
| 12864 <description> | |
| 12865 JNI local reference to the monitor | |
| 12866 </description> | |
| 12867 </param> | |
| 12868 <param id="timeout"> | |
| 12869 <jlong/> | |
| 12870 <description> | |
| 12871 The number of milliseconds the thread will wait | |
| 12872 </description> | |
| 12873 </param> | |
| 12874 </parameters> | |
| 12875 </event> | |
| 12876 | |
| 12877 <event label="Monitor Waited" | |
| 12878 id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74"> | |
| 12879 <description> | |
| 12880 Sent when a thread finishes waiting on an object. | |
| 12881 </description> | |
| 12882 <origin>jvmpi</origin> | |
| 12883 <capabilities> | |
| 12884 <required id="can_generate_monitor_events"></required> | |
| 12885 </capabilities> | |
| 12886 <parameters> | |
| 12887 <param id="jni_env"> | |
| 12888 <outptr> | |
| 12889 <struct>JNIEnv</struct> | |
| 12890 </outptr> | |
| 12891 <description> | |
| 12892 The JNI environment of the event (current) thread | |
| 12893 </description> | |
| 12894 </param> | |
| 12895 <param id="thread"> | |
| 12896 <jthread/> | |
| 12897 <description> | |
| 12898 JNI local reference to the thread that was finished waiting | |
| 12899 </description> | |
| 12900 </param> | |
| 12901 <param id="object"> | |
| 12902 <jobject/> | |
| 12903 <description> | |
| 12904 JNI local reference to the monitor. | |
| 12905 </description> | |
| 12906 </param> | |
| 12907 <param id="timed_out"> | |
| 12908 <jboolean/> | |
| 12909 <description> | |
| 12910 True if the monitor timed out | |
| 12911 </description> | |
| 12912 </param> | |
| 12913 </parameters> | |
| 12914 </event> | |
| 12915 | |
| 12916 <event label="Resource Exhausted" | |
| 12917 id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80" | |
| 12918 since="1.1"> | |
| 12919 <description> | |
| 12920 Sent when a VM resource needed by a running application has been exhausted. | |
| 12921 Except as required by the optional capabilities, the set of resources | |
| 12922 which report exhaustion is implementation dependent. | |
| 12923 <p/> | |
| 12924 The following bit flags define the properties of the resource exhaustion: | |
| 12925 <constants id="jvmtiResourceExhaustionFlags" | |
| 12926 label="Resource Exhaustion Flags" | |
| 12927 kind="bits" | |
| 12928 since="1.1"> | |
| 12929 <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001"> | |
| 12930 After this event returns, the VM will throw a | |
| 12931 <code>java.lang.OutOfMemoryError</code>. | |
| 12932 </constant> | |
| 12933 <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002"> | |
| 12934 The VM was unable to allocate memory from the <tm>Java</tm> | |
| 12935 platform <i>heap</i>. | |
| 12936 The <i>heap</i> is the runtime | |
| 12937 data area from which memory for all class instances and | |
| 12938 arrays are allocated. | |
| 12939 </constant> | |
| 12940 <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004"> | |
| 12941 The VM was unable to create a thread. | |
| 12942 </constant> | |
| 12943 </constants> | |
| 12944 </description> | |
| 12945 <origin>new</origin> | |
| 12946 <capabilities> | |
| 12947 <capability id="can_generate_resource_exhaustion_heap_events"> | |
| 12948 Can generate events when the VM is unable to allocate memory from the | |
| 12949 <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>. | |
| 12950 </capability> | |
| 12951 <capability id="can_generate_resource_exhaustion_threads_events"> | |
| 12952 Can generate events when the VM is unable to | |
| 12953 <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create | |
| 12954 a thread</internallink>. | |
| 12955 </capability> | |
| 12956 </capabilities> | |
| 12957 <parameters> | |
| 12958 <param id="jni_env"> | |
| 12959 <outptr> | |
| 12960 <struct>JNIEnv</struct> | |
| 12961 </outptr> | |
| 12962 <description> | |
| 12963 The JNI environment of the event (current) thread | |
| 12964 </description> | |
| 12965 </param> | |
| 12966 <param id="flags"> | |
| 12967 <jint/> | |
| 12968 <description> | |
| 12969 Flags defining the properties of the of resource exhaustion | |
| 12970 as specified by the | |
| 12971 <internallink id="jvmtiResourceExhaustionFlags">Resource | |
| 12972 Exhaustion Flags</internallink>. | |
| 12973 </description> | |
| 12974 </param> | |
| 12975 <param id="reserved"> | |
| 12976 <vmbuf><void/></vmbuf> | |
| 12977 <description> | |
| 12978 Reserved. | |
| 12979 </description> | |
| 12980 </param> | |
| 12981 <param id="description"> | |
| 12982 <vmbuf><char/></vmbuf> | |
| 12983 <description> | |
| 12984 Description of the resource exhaustion, encoded as a | |
| 12985 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 12986 </description> | |
| 12987 </param> | |
| 12988 </parameters> | |
| 12989 </event> | |
| 12990 | |
| 12991 <event label="VM Object Allocation" | |
| 12992 id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84"> | |
| 12993 <description> | |
| 12994 Sent when a method causes the virtual machine to allocate an | |
| 12995 Object visible to Java programming language code and the | |
| 12996 allocation is not detectable by other intrumentation mechanisms. | |
| 12997 Generally object allocation should be detected by instrumenting | |
| 12998 the bytecodes of allocating methods. | |
| 12999 Object allocation generated in native code by JNI function | |
| 13000 calls should be detected using | |
| 13001 <internallink id="jniIntercept">JNI function interception</internallink>. | |
| 13002 Some methods might not have associated bytecodes and are not | |
| 13003 native methods, they instead are executed directly by the | |
| 13004 VM. These methods should send this event. | |
| 13005 Virtual machines which are incapable of bytecode instrumentation | |
| 13006 for some or all of their methods can send this event. | |
| 13007 <p/> | |
| 13008 Typical examples where this event might be sent: | |
| 13009 <ul> | |
| 13010 <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li> | |
| 13011 <li>Methods not represented by bytecodes -- for example, VM intrinsics and | |
| 13012 J2ME preloaded classes</li> | |
| 13013 </ul> | |
| 13014 Cases where this event would not be generated: | |
| 13015 <ul> | |
| 13016 <li>Allocation due to bytecodes -- for example, the <code>new</code> | |
| 13017 and <code>newarray</code> VM instructions</li> | |
| 13018 <li>Allocation due to JNI function calls -- for example, | |
| 13019 <code>AllocObject</code></li> | |
| 13020 <li>Allocations during VM initialization</li> | |
| 13021 <li>VM internal objects</li> | |
| 13022 </ul> | |
| 13023 </description> | |
| 13024 <origin>new</origin> | |
| 13025 <capabilities> | |
| 13026 <required id="can_generate_vm_object_alloc_events"></required> | |
| 13027 </capabilities> | |
| 13028 <parameters> | |
| 13029 <param id="jni_env"> | |
| 13030 <outptr> | |
| 13031 <struct>JNIEnv</struct> | |
| 13032 </outptr> | |
| 13033 <description> | |
| 13034 The JNI environment of the event (current) thread | |
| 13035 </description> | |
| 13036 </param> | |
| 13037 <param id="thread"> | |
| 13038 <jthread/> | |
| 13039 <description> | |
| 13040 Thread allocating the object. | |
| 13041 </description> | |
| 13042 </param> | |
| 13043 <param id="object"> | |
| 13044 <jobject/> | |
| 13045 <description> | |
| 13046 JNI local reference to the object that was allocated | |
| 13047 </description> | |
| 13048 </param> | |
| 13049 <param id="object_klass"> | |
| 13050 <jclass/> | |
| 13051 <description> | |
| 13052 JNI local reference to the class of the object | |
| 13053 </description> | |
| 13054 </param> | |
| 13055 <param id="size"> | |
| 13056 <jlong/> | |
| 13057 <description> | |
| 13058 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
| 13059 </description> | |
| 13060 </param> | |
| 13061 </parameters> | |
| 13062 </event> | |
| 13063 | |
| 13064 <event label="Object Free" | |
| 13065 id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83"> | |
| 13066 <description> | |
| 13067 An Object Free event is sent when the garbage collector frees an object. | |
| 13068 Events are only sent for tagged objects--see | |
| 13069 <internallink id="Heap">heap functions</internallink>. | |
| 13070 <p/> | |
| 13071 The event handler must not use JNI functions and | |
| 13072 must not use <jvmti/> functions except those which | |
| 13073 specifically allow such use (see the raw monitor, memory management, | |
| 13074 and environment local storage functions). | |
| 13075 </description> | |
| 13076 <origin>new</origin> | |
| 13077 <capabilities> | |
| 13078 <required id="can_generate_object_free_events"></required> | |
| 13079 </capabilities> | |
| 13080 <parameters> | |
| 13081 <param id="tag"> | |
| 13082 <jlong/> | |
| 13083 <description> | |
| 13084 The freed object's tag | |
| 13085 </description> | |
| 13086 </param> | |
| 13087 </parameters> | |
| 13088 </event> | |
| 13089 | |
| 13090 <event label="Garbage Collection Start" | |
| 13091 id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81"> | |
| 13092 <description> | |
|
2125
7246a374a9f2
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
2100
diff
changeset
|
13093 A Garbage Collection Start event is sent when a |
|
7246a374a9f2
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
2100
diff
changeset
|
13094 garbage collection pause begins. |
| 0 | 13095 Only stop-the-world collections are reported--that is, collections during |
| 13096 which all threads cease to modify the state of the Java virtual machine. | |
| 13097 This means that some collectors will never generate these events. | |
| 13098 This event is sent while the VM is still stopped, thus | |
| 13099 the event handler must not use JNI functions and | |
| 13100 must not use <jvmti/> functions except those which | |
| 13101 specifically allow such use (see the raw monitor, memory management, | |
| 13102 and environment local storage functions). | |
| 13103 <p/> | |
| 13104 This event is always sent as a matched pair with | |
| 13105 <eventlink id="GarbageCollectionFinish"/> | |
| 13106 (assuming both events are enabled) and no garbage collection | |
| 13107 events will occur between them. | |
| 13108 </description> | |
| 13109 <origin>new</origin> | |
| 13110 <capabilities> | |
| 13111 <required id="can_generate_garbage_collection_events"></required> | |
| 13112 </capabilities> | |
| 13113 <parameters> | |
| 13114 </parameters> | |
| 13115 </event> | |
| 13116 | |
| 13117 <event label="Garbage Collection Finish" | |
| 13118 id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82"> | |
| 13119 <description> | |
|
2125
7246a374a9f2
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
2100
diff
changeset
|
13120 A Garbage Collection Finish event is sent when a |
|
7246a374a9f2
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
2100
diff
changeset
|
13121 garbage collection pause ends. |
| 0 | 13122 This event is sent while the VM is still stopped, thus |
| 13123 the event handler must not use JNI functions and | |
| 13124 must not use <jvmti/> functions except those which | |
| 13125 specifically allow such use (see the raw monitor, memory management, | |
| 13126 and environment local storage functions). | |
| 13127 <p/> | |
| 13128 Some agents may need to do post garbage collection operations that | |
| 13129 require the use of the disallowed <jvmti/> or JNI functions. For these | |
| 13130 cases an agent thread can be created which waits on a raw monitor, | |
| 13131 and the handler for the Garbage Collection Finish event simply | |
| 13132 notifies the raw monitor | |
| 13133 <p/> | |
| 13134 This event is always sent as a matched pair with | |
| 13135 <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled). | |
| 13136 <issue> | |
| 13137 The most important use of this event is to provide timing information, | |
| 13138 and thus additional information is not required. However, | |
| 13139 information about the collection which is "free" should be included - | |
| 13140 what that information is needs to be determined. | |
| 13141 </issue> | |
| 13142 </description> | |
| 13143 <origin>new</origin> | |
| 13144 <capabilities> | |
| 13145 <required id="can_generate_garbage_collection_events"></required> | |
| 13146 </capabilities> | |
| 13147 <parameters> | |
| 13148 </parameters> | |
| 13149 </event> | |
| 13150 | |
| 13151 <elide> | |
| 13152 <event label="Verbose Output" phase="any" | |
| 13153 id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85"> | |
| 13154 <description> | |
| 13155 Send verbose messages as strings. | |
| 13156 <issue> | |
| 13157 This format is extremely fragile, as it can change with each | |
| 13158 platform, collector and version. Alternatives include: | |
| 13159 <ul> | |
| 13160 <li>building off Java programming language M and M APIs</li> | |
| 13161 <li>XML</li> | |
| 13162 <li>key/value pairs</li> | |
| 13163 <li>removing it</li> | |
| 13164 </ul> | |
| 13165 </issue> | |
| 13166 <issue> | |
| 13167 Though this seemed trivial to implement. | |
| 13168 In the RI it appears this will be quite complex. | |
| 13169 </issue> | |
| 13170 </description> | |
| 13171 <origin>new</origin> | |
| 13172 <capabilities> | |
| 13173 </capabilities> | |
| 13174 <parameters> | |
| 13175 <param id="flag"> | |
| 13176 <enum>jvmtiVerboseFlag</enum> | |
| 13177 <description> | |
| 13178 Which verbose output is being sent. | |
| 13179 </description> | |
| 13180 </param> | |
| 13181 <param id="message"> | |
| 13182 <vmbuf><char/></vmbuf> | |
| 13183 <description> | |
| 13184 Message text, encoded as a | |
| 13185 <internallink id="mUTF">modified UTF-8</internallink> string. | |
| 13186 </description> | |
| 13187 </param> | |
| 13188 </parameters> | |
| 13189 </event> | |
| 13190 </elide> | |
| 13191 | |
| 13192 </eventsection> | |
| 13193 | |
| 13194 <datasection> | |
| 13195 <intro> | |
| 13196 <jvmti/> extends the data types defined by JNI. | |
| 13197 </intro> | |
| 13198 <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface"> | |
| 13199 <basetype id="jboolean"> | |
| 13200 <description> | |
| 13201 Holds a Java programming language <code>boolean</code>. | |
| 13202 Unsigned 8 bits. | |
| 13203 </description> | |
| 13204 </basetype> | |
| 6919 | 13205 <basetype id="jchar"> |
| 13206 <description> | |
| 13207 Holds a Java programming language <code>char</code>. | |
| 13208 Unsigned 16 bits. | |
| 13209 </description> | |
| 13210 </basetype> | |
| 0 | 13211 <basetype id="jint"> |
| 13212 <description> | |
| 13213 Holds a Java programming language <code>int</code>. | |
| 13214 Signed 32 bits. | |
| 13215 </description> | |
| 13216 </basetype> | |
| 13217 <basetype id="jlong"> | |
| 13218 <description> | |
| 13219 Holds a Java programming language <code>long</code>. | |
| 13220 Signed 64 bits. | |
| 13221 </description> | |
| 13222 </basetype> | |
| 13223 <basetype id="jfloat"> | |
| 13224 <description> | |
| 13225 Holds a Java programming language <code>float</code>. | |
| 13226 32 bits. | |
| 13227 </description> | |
| 13228 </basetype> | |
| 13229 <basetype id="jdouble"> | |
| 13230 <description> | |
| 13231 Holds a Java programming language <code>double</code>. | |
| 13232 64 bits. | |
| 13233 </description> | |
| 13234 </basetype> | |
| 13235 <basetype id="jobject"> | |
| 13236 <description> | |
| 13237 Holds a Java programming language object. | |
| 13238 </description> | |
| 13239 </basetype> | |
| 13240 <basetype id="jclass"> | |
| 13241 <description> | |
| 13242 Holds a Java programming language class. | |
| 13243 </description> | |
| 13244 </basetype> | |
| 13245 <basetype id="jvalue"> | |
| 13246 <description> | |
| 13247 Is a union of all primitive types and <code>jobject</code>. Thus, holds any Java | |
| 13248 programming language value. | |
| 13249 </description> | |
| 13250 </basetype> | |
| 13251 <basetype id="jfieldID"> | |
| 13252 <description> | |
| 13253 Identifies a Java programming language field. | |
| 13254 <code>jfieldID</code>s returned by <jvmti/> functions and events may be | |
| 13255 safely stored. | |
| 13256 </description> | |
| 13257 </basetype> | |
| 13258 <basetype id="jmethodID"> | |
| 13259 <description> | |
| 13260 Identifies a Java programming language method, initializer, or constructor. | |
| 13261 <code>jmethodID</code>s returned by <jvmti/> functions and events may be | |
| 13262 safely stored. However, if the class is unloaded, they become invalid | |
| 13263 and must not be used. | |
| 13264 </description> | |
| 13265 </basetype> | |
| 13266 <basetype id="JNIEnv"> | |
| 13267 <description> | |
| 13268 Pointer to the JNI function table. Pointer to this (<code>JNIEnv *</code>) | |
| 13269 is a JNI environment. | |
| 13270 </description> | |
| 13271 </basetype> | |
| 13272 </basetypes> | |
| 13273 | |
| 13274 <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types"> | |
| 13275 <basetype id="jvmtiEnv"> | |
| 13276 <description> | |
| 13277 The <jvmti/> <internallink id="environments">environment</internallink> pointer. | |
| 13278 See the <internallink id="FunctionSection">Function Section</internallink>. | |
| 13279 <code>jvmtiEnv</code> points to the | |
| 13280 <internallink id="FunctionTable">function table</internallink> pointer. | |
| 13281 </description> | |
| 13282 </basetype> | |
| 13283 <basetype id="jthread"> | |
| 13284 <definition>typedef jobject jthread;</definition> | |
| 13285 <description> | |
| 13286 Subtype of <datalink id="jobject"></datalink> that holds a thread. | |
| 13287 </description> | |
| 13288 </basetype> | |
| 13289 <basetype id="jthreadGroup"> | |
| 13290 <definition>typedef jobject jthreadGroup;</definition> | |
| 13291 <description> | |
| 13292 Subtype of <datalink id="jobject"></datalink> that holds a thread group. | |
| 13293 </description> | |
| 13294 </basetype> | |
| 13295 <basetype id="jlocation"> | |
| 13296 <definition>typedef jlong jlocation;</definition> | |
| 13297 <description> | |
| 13298 A 64 bit value, representing a monotonically increasing | |
| 13299 executable position within a method. | |
| 13300 <code>-1</code> indicates a native method. | |
| 13301 See <functionlink id="GetJLocationFormat"></functionlink> for the format on a | |
| 13302 given VM. | |
| 13303 </description> | |
| 13304 </basetype> | |
| 13305 <basetype id="jrawMonitorID"> | |
| 13306 <definition>struct _jrawMonitorID; | |
| 13307 typedef struct _jrawMonitorID *jrawMonitorID;</definition> | |
| 13308 <description> | |
| 13309 A raw monitor. | |
| 13310 </description> | |
| 13311 </basetype> | |
| 13312 <basetype id="jvmtiError"> | |
| 13313 <description> | |
| 13314 Holds an error return code. | |
| 13315 See the <internallink id="ErrorSection">Error section</internallink> for possible values. | |
| 13316 <example> | |
| 13317 typedef enum { | |
| 13318 JVMTI_ERROR_NONE = 0, | |
| 13319 JVMTI_ERROR_INVALID_THREAD = 10, | |
| 13320 ... | |
| 13321 } jvmtiError; | |
| 13322 </example> | |
| 13323 </description> | |
| 13324 </basetype> | |
| 13325 <basetype id="jvmtiEvent"> | |
| 13326 <description> | |
| 13327 An identifier for an event type. | |
| 13328 See the <internallink id="EventSection">Event section</internallink> for possible values. | |
| 13329 It is guaranteed that future versions of this specification will | |
| 13330 never assign zero as an event type identifier. | |
| 13331 <example> | |
| 13332 typedef enum { | |
| 13333 JVMTI_EVENT_SINGLE_STEP = 1, | |
| 13334 JVMTI_EVENT_BREAKPOINT = 2, | |
| 13335 ... | |
| 13336 } jvmtiEvent; | |
| 13337 </example> | |
| 13338 </description> | |
| 13339 </basetype> | |
| 13340 <basetype id="jvmtiEventCallbacks"> | |
| 13341 <description> | |
| 13342 The callbacks used for events. | |
| 13343 <example> | |
| 13344 typedef struct { | |
| 13345 jvmtiEventVMInit VMInit; | |
| 13346 jvmtiEventVMDeath VMDeath; | |
| 13347 ... | |
| 13348 } jvmtiEventCallbacks; | |
| 13349 </example> | |
| 13350 See <internallink id="jvmtiEventCallbacks">event callbacks</internallink> | |
| 13351 for the complete structure. | |
| 13352 <p/> | |
| 13353 Where, for example, the VM initialization callback is defined: | |
| 13354 <example> | |
| 13355 typedef void (JNICALL *jvmtiEventVMInit) | |
| 13356 (jvmtiEnv *jvmti_env, | |
| 13357 JNIEnv* jni_env, | |
| 13358 jthread thread); | |
| 13359 </example> | |
| 13360 See the individual events for the callback function definition. | |
| 13361 </description> | |
| 13362 </basetype> | |
| 13363 <basetype id="jniNativeInterface"> | |
| 13364 <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition> | |
| 13365 <description> | |
| 13366 Typedef for the JNI function table <code>JNINativeInterface</code> | |
| 13367 defined in the | |
| 6919 | 13368 <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp23720">JNI Specification</externallink>. |
| 0 | 13369 The JNI reference implementation defines this with an underscore. |
| 13370 </description> | |
| 13371 </basetype> | |
| 13372 </basetypes> | |
| 13373 | |
| 13374 </datasection> | |
| 13375 | |
| 13376 <issuessection label="Issues"> | |
| 13377 <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic"> | |
| 13378 JVMDI requires that the agent suspend threads before calling | |
| 13379 certain sensitive functions. JVMPI requires garbage collection to be | |
| 13380 disabled before calling certain sensitive functions. | |
| 13381 It was suggested that rather than have this requirement, that | |
| 13382 VM place itself in a suitable state before performing an | |
| 13383 operation. This makes considerable sense since each VM | |
| 13384 knows its requirements and can most easily arrange a | |
| 13385 safe state. | |
| 13386 <p/> | |
| 13387 The ability to externally suspend/resume threads will, of | |
| 13388 course, remain. The ability to enable/disable garbage collection will not. | |
| 13389 <p/> | |
| 13390 This issue is resolved--suspend will not | |
| 13391 be required. The spec has been updated to reflect this. | |
| 13392 </intro> | |
| 13393 | |
| 13394 <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling"> | |
| 13395 There are a variety of approaches to sampling call stacks. | |
| 13396 The biggest bifurcation is between VM controlled and agent | |
| 13397 controlled. | |
| 13398 <p/> | |
| 13399 This issue is resolved--agent controlled | |
| 13400 sampling will be the approach. | |
| 13401 </intro> | |
| 13402 | |
| 13403 <intro id="threadRepresentation" label="Resolved Issue: Thread Representation"> | |
| 13404 JVMDI represents threads as jthread. JVMPI primarily | |
| 13405 uses JNIEnv* to represent threads. | |
| 13406 <p/> | |
| 13407 The Expert Group has chosen jthread as the representation | |
| 13408 for threads in <jvmti/>. | |
| 13409 JNIEnv* is sent by | |
| 13410 events since it is needed to JNI functions. JNIEnv, per the | |
| 13411 JNI spec, are not supposed to be used outside their thread. | |
| 13412 </intro> | |
| 13413 | |
| 13414 <intro id="design" label="Resolved Issue: Method Representation"> | |
| 13415 The JNI spec allows an implementation to depend on jclass/jmethodID | |
| 13416 pairs, rather than simply a jmethodID, to reference a method. | |
| 13417 JVMDI, for consistency, choose the same representation. | |
| 13418 JVMPI, however, specifies that a jmethodID alone maps to a | |
| 13419 method. Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store | |
| 13420 pointers in jmethodIDs, and as a result, a jmethodID is sufficient. | |
| 13421 In fact, any JVM implementation that supports JVMPI must have | |
| 13422 such a representation. | |
| 13423 <jvmti/> will use jmethodID as a unique representation of a method | |
| 13424 (no jclass is used). | |
| 13425 There should be efficiency gains, particularly in | |
| 13426 functionality like stack dumping, to this representation. | |
| 13427 <p/> | |
| 13428 Note that fields were not used in JVMPI and that the access profile | |
| 13429 of fields differs from methods--for implementation efficiency | |
| 13430 reasons, a jclass/jfieldID pair will still be needed for field | |
| 13431 reference. | |
| 13432 </intro> | |
| 13433 | |
| 13434 <intro id="localReferenceIssue" label="Resolved Issue: Local References"> | |
| 13435 Functions return local references. | |
| 13436 </intro> | |
| 13437 | |
| 13438 <intro id="frameRep" label="Resolved Issue: Representation of frames"> | |
| 13439 In JVMDI, a frame ID is used to represent a frame. Problem with this | |
| 13440 is that a VM must track when a frame becomes invalid, a far better | |
| 13441 approach, and the one used in <jvmti/>, is to reference frames by depth. | |
| 13442 </intro> | |
| 13443 | |
| 13444 <intro id="requiredCapabilities" label="Issue: Required Capabilities"> | |
| 13445 Currently, having a required capabilities means that the functionality | |
| 13446 is optional. Capabilities are useful even for required functionality | |
| 13447 since they can inform the VM is needed set-up. Thus, there should be | |
| 13448 a set of capabilities that a conformant implementation must provide | |
| 13449 (if requested during Agent_OnLoad). | |
| 13450 </intro> | |
| 13451 | |
| 13452 <intro id="taghint" label="Proposal: add tag hint function"> | |
| 13453 A hint of the percentage of objects that will be tagged would | |
| 13454 help the VM pick a good implementation. | |
| 13455 </intro> | |
| 13456 | |
| 13457 <intro id="moreMonitorQueries" label="Request: More Monitor Quires"> | |
| 13458 How difficult or easy would be to extend the monitor_info category to include | |
| 13459 <pre> | |
| 13460 - current number of monitors | |
| 13461 - enumeration of monitors | |
| 13462 - enumeration of threads waiting on a given monitor | |
| 13463 </pre> | |
| 13464 The reason for my question is the fact that current get_monitor_info support | |
| 13465 requires the agent to specify a given thread to get the info which is probably | |
| 13466 OK in the profiling/debugging space, while in the monitoring space the agent | |
| 13467 could be watching the monitor list and then decide which thread to ask for | |
| 13468 the info. You might ask why is this important for monitoring .... I think it | |
| 13469 can aid in the detection/prediction of application contention caused by hot-locks. | |
| 13470 </intro> | |
| 13471 </issuessection> | |
| 13472 | |
| 13473 <changehistory id="ChangeHistory" update="09/05/07"> | |
| 13474 <intro> | |
| 13475 The <jvmti/> specification is an evolving document with major, minor, | |
| 13476 and micro version numbers. | |
| 13477 A released version of the specification is uniquely identified | |
| 13478 by its major and minor version. | |
| 13479 The functions, events, and capabilities in this specification | |
| 13480 indicate a "Since" value which is the major and minor version in | |
| 13481 which it was introduced. | |
| 13482 The version of the specification implemented by the VM can | |
| 13483 be retrieved at runtime with the <functionlink id="GetVersionNumber"/> | |
| 13484 function. | |
| 13485 </intro> | |
| 13486 <change date="14 Nov 2002"> | |
| 13487 Converted to XML document. | |
| 13488 </change> | |
| 13489 <change date="14 Nov 2002"> | |
| 13490 Elided heap dump functions (for now) since what was there | |
| 13491 was wrong. | |
| 13492 </change> | |
| 13493 <change date="18 Nov 2002"> | |
| 13494 Added detail throughout. | |
| 13495 </change> | |
| 13496 <change date="18 Nov 2002"> | |
| 13497 Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE. | |
| 13498 </change> | |
| 13499 <change date="19 Nov 2002"> | |
| 13500 Added AsyncGetStackTrace. | |
| 13501 </change> | |
| 13502 <change date="19 Nov 2002"> | |
| 13503 Added jframeID return to GetStackTrace. | |
| 13504 </change> | |
| 13505 <change date="19 Nov 2002"> | |
| 13506 Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there | |
| 13507 since they are redundant with GetStackTrace. | |
| 13508 </change> | |
| 13509 <change date="19 Nov 2002"> | |
| 13510 Elided ClearAllBreakpoints since it has always been redundant. | |
| 13511 </change> | |
| 13512 <change date="19 Nov 2002"> | |
| 13513 Added GetSystemProperties. | |
| 13514 </change> | |
| 13515 <change date="19 Nov 2002"> | |
| 13516 Changed the thread local storage functions to use jthread. | |
| 13517 </change> | |
| 13518 <change date="20 Nov 2002"> | |
| 13519 Added GetJLocationFormat. | |
| 13520 </change> | |
| 13521 <change date="22 Nov 2002"> | |
| 13522 Added events and introductory text. | |
| 13523 </change> | |
| 13524 <change date="22 Nov 2002"> | |
| 13525 Cross reference type and constant definitions. | |
| 13526 </change> | |
| 13527 <change date="24 Nov 2002"> | |
| 13528 Added DTD. | |
| 13529 </change> | |
| 13530 <change date="24 Nov 2002"> | |
| 13531 Added capabilities function section. | |
| 13532 </change> | |
| 13533 <change date="29 Nov 2002"> | |
| 13534 Assign capabilities to each function and event. | |
| 13535 </change> | |
| 13536 <change date="29 Nov 2002"> | |
| 13537 Add <internallink id="jniIntercept">JNI interception functions</internallink>. | |
| 13538 </change> | |
| 13539 <change date="30 Nov 2002"> | |
| 13540 Auto generate SetEventNotificationMode capabilities. | |
| 13541 </change> | |
| 13542 <change date="30 Nov 2002"> | |
| 13543 Add <eventlink id="VMObjectAlloc"></eventlink> event. | |
| 13544 </change> | |
| 13545 <change date="30 Nov 2002"> | |
| 13546 Add <eventlink id="DynamicCodeGenerated"></eventlink> event. | |
| 13547 </change> | |
| 13548 <change date="30 Nov 2002"> | |
| 13549 Add const to declarations. | |
| 13550 </change> | |
| 13551 <change date="30 Nov 2002"> | |
| 13552 Change method exit and frame pop to send on exception. | |
| 13553 </change> | |
| 13554 <change date="1 Dec 2002"> | |
| 13555 Add ForceGarbageCollection. | |
| 13556 </change> | |
| 13557 <change date="2 Dec 2002"> | |
| 13558 Redo Xrun section; clarify GetStackTrace and add example; | |
| 13559 Fix width problems; use "agent" consistently. | |
| 13560 </change> | |
| 13561 <change date="8 Dec 2002"> | |
| 13562 Remove previous start-up intro. | |
| 13563 Add <internallink id="environments"><jvmti/> Environments</internallink> | |
| 13564 section. | |
| 13565 </change> | |
| 13566 <change date="8 Dec 2002"> | |
| 13567 Add <functionlink id="DisposeEnvironment"></functionlink>. | |
| 13568 </change> | |
| 13569 <change date="9 Dec 2002"> | |
| 13570 Numerous minor updates. | |
| 13571 </change> | |
| 13572 <change date="15 Dec 2002"> | |
| 13573 Add heap profiling functions added: | |
| 13574 get/set annotation, iterate live objects/heap. | |
| 13575 Add heap profiling functions place holder added: | |
| 13576 heap roots. | |
| 13577 Heap profiling event added: object free. | |
| 13578 Heap profiling event redesigned: vm object allocation. | |
| 13579 Heap profiling event placeholders added: garbage collection start/finish. | |
| 13580 Native method bind event added. | |
| 13581 </change> | |
| 13582 <change date="19 Dec 2002"> | |
| 13583 Revamp suspend/resume functions. | |
| 13584 Add origin information with jvmdi tag. | |
| 13585 Misc fixes. | |
| 13586 </change> | |
| 13587 <change date="24 Dec 2002"> | |
| 13588 Add semantics to types. | |
| 13589 </change> | |
| 13590 <change date="27 Dec 2002"> | |
| 13591 Add local reference section. | |
| 13592 Autogenerate parameter descriptions from types. | |
| 13593 </change> | |
| 13594 <change date="28 Dec 2002"> | |
| 13595 Document that RunAgentThread sends threadStart. | |
| 13596 </change> | |
| 13597 <change date="29 Dec 2002"> | |
| 13598 Remove redundant local ref and dealloc warning. | |
| 13599 Convert GetRawMonitorName to allocated buffer. | |
| 13600 Add GenerateEvents. | |
| 13601 </change> | |
| 13602 <change date="30 Dec 2002"> | |
| 13603 Make raw monitors a type and rename to "jrawMonitorID". | |
| 13604 </change> | |
| 13605 <change date="1 Jan 2003"> | |
| 13606 Include origin information. | |
| 13607 Clean-up JVMDI issue references. | |
| 13608 Remove Deallocate warnings which are now automatically generated. | |
| 13609 </change> | |
| 13610 <change date="2 Jan 2003"> | |
| 13611 Fix representation issues for jthread. | |
| 13612 </change> | |
| 13613 <change date="3 Jan 2003"> | |
| 13614 Make capabilities buffered out to 64 bits - and do it automatically. | |
| 13615 </change> | |
| 13616 <change date="4 Jan 2003"> | |
| 13617 Make constants which are enumeration into enum types. | |
| 13618 Parameters now of enum type. | |
| 13619 Clean-up and index type section. | |
| 13620 Replace remaining datadef entities with callback. | |
| 13621 </change> | |
| 13622 <change date="7 Jan 2003"> | |
| 13623 Correct GenerateEvents description. | |
| 13624 More internal semantics work. | |
| 13625 </change> | |
| 13626 <change date="9 Jan 2003"> | |
| 13627 Replace previous GetSystemProperties with two functions | |
| 13628 which use allocated information instead fixed. | |
| 13629 Add SetSystemProperty. | |
| 13630 More internal semantics work. | |
| 13631 </change> | |
| 13632 <change date="12 Jan 2003"> | |
| 13633 Add varargs to end of SetEventNotificationMode. | |
| 13634 </change> | |
| 13635 <change date="20 Jan 2003"> | |
| 13636 Finish fixing spec to reflect that alloc sizes are jlong. | |
| 13637 </change> | |
| 13638 <change date="22 Jan 2003"> | |
| 13639 Allow NULL as RunAgentThread arg. | |
| 13640 </change> | |
| 13641 <change date="22 Jan 2003"> | |
| 13642 Fixed names to standardized naming convention | |
| 13643 Removed AsyncGetStackTrace. | |
| 13644 </change> | |
| 13645 <change date="29 Jan 2003"> | |
| 13646 Since we are using jthread, removed GetThread. | |
| 13647 </change> | |
| 13648 <change date="31 Jan 2003"> | |
| 13649 Change GetFieldName to allow NULLs like GetMethodName. | |
| 13650 </change> | |
| 13651 <change date="29 Feb 2003" version="v40"> | |
| 13652 Rewrite the introductory text, adding sections on | |
| 13653 start-up, environments and bytecode instrumentation. | |
| 13654 Change the command line arguments per EG discussions. | |
| 13655 Add an introduction to the capabilities section. | |
| 13656 Add the extension mechanism category and functions. | |
| 13657 Mark for deletion, but clarified anyhow, SuspendAllThreads. | |
| 13658 Rename IterateOverLiveObjects to IterateOverReachableObjects and | |
| 13659 change the text accordingly. | |
| 13660 Clarify IterateOverHeap. | |
| 13661 Clarify CompiledMethodLoad. | |
| 13662 Discuss prerequisite state for Calling Functions. | |
| 13663 Clarify SetAllocationHooks. | |
| 13664 Added issues ("To be resolved:") through-out. | |
| 13665 And so on... | |
| 13666 </change> | |
| 13667 <change date="6 Mar 2003" version="v41"> | |
| 13668 Remove struct from the call to GetOwnedMonitorInfo. | |
| 13669 Automatically generate most error documentation, remove | |
| 13670 (rather broken) hand written error doc. | |
| 13671 Better describe capability use (empty initial set). | |
| 13672 Add min value to jint params. | |
| 13673 Remove the capability can_access_thread_local_storage. | |
| 13674 Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY; | |
| 13675 same for *NOT_IMPLEMENTED. | |
| 13676 Description fixes. | |
| 13677 </change> | |
| 13678 <change date="8 Mar 2003" version="v42"> | |
| 13679 Rename GetClassSignature to GetClassName. | |
| 13680 Rename IterateOverClassObjects to IterateOverInstancesOfClass. | |
| 13681 Remove GetMaxStack (operand stack isn't used in <jvmti/>). | |
| 13682 Description fixes: define launch-time, remove native frame pop | |
| 13683 from PopFrame, and assorted clarifications. | |
| 13684 </change> | |
| 13685 <change date="8 Mar 2003" version="v43"> | |
| 13686 Fix minor editing problem. | |
| 13687 </change> | |
| 13688 <change date="10 Mar 2003" version="v44"> | |
| 13689 Add phase information. | |
| 13690 Remap (compact) event numbers. | |
| 13691 </change> | |
| 13692 <change date="11 Mar 2003" version="v45"> | |
| 13693 More phase information - allow "any". | |
| 13694 Elide raw monitor queries and events. | |
| 13695 Minor description fixes. | |
| 13696 </change> | |
| 13697 <change date="12 Mar 2003" version="v46"> | |
| 13698 Add GetPhase. | |
| 13699 Use "phase" through document. | |
| 13700 Elide GetRawMonitorName. | |
| 13701 Elide GetObjectMonitors. | |
| 13702 </change> | |
| 13703 <change date="12 Mar 2003" version="v47"> | |
| 13704 Fixes from link, XML, and spell checking. | |
| 13705 Auto-generate the callback structure. | |
| 13706 </change> | |
| 13707 <change date="13 Mar 2003" version="v48"> | |
| 13708 One character XML fix. | |
| 13709 </change> | |
| 13710 <change date="13 Mar 2003" version="v49"> | |
| 13711 Change function parameter names to be consistent with | |
| 13712 event parameters (fooBarBaz becomes foo_bar_baz). | |
| 13713 </change> | |
| 13714 <change date="14 Mar 2003" version="v50"> | |
| 13715 Fix broken link. Fix thread markers. | |
| 13716 </change> | |
| 13717 <change date="14 Mar 2003" version="v51"> | |
| 13718 Change constants so they are under 128 to workaround | |
| 13719 compiler problems. | |
| 13720 </change> | |
| 13721 <change date="23 Mar 2003" version="v52"> | |
| 13722 Overhaul capabilities. Separate GetStackTrace into | |
| 13723 GetStackTrace and GetStackFrames. | |
| 13724 </change> | |
| 13725 <change date="8 Apr 2003" version="v54"> | |
| 13726 Use depth instead of jframeID to reference frames. | |
| 13727 Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames. | |
| 13728 Remove frame arg from events. | |
| 13729 </change> | |
| 13730 <change date="9 Apr 2003" version="v55"> | |
| 13731 Remove GetObjectWithAnnotation since tests show bufferred approach more efficient. | |
| 13732 Add missing annotation_count to GetObjectsWithAnnotations | |
| 13733 </change> | |
| 13734 <change date="10 Apr 2003" version="v56"> | |
| 13735 Remove confusing parenthetical statement in GetObjectsWithAnnotations | |
| 13736 </change> | |
| 13737 <change date="13 Apr 2003" version="v58"> | |
| 13738 Replace jclass/jmethodID representation of method with simply jmethodID; | |
| 13739 Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate. | |
| 13740 Replace can_access_frames with can_access_local_variables; remove from purely stack access. | |
| 13741 Use can_get_synthetic_attribute; fix description. | |
| 13742 Clarify that zero length arrays must be deallocated. | |
| 13743 Clarify RelinquishCapabilities. | |
| 13744 Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE. | |
| 13745 </change> | |
| 13746 <change date="27 Apr 2003" version="v59"> | |
| 13747 Remove lingering indirect references to OBSOLETE_METHOD_ID. | |
| 13748 </change> | |
| 13749 <change date="4 May 2003" version="v60"> | |
| 13750 Allow DestroyRawMonitor during OnLoad. | |
| 13751 </change> | |
| 13752 <change date="7 May 2003" version="v61"> | |
| 13753 Added not monitor owner error return to DestroyRawMonitor. | |
| 13754 </change> | |
| 13755 <change date="13 May 2003" version="v62"> | |
| 13756 Clarify semantics of raw monitors. | |
| 13757 Change flags on <code>GetThreadStatus</code>. | |
| 13758 <code>GetClassLoader</code> return NULL for the bootstrap class loader. | |
| 13759 Add <code>GetClassName</code> issue. | |
| 13760 Define local variable signature. | |
| 13761 Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>. | |
| 13762 Remove over specification in <code>GetObjectsWithAnnotations</code>. | |
| 13763 Elide <code>SetAllocationHooks</code>. | |
| 13764 Elide <code>SuspendAllThreads</code>. | |
| 13765 </change> | |
| 13766 <change date="14 May 2003" version="v63"> | |
| 13767 Define the data type <code>jvmtiEventCallbacks</code>. | |
| 13768 Zero length allocations return NULL. | |
| 13769 Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>. | |
| 13770 Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED. | |
| 13771 </change> | |
| 13772 <change date="15 May 2003" version="v64"> | |
| 13773 Better wording, per review. | |
| 13774 </change> | |
| 13775 <change date="15 May 2003" version="v65"> | |
| 13776 First Alpha. | |
| 13777 Make jmethodID and jfieldID unique, jclass not used. | |
| 13778 </change> | |
| 13779 <change date="27 May 2003" version="v66"> | |
| 13780 Fix minor XSLT errors. | |
| 13781 </change> | |
| 13782 <change date="13 June 2003" version="v67"> | |
| 13783 Undo making jfieldID unique (jmethodID still is). | |
| 13784 </change> | |
| 13785 <change date="17 June 2003" version="v68"> | |
| 13786 Changes per June 11th Expert Group meeting -- | |
| 13787 Overhaul Heap functionality: single callback, | |
| 13788 remove GetHeapRoots, add reachable iterators, | |
| 13789 and rename "annotation" to "tag". | |
| 13790 NULL thread parameter on most functions is current | |
| 13791 thread. | |
| 13792 Add timers. | |
| 13793 Remove ForceExit. | |
| 13794 Add GetEnvironmentLocalStorage. | |
| 13795 Add verbose flag and event. | |
| 13796 Add AddToBootstrapClassLoaderSearch. | |
| 13797 Update ClassFileLoadHook. | |
| 13798 </change> | |
| 13799 <change date="18 June 2003" version="v69"> | |
| 13800 Clean up issues sections. | |
| 13801 Rename GetClassName back to GetClassSignature and | |
| 13802 fix description. | |
| 13803 Add generic signature to GetClassSignature, | |
| 13804 GetFieldSignature, GetMethodSignature, and | |
| 13805 GetLocalVariableTable. | |
| 13806 Elide EstimateCostOfCapabilities. | |
| 13807 Clarify that the system property functions operate | |
| 13808 on the VM view of system properties. | |
| 13809 Clarify Agent_OnLoad. | |
| 13810 Remove "const" from JNIEnv* in events. | |
| 13811 Add metadata accessors. | |
| 13812 </change> | |
| 13813 <change date="18 June 2003" version="v70"> | |
| 13814 Add start_depth to GetStackTrace. | |
| 13815 Move system properties to a new category. | |
| 13816 Add GetObjectSize. | |
| 13817 Remove "X" from command line flags. | |
| 13818 XML, HTML, and spell check corrections. | |
| 13819 </change> | |
| 13820 <change date="19 June 2003" version="v71"> | |
| 13821 Fix JVMTI_HEAP_ROOT_THREAD to be 6. | |
| 13822 Make each synopsis match the function name. | |
| 13823 Fix unclear wording. | |
| 13824 </change> | |
| 13825 <change date="26 June 2003" version="v72"> | |
| 13826 SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value | |
| 13827 to be set to NULL. | |
| 13828 NotifyFramePop, GetFrameLocationm and all the local variable operations | |
| 13829 needed to have their wording about frames fixed. | |
| 13830 Grammar and clarity need to be fixed throughout. | |
| 13831 Capitalization and puntuation need to be consistent. | |
| 13832 Need micro version number and masks for accessing major, minor, and micro. | |
| 13833 The error code lists should indicate which must be returned by | |
| 13834 an implementation. | |
| 13835 The command line properties should be visible in the properties functions. | |
| 13836 Disallow popping from the current thread. | |
| 13837 Allow implementations to return opaque frame error when they cannot pop. | |
| 13838 The NativeMethodBind event should be sent during any phase. | |
| 13839 The DynamicCodeGenerated event should be sent during any phase. | |
| 13840 The following functions should be allowed to operate before VMInit: | |
| 13841 Set/GetEnvironmentLocalStorage | |
| 13842 GetMethodDeclaringClass | |
| 13843 GetClassSignature | |
| 13844 GetClassModifiers | |
| 13845 IsInterface | |
| 13846 IsArrayClass | |
| 13847 GetMethodName | |
| 13848 GetMethodModifiers | |
| 13849 GetMaxLocals | |
| 13850 GetArgumentsSize | |
| 13851 GetLineNumberTable | |
| 13852 GetMethodLocation | |
| 13853 IsMethodNative | |
| 13854 IsMethodSynthetic. | |
| 13855 Other changes (to XSL): | |
| 13856 Argument description should show asterisk after not before pointers. | |
| 13857 NotifyFramePop, GetFrameLocationm and all the local variable operations | |
| 13858 should hsve the NO_MORE_FRAMES error added. | |
| 13859 Not alive threads should have a different error return than invalid thread. | |
| 13860 </change> | |
| 13861 <change date="7 July 2003" version="v73"> | |
| 13862 VerboseOutput event was missing message parameter. | |
| 13863 Minor fix-ups. | |
| 13864 </change> | |
| 13865 <change date="14 July 2003" version="v74"> | |
| 13866 Technical Publications Department corrections. | |
| 13867 Allow thread and environment local storage to be set to NULL. | |
| 13868 </change> | |
| 13869 <change date="23 July 2003" version="v75"> | |
| 13870 Use new Agent_OnLoad rather than overloaded JVM_OnLoad. | |
| 13871 Add JNICALL to callbacks (XSL). | |
| 13872 Document JNICALL requirement for both events and callbacks (XSL). | |
| 13873 Restrict RedefineClasses to methods and attributes. | |
| 13874 Elide the VerboseOutput event. | |
| 13875 VMObjectAlloc: restrict when event is sent and remove method parameter. | |
| 13876 Finish loose ends from Tech Pubs edit. | |
| 13877 </change> | |
| 13878 <change date="24 July 2003" version="v76"> | |
| 13879 Change ClassFileLoadHook event to send the class instead of a boolean of redefine. | |
| 13880 </change> | |
| 13881 <change date="24 July 2003" version="v77"> | |
| 13882 XML fixes. | |
| 13883 Minor text clarifications and corrections. | |
| 13884 </change> | |
| 13885 <change date="24 July 2003" version="v78"> | |
| 13886 Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>. | |
| 13887 Clarify that stack frames are JVM Spec frames. | |
| 13888 Split can_get_source_info into can_get_source_file_name, can_get_line_numbers, | |
| 13889 and can_get_source_debug_extension. | |
| 13890 PopFrame cannot have a native calling method. | |
| 13891 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
|
13892 (see <vmspec chapter="4.4"/>). |
| 0 | 13893 </change> |
| 13894 <change date="24 July 2003" version="v79"> | |
| 13895 XML and text fixes. | |
| 13896 Move stack frame description into Stack Frame category. | |
| 13897 </change> | |
| 13898 <change date="26 July 2003" version="v80"> | |
| 13899 Allow NULL (means bootstrap loader) for GetClassloaderClasses. | |
| 13900 Add new heap reference kinds for references from classes. | |
| 13901 Add timer information struct and query functions. | |
| 13902 Add AvailableProcessors. | |
| 13903 Rename GetOtherThreadCpuTime to GetThreadCpuTime. | |
| 13904 Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE | |
| 13905 to SetEventNotification mode. | |
| 13906 Add initial thread to the VM_INIT event. | |
| 13907 Remove platform assumptions from AddToBootstrapClassLoaderSearch. | |
| 13908 </change> | |
| 13909 <change date="26 July 2003" version="v81"> | |
| 13910 Grammar and clarity changes per review. | |
| 13911 </change> | |
| 13912 <change date="27 July 2003" version="v82"> | |
| 13913 More grammar and clarity changes per review. | |
| 13914 Add Agent_OnUnload. | |
| 13915 </change> | |
| 13916 <change date="28 July 2003" version="v83"> | |
| 13917 Change return type of Agent_OnUnload to void. | |
| 13918 </change> | |
| 13919 <change date="28 July 2003" version="v84"> | |
| 13920 Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT. | |
| 13921 </change> | |
| 13922 <change date="28 July 2003" version="v85"> | |
| 13923 Steal java.lang.Runtime.availableProcessors() wording for | |
| 13924 AvailableProcessors(). | |
| 13925 Guarantee that zero will never be an event ID. | |
| 13926 Remove some issues which are no longer issues. | |
| 13927 Per review, rename and more completely document the timer | |
| 13928 information functions. | |
| 13929 </change> | |
| 13930 <change date="29 July 2003" version="v86"> | |
| 13931 Non-spec visible change to XML controlled implementation: | |
| 13932 SetThreadLocalStorage must run in VM mode. | |
| 13933 </change> | |
| 13934 <change date="5 August 2003" version="0.1.87"> | |
| 13935 Add GetErrorName. | |
| 13936 Add varargs warning to jvmtiExtensionEvent. | |
| 13937 Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent. | |
| 13938 Remove unused can_get_exception_info capability. | |
| 13939 Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction. | |
| 13940 Fix jvmtiExtensionFunctionInfo.func declared type. | |
| 13941 Extension function returns error code. | |
| 13942 Use new version numbering. | |
| 13943 </change> | |
| 13944 <change date="5 August 2003" version="0.2.88"> | |
| 13945 Remove the ClassUnload event. | |
| 13946 </change> | |
| 13947 <change date="8 August 2003" version="0.2.89"> | |
| 13948 Heap reference iterator callbacks return an enum that | |
| 13949 allows outgoing object references to be ignored. | |
| 13950 Allow JNIEnv as a param type to extension events/functions. | |
| 13951 </change> | |
| 13952 <change date="15 August 2003" version="0.2.90"> | |
| 13953 Fix a typo. | |
| 13954 </change> | |
| 13955 <change date="2 September 2003" version="0.2.91"> | |
| 13956 Remove all metadata functions: GetClassMetadata, | |
| 13957 GetFieldMetadata, and GetMethodMetadata. | |
| 13958 </change> | |
| 13959 <change date="1 October 2003" version="0.2.92"> | |
| 13960 Mark the functions Allocate. Deallocate, RawMonitor*, | |
| 13961 SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage | |
| 13962 as safe for use in heap callbacks and GC events. | |
| 13963 </change> | |
| 13964 <change date="24 November 2003" version="0.2.93"> | |
| 13965 Add pass through opaque user data pointer to heap iterate | |
| 13966 functions and callbacks. | |
| 13967 In the CompiledMethodUnload event, send the code address. | |
| 13968 Add GarbageCollectionOccurred event. | |
| 13969 Add constant pool reference kind. | |
| 13970 Mark the functions CreateRawMonitor and DestroyRawMonitor | |
| 13971 as safe for use in heap callbacks and GC events. | |
| 13972 Clarify: VMDeath, GetCurrentThreadCpuTimerInfo, | |
| 13973 GetThreadCpuTimerInfo, IterateOverReachableObjects, | |
| 13974 IterateOverObjectsReachableFromObject, GetTime and | |
| 13975 JVMTI_ERROR_NULL_POINTER. | |
| 13976 Add missing errors to: GenerateEvents and | |
| 13977 AddToBootstrapClassLoaderSearch. | |
| 13978 Fix description of ClassFileLoadHook name parameter. | |
| 13979 In heap callbacks and GC/ObjectFree events, specify | |
| 13980 that only explicitly allowed functions can be called. | |
| 13981 Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime, | |
| 13982 GetTimerInfo, and GetTime during callback. | |
| 13983 Allow calling SetTag/GetTag during the onload phase. | |
| 13984 SetEventNotificationMode, add: error attempted inappropriate | |
| 13985 thread level control. | |
| 13986 Remove jvmtiExceptionHandlerEntry. | |
| 13987 Fix handling of native methods on the stack -- | |
| 13988 location_ptr param of GetFrameLocation, remove | |
| 13989 JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation, | |
| 13990 jvmtiFrameInfo.location, and jlocation. | |
| 13991 Remove typo (from JVMPI) implying that the MonitorWaited | |
| 13992 event is sent on sleep. | |
| 13993 </change> | |
| 13994 <change date="25 November 2003" version="0.2.94"> | |
| 13995 Clarifications and typos. | |
| 13996 </change> | |
| 13997 <change date="3 December 2003" version="0.2.95"> | |
| 13998 Allow NULL user_data in heap iterators. | |
| 13999 </change> | |
| 14000 <change date="28 January 2004" version="0.2.97"> | |
| 14001 Add GetThreadState, deprecate GetThreadStatus. | |
| 14002 </change> | |
| 14003 <change date="29 January 2004" version="0.2.98"> | |
| 14004 INVALID_SLOT and TYPE_MISMATCH errors should be optional. | |
| 14005 </change> | |
| 14006 <change date="12 February 2004" version="0.2.102"> | |
| 14007 Remove MonitorContendedExit. | |
| 14008 Added JNIEnv parameter to VMObjectAlloc. | |
| 14009 Clarified definition of class_tag and referrer_index | |
| 14010 parameters to heap callbacks. | |
| 14011 </change> | |
| 14012 <change date="16 Febuary 2004" version="0.2.103"> | |
| 14013 Document JAVA_TOOL_OPTIONS. | |
| 14014 </change> | |
| 14015 <change date="17 Febuary 2004" version="0.2.105"> | |
| 14016 Divide start phase into primordial and start. | |
| 14017 Add VMStart event | |
| 14018 Change phase associations of functions and events. | |
| 14019 </change> | |
| 14020 <change date="18 Febuary 2004" version="0.3.6"> | |
| 14021 Elide deprecated GetThreadStatus. | |
| 14022 Bump minor version, subtract 100 from micro version | |
| 14023 </change> | |
| 14024 <change date="18 Febuary 2004" version="0.3.7"> | |
| 14025 Document that timer nanosecond values are unsigned. | |
| 14026 Clarify text having to do with native methods. | |
| 14027 </change> | |
| 14028 <change date="19 Febuary 2004" version="0.3.8"> | |
| 14029 Fix typos. | |
| 14030 Remove elided deprecated GetThreadStatus. | |
| 14031 </change> | |
| 14032 <change date="23 Febuary 2004" version="0.3.9"> | |
| 14033 Require NotifyFramePop to act on suspended threads. | |
| 14034 </change> | |
| 14035 <change date="24 Febuary 2004" version="0.3.10"> | |
| 14036 Add capabilities | |
| 14037 (<internallink id="jvmtiCapabilities.can_redefine_any_class" | |
| 14038 ><code>can_redefine_any_class</code></internallink> | |
| 14039 and | |
| 14040 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events" | |
| 14041 ><code>can_generate_all_class_hook_events</code></internallink>) | |
| 14042 and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>) | |
| 14043 which allow some classes to be unmodifiable. | |
| 14044 </change> | |
| 14045 <change date="28 Febuary 2004" version="0.3.11"> | |
| 14046 Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode. | |
| 14047 </change> | |
| 14048 <change date="8 March 2004" version="0.3.12"> | |
| 14049 Clarified CompiledMethodUnload so that it is clear the event | |
| 14050 may be posted after the class has been unloaded. | |
| 14051 </change> | |
| 14052 <change date="5 March 2004" version="0.3.13"> | |
| 14053 Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize. | |
| 14054 </change> | |
| 14055 <change date="13 March 2004" version="0.3.14"> | |
| 14056 Added guideline for the use of the JNI FindClass function in event | |
| 14057 callback functions. | |
| 14058 </change> | |
| 14059 <change date="15 March 2004" version="0.3.15"> | |
| 14060 Add GetAllStackTraces and GetThreadListStackTraces. | |
| 14061 </change> | |
| 14062 <change date="19 March 2004" version="0.3.16"> | |
| 14063 ClassLoad and ClassPrepare events can be posted during start phase. | |
| 14064 </change> | |
| 14065 <change date="25 March 2004" version="0.3.17"> | |
| 14066 Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable, | |
| 14067 GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes. | |
| 14068 </change> | |
| 14069 <change date="29 March 2004" version="0.3.18"> | |
| 14070 Return the timer kind in the timer information structure. | |
| 14071 </change> | |
| 14072 <change date="31 March 2004" version="0.3.19"> | |
| 14073 Spec clarifications: | |
| 14074 JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>. | |
| 14075 ForceGarbageCollection does not run finalizers. | |
| 14076 The context of the specification is the Java platform. | |
| 14077 Warn about early instrumentation. | |
| 14078 </change> | |
| 14079 <change date="1 April 2004" version="0.3.20"> | |
| 14080 Refinements to the above clarifications and | |
| 14081 Clarify that an error returned by Agent_OnLoad terminates the VM. | |
| 14082 </change> | |
| 14083 <change date="1 April 2004" version="0.3.21"> | |
| 14084 Array class creation does not generate a class load event. | |
| 14085 </change> | |
| 14086 <change date="7 April 2004" version="0.3.22"> | |
| 14087 Align thread state hierarchy more closely with java.lang.Thread.State. | |
| 14088 </change> | |
| 14089 <change date="12 April 2004" version="0.3.23"> | |
| 14090 Clarify the documentation of thread state. | |
| 14091 </change> | |
| 14092 <change date="19 April 2004" version="0.3.24"> | |
| 14093 Remove GarbageCollectionOccurred event -- can be done by agent. | |
| 14094 </change> | |
| 14095 <change date="22 April 2004" version="0.3.25"> | |
| 14096 Define "command-line option". | |
| 14097 </change> | |
| 14098 <change date="29 April 2004" version="0.3.26"> | |
| 14099 Describe the intended use of bytecode instrumentation. | |
| 14100 Fix description of extension event first parameter. | |
| 14101 </change> | |
| 14102 <change date="30 April 2004" version="0.3.27"> | |
| 14103 Clarification and typos. | |
| 14104 </change> | |
| 14105 <change date="18 May 2004" version="0.3.28"> | |
| 14106 Remove DataDumpRequest event. | |
| 14107 </change> | |
| 14108 <change date="18 May 2004" version="0.3.29"> | |
| 14109 Clarify RawMonitorWait with zero timeout. | |
| 14110 Clarify thread state after RunAgentThread. | |
| 14111 </change> | |
| 14112 <change date="24 May 2004" version="0.3.30"> | |
| 14113 Clean-up: fix bad/old links, etc. | |
| 14114 </change> | |
| 14115 <change date="30 May 2004" version="0.3.31"> | |
| 14116 Clarifications including: | |
| 14117 All character strings are modified UTF-8. | |
| 14118 Agent thread visibiity. | |
| 14119 Meaning of obsolete method version. | |
| 14120 Thread invoking heap callbacks, | |
| 14121 </change> | |
| 14122 <change date="1 June 2004" version="1.0.32"> | |
| 14123 Bump major.minor version numbers to "1.0". | |
| 14124 </change> | |
| 14125 <change date="2 June 2004" version="1.0.33"> | |
| 14126 Clarify interaction between ForceGarbageCollection | |
| 14127 and ObjectFree. | |
| 14128 </change> | |
| 14129 <change date="6 June 2004" version="1.0.34"> | |
| 14130 Restrict AddToBootstrapClassLoaderSearch and | |
| 14131 SetSystemProperty to the OnLoad phase only. | |
| 14132 </change> | |
| 14133 <change date="11 June 2004" version="1.0.35"> | |
| 14134 Fix typo in SetTag. | |
| 14135 </change> | |
| 14136 <change date="18 June 2004" version="1.0.36"> | |
| 14137 Fix trademarks. | |
| 14138 Add missing parameter in example GetThreadState usage. | |
| 14139 </change> | |
| 14140 <change date="4 August 2004" version="1.0.37"> | |
| 14141 Copyright updates. | |
| 14142 </change> | |
| 14143 <change date="5 November 2004" version="1.0.38"> | |
| 14144 Add missing function table layout. | |
| 14145 Add missing description of C++ member function format of functions. | |
| 14146 Clarify that name in CFLH can be NULL. | |
| 14147 Released as part of <tm>J2SE</tm> 5.0. | |
| 14148 </change> | |
| 14149 <change date="24 April 2005" version="1.1.47"> | |
| 14150 Bump major.minor version numbers to "1.1". | |
| 14151 Add ForceEarlyReturn* functions. | |
| 14152 Add GetOwnedMonitorStackDepthInfo function. | |
| 14153 Add GetCurrentThread function. | |
| 14154 Add "since" version marker. | |
| 14155 Add AddToSystemClassLoaderSearch. | |
| 14156 Allow AddToBootstrapClassLoaderSearch be used in live phase. | |
| 14157 Fix historic rubbish in the descriptions of the heap_object_callback | |
| 14158 parameter of IterateOverHeap and IterateOverInstancesOfClass functions; | |
| 14159 disallow NULL for this parameter. | |
| 14160 Clarify, correct and make consistent: wording about current thread, | |
| 14161 opaque frames and insufficient number of frames in PopFrame. | |
| 14162 Consistently use "current frame" rather than "topmost". | |
| 14163 Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal* | |
| 14164 by making them compatible with those in ForceEarlyReturn*. | |
| 14165 Many other clarifications and wording clean ups. | |
| 14166 </change> | |
| 14167 <change date="25 April 2005" version="1.1.48"> | |
| 14168 Add GetConstantPool. | |
| 14169 Switch references to the first edition of the VM Spec, to the seconds edition. | |
| 14170 </change> | |
| 14171 <change date="26 April 2005" version="1.1.49"> | |
| 14172 Clarify minor/major version order in GetConstantPool. | |
| 14173 </change> | |
| 14174 <change date="26 April 2005" version="1.1.50"> | |
| 14175 Add SetNativeMethodPrefix and SetNativeMethodPrefixes. | |
| 14176 Reassign GetOwnedMonitorStackDepthInfo to position 153. | |
| 14177 Break out Class Loader Search in its own documentation category. | |
| 14178 Deal with overly long lines in XML source. | |
| 14179 </change> | |
| 14180 <change date="29 April 2005" version="1.1.51"> | |
| 14181 Allow agents be started in the live phase. | |
| 14182 Added paragraph about deploying agents. | |
| 14183 </change> | |
| 14184 <change date="30 April 2005" version="1.1.52"> | |
| 14185 Add specification description to SetNativeMethodPrefix(es). | |
| 14186 Better define the conditions on GetConstantPool. | |
| 14187 </change> | |
| 14188 <change date="30 April 2005" version="1.1.53"> | |
| 14189 Break out the GetClassVersionNumber function from GetConstantPool. | |
| 14190 Clean-up the references to the VM Spec. | |
| 14191 </change> | |
| 14192 <change date="1 May 2005" version="1.1.54"> | |
| 14193 Allow SetNativeMethodPrefix(es) in any phase. | |
| 14194 Add clarifications about the impact of redefinition on GetConstantPool. | |
| 14195 </change> | |
| 14196 <change date="2 May 2005" version="1.1.56"> | |
| 14197 Various clarifications to SetNativeMethodPrefix(es). | |
| 14198 </change> | |
| 14199 <change date="2 May 2005" version="1.1.57"> | |
| 14200 Add missing performance warning to the method entry event. | |
| 14201 </change> | |
| 14202 <change date="5 May 2005" version="1.1.58"> | |
| 14203 Remove internal JVMDI support. | |
| 14204 </change> | |
| 14205 <change date="8 May 2005" version="1.1.59"> | |
| 14206 Add <functionlink id="RetransformClasses"/>. | |
| 14207 Revamp the bytecode instrumentation documentation. | |
| 14208 Change <functionlink id="IsMethodObsolete"/> to no longer | |
| 14209 require the can_redefine_classes capability. | |
| 14210 </change> | |
| 14211 <change date="11 May 2005" version="1.1.63"> | |
| 14212 Clarifications for retransformation. | |
| 14213 </change> | |
| 14214 <change date="11 May 2005" version="1.1.64"> | |
| 14215 Clarifications for retransformation, per review. | |
| 14216 Lock "retransformation (in)capable" at class load enable time. | |
| 14217 </change> | |
| 14218 <change date="4 June 2005" version="1.1.67"> | |
| 14219 Add new heap functionity which supports reporting primitive values, | |
| 14220 allows setting the referrer tag, and has more powerful filtering: | |
| 14221 FollowReferences, IterateThroughHeap, and their associated | |
| 14222 callbacks, structs, enums, and constants. | |
| 14223 </change> | |
| 14224 <change date="4 June 2005" version="1.1.68"> | |
| 14225 Clarification. | |
| 14226 </change> | |
| 14227 <change date="6 June 2005" version="1.1.69"> | |
| 14228 FollowReferences, IterateThroughHeap: Put callbacks in a struct; | |
| 14229 Add missing error codes; reduce bits in the visit control flags. | |
| 14230 </change> | |
| 14231 <change date="14 June 2005" version="1.1.70"> | |
| 14232 More on new heap functionity: spec clean-up per review. | |
| 14233 </change> | |
| 14234 <change date="15 June 2005" version="1.1.71"> | |
| 14235 More on new heap functionity: Rename old heap section to Heap (1.0). | |
| 14236 </change> | |
| 14237 <change date="21 June 2005" version="1.1.72"> | |
| 14238 Fix typos. | |
| 14239 </change> | |
| 14240 <change date="27 June 2005" version="1.1.73"> | |
| 14241 Make referrer info structure a union. | |
| 14242 </change> | |
| 14243 <change date="9 September 2005" version="1.1.74"> | |
| 14244 In new heap functions: | |
| 14245 Add missing superclass reference kind. | |
| 14246 Use a single scheme for computing field indexes. | |
| 14247 Remove outdated references to struct based referrer info. | |
| 14248 </change> | |
| 14249 <change date="12 September 2005" version="1.1.75"> | |
| 14250 Don't callback during FollowReferences on frivolous java.lang.Object superclass. | |
| 14251 </change> | |
| 14252 <change date="13 September 2005" version="1.1.76"> | |
| 14253 In string primitive callback, length now Unicode length. | |
| 14254 In array and string primitive callbacks, value now "const". | |
| 14255 Note possible compiler impacts on setting JNI function table. | |
| 14256 </change> | |
| 14257 <change date="13 September 2005" version="1.1.77"> | |
| 14258 GetClassVersionNumbers() and GetConstantPool() should return | |
| 14259 error on array or primitive class. | |
| 14260 </change> | |
| 14261 <change date="14 September 2005" version="1.1.78"> | |
| 14262 Grammar fixes. | |
| 14263 </change> | |
| 14264 <change date="26 September 2005" version="1.1.79"> | |
| 14265 Add IsModifiableClass query. | |
| 14266 </change> | |
| 14267 <change date="9 February 2006" version="1.1.81"> | |
| 14268 Add referrer_class_tag parameter to jvmtiHeapReferenceCallback. | |
| 14269 </change> | |
| 14270 <change date="13 February 2006" version="1.1.82"> | |
| 14271 Doc fixes: update can_redefine_any_class to include retransform. | |
| 14272 Clarify that exception events cover all Throwables. | |
| 14273 In GetStackTrace, no test is done for start_depth too big if start_depth is zero, | |
| 14274 Clarify fields reported in Primitive Field Callback -- static vs instance. | |
| 14275 Repair confusing names of heap types, including callback names. | |
| 14276 Require consistent usage of stack depth in the face of thread launch methods. | |
| 14277 Note incompatibility of <jvmti/> memory management with other systems. | |
| 14278 </change> | |
| 14279 <change date="14 February 2006" version="1.1.85"> | |
| 14280 Fix typos and missing renames. | |
| 14281 </change> | |
| 14282 <change date="13 March 2006" version="1.1.86"> | |
| 14283 Clarify that jmethodIDs and jfieldIDs can be saved. | |
| 14284 Clarify that Iterate Over Instances Of Class includes subclasses. | |
| 14285 </change> | |
| 14286 <change date="14 March 2006" version="1.1.87"> | |
| 14287 Better phrasing. | |
| 14288 </change> | |
| 14289 <change date="16 March 2006" version="1.1.88"> | |
| 14290 Match the referrer_index for static fields in Object Reference Callback | |
| 14291 with the Reference Implementation (and all other known implementations); | |
| 14292 that is, make it match the definition for instance fields. | |
| 14293 In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover | |
| 14294 an invalid thread in the list; and specify that not started threads | |
| 14295 return empty stacks. | |
| 14296 </change> | |
| 14297 <change date="17 March 2006" version="1.1.89"> | |
| 14298 Typo. | |
| 14299 </change> | |
| 14300 <change date="25 March 2006" version="1.1.90"> | |
| 14301 Typo. | |
| 14302 </change> | |
| 14303 <change date="6 April 2006" version="1.1.91"> | |
| 14304 Remove restrictions on AddToBootstrapClassLoaderSearch and | |
| 14305 AddToSystemClassLoaderSearch. | |
| 14306 </change> | |
| 14307 <change date="1 May 2006" version="1.1.93"> | |
| 14308 Changed spec to return -1 for monitor stack depth for the | |
| 14309 implementation which can not determine stack depth. | |
| 14310 </change> | |
| 14311 <change date="3 May 2006" version="1.1.94"> | |
| 14312 Corrections for readability and accuracy courtesy of Alan Pratt of IBM. | |
| 14313 List the object relationships reported in FollowReferences. | |
| 14314 </change> | |
| 14315 <change date="5 May 2006" version="1.1.95"> | |
| 14316 Clarify the object relationships reported in FollowReferences. | |
| 14317 </change> | |
| 14318 <change date="28 June 2006" version="1.1.98"> | |
| 14319 Clarify DisposeEnvironment; add warning. | |
| 14320 Fix typos in SetLocalXXX "retrieve" => "set". | |
| 14321 Clarify that native method prefixes must remain set while used. | |
| 14322 Clarify that exactly one Agent_OnXXX is called per agent. | |
| 14323 Clarify that library loading is independent from start-up. | |
| 14324 Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec. | |
| 14325 </change> | |
| 14326 <change date="31 July 2006" version="1.1.99"> | |
| 14327 Clarify the interaction between functions and exceptions. | |
| 14328 Clarify and give examples of field indices. | |
| 14329 Remove confusing "That is" sentence from MonitorWait and MonitorWaited events. | |
| 14330 Update links to point to Java 6. | |
| 14331 </change> | |
| 14332 <change date="6 August 2006" version="1.1.102"> | |
| 14333 Add ResourceExhaustedEvent. | |
| 14334 </change> | |
| 6919 | 14335 <change date="11 October 2012" version="1.2.2"> |
| 14336 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool. | |
| 14337 </change> | |
|
12117
f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
bpittore
parents:
10981
diff
changeset
|
14338 <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
|
14339 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
|
14340 </change> |
| 0 | 14341 </changehistory> |
| 14342 | |
| 14343 </specification> | |
| 14344 <!-- Keep this comment at the end of the file | |
| 14345 Local variables: | |
| 14346 mode: sgml | |
| 14347 sgml-omittag:t | |
| 14348 sgml-shorttag:t | |
| 14349 sgml-namecase-general:t | |
| 14350 sgml-general-insert-case:lower | |
| 14351 sgml-minimize-attributes:nil | |
| 14352 sgml-always-quote-attributes:t | |
| 14353 sgml-indent-step:2 | |
| 14354 sgml-indent-data:t | |
| 14355 sgml-parent-document:nil | |
| 14356 sgml-exposed-tags:nil | |
| 14357 sgml-local-catalogs:nil | |
| 14358 sgml-local-ecat-files:nil | |
| 14359 End: | |
| 14360 --> |