Mercurial > hg > graal-jvmci-8
comparison src/share/vm/prims/jvmti.xml @ 0:a61af66fc99e jdk7-b24
Initial load
author | duke |
---|---|
date | Sat, 01 Dec 2007 00:00:00 +0000 |
parents | |
children | c18cbe5936b8 |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:a61af66fc99e |
---|---|
1 <?xml version="1.0" encoding="ISO-8859-1"?> | |
2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?> | |
3 <!-- | |
4 Copyright 2002-2006 Sun Microsystems, Inc. All Rights Reserved. | |
5 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
6 | |
7 This code is free software; you can redistribute it and/or modify it | |
8 under the terms of the GNU General Public License version 2 only, as | |
9 published by the Free Software Foundation. | |
10 | |
11 This code is distributed in the hope that it will be useful, but WITHOUT | |
12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
14 version 2 for more details (a copy is included in the LICENSE file that | |
15 accompanied this code). | |
16 | |
17 You should have received a copy of the GNU General Public License version | |
18 2 along with this work; if not, write to the Free Software Foundation, | |
19 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
20 | |
21 Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, | |
22 CA 95054 USA or visit www.sun.com if you need additional information or | |
23 have any questions. | |
24 | |
25 --> | |
26 | |
27 <!DOCTYPE specification [ | |
28 <!ELEMENT specification (title, intro*, functionsection, errorsection, | |
29 eventsection, datasection, issuessection, changehistory)> | |
30 <!ATTLIST specification label CDATA #REQUIRED | |
31 majorversion CDATA #REQUIRED | |
32 minorversion CDATA #REQUIRED | |
33 microversion CDATA #REQUIRED> | |
34 | |
35 <!ELEMENT title (#PCDATA|jvmti|tm)*> | |
36 <!ATTLIST title subtitle CDATA #REQUIRED> | |
37 | |
38 <!ELEMENT intro ANY> | |
39 <!ATTLIST intro id CDATA #IMPLIED | |
40 label CDATA ""> | |
41 | |
42 <!ELEMENT functionsection (intro*, category*)> | |
43 <!ATTLIST functionsection label CDATA #REQUIRED> | |
44 | |
45 <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*, | |
46 (function|callback|elide)*)> | |
47 <!ATTLIST category id CDATA #REQUIRED | |
48 label CDATA #REQUIRED> | |
49 | |
50 <!ELEMENT function (synopsis, typedef*, description?, origin, | |
51 (capabilities|eventcapabilities), | |
52 parameters, errors)> | |
53 <!ATTLIST function id CDATA #REQUIRED | |
54 num CDATA #REQUIRED | |
55 phase (onload|onloadOnly|start|live|any) #IMPLIED | |
56 callbacksafe (safe|unsafe) #IMPLIED | |
57 impl CDATA #IMPLIED | |
58 hide CDATA #IMPLIED | |
59 jkernel (yes|no) #IMPLIED | |
60 since CDATA "1.0"> | |
61 | |
62 <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject| | |
63 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void), | |
64 synopsis, description?, parameters)> | |
65 <!ATTLIST callback id CDATA #REQUIRED | |
66 since CDATA "1.0"> | |
67 | |
68 <!ELEMENT synopsis (#PCDATA|jvmti)*> | |
69 | |
70 <!ELEMENT typedef (description?, field*)> | |
71 <!ATTLIST typedef id CDATA #REQUIRED | |
72 label CDATA #REQUIRED | |
73 since CDATA "1.0"> | |
74 | |
75 <!ELEMENT uniontypedef (description?, field*)> | |
76 <!ATTLIST uniontypedef id CDATA #REQUIRED | |
77 label CDATA #REQUIRED | |
78 since CDATA "1.0"> | |
79 | |
80 <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject| | |
81 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct), | |
82 description)> | |
83 <!ATTLIST field id CDATA #REQUIRED> | |
84 | |
85 <!ELEMENT capabilitiestypedef (description?, capabilityfield*)> | |
86 <!ATTLIST capabilitiestypedef id CDATA #REQUIRED | |
87 label CDATA #REQUIRED> | |
88 | |
89 <!ELEMENT capabilityfield (description)> | |
90 <!ATTLIST capabilityfield id CDATA #REQUIRED | |
91 disp1 CDATA "" | |
92 disp2 CDATA "" | |
93 since CDATA "1.0"> | |
94 | |
95 <!ELEMENT description ANY> | |
96 | |
97 <!ELEMENT capabilities (required*, capability*)> | |
98 | |
99 <!ELEMENT eventcapabilities EMPTY> | |
100 | |
101 <!ELEMENT required ANY> | |
102 <!ATTLIST required id CDATA #REQUIRED> | |
103 | |
104 <!ELEMENT capability ANY> | |
105 <!ATTLIST capability id CDATA #REQUIRED> | |
106 | |
107 <!ELEMENT parameters (param*)> | |
108 | |
109 <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject| | |
110 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype| | |
111 outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf), | |
112 description)> | |
113 <!ATTLIST param id CDATA #REQUIRED> | |
114 | |
115 <!ELEMENT jmethodID EMPTY> | |
116 <!ATTLIST jmethodID class CDATA #IMPLIED | |
117 native CDATA #IMPLIED> | |
118 | |
119 <!ELEMENT jfieldID EMPTY> | |
120 <!ATTLIST jfieldID class CDATA #IMPLIED> | |
121 | |
122 <!ELEMENT jclass EMPTY> | |
123 <!ATTLIST jclass method CDATA #IMPLIED | |
124 field CDATA #IMPLIED> | |
125 | |
126 <!ELEMENT jframeID EMPTY> | |
127 <!ATTLIST jframeID thread CDATA #IMPLIED> | |
128 | |
129 <!ELEMENT jrawMonitorID EMPTY> | |
130 | |
131 <!ELEMENT jthread EMPTY> | |
132 <!ATTLIST jthread started CDATA #IMPLIED | |
133 null CDATA #IMPLIED | |
134 frame CDATA #IMPLIED | |
135 impl CDATA #IMPLIED> | |
136 | |
137 <!ELEMENT varargs EMPTY> | |
138 | |
139 <!ELEMENT jthreadGroup EMPTY> | |
140 <!ELEMENT jobject EMPTY> | |
141 <!ELEMENT jvalue EMPTY> | |
142 <!ELEMENT jchar EMPTY> | |
143 <!ELEMENT jint EMPTY> | |
144 <!ATTLIST jint min CDATA #IMPLIED> | |
145 <!ELEMENT jlong EMPTY> | |
146 <!ELEMENT jfloat EMPTY> | |
147 <!ELEMENT jdouble EMPTY> | |
148 <!ELEMENT jlocation EMPTY> | |
149 <!ELEMENT jboolean EMPTY> | |
150 <!ELEMENT char EMPTY> | |
151 <!ELEMENT uchar EMPTY> | |
152 <!ELEMENT size_t EMPTY> | |
153 <!ELEMENT void EMPTY> | |
154 <!ELEMENT enum (#PCDATA)*> | |
155 <!ELEMENT struct (#PCDATA)*> | |
156 | |
157 <!ELEMENT nullok ANY> | |
158 | |
159 <!ELEMENT ptrtype ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
160 jthreadGroup|jobject|jvalue), nullok?)> | |
161 | |
162 <!ELEMENT outptr ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
163 jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble| | |
164 jlocation|jboolean|char|uchar|size_t|void), nullok?)> | |
165 | |
166 <!ELEMENT allocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
167 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| | |
168 jlocation|jboolean|char|uchar|size_t|void), nullok?)> | |
169 <!ATTLIST allocbuf incount CDATA #IMPLIED | |
170 outcount CDATA #IMPLIED> | |
171 | |
172 <!ELEMENT allocallocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
173 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| | |
174 jlocation|jboolean|char|uchar|size_t|void), nullok?)> | |
175 <!ATTLIST allocallocbuf incount CDATA #IMPLIED | |
176 outcount CDATA #IMPLIED> | |
177 | |
178 <!ELEMENT inptr (struct, nullok?)> | |
179 | |
180 <!ELEMENT inbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
181 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| | |
182 jlocation|jboolean|char|uchar|size_t|void), nullok?)> | |
183 <!ATTLIST inbuf incount CDATA #IMPLIED> | |
184 | |
185 <!ELEMENT outbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
186 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| | |
187 jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)> | |
188 <!ATTLIST outbuf incount CDATA #IMPLIED | |
189 outcount CDATA #IMPLIED> | |
190 | |
191 <!ELEMENT vmbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
192 jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble| | |
193 jlocation|jboolean|char|uchar|size_t|void), nullok?)> | |
194 <!ATTLIST vmbuf incount CDATA #IMPLIED | |
195 outcount CDATA #IMPLIED> | |
196 | |
197 <!ELEMENT agentbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
198 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| | |
199 jlocation|jboolean|char|uchar|size_t|void), nullok?)> | |
200 <!ATTLIST agentbuf incount CDATA #IMPLIED | |
201 outcount CDATA #IMPLIED> | |
202 | |
203 <!ELEMENT allocfieldbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread| | |
204 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble| | |
205 jlocation|jboolean|char|uchar|size_t|void))> | |
206 <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED> | |
207 | |
208 <!ELEMENT errors (error*)> | |
209 | |
210 <!ELEMENT error ANY> | |
211 <!ATTLIST error id CDATA #REQUIRED> | |
212 | |
213 <!ELEMENT errorsection (intro*, errorcategory*)> | |
214 <!ATTLIST errorsection label CDATA #REQUIRED> | |
215 | |
216 <!ELEMENT errorcategory (intro*, errorid*)> | |
217 <!ATTLIST errorcategory id CDATA #REQUIRED | |
218 label CDATA #REQUIRED> | |
219 | |
220 <!ELEMENT errorid ANY> | |
221 <!ATTLIST errorid id CDATA #REQUIRED | |
222 num CDATA #REQUIRED> | |
223 | |
224 <!ELEMENT datasection (intro*, basetypes*)> | |
225 | |
226 <!ELEMENT basetypes (intro*, basetype*)> | |
227 <!ATTLIST basetypes id CDATA #REQUIRED | |
228 label CDATA #REQUIRED> | |
229 | |
230 <!ELEMENT basetype (definition?,description)> | |
231 <!ATTLIST basetype id CDATA #REQUIRED> | |
232 | |
233 <!ELEMENT definition (#PCDATA|jvmti)*> | |
234 | |
235 <!ELEMENT eventsection (intro*, (event|elide)*)> | |
236 <!ATTLIST eventsection label CDATA #REQUIRED> | |
237 | |
238 <!ELEMENT event (description, origin, typedef*, capabilities, parameters)> | |
239 <!ATTLIST event id CDATA #REQUIRED | |
240 label CDATA #REQUIRED | |
241 const CDATA #REQUIRED | |
242 num CDATA #REQUIRED | |
243 phase (onload|start|live|any) #IMPLIED | |
244 filtered (thread|global) #IMPLIED | |
245 since CDATA "1.0"> | |
246 | |
247 <!ELEMENT issuessection (intro*)> | |
248 <!ATTLIST issuessection label CDATA #REQUIRED> | |
249 | |
250 <!ELEMENT changehistory (intro*, change*)> | |
251 <!ATTLIST changehistory update CDATA #REQUIRED | |
252 id CDATA #REQUIRED> | |
253 | |
254 <!ELEMENT change ANY> | |
255 <!ATTLIST change date CDATA #REQUIRED | |
256 version CDATA #IMPLIED> | |
257 | |
258 <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*> | |
259 <!ATTLIST functionlink id CDATA #REQUIRED> | |
260 | |
261 <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*> | |
262 <!ATTLIST datalink id CDATA #REQUIRED> | |
263 | |
264 <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*> | |
265 <!ATTLIST typelink id CDATA #REQUIRED> | |
266 | |
267 <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*> | |
268 <!ATTLIST fieldlink id CDATA #REQUIRED | |
269 struct CDATA #REQUIRED> | |
270 | |
271 <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*> | |
272 <!ATTLIST paramlink id CDATA #REQUIRED> | |
273 | |
274 <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*> | |
275 <!ATTLIST eventlink id CDATA #REQUIRED> | |
276 | |
277 <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*> | |
278 <!ATTLIST errorlink id CDATA #REQUIRED> | |
279 | |
280 <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*> | |
281 <!ATTLIST externallink id CDATA #REQUIRED> | |
282 | |
283 <!ELEMENT vmspeclink EMPTY> | |
284 <!ATTLIST vmspeclink id CDATA #IMPLIED> | |
285 <!ATTLIST vmspeclink name CDATA #IMPLIED> | |
286 <!ATTLIST vmspeclink preposition CDATA #IMPLIED> | |
287 | |
288 <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*> | |
289 <!ATTLIST internallink id CDATA #REQUIRED> | |
290 | |
291 <!ELEMENT functionphaselist EMPTY> | |
292 <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED> | |
293 | |
294 <!ELEMENT eventphaselist EMPTY> | |
295 <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED> | |
296 | |
297 <!ELEMENT issue ANY> | |
298 | |
299 <!ELEMENT rationale ANY> | |
300 | |
301 <!ELEMENT todo ANY> | |
302 | |
303 <!ELEMENT origin (#PCDATA)*> | |
304 | |
305 <!ELEMENT elide (intro|function|callback|event)*> | |
306 <!ATTLIST elide why CDATA #IMPLIED> | |
307 | |
308 <!ELEMENT constants (constant*)> | |
309 <!ATTLIST constants id CDATA #REQUIRED | |
310 label CDATA #REQUIRED | |
311 kind (enum|bits|const) #REQUIRED | |
312 since CDATA "1.0"> | |
313 | |
314 <!ELEMENT constant ANY> | |
315 <!ATTLIST constant id CDATA #REQUIRED | |
316 num CDATA #REQUIRED> | |
317 | |
318 <!ELEMENT tm (#PCDATA)> | |
319 | |
320 <!ELEMENT i (#PCDATA|jvmti|tm)*> | |
321 | |
322 <!ELEMENT b (#PCDATA|jvmti|code)*> | |
323 | |
324 <!ELEMENT code (#PCDATA|space)*> | |
325 | |
326 <!ELEMENT pre ANY> | |
327 | |
328 <!ELEMENT space EMPTY> | |
329 | |
330 <!ELEMENT jvmti EMPTY> | |
331 | |
332 <!ELEMENT example (#PCDATA|i)*> | |
333 | |
334 <!ELEMENT br EMPTY> | |
335 | |
336 <!ELEMENT p EMPTY> | |
337 | |
338 <!ELEMENT dl (dt|dd)+> | |
339 | |
340 <!ELEMENT dd ANY> | |
341 | |
342 <!ELEMENT dt (#PCDATA|jvmti|code|i|b)*> | |
343 | |
344 <!ELEMENT table (tr)+> | |
345 | |
346 <!ELEMENT tr (td|th)*> | |
347 | |
348 <!ELEMENT td ANY> | |
349 <!ATTLIST td align (left|right|center) "center"> | |
350 | |
351 <!ELEMENT th ANY> | |
352 <!ATTLIST th align (left|right|center) "center"> | |
353 | |
354 <!ELEMENT ul (li)+> | |
355 <!ATTLIST ul type (disc|circle|square) "disc"> | |
356 | |
357 <!ELEMENT li ANY> | |
358 ]> | |
359 | |
360 <specification label="JVM(TM) Tool Interface" | |
361 majorversion="1" | |
362 minorversion="1" | |
363 microversion="109"> | |
364 <title subtitle="Version"> | |
365 <tm>JVM</tm> Tool Interface | |
366 </title> | |
367 | |
368 <intro id="whatIs" label="What is the JVM Tool Interface?"> | |
369 The <tm>JVM</tm> Tool Interface (<jvmti/>) | |
370 is a programming interface used by development and monitoring tools. | |
371 It provides both a way to inspect the state and | |
372 to control the execution of applications running in the | |
373 <tm>Java</tm> virtual machine (VM). | |
374 <p/> | |
375 <jvmti/> is intended to provide a VM interface for the full breadth of tools | |
376 that need access to VM state, including but not limited to: profiling, | |
377 debugging, monitoring, thread analysis, and coverage analysis tools. | |
378 <p/> | |
379 <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual | |
380 machine. | |
381 <p/> | |
382 <jvmti/> is a two-way interface. | |
383 A client of <jvmti/>, hereafter called an <i>agent</i>, | |
384 can be notified of | |
385 interesting occurrences through <internallink id="EventSection">events</internallink>. | |
386 <jvmti/> | |
387 can query and control the application through many | |
388 <internallink id="FunctionSection">functions</internallink>, | |
389 either in response to events or | |
390 independent of them. | |
391 <p/> | |
392 Agents run in the same process with and communicate directly with | |
393 the virtual machine executing | |
394 the application being examined. This communication is | |
395 through a native interface (<jvmti/>). The native in-process interface allows | |
396 maximal control with minimal intrusion on the part of a tool. | |
397 Typically, agents are relatively compact. They can be controlled | |
398 by a separate process which implements the bulk of a tool's | |
399 function without interfering with the target application's normal execution. | |
400 </intro> | |
401 | |
402 <intro id="architecture" label="Architecture"> | |
403 Tools can be written directly to <jvmti/> or indirectly | |
404 through higher level interfaces. | |
405 The Java Platform Debugger Architecture includes <jvmti/>, but also | |
406 contains higher-level, out-of-process debugger interfaces. The higher-level | |
407 interfaces are more appropriate than <jvmti/> for many tools. | |
408 For more information on the Java Platform Debugger Architecture, | |
409 see the | |
410 <externallink id="http://java.sun.com/products/jpda/">Java | |
411 Platform Debugger Architecture website</externallink>. | |
412 </intro> | |
413 | |
414 <intro id="writingAgents" label="Writing Agents"> | |
415 Agents can be written in any native language that supports C | |
416 language calling conventions and C or C++ | |
417 definitions. | |
418 <p/> | |
419 The function, event, data type, and constant definitions needed for | |
420 using <jvmti/> are defined in the include file <code>jvmti.h</code>. | |
421 To use these definitions add the <tm>J2SE</tm> include directory | |
422 to your include path and add | |
423 <example> | |
424 #include <jvmti.h> | |
425 </example> | |
426 to your source code. | |
427 </intro> | |
428 | |
429 <intro id="deployingAgents" label="Deploying Agents"> | |
430 An agent is deployed in a platform specific manner but is typically the | |
431 platform equivalent of a dynamic library. On the <tm>Windows</tm> operating | |
432 system, for example, an agent library is a "Dynamic Linked Library" (DLL). | |
433 On the <tm>Solaris</tm> Operating Environment, an agent library is a shared | |
434 object (<code>.so</code> file). | |
435 <p/> | |
436 An agent may be started at VM startup by specifying the agent library | |
437 name using a <internallink id="starting">command line option</internallink>. | |
438 Some implementations may support a mechanism to <internallink id="onattach"> | |
439 start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>. | |
440 The details of how this is initiated are implementation specific. | |
441 </intro> | |
442 | |
443 <intro id="starting" label="Agent Command Line Options"> | |
444 The term "command-line option" is used below to | |
445 mean options supplied in the <code>JavaVMInitArgs</code> argument | |
446 to the <code>JNI_CreateJavaVM</code> function of the JNI | |
447 Invocation API. | |
448 <p/> | |
449 One of the two following | |
450 command-line options is used on VM startup to | |
451 properly load and run agents. | |
452 These arguments identify the library containing | |
453 the agent as well as an options | |
454 string to be passed in at startup. | |
455 <dl> | |
456 <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt> | |
457 <dd> | |
458 The name following <code>-agentlib:</code> is the name of the | |
459 library to load. Lookup of the library, both its full name and location, | |
460 proceeds in a platform-specific manner. | |
461 Typically, the <i><agent-lib-name></i> is expanded to an | |
462 operating system specific file name. | |
463 The <i><options></i> will be passed to the agent on start-up. | |
464 For example, if the option | |
465 <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to | |
466 load the shared library <code>foo.dll</code> from the system <code>PATH</code> | |
467 under <tm>Windows</tm> or <code>libfoo.so</code> from the | |
468 <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment. | |
469 </dd> | |
470 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt> | |
471 <dd> | |
472 The path following <code>-agentpath:</code> is the absolute path from which | |
473 to load the library. | |
474 No library name expansion will occur. | |
475 The <i><options></i> will be passed to the agent on start-up. | |
476 For example, if the option | |
477 <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to | |
478 load the shared library <code>c:\myLibs\foo.dll</code>. | |
479 </dd> | |
480 </dl> | |
481 The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink> | |
482 in the library will be invoked. | |
483 <p/> | |
484 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code> | |
485 will be searched for JNI native method implementations to facilitate the | |
486 use of Java programming language code in tools, as is needed for | |
487 <internallink id="bci">bytecode instrumentation</internallink>. | |
488 <p/> | |
489 The agent libraries will be searched after all other libraries have been | |
490 searched (agents wishing to override or intercept the native method | |
491 implementations of non-agent methods can use the | |
492 <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>). | |
493 <p/> | |
494 These switches do the above and nothing more - they do not change the | |
495 state of the VM or <jvmti/>. No command line options are needed | |
496 to enable <jvmti/> | |
497 or aspects of <jvmti/>, this is handled programmatically | |
498 by the use of | |
499 <internallink id="capability">capabilities</internallink>. | |
500 </intro> | |
501 | |
502 <intro id="startup" label="Agent Start-Up"> | |
503 The VM starts each agent by invoking a start-up function. | |
504 If the agent is started in the <code>OnLoad</code> | |
505 <functionlink id="GetPhase">phase</functionlink> the function | |
506 <internallink id="onload"><code>Agent_OnLoad</code></internallink> | |
507 will be invoked. | |
508 If the agent is started in the live | |
509 <functionlink id="GetPhase">phase</functionlink> the function | |
510 <internallink id="onattach"><code>Agent_OnAttach</code></internallink> | |
511 will be invoked. | |
512 Exactly one call to a start-up function is made per agent. | |
513 </intro> | |
514 | |
515 <intro id="onload" label="Agent Start-Up (OnLoad phase)"> | |
516 If an agent is started during the <code>OnLoad</code> phase then its | |
517 agent library must export a start-up function with the following prototype: | |
518 <example> | |
519 JNIEXPORT jint JNICALL | |
520 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example> | |
521 The VM will start the agent by calling this function. | |
522 It will be called early enough in VM initialization that: | |
523 <ul> | |
524 <li><functionlink id="SetSystemProperty">system properties</functionlink> | |
525 may be set before they have been used in the start-up of the VM</li> | |
526 <li>the full set of | |
527 <internallink id="capability">capabilities</internallink> | |
528 is still available (note that capabilities that configure the VM | |
529 may only be available at this time--see the | |
530 <internallink id="capability">Capability function section</internallink>)</li> | |
531 <li>no bytecodes have executed</li> | |
532 <li>no classes have been loaded</li> | |
533 <li>no objects have been created</li> | |
534 </ul> | |
535 <p/> | |
536 The VM will call the <code>Agent_OnLoad</code> function with | |
537 <i><options></i> as the second argument - | |
538 that is, using the command-line option examples, | |
539 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> | |
540 argument of <code>Agent_OnLoad</code>. | |
541 The <code>options</code> argument is encoded as a | |
542 <internallink id="mUTF">modified UTF-8</internallink> string. | |
543 If <i>=<options></i> is not specified, | |
544 a zero length string is passed to <code>options</code>. | |
545 The lifespan of the <code>options</code> string is the <code>Agent_OnLoad</code> | |
546 call. If needed beyond this time the string or parts of the string must | |
547 be copied. | |
548 The period between when <code>Agent_OnLoad</code> is called and when it | |
549 returns is called the <i>OnLoad phase</i>. | |
550 Since the VM is not initialized during the OnLoad | |
551 <functionlink id="GetPhase">phase</functionlink>, | |
552 the set of allowed operations | |
553 inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the | |
554 functionality available at this time). | |
555 The agent can safely process the options and set | |
556 event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once | |
557 the VM initialization event is received | |
558 (that is, the <eventlink id="VMInit">VMInit</eventlink> | |
559 callback is invoked), the agent | |
560 can complete its initialization. | |
561 <rationale> | |
562 Early startup is required so that agents can set the desired capabilities, | |
563 many of which must be set before the VM is initialized. | |
564 In JVMDI, the -Xdebug command-line option provided | |
565 very coarse-grain control of capabilities. | |
566 JVMPI implementations use various tricks to provide a single "JVMPI on" switch. | |
567 No reasonable command-line | |
568 option could provide the fine-grain of control required to balance needed capabilities vs | |
569 performance impact. | |
570 Early startup is also needed so that agents can control the execution | |
571 environment - modifying the file system and system properties to install | |
572 their functionality. | |
573 </rationale> | |
574 <p/> | |
575 The return value from <code>Agent_OnLoad</code> is used to indicate an error. | |
576 Any value other than zero indicates an error and causes termination of the VM. | |
577 </intro> | |
578 | |
579 <intro id="onattach" label="Agent Start-Up (Live phase)"> | |
580 A VM may support a mechanism that allows agents to be started in the VM during the live | |
581 <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported, | |
582 are implementation specific. For example, a tool may use some platform specific mechanism, | |
583 or implementation specific API, to attach to the running VM, and request it start a given | |
584 agent. | |
585 <p/> | |
586 If an agent is started during the live phase then its agent library | |
587 must export a start-up function | |
588 with the following prototype: | |
589 <example> | |
590 JNIEXPORT jint JNICALL | |
591 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example> | |
592 <p/> | |
593 The VM will start the agent by calling this function. | |
594 It will be called in the context of a thread | |
595 that is attached to the VM. The first argument <i><vm></i> is the Java VM. | |
596 The <i><options></i> argument is the startup options provided to the agent. | |
597 <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8 | |
598 </internallink> string. | |
599 If startup options were not provided, a zero length string is passed to | |
600 <code>options</code>. The lifespan of the <code>options</code> string is the | |
601 <code>Agent_OnAttach</code> call. If needed beyond this time the string or parts of | |
602 the string must be copied. | |
603 <p/> | |
604 Note that some <internallink id="capability">capabilities</internallink> | |
605 may not be available in the live phase. | |
606 <p/> | |
607 The <code>Agent_OnAttach</code> function initializes the agent and returns a value | |
608 to the VM to indicate if an error occurred. Any value other than zero indicates an error. | |
609 An error does not cause the VM to terminate. Instead the VM ignores the error, or takes | |
610 some implementation specific action -- for example it might print an error to standard error, | |
611 or record the error in a system log. | |
612 </intro> | |
613 | |
614 <intro id="onunload" label="Agent Shutdown"> | |
615 The library may optionally export a | |
616 shutdown function with the following prototype: | |
617 <example> | |
618 JNIEXPORT void JNICALL | |
619 Agent_OnUnload(JavaVM *vm)</example> | |
620 This function will be called by the VM when the library is about to be unloaded. | |
621 The library will be unloaded and this function will be called if some platform specific | |
622 mechanism causes the unload (an unload mechanism is not specified in this document) | |
623 or the library is (in effect) unloaded by the termination of the VM whether through | |
624 normal termination or VM failure, including start-up failure. | |
625 Uncontrolled shutdown is, of couse, an exception to this rule. | |
626 Note the distinction between this function and the | |
627 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event | |
628 to be sent, the VM must have run at least to the point of initialization and a valid | |
629 <jvmti/> environment must exist which has set a callback for VMDeath | |
630 and enabled the event | |
631 None of these are required for <code>Agent_OnUnload</code> and this function | |
632 is also called if the library is unloaded for other reasons. | |
633 In the case that a VM Death event is sent, it will be sent before this | |
634 function is called (assuming this function is called due to VM termination). | |
635 This function can be used to clean-up resources allocated by the agent. | |
636 </intro> | |
637 | |
638 <intro id="tooloptions" label="JAVA_TOOL_OPTIONS"> | |
639 Since the command-line cannot always be accessed or modified, for example in embedded VMs | |
640 or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is | |
641 provided so that agents may be launched in these cases. | |
642 <p/> | |
643 Platforms which support environment variables or other named strings, may support the | |
644 <code>JAVA_TOOL_OPTIONS</code> variable. This variable will be broken into options at white-space | |
645 boundaries. White-space characters include space, tab, carriage-return, new-line, | |
646 vertical-tab, and form-feed. Sequences of white-space characters are considered | |
647 equivalent to a single white-space character. No white-space is included in the options | |
648 unless quoted. Quoting is as follows: | |
649 <ul> | |
650 <li>All characters enclosed between a pair of single quote marks (''), except a single | |
651 quote, are quoted.</li> | |
652 <li>Double quote characters have no special meaning inside a pair of single quote marks.</li> | |
653 <li>All characters enclosed between a pair of double quote marks (""), except a double | |
654 quote, are quoted.</li> | |
655 <li>Single quote characters have no special meaning inside a pair of double quote marks.</li> | |
656 <li>A quoted part can start or end anywhere in the variable.</li> | |
657 <li>White-space characters have no special meaning when quoted -- they are included in | |
658 the option like any other character and do not mark white-space boundaries.</li> | |
659 <li>The pair of quote marks is not included in the option.</li> | |
660 </ul> | |
661 <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied | |
662 in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is | |
663 a concern; for example, the Reference Implementation disables this feature on Unix systems when | |
664 the effective user or group ID differs from the real ID. | |
665 This feature is intended to support the initialization of tools -- specifically including the | |
666 launching of native or Java programming language agents. Multiple tools may wish to use this | |
667 feature, so the variable should not be overwritten, instead, options should be appended to | |
668 the variable. Note that since the variable is processed at the time of the JNI Invocation | |
669 API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled. | |
670 </intro> | |
671 | |
672 <intro id="environments" label="Environments"> | |
673 The <jvmti/> specification supports the use of multiple simultaneous | |
674 <jvmti/> agents. | |
675 Each agent has its own <jvmti/> environment. | |
676 That is, the <jvmti/> state is | |
677 separate for each agent - changes to one environment do not affect the | |
678 others. The state of a <jvmti/> | |
679 environment includes: | |
680 <ul> | |
681 <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li> | |
682 <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li> | |
683 <li><internallink id="capability">the capabilities</internallink></li> | |
684 <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li> | |
685 </ul> | |
686 Although their <jvmti/> state | |
687 is separate, agents inspect and modify the shared state | |
688 of the VM, they also share the native environment in which they execute. | |
689 As such, an agent can perturb the results of other agents or cause them | |
690 to fail. It is the responsibility of the agent writer to specify the level | |
691 of compatibility with other agents. <jvmti/> implementations are not capable | |
692 of preventing destructive interactions between agents. Techniques to reduce | |
693 the likelihood of these occurrences are beyond the scope of this document. | |
694 <p/> | |
695 An agent creates a <jvmti/> environment | |
696 by passing a <jvmti/> version | |
697 as the interface ID to the JNI Invocation API function | |
698 <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><code>GetEnv</code></externallink>. | |
699 See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink> | |
700 for more details on the creation and use of | |
701 <jvmti/> environments. | |
702 Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from | |
703 <internallink id="onload"><code>Agent_OnLoad</code></internallink>. | |
704 </intro> | |
705 | |
706 <intro id="bci" label="Bytecode Instrumentation"> | |
707 This interface does not include some events that one might expect in an interface with | |
708 profiling support. Some examples include object allocation events and full speed | |
709 method enter and exit events. The interface instead provides support for | |
710 <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine | |
711 bytecode instructions which comprise the target program. Typically, these alterations | |
712 are to add "events" to the code of a method - for example, to add, at the beginning of a method, | |
713 a call to <code>MyProfiler.methodEntered()</code>. | |
714 Since the changes are purely additive, they do not modify application | |
715 state or behavior. | |
716 Because the inserted agent code is standard bytecodes, the VM can run at full speed, | |
717 optimizing not only the target program but also the instrumentation. If the | |
718 instrumentation does not involve switching from bytecode execution, no expensive | |
719 state transitions are needed. The result is high performance events. | |
720 This approach also provides complete control to the agent: instrumentation can be | |
721 restricted to "interesting" portions of the code (e.g., the end user's code) and | |
722 can be conditional. Instrumentation can run entirely in Java programming language | |
723 code or can call into the native agent. Instrumentation can simply maintain | |
724 counters or can statistically sample events. | |
725 <p/> | |
726 Instrumentation can be inserted in one of three ways: | |
727 <ul> | |
728 <li> | |
729 Static Instrumentation: The class file is instrumented before it | |
730 is loaded into the VM - for example, by creating a duplicate directory of | |
731 <code>*.class</code> files which have been modified to add the instrumentation. | |
732 This method is extremely awkward and, in general, an agent cannot know | |
733 the origin of the class files which will be loaded. | |
734 </li> | |
735 <li> | |
736 Load-Time Instrumentation: When a class file is loaded by the VM, the raw | |
737 bytes of the class file are sent for instrumentation to the agent. | |
738 The <eventlink id="ClassFileLoadHook"/> | |
739 event, triggered by the class load, | |
740 provides this functionality. This mechanism provides efficient | |
741 and complete access to one-time instrumentation. | |
742 </li> | |
743 <li> | |
744 Dynamic Instrumentation: A class which is already loaded (and possibly | |
745 even running) is modified. This optional feature is provided by the | |
746 <eventlink id="ClassFileLoadHook"/> event, triggered by calling the | |
747 <functionlink id="RetransformClasses"/> function. | |
748 Classes can be modified multiple times and can be returned to their | |
749 original state. | |
750 The mechanism allows instrumentation which changes during the | |
751 course of execution. | |
752 </li> | |
753 </ul> | |
754 <p/> | |
755 The class modification functionality provided in this interface | |
756 is intended to provide a mechanism for instrumentation | |
757 (the <eventlink id="ClassFileLoadHook"/> event | |
758 and the <functionlink id="RetransformClasses"/> function) | |
759 and, during development, for fix-and-continue debugging | |
760 (the <functionlink id="RedefineClasses"/> function). | |
761 <p/> | |
762 Care must be taken to avoid perturbing dependencies, especially when | |
763 instrumenting core classes. For example, an approach to getting notification | |
764 of every object allocation is to instrument the constructor on | |
765 <code>Object</code>. Assuming that the constructor is initially | |
766 empty, the constructor could be changed to: | |
767 <example> | |
768 public Object() { | |
769 MyProfiler.allocationTracker(this); | |
770 } | |
771 </example> | |
772 However, if this change was made using the | |
773 <eventlink id="ClassFileLoadHook"/> | |
774 event then this might impact a typical VM as follows: | |
775 the first created object will call the constructor causing a class load of | |
776 <code>MyProfiler</code>; which will then cause | |
777 object creation, and since <code>MyProfiler</code> isn't loaded yet, | |
778 infinite recursion; resulting in a stack overflow. A refinement of this | |
779 would be to delay invoking the tracking method until a safe time. For | |
780 example, <code>trackAllocations</code> could be set in the | |
781 handler for the <code>VMInit</code> event. | |
782 <example> | |
783 static boolean trackAllocations = false; | |
784 | |
785 public Object() { | |
786 if (trackAllocations) { | |
787 MyProfiler.allocationTracker(this); | |
788 } | |
789 } | |
790 </example> | |
791 <p/> | |
792 The <functionlink id="SetNativeMethodPrefix"/> allows native methods | |
793 to be instrumented by the use of wrapper methods. | |
794 </intro> | |
795 | |
796 <intro id="mUTF" label="Modified UTF-8 String Encoding"> | |
797 <jvmti/> uses modified UTF-8 to encode character strings. | |
798 This is the same encoding used by JNI. | |
799 Modified UTF-8 differs | |
800 from standard UTF-8 in the representation of supplementary characters | |
801 and of the null character. See the | |
802 <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/types.html#wp16542"> | |
803 Modified UTF-8 Strings</externallink> | |
804 section of the JNI specification for details. | |
805 </intro> | |
806 | |
807 <intro id="context" label="Specification Context"> | |
808 Since this interface provides access to the state of applications running in the | |
809 Java virtual machine; | |
810 terminology refers to the Java platform and not the native | |
811 platform (unless stated otherwise). For example: | |
812 <ul> | |
813 <li>"thread" means Java programming language thread.</li> | |
814 <li>"stack frame" means Java virtual machine stack frame.</li> | |
815 <li>"class" means Java programming language class.</li> | |
816 <li>"heap" means Java virtual machine heap.</li> | |
817 <li>"monitor" means Java programming language object monitor.</li> | |
818 </ul> | |
819 <p/> | |
820 Sun, Sun Microsystems, the Sun logo, Java, and JVM | |
821 are trademarks or registered trademarks of Sun | |
822 Microsystems, Inc. in the U.S. and other countries. | |
823 </intro> | |
824 | |
825 | |
826 <functionsection label="Functions"> | |
827 <intro id="jvmtiEnvAccess" label="Accessing Functions"> | |
828 Native code accesses <jvmti/> features | |
829 by calling <jvmti/> functions. | |
830 Access to <jvmti/> functions is by use of an interface pointer | |
831 in the same manner as | |
832 <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html">Java | |
833 Native Interface (JNI) functions</externallink> are accessed. | |
834 The <jvmti/> interface pointer is called the | |
835 <i>environment pointer</i>. | |
836 <p/> | |
837 An environment pointer is a pointer to an environment and has | |
838 the type <code>jvmtiEnv*</code>. | |
839 An environment has information about its <jvmti/> connection. | |
840 The first value in the environment is a pointer to the function table. | |
841 The function table is an array of pointers to <jvmti/> functions. | |
842 Every function pointer is at a predefined offset inside the | |
843 array. | |
844 <p/> | |
845 When used from the C language: | |
846 double indirection is used to access the functions; | |
847 the environment pointer provides context and is the first | |
848 parameter of each function call; for example: | |
849 <example> | |
850 jvmtiEnv *jvmti; | |
851 ... | |
852 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &class_count, &classes); | |
853 </example> | |
854 <p/> | |
855 When used from the C++ language: | |
856 functions are accessed as member functions of <code>jvmtiEnv</code>; | |
857 the environment pointer is not passed to the function call; for example: | |
858 <example> | |
859 jvmtiEnv *jvmti; | |
860 ... | |
861 jvmtiError err = jvmti->GetLoadedClasses(&class_count, &classes); | |
862 </example> | |
863 Unless otherwise stated, all examples and declarations in this | |
864 specification use the C language. | |
865 <p/> | |
866 A <jvmti/> environment can be obtained through the JNI Invocation API | |
867 <code>GetEnv</code> function: | |
868 <example> | |
869 jvmtiEnv *jvmti; | |
870 ... | |
871 (*jvm)->GetEnv(jvm, &jvmti, JVMTI_VERSION_1_0); | |
872 </example> | |
873 Each call to <code>GetEnv</code> | |
874 creates a new <jvmti/> connection and thus | |
875 a new <jvmti/> environment. | |
876 The <code>version</code> argument of <code>GetEnv</code> must be | |
877 a <jvmti/> version. | |
878 The returned environment may have a different version than the | |
879 requested version but the returned environment must be compatible. | |
880 <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a | |
881 compatible version is not available, if <jvmti/> is not supported or | |
882 <jvmti/> is not supported in the current VM configuration. | |
883 Other interfaces may be added for creating <jvmti/> environments | |
884 in specific contexts. | |
885 Each environment has its own state (for example, | |
886 <functionlink id="SetEventNotificationMode">desired events</functionlink>, | |
887 <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and | |
888 <functionlink id="AddCapabilities">capabilities</functionlink>). | |
889 An environment is released with | |
890 <functionlink id="DisposeEnvironment"></functionlink>. | |
891 Thus, unlike JNI which has one environment per thread, <jvmti/> environments work | |
892 across threads and are created dynamically. | |
893 </intro> | |
894 | |
895 <intro id="functionReturn" label="Function Return Values"> | |
896 <jvmti/> functions always return an | |
897 <internallink id="ErrorSection">error code</internallink> via the | |
898 <datalink id="jvmtiError"/> function return value. | |
899 Some functions can return additional | |
900 values through pointers provided by the calling function. | |
901 In some cases, <jvmti/> functions allocate memory that your program must | |
902 explicitly deallocate. This is indicated in the individual <jvmti/> | |
903 function descriptions. Empty lists, arrays, sequences, etc are | |
904 returned as <code>NULL</code>. | |
905 <p/> | |
906 In the event that the <jvmti/> function encounters | |
907 an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values | |
908 of memory referenced by argument pointers is undefined, but no memory | |
909 will have been allocated and no global references will have been allocated. | |
910 If the error occurs because of invalid input, no action will have occurred. | |
911 </intro> | |
912 | |
913 <intro id="refs" label="Managing JNI Object References"> | |
914 <jvmti/> functions identify objects with JNI references | |
915 (<datalink id="jobject"/> and <datalink id="jclass"/>) | |
916 and their derivatives | |
917 (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>). | |
918 References passed to | |
919 <jvmti/> functions can be either global or local, but they must be | |
920 strong references. All references returned by <jvmti/> functions are | |
921 local references--these local references are created | |
922 during the <jvmti/> call. | |
923 Local references are a resource that must be managed (see the | |
924 <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html#wp18654">JNI Documentation</externallink>). | |
925 When threads return from native code all local references | |
926 are freed. Note that some threads, including typical | |
927 agent threads, will never return from native code. | |
928 A thread is ensured the ability to create sixteen local | |
929 references without the need for any explicit management. | |
930 For threads executing a limited number of <jvmti/> calls before | |
931 returning from native code | |
932 (for example, threads processing events), | |
933 it may be determined that no explicit management | |
934 is needed. | |
935 However, long running agent threads will need explicit | |
936 local reference management--usually with the JNI functions | |
937 <code>PushLocalFrame</code> and <code>PopLocalFrame</code>. | |
938 Conversely, to preserve references beyond the | |
939 return from native code, they must be converted to global references. | |
940 These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> | |
941 as they are not <datalink id="jobject"/>s. | |
942 </intro> | |
943 | |
944 <intro id="prereqState" label="Prerequisite State for Calling Functions"> | |
945 Unless the function explicitly states that the agent must bring | |
946 a thread or the VM to a particular state (for example, suspended), | |
947 the <jvmti/> implementation is responsible for bringing the VM to a | |
948 safe and consistent state for performing the function. | |
949 </intro> | |
950 | |
951 <intro id="functionsExceptions" label="Exceptions and Functions"> | |
952 <jvmti/> functions never throw exceptions; error conditions are | |
953 communicated via the | |
954 <internallink id="functionReturn">function return value</internallink>. | |
955 Any existing exception state is preserved across a call to a | |
956 <jvmti/> function. | |
957 See the | |
958 <externallink | |
959 id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html#wp770" | |
960 >Java Exceptions</externallink> | |
961 section of the JNI specification for information on handling exceptions. | |
962 </intro> | |
963 | |
964 <category id="memory" label="Memory Management"> | |
965 <intro> | |
966 These functions provide for the allocation and deallocation of | |
967 memory used by <jvmti/> functionality and can be used to provide | |
968 working memory for agents. | |
969 Memory managed by <jvmti/> is not compatible with other memory | |
970 allocation libraries and mechanisms. | |
971 </intro> | |
972 | |
973 <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46"> | |
974 <synopsis>Allocate</synopsis> | |
975 <description> | |
976 Allocate an area of memory through the <jvmti/> allocator. | |
977 The allocated | |
978 memory should be freed with <functionlink id="Deallocate"></functionlink>. | |
979 </description> | |
980 <origin>jvmdi</origin> | |
981 <capabilities> | |
982 </capabilities> | |
983 <parameters> | |
984 <param id="size"> | |
985 <jlong/> | |
986 <description> | |
987 The number of bytes to allocate. | |
988 <rationale> | |
989 <code>jlong</code> is used for compatibility with JVMDI. | |
990 </rationale> | |
991 </description> | |
992 </param> | |
993 <param id="mem_ptr"> | |
994 <allocbuf incount="size"><uchar/></allocbuf> | |
995 <description> | |
996 On return, a pointer to the beginning of the allocated memory. | |
997 If <code>size</code> is zero, <code>NULL</code> is returned. | |
998 </description> | |
999 </param> | |
1000 </parameters> | |
1001 <errors> | |
1002 <error id="JVMTI_ERROR_OUT_OF_MEMORY"> | |
1003 Memory request cannot be honored. | |
1004 </error> | |
1005 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
1006 <paramlink id="size"></paramlink> is less than zero. | |
1007 </error> | |
1008 </errors> | |
1009 </function> | |
1010 | |
1011 <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47"> | |
1012 <synopsis>Deallocate</synopsis> | |
1013 <description> | |
1014 Deallocate <code>mem</code> using the <jvmti/> allocator. | |
1015 This function should | |
1016 be used to deallocate any memory allocated and returned | |
1017 by a <jvmti/> function | |
1018 (including memory allocated with <functionlink id="Allocate"></functionlink>). | |
1019 All allocated memory must be deallocated | |
1020 or the memory cannot be reclaimed. | |
1021 </description> | |
1022 <origin>jvmdi</origin> | |
1023 <capabilities> | |
1024 </capabilities> | |
1025 <parameters> | |
1026 <param id="mem"> | |
1027 <outbuf> | |
1028 <uchar/> | |
1029 <nullok>the call is ignored</nullok> | |
1030 </outbuf> | |
1031 <description> | |
1032 A pointer to the beginning of the allocated memory. | |
1033 Please ignore "On return, the elements are set." | |
1034 <todo>keep it from generating "On return, the elements are set"</todo> | |
1035 </description> | |
1036 </param> | |
1037 </parameters> | |
1038 <errors> | |
1039 </errors> | |
1040 </function> | |
1041 </category> | |
1042 | |
1043 <category id="threadCategory" label="Thread"> | |
1044 <intro> | |
1045 </intro> | |
1046 | |
1047 <function id="GetThreadState" num="17"> | |
1048 <synopsis>Get Thread State</synopsis> | |
1049 <description> | |
1050 Get the state of a thread. The state of the thread is represented by the | |
1051 answers to the hierarchical set of questions below: | |
1052 <ul type="circle"> | |
1053 <li><i>Alive?</i> | |
1054 <ul> | |
1055 <li>Not alive. | |
1056 <ul type="circle"> | |
1057 <li><i>Why not alive?</i> | |
1058 <ul> | |
1059 <li>New.</li> | |
1060 <li>Terminated (<datalink | |
1061 id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li> | |
1062 </ul> | |
1063 </li> | |
1064 </ul> | |
1065 </li> | |
1066 <li>Alive (<datalink | |
1067 id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>) | |
1068 <ul type="circle"> | |
1069 <li><i>Suspended?</i> | |
1070 <ul> | |
1071 <li>Suspended (<datalink | |
1072 id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li> | |
1073 <li>Not suspended</li> | |
1074 </ul> | |
1075 </li> | |
1076 <li><i>Interrupted?</i> | |
1077 <ul> | |
1078 <li>Interrupted (<datalink | |
1079 id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li> | |
1080 <li>Not interrupted.</li> | |
1081 </ul> | |
1082 </li> | |
1083 <li><i>In native?</i> | |
1084 <ul> | |
1085 <li>In native code (<datalink | |
1086 id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li> | |
1087 <li>In Java programming language code</li> | |
1088 </ul> | |
1089 </li> | |
1090 <li><i>What alive state?</i> | |
1091 <ul> | |
1092 <li>Runnable (<datalink | |
1093 id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li> | |
1094 <li>Blocked (<datalink | |
1095 id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li> | |
1096 <li>Waiting (<datalink | |
1097 id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>) | |
1098 <ul type="circle"> | |
1099 <li><i>Timed wait?</i> | |
1100 <ul> | |
1101 <li>Indefinite (<datalink | |
1102 id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li> | |
1103 <li>Timed (<datalink | |
1104 id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li> | |
1105 </ul> | |
1106 </li> | |
1107 <li><i>Why waiting?</i> | |
1108 <ul> | |
1109 <li>Object.wait (<datalink | |
1110 id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li> | |
1111 <li>LockSupport.park (<datalink | |
1112 id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li> | |
1113 <li>Sleeping (<datalink | |
1114 id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li> | |
1115 </ul> | |
1116 </li> | |
1117 </ul> | |
1118 </li> | |
1119 </ul> | |
1120 </li> | |
1121 </ul> | |
1122 </li> | |
1123 </ul> | |
1124 </li> | |
1125 </ul> | |
1126 <p/> | |
1127 The answers are represented by the following bit vector. | |
1128 <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits"> | |
1129 <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001"> | |
1130 Thread is alive. Zero if thread is new (not started) or terminated. | |
1131 </constant> | |
1132 <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002"> | |
1133 Thread has completed execution. | |
1134 </constant> | |
1135 <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004"> | |
1136 Thread is runnable. | |
1137 </constant> | |
1138 <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400"> | |
1139 Thread is waiting to enter a synchronization block/method or, | |
1140 after an <code>Object.wait()</code>, waiting to re-enter a | |
1141 synchronization block/method. | |
1142 </constant> | |
1143 <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080"> | |
1144 Thread is waiting. | |
1145 </constant> | |
1146 <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010"> | |
1147 Thread is waiting without a timeout. | |
1148 For example, <code>Object.wait()</code>. | |
1149 </constant> | |
1150 <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020"> | |
1151 Thread is waiting with a maximum time to wait specified. | |
1152 For example, <code>Object.wait(long)</code>. | |
1153 </constant> | |
1154 <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040"> | |
1155 Thread is sleeping -- <code>Thread.sleep(long)</code>. | |
1156 </constant> | |
1157 <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100"> | |
1158 Thread is waiting on an object monitor -- <code>Object.wait</code>. | |
1159 </constant> | |
1160 <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200"> | |
1161 Thread is parked, for example: <code>LockSupport.park</code>, | |
1162 <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>. | |
1163 </constant> | |
1164 <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000"> | |
1165 Thread suspended. | |
1166 <code>java.lang.Thread.suspend()</code> | |
1167 or a <jvmti/> suspend function | |
1168 (such as <functionlink id="SuspendThread"></functionlink>) | |
1169 has been called on the thread. If this bit | |
1170 is set, the other bits refer to the thread state before suspension. | |
1171 </constant> | |
1172 <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000"> | |
1173 Thread has been interrupted. | |
1174 </constant> | |
1175 <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000"> | |
1176 Thread is in native code--that is, a native method is running | |
1177 which has not called back into the VM or Java programming | |
1178 language code. | |
1179 <p/> | |
1180 This flag is not set when running VM compiled Java programming | |
1181 language code nor is it set when running VM code or | |
1182 VM support code. Native VM interface functions, such as JNI and | |
1183 <jvmti/> functions, may be implemented as VM code. | |
1184 </constant> | |
1185 <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000"> | |
1186 Defined by VM vendor. | |
1187 </constant> | |
1188 <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000"> | |
1189 Defined by VM vendor. | |
1190 </constant> | |
1191 <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000"> | |
1192 Defined by VM vendor. | |
1193 </constant> | |
1194 </constants> | |
1195 The following definitions are used to convert <jvmti/> thread state | |
1196 to <code>java.lang.Thread.State</code> style states. | |
1197 <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits"> | |
1198 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK" | |
1199 num="JVMTI_THREAD_STATE_TERMINATED | JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"> | |
1200 Mask the state with this before comparison | |
1201 </constant> | |
1202 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW" | |
1203 num="0"> | |
1204 <code>java.lang.Thread.State.NEW</code> | |
1205 </constant> | |
1206 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED" | |
1207 num="JVMTI_THREAD_STATE_TERMINATED"> | |
1208 <code>java.lang.Thread.State.TERMINATED</code> | |
1209 </constant> | |
1210 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE" | |
1211 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE"> | |
1212 <code>java.lang.Thread.State.RUNNABLE</code> | |
1213 </constant> | |
1214 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED" | |
1215 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"> | |
1216 <code>java.lang.Thread.State.BLOCKED</code> | |
1217 </constant> | |
1218 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING" | |
1219 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY"> | |
1220 <code>java.lang.Thread.State.WAITING</code> | |
1221 </constant> | |
1222 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING" | |
1223 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"> | |
1224 <code>java.lang.Thread.State.TIMED_WAITING</code> | |
1225 </constant> | |
1226 </constants> | |
1227 <b>Rules</b> | |
1228 <p/> | |
1229 There can be no more than one answer to a question, although there can be no | |
1230 answer (because the answer is unknown, does not apply, or none of the answers is | |
1231 correct). An answer is set only when the enclosing answers match. | |
1232 That is, no more than one of | |
1233 <ul type="circle"> | |
1234 <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li> | |
1235 <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li> | |
1236 <li><code>JVMTI_THREAD_STATE_WAITING</code></li> | |
1237 </ul> | |
1238 can be set (a <tm>J2SE</tm> compliant implementation will always set | |
1239 one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set). | |
1240 And if any of these are set, the enclosing answer | |
1241 <code>JVMTI_THREAD_STATE_ALIVE</code> is set. | |
1242 No more than one of | |
1243 <ul type="circle"> | |
1244 <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li> | |
1245 <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li> | |
1246 </ul> | |
1247 can be set (a <tm>J2SE</tm> compliant implementation will always set | |
1248 one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set). | |
1249 And if either is set, the enclosing answers | |
1250 <code>JVMTI_THREAD_STATE_ALIVE</code> and | |
1251 <code>JVMTI_THREAD_STATE_WAITING</code> are set. | |
1252 No more than one of | |
1253 <ul type="circle"> | |
1254 <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li> | |
1255 <li><code>JVMTI_THREAD_STATE_PARKED</code></li> | |
1256 <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li> | |
1257 </ul> | |
1258 can be set. And if any of these is set, the enclosing answers | |
1259 <code>JVMTI_THREAD_STATE_ALIVE</code> and | |
1260 <code>JVMTI_THREAD_STATE_WAITING</code> are set. | |
1261 Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set, | |
1262 then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set. | |
1263 If a state <i>A</i> is implemented using the mechanism of | |
1264 state <i>B</i> then it is state <i>A</i> which | |
1265 is returned by this function. | |
1266 For example, if <code>Thread.sleep(long)</code> | |
1267 is implemented using <code>Object.wait(long)</code> | |
1268 then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code> | |
1269 which is returned. | |
1270 More than one of | |
1271 <ul type="circle"> | |
1272 <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li> | |
1273 <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li> | |
1274 <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li> | |
1275 </ul> | |
1276 can be set, but if any is set, | |
1277 <code>JVMTI_THREAD_STATE_ALIVE</code> is set. | |
1278 <p/> | |
1279 And finally, | |
1280 <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless | |
1281 <code>JVMTI_THREAD_STATE_ALIVE</code> is not set. | |
1282 <p/> | |
1283 The thread state representation is designed for extension in future versions | |
1284 of the specification; thread state values should be used accordingly, that is | |
1285 they should not be used as ordinals. | |
1286 Most queries can be made by testing a single bit, if use in a switch statement is desired, | |
1287 the state bits should be masked with the interesting bits. | |
1288 All bits not defined above are reserved for future use. | |
1289 A VM, compliant to the current specification, must set reserved bits to zero. | |
1290 An agent should ignore reserved bits -- | |
1291 they should not be assumed to be zero and thus should not be included in comparisons. | |
1292 <p/> | |
1293 <b>Examples</b> | |
1294 <p/> | |
1295 Note that the values below exclude reserved and vendor bits. | |
1296 <p/> | |
1297 The state of a thread blocked at a <code>synchronized</code>-statement would be: | |
1298 <example> | |
1299 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | |
1300 </example> | |
1301 The state of a thread which hasn't started yet would be: | |
1302 <example> | |
1303 0 | |
1304 </example> | |
1305 The state of a thread at a <code>Object.wait(3000)</code> would be: | |
1306 <example> | |
1307 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING + | |
1308 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT + | |
1309 JVMTI_THREAD_STATE_MONITOR_WAITING | |
1310 </example> | |
1311 The state of a thread suspended while runnable would be: | |
1312 <example> | |
1313 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED | |
1314 </example> | |
1315 <p/> | |
1316 <b>Testing the State</b> | |
1317 <p/> | |
1318 In most cases, the thread state can be determined by testing the one bit corresponding | |
1319 to that question. For example, the code to test if a thread is sleeping: | |
1320 <example> | |
1321 jint state; | |
1322 jvmtiError err; | |
1323 | |
1324 err = (*jvmti)->GetThreadState(jvmti, thread, &state); | |
1325 if (err == JVMTI_ERROR_NONE) { | |
1326 if (state & JVMTI_THREAD_STATE_SLEEPING) { ... | |
1327 </example> | |
1328 <p/> | |
1329 For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be: | |
1330 <example> | |
1331 if (state & JVMTI_THREAD_STATE_WAITING) { ... | |
1332 </example> | |
1333 For some states, more than one bit will need to be tested as is the case | |
1334 when testing if a thread has not yet been started: | |
1335 <example> | |
1336 if ((state & (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0) { ... | |
1337 </example> | |
1338 To distinguish timed from untimed <code>Object.wait</code>: | |
1339 <example> | |
1340 if (state & JVMTI_THREAD_STATE_IN_OBJECT_WAIT) { | |
1341 if (state & JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT) { | |
1342 printf("in Object.wait(long timeout)\n"); | |
1343 } else { | |
1344 printf("in Object.wait()\n"); | |
1345 } | |
1346 } | |
1347 </example> | |
1348 <p/> | |
1349 <b>Relationship to <code>java.lang.Thread.State</code></b> | |
1350 <p/> | |
1351 The thread state represented by <code>java.lang.Thread.State</code> | |
1352 returned from <code>java.lang.Thread.getState()</code> is a subset of the | |
1353 information returned from this function. | |
1354 The corresponding <code>java.lang.Thread.State</code> can be determined | |
1355 by using the provided conversion masks. | |
1356 For example, this returns the name of the <code>java.lang.Thread.State</code> thread state: | |
1357 <example> | |
1358 err = (*jvmti)->GetThreadState(jvmti, thread, &state); | |
1359 abortOnError(err); | |
1360 switch (state & JVMTI_JAVA_LANG_THREAD_STATE_MASK) { | |
1361 case JVMTI_JAVA_LANG_THREAD_STATE_NEW: | |
1362 return "NEW"; | |
1363 case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED: | |
1364 return "TERMINATED"; | |
1365 case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE: | |
1366 return "RUNNABLE"; | |
1367 case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED: | |
1368 return "BLOCKED"; | |
1369 case JVMTI_JAVA_LANG_THREAD_STATE_WAITING: | |
1370 return "WAITING"; | |
1371 case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING: | |
1372 return "TIMED_WAITING"; | |
1373 } | |
1374 </example> | |
1375 </description> | |
1376 <origin>new</origin> | |
1377 <capabilities> | |
1378 </capabilities> | |
1379 <parameters> | |
1380 <param id="thread"> | |
1381 <jthread null="current" started="maybe" impl="noconvert"/> | |
1382 <description> | |
1383 The thread to query. | |
1384 </description> | |
1385 </param> | |
1386 <param id="thread_state_ptr"> | |
1387 <outptr><jint/></outptr> | |
1388 <description> | |
1389 On return, points to state flags, | |
1390 as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>. | |
1391 </description> | |
1392 </param> | |
1393 </parameters> | |
1394 <errors> | |
1395 </errors> | |
1396 </function> | |
1397 | |
1398 <function id="GetCurrentThread" phase="start" num="18" since="1.1"> | |
1399 <synopsis>Get Current Thread</synopsis> | |
1400 <description> | |
1401 Get the current thread. | |
1402 The current thread is the Java programming language thread which has called the function. | |
1403 <p/> | |
1404 Note that most <jvmti/> functions that take a thread | |
1405 as an argument will accept <code>NULL</code> to mean | |
1406 the current thread. | |
1407 </description> | |
1408 <origin>new</origin> | |
1409 <capabilities> | |
1410 </capabilities> | |
1411 <parameters> | |
1412 <param id="thread_ptr"> | |
1413 <outptr><jthread/></outptr> | |
1414 <description> | |
1415 On return, points to the current thread. | |
1416 </description> | |
1417 </param> | |
1418 </parameters> | |
1419 <errors> | |
1420 </errors> | |
1421 </function> | |
1422 | |
1423 <function id="GetAllThreads" num="4"> | |
1424 <synopsis>Get All Threads</synopsis> | |
1425 <description> | |
1426 Get all live threads. | |
1427 The threads are Java programming language threads; | |
1428 that is, threads that are attached to the VM. | |
1429 A thread is live if <code>java.lang.Thread.isAlive()</code> | |
1430 would return <code>true</code>, that is, the thread has | |
1431 been started and has not yet died. | |
1432 The universe of threads is determined by the context of the <jvmti/> | |
1433 environment, which typically is all threads attached to the VM. | |
1434 Note that this includes <jvmti/> agent threads | |
1435 (see <functionlink id="RunAgentThread"/>). | |
1436 </description> | |
1437 <origin>jvmdi</origin> | |
1438 <capabilities> | |
1439 </capabilities> | |
1440 <parameters> | |
1441 <param id="threads_count_ptr"> | |
1442 <outptr><jint/></outptr> | |
1443 <description> | |
1444 On return, points to the number of running threads. | |
1445 </description> | |
1446 </param> | |
1447 <param id="threads_ptr"> | |
1448 <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf> | |
1449 <description> | |
1450 On return, points to an array of references, one | |
1451 for each running thread. | |
1452 </description> | |
1453 </param> | |
1454 </parameters> | |
1455 <errors> | |
1456 </errors> | |
1457 </function> | |
1458 | |
1459 <function id="SuspendThread" num="5"> | |
1460 <synopsis>Suspend Thread</synopsis> | |
1461 <description> | |
1462 Suspend the specified thread. If the calling thread is specified, | |
1463 this function will not return until some other thread calls | |
1464 <functionlink id="ResumeThread"></functionlink>. | |
1465 If the thread is currently suspended, this function | |
1466 does nothing and returns an error. | |
1467 </description> | |
1468 <origin>jvmdi</origin> | |
1469 <capabilities> | |
1470 <required id="can_suspend"></required> | |
1471 </capabilities> | |
1472 <parameters> | |
1473 <param id="thread"> | |
1474 <jthread null="current"/> | |
1475 <description> | |
1476 The thread to suspend. | |
1477 </description> | |
1478 </param> | |
1479 </parameters> | |
1480 <errors> | |
1481 <error id="JVMTI_ERROR_THREAD_SUSPENDED"> | |
1482 Thread already suspended. | |
1483 </error> | |
1484 </errors> | |
1485 </function> | |
1486 | |
1487 <elide> | |
1488 <function id="SuspendAllThreads" num="101"> | |
1489 <synopsis>Suspend All Threads</synopsis> | |
1490 <description> | |
1491 <issue> | |
1492 There has been no explicit call for this function, and it will | |
1493 thus be removed if there is no interest. | |
1494 </issue> | |
1495 Suspend all live threads except: | |
1496 <ul> | |
1497 <li>already suspended threads</li> | |
1498 <li>those listed in <paramlink id="except_list"></paramlink></li> | |
1499 <li>certain system (non application) threads, as determined | |
1500 by the VM implementation</li> | |
1501 </ul> | |
1502 The threads are Java programming language threads; | |
1503 native threads which are not attached to the VM are not | |
1504 Java programming language threads. | |
1505 A thread is live if <code>java.lang.Thread.isAlive()</code> | |
1506 would return <code>true</code>, that is, the thread has | |
1507 been started and has not yet died. | |
1508 The universe of threads is determined | |
1509 by the context of the <jvmti/> | |
1510 environment, which, typically, is all threads attached to the VM, | |
1511 except critical VM internal threads and <jvmti/> agent threads | |
1512 (see <functionlink id="RunAgentThread"/>). | |
1513 <p/> | |
1514 If the calling thread is specified, | |
1515 all other threads are suspended first then the caller thread is suspended - | |
1516 this function will not return until some other thread calls | |
1517 <functionlink id="ResumeThread"></functionlink>. | |
1518 <p/> | |
1519 The list of actually | |
1520 suspended threads is returned in | |
1521 <paramlink id="suspended_list_ptr"></paramlink>. | |
1522 Suspension is as defined in <functionlink id="SuspendThread"></functionlink>. | |
1523 <functionlink id="ResumeThreadList"></functionlink> | |
1524 can be used to resume the suspended threads. | |
1525 </description> | |
1526 <origin>new</origin> | |
1527 <capabilities> | |
1528 <required id="can_suspend"></required> | |
1529 </capabilities> | |
1530 <parameters> | |
1531 <param id="except_count"> | |
1532 <jint min="0"/> | |
1533 <description> | |
1534 The number of threads in the list of threads not to be suspended. | |
1535 </description> | |
1536 </param> | |
1537 <param id="except_list"> | |
1538 <inbuf incount="except_count"> | |
1539 <jthread/> | |
1540 <nullok>not an error if <code>except_count == 0</code></nullok> | |
1541 </inbuf> | |
1542 <description> | |
1543 The list of threads not to be suspended. | |
1544 </description> | |
1545 </param> | |
1546 <param id="suspended_count_ptr"> | |
1547 <outptr><jint/></outptr> | |
1548 <description> | |
1549 On return, points to the number of threads suspended by this call. | |
1550 </description> | |
1551 </param> | |
1552 <param id="suspended_list_ptr"> | |
1553 <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf> | |
1554 <description> | |
1555 On return, points to an array of references, one | |
1556 for each thread suspended. | |
1557 </description> | |
1558 </param> | |
1559 </parameters> | |
1560 <errors> | |
1561 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
1562 A thread in <paramlink id="except_list"></paramlink> was invalid. | |
1563 </error> | |
1564 <error id="JVMTI_ERROR_NULL_POINTER"> | |
1565 Both <paramlink id="except_list"></paramlink> was <code>NULL</code> | |
1566 and <paramlink id="except_count"></paramlink> was non-zero. | |
1567 </error> | |
1568 </errors> | |
1569 </function> | |
1570 </elide> | |
1571 | |
1572 <function id="SuspendThreadList" num="92"> | |
1573 <synopsis>Suspend Thread List</synopsis> | |
1574 <description> | |
1575 Suspend the <paramlink id="request_count"></paramlink> | |
1576 threads specified in the | |
1577 <paramlink id="request_list"></paramlink> array. | |
1578 Threads may be resumed with | |
1579 <functionlink id="ResumeThreadList"></functionlink> or | |
1580 <functionlink id="ResumeThread"></functionlink>. | |
1581 If the calling thread is specified in the | |
1582 <paramlink id="request_list"></paramlink> array, this function will | |
1583 not return until some other thread resumes it. | |
1584 Errors encountered in the suspension of a thread | |
1585 are returned in the <paramlink id="results"></paramlink> | |
1586 array, <b>not</b> in the return value of this function. | |
1587 Threads that are currently suspended do not change state. | |
1588 </description> | |
1589 <origin>jvmdi</origin> | |
1590 <capabilities> | |
1591 <required id="can_suspend"></required> | |
1592 </capabilities> | |
1593 <parameters> | |
1594 <param id="request_count"> | |
1595 <jint min="0"/> | |
1596 <description> | |
1597 The number of threads to suspend. | |
1598 </description> | |
1599 </param> | |
1600 <param id="request_list"> | |
1601 <inbuf incount="request_count"><jthread/></inbuf> | |
1602 <description> | |
1603 The list of threads to suspend. | |
1604 </description> | |
1605 </param> | |
1606 <param id="results"> | |
1607 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> | |
1608 <description> | |
1609 An agent supplied array of | |
1610 <paramlink id="request_count"></paramlink> elements. | |
1611 On return, filled with the error code for | |
1612 the suspend of the corresponding thread. | |
1613 The error code will be | |
1614 <errorlink id="JVMTI_ERROR_NONE"></errorlink> | |
1615 if the thread was suspended by this call. | |
1616 Possible error codes are those specified | |
1617 for <functionlink id="SuspendThread"></functionlink>. | |
1618 </description> | |
1619 </param> | |
1620 </parameters> | |
1621 <errors> | |
1622 </errors> | |
1623 </function> | |
1624 | |
1625 <function id="ResumeThread" num="6"> | |
1626 <synopsis>Resume Thread</synopsis> | |
1627 <description> | |
1628 Resume a suspended thread. | |
1629 Any threads currently suspended through | |
1630 a <jvmti/> suspend function (eg. | |
1631 <functionlink id="SuspendThread"></functionlink>) | |
1632 or <code>java.lang.Thread.suspend()</code> | |
1633 will resume execution; | |
1634 all other threads are unaffected. | |
1635 </description> | |
1636 <origin>jvmdi</origin> | |
1637 <capabilities> | |
1638 <required id="can_suspend"></required> | |
1639 </capabilities> | |
1640 <parameters> | |
1641 <param id="thread"> | |
1642 <jthread/> | |
1643 <description> | |
1644 The thread to resume. | |
1645 </description> | |
1646 </param> | |
1647 </parameters> | |
1648 <errors> | |
1649 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
1650 Thread was not suspended. | |
1651 </error> | |
1652 <error id="JVMTI_ERROR_INVALID_TYPESTATE"> | |
1653 The state of the thread has been modified, and is now inconsistent. | |
1654 </error> | |
1655 </errors> | |
1656 </function> | |
1657 | |
1658 <function id="ResumeThreadList" num="93"> | |
1659 <synopsis>Resume Thread List</synopsis> | |
1660 <description> | |
1661 Resume the <paramlink id="request_count"></paramlink> | |
1662 threads specified in the | |
1663 <paramlink id="request_list"></paramlink> array. | |
1664 Any thread suspended through | |
1665 a <jvmti/> suspend function (eg. | |
1666 <functionlink id="SuspendThreadList"></functionlink>) | |
1667 or <code>java.lang.Thread.suspend()</code> | |
1668 will resume execution. | |
1669 </description> | |
1670 <origin>jvmdi</origin> | |
1671 <capabilities> | |
1672 <required id="can_suspend"></required> | |
1673 </capabilities> | |
1674 <parameters> | |
1675 <param id="request_count"> | |
1676 <jint min="0"/> | |
1677 <description> | |
1678 The number of threads to resume. | |
1679 </description> | |
1680 </param> | |
1681 <param id="request_list"> | |
1682 <inbuf incount="request_count"><jthread/></inbuf> | |
1683 <description> | |
1684 The threads to resume. | |
1685 </description> | |
1686 </param> | |
1687 <param id="results"> | |
1688 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> | |
1689 <description> | |
1690 An agent supplied array of | |
1691 <paramlink id="request_count"></paramlink> elements. | |
1692 On return, filled with the error code for | |
1693 the resume of the corresponding thread. | |
1694 The error code will be | |
1695 <errorlink id="JVMTI_ERROR_NONE"></errorlink> | |
1696 if the thread was suspended by this call. | |
1697 Possible error codes are those specified | |
1698 for <functionlink id="ResumeThread"></functionlink>. | |
1699 </description> | |
1700 </param> | |
1701 </parameters> | |
1702 <errors> | |
1703 </errors> | |
1704 </function> | |
1705 | |
1706 <function id="StopThread" num="7"> | |
1707 <synopsis>Stop Thread</synopsis> | |
1708 <description> | |
1709 Send the specified asynchronous exception to the specified thread | |
1710 (similar to <code>java.lang.Thread.stop</code>). | |
1711 Normally, this function is used to kill the specified thread with an | |
1712 instance of the exception <code>ThreadDeath</code>. | |
1713 </description> | |
1714 <origin>jvmdi</origin> | |
1715 <capabilities> | |
1716 <required id="can_signal_thread"></required> | |
1717 </capabilities> | |
1718 <parameters> | |
1719 <param id="thread"> | |
1720 <jthread/> | |
1721 <description> | |
1722 The thread to stop. | |
1723 </description> | |
1724 </param> | |
1725 <param id="exception"> | |
1726 <jobject/> | |
1727 <description> | |
1728 The asynchronous exception object. | |
1729 </description> | |
1730 </param> | |
1731 </parameters> | |
1732 <errors> | |
1733 </errors> | |
1734 </function> | |
1735 | |
1736 <function id="InterruptThread" num="8"> | |
1737 <synopsis>Interrupt Thread</synopsis> | |
1738 <description> | |
1739 Interrupt the specified thread | |
1740 (similar to <code>java.lang.Thread.interrupt</code>). | |
1741 </description> | |
1742 <origin>jvmdi</origin> | |
1743 <capabilities> | |
1744 <required id="can_signal_thread"></required> | |
1745 </capabilities> | |
1746 <parameters> | |
1747 <param id="thread"> | |
1748 <jthread impl="noconvert"/> | |
1749 <description> | |
1750 The thread to interrupt. | |
1751 </description> | |
1752 </param> | |
1753 </parameters> | |
1754 <errors> | |
1755 </errors> | |
1756 </function> | |
1757 | |
1758 <function id="GetThreadInfo" num="9"> | |
1759 <synopsis>Get Thread Info</synopsis> | |
1760 <typedef id="jvmtiThreadInfo" label="Thread information structure"> | |
1761 <field id="name"> | |
1762 <allocfieldbuf><char/></allocfieldbuf> | |
1763 <description> | |
1764 The thread name, encoded as a | |
1765 <internallink id="mUTF">modified UTF-8</internallink> string. | |
1766 </description> | |
1767 </field> | |
1768 <field id="priority"> | |
1769 <jint/> | |
1770 <description> | |
1771 The thread priority. See the thread priority constants: | |
1772 <datalink id="jvmtiThreadPriority"></datalink>. | |
1773 </description> | |
1774 </field> | |
1775 <field id="is_daemon"> | |
1776 <jboolean/> | |
1777 <description> | |
1778 Is this a daemon thread? | |
1779 </description> | |
1780 </field> | |
1781 <field id="thread_group"> | |
1782 <jthreadGroup/> | |
1783 <description> | |
1784 The thread group to which this thread belongs. | |
1785 <code>NULL</code> if the thread has died. | |
1786 </description> | |
1787 </field> | |
1788 <field id="context_class_loader"> | |
1789 <jobject/> | |
1790 <description> | |
1791 The context class loader associated with this thread. | |
1792 </description> | |
1793 </field> | |
1794 </typedef> | |
1795 <description> | |
1796 Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure | |
1797 are filled in with details of the specified thread. | |
1798 </description> | |
1799 <origin>jvmdi</origin> | |
1800 <capabilities> | |
1801 </capabilities> | |
1802 <parameters> | |
1803 <param id="thread"> | |
1804 <jthread null="current" impl="noconvert" started="maybe"/> | |
1805 <description> | |
1806 The thread to query. | |
1807 </description> | |
1808 </param> | |
1809 <param id="info_ptr"> | |
1810 <outptr><struct>jvmtiThreadInfo</struct></outptr> | |
1811 <description> | |
1812 On return, filled with information describing the specified thread. | |
1813 <p/> | |
1814 For JDK 1.1 implementations that don't | |
1815 recognize context class loaders, | |
1816 the <code>context_class_loader</code> field will be NULL. | |
1817 </description> | |
1818 </param> | |
1819 </parameters> | |
1820 <errors> | |
1821 </errors> | |
1822 </function> | |
1823 | |
1824 <function id="GetOwnedMonitorInfo" num="10"> | |
1825 <synopsis>Get Owned Monitor Info</synopsis> | |
1826 <description> | |
1827 Get information about the monitors owned by the | |
1828 specified thread. | |
1829 </description> | |
1830 <origin>jvmdiClone</origin> | |
1831 <capabilities> | |
1832 <required id="can_get_owned_monitor_info"></required> | |
1833 </capabilities> | |
1834 <parameters> | |
1835 <param id="thread"> | |
1836 <jthread null="current"/> | |
1837 <description> | |
1838 The thread to query. | |
1839 </description> | |
1840 </param> | |
1841 <param id="owned_monitor_count_ptr"> | |
1842 <outptr><jint/></outptr> | |
1843 <description> | |
1844 The number of monitors returned. | |
1845 </description> | |
1846 </param> | |
1847 <param id="owned_monitors_ptr"> | |
1848 <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf> | |
1849 <description> | |
1850 The array of owned monitors. | |
1851 </description> | |
1852 </param> | |
1853 </parameters> | |
1854 <errors> | |
1855 </errors> | |
1856 </function> | |
1857 | |
1858 <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1"> | |
1859 <synopsis>Get Owned Monitor Stack Depth Info</synopsis> | |
1860 <typedef id="jvmtiMonitorStackDepthInfo" | |
1861 label="Monitor stack depth information structure"> | |
1862 <field id="monitor"> | |
1863 <jobject/> | |
1864 <description> | |
1865 The owned monitor. | |
1866 </description> | |
1867 </field> | |
1868 <field id="stack_depth"> | |
1869 <jint/> | |
1870 <description> | |
1871 The stack depth. Corresponds to the stack depth used in the | |
1872 <internallink id="stack">Stack Frame functions</internallink>. | |
1873 That is, zero is the current frame, one is the frame which | |
1874 called the current frame. And it is negative one if the | |
1875 implementation cannot determine the stack depth (e.g., for | |
1876 monitors acquired by JNI <code>MonitorEnter</code>). | |
1877 </description> | |
1878 </field> | |
1879 </typedef> | |
1880 <description> | |
1881 Get information about the monitors owned by the | |
1882 specified thread and the depth of the stack frame which locked them. | |
1883 </description> | |
1884 <origin>new</origin> | |
1885 <capabilities> | |
1886 <required id="can_get_owned_monitor_stack_depth_info"></required> | |
1887 </capabilities> | |
1888 <parameters> | |
1889 <param id="thread"> | |
1890 <jthread null="current"/> | |
1891 <description> | |
1892 The thread to query. | |
1893 </description> | |
1894 </param> | |
1895 <param id="monitor_info_count_ptr"> | |
1896 <outptr><jint/></outptr> | |
1897 <description> | |
1898 The number of monitors returned. | |
1899 </description> | |
1900 </param> | |
1901 <param id="monitor_info_ptr"> | |
1902 <allocbuf outcount="owned_monitor_depth_count_ptr"> | |
1903 <struct>jvmtiMonitorStackDepthInfo</struct> | |
1904 </allocbuf> | |
1905 <description> | |
1906 The array of owned monitor depth information. | |
1907 </description> | |
1908 </param> | |
1909 </parameters> | |
1910 <errors> | |
1911 </errors> | |
1912 </function> | |
1913 | |
1914 <function id="GetCurrentContendedMonitor" num="11"> | |
1915 <synopsis>Get Current Contended Monitor</synopsis> | |
1916 <description> | |
1917 Get the object, if any, whose monitor the specified thread is waiting to | |
1918 enter or waiting to regain through <code>java.lang.Object.wait</code>. | |
1919 </description> | |
1920 <origin>jvmdi</origin> | |
1921 <capabilities> | |
1922 <required id="can_get_current_contended_monitor"></required> | |
1923 </capabilities> | |
1924 <parameters> | |
1925 <param id="thread"> | |
1926 <jthread null="current"/> | |
1927 <description> | |
1928 The thread to query. | |
1929 </description> | |
1930 </param> | |
1931 <param id="monitor_ptr"> | |
1932 <outptr><jobject/></outptr> | |
1933 <description> | |
1934 On return, filled with the current contended monitor, or | |
1935 NULL if there is none. | |
1936 </description> | |
1937 </param> | |
1938 </parameters> | |
1939 <errors> | |
1940 </errors> | |
1941 </function> | |
1942 | |
1943 <callback id="jvmtiStartFunction"> | |
1944 <void/> | |
1945 <synopsis>Agent Start Function</synopsis> | |
1946 <description> | |
1947 Agent supplied callback function. | |
1948 This function is the entry point for an agent thread | |
1949 started with | |
1950 <functionlink id="RunAgentThread"></functionlink>. | |
1951 </description> | |
1952 <parameters> | |
1953 <param id="jvmti_env"> | |
1954 <outptr> | |
1955 <struct>jvmtiEnv</struct> | |
1956 </outptr> | |
1957 <description> | |
1958 The <jvmti/> environment. | |
1959 </description> | |
1960 </param> | |
1961 <param id="jni_env"> | |
1962 <outptr> | |
1963 <struct>JNIEnv</struct> | |
1964 </outptr> | |
1965 <description> | |
1966 The JNI environment. | |
1967 </description> | |
1968 </param> | |
1969 <param id="arg"> | |
1970 <outptr> | |
1971 <void/> | |
1972 </outptr> | |
1973 <description> | |
1974 The <code>arg</code> parameter passed to | |
1975 <functionlink id="RunAgentThread"></functionlink>. | |
1976 </description> | |
1977 </param> | |
1978 </parameters> | |
1979 </callback> | |
1980 | |
1981 <function id="RunAgentThread" num="12"> | |
1982 <synopsis>Run Agent Thread</synopsis> | |
1983 <description> | |
1984 Starts the execution of an agent thread. with the specified native function. | |
1985 The parameter <paramlink id="arg"></paramlink> is forwarded on to the | |
1986 <functionlink id="jvmtiStartFunction">start function</functionlink> | |
1987 (specified with <paramlink id="proc"></paramlink>) as its single argument. | |
1988 This function allows the creation of agent threads | |
1989 for handling communication with another process or for handling events | |
1990 without the need to load a special subclass of <code>java.lang.Thread</code> or | |
1991 implementer of <code>java.lang.Runnable</code>. | |
1992 Instead, the created thread can run entirely in native code. | |
1993 However, the created thread does require a newly created instance | |
1994 of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to | |
1995 which it will be associated. | |
1996 The thread object can be created with JNI calls. | |
1997 <p/> | |
1998 The following common thread priorities are provided for your convenience: | |
1999 <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const"> | |
2000 <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1"> | |
2001 Minimum possible thread priority | |
2002 </constant> | |
2003 <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5"> | |
2004 Normal thread priority | |
2005 </constant> | |
2006 <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10"> | |
2007 Maximum possible thread priority | |
2008 </constant> | |
2009 </constants> | |
2010 <p/> | |
2011 The new thread is started as a daemon thread with the specified | |
2012 <paramlink id="priority"></paramlink>. | |
2013 If enabled, a <eventlink id="ThreadStart"/> event will be sent. | |
2014 <p/> | |
2015 Since the thread has been started, the thread will be live when this function | |
2016 returns, unless the thread has died immediately. | |
2017 <p/> | |
2018 The thread group of the thread is ignored -- specifically, the thread is not | |
2019 added to the thread group and the thread is not seen on queries of the thread | |
2020 group at either the Java programming language or <jvmti/> levels. | |
2021 <p/> | |
2022 The thread is not visible to Java programming language queries but is | |
2023 included in <jvmti/> queries (for example, | |
2024 <functionlink id="GetAllThreads"/> and | |
2025 <functionlink id="GetAllStackTraces"/>). | |
2026 <p/> | |
2027 Upon execution of <code>proc</code>, the new thread will be attached to the | |
2028 VM--see the JNI documentation on | |
2029 <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/invocation.html#wp1060" | |
2030 >Attaching to the VM</externallink>. | |
2031 </description> | |
2032 <origin>jvmdiClone</origin> | |
2033 <capabilities> | |
2034 </capabilities> | |
2035 <parameters> | |
2036 <param id="thread"> | |
2037 <jthread impl="noconvert" started="no"/> | |
2038 <description> | |
2039 The thread to run. | |
2040 </description> | |
2041 </param> | |
2042 <param id="proc"> | |
2043 <ptrtype> | |
2044 <struct>jvmtiStartFunction</struct> | |
2045 </ptrtype> | |
2046 <description> | |
2047 The start function. | |
2048 </description> | |
2049 </param> | |
2050 <param id="arg"> | |
2051 <inbuf> | |
2052 <void/> | |
2053 <nullok><code>NULL</code> is passed to the start function</nullok> | |
2054 </inbuf> | |
2055 <description> | |
2056 The argument to the start function. | |
2057 </description> | |
2058 </param> | |
2059 <param id="priority"> | |
2060 <jint/> | |
2061 <description> | |
2062 The priority of the started thread. Any thread | |
2063 priority allowed by <code>java.lang.Thread.setPriority</code> can be used including | |
2064 those in <datalink id="jvmtiThreadPriority"></datalink>. | |
2065 </description> | |
2066 </param> | |
2067 </parameters> | |
2068 <errors> | |
2069 <error id="JVMTI_ERROR_INVALID_PRIORITY"> | |
2070 <paramlink id="priority"/> is less than | |
2071 <datalink id="JVMTI_THREAD_MIN_PRIORITY"/> | |
2072 or greater than | |
2073 <datalink id="JVMTI_THREAD_MAX_PRIORITY"/> | |
2074 </error> | |
2075 </errors> | |
2076 </function> | |
2077 | |
2078 <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103"> | |
2079 <synopsis>Set Thread Local Storage</synopsis> | |
2080 <description> | |
2081 The VM stores a pointer value associated with each environment-thread | |
2082 pair. This pointer value is called <i>thread-local storage</i>. | |
2083 This value is <code>NULL</code> unless set with this function. | |
2084 Agents can allocate memory in which they store thread specific | |
2085 information. By setting thread-local storage it can then be | |
2086 accessed with | |
2087 <functionlink id="GetThreadLocalStorage"></functionlink>. | |
2088 <p/> | |
2089 This function is called by the agent to set the value of the <jvmti/> | |
2090 thread-local storage. <jvmti/> supplies to the agent a pointer-size | |
2091 thread-local storage that can be used to record per-thread | |
2092 information. | |
2093 </description> | |
2094 <origin>jvmpi</origin> | |
2095 <capabilities> | |
2096 </capabilities> | |
2097 <parameters> | |
2098 <param id="thread"> | |
2099 <jthread null="current"/> | |
2100 <description> | |
2101 Store to this thread. | |
2102 </description> | |
2103 </param> | |
2104 <param id="data"> | |
2105 <inbuf> | |
2106 <void/> | |
2107 <nullok>value is set to <code>NULL</code></nullok> | |
2108 </inbuf> | |
2109 <description> | |
2110 The value to be entered into the thread-local storage. | |
2111 </description> | |
2112 </param> | |
2113 </parameters> | |
2114 <errors> | |
2115 </errors> | |
2116 </function> | |
2117 | |
2118 <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102"> | |
2119 <synopsis>Get Thread Local Storage</synopsis> | |
2120 <description> | |
2121 Called by the agent to get the value of the <jvmti/> thread-local | |
2122 storage. | |
2123 </description> | |
2124 <origin>jvmpi</origin> | |
2125 <capabilities> | |
2126 </capabilities> | |
2127 <parameters> | |
2128 <param id="thread"> | |
2129 <jthread null="current" impl="noconvert"/> | |
2130 <description> | |
2131 Retrieve from this thread. | |
2132 </description> | |
2133 </param> | |
2134 <param id="data_ptr"> | |
2135 <agentbuf><void/></agentbuf> | |
2136 <description> | |
2137 Pointer through which the value of the thread local | |
2138 storage is returned. | |
2139 If thread-local storage has not been set with | |
2140 <functionlink id="SetThreadLocalStorage"></functionlink> the returned | |
2141 pointer is <code>NULL</code>. | |
2142 </description> | |
2143 </param> | |
2144 </parameters> | |
2145 <errors> | |
2146 </errors> | |
2147 </function> | |
2148 | |
2149 </category> | |
2150 | |
2151 <category id="thread_groups" label="Thread Group"> | |
2152 <intro> | |
2153 </intro> | |
2154 | |
2155 <function id="GetTopThreadGroups" num="13"> | |
2156 <synopsis>Get Top Thread Groups</synopsis> | |
2157 <description> | |
2158 Return all top-level (parentless) thread groups in the VM. | |
2159 </description> | |
2160 <origin>jvmdi</origin> | |
2161 <capabilities> | |
2162 </capabilities> | |
2163 <parameters> | |
2164 <param id="group_count_ptr"> | |
2165 <outptr><jint/></outptr> | |
2166 <description> | |
2167 On return, points to the number of top-level thread groups. | |
2168 </description> | |
2169 </param> | |
2170 <param id="groups_ptr"> | |
2171 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> | |
2172 <description> | |
2173 On return, refers to a pointer to the top-level thread group array. | |
2174 </description> | |
2175 </param> | |
2176 </parameters> | |
2177 <errors> | |
2178 </errors> | |
2179 </function> | |
2180 | |
2181 <function id="GetThreadGroupInfo" num="14"> | |
2182 <synopsis>Get Thread Group Info</synopsis> | |
2183 <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure"> | |
2184 <field id="parent"> | |
2185 <jthreadGroup/> | |
2186 <description> | |
2187 The parent thread group. | |
2188 </description> | |
2189 </field> | |
2190 <field id="name"> | |
2191 <allocfieldbuf><char/></allocfieldbuf> | |
2192 <description> | |
2193 The thread group's name, encoded as a | |
2194 <internallink id="mUTF">modified UTF-8</internallink> string. | |
2195 </description> | |
2196 </field> | |
2197 <field id="max_priority"> | |
2198 <jint/> | |
2199 <description> | |
2200 The maximum priority for this thread group. | |
2201 </description> | |
2202 </field> | |
2203 <field id="is_daemon"> | |
2204 <jboolean/> | |
2205 <description> | |
2206 Is this a daemon thread group? | |
2207 </description> | |
2208 </field> | |
2209 </typedef> | |
2210 <description> | |
2211 Get information about the thread group. The fields of the | |
2212 <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure | |
2213 are filled in with details of the specified thread group. | |
2214 </description> | |
2215 <origin>jvmdi</origin> | |
2216 <capabilities> | |
2217 </capabilities> | |
2218 <parameters> | |
2219 <param id="group"> | |
2220 <jthreadGroup/> | |
2221 <description> | |
2222 The thread group to query. | |
2223 </description> | |
2224 </param> | |
2225 <param id="info_ptr"> | |
2226 <outptr><struct>jvmtiThreadGroupInfo</struct></outptr> | |
2227 <description> | |
2228 On return, filled with information describing the specified | |
2229 thread group. | |
2230 </description> | |
2231 </param> | |
2232 </parameters> | |
2233 <errors> | |
2234 </errors> | |
2235 </function> | |
2236 | |
2237 <function id="GetThreadGroupChildren" num="15"> | |
2238 <synopsis>Get Thread Group Children</synopsis> | |
2239 <description> | |
2240 Get the live threads and active subgroups in this thread group. | |
2241 </description> | |
2242 <origin>jvmdi</origin> | |
2243 <capabilities> | |
2244 </capabilities> | |
2245 <parameters> | |
2246 <param id="group"> | |
2247 <jthreadGroup/> | |
2248 <description> | |
2249 The group to query. | |
2250 </description> | |
2251 </param> | |
2252 <param id="thread_count_ptr"> | |
2253 <outptr><jint/></outptr> | |
2254 <description> | |
2255 On return, points to the number of live threads in this thread group. | |
2256 </description> | |
2257 </param> | |
2258 <param id="threads_ptr"> | |
2259 <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf> | |
2260 <description> | |
2261 On return, points to an array of the live threads in this thread group. | |
2262 </description> | |
2263 </param> | |
2264 <param id="group_count_ptr"> | |
2265 <outptr><jint/></outptr> | |
2266 <description> | |
2267 On return, points to the number of active child thread groups | |
2268 </description> | |
2269 </param> | |
2270 <param id="groups_ptr"> | |
2271 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> | |
2272 <description> | |
2273 On return, points to an array of the active child thread groups. | |
2274 </description> | |
2275 </param> | |
2276 </parameters> | |
2277 <errors> | |
2278 </errors> | |
2279 </function> | |
2280 </category> | |
2281 | |
2282 <category id="stack" label="Stack Frame"> | |
2283 <intro> | |
2284 These functions provide information about the stack of a thread. | |
2285 Stack frames are referenced by depth. | |
2286 The frame at depth zero is the current frame. | |
2287 <p/> | |
2288 Stack frames are as described in the | |
2289 <vmspeclink id="Overview.doc.html#17257" | |
2290 name="Frames section"/>. | |
2291 That is, they correspond to method | |
2292 invocations (including native methods) but do not correspond to platform native or | |
2293 VM internal frames. | |
2294 <p/> | |
2295 A <jvmti/> implementation may use method invocations to launch a thread and | |
2296 the corresponding frames may be included in the stack as presented by these functions -- | |
2297 that is, there may be frames shown | |
2298 deeper than <code>main()</code> and <code>run()</code>. | |
2299 However this presentation must be consistent across all <jvmti/> functionality which | |
2300 uses stack frames or stack depth. | |
2301 </intro> | |
2302 | |
2303 <typedef id="jvmtiFrameInfo" label="Stack frame information structure"> | |
2304 <description> | |
2305 Information about a stack frame is returned in this structure. | |
2306 </description> | |
2307 <field id="method"> | |
2308 <jmethodID/> | |
2309 <description> | |
2310 The method executing in this frame. | |
2311 </description> | |
2312 </field> | |
2313 <field id="location"> | |
2314 <jlocation/> | |
2315 <description> | |
2316 The index of the instruction executing in this frame. | |
2317 <code>-1</code> if the frame is executing a native method. | |
2318 </description> | |
2319 </field> | |
2320 </typedef> | |
2321 | |
2322 <typedef id="jvmtiStackInfo" label="Stack information structure"> | |
2323 <description> | |
2324 Information about a set of stack frames is returned in this structure. | |
2325 </description> | |
2326 <field id="thread"> | |
2327 <jthread/> | |
2328 <description> | |
2329 On return, the thread traced. | |
2330 </description> | |
2331 </field> | |
2332 <field id="state"> | |
2333 <jint/> | |
2334 <description> | |
2335 On return, the thread state. See <functionlink id="GetThreadState"></functionlink>. | |
2336 </description> | |
2337 </field> | |
2338 <field id="frame_buffer"> | |
2339 <outbuf incount="max_frame_count"> | |
2340 <struct>jvmtiFrameInfo</struct> | |
2341 </outbuf> | |
2342 <description> | |
2343 On return, this agent allocated buffer is filled | |
2344 with stack frame information. | |
2345 </description> | |
2346 </field> | |
2347 <field id="frame_count"> | |
2348 <jint/> | |
2349 <description> | |
2350 On return, the number of records filled into | |
2351 <code>frame_buffer</code>. | |
2352 This will be | |
2353 min(<code>max_frame_count</code>, <i>stackDepth</i>). | |
2354 </description> | |
2355 </field> | |
2356 </typedef> | |
2357 | |
2358 <function id="GetStackTrace" num="104"> | |
2359 <synopsis>Get Stack Trace</synopsis> | |
2360 <description> | |
2361 Get information about the stack of a thread. | |
2362 If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack, | |
2363 the <paramlink id="max_frame_count"></paramlink> topmost frames are returned, | |
2364 otherwise the entire stack is returned. | |
2365 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
2366 <p/> | |
2367 The following example causes up to five of the topmost frames | |
2368 to be returned and (if there are any frames) the currently | |
2369 executing method name to be printed. | |
2370 <example> | |
2371 jvmtiFrameInfo frames[5]; | |
2372 jint count; | |
2373 jvmtiError err; | |
2374 | |
2375 err = (*jvmti)->GetStackTrace(jvmti, aThread, 0, 5, | |
2376 &frames, &count); | |
2377 if (err == JVMTI_ERROR_NONE && count >= 1) { | |
2378 char *methodName; | |
2379 err = (*jvmti)->GetMethodName(jvmti, frames[0].method, | |
2380 &methodName, NULL); | |
2381 if (err == JVMTI_ERROR_NONE) { | |
2382 printf("Executing method: %s", methodName); | |
2383 } | |
2384 } | |
2385 </example> | |
2386 <todo> | |
2387 check example code. | |
2388 </todo> | |
2389 <p/> | |
2390 The <paramlink id="thread"></paramlink> need not be suspended | |
2391 to call this function. | |
2392 <p/> | |
2393 The <functionlink id="GetLineNumberTable"></functionlink> | |
2394 function can be used to map locations to line numbers. Note that | |
2395 this mapping can be done lazily. | |
2396 </description> | |
2397 <origin>jvmpi</origin> | |
2398 <capabilities> | |
2399 </capabilities> | |
2400 <parameters> | |
2401 <param id="thread"> | |
2402 <jthread null="current"/> | |
2403 <description> | |
2404 Fetch the stack trace of this thread. | |
2405 </description> | |
2406 </param> | |
2407 <param id="start_depth"> | |
2408 <jint/> | |
2409 <description> | |
2410 Begin retrieving frames at this depth. | |
2411 If non-negative, count from the current frame, | |
2412 the first frame retrieved is at depth <code>start_depth</code>. | |
2413 For example, if zero, start from the current frame; if one, start from the | |
2414 caller of the current frame; if two, start from the caller of the | |
2415 caller of the current frame; and so on. | |
2416 If negative, count from below the oldest frame, | |
2417 the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>, | |
2418 where <i>stackDepth</i> is the count of frames on the stack. | |
2419 For example, if negative one, only the oldest frame is retrieved; | |
2420 if negative two, start from the frame called by the oldest frame. | |
2421 </description> | |
2422 </param> | |
2423 <param id="max_frame_count"> | |
2424 <jint min="0"/> | |
2425 <description> | |
2426 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. | |
2427 </description> | |
2428 </param> | |
2429 <param id="frame_buffer"> | |
2430 <outbuf incount="max_frame_count" outcount="count_ptr"> | |
2431 <struct>jvmtiFrameInfo</struct> | |
2432 </outbuf> | |
2433 <description> | |
2434 On return, this agent allocated buffer is filled | |
2435 with stack frame information. | |
2436 </description> | |
2437 </param> | |
2438 <param id="count_ptr"> | |
2439 <outptr><jint/></outptr> | |
2440 <description> | |
2441 On return, points to the number of records filled in. | |
2442 For non-negative <code>start_depth</code>, this will be | |
2443 min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>). | |
2444 For negative <code>start_depth</code>, this will be | |
2445 min(<code>max_frame_count</code>, <code>-start_depth</code>). | |
2446 </description> | |
2447 </param> | |
2448 </parameters> | |
2449 <errors> | |
2450 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
2451 <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>. | |
2452 Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>. | |
2453 </error> | |
2454 </errors> | |
2455 </function> | |
2456 | |
2457 | |
2458 <function id="GetAllStackTraces" num="100"> | |
2459 <synopsis>Get All Stack Traces</synopsis> | |
2460 <description> | |
2461 Get information about the stacks of all live threads | |
2462 (including <internallink id="RunAgentThread">agent threads</internallink>). | |
2463 If <paramlink id="max_frame_count"/> is less than the depth of a stack, | |
2464 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, | |
2465 otherwise the entire stack is returned. | |
2466 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
2467 <p/> | |
2468 All stacks are collected simultaneously, that is, no changes will occur to the | |
2469 thread state or stacks between the sampling of one thread and the next. | |
2470 The threads need not be suspended. | |
2471 | |
2472 <example> | |
2473 jvmtiStackInfo *stack_info; | |
2474 jint thread_count; | |
2475 int ti; | |
2476 jvmtiError err; | |
2477 | |
2478 err = (*jvmti)->GetAllStackTraces(jvmti, MAX_FRAMES, &stack_info, &thread_count); | |
2479 if (err != JVMTI_ERROR_NONE) { | |
2480 ... | |
2481 } | |
2482 for (ti = 0; ti < thread_count; ++ti) { | |
2483 jvmtiStackInfo *infop = &stack_info[ti]; | |
2484 jthread thread = infop->thread; | |
2485 jint state = infop->state; | |
2486 jvmtiFrameInfo *frames = infop->frame_buffer; | |
2487 int fi; | |
2488 | |
2489 myThreadAndStatePrinter(thread, state); | |
2490 for (fi = 0; fi < infop->frame_count; fi++) { | |
2491 myFramePrinter(frames[fi].method, frames[fi].location); | |
2492 } | |
2493 } | |
2494 /* this one Deallocate call frees all data allocated by GetAllStackTraces */ | |
2495 err = (*jvmti)->Deallocate(jvmti, stack_info); | |
2496 </example> | |
2497 <todo> | |
2498 check example code. | |
2499 </todo> | |
2500 | |
2501 </description> | |
2502 <origin>new</origin> | |
2503 <capabilities> | |
2504 </capabilities> | |
2505 <parameters> | |
2506 <param id="max_frame_count"> | |
2507 <jint min="0"/> | |
2508 <description> | |
2509 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. | |
2510 </description> | |
2511 </param> | |
2512 <param id="stack_info_ptr"> | |
2513 <allocbuf> | |
2514 <struct>jvmtiStackInfo</struct> | |
2515 </allocbuf> | |
2516 <description> | |
2517 On return, this buffer is filled | |
2518 with stack information for each thread. | |
2519 The number of <datalink id="jvmtiStackInfo"/> records is determined | |
2520 by <paramlink id="thread_count_ptr"/>. | |
2521 <p/> | |
2522 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> | |
2523 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. | |
2524 These buffers must not be separately deallocated. | |
2525 </description> | |
2526 </param> | |
2527 <param id="thread_count_ptr"> | |
2528 <outptr><jint/></outptr> | |
2529 <description> | |
2530 The number of threads traced. | |
2531 </description> | |
2532 </param> | |
2533 </parameters> | |
2534 <errors> | |
2535 </errors> | |
2536 </function> | |
2537 | |
2538 <function id="GetThreadListStackTraces" num="101"> | |
2539 <synopsis>Get Thread List Stack Traces</synopsis> | |
2540 <description> | |
2541 Get information about the stacks of the supplied threads. | |
2542 If <paramlink id="max_frame_count"/> is less than the depth of a stack, | |
2543 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, | |
2544 otherwise the entire stack is returned. | |
2545 The topmost frames, those most recently invoked, are at the beginning of the returned buffer. | |
2546 <p/> | |
2547 All stacks are collected simultaneously, that is, no changes will occur to the | |
2548 thread state or stacks between the sampling one thread and the next. | |
2549 The threads need not be suspended. | |
2550 <p/> | |
2551 If a thread has not yet started or terminates before the stack information is collected, | |
2552 a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero) | |
2553 will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked. | |
2554 <p/> | |
2555 See the example for the similar function | |
2556 <functionlink id="GetAllStackTraces"/>. | |
2557 </description> | |
2558 <origin>new</origin> | |
2559 <capabilities> | |
2560 </capabilities> | |
2561 <parameters> | |
2562 <param id="thread_count"> | |
2563 <jint min="0"/> | |
2564 <description> | |
2565 The number of threads to trace. | |
2566 </description> | |
2567 </param> | |
2568 <param id="thread_list"> | |
2569 <inbuf incount="thread_count"><jthread/></inbuf> | |
2570 <description> | |
2571 The list of threads to trace. | |
2572 </description> | |
2573 </param> | |
2574 <param id="max_frame_count"> | |
2575 <jint min="0"/> | |
2576 <description> | |
2577 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. | |
2578 </description> | |
2579 </param> | |
2580 <param id="stack_info_ptr"> | |
2581 <allocbuf outcount="thread_count"> | |
2582 <struct>jvmtiStackInfo</struct> | |
2583 </allocbuf> | |
2584 <description> | |
2585 On return, this buffer is filled | |
2586 with stack information for each thread. | |
2587 The number of <datalink id="jvmtiStackInfo"/> records is determined | |
2588 by <paramlink id="thread_count"/>. | |
2589 <p/> | |
2590 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> | |
2591 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. | |
2592 These buffers must not be separately deallocated. | |
2593 </description> | |
2594 </param> | |
2595 </parameters> | |
2596 <errors> | |
2597 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
2598 An element in <paramlink id="thread_list"/> is not a thread object. | |
2599 </error> | |
2600 </errors> | |
2601 </function> | |
2602 | |
2603 <elide> | |
2604 <function id="AsyncGetStackTrace" num="1000"> | |
2605 <synopsis>Get Stack Trace--Asynchronous</synopsis> | |
2606 <description> | |
2607 Get information about the entire stack of a thread (or a sub-section of it). | |
2608 This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink> | |
2609 and is reentrant and safe to call | |
2610 from asynchronous signal handlers. | |
2611 The stack trace is returned only for the calling thread. | |
2612 <p/> | |
2613 The <functionlink id="GetLineNumberTable"></functionlink> | |
2614 function can be used to map locations to line numbers. Note that | |
2615 this mapping can be done lazily. | |
2616 </description> | |
2617 <origin>jvmpi</origin> | |
2618 <capabilities> | |
2619 <required id="can_get_async_stack_trace"></required> | |
2620 <capability id="can_show_JVM_spec_async_frames"> | |
2621 If <code>false</code>, | |
2622 <paramlink id="use_java_stack"></paramlink> | |
2623 must be <code>false</code>. | |
2624 </capability> | |
2625 </capabilities> | |
2626 <parameters> | |
2627 <param id="use_java_stack"> | |
2628 <jboolean/> | |
2629 <description> | |
2630 Return the stack showing the <vmspeclink/> | |
2631 model of the stack; | |
2632 otherwise, show the internal representation of the stack with | |
2633 inlined and optimized methods missing. If the virtual machine | |
2634 is using the <i>Java Virtual Machine Specification</i> stack model | |
2635 internally, this flag is ignored. | |
2636 </description> | |
2637 </param> | |
2638 <param id="max_count"> | |
2639 <jint min="0"/> | |
2640 <description> | |
2641 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. | |
2642 Retrieve this many unless the stack depth is less than <code>max_count</code>. | |
2643 </description> | |
2644 </param> | |
2645 <param id="frame_buffer"> | |
2646 <outbuf incount="max_count" outcount="count_ptr"> | |
2647 <struct>jvmtiFrameInfo</struct> | |
2648 <nullok>this information is not returned</nullok> | |
2649 </outbuf> | |
2650 <description> | |
2651 The agent passes in a buffer | |
2652 large enough to hold <code>max_count</code> records of | |
2653 <datalink id="jvmtiFrameInfo"></datalink>. This buffer must be | |
2654 pre-allocated by the agent. | |
2655 </description> | |
2656 </param> | |
2657 <param id="count_ptr"> | |
2658 <outptr><jint/></outptr> | |
2659 <description> | |
2660 On return, points to the number of records filled in.. | |
2661 </description> | |
2662 </param> | |
2663 </parameters> | |
2664 <errors> | |
2665 <error id="JVMTI_ERROR_UNATTACHED_THREAD"> | |
2666 The thread being used to call this function is not attached | |
2667 to the virtual machine. Calls must be made from attached threads. | |
2668 </error> | |
2669 </errors> | |
2670 </function> | |
2671 </elide> | |
2672 | |
2673 <function id="GetFrameCount" num="16"> | |
2674 <synopsis>Get Frame Count</synopsis> | |
2675 <description> | |
2676 Get the number of frames currently in the specified thread's call stack. | |
2677 <p/> | |
2678 If this function is called for a thread actively executing bytecodes (for example, | |
2679 not the current thread and not suspended), the information returned is transient. | |
2680 </description> | |
2681 <origin>jvmdi</origin> | |
2682 <capabilities> | |
2683 </capabilities> | |
2684 <parameters> | |
2685 <param id="thread"> | |
2686 <jthread null="current"/> | |
2687 <description> | |
2688 The thread to query. | |
2689 </description> | |
2690 </param> | |
2691 <param id="count_ptr"> | |
2692 <outptr><jint/></outptr> | |
2693 <description> | |
2694 On return, points to the number of frames in the call stack. | |
2695 </description> | |
2696 </param> | |
2697 </parameters> | |
2698 <errors> | |
2699 </errors> | |
2700 </function> | |
2701 | |
2702 <function id="PopFrame" num="80"> | |
2703 <synopsis>Pop Frame</synopsis> | |
2704 <description> | |
2705 Pop the current frame of <code>thread</code>'s stack. | |
2706 Popping a frame takes you to the previous frame. | |
2707 When the thread is resumed, the execution | |
2708 state of the thread is reset to the state | |
2709 immediately before the called method was invoked. | |
2710 That is (using the <vmspeclink/> terminology): | |
2711 <ul> | |
2712 <li>the current frame is discarded as the previous frame becomes the current one</li> | |
2713 <li>the operand stack is restored--the argument values are added back | |
2714 and if the invoke was not <code>invokestatic</code>, | |
2715 <code>objectref</code> is added back as well</li> | |
2716 <li>the Java virtual machine PC is restored to the opcode | |
2717 of the invoke instruction</li> | |
2718 </ul> | |
2719 Note however, that any changes to the arguments, which | |
2720 occurred in the called method, remain; | |
2721 when execution continues, the first instruction to | |
2722 execute will be the invoke. | |
2723 <p/> | |
2724 Between calling <code>PopFrame</code> and resuming the | |
2725 thread the state of the stack is undefined. | |
2726 To pop frames beyond the first, | |
2727 these three steps must be repeated: | |
2728 <ul> | |
2729 <li>suspend the thread via an event (step, breakpoint, ...)</li> | |
2730 <li>call <code>PopFrame</code></li> | |
2731 <li>resume the thread</li> | |
2732 </ul> | |
2733 <p/> | |
2734 A lock acquired by calling the called method | |
2735 (if it is a <code>synchronized</code> method) | |
2736 and locks acquired by entering <code>synchronized</code> | |
2737 blocks within the called method are released. | |
2738 Note: this does not apply to native locks or | |
2739 <code>java.util.concurrent.locks</code> locks. | |
2740 <p/> | |
2741 Finally blocks are not executed. | |
2742 <p/> | |
2743 Changes to global state are not addressed and thus remain changed. | |
2744 <p/> | |
2745 The specified thread must be suspended (which implies it cannot be the current thread). | |
2746 <p/> | |
2747 Both the called method and calling method must be non-native Java programming | |
2748 language methods. | |
2749 <p/> | |
2750 No <jvmti/> events are generated by this function. | |
2751 </description> | |
2752 <origin>jvmdi</origin> | |
2753 <capabilities> | |
2754 <required id="can_pop_frame"></required> | |
2755 </capabilities> | |
2756 <parameters> | |
2757 <param id="thread"> | |
2758 <jthread/> | |
2759 <description> | |
2760 The thread whose current frame is to be popped. | |
2761 </description> | |
2762 </param> | |
2763 </parameters> | |
2764 <errors> | |
2765 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
2766 Called or calling method is a native method. | |
2767 The implementation is unable to pop this frame. | |
2768 </error> | |
2769 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
2770 Thread was not suspended. | |
2771 </error> | |
2772 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
2773 There are less than two stack frames on the call stack. | |
2774 </error> | |
2775 </errors> | |
2776 </function> | |
2777 | |
2778 <function id="GetFrameLocation" num="19"> | |
2779 <synopsis>Get Frame Location</synopsis> | |
2780 <description> | |
2781 <p/> | |
2782 For a Java programming language frame, return the location of the instruction | |
2783 currently executing. | |
2784 </description> | |
2785 <origin>jvmdiClone</origin> | |
2786 <capabilities> | |
2787 </capabilities> | |
2788 <parameters> | |
2789 <param id="thread"> | |
2790 <jthread null="current" frame="frame"/> | |
2791 <description> | |
2792 The thread of the frame to query. | |
2793 </description> | |
2794 </param> | |
2795 <param id="depth"> | |
2796 <jframeID thread="thread"/> | |
2797 <description> | |
2798 The depth of the frame to query. | |
2799 </description> | |
2800 </param> | |
2801 <param id="method_ptr"> | |
2802 <outptr><jmethodID/></outptr> | |
2803 <description> | |
2804 On return, points to the method for the current location. | |
2805 </description> | |
2806 </param> | |
2807 <param id="location_ptr"> | |
2808 <outptr><jlocation/></outptr> | |
2809 <description> | |
2810 On return, points to the index of the currently | |
2811 executing instruction. | |
2812 Is set to <code>-1</code> if the frame is executing | |
2813 a native method. | |
2814 </description> | |
2815 </param> | |
2816 </parameters> | |
2817 <errors> | |
2818 </errors> | |
2819 </function> | |
2820 | |
2821 <function id="NotifyFramePop" num="20"> | |
2822 <synopsis>Notify Frame Pop</synopsis> | |
2823 <description> | |
2824 When the frame that is currently at <paramlink id="depth"></paramlink> | |
2825 is popped from the stack, generate a | |
2826 <eventlink id="FramePop"></eventlink> event. See the | |
2827 <eventlink id="FramePop"></eventlink> event for details. | |
2828 Only frames corresponding to non-native Java programming language | |
2829 methods can receive notification. | |
2830 <p/> | |
2831 The specified thread must either be the current thread | |
2832 or the thread must be suspended. | |
2833 </description> | |
2834 <origin>jvmdi</origin> | |
2835 <capabilities> | |
2836 <required id="can_generate_frame_pop_events"></required> | |
2837 </capabilities> | |
2838 <parameters> | |
2839 <param id="thread"> | |
2840 <jthread null="current" frame="depth"/> | |
2841 <description> | |
2842 The thread of the frame for which the frame pop event will be generated. | |
2843 </description> | |
2844 </param> | |
2845 <param id="depth"> | |
2846 <jframeID thread="thread"/> | |
2847 <description> | |
2848 The depth of the frame for which the frame pop event will be generated. | |
2849 </description> | |
2850 </param> | |
2851 </parameters> | |
2852 <errors> | |
2853 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
2854 The frame at <code>depth</code> is executing a | |
2855 native method. | |
2856 </error> | |
2857 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
2858 Thread was not suspended and was not the current thread. | |
2859 </error> | |
2860 </errors> | |
2861 </function> | |
2862 | |
2863 </category> | |
2864 | |
2865 <category id="ForceEarlyReturn" label="Force Early Return"> | |
2866 <intro> | |
2867 These functions allow an agent to force a method | |
2868 to return at any point during its execution. | |
2869 The method which will return early is referred to as the <i>called method</i>. | |
2870 The called method is the current method | |
2871 (as defined by the | |
2872 <vmspeclink id="Overview.doc.html#17257" | |
2873 name="Frames section"/>) | |
2874 for the specified thread at | |
2875 the time the function is called. | |
2876 <p/> | |
2877 The specified thread must be suspended or must be the current thread. | |
2878 The return occurs when execution of Java programming | |
2879 language code is resumed on this thread. | |
2880 Between calling one of these functions and resumption | |
2881 of thread execution, the state of the stack is undefined. | |
2882 <p/> | |
2883 No further instructions are executed in the called method. | |
2884 Specifically, finally blocks are not executed. | |
2885 Note: this can cause inconsistent states in the application. | |
2886 <p/> | |
2887 A lock acquired by calling the called method | |
2888 (if it is a <code>synchronized</code> method) | |
2889 and locks acquired by entering <code>synchronized</code> | |
2890 blocks within the called method are released. | |
2891 Note: this does not apply to native locks or | |
2892 <code>java.util.concurrent.locks</code> locks. | |
2893 <p/> | |
2894 Events, such as <eventlink id="MethodExit"></eventlink>, | |
2895 are generated as they would be in a normal return. | |
2896 <p/> | |
2897 The called method must be a non-native Java programming | |
2898 language method. | |
2899 Forcing return on a thread with only one frame on the | |
2900 stack causes the thread to exit when resumed. | |
2901 </intro> | |
2902 | |
2903 <function id="ForceEarlyReturnObject" num="81" since="1.1"> | |
2904 <synopsis>Force Early Return - Object</synopsis> | |
2905 <description> | |
2906 This function can be used to return from a method whose | |
2907 result type is <code>Object</code> | |
2908 or a subclass of <code>Object</code>. | |
2909 </description> | |
2910 <origin>new</origin> | |
2911 <capabilities> | |
2912 <required id="can_force_early_return"></required> | |
2913 </capabilities> | |
2914 <parameters> | |
2915 <param id="thread"> | |
2916 <jthread null="current"/> | |
2917 <description> | |
2918 The thread whose current frame is to return early. | |
2919 </description> | |
2920 </param> | |
2921 <param id="value"> | |
2922 <jobject/> | |
2923 <description> | |
2924 The return value for the called frame. | |
2925 An object or <code>NULL</code>. | |
2926 </description> | |
2927 </param> | |
2928 </parameters> | |
2929 <errors> | |
2930 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
2931 Attempted to return early from a frame | |
2932 corresponding to a native method. | |
2933 Or the implementation is unable to provide | |
2934 this functionality on this frame. | |
2935 </error> | |
2936 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
2937 The result type of the called method is not | |
2938 <code>Object</code> or a subclass of <code>Object</code>. | |
2939 </error> | |
2940 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
2941 The supplied <paramlink id="value"/> is not compatible with the | |
2942 result type of the called method. | |
2943 </error> | |
2944 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
2945 Thread was not the current thread and was not suspended. | |
2946 </error> | |
2947 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
2948 There are no more frames on the call stack. | |
2949 </error> | |
2950 </errors> | |
2951 </function> | |
2952 | |
2953 <function id="ForceEarlyReturnInt" num="82" since="1.1"> | |
2954 <synopsis>Force Early Return - Int</synopsis> | |
2955 <description> | |
2956 This function can be used to return from a method whose | |
2957 result type is <code>int</code>, <code>short</code>, | |
2958 <code>char</code>, <code>byte</code>, or | |
2959 <code>boolean</code>. | |
2960 </description> | |
2961 <origin>new</origin> | |
2962 <capabilities> | |
2963 <required id="can_force_early_return"></required> | |
2964 </capabilities> | |
2965 <parameters> | |
2966 <param id="thread"> | |
2967 <jthread null="current"/> | |
2968 <description> | |
2969 The thread whose current frame is to return early. | |
2970 </description> | |
2971 </param> | |
2972 <param id="value"> | |
2973 <jint/> | |
2974 <description> | |
2975 The return value for the called frame. | |
2976 </description> | |
2977 </param> | |
2978 </parameters> | |
2979 <errors> | |
2980 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
2981 Attempted to return early from a frame | |
2982 corresponding to a native method. | |
2983 Or the implementation is unable to provide | |
2984 this functionality on this frame. | |
2985 </error> | |
2986 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
2987 The result type of the called method is not | |
2988 <code>int</code>, <code>short</code>, | |
2989 <code>char</code>, <code>byte</code>, or | |
2990 <code>boolean</code>. | |
2991 </error> | |
2992 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
2993 Thread was not the current thread and was not suspended. | |
2994 </error> | |
2995 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
2996 There are no frames on the call stack. | |
2997 </error> | |
2998 </errors> | |
2999 </function> | |
3000 | |
3001 <function id="ForceEarlyReturnLong" num="83" since="1.1"> | |
3002 <synopsis>Force Early Return - Long</synopsis> | |
3003 <description> | |
3004 This function can be used to return from a method whose | |
3005 result type is <code>long</code>. | |
3006 </description> | |
3007 <origin>new</origin> | |
3008 <capabilities> | |
3009 <required id="can_force_early_return"></required> | |
3010 </capabilities> | |
3011 <parameters> | |
3012 <param id="thread"> | |
3013 <jthread null="current"/> | |
3014 <description> | |
3015 The thread whose current frame is to return early. | |
3016 </description> | |
3017 </param> | |
3018 <param id="value"> | |
3019 <jlong/> | |
3020 <description> | |
3021 The return value for the called frame. | |
3022 </description> | |
3023 </param> | |
3024 </parameters> | |
3025 <errors> | |
3026 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
3027 Attempted to return early from a frame | |
3028 corresponding to a native method. | |
3029 Or the implementation is unable to provide | |
3030 this functionality on this frame. | |
3031 </error> | |
3032 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
3033 The result type of the called method is not <code>long</code>. | |
3034 </error> | |
3035 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
3036 Thread was not the current thread and was not suspended. | |
3037 </error> | |
3038 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
3039 There are no frames on the call stack. | |
3040 </error> | |
3041 </errors> | |
3042 </function> | |
3043 | |
3044 <function id="ForceEarlyReturnFloat" num="84" since="1.1"> | |
3045 <synopsis>Force Early Return - Float</synopsis> | |
3046 <description> | |
3047 This function can be used to return from a method whose | |
3048 result type is <code>float</code>. | |
3049 </description> | |
3050 <origin>new</origin> | |
3051 <capabilities> | |
3052 <required id="can_force_early_return"></required> | |
3053 </capabilities> | |
3054 <parameters> | |
3055 <param id="thread"> | |
3056 <jthread null="current"/> | |
3057 <description> | |
3058 The thread whose current frame is to return early. | |
3059 </description> | |
3060 </param> | |
3061 <param id="value"> | |
3062 <jfloat/> | |
3063 <description> | |
3064 The return value for the called frame. | |
3065 </description> | |
3066 </param> | |
3067 </parameters> | |
3068 <errors> | |
3069 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
3070 Attempted to return early from a frame | |
3071 corresponding to a native method. | |
3072 Or the implementation is unable to provide | |
3073 this functionality on this frame. | |
3074 </error> | |
3075 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
3076 The result type of the called method is not <code>float</code>. | |
3077 </error> | |
3078 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
3079 Thread was not the current thread and was not suspended. | |
3080 </error> | |
3081 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
3082 There are no frames on the call stack. | |
3083 </error> | |
3084 </errors> | |
3085 </function> | |
3086 | |
3087 <function id="ForceEarlyReturnDouble" num="85" since="1.1"> | |
3088 <synopsis>Force Early Return - Double</synopsis> | |
3089 <description> | |
3090 This function can be used to return from a method whose | |
3091 result type is <code>double</code>. | |
3092 </description> | |
3093 <origin>new</origin> | |
3094 <capabilities> | |
3095 <required id="can_force_early_return"></required> | |
3096 </capabilities> | |
3097 <parameters> | |
3098 <param id="thread"> | |
3099 <jthread null="current"/> | |
3100 <description> | |
3101 The thread whose current frame is to return early. | |
3102 </description> | |
3103 </param> | |
3104 <param id="value"> | |
3105 <jdouble/> | |
3106 <description> | |
3107 The return value for the called frame. | |
3108 </description> | |
3109 </param> | |
3110 </parameters> | |
3111 <errors> | |
3112 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
3113 Attempted to return early from a frame corresponding to a native method. | |
3114 Or the implementation is unable to provide this functionality on this frame. | |
3115 </error> | |
3116 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
3117 The result type of the called method is not <code>double</code>. | |
3118 </error> | |
3119 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
3120 Thread was not the current thread and was not suspended. | |
3121 </error> | |
3122 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
3123 There are no frames on the call stack. | |
3124 </error> | |
3125 </errors> | |
3126 </function> | |
3127 | |
3128 <function id="ForceEarlyReturnVoid" num="86" since="1.1"> | |
3129 <synopsis>Force Early Return - Void</synopsis> | |
3130 <description> | |
3131 This function can be used to return from a method with no result type. | |
3132 That is, the called method must be declared <code>void</code>. | |
3133 </description> | |
3134 <origin>new</origin> | |
3135 <capabilities> | |
3136 <required id="can_force_early_return"></required> | |
3137 </capabilities> | |
3138 <parameters> | |
3139 <param id="thread"> | |
3140 <jthread null="current"/> | |
3141 <description> | |
3142 The thread whose current frame is to return early. | |
3143 </description> | |
3144 </param> | |
3145 </parameters> | |
3146 <errors> | |
3147 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
3148 Attempted to return early from a frame | |
3149 corresponding to a native method. | |
3150 Or the implementation is unable to provide | |
3151 this functionality on this frame. | |
3152 </error> | |
3153 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
3154 The called method has a result type. | |
3155 </error> | |
3156 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> | |
3157 Thread was not the current thread and was not suspended. | |
3158 </error> | |
3159 <error id="JVMTI_ERROR_NO_MORE_FRAMES"> | |
3160 There are no frames on the call stack. | |
3161 </error> | |
3162 </errors> | |
3163 </function> | |
3164 | |
3165 </category> | |
3166 | |
3167 <category id="Heap" label="Heap"> | |
3168 <intro> | |
3169 These functions are used to analyze the heap. | |
3170 Functionality includes the ability to view the objects in the | |
3171 heap and to tag these objects. | |
3172 </intro> | |
3173 | |
3174 <intro id="objectTags" label="Object Tags"> | |
3175 A <i>tag</i> is a value associated with an object. | |
3176 Tags are explicitly set by the agent using the | |
3177 <functionlink id="SetTag"></functionlink> function or by | |
3178 callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>. | |
3179 <p/> | |
3180 Tags are local to the environment; that is, the tags of one | |
3181 environment are not visible in another. | |
3182 <p/> | |
3183 Tags are <code>jlong</code> values which can be used | |
3184 simply to mark an object or to store a pointer to more detailed | |
3185 information. Objects which have not been tagged have a | |
3186 tag of zero. | |
3187 Setting a tag to zero makes the object untagged. | |
3188 </intro> | |
3189 | |
3190 <intro id="heapCallbacks" label="Heap Callback Functions"> | |
3191 Heap functions which iterate through the heap and recursively | |
3192 follow object references use agent supplied callback functions | |
3193 to deliver the information. | |
3194 <p/> | |
3195 These heap callback functions must adhere to the following restrictions -- | |
3196 These callbacks must not use JNI functions. | |
3197 These callbacks must not use <jvmti/> functions except | |
3198 <i>callback safe</i> functions which | |
3199 specifically allow such use (see the raw monitor, memory management, | |
3200 and environment local storage functions). | |
3201 <p/> | |
3202 An implementation may invoke a callback on an internal thread or | |
3203 the thread which called the iteration function. | |
3204 Heap callbacks are single threaded -- no more than one callback will | |
3205 be invoked at a time. | |
3206 <p/> | |
3207 The Heap Filter Flags can be used to prevent reporting | |
3208 based on the tag status of an object or its class. | |
3209 If no flags are set (the <code>jint</code> is zero), objects | |
3210 will not be filtered out. | |
3211 | |
3212 <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits"> | |
3213 <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4"> | |
3214 Filter out tagged objects. Objects which are tagged are not included. | |
3215 </constant> | |
3216 <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8"> | |
3217 Filter out untagged objects. Objects which are not tagged are not included. | |
3218 </constant> | |
3219 <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10"> | |
3220 Filter out objects with tagged classes. Objects whose class is tagged are not included. | |
3221 </constant> | |
3222 <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20"> | |
3223 Filter out objects with untagged classes. Objects whose class is not tagged are not included. | |
3224 </constant> | |
3225 </constants> | |
3226 | |
3227 <p/> | |
3228 The Heap Visit Control Flags are returned by the heap callbacks | |
3229 and can be used to abort the iteration. For the | |
3230 <functionlink id="jvmtiHeapReferenceCallback">Heap | |
3231 Reference Callback</functionlink>, it can also be used | |
3232 to prune the graph of traversed references | |
3233 (<code>JVMTI_VISIT_OBJECTS</code> is not set). | |
3234 | |
3235 <constants id="jvmtiHeapVisitControl" | |
3236 label="Heap Visit Control Flags" | |
3237 kind="bits" | |
3238 since="1.1"> | |
3239 <constant id="JVMTI_VISIT_OBJECTS" num="0x100"> | |
3240 If we are visiting an object and if this callback | |
3241 was initiated by <functionlink id="FollowReferences"/>, | |
3242 traverse the references of this object. | |
3243 Otherwise ignored. | |
3244 </constant> | |
3245 <constant id="JVMTI_VISIT_ABORT" num="0x8000"> | |
3246 Abort the iteration. Ignore all other bits. | |
3247 </constant> | |
3248 </constants> | |
3249 | |
3250 <p/> | |
3251 The Heap Reference Enumeration is provided by the | |
3252 <functionlink id="jvmtiHeapReferenceCallback">Heap | |
3253 Reference Callback</functionlink> and | |
3254 <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field | |
3255 Callback</functionlink> to | |
3256 describe the kind of reference | |
3257 being reported. | |
3258 | |
3259 <constants id="jvmtiHeapReferenceKind" | |
3260 label="Heap Reference Enumeration" | |
3261 kind="enum" | |
3262 since="1.1"> | |
3263 <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1"> | |
3264 Reference from an object to its class. | |
3265 </constant> | |
3266 <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2"> | |
3267 Reference from an object to the value of one of its instance fields. | |
3268 </constant> | |
3269 <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3"> | |
3270 Reference from an array to one of its elements. | |
3271 </constant> | |
3272 <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4"> | |
3273 Reference from a class to its class loader. | |
3274 </constant> | |
3275 <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5"> | |
3276 Reference from a class to its signers array. | |
3277 </constant> | |
3278 <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6"> | |
3279 Reference from a class to its protection domain. | |
3280 </constant> | |
3281 <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7"> | |
3282 Reference from a class to one of its interfaces. | |
3283 Note: interfaces are defined via a constant pool reference, | |
3284 so the referenced interfaces may also be reported with a | |
3285 <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. | |
3286 </constant> | |
3287 <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8"> | |
3288 Reference from a class to the value of one of its static fields. | |
3289 </constant> | |
3290 <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9"> | |
3291 Reference from a class to a resolved entry in the constant pool. | |
3292 </constant> | |
3293 <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10"> | |
3294 Reference from a class to its superclass. | |
3295 A callback is bot sent if the superclass is <code>java.lang.Object</code>. | |
3296 Note: loaded classes define superclasses via a constant pool | |
3297 reference, so the referenced superclass may also be reported with | |
3298 a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. | |
3299 </constant> | |
3300 <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21"> | |
3301 Heap root reference: JNI global reference. | |
3302 </constant> | |
3303 <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22"> | |
3304 Heap root reference: System class. | |
3305 </constant> | |
3306 <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23"> | |
3307 Heap root reference: monitor. | |
3308 </constant> | |
3309 <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24"> | |
3310 Heap root reference: local variable on the stack. | |
3311 </constant> | |
3312 <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25"> | |
3313 Heap root reference: JNI local reference. | |
3314 </constant> | |
3315 <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26"> | |
3316 Heap root reference: Thread. | |
3317 </constant> | |
3318 <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27"> | |
3319 Heap root reference: other heap root reference. | |
3320 </constant> | |
3321 </constants> | |
3322 | |
3323 <p/> | |
3324 Definitions for the single character type descriptors of | |
3325 primitive types. | |
3326 | |
3327 <constants id="jvmtiPrimitiveType" | |
3328 label="Primitive Type Enumeration" | |
3329 kind="enum" | |
3330 since="1.1"> | |
3331 <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90"> | |
3332 'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code> | |
3333 </constant> | |
3334 <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66"> | |
3335 'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code> | |
3336 </constant> | |
3337 <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67"> | |
3338 'C' - Java programming language <code>char</code> - JNI <code>jchar</code> | |
3339 </constant> | |
3340 <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83"> | |
3341 'S' - Java programming language <code>short</code> - JNI <code>jshort</code> | |
3342 </constant> | |
3343 <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73"> | |
3344 'I' - Java programming language <code>int</code> - JNI <code>jint</code> | |
3345 </constant> | |
3346 <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74"> | |
3347 'J' - Java programming language <code>long</code> - JNI <code>jlong</code> | |
3348 </constant> | |
3349 <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70"> | |
3350 'F' - Java programming language <code>float</code> - JNI <code>jfloat</code> | |
3351 </constant> | |
3352 <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68"> | |
3353 'D' - Java programming language <code>double</code> - JNI <code>jdouble</code> | |
3354 </constant> | |
3355 </constants> | |
3356 </intro> | |
3357 | |
3358 <typedef id="jvmtiHeapReferenceInfoField" | |
3359 label="Reference information structure for Field references" | |
3360 since="1.1"> | |
3361 <description> | |
3362 Reference information returned for | |
3363 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and | |
3364 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. | |
3365 </description> | |
3366 <field id="index"> | |
3367 <jint/> | |
3368 <description> | |
3369 For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the | |
3370 referrer object is not a class or an inteface. | |
3371 In this case, <code>index</code> is the index of the field | |
3372 in the class of the referrer object. | |
3373 This class is referred to below as <i>C</i>. | |
3374 <p/> | |
3375 For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, | |
3376 the referrer object is a class (referred to below as <i>C</i>) | |
3377 or an interface (referred to below as <i>I</i>). | |
3378 In this case, <code>index</code> is the index of the field in | |
3379 that class or interface. | |
3380 <p/> | |
3381 If the referrer object is not an interface, then the field | |
3382 indices are determined as follows: | |
3383 <ul> | |
3384 <li>make a list of all the fields in <i>C</i> and its | |
3385 superclasses, starting with all the fields in | |
3386 <code>java.lang.Object</code> and ending with all the | |
3387 fields in <i>C</i>.</li> | |
3388 <li>Within this list, put | |
3389 the fields for a given class in the order returned by | |
3390 <functionlink id="GetClassFields"/>.</li> | |
3391 <li>Assign the fields in this list indices | |
3392 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> | |
3393 is the count of the fields in all the interfaces | |
3394 implemented by <i>C</i>. | |
3395 Note that <i>C</i> implements all interfaces | |
3396 directly implemented by its superclasses; as well | |
3397 as all superinterfaces of these interfaces.</li> | |
3398 </ul> | |
3399 If the referrer object is an interface, then the field | |
3400 indices are determined as follows: | |
3401 <ul> | |
3402 <li>make a list of the fields directly declared in | |
3403 <i>I</i>.</li> | |
3404 <li>Within this list, put | |
3405 the fields in the order returned by | |
3406 <functionlink id="GetClassFields"/>.</li> | |
3407 <li>Assign the fields in this list indices | |
3408 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> | |
3409 is the count of the fields in all the superinterfaces | |
3410 of <i>I</i>.</li> | |
3411 </ul> | |
3412 All fields are included in this computation, regardless of | |
3413 field modifier (static, public, private, etc). | |
3414 <p/> | |
3415 For example, given the following classes and interfaces: | |
3416 <example> | |
3417 interface I0 { | |
3418 int p = 0; | |
3419 } | |
3420 | |
3421 interface I1 extends I0 { | |
3422 int x = 1; | |
3423 } | |
3424 | |
3425 interface I2 extends I0 { | |
3426 int y = 2; | |
3427 } | |
3428 | |
3429 class C1 implements I1 { | |
3430 public static int a = 3; | |
3431 private int b = 4; | |
3432 } | |
3433 | |
3434 class C2 extends C1 implements I2 { | |
3435 static int q = 5; | |
3436 final int r = 6; | |
3437 } | |
3438 </example> | |
3439 Assume that <functionlink id="GetClassFields"/> called on | |
3440 <code>C1</code> returns the fields of <code>C1</code> in the | |
3441 order: a, b; and that the fields of <code>C2</code> are | |
3442 returned in the order: q, r. | |
3443 An instance of class <code>C1</code> will have the | |
3444 following field indices: | |
3445 <dl><dd><table> | |
3446 <tr> | |
3447 <td> | |
3448 a | |
3449 </td> | |
3450 <td> | |
3451 2 | |
3452 </td> | |
3453 <td align="left"> | |
3454 The count of the fields in the interfaces | |
3455 implemented by <code>C1</code> is two (<i>n</i>=2): | |
3456 <code>p</code> of <code>I0</code> | |
3457 and <code>x</code> of <code>I1</code>. | |
3458 </td> | |
3459 </tr> | |
3460 <tr> | |
3461 <td> | |
3462 b | |
3463 </td> | |
3464 <td> | |
3465 3 | |
3466 </td> | |
3467 <td align="left"> | |
3468 the subsequent index. | |
3469 </td> | |
3470 </tr> | |
3471 </table></dd></dl> | |
3472 The class <code>C1</code> will have the same field indices. | |
3473 <p/> | |
3474 An instance of class <code>C2</code> will have the | |
3475 following field indices: | |
3476 <dl><dd><table> | |
3477 <tr> | |
3478 <td> | |
3479 a | |
3480 </td> | |
3481 <td> | |
3482 3 | |
3483 </td> | |
3484 <td align="left"> | |
3485 The count of the fields in the interfaces | |
3486 implemented by <code>C2</code> is three (<i>n</i>=3): | |
3487 <code>p</code> of <code>I0</code>, | |
3488 <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code> | |
3489 (an interface of <code>C2</code>). Note that the field <code>p</code> | |
3490 of <code>I0</code> is only included once. | |
3491 </td> | |
3492 </tr> | |
3493 <tr> | |
3494 <td> | |
3495 b | |
3496 </td> | |
3497 <td> | |
3498 4 | |
3499 </td> | |
3500 <td align="left"> | |
3501 the subsequent index to "a". | |
3502 </td> | |
3503 </tr> | |
3504 <tr> | |
3505 <td> | |
3506 q | |
3507 </td> | |
3508 <td> | |
3509 5 | |
3510 </td> | |
3511 <td align="left"> | |
3512 the subsequent index to "b". | |
3513 </td> | |
3514 </tr> | |
3515 <tr> | |
3516 <td> | |
3517 r | |
3518 </td> | |
3519 <td> | |
3520 6 | |
3521 </td> | |
3522 <td align="left"> | |
3523 the subsequent index to "q". | |
3524 </td> | |
3525 </tr> | |
3526 </table></dd></dl> | |
3527 The class <code>C2</code> will have the same field indices. | |
3528 Note that a field may have a different index depending on the | |
3529 object that is viewing it -- for example field "a" above. | |
3530 Note also: not all field indices may be visible from the | |
3531 callbacks, but all indices are shown for illustrative purposes. | |
3532 <p/> | |
3533 The interface <code>I1</code> will have the | |
3534 following field indices: | |
3535 <dl><dd><table> | |
3536 <tr> | |
3537 <td> | |
3538 x | |
3539 </td> | |
3540 <td> | |
3541 1 | |
3542 </td> | |
3543 <td align="left"> | |
3544 The count of the fields in the superinterfaces | |
3545 of <code>I1</code> is one (<i>n</i>=1): | |
3546 <code>p</code> of <code>I0</code>. | |
3547 </td> | |
3548 </tr> | |
3549 </table></dd></dl> | |
3550 </description> | |
3551 </field> | |
3552 </typedef> | |
3553 | |
3554 <typedef id="jvmtiHeapReferenceInfoArray" | |
3555 label="Reference information structure for Array references" | |
3556 since="1.1"> | |
3557 <description> | |
3558 Reference information returned for | |
3559 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. | |
3560 </description> | |
3561 <field id="index"> | |
3562 <jint/> | |
3563 <description> | |
3564 The array index. | |
3565 </description> | |
3566 </field> | |
3567 </typedef> | |
3568 | |
3569 <typedef id="jvmtiHeapReferenceInfoConstantPool" | |
3570 label="Reference information structure for Constant Pool references" | |
3571 since="1.1"> | |
3572 <description> | |
3573 Reference information returned for | |
3574 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. | |
3575 </description> | |
3576 <field id="index"> | |
3577 <jint/> | |
3578 <description> | |
3579 The index into the constant pool of the class. See the | |
3580 <vmspeclink id="ClassFile.doc.html#20080" | |
3581 name="Constant Pool section"/> | |
3582 description. | |
3583 </description> | |
3584 </field> | |
3585 </typedef> | |
3586 | |
3587 <typedef id="jvmtiHeapReferenceInfoStackLocal" | |
3588 label="Reference information structure for Local Variable references" | |
3589 since="1.1"> | |
3590 <description> | |
3591 Reference information returned for | |
3592 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. | |
3593 </description> | |
3594 <field id="thread_tag"> | |
3595 <jlong/> | |
3596 <description> | |
3597 The tag of the thread corresponding to this stack, zero if not tagged. | |
3598 </description> | |
3599 </field> | |
3600 <field id="thread_id"> | |
3601 <jlong/> | |
3602 <description> | |
3603 The unique thread ID of the thread corresponding to this stack. | |
3604 </description> | |
3605 </field> | |
3606 <field id="depth"> | |
3607 <jint/> | |
3608 <description> | |
3609 The depth of the frame. | |
3610 </description> | |
3611 </field> | |
3612 <field id="method"> | |
3613 <jmethodID/> | |
3614 <description> | |
3615 The method executing in this frame. | |
3616 </description> | |
3617 </field> | |
3618 <field id="location"> | |
3619 <jlocation/> | |
3620 <description> | |
3621 The currently executing location in this frame. | |
3622 </description> | |
3623 </field> | |
3624 <field id="slot"> | |
3625 <jint/> | |
3626 <description> | |
3627 The slot number of the local variable. | |
3628 </description> | |
3629 </field> | |
3630 </typedef> | |
3631 | |
3632 <typedef id="jvmtiHeapReferenceInfoJniLocal" | |
3633 label="Reference information structure for JNI local references" | |
3634 since="1.1"> | |
3635 <description> | |
3636 Reference information returned for | |
3637 <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. | |
3638 </description> | |
3639 <field id="thread_tag"> | |
3640 <jlong/> | |
3641 <description> | |
3642 The tag of the thread corresponding to this stack, zero if not tagged. | |
3643 </description> | |
3644 </field> | |
3645 <field id="thread_id"> | |
3646 <jlong/> | |
3647 <description> | |
3648 The unique thread ID of the thread corresponding to this stack. | |
3649 </description> | |
3650 </field> | |
3651 <field id="depth"> | |
3652 <jint/> | |
3653 <description> | |
3654 The depth of the frame. | |
3655 </description> | |
3656 </field> | |
3657 <field id="method"> | |
3658 <jmethodID/> | |
3659 <description> | |
3660 The method executing in this frame. | |
3661 </description> | |
3662 </field> | |
3663 </typedef> | |
3664 | |
3665 <typedef id="jvmtiHeapReferenceInfoReserved" | |
3666 label="Reference information structure for Other references" | |
3667 since="1.1"> | |
3668 <description> | |
3669 Reference information returned for other references. | |
3670 </description> | |
3671 <field id="reserved1"> | |
3672 <jlong/> | |
3673 <description> | |
3674 reserved for future use. | |
3675 </description> | |
3676 </field> | |
3677 <field id="reserved2"> | |
3678 <jlong/> | |
3679 <description> | |
3680 reserved for future use. | |
3681 </description> | |
3682 </field> | |
3683 <field id="reserved3"> | |
3684 <jlong/> | |
3685 <description> | |
3686 reserved for future use. | |
3687 </description> | |
3688 </field> | |
3689 <field id="reserved4"> | |
3690 <jlong/> | |
3691 <description> | |
3692 reserved for future use. | |
3693 </description> | |
3694 </field> | |
3695 <field id="reserved5"> | |
3696 <jlong/> | |
3697 <description> | |
3698 reserved for future use. | |
3699 </description> | |
3700 </field> | |
3701 <field id="reserved6"> | |
3702 <jlong/> | |
3703 <description> | |
3704 reserved for future use. | |
3705 </description> | |
3706 </field> | |
3707 <field id="reserved7"> | |
3708 <jlong/> | |
3709 <description> | |
3710 reserved for future use. | |
3711 </description> | |
3712 </field> | |
3713 <field id="reserved8"> | |
3714 <jlong/> | |
3715 <description> | |
3716 reserved for future use. | |
3717 </description> | |
3718 </field> | |
3719 </typedef> | |
3720 | |
3721 <uniontypedef id="jvmtiHeapReferenceInfo" | |
3722 label="Reference information structure" | |
3723 since="1.1"> | |
3724 <description> | |
3725 The information returned about referrers. | |
3726 Represented as a union of the various kinds of reference information. | |
3727 </description> | |
3728 <field id="field"> | |
3729 <struct>jvmtiHeapReferenceInfoField</struct> | |
3730 <description> | |
3731 The referrer information for | |
3732 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> | |
3733 and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. | |
3734 </description> | |
3735 </field> | |
3736 <field id="array"> | |
3737 <struct>jvmtiHeapReferenceInfoArray</struct> | |
3738 <description> | |
3739 The referrer information for | |
3740 For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. | |
3741 </description> | |
3742 </field> | |
3743 <field id="constant_pool"> | |
3744 <struct>jvmtiHeapReferenceInfoConstantPool</struct> | |
3745 <description> | |
3746 The referrer information for | |
3747 For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. | |
3748 </description> | |
3749 </field> | |
3750 <field id="stack_local"> | |
3751 <struct>jvmtiHeapReferenceInfoStackLocal</struct> | |
3752 <description> | |
3753 The referrer information for | |
3754 For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. | |
3755 </description> | |
3756 </field> | |
3757 <field id="jni_local"> | |
3758 <struct>jvmtiHeapReferenceInfoJniLocal</struct> | |
3759 <description> | |
3760 The referrer information for | |
3761 For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. | |
3762 </description> | |
3763 </field> | |
3764 <field id="other"> | |
3765 <struct>jvmtiHeapReferenceInfoReserved</struct> | |
3766 <description> | |
3767 reserved for future use. | |
3768 </description> | |
3769 </field> | |
3770 </uniontypedef> | |
3771 | |
3772 <typedef id="jvmtiHeapCallbacks" | |
3773 label="Heap callback function structure" | |
3774 since="1.1"> | |
3775 <field id="heap_iteration_callback"> | |
3776 <ptrtype> | |
3777 <struct>jvmtiHeapIterationCallback</struct> | |
3778 </ptrtype> | |
3779 <description> | |
3780 The callback to be called to describe an | |
3781 object in the heap. Used by the | |
3782 <functionlink id="IterateThroughHeap"/> function, ignored by the | |
3783 <functionlink id="FollowReferences"/> function. | |
3784 </description> | |
3785 </field> | |
3786 <field id="heap_reference_callback"> | |
3787 <ptrtype> | |
3788 <struct>jvmtiHeapReferenceCallback</struct> | |
3789 </ptrtype> | |
3790 <description> | |
3791 The callback to be called to describe an | |
3792 object reference. Used by the | |
3793 <functionlink id="FollowReferences"/> function, ignored by the | |
3794 <functionlink id="IterateThroughHeap"/> function. | |
3795 </description> | |
3796 </field> | |
3797 <field id="primitive_field_callback"> | |
3798 <ptrtype> | |
3799 <struct>jvmtiPrimitiveFieldCallback</struct> | |
3800 </ptrtype> | |
3801 <description> | |
3802 The callback to be called to describe a | |
3803 primitive field. | |
3804 </description> | |
3805 </field> | |
3806 <field id="array_primitive_value_callback"> | |
3807 <ptrtype> | |
3808 <struct>jvmtiArrayPrimitiveValueCallback</struct> | |
3809 </ptrtype> | |
3810 <description> | |
3811 The callback to be called to describe an | |
3812 array of primitive values. | |
3813 </description> | |
3814 </field> | |
3815 <field id="string_primitive_value_callback"> | |
3816 <ptrtype> | |
3817 <struct>jvmtiStringPrimitiveValueCallback</struct> | |
3818 </ptrtype> | |
3819 <description> | |
3820 The callback to be called to describe a String value. | |
3821 </description> | |
3822 </field> | |
3823 <field id="reserved5"> | |
3824 <ptrtype> | |
3825 <struct>jvmtiReservedCallback</struct> | |
3826 </ptrtype> | |
3827 <description> | |
3828 Reserved for future use.. | |
3829 </description> | |
3830 </field> | |
3831 <field id="reserved6"> | |
3832 <ptrtype> | |
3833 <struct>jvmtiReservedCallback</struct> | |
3834 </ptrtype> | |
3835 <description> | |
3836 Reserved for future use.. | |
3837 </description> | |
3838 </field> | |
3839 <field id="reserved7"> | |
3840 <ptrtype> | |
3841 <struct>jvmtiReservedCallback</struct> | |
3842 </ptrtype> | |
3843 <description> | |
3844 Reserved for future use.. | |
3845 </description> | |
3846 </field> | |
3847 <field id="reserved8"> | |
3848 <ptrtype> | |
3849 <struct>jvmtiReservedCallback</struct> | |
3850 </ptrtype> | |
3851 <description> | |
3852 Reserved for future use.. | |
3853 </description> | |
3854 </field> | |
3855 <field id="reserved9"> | |
3856 <ptrtype> | |
3857 <struct>jvmtiReservedCallback</struct> | |
3858 </ptrtype> | |
3859 <description> | |
3860 Reserved for future use.. | |
3861 </description> | |
3862 </field> | |
3863 <field id="reserved10"> | |
3864 <ptrtype> | |
3865 <struct>jvmtiReservedCallback</struct> | |
3866 </ptrtype> | |
3867 <description> | |
3868 Reserved for future use.. | |
3869 </description> | |
3870 </field> | |
3871 <field id="reserved11"> | |
3872 <ptrtype> | |
3873 <struct>jvmtiReservedCallback</struct> | |
3874 </ptrtype> | |
3875 <description> | |
3876 Reserved for future use.. | |
3877 </description> | |
3878 </field> | |
3879 <field id="reserved12"> | |
3880 <ptrtype> | |
3881 <struct>jvmtiReservedCallback</struct> | |
3882 </ptrtype> | |
3883 <description> | |
3884 Reserved for future use.. | |
3885 </description> | |
3886 </field> | |
3887 <field id="reserved13"> | |
3888 <ptrtype> | |
3889 <struct>jvmtiReservedCallback</struct> | |
3890 </ptrtype> | |
3891 <description> | |
3892 Reserved for future use.. | |
3893 </description> | |
3894 </field> | |
3895 <field id="reserved14"> | |
3896 <ptrtype> | |
3897 <struct>jvmtiReservedCallback</struct> | |
3898 </ptrtype> | |
3899 <description> | |
3900 Reserved for future use.. | |
3901 </description> | |
3902 </field> | |
3903 <field id="reserved15"> | |
3904 <ptrtype> | |
3905 <struct>jvmtiReservedCallback</struct> | |
3906 </ptrtype> | |
3907 <description> | |
3908 Reserved for future use.. | |
3909 </description> | |
3910 </field> | |
3911 </typedef> | |
3912 | |
3913 | |
3914 <intro> | |
3915 <rationale> | |
3916 The heap dumping functionality (below) uses a callback | |
3917 for each object. While it would seem that a buffered approach | |
3918 would provide better throughput, tests do | |
3919 not show this to be the case--possibly due to locality of | |
3920 memory reference or array access overhead. | |
3921 </rationale> | |
3922 | |
3923 <issue> | |
3924 Still under investigation as to if java.lang.ref references | |
3925 are reported as a different type of reference. | |
3926 </issue> | |
3927 | |
3928 <issue> | |
3929 Should or can an indication of the cost or relative cost of | |
3930 these operations be included? | |
3931 </issue> | |
3932 | |
3933 </intro> | |
3934 | |
3935 <callback id="jvmtiHeapIterationCallback" since="1.1"> | |
3936 <jint/> | |
3937 <synopsis>Heap Iteration Callback</synopsis> | |
3938 <description> | |
3939 Agent supplied callback function. | |
3940 Describes (but does not pass in) an object in the heap. | |
3941 <p/> | |
3942 This function should return a bit vector of the desired | |
3943 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
3944 This will determine if the entire iteration should be aborted | |
3945 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
3946 <p/> | |
3947 See the <internallink id="heapCallbacks">heap callback | |
3948 function restrictions</internallink>. | |
3949 </description> | |
3950 <parameters> | |
3951 <param id="class_tag"> | |
3952 <jlong/> | |
3953 <description> | |
3954 The tag of the class of object (zero if the class is not tagged). | |
3955 If the object represents a runtime class, | |
3956 the <code>class_tag</code> is the tag | |
3957 associated with <code>java.lang.Class</code> | |
3958 (zero if <code>java.lang.Class</code> is not tagged). | |
3959 </description> | |
3960 </param> | |
3961 <param id="size"> | |
3962 <jlong/> | |
3963 <description> | |
3964 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
3965 </description> | |
3966 </param> | |
3967 <param id="tag_ptr"> | |
3968 <outptr><jlong/></outptr> | |
3969 <description> | |
3970 The object tag value, or zero if the object is not tagged. | |
3971 To set the tag value to be associated with the object | |
3972 the agent sets the <code>jlong</code> pointed to by the parameter. | |
3973 </description> | |
3974 </param> | |
3975 <param id="length"> | |
3976 <jint/> | |
3977 <description> | |
3978 If this object is an array, the length of the array. Otherwise negative one (-1). | |
3979 </description> | |
3980 </param> | |
3981 <param id="user_data"> | |
3982 <outptr><void/></outptr> | |
3983 <description> | |
3984 The user supplied data that was passed into the iteration function. | |
3985 </description> | |
3986 </param> | |
3987 </parameters> | |
3988 </callback> | |
3989 | |
3990 <callback id="jvmtiHeapReferenceCallback" since="1.1"> | |
3991 <jint/> | |
3992 <synopsis>Heap Reference Callback</synopsis> | |
3993 <description> | |
3994 Agent supplied callback function. | |
3995 Describes a reference from an object or the VM (the referrer) to another object | |
3996 (the referree) or a heap root to a referree. | |
3997 <p/> | |
3998 This function should return a bit vector of the desired | |
3999 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
4000 This will determine if the objects referenced by the referree | |
4001 should be visited or if the entire iteration should be aborted. | |
4002 <p/> | |
4003 See the <internallink id="heapCallbacks">heap callback | |
4004 function restrictions</internallink>. | |
4005 </description> | |
4006 <parameters> | |
4007 <param id="reference_kind"> | |
4008 <enum>jvmtiHeapReferenceKind</enum> | |
4009 <description> | |
4010 The kind of reference. | |
4011 </description> | |
4012 </param> | |
4013 <param id="reference_info"> | |
4014 <inptr> | |
4015 <struct>jvmtiHeapReferenceInfo</struct> | |
4016 </inptr> | |
4017 <description> | |
4018 Details about the reference. | |
4019 Set when the <paramlink id="reference_kind"/> is | |
4020 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, | |
4021 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, | |
4022 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>, | |
4023 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>, | |
4024 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>, | |
4025 or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>. | |
4026 Otherwise <code>NULL</code>. | |
4027 </description> | |
4028 </param> | |
4029 <param id="class_tag"> | |
4030 <jlong/> | |
4031 <description> | |
4032 The tag of the class of referree object (zero if the class is not tagged). | |
4033 If the referree object represents a runtime class, | |
4034 the <code>class_tag</code> is the tag | |
4035 associated with <code>java.lang.Class</code> | |
4036 (zero if <code>java.lang.Class</code> is not tagged). | |
4037 </description> | |
4038 </param> | |
4039 <param id="referrer_class_tag"> | |
4040 <jlong/> | |
4041 <description> | |
4042 The tag of the class of the referrer object (zero if the class is not tagged | |
4043 or the referree is a heap root). If the referrer object represents a runtime | |
4044 class, the <code>referrer_class_tag</code> is the tag associated with | |
4045 the <code>java.lang.Class</code> | |
4046 (zero if <code>java.lang.Class</code> is not tagged). | |
4047 </description> | |
4048 </param> | |
4049 <param id="size"> | |
4050 <jlong/> | |
4051 <description> | |
4052 Size of the referree object (in bytes). | |
4053 See <functionlink id="GetObjectSize"/>. | |
4054 </description> | |
4055 </param> | |
4056 <param id="tag_ptr"> | |
4057 <outptr><jlong/></outptr> | |
4058 <description> | |
4059 Points to the referree object tag value, or zero if the object is not | |
4060 tagged. | |
4061 To set the tag value to be associated with the object | |
4062 the agent sets the <code>jlong</code> pointed to by the parameter. | |
4063 </description> | |
4064 </param> | |
4065 <param id="referrer_tag_ptr"> | |
4066 <outptr><jlong/></outptr> | |
4067 <description> | |
4068 Points to the tag of the referrer object, or | |
4069 points to the zero if the referrer | |
4070 object is not tagged. | |
4071 <code>NULL</code> if the referrer in not an object (that is, | |
4072 this callback is reporting a heap root). | |
4073 To set the tag value to be associated with the referrer object | |
4074 the agent sets the <code>jlong</code> pointed to by the parameter. | |
4075 If this callback is reporting a reference from an object to itself, | |
4076 <code>referrer_tag_ptr == tag_ptr</code>. | |
4077 </description> | |
4078 </param> | |
4079 <param id="length"> | |
4080 <jint/> | |
4081 <description> | |
4082 If this object is an array, the length of the array. Otherwise negative one (-1). | |
4083 </description> | |
4084 </param> | |
4085 <param id="user_data"> | |
4086 <outptr><void/></outptr> | |
4087 <description> | |
4088 The user supplied data that was passed into the iteration function. | |
4089 </description> | |
4090 </param> | |
4091 </parameters> | |
4092 </callback> | |
4093 | |
4094 <callback id="jvmtiPrimitiveFieldCallback" since="1.1"> | |
4095 <jint/> | |
4096 <synopsis>Primitive Field Callback</synopsis> | |
4097 <description> | |
4098 Agent supplied callback function which | |
4099 describes a primitive field of an object (<i>the object</i>). | |
4100 A primitive field is a field whose type is a primitive type. | |
4101 This callback will describe a static field if the object is a class, | |
4102 and otherwise will describe an instance field. | |
4103 <p/> | |
4104 This function should return a bit vector of the desired | |
4105 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
4106 This will determine if the entire iteration should be aborted | |
4107 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
4108 <p/> | |
4109 See the <internallink id="heapCallbacks">heap callback | |
4110 function restrictions</internallink>. | |
4111 </description> | |
4112 <parameters> | |
4113 <param id="kind"> | |
4114 <enum>jvmtiHeapReferenceKind</enum> | |
4115 <description> | |
4116 The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or | |
4117 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>). | |
4118 </description> | |
4119 </param> | |
4120 <param id="info"> | |
4121 <inptr> | |
4122 <struct>jvmtiHeapReferenceInfo</struct> | |
4123 </inptr> | |
4124 <description> | |
4125 Which field (the field index). | |
4126 </description> | |
4127 </param> | |
4128 <param id="object_class_tag"> | |
4129 <jlong/> | |
4130 <description> | |
4131 The tag of the class of the object (zero if the class is not tagged). | |
4132 If the object represents a runtime class, the | |
4133 <code>object_class_tag</code> is the tag | |
4134 associated with <code>java.lang.Class</code> | |
4135 (zero if <code>java.lang.Class</code> is not tagged). | |
4136 </description> | |
4137 </param> | |
4138 <param id="object_tag_ptr"> | |
4139 <outptr><jlong/></outptr> | |
4140 <description> | |
4141 Points to the tag of the object, or zero if the object is not | |
4142 tagged. | |
4143 To set the tag value to be associated with the object | |
4144 the agent sets the <code>jlong</code> pointed to by the parameter. | |
4145 </description> | |
4146 </param> | |
4147 <param id="value"> | |
4148 <jvalue/> | |
4149 <description> | |
4150 The value of the field. | |
4151 </description> | |
4152 </param> | |
4153 <param id="value_type"> | |
4154 <enum>jvmtiPrimitiveType</enum> | |
4155 <description> | |
4156 The type of the field. | |
4157 </description> | |
4158 </param> | |
4159 <param id="user_data"> | |
4160 <outptr><void/></outptr> | |
4161 <description> | |
4162 The user supplied data that was passed into the iteration function. | |
4163 </description> | |
4164 </param> | |
4165 </parameters> | |
4166 </callback> | |
4167 | |
4168 <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1"> | |
4169 <jint/> | |
4170 <synopsis>Array Primitive Value Callback</synopsis> | |
4171 <description> | |
4172 Agent supplied callback function. | |
4173 Describes the values in an array of a primitive type. | |
4174 <p/> | |
4175 This function should return a bit vector of the desired | |
4176 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
4177 This will determine if the entire iteration should be aborted | |
4178 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
4179 <p/> | |
4180 See the <internallink id="heapCallbacks">heap callback | |
4181 function restrictions</internallink>. | |
4182 </description> | |
4183 <parameters> | |
4184 <param id="class_tag"> | |
4185 <jlong/> | |
4186 <description> | |
4187 The tag of the class of the array object (zero if the class is not tagged). | |
4188 </description> | |
4189 </param> | |
4190 <param id="size"> | |
4191 <jlong/> | |
4192 <description> | |
4193 Size of the array (in bytes). | |
4194 See <functionlink id="GetObjectSize"/>. | |
4195 </description> | |
4196 </param> | |
4197 <param id="tag_ptr"> | |
4198 <outptr><jlong/></outptr> | |
4199 <description> | |
4200 Points to the tag of the array object, or zero if the object is not | |
4201 tagged. | |
4202 To set the tag value to be associated with the object | |
4203 the agent sets the <code>jlong</code> pointed to by the parameter. | |
4204 </description> | |
4205 </param> | |
4206 <param id="element_count"> | |
4207 <jint/> | |
4208 <description> | |
4209 The length of the primitive array. | |
4210 </description> | |
4211 </param> | |
4212 <param id="element_type"> | |
4213 <enum>jvmtiPrimitiveType</enum> | |
4214 <description> | |
4215 The type of the elements of the array. | |
4216 </description> | |
4217 </param> | |
4218 <param id="elements"> | |
4219 <vmbuf><void/></vmbuf> | |
4220 <description> | |
4221 The elements of the array in a packed array of <code>element_count</code> | |
4222 items of <code>element_type</code> size each. | |
4223 </description> | |
4224 </param> | |
4225 <param id="user_data"> | |
4226 <outptr><void/></outptr> | |
4227 <description> | |
4228 The user supplied data that was passed into the iteration function. | |
4229 </description> | |
4230 </param> | |
4231 </parameters> | |
4232 </callback> | |
4233 | |
4234 <callback id="jvmtiStringPrimitiveValueCallback" since="1.1"> | |
4235 <jint/> | |
4236 <synopsis>String Primitive Value Callback</synopsis> | |
4237 <description> | |
4238 Agent supplied callback function. | |
4239 Describes the value of a java.lang.String. | |
4240 <p/> | |
4241 This function should return a bit vector of the desired | |
4242 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. | |
4243 This will determine if the entire iteration should be aborted | |
4244 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). | |
4245 <p/> | |
4246 See the <internallink id="heapCallbacks">heap callback | |
4247 function restrictions</internallink>. | |
4248 </description> | |
4249 <parameters> | |
4250 <param id="class_tag"> | |
4251 <jlong/> | |
4252 <description> | |
4253 The tag of the class of the String class (zero if the class is not tagged). | |
4254 <issue>Is this needed?</issue> | |
4255 </description> | |
4256 </param> | |
4257 <param id="size"> | |
4258 <jlong/> | |
4259 <description> | |
4260 Size of the string (in bytes). | |
4261 See <functionlink id="GetObjectSize"/>. | |
4262 </description> | |
4263 </param> | |
4264 <param id="tag_ptr"> | |
4265 <outptr><jlong/></outptr> | |
4266 <description> | |
4267 Points to the tag of the String object, or zero if the object is not | |
4268 tagged. | |
4269 To set the tag value to be associated with the object | |
4270 the agent sets the <code>jlong</code> pointed to by the parameter. | |
4271 </description> | |
4272 </param> | |
4273 <param id="value"> | |
4274 <vmbuf><jchar/></vmbuf> | |
4275 <description> | |
4276 The value of the String, encoded as a Unicode string. | |
4277 </description> | |
4278 </param> | |
4279 <param id="value_length"> | |
4280 <jint/> | |
4281 <description> | |
4282 The length of the string. | |
4283 The length is equal to the number of 16-bit Unicode | |
4284 characters in the string. | |
4285 </description> | |
4286 </param> | |
4287 <param id="user_data"> | |
4288 <outptr><void/></outptr> | |
4289 <description> | |
4290 The user supplied data that was passed into the iteration function. | |
4291 </description> | |
4292 </param> | |
4293 </parameters> | |
4294 </callback> | |
4295 | |
4296 | |
4297 <callback id="jvmtiReservedCallback" since="1.1"> | |
4298 <jint/> | |
4299 <synopsis>reserved for future use Callback</synopsis> | |
4300 <description> | |
4301 Placeholder -- reserved for future use. | |
4302 </description> | |
4303 <parameters> | |
4304 </parameters> | |
4305 </callback> | |
4306 | |
4307 <function id="FollowReferences" num="115" since="1.1"> | |
4308 <synopsis>Follow References</synopsis> | |
4309 <description> | |
4310 This function initiates a traversal over the objects that are | |
4311 directly and indirectly reachable from the specified object or, | |
4312 if <code>initial_object</code> is not specified, all objects | |
4313 reachable from the heap roots. | |
4314 The heap root are the set of system classes, | |
4315 JNI globals, references from thread stacks, and other objects used as roots | |
4316 for the purposes of garbage collection. | |
4317 <p/> | |
4318 This function operates by traversing the reference graph. | |
4319 Let <i>A</i>, <i>B</i>, ... represent objects. | |
4320 When a reference from <i>A</i> to <i>B</i> is traversed, | |
4321 when a reference from a heap root to <i>B</i> is traversed, | |
4322 or when <i>B</i> is specified as the <paramlink id="initial_object"/>, | |
4323 then <i>B</i> is said to be <i>visited</i>. | |
4324 A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i> | |
4325 is visited. | |
4326 References are reported in the same order that the references are traversed. | |
4327 Object references are reported by invoking the agent supplied | |
4328 callback function <functionlink id="jvmtiHeapReferenceCallback"/>. | |
4329 In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known | |
4330 as the <i>referrer</i> and <i>B</i> as the <i>referree</i>. | |
4331 The callback is invoked exactly once for each reference from a referrer; | |
4332 this is true even if there are reference cycles or multiple paths to | |
4333 the referrer. | |
4334 There may be more than one reference between a referrer and a referree, | |
4335 each reference is reported. | |
4336 These references may be distinguished by examining the | |
4337 <datalink | |
4338 id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink> | |
4339 and | |
4340 <datalink | |
4341 id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink> | |
4342 parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback. | |
4343 <p/> | |
4344 This function reports a Java programming language view of object references, | |
4345 not a virtual machine implementation view. The following object references | |
4346 are reported when they are non-null: | |
4347 <ul> | |
4348 <li>Instance objects report references to each non-primitive instance fields | |
4349 (including inherited fields).</li> | |
4350 <li>Instance objects report a reference to the object type (class).</li> | |
4351 <li>Classes report a reference to the superclass and directly | |
4352 implemented/extended interfaces.</li> | |
4353 <li>Classes report a reference to the class loader, protection domain, | |
4354 signers, and resolved entries in the constant pool.</li> | |
4355 <li>Classes report a reference to each directly declared non-primitive | |
4356 static field.</li> | |
4357 <li>Arrays report a reference to the array type (class) and each | |
4358 array element.</li> | |
4359 <li>Primitive arrays report a reference to the array type.</li> | |
4360 </ul> | |
4361 <p/> | |
4362 This function can also be used to examine primitive (non-object) values. | |
4363 The primitive value of an array or String | |
4364 is reported after the object has been visited; | |
4365 it is reported by invoking the agent supplied callback function | |
4366 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or | |
4367 <functionlink id="jvmtiStringPrimitiveValueCallback"/>. | |
4368 A primitive field | |
4369 is reported after the object with that field is visited; | |
4370 it is reported by invoking the agent supplied callback function | |
4371 <functionlink id="jvmtiPrimitiveFieldCallback"/>. | |
4372 <p/> | |
4373 Whether a callback is provided or is <code>NULL</code> only determines | |
4374 whether the callback will be invoked, it does not influence | |
4375 which objects are visited nor does it influence whether other callbacks | |
4376 will be invoked. | |
4377 However, the | |
4378 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink> | |
4379 returned by <functionlink id="jvmtiHeapReferenceCallback"/> | |
4380 do determine if the objects referenced by the | |
4381 current object as visited. | |
4382 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> | |
4383 and <paramlink id="klass"/> provided as parameters to this function | |
4384 do not control which objects are visited but they do control which | |
4385 objects and primitive values are reported by the callbacks. | |
4386 For example, if the only callback that was set is | |
4387 <paramlink id="array_primitive_value_callback"/> and <code>klass</code> | |
4388 is set to the array of bytes class, then only arrays of byte will be | |
4389 reported. | |
4390 The table below summarizes this: | |
4391 <p/> | |
4392 <table> | |
4393 <tr> | |
4394 <th/> | |
4395 <th> | |
4396 Controls objects visited | |
4397 </th> | |
4398 <th> | |
4399 Controls objects reported | |
4400 </th> | |
4401 <th> | |
4402 Controls primitives reported | |
4403 </th> | |
4404 </tr> | |
4405 <tr> | |
4406 <th align="left"> | |
4407 the | |
4408 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
4409 returned by <functionlink id="jvmtiHeapReferenceCallback"/> | |
4410 </th> | |
4411 <td> | |
4412 <b>Yes</b> | |
4413 </td> | |
4414 <td> | |
4415 <b>Yes</b>, since visits are controlled | |
4416 </td> | |
4417 <td> | |
4418 <b>Yes</b>, since visits are controlled | |
4419 </td> | |
4420 </tr> | |
4421 <tr> | |
4422 <th align="left"> | |
4423 <fieldlink id="object_reference_callback" struct="jvmtiHeapCallbacks"/> | |
4424 in <paramlink id="callbacks"/> set | |
4425 </th> | |
4426 <td> | |
4427 No | |
4428 </td> | |
4429 <td> | |
4430 <b>Yes</b> | |
4431 </td> | |
4432 <td> | |
4433 No | |
4434 </td> | |
4435 </tr> | |
4436 <tr> | |
4437 <th align="left"> | |
4438 <paramlink id="heap_filter"/> | |
4439 </th> | |
4440 <td> | |
4441 No | |
4442 </td> | |
4443 <td> | |
4444 <b>Yes</b> | |
4445 </td> | |
4446 <td> | |
4447 <b>Yes</b> | |
4448 </td> | |
4449 </tr> | |
4450 <tr> | |
4451 <th align="left"> | |
4452 <paramlink id="klass"/> | |
4453 </th> | |
4454 <td> | |
4455 No | |
4456 </td> | |
4457 <td> | |
4458 <b>Yes</b> | |
4459 </td> | |
4460 <td> | |
4461 <b>Yes</b> | |
4462 </td> | |
4463 </tr> | |
4464 </table> | |
4465 <p/> | |
4466 During the execution of this function the state of the heap | |
4467 does not change: no objects are allocated, no objects are | |
4468 garbage collected, and the state of objects (including | |
4469 held values) does not change. | |
4470 As a result, threads executing Java | |
4471 programming language code, threads attempting to resume the | |
4472 execution of Java programming language code, and threads | |
4473 attempting to execute JNI functions are typically stalled. | |
4474 </description> | |
4475 <origin>new</origin> | |
4476 <capabilities> | |
4477 <required id="can_tag_objects"></required> | |
4478 </capabilities> | |
4479 <parameters> | |
4480 <param id="heap_filter"> | |
4481 <jint/> | |
4482 <description> | |
4483 This bit vector of | |
4484 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>. | |
4485 restricts the objects for which the callback function is called. | |
4486 This applies to both the object and primitive callbacks. | |
4487 </description> | |
4488 </param> | |
4489 <param id="klass"> | |
4490 <ptrtype> | |
4491 <jclass/> | |
4492 <nullok>callbacks are not limited to instances of a particular | |
4493 class</nullok> | |
4494 </ptrtype> | |
4495 <description> | |
4496 Callbacks are only reported when the object is an instance of | |
4497 this class. | |
4498 Objects which are instances of a subclass of <code>klass</code> | |
4499 are not reported. | |
4500 If <code>klass</code> is an interface, no objects are reported. | |
4501 This applies to both the object and primitive callbacks. | |
4502 </description> | |
4503 </param> | |
4504 <param id="initial_object"> | |
4505 <ptrtype> | |
4506 <jobject/> | |
4507 <nullok>references are followed from the heap roots</nullok> | |
4508 </ptrtype> | |
4509 <description> | |
4510 The object to follow | |
4511 </description> | |
4512 </param> | |
4513 <param id="callbacks"> | |
4514 <inptr> | |
4515 <struct>jvmtiHeapCallbacks</struct> | |
4516 </inptr> | |
4517 <description> | |
4518 Structure defining the set of callback functions. | |
4519 </description> | |
4520 </param> | |
4521 <param id="user_data"> | |
4522 <inbuf> | |
4523 <void/> | |
4524 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
4525 </inbuf> | |
4526 <description> | |
4527 User supplied data to be passed to the callback. | |
4528 </description> | |
4529 </param> | |
4530 </parameters> | |
4531 <errors> | |
4532 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
4533 <paramlink id="klass"/> is not a valid class. | |
4534 </error> | |
4535 <error id="JVMTI_ERROR_INVALID_OBJECT"> | |
4536 <paramlink id="initial_object"/> is not a valid object. | |
4537 </error> | |
4538 </errors> | |
4539 </function> | |
4540 | |
4541 | |
4542 <function id="IterateThroughHeap" num="116" since="1.1"> | |
4543 <synopsis>Iterate Through Heap</synopsis> | |
4544 <description> | |
4545 Initiate an iteration over all objects in the heap. | |
4546 This includes both reachable and | |
4547 unreachable objects. Objects are visited in no particular order. | |
4548 <p/> | |
4549 Heap objects are reported by invoking the agent supplied | |
4550 callback function <functionlink id="jvmtiHeapIterationCallback"/>. | |
4551 References between objects are not reported. | |
4552 If only reachable objects are desired, or if object reference information | |
4553 is needed, use <functionlink id="FollowReferences"/>. | |
4554 <p/> | |
4555 This function can also be used to examine primitive (non-object) values. | |
4556 The primitive value of an array or String | |
4557 is reported after the object has been visited; | |
4558 it is reported by invoking the agent supplied callback function | |
4559 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or | |
4560 <functionlink id="jvmtiStringPrimitiveValueCallback"/>. | |
4561 A primitive field | |
4562 is reported after the object with that field is visited; | |
4563 it is reported by invoking the agent supplied | |
4564 callback function | |
4565 <functionlink id="jvmtiPrimitiveFieldCallback"/>. | |
4566 <p/> | |
4567 Unless the iteration is aborted by the | |
4568 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
4569 returned by a callback, all objects in the heap are visited. | |
4570 Whether a callback is provided or is <code>NULL</code> only determines | |
4571 whether the callback will be invoked, it does not influence | |
4572 which objects are visited nor does it influence whether other callbacks | |
4573 will be invoked. | |
4574 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> | |
4575 and <paramlink id="klass"/> provided as parameters to this function | |
4576 do not control which objects are visited but they do control which | |
4577 objects and primitive values are reported by the callbacks. | |
4578 For example, if the only callback that was set is | |
4579 <paramlink id="array_primitive_value_callback"/> and <code>klass</code> | |
4580 is set to the array of bytes class, then only arrays of byte will be | |
4581 reported. The table below summarizes this (contrast this with | |
4582 <functionlink id="FollowReferences"/>): | |
4583 <p/> | |
4584 <table> | |
4585 <tr> | |
4586 <th/> | |
4587 <th> | |
4588 Controls objects visited | |
4589 </th> | |
4590 <th> | |
4591 Controls objects reported | |
4592 </th> | |
4593 <th> | |
4594 Controls primitives reported | |
4595 </th> | |
4596 </tr> | |
4597 <tr> | |
4598 <th align="left"> | |
4599 the | |
4600 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> | |
4601 returned by <functionlink id="jvmtiHeapIterationCallback"/> | |
4602 </th> | |
4603 <td> | |
4604 No<br/>(unless they abort the iteration) | |
4605 </td> | |
4606 <td> | |
4607 No<br/>(unless they abort the iteration) | |
4608 </td> | |
4609 <td> | |
4610 No<br/>(unless they abort the iteration) | |
4611 </td> | |
4612 </tr> | |
4613 <tr> | |
4614 <th align="left"> | |
4615 <fieldlink id="object_callback" struct="jvmtiHeapCallbacks"/> | |
4616 in <paramlink id="callbacks"/> set | |
4617 </th> | |
4618 <td> | |
4619 No | |
4620 </td> | |
4621 <td> | |
4622 <b>Yes</b> | |
4623 </td> | |
4624 <td> | |
4625 No | |
4626 </td> | |
4627 </tr> | |
4628 <tr> | |
4629 <th align="left"> | |
4630 <paramlink id="heap_filter"/> | |
4631 </th> | |
4632 <td> | |
4633 No | |
4634 </td> | |
4635 <td> | |
4636 <b>Yes</b> | |
4637 </td> | |
4638 <td> | |
4639 <b>Yes</b> | |
4640 </td> | |
4641 </tr> | |
4642 <tr> | |
4643 <th align="left"> | |
4644 <paramlink id="klass"/> | |
4645 </th> | |
4646 <td> | |
4647 No | |
4648 </td> | |
4649 <td> | |
4650 <b>Yes</b> | |
4651 </td> | |
4652 <td> | |
4653 <b>Yes</b> | |
4654 </td> | |
4655 </tr> | |
4656 </table> | |
4657 <p/> | |
4658 During the execution of this function the state of the heap | |
4659 does not change: no objects are allocated, no objects are | |
4660 garbage collected, and the state of objects (including | |
4661 held values) does not change. | |
4662 As a result, threads executing Java | |
4663 programming language code, threads attempting to resume the | |
4664 execution of Java programming language code, and threads | |
4665 attempting to execute JNI functions are typically stalled. | |
4666 </description> | |
4667 <origin>new</origin> | |
4668 <capabilities> | |
4669 <required id="can_tag_objects"></required> | |
4670 </capabilities> | |
4671 <parameters> | |
4672 <param id="heap_filter"> | |
4673 <jint/> | |
4674 <description> | |
4675 This bit vector of | |
4676 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>. | |
4677 restricts the objects for which the callback function is called. | |
4678 This applies to both the object and primitive callbacks. | |
4679 </description> | |
4680 </param> | |
4681 <param id="klass"> | |
4682 <ptrtype> | |
4683 <jclass/> | |
4684 <nullok>callbacks are not limited to instances of a particular class</nullok> | |
4685 </ptrtype> | |
4686 <description> | |
4687 Callbacks are only reported when the object is an instance of | |
4688 this class. | |
4689 Objects which are instances of a subclass of <code>klass</code> | |
4690 are not reported. | |
4691 If <code>klass</code> is an interface, no objects are reported. | |
4692 This applies to both the object and primitive callbacks. | |
4693 </description> | |
4694 </param> | |
4695 <param id="callbacks"> | |
4696 <inptr> | |
4697 <struct>jvmtiHeapCallbacks</struct> | |
4698 </inptr> | |
4699 <description> | |
4700 Structure defining the set callback functions. | |
4701 </description> | |
4702 </param> | |
4703 <param id="user_data"> | |
4704 <inbuf> | |
4705 <void/> | |
4706 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
4707 </inbuf> | |
4708 <description> | |
4709 User supplied data to be passed to the callback. | |
4710 </description> | |
4711 </param> | |
4712 </parameters> | |
4713 <errors> | |
4714 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
4715 <paramlink id="klass"/> is not a valid class. | |
4716 </error> | |
4717 </errors> | |
4718 </function> | |
4719 | |
4720 <function id="GetTag" phase="start" num="106"> | |
4721 <synopsis>Get Tag</synopsis> | |
4722 <description> | |
4723 Retrieve the tag associated with an object. | |
4724 The tag is a long value typically used to store a | |
4725 unique identifier or pointer to object information. | |
4726 The tag is set with | |
4727 <functionlink id="SetTag"></functionlink>. | |
4728 Objects for which no tags have been set return a | |
4729 tag value of zero. | |
4730 </description> | |
4731 <origin>new</origin> | |
4732 <capabilities> | |
4733 <required id="can_tag_objects"></required> | |
4734 </capabilities> | |
4735 <parameters> | |
4736 <param id="object"> | |
4737 <jobject/> | |
4738 <description> | |
4739 The object whose tag is to be retrieved. | |
4740 </description> | |
4741 </param> | |
4742 <param id="tag_ptr"> | |
4743 <outptr><jlong/></outptr> | |
4744 <description> | |
4745 On return, the referenced long is set to the value | |
4746 of the tag. | |
4747 </description> | |
4748 </param> | |
4749 </parameters> | |
4750 <errors> | |
4751 </errors> | |
4752 </function> | |
4753 | |
4754 <function id="SetTag" phase="start" num="107"> | |
4755 <synopsis>Set Tag</synopsis> | |
4756 <description> | |
4757 Set the tag associated with an object. | |
4758 The tag is a long value typically used to store a | |
4759 unique identifier or pointer to object information. | |
4760 The tag is visible with | |
4761 <functionlink id="GetTag"></functionlink>. | |
4762 </description> | |
4763 <origin>new</origin> | |
4764 <capabilities> | |
4765 <required id="can_tag_objects"></required> | |
4766 </capabilities> | |
4767 <parameters> | |
4768 <param id="object"> | |
4769 <jobject/> | |
4770 <description> | |
4771 The object whose tag is to be set. | |
4772 </description> | |
4773 </param> | |
4774 <param id="tag"> | |
4775 <jlong/> | |
4776 <description> | |
4777 The new value of the tag. | |
4778 </description> | |
4779 </param> | |
4780 </parameters> | |
4781 <errors> | |
4782 </errors> | |
4783 </function> | |
4784 | |
4785 <function id="GetObjectsWithTags" num="114"> | |
4786 <synopsis>Get Objects With Tags</synopsis> | |
4787 <description> | |
4788 Return objects in the heap with the specified tags. | |
4789 The format is parallel arrays of objects and tags. | |
4790 </description> | |
4791 <origin>new</origin> | |
4792 <capabilities> | |
4793 <required id="can_tag_objects"></required> | |
4794 </capabilities> | |
4795 <parameters> | |
4796 <param id="tag_count"> | |
4797 <jint min="0"/> | |
4798 <description> | |
4799 Number of tags to scan for. | |
4800 </description> | |
4801 </param> | |
4802 <param id="tags"> | |
4803 <inbuf incount="tag_count"> | |
4804 <jlong/> | |
4805 </inbuf> | |
4806 <description> | |
4807 Scan for objects with these tags. | |
4808 Zero is not permitted in this array. | |
4809 </description> | |
4810 </param> | |
4811 <param id="count_ptr"> | |
4812 <outptr> | |
4813 <jint/> | |
4814 </outptr> | |
4815 <description> | |
4816 Return the number of objects with any of the tags | |
4817 in <paramlink id="tags"/>. | |
4818 </description> | |
4819 </param> | |
4820 <param id="object_result_ptr"> | |
4821 <allocbuf outcount="count_ptr"> | |
4822 <jobject/> | |
4823 <nullok>this information is not returned</nullok> | |
4824 </allocbuf> | |
4825 <description> | |
4826 Returns the array of objects with any of the tags | |
4827 in <paramlink id="tags"/>. | |
4828 </description> | |
4829 </param> | |
4830 <param id="tag_result_ptr"> | |
4831 <allocbuf outcount="count_ptr"> | |
4832 <jlong/> | |
4833 <nullok>this information is not returned</nullok> | |
4834 </allocbuf> | |
4835 <description> | |
4836 For each object in <paramlink id="object_result_ptr"/>, | |
4837 return the tag at the corresponding index. | |
4838 </description> | |
4839 </param> | |
4840 </parameters> | |
4841 <errors> | |
4842 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
4843 Zero is present in <paramlink id="tags"></paramlink>. | |
4844 </error> | |
4845 </errors> | |
4846 </function> | |
4847 | |
4848 <function id="ForceGarbageCollection" num="108"> | |
4849 <synopsis>Force Garbage Collection</synopsis> | |
4850 <description> | |
4851 Force the VM to perform a garbage collection. | |
4852 The garbage collection is as complete as possible. | |
4853 This function does not cause finalizers to be run. | |
4854 This function does not return until the garbage collection | |
4855 is finished. | |
4856 <p/> | |
4857 Although garbage collection is as complete | |
4858 as possible there is no guarantee that all | |
4859 <eventlink id="ObjectFree"/> | |
4860 events will have been | |
4861 sent by the time that this function | |
4862 returns. In particular, an object may be | |
4863 prevented from being freed because it | |
4864 is awaiting finalization. | |
4865 </description> | |
4866 <origin>new</origin> | |
4867 <capabilities> | |
4868 </capabilities> | |
4869 <parameters> | |
4870 </parameters> | |
4871 <errors> | |
4872 </errors> | |
4873 </function> | |
4874 | |
4875 | |
4876 </category> | |
4877 | |
4878 <category id="Heap_1_0" label="Heap (1.0)"> | |
4879 <intro> | |
4880 <b> | |
4881 These functions and data types were introduced in the original | |
4882 <jvmti/> version 1.0 and have been superseded by more | |
4883 </b> | |
4884 <internallink id="Heap"><b>powerful and flexible versions</b></internallink> | |
4885 <b> | |
4886 which: | |
4887 </b> | |
4888 <ul> | |
4889 <li> | |
4890 <b> | |
4891 Allow access to primitive values (the value of Strings, arrays, | |
4892 and primitive fields) | |
4893 </b> | |
4894 </li> | |
4895 <li> | |
4896 <b> | |
4897 Allow the tag of the referrer to be set, thus enabling more | |
4898 efficient localized reference graph building | |
4899 </b> | |
4900 </li> | |
4901 <li> | |
4902 <b> | |
4903 Provide more extensive filtering abilities | |
4904 </b> | |
4905 </li> | |
4906 <li> | |
4907 <b> | |
4908 Are extensible, allowing their abilities to grow in future versions of <jvmti/> | |
4909 </b> | |
4910 </li> | |
4911 </ul> | |
4912 <p/> | |
4913 <b>Please use the </b> | |
4914 <internallink id="Heap"><b>current Heap functions</b></internallink>. | |
4915 <p/> | |
4916 <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum"> | |
4917 <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1"> | |
4918 Tagged objects only. | |
4919 </constant> | |
4920 <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2"> | |
4921 Untagged objects only. | |
4922 </constant> | |
4923 <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3"> | |
4924 Either tagged or untagged objects. | |
4925 </constant> | |
4926 </constants> | |
4927 | |
4928 <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum"> | |
4929 <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1"> | |
4930 JNI global reference. | |
4931 </constant> | |
4932 <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2"> | |
4933 System class. | |
4934 </constant> | |
4935 <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3"> | |
4936 Monitor. | |
4937 </constant> | |
4938 <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4"> | |
4939 Stack local. | |
4940 </constant> | |
4941 <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5"> | |
4942 JNI local reference. | |
4943 </constant> | |
4944 <constant id="JVMTI_HEAP_ROOT_THREAD" num="6"> | |
4945 Thread. | |
4946 </constant> | |
4947 <constant id="JVMTI_HEAP_ROOT_OTHER" num="7"> | |
4948 Other. | |
4949 </constant> | |
4950 </constants> | |
4951 | |
4952 <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum"> | |
4953 <constant id="JVMTI_REFERENCE_CLASS" num="1"> | |
4954 Reference from an object to its class. | |
4955 </constant> | |
4956 <constant id="JVMTI_REFERENCE_FIELD" num="2"> | |
4957 Reference from an object to the value of one of its instance fields. | |
4958 For references of this kind the <code>referrer_index</code> | |
4959 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
4960 jvmtiObjectReferenceCallback</internallink> is the index of the | |
4961 the instance field. The index is based on the order of all the | |
4962 object's fields. This includes all fields of the directly declared | |
4963 static and instance fields in the class, and includes all fields (both | |
4964 public and private) fields declared in superclasses and superinterfaces. | |
4965 The index is thus calculated by summing the index of the field in the directly | |
4966 declared class (see <functionlink id="GetClassFields"/>), with the total | |
4967 number of fields (both public and private) declared in all superclasses | |
4968 and superinterfaces. The index starts at zero. | |
4969 </constant> | |
4970 <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3"> | |
4971 Reference from an array to one of its elements. | |
4972 For references of this kind the <code>referrer_index</code> | |
4973 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
4974 jvmtiObjectReferenceCallback</internallink> is the array index. | |
4975 </constant> | |
4976 <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4"> | |
4977 Reference from a class to its class loader. | |
4978 </constant> | |
4979 <constant id="JVMTI_REFERENCE_SIGNERS" num="5"> | |
4980 Reference from a class to its signers array. | |
4981 </constant> | |
4982 <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6"> | |
4983 Reference from a class to its protection domain. | |
4984 </constant> | |
4985 <constant id="JVMTI_REFERENCE_INTERFACE" num="7"> | |
4986 Reference from a class to one of its interfaces. | |
4987 </constant> | |
4988 <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8"> | |
4989 Reference from a class to the value of one of its static fields. | |
4990 For references of this kind the <code>referrer_index</code> | |
4991 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
4992 jvmtiObjectReferenceCallback</internallink> is the index of the | |
4993 the static field. The index is based on the order of all the | |
4994 object's fields. This includes all fields of the directly declared | |
4995 static and instance fields in the class, and includes all fields (both | |
4996 public and private) fields declared in superclasses and superinterfaces. | |
4997 The index is thus calculated by summing the index of the field in the directly | |
4998 declared class (see <functionlink id="GetClassFields"/>), with the total | |
4999 number of fields (both public and private) declared in all superclasses | |
5000 and superinterfaces. The index starts at zero. | |
5001 Note: this definition differs from that in the <jvmti/> 1.0 Specification. | |
5002 <rationale>No known implementations used the 1.0 definition.</rationale> | |
5003 </constant> | |
5004 <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9"> | |
5005 Reference from a class to a resolved entry in the constant pool. | |
5006 For references of this kind the <code>referrer_index</code> | |
5007 parameter to the <internallink id="jvmtiObjectReferenceCallback"> | |
5008 jvmtiObjectReferenceCallback</internallink> is the index into | |
5009 constant pool table of the class, starting at 1. See the | |
5010 <vmspeclink id="ClassFile.doc.html#20080" | |
5011 name="Constant Pool section"/> | |
5012 </constant> | |
5013 </constants> | |
5014 | |
5015 <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum"> | |
5016 <constant id="JVMTI_ITERATION_CONTINUE" num="1"> | |
5017 Continue the iteration. | |
5018 If this is a reference iteration, follow the references of this object. | |
5019 </constant> | |
5020 <constant id="JVMTI_ITERATION_IGNORE" num="2"> | |
5021 Continue the iteration. | |
5022 If this is a reference iteration, ignore the references of this object. | |
5023 </constant> | |
5024 <constant id="JVMTI_ITERATION_ABORT" num="0"> | |
5025 Abort the iteration. | |
5026 </constant> | |
5027 </constants> | |
5028 </intro> | |
5029 | |
5030 <callback id="jvmtiHeapObjectCallback"> | |
5031 <enum>jvmtiIterationControl</enum> | |
5032 <synopsis>Heap Object Callback</synopsis> | |
5033 <description> | |
5034 Agent supplied callback function. | |
5035 Describes (but does not pass in) an object in the heap. | |
5036 <p/> | |
5037 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
5038 or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
5039 <p/> | |
5040 See the <internallink id="heapCallbacks">heap callback | |
5041 function restrictions</internallink>. | |
5042 </description> | |
5043 <parameters> | |
5044 <param id="class_tag"> | |
5045 <jlong/> | |
5046 <description> | |
5047 The tag of the class of object (zero if the class is not tagged). | |
5048 If the object represents a runtime class, | |
5049 the <code>class_tag</code> is the tag | |
5050 associated with <code>java.lang.Class</code> | |
5051 (zero if <code>java.lang.Class</code> is not tagged). | |
5052 </description> | |
5053 </param> | |
5054 <param id="size"> | |
5055 <jlong/> | |
5056 <description> | |
5057 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
5058 </description> | |
5059 </param> | |
5060 <param id="tag_ptr"> | |
5061 <outptr><jlong/></outptr> | |
5062 <description> | |
5063 The object tag value, or zero if the object is not tagged. | |
5064 To set the tag value to be associated with the object | |
5065 the agent sets the <code>jlong</code> pointed to by the parameter. | |
5066 </description> | |
5067 </param> | |
5068 <param id="user_data"> | |
5069 <outptr><void/></outptr> | |
5070 <description> | |
5071 The user supplied data that was passed into the iteration function. | |
5072 </description> | |
5073 </param> | |
5074 </parameters> | |
5075 </callback> | |
5076 | |
5077 <callback id="jvmtiHeapRootCallback"> | |
5078 <enum>jvmtiIterationControl</enum> | |
5079 <synopsis>Heap Root Object Callback</synopsis> | |
5080 <description> | |
5081 Agent supplied callback function. | |
5082 Describes (but does not pass in) an object that is a root for the purposes | |
5083 of garbage collection. | |
5084 <p/> | |
5085 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
5086 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
5087 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
5088 <p/> | |
5089 See the <internallink id="heapCallbacks">heap callback | |
5090 function restrictions</internallink>. | |
5091 </description> | |
5092 <parameters> | |
5093 <param id="root_kind"> | |
5094 <enum>jvmtiHeapRootKind</enum> | |
5095 <description> | |
5096 The kind of heap root. | |
5097 </description> | |
5098 </param> | |
5099 <param id="class_tag"> | |
5100 <jlong/> | |
5101 <description> | |
5102 The tag of the class of object (zero if the class is not tagged). | |
5103 If the object represents a runtime class, the <code>class_tag</code> is the tag | |
5104 associated with <code>java.lang.Class</code> | |
5105 (zero if <code>java.lang.Class</code> is not tagged). | |
5106 </description> | |
5107 </param> | |
5108 <param id="size"> | |
5109 <jlong/> | |
5110 <description> | |
5111 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
5112 </description> | |
5113 </param> | |
5114 <param id="tag_ptr"> | |
5115 <outptr><jlong/></outptr> | |
5116 <description> | |
5117 The object tag value, or zero if the object is not tagged. | |
5118 To set the tag value to be associated with the object | |
5119 the agent sets the <code>jlong</code> pointed to by the parameter. | |
5120 </description> | |
5121 </param> | |
5122 <param id="user_data"> | |
5123 <outptr><void/></outptr> | |
5124 <description> | |
5125 The user supplied data that was passed into the iteration function. | |
5126 </description> | |
5127 </param> | |
5128 </parameters> | |
5129 </callback> | |
5130 | |
5131 <callback id="jvmtiStackReferenceCallback"> | |
5132 <enum>jvmtiIterationControl</enum> | |
5133 <synopsis>Stack Reference Object Callback</synopsis> | |
5134 <description> | |
5135 Agent supplied callback function. | |
5136 Describes (but does not pass in) an object on the stack that is a root for | |
5137 the purposes of garbage collection. | |
5138 <p/> | |
5139 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
5140 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
5141 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
5142 <p/> | |
5143 See the <internallink id="heapCallbacks">heap callback | |
5144 function restrictions</internallink>. | |
5145 </description> | |
5146 <parameters> | |
5147 <param id="root_kind"> | |
5148 <enum>jvmtiHeapRootKind</enum> | |
5149 <description> | |
5150 The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or | |
5151 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>). | |
5152 </description> | |
5153 </param> | |
5154 <param id="class_tag"> | |
5155 <jlong/> | |
5156 <description> | |
5157 The tag of the class of object (zero if the class is not tagged). | |
5158 If the object represents a runtime class, the <code>class_tag</code> is the tag | |
5159 associated with <code>java.lang.Class</code> | |
5160 (zero if <code>java.lang.Class</code> is not tagged). | |
5161 </description> | |
5162 </param> | |
5163 <param id="size"> | |
5164 <jlong/> | |
5165 <description> | |
5166 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
5167 </description> | |
5168 </param> | |
5169 <param id="tag_ptr"> | |
5170 <outptr><jlong/></outptr> | |
5171 <description> | |
5172 The object tag value, or zero if the object is not tagged. | |
5173 To set the tag value to be associated with the object | |
5174 the agent sets the <code>jlong</code> pointed to by the parameter. | |
5175 </description> | |
5176 </param> | |
5177 <param id="thread_tag"> | |
5178 <jlong/> | |
5179 <description> | |
5180 The tag of the thread corresponding to this stack, zero if not tagged. | |
5181 </description> | |
5182 </param> | |
5183 <param id="depth"> | |
5184 <jint/> | |
5185 <description> | |
5186 The depth of the frame. | |
5187 </description> | |
5188 </param> | |
5189 <param id="method"> | |
5190 <jmethodID/> | |
5191 <description> | |
5192 The method executing in this frame. | |
5193 </description> | |
5194 </param> | |
5195 <param id="slot"> | |
5196 <jint/> | |
5197 <description> | |
5198 The slot number. | |
5199 </description> | |
5200 </param> | |
5201 <param id="user_data"> | |
5202 <outptr><void/></outptr> | |
5203 <description> | |
5204 The user supplied data that was passed into the iteration function. | |
5205 </description> | |
5206 </param> | |
5207 </parameters> | |
5208 </callback> | |
5209 | |
5210 <callback id="jvmtiObjectReferenceCallback"> | |
5211 <enum>jvmtiIterationControl</enum> | |
5212 <synopsis>Object Reference Callback</synopsis> | |
5213 <description> | |
5214 Agent supplied callback function. | |
5215 Describes a reference from an object (the referrer) to another object | |
5216 (the referree). | |
5217 <p/> | |
5218 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, | |
5219 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing | |
5220 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. | |
5221 <p/> | |
5222 See the <internallink id="heapCallbacks">heap callback | |
5223 function restrictions</internallink>. | |
5224 </description> | |
5225 <parameters> | |
5226 <param id="reference_kind"> | |
5227 <enum>jvmtiObjectReferenceKind</enum> | |
5228 <description> | |
5229 The type of reference. | |
5230 </description> | |
5231 </param> | |
5232 <param id="class_tag"> | |
5233 <jlong/> | |
5234 <description> | |
5235 The tag of the class of referree object (zero if the class is not tagged). | |
5236 If the referree object represents a runtime class, | |
5237 the <code>class_tag</code> is the tag | |
5238 associated with <code>java.lang.Class</code> | |
5239 (zero if <code>java.lang.Class</code> is not tagged). | |
5240 </description> | |
5241 </param> | |
5242 <param id="size"> | |
5243 <jlong/> | |
5244 <description> | |
5245 Size of the referree object (in bytes). | |
5246 See <functionlink id="GetObjectSize"/>. | |
5247 </description> | |
5248 </param> | |
5249 <param id="tag_ptr"> | |
5250 <outptr><jlong/></outptr> | |
5251 <description> | |
5252 The referree object tag value, or zero if the object is not | |
5253 tagged. | |
5254 To set the tag value to be associated with the object | |
5255 the agent sets the <code>jlong</code> pointed to by the parameter. | |
5256 </description> | |
5257 </param> | |
5258 <param id="referrer_tag"> | |
5259 <jlong/> | |
5260 <description> | |
5261 The tag of the referrer object, or zero if the referrer | |
5262 object is not tagged. | |
5263 </description> | |
5264 </param> | |
5265 <param id="referrer_index"> | |
5266 <jint/> | |
5267 <description> | |
5268 For references of type <code>JVMTI_REFERENCE_FIELD</code> or | |
5269 <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index | |
5270 of the field in the referrer object. The index is based on the | |
5271 order of all the object's fields - see <internallink | |
5272 id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink> | |
5273 or <internallink | |
5274 id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD | |
5275 </internallink> for further description. | |
5276 <p/> | |
5277 For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code> | |
5278 the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT"> | |
5279 JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description. | |
5280 <p/> | |
5281 For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code> | |
5282 the index into the constant pool of the class - see | |
5283 <internallink id="JVMTI_REFERENCE_CONSTANT_POOL"> | |
5284 JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further | |
5285 description. | |
5286 <p/> | |
5287 For references of other kinds the <code>referrer_index</code> is | |
5288 <code>-1</code>. | |
5289 </description> | |
5290 </param> | |
5291 <param id="user_data"> | |
5292 <outptr><void/></outptr> | |
5293 <description> | |
5294 The user supplied data that was passed into the iteration function. | |
5295 </description> | |
5296 </param> | |
5297 </parameters> | |
5298 </callback> | |
5299 | |
5300 <function id="IterateOverObjectsReachableFromObject" num="109"> | |
5301 <synopsis>Iterate Over Objects Reachable From Object</synopsis> | |
5302 <description> | |
5303 This function iterates over all objects that are directly | |
5304 and indirectly reachable from the specified object. | |
5305 For each object <i>A</i> (known | |
5306 as the referrer) with a reference to object <i>B</i> the specified | |
5307 callback function is called to describe the object reference. | |
5308 The callback is called exactly once for each reference from a referrer; | |
5309 this is true even if there are reference cycles or multiple paths to | |
5310 the referrer. | |
5311 There may be more than one reference between a referrer and a referree, | |
5312 These may be distinguished by the | |
5313 <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and | |
5314 <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>. | |
5315 The callback for an object will always occur after the callback for | |
5316 its referrer. | |
5317 <p/> | |
5318 See <functionlink id="FollowReferences"/> for the object | |
5319 references which are reported. | |
5320 <p/> | |
5321 During the execution of this function the state of the heap | |
5322 does not change: no objects are allocated, no objects are | |
5323 garbage collected, and the state of objects (including | |
5324 held values) does not change. | |
5325 As a result, threads executing Java | |
5326 programming language code, threads attempting to resume the | |
5327 execution of Java programming language code, and threads | |
5328 attempting to execute JNI functions are typically stalled. | |
5329 </description> | |
5330 <origin>new</origin> | |
5331 <capabilities> | |
5332 <required id="can_tag_objects"></required> | |
5333 </capabilities> | |
5334 <parameters> | |
5335 <param id="object"> | |
5336 <jobject/> | |
5337 <description> | |
5338 The object | |
5339 </description> | |
5340 </param> | |
5341 <param id="object_reference_callback"> | |
5342 <ptrtype> | |
5343 <struct>jvmtiObjectReferenceCallback</struct> | |
5344 </ptrtype> | |
5345 <description> | |
5346 The callback to be called to describe each | |
5347 object reference. | |
5348 </description> | |
5349 </param> | |
5350 <param id="user_data"> | |
5351 <inbuf> | |
5352 <void/> | |
5353 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
5354 </inbuf> | |
5355 <description> | |
5356 User supplied data to be passed to the callback. | |
5357 </description> | |
5358 </param> | |
5359 </parameters> | |
5360 <errors> | |
5361 </errors> | |
5362 </function> | |
5363 | |
5364 <function id="IterateOverReachableObjects" num="110"> | |
5365 <synopsis>Iterate Over Reachable Objects</synopsis> | |
5366 <description> | |
5367 This function iterates over the root objects and all objects that | |
5368 are directly and indirectly reachable from the root objects. | |
5369 The root objects comprise the set of system classes, | |
5370 JNI globals, references from thread stacks, and other objects used as roots | |
5371 for the purposes of garbage collection. | |
5372 <p/> | |
5373 For each root the <paramlink id="heap_root_callback"></paramlink> | |
5374 or <paramlink id="stack_ref_callback"></paramlink> callback is called. | |
5375 An object can be a root object for more than one reason and in that case | |
5376 the appropriate callback is called for each reason. | |
5377 <p/> | |
5378 For each object reference the <paramlink id="object_ref_callback"></paramlink> | |
5379 callback function is called to describe the object reference. | |
5380 The callback is called exactly once for each reference from a referrer; | |
5381 this is true even if there are reference cycles or multiple paths to | |
5382 the referrer. | |
5383 There may be more than one reference between a referrer and a referree, | |
5384 These may be distinguished by the | |
5385 <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and | |
5386 <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>. | |
5387 The callback for an object will always occur after the callback for | |
5388 its referrer. | |
5389 <p/> | |
5390 See <functionlink id="FollowReferences"/> for the object | |
5391 references which are reported. | |
5392 <p/> | |
5393 Roots are always reported to the profiler before any object references | |
5394 are reported. In other words, the <paramlink id="object_ref_callback"></paramlink> | |
5395 callback will not be called until the appropriate callback has been called | |
5396 for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is | |
5397 specified as <code>NULL</code> then this function returns after | |
5398 reporting the root objects to the profiler. | |
5399 <p/> | |
5400 During the execution of this function the state of the heap | |
5401 does not change: no objects are allocated, no objects are | |
5402 garbage collected, and the state of objects (including | |
5403 held values) does not change. | |
5404 As a result, threads executing Java | |
5405 programming language code, threads attempting to resume the | |
5406 execution of Java programming language code, and threads | |
5407 attempting to execute JNI functions are typically stalled. | |
5408 </description> | |
5409 <origin>new</origin> | |
5410 <capabilities> | |
5411 <required id="can_tag_objects"></required> | |
5412 </capabilities> | |
5413 <parameters> | |
5414 <param id="heap_root_callback"> | |
5415 <ptrtype> | |
5416 <struct>jvmtiHeapRootCallback</struct> | |
5417 <nullok>do not report heap roots</nullok> | |
5418 </ptrtype> | |
5419 <description> | |
5420 The callback function to be called for each heap root of type | |
5421 <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>, | |
5422 <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>, | |
5423 <code>JVMTI_HEAP_ROOT_MONITOR</code>, | |
5424 <code>JVMTI_HEAP_ROOT_THREAD</code>, or | |
5425 <code>JVMTI_HEAP_ROOT_OTHER</code>. | |
5426 </description> | |
5427 </param> | |
5428 <param id="stack_ref_callback"> | |
5429 <ptrtype> | |
5430 <struct>jvmtiStackReferenceCallback</struct> | |
5431 <nullok>do not report stack references</nullok> | |
5432 </ptrtype> | |
5433 <description> | |
5434 The callback function to be called for each heap root of | |
5435 <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or | |
5436 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>. | |
5437 </description> | |
5438 </param> | |
5439 <param id="object_ref_callback"> | |
5440 <ptrtype> | |
5441 <struct>jvmtiObjectReferenceCallback</struct> | |
5442 <nullok>do not follow references from the root objects</nullok> | |
5443 </ptrtype> | |
5444 <description> | |
5445 The callback function to be called for each object reference. | |
5446 </description> | |
5447 </param> | |
5448 <param id="user_data"> | |
5449 <inbuf> | |
5450 <void/> | |
5451 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
5452 </inbuf> | |
5453 <description> | |
5454 User supplied data to be passed to the callback. | |
5455 </description> | |
5456 </param> | |
5457 </parameters> | |
5458 <errors> | |
5459 </errors> | |
5460 </function> | |
5461 | |
5462 <function id="IterateOverHeap" num="111"> | |
5463 <synopsis>Iterate Over Heap</synopsis> | |
5464 <description> | |
5465 Iterate over all objects in the heap. This includes both reachable and | |
5466 unreachable objects. | |
5467 <p/> | |
5468 The <paramlink id="object_filter"></paramlink> parameter indicates the | |
5469 objects for which the callback function is called. If this parameter | |
5470 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be | |
5471 called for every object that is tagged. If the parameter is | |
5472 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be | |
5473 for objects that are not tagged. If the parameter | |
5474 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be | |
5475 called for every object in the heap, irrespective of whether it is | |
5476 tagged or not. | |
5477 <p/> | |
5478 During the execution of this function the state of the heap | |
5479 does not change: no objects are allocated, no objects are | |
5480 garbage collected, and the state of objects (including | |
5481 held values) does not change. | |
5482 As a result, threads executing Java | |
5483 programming language code, threads attempting to resume the | |
5484 execution of Java programming language code, and threads | |
5485 attempting to execute JNI functions are typically stalled. | |
5486 </description> | |
5487 <origin>new</origin> | |
5488 <capabilities> | |
5489 <required id="can_tag_objects"></required> | |
5490 </capabilities> | |
5491 <parameters> | |
5492 <param id="object_filter"> | |
5493 <enum>jvmtiHeapObjectFilter</enum> | |
5494 <description> | |
5495 Indicates the objects for which the callback function is called. | |
5496 </description> | |
5497 </param> | |
5498 <param id="heap_object_callback"> | |
5499 <ptrtype> | |
5500 <struct>jvmtiHeapObjectCallback</struct> | |
5501 </ptrtype> | |
5502 <description> | |
5503 The iterator function to be called for each | |
5504 object matching the <paramlink id="object_filter"/>. | |
5505 </description> | |
5506 </param> | |
5507 <param id="user_data"> | |
5508 <inbuf> | |
5509 <void/> | |
5510 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
5511 </inbuf> | |
5512 <description> | |
5513 User supplied data to be passed to the callback. | |
5514 </description> | |
5515 </param> | |
5516 </parameters> | |
5517 <errors> | |
5518 </errors> | |
5519 </function> | |
5520 | |
5521 <function id="IterateOverInstancesOfClass" num="112"> | |
5522 <synopsis>Iterate Over Instances Of Class</synopsis> | |
5523 <description> | |
5524 Iterate over all objects in the heap that are instances of the specified class. | |
5525 This includes direct instances of the specified class and | |
5526 instances of all subclasses of the specified class. | |
5527 This includes both reachable and unreachable objects. | |
5528 <p/> | |
5529 The <paramlink id="object_filter"></paramlink> parameter indicates the | |
5530 objects for which the callback function is called. If this parameter | |
5531 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be | |
5532 called for every object that is tagged. If the parameter is | |
5533 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be | |
5534 called for objects that are not tagged. If the parameter | |
5535 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be | |
5536 called for every object in the heap, irrespective of whether it is | |
5537 tagged or not. | |
5538 <p/> | |
5539 During the execution of this function the state of the heap | |
5540 does not change: no objects are allocated, no objects are | |
5541 garbage collected, and the state of objects (including | |
5542 held values) does not change. | |
5543 As a result, threads executing Java | |
5544 programming language code, threads attempting to resume the | |
5545 execution of Java programming language code, and threads | |
5546 attempting to execute JNI functions are typically stalled. | |
5547 </description> | |
5548 <origin>new</origin> | |
5549 <capabilities> | |
5550 <required id="can_tag_objects"></required> | |
5551 </capabilities> | |
5552 <parameters> | |
5553 <param id="klass"> | |
5554 <jclass/> | |
5555 <description> | |
5556 Iterate over objects of this class only. | |
5557 </description> | |
5558 </param> | |
5559 <param id="object_filter"> | |
5560 <enum>jvmtiHeapObjectFilter</enum> | |
5561 <description> | |
5562 Indicates the objects for which the callback function is called. | |
5563 </description> | |
5564 </param> | |
5565 <param id="heap_object_callback"> | |
5566 <ptrtype> | |
5567 <struct>jvmtiHeapObjectCallback</struct> | |
5568 </ptrtype> | |
5569 <description> | |
5570 The iterator function to be called for each | |
5571 <paramlink id="klass"/> instance matching | |
5572 the <paramlink id="object_filter"/>. | |
5573 </description> | |
5574 </param> | |
5575 <param id="user_data"> | |
5576 <inbuf> | |
5577 <void/> | |
5578 <nullok><code>NULL</code> is passed as the user supplied data</nullok> | |
5579 </inbuf> | |
5580 <description> | |
5581 User supplied data to be passed to the callback. | |
5582 </description> | |
5583 </param> | |
5584 </parameters> | |
5585 <errors> | |
5586 </errors> | |
5587 </function> | |
5588 | |
5589 </category> | |
5590 | |
5591 <category id="local" label="Local Variable"> | |
5592 | |
5593 <intro> | |
5594 These functions are used to retrieve or set the value of a local variable. | |
5595 The variable is identified by the depth of the frame containing its | |
5596 value and the variable's slot number within that frame. | |
5597 The mapping of variables to | |
5598 slot numbers can be obtained with the function | |
5599 <functionlink id="GetLocalVariableTable"></functionlink>. | |
5600 </intro> | |
5601 | |
5602 <function id="GetLocalObject" num="21"> | |
5603 <synopsis>Get Local Variable - Object</synopsis> | |
5604 <description> | |
5605 This function can be used to retrieve the value of a local | |
5606 variable whose type is <code>Object</code> or a subclass of <code>Object</code>. | |
5607 </description> | |
5608 <origin>jvmdi</origin> | |
5609 <capabilities> | |
5610 <required id="can_access_local_variables"></required> | |
5611 </capabilities> | |
5612 <parameters> | |
5613 <param id="thread"> | |
5614 <jthread null="current" frame="frame"/> | |
5615 <description> | |
5616 The thread of the frame containing the variable's value. | |
5617 </description> | |
5618 </param> | |
5619 <param id="depth"> | |
5620 <jframeID thread="thread"/> | |
5621 <description> | |
5622 The depth of the frame containing the variable's value. | |
5623 </description> | |
5624 </param> | |
5625 <param id="slot"> | |
5626 <jint/> | |
5627 <description> | |
5628 The variable's slot number. | |
5629 </description> | |
5630 </param> | |
5631 <param id="value_ptr"> | |
5632 <outptr><jobject/></outptr> | |
5633 <description> | |
5634 On return, points to the variable's value. | |
5635 </description> | |
5636 </param> | |
5637 </parameters> | |
5638 <errors> | |
5639 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
5640 Invalid <code>slot</code>. | |
5641 </error> | |
5642 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
5643 The variable type is not | |
5644 <code>Object</code> or a subclass of <code>Object</code>. | |
5645 </error> | |
5646 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
5647 Not a visible frame | |
5648 </error> | |
5649 </errors> | |
5650 </function> | |
5651 | |
5652 <function id="GetLocalInt" num="22"> | |
5653 <synopsis>Get Local Variable - Int</synopsis> | |
5654 <description> | |
5655 This function can be used to retrieve the value of a local | |
5656 variable whose type is <code>int</code>, | |
5657 <code>short</code>, <code>char</code>, <code>byte</code>, or | |
5658 <code>boolean</code>. | |
5659 </description> | |
5660 <origin>jvmdi</origin> | |
5661 <capabilities> | |
5662 <required id="can_access_local_variables"></required> | |
5663 </capabilities> | |
5664 <parameters> | |
5665 <param id="thread"> | |
5666 <jthread null="current" frame="frame"/> | |
5667 <description> | |
5668 The thread of the frame containing the variable's value. | |
5669 </description> | |
5670 </param> | |
5671 <param id="depth"> | |
5672 <jframeID thread="thread"/> | |
5673 <description> | |
5674 The depth of the frame containing the variable's value. | |
5675 </description> | |
5676 </param> | |
5677 <param id="slot"> | |
5678 <jint/> | |
5679 <description> | |
5680 The variable's slot number. | |
5681 </description> | |
5682 </param> | |
5683 <param id="value_ptr"> | |
5684 <outptr><jint/></outptr> | |
5685 <description> | |
5686 On return, points to the variable's value. | |
5687 </description> | |
5688 </param> | |
5689 </parameters> | |
5690 <errors> | |
5691 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
5692 Invalid <code>slot</code>. | |
5693 </error> | |
5694 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
5695 The variable type is not | |
5696 <code>int</code>, <code>short</code>, | |
5697 <code>char</code>, <code>byte</code>, or | |
5698 <code>boolean</code>. | |
5699 </error> | |
5700 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
5701 Not a visible frame | |
5702 </error> | |
5703 </errors> | |
5704 </function> | |
5705 | |
5706 <function id="GetLocalLong" num="23"> | |
5707 <synopsis>Get Local Variable - Long</synopsis> | |
5708 <description> | |
5709 This function can be used to retrieve the value of a local | |
5710 variable whose type is <code>long</code>. | |
5711 </description> | |
5712 <origin>jvmdi</origin> | |
5713 <capabilities> | |
5714 <required id="can_access_local_variables"></required> | |
5715 </capabilities> | |
5716 <parameters> | |
5717 <param id="thread"> | |
5718 <jthread null="current" frame="frame"/> | |
5719 <description> | |
5720 The thread of the frame containing the variable's value. | |
5721 </description> | |
5722 </param> | |
5723 <param id="depth"> | |
5724 <jframeID thread="thread"/> | |
5725 <description> | |
5726 The depth of the frame containing the variable's value. | |
5727 </description> | |
5728 </param> | |
5729 <param id="slot"> | |
5730 <jint/> | |
5731 <description> | |
5732 The variable's slot number. | |
5733 </description> | |
5734 </param> | |
5735 <param id="value_ptr"> | |
5736 <outptr><jlong/></outptr> | |
5737 <description> | |
5738 On return, points to the variable's value. | |
5739 </description> | |
5740 </param> | |
5741 </parameters> | |
5742 <errors> | |
5743 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
5744 Invalid <code>slot</code>. | |
5745 </error> | |
5746 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
5747 The variable type is not <code>long</code>. | |
5748 </error> | |
5749 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
5750 Not a visible frame | |
5751 </error> | |
5752 </errors> | |
5753 </function> | |
5754 | |
5755 <function id="GetLocalFloat" num="24"> | |
5756 <synopsis>Get Local Variable - Float</synopsis> | |
5757 <description> | |
5758 This function can be used to retrieve the value of a local | |
5759 variable whose type is <code>float</code>. | |
5760 </description> | |
5761 <origin>jvmdi</origin> | |
5762 <capabilities> | |
5763 <required id="can_access_local_variables"></required> | |
5764 </capabilities> | |
5765 <parameters> | |
5766 <param id="thread"> | |
5767 <jthread null="current" frame="frame"/> | |
5768 <description> | |
5769 The thread of the frame containing the variable's value. | |
5770 </description> | |
5771 </param> | |
5772 <param id="depth"> | |
5773 <jframeID thread="thread"/> | |
5774 <description> | |
5775 The depth of the frame containing the variable's value. | |
5776 </description> | |
5777 </param> | |
5778 <param id="slot"> | |
5779 <jint/> | |
5780 <description> | |
5781 The variable's slot number. | |
5782 </description> | |
5783 </param> | |
5784 <param id="value_ptr"> | |
5785 <outptr><jfloat/></outptr> | |
5786 <description> | |
5787 On return, points to the variable's value. | |
5788 </description> | |
5789 </param> | |
5790 </parameters> | |
5791 <errors> | |
5792 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
5793 Invalid <code>slot</code>. | |
5794 </error> | |
5795 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
5796 The variable type is not <code>float</code>. | |
5797 </error> | |
5798 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
5799 Not a visible frame | |
5800 </error> | |
5801 </errors> | |
5802 </function> | |
5803 | |
5804 <function id="GetLocalDouble" num="25"> | |
5805 <synopsis>Get Local Variable - Double</synopsis> | |
5806 <description> | |
5807 This function can be used to retrieve the value of a local | |
5808 variable whose type is <code>long</code>. | |
5809 </description> | |
5810 <origin>jvmdi</origin> | |
5811 <capabilities> | |
5812 <required id="can_access_local_variables"></required> | |
5813 </capabilities> | |
5814 <parameters> | |
5815 <param id="thread"> | |
5816 <jthread null="current" frame="frame"/> | |
5817 <description> | |
5818 The thread of the frame containing the variable's value. | |
5819 </description> | |
5820 </param> | |
5821 <param id="depth"> | |
5822 <jframeID thread="thread"/> | |
5823 <description> | |
5824 The depth of the frame containing the variable's value. | |
5825 </description> | |
5826 </param> | |
5827 <param id="slot"> | |
5828 <jint/> | |
5829 <description> | |
5830 The variable's slot number. | |
5831 </description> | |
5832 </param> | |
5833 <param id="value_ptr"> | |
5834 <outptr><jdouble/></outptr> | |
5835 <description> | |
5836 On return, points to the variable's value. | |
5837 </description> | |
5838 </param> | |
5839 </parameters> | |
5840 <errors> | |
5841 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
5842 Invalid <code>slot</code>. | |
5843 </error> | |
5844 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
5845 The variable type is not <code>double</code>. | |
5846 </error> | |
5847 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
5848 Not a visible frame | |
5849 </error> | |
5850 </errors> | |
5851 </function> | |
5852 | |
5853 <function id="SetLocalObject" num="26"> | |
5854 <synopsis>Set Local Variable - Object</synopsis> | |
5855 <description> | |
5856 This function can be used to set the value of a local | |
5857 variable whose type is <code>Object</code> or a subclass of <code>Object</code>. | |
5858 </description> | |
5859 <origin>jvmdi</origin> | |
5860 <capabilities> | |
5861 <required id="can_access_local_variables"></required> | |
5862 </capabilities> | |
5863 <parameters> | |
5864 <param id="thread"> | |
5865 <jthread null="current" frame="frame"/> | |
5866 <description> | |
5867 The thread of the frame containing the variable's value. | |
5868 </description> | |
5869 </param> | |
5870 <param id="depth"> | |
5871 <jframeID thread="thread"/> | |
5872 <description> | |
5873 The depth of the frame containing the variable's value. | |
5874 </description> | |
5875 </param> | |
5876 <param id="slot"> | |
5877 <jint/> | |
5878 <description> | |
5879 The variable's slot number. | |
5880 </description> | |
5881 </param> | |
5882 <param id="value"> | |
5883 <jobject/> | |
5884 <description> | |
5885 The new value for the variable. | |
5886 </description> | |
5887 </param> | |
5888 </parameters> | |
5889 <errors> | |
5890 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
5891 Invalid <code>slot</code>. | |
5892 </error> | |
5893 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
5894 The variable type is not | |
5895 <code>Object</code> or a subclass of <code>Object</code>. | |
5896 </error> | |
5897 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
5898 The supplied <paramlink id="value"/> is not compatible | |
5899 with the variable type. | |
5900 </error> | |
5901 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
5902 Not a visible frame | |
5903 </error> | |
5904 </errors> | |
5905 </function> | |
5906 | |
5907 <function id="SetLocalInt" num="27"> | |
5908 <synopsis>Set Local Variable - Int</synopsis> | |
5909 <description> | |
5910 This function can be used to set the value of a local | |
5911 variable whose type is <code>int</code>, | |
5912 <code>short</code>, <code>char</code>, <code>byte</code>, or | |
5913 <code>boolean</code>. | |
5914 </description> | |
5915 <origin>jvmdi</origin> | |
5916 <capabilities> | |
5917 <required id="can_access_local_variables"></required> | |
5918 </capabilities> | |
5919 <parameters> | |
5920 <param id="thread"> | |
5921 <jthread null="current" frame="frame"/> | |
5922 <description> | |
5923 The thread of the frame containing the variable's value. | |
5924 </description> | |
5925 </param> | |
5926 <param id="depth"> | |
5927 <jframeID thread="thread"/> | |
5928 <description> | |
5929 The depth of the frame containing the variable's value. | |
5930 </description> | |
5931 </param> | |
5932 <param id="slot"> | |
5933 <jint/> | |
5934 <description> | |
5935 The variable's slot number. | |
5936 </description> | |
5937 </param> | |
5938 <param id="value"> | |
5939 <jint/> | |
5940 <description> | |
5941 The new value for the variable. | |
5942 </description> | |
5943 </param> | |
5944 </parameters> | |
5945 <errors> | |
5946 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
5947 Invalid <code>slot</code>. | |
5948 </error> | |
5949 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
5950 The variable type is not | |
5951 <code>int</code>, <code>short</code>, | |
5952 <code>char</code>, <code>byte</code>, or | |
5953 <code>boolean</code>. | |
5954 </error> | |
5955 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
5956 Not a visible frame | |
5957 </error> | |
5958 </errors> | |
5959 </function> | |
5960 | |
5961 <function id="SetLocalLong" num="28"> | |
5962 <synopsis>Set Local Variable - Long</synopsis> | |
5963 <description> | |
5964 This function can be used to set the value of a local | |
5965 variable whose type is <code>long</code>. | |
5966 </description> | |
5967 <origin>jvmdi</origin> | |
5968 <capabilities> | |
5969 <required id="can_access_local_variables"></required> | |
5970 </capabilities> | |
5971 <parameters> | |
5972 <param id="thread"> | |
5973 <jthread null="current" frame="frame"/> | |
5974 <description> | |
5975 The thread of the frame containing the variable's value. | |
5976 </description> | |
5977 </param> | |
5978 <param id="depth"> | |
5979 <jframeID thread="thread"/> | |
5980 <description> | |
5981 The depth of the frame containing the variable's value. | |
5982 </description> | |
5983 </param> | |
5984 <param id="slot"> | |
5985 <jint/> | |
5986 <description> | |
5987 The variable's slot number. | |
5988 </description> | |
5989 </param> | |
5990 <param id="value"> | |
5991 <jlong/> | |
5992 <description> | |
5993 The new value for the variable. | |
5994 </description> | |
5995 </param> | |
5996 </parameters> | |
5997 <errors> | |
5998 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
5999 Invalid <code>slot</code>. | |
6000 </error> | |
6001 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
6002 The variable type is not <code>long</code>. | |
6003 </error> | |
6004 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
6005 Not a visible frame | |
6006 </error> | |
6007 </errors> | |
6008 </function> | |
6009 | |
6010 <function id="SetLocalFloat" num="29"> | |
6011 <synopsis>Set Local Variable - Float</synopsis> | |
6012 <description> | |
6013 This function can be used to set the value of a local | |
6014 variable whose type is <code>float</code>. | |
6015 </description> | |
6016 <origin>jvmdi</origin> | |
6017 <capabilities> | |
6018 <required id="can_access_local_variables"></required> | |
6019 </capabilities> | |
6020 <parameters> | |
6021 <param id="thread"> | |
6022 <jthread null="current" frame="frame"/> | |
6023 <description> | |
6024 The thread of the frame containing the variable's value. | |
6025 </description> | |
6026 </param> | |
6027 <param id="depth"> | |
6028 <jframeID thread="thread"/> | |
6029 <description> | |
6030 The depth of the frame containing the variable's value. | |
6031 </description> | |
6032 </param> | |
6033 <param id="slot"> | |
6034 <jint/> | |
6035 <description> | |
6036 The variable's slot number. | |
6037 </description> | |
6038 </param> | |
6039 <param id="value"> | |
6040 <jfloat/> | |
6041 <description> | |
6042 The new value for the variable. | |
6043 </description> | |
6044 </param> | |
6045 </parameters> | |
6046 <errors> | |
6047 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
6048 Invalid <code>slot</code>. | |
6049 </error> | |
6050 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
6051 The variable type is not <code>float</code>. | |
6052 </error> | |
6053 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
6054 Not a visible frame | |
6055 </error> | |
6056 </errors> | |
6057 </function> | |
6058 | |
6059 <function id="SetLocalDouble" num="30"> | |
6060 <synopsis>Set Local Variable - Double</synopsis> | |
6061 <description> | |
6062 This function can be used to set the value of a local | |
6063 variable whose type is <code>double</code>. | |
6064 </description> | |
6065 <origin>jvmdi</origin> | |
6066 <capabilities> | |
6067 <required id="can_access_local_variables"></required> | |
6068 </capabilities> | |
6069 <parameters> | |
6070 <param id="thread"> | |
6071 <jthread null="current" frame="frame"/> | |
6072 <description> | |
6073 The thread of the frame containing the variable's value. | |
6074 </description> | |
6075 </param> | |
6076 <param id="depth"> | |
6077 <jframeID thread="thread"/> | |
6078 <description> | |
6079 The depth of the frame containing the variable's value. | |
6080 </description> | |
6081 </param> | |
6082 <param id="slot"> | |
6083 <jint/> | |
6084 <description> | |
6085 The variable's slot number. | |
6086 </description> | |
6087 </param> | |
6088 <param id="value"> | |
6089 <jdouble/> | |
6090 <description> | |
6091 The new value for the variable. | |
6092 </description> | |
6093 </param> | |
6094 </parameters> | |
6095 <errors> | |
6096 <error id="JVMTI_ERROR_INVALID_SLOT"> | |
6097 Invalid <code>slot</code>. | |
6098 </error> | |
6099 <error id="JVMTI_ERROR_TYPE_MISMATCH"> | |
6100 The variable type is not <code>double</code>. | |
6101 </error> | |
6102 <error id="JVMTI_ERROR_OPAQUE_FRAME"> | |
6103 Not a visible frame | |
6104 </error> | |
6105 </errors> | |
6106 </function> | |
6107 </category> | |
6108 | |
6109 <category id="breakpointCategory" label="Breakpoint"> | |
6110 | |
6111 <intro> | |
6112 </intro> | |
6113 | |
6114 <function id="SetBreakpoint" num="38"> | |
6115 <synopsis>Set Breakpoint</synopsis> | |
6116 <description> | |
6117 Set a breakpoint at the instruction indicated by | |
6118 <code>method</code> and <code>location</code>. | |
6119 An instruction can only have one breakpoint. | |
6120 <p/> | |
6121 Whenever the designated instruction is about to be executed, a | |
6122 <eventlink id="Breakpoint"></eventlink> event is generated. | |
6123 </description> | |
6124 <origin>jvmdi</origin> | |
6125 <capabilities> | |
6126 <required id="can_generate_breakpoint_events"></required> | |
6127 </capabilities> | |
6128 <parameters> | |
6129 <param id="klass"> | |
6130 <jclass method="method"/> | |
6131 <description> | |
6132 The class in which to set the breakpoint | |
6133 </description> | |
6134 </param> | |
6135 <param id="method"> | |
6136 <jmethodID class="klass"/> | |
6137 <description> | |
6138 The method in which to set the breakpoint | |
6139 </description> | |
6140 </param> | |
6141 <param id="location"> | |
6142 <jlocation/> | |
6143 <description> | |
6144 the index of the instruction at which to set the breakpoint | |
6145 | |
6146 </description> | |
6147 </param> | |
6148 </parameters> | |
6149 <errors> | |
6150 <error id="JVMTI_ERROR_DUPLICATE"> | |
6151 The designated bytecode already has a breakpoint. | |
6152 </error> | |
6153 </errors> | |
6154 </function> | |
6155 | |
6156 <function id="ClearBreakpoint" num="39"> | |
6157 <synopsis>Clear Breakpoint</synopsis> | |
6158 <description> | |
6159 Clear the breakpoint at the bytecode indicated by | |
6160 <code>method</code> and <code>location</code>. | |
6161 </description> | |
6162 <origin>jvmdi</origin> | |
6163 <capabilities> | |
6164 <required id="can_generate_breakpoint_events"></required> | |
6165 </capabilities> | |
6166 <parameters> | |
6167 <param id="klass"> | |
6168 <jclass method="method"/> | |
6169 <description> | |
6170 The class in which to clear the breakpoint | |
6171 </description> | |
6172 </param> | |
6173 <param id="method"> | |
6174 <jmethodID class="klass"/> | |
6175 <description> | |
6176 The method in which to clear the breakpoint | |
6177 </description> | |
6178 </param> | |
6179 <param id="location"> | |
6180 <jlocation/> | |
6181 <description> | |
6182 the index of the instruction at which to clear the breakpoint | |
6183 </description> | |
6184 </param> | |
6185 </parameters> | |
6186 <errors> | |
6187 <error id="JVMTI_ERROR_NOT_FOUND"> | |
6188 There's no breakpoint at the designated bytecode. | |
6189 </error> | |
6190 </errors> | |
6191 </function> | |
6192 | |
6193 </category> | |
6194 | |
6195 <category id="fieldWatch" label="Watched Field"> | |
6196 | |
6197 <intro> | |
6198 </intro> | |
6199 | |
6200 <function id="SetFieldAccessWatch" num="41"> | |
6201 <synopsis>Set Field Access Watch</synopsis> | |
6202 <description> | |
6203 Generate a <eventlink id="FieldAccess"></eventlink> event | |
6204 when the field specified | |
6205 by <code>klass</code> and | |
6206 <code>field</code> is about to be accessed. | |
6207 An event will be generated for each access of the field | |
6208 until it is canceled with | |
6209 <functionlink id="ClearFieldAccessWatch"></functionlink>. | |
6210 Field accesses from Java programming language code or from JNI code are watched, | |
6211 fields modified by other means are not watched. | |
6212 Note that <jvmti/> users should be aware that their own field accesses | |
6213 will trigger the watch. | |
6214 A field can only have one field access watch set. | |
6215 Modification of a field is not considered an access--use | |
6216 <functionlink id="SetFieldModificationWatch"></functionlink> | |
6217 to monitor modifications. | |
6218 </description> | |
6219 <origin>jvmdi</origin> | |
6220 <capabilities> | |
6221 <required id="can_generate_field_access_events"></required> | |
6222 </capabilities> | |
6223 <parameters> | |
6224 <param id="klass"> | |
6225 <jclass field="field"/> | |
6226 <description> | |
6227 The class containing the field to watch | |
6228 </description> | |
6229 </param> | |
6230 <param id="field"> | |
6231 <jfieldID class="klass"/> | |
6232 <description> | |
6233 The field to watch | |
6234 | |
6235 </description> | |
6236 </param> | |
6237 </parameters> | |
6238 <errors> | |
6239 <error id="JVMTI_ERROR_DUPLICATE"> | |
6240 The designated field is already being watched for accesses. | |
6241 </error> | |
6242 </errors> | |
6243 </function> | |
6244 | |
6245 <function id="ClearFieldAccessWatch" num="42"> | |
6246 <synopsis>Clear Field Access Watch</synopsis> | |
6247 <description> | |
6248 Cancel a field access watch previously set by | |
6249 <functionlink id="SetFieldAccessWatch"></functionlink>, on the | |
6250 field specified | |
6251 by <code>klass</code> and | |
6252 <code>field</code>. | |
6253 </description> | |
6254 <origin>jvmdi</origin> | |
6255 <capabilities> | |
6256 <required id="can_generate_field_access_events"></required> | |
6257 </capabilities> | |
6258 <parameters> | |
6259 <param id="klass"> | |
6260 <jclass field="field"/> | |
6261 <description> | |
6262 The class containing the field to watch | |
6263 </description> | |
6264 </param> | |
6265 <param id="field"> | |
6266 <jfieldID class="klass"/> | |
6267 <description> | |
6268 The field to watch | |
6269 | |
6270 </description> | |
6271 </param> | |
6272 </parameters> | |
6273 <errors> | |
6274 <error id="JVMTI_ERROR_NOT_FOUND"> | |
6275 The designated field is not being watched for accesses. | |
6276 </error> | |
6277 </errors> | |
6278 </function> | |
6279 | |
6280 <function id="SetFieldModificationWatch" num="43"> | |
6281 <synopsis>Set Field Modification Watch</synopsis> | |
6282 <description> | |
6283 Generate a <eventlink id="FieldModification"></eventlink> event | |
6284 when the field specified | |
6285 by <code>klass</code> and | |
6286 <code>field</code> is about to be modified. | |
6287 An event will be generated for each modification of the field | |
6288 until it is canceled with | |
6289 <functionlink id="ClearFieldModificationWatch"></functionlink>. | |
6290 Field modifications from Java programming language code or from JNI code are watched, | |
6291 fields modified by other means are not watched. | |
6292 Note that <jvmti/> users should be aware that their own field modifications | |
6293 will trigger the watch. | |
6294 A field can only have one field modification watch set. | |
6295 </description> | |
6296 <origin>jvmdi</origin> | |
6297 <capabilities> | |
6298 <required id="can_generate_field_modification_events"></required> | |
6299 </capabilities> | |
6300 <parameters> | |
6301 <param id="klass"> | |
6302 <jclass field="field"/> | |
6303 <description> | |
6304 The class containing the field to watch | |
6305 </description> | |
6306 </param> | |
6307 <param id="field"> | |
6308 <jfieldID class="klass"/> | |
6309 <description> | |
6310 The field to watch | |
6311 | |
6312 </description> | |
6313 </param> | |
6314 </parameters> | |
6315 <errors> | |
6316 <error id="JVMTI_ERROR_DUPLICATE"> | |
6317 The designated field is already being watched for modifications. | |
6318 </error> | |
6319 </errors> | |
6320 </function> | |
6321 | |
6322 <function id="ClearFieldModificationWatch" num="44"> | |
6323 <synopsis>Clear Field Modification Watch</synopsis> | |
6324 <description> | |
6325 | |
6326 Cancel a field modification watch previously set by | |
6327 <functionlink id="SetFieldModificationWatch"></functionlink>, on the | |
6328 field specified | |
6329 by <code>klass</code> and | |
6330 <code>field</code>. | |
6331 </description> | |
6332 <origin>jvmdi</origin> | |
6333 <capabilities> | |
6334 <required id="can_generate_field_modification_events"></required> | |
6335 </capabilities> | |
6336 <parameters> | |
6337 <param id="klass"> | |
6338 <jclass field="field"/> | |
6339 <description> | |
6340 The class containing the field to watch | |
6341 </description> | |
6342 </param> | |
6343 <param id="field"> | |
6344 <jfieldID class="klass"/> | |
6345 <description> | |
6346 The field to watch | |
6347 | |
6348 </description> | |
6349 </param> | |
6350 </parameters> | |
6351 <errors> | |
6352 <error id="JVMTI_ERROR_NOT_FOUND"> | |
6353 The designated field is not being watched for modifications. | |
6354 </error> | |
6355 </errors> | |
6356 </function> | |
6357 </category> | |
6358 | |
6359 <category id="class" label="Class"> | |
6360 | |
6361 <intro> | |
6362 </intro> | |
6363 | |
6364 <function id="GetLoadedClasses" jkernel="yes" num="78"> | |
6365 <synopsis>Get Loaded Classes</synopsis> | |
6366 <description> | |
6367 Return an array of all classes loaded in the virtual machine. | |
6368 The number of classes in the array is returned via | |
6369 <code>class_count_ptr</code>, and the array itself via | |
6370 <code>classes_ptr</code>. | |
6371 <p/> | |
6372 Array classes of all types (including arrays of primitive types) are | |
6373 included in the returned list. Primitive classes (for example, | |
6374 <code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list. | |
6375 </description> | |
6376 <origin>jvmdi</origin> | |
6377 <capabilities> | |
6378 </capabilities> | |
6379 <parameters> | |
6380 <param id="class_count_ptr"> | |
6381 <outptr><jint/></outptr> | |
6382 <description> | |
6383 On return, points to the number of classes. | |
6384 </description> | |
6385 </param> | |
6386 <param id="classes_ptr"> | |
6387 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf> | |
6388 <description> | |
6389 On return, points to an array of references, one | |
6390 for each class. | |
6391 </description> | |
6392 </param> | |
6393 </parameters> | |
6394 <errors> | |
6395 </errors> | |
6396 </function> | |
6397 | |
6398 <function id="GetClassLoaderClasses" jkernel="yes" num="79"> | |
6399 <synopsis>Get Classloader Classes</synopsis> | |
6400 <description> | |
6401 Returns an array of those classes for which this class loader has | |
6402 been recorded as an initiating loader. Each | |
6403 class in the returned array was created by this class loader, | |
6404 either by defining it directly or by delegation to another class loader. | |
6405 See the | |
6406 <vmspeclink id="ConstantPool.doc.html#72007" | |
6407 name="Creation and Loading section"/>. | |
6408 <p/> | |
6409 For JDK version 1.1 implementations that don't | |
6410 recognize the distinction between initiating and defining class loaders, | |
6411 this function should return all classes loaded in the virtual machine. | |
6412 The number of classes in the array is returned via | |
6413 <code>class_count_ptr</code>, and the array itself via | |
6414 <code>classes_ptr</code>. | |
6415 </description> | |
6416 <origin>jvmdi</origin> | |
6417 <capabilities> | |
6418 </capabilities> | |
6419 <parameters> | |
6420 <param id="initiating_loader"> | |
6421 <ptrtype> | |
6422 <jobject/> | |
6423 <nullok>the classes initiated by the bootstrap loader will be returned</nullok> | |
6424 </ptrtype> | |
6425 <description> | |
6426 An initiating class loader. | |
6427 </description> | |
6428 </param> | |
6429 <param id="class_count_ptr"> | |
6430 <outptr><jint/></outptr> | |
6431 <description> | |
6432 On return, points to the number of classes. | |
6433 </description> | |
6434 </param> | |
6435 <param id="classes_ptr"> | |
6436 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf> | |
6437 <description> | |
6438 On return, points to an array of references, one | |
6439 for each class. | |
6440 </description> | |
6441 </param> | |
6442 </parameters> | |
6443 <errors> | |
6444 </errors> | |
6445 </function> | |
6446 | |
6447 <function id="GetClassSignature" phase="start" num="48"> | |
6448 <synopsis>Get Class Signature</synopsis> | |
6449 <description> | |
6450 For the class indicated by <code>klass</code>, return the | |
6451 <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/types.html#wp16432">JNI | |
6452 type signature</externallink> | |
6453 and the generic signature of the class. | |
6454 For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code> | |
6455 and <code>int[]</code> is <code>"[I"</code> | |
6456 The returned name for primitive classes | |
6457 is the type signature character of the corresponding primitive type. | |
6458 For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>. | |
6459 </description> | |
6460 <origin>jvmdiClone</origin> | |
6461 <capabilities> | |
6462 </capabilities> | |
6463 <parameters> | |
6464 <param id="klass"> | |
6465 <jclass/> | |
6466 <description> | |
6467 The class to query. | |
6468 </description> | |
6469 </param> | |
6470 <param id="signature_ptr"> | |
6471 <allocbuf> | |
6472 <char/> | |
6473 <nullok>the signature is not returned</nullok> | |
6474 </allocbuf> | |
6475 <description> | |
6476 On return, points to the JNI type signature of the class, encoded as a | |
6477 <internallink id="mUTF">modified UTF-8</internallink> string. | |
6478 </description> | |
6479 </param> | |
6480 <param id="generic_ptr"> | |
6481 <allocbuf> | |
6482 <char/> | |
6483 <nullok>the generic signature is not returned</nullok> | |
6484 </allocbuf> | |
6485 <description> | |
6486 On return, points to the generic signature of the class, encoded as a | |
6487 <internallink id="mUTF">modified UTF-8</internallink> string. | |
6488 If there is no generic signature attribute for the class, then, | |
6489 on return, points to <code>NULL</code>. | |
6490 </description> | |
6491 </param> | |
6492 </parameters> | |
6493 <errors> | |
6494 </errors> | |
6495 </function> | |
6496 | |
6497 <function id="GetClassStatus" phase="start" num="49"> | |
6498 <synopsis>Get Class Status</synopsis> | |
6499 <description> | |
6500 Get the status of the class. Zero or more of the following bits can be | |
6501 set. | |
6502 <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits"> | |
6503 <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1"> | |
6504 Class bytecodes have been verified | |
6505 </constant> | |
6506 <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2"> | |
6507 Class preparation is complete | |
6508 </constant> | |
6509 <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4"> | |
6510 Class initialization is complete. Static initializer has been run. | |
6511 </constant> | |
6512 <constant id="JVMTI_CLASS_STATUS_ERROR" num="8"> | |
6513 Error during initialization makes class unusable | |
6514 </constant> | |
6515 <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16"> | |
6516 Class is an array. If set, all other bits are zero. | |
6517 </constant> | |
6518 <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32"> | |
6519 Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>). | |
6520 If set, all other bits are zero. | |
6521 </constant> | |
6522 </constants> | |
6523 </description> | |
6524 <origin>jvmdi</origin> | |
6525 <capabilities> | |
6526 </capabilities> | |
6527 <parameters> | |
6528 <param id="klass"> | |
6529 <jclass/> | |
6530 <description> | |
6531 The class to query. | |
6532 </description> | |
6533 </param> | |
6534 <param id="status_ptr"> | |
6535 <outptr><jint/></outptr> | |
6536 <description> | |
6537 On return, points to the current state of this class as one or | |
6538 more of the <internallink id="jvmtiClassStatus">class status flags</internallink>. | |
6539 </description> | |
6540 </param> | |
6541 </parameters> | |
6542 <errors> | |
6543 </errors> | |
6544 </function> | |
6545 | |
6546 <function id="GetSourceFileName" phase="start" num="50"> | |
6547 <synopsis>Get Source File Name</synopsis> | |
6548 <description> | |
6549 For the class indicated by <code>klass</code>, return the source file | |
6550 name via <code>source_name_ptr</code>. The returned string | |
6551 is a file name only and never contains a directory name. | |
6552 <p/> | |
6553 For primitive classes (for example, <code>java.lang.Integer.TYPE</code>) | |
6554 and for arrays this function returns | |
6555 <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>. | |
6556 </description> | |
6557 <origin>jvmdi</origin> | |
6558 <capabilities> | |
6559 <required id="can_get_source_file_name"></required> | |
6560 </capabilities> | |
6561 <parameters> | |
6562 <param id="klass"> | |
6563 <jclass/> | |
6564 <description> | |
6565 The class to query. | |
6566 </description> | |
6567 </param> | |
6568 <param id="source_name_ptr"> | |
6569 <allocbuf><char/></allocbuf> | |
6570 <description> | |
6571 On return, points to the class's source file name, encoded as a | |
6572 <internallink id="mUTF">modified UTF-8</internallink> string. | |
6573 </description> | |
6574 </param> | |
6575 </parameters> | |
6576 <errors> | |
6577 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
6578 Class information does not include a source file name. This includes | |
6579 cases where the class is an array class or primitive class. | |
6580 </error> | |
6581 </errors> | |
6582 </function> | |
6583 | |
6584 <function id="GetClassModifiers" phase="start" num="51"> | |
6585 <synopsis>Get Class Modifiers</synopsis> | |
6586 <description> | |
6587 For the class indicated by <code>klass</code>, return the access | |
6588 flags | |
6589 via <code>modifiers_ptr</code>. | |
6590 Access flags are defined in the | |
6591 <vmspeclink id="ClassFile.doc.html" | |
6592 name="Class File Format chapter"/>. | |
6593 <p/> | |
6594 If the class is an array class, then its public, private, and protected | |
6595 modifiers are the same as those of its component type. For arrays of | |
6596 primitives, this component type is represented by one of the primitive | |
6597 classes (for example, <code>java.lang.Integer.TYPE</code>). | |
6598 <p/> | |
6599 If the class is a primitive class, its public modifier is always true, | |
6600 and its protected and private modifiers are always false. | |
6601 <p/> | |
6602 If the class is an array class or a primitive class then its final | |
6603 modifier is always true and its interface modifier is always false. | |
6604 The values of its other modifiers are not determined by this specification. | |
6605 | |
6606 </description> | |
6607 <origin>jvmdi</origin> | |
6608 <capabilities> | |
6609 </capabilities> | |
6610 <parameters> | |
6611 <param id="klass"> | |
6612 <jclass/> | |
6613 <description> | |
6614 The class to query. | |
6615 </description> | |
6616 </param> | |
6617 <param id="modifiers_ptr"> | |
6618 <outptr><jint/></outptr> | |
6619 <description> | |
6620 On return, points to the current access flags of this class. | |
6621 | |
6622 </description> | |
6623 </param> | |
6624 </parameters> | |
6625 <errors> | |
6626 </errors> | |
6627 </function> | |
6628 | |
6629 <function id="GetClassMethods" phase="start" num="52"> | |
6630 <synopsis>Get Class Methods</synopsis> | |
6631 <description> | |
6632 For the class indicated by <code>klass</code>, return a count of | |
6633 methods via <code>method_count_ptr</code> and a list of | |
6634 method IDs via <code>methods_ptr</code>. The method list contains | |
6635 constructors and static initializers as well as true methods. | |
6636 Only directly declared methods are returned (not inherited methods). | |
6637 An empty method list is returned for array classes and primitive classes | |
6638 (for example, <code>java.lang.Integer.TYPE</code>). | |
6639 </description> | |
6640 <origin>jvmdi</origin> | |
6641 <capabilities> | |
6642 <capability id="can_maintain_original_method_order"/> | |
6643 </capabilities> | |
6644 <parameters> | |
6645 <param id="klass"> | |
6646 <jclass/> | |
6647 <description> | |
6648 The class to query. | |
6649 </description> | |
6650 </param> | |
6651 <param id="method_count_ptr"> | |
6652 <outptr><jint/></outptr> | |
6653 <description> | |
6654 On return, points to the number of methods declared in this class. | |
6655 </description> | |
6656 </param> | |
6657 <param id="methods_ptr"> | |
6658 <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf> | |
6659 <description> | |
6660 On return, points to the method ID array. | |
6661 </description> | |
6662 </param> | |
6663 </parameters> | |
6664 <errors> | |
6665 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
6666 <paramlink id="klass"></paramlink> is not prepared. | |
6667 </error> | |
6668 </errors> | |
6669 </function> | |
6670 | |
6671 <function id="GetClassFields" phase="start" num="53"> | |
6672 <synopsis>Get Class Fields</synopsis> | |
6673 <description> | |
6674 For the class indicated by <code>klass</code>, return a count of fields | |
6675 via <code>field_count_ptr</code> and a list of field IDs via | |
6676 <code>fields_ptr</code>. | |
6677 Only directly declared fields are returned (not inherited fields). | |
6678 Fields are returned in the order they occur in the class file. | |
6679 An empty field list is returned for array classes and primitive classes | |
6680 (for example, <code>java.lang.Integer.TYPE</code>). | |
6681 Use JNI to determine the length of an array. | |
6682 </description> | |
6683 <origin>jvmdi</origin> | |
6684 <capabilities> | |
6685 </capabilities> | |
6686 <parameters> | |
6687 <param id="klass"> | |
6688 <jclass/> | |
6689 <description> | |
6690 The class to query. | |
6691 </description> | |
6692 </param> | |
6693 <param id="field_count_ptr"> | |
6694 <outptr><jint/></outptr> | |
6695 <description> | |
6696 On return, points to the number of fields declared in this class. | |
6697 </description> | |
6698 </param> | |
6699 <param id="fields_ptr"> | |
6700 <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf> | |
6701 <description> | |
6702 On return, points to the field ID array. | |
6703 </description> | |
6704 </param> | |
6705 </parameters> | |
6706 <errors> | |
6707 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
6708 <paramlink id="klass"></paramlink> is not prepared. | |
6709 </error> | |
6710 </errors> | |
6711 </function> | |
6712 | |
6713 <function id="GetImplementedInterfaces" phase="start" num="54"> | |
6714 <synopsis>Get Implemented Interfaces</synopsis> | |
6715 <description> | |
6716 Return the direct super-interfaces of this class. For a class, this | |
6717 function returns the interfaces declared in its <code>implements</code> | |
6718 clause. For an interface, this function returns the interfaces declared in | |
6719 its <code>extends</code> clause. | |
6720 An empty interface list is returned for array classes and primitive classes | |
6721 (for example, <code>java.lang.Integer.TYPE</code>). | |
6722 </description> | |
6723 <origin>jvmdi</origin> | |
6724 <capabilities> | |
6725 </capabilities> | |
6726 <parameters> | |
6727 <param id="klass"> | |
6728 <jclass/> | |
6729 <description> | |
6730 The class to query. | |
6731 </description> | |
6732 </param> | |
6733 <param id="interface_count_ptr"> | |
6734 <outptr><jint/></outptr> | |
6735 <description> | |
6736 On return, points to the number of interfaces. | |
6737 </description> | |
6738 </param> | |
6739 <param id="interfaces_ptr"> | |
6740 <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf> | |
6741 <description> | |
6742 On return, points to the interface array. | |
6743 </description> | |
6744 </param> | |
6745 </parameters> | |
6746 <errors> | |
6747 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> | |
6748 <paramlink id="klass"></paramlink> is not prepared. | |
6749 </error> | |
6750 </errors> | |
6751 </function> | |
6752 | |
6753 <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1"> | |
6754 <synopsis>Get Class Version Numbers</synopsis> | |
6755 <description> | |
6756 For the class indicated by <code>klass</code>, | |
6757 return the minor and major version numbers, | |
6758 as defined in the | |
6759 <vmspeclink id="ClassFile.doc.html" | |
6760 name="Class File Format chapter"/>. | |
6761 </description> | |
6762 <origin>new</origin> | |
6763 <capabilities> | |
6764 </capabilities> | |
6765 <parameters> | |
6766 <param id="klass"> | |
6767 <jclass/> | |
6768 <description> | |
6769 The class to query. | |
6770 </description> | |
6771 </param> | |
6772 <param id="minor_version_ptr"> | |
6773 <outptr><jint/></outptr> | |
6774 <description> | |
6775 On return, points to the value of the | |
6776 <code>minor_version</code> item of the | |
6777 Class File Format. | |
6778 Note: to be consistent with the Class File Format, | |
6779 the minor version number is the first parameter. | |
6780 </description> | |
6781 </param> | |
6782 <param id="major_version_ptr"> | |
6783 <outptr><jint/></outptr> | |
6784 <description> | |
6785 On return, points to the value of the | |
6786 <code>major_version</code> item of the | |
6787 Class File Format. | |
6788 </description> | |
6789 </param> | |
6790 </parameters> | |
6791 <errors> | |
6792 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
6793 The class is a primitive or array class. | |
6794 </error> | |
6795 </errors> | |
6796 </function> | |
6797 | |
6798 <function id="GetConstantPool" phase="start" num="146" since="1.1"> | |
6799 <synopsis>Get Constant Pool</synopsis> | |
6800 <description> | |
6801 For the class indicated by <code>klass</code>, | |
6802 return the raw bytes of the constant pool in the format of the | |
6803 <code>constant_pool</code> item of the | |
6804 <vmspeclink id="ClassFile.doc.html" | |
6805 name="Class File Format" | |
6806 preposition="in"/>. | |
6807 The format of the constant pool may differ between versions | |
6808 of the Class File Format, so, the | |
6809 <functionlink id="GetClassVersionNumbers">minor and major | |
6810 class version numbers</functionlink> should be checked for | |
6811 compatibility. | |
6812 <p/> | |
6813 The returned constant pool might not have the same layout or | |
6814 contents as the constant pool in the defining class file. | |
6815 The constant pool returned by GetConstantPool() may have | |
6816 more or fewer entries than the defining constant pool. | |
6817 Entries may be in a different order. | |
6818 The constant pool returned by GetConstantPool() will match the | |
6819 constant pool used by | |
6820 <functionlink id="GetBytecodes">GetBytecodes()</functionlink>. | |
6821 That is, the bytecodes returned by GetBytecodes() will have | |
6822 constant pool indices which refer to constant pool entries returned | |
6823 by GetConstantPool(). | |
6824 Note that since <functionlink id="RetransformClasses"/> | |
6825 and <functionlink id="RedefineClasses"/> can change | |
6826 the constant pool, the constant pool returned by this function | |
6827 can change accordingly. Thus, the correspondence between | |
6828 GetConstantPool() and GetBytecodes() does not hold if there | |
6829 is an intervening class retransformation or redefinition. | |
6830 The value of a constant pool entry used by a given bytecode will | |
6831 match that of the defining class file (even if the indices don't match). | |
6832 Constant pool entries which are not used directly or indirectly by | |
6833 bytecodes (for example, UTF-8 strings associated with annotations) are | |
6834 not required to exist in the returned constant pool. | |
6835 </description> | |
6836 <origin>new</origin> | |
6837 <capabilities> | |
6838 <required id="can_get_constant_pool"></required> | |
6839 </capabilities> | |
6840 <parameters> | |
6841 <param id="klass"> | |
6842 <jclass/> | |
6843 <description> | |
6844 The class to query. | |
6845 </description> | |
6846 </param> | |
6847 <param id="constant_pool_count_ptr"> | |
6848 <outptr><jint/></outptr> | |
6849 <description> | |
6850 On return, points to the number of entries | |
6851 in the constant pool table plus one. | |
6852 This corresponds to the <code>constant_pool_count</code> | |
6853 item of the Class File Format. | |
6854 </description> | |
6855 </param> | |
6856 <param id="constant_pool_byte_count_ptr"> | |
6857 <outptr><jint/></outptr> | |
6858 <description> | |
6859 On return, points to the number of bytes | |
6860 in the returned raw constant pool. | |
6861 </description> | |
6862 </param> | |
6863 <param id="constant_pool_bytes_ptr"> | |
6864 <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf> | |
6865 <description> | |
6866 On return, points to the raw constant pool, that is the bytes | |
6867 defined by the <code>constant_pool</code> item of the | |
6868 Class File Format | |
6869 </description> | |
6870 </param> | |
6871 </parameters> | |
6872 <errors> | |
6873 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
6874 The class is a primitive or array class. | |
6875 </error> | |
6876 </errors> | |
6877 </function> | |
6878 | |
6879 <function id="IsInterface" phase="start" num="55"> | |
6880 <synopsis>Is Interface</synopsis> | |
6881 <description> | |
6882 Determines whether a class object reference represents an interface. | |
6883 The <code>jboolean</code> result is | |
6884 <code>JNI_TRUE</code> if the "class" is actually an interface, | |
6885 <code>JNI_FALSE</code> otherwise. | |
6886 </description> | |
6887 <origin>jvmdi</origin> | |
6888 <capabilities> | |
6889 </capabilities> | |
6890 <parameters> | |
6891 <param id="klass"> | |
6892 <jclass/> | |
6893 <description> | |
6894 The class to query. | |
6895 </description> | |
6896 </param> | |
6897 <param id="is_interface_ptr"> | |
6898 <outptr><jboolean/></outptr> | |
6899 <description> | |
6900 On return, points to the boolean result of this function. | |
6901 | |
6902 </description> | |
6903 </param> | |
6904 </parameters> | |
6905 <errors> | |
6906 </errors> | |
6907 </function> | |
6908 | |
6909 <function id="IsArrayClass" phase="start" num="56"> | |
6910 <synopsis>Is Array Class</synopsis> | |
6911 <description> | |
6912 Determines whether a class object reference represents an array. | |
6913 The <code>jboolean</code> result is | |
6914 <code>JNI_TRUE</code> if the class is an array, | |
6915 <code>JNI_FALSE</code> otherwise. | |
6916 </description> | |
6917 <origin>jvmdi</origin> | |
6918 <capabilities> | |
6919 </capabilities> | |
6920 <parameters> | |
6921 <param id="klass"> | |
6922 <jclass/> | |
6923 <description> | |
6924 The class to query. | |
6925 </description> | |
6926 </param> | |
6927 <param id="is_array_class_ptr"> | |
6928 <outptr><jboolean/></outptr> | |
6929 <description> | |
6930 On return, points to the boolean result of this function. | |
6931 | |
6932 </description> | |
6933 </param> | |
6934 </parameters> | |
6935 <errors> | |
6936 </errors> | |
6937 </function> | |
6938 | |
6939 <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1"> | |
6940 <synopsis>Is Modifiable Class</synopsis> | |
6941 <description> | |
6942 Determines whether a class is modifiable. | |
6943 If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/> | |
6944 returns <code>JNI_TRUE</code>) the class can be | |
6945 redefined with <functionlink id="RedefineClasses"/> (assuming | |
6946 the agent possesses the | |
6947 <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/> | |
6948 capability) or | |
6949 retransformed with <functionlink id="RetransformClasses"/> (assuming | |
6950 the agent possesses the | |
6951 <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> | |
6952 capability). | |
6953 If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/> | |
6954 returns <code>JNI_FALSE</code>) the class can be neither | |
6955 redefined nor retransformed. | |
6956 <p/> | |
6957 Primitive classes (for example, <code>java.lang.Integer.TYPE</code>) | |
6958 and array classes are never modifiable. | |
6959 <p/> | |
6960 </description> | |
6961 <origin>new</origin> | |
6962 <capabilities> | |
6963 <capability id="can_redefine_any_class"> | |
6964 If possessed then all classes (except primitive and array classes) | |
6965 are modifiable. | |
6966 </capability> | |
6967 <capability id="can_redefine_classes"> | |
6968 No effect on the result of the function. | |
6969 But must additionally be possessed to modify the class with | |
6970 <functionlink id="RedefineClasses"/>. | |
6971 </capability> | |
6972 <capability id="can_retransform_classes"> | |
6973 No effect on the result of the function. | |
6974 But must additionally be possessed to modify the class with | |
6975 <functionlink id="RetransformClasses"/>. | |
6976 </capability> | |
6977 </capabilities> | |
6978 <parameters> | |
6979 <param id="klass"> | |
6980 <jclass/> | |
6981 <description> | |
6982 The class to query. | |
6983 </description> | |
6984 </param> | |
6985 <param id="is_modifiable_class_ptr"> | |
6986 <outptr><jboolean/></outptr> | |
6987 <description> | |
6988 On return, points to the boolean result of this function. | |
6989 </description> | |
6990 </param> | |
6991 </parameters> | |
6992 <errors> | |
6993 </errors> | |
6994 </function> | |
6995 | |
6996 <function id="GetClassLoader" phase="start" num="57"> | |
6997 <synopsis>Get Class Loader</synopsis> | |
6998 <description> | |
6999 For the class indicated by <code>klass</code>, return via | |
7000 <code>classloader_ptr</code> a reference to the class loader for the | |
7001 class. | |
7002 </description> | |
7003 <origin>jvmdi</origin> | |
7004 <capabilities> | |
7005 </capabilities> | |
7006 <parameters> | |
7007 <param id="klass"> | |
7008 <jclass/> | |
7009 <description> | |
7010 The class to query. | |
7011 </description> | |
7012 </param> | |
7013 <param id="classloader_ptr"> | |
7014 <outptr><jobject/></outptr> | |
7015 <description> | |
7016 On return, points to the class loader that loaded | |
7017 this class. | |
7018 If the class was not created by a class loader | |
7019 or if the class loader is the bootstrap class loader, | |
7020 points to <code>NULL</code>. | |
7021 </description> | |
7022 </param> | |
7023 </parameters> | |
7024 <errors> | |
7025 </errors> | |
7026 | |
7027 </function> | |
7028 | |
7029 <function id="GetSourceDebugExtension" phase="start" num="90"> | |
7030 <synopsis>Get Source Debug Extension</synopsis> | |
7031 <description> | |
7032 For the class indicated by <code>klass</code>, return the debug | |
7033 extension via <code>source_debug_extension_ptr</code>. | |
7034 The returned string | |
7035 contains exactly the debug extension information present in the | |
7036 class file of <code>klass</code>. | |
7037 </description> | |
7038 <origin>jvmdi</origin> | |
7039 <capabilities> | |
7040 <required id="can_get_source_debug_extension"></required> | |
7041 </capabilities> | |
7042 <parameters> | |
7043 <param id="klass"> | |
7044 <jclass/> | |
7045 <description> | |
7046 The class to query. | |
7047 </description> | |
7048 </param> | |
7049 <param id="source_debug_extension_ptr"> | |
7050 <allocbuf><char/></allocbuf> | |
7051 <description> | |
7052 On return, points to the class's debug extension, encoded as a | |
7053 <internallink id="mUTF">modified UTF-8</internallink> string. | |
7054 </description> | |
7055 </param> | |
7056 </parameters> | |
7057 <errors> | |
7058 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
7059 Class information does not include a debug extension. | |
7060 </error> | |
7061 </errors> | |
7062 </function> | |
7063 | |
7064 <function id="RetransformClasses" jkernel="yes" num="152" since="1.1"> | |
7065 <synopsis>Retransform Classes</synopsis> | |
7066 <description> | |
7067 This function facilitates the | |
7068 <internallink id="bci">bytecode instrumentation</internallink> | |
7069 of already loaded classes. | |
7070 To replace the class definition without reference to the existing | |
7071 bytecodes, as one might do when recompiling from source for | |
7072 fix-and-continue debugging, <functionlink id="RedefineClasses"/> | |
7073 function should be used instead. | |
7074 <p/> | |
7075 When classes are initially loaded or when they are | |
7076 <functionlink id="RedefineClasses">redefined</functionlink>, | |
7077 the initial class file bytes can be transformed with the | |
7078 <eventlink id="ClassFileLoadHook"/> event. | |
7079 This function reruns the transformation process | |
7080 (whether or not a transformation has previously occurred). | |
7081 This retransformation follows these steps: | |
7082 <ul> | |
7083 <li>starting from the initial class file bytes | |
7084 </li> | |
7085 <li>for each <fieldlink id="can_retransform_classes" | |
7086 struct="jvmtiCapabilities">retransformation | |
7087 incapable</fieldlink> | |
7088 agent which received a | |
7089 <code>ClassFileLoadHook</code> event during the previous | |
7090 load or redefine, the bytes it returned | |
7091 (via the <code>new_class_data</code> parameter) | |
7092 are reused as the output of the transformation; | |
7093 note that this is equivalent to reapplying | |
7094 the previous transformation, unaltered. except that | |
7095 the <code>ClassFileLoadHook</code> event | |
7096 is <b>not</b> sent to these agents | |
7097 </li> | |
7098 <li>for each <fieldlink id="can_retransform_classes" | |
7099 struct="jvmtiCapabilities">retransformation | |
7100 capable</fieldlink> | |
7101 agent, the <code>ClassFileLoadHook</code> event is sent, | |
7102 allowing a new transformation to be applied | |
7103 </li> | |
7104 <li>the transformed class file bytes are installed as the new | |
7105 definition of the class | |
7106 </li> | |
7107 </ul> | |
7108 See the <eventlink id="ClassFileLoadHook"/> event for more details. | |
7109 <p/> | |
7110 The initial class file bytes represent the bytes passed to | |
7111 <code>ClassLoader.defineClass</code> | |
7112 or <code>RedefineClasses</code> (before any transformations | |
7113 were applied), however they may not exactly match them. | |
7114 The constant pool may differ in ways described in | |
7115 <functionlink id="GetConstantPool"/>. | |
7116 Constant pool indices in the bytecodes of methods will correspond. | |
7117 Some attributes may not be present. | |
7118 Where order is not meaningful, for example the order of methods, | |
7119 order may not be preserved. | |
7120 <p/> | |
7121 Retransformation can cause new versions of methods to be installed. | |
7122 Old method versions may become | |
7123 <internallink id="obsoleteMethods">obsolete</internallink> | |
7124 The new method version will be used on new invokes. | |
7125 If a method has active stack frames, those active frames continue to | |
7126 run the bytecodes of the original method version. | |
7127 <p/> | |
7128 This function does not cause any initialization except that which | |
7129 would occur under the customary JVM semantics. | |
7130 In other words, retransforming a class does not cause its initializers to be | |
7131 run. The values of static fields will remain as they were | |
7132 prior to the call. | |
7133 <p/> | |
7134 Threads need not be suspended. | |
7135 <p/> | |
7136 All breakpoints in the class are cleared. | |
7137 <p/> | |
7138 All attributes are updated. | |
7139 <p/> | |
7140 Instances of the retransformed class are not affected -- fields retain their | |
7141 previous values. | |
7142 <functionlink id="GetTag">Tags</functionlink> on the instances are | |
7143 also unaffected. | |
7144 <p/> | |
7145 In response to this call, no events other than the | |
7146 <eventlink id="ClassFileLoadHook"/> event | |
7147 will be sent. | |
7148 <p/> | |
7149 The retransformation may change method bodies, the constant pool and attributes. | |
7150 The retransformation must not add, remove or rename fields or methods, change the | |
7151 signatures of methods, change modifiers, or change inheritance. | |
7152 These restrictions may be lifted in future versions. | |
7153 See the error return description below for information on error codes | |
7154 returned if an unsupported retransformation is attempted. | |
7155 The class file bytes are not verified or installed until they have passed | |
7156 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the | |
7157 returned error code reflects the result of the transformations. | |
7158 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, | |
7159 none of the classes to be retransformed will have a new definition installed. | |
7160 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) | |
7161 all of the classes to be retransformed will have their new definitions installed. | |
7162 </description> | |
7163 <origin>new</origin> | |
7164 <capabilities> | |
7165 <required id="can_retransform_classes"></required> | |
7166 <capability id="can_retransform_any_class"></capability> | |
7167 </capabilities> | |
7168 <parameters> | |
7169 <param id="class_count"> | |
7170 <jint min="0"/> | |
7171 <description> | |
7172 The number of classes to be retransformed. | |
7173 </description> | |
7174 </param> | |
7175 <param id="classes"> | |
7176 <inbuf incount="class_count"><jclass/></inbuf> | |
7177 <description> | |
7178 The array of classes to be retransformed. | |
7179 </description> | |
7180 </param> | |
7181 </parameters> | |
7182 <errors> | |
7183 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> | |
7184 One of the <paramlink id="classes"/> cannot be modified. | |
7185 See <functionlink id="IsModifiableClass"/>. | |
7186 </error> | |
7187 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
7188 One of the <paramlink id="classes"/> is not a valid class. | |
7189 </error> | |
7190 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> | |
7191 A retransformed class file has a version number not supported by this VM. | |
7192 </error> | |
7193 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> | |
7194 A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>). | |
7195 </error> | |
7196 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> | |
7197 The retransformed class file definitions would lead to a circular definition | |
7198 (the VM would return a <code>ClassCircularityError</code>). | |
7199 </error> | |
7200 <error id="JVMTI_ERROR_FAILS_VERIFICATION"> | |
7201 The retransformed class file bytes fail verification. | |
7202 </error> | |
7203 <error id="JVMTI_ERROR_NAMES_DONT_MATCH"> | |
7204 The class name defined in a retransformed class file is | |
7205 different from the name in the old class object. | |
7206 </error> | |
7207 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> | |
7208 A retransformed class file would require adding a method. | |
7209 </error> | |
7210 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> | |
7211 A retransformed class file changes a field. | |
7212 </error> | |
7213 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> | |
7214 A direct superclass is different for a retransformed class file, | |
7215 or the set of directly implemented | |
7216 interfaces is different. | |
7217 </error> | |
7218 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> | |
7219 A retransformed class file does not declare a method | |
7220 declared in the old class version. | |
7221 </error> | |
7222 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> | |
7223 A retransformed class file has different class modifiers. | |
7224 </error> | |
7225 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> | |
7226 A method in the retransformed class file has different modifiers | |
7227 than its counterpart in the old class version. | |
7228 </error> | |
7229 </errors> | |
7230 </function> | |
7231 | |
7232 <function id="RedefineClasses" jkernel="yes" num="87"> | |
7233 <synopsis>Redefine Classes</synopsis> | |
7234 <typedef id="jvmtiClassDefinition" label="Class redefinition description"> | |
7235 <field id="klass"> | |
7236 <jclass/> | |
7237 <description> | |
7238 Class object for this class | |
7239 </description> | |
7240 </field> | |
7241 <field id="class_byte_count"> | |
7242 <jint/> | |
7243 <description> | |
7244 Number of bytes defining class (below) | |
7245 </description> | |
7246 </field> | |
7247 <field id="class_bytes"> | |
7248 <inbuf incount="class_byte_count"><uchar/></inbuf> | |
7249 <description> | |
7250 Bytes defining class (in the | |
7251 <vmspeclink id="ClassFile.doc.html" | |
7252 name="Class File Format"/>) | |
7253 </description> | |
7254 </field> | |
7255 </typedef> | |
7256 <description> | |
7257 All classes given are redefined according to the definitions | |
7258 supplied. | |
7259 This function is used to replace the definition of a class | |
7260 with a new definition, as might be needed in fix-and-continue | |
7261 debugging. | |
7262 Where the existing class file bytes are to be transformed, for | |
7263 example in | |
7264 <internallink id="bci">bytecode instrumentation</internallink>, | |
7265 <functionlink id="RetransformClasses"/> should be used. | |
7266 <p/> | |
7267 Redefinition can cause new versions of methods to be installed. | |
7268 Old method versions may become | |
7269 <internallink id="obsoleteMethods">obsolete</internallink> | |
7270 The new method version will be used on new invokes. | |
7271 If a method has active stack frames, those active frames continue to | |
7272 run the bytecodes of the original method version. | |
7273 If resetting of stack frames is desired, use | |
7274 <functionlink id="PopFrame"></functionlink> | |
7275 to pop frames with obsolete method versions. | |
7276 <p/> | |
7277 This function does not cause any initialization except that which | |
7278 would occur under the customary JVM semantics. | |
7279 In other words, redefining a class does not cause its initializers to be | |
7280 run. The values of static fields will remain as they were | |
7281 prior to the call. | |
7282 <p/> | |
7283 Threads need not be suspended. | |
7284 <p/> | |
7285 All breakpoints in the class are cleared. | |
7286 <p/> | |
7287 All attributes are updated. | |
7288 <p/> | |
7289 Instances of the redefined class are not affected -- fields retain their | |
7290 previous values. | |
7291 <functionlink id="GetTag">Tags</functionlink> on the instances are | |
7292 also unaffected. | |
7293 <p/> | |
7294 In response to this call, the <jvmti/> event | |
7295 <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink> | |
7296 will be sent (if enabled), but no other <jvmti/> events will be sent. | |
7297 <p/> | |
7298 The redefinition may change method bodies, the constant pool and attributes. | |
7299 The redefinition must not add, remove or rename fields or methods, change the | |
7300 signatures of methods, change modifiers, or change inheritance. | |
7301 These restrictions may be lifted in future versions. | |
7302 See the error return description below for information on error codes | |
7303 returned if an unsupported redefinition is attempted. | |
7304 The class file bytes are not verified or installed until they have passed | |
7305 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the | |
7306 returned error code reflects the result of the transformations applied | |
7307 to the bytes passed into <paramlink id="class_definitions"/>. | |
7308 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, | |
7309 none of the classes to be redefined will have a new definition installed. | |
7310 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) | |
7311 all of the classes to be redefined will have their new definitions installed. | |
7312 </description> | |
7313 <origin>jvmdi</origin> | |
7314 <capabilities> | |
7315 <required id="can_redefine_classes"></required> | |
7316 <capability id="can_redefine_any_class"></capability> | |
7317 </capabilities> | |
7318 <parameters> | |
7319 <param id="class_count"> | |
7320 <jint min="0"/> | |
7321 <description> | |
7322 The number of classes specified in <code>class_definitions</code> | |
7323 </description> | |
7324 </param> | |
7325 <param id="class_definitions"> | |
7326 <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf> | |
7327 <description> | |
7328 The array of new class definitions | |
7329 </description> | |
7330 </param> | |
7331 </parameters> | |
7332 <errors> | |
7333 <error id="JVMTI_ERROR_NULL_POINTER"> | |
7334 One of <code>class_bytes</code> is <code>NULL</code>. | |
7335 </error> | |
7336 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> | |
7337 An element of <code>class_definitions</code> cannot be modified. | |
7338 See <functionlink id="IsModifiableClass"/>. | |
7339 </error> | |
7340 <error id="JVMTI_ERROR_INVALID_CLASS"> | |
7341 An element of <code>class_definitions</code> is not a valid class. | |
7342 </error> | |
7343 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> | |
7344 A new class file has a version number not supported by this VM. | |
7345 </error> | |
7346 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> | |
7347 A new class file is malformed (The VM would return a <code>ClassFormatError</code>). | |
7348 </error> | |
7349 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> | |
7350 The new class file definitions would lead to a circular definition | |
7351 (the VM would return a <code>ClassCircularityError</code>). | |
7352 </error> | |
7353 <error id="JVMTI_ERROR_FAILS_VERIFICATION"> | |
7354 The class bytes fail verification. | |
7355 </error> | |
7356 <error id="JVMTI_ERROR_NAMES_DONT_MATCH"> | |
7357 The class name defined in a new class file is | |
7358 different from the name in the old class object. | |
7359 </error> | |
7360 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> | |
7361 A new class file would require adding a method. | |
7362 </error> | |
7363 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> | |
7364 A new class version changes a field. | |
7365 </error> | |
7366 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> | |
7367 A direct superclass is different for a new class | |
7368 version, or the set of directly implemented | |
7369 interfaces is different. | |
7370 </error> | |
7371 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> | |
7372 A new class version does not declare a method | |
7373 declared in the old class version. | |
7374 </error> | |
7375 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> | |
7376 A new class version has different modifiers. | |
7377 </error> | |
7378 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> | |
7379 A method in the new class version has different modifiers | |
7380 than its counterpart in the old class version. | |
7381 </error> | |
7382 </errors> | |
7383 </function> | |
7384 | |
7385 </category> | |
7386 | |
7387 <category id="object" label="Object"> | |
7388 | |
7389 <function id="GetObjectSize" jkernel="yes" phase="start" num="154"> | |
7390 <synopsis>Get Object Size</synopsis> | |
7391 <description> | |
7392 For the object indicated by <code>object</code>, | |
7393 return via <code>size_ptr</code> the size of the object. | |
7394 This size is an implementation-specific approximation of | |
7395 the amount of storage consumed by this object. | |
7396 It may include some or all of the object's overhead, and thus | |
7397 is useful for comparison within an implementation but not | |
7398 between implementations. | |
7399 The estimate may change during a single invocation of the JVM. | |
7400 </description> | |
7401 <origin>new</origin> | |
7402 <capabilities> | |
7403 </capabilities> | |
7404 <parameters> | |
7405 <param id="object"> | |
7406 <jobject/> | |
7407 <description> | |
7408 The object to query. | |
7409 </description> | |
7410 </param> | |
7411 <param id="size_ptr"> | |
7412 <outptr><jlong/></outptr> | |
7413 <description> | |
7414 On return, points to the object's size in bytes. | |
7415 </description> | |
7416 </param> | |
7417 </parameters> | |
7418 <errors> | |
7419 </errors> | |
7420 </function> | |
7421 | |
7422 <function id="GetObjectHashCode" phase="start" num="58"> | |
7423 <synopsis>Get Object Hash Code</synopsis> | |
7424 <description> | |
7425 For the object indicated by <code>object</code>, | |
7426 return via <code>hash_code_ptr</code> a hash code. | |
7427 This hash code could be used to maintain a hash table of object references, | |
7428 however, on some implementations this can cause significant performance | |
7429 impacts--in most cases | |
7430 <internallink id="Heap">tags</internallink> | |
7431 will be a more efficient means of associating information with objects. | |
7432 This function guarantees | |
7433 the same hash code value for a particular object throughout its life | |
7434 </description> | |
7435 <origin>jvmdi</origin> | |
7436 <capabilities> | |
7437 </capabilities> | |
7438 <parameters> | |
7439 <param id="object"> | |
7440 <jobject/> | |
7441 <description> | |
7442 The object to query. | |
7443 </description> | |
7444 </param> | |
7445 <param id="hash_code_ptr"> | |
7446 <outptr><jint/></outptr> | |
7447 <description> | |
7448 On return, points to the object's hash code. | |
7449 </description> | |
7450 </param> | |
7451 </parameters> | |
7452 <errors> | |
7453 </errors> | |
7454 </function> | |
7455 | |
7456 <function id="GetObjectMonitorUsage" num="59"> | |
7457 <synopsis>Get Object Monitor Usage</synopsis> | |
7458 <typedef id="jvmtiMonitorUsage" label="Object monitor usage information"> | |
7459 <field id="owner"> | |
7460 <jthread/> | |
7461 <description> | |
7462 The thread owning this monitor, or <code>NULL</code> if unused | |
7463 </description> | |
7464 </field> | |
7465 <field id="entry_count"> | |
7466 <jint/> | |
7467 <description> | |
7468 The number of times the owning thread has entered the monitor | |
7469 </description> | |
7470 </field> | |
7471 <field id="waiter_count"> | |
7472 <jint/> | |
7473 <description> | |
7474 The number of threads waiting to own this monitor | |
7475 </description> | |
7476 </field> | |
7477 <field id="waiters"> | |
7478 <allocfieldbuf><jthread/></allocfieldbuf> | |
7479 <description> | |
7480 The <code>waiter_count</code> waiting threads | |
7481 </description> | |
7482 </field> | |
7483 <field id="notify_waiter_count"> | |
7484 <jint/> | |
7485 <description> | |
7486 The number of threads waiting to be notified by this monitor | |
7487 </description> | |
7488 </field> | |
7489 <field id="notify_waiters"> | |
7490 <allocfieldbuf><jthread/></allocfieldbuf> | |
7491 <description> | |
7492 The <code>notify_waiter_count</code> threads waiting to be notified | |
7493 </description> | |
7494 </field> | |
7495 </typedef> | |
7496 <description> | |
7497 Get information about the object's monitor. | |
7498 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure | |
7499 are filled in with information about usage of the monitor. | |
7500 <todo> | |
7501 Decide and then clarify suspend requirements. | |
7502 </todo> | |
7503 </description> | |
7504 <origin>jvmdi</origin> | |
7505 <capabilities> | |
7506 <required id="can_get_monitor_info"></required> | |
7507 </capabilities> | |
7508 <parameters> | |
7509 <param id="object"> | |
7510 <jobject/> | |
7511 <description> | |
7512 The object to query. | |
7513 </description> | |
7514 </param> | |
7515 <param id="info_ptr"> | |
7516 <outptr><struct>jvmtiMonitorUsage</struct></outptr> | |
7517 <description> | |
7518 On return, filled with monitor information for the | |
7519 specified object. | |
7520 </description> | |
7521 </param> | |
7522 </parameters> | |
7523 <errors> | |
7524 </errors> | |
7525 </function> | |
7526 | |
7527 <elide> | |
7528 <function id="GetObjectMonitors" num="116"> | |
7529 <synopsis>Get Object Monitors</synopsis> | |
7530 <description> | |
7531 Return the list of object monitors. | |
7532 <p/> | |
7533 Note: details about each monitor can be examined with | |
7534 <functionlink id="GetObjectMonitorUsage"></functionlink>. | |
7535 </description> | |
7536 <origin>new</origin> | |
7537 <capabilities> | |
7538 <required id="can_get_monitor_info"></required> | |
7539 </capabilities> | |
7540 <parameters> | |
7541 <param id="monitorCnt"> | |
7542 <outptr><jint/></outptr> | |
7543 <description> | |
7544 On return, pointer to the number | |
7545 of monitors returned in <code>monitors_ptr</code>. | |
7546 </description> | |
7547 </param> | |
7548 <param id="monitors_ptr"> | |
7549 <allocbuf outcount="monitorCnt"><jobject/></allocbuf> | |
7550 <description> | |
7551 On return, pointer to the monitor list. | |
7552 </description> | |
7553 </param> | |
7554 </parameters> | |
7555 <errors> | |
7556 </errors> | |
7557 </function> | |
7558 </elide> | |
7559 | |
7560 </category> | |
7561 | |
7562 <category id="fieldCategory" label="Field"> | |
7563 | |
7564 <intro> | |
7565 </intro> | |
7566 | |
7567 <function id="GetFieldName" phase="start" num="60"> | |
7568 <synopsis>Get Field Name (and Signature)</synopsis> | |
7569 <description> | |
7570 For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>, | |
7571 return the field name via <paramlink id="name_ptr"/> and field signature via | |
7572 <paramlink id="signature_ptr"/>. | |
7573 <p/> | |
7574 Field signatures are defined in the JNI Specification and | |
7575 are referred to as | |
7576 <vmspeclink id="ClassFile.doc.html#14152" | |
7577 name="field descriptors" | |
7578 preposition="in"/>. | |
7579 </description> | |
7580 <origin>jvmdiClone</origin> | |
7581 <capabilities> | |
7582 </capabilities> | |
7583 <parameters> | |
7584 <param id="klass"> | |
7585 <jclass field="field"/> | |
7586 <description> | |
7587 The class of the field to query. | |
7588 </description> | |
7589 </param> | |
7590 <param id="field"> | |
7591 <jfieldID class="klass"/> | |
7592 <description> | |
7593 The field to query. | |
7594 </description> | |
7595 </param> | |
7596 <param id="name_ptr"> | |
7597 <allocbuf> | |
7598 <char/> | |
7599 <nullok>the name is not returned</nullok> | |
7600 </allocbuf> | |
7601 <description> | |
7602 On return, points to the field name, encoded as a | |
7603 <internallink id="mUTF">modified UTF-8</internallink> string. | |
7604 </description> | |
7605 </param> | |
7606 <param id="signature_ptr"> | |
7607 <allocbuf> | |
7608 <char/> | |
7609 <nullok>the signature is not returned</nullok> | |
7610 </allocbuf> | |
7611 <description> | |
7612 On return, points to the field signature, encoded as a | |
7613 <internallink id="mUTF">modified UTF-8</internallink> string. | |
7614 </description> | |
7615 </param> | |
7616 <param id="generic_ptr"> | |
7617 <allocbuf> | |
7618 <char/> | |
7619 <nullok>the generic signature is not returned</nullok> | |
7620 </allocbuf> | |
7621 <description> | |
7622 On return, points to the generic signature of the field, encoded as a | |
7623 <internallink id="mUTF">modified UTF-8</internallink> string. | |
7624 If there is no generic signature attribute for the field, then, | |
7625 on return, points to <code>NULL</code>. | |
7626 </description> | |
7627 </param> | |
7628 </parameters> | |
7629 <errors> | |
7630 </errors> | |
7631 </function> | |
7632 | |
7633 <function id="GetFieldDeclaringClass" phase="start" num="61"> | |
7634 <synopsis>Get Field Declaring Class</synopsis> | |
7635 <description> | |
7636 For the field indicated by <code>klass</code> and <code>field</code> | |
7637 return the class that defined it via <code>declaring_class_ptr</code>. | |
7638 The declaring class will either be <code>klass</code>, a superclass, or | |
7639 an implemented interface. | |
7640 </description> | |
7641 <origin>jvmdi</origin> | |
7642 <capabilities> | |
7643 </capabilities> | |
7644 <parameters> | |
7645 <param id="klass"> | |
7646 <jclass field="field"/> | |
7647 <description> | |
7648 The class to query. | |
7649 </description> | |
7650 </param> | |
7651 <param id="field"> | |
7652 <jfieldID class="klass"/> | |
7653 <description> | |
7654 The field to query. | |
7655 </description> | |
7656 </param> | |
7657 <param id="declaring_class_ptr"> | |
7658 <outptr><jclass/></outptr> | |
7659 <description> | |
7660 On return, points to the declaring class | |
7661 </description> | |
7662 </param> | |
7663 </parameters> | |
7664 <errors> | |
7665 </errors> | |
7666 </function> | |
7667 | |
7668 <function id="GetFieldModifiers" phase="start" num="62"> | |
7669 <synopsis>Get Field Modifiers</synopsis> | |
7670 <description> | |
7671 For the field indicated by <code>klass</code> and <code>field</code> | |
7672 return the access flags via <code>modifiers_ptr</code>. | |
7673 Access flags are defined in the | |
7674 <vmspeclink id="ClassFile.doc.html" | |
7675 name="Class File Format chapter"/>. | |
7676 </description> | |
7677 <origin>jvmdi</origin> | |
7678 <capabilities> | |
7679 </capabilities> | |
7680 <parameters> | |
7681 <param id="klass"> | |
7682 <jclass field="field"/> | |
7683 <description> | |
7684 The class to query. | |
7685 </description> | |
7686 </param> | |
7687 <param id="field"> | |
7688 <jfieldID class="klass"/> | |
7689 <description> | |
7690 The field to query. | |
7691 </description> | |
7692 </param> | |
7693 <param id="modifiers_ptr"> | |
7694 <outptr><jint/></outptr> | |
7695 <description> | |
7696 On return, points to the access flags. | |
7697 </description> | |
7698 </param> | |
7699 </parameters> | |
7700 <errors> | |
7701 </errors> | |
7702 </function> | |
7703 | |
7704 <function id="IsFieldSynthetic" phase="start" num="63"> | |
7705 <synopsis>Is Field Synthetic</synopsis> | |
7706 <description> | |
7707 For the field indicated by <code>klass</code> and <code>field</code>, return a | |
7708 value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>. | |
7709 Synthetic fields are generated by the compiler but not present in the | |
7710 original source code. | |
7711 </description> | |
7712 <origin>jvmdi</origin> | |
7713 <capabilities> | |
7714 <required id="can_get_synthetic_attribute"></required> | |
7715 </capabilities> | |
7716 <parameters> | |
7717 <param id="klass"> | |
7718 <jclass field="field"/> | |
7719 <description> | |
7720 The class of the field to query. | |
7721 </description> | |
7722 </param> | |
7723 <param id="field"> | |
7724 <jfieldID class="klass"/> | |
7725 <description> | |
7726 The field to query. | |
7727 </description> | |
7728 </param> | |
7729 <param id="is_synthetic_ptr"> | |
7730 <outptr><jboolean/></outptr> | |
7731 <description> | |
7732 On return, points to the boolean result of this function. | |
7733 </description> | |
7734 </param> | |
7735 </parameters> | |
7736 <errors> | |
7737 </errors> | |
7738 </function> | |
7739 | |
7740 </category> | |
7741 | |
7742 <category id="method" label="Method"> | |
7743 | |
7744 <intro> | |
7745 These functions provide information about a method (represented as a | |
7746 <typelink id="jmethodID"/>) and set how methods are processed. | |
7747 </intro> | |
7748 | |
7749 <intro id="obsoleteMethods" label="Obsolete Methods"> | |
7750 The functions <functionlink id="RetransformClasses"/> and | |
7751 <functionlink id="RedefineClasses"/> can cause new versions | |
7752 of methods to be installed. | |
7753 An original version of a method is considered equivalent | |
7754 to the new version if: | |
7755 <ul> | |
7756 <li>their bytecodes are the same except for indices into the | |
7757 constant pool and </li> | |
7758 <li>the referenced constants are equal.</li> | |
7759 </ul> | |
7760 An original method version which is not equivalent to the | |
7761 new method version is called obsolete and is assigned a new method ID; | |
7762 the original method ID now refers to the new method version. | |
7763 A method ID can be tested for obsolescence with | |
7764 <functionlink id="IsMethodObsolete"/>. | |
7765 </intro> | |
7766 | |
7767 <function id="GetMethodName" phase="start" num="64"> | |
7768 <synopsis>Get Method Name (and Signature)</synopsis> | |
7769 <description> | |
7770 For the method indicated by <code>method</code>, | |
7771 return the method name via <code>name_ptr</code> and method signature via | |
7772 <code>signature_ptr</code>. | |
7773 <p/> | |
7774 Method signatures are defined in the JNI Specification and are referred to as | |
7775 <vmspeclink id="ClassFile.doc.html#7035" | |
7776 name="method descriptors" | |
7777 preposition="in"/>. | |
7778 Note this is different | |
7779 than method signatures as defined in the <i>Java Language Specification</i>. | |
7780 </description> | |
7781 <origin>jvmdiClone</origin> | |
7782 <capabilities> | |
7783 </capabilities> | |
7784 <parameters> | |
7785 <param id="method"> | |
7786 <jmethodID/> | |
7787 <description> | |
7788 The method to query. | |
7789 </description> | |
7790 </param> | |
7791 <param id="name_ptr"> | |
7792 <allocbuf> | |
7793 <char/> | |
7794 <nullok>the name is not returned</nullok> | |
7795 </allocbuf> | |
7796 <description> | |
7797 On return, points to the method name, encoded as a | |
7798 <internallink id="mUTF">modified UTF-8</internallink> string. | |
7799 </description> | |
7800 </param> | |
7801 <param id="signature_ptr"> | |
7802 <allocbuf> | |
7803 <char/> | |
7804 <nullok>the signature is not returned</nullok> | |
7805 </allocbuf> | |
7806 <description> | |
7807 On return, points to the method signature, encoded as a | |
7808 <internallink id="mUTF">modified UTF-8</internallink> string. | |
7809 </description> | |
7810 </param> | |
7811 <param id="generic_ptr"> | |
7812 <allocbuf> | |
7813 <char/> | |
7814 <nullok>the generic signature is not returned</nullok> | |
7815 </allocbuf> | |
7816 <description> | |
7817 On return, points to the generic signature of the method, encoded as a | |
7818 <internallink id="mUTF">modified UTF-8</internallink> string. | |
7819 If there is no generic signature attribute for the method, then, | |
7820 on return, points to <code>NULL</code>. | |
7821 </description> | |
7822 </param> | |
7823 </parameters> | |
7824 <errors> | |
7825 </errors> | |
7826 </function> | |
7827 | |
7828 <function id="GetMethodDeclaringClass" phase="start" num="65"> | |
7829 <synopsis>Get Method Declaring Class</synopsis> | |
7830 <description> | |
7831 For the method indicated by <code>method</code>, | |
7832 return the class that defined it via <code>declaring_class_ptr</code>. | |
7833 </description> | |
7834 <origin>jvmdi</origin> | |
7835 <capabilities> | |
7836 </capabilities> | |
7837 <parameters> | |
7838 <param id="klass"> | |
7839 <jclass method="method"/> | |
7840 <description> | |
7841 The class to query. | |
7842 </description> | |
7843 </param> | |
7844 <param id="method"> | |
7845 <jmethodID class="klass"/> | |
7846 <description> | |
7847 The method to query. | |
7848 </description> | |
7849 </param> | |
7850 <param id="declaring_class_ptr"> | |
7851 <outptr><jclass/></outptr> | |
7852 <description> | |
7853 On return, points to the declaring class | |
7854 </description> | |
7855 </param> | |
7856 </parameters> | |
7857 <errors> | |
7858 </errors> | |
7859 </function> | |
7860 | |
7861 <function id="GetMethodModifiers" phase="start" num="66"> | |
7862 <synopsis>Get Method Modifiers</synopsis> | |
7863 <description> | |
7864 For the method indicated by <code>method</code>, | |
7865 return the access flags via <code>modifiers_ptr</code>. | |
7866 Access flags are defined in the | |
7867 <vmspeclink id="ClassFile.doc.html" | |
7868 name="Class File Format chapter"/>. | |
7869 </description> | |
7870 <origin>jvmdi</origin> | |
7871 <capabilities> | |
7872 </capabilities> | |
7873 <parameters> | |
7874 <param id="klass"> | |
7875 <jclass method="method"/> | |
7876 <description> | |
7877 The class to query. | |
7878 </description> | |
7879 </param> | |
7880 <param id="method"> | |
7881 <jmethodID class="klass"/> | |
7882 <description> | |
7883 The method to query. | |
7884 </description> | |
7885 </param> | |
7886 <param id="modifiers_ptr"> | |
7887 <outptr><jint/></outptr> | |
7888 <description> | |
7889 On return, points to the access flags. | |
7890 </description> | |
7891 </param> | |
7892 </parameters> | |
7893 <errors> | |
7894 </errors> | |
7895 </function> | |
7896 | |
7897 <function id="GetMaxLocals" phase="start" num="68"> | |
7898 <synopsis>Get Max Locals</synopsis> | |
7899 <description> | |
7900 For the method indicated by <code>method</code>, | |
7901 return the number of local variable slots used by the method, | |
7902 including the local variables used to pass parameters to the | |
7903 method on its invocation. | |
7904 <p/> | |
7905 See <code>max_locals</code> in the | |
7906 <vmspeclink id="ClassFile.doc.html#1546" | |
7907 name="Code Attribute section"/>. | |
7908 </description> | |
7909 <origin>jvmdi</origin> | |
7910 <capabilities> | |
7911 </capabilities> | |
7912 <parameters> | |
7913 <param id="klass"> | |
7914 <jclass method="method"/> | |
7915 <description> | |
7916 The class to query. | |
7917 </description> | |
7918 </param> | |
7919 <param id="method"> | |
7920 <jmethodID class="klass" native="error"/> | |
7921 <description> | |
7922 The method to query. | |
7923 </description> | |
7924 </param> | |
7925 <param id="max_ptr"> | |
7926 <outptr><jint/></outptr> | |
7927 <description> | |
7928 On return, points to the maximum number of local slots | |
7929 </description> | |
7930 </param> | |
7931 </parameters> | |
7932 <errors> | |
7933 </errors> | |
7934 </function> | |
7935 | |
7936 <function id="GetArgumentsSize" phase="start" num="69"> | |
7937 <synopsis>Get Arguments Size</synopsis> | |
7938 <description> | |
7939 For the method indicated by <code>method</code>, | |
7940 return via <code>max_ptr</code> the number of local variable slots used | |
7941 by the method's arguments. | |
7942 Note that two-word arguments use two slots. | |
7943 </description> | |
7944 <origin>jvmdi</origin> | |
7945 <capabilities> | |
7946 </capabilities> | |
7947 <parameters> | |
7948 <param id="klass"> | |
7949 <jclass method="method"/> | |
7950 <description> | |
7951 The class to query. | |
7952 </description> | |
7953 </param> | |
7954 <param id="method"> | |
7955 <jmethodID class="klass" native="error"/> | |
7956 <description> | |
7957 The method to query. | |
7958 </description> | |
7959 </param> | |
7960 <param id="size_ptr"> | |
7961 <outptr><jint/></outptr> | |
7962 <description> | |
7963 On return, points to the number of argument slots | |
7964 </description> | |
7965 </param> | |
7966 </parameters> | |
7967 <errors> | |
7968 </errors> | |
7969 </function> | |
7970 | |
7971 <function id="GetLineNumberTable" phase="start" num="70"> | |
7972 <synopsis>Get Line Number Table</synopsis> | |
7973 <typedef id="jvmtiLineNumberEntry" label="Line number table entry"> | |
7974 <field id="start_location"> | |
7975 <jlocation/> | |
7976 <description> | |
7977 the <datalink id="jlocation"></datalink> where the line begins | |
7978 </description> | |
7979 </field> | |
7980 <field id="line_number"> | |
7981 <jint/> | |
7982 <description> | |
7983 the line number | |
7984 </description> | |
7985 </field> | |
7986 </typedef> | |
7987 <description> | |
7988 For the method indicated by <code>method</code>, | |
7989 return a table of source line number entries. The size of the table is | |
7990 returned via <code>entry_count_ptr</code> and the table itself is | |
7991 returned via <code>table_ptr</code>. | |
7992 </description> | |
7993 <origin>jvmdi</origin> | |
7994 <capabilities> | |
7995 <required id="can_get_line_numbers"></required> | |
7996 </capabilities> | |
7997 <parameters> | |
7998 <param id="klass"> | |
7999 <jclass method="method"/> | |
8000 <description> | |
8001 The class to query. | |
8002 </description> | |
8003 </param> | |
8004 <param id="method"> | |
8005 <jmethodID class="klass" native="error"/> | |
8006 <description> | |
8007 The method to query. | |
8008 </description> | |
8009 </param> | |
8010 <param id="entry_count_ptr"> | |
8011 <outptr><jint/></outptr> | |
8012 <description> | |
8013 On return, points to the number of entries in the table | |
8014 </description> | |
8015 </param> | |
8016 <param id="table_ptr"> | |
8017 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf> | |
8018 <description> | |
8019 On return, points to the line number table pointer. | |
8020 </description> | |
8021 </param> | |
8022 </parameters> | |
8023 <errors> | |
8024 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
8025 Class information does not include line numbers. | |
8026 </error> | |
8027 </errors> | |
8028 </function> | |
8029 | |
8030 <function id="GetMethodLocation" phase="start" num="71"> | |
8031 <synopsis>Get Method Location</synopsis> | |
8032 <description> | |
8033 For the method indicated by <code>method</code>, | |
8034 return the beginning and ending addresses through | |
8035 <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a | |
8036 conventional byte code indexing scheme, | |
8037 <code>start_location_ptr</code> will always point to zero | |
8038 and <code>end_location_ptr</code> | |
8039 will always point to the byte code count minus one. | |
8040 </description> | |
8041 <origin>jvmdi</origin> | |
8042 <capabilities> | |
8043 </capabilities> | |
8044 <parameters> | |
8045 <param id="klass"> | |
8046 <jclass method="method"/> | |
8047 <description> | |
8048 The class to query. | |
8049 </description> | |
8050 </param> | |
8051 <param id="method"> | |
8052 <jmethodID class="klass" native="error"/> | |
8053 <description> | |
8054 The method to query. | |
8055 </description> | |
8056 </param> | |
8057 <param id="start_location_ptr"> | |
8058 <outptr><jlocation/></outptr> | |
8059 <description> | |
8060 On return, points to the first location, or | |
8061 <code>-1</code> if location information is not available. | |
8062 If the information is available and | |
8063 <functionlink id="GetJLocationFormat"></functionlink> | |
8064 returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink> | |
8065 then this will always be zero. | |
8066 </description> | |
8067 </param> | |
8068 <param id="end_location_ptr"> | |
8069 <outptr><jlocation/></outptr> | |
8070 <description> | |
8071 On return, points to the last location, | |
8072 or <code>-1</code> if location information is not available. | |
8073 </description> | |
8074 </param> | |
8075 </parameters> | |
8076 <errors> | |
8077 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
8078 Class information does not include method sizes. | |
8079 </error> | |
8080 </errors> | |
8081 </function> | |
8082 | |
8083 <function id="GetLocalVariableTable" num="72"> | |
8084 <synopsis>Get Local Variable Table</synopsis> | |
8085 <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry"> | |
8086 <field id="start_location"> | |
8087 <jlocation/> | |
8088 <description> | |
8089 The code array index where the local variable is first valid | |
8090 (that is, where it must have a value). | |
8091 </description> | |
8092 </field> | |
8093 <field id="length"> | |
8094 <jint/> | |
8095 <description> | |
8096 The length of the valid section for this local variable. | |
8097 The last code array index where the local variable is valid | |
8098 is <code>start_location + length</code>. | |
8099 </description> | |
8100 </field> | |
8101 <field id="name"> | |
8102 <allocfieldbuf><char/></allocfieldbuf> | |
8103 <description> | |
8104 The local variable name, encoded as a | |
8105 <internallink id="mUTF">modified UTF-8</internallink> string. | |
8106 </description> | |
8107 </field> | |
8108 <field id="signature"> | |
8109 <allocfieldbuf><char/></allocfieldbuf> | |
8110 <description> | |
8111 The local variable's type signature, encoded as a | |
8112 <internallink id="mUTF">modified UTF-8</internallink> string. | |
8113 The signature format is the same as that defined in | |
8114 <vmspeclink id="ClassFile.doc.html#14152" | |
8115 name="Field Descriptors section"/> | |
8116 </description> | |
8117 </field> | |
8118 <field id="generic_signature"> | |
8119 <allocfieldbuf><char/></allocfieldbuf> | |
8120 <description> | |
8121 The local variable's generic signature, encoded as a | |
8122 <internallink id="mUTF">modified UTF-8</internallink> string. | |
8123 The value of this field will be <code>NULL</code> for any local | |
8124 variable which does not have a generic type. | |
8125 </description> | |
8126 </field> | |
8127 <field id="slot"> | |
8128 <jint/> | |
8129 <description> | |
8130 The local variable's slot. See <internallink id="local">Local Variables</internallink>. | |
8131 </description> | |
8132 </field> | |
8133 </typedef> | |
8134 <description> | |
8135 Return local variable information. | |
8136 </description> | |
8137 <origin>jvmdiClone</origin> | |
8138 <capabilities> | |
8139 <required id="can_access_local_variables"></required> | |
8140 </capabilities> | |
8141 <parameters> | |
8142 <param id="method"> | |
8143 <jmethodID native="error"/> | |
8144 <description> | |
8145 The method to query. | |
8146 </description> | |
8147 </param> | |
8148 <param id="entry_count_ptr"> | |
8149 <outptr><jint/></outptr> | |
8150 <description> | |
8151 On return, points to the number of entries in the table | |
8152 </description> | |
8153 </param> | |
8154 <param id="table_ptr"> | |
8155 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf> | |
8156 <description> | |
8157 On return, points to an array of local variable table entries. | |
8158 </description> | |
8159 </param> | |
8160 </parameters> | |
8161 <errors> | |
8162 <error id="JVMTI_ERROR_ABSENT_INFORMATION"> | |
8163 Class information does not include local variable | |
8164 information. | |
8165 </error> | |
8166 </errors> | |
8167 </function> | |
8168 | |
8169 <function id="GetBytecodes" phase="start" num="75"> | |
8170 <synopsis>Get Bytecodes</synopsis> | |
8171 <description> | |
8172 For the method indicated by <code>method</code>, | |
8173 return the byte codes that implement the method. The number of | |
8174 bytecodes is returned via <code>bytecode_count_ptr</code>. The byte codes | |
8175 themselves are returned via <code>bytecodes_ptr</code>. | |
8176 </description> | |
8177 <origin>jvmdi</origin> | |
8178 <capabilities> | |
8179 <required id="can_get_bytecodes"></required> | |
8180 </capabilities> | |
8181 <parameters> | |
8182 <param id="klass"> | |
8183 <jclass method="method"/> | |
8184 <description> | |
8185 The class to query. | |
8186 </description> | |
8187 </param> | |
8188 <param id="method"> | |
8189 <jmethodID class="klass" native="error"/> | |
8190 <description> | |
8191 The method to query. | |
8192 </description> | |
8193 </param> | |
8194 <param id="bytecode_count_ptr"> | |
8195 <outptr><jint/></outptr> | |
8196 <description> | |
8197 On return, points to the length of the byte code array | |
8198 </description> | |
8199 </param> | |
8200 <param id="bytecodes_ptr"> | |
8201 <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf> | |
8202 <description> | |
8203 On return, points to the pointer to the byte code array | |
8204 </description> | |
8205 </param> | |
8206 </parameters> | |
8207 <errors> | |
8208 </errors> | |
8209 </function> | |
8210 | |
8211 <function id="IsMethodNative" phase="start" num="76"> | |
8212 <synopsis>Is Method Native</synopsis> | |
8213 <description> | |
8214 For the method indicated by <code>method</code>, return a | |
8215 value indicating whether the method is native via <code>is_native_ptr</code> | |
8216 </description> | |
8217 <origin>jvmdi</origin> | |
8218 <capabilities> | |
8219 </capabilities> | |
8220 <parameters> | |
8221 <param id="klass"> | |
8222 <jclass method="method"/> | |
8223 <description> | |
8224 The class to query. | |
8225 </description> | |
8226 </param> | |
8227 <param id="method"> | |
8228 <jmethodID class="klass"/> | |
8229 <description> | |
8230 The method to query. | |
8231 </description> | |
8232 </param> | |
8233 <param id="is_native_ptr"> | |
8234 <outptr><jboolean/></outptr> | |
8235 <description> | |
8236 On return, points to the boolean result of this function. | |
8237 </description> | |
8238 </param> | |
8239 </parameters> | |
8240 <errors> | |
8241 </errors> | |
8242 </function> | |
8243 | |
8244 <function id="IsMethodSynthetic" phase="start" num="77"> | |
8245 <synopsis>Is Method Synthetic</synopsis> | |
8246 <description> | |
8247 For the method indicated by <code>method</code>, return a | |
8248 value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>. | |
8249 Synthetic methods are generated by the compiler but not present in the | |
8250 original source code. | |
8251 </description> | |
8252 <origin>jvmdi</origin> | |
8253 <capabilities> | |
8254 <required id="can_get_synthetic_attribute"></required> | |
8255 </capabilities> | |
8256 <parameters> | |
8257 <param id="klass"> | |
8258 <jclass method="method"/> | |
8259 <description> | |
8260 The class to query. | |
8261 </description> | |
8262 </param> | |
8263 <param id="method"> | |
8264 <jmethodID class="klass"/> | |
8265 <description> | |
8266 The method to query. | |
8267 </description> | |
8268 </param> | |
8269 <param id="is_synthetic_ptr"> | |
8270 <outptr><jboolean/></outptr> | |
8271 <description> | |
8272 On return, points to the boolean result of this function. | |
8273 </description> | |
8274 </param> | |
8275 </parameters> | |
8276 <errors> | |
8277 </errors> | |
8278 </function> | |
8279 | |
8280 <function id="IsMethodObsolete" phase="start" num="91"> | |
8281 <synopsis>Is Method Obsolete</synopsis> | |
8282 <description> | |
8283 Determine if a method ID refers to an | |
8284 <internallink id="obsoleteMethods">obsolete</internallink> | |
8285 method version. | |
8286 </description> | |
8287 <origin>jvmdi</origin> | |
8288 <capabilities> | |
8289 </capabilities> | |
8290 <parameters> | |
8291 <param id="klass"> | |
8292 <jclass method="method"/> | |
8293 <description> | |
8294 The class to query. | |
8295 </description> | |
8296 </param> | |
8297 <param id="method"> | |
8298 <jmethodID class="klass"/> | |
8299 <description> | |
8300 The method ID to query. | |
8301 </description> | |
8302 </param> | |
8303 <param id="is_obsolete_ptr"> | |
8304 <outptr><jboolean/></outptr> | |
8305 <description> | |
8306 On return, points to the boolean result of this function. | |
8307 </description> | |
8308 </param> | |
8309 </parameters> | |
8310 <errors> | |
8311 </errors> | |
8312 </function> | |
8313 | |
8314 <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1"> | |
8315 <synopsis>Set Native Method Prefix</synopsis> | |
8316 <description> | |
8317 This function modifies the failure handling of | |
8318 native method resolution by allowing retry | |
8319 with a prefix applied to the name. | |
8320 When used with the | |
8321 <eventlink id="ClassFileLoadHook">ClassFileLoadHook | |
8322 event</eventlink>, it enables native methods to be | |
8323 <internallink id="bci">instrumented</internallink>. | |
8324 <p/> | |
8325 Since native methods cannot be directly instrumented | |
8326 (they have no bytecodes), they must be wrapped with | |
8327 a non-native method which can be instrumented. | |
8328 For example, if we had: | |
8329 <example> | |
8330 native boolean foo(int x);</example> | |
8331 <p/> | |
8332 We could transform the class file (with the | |
8333 ClassFileLoadHook event) so that this becomes: | |
8334 <example> | |
8335 boolean foo(int x) { | |
8336 <i>... record entry to foo ...</i> | |
8337 return wrapped_foo(x); | |
8338 } | |
8339 | |
8340 native boolean wrapped_foo(int x);</example> | |
8341 <p/> | |
8342 Where foo becomes a wrapper for the actual native method | |
8343 with the appended prefix "wrapped_". Note that | |
8344 "wrapped_" would be a poor choice of prefix since it | |
8345 might conceivably form the name of an existing method | |
8346 thus something like "$$$MyAgentWrapped$$$_" would be | |
8347 better but would make these examples less readable. | |
8348 <p/> | |
8349 The wrapper will allow data to be collected on the native | |
8350 method call, but now the problem becomes linking up the | |
8351 wrapped method with the native implementation. | |
8352 That is, the method <code>wrapped_foo</code> needs to be | |
8353 resolved to the native implementation of <code>foo</code>, | |
8354 which might be: | |
8355 <example> | |
8356 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example> | |
8357 <p/> | |
8358 This function allows the prefix to be specified and the | |
8359 proper resolution to occur. | |
8360 Specifically, when the standard resolution fails, the | |
8361 resolution is retried taking the prefix into consideration. | |
8362 There are two ways that resolution occurs, explicit | |
8363 resolution with the JNI function <code>RegisterNatives</code> | |
8364 and the normal automatic resolution. For | |
8365 <code>RegisterNatives</code>, the VM will attempt this | |
8366 association: | |
8367 <example> | |
8368 method(foo) -> nativeImplementation(foo)</example> | |
8369 <p/> | |
8370 When this fails, the resolution will be retried with | |
8371 the specified prefix prepended to the method name, | |
8372 yielding the correct resolution: | |
8373 <example> | |
8374 method(wrapped_foo) -> nativeImplementation(foo)</example> | |
8375 <p/> | |
8376 For automatic resolution, the VM will attempt: | |
8377 <example> | |
8378 method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example> | |
8379 <p/> | |
8380 When this fails, the resolution will be retried with | |
8381 the specified prefix deleted from the implementation name, | |
8382 yielding the correct resolution: | |
8383 <example> | |
8384 method(wrapped_foo) -> nativeImplementation(foo)</example> | |
8385 <p/> | |
8386 Note that since the prefix is only used when standard | |
8387 resolution fails, native methods can be wrapped selectively. | |
8388 <p/> | |
8389 Since each <jvmti/> environment is independent and | |
8390 can do its own transformation of the bytecodes, more | |
8391 than one layer of wrappers may be applied. Thus each | |
8392 environment needs its own prefix. Since transformations | |
8393 are applied in order, the prefixes, if applied, will | |
8394 be applied in the same order. | |
8395 The order of transformation application is described in | |
8396 the <eventlink id="ClassFileLoadHook"/> event. | |
8397 Thus if three environments applied | |
8398 wrappers, <code>foo</code> might become | |
8399 <code>$env3_$env2_$env1_foo</code>. But if, say, | |
8400 the second environment did not apply a wrapper to | |
8401 <code>foo</code> it would be just | |
8402 <code>$env3_$env1_foo</code>. To be able to | |
8403 efficiently determine the sequence of prefixes, | |
8404 an intermediate prefix is only applied if its non-native | |
8405 wrapper exists. Thus, in the last example, even though | |
8406 <code>$env1_foo</code> is not a native method, the | |
8407 <code>$env1_</code> prefix is applied since | |
8408 <code>$env1_foo</code> exists. | |
8409 <p/> | |
8410 Since the prefixes are used at resolution time | |
8411 and since resolution may be arbitrarily delayed, a | |
8412 native method prefix must remain set as long as there | |
8413 are corresponding prefixed native methods. | |
8414 </description> | |
8415 <origin>new</origin> | |
8416 <capabilities> | |
8417 <required id="can_set_native_method_prefix"></required> | |
8418 </capabilities> | |
8419 <parameters> | |
8420 <param id="prefix"> | |
8421 <inbuf> | |
8422 <char/> | |
8423 <nullok> | |
8424 any existing prefix in this environment is cancelled | |
8425 </nullok> | |
8426 </inbuf> | |
8427 <description> | |
8428 The prefix to apply, encoded as a | |
8429 <internallink id="mUTF">modified UTF-8</internallink> string. | |
8430 </description> | |
8431 </param> | |
8432 </parameters> | |
8433 <errors> | |
8434 </errors> | |
8435 </function> | |
8436 | |
8437 <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1"> | |
8438 <synopsis>Set Native Method Prefixes</synopsis> | |
8439 <description> | |
8440 For a normal agent, <functionlink id="SetNativeMethodPrefix"/> | |
8441 will provide all needed native method prefixing. | |
8442 For a meta-agent that performs multiple independent class | |
8443 file transformations (for example as a proxy for another | |
8444 layer of agents) this function allows each transformation | |
8445 to have its own prefix. | |
8446 The prefixes are applied in the order supplied and are | |
8447 processed in the same manor as described for the | |
8448 application of prefixes from multiple <jvmti/> environments | |
8449 in <functionlink id="SetNativeMethodPrefix"/>. | |
8450 <p/> | |
8451 Any previous prefixes are replaced. Thus, calling this | |
8452 function with a <paramlink id="prefix_count"/> of <code>0</code> | |
8453 disables prefixing in this environment. | |
8454 <p/> | |
8455 <functionlink id="SetNativeMethodPrefix"/> and this function | |
8456 are the two ways to set the prefixes. | |
8457 Calling <code>SetNativeMethodPrefix</code> with | |
8458 a prefix is the same as calling this function with | |
8459 <paramlink id="prefix_count"/> of <code>1</code>. | |
8460 Calling <code>SetNativeMethodPrefix</code> with | |
8461 <code>NULL</code> is the same as calling this function with | |
8462 <paramlink id="prefix_count"/> of <code>0</code>. | |
8463 </description> | |
8464 <origin>new</origin> | |
8465 <capabilities> | |
8466 <required id="can_set_native_method_prefix"></required> | |
8467 </capabilities> | |
8468 <parameters> | |
8469 <param id="prefix_count"> | |
8470 <jint min="0"/> | |
8471 <description> | |
8472 The number of prefixes to apply. | |
8473 </description> | |
8474 </param> | |
8475 <param id="prefixes"> | |
8476 <agentbuf> | |
8477 <char/> | |
8478 </agentbuf> | |
8479 <description> | |
8480 The prefixes to apply for this environment, each encoded as a | |
8481 <internallink id="mUTF">modified UTF-8</internallink> string. | |
8482 </description> | |
8483 </param> | |
8484 </parameters> | |
8485 <errors> | |
8486 </errors> | |
8487 </function> | |
8488 | |
8489 </category> | |
8490 | |
8491 <category id="RawMonitors" label="Raw Monitor"> | |
8492 | |
8493 <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31"> | |
8494 <synopsis>Create Raw Monitor</synopsis> | |
8495 <description> | |
8496 Create a raw monitor. | |
8497 </description> | |
8498 <origin>jvmdi</origin> | |
8499 <capabilities> | |
8500 </capabilities> | |
8501 <parameters> | |
8502 <param id="name"> | |
8503 <inbuf><char/></inbuf> | |
8504 <description> | |
8505 A name to identify the monitor, encoded as a | |
8506 <internallink id="mUTF">modified UTF-8</internallink> string. | |
8507 </description> | |
8508 </param> | |
8509 <param id="monitor_ptr"> | |
8510 <outptr><jrawMonitorID/></outptr> | |
8511 <description> | |
8512 On return, points to the created monitor. | |
8513 </description> | |
8514 </param> | |
8515 </parameters> | |
8516 <errors> | |
8517 </errors> | |
8518 </function> | |
8519 | |
8520 <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32"> | |
8521 <synopsis>Destroy Raw Monitor</synopsis> | |
8522 <description> | |
8523 Destroy the raw monitor. | |
8524 If the monitor being destroyed has been entered by this thread, it will be | |
8525 exited before it is destroyed. | |
8526 If the monitor being destroyed has been entered by another thread, | |
8527 an error will be returned and the monitor will not be destroyed. | |
8528 </description> | |
8529 <origin>jvmdi</origin> | |
8530 <capabilities> | |
8531 </capabilities> | |
8532 <parameters> | |
8533 <param id="monitor"> | |
8534 <jrawMonitorID/> | |
8535 <description> | |
8536 The monitor | |
8537 </description> | |
8538 </param> | |
8539 </parameters> | |
8540 <errors> | |
8541 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
8542 Not monitor owner | |
8543 </error> | |
8544 </errors> | |
8545 </function> | |
8546 | |
8547 <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33"> | |
8548 <synopsis>Raw Monitor Enter</synopsis> | |
8549 <description> | |
8550 Gain exclusive ownership of a raw monitor. | |
8551 The same thread may enter a monitor more then once. | |
8552 The thread must | |
8553 <functionlink id="RawMonitorExit">exit</functionlink> | |
8554 the monitor the same number of times as it is entered. | |
8555 If a monitor is entered during <code>OnLoad</code> (before attached threads exist) | |
8556 and has not exited when attached threads come into existence, the enter | |
8557 is considered to have occurred on the main thread. | |
8558 </description> | |
8559 <origin>jvmdi</origin> | |
8560 <capabilities> | |
8561 </capabilities> | |
8562 <parameters> | |
8563 <param id="monitor"> | |
8564 <jrawMonitorID/> | |
8565 <description> | |
8566 The monitor | |
8567 </description> | |
8568 </param> | |
8569 </parameters> | |
8570 <errors> | |
8571 </errors> | |
8572 </function> | |
8573 | |
8574 <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34"> | |
8575 <synopsis>Raw Monitor Exit</synopsis> | |
8576 <description> | |
8577 Release exclusive ownership of a raw monitor. | |
8578 </description> | |
8579 <origin>jvmdi</origin> | |
8580 <capabilities> | |
8581 </capabilities> | |
8582 <parameters> | |
8583 <param id="monitor"> | |
8584 <jrawMonitorID/> | |
8585 <description> | |
8586 The monitor | |
8587 </description> | |
8588 </param> | |
8589 </parameters> | |
8590 <errors> | |
8591 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
8592 Not monitor owner | |
8593 </error> | |
8594 </errors> | |
8595 </function> | |
8596 | |
8597 <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35"> | |
8598 <synopsis>Raw Monitor Wait</synopsis> | |
8599 <description> | |
8600 Wait for notification of the raw monitor. | |
8601 <p/> | |
8602 Causes the current thread to wait until either another thread calls | |
8603 <functionlink id="RawMonitorNotify"/> or | |
8604 <functionlink id="RawMonitorNotifyAll"/> | |
8605 for the specified raw monitor, or the specified | |
8606 <paramlink id="millis">timeout</paramlink> | |
8607 has elapsed. | |
8608 </description> | |
8609 <origin>jvmdi</origin> | |
8610 <capabilities> | |
8611 </capabilities> | |
8612 <parameters> | |
8613 <param id="monitor"> | |
8614 <jrawMonitorID/> | |
8615 <description> | |
8616 The monitor | |
8617 </description> | |
8618 </param> | |
8619 <param id="millis"> | |
8620 <jlong/> | |
8621 <description> | |
8622 The timeout, in milliseconds. If the timeout is | |
8623 zero, then real time is not taken into consideration | |
8624 and the thread simply waits until notified. | |
8625 </description> | |
8626 </param> | |
8627 </parameters> | |
8628 <errors> | |
8629 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
8630 Not monitor owner | |
8631 </error> | |
8632 <error id="JVMTI_ERROR_INTERRUPT"> | |
8633 Wait was interrupted, try again | |
8634 </error> | |
8635 </errors> | |
8636 </function> | |
8637 | |
8638 <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36"> | |
8639 <synopsis>Raw Monitor Notify</synopsis> | |
8640 <description> | |
8641 Notify a single thread waiting on the raw monitor. | |
8642 </description> | |
8643 <origin>jvmdi</origin> | |
8644 <capabilities> | |
8645 </capabilities> | |
8646 <parameters> | |
8647 <param id="monitor"> | |
8648 <jrawMonitorID/> | |
8649 <description> | |
8650 The monitor | |
8651 </description> | |
8652 </param> | |
8653 </parameters> | |
8654 <errors> | |
8655 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
8656 Not monitor owner | |
8657 </error> | |
8658 </errors> | |
8659 </function> | |
8660 | |
8661 <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37"> | |
8662 <synopsis>Raw Monitor Notify All</synopsis> | |
8663 <description> | |
8664 Notify all threads waiting on the raw monitor. | |
8665 </description> | |
8666 <origin>jvmdi</origin> | |
8667 <capabilities> | |
8668 </capabilities> | |
8669 <parameters> | |
8670 <param id="monitor"> | |
8671 <jrawMonitorID/> | |
8672 <description> | |
8673 The monitor | |
8674 </description> | |
8675 </param> | |
8676 </parameters> | |
8677 <errors> | |
8678 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> | |
8679 Not monitor owner | |
8680 </error> | |
8681 </errors> | |
8682 </function> | |
8683 | |
8684 <elide> | |
8685 <function id="GetRawMonitorUse" num="118"> | |
8686 <synopsis>Get Raw Monitor Use</synopsis> | |
8687 <description> | |
8688 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure | |
8689 are filled in with information about usage of the raw monitor. | |
8690 </description> | |
8691 <origin>new</origin> | |
8692 <capabilities> | |
8693 <required id="can_get_raw_monitor_usage"></required> | |
8694 </capabilities> | |
8695 <parameters> | |
8696 <param id="monitor"> | |
8697 <jrawMonitorID/> | |
8698 <description> | |
8699 the raw monitor to query. | |
8700 </description> | |
8701 </param> | |
8702 <param id="info_ptr"> | |
8703 <outptr><struct>jvmtiMonitorUsage</struct></outptr> | |
8704 <description> | |
8705 On return, filled with monitor information for the | |
8706 specified raw monitor. | |
8707 </description> | |
8708 </param> | |
8709 </parameters> | |
8710 <errors> | |
8711 </errors> | |
8712 </function> | |
8713 | |
8714 <function id="GetRawMonitors" num="119"> | |
8715 <synopsis>Get Raw Monitors</synopsis> | |
8716 <description> | |
8717 Return the list of raw monitors. | |
8718 <p/> | |
8719 Note: details about each monitor can be examined with | |
8720 <functionlink id="GetRawMonitorUse"></functionlink>. | |
8721 </description> | |
8722 <origin>new</origin> | |
8723 <capabilities> | |
8724 <required id="can_get_raw_monitor_usage"></required> | |
8725 </capabilities> | |
8726 <parameters> | |
8727 <param id="monitorCnt"> | |
8728 <outptr><jint/></outptr> | |
8729 <description> | |
8730 On return, pointer to the number | |
8731 of monitors returned in <code>monitors_ptr</code>. | |
8732 </description> | |
8733 </param> | |
8734 <param id="monitors_ptr"> | |
8735 <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf> | |
8736 <description> | |
8737 On return, pointer to the monitor list. | |
8738 </description> | |
8739 </param> | |
8740 </parameters> | |
8741 <errors> | |
8742 </errors> | |
8743 </function> | |
8744 </elide> | |
8745 </category> | |
8746 | |
8747 <category id="jniIntercept" label="JNI Function Interception"> | |
8748 | |
8749 <intro> | |
8750 Provides the ability to intercept and resend | |
8751 Java Native Interface (JNI) function calls | |
8752 by manipulating the JNI function table. | |
8753 See <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html">JNI | |
8754 Functions</externallink> in the <i>Java Native Interface Specification</i>. | |
8755 <p/> | |
8756 The following example illustrates intercepting the | |
8757 <code>NewGlobalRef</code> JNI call in order to count reference | |
8758 creation. | |
8759 <example> | |
8760 JNIEnv original_jni_Functions; | |
8761 JNIEnv redirected_jni_Functions; | |
8762 int my_global_ref_count = 0; | |
8763 | |
8764 jobject | |
8765 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) { | |
8766 ++my_global_ref_count; | |
8767 return originalJNIFunctions->NewGlobalRef(env, lobj); | |
8768 } | |
8769 | |
8770 void | |
8771 myInit() { | |
8772 jvmtiError err; | |
8773 | |
8774 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &original_jni_Functions); | |
8775 if (err != JVMTI_ERROR_NONE) { | |
8776 die(); | |
8777 } | |
8778 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &redirected_jni_Functions); | |
8779 if (err != JVMTI_ERROR_NONE) { | |
8780 die(); | |
8781 } | |
8782 redirectedJNIFunctions->NewGlobalRef = MyNewGlobalRef; | |
8783 err = (*jvmti_env)->SetJNIFunctionTable(jvmti_env, redirected_jni_Functions); | |
8784 if (err != JVMTI_ERROR_NONE) { | |
8785 die(); | |
8786 } | |
8787 } | |
8788 </example> | |
8789 Sometime after <code>myInit</code> is called the user's JNI | |
8790 code is executed which makes the call to create a new global | |
8791 reference. Instead of going to the normal JNI implementation | |
8792 the call goes to <code>myNewGlobalRef</code>. Note that a | |
8793 copy of the original function table is kept so that the normal | |
8794 JNI function can be called after the data is collected. | |
8795 Note also that any JNI functions which are not overwritten | |
8796 will behave normally. | |
8797 <todo> | |
8798 check that the example compiles and executes. | |
8799 </todo> | |
8800 </intro> | |
8801 | |
8802 <function id="SetJNIFunctionTable" phase="start" num="120"> | |
8803 <synopsis>Set JNI Function Table</synopsis> | |
8804 <description> | |
8805 Set the JNI function table | |
8806 in all current and future JNI environments. | |
8807 As a result, all future JNI calls are directed to the specified functions. | |
8808 Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the | |
8809 function table to pass to this function. | |
8810 For this function to take effect the the updated table entries must be | |
8811 used by the JNI clients. | |
8812 Since the table is defined <code>const</code> some compilers may optimize | |
8813 away the access to the table, thus preventing this function from taking | |
8814 effect. | |
8815 The table is copied--changes to the local copy of the | |
8816 table have no effect. | |
8817 This function affects only the function table, all other aspects of the environment are | |
8818 unaffected. | |
8819 See the examples <internallink id="jniIntercept">above</internallink>. | |
8820 </description> | |
8821 <origin>new</origin> | |
8822 <capabilities> | |
8823 </capabilities> | |
8824 <parameters> | |
8825 <param id="function_table"> | |
8826 <inptr> | |
8827 <struct>jniNativeInterface</struct> | |
8828 </inptr> | |
8829 <description> | |
8830 Points to the new JNI function table. | |
8831 </description> | |
8832 </param> | |
8833 </parameters> | |
8834 <errors> | |
8835 </errors> | |
8836 </function> | |
8837 | |
8838 <function id="GetJNIFunctionTable" phase="start" num="121"> | |
8839 <synopsis>Get JNI Function Table</synopsis> | |
8840 <description> | |
8841 Get the JNI function table. | |
8842 The JNI function table is copied into allocated memory. | |
8843 If <functionlink id="SetJNIFunctionTable"></functionlink> | |
8844 has been called, the modified (not the original) function | |
8845 table is returned. | |
8846 Only the function table is copied, no other aspects of the environment | |
8847 are copied. | |
8848 See the examples <internallink id="jniIntercept">above</internallink>. | |
8849 </description> | |
8850 <origin>new</origin> | |
8851 <capabilities> | |
8852 </capabilities> | |
8853 <parameters> | |
8854 <param id="function_table"> | |
8855 <allocbuf> | |
8856 <struct>jniNativeInterface</struct> | |
8857 </allocbuf> | |
8858 <description> | |
8859 On return, <code>*function_table</code> | |
8860 points a newly allocated copy of the JNI function table. | |
8861 </description> | |
8862 </param> | |
8863 </parameters> | |
8864 <errors> | |
8865 </errors> | |
8866 </function> | |
8867 | |
8868 </category> | |
8869 | |
8870 <category id="eventManagement" label="Event Management"> | |
8871 | |
8872 <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122"> | |
8873 <synopsis>Set Event Callbacks</synopsis> | |
8874 <description> | |
8875 Set the functions to be called for each event. | |
8876 The callbacks are specified by supplying a replacement function table. | |
8877 The function table is copied--changes to the local copy of the | |
8878 table have no effect. | |
8879 This is an atomic action, all callbacks are set at once. | |
8880 No events are sent before this function is called. | |
8881 When an entry is <code>NULL</code> or when the event is beyond | |
8882 <paramlink id="size_of_callbacks"></paramlink> no event is sent. | |
8883 Details on events are | |
8884 described <internallink id="EventSection">later</internallink> in this document. | |
8885 An event must be enabled and have a callback in order to be | |
8886 sent--the order in which this function and | |
8887 <functionlink id="SetEventNotificationMode"></functionlink> | |
8888 are called does not affect the result. | |
8889 </description> | |
8890 <origin>new</origin> | |
8891 <capabilities> | |
8892 </capabilities> | |
8893 <parameters> | |
8894 <param id="callbacks"> | |
8895 <inptr> | |
8896 <struct>jvmtiEventCallbacks</struct> | |
8897 <nullok>remove the existing callbacks</nullok> | |
8898 </inptr> | |
8899 <description> | |
8900 The new event callbacks. | |
8901 </description> | |
8902 </param> | |
8903 <param id="size_of_callbacks"> | |
8904 <jint min="0"/> | |
8905 <description> | |
8906 <code>sizeof(jvmtiEventCallbacks)</code>--for version | |
8907 compatibility. | |
8908 </description> | |
8909 </param> | |
8910 </parameters> | |
8911 <errors> | |
8912 </errors> | |
8913 </function> | |
8914 | |
8915 <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2"> | |
8916 <synopsis>Set Event Notification Mode</synopsis> | |
8917 <description> | |
8918 Control the generation of events. | |
8919 <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum"> | |
8920 <constant id="JVMTI_ENABLE" num="1"> | |
8921 If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>, | |
8922 the event <paramlink id="event_type"></paramlink> will be enabled | |
8923 </constant> | |
8924 <constant id="JVMTI_DISABLE" num="0"> | |
8925 If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>, | |
8926 the event <paramlink id="event_type"></paramlink> will be disabled | |
8927 </constant> | |
8928 </constants> | |
8929 If <code>thread</code> is <code>NULL</code>, | |
8930 the event is enabled or disabled globally; otherwise, it is | |
8931 enabled or disabled for a particular thread. | |
8932 An event is generated for | |
8933 a particular thread if it is enabled either at the thread or global | |
8934 levels. | |
8935 <p/> | |
8936 See <internallink id="EventIndex">below</internallink> for information on specific events. | |
8937 <p/> | |
8938 The following events cannot be controlled at the thread | |
8939 level through this function. | |
8940 <ul> | |
8941 <li><eventlink id="VMInit"></eventlink></li> | |
8942 <li><eventlink id="VMStart"></eventlink></li> | |
8943 <li><eventlink id="VMDeath"></eventlink></li> | |
8944 <li><eventlink id="ThreadStart"></eventlink></li> | |
8945 <li><eventlink id="CompiledMethodLoad"></eventlink></li> | |
8946 <li><eventlink id="CompiledMethodUnload"></eventlink></li> | |
8947 <li><eventlink id="DynamicCodeGenerated"></eventlink></li> | |
8948 <li><eventlink id="DataDumpRequest"></eventlink></li> | |
8949 </ul> | |
8950 <p/> | |
8951 Initially, no events are enabled at either the thread level | |
8952 or the global level. | |
8953 <p/> | |
8954 Any needed capabilities (see Event Enabling Capabilities below) must be possessed | |
8955 before calling this function. | |
8956 <p/> | |
8957 Details on events are | |
8958 described <internallink id="EventSection">below</internallink>. | |
8959 </description> | |
8960 <origin>jvmdiClone</origin> | |
8961 <eventcapabilities></eventcapabilities> | |
8962 <parameters> | |
8963 <param id="mode"> | |
8964 <enum>jvmtiEventMode</enum> | |
8965 <description> | |
8966 <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code> | |
8967 </description> | |
8968 </param> | |
8969 <param id="event_type"> | |
8970 <enum>jvmtiEvent</enum> | |
8971 <description> | |
8972 the event to control | |
8973 </description> | |
8974 </param> | |
8975 <param id="event_thread"> | |
8976 <ptrtype> | |
8977 <jthread impl="noconvert"/> | |
8978 <nullok>event is controlled at the global level</nullok> | |
8979 </ptrtype> | |
8980 <description> | |
8981 The thread to control | |
8982 </description> | |
8983 </param> | |
8984 <param id="..."> | |
8985 <varargs/> | |
8986 <description> | |
8987 for future expansion | |
8988 </description> | |
8989 </param> | |
8990 </parameters> | |
8991 <errors> | |
8992 <error id="JVMTI_ERROR_INVALID_THREAD"> | |
8993 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread. | |
8994 </error> | |
8995 <error id="JVMTI_ERROR_THREAD_NOT_ALIVE"> | |
8996 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead). | |
8997 </error> | |
8998 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
8999 thread level control was attempted on events which do not | |
9000 permit thread level control. | |
9001 </error> | |
9002 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> | |
9003 The Required Event Enabling Capability is not possessed. | |
9004 </error> | |
9005 </errors> | |
9006 </function> | |
9007 | |
9008 <function id="GenerateEvents" num="123"> | |
9009 <synopsis>Generate Events</synopsis> | |
9010 <description> | |
9011 Generate events to represent the current state of the VM. | |
9012 For example, if <paramlink id="event_type"/> is | |
9013 <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>, | |
9014 a <eventlink id="CompiledMethodLoad"></eventlink> event will be | |
9015 sent for each currently compiled method. | |
9016 Methods that were loaded and now have been unloaded are not sent. | |
9017 The history of what events have previously been sent does not | |
9018 effect what events are sent by this function--for example, | |
9019 all currently compiled methods | |
9020 will be sent each time this function is called. | |
9021 <p/> | |
9022 This function is useful when | |
9023 events may have been missed due to the agent attaching after program | |
9024 execution begins; this function generates the missed events. | |
9025 <p/> | |
9026 Attempts to execute Java programming language code or | |
9027 JNI functions may be paused until this function returns - | |
9028 so neither should be called from the thread sending the event. | |
9029 This function returns only after the missed events have been | |
9030 sent, processed and have returned. | |
9031 The event may be sent on a different thread than the thread | |
9032 on which the event occurred. | |
9033 The callback for the event must be set with | |
9034 <functionlink id="SetEventCallbacks"></functionlink> | |
9035 and the event must be enabled with | |
9036 <functionlink id="SetEventNotificationMode"></functionlink> | |
9037 or the events will not occur. | |
9038 If the VM no longer has the information to generate some or | |
9039 all of the requested events, the events are simply not sent - | |
9040 no error is returned. | |
9041 <p/> | |
9042 Only the following events are supported: | |
9043 <ul> | |
9044 <li><eventlink id="CompiledMethodLoad"></eventlink></li> | |
9045 <li><eventlink id="DynamicCodeGenerated"></eventlink></li> | |
9046 </ul> | |
9047 </description> | |
9048 <origin>new</origin> | |
9049 <capabilities> | |
9050 <capability id="can_generate_compiled_method_load_events"></capability> | |
9051 </capabilities> | |
9052 <parameters> | |
9053 <param id="event_type"> | |
9054 <enum>jvmtiEvent</enum> | |
9055 <description> | |
9056 The type of event to generate. Must be one of these: | |
9057 <ul> | |
9058 <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li> | |
9059 <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li> | |
9060 </ul> | |
9061 </description> | |
9062 </param> | |
9063 </parameters> | |
9064 <errors> | |
9065 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> | |
9066 <paramlink id="event_type"/> is | |
9067 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> | |
9068 and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink> | |
9069 is <code>false</code>. | |
9070 </error> | |
9071 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
9072 <paramlink id="event_type"/> is other than | |
9073 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> | |
9074 or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>. | |
9075 </error> | |
9076 </errors> | |
9077 </function> | |
9078 | |
9079 </category> | |
9080 | |
9081 <category id="extension" label="Extension Mechanism"> | |
9082 | |
9083 <intro> | |
9084 These functions | |
9085 allow a <jvmti/> implementation to provide functions and events | |
9086 beyond those defined in this specification. | |
9087 <p/> | |
9088 Both extension functions and extension events have parameters | |
9089 each of which has a 'type' and 'kind' chosen from the following tables: | |
9090 | |
9091 <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum"> | |
9092 <constant id="JVMTI_TYPE_JBYTE" num="101"> | |
9093 Java programming language primitive type - <code>byte</code>. | |
9094 JNI type <code>jbyte</code>. | |
9095 </constant> | |
9096 <constant id="JVMTI_TYPE_JCHAR" num="102"> | |
9097 Java programming language primitive type - <code>char</code>. | |
9098 JNI type <code>jchar</code>. | |
9099 </constant> | |
9100 <constant id="JVMTI_TYPE_JSHORT" num="103"> | |
9101 Java programming language primitive type - <code>short</code>. | |
9102 JNI type <code>jshort</code>. | |
9103 </constant> | |
9104 <constant id="JVMTI_TYPE_JINT" num="104"> | |
9105 Java programming language primitive type - <code>int</code>. | |
9106 JNI type <datalink id="jint"></datalink>. | |
9107 </constant> | |
9108 <constant id="JVMTI_TYPE_JLONG" num="105"> | |
9109 Java programming language primitive type - <code>long</code>. | |
9110 JNI type <datalink id="jlong"></datalink>. | |
9111 </constant> | |
9112 <constant id="JVMTI_TYPE_JFLOAT" num="106"> | |
9113 Java programming language primitive type - <code>float</code>. | |
9114 JNI type <datalink id="jfloat"></datalink>. | |
9115 </constant> | |
9116 <constant id="JVMTI_TYPE_JDOUBLE" num="107"> | |
9117 Java programming language primitive type - <code>double</code>. | |
9118 JNI type <datalink id="jdouble"></datalink>. | |
9119 </constant> | |
9120 <constant id="JVMTI_TYPE_JBOOLEAN" num="108"> | |
9121 Java programming language primitive type - <code>boolean</code>. | |
9122 JNI type <datalink id="jboolean"></datalink>. | |
9123 </constant> | |
9124 <constant id="JVMTI_TYPE_JOBJECT" num="109"> | |
9125 Java programming language object type - <code>java.lang.Object</code>. | |
9126 JNI type <datalink id="jobject"></datalink>. | |
9127 Returned values are JNI local references and must be managed. | |
9128 </constant> | |
9129 <constant id="JVMTI_TYPE_JTHREAD" num="110"> | |
9130 Java programming language object type - <code>java.lang.Thread</code>. | |
9131 <jvmti/> type <datalink id="jthread"></datalink>. | |
9132 Returned values are JNI local references and must be managed. | |
9133 </constant> | |
9134 <constant id="JVMTI_TYPE_JCLASS" num="111"> | |
9135 Java programming language object type - <code>java.lang.Class</code>. | |
9136 JNI type <datalink id="jclass"></datalink>. | |
9137 Returned values are JNI local references and must be managed. | |
9138 </constant> | |
9139 <constant id="JVMTI_TYPE_JVALUE" num="112"> | |
9140 Union of all Java programming language primitive and object types - | |
9141 JNI type <datalink id="jvalue"></datalink>. | |
9142 Returned values which represent object types are JNI local references and must be managed. | |
9143 </constant> | |
9144 <constant id="JVMTI_TYPE_JFIELDID" num="113"> | |
9145 Java programming language field identifier - | |
9146 JNI type <datalink id="jfieldID"></datalink>. | |
9147 </constant> | |
9148 <constant id="JVMTI_TYPE_JMETHODID" num="114"> | |
9149 Java programming language method identifier - | |
9150 JNI type <datalink id="jmethodID"></datalink>. | |
9151 </constant> | |
9152 <constant id="JVMTI_TYPE_CCHAR" num="115"> | |
9153 C programming language type - <code>char</code>. | |
9154 </constant> | |
9155 <constant id="JVMTI_TYPE_CVOID" num="116"> | |
9156 C programming language type - <code>void</code>. | |
9157 </constant> | |
9158 <constant id="JVMTI_TYPE_JNIENV" num="117"> | |
9159 JNI environment - <code>JNIEnv</code>. | |
9160 Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type. | |
9161 </constant> | |
9162 </constants> | |
9163 | |
9164 <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum"> | |
9165 <constant id="JVMTI_KIND_IN" num="91"> | |
9166 Ingoing argument - <code>foo</code>. | |
9167 </constant> | |
9168 <constant id="JVMTI_KIND_IN_PTR" num="92"> | |
9169 Ingoing pointer argument - <code>const foo*</code>. | |
9170 </constant> | |
9171 <constant id="JVMTI_KIND_IN_BUF" num="93"> | |
9172 Ingoing array argument - <code>const foo*</code>. | |
9173 </constant> | |
9174 <constant id="JVMTI_KIND_ALLOC_BUF" num="94"> | |
9175 Outgoing allocated array argument - <code>foo**</code>. | |
9176 Free with <code>Deallocate</code>. | |
9177 </constant> | |
9178 <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95"> | |
9179 Outgoing allocated array of allocated arrays argument - <code>foo***</code>. | |
9180 Free with <code>Deallocate</code>. | |
9181 </constant> | |
9182 <constant id="JVMTI_KIND_OUT" num="96"> | |
9183 Outgoing argument - <code>foo*</code>. | |
9184 </constant> | |
9185 <constant id="JVMTI_KIND_OUT_BUF" num="97"> | |
9186 Outgoing array argument (pre-allocated by agent) - <code>foo*</code>. | |
9187 Do not <code>Deallocate</code>. | |
9188 </constant> | |
9189 </constants> | |
9190 | |
9191 </intro> | |
9192 | |
9193 <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info"> | |
9194 <field id="name"> | |
9195 <allocfieldbuf><char/></allocfieldbuf> | |
9196 <description> | |
9197 The parameter name, encoded as a | |
9198 <internallink id="mUTF">modified UTF-8</internallink> string | |
9199 </description> | |
9200 </field> | |
9201 <field id="kind"> | |
9202 <enum>jvmtiParamKind</enum> | |
9203 <description> | |
9204 The kind of the parameter - type modifiers | |
9205 </description> | |
9206 </field> | |
9207 <field id="base_type"> | |
9208 <enum>jvmtiParamTypes</enum> | |
9209 <description> | |
9210 The base type of the parameter - modified by <code>kind</code> | |
9211 </description> | |
9212 </field> | |
9213 <field id="null_ok"> | |
9214 <jboolean/> | |
9215 <description> | |
9216 Is a <code>NULL</code> argument permitted? Applies only to pointer and object types. | |
9217 </description> | |
9218 </field> | |
9219 </typedef> | |
9220 | |
9221 <callback id="jvmtiExtensionFunction"> | |
9222 <enum>jvmtiError</enum> | |
9223 <synopsis>Extension Function</synopsis> | |
9224 <description> | |
9225 This is the implementation-specific extension function. | |
9226 </description> | |
9227 <parameters> | |
9228 <param id="jvmti_env"> | |
9229 <outptr> | |
9230 <struct>jvmtiEnv</struct> | |
9231 </outptr> | |
9232 <description> | |
9233 The <jvmti/> environment is the only fixed parameter for extension functions. | |
9234 </description> | |
9235 </param> | |
9236 <param id="..."> | |
9237 <varargs/> | |
9238 <description> | |
9239 The extension function-specific parameters | |
9240 </description> | |
9241 </param> | |
9242 </parameters> | |
9243 </callback> | |
9244 | |
9245 <function id="GetExtensionFunctions" phase="onload" num="124"> | |
9246 <synopsis>Get Extension Functions</synopsis> | |
9247 | |
9248 <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info"> | |
9249 <field id="func"> | |
9250 <ptrtype> | |
9251 <struct>jvmtiExtensionFunction</struct> | |
9252 </ptrtype> | |
9253 <description> | |
9254 The actual function to call | |
9255 </description> | |
9256 </field> | |
9257 <field id="id"> | |
9258 <allocfieldbuf><char/></allocfieldbuf> | |
9259 <description> | |
9260 The identifier for the extension function, encoded as a | |
9261 <internallink id="mUTF">modified UTF-8</internallink> string. | |
9262 Uses package name conventions. | |
9263 For example, <code>com.sun.hotspot.bar</code> | |
9264 </description> | |
9265 </field> | |
9266 <field id="short_description"> | |
9267 <allocfieldbuf><char/></allocfieldbuf> | |
9268 <description> | |
9269 A one sentence description of the function, encoded as a | |
9270 <internallink id="mUTF">modified UTF-8</internallink> string. | |
9271 </description> | |
9272 </field> | |
9273 <field id="param_count"> | |
9274 <jint/> | |
9275 <description> | |
9276 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code> | |
9277 </description> | |
9278 </field> | |
9279 <field id="params"> | |
9280 <allocfieldbuf outcount="param_count"> | |
9281 <struct>jvmtiParamInfo</struct> | |
9282 </allocfieldbuf> | |
9283 <description> | |
9284 Array of | |
9285 <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> | |
9286 parameters (<code>jvmtiEnv *jvmti_env</code> excluded) | |
9287 </description> | |
9288 </field> | |
9289 <field id="error_count"> | |
9290 <jint/> | |
9291 <description> | |
9292 The number of possible error returns (excluding universal errors) | |
9293 </description> | |
9294 </field> | |
9295 <field id="errors"> | |
9296 <allocfieldbuf outcount="error_count"> | |
9297 <enum>jvmtiError</enum> | |
9298 </allocfieldbuf> | |
9299 <description> | |
9300 Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> | |
9301 possible errors | |
9302 </description> | |
9303 </field> | |
9304 </typedef> | |
9305 | |
9306 <description> | |
9307 Returns the set of extension functions. | |
9308 </description> | |
9309 <origin>new</origin> | |
9310 <capabilities> | |
9311 </capabilities> | |
9312 <parameters> | |
9313 <param id="extension_count_ptr"> | |
9314 <outptr><jint/></outptr> | |
9315 <description> | |
9316 On return, points to the number of extension functions | |
9317 </description> | |
9318 </param> | |
9319 <param id="extensions"> | |
9320 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf> | |
9321 <description> | |
9322 Returns an array of extension function info, one per function | |
9323 </description> | |
9324 </param> | |
9325 </parameters> | |
9326 <errors> | |
9327 </errors> | |
9328 </function> | |
9329 | |
9330 <function id="GetExtensionEvents" phase="onload" num="125"> | |
9331 <synopsis>Get Extension Events</synopsis> | |
9332 | |
9333 <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info"> | |
9334 <field id="extension_event_index"> | |
9335 <jint/> | |
9336 <description> | |
9337 The identifying index of the event | |
9338 </description> | |
9339 </field> | |
9340 <field id="id"> | |
9341 <allocfieldbuf><char/></allocfieldbuf> | |
9342 <description> | |
9343 The identifier for the extension event, 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 event, 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="jvmtiExtensionEventInfo"></fieldlink> | |
9369 parameters (<code>jvmtiEnv *jvmti_env</code> excluded) | |
9370 </description> | |
9371 </field> | |
9372 </typedef> | |
9373 | |
9374 <description> | |
9375 Returns the set of extension events. | |
9376 </description> | |
9377 <origin>new</origin> | |
9378 <capabilities> | |
9379 </capabilities> | |
9380 <parameters> | |
9381 <param id="extension_count_ptr"> | |
9382 <outptr><jint/></outptr> | |
9383 <description> | |
9384 On return, points to the number of extension events | |
9385 </description> | |
9386 </param> | |
9387 <param id="extensions"> | |
9388 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf> | |
9389 <description> | |
9390 Returns an array of extension event info, one per event | |
9391 </description> | |
9392 </param> | |
9393 </parameters> | |
9394 <errors> | |
9395 </errors> | |
9396 </function> | |
9397 | |
9398 <callback id="jvmtiExtensionEvent"> | |
9399 <void/> | |
9400 <synopsis>Extension Event</synopsis> | |
9401 <description> | |
9402 This is the implementation-specific event. | |
9403 The event handler is set with | |
9404 <functionlink id="SetExtensionEventCallback"/>. | |
9405 <p/> | |
9406 Event handlers for extension events must be declared varargs to match this definition. | |
9407 Failure to do so could result in calling convention mismatch and undefined behavior | |
9408 on some platforms. | |
9409 <p/> | |
9410 For example, if the <code>jvmtiParamInfo</code> | |
9411 returned by <functionlink id="GetExtensionEvents"/> indicates that | |
9412 there is a <code>jint</code> parameter, the event handler should be | |
9413 declared: | |
9414 <example> | |
9415 void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...) | |
9416 </example> | |
9417 Note the terminal "<code>...</code>" which indicates varargs. | |
9418 </description> | |
9419 <parameters> | |
9420 <param id="jvmti_env"> | |
9421 <outptr> | |
9422 <struct>jvmtiEnv</struct> | |
9423 </outptr> | |
9424 <description> | |
9425 The <jvmti/> environment is the only fixed parameter for extension events. | |
9426 </description> | |
9427 </param> | |
9428 <param id="..."> | |
9429 <varargs/> | |
9430 <description> | |
9431 The extension event-specific parameters | |
9432 </description> | |
9433 </param> | |
9434 </parameters> | |
9435 </callback> | |
9436 | |
9437 <function id="SetExtensionEventCallback" phase="onload" num="126"> | |
9438 <synopsis>Set Extension Event Callback</synopsis> | |
9439 | |
9440 <description> | |
9441 Sets the callback function for an extension event and | |
9442 enables the event. Or, if the callback is <code>NULL</code>, disables | |
9443 the event. Note that unlike standard events, setting | |
9444 the callback and enabling the event are a single operation. | |
9445 </description> | |
9446 <origin>new</origin> | |
9447 <capabilities> | |
9448 </capabilities> | |
9449 <parameters> | |
9450 <param id="extension_event_index"> | |
9451 <jint/> | |
9452 <description> | |
9453 Identifies which callback to set. | |
9454 This index is the | |
9455 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink> | |
9456 field of | |
9457 <datalink id="jvmtiExtensionEventInfo"/>. | |
9458 </description> | |
9459 </param> | |
9460 <param id="callback"> | |
9461 <ptrtype> | |
9462 <struct>jvmtiExtensionEvent</struct> | |
9463 <nullok>disable the event</nullok> | |
9464 </ptrtype> | |
9465 <description> | |
9466 If <code>callback</code> is non-<code>NULL</code>, | |
9467 set <code>callback</code> to be the event callback function | |
9468 and enable the event. | |
9469 </description> | |
9470 </param> | |
9471 </parameters> | |
9472 <errors> | |
9473 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
9474 <paramlink id="extension_event_index"/> is not an | |
9475 <fieldlink id="extension_event_index" | |
9476 struct="jvmtiExtensionEventInfo"/> | |
9477 returned by | |
9478 <functionlink id="GetExtensionEvents"/> | |
9479 </error> | |
9480 </errors> | |
9481 </function> | |
9482 | |
9483 </category> | |
9484 | |
9485 <category id="capability" label="Capability"> | |
9486 | |
9487 <intro> | |
9488 The capabilities functions allow you to change the | |
9489 functionality available to <jvmti/>--that is, | |
9490 which <jvmti/> | |
9491 functions can be called, what events can be generated, | |
9492 and what functionality these events and functions can | |
9493 provide. | |
9494 <p/> | |
9495 The "Capabilities" section of each function and event describe which | |
9496 capabilities, if any, they are associated with. "Required Functionality" | |
9497 means it is available for use and no capabilities must be added to use it. | |
9498 "Optional Functionality" means the agent must possess the capability | |
9499 before it can be used. | |
9500 To possess a capability, the agent must | |
9501 <functionlink id="AddCapabilities">add the capability</functionlink>. | |
9502 "Optional Features" describe capabilities which, | |
9503 if added, extend the feature set. | |
9504 <p/> | |
9505 The potentially available capabilities of each <jvmti/> implementation are different. | |
9506 Depending on the implementation, a capability: | |
9507 <ul> | |
9508 <li>may never be added</li> | |
9509 <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li> | |
9510 <li>may be added only during the <code>OnLoad</code> phase</li> | |
9511 <li>may be possessed by only one environment at a time</li> | |
9512 <li>may be possessed by only one environment at a time, | |
9513 and only during the <code>OnLoad</code> phase</li> | |
9514 <li>and so on ...</li> | |
9515 </ul> | |
9516 Frequently, the addition of a capability may incur a cost in execution speed, start up | |
9517 time, and/or memory footprint. Note that the overhead of using a capability | |
9518 is completely different than the overhead of possessing a capability. | |
9519 Take single stepping as an example. When single stepping is on (that | |
9520 is, when the event is enabled and thus actively sending events) | |
9521 the overhead of sending and processing an event | |
9522 on each instruction is huge in any implementation. | |
9523 However, the overhead of possessing the capability may be small or large, | |
9524 depending on the implementation. Also, when and if a capability is potentially | |
9525 available depends on the implementation. Some examples: | |
9526 <ul> | |
9527 <li>One VM might perform all execution by compiling bytecodes into | |
9528 native code and be unable to generate single step instructions. | |
9529 In this implementation the capability can not be added.</li> | |
9530 <li>Another VM may be able to switch execution to a single stepping | |
9531 interpreter at any time. In this implementation, having the capability has no | |
9532 overhead and could be added at any time.</li> | |
9533 <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted | |
9534 execution engine at start up, but be unable to switch between them. | |
9535 In this implementation the capability would need to be added | |
9536 during the <code>OnLoad</code> phase (before bytecode | |
9537 execution begins) and would have a large impact on execution speed | |
9538 even if single stepping was never used.</li> | |
9539 <li>Still another VM might be able to add an "is single stepping on" check | |
9540 into compiled bytecodes or a generated interpreter. Again in this implementation | |
9541 the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test | |
9542 and branch on each instruction) would be considerably less.</li> | |
9543 </ul> | |
9544 <p/> | |
9545 Each <jvmti/> <internallink id="environments">environment</internallink> | |
9546 has its own set of capabilities. | |
9547 Initially, that set is empty. | |
9548 Any desired capability must be added. | |
9549 If possible, capabilities should be added during the <code>OnLoad</code> phase. For most | |
9550 virtual machines certain capabilities require special set up for | |
9551 the virtual machine and this set up must happen | |
9552 during the <code>OnLoad</code> phase, before the virtual machine begins execution. | |
9553 Once a capability is added, it can | |
9554 only be removed if explicitly relinquished by the environment. | |
9555 <p/> | |
9556 The agent can, | |
9557 <functionlink id="GetPotentialCapabilities">determine what | |
9558 capabilities this VM can potentially provide</functionlink>, | |
9559 <functionlink id="AddCapabilities">add the capabilities | |
9560 to be used</functionlink>, | |
9561 <functionlink id="RelinquishCapabilities">release capabilities | |
9562 which are no longer needed</functionlink>, and | |
9563 <functionlink id="GetCapabilities">examine the currently available | |
9564 capabilities</functionlink>. | |
9565 </intro> | |
9566 | |
9567 <intro id="capabilityExamples" label="Capability Examples"> | |
9568 For example, a freshly started agent (in the <code>OnLoad</code> function) | |
9569 wants to enable all possible capabilities. | |
9570 Note that, in general, this is not advisable as the agent may suffer | |
9571 a performance penalty for functionality it is not using. | |
9572 The code might look like this in C: | |
9573 <example> | |
9574 jvmtiCapabilities capa; | |
9575 jvmtiError err; | |
9576 | |
9577 err = (*jvmti)->GetPotentialCapabilities(jvmti, &capa); | |
9578 if (err == JVMTI_ERROR_NONE) { | |
9579 err = (*jvmti)->AddCapabilities(jvmti, &capa); | |
9580 </example> | |
9581 For example, if an agent wants to check if it can get | |
9582 the bytecodes of a method (that is, it wants to check | |
9583 if it previously added this capability and has not | |
9584 relinquished it), the code might | |
9585 look like this in C: | |
9586 <example> | |
9587 jvmtiCapabilities capa; | |
9588 jvmtiError err; | |
9589 | |
9590 err = (*jvmti)->GetCapabilities(jvmti, &capa); | |
9591 if (err == JVMTI_ERROR_NONE) { | |
9592 if (capa.can_get_bytecodes) { ... } } | |
9593 </example> | |
9594 </intro> | |
9595 | |
9596 <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure"> | |
9597 <description> | |
9598 The functions in this category use this capabilities structure | |
9599 which contains boolean flags corresponding to each capability: | |
9600 </description> | |
9601 <capabilityfield id="can_tag_objects"> | |
9602 <description> | |
9603 Can set and get tags, as described in the | |
9604 <internallink id="Heap">Heap category</internallink>. | |
9605 </description> | |
9606 </capabilityfield> | |
9607 <capabilityfield id="can_generate_field_modification_events"> | |
9608 <description> | |
9609 Can set watchpoints on field modification - | |
9610 <functionlink id="SetFieldModificationWatch"></functionlink> | |
9611 </description> | |
9612 </capabilityfield> | |
9613 <capabilityfield id="can_generate_field_access_events"> | |
9614 <description> | |
9615 Can set watchpoints on field access - | |
9616 <functionlink id="SetFieldAccessWatch"></functionlink> | |
9617 </description> | |
9618 </capabilityfield> | |
9619 <capabilityfield id="can_get_bytecodes"> | |
9620 <description> | |
9621 Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink> | |
9622 </description> | |
9623 </capabilityfield> | |
9624 <capabilityfield id="can_get_synthetic_attribute"> | |
9625 <description> | |
9626 Can test if a field or method is synthetic - | |
9627 <functionlink id="IsFieldSynthetic"></functionlink> and | |
9628 <functionlink id="IsMethodSynthetic"></functionlink> | |
9629 </description> | |
9630 </capabilityfield> | |
9631 <capabilityfield id="can_get_owned_monitor_info"> | |
9632 <description> | |
9633 Can get information about ownership of monitors - | |
9634 <functionlink id="GetOwnedMonitorInfo"></functionlink> | |
9635 </description> | |
9636 </capabilityfield> | |
9637 <capabilityfield id="can_get_current_contended_monitor"> | |
9638 <description> | |
9639 Can <functionlink id="GetCurrentContendedMonitor"></functionlink> | |
9640 </description> | |
9641 </capabilityfield> | |
9642 <capabilityfield id="can_get_monitor_info"> | |
9643 <description> | |
9644 Can <functionlink id="GetObjectMonitorUsage"></functionlink> | |
9645 </description> | |
9646 </capabilityfield> | |
9647 <capabilityfield id="can_pop_frame"> | |
9648 <description> | |
9649 Can pop frames off the stack - <functionlink id="PopFrame"></functionlink> | |
9650 </description> | |
9651 </capabilityfield> | |
9652 <capabilityfield id="can_redefine_classes"> | |
9653 <description> | |
9654 Can redefine classes with <functionlink id="RedefineClasses"/>. | |
9655 </description> | |
9656 </capabilityfield> | |
9657 <capabilityfield id="can_signal_thread"> | |
9658 <description> | |
9659 Can send stop or interrupt to threads | |
9660 </description> | |
9661 </capabilityfield> | |
9662 <capabilityfield id="can_get_source_file_name"> | |
9663 <description> | |
9664 Can get the source file name of a class | |
9665 </description> | |
9666 </capabilityfield> | |
9667 <capabilityfield id="can_get_line_numbers"> | |
9668 <description> | |
9669 Can get the line number table of a method | |
9670 </description> | |
9671 </capabilityfield> | |
9672 <capabilityfield id="can_get_source_debug_extension"> | |
9673 <description> | |
9674 Can get the source debug extension of a class | |
9675 </description> | |
9676 </capabilityfield> | |
9677 <capabilityfield id="can_access_local_variables"> | |
9678 <description> | |
9679 Can set and get local variables | |
9680 </description> | |
9681 </capabilityfield> | |
9682 <capabilityfield id="can_maintain_original_method_order"> | |
9683 <description> | |
9684 Can return methods in the order they occur in the class file | |
9685 </description> | |
9686 </capabilityfield> | |
9687 <capabilityfield id="can_generate_single_step_events"> | |
9688 <description> | |
9689 Can get <eventlink id="SingleStep">single step</eventlink> events | |
9690 </description> | |
9691 </capabilityfield> | |
9692 <capabilityfield id="can_generate_exception_events"> | |
9693 <description> | |
9694 Can get <eventlink id="Exception">exception thrown</eventlink> and | |
9695 <eventlink id="ExceptionCatch">exception catch</eventlink> events | |
9696 </description> | |
9697 </capabilityfield> | |
9698 <capabilityfield id="can_generate_frame_pop_events"> | |
9699 <description> | |
9700 Can <functionlink id="NotifyFramePop">set</functionlink> and thus get | |
9701 <eventlink id="FramePop"></eventlink> events | |
9702 </description> | |
9703 </capabilityfield> | |
9704 <capabilityfield id="can_generate_breakpoint_events"> | |
9705 <description> | |
9706 Can <functionlink id="SetBreakpoint">set</functionlink> and thus get | |
9707 <eventlink id="Breakpoint"></eventlink> events | |
9708 </description> | |
9709 </capabilityfield> | |
9710 <capabilityfield id="can_suspend"> | |
9711 <description> | |
9712 Can suspend and resume threads | |
9713 </description> | |
9714 </capabilityfield> | |
9715 <capabilityfield id="can_redefine_any_class"> | |
9716 <description> | |
9717 Can modify (retransform or redefine) any non-primitive non-array class. | |
9718 See <functionlink id="IsModifiableClass"/>. | |
9719 </description> | |
9720 </capabilityfield> | |
9721 <capabilityfield id="can_get_current_thread_cpu_time"> | |
9722 <description> | |
9723 Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink> | |
9724 current thread CPU time | |
9725 </description> | |
9726 </capabilityfield> | |
9727 <capabilityfield id="can_get_thread_cpu_time"> | |
9728 <description> | |
9729 Can <functionlink id="GetThreadCpuTime">get</functionlink> | |
9730 thread CPU time | |
9731 </description> | |
9732 </capabilityfield> | |
9733 <capabilityfield id="can_generate_method_entry_events" | |
9734 disp1="can_generate" disp2="_method_entry_events" | |
9735 > | |
9736 <description> | |
9737 Can generate method entry events on entering a method | |
9738 </description> | |
9739 </capabilityfield> | |
9740 <capabilityfield id="can_generate_method_exit_events" | |
9741 disp1="can_generate" disp2="_method_exit_events" | |
9742 > | |
9743 <description> | |
9744 Can generate method exit events on leaving a method | |
9745 </description> | |
9746 </capabilityfield> | |
9747 <capabilityfield id="can_generate_all_class_hook_events" | |
9748 disp1="can_generate" disp2="_all_class_hook_events" | |
9749 > | |
9750 <description> | |
9751 Can generate ClassFileLoadHook events for every loaded class. | |
9752 </description> | |
9753 </capabilityfield> | |
9754 <capabilityfield id="can_generate_compiled_method_load_events" | |
9755 disp1="can_generate" disp2="_compiled_method_load_events" | |
9756 > | |
9757 <description> | |
9758 Can generate events when a method is compiled or unloaded | |
9759 </description> | |
9760 </capabilityfield> | |
9761 <capabilityfield id="can_generate_monitor_events" | |
9762 disp1="can_generate" disp2="_monitor_events" | |
9763 > | |
9764 <description> | |
9765 Can generate events on monitor activity | |
9766 </description> | |
9767 </capabilityfield> | |
9768 <capabilityfield id="can_generate_vm_object_alloc_events" | |
9769 disp1="can_generate" disp2="_vm_object_alloc_events" | |
9770 > | |
9771 <description> | |
9772 Can generate events on VM allocation of an object | |
9773 </description> | |
9774 </capabilityfield> | |
9775 <capabilityfield id="can_generate_native_method_bind_events" | |
9776 disp1="can_generate" disp2="_native_method_bind_events" | |
9777 > | |
9778 <description> | |
9779 Can generate events when a native method is bound to its | |
9780 implementation | |
9781 </description> | |
9782 </capabilityfield> | |
9783 <capabilityfield id="can_generate_garbage_collection_events" | |
9784 disp1="can_generate" disp2="_garbage_collection_events" | |
9785 > | |
9786 <description> | |
9787 Can generate events when garbage collection begins or ends | |
9788 </description> | |
9789 </capabilityfield> | |
9790 <capabilityfield id="can_generate_object_free_events" | |
9791 disp1="can_generate" disp2="_object_free_events" | |
9792 > | |
9793 <description> | |
9794 Can generate events when the garbage collector frees an object | |
9795 </description> | |
9796 </capabilityfield> | |
9797 <capabilityfield id="can_force_early_return" since="1.1"> | |
9798 <description> | |
9799 Can return early from a method, as described in the | |
9800 <internallink id="ForceEarlyReturn">Force Early Return category</internallink>. | |
9801 </description> | |
9802 </capabilityfield> | |
9803 <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1"> | |
9804 <description> | |
9805 Can get information about owned monitors with stack depth - | |
9806 <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink> | |
9807 </description> | |
9808 </capabilityfield> | |
9809 <capabilityfield id="can_get_constant_pool" since="1.1"> | |
9810 <description> | |
9811 Can get the constant pool of a class - | |
9812 <functionlink id="GetConstantPool"></functionlink> | |
9813 </description> | |
9814 </capabilityfield> | |
9815 <capabilityfield id="can_set_native_method_prefix" since="1.1"> | |
9816 <description> | |
9817 Can set prefix to be applied when native method cannot be resolved - | |
9818 <functionlink id="SetNativeMethodPrefix"/> and | |
9819 <functionlink id="SetNativeMethodPrefixes"/> | |
9820 </description> | |
9821 </capabilityfield> | |
9822 <capabilityfield id="can_retransform_classes" since="1.1"> | |
9823 <description> | |
9824 Can retransform classes with <functionlink id="RetransformClasses"/>. | |
9825 In addition to the restrictions imposed by the specific | |
9826 implementation on this capability (see the | |
9827 <internallink id="capability">Capability</internallink> section), | |
9828 this capability must be set before the | |
9829 <eventlink id="ClassFileLoadHook"/> event is enabled for the | |
9830 first time in this environment. | |
9831 An environment that possesses this capability at the time that | |
9832 <code>ClassFileLoadHook</code> is enabled for the first time is | |
9833 said to be <i>retransformation capable</i>. | |
9834 An environment that does not possess this capability at the time that | |
9835 <code>ClassFileLoadHook</code> is enabled for the first time is | |
9836 said to be <i>retransformation incapable</i>. | |
9837 </description> | |
9838 </capabilityfield> | |
9839 <capabilityfield id="can_retransform_any_class" since="1.1"> | |
9840 <description> | |
9841 <functionlink id="RetransformClasses"/> can be called on any class | |
9842 (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> | |
9843 must also be set) | |
9844 </description> | |
9845 </capabilityfield> | |
9846 <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1"> | |
9847 <description> | |
9848 Can generate events when the VM is unable to allocate memory from | |
9849 the <tm>Java</tm> platform heap. | |
9850 See <eventlink id="ResourceExhausted"/>. | |
9851 </description> | |
9852 </capabilityfield> | |
9853 <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1"> | |
9854 <description> | |
9855 Can generate events when the VM is unable to create a thread. | |
9856 See <eventlink id="ResourceExhausted"/>. | |
9857 </description> | |
9858 </capabilityfield> | |
9859 </capabilitiestypedef> | |
9860 | |
9861 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140"> | |
9862 <synopsis>Get Potential Capabilities</synopsis> | |
9863 <description> | |
9864 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/> | |
9865 features that can potentially be possessed by this environment | |
9866 at this time. | |
9867 The returned capabilities differ from the complete set of capabilities | |
9868 implemented by the VM in two cases: another environment possesses | |
9869 capabilities that can only be possessed by one environment, or the | |
9870 current <functionlink id="GetPhase">phase</functionlink> is live, | |
9871 and certain capabilities can only be added during the <code>OnLoad</code> phase. | |
9872 The <functionlink id="AddCapabilities"></functionlink> function | |
9873 may be used to set any or all or these capabilities. | |
9874 Currently possessed capabilities are included. | |
9875 <p/> | |
9876 Typically this function is used in the <code>OnLoad</code> function. | |
9877 Some virtual machines may allow a limited set of capabilities to be | |
9878 added in the live phase. | |
9879 In this case, the set of potentially available capabilities | |
9880 will likely differ from the <code>OnLoad</code> phase set. | |
9881 <p/> | |
9882 See the | |
9883 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
9884 </description> | |
9885 <origin>new</origin> | |
9886 <capabilities> | |
9887 </capabilities> | |
9888 <parameters> | |
9889 <param id="capabilities_ptr"> | |
9890 <outptr><struct>jvmtiCapabilities</struct></outptr> | |
9891 <description> | |
9892 On return, points to the <jvmti/> capabilities that may be added. | |
9893 </description> | |
9894 </param> | |
9895 </parameters> | |
9896 <errors> | |
9897 </errors> | |
9898 </function> | |
9899 | |
9900 <elide> | |
9901 <function id="EstimateCostOfCapabilities" phase="onload" num="141"> | |
9902 <synopsis>Estimate Cost Of Capabilities</synopsis> | |
9903 <description> | |
9904 <issue>There is strong opposition to this function. The concern is | |
9905 that it would be difficult or impossible to provide meaningful | |
9906 numbers, as the amount of impact is conditional on many factors | |
9907 that a single number could not represent. There is doubt that | |
9908 conditional implementations would be used or are even a good idea. | |
9909 The thought is that release documentation for the implementation | |
9910 would be the best means of exposing this information. | |
9911 Unless new arguments are presented, I intend to remove this | |
9912 function in the next revision. | |
9913 </issue> | |
9914 <p/> | |
9915 Return via the <paramlink id="time_impact_ptr"></paramlink> and | |
9916 <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact | |
9917 of adding the capabilities pointed to by | |
9918 <paramlink id="capabilities_ptr"></paramlink>. | |
9919 The returned estimates are in percentage of additional overhead, thus | |
9920 a time impact of 100 mean the application might run | |
9921 at half the speed. | |
9922 The estimates are very rough approximations and are not guaranteed. | |
9923 Note also, that the estimates are of the impact of having the | |
9924 capability available--when and if it is used the impact may be | |
9925 much greater. | |
9926 Estimates can be for a single capability or for a set of | |
9927 capabilities. Note that the costs are not necessarily additive, | |
9928 adding support for one capability might make another available | |
9929 for free or conversely having two capabilities at once may | |
9930 have multiplicative impact. | |
9931 Estimates are relative to the current set of capabilities - | |
9932 that is, how much more impact given the currently possessed capabilities. | |
9933 <p/> | |
9934 Typically this function is used in the OnLoad function, | |
9935 some virtual machines may allow a limited set of capabilities to be | |
9936 added in the live phase. | |
9937 In this case, the set of potentially available capabilities | |
9938 will likely differ from the OnLoad phase set. | |
9939 <p/> | |
9940 See the | |
9941 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
9942 </description> | |
9943 <origin>new</origin> | |
9944 <capabilities> | |
9945 </capabilities> | |
9946 <parameters> | |
9947 <param id="capabilities_ptr"> | |
9948 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
9949 <description> | |
9950 points to the <jvmti/> capabilities to evaluate. | |
9951 </description> | |
9952 </param> | |
9953 <param id="time_impact_ptr"> | |
9954 <outptr><jint/></outptr> | |
9955 <description> | |
9956 On return, points to the estimated percentage increase in | |
9957 run time if this capability was added. | |
9958 </description> | |
9959 </param> | |
9960 <param id="space_impact_ptr"> | |
9961 <outptr><jint/></outptr> | |
9962 <description> | |
9963 On return, points to the estimated percentage increase in | |
9964 memory space used if this capability was added. | |
9965 </description> | |
9966 </param> | |
9967 </parameters> | |
9968 <errors> | |
9969 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
9970 The desired capabilities are not even potentially available. | |
9971 </error> | |
9972 </errors> | |
9973 </function> | |
9974 </elide> | |
9975 | |
9976 <function id="AddCapabilities" jkernel="yes" phase="onload" num="142"> | |
9977 <synopsis>Add Capabilities</synopsis> | |
9978 <description> | |
9979 Set new capabilities by adding the capabilities | |
9980 whose values are set to one (<code>1</code>) in | |
9981 <code>*</code><paramlink id="capabilities_ptr"></paramlink>. | |
9982 All previous capabilities are retained. | |
9983 Typically this function is used in the <code>OnLoad</code> function. | |
9984 Some virtual machines may allow a limited set of capabilities to be | |
9985 added in the live phase. | |
9986 <p/> | |
9987 See the | |
9988 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
9989 </description> | |
9990 <origin>new</origin> | |
9991 <capabilities> | |
9992 </capabilities> | |
9993 <parameters> | |
9994 <param id="capabilities_ptr"> | |
9995 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
9996 <description> | |
9997 Points to the <jvmti/> capabilities to add. | |
9998 </description> | |
9999 </param> | |
10000 </parameters> | |
10001 <errors> | |
10002 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
10003 The desired capabilities are not even potentially available. | |
10004 </error> | |
10005 </errors> | |
10006 </function> | |
10007 | |
10008 | |
10009 <function id="RelinquishCapabilities" phase="onload" num="143"> | |
10010 <synopsis>Relinquish Capabilities</synopsis> | |
10011 <description> | |
10012 Relinquish the capabilities | |
10013 whose values are set to one (<code>1</code>) in | |
10014 <code>*</code><paramlink id="capabilities_ptr"></paramlink>. | |
10015 Some implementations may allow only one environment to have a capability | |
10016 (see the <internallink id="capability">capability introduction</internallink>). | |
10017 This function releases capabilities | |
10018 so that they may be used by other agents. | |
10019 All other capabilities are retained. | |
10020 The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>. | |
10021 Attempting to relinquish a capability that the agent does not possess is not an error. | |
10022 <issue> | |
10023 It is possible for the agent to be actively using capabilities | |
10024 which are being relinquished. For example, a thread is currently | |
10025 suspended and can_suspend is being relinquished or an event is currently | |
10026 enabled and can_generate_whatever is being relinquished. | |
10027 There are three possible ways we could spec this: | |
10028 <ul> | |
10029 <li>relinquish automatically releases them</li> | |
10030 <li>relinquish checks and returns some error code if held</li> | |
10031 <li>it is the agent's responsibility and it is not checked</li> | |
10032 </ul> | |
10033 One of these should be chosen. | |
10034 </issue> | |
10035 </description> | |
10036 <origin>new</origin> | |
10037 <capabilities> | |
10038 </capabilities> | |
10039 <parameters> | |
10040 <param id="capabilities_ptr"> | |
10041 <inptr><struct>jvmtiCapabilities</struct></inptr> | |
10042 <description> | |
10043 Points to the <jvmti/> capabilities to relinquish. | |
10044 </description> | |
10045 </param> | |
10046 </parameters> | |
10047 <errors> | |
10048 </errors> | |
10049 </function> | |
10050 | |
10051 | |
10052 | |
10053 <function id="GetCapabilities" jkernel="yes" phase="any" num="89"> | |
10054 <synopsis>Get Capabilities</synopsis> | |
10055 <description> | |
10056 Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/> | |
10057 features which this environment currently possesses. | |
10058 Each possessed capability is indicated by a one (<code>1</code>) in the | |
10059 corresponding field of the <internallink id="jvmtiCapabilities">capabilities | |
10060 structure</internallink>. | |
10061 An environment does not possess a capability unless it has been successfully added with | |
10062 <functionlink id="AddCapabilities"/>. | |
10063 An environment only loses possession of a capability if it has been relinquished with | |
10064 <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result | |
10065 of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which | |
10066 have been made. | |
10067 <p/> | |
10068 See the | |
10069 <internallink id="capabilityExamples">Capability Examples</internallink>. | |
10070 </description> | |
10071 <origin>jvmdiClone</origin> | |
10072 <capabilities> | |
10073 </capabilities> | |
10074 <parameters> | |
10075 <param id="capabilities_ptr"> | |
10076 <outptr><struct>jvmtiCapabilities</struct></outptr> | |
10077 <description> | |
10078 On return, points to the <jvmti/> capabilities. | |
10079 </description> | |
10080 </param> | |
10081 </parameters> | |
10082 <errors> | |
10083 </errors> | |
10084 </function> | |
10085 | |
10086 </category> | |
10087 | |
10088 | |
10089 <category id="timers" label="Timers"> | |
10090 | |
10091 <intro> | |
10092 These functions provide timing information. | |
10093 The resolution at which the time is updated is not specified. | |
10094 They provides nanosecond precision, but not necessarily nanosecond accuracy. | |
10095 Details about the timers, such as their maximum values, can be accessed with | |
10096 the timer information functions. | |
10097 </intro> | |
10098 | |
10099 <typedef id="jvmtiTimerInfo" label="Timer Info"> | |
10100 <description> | |
10101 The information function for each timer returns this data structure. | |
10102 </description> | |
10103 <field id="max_value"> | |
10104 <jlong/> | |
10105 <description> | |
10106 The maximum value the timer can reach. | |
10107 After this value is reached the timer wraps back to zero. | |
10108 This is an unsigned value. If tested or printed as a jlong (signed value) | |
10109 it may appear to be a negative number. | |
10110 </description> | |
10111 </field> | |
10112 <field id="may_skip_forward"> | |
10113 <jboolean/> | |
10114 <description> | |
10115 If true, the timer can be externally adjusted and as a result skip forward. | |
10116 If false, the timer value will never increase faster than real time. | |
10117 </description> | |
10118 </field> | |
10119 <field id="may_skip_backward"> | |
10120 <jboolean/> | |
10121 <description> | |
10122 If true, the timer can be externally adjusted and as a result skip backward. | |
10123 If false, the timer value will be monotonically increasing. | |
10124 </description> | |
10125 </field> | |
10126 <field id="kind"> | |
10127 <enum>jvmtiTimerKind</enum> | |
10128 <description> | |
10129 The kind of timer. | |
10130 On a platform that does not distinguish between user and system time, <datalink | |
10131 id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink> | |
10132 is returned. | |
10133 </description> | |
10134 </field> | |
10135 <field id="reserved1"> | |
10136 <jlong/> | |
10137 <description> | |
10138 Reserved for future use. | |
10139 </description> | |
10140 </field> | |
10141 <field id="reserved2"> | |
10142 <jlong/> | |
10143 <description> | |
10144 Reserved for future use. | |
10145 </description> | |
10146 </field> | |
10147 </typedef> | |
10148 | |
10149 <intro> | |
10150 Where the timer kind is -- | |
10151 | |
10152 <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum"> | |
10153 <constant id="JVMTI_TIMER_USER_CPU" num="30"> | |
10154 CPU time that a thread is in user mode. | |
10155 </constant> | |
10156 <constant id="JVMTI_TIMER_TOTAL_CPU" num="31"> | |
10157 CPU time that a thread is in user or system mode. | |
10158 </constant> | |
10159 <constant id="JVMTI_TIMER_ELAPSED" num="32"> | |
10160 Elapsed time. | |
10161 </constant> | |
10162 </constants> | |
10163 </intro> | |
10164 | |
10165 <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe" impl="innative notrace" phase="start" num="134"> | |
10166 <synopsis>Get Current Thread CPU Timer Information</synopsis> | |
10167 <description> | |
10168 Get information about the | |
10169 <functionlink id="GetCurrentThreadCpuTime"/> timer. | |
10170 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
10171 are filled in with details about the timer. | |
10172 This information is specific to the platform and the implementation of | |
10173 <functionlink id="GetCurrentThreadCpuTime"/> and thus | |
10174 does not vary by thread nor does it vary | |
10175 during a particular invocation of the VM. | |
10176 <p/> | |
10177 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> | |
10178 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values | |
10179 returned by <code>GetCurrentThreadCpuTimerInfo</code> | |
10180 and <functionlink id="GetThreadCpuTimerInfo"/> | |
10181 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. | |
10182 </description> | |
10183 <origin>new</origin> | |
10184 <capabilities> | |
10185 <required id="can_get_current_thread_cpu_time"> | |
10186 Can get current thread CPU time. | |
10187 </required> | |
10188 </capabilities> | |
10189 <parameters> | |
10190 <param id="info_ptr"> | |
10191 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
10192 <description> | |
10193 On return, filled with information describing the time | |
10194 returned by <functionlink id="GetCurrentThreadCpuTime"/>. | |
10195 </description> | |
10196 </param> | |
10197 </parameters> | |
10198 <errors> | |
10199 </errors> | |
10200 </function> | |
10201 | |
10202 <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135"> | |
10203 <synopsis>Get Current Thread CPU Time</synopsis> | |
10204 <description> | |
10205 Return the CPU time utilized by the current thread. | |
10206 <p/> | |
10207 Note that the <functionlink id="GetThreadCpuTime"/> | |
10208 function provides CPU time for any thread, including | |
10209 the current thread. <code>GetCurrentThreadCpuTime</code> | |
10210 exists to support platforms which cannot | |
10211 supply CPU time for threads other than the current | |
10212 thread or which have more accurate information for | |
10213 the current thread (see | |
10214 <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs | |
10215 <functionlink id="GetThreadCpuTimerInfo"/>). | |
10216 On many platforms this call will be equivalent to: | |
10217 <example> | |
10218 GetThreadCpuTime(env, NULL, nanos_ptr) | |
10219 </example> | |
10220 </description> | |
10221 <origin>new</origin> | |
10222 <capabilities> | |
10223 <required id="can_get_current_thread_cpu_time"> | |
10224 Can get current thread CPU time. | |
10225 <p/> | |
10226 If this capability is enabled after threads have started, | |
10227 the implementation may choose any time up | |
10228 to and including the time that the capability is enabled | |
10229 as the point where CPU time collection starts. | |
10230 <p/> | |
10231 This capability must be potentially available on any | |
10232 platform where | |
10233 <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink> | |
10234 is potentially available. | |
10235 </required> | |
10236 </capabilities> | |
10237 <parameters> | |
10238 <param id="nanos_ptr"> | |
10239 <outptr><jlong/></outptr> | |
10240 <description> | |
10241 On return, points to the CPU time used by this thread | |
10242 in nanoseconds. | |
10243 This is an unsigned value. If tested or printed as a jlong (signed value) | |
10244 it may appear to be a negative number. | |
10245 </description> | |
10246 </param> | |
10247 </parameters> | |
10248 <errors> | |
10249 </errors> | |
10250 </function> | |
10251 | |
10252 <function id="GetThreadCpuTimerInfo" num="136"> | |
10253 <synopsis>Get Thread CPU Timer Information</synopsis> | |
10254 <description> | |
10255 Get information about the | |
10256 <functionlink id="GetThreadCpuTime"/> timer. | |
10257 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
10258 are filled in with details about the timer. | |
10259 This information is specific to the platform and the implementation of | |
10260 <functionlink id="GetThreadCpuTime"/> and thus | |
10261 does not vary by thread nor does it vary | |
10262 during a particular invocation of the VM. | |
10263 <p/> | |
10264 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> | |
10265 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values | |
10266 returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/> | |
10267 and <code>GetThreadCpuTimerInfo</code> | |
10268 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. | |
10269 </description> | |
10270 <origin>new</origin> | |
10271 <capabilities> | |
10272 <required id="can_get_thread_cpu_time"> | |
10273 Can get thread CPU time. | |
10274 </required> | |
10275 </capabilities> | |
10276 <parameters> | |
10277 <param id="info_ptr"> | |
10278 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
10279 <description> | |
10280 On return, filled with information describing the time | |
10281 returned by <functionlink id="GetThreadCpuTime"/>. | |
10282 </description> | |
10283 </param> | |
10284 </parameters> | |
10285 <errors> | |
10286 </errors> | |
10287 </function> | |
10288 | |
10289 <function id="GetThreadCpuTime" num="137"> | |
10290 <synopsis>Get Thread CPU Time</synopsis> | |
10291 <description> | |
10292 Return the CPU time utilized by the specified thread. | |
10293 <p/> | |
10294 Get information about this timer with | |
10295 <functionlink id="GetThreadCpuTimerInfo"/>. | |
10296 </description> | |
10297 <origin>new</origin> | |
10298 <capabilities> | |
10299 <required id="can_get_thread_cpu_time"> | |
10300 Can get thread CPU time. | |
10301 <p/> | |
10302 If this capability is enabled after threads have started, | |
10303 the implementation may choose any time up | |
10304 to and including the time that the capability is enabled | |
10305 as the point where CPU time collection starts. | |
10306 </required> | |
10307 </capabilities> | |
10308 <parameters> | |
10309 <param id="thread"> | |
10310 <jthread null="current"/> | |
10311 <description> | |
10312 The thread to query. | |
10313 </description> | |
10314 </param> | |
10315 <param id="nanos_ptr"> | |
10316 <outptr><jlong/></outptr> | |
10317 <description> | |
10318 On return, points to the CPU time used by the specified thread | |
10319 in nanoseconds. | |
10320 This is an unsigned value. If tested or printed as a jlong (signed value) | |
10321 it may appear to be a negative number. | |
10322 </description> | |
10323 </param> | |
10324 </parameters> | |
10325 <errors> | |
10326 </errors> | |
10327 </function> | |
10328 | |
10329 <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138"> | |
10330 <synopsis>Get Timer Information</synopsis> | |
10331 <description> | |
10332 Get information about the | |
10333 <functionlink id="GetTime"/> timer. | |
10334 The fields of the <datalink id="jvmtiTimerInfo"/> structure | |
10335 are filled in with details about the timer. | |
10336 This information will not change during a particular invocation of the VM. | |
10337 </description> | |
10338 <origin>new</origin> | |
10339 <capabilities> | |
10340 </capabilities> | |
10341 <parameters> | |
10342 <param id="info_ptr"> | |
10343 <outptr><struct>jvmtiTimerInfo</struct></outptr> | |
10344 <description> | |
10345 On return, filled with information describing the time | |
10346 returned by <functionlink id="GetTime"/>. | |
10347 </description> | |
10348 </param> | |
10349 </parameters> | |
10350 <errors> | |
10351 </errors> | |
10352 </function> | |
10353 | |
10354 <function id="GetTime" phase="any" callbacksafe="safe" num="139"> | |
10355 <synopsis>Get Time</synopsis> | |
10356 <description> | |
10357 Return the current value of the system timer, in nanoseconds. | |
10358 <p/> | |
10359 The value returned represents nanoseconds since some fixed but | |
10360 arbitrary time (perhaps in the future, so values may be | |
10361 negative). This function provides nanosecond precision, but not | |
10362 necessarily nanosecond accuracy. No guarantees are made about | |
10363 how frequently values change. | |
10364 <p/> | |
10365 Get information about this timer with | |
10366 <functionlink id="GetTimerInfo"/>. | |
10367 </description> | |
10368 <origin>new</origin> | |
10369 <capabilities> | |
10370 </capabilities> | |
10371 <parameters> | |
10372 <param id="nanos_ptr"> | |
10373 <outptr><jlong/></outptr> | |
10374 <description> | |
10375 On return, points to the time in nanoseconds. | |
10376 This is an unsigned value. If tested or printed as a jlong (signed value) | |
10377 it may appear to be a negative number. | |
10378 </description> | |
10379 </param> | |
10380 </parameters> | |
10381 <errors> | |
10382 </errors> | |
10383 </function> | |
10384 | |
10385 <function id="GetAvailableProcessors" phase="any" num="144"> | |
10386 <synopsis>Get Available Processors</synopsis> | |
10387 <description> | |
10388 Returns the number of processors available to the Java virtual machine. | |
10389 <p/> | |
10390 This value may change during a particular invocation of the virtual machine. | |
10391 Applications that are sensitive to the number of available processors should | |
10392 therefore occasionally poll this property. | |
10393 </description> | |
10394 <origin>new</origin> | |
10395 <capabilities> | |
10396 </capabilities> | |
10397 <parameters> | |
10398 <param id="processor_count_ptr"> | |
10399 <outptr><jint/></outptr> | |
10400 <description> | |
10401 On return, points to the maximum number of processors available to the | |
10402 virtual machine; never smaller than one. | |
10403 </description> | |
10404 </param> | |
10405 </parameters> | |
10406 <errors> | |
10407 </errors> | |
10408 </function> | |
10409 | |
10410 </category> | |
10411 | |
10412 | |
10413 <category id="classLoaderSearch" label="Class Loader Search"> | |
10414 | |
10415 <intro> | |
10416 These functions allow the agent to add to the locations that a class loader searches for a class. | |
10417 This is useful for installing instrumentation under the correct class loader. | |
10418 </intro> | |
10419 | |
10420 <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149"> | |
10421 <synopsis>Add To Bootstrap Class Loader Search</synopsis> | |
10422 <description> | |
10423 This function can be used to cause instrumentation classes to be defined by the | |
10424 bootstrap class loader. See | |
10425 <vmspeclink id="ConstantPool.doc.html#79383" | |
10426 name="Loading Using the Bootstrap Class Loader" | |
10427 preposition="in"/>. | |
10428 After the bootstrap | |
10429 class loader unsuccessfully searches for a class, the specified platform-dependent | |
10430 search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in | |
10431 the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, | |
10432 the segments will be searched in the order that this function was called. | |
10433 <p/> | |
10434 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent | |
10435 search path segment to be searched after the bootstrap class loader unsuccessfully searches | |
10436 for a class. The segment is typically a directory or JAR file. | |
10437 <p/> | |
10438 In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent | |
10439 path to a <externallink id="http://java.sun.com/javase/6/docs/guide/jar/jar.html"> | |
10440 JAR file</externallink>. The agent should take care that the JAR file does not | |
10441 contain any classes or resources other than those to be defined by the bootstrap | |
10442 class loader for the purposes of instrumentation. | |
10443 <p/> | |
10444 The <vmspeclink/> specifies that a subsequent attempt to resolve a symbolic | |
10445 reference that the Java virtual machine has previously unsuccessfully attempted | |
10446 to resolve always fails with the same error that was thrown as a result of the | |
10447 initial resolution attempt. Consequently, if the JAR file contains an entry | |
10448 that corresponds to a class for which the Java virtual machine has | |
10449 unsuccessfully attempted to resolve a reference, then subsequent attempts to | |
10450 resolve that reference will fail with the same error as the initial attempt. | |
10451 </description> | |
10452 <origin>new</origin> | |
10453 <capabilities> | |
10454 </capabilities> | |
10455 <parameters> | |
10456 <param id="segment"> | |
10457 <inbuf><char/></inbuf> | |
10458 <description> | |
10459 The platform-dependent search path segment, encoded as a | |
10460 <internallink id="mUTF">modified UTF-8</internallink> string. | |
10461 </description> | |
10462 </param> | |
10463 </parameters> | |
10464 <errors> | |
10465 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
10466 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an | |
10467 existing JAR file is an invalid path. | |
10468 </error> | |
10469 </errors> | |
10470 </function> | |
10471 | |
10472 <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1"> | |
10473 <synopsis>Add To System Class Loader Search</synopsis> | |
10474 <description> | |
10475 This function can be used to cause instrumentation classes to be | |
10476 defined by the system class loader. See | |
10477 <vmspeclink id="ConstantPool.doc.html#79441" | |
10478 name="Loading Using a User-defined Class Loader" | |
10479 preposition="in"/>. | |
10480 After the class loader unsuccessfully searches for a class, the specified platform-dependent search | |
10481 path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the | |
10482 <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the | |
10483 segments will be searched in the order that this function was called. | |
10484 <p/> | |
10485 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent | |
10486 search path segment to be searched after the system class loader unsuccessfully searches | |
10487 for a class. The segment is typically a directory or JAR file. | |
10488 <p/> | |
10489 In the live phase the <paramlink id="segment"/> is a platform-dependent path to a <externallink | |
10490 id="http://java.sun.com/javase/6/docs/guide/jar/jar.html">JAR file</externallink> to be | |
10491 searched after the system class loader unsuccessfully searches for a class. The agent should | |
10492 take care that the JAR file does not contain any classes or resources other than those to be | |
10493 defined by the system class loader for the purposes of instrumentation. | |
10494 <p/> | |
10495 In the live phase the system class loader supports adding a JAR file to be searched if | |
10496 the system class loader implements a method name <code>appendToClassPathForInstrumentation</code> | |
10497 which takes a single parameter of type <code>java.lang.String</code>. The method is not required | |
10498 to have <code>public</code> access. | |
10499 <p/> | |
10500 The <vmspeclink/> specifies that a subsequent attempt to resolve a symbolic | |
10501 reference that the Java virtual machine has previously unsuccessfully attempted | |
10502 to resolve always fails with the same error that was thrown as a result of the | |
10503 initial resolution attempt. Consequently, if the JAR file contains an entry | |
10504 that corresponds to a class for which the Java virtual machine has | |
10505 unsuccessfully attempted to resolve a reference, then subsequent attempts to | |
10506 resolve that reference will fail with the same error as the initial attempt. | |
10507 </description> | |
10508 <origin>new</origin> | |
10509 <capabilities> | |
10510 </capabilities> | |
10511 <parameters> | |
10512 <param id="segment"> | |
10513 <inbuf><char/></inbuf> | |
10514 <description> | |
10515 The platform-dependent search path segment, encoded as a | |
10516 <internallink id="mUTF">modified UTF-8</internallink> string. | |
10517 </description> | |
10518 </param> | |
10519 </parameters> | |
10520 <errors> | |
10521 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> | |
10522 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an | |
10523 existing JAR file is an invalid path. | |
10524 </error> | |
10525 <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED"> | |
10526 Operation not supported by the system class loader. | |
10527 </error> | |
10528 </errors> | |
10529 </function> | |
10530 | |
10531 </category> | |
10532 | |
10533 | |
10534 <category id="props" label="System Properties"> | |
10535 | |
10536 <intro> | |
10537 These functions get and set system properties. | |
10538 </intro> | |
10539 | |
10540 <function id="GetSystemProperties" phase="onload" num="130"> | |
10541 <synopsis>Get System Properties</synopsis> | |
10542 <description> | |
10543 The list of VM system property keys which may be used with | |
10544 <functionlink id="GetSystemProperty"/> is returned. | |
10545 It is strongly recommended that virtual machines provide the | |
10546 following property keys: | |
10547 <ul> | |
10548 <li><code>java.vm.vendor</code></li> | |
10549 <li><code>java.vm.version</code></li> | |
10550 <li><code>java.vm.name</code></li> | |
10551 <li><code>java.vm.info</code></li> | |
10552 <li><code>java.library.path</code></li> | |
10553 <li><code>java.class.path</code></li> | |
10554 </ul> | |
10555 Provides access to system properties defined by and used | |
10556 by the VM. | |
10557 Properties set on the command-line are included. | |
10558 This allows getting and setting of these properties | |
10559 before the VM even begins executing bytecodes. | |
10560 Since this is a VM view of system properties, the set of available | |
10561 properties will usually be different than that | |
10562 in <code>java.lang.System.getProperties</code>. | |
10563 JNI method invocation may be used to access | |
10564 <code>java.lang.System.getProperties</code>. | |
10565 <p/> | |
10566 The set of properties may grow during execution. | |
10567 </description> | |
10568 <origin>new</origin> | |
10569 <capabilities> | |
10570 </capabilities> | |
10571 <parameters> | |
10572 <param id="count_ptr"> | |
10573 <outptr><jint/></outptr> | |
10574 <description> | |
10575 On return, points to the number of property keys returned. | |
10576 </description> | |
10577 </param> | |
10578 <param id="property_ptr"> | |
10579 <allocallocbuf outcount="count_ptr"><char/></allocallocbuf> | |
10580 <description> | |
10581 On return, points to an array of property keys, encoded as | |
10582 <internallink id="mUTF">modified UTF-8</internallink> strings. | |
10583 </description> | |
10584 </param> | |
10585 </parameters> | |
10586 <errors> | |
10587 </errors> | |
10588 </function> | |
10589 | |
10590 <function id="GetSystemProperty" phase="onload" num="131"> | |
10591 <synopsis>Get System Property</synopsis> | |
10592 <description> | |
10593 Return a VM system property value given the property key. | |
10594 <p/> | |
10595 The function <functionlink id="GetSystemProperties"/> | |
10596 returns the set of property keys which may be used. | |
10597 The properties which can be retrieved may grow during | |
10598 execution. | |
10599 <p/> | |
10600 Since this is a VM view of system properties, the values | |
10601 of properties may differ from that returned by | |
10602 <code>java.lang.System.getProperty(String)</code>. | |
10603 A typical VM might copy the values of the VM system | |
10604 properties into the <code>Properties</code> held by | |
10605 <code>java.lang.System</code> during the initialization | |
10606 of that class. Thereafter any changes to the VM system | |
10607 properties (with <functionlink id="SetSystemProperty"/>) | |
10608 or the <code>java.lang.System</code> system properties | |
10609 (with <code>java.lang.System.setProperty(String,String)</code>) | |
10610 would cause the values to diverge. | |
10611 JNI method invocation may be used to access | |
10612 <code>java.lang.System.getProperty(String)</code>. | |
10613 </description> | |
10614 <origin>new</origin> | |
10615 <capabilities> | |
10616 </capabilities> | |
10617 <parameters> | |
10618 <param id="property"> | |
10619 <inbuf><char/></inbuf> | |
10620 <description> | |
10621 The key of the property to retrieve, encoded as a | |
10622 <internallink id="mUTF">modified UTF-8</internallink> string. | |
10623 </description> | |
10624 </param> | |
10625 <param id="value_ptr"> | |
10626 <allocbuf><char/></allocbuf> | |
10627 <description> | |
10628 On return, points to the property value, encoded as a | |
10629 <internallink id="mUTF">modified UTF-8</internallink> string. | |
10630 </description> | |
10631 </param> | |
10632 </parameters> | |
10633 <errors> | |
10634 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
10635 This property is not available. | |
10636 Use <functionlink id="GetSystemProperties"/> to find available properties. | |
10637 </error> | |
10638 </errors> | |
10639 </function> | |
10640 | |
10641 <function id="SetSystemProperty" phase="onloadOnly" num="132"> | |
10642 <synopsis>Set System Property</synopsis> | |
10643 <description> | |
10644 Set a VM system property value. | |
10645 <p/> | |
10646 The function <functionlink id="GetSystemProperties"/> | |
10647 returns the set of property keys, some of these may be settable. | |
10648 See <functionlink id="GetSystemProperty"/>. | |
10649 </description> | |
10650 <origin>new</origin> | |
10651 <capabilities> | |
10652 </capabilities> | |
10653 <parameters> | |
10654 <param id="property"> | |
10655 <inbuf><char/></inbuf> | |
10656 <description> | |
10657 The key of the property, encoded as a | |
10658 <internallink id="mUTF">modified UTF-8</internallink> string. | |
10659 </description> | |
10660 </param> | |
10661 <param id="value"> | |
10662 <inbuf> | |
10663 <char/> | |
10664 <nullok> | |
10665 do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/> | |
10666 if the property is not writeable | |
10667 </nullok> | |
10668 </inbuf> | |
10669 <description> | |
10670 The property value to set, encoded as a | |
10671 <internallink id="mUTF">modified UTF-8</internallink> string. | |
10672 </description> | |
10673 </param> | |
10674 </parameters> | |
10675 <errors> | |
10676 <error id="JVMTI_ERROR_NOT_AVAILABLE"> | |
10677 This property is not available or is not writeable. | |
10678 </error> | |
10679 </errors> | |
10680 </function> | |
10681 | |
10682 </category> | |
10683 | |
10684 <category id="general" label="General"> | |
10685 | |
10686 <intro> | |
10687 </intro> | |
10688 | |
10689 <function id="GetPhase" jkernel="yes" phase="any" num="133"> | |
10690 <synopsis>Get Phase</synopsis> | |
10691 <description> | |
10692 Return the current phase of VM execution. | |
10693 The phases proceed in sequence: | |
10694 <constants id="jvmtiPhase" label="Phases of execution" kind="enum"> | |
10695 <constant id="JVMTI_PHASE_ONLOAD" num="1"> | |
10696 <code>OnLoad</code> phase: while in the | |
10697 <internallink id="onload"><code>Agent_OnLoad</code></internallink> function. | |
10698 </constant> | |
10699 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2"> | |
10700 Primordial phase: between return from <code>Agent_OnLoad</code> and the | |
10701 <code>VMStart</code> event. | |
10702 </constant> | |
10703 <constant id="JVMTI_PHASE_START" num="6"> | |
10704 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event | |
10705 is sent and until the <code>VMInit</code> event is sent. | |
10706 </constant> | |
10707 <constant id="JVMTI_PHASE_LIVE" num="4"> | |
10708 Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent | |
10709 and until the <eventlink id="VMDeath"></eventlink> event returns. | |
10710 </constant> | |
10711 <constant id="JVMTI_PHASE_DEAD" num="8"> | |
10712 Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after | |
10713 start-up failure. | |
10714 </constant> | |
10715 </constants> | |
10716 In the case of start-up failure the VM will proceed directly to the dead | |
10717 phase skipping intermediate phases and neither a <code>VMInit</code> nor | |
10718 <code>VMDeath</code> event will be sent. | |
10719 <p/> | |
10720 Most <jvmti/> functions operate only in the live phase. | |
10721 The following functions operate in either the <code>OnLoad</code> or live phases: | |
10722 <functionphaselist phase="onload"/> | |
10723 The following functions operate in only the <code>OnLoad</code> phase: | |
10724 <functionphaselist phase="onloadOnly"/> | |
10725 The following functions operate in the start or live phases: | |
10726 <functionphaselist phase="start"/> | |
10727 The following functions operate in any phase: | |
10728 <functionphaselist phase="any"/> | |
10729 JNI functions (except the Invocation API) must only be used in the start or live phases. | |
10730 <p/> | |
10731 Most <jvmti/> events are sent only in the live phase. | |
10732 The following events operate in others phases: | |
10733 <eventphaselist phase="start"/> | |
10734 <eventphaselist phase="any"/> | |
10735 </description> | |
10736 <origin>new</origin> | |
10737 <capabilities> | |
10738 </capabilities> | |
10739 <parameters> | |
10740 <param id="phase_ptr"> | |
10741 <outptr><enum>jvmtiPhase</enum></outptr> | |
10742 <description> | |
10743 On return, points to the phase. | |
10744 </description> | |
10745 </param> | |
10746 </parameters> | |
10747 <errors> | |
10748 </errors> | |
10749 </function> | |
10750 | |
10751 <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127"> | |
10752 <synopsis>Dispose Environment</synopsis> | |
10753 <description> | |
10754 Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code> | |
10755 (see <internallink id="environments"><jvmti/> Environments</internallink>). | |
10756 Dispose of any resources held by the environment. | |
10757 <issue> | |
10758 What resources are reclaimed? What is undone? | |
10759 Breakpoints,watchpoints removed? | |
10760 </issue> | |
10761 Threads suspended by this environment are not resumed by this call, | |
10762 this must be done explicitly by the agent. | |
10763 Memory allocated by this environment via calls to <jvmti/> functions | |
10764 is not released, this can be done explicitly by the agent | |
10765 by calling <functionlink id="Deallocate"/>. | |
10766 Raw monitors created by this environment are not destroyed, | |
10767 this can be done explicitly by the agent | |
10768 by calling <functionlink id="DestroyRawMonitor"/>. | |
10769 The state of threads waiting on raw monitors created by this environment | |
10770 are not affected. | |
10771 <p/> | |
10772 Any <functionlink id="SetNativeMethodPrefix">native method | |
10773 prefixes</functionlink> for this environment will be unset; | |
10774 the agent must remove any prefixed native methods before | |
10775 dispose is called. | |
10776 <p/> | |
10777 Any <internallink id="capability">capabilities</internallink> | |
10778 held by this environment are relinquished. | |
10779 <p/> | |
10780 Events enabled by this environment will no longer be sent, however | |
10781 event handlers currently running will continue to run. Caution must | |
10782 be exercised in the design of event handlers whose environment may | |
10783 be disposed and thus become invalid during their execution. | |
10784 <p/> | |
10785 This environment may not be used after this call. | |
10786 This call returns to the caller. | |
10787 </description> | |
10788 <origin>new</origin> | |
10789 <capabilities> | |
10790 </capabilities> | |
10791 <parameters> | |
10792 </parameters> | |
10793 <errors> | |
10794 </errors> | |
10795 </function> | |
10796 | |
10797 <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148"> | |
10798 <synopsis>Set Environment Local Storage</synopsis> | |
10799 <description> | |
10800 The VM stores a pointer value associated with each environment. | |
10801 This pointer value is called <i>environment-local storage</i>. | |
10802 This value is <code>NULL</code> unless set with this function. | |
10803 Agents can allocate memory in which they store environment specific | |
10804 information. By setting environment-local storage it can then be | |
10805 accessed with | |
10806 <functionlink id="GetEnvironmentLocalStorage"></functionlink>. | |
10807 <p/> | |
10808 Called by the agent to set the value of the <jvmti/> | |
10809 environment-local storage. <jvmti/> supplies to the agent a pointer-size | |
10810 environment-local storage that can be used to record per-environment | |
10811 information. | |
10812 </description> | |
10813 <origin>new</origin> | |
10814 <capabilities> | |
10815 </capabilities> | |
10816 <parameters> | |
10817 <param id="data"> | |
10818 <inbuf> | |
10819 <void/> | |
10820 <nullok>value is set to <code>NULL</code></nullok> | |
10821 </inbuf> | |
10822 <description> | |
10823 The value to be entered into the environment-local storage. | |
10824 </description> | |
10825 </param> | |
10826 </parameters> | |
10827 <errors> | |
10828 </errors> | |
10829 </function> | |
10830 | |
10831 <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147"> | |
10832 <synopsis>Get Environment Local Storage</synopsis> | |
10833 <description> | |
10834 Called by the agent to get the value of the <jvmti/> environment-local | |
10835 storage. | |
10836 </description> | |
10837 <origin>new</origin> | |
10838 <capabilities> | |
10839 </capabilities> | |
10840 <parameters> | |
10841 <param id="data_ptr"> | |
10842 <agentbuf><void/></agentbuf> | |
10843 <description> | |
10844 Pointer through which the value of the environment local | |
10845 storage is returned. | |
10846 If environment-local storage has not been set with | |
10847 <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned | |
10848 pointer is <code>NULL</code>. | |
10849 </description> | |
10850 </param> | |
10851 </parameters> | |
10852 <errors> | |
10853 </errors> | |
10854 </function> | |
10855 | |
10856 <function id="GetVersionNumber" jkernel="yes" phase="any" num="88"> | |
10857 <synopsis>Get Version Number</synopsis> | |
10858 <description> | |
10859 Return the <jvmti/> version via <code>version_ptr</code>. | |
10860 The return value is the version identifier. | |
10861 The version identifier includes major, minor and micro | |
10862 version as well as the interface type. | |
10863 <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits"> | |
10864 <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000"> | |
10865 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI. | |
10866 </constant> | |
10867 <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000"> | |
10868 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>. | |
10869 </constant> | |
10870 </constants> | |
10871 <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits"> | |
10872 <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000"> | |
10873 Mask to extract interface type. | |
10874 The value of the version returned by this function masked with | |
10875 <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always | |
10876 <code>JVMTI_VERSION_INTERFACE_JVMTI</code> | |
10877 since this is a <jvmti/> function. | |
10878 </constant> | |
10879 <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000"> | |
10880 Mask to extract major version number. | |
10881 </constant> | |
10882 <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00"> | |
10883 Mask to extract minor version number. | |
10884 </constant> | |
10885 <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF"> | |
10886 Mask to extract micro version number. | |
10887 </constant> | |
10888 </constants> | |
10889 <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits"> | |
10890 <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16"> | |
10891 Shift to extract major version number. | |
10892 </constant> | |
10893 <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8"> | |
10894 Shift to extract minor version number. | |
10895 </constant> | |
10896 <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0"> | |
10897 Shift to extract micro version number. | |
10898 </constant> | |
10899 </constants> | |
10900 </description> | |
10901 <origin>jvmdi</origin> | |
10902 <capabilities> | |
10903 </capabilities> | |
10904 <parameters> | |
10905 <param id="version_ptr"> | |
10906 <outptr><jint/></outptr> | |
10907 <description> | |
10908 On return, points to the <jvmti/> version. | |
10909 </description> | |
10910 </param> | |
10911 </parameters> | |
10912 <errors> | |
10913 </errors> | |
10914 </function> | |
10915 | |
10916 | |
10917 <function id="GetErrorName" phase="any" num="128"> | |
10918 <synopsis>Get Error Name</synopsis> | |
10919 <description> | |
10920 Return the symbolic name for an | |
10921 <internallink id="ErrorSection">error code</internallink>. | |
10922 <p/> | |
10923 For example | |
10924 <code>GetErrorName(env, JVMTI_ERROR_NONE, &err_name)</code> | |
10925 would return in <code>err_name</code> the string | |
10926 <code>"JVMTI_ERROR_NONE"</code>. | |
10927 </description> | |
10928 <origin>new</origin> | |
10929 <capabilities> | |
10930 </capabilities> | |
10931 <parameters> | |
10932 <param id="error"> | |
10933 <enum>jvmtiError</enum> | |
10934 <description> | |
10935 The error code. | |
10936 </description> | |
10937 </param> | |
10938 <param id="name_ptr"> | |
10939 <allocbuf><char/></allocbuf> | |
10940 <description> | |
10941 On return, points to the error name. | |
10942 The name is encoded as a | |
10943 <internallink id="mUTF">modified UTF-8</internallink> string, | |
10944 but is restricted to the ASCII subset. | |
10945 </description> | |
10946 </param> | |
10947 </parameters> | |
10948 <errors> | |
10949 </errors> | |
10950 </function> | |
10951 | |
10952 <function id="SetVerboseFlag" phase="any" num="150"> | |
10953 <synopsis>Set Verbose Flag</synopsis> | |
10954 <description> | |
10955 <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum"> | |
10956 <constant id="JVMTI_VERBOSE_OTHER" num="0"> | |
10957 Verbose output other than the below. | |
10958 </constant> | |
10959 <constant id="JVMTI_VERBOSE_GC" num="1"> | |
10960 Verbose garbage collector output, like that specified with <code>-verbose:gc</code>. | |
10961 </constant> | |
10962 <constant id="JVMTI_VERBOSE_CLASS" num="2"> | |
10963 Verbose class loading output, like that specified with <code>-verbose:class</code>. | |
10964 </constant> | |
10965 <constant id="JVMTI_VERBOSE_JNI" num="4"> | |
10966 Verbose JNI output, like that specified with <code>-verbose:jni</code>. | |
10967 </constant> | |
10968 </constants> | |
10969 Control verbose output. | |
10970 This is the output which typically is sent to <code>stderr</code>. | |
10971 </description> | |
10972 <origin>new</origin> | |
10973 <capabilities> | |
10974 </capabilities> | |
10975 <parameters> | |
10976 <param id="flag"> | |
10977 <enum>jvmtiVerboseFlag</enum> | |
10978 <description> | |
10979 Which verbose flag to set. | |
10980 </description> | |
10981 </param> | |
10982 <param id="value"> | |
10983 <jboolean/> | |
10984 <description> | |
10985 New value of the flag. | |
10986 </description> | |
10987 </param> | |
10988 </parameters> | |
10989 <errors> | |
10990 </errors> | |
10991 </function> | |
10992 | |
10993 | |
10994 <function id="GetJLocationFormat" phase="any" num="129"> | |
10995 <synopsis>Get JLocation Format</synopsis> | |
10996 <description> | |
10997 Although the greatest functionality is achieved with location information | |
10998 referencing the virtual machine bytecode index, the definition of | |
10999 <code>jlocation</code> has intentionally been left unconstrained to allow VM | |
11000 implementations that do not have this information. | |
11001 <p/> | |
11002 This function describes the representation of <code>jlocation</code> used in this VM. | |
11003 If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>, | |
11004 <code>jlocation</code>s can | |
11005 be used as in indices into the array returned by | |
11006 <functionlink id="GetBytecodes"></functionlink>. | |
11007 <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum"> | |
11008 <constant id="JVMTI_JLOCATION_JVMBCI" num="1"> | |
11009 <code>jlocation</code> values represent virtual machine | |
11010 bytecode indices--that is, offsets into the | |
11011 virtual machine code for a method. | |
11012 </constant> | |
11013 <constant id="JVMTI_JLOCATION_MACHINEPC" num="2"> | |
11014 <code>jlocation</code> values represent native machine | |
11015 program counter values. | |
11016 </constant> | |
11017 <constant id="JVMTI_JLOCATION_OTHER" num="0"> | |
11018 <code>jlocation</code> values have some other representation. | |
11019 </constant> | |
11020 </constants> | |
11021 </description> | |
11022 <origin>new</origin> | |
11023 <capabilities> | |
11024 </capabilities> | |
11025 <parameters> | |
11026 <param id="format_ptr"> | |
11027 <outptr><enum>jvmtiJlocationFormat</enum></outptr> | |
11028 <description> | |
11029 On return, points to the format identifier for <code>jlocation</code> values. | |
11030 </description> | |
11031 </param> | |
11032 </parameters> | |
11033 <errors> | |
11034 </errors> | |
11035 </function> | |
11036 | |
11037 </category> | |
11038 | |
11039 </functionsection> | |
11040 | |
11041 <errorsection label="Error Reference"> | |
11042 <intro> | |
11043 Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code. | |
11044 <p/> | |
11045 It is the responsibility of the agent to call <jvmti/> functions with | |
11046 valid parameters and in the proper context (calling thread is attached, | |
11047 phase is correct, etc.). | |
11048 Detecting some error conditions may be difficult, inefficient, or | |
11049 impossible for an implementation. | |
11050 The errors listed in | |
11051 <internallink id="reqerrors">Function Specific Required Errors</internallink> | |
11052 must be detected by the implementation. | |
11053 All other errors represent the recommended response to the error | |
11054 condition. | |
11055 </intro> | |
11056 | |
11057 <errorcategory id="universal-error" label="Universal Errors"> | |
11058 <intro> | |
11059 The following errors may be returned by any function | |
11060 </intro> | |
11061 | |
11062 <errorid id="JVMTI_ERROR_NONE" num="0"> | |
11063 No error has occurred. This is the error code that is returned | |
11064 on successful completion of the function. | |
11065 </errorid> | |
11066 <errorid id="JVMTI_ERROR_NULL_POINTER" num="100"> | |
11067 Pointer is unexpectedly <code>NULL</code>. | |
11068 </errorid> | |
11069 <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110"> | |
11070 The function attempted to allocate memory and no more memory was | |
11071 available for allocation. | |
11072 </errorid> | |
11073 <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111"> | |
11074 The desired functionality has not been enabled in this virtual machine. | |
11075 </errorid> | |
11076 <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115"> | |
11077 The thread being used to call this function is not attached | |
11078 to the virtual machine. Calls must be made from attached threads. | |
11079 See <code>AttachCurrentThread</code> in the JNI invocation API. | |
11080 </errorid> | |
11081 <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116"> | |
11082 The <jvmti/> environment provided is no longer connected or is | |
11083 not an environment. | |
11084 </errorid> | |
11085 <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112"> | |
11086 The desired functionality is not available in the current | |
11087 <functionlink id="GetPhase">phase</functionlink>. | |
11088 Always returned if the virtual machine has completed running. | |
11089 </errorid> | |
11090 <errorid id="JVMTI_ERROR_INTERNAL" num="113"> | |
11091 An unexpected internal error has occurred. | |
11092 </errorid> | |
11093 </errorcategory> | |
11094 | |
11095 <errorcategory id="reqerrors" label="Function Specific Required Errors"> | |
11096 <intro> | |
11097 The following errors are returned by some <jvmti/> functions and must | |
11098 be returned by the implementation when the condition occurs. | |
11099 </intro> | |
11100 | |
11101 <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12"> | |
11102 Invalid priority. | |
11103 </errorid> | |
11104 <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13"> | |
11105 Thread was not suspended. | |
11106 </errorid> | |
11107 <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14"> | |
11108 Thread already suspended. | |
11109 </errorid> | |
11110 <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15"> | |
11111 This operation requires the thread to be alive--that is, | |
11112 it must be started and not yet have died. | |
11113 </errorid> | |
11114 <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22"> | |
11115 The class has been loaded but not yet prepared. | |
11116 </errorid> | |
11117 <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31"> | |
11118 There are no Java programming language or JNI stack frames at the specified depth. | |
11119 </errorid> | |
11120 <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32"> | |
11121 Information about the frame is not available (e.g. for native frames). | |
11122 </errorid> | |
11123 <errorid id="JVMTI_ERROR_DUPLICATE" num="40"> | |
11124 Item already set. | |
11125 </errorid> | |
11126 <errorid id="JVMTI_ERROR_NOT_FOUND" num="41"> | |
11127 Desired element (e.g. field or breakpoint) not found | |
11128 </errorid> | |
11129 <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51"> | |
11130 This thread doesn't own the raw monitor. | |
11131 </errorid> | |
11132 <errorid id="JVMTI_ERROR_INTERRUPT" num="52"> | |
11133 The call has been interrupted before completion. | |
11134 </errorid> | |
11135 <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79"> | |
11136 The class cannot be modified. | |
11137 </errorid> | |
11138 <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98"> | |
11139 The functionality is not available in this virtual machine. | |
11140 </errorid> | |
11141 <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101"> | |
11142 The requested information is not available. | |
11143 </errorid> | |
11144 <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102"> | |
11145 The specified event type ID is not recognized. | |
11146 </errorid> | |
11147 <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104"> | |
11148 The requested information is not available for native method. | |
11149 </errorid> | |
11150 <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106"> | |
11151 The class loader does not support this operation. | |
11152 </errorid> | |
11153 </errorcategory> | |
11154 | |
11155 <errorcategory id="function-specific-errors" label="Function Specific Agent Errors"> | |
11156 <intro> | |
11157 The following errors are returned by some <jvmti/> functions. | |
11158 They are returned in the event of invalid parameters passed by the | |
11159 agent or usage in an invalid context. | |
11160 An implementation is not required to detect these errors. | |
11161 </intro> | |
11162 | |
11163 <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10"> | |
11164 The passed thread is not a valid thread. | |
11165 </errorid> | |
11166 <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25"> | |
11167 Invalid field. | |
11168 </errorid> | |
11169 <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23"> | |
11170 Invalid method. | |
11171 </errorid> | |
11172 <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24"> | |
11173 Invalid location. | |
11174 </errorid> | |
11175 <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20"> | |
11176 Invalid object. | |
11177 </errorid> | |
11178 <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21"> | |
11179 Invalid class. | |
11180 </errorid> | |
11181 <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34"> | |
11182 The variable is not an appropriate type for the function used. | |
11183 </errorid> | |
11184 <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35"> | |
11185 Invalid slot. | |
11186 </errorid> | |
11187 <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99"> | |
11188 The capability being used is false in this environment. | |
11189 </errorid> | |
11190 <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11"> | |
11191 Thread group invalid. | |
11192 </errorid> | |
11193 <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50"> | |
11194 Invalid raw monitor. | |
11195 </errorid> | |
11196 <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103"> | |
11197 Illegal argument. | |
11198 </errorid> | |
11199 <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65"> | |
11200 The state of the thread has been modified, and is now inconsistent. | |
11201 </errorid> | |
11202 <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68"> | |
11203 A new class file has a version number not supported by this VM. | |
11204 </errorid> | |
11205 <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60"> | |
11206 A new class file is malformed (the VM would return a <code>ClassFormatError</code>). | |
11207 </errorid> | |
11208 <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61"> | |
11209 The new class file definitions would lead to a circular | |
11210 definition (the VM would return a <code>ClassCircularityError</code>). | |
11211 </errorid> | |
11212 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63"> | |
11213 A new class file would require adding a method. | |
11214 </errorid> | |
11215 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64"> | |
11216 A new class version changes a field. | |
11217 </errorid> | |
11218 <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62"> | |
11219 The class bytes fail verification. | |
11220 </errorid> | |
11221 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66"> | |
11222 A direct superclass is different for the new class | |
11223 version, or the set of directly implemented | |
11224 interfaces is different. | |
11225 </errorid> | |
11226 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67"> | |
11227 A new class version does not declare a method | |
11228 declared in the old class version. | |
11229 </errorid> | |
11230 <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69"> | |
11231 The class name defined in the new class file is | |
11232 different from the name in the old class object. | |
11233 </errorid> | |
11234 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70"> | |
11235 A new class version has different modifiers. | |
11236 </errorid> | |
11237 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71"> | |
11238 A method in the new class version has different modifiers | |
11239 than its counterpart in the old class version. | |
11240 </errorid> | |
11241 </errorcategory> | |
11242 </errorsection> | |
11243 | |
11244 <eventsection label="Events"> | |
11245 <intro label="Handling Events" id="eventIntro"> | |
11246 Agents can be informed of many events that occur in application | |
11247 programs. | |
11248 <p/> | |
11249 To handle events, designate a set of callback functions with | |
11250 <functionlink id="SetEventCallbacks"></functionlink>. | |
11251 For each event the corresponding callback function will be | |
11252 called. | |
11253 Arguments to the callback function provide additional | |
11254 information about the event. | |
11255 <p/> | |
11256 The callback function is usually called from within an application | |
11257 thread. The <jvmti/> implementation does not | |
11258 queue events in any way. This means | |
11259 that event callback functions must be written | |
11260 carefully. Here are some general guidelines. See | |
11261 the individual event descriptions for further | |
11262 suggestions. | |
11263 <p/> | |
11264 <ul> | |
11265 <li>Any exception thrown during the execution of an event callback can | |
11266 overwrite any current pending exception in the current application thread. | |
11267 Care must be taken to preserve a pending exception | |
11268 when an event callback makes a JNI call that might generate an exception. | |
11269 </li> | |
11270 <li>Event callback functions must be re-entrant. The <jvmti/> implementation does | |
11271 not queue events. If an agent needs to process events one at a time, it | |
11272 can use a raw monitor inside the | |
11273 event callback functions to serialize event processing. | |
11274 </li> | |
11275 <li>Event callback functions that execute JNI's FindClass function to load | |
11276 classes need to note that FindClass locates the class loader associated | |
11277 with the current native method. For the purposes of class loading, an | |
11278 event callback that includes a JNI environment as a parameter to the | |
11279 callback will treated as if it is a native call, where the native method | |
11280 is in the class of the event thread's current frame. | |
11281 </li> | |
11282 </ul> | |
11283 <p/> | |
11284 Some <jvmti/> events identify objects with JNI references. | |
11285 All references | |
11286 in <jvmti/> events are JNI local references and will become invalid | |
11287 after the event callback returns. | |
11288 Unless stated otherwise, memory referenced by pointers sent in event | |
11289 callbacks may not be referenced after the event callback returns. | |
11290 <p/> | |
11291 Except where stated otherwise, events are delivered on the thread | |
11292 that caused the event. | |
11293 Events are sent at the time they occur. | |
11294 The specification for each event includes the set of | |
11295 <functionlink id="GetPhase">phases</functionlink> in which it can be sent; | |
11296 if an event triggering activity occurs during another phase, no event | |
11297 is sent. | |
11298 <p/> | |
11299 A thread that generates an event does not change its execution status | |
11300 (for example, the event does not cause the thread to be suspended). | |
11301 If an agent wishes the event to result in suspension, then the agent | |
11302 is responsible for explicitly suspending the thread with | |
11303 <functionlink id="SuspendThread"></functionlink>. | |
11304 <p/> | |
11305 If an event is enabled in multiple environments, the event will be sent | |
11306 to each agent in the order that the environments were created. | |
11307 </intro> | |
11308 | |
11309 <intro label="Enabling Events" id="enablingevents"> | |
11310 All events are initially disabled. In order to receive any | |
11311 event: | |
11312 <ul> | |
11313 <li> | |
11314 If the event requires a capability, that capability must | |
11315 be added with | |
11316 <functionlink id="AddCapabilities"></functionlink>. | |
11317 </li> | |
11318 <li> | |
11319 A callback for the event must be set with | |
11320 <functionlink id="SetEventCallbacks"></functionlink>. | |
11321 </li> | |
11322 <li> | |
11323 The event must be enabled with | |
11324 <functionlink id="SetEventNotificationMode"></functionlink>. | |
11325 </li> | |
11326 </ul> | |
11327 </intro> | |
11328 | |
11329 <intro label="Multiple Co-located Events" id="eventorder"> | |
11330 In many situations it is possible for multiple events to occur | |
11331 at the same location in one thread. When this happens, all the events | |
11332 are reported through the event callbacks in the order specified in this section. | |
11333 <p/> | |
11334 If the current location is at the entry point of a method, the | |
11335 <eventlink id="MethodEntry"></eventlink> event is reported before | |
11336 any other event at the current location in the same thread. | |
11337 <p/> | |
11338 If an exception catch has been detected at the current location, | |
11339 either because it is the beginning of a catch clause or a native method | |
11340 that cleared a pending exception has returned, the | |
11341 <code>exceptionCatch</code> event is reported before | |
11342 any other event at the current location in the same thread. | |
11343 <p/> | |
11344 If a <code>singleStep</code> event or | |
11345 <code>breakpoint</code> event is triggered at the | |
11346 current location, the event is defined to occur | |
11347 immediately before the code at the current location is executed. | |
11348 These events are reported before any events which are triggered | |
11349 by the execution of code at the current location in the same | |
11350 thread (specifically: | |
11351 <code>exception</code>, | |
11352 <code>fieldAccess</code>, and | |
11353 <code>fieldModification</code>). | |
11354 If both a step and breakpoint event are triggered for the same thread and | |
11355 location, the step event is reported before the breakpoint event. | |
11356 <p/> | |
11357 If the current location is the exit point of a method (that is, the last | |
11358 location before returning to the caller), the | |
11359 <eventlink id="MethodExit"></eventlink> event and | |
11360 the <eventlink id="FramePop"></eventlink> event (if requested) | |
11361 are reported after all other events at the current location in the same | |
11362 thread. There is no specified ordering of these two events | |
11363 with respect to each other. | |
11364 <p/> | |
11365 Co-located events can be triggered during the processing of some other | |
11366 event by the agent at the same location in the same thread. | |
11367 If such an event, of type <i>y</i>, is triggered during the processing of | |
11368 an event of type <i>x</i>, and if <i>x</i> | |
11369 precedes <i>y</i> in the ordering specified above, the co-located event | |
11370 <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede | |
11371 <i>y</i>, <i>y</i> is not reported for the current thread and location. | |
11372 For example, if a breakpoint is set at the current location | |
11373 during the processing of <eventlink id="SingleStep"></eventlink>, | |
11374 that breakpoint will be reported before the thread moves off the current | |
11375 location. | |
11376 <p/>The following events are never considered to be co-located with | |
11377 other events. | |
11378 <ul> | |
11379 <li><eventlink id="VMStart"></eventlink></li> | |
11380 <li><eventlink id="VMInit"></eventlink></li> | |
11381 <li><eventlink id="VMDeath"></eventlink></li> | |
11382 <li><eventlink id="ThreadStart"></eventlink></li> | |
11383 <li><eventlink id="ThreadEnd"></eventlink></li> | |
11384 <li><eventlink id="ClassLoad"></eventlink></li> | |
11385 <li><eventlink id="ClassPrepare"></eventlink></li> | |
11386 </ul> | |
11387 </intro> | |
11388 | |
11389 <intro label="Event Callbacks" id="jvmtiEventCallbacks"> | |
11390 The event callback structure below is used to specify the handler function | |
11391 for events. It is set with the | |
11392 <functionlink id="SetEventCallbacks"></functionlink> function. | |
11393 </intro> | |
11394 | |
11395 <event label="Single Step" | |
11396 id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60"> | |
11397 <description> | |
11398 Single step events allow the agent to trace thread execution | |
11399 at the finest granularity allowed by the VM. A single step event is | |
11400 generated whenever a thread reaches a new location. | |
11401 Typically, single step events represent the completion of one VM | |
11402 instruction as defined in the <vmspeclink/>. However, some implementations | |
11403 may define locations differently. In any case the | |
11404 <code>method</code> and <code>location</code> | |
11405 parameters uniquely identify the current location and allow | |
11406 the mapping to source file and line number when that information is | |
11407 available. | |
11408 <p/> | |
11409 No single step events are generated from within native methods. | |
11410 </description> | |
11411 <origin>jvmdi</origin> | |
11412 <capabilities> | |
11413 <required id="can_generate_single_step_events"></required> | |
11414 </capabilities> | |
11415 <parameters> | |
11416 <param id="jni_env"> | |
11417 <outptr> | |
11418 <struct>JNIEnv</struct> | |
11419 </outptr> | |
11420 <description> | |
11421 The JNI environment of the event (current) thread | |
11422 </description> | |
11423 </param> | |
11424 <param id="thread"> | |
11425 <jthread/> | |
11426 <description> | |
11427 Thread about to execution a new instruction | |
11428 </description> | |
11429 </param> | |
11430 <param id="klass"> | |
11431 <jclass method="method"/> | |
11432 <description> | |
11433 Class of the method about to execute a new instruction | |
11434 </description> | |
11435 </param> | |
11436 <param id="method"> | |
11437 <jmethodID class="klass"/> | |
11438 <description> | |
11439 Method about to execute a new instruction | |
11440 </description> | |
11441 </param> | |
11442 <param id="location"> | |
11443 <jlocation/> | |
11444 <description> | |
11445 Location of the new instruction | |
11446 </description> | |
11447 </param> | |
11448 </parameters> | |
11449 </event> | |
11450 | |
11451 <event label="Breakpoint" | |
11452 id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62"> | |
11453 <description> | |
11454 Breakpoint events are generated whenever a thread reaches a location | |
11455 designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>. | |
11456 The <code>method</code> and <code>location</code> | |
11457 parameters uniquely identify the current location and allow | |
11458 the mapping to source file and line number when that information is | |
11459 available. | |
11460 </description> | |
11461 <origin>jvmdi</origin> | |
11462 <capabilities> | |
11463 <required id="can_generate_breakpoint_events"></required> | |
11464 </capabilities> | |
11465 <parameters> | |
11466 <param id="jni_env"> | |
11467 <outptr> | |
11468 <struct>JNIEnv</struct> | |
11469 </outptr> | |
11470 <description> | |
11471 The JNI environment of the event (current) thread. | |
11472 </description> | |
11473 </param> | |
11474 <param id="thread"> | |
11475 <jthread/> | |
11476 <description> | |
11477 Thread that hit the breakpoint | |
11478 </description> | |
11479 </param> | |
11480 <param id="klass"> | |
11481 <jclass method="method"/> | |
11482 <description> | |
11483 Class of the method that hit the breakpoint | |
11484 </description> | |
11485 </param> | |
11486 <param id="method"> | |
11487 <jmethodID class="klass"/> | |
11488 <description> | |
11489 Method that hit the breakpoint | |
11490 </description> | |
11491 </param> | |
11492 <param id="location"> | |
11493 <jlocation/> | |
11494 <description> | |
11495 location of the breakpoint | |
11496 </description> | |
11497 </param> | |
11498 </parameters> | |
11499 </event> | |
11500 | |
11501 <event label="Field Access" | |
11502 id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63"> | |
11503 <description> | |
11504 Field access events are generated whenever a thread accesses | |
11505 a field that was designated as a watchpoint | |
11506 with <functionlink id="SetFieldAccessWatch"></functionlink>. | |
11507 The <code>method</code> and <code>location</code> | |
11508 parameters uniquely identify the current location and allow | |
11509 the mapping to source file and line number when that information is | |
11510 available. | |
11511 </description> | |
11512 <origin>jvmdi</origin> | |
11513 <capabilities> | |
11514 <required id="can_generate_field_access_events"></required> | |
11515 </capabilities> | |
11516 <parameters> | |
11517 <param id="jni_env"> | |
11518 <outptr> | |
11519 <struct>JNIEnv</struct> | |
11520 </outptr> | |
11521 <description> | |
11522 The JNI environment of the event (current) thread | |
11523 </description> | |
11524 </param> | |
11525 <param id="thread"> | |
11526 <jthread/> | |
11527 <description> | |
11528 Thread accessing the field | |
11529 </description> | |
11530 </param> | |
11531 <param id="klass"> | |
11532 <jclass method="method"/> | |
11533 <description> | |
11534 Class of the method where the access is occurring | |
11535 </description> | |
11536 </param> | |
11537 <param id="method"> | |
11538 <jmethodID class="klass"/> | |
11539 <description> | |
11540 Method where the access is occurring | |
11541 </description> | |
11542 </param> | |
11543 <param id="location"> | |
11544 <jlocation/> | |
11545 <description> | |
11546 Location where the access is occurring | |
11547 </description> | |
11548 </param> | |
11549 <param id="field_klass"> | |
11550 <jclass field="field"/> | |
11551 <description> | |
11552 Class of the field being accessed | |
11553 </description> | |
11554 </param> | |
11555 <param id="object"> | |
11556 <jobject/> | |
11557 <description> | |
11558 Object with the field being accessed if the field is an | |
11559 instance field; <code>NULL</code> otherwise | |
11560 </description> | |
11561 </param> | |
11562 <param id="field"> | |
11563 <jfieldID class="field_klass"/> | |
11564 <description> | |
11565 Field being accessed | |
11566 </description> | |
11567 </param> | |
11568 </parameters> | |
11569 </event> | |
11570 | |
11571 <event label="Field Modification" | |
11572 id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64"> | |
11573 <description> | |
11574 Field modification events are generated whenever a thread modifies | |
11575 a field that was designated as a watchpoint | |
11576 with <functionlink id="SetFieldModificationWatch"></functionlink>. | |
11577 The <code>method</code> and <code>location</code> | |
11578 parameters uniquely identify the current location and allow | |
11579 the mapping to source file and line number when that information is | |
11580 available. | |
11581 </description> | |
11582 <origin>jvmdi</origin> | |
11583 <capabilities> | |
11584 <required id="can_generate_field_modification_events"></required> | |
11585 </capabilities> | |
11586 <parameters> | |
11587 <param id="jni_env"> | |
11588 <outptr> | |
11589 <struct>JNIEnv</struct> | |
11590 </outptr> | |
11591 <description> | |
11592 The JNI environment of the event (current) thread | |
11593 </description> | |
11594 </param> | |
11595 <param id="thread"> | |
11596 <jthread/> | |
11597 <description> | |
11598 Thread modifying the field | |
11599 </description> | |
11600 </param> | |
11601 <param id="klass"> | |
11602 <jclass method="method"/> | |
11603 <description> | |
11604 Class of the method where the modification is occurring | |
11605 </description> | |
11606 </param> | |
11607 <param id="method"> | |
11608 <jmethodID class="klass"/> | |
11609 <description> | |
11610 Method where the modification is occurring | |
11611 </description> | |
11612 </param> | |
11613 <param id="location"> | |
11614 <jlocation/> | |
11615 <description> | |
11616 Location where the modification is occurring | |
11617 </description> | |
11618 </param> | |
11619 <param id="field_klass"> | |
11620 <jclass field="field"/> | |
11621 <description> | |
11622 Class of the field being modified | |
11623 </description> | |
11624 </param> | |
11625 <param id="object"> | |
11626 <jobject/> | |
11627 <description> | |
11628 Object with the field being modified if the field is an | |
11629 instance field; <code>NULL</code> otherwise | |
11630 </description> | |
11631 </param> | |
11632 <param id="field"> | |
11633 <jfieldID class="field_klass"/> | |
11634 <description> | |
11635 Field being modified | |
11636 </description> | |
11637 </param> | |
11638 <param id="signature_type"> | |
11639 <char/> | |
11640 <description> | |
11641 Signature type of the new value | |
11642 </description> | |
11643 </param> | |
11644 <param id="new_value"> | |
11645 <jvalue/> | |
11646 <description> | |
11647 The new value | |
11648 </description> | |
11649 </param> | |
11650 </parameters> | |
11651 </event> | |
11652 | |
11653 <event label="Frame Pop" | |
11654 id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61"> | |
11655 <description> | |
11656 Frame pop events are generated upon exit from a single method | |
11657 in a single frame as specified | |
11658 in a call to <functionlink id="NotifyFramePop"></functionlink>. | |
11659 This is true whether termination is caused by | |
11660 executing its return instruction | |
11661 or by throwing an exception to its caller | |
11662 (see <paramlink id="was_popped_by_exception"></paramlink>). | |
11663 However, frame pops caused by the <functionlink id="PopFrame"/> | |
11664 function are not reported. | |
11665 <p/> | |
11666 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
11667 identifies the executable location in the returning method, | |
11668 immediately prior to the return. | |
11669 </description> | |
11670 <origin>jvmdi</origin> | |
11671 <capabilities> | |
11672 <required id="can_generate_frame_pop_events"></required> | |
11673 </capabilities> | |
11674 <parameters> | |
11675 <param id="jni_env"> | |
11676 <outptr> | |
11677 <struct>JNIEnv</struct> | |
11678 </outptr> | |
11679 <description> | |
11680 The JNI environment of the event (current) thread | |
11681 </description> | |
11682 </param> | |
11683 <param id="thread"> | |
11684 <jthread/> | |
11685 <description> | |
11686 Thread that is popping the frame | |
11687 </description> | |
11688 </param> | |
11689 <param id="klass"> | |
11690 <jclass method="method"/> | |
11691 <description> | |
11692 Class of the method being popped | |
11693 </description> | |
11694 </param> | |
11695 <param id="method"> | |
11696 <jmethodID class="klass"/> | |
11697 <description> | |
11698 Method being popped | |
11699 </description> | |
11700 </param> | |
11701 <param id="was_popped_by_exception"> | |
11702 <jboolean/> | |
11703 <description> | |
11704 True if frame was popped by a thrown exception. | |
11705 False if method exited through its return instruction. | |
11706 </description> | |
11707 </param> | |
11708 </parameters> | |
11709 </event> | |
11710 | |
11711 <event label="Method Entry" | |
11712 id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65"> | |
11713 <description> | |
11714 Method entry events are generated upon entry of Java | |
11715 programming language methods (including native methods). | |
11716 <p/> | |
11717 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
11718 identifies the initial executable location in | |
11719 the method. | |
11720 <p/> | |
11721 Enabling method | |
11722 entry or exit events will significantly degrade performance on many platforms and is thus | |
11723 not advised for performance critical usage (such as profiling). | |
11724 <internallink id="bci">Bytecode instrumentation</internallink> should be | |
11725 used in these cases. | |
11726 </description> | |
11727 <origin>jvmdi</origin> | |
11728 <capabilities> | |
11729 <required id="can_generate_method_entry_events"></required> | |
11730 </capabilities> | |
11731 <parameters> | |
11732 <param id="jni_env"> | |
11733 <outptr> | |
11734 <struct>JNIEnv</struct> | |
11735 </outptr> | |
11736 <description> | |
11737 The JNI environment of the event (current) thread | |
11738 </description> | |
11739 </param> | |
11740 <param id="thread"> | |
11741 <jthread/> | |
11742 <description> | |
11743 Thread entering the method | |
11744 </description> | |
11745 </param> | |
11746 <param id="klass"> | |
11747 <jclass method="method"/> | |
11748 <description> | |
11749 Class of the method being entered | |
11750 </description> | |
11751 </param> | |
11752 <param id="method"> | |
11753 <jmethodID class="klass"/> | |
11754 <description> | |
11755 Method being entered | |
11756 </description> | |
11757 </param> | |
11758 </parameters> | |
11759 </event> | |
11760 | |
11761 <event label="Method Exit" | |
11762 id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66"> | |
11763 <description> | |
11764 Method exit events are generated upon exit from Java | |
11765 programming language methods (including native methods). | |
11766 This is true whether termination is caused by | |
11767 executing its return instruction | |
11768 or by throwing an exception to its caller | |
11769 (see <paramlink id="was_popped_by_exception"></paramlink>). | |
11770 <p/> | |
11771 The <code>method</code> field uniquely identifies the | |
11772 method being entered or exited. The <code>frame</code> field provides | |
11773 access to the stack frame for the method. | |
11774 <p/> | |
11775 The location reported by <functionlink id="GetFrameLocation"></functionlink> | |
11776 identifies the executable location in the returning method | |
11777 immediately prior to the return. | |
11778 <p/> | |
11779 Enabling method | |
11780 entry or exit events will significantly degrade performance on many platforms and is thus | |
11781 not advised for performance critical usage (such as profiling). | |
11782 <internallink id="bci">Bytecode instrumentation</internallink> should be | |
11783 used in these cases. | |
11784 </description> | |
11785 <origin>jvmdi</origin> | |
11786 <capabilities> | |
11787 <required id="can_generate_method_exit_events"></required> | |
11788 </capabilities> | |
11789 <parameters> | |
11790 <param id="jni_env"> | |
11791 <outptr> | |
11792 <struct>JNIEnv</struct> | |
11793 </outptr> | |
11794 <description> | |
11795 The JNI environment of the event (current) thread | |
11796 </description> | |
11797 </param> | |
11798 <param id="thread"> | |
11799 <jthread/> | |
11800 <description> | |
11801 Thread exiting the method | |
11802 </description> | |
11803 </param> | |
11804 <param id="klass"> | |
11805 <jclass method="method"/> | |
11806 <description> | |
11807 Class of the method being exited | |
11808 </description> | |
11809 </param> | |
11810 <param id="method"> | |
11811 <jmethodID class="klass"/> | |
11812 <description> | |
11813 Method being exited | |
11814 </description> | |
11815 </param> | |
11816 <param id="was_popped_by_exception"> | |
11817 <jboolean/> | |
11818 <description> | |
11819 True if frame was popped by a thrown exception. | |
11820 False if method exited through its return instruction. | |
11821 </description> | |
11822 </param> | |
11823 <param id="return_value"> | |
11824 <jvalue/> | |
11825 <description> | |
11826 The return value of the method being exited. | |
11827 Undefined and should not be used if | |
11828 <paramlink id="was_popped_by_exception"></paramlink> | |
11829 is true. | |
11830 </description> | |
11831 </param> | |
11832 </parameters> | |
11833 </event> | |
11834 | |
11835 <event label="Native Method Bind" phase="any" | |
11836 id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67"> | |
11837 <description> | |
11838 A Native Method Bind event is sent when a VM binds a | |
11839 Java programming language native method | |
11840 to the address of a function that implements the native method. | |
11841 This will occur when the native method is called for the first time | |
11842 and also occurs when the JNI function <code>RegisterNatives</code> is called. | |
11843 This event allows the bind to be redirected to an agent-specified | |
11844 proxy function. | |
11845 This event is not sent when the native method is unbound. | |
11846 Typically, this proxy function will need to be specific to a | |
11847 particular method or, to handle the general case, automatically | |
11848 generated assembly code, since after instrumentation code is | |
11849 executed the function at the original binding | |
11850 address will usually be invoked. | |
11851 The original binding can be restored or the redirection changed | |
11852 by use of the JNI function <code>RegisterNatives</code>. | |
11853 Some events may be sent during the primordial phase, JNI and | |
11854 most of <jvmti/> cannot be used at this time but the method and | |
11855 address can be saved for use later. | |
11856 </description> | |
11857 <origin>new</origin> | |
11858 <capabilities> | |
11859 <required id="can_generate_native_method_bind_events"></required> | |
11860 </capabilities> | |
11861 <parameters> | |
11862 <param id="jni_env"> | |
11863 <outptr> | |
11864 <struct>JNIEnv</struct> | |
11865 </outptr> | |
11866 <description> | |
11867 The JNI environment of the event (current) thread | |
11868 Will be <code>NULL</code> if sent during the primordial | |
11869 <functionlink id="GetPhase">phase</functionlink>. | |
11870 </description> | |
11871 </param> | |
11872 <param id="thread"> | |
11873 <jthread/> | |
11874 <description> | |
11875 Thread requesting the bind | |
11876 </description> | |
11877 </param> | |
11878 <param id="klass"> | |
11879 <jclass method="method"/> | |
11880 <description> | |
11881 Class of the method being bound | |
11882 </description> | |
11883 </param> | |
11884 <param id="method"> | |
11885 <jmethodID class="klass"/> | |
11886 <description> | |
11887 Native method being bound | |
11888 </description> | |
11889 </param> | |
11890 <param id="address"> | |
11891 <outptr><void/></outptr> | |
11892 <description> | |
11893 The address the VM is about to bind to--that is, the | |
11894 address of the implementation of the native method | |
11895 </description> | |
11896 </param> | |
11897 <param id="new_address_ptr"> | |
11898 <agentbuf><void/></agentbuf> | |
11899 <description> | |
11900 if the referenced address is changed (that is, if | |
11901 <code>*new_address_ptr</code> is set), the binding | |
11902 will instead be made to the supplied address. | |
11903 </description> | |
11904 </param> | |
11905 </parameters> | |
11906 </event> | |
11907 | |
11908 <event label="Exception" | |
11909 id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58"> | |
11910 <description> | |
11911 Exception events are generated whenever an exception is first detected | |
11912 in a Java programming language method. | |
11913 Where "exception" means any <code>java.lang.Throwable</code>. | |
11914 The exception may have been thrown by a Java programming language or native | |
11915 method, but in the case of native methods, the event is not generated | |
11916 until the exception is first seen by a Java programming language method. If an exception is | |
11917 set and cleared in a native method (and thus is never visible to Java programming language code), | |
11918 no exception event is generated. | |
11919 <p/> | |
11920 The <code>method</code> and <code>location</code> | |
11921 parameters uniquely identify the current location | |
11922 (where the exception was detected) and allow | |
11923 the mapping to source file and line number when that information is | |
11924 available. The <code>exception</code> field identifies the thrown | |
11925 exception object. The <code>catch_method</code> | |
11926 and <code>catch_location</code> identify the location of the catch clause, | |
11927 if any, that handles the thrown exception. If there is no such catch clause, | |
11928 each field is set to 0. There is no guarantee that the thread will ever | |
11929 reach this catch clause. If there are native methods on the call stack | |
11930 between the throw location and the catch clause, the exception may | |
11931 be reset by one of those native methods. | |
11932 Similarly, exceptions that are reported as uncaught (<code>catch_klass</code> | |
11933 et al. set to 0) may in fact be caught by native code. | |
11934 Agents can check for these occurrences by monitoring | |
11935 <eventlink id="ExceptionCatch"></eventlink> events. | |
11936 Note that finally clauses are implemented as catch and re-throw. Therefore they | |
11937 will be reported in the catch location. | |
11938 </description> | |
11939 <origin>jvmdi</origin> | |
11940 <capabilities> | |
11941 <required id="can_generate_exception_events"></required> | |
11942 </capabilities> | |
11943 <parameters> | |
11944 <param id="jni_env"> | |
11945 <outptr> | |
11946 <struct>JNIEnv</struct> | |
11947 </outptr> | |
11948 <description> | |
11949 The JNI environment of the event (current) thread | |
11950 </description> | |
11951 </param> | |
11952 <param id="thread"> | |
11953 <jthread/> | |
11954 <description> | |
11955 Thread generating the exception | |
11956 </description> | |
11957 </param> | |
11958 <param id="klass"> | |
11959 <jclass method="method"/> | |
11960 <description> | |
11961 Class generating the exception | |
11962 </description> | |
11963 </param> | |
11964 <param id="method"> | |
11965 <jmethodID class="klass"/> | |
11966 <description> | |
11967 Method generating the exception | |
11968 </description> | |
11969 </param> | |
11970 <param id="location"> | |
11971 <jlocation/> | |
11972 <description> | |
11973 Location where exception occurred | |
11974 </description> | |
11975 </param> | |
11976 <param id="exception"> | |
11977 <jobject/> | |
11978 <description> | |
11979 The exception being thrown | |
11980 </description> | |
11981 </param> | |
11982 <param id="catch_klass"> | |
11983 <jclass method="catch_method"/> | |
11984 <description> | |
11985 Class that will catch the exception, or <code>NULL</code> if no known catch | |
11986 </description> | |
11987 </param> | |
11988 <param id="catch_method"> | |
11989 <jmethodID class="catch_klass"/> | |
11990 <description> | |
11991 Method that will catch the exception, or <code>NULL</code> if no known catch | |
11992 </description> | |
11993 </param> | |
11994 <param id="catch_location"> | |
11995 <jlocation/> | |
11996 <description> | |
11997 location which will catch the exception or zero if no known catch | |
11998 </description> | |
11999 </param> | |
12000 </parameters> | |
12001 </event> | |
12002 | |
12003 <event label="Exception Catch" | |
12004 id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59"> | |
12005 <description> | |
12006 Exception catch events are generated whenever a thrown exception is caught. | |
12007 Where "exception" means any <code>java.lang.Throwable</code>. | |
12008 If the exception is caught in a Java programming language method, the event is generated | |
12009 when the catch clause is reached. If the exception is caught in a native | |
12010 method, the event is generated as soon as control is returned to a Java programming language | |
12011 method. Exception catch events are generated for any exception for which | |
12012 a throw was detected in a Java programming language method. | |
12013 Note that finally clauses are implemented as catch and re-throw. Therefore they | |
12014 will generate exception catch events. | |
12015 <p/> | |
12016 The <code>method</code> and <code>location</code> | |
12017 parameters uniquely identify the current location | |
12018 and allow the mapping to source file and line number when that information is | |
12019 available. For exceptions caught in a Java programming language method, the | |
12020 <code>exception</code> object identifies the exception object. Exceptions | |
12021 caught in native methods are not necessarily available by the time the | |
12022 exception catch is reported, so the <code>exception</code> field is set | |
12023 to <code>NULL</code>. | |
12024 </description> | |
12025 <origin>jvmdi</origin> | |
12026 <capabilities> | |
12027 <required id="can_generate_exception_events"></required> | |
12028 </capabilities> | |
12029 <parameters> | |
12030 <param id="jni_env"> | |
12031 <outptr> | |
12032 <struct>JNIEnv</struct> | |
12033 </outptr> | |
12034 <description> | |
12035 The JNI environment of the event (current) thread | |
12036 </description> | |
12037 </param> | |
12038 <param id="thread"> | |
12039 <jthread/> | |
12040 <description> | |
12041 Thread catching the exception | |
12042 </description> | |
12043 </param> | |
12044 <param id="klass"> | |
12045 <jclass method="method"/> | |
12046 <description> | |
12047 Class catching the exception | |
12048 </description> | |
12049 </param> | |
12050 <param id="method"> | |
12051 <jmethodID class="klass"/> | |
12052 <description> | |
12053 Method catching the exception | |
12054 </description> | |
12055 </param> | |
12056 <param id="location"> | |
12057 <jlocation/> | |
12058 <description> | |
12059 Location where exception is being caught | |
12060 </description> | |
12061 </param> | |
12062 <param id="exception"> | |
12063 <jobject/> | |
12064 <description> | |
12065 Exception being caught | |
12066 </description> | |
12067 </param> | |
12068 </parameters> | |
12069 </event> | |
12070 | |
12071 <event label="Thread Start" | |
12072 id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start"> | |
12073 <description> | |
12074 Thread start events are generated by a new thread before its initial | |
12075 method executes. | |
12076 <p/> | |
12077 A thread may be listed in the array returned by | |
12078 <functionlink id="GetAllThreads"></functionlink> | |
12079 before its thread start event is generated. | |
12080 It is possible for other events to be generated | |
12081 on a thread before its thread start event. | |
12082 <p/> | |
12083 The event is sent on the newly started <paramlink id="thread"></paramlink>. | |
12084 </description> | |
12085 <origin>jvmdi</origin> | |
12086 <capabilities> | |
12087 </capabilities> | |
12088 <parameters> | |
12089 <param id="jni_env"> | |
12090 <outptr> | |
12091 <struct>JNIEnv</struct> | |
12092 </outptr> | |
12093 <description> | |
12094 The JNI environment of the event (current) thread. | |
12095 </description> | |
12096 </param> | |
12097 <param id="thread"> | |
12098 <jthread/> | |
12099 <description> | |
12100 Thread starting | |
12101 </description> | |
12102 </param> | |
12103 </parameters> | |
12104 </event> | |
12105 | |
12106 <event label="Thread End" | |
12107 id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start"> | |
12108 <description> | |
12109 Thread end events are generated by a terminating thread | |
12110 after its initial method has finished execution. | |
12111 <p/> | |
12112 A thread may be listed in the array returned by | |
12113 <functionlink id="GetAllThreads"></functionlink> | |
12114 after its thread end event is generated. | |
12115 No events are generated on a thread | |
12116 after its thread end event. | |
12117 <p/> | |
12118 The event is sent on the dying <paramlink id="thread"></paramlink>. | |
12119 </description> | |
12120 <origin>jvmdi</origin> | |
12121 <capabilities> | |
12122 </capabilities> | |
12123 <parameters> | |
12124 <param id="jni_env"> | |
12125 <outptr> | |
12126 <struct>JNIEnv</struct> | |
12127 </outptr> | |
12128 <description> | |
12129 The JNI environment of the event (current) thread. | |
12130 </description> | |
12131 </param> | |
12132 <param id="thread"> | |
12133 <jthread/> | |
12134 <description> | |
12135 Thread ending | |
12136 </description> | |
12137 </param> | |
12138 </parameters> | |
12139 </event> | |
12140 | |
12141 <event label="Class Load" | |
12142 id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55"> | |
12143 <description> | |
12144 A class load event is generated when a class is first loaded. The order | |
12145 of class load events generated by a particular thread are guaranteed | |
12146 to match the order of class loading within that thread. | |
12147 Array class creation does not generate a class load event. | |
12148 The creation of a primitive class (for example, java.lang.Integer.TYPE) | |
12149 does not generate a class load event. | |
12150 <p/> | |
12151 This event is sent at an early stage in loading the class. As | |
12152 a result the class should be used carefully. Note, for example, | |
12153 that methods and fields are not yet loaded, so queries for methods, | |
12154 fields, subclasses, and so on will not give correct results. | |
12155 See "Loading of Classes and Interfaces" in the <i>Java Language | |
12156 Specification</i>. For most | |
12157 purposes the <eventlink id="ClassPrepare"></eventlink> event will | |
12158 be more useful. | |
12159 </description> | |
12160 <origin>jvmdi</origin> | |
12161 <capabilities> | |
12162 </capabilities> | |
12163 <parameters> | |
12164 <param id="jni_env"> | |
12165 <outptr> | |
12166 <struct>JNIEnv</struct> | |
12167 </outptr> | |
12168 <description> | |
12169 The JNI environment of the event (current) thread | |
12170 </description> | |
12171 </param> | |
12172 <param id="thread"> | |
12173 <jthread/> | |
12174 <description> | |
12175 Thread loading the class | |
12176 </description> | |
12177 </param> | |
12178 <param id="klass"> | |
12179 <jclass/> | |
12180 <description> | |
12181 Class being loaded | |
12182 </description> | |
12183 </param> | |
12184 </parameters> | |
12185 </event> | |
12186 | |
12187 <elide> | |
12188 <event label="Class Unload" | |
12189 id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57"> | |
12190 <description> | |
12191 A class unload event is generated when the class is about to be unloaded. | |
12192 Class unload events take place during garbage collection and must be | |
12193 handled extremely carefully. The garbage collector holds many locks | |
12194 and has suspended all other threads, so the event handler cannot depend | |
12195 on the ability to acquire any locks. The class unload event handler should | |
12196 do as little as possible, perhaps by queuing information to be processed | |
12197 later. In particular, the <code>jclass</code> should be used only in | |
12198 the JNI function <code>isSameObject</code> or in the following <jvmti/> functions: | |
12199 <ul> | |
12200 <li><functionlink id="GetClassSignature"></functionlink></li> | |
12201 <li><functionlink id="GetSourceFileName"></functionlink></li> | |
12202 <li><functionlink id="IsInterface"></functionlink></li> | |
12203 <li><functionlink id="IsArrayClass"></functionlink></li> | |
12204 </ul> | |
12205 </description> | |
12206 <origin>jvmdi</origin> | |
12207 <capabilities> | |
12208 </capabilities> | |
12209 <parameters> | |
12210 <param id="jni_env"> | |
12211 <outptr> | |
12212 <struct>JNIEnv</struct> | |
12213 </outptr> | |
12214 <description> | |
12215 The JNI environment of the event (current) thread | |
12216 </description> | |
12217 </param> | |
12218 <param id="thread"> | |
12219 <jthread/> | |
12220 <description> | |
12221 Thread generating the class unload | |
12222 </description> | |
12223 </param> | |
12224 <param id="klass"> | |
12225 <jclass/> | |
12226 <description> | |
12227 Class being unloaded | |
12228 </description> | |
12229 </param> | |
12230 </parameters> | |
12231 </event> | |
12232 </elide> | |
12233 | |
12234 <event label="Class Prepare" | |
12235 id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56"> | |
12236 <description> | |
12237 A class prepare event is generated when class preparation is complete. | |
12238 At this point, class fields, methods, and implemented interfaces are | |
12239 available, and no code from the class has been executed. Since array | |
12240 classes never have fields or methods, class prepare events are not | |
12241 generated for them. Class prepare events are not generated for | |
12242 primitive classes (for example, <code>java.lang.Integer.TYPE</code>). | |
12243 </description> | |
12244 <origin>jvmdi</origin> | |
12245 <capabilities> | |
12246 </capabilities> | |
12247 <parameters> | |
12248 <param id="jni_env"> | |
12249 <outptr> | |
12250 <struct>JNIEnv</struct> | |
12251 </outptr> | |
12252 <description> | |
12253 The JNI environment of the event (current) thread | |
12254 </description> | |
12255 </param> | |
12256 <param id="thread"> | |
12257 <jthread/> | |
12258 <description> | |
12259 Thread generating the class prepare | |
12260 </description> | |
12261 </param> | |
12262 <param id="klass"> | |
12263 <jclass/> | |
12264 <description> | |
12265 Class being prepared | |
12266 </description> | |
12267 </param> | |
12268 </parameters> | |
12269 </event> | |
12270 | |
12271 <event label="Class File Load Hook" phase="any" | |
12272 id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54"> | |
12273 <description> | |
12274 This event is sent when the VM obtains class file data, | |
12275 but before it constructs | |
12276 the in-memory representation for that class. | |
12277 This event is also sent when the class is being modified by the | |
12278 <functionlink id="RetransformClasses"/> function or | |
12279 the <functionlink id="RedefineClasses"/> function, | |
12280 called in any <jvmti/> environment. | |
12281 The agent can instrument | |
12282 the existing class file data sent by the VM to include profiling/debugging hooks. | |
12283 See the description of | |
12284 <internallink id="bci">bytecode instrumentation</internallink> | |
12285 for usage information. | |
12286 <p/> | |
12287 This event may be sent before the VM is initialized (the primordial | |
12288 <functionlink id="GetPhase">phase</functionlink>). During this time | |
12289 no VM resources should be created. Some classes might not be compatible | |
12290 with the function (eg. ROMized classes) and this event will not be | |
12291 generated for these classes. | |
12292 <p/> | |
12293 The agent must allocate the space for the modified | |
12294 class file data buffer | |
12295 using the memory allocation function | |
12296 <functionlink id="Allocate"></functionlink> because the | |
12297 VM is responsible for freeing the new class file data buffer | |
12298 using <functionlink id="Deallocate"></functionlink>. | |
12299 Note that <functionlink id="Allocate"></functionlink> | |
12300 is permitted during the primordial phase. | |
12301 <p/> | |
12302 If the agent wishes to modify the class file, it must set | |
12303 <code>new_class_data</code> to point | |
12304 to the newly instrumented class file data buffer and set | |
12305 <code>new_class_data_len</code> to the length of that | |
12306 buffer before returning | |
12307 from this call. If no modification is desired, the agent simply | |
12308 does not set <code>new_class_data</code>. If multiple agents | |
12309 have enabled this event the results are chained. That is, if | |
12310 <code>new_class_data</code> has been set, it becomes the | |
12311 <code>class_data</code> for the next agent. | |
12312 <p/> | |
12313 The order that this event is sent to each environment differs | |
12314 from other events. | |
12315 This event is sent to environments in the following order: | |
12316 <ul> | |
12317 <li><fieldlink id="can_retransform_classes" | |
12318 struct="jvmtiCapabilities">retransformation | |
12319 incapable</fieldlink> | |
12320 environments, in the | |
12321 order in which they were created | |
12322 </li> | |
12323 <li><fieldlink id="can_retransform_classes" | |
12324 struct="jvmtiCapabilities">retransformation | |
12325 capable</fieldlink> | |
12326 environments, in the | |
12327 order in which they were created | |
12328 </li> | |
12329 </ul> | |
12330 When triggered by <functionlink id="RetransformClasses"/>, | |
12331 this event is sent only to <fieldlink id="can_retransform_classes" | |
12332 struct="jvmtiCapabilities">retransformation | |
12333 capable</fieldlink> | |
12334 environments. | |
12335 </description> | |
12336 <origin>jvmpi</origin> | |
12337 <capabilities> | |
12338 <capability id="can_generate_all_class_hook_events"></capability> | |
12339 </capabilities> | |
12340 <parameters> | |
12341 <param id="jni_env"> | |
12342 <outptr> | |
12343 <struct>JNIEnv</struct> | |
12344 </outptr> | |
12345 <description> | |
12346 The JNI environment of the event (current) thread. | |
12347 Will be <code>NULL</code> if sent during the primordial | |
12348 <functionlink id="GetPhase">phase</functionlink>. | |
12349 </description> | |
12350 </param> | |
12351 <param id="class_being_redefined"> | |
12352 <jclass/> | |
12353 <description> | |
12354 The class being | |
12355 <functionlink id="RedefineClasses">redefined</functionlink> or | |
12356 <functionlink id="RetransformClasses">retransformed</functionlink>. | |
12357 <code>NULL</code> if sent by class load. | |
12358 </description> | |
12359 </param> | |
12360 <param id="loader"> | |
12361 <jobject/> | |
12362 <description> | |
12363 The class loader loading the class. | |
12364 <code>NULL</code> if the bootstrap class loader. | |
12365 </description> | |
12366 </param> | |
12367 <param id="name"> | |
12368 <vmbuf><char/></vmbuf> | |
12369 <description> | |
12370 Name of class being loaded as a VM internal qualified name | |
12371 (for example, "java/util/List"), encoded as a | |
12372 <internallink id="mUTF">modified UTF-8</internallink> string. | |
12373 Note: if the class is defined with a <code>NULL</code> name or | |
12374 without a name specified, <code>name</code> will be <code>NULL</code>. | |
12375 </description> | |
12376 </param> | |
12377 <param id="protection_domain"> | |
12378 <jobject/> | |
12379 <description> | |
12380 The <code>ProtectionDomain</code> of the class. | |
12381 </description> | |
12382 </param> | |
12383 <param id="class_data_len"> | |
12384 <jint/> | |
12385 <description> | |
12386 Length of current class file data buffer. | |
12387 </description> | |
12388 </param> | |
12389 <param id="class_data"> | |
12390 <vmbuf><uchar/></vmbuf> | |
12391 <description> | |
12392 Pointer to the current class file data buffer. | |
12393 </description> | |
12394 </param> | |
12395 <param id="new_class_data_len"> | |
12396 <outptr><jint/></outptr> | |
12397 <description> | |
12398 Pointer to the length of the new class file data buffer. | |
12399 </description> | |
12400 </param> | |
12401 <param id="new_class_data"> | |
12402 <agentbuf incount="new_class_data_len"><uchar/></agentbuf> | |
12403 <description> | |
12404 Pointer to the pointer to the instrumented class file data buffer. | |
12405 </description> | |
12406 </param> | |
12407 </parameters> | |
12408 </event> | |
12409 | |
12410 <event label="VM Start Event" | |
12411 id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start"> | |
12412 <description> | |
12413 The VM initialization event signals the start of the VM. | |
12414 At this time JNI is live but the VM is not yet fully initialized. | |
12415 Once this event is generated, the agent is free to call any JNI function. | |
12416 This event signals the beginning of the start phase, | |
12417 <jvmti/> functions permitted in the start phase may be called. | |
12418 <p/> | |
12419 In the case of VM start-up failure, this event will not be sent. | |
12420 </description> | |
12421 <origin>jvmdi</origin> | |
12422 <capabilities> | |
12423 </capabilities> | |
12424 <parameters> | |
12425 <param id="jni_env"> | |
12426 <outptr> | |
12427 <struct>JNIEnv</struct> | |
12428 </outptr> | |
12429 <description> | |
12430 The JNI environment of the event (current) thread. | |
12431 </description> | |
12432 </param> | |
12433 </parameters> | |
12434 </event> | |
12435 | |
12436 <event label="VM Initialization Event" | |
12437 id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50"> | |
12438 <description> | |
12439 The VM initialization event signals the completion of VM initialization. Once | |
12440 this event is generated, the agent is free to call any JNI or <jvmti/> | |
12441 function. The VM initialization event can be preceded by or can be concurrent | |
12442 with other events, but | |
12443 the preceding events should be handled carefully, if at all, because the | |
12444 VM has not completed its initialization. The thread start event for the | |
12445 main application thread is guaranteed not to occur until after the | |
12446 handler for the VM initialization event returns. | |
12447 <p/> | |
12448 In the case of VM start-up failure, this event will not be sent. | |
12449 </description> | |
12450 <origin>jvmdi</origin> | |
12451 <capabilities> | |
12452 </capabilities> | |
12453 <parameters> | |
12454 <param id="jni_env"> | |
12455 <outptr> | |
12456 <struct>JNIEnv</struct> | |
12457 </outptr> | |
12458 <description> | |
12459 The JNI environment of the event (current) thread. | |
12460 </description> | |
12461 </param> | |
12462 <param id="thread"> | |
12463 <jthread/> | |
12464 <description> | |
12465 The initial thread | |
12466 </description> | |
12467 </param> | |
12468 </parameters> | |
12469 </event> | |
12470 | |
12471 <event label="VM Death Event" | |
12472 id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51"> | |
12473 <description> | |
12474 The VM death event notifies the agent of the termination of the VM. | |
12475 No events will occur after the VMDeath event. | |
12476 <p/> | |
12477 In the case of VM start-up failure, this event will not be sent. | |
12478 Note that <internallink id="onunload">Agent_OnUnload</internallink> | |
12479 will still be called in these cases. | |
12480 </description> | |
12481 <origin>jvmdi</origin> | |
12482 <capabilities> | |
12483 </capabilities> | |
12484 <parameters> | |
12485 <param id="jni_env"> | |
12486 <outptr> | |
12487 <struct>JNIEnv</struct> | |
12488 </outptr> | |
12489 <description> | |
12490 The JNI environment of the event (current) thread | |
12491 </description> | |
12492 </param> | |
12493 </parameters> | |
12494 </event> | |
12495 | |
12496 <event label="Compiled Method Load" | |
12497 id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68"> | |
12498 <description> | |
12499 Sent when a method is compiled and loaded into memory by the VM. | |
12500 If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent. | |
12501 If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent, | |
12502 followed by a new <code>CompiledMethodLoad</code> event. | |
12503 Note that a single method may have multiple compiled forms, and that | |
12504 this event will be sent for each form. | |
12505 Note also that several methods may be inlined into a single | |
12506 address range, and that this event will be sent for each method. | |
12507 <p/> | |
12508 These events can be sent after their initial occurrence with | |
12509 <functionlink id="GenerateEvents"></functionlink>. | |
12510 </description> | |
12511 <origin>jvmpi</origin> | |
12512 <typedef id="jvmtiAddrLocationMap" label="Native address to location entry"> | |
12513 <field id="start_address"> | |
12514 <vmbuf><void/></vmbuf> | |
12515 <description> | |
12516 Starting native address of code corresponding to a location | |
12517 </description> | |
12518 </field> | |
12519 <field id="location"> | |
12520 <jlocation/> | |
12521 <description> | |
12522 Corresponding location. See | |
12523 <functionlink id="GetJLocationFormat"></functionlink> | |
12524 for the meaning of location. | |
12525 </description> | |
12526 </field> | |
12527 </typedef> | |
12528 <capabilities> | |
12529 <required id="can_generate_compiled_method_load_events"></required> | |
12530 </capabilities> | |
12531 <parameters> | |
12532 <param id="klass"> | |
12533 <jclass method="method"/> | |
12534 <description> | |
12535 Class of the method being compiled and loaded | |
12536 </description> | |
12537 </param> | |
12538 <param id="method"> | |
12539 <jmethodID class="klass"/> | |
12540 <description> | |
12541 Method being compiled and loaded | |
12542 </description> | |
12543 </param> | |
12544 <param id="code_size"> | |
12545 <jint/> | |
12546 <description> | |
12547 Size of compiled code | |
12548 </description> | |
12549 </param> | |
12550 <param id="code_addr"> | |
12551 <vmbuf><void/></vmbuf> | |
12552 <description> | |
12553 Address where compiled method code is loaded | |
12554 </description> | |
12555 </param> | |
12556 <param id="map_length"> | |
12557 <jint/> | |
12558 <description> | |
12559 Number of <typelink id="jvmtiAddrLocationMap"></typelink> | |
12560 entries in the address map. | |
12561 Zero if mapping information cannot be supplied. | |
12562 </description> | |
12563 </param> | |
12564 <param id="map"> | |
12565 <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf> | |
12566 <description> | |
12567 Map from native addresses to location. | |
12568 The native address range of each entry is from | |
12569 <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink> | |
12570 to <code>start_address-1</code> of the next entry. | |
12571 <code>NULL</code> if mapping information cannot be supplied. | |
12572 </description> | |
12573 </param> | |
12574 <param id="compile_info"> | |
12575 <vmbuf><void/></vmbuf> | |
12576 <description> | |
12577 VM-specific compilation information. | |
12578 The referenced compile information is managed by the VM | |
12579 and must not depend on the agent for collection. | |
12580 A VM implementation defines the content and lifetime | |
12581 of the information. | |
12582 </description> | |
12583 </param> | |
12584 </parameters> | |
12585 </event> | |
12586 | |
12587 <event label="Compiled Method Unload" | |
12588 id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69"> | |
12589 <description> | |
12590 Sent when a compiled method is unloaded from memory. | |
12591 This event might not be sent on the thread which performed the unload. | |
12592 This event may be sent sometime after the unload occurs, but | |
12593 will be sent before the memory is reused | |
12594 by a newly generated compiled method. This event may be sent after | |
12595 the class is unloaded. | |
12596 </description> | |
12597 <origin>jvmpi</origin> | |
12598 <capabilities> | |
12599 <required id="can_generate_compiled_method_load_events"></required> | |
12600 </capabilities> | |
12601 <parameters> | |
12602 <param id="klass"> | |
12603 <jclass method="method"/> | |
12604 <description> | |
12605 Class of the compiled method being unloaded. | |
12606 </description> | |
12607 </param> | |
12608 <param id="method"> | |
12609 <jmethodID class="klass"/> | |
12610 <description> | |
12611 Compiled method being unloaded. | |
12612 For identification of the compiled method only -- the class | |
12613 may be unloaded and therefore the method should not be used | |
12614 as an argument to further JNI or <jvmti/> functions. | |
12615 </description> | |
12616 </param> | |
12617 <param id="code_addr"> | |
12618 <vmbuf><void/></vmbuf> | |
12619 <description> | |
12620 Address where compiled method code was loaded. | |
12621 For identification of the compiled method only -- | |
12622 the space may have been reclaimed. | |
12623 </description> | |
12624 </param> | |
12625 </parameters> | |
12626 </event> | |
12627 | |
12628 <event label="Dynamic Code Generated" phase="any" | |
12629 id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70"> | |
12630 <description> | |
12631 Sent when a component of the virtual machine is generated dynamically. | |
12632 This does not correspond to Java programming language code that is | |
12633 compiled--see <eventlink id="CompiledMethodLoad"></eventlink>. | |
12634 This is for native code--for example, an interpreter that is generated | |
12635 differently depending on command-line options. | |
12636 <p/> | |
12637 Note that this event has no controlling capability. | |
12638 If a VM cannot generate these events, it simply does not send any. | |
12639 <p/> | |
12640 These events can be sent after their initial occurrence with | |
12641 <functionlink id="GenerateEvents"></functionlink>. | |
12642 </description> | |
12643 <origin>jvmpi</origin> | |
12644 <capabilities> | |
12645 </capabilities> | |
12646 <parameters> | |
12647 <param id="name"> | |
12648 <vmbuf><char/></vmbuf> | |
12649 <description> | |
12650 Name of the code, encoded as a | |
12651 <internallink id="mUTF">modified UTF-8</internallink> string. | |
12652 Intended for display to an end-user. | |
12653 The name might not be unique. | |
12654 </description> | |
12655 </param> | |
12656 <param id="address"> | |
12657 <vmbuf><void/></vmbuf> | |
12658 <description> | |
12659 Native address of the code | |
12660 </description> | |
12661 </param> | |
12662 <param id="length"> | |
12663 <jint/> | |
12664 <description> | |
12665 Length in bytes of the code | |
12666 </description> | |
12667 </param> | |
12668 </parameters> | |
12669 </event> | |
12670 | |
12671 <event label="Data Dump Request" | |
12672 id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71"> | |
12673 <description> | |
12674 Sent by the VM to request the agent to dump its data. This | |
12675 is just a hint and the agent need not react to this event. | |
12676 This is useful for processing command-line signals from users. For | |
12677 example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris | |
12678 causes the VM to send this event to the agent. | |
12679 </description> | |
12680 <origin>jvmpi</origin> | |
12681 <capabilities> | |
12682 </capabilities> | |
12683 <parameters> | |
12684 </parameters> | |
12685 </event> | |
12686 | |
12687 <event label="Monitor Contended Enter" | |
12688 id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75"> | |
12689 <description> | |
12690 Sent when a thread is attempting to enter a Java programming language | |
12691 monitor already acquired by another thread. | |
12692 </description> | |
12693 <origin>jvmpi</origin> | |
12694 <capabilities> | |
12695 <required id="can_generate_monitor_events"></required> | |
12696 </capabilities> | |
12697 <parameters> | |
12698 <param id="jni_env"> | |
12699 <outptr> | |
12700 <struct>JNIEnv</struct> | |
12701 </outptr> | |
12702 <description> | |
12703 The JNI environment of the event (current) thread | |
12704 </description> | |
12705 </param> | |
12706 <param id="thread"> | |
12707 <jthread/> | |
12708 <description> | |
12709 JNI local reference to the thread | |
12710 attempting to enter the monitor | |
12711 </description> | |
12712 </param> | |
12713 <param id="object"> | |
12714 <jobject/> | |
12715 <description> | |
12716 JNI local reference to the monitor | |
12717 </description> | |
12718 </param> | |
12719 </parameters> | |
12720 </event> | |
12721 | |
12722 <event label="Monitor Contended Entered" | |
12723 id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76"> | |
12724 <description> | |
12725 Sent when a thread enters a Java programming language | |
12726 monitor after waiting for it to be released by another thread. | |
12727 </description> | |
12728 <origin>jvmpi</origin> | |
12729 <capabilities> | |
12730 <required id="can_generate_monitor_events"></required> | |
12731 </capabilities> | |
12732 <parameters> | |
12733 <param id="jni_env"> | |
12734 <outptr> | |
12735 <struct>JNIEnv</struct> | |
12736 </outptr> | |
12737 <description> | |
12738 The JNI environment of the event (current) thread | |
12739 </description> | |
12740 </param> | |
12741 <param id="thread"> | |
12742 <jthread/> | |
12743 <description> | |
12744 JNI local reference to the thread entering | |
12745 the monitor | |
12746 </description> | |
12747 </param> | |
12748 <param id="object"> | |
12749 <jobject/> | |
12750 <description> | |
12751 JNI local reference to the monitor | |
12752 </description> | |
12753 </param> | |
12754 </parameters> | |
12755 </event> | |
12756 | |
12757 <event label="Monitor Wait" | |
12758 id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73"> | |
12759 <description> | |
12760 Sent when a thread is about to wait on an object. | |
12761 </description> | |
12762 <origin>jvmpi</origin> | |
12763 <capabilities> | |
12764 <required id="can_generate_monitor_events"></required> | |
12765 </capabilities> | |
12766 <parameters> | |
12767 <param id="jni_env"> | |
12768 <outptr> | |
12769 <struct>JNIEnv</struct> | |
12770 </outptr> | |
12771 <description> | |
12772 The JNI environment of the event (current) thread | |
12773 </description> | |
12774 </param> | |
12775 <param id="thread"> | |
12776 <jthread/> | |
12777 <description> | |
12778 JNI local reference to the thread about to wait | |
12779 </description> | |
12780 </param> | |
12781 <param id="object"> | |
12782 <jobject/> | |
12783 <description> | |
12784 JNI local reference to the monitor | |
12785 </description> | |
12786 </param> | |
12787 <param id="timeout"> | |
12788 <jlong/> | |
12789 <description> | |
12790 The number of milliseconds the thread will wait | |
12791 </description> | |
12792 </param> | |
12793 </parameters> | |
12794 </event> | |
12795 | |
12796 <event label="Monitor Waited" | |
12797 id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74"> | |
12798 <description> | |
12799 Sent when a thread finishes waiting on an object. | |
12800 </description> | |
12801 <origin>jvmpi</origin> | |
12802 <capabilities> | |
12803 <required id="can_generate_monitor_events"></required> | |
12804 </capabilities> | |
12805 <parameters> | |
12806 <param id="jni_env"> | |
12807 <outptr> | |
12808 <struct>JNIEnv</struct> | |
12809 </outptr> | |
12810 <description> | |
12811 The JNI environment of the event (current) thread | |
12812 </description> | |
12813 </param> | |
12814 <param id="thread"> | |
12815 <jthread/> | |
12816 <description> | |
12817 JNI local reference to the thread that was finished waiting | |
12818 </description> | |
12819 </param> | |
12820 <param id="object"> | |
12821 <jobject/> | |
12822 <description> | |
12823 JNI local reference to the monitor. | |
12824 </description> | |
12825 </param> | |
12826 <param id="timed_out"> | |
12827 <jboolean/> | |
12828 <description> | |
12829 True if the monitor timed out | |
12830 </description> | |
12831 </param> | |
12832 </parameters> | |
12833 </event> | |
12834 | |
12835 <event label="Resource Exhausted" | |
12836 id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80" | |
12837 since="1.1"> | |
12838 <description> | |
12839 Sent when a VM resource needed by a running application has been exhausted. | |
12840 Except as required by the optional capabilities, the set of resources | |
12841 which report exhaustion is implementation dependent. | |
12842 <p/> | |
12843 The following bit flags define the properties of the resource exhaustion: | |
12844 <constants id="jvmtiResourceExhaustionFlags" | |
12845 label="Resource Exhaustion Flags" | |
12846 kind="bits" | |
12847 since="1.1"> | |
12848 <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001"> | |
12849 After this event returns, the VM will throw a | |
12850 <code>java.lang.OutOfMemoryError</code>. | |
12851 </constant> | |
12852 <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002"> | |
12853 The VM was unable to allocate memory from the <tm>Java</tm> | |
12854 platform <i>heap</i>. | |
12855 The <i>heap</i> is the runtime | |
12856 data area from which memory for all class instances and | |
12857 arrays are allocated. | |
12858 </constant> | |
12859 <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004"> | |
12860 The VM was unable to create a thread. | |
12861 </constant> | |
12862 </constants> | |
12863 </description> | |
12864 <origin>new</origin> | |
12865 <capabilities> | |
12866 <capability id="can_generate_resource_exhaustion_heap_events"> | |
12867 Can generate events when the VM is unable to allocate memory from the | |
12868 <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>. | |
12869 </capability> | |
12870 <capability id="can_generate_resource_exhaustion_threads_events"> | |
12871 Can generate events when the VM is unable to | |
12872 <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create | |
12873 a thread</internallink>. | |
12874 </capability> | |
12875 </capabilities> | |
12876 <parameters> | |
12877 <param id="jni_env"> | |
12878 <outptr> | |
12879 <struct>JNIEnv</struct> | |
12880 </outptr> | |
12881 <description> | |
12882 The JNI environment of the event (current) thread | |
12883 </description> | |
12884 </param> | |
12885 <param id="flags"> | |
12886 <jint/> | |
12887 <description> | |
12888 Flags defining the properties of the of resource exhaustion | |
12889 as specified by the | |
12890 <internallink id="jvmtiResourceExhaustionFlags">Resource | |
12891 Exhaustion Flags</internallink>. | |
12892 </description> | |
12893 </param> | |
12894 <param id="reserved"> | |
12895 <vmbuf><void/></vmbuf> | |
12896 <description> | |
12897 Reserved. | |
12898 </description> | |
12899 </param> | |
12900 <param id="description"> | |
12901 <vmbuf><char/></vmbuf> | |
12902 <description> | |
12903 Description of the resource exhaustion, encoded as a | |
12904 <internallink id="mUTF">modified UTF-8</internallink> string. | |
12905 </description> | |
12906 </param> | |
12907 </parameters> | |
12908 </event> | |
12909 | |
12910 <event label="VM Object Allocation" | |
12911 id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84"> | |
12912 <description> | |
12913 Sent when a method causes the virtual machine to allocate an | |
12914 Object visible to Java programming language code and the | |
12915 allocation is not detectable by other intrumentation mechanisms. | |
12916 Generally object allocation should be detected by instrumenting | |
12917 the bytecodes of allocating methods. | |
12918 Object allocation generated in native code by JNI function | |
12919 calls should be detected using | |
12920 <internallink id="jniIntercept">JNI function interception</internallink>. | |
12921 Some methods might not have associated bytecodes and are not | |
12922 native methods, they instead are executed directly by the | |
12923 VM. These methods should send this event. | |
12924 Virtual machines which are incapable of bytecode instrumentation | |
12925 for some or all of their methods can send this event. | |
12926 <p/> | |
12927 Typical examples where this event might be sent: | |
12928 <ul> | |
12929 <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li> | |
12930 <li>Methods not represented by bytecodes -- for example, VM intrinsics and | |
12931 J2ME preloaded classes</li> | |
12932 </ul> | |
12933 Cases where this event would not be generated: | |
12934 <ul> | |
12935 <li>Allocation due to bytecodes -- for example, the <code>new</code> | |
12936 and <code>newarray</code> VM instructions</li> | |
12937 <li>Allocation due to JNI function calls -- for example, | |
12938 <code>AllocObject</code></li> | |
12939 <li>Allocations during VM initialization</li> | |
12940 <li>VM internal objects</li> | |
12941 </ul> | |
12942 </description> | |
12943 <origin>new</origin> | |
12944 <capabilities> | |
12945 <required id="can_generate_vm_object_alloc_events"></required> | |
12946 </capabilities> | |
12947 <parameters> | |
12948 <param id="jni_env"> | |
12949 <outptr> | |
12950 <struct>JNIEnv</struct> | |
12951 </outptr> | |
12952 <description> | |
12953 The JNI environment of the event (current) thread | |
12954 </description> | |
12955 </param> | |
12956 <param id="thread"> | |
12957 <jthread/> | |
12958 <description> | |
12959 Thread allocating the object. | |
12960 </description> | |
12961 </param> | |
12962 <param id="object"> | |
12963 <jobject/> | |
12964 <description> | |
12965 JNI local reference to the object that was allocated | |
12966 </description> | |
12967 </param> | |
12968 <param id="object_klass"> | |
12969 <jclass/> | |
12970 <description> | |
12971 JNI local reference to the class of the object | |
12972 </description> | |
12973 </param> | |
12974 <param id="size"> | |
12975 <jlong/> | |
12976 <description> | |
12977 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. | |
12978 </description> | |
12979 </param> | |
12980 </parameters> | |
12981 </event> | |
12982 | |
12983 <event label="Object Free" | |
12984 id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83"> | |
12985 <description> | |
12986 An Object Free event is sent when the garbage collector frees an object. | |
12987 Events are only sent for tagged objects--see | |
12988 <internallink id="Heap">heap functions</internallink>. | |
12989 <p/> | |
12990 The event handler must not use JNI functions and | |
12991 must not use <jvmti/> functions except those which | |
12992 specifically allow such use (see the raw monitor, memory management, | |
12993 and environment local storage functions). | |
12994 </description> | |
12995 <origin>new</origin> | |
12996 <capabilities> | |
12997 <required id="can_generate_object_free_events"></required> | |
12998 </capabilities> | |
12999 <parameters> | |
13000 <param id="tag"> | |
13001 <jlong/> | |
13002 <description> | |
13003 The freed object's tag | |
13004 </description> | |
13005 </param> | |
13006 </parameters> | |
13007 </event> | |
13008 | |
13009 <event label="Garbage Collection Start" | |
13010 id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81"> | |
13011 <description> | |
13012 A Garbage Collection Start event is sent when a full cycle | |
13013 garbage collection begins. | |
13014 Only stop-the-world collections are reported--that is, collections during | |
13015 which all threads cease to modify the state of the Java virtual machine. | |
13016 This means that some collectors will never generate these events. | |
13017 This event is sent while the VM is still stopped, thus | |
13018 the event handler must not use JNI functions and | |
13019 must not use <jvmti/> functions except those which | |
13020 specifically allow such use (see the raw monitor, memory management, | |
13021 and environment local storage functions). | |
13022 <p/> | |
13023 This event is always sent as a matched pair with | |
13024 <eventlink id="GarbageCollectionFinish"/> | |
13025 (assuming both events are enabled) and no garbage collection | |
13026 events will occur between them. | |
13027 </description> | |
13028 <origin>new</origin> | |
13029 <capabilities> | |
13030 <required id="can_generate_garbage_collection_events"></required> | |
13031 </capabilities> | |
13032 <parameters> | |
13033 </parameters> | |
13034 </event> | |
13035 | |
13036 <event label="Garbage Collection Finish" | |
13037 id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82"> | |
13038 <description> | |
13039 A Garbage Collection Finish event is sent when a full | |
13040 garbage collection cycle ends. | |
13041 This event is sent while the VM is still stopped, thus | |
13042 the event handler must not use JNI functions and | |
13043 must not use <jvmti/> functions except those which | |
13044 specifically allow such use (see the raw monitor, memory management, | |
13045 and environment local storage functions). | |
13046 <p/> | |
13047 Some agents may need to do post garbage collection operations that | |
13048 require the use of the disallowed <jvmti/> or JNI functions. For these | |
13049 cases an agent thread can be created which waits on a raw monitor, | |
13050 and the handler for the Garbage Collection Finish event simply | |
13051 notifies the raw monitor | |
13052 <p/> | |
13053 This event is always sent as a matched pair with | |
13054 <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled). | |
13055 <issue> | |
13056 The most important use of this event is to provide timing information, | |
13057 and thus additional information is not required. However, | |
13058 information about the collection which is "free" should be included - | |
13059 what that information is needs to be determined. | |
13060 </issue> | |
13061 </description> | |
13062 <origin>new</origin> | |
13063 <capabilities> | |
13064 <required id="can_generate_garbage_collection_events"></required> | |
13065 </capabilities> | |
13066 <parameters> | |
13067 </parameters> | |
13068 </event> | |
13069 | |
13070 <elide> | |
13071 <event label="Verbose Output" phase="any" | |
13072 id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85"> | |
13073 <description> | |
13074 Send verbose messages as strings. | |
13075 <issue> | |
13076 This format is extremely fragile, as it can change with each | |
13077 platform, collector and version. Alternatives include: | |
13078 <ul> | |
13079 <li>building off Java programming language M and M APIs</li> | |
13080 <li>XML</li> | |
13081 <li>key/value pairs</li> | |
13082 <li>removing it</li> | |
13083 </ul> | |
13084 </issue> | |
13085 <issue> | |
13086 Though this seemed trivial to implement. | |
13087 In the RI it appears this will be quite complex. | |
13088 </issue> | |
13089 </description> | |
13090 <origin>new</origin> | |
13091 <capabilities> | |
13092 </capabilities> | |
13093 <parameters> | |
13094 <param id="flag"> | |
13095 <enum>jvmtiVerboseFlag</enum> | |
13096 <description> | |
13097 Which verbose output is being sent. | |
13098 </description> | |
13099 </param> | |
13100 <param id="message"> | |
13101 <vmbuf><char/></vmbuf> | |
13102 <description> | |
13103 Message text, encoded as a | |
13104 <internallink id="mUTF">modified UTF-8</internallink> string. | |
13105 </description> | |
13106 </param> | |
13107 </parameters> | |
13108 </event> | |
13109 </elide> | |
13110 | |
13111 </eventsection> | |
13112 | |
13113 <datasection> | |
13114 <intro> | |
13115 <jvmti/> extends the data types defined by JNI. | |
13116 </intro> | |
13117 <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface"> | |
13118 <basetype id="jboolean"> | |
13119 <description> | |
13120 Holds a Java programming language <code>boolean</code>. | |
13121 Unsigned 8 bits. | |
13122 </description> | |
13123 </basetype> | |
13124 <basetype id="jint"> | |
13125 <description> | |
13126 Holds a Java programming language <code>int</code>. | |
13127 Signed 32 bits. | |
13128 </description> | |
13129 </basetype> | |
13130 <basetype id="jlong"> | |
13131 <description> | |
13132 Holds a Java programming language <code>long</code>. | |
13133 Signed 64 bits. | |
13134 </description> | |
13135 </basetype> | |
13136 <basetype id="jfloat"> | |
13137 <description> | |
13138 Holds a Java programming language <code>float</code>. | |
13139 32 bits. | |
13140 </description> | |
13141 </basetype> | |
13142 <basetype id="jdouble"> | |
13143 <description> | |
13144 Holds a Java programming language <code>double</code>. | |
13145 64 bits. | |
13146 </description> | |
13147 </basetype> | |
13148 <basetype id="jobject"> | |
13149 <description> | |
13150 Holds a Java programming language object. | |
13151 </description> | |
13152 </basetype> | |
13153 <basetype id="jclass"> | |
13154 <description> | |
13155 Holds a Java programming language class. | |
13156 </description> | |
13157 </basetype> | |
13158 <basetype id="jvalue"> | |
13159 <description> | |
13160 Is a union of all primitive types and <code>jobject</code>. Thus, holds any Java | |
13161 programming language value. | |
13162 </description> | |
13163 </basetype> | |
13164 <basetype id="jfieldID"> | |
13165 <description> | |
13166 Identifies a Java programming language field. | |
13167 <code>jfieldID</code>s returned by <jvmti/> functions and events may be | |
13168 safely stored. | |
13169 </description> | |
13170 </basetype> | |
13171 <basetype id="jmethodID"> | |
13172 <description> | |
13173 Identifies a Java programming language method, initializer, or constructor. | |
13174 <code>jmethodID</code>s returned by <jvmti/> functions and events may be | |
13175 safely stored. However, if the class is unloaded, they become invalid | |
13176 and must not be used. | |
13177 </description> | |
13178 </basetype> | |
13179 <basetype id="JNIEnv"> | |
13180 <description> | |
13181 Pointer to the JNI function table. Pointer to this (<code>JNIEnv *</code>) | |
13182 is a JNI environment. | |
13183 </description> | |
13184 </basetype> | |
13185 </basetypes> | |
13186 | |
13187 <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types"> | |
13188 <basetype id="jvmtiEnv"> | |
13189 <description> | |
13190 The <jvmti/> <internallink id="environments">environment</internallink> pointer. | |
13191 See the <internallink id="FunctionSection">Function Section</internallink>. | |
13192 <code>jvmtiEnv</code> points to the | |
13193 <internallink id="FunctionTable">function table</internallink> pointer. | |
13194 </description> | |
13195 </basetype> | |
13196 <basetype id="jthread"> | |
13197 <definition>typedef jobject jthread;</definition> | |
13198 <description> | |
13199 Subtype of <datalink id="jobject"></datalink> that holds a thread. | |
13200 </description> | |
13201 </basetype> | |
13202 <basetype id="jthreadGroup"> | |
13203 <definition>typedef jobject jthreadGroup;</definition> | |
13204 <description> | |
13205 Subtype of <datalink id="jobject"></datalink> that holds a thread group. | |
13206 </description> | |
13207 </basetype> | |
13208 <basetype id="jlocation"> | |
13209 <definition>typedef jlong jlocation;</definition> | |
13210 <description> | |
13211 A 64 bit value, representing a monotonically increasing | |
13212 executable position within a method. | |
13213 <code>-1</code> indicates a native method. | |
13214 See <functionlink id="GetJLocationFormat"></functionlink> for the format on a | |
13215 given VM. | |
13216 </description> | |
13217 </basetype> | |
13218 <basetype id="jrawMonitorID"> | |
13219 <definition>struct _jrawMonitorID; | |
13220 typedef struct _jrawMonitorID *jrawMonitorID;</definition> | |
13221 <description> | |
13222 A raw monitor. | |
13223 </description> | |
13224 </basetype> | |
13225 <basetype id="jvmtiError"> | |
13226 <description> | |
13227 Holds an error return code. | |
13228 See the <internallink id="ErrorSection">Error section</internallink> for possible values. | |
13229 <example> | |
13230 typedef enum { | |
13231 JVMTI_ERROR_NONE = 0, | |
13232 JVMTI_ERROR_INVALID_THREAD = 10, | |
13233 ... | |
13234 } jvmtiError; | |
13235 </example> | |
13236 </description> | |
13237 </basetype> | |
13238 <basetype id="jvmtiEvent"> | |
13239 <description> | |
13240 An identifier for an event type. | |
13241 See the <internallink id="EventSection">Event section</internallink> for possible values. | |
13242 It is guaranteed that future versions of this specification will | |
13243 never assign zero as an event type identifier. | |
13244 <example> | |
13245 typedef enum { | |
13246 JVMTI_EVENT_SINGLE_STEP = 1, | |
13247 JVMTI_EVENT_BREAKPOINT = 2, | |
13248 ... | |
13249 } jvmtiEvent; | |
13250 </example> | |
13251 </description> | |
13252 </basetype> | |
13253 <basetype id="jvmtiEventCallbacks"> | |
13254 <description> | |
13255 The callbacks used for events. | |
13256 <example> | |
13257 typedef struct { | |
13258 jvmtiEventVMInit VMInit; | |
13259 jvmtiEventVMDeath VMDeath; | |
13260 ... | |
13261 } jvmtiEventCallbacks; | |
13262 </example> | |
13263 See <internallink id="jvmtiEventCallbacks">event callbacks</internallink> | |
13264 for the complete structure. | |
13265 <p/> | |
13266 Where, for example, the VM initialization callback is defined: | |
13267 <example> | |
13268 typedef void (JNICALL *jvmtiEventVMInit) | |
13269 (jvmtiEnv *jvmti_env, | |
13270 JNIEnv* jni_env, | |
13271 jthread thread); | |
13272 </example> | |
13273 See the individual events for the callback function definition. | |
13274 </description> | |
13275 </basetype> | |
13276 <basetype id="jniNativeInterface"> | |
13277 <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition> | |
13278 <description> | |
13279 Typedef for the JNI function table <code>JNINativeInterface</code> | |
13280 defined in the | |
13281 <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html#wp23720">JNI Specification</externallink>. | |
13282 The JNI reference implementation defines this with an underscore. | |
13283 </description> | |
13284 </basetype> | |
13285 </basetypes> | |
13286 | |
13287 </datasection> | |
13288 | |
13289 <issuessection label="Issues"> | |
13290 <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic"> | |
13291 JVMDI requires that the agent suspend threads before calling | |
13292 certain sensitive functions. JVMPI requires garbage collection to be | |
13293 disabled before calling certain sensitive functions. | |
13294 It was suggested that rather than have this requirement, that | |
13295 VM place itself in a suitable state before performing an | |
13296 operation. This makes considerable sense since each VM | |
13297 knows its requirements and can most easily arrange a | |
13298 safe state. | |
13299 <p/> | |
13300 The ability to externally suspend/resume threads will, of | |
13301 course, remain. The ability to enable/disable garbage collection will not. | |
13302 <p/> | |
13303 This issue is resolved--suspend will not | |
13304 be required. The spec has been updated to reflect this. | |
13305 </intro> | |
13306 | |
13307 <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling"> | |
13308 There are a variety of approaches to sampling call stacks. | |
13309 The biggest bifurcation is between VM controlled and agent | |
13310 controlled. | |
13311 <p/> | |
13312 This issue is resolved--agent controlled | |
13313 sampling will be the approach. | |
13314 </intro> | |
13315 | |
13316 <intro id="threadRepresentation" label="Resolved Issue: Thread Representation"> | |
13317 JVMDI represents threads as jthread. JVMPI primarily | |
13318 uses JNIEnv* to represent threads. | |
13319 <p/> | |
13320 The Expert Group has chosen jthread as the representation | |
13321 for threads in <jvmti/>. | |
13322 JNIEnv* is sent by | |
13323 events since it is needed to JNI functions. JNIEnv, per the | |
13324 JNI spec, are not supposed to be used outside their thread. | |
13325 </intro> | |
13326 | |
13327 <intro id="design" label="Resolved Issue: Method Representation"> | |
13328 The JNI spec allows an implementation to depend on jclass/jmethodID | |
13329 pairs, rather than simply a jmethodID, to reference a method. | |
13330 JVMDI, for consistency, choose the same representation. | |
13331 JVMPI, however, specifies that a jmethodID alone maps to a | |
13332 method. Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store | |
13333 pointers in jmethodIDs, and as a result, a jmethodID is sufficient. | |
13334 In fact, any JVM implementation that supports JVMPI must have | |
13335 such a representation. | |
13336 <jvmti/> will use jmethodID as a unique representation of a method | |
13337 (no jclass is used). | |
13338 There should be efficiency gains, particularly in | |
13339 functionality like stack dumping, to this representation. | |
13340 <p/> | |
13341 Note that fields were not used in JVMPI and that the access profile | |
13342 of fields differs from methods--for implementation efficiency | |
13343 reasons, a jclass/jfieldID pair will still be needed for field | |
13344 reference. | |
13345 </intro> | |
13346 | |
13347 <intro id="localReferenceIssue" label="Resolved Issue: Local References"> | |
13348 Functions return local references. | |
13349 </intro> | |
13350 | |
13351 <intro id="frameRep" label="Resolved Issue: Representation of frames"> | |
13352 In JVMDI, a frame ID is used to represent a frame. Problem with this | |
13353 is that a VM must track when a frame becomes invalid, a far better | |
13354 approach, and the one used in <jvmti/>, is to reference frames by depth. | |
13355 </intro> | |
13356 | |
13357 <intro id="requiredCapabilities" label="Issue: Required Capabilities"> | |
13358 Currently, having a required capabilities means that the functionality | |
13359 is optional. Capabilities are useful even for required functionality | |
13360 since they can inform the VM is needed set-up. Thus, there should be | |
13361 a set of capabilities that a conformant implementation must provide | |
13362 (if requested during Agent_OnLoad). | |
13363 </intro> | |
13364 | |
13365 <intro id="taghint" label="Proposal: add tag hint function"> | |
13366 A hint of the percentage of objects that will be tagged would | |
13367 help the VM pick a good implementation. | |
13368 </intro> | |
13369 | |
13370 <intro id="moreMonitorQueries" label="Request: More Monitor Quires"> | |
13371 How difficult or easy would be to extend the monitor_info category to include | |
13372 <pre> | |
13373 - current number of monitors | |
13374 - enumeration of monitors | |
13375 - enumeration of threads waiting on a given monitor | |
13376 </pre> | |
13377 The reason for my question is the fact that current get_monitor_info support | |
13378 requires the agent to specify a given thread to get the info which is probably | |
13379 OK in the profiling/debugging space, while in the monitoring space the agent | |
13380 could be watching the monitor list and then decide which thread to ask for | |
13381 the info. You might ask why is this important for monitoring .... I think it | |
13382 can aid in the detection/prediction of application contention caused by hot-locks. | |
13383 </intro> | |
13384 </issuessection> | |
13385 | |
13386 <changehistory id="ChangeHistory" update="09/05/07"> | |
13387 <intro> | |
13388 The <jvmti/> specification is an evolving document with major, minor, | |
13389 and micro version numbers. | |
13390 A released version of the specification is uniquely identified | |
13391 by its major and minor version. | |
13392 The functions, events, and capabilities in this specification | |
13393 indicate a "Since" value which is the major and minor version in | |
13394 which it was introduced. | |
13395 The version of the specification implemented by the VM can | |
13396 be retrieved at runtime with the <functionlink id="GetVersionNumber"/> | |
13397 function. | |
13398 </intro> | |
13399 <change date="14 Nov 2002"> | |
13400 Converted to XML document. | |
13401 </change> | |
13402 <change date="14 Nov 2002"> | |
13403 Elided heap dump functions (for now) since what was there | |
13404 was wrong. | |
13405 </change> | |
13406 <change date="18 Nov 2002"> | |
13407 Added detail throughout. | |
13408 </change> | |
13409 <change date="18 Nov 2002"> | |
13410 Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE. | |
13411 </change> | |
13412 <change date="19 Nov 2002"> | |
13413 Added AsyncGetStackTrace. | |
13414 </change> | |
13415 <change date="19 Nov 2002"> | |
13416 Added jframeID return to GetStackTrace. | |
13417 </change> | |
13418 <change date="19 Nov 2002"> | |
13419 Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there | |
13420 since they are redundant with GetStackTrace. | |
13421 </change> | |
13422 <change date="19 Nov 2002"> | |
13423 Elided ClearAllBreakpoints since it has always been redundant. | |
13424 </change> | |
13425 <change date="19 Nov 2002"> | |
13426 Added GetSystemProperties. | |
13427 </change> | |
13428 <change date="19 Nov 2002"> | |
13429 Changed the thread local storage functions to use jthread. | |
13430 </change> | |
13431 <change date="20 Nov 2002"> | |
13432 Added GetJLocationFormat. | |
13433 </change> | |
13434 <change date="22 Nov 2002"> | |
13435 Added events and introductory text. | |
13436 </change> | |
13437 <change date="22 Nov 2002"> | |
13438 Cross reference type and constant definitions. | |
13439 </change> | |
13440 <change date="24 Nov 2002"> | |
13441 Added DTD. | |
13442 </change> | |
13443 <change date="24 Nov 2002"> | |
13444 Added capabilities function section. | |
13445 </change> | |
13446 <change date="29 Nov 2002"> | |
13447 Assign capabilities to each function and event. | |
13448 </change> | |
13449 <change date="29 Nov 2002"> | |
13450 Add <internallink id="jniIntercept">JNI interception functions</internallink>. | |
13451 </change> | |
13452 <change date="30 Nov 2002"> | |
13453 Auto generate SetEventNotificationMode capabilities. | |
13454 </change> | |
13455 <change date="30 Nov 2002"> | |
13456 Add <eventlink id="VMObjectAlloc"></eventlink> event. | |
13457 </change> | |
13458 <change date="30 Nov 2002"> | |
13459 Add <eventlink id="DynamicCodeGenerated"></eventlink> event. | |
13460 </change> | |
13461 <change date="30 Nov 2002"> | |
13462 Add const to declarations. | |
13463 </change> | |
13464 <change date="30 Nov 2002"> | |
13465 Change method exit and frame pop to send on exception. | |
13466 </change> | |
13467 <change date="1 Dec 2002"> | |
13468 Add ForceGarbageCollection. | |
13469 </change> | |
13470 <change date="2 Dec 2002"> | |
13471 Redo Xrun section; clarify GetStackTrace and add example; | |
13472 Fix width problems; use "agent" consistently. | |
13473 </change> | |
13474 <change date="8 Dec 2002"> | |
13475 Remove previous start-up intro. | |
13476 Add <internallink id="environments"><jvmti/> Environments</internallink> | |
13477 section. | |
13478 </change> | |
13479 <change date="8 Dec 2002"> | |
13480 Add <functionlink id="DisposeEnvironment"></functionlink>. | |
13481 </change> | |
13482 <change date="9 Dec 2002"> | |
13483 Numerous minor updates. | |
13484 </change> | |
13485 <change date="15 Dec 2002"> | |
13486 Add heap profiling functions added: | |
13487 get/set annotation, iterate live objects/heap. | |
13488 Add heap profiling functions place holder added: | |
13489 heap roots. | |
13490 Heap profiling event added: object free. | |
13491 Heap profiling event redesigned: vm object allocation. | |
13492 Heap profiling event placeholders added: garbage collection start/finish. | |
13493 Native method bind event added. | |
13494 </change> | |
13495 <change date="19 Dec 2002"> | |
13496 Revamp suspend/resume functions. | |
13497 Add origin information with jvmdi tag. | |
13498 Misc fixes. | |
13499 </change> | |
13500 <change date="24 Dec 2002"> | |
13501 Add semantics to types. | |
13502 </change> | |
13503 <change date="27 Dec 2002"> | |
13504 Add local reference section. | |
13505 Autogenerate parameter descriptions from types. | |
13506 </change> | |
13507 <change date="28 Dec 2002"> | |
13508 Document that RunAgentThread sends threadStart. | |
13509 </change> | |
13510 <change date="29 Dec 2002"> | |
13511 Remove redundant local ref and dealloc warning. | |
13512 Convert GetRawMonitorName to allocated buffer. | |
13513 Add GenerateEvents. | |
13514 </change> | |
13515 <change date="30 Dec 2002"> | |
13516 Make raw monitors a type and rename to "jrawMonitorID". | |
13517 </change> | |
13518 <change date="1 Jan 2003"> | |
13519 Include origin information. | |
13520 Clean-up JVMDI issue references. | |
13521 Remove Deallocate warnings which are now automatically generated. | |
13522 </change> | |
13523 <change date="2 Jan 2003"> | |
13524 Fix representation issues for jthread. | |
13525 </change> | |
13526 <change date="3 Jan 2003"> | |
13527 Make capabilities buffered out to 64 bits - and do it automatically. | |
13528 </change> | |
13529 <change date="4 Jan 2003"> | |
13530 Make constants which are enumeration into enum types. | |
13531 Parameters now of enum type. | |
13532 Clean-up and index type section. | |
13533 Replace remaining datadef entities with callback. | |
13534 </change> | |
13535 <change date="7 Jan 2003"> | |
13536 Correct GenerateEvents description. | |
13537 More internal semantics work. | |
13538 </change> | |
13539 <change date="9 Jan 2003"> | |
13540 Replace previous GetSystemProperties with two functions | |
13541 which use allocated information instead fixed. | |
13542 Add SetSystemProperty. | |
13543 More internal semantics work. | |
13544 </change> | |
13545 <change date="12 Jan 2003"> | |
13546 Add varargs to end of SetEventNotificationMode. | |
13547 </change> | |
13548 <change date="20 Jan 2003"> | |
13549 Finish fixing spec to reflect that alloc sizes are jlong. | |
13550 </change> | |
13551 <change date="22 Jan 2003"> | |
13552 Allow NULL as RunAgentThread arg. | |
13553 </change> | |
13554 <change date="22 Jan 2003"> | |
13555 Fixed names to standardized naming convention | |
13556 Removed AsyncGetStackTrace. | |
13557 </change> | |
13558 <change date="29 Jan 2003"> | |
13559 Since we are using jthread, removed GetThread. | |
13560 </change> | |
13561 <change date="31 Jan 2003"> | |
13562 Change GetFieldName to allow NULLs like GetMethodName. | |
13563 </change> | |
13564 <change date="29 Feb 2003" version="v40"> | |
13565 Rewrite the introductory text, adding sections on | |
13566 start-up, environments and bytecode instrumentation. | |
13567 Change the command line arguments per EG discussions. | |
13568 Add an introduction to the capabilities section. | |
13569 Add the extension mechanism category and functions. | |
13570 Mark for deletion, but clarified anyhow, SuspendAllThreads. | |
13571 Rename IterateOverLiveObjects to IterateOverReachableObjects and | |
13572 change the text accordingly. | |
13573 Clarify IterateOverHeap. | |
13574 Clarify CompiledMethodLoad. | |
13575 Discuss prerequisite state for Calling Functions. | |
13576 Clarify SetAllocationHooks. | |
13577 Added issues ("To be resolved:") through-out. | |
13578 And so on... | |
13579 </change> | |
13580 <change date="6 Mar 2003" version="v41"> | |
13581 Remove struct from the call to GetOwnedMonitorInfo. | |
13582 Automatically generate most error documentation, remove | |
13583 (rather broken) hand written error doc. | |
13584 Better describe capability use (empty initial set). | |
13585 Add min value to jint params. | |
13586 Remove the capability can_access_thread_local_storage. | |
13587 Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY; | |
13588 same for *NOT_IMPLEMENTED. | |
13589 Description fixes. | |
13590 </change> | |
13591 <change date="8 Mar 2003" version="v42"> | |
13592 Rename GetClassSignature to GetClassName. | |
13593 Rename IterateOverClassObjects to IterateOverInstancesOfClass. | |
13594 Remove GetMaxStack (operand stack isn't used in <jvmti/>). | |
13595 Description fixes: define launch-time, remove native frame pop | |
13596 from PopFrame, and assorted clarifications. | |
13597 </change> | |
13598 <change date="8 Mar 2003" version="v43"> | |
13599 Fix minor editing problem. | |
13600 </change> | |
13601 <change date="10 Mar 2003" version="v44"> | |
13602 Add phase information. | |
13603 Remap (compact) event numbers. | |
13604 </change> | |
13605 <change date="11 Mar 2003" version="v45"> | |
13606 More phase information - allow "any". | |
13607 Elide raw monitor queries and events. | |
13608 Minor description fixes. | |
13609 </change> | |
13610 <change date="12 Mar 2003" version="v46"> | |
13611 Add GetPhase. | |
13612 Use "phase" through document. | |
13613 Elide GetRawMonitorName. | |
13614 Elide GetObjectMonitors. | |
13615 </change> | |
13616 <change date="12 Mar 2003" version="v47"> | |
13617 Fixes from link, XML, and spell checking. | |
13618 Auto-generate the callback structure. | |
13619 </change> | |
13620 <change date="13 Mar 2003" version="v48"> | |
13621 One character XML fix. | |
13622 </change> | |
13623 <change date="13 Mar 2003" version="v49"> | |
13624 Change function parameter names to be consistent with | |
13625 event parameters (fooBarBaz becomes foo_bar_baz). | |
13626 </change> | |
13627 <change date="14 Mar 2003" version="v50"> | |
13628 Fix broken link. Fix thread markers. | |
13629 </change> | |
13630 <change date="14 Mar 2003" version="v51"> | |
13631 Change constants so they are under 128 to workaround | |
13632 compiler problems. | |
13633 </change> | |
13634 <change date="23 Mar 2003" version="v52"> | |
13635 Overhaul capabilities. Separate GetStackTrace into | |
13636 GetStackTrace and GetStackFrames. | |
13637 </change> | |
13638 <change date="8 Apr 2003" version="v54"> | |
13639 Use depth instead of jframeID to reference frames. | |
13640 Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames. | |
13641 Remove frame arg from events. | |
13642 </change> | |
13643 <change date="9 Apr 2003" version="v55"> | |
13644 Remove GetObjectWithAnnotation since tests show bufferred approach more efficient. | |
13645 Add missing annotation_count to GetObjectsWithAnnotations | |
13646 </change> | |
13647 <change date="10 Apr 2003" version="v56"> | |
13648 Remove confusing parenthetical statement in GetObjectsWithAnnotations | |
13649 </change> | |
13650 <change date="13 Apr 2003" version="v58"> | |
13651 Replace jclass/jmethodID representation of method with simply jmethodID; | |
13652 Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate. | |
13653 Replace can_access_frames with can_access_local_variables; remove from purely stack access. | |
13654 Use can_get_synthetic_attribute; fix description. | |
13655 Clarify that zero length arrays must be deallocated. | |
13656 Clarify RelinquishCapabilities. | |
13657 Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE. | |
13658 </change> | |
13659 <change date="27 Apr 2003" version="v59"> | |
13660 Remove lingering indirect references to OBSOLETE_METHOD_ID. | |
13661 </change> | |
13662 <change date="4 May 2003" version="v60"> | |
13663 Allow DestroyRawMonitor during OnLoad. | |
13664 </change> | |
13665 <change date="7 May 2003" version="v61"> | |
13666 Added not monitor owner error return to DestroyRawMonitor. | |
13667 </change> | |
13668 <change date="13 May 2003" version="v62"> | |
13669 Clarify semantics of raw monitors. | |
13670 Change flags on <code>GetThreadStatus</code>. | |
13671 <code>GetClassLoader</code> return NULL for the bootstrap class loader. | |
13672 Add <code>GetClassName</code> issue. | |
13673 Define local variable signature. | |
13674 Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>. | |
13675 Remove over specification in <code>GetObjectsWithAnnotations</code>. | |
13676 Elide <code>SetAllocationHooks</code>. | |
13677 Elide <code>SuspendAllThreads</code>. | |
13678 </change> | |
13679 <change date="14 May 2003" version="v63"> | |
13680 Define the data type <code>jvmtiEventCallbacks</code>. | |
13681 Zero length allocations return NULL. | |
13682 Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>. | |
13683 Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED. | |
13684 </change> | |
13685 <change date="15 May 2003" version="v64"> | |
13686 Better wording, per review. | |
13687 </change> | |
13688 <change date="15 May 2003" version="v65"> | |
13689 First Alpha. | |
13690 Make jmethodID and jfieldID unique, jclass not used. | |
13691 </change> | |
13692 <change date="27 May 2003" version="v66"> | |
13693 Fix minor XSLT errors. | |
13694 </change> | |
13695 <change date="13 June 2003" version="v67"> | |
13696 Undo making jfieldID unique (jmethodID still is). | |
13697 </change> | |
13698 <change date="17 June 2003" version="v68"> | |
13699 Changes per June 11th Expert Group meeting -- | |
13700 Overhaul Heap functionality: single callback, | |
13701 remove GetHeapRoots, add reachable iterators, | |
13702 and rename "annotation" to "tag". | |
13703 NULL thread parameter on most functions is current | |
13704 thread. | |
13705 Add timers. | |
13706 Remove ForceExit. | |
13707 Add GetEnvironmentLocalStorage. | |
13708 Add verbose flag and event. | |
13709 Add AddToBootstrapClassLoaderSearch. | |
13710 Update ClassFileLoadHook. | |
13711 </change> | |
13712 <change date="18 June 2003" version="v69"> | |
13713 Clean up issues sections. | |
13714 Rename GetClassName back to GetClassSignature and | |
13715 fix description. | |
13716 Add generic signature to GetClassSignature, | |
13717 GetFieldSignature, GetMethodSignature, and | |
13718 GetLocalVariableTable. | |
13719 Elide EstimateCostOfCapabilities. | |
13720 Clarify that the system property functions operate | |
13721 on the VM view of system properties. | |
13722 Clarify Agent_OnLoad. | |
13723 Remove "const" from JNIEnv* in events. | |
13724 Add metadata accessors. | |
13725 </change> | |
13726 <change date="18 June 2003" version="v70"> | |
13727 Add start_depth to GetStackTrace. | |
13728 Move system properties to a new category. | |
13729 Add GetObjectSize. | |
13730 Remove "X" from command line flags. | |
13731 XML, HTML, and spell check corrections. | |
13732 </change> | |
13733 <change date="19 June 2003" version="v71"> | |
13734 Fix JVMTI_HEAP_ROOT_THREAD to be 6. | |
13735 Make each synopsis match the function name. | |
13736 Fix unclear wording. | |
13737 </change> | |
13738 <change date="26 June 2003" version="v72"> | |
13739 SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value | |
13740 to be set to NULL. | |
13741 NotifyFramePop, GetFrameLocationm and all the local variable operations | |
13742 needed to have their wording about frames fixed. | |
13743 Grammar and clarity need to be fixed throughout. | |
13744 Capitalization and puntuation need to be consistent. | |
13745 Need micro version number and masks for accessing major, minor, and micro. | |
13746 The error code lists should indicate which must be returned by | |
13747 an implementation. | |
13748 The command line properties should be visible in the properties functions. | |
13749 Disallow popping from the current thread. | |
13750 Allow implementations to return opaque frame error when they cannot pop. | |
13751 The NativeMethodBind event should be sent during any phase. | |
13752 The DynamicCodeGenerated event should be sent during any phase. | |
13753 The following functions should be allowed to operate before VMInit: | |
13754 Set/GetEnvironmentLocalStorage | |
13755 GetMethodDeclaringClass | |
13756 GetClassSignature | |
13757 GetClassModifiers | |
13758 IsInterface | |
13759 IsArrayClass | |
13760 GetMethodName | |
13761 GetMethodModifiers | |
13762 GetMaxLocals | |
13763 GetArgumentsSize | |
13764 GetLineNumberTable | |
13765 GetMethodLocation | |
13766 IsMethodNative | |
13767 IsMethodSynthetic. | |
13768 Other changes (to XSL): | |
13769 Argument description should show asterisk after not before pointers. | |
13770 NotifyFramePop, GetFrameLocationm and all the local variable operations | |
13771 should hsve the NO_MORE_FRAMES error added. | |
13772 Not alive threads should have a different error return than invalid thread. | |
13773 </change> | |
13774 <change date="7 July 2003" version="v73"> | |
13775 VerboseOutput event was missing message parameter. | |
13776 Minor fix-ups. | |
13777 </change> | |
13778 <change date="14 July 2003" version="v74"> | |
13779 Technical Publications Department corrections. | |
13780 Allow thread and environment local storage to be set to NULL. | |
13781 </change> | |
13782 <change date="23 July 2003" version="v75"> | |
13783 Use new Agent_OnLoad rather than overloaded JVM_OnLoad. | |
13784 Add JNICALL to callbacks (XSL). | |
13785 Document JNICALL requirement for both events and callbacks (XSL). | |
13786 Restrict RedefineClasses to methods and attributes. | |
13787 Elide the VerboseOutput event. | |
13788 VMObjectAlloc: restrict when event is sent and remove method parameter. | |
13789 Finish loose ends from Tech Pubs edit. | |
13790 </change> | |
13791 <change date="24 July 2003" version="v76"> | |
13792 Change ClassFileLoadHook event to send the class instead of a boolean of redefine. | |
13793 </change> | |
13794 <change date="24 July 2003" version="v77"> | |
13795 XML fixes. | |
13796 Minor text clarifications and corrections. | |
13797 </change> | |
13798 <change date="24 July 2003" version="v78"> | |
13799 Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>. | |
13800 Clarify that stack frames are JVM Spec frames. | |
13801 Split can_get_source_info into can_get_source_file_name, can_get_line_numbers, | |
13802 and can_get_source_debug_extension. | |
13803 PopFrame cannot have a native calling method. | |
13804 Removed incorrect statement in GetClassloaderClasses | |
13805 (see http://java.sun.com/docs/books/vmspec/2nd-edition/html/ConstantPool.doc.html#79383). | |
13806 </change> | |
13807 <change date="24 July 2003" version="v79"> | |
13808 XML and text fixes. | |
13809 Move stack frame description into Stack Frame category. | |
13810 </change> | |
13811 <change date="26 July 2003" version="v80"> | |
13812 Allow NULL (means bootstrap loader) for GetClassloaderClasses. | |
13813 Add new heap reference kinds for references from classes. | |
13814 Add timer information struct and query functions. | |
13815 Add AvailableProcessors. | |
13816 Rename GetOtherThreadCpuTime to GetThreadCpuTime. | |
13817 Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE | |
13818 to SetEventNotification mode. | |
13819 Add initial thread to the VM_INIT event. | |
13820 Remove platform assumptions from AddToBootstrapClassLoaderSearch. | |
13821 </change> | |
13822 <change date="26 July 2003" version="v81"> | |
13823 Grammar and clarity changes per review. | |
13824 </change> | |
13825 <change date="27 July 2003" version="v82"> | |
13826 More grammar and clarity changes per review. | |
13827 Add Agent_OnUnload. | |
13828 </change> | |
13829 <change date="28 July 2003" version="v83"> | |
13830 Change return type of Agent_OnUnload to void. | |
13831 </change> | |
13832 <change date="28 July 2003" version="v84"> | |
13833 Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT. | |
13834 </change> | |
13835 <change date="28 July 2003" version="v85"> | |
13836 Steal java.lang.Runtime.availableProcessors() wording for | |
13837 AvailableProcessors(). | |
13838 Guarantee that zero will never be an event ID. | |
13839 Remove some issues which are no longer issues. | |
13840 Per review, rename and more completely document the timer | |
13841 information functions. | |
13842 </change> | |
13843 <change date="29 July 2003" version="v86"> | |
13844 Non-spec visible change to XML controlled implementation: | |
13845 SetThreadLocalStorage must run in VM mode. | |
13846 </change> | |
13847 <change date="5 August 2003" version="0.1.87"> | |
13848 Add GetErrorName. | |
13849 Add varargs warning to jvmtiExtensionEvent. | |
13850 Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent. | |
13851 Remove unused can_get_exception_info capability. | |
13852 Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction. | |
13853 Fix jvmtiExtensionFunctionInfo.func declared type. | |
13854 Extension function returns error code. | |
13855 Use new version numbering. | |
13856 </change> | |
13857 <change date="5 August 2003" version="0.2.88"> | |
13858 Remove the ClassUnload event. | |
13859 </change> | |
13860 <change date="8 August 2003" version="0.2.89"> | |
13861 Heap reference iterator callbacks return an enum that | |
13862 allows outgoing object references to be ignored. | |
13863 Allow JNIEnv as a param type to extension events/functions. | |
13864 </change> | |
13865 <change date="15 August 2003" version="0.2.90"> | |
13866 Fix a typo. | |
13867 </change> | |
13868 <change date="2 September 2003" version="0.2.91"> | |
13869 Remove all metadata functions: GetClassMetadata, | |
13870 GetFieldMetadata, and GetMethodMetadata. | |
13871 </change> | |
13872 <change date="1 October 2003" version="0.2.92"> | |
13873 Mark the functions Allocate. Deallocate, RawMonitor*, | |
13874 SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage | |
13875 as safe for use in heap callbacks and GC events. | |
13876 </change> | |
13877 <change date="24 November 2003" version="0.2.93"> | |
13878 Add pass through opaque user data pointer to heap iterate | |
13879 functions and callbacks. | |
13880 In the CompiledMethodUnload event, send the code address. | |
13881 Add GarbageCollectionOccurred event. | |
13882 Add constant pool reference kind. | |
13883 Mark the functions CreateRawMonitor and DestroyRawMonitor | |
13884 as safe for use in heap callbacks and GC events. | |
13885 Clarify: VMDeath, GetCurrentThreadCpuTimerInfo, | |
13886 GetThreadCpuTimerInfo, IterateOverReachableObjects, | |
13887 IterateOverObjectsReachableFromObject, GetTime and | |
13888 JVMTI_ERROR_NULL_POINTER. | |
13889 Add missing errors to: GenerateEvents and | |
13890 AddToBootstrapClassLoaderSearch. | |
13891 Fix description of ClassFileLoadHook name parameter. | |
13892 In heap callbacks and GC/ObjectFree events, specify | |
13893 that only explicitly allowed functions can be called. | |
13894 Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime, | |
13895 GetTimerInfo, and GetTime during callback. | |
13896 Allow calling SetTag/GetTag during the onload phase. | |
13897 SetEventNotificationMode, add: error attempted inappropriate | |
13898 thread level control. | |
13899 Remove jvmtiExceptionHandlerEntry. | |
13900 Fix handling of native methods on the stack -- | |
13901 location_ptr param of GetFrameLocation, remove | |
13902 JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation, | |
13903 jvmtiFrameInfo.location, and jlocation. | |
13904 Remove typo (from JVMPI) implying that the MonitorWaited | |
13905 event is sent on sleep. | |
13906 </change> | |
13907 <change date="25 November 2003" version="0.2.94"> | |
13908 Clarifications and typos. | |
13909 </change> | |
13910 <change date="3 December 2003" version="0.2.95"> | |
13911 Allow NULL user_data in heap iterators. | |
13912 </change> | |
13913 <change date="28 January 2004" version="0.2.97"> | |
13914 Add GetThreadState, deprecate GetThreadStatus. | |
13915 </change> | |
13916 <change date="29 January 2004" version="0.2.98"> | |
13917 INVALID_SLOT and TYPE_MISMATCH errors should be optional. | |
13918 </change> | |
13919 <change date="12 February 2004" version="0.2.102"> | |
13920 Remove MonitorContendedExit. | |
13921 Added JNIEnv parameter to VMObjectAlloc. | |
13922 Clarified definition of class_tag and referrer_index | |
13923 parameters to heap callbacks. | |
13924 </change> | |
13925 <change date="16 Febuary 2004" version="0.2.103"> | |
13926 Document JAVA_TOOL_OPTIONS. | |
13927 </change> | |
13928 <change date="17 Febuary 2004" version="0.2.105"> | |
13929 Divide start phase into primordial and start. | |
13930 Add VMStart event | |
13931 Change phase associations of functions and events. | |
13932 </change> | |
13933 <change date="18 Febuary 2004" version="0.3.6"> | |
13934 Elide deprecated GetThreadStatus. | |
13935 Bump minor version, subtract 100 from micro version | |
13936 </change> | |
13937 <change date="18 Febuary 2004" version="0.3.7"> | |
13938 Document that timer nanosecond values are unsigned. | |
13939 Clarify text having to do with native methods. | |
13940 </change> | |
13941 <change date="19 Febuary 2004" version="0.3.8"> | |
13942 Fix typos. | |
13943 Remove elided deprecated GetThreadStatus. | |
13944 </change> | |
13945 <change date="23 Febuary 2004" version="0.3.9"> | |
13946 Require NotifyFramePop to act on suspended threads. | |
13947 </change> | |
13948 <change date="24 Febuary 2004" version="0.3.10"> | |
13949 Add capabilities | |
13950 (<internallink id="jvmtiCapabilities.can_redefine_any_class" | |
13951 ><code>can_redefine_any_class</code></internallink> | |
13952 and | |
13953 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events" | |
13954 ><code>can_generate_all_class_hook_events</code></internallink>) | |
13955 and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>) | |
13956 which allow some classes to be unmodifiable. | |
13957 </change> | |
13958 <change date="28 Febuary 2004" version="0.3.11"> | |
13959 Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode. | |
13960 </change> | |
13961 <change date="8 March 2004" version="0.3.12"> | |
13962 Clarified CompiledMethodUnload so that it is clear the event | |
13963 may be posted after the class has been unloaded. | |
13964 </change> | |
13965 <change date="5 March 2004" version="0.3.13"> | |
13966 Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize. | |
13967 </change> | |
13968 <change date="13 March 2004" version="0.3.14"> | |
13969 Added guideline for the use of the JNI FindClass function in event | |
13970 callback functions. | |
13971 </change> | |
13972 <change date="15 March 2004" version="0.3.15"> | |
13973 Add GetAllStackTraces and GetThreadListStackTraces. | |
13974 </change> | |
13975 <change date="19 March 2004" version="0.3.16"> | |
13976 ClassLoad and ClassPrepare events can be posted during start phase. | |
13977 </change> | |
13978 <change date="25 March 2004" version="0.3.17"> | |
13979 Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable, | |
13980 GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes. | |
13981 </change> | |
13982 <change date="29 March 2004" version="0.3.18"> | |
13983 Return the timer kind in the timer information structure. | |
13984 </change> | |
13985 <change date="31 March 2004" version="0.3.19"> | |
13986 Spec clarifications: | |
13987 JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>. | |
13988 ForceGarbageCollection does not run finalizers. | |
13989 The context of the specification is the Java platform. | |
13990 Warn about early instrumentation. | |
13991 </change> | |
13992 <change date="1 April 2004" version="0.3.20"> | |
13993 Refinements to the above clarifications and | |
13994 Clarify that an error returned by Agent_OnLoad terminates the VM. | |
13995 </change> | |
13996 <change date="1 April 2004" version="0.3.21"> | |
13997 Array class creation does not generate a class load event. | |
13998 </change> | |
13999 <change date="7 April 2004" version="0.3.22"> | |
14000 Align thread state hierarchy more closely with java.lang.Thread.State. | |
14001 </change> | |
14002 <change date="12 April 2004" version="0.3.23"> | |
14003 Clarify the documentation of thread state. | |
14004 </change> | |
14005 <change date="19 April 2004" version="0.3.24"> | |
14006 Remove GarbageCollectionOccurred event -- can be done by agent. | |
14007 </change> | |
14008 <change date="22 April 2004" version="0.3.25"> | |
14009 Define "command-line option". | |
14010 </change> | |
14011 <change date="29 April 2004" version="0.3.26"> | |
14012 Describe the intended use of bytecode instrumentation. | |
14013 Fix description of extension event first parameter. | |
14014 </change> | |
14015 <change date="30 April 2004" version="0.3.27"> | |
14016 Clarification and typos. | |
14017 </change> | |
14018 <change date="18 May 2004" version="0.3.28"> | |
14019 Remove DataDumpRequest event. | |
14020 </change> | |
14021 <change date="18 May 2004" version="0.3.29"> | |
14022 Clarify RawMonitorWait with zero timeout. | |
14023 Clarify thread state after RunAgentThread. | |
14024 </change> | |
14025 <change date="24 May 2004" version="0.3.30"> | |
14026 Clean-up: fix bad/old links, etc. | |
14027 </change> | |
14028 <change date="30 May 2004" version="0.3.31"> | |
14029 Clarifications including: | |
14030 All character strings are modified UTF-8. | |
14031 Agent thread visibiity. | |
14032 Meaning of obsolete method version. | |
14033 Thread invoking heap callbacks, | |
14034 </change> | |
14035 <change date="1 June 2004" version="1.0.32"> | |
14036 Bump major.minor version numbers to "1.0". | |
14037 </change> | |
14038 <change date="2 June 2004" version="1.0.33"> | |
14039 Clarify interaction between ForceGarbageCollection | |
14040 and ObjectFree. | |
14041 </change> | |
14042 <change date="6 June 2004" version="1.0.34"> | |
14043 Restrict AddToBootstrapClassLoaderSearch and | |
14044 SetSystemProperty to the OnLoad phase only. | |
14045 </change> | |
14046 <change date="11 June 2004" version="1.0.35"> | |
14047 Fix typo in SetTag. | |
14048 </change> | |
14049 <change date="18 June 2004" version="1.0.36"> | |
14050 Fix trademarks. | |
14051 Add missing parameter in example GetThreadState usage. | |
14052 </change> | |
14053 <change date="4 August 2004" version="1.0.37"> | |
14054 Copyright updates. | |
14055 </change> | |
14056 <change date="5 November 2004" version="1.0.38"> | |
14057 Add missing function table layout. | |
14058 Add missing description of C++ member function format of functions. | |
14059 Clarify that name in CFLH can be NULL. | |
14060 Released as part of <tm>J2SE</tm> 5.0. | |
14061 </change> | |
14062 <change date="24 April 2005" version="1.1.47"> | |
14063 Bump major.minor version numbers to "1.1". | |
14064 Add ForceEarlyReturn* functions. | |
14065 Add GetOwnedMonitorStackDepthInfo function. | |
14066 Add GetCurrentThread function. | |
14067 Add "since" version marker. | |
14068 Add AddToSystemClassLoaderSearch. | |
14069 Allow AddToBootstrapClassLoaderSearch be used in live phase. | |
14070 Fix historic rubbish in the descriptions of the heap_object_callback | |
14071 parameter of IterateOverHeap and IterateOverInstancesOfClass functions; | |
14072 disallow NULL for this parameter. | |
14073 Clarify, correct and make consistent: wording about current thread, | |
14074 opaque frames and insufficient number of frames in PopFrame. | |
14075 Consistently use "current frame" rather than "topmost". | |
14076 Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal* | |
14077 by making them compatible with those in ForceEarlyReturn*. | |
14078 Many other clarifications and wording clean ups. | |
14079 </change> | |
14080 <change date="25 April 2005" version="1.1.48"> | |
14081 Add GetConstantPool. | |
14082 Switch references to the first edition of the VM Spec, to the seconds edition. | |
14083 </change> | |
14084 <change date="26 April 2005" version="1.1.49"> | |
14085 Clarify minor/major version order in GetConstantPool. | |
14086 </change> | |
14087 <change date="26 April 2005" version="1.1.50"> | |
14088 Add SetNativeMethodPrefix and SetNativeMethodPrefixes. | |
14089 Reassign GetOwnedMonitorStackDepthInfo to position 153. | |
14090 Break out Class Loader Search in its own documentation category. | |
14091 Deal with overly long lines in XML source. | |
14092 </change> | |
14093 <change date="29 April 2005" version="1.1.51"> | |
14094 Allow agents be started in the live phase. | |
14095 Added paragraph about deploying agents. | |
14096 </change> | |
14097 <change date="30 April 2005" version="1.1.52"> | |
14098 Add specification description to SetNativeMethodPrefix(es). | |
14099 Better define the conditions on GetConstantPool. | |
14100 </change> | |
14101 <change date="30 April 2005" version="1.1.53"> | |
14102 Break out the GetClassVersionNumber function from GetConstantPool. | |
14103 Clean-up the references to the VM Spec. | |
14104 </change> | |
14105 <change date="1 May 2005" version="1.1.54"> | |
14106 Allow SetNativeMethodPrefix(es) in any phase. | |
14107 Add clarifications about the impact of redefinition on GetConstantPool. | |
14108 </change> | |
14109 <change date="2 May 2005" version="1.1.56"> | |
14110 Various clarifications to SetNativeMethodPrefix(es). | |
14111 </change> | |
14112 <change date="2 May 2005" version="1.1.57"> | |
14113 Add missing performance warning to the method entry event. | |
14114 </change> | |
14115 <change date="5 May 2005" version="1.1.58"> | |
14116 Remove internal JVMDI support. | |
14117 </change> | |
14118 <change date="8 May 2005" version="1.1.59"> | |
14119 Add <functionlink id="RetransformClasses"/>. | |
14120 Revamp the bytecode instrumentation documentation. | |
14121 Change <functionlink id="IsMethodObsolete"/> to no longer | |
14122 require the can_redefine_classes capability. | |
14123 </change> | |
14124 <change date="11 May 2005" version="1.1.63"> | |
14125 Clarifications for retransformation. | |
14126 </change> | |
14127 <change date="11 May 2005" version="1.1.64"> | |
14128 Clarifications for retransformation, per review. | |
14129 Lock "retransformation (in)capable" at class load enable time. | |
14130 </change> | |
14131 <change date="4 June 2005" version="1.1.67"> | |
14132 Add new heap functionity which supports reporting primitive values, | |
14133 allows setting the referrer tag, and has more powerful filtering: | |
14134 FollowReferences, IterateThroughHeap, and their associated | |
14135 callbacks, structs, enums, and constants. | |
14136 </change> | |
14137 <change date="4 June 2005" version="1.1.68"> | |
14138 Clarification. | |
14139 </change> | |
14140 <change date="6 June 2005" version="1.1.69"> | |
14141 FollowReferences, IterateThroughHeap: Put callbacks in a struct; | |
14142 Add missing error codes; reduce bits in the visit control flags. | |
14143 </change> | |
14144 <change date="14 June 2005" version="1.1.70"> | |
14145 More on new heap functionity: spec clean-up per review. | |
14146 </change> | |
14147 <change date="15 June 2005" version="1.1.71"> | |
14148 More on new heap functionity: Rename old heap section to Heap (1.0). | |
14149 </change> | |
14150 <change date="21 June 2005" version="1.1.72"> | |
14151 Fix typos. | |
14152 </change> | |
14153 <change date="27 June 2005" version="1.1.73"> | |
14154 Make referrer info structure a union. | |
14155 </change> | |
14156 <change date="9 September 2005" version="1.1.74"> | |
14157 In new heap functions: | |
14158 Add missing superclass reference kind. | |
14159 Use a single scheme for computing field indexes. | |
14160 Remove outdated references to struct based referrer info. | |
14161 </change> | |
14162 <change date="12 September 2005" version="1.1.75"> | |
14163 Don't callback during FollowReferences on frivolous java.lang.Object superclass. | |
14164 </change> | |
14165 <change date="13 September 2005" version="1.1.76"> | |
14166 In string primitive callback, length now Unicode length. | |
14167 In array and string primitive callbacks, value now "const". | |
14168 Note possible compiler impacts on setting JNI function table. | |
14169 </change> | |
14170 <change date="13 September 2005" version="1.1.77"> | |
14171 GetClassVersionNumbers() and GetConstantPool() should return | |
14172 error on array or primitive class. | |
14173 </change> | |
14174 <change date="14 September 2005" version="1.1.78"> | |
14175 Grammar fixes. | |
14176 </change> | |
14177 <change date="26 September 2005" version="1.1.79"> | |
14178 Add IsModifiableClass query. | |
14179 </change> | |
14180 <change date="9 February 2006" version="1.1.81"> | |
14181 Add referrer_class_tag parameter to jvmtiHeapReferenceCallback. | |
14182 </change> | |
14183 <change date="13 February 2006" version="1.1.82"> | |
14184 Doc fixes: update can_redefine_any_class to include retransform. | |
14185 Clarify that exception events cover all Throwables. | |
14186 In GetStackTrace, no test is done for start_depth too big if start_depth is zero, | |
14187 Clarify fields reported in Primitive Field Callback -- static vs instance. | |
14188 Repair confusing names of heap types, including callback names. | |
14189 Require consistent usage of stack depth in the face of thread launch methods. | |
14190 Note incompatibility of <jvmti/> memory management with other systems. | |
14191 </change> | |
14192 <change date="14 February 2006" version="1.1.85"> | |
14193 Fix typos and missing renames. | |
14194 </change> | |
14195 <change date="13 March 2006" version="1.1.86"> | |
14196 Clarify that jmethodIDs and jfieldIDs can be saved. | |
14197 Clarify that Iterate Over Instances Of Class includes subclasses. | |
14198 </change> | |
14199 <change date="14 March 2006" version="1.1.87"> | |
14200 Better phrasing. | |
14201 </change> | |
14202 <change date="16 March 2006" version="1.1.88"> | |
14203 Match the referrer_index for static fields in Object Reference Callback | |
14204 with the Reference Implementation (and all other known implementations); | |
14205 that is, make it match the definition for instance fields. | |
14206 In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover | |
14207 an invalid thread in the list; and specify that not started threads | |
14208 return empty stacks. | |
14209 </change> | |
14210 <change date="17 March 2006" version="1.1.89"> | |
14211 Typo. | |
14212 </change> | |
14213 <change date="25 March 2006" version="1.1.90"> | |
14214 Typo. | |
14215 </change> | |
14216 <change date="6 April 2006" version="1.1.91"> | |
14217 Remove restrictions on AddToBootstrapClassLoaderSearch and | |
14218 AddToSystemClassLoaderSearch. | |
14219 </change> | |
14220 <change date="1 May 2006" version="1.1.93"> | |
14221 Changed spec to return -1 for monitor stack depth for the | |
14222 implementation which can not determine stack depth. | |
14223 </change> | |
14224 <change date="3 May 2006" version="1.1.94"> | |
14225 Corrections for readability and accuracy courtesy of Alan Pratt of IBM. | |
14226 List the object relationships reported in FollowReferences. | |
14227 </change> | |
14228 <change date="5 May 2006" version="1.1.95"> | |
14229 Clarify the object relationships reported in FollowReferences. | |
14230 </change> | |
14231 <change date="28 June 2006" version="1.1.98"> | |
14232 Clarify DisposeEnvironment; add warning. | |
14233 Fix typos in SetLocalXXX "retrieve" => "set". | |
14234 Clarify that native method prefixes must remain set while used. | |
14235 Clarify that exactly one Agent_OnXXX is called per agent. | |
14236 Clarify that library loading is independent from start-up. | |
14237 Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec. | |
14238 </change> | |
14239 <change date="31 July 2006" version="1.1.99"> | |
14240 Clarify the interaction between functions and exceptions. | |
14241 Clarify and give examples of field indices. | |
14242 Remove confusing "That is" sentence from MonitorWait and MonitorWaited events. | |
14243 Update links to point to Java 6. | |
14244 </change> | |
14245 <change date="6 August 2006" version="1.1.102"> | |
14246 Add ResourceExhaustedEvent. | |
14247 </change> | |
14248 </changehistory> | |
14249 | |
14250 </specification> | |
14251 <!-- Keep this comment at the end of the file | |
14252 Local variables: | |
14253 mode: sgml | |
14254 sgml-omittag:t | |
14255 sgml-shorttag:t | |
14256 sgml-namecase-general:t | |
14257 sgml-general-insert-case:lower | |
14258 sgml-minimize-attributes:nil | |
14259 sgml-always-quote-attributes:t | |
14260 sgml-indent-step:2 | |
14261 sgml-indent-data:t | |
14262 sgml-parent-document:nil | |
14263 sgml-exposed-tags:nil | |
14264 sgml-local-catalogs:nil | |
14265 sgml-local-ecat-files:nil | |
14266 End: | |
14267 --> |